Split rules.md and decisions.md into one named file per entry

[derek73]

Closes #713.

docs/design/rules.md (31k words) and docs/design/decisions.md (205k words, more than an agent's context window holds) are now folders of named files. Each folder has a README with the old preamble and an index:

• docs/design/rules/: one file per rule (S2-case-signal-at-the-suffix-slot.md) and one per section Background (S-suffixes-generational-and-credentials.md).
• docs/design/decisions/: one file per key (S2-case-signal-at-the-suffix-slot.md, vocabulary-collisions.md). The 11 differential-ledger arcs share one file. The vocabulary-keyed Excluded:/Open: blocks are gathered into the new vocabulary-exclusions.md, unedited and in their old order. They had no heading of their own, so the split had filed them by position into P3, W2, P5 and R4.
• mechanisms.md is unchanged.

Citations are now rules/S2 and decisions/key (mechanisms.md#X is unchanged). A script rewrote 1,347 of them across 159 tracked files. test_no_old_design_doc_anchors keeps the old form out of every tracked .py/.md/.rst file, because an old-form citation would no longer be read, and its quote would go unchecked. Citations carry only the ID, so renaming a file breaks nothing.

Names. 39 rules take the name their decisions entry already had. Seven are new: C2 "parts past the second comma", O3 "compound family names written unmarked", P4 "a particle at the front of the name", R1 "fields are views of the parsed words", S1 "a bracketed credential is not a nickname", S3 "credentials written with interior periods", T2 "the katakana middle dot divides like a space". The ledger file is named "the differential ledger's arcs". AGENTS.md now asks that a rule cited in chat, a commit or a PR give its name with its ID.

Verification

• Lossless split: the migration script (committed in a839084, deleted in 526630e) refused to write anything unless joining the pieces back reproduced both files byte for byte. It printed round trip: rules.md and decisions.md both byte-identical. The final review rebuilt both documents independently. The only differences it found are the intended layout-describing prose edits, and it also found the NFD example lines intact. corpus_rules.jsonl regenerates byte-identical.
• No citation lost: before the rewrite the checker saw 990 references; afterwards it sees 1,011. Diffed by file, line and key: 0 lost. The gains are prose mentions the sweep turned into real, checked citations, plus three keys wrapped at a hyphen across lines that the old checker never read. The first version of the new pattern dropped those three wrapped keys, which a set diff caught. test_mention_re_reads_a_key_wrapped_at_its_hyphen now pins that shape, and a floor (>= 1000) guards against losing a whole shape.
• Negative control: citing rules/S99, misquoting an M3 excerpt, and appending rules.md#S2 to docs/design/AGENTS.md each fails test_doc_citations.py (3 failures). Breaking the folder names in MENTION_RE drops the count to 102 and fails the floor.
• New layout tests (tests/v2/test_design_docs.py): every file is indexed exactly once; each index title matches its file's heading and file name; every key resolves to exactly one file; rules/S resolves to the section file, never to S1-…; a sentence-final rules/S2. is a citation; a file path is not.
• Full suite (20,867 passed), mypy, ruff, the Sphinx HTML and doctest builds (no output), and python -m doctest README.rst.

Reviews

A whole-branch code review and a design-docs review ran in parallel, and a third reviewer checked the fix commits. Every finding is fixed:

• Prose still describing the old layout (grep deviates: on "this file", "this file is the record", the guard list in docs/design/AGENTS.md).
• The misfiled vocabulary blocks.
• Thirteen positional references ("the bullet above", "this file's Excluded block") left pointing at nothing by the move. The lesson is recorded in docs/design/AGENTS.md.

Known and left alone

• A gap in the citation check. A decisions key starting with a digit (decisions/3-0-reevaluations) is still not read by the code-side check, same as before the split. The docs-internal check does read it.
• History keeps the old names. Dated decisions entries and past release-log bullets still say rules.md/decisions.md, since they record what the files were then. Bare #key shorthands inside dated entries (about 90) now read like issue numbers.
• Deferred minors: MENTION_RE has no leading word boundary; nothing checks that each rule file holds the rule its name claims; a rules/P5-style mention is silently not a citation.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.03%. Comparing base (901ab66) to head (3dac055).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #715   +/-   ##
=======================================
  Coverage   99.03%   99.03%           
=======================================
  Files          46       46           
  Lines        4557     4557           
=======================================
  Hits         4513     4513           
  Misses         44       44           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.