Trim the design docs: archive the differential ledger, tidy mechanisms.md, compact shipped measurements (#759)

[derek73]

Closes #759. Docs only, under docs/design/. Nothing under nameparser/ changes.

docs/design goes from about 249,000 words to 202,000. The three items are one commit each. Two review-fix commits follow, then a merge of master (#763, #757).

1. differential-ledger archived (33,103 → 1,441 words)

Each of the eleven ledger arcs is cut to a tombstone, following decisions/README rule 3: date, issue, verdict and SUPERSEDED by 2026-10-13 #664. Harvested arcs keep their framing lines.

• Kept in full: the retirement entry (Replace the differential ledgers with a committed snapshot of corpus readings #664), which is the decision still in force.
• Kept, because they are about code and process the ledgers didn't take with them: three Declined entries — the Policy annotations / .pyi stub, _check_tree's predicate, and the DEFAULT_BASELINE checklist step.
• Kept as one line each, because other files cite them:
  • the 'Donald mc' decline, cited by decisions/suffix-acronym-collisions and v1-xfail-triage;
  • the initials view, cited by decisions/R4 and by the 2.3.0 release-log bullet. That line now points at the bullet's evidence at fe85bb3.

The full text is at git show fe85bb3d:docs/design/decisions/differential-ledger.md. mechanisms.md#RECORDED-ROSTERS used to say this entry keeps the roster measurements; it now points to git through it.

2. mechanisms.md (14,557 → 10,902 words)

• Labels on their own lines. Every entry's labels now open their own paragraph. This is load-bearing: test_doc_citations reads a Contract statement up to the end of its paragraph, so in the old one-paragraph layout every sentence of an entry was quotable. The preamble now says so.
• ONE-PREDICATE-PER-QUESTION and RENDER-HONORS-THE-PARSE (1,856 and 2,771 words) are cut to their contract, a short How it works, and Lives-in rosters naming each predicate with its issue and decisions entry. Every predicate and module in the rosters was checked against the code.
  • Two code comments quote sentences from outside the old contract: _group.py's "where the reader comes AFTER the decider…" and _render.py's "a token the parse never saw…". Those sentences moved into the Contract paragraphs, so no comment changes.
  • The census and case history are in git at fe85bb3.
  • One piece no decisions entry held moves to decisions/R3's 2026-09-13 HumanName.initials() re-derives the conjunction decision instead of honoring the parse's tags: john e smith gives j. s. from the facade and j. e. s. from parse() #528 entry: the facade's spliced-field divergence under a caller-added conjunction (太.). I re-ran it on this tree and it holds.
• Retired: LEDGER-RULE-SEPARATION and CROSS-RULE-OUTCOME-PINS. Both were already "Retired with the ledgers" stubs that lived in nothing, and no code or test cites either.
• Kept on purpose: the other entries that no code cites — SPANS, STRUCTURE-GATES, LICENSED-BY-NEIGHBOR, STATE-OFFSET-CHANNELS, PIPELINE-STAGE-CONTRACTS, CLAUSE-CONTENT-OVERRULES-DELIMITER, CURATED-VOCABULARY-ALTERNATION, COMPILED-DATA-COMMITTED, CANONICAL-VOCABULARY-AT-THE-BOUNDARY, VOCABULARY-FEEDS-STRUCTURE, WARN-AT-THE-CALLER, LEGACY-STATE-SIGNATURE, MAKE-WRONG-STATES-UNREPRESENTABLE, and five verification shapes. Each describes a pattern that is live in the code, and the catalog exists for recall, not citation.
  • SENTINEL-SET-OVER-MATCH-CHECK's code went with the ledgers. It stays because its lesson is general (the empty-string probe misses .+) and the differential-ledger tombstone cites it.

3. Compaction sweep under rule 3

The sweep covered the 22 largest files after differential-ledger. Every compacted change shipped in v2.5.0 or earlier; the unshipped PRs are #737, #741–#746, #755 and #756, and spot-checks used git tag --contains. Three triggers apply, and nothing else was touched:

• a whole entry headed SUPERSEDED by becomes a tombstone;
• a superseded passage inside a live entry is cut to its decision and what replaced it;
• a measurement paragraph of a shipped change is cut to one line naming population, counts, baseline and PR.

These always stay: verdicts, reasons, Accepted costs, Declined/Excluded/Open blocks, measurements of declined or unshipped changes, harvested framing lines, any recipe a release-log bullet rests on, and anything quoted or pointed at from elsewhere.

File	Words	What was compacted
M2	14,882 → 12,136	#412/#417/#418, #434, #533 (+review), #397 follow-up, #535 and #538 measurements; the passages #601 and #549 superseded (release checks, view checks, anchored head); the #731 entry → tombstone
R4	13,819 → 12,877	#407, #458, #459 and #461/#397 measurements; the dotted-shape default-path passage, finding (a)'s splitting half, and #541's "Also left" sentence → one sentence each
H5	5,292 → 4,192	#316/#489 population, /simplify class sizes and null result, and #623 results → one line each; #614's passage superseded by #623
cjk-full-stops	4,706 → 3,410	what moved, the axis-11 invariant, parse cost; the halfwidth-kana passage closed by #594
S6	3,887 → 2,678	WHERE THE FACT LIVES cost totals, blast radius, report inventory
S2	4,589 → 3,662	#614, #620 and #625 MEASURED, COST, review classes
S9	6,234 → 5,529	the comma harness and the #563/#564 measurements
P5	6,353 → 5,806	#369, #425 and #637/#640 measurements
S7	4,053 → 3,481	#544 MEASURED and the addendum's measurement and frames
P6	6,127 → 5,685	#379/#380, #405 and #613 measurements
R3	5,721 → 5,271	#408's gate run, #528's population, differential and recompute, #461's blast radius and frames, #585's verification
T4	2,512 → 2,043	the #731 entry → tombstone; its gap and declined option predate #731 and still stand, so they stay, with a scoping lead; the #723 grid
generational-words	1,452 → 1,032	the run-start passage superseded by #679; the #661 and #679 measurements
cjk-comma-demotion	3,465 → 3,082	#469 and 2026-09-05 COUNTS
H1	3,288 → 2,898	#410, review-round-2 and #720 measurements
suffix-acronym-collisions	4,263 → 3,904	#342 and #540 measurements
R5	4,558 → 4,299	capitalized_forced population, #492 MEASURED
S10	3,672 → 3,380	#718's re-pinned rows, the stand-down #722 removed, #721's WHAT MOVES
P3, P8, R1, phd-merge, M3	small	one measurement line each (P3 #397, P8 #383/#479, R1 #511); phd-merge's half superseded by #511; M3's old pin sentence

Unchanged on purpose: P1, whose entries are evidence, a recorded trap, or a declined proposal, and vocabulary-collisions, whose superseded clause is quoted verbatim by suffix-acronym-collisions. The other ~60 decisions files are not swept in this PR.

Review

I ran the design-docs-reviewer over the diff, then over the fix commit, as AGENTS.md asks.

• The first round found ten issues; nine are fixed in 5bd64ce:
  • the Should john smith nee x x read like JOHN SMITH NEE X X? A shape-only numeral in a maiden clause #731 tombstone had cut a gap that predates Should john smith nee x x read like JOHN SMITH NEE X X? A shape-only numeral in a maiden clause #731 and is still live;
  • tombstones had dropped harvested framing lines;
  • the tooling-arc tombstone superseded Declined entries about surviving code;
  • H5 called 毛 泽东 Dr. a rules example;
  • H5 dropped two results, and S2 gave the whole stress grid a classification measured on one slice of it;
  • S9 pointed at S6 totals that had been cut;
  • R3 had two entries dated 2026-09-13 HumanName.initials() re-derives the conjunction decision instead of honoring the parse's tags: john e smith gives j. s. from the facade and j. e. s. from parse() #528;
  • the release bullet's pointer was weak;
  • two entry heads had been edited.
• Left as is: decisions/R2's dated pointer to RENDER-HONORS-THE-PARSE for a gap that rules.md#R3's "a conjunction never initials" is unqualified: Juan de y has base y and initials J. #461 has since closed.
• The second round found three more, fixed in a4fed35: wrong cluster counts on the initials-view tombstone, the T4 lead re-anchoring "the committed grid" (which the revert deleted), and an "only" in H5's frames line. a4fed35 also adds both kinds of trap to decisions/README rule 3, so the next compaction meets them. - A third round, on a4fed35, found no confirmed defect and two scoping issues, fixed in the last commit:
  • T4's lead now also marks the declined option's "closes both" as Should john smith nee x x read like JOHN SMITH NEE X X? A shape-only numeral in a maiden clause #731's measurement, since an approximation re-run leaves 27 of 396 report pairs differing.
  • Rule 3's tombstone definition itself now says a tombstone keeps what the superseding entry did not replace, instead of a later sentence contradicting it.

Checks

On the merged tip:

• uv run pytest -q: 21,879 passed.
• uv run mypy and uv run ruff check: clean.
• The doc guards (test_design_docs, test_doc_citations, test_rules_doc, test_rules_budget) pass.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.05%. Comparing base (991a6f9) to head (875e705).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #764   +/-   ##
=======================================
  Coverage   99.05%   99.05%           
=======================================
  Files          47       47           
  Lines        4642     4642           
=======================================
  Hits         4598     4598           
  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.