Night Market Docs And Writing

ADR conventions

An ADR (Architecture Decision Record) captures a decision that is expensive to reverse. They live in docs/adr/ as NNNN-kebab-slug.md with zero-padded sequential numbers (0001-0017 as of 2026-07-02).

Header template (verified against ADR-0001 and ADR-0017):

# ADR-NNNN: Title

**Date**: YYYY-MM-DD
**Status**: Accepted
**Deciders**: Claude Night Market maintainers
**Source**: Issue #NNN, Discussion #NNN
**Supersedes**: ADR-NNNN

## Context

## Decision

## Consequences

Rules:

• Status values in use: Accepted, Superseded by ADR-NNNN. Never delete or rewrite a superseded ADR. Example chain: ADR-0012 and ADR-0013 both carry "Superseded by ADR-0017", and 0017 lists "Supersedes: ADR-0012, ADR-0013" in its header.
• An ADR may supersede itself in place for a scoped correction (ADR-0008 swapped its mechanism and documented the change inline).
• Source links the issue or discussion that forced the decision.

ADR vs journal entry vs discussion post

For the Discussions mechanics and promotion path, use the sibling skill night-market-collective-memory.

Changelog conventions

CHANGELOG.md follows Keep a Changelog 1.1.0 and SemVer:

• ## [Unreleased] stays at the top; new entries land there and get moved under a ## [X.Y.Z] - YYYY-MM-DD heading at release.
• Standard subsections: ### Added, ### Fixed, ### Changed.
• Never retroactively de-slop or reword historical entries. The slop anti-goals (scribe:slop-detector module anti-goals.md) explicitly exempt changelog history: it is a record, not prose to polish.

Skill description contract

Every SKILL.md and command description: field is loaded into the model's skill-discovery budget, so length is policed:

• Hard cap: 160 characters per description (hard fail).
• Third person only. Template: [Verb phrase] [domain]. Use when [trigger]. Do not use when [negative]; use [alternative] instead.
• Full guide: docs/skill-description-guide.md.

Two pre-commit hooks enforce it:

python3 plugins/abstract/scripts/validate_budget.py
python3 scripts/fix_descriptions.py --check

validate_budget.py hard-fails any description over 160 chars and warns when the ecosystem total approaches its budget (default 90,000 chars, override via SLASH_COMMAND_TOOL_CHAR_BUDGET). Note: docs/skill-description-guide.md still cites an older 60,000-char ceiling; the script value is current (the script is the enforcer).

The book (mdBook)

• Structure: edit book/src/SUMMARY.md to add pages; create-missing = false means a SUMMARY entry without a file breaks the build.
• Local build: cd book && mdbook build (output in book/build/). mdbook is installed separately; CI uses the unpinned latest.
• Deploy: .github/workflows/deploy-book.yml publishes to GitHub Pages on push to master touching book/**. PRs touching book/** get a build check.
• book/src/reference/capabilities-*.md are generated from plugin manifests. Check drift with make docs-sync-check (runs scripts/capabilities-sync-check.sh); fix drift with the /sanctum:sync-capabilities --fix command, not by hand.

Doc gate command checklist

Run before committing markdown:

python3 scripts/check-markdown-links.py path/to/file.md
python3 plugins/abstract/scripts/validate_budget.py   # if SKILL.md touched
make docs-sync-check                                  # if manifests touched

Then walk the three slop layers manually or via Skill(scribe:slop-detector). Every new or modified SKILL.md also needs a ## Exit Criteria section (.claude/rules/skill-exit-criteria.md, issue #454).

When NOT to use

• Running tests, lint, releases, or the version bump: use night-market-operations.
• Classifying whether a change needs an ADR-gated review at all: use night-market-change-control.
• Posting to or querying GitHub Discussions, journal promotion paths, ADR-vs-memory routing details: use night-market-collective-memory.
• Plugin/skill/hook file mechanics (frontmatter fields, discovery): use claude-code-plugin-reference.
• Test evidence standards and coverage thresholds: use night-market-validation-and-qa.

Exit Criteria

• Any doc edit touched the file the map marks as canonical, and no file marked GENERATED was hand-edited (verify: git diff --stat shows no book/src/reference/capabilities-* unless produced by the sync command).
• New prose passes the local slop pre-check: zero P0 hits, zero new em dashes, no tier-1 vocabulary in the diff.
• python3 scripts/check-markdown-links.py <file> exits 0 for each markdown file touched.
• If a SKILL.md was touched: python3 plugins/abstract/scripts/validate_budget.py exits 0 and the file contains a ## Exit Criteria section.
• If a decision was recorded: it landed as a numbered ADR, a TR-NNN/LL-NNN journal entry, or a Discussion post, and any superseded ADR's Status field was updated in place.
• CHANGELOG.md still has ## [Unreleased] as its first version heading and no historical entry was reworded.

Provenance and maintenance

Compiled 2026-07-02 against repo v1.9.15 (branch discussions-fix-1.9.14). Volatile facts and how to re-verify:

• ADR count (17) and statuses: ls docs/adr/ and rg -l "Superseded" docs/adr/.
• Slop CI threshold (3.0) and scanned paths (docs/, book/src/): read .github/workflows/slop-check.yml.
• Description cap (160) and total budget (90,000): rg "DESCRIPTION_MAX|DEFAULT_BUDGET" plugins/abstract/scripts/validate_budget.py.
• Rules inventory (8 files): ls .claude/rules/.
• Per-feature doc occupant: head -5 docs/project-brief.md.
• Journal files existence: ls docs/tradeoffs.md docs/lessons-learned.md.
• Book deploy trigger: read .github/workflows/deploy-book.yml.
• Guide-vs-script budget drift (60K vs 90K): re-check docs/skill-description-guide.md in case the guide was updated.