Check ledger rule citations as verbatim excerpts, fix the stale ones

[derek73]

Why

test_citations_are_verbatim_excerpts swept only *.py, and only the colon form's first quote. So the rule citations in tools/differential/expected_since_*.toml — which AGENTS.md puts under the excerpt discipline — were checked by nothing, and so was every citation in another shape. #631's review found five stale ledger quotes by hand. Measured 2026-10-10 by running this PR's check over the tree before it (8e6e524, master after #631): 27 more stale quotes and 5 colon citations quoting nothing; review found 14 more beyond the check's reach (below).

Scanner (tests/v2/test_doc_citations.py)

• Sweeps the ledgers beside the code (this module's own illustrative comments excluded).
• Reads a quote in every shape the tree writes: rules.md#X: "…", rules.md#X -- "…", rules.md#X's Accepted clause ("…"), a verb between (rules.md#S2 consumes "…"), and every quote chained on by "and"/comma/dash.
• Quotable text: a rule's statement and its Accepted: clauses (not example or pointer lines); a section letter's Background (rules.md#H Background); a mechanism's Contract statement; a decisions entry's text. A decisions citation may paraphrase, but what it quotes must be verbatim.
• Fix: decisions.md#X: was looked up in rules.md's statements, so decisions.md#P6: "…" was checked against rules.md#P6.
• A reference with no quote must still name an existing rule, section, mechanism or decisions entry. Lowercase decisions keys are matched; the ### differential-ledger, … arc headings merge onto their one key.
• [...] elision (fragments verbatim, in order, non-empty); -- reads as —, a nested ' as "; #: continuations and hyphen-wrapped IDs followed.
• test_implemented_matches_citing_modules keeps its population: colon-form .py citations only.
• Guards: a reach test asserting every lead shape is live ('s, parenthesis, dash, bare words, plus ledgers, chained, decisions, elided); a test pinning what is quotable (Accepted clause, a Background's wrapped line) and what is not (example lines, a wrapped no-boundary: marker); and _RETIRED_EXCERPTS, the recorded negative control for the quotable text.
• Stated limit: a quote is checked when it stands within four words of its ID or is chained to one that does. A quote further off reads like a name written in double quotes — checking every quote in the paragraph was measured at 139 failures, nearly all names — so it is not checked, and AGENTS.md says to keep a quote beside its ID. Case folds, so emphasis in capitals is unchecked.

Stale citations fixed

Citation	Problem
C1, S2 (title run), T3	reworded rule / unquoted paraphrase (first commit)
P5, P2	reworded by #614
M2 (4 rows)	#601 replaced the maiden walk with the clause-free trailing run; each reading re-verified by parse
S2 "BEGINS a name"	now "OPENS THE STRING"
rules.md#A1 "hesitate too" (4 ledgers)	wrong document — it is AGENTS.md's convention
decisions.md#S2 Accepted (test_pieces.py)	wrong document — rules.md#S2's Accepted clause
decisions.md#S2 paraphrase (4 ledgers)	now quotes the headline and names #544's second exception
A1 segmenter clause (_script_segment.py)	one-word drift
C1 paired initials (5 ledgers), N3 (3), P2 (1)	beyond the check's reach, found by the second review; #563 made C1's speaking word an unambiguous suffix
P2 (#424) and P5 (#425) landing paragraphs	now say they describe the rule as it then stood, cite today's text separately, and point at the dated notes that record later moves

T3: measured, 王·Smith never divides (the dot has a Latin neighbour) and 王Smith reads the same — a mixed-script word W4 never reaches, so O5 decides; the old comment described a mechanism that isn't there. The M2 rule whose names #601 moved now names all four (three comma names to fix(#601), Jane Doe Jr. nee Smith Ma to fix(#601/#602)) in a dated note rather than rewriting its history. No issue strings changed.

AGENTS.md's ledger-citation sentence now names the check, what is quotable, its reach, and the measured dated count.

Reviewed twice: a four-agent first round, then a second round on the fix commit (scanner + prose), whose findings are f481c721.

Verification

• tests/v2/test_doc_citations.py, test_ledger_guards.py, test_rules_doc*: pass
• full suite (rebased on master after Count a lone particle with the run behind it as a name word (#627) #631 and Decide where the name starts once, for title-particle heads (#624) #633): 14847 passed, 110 skipped, 3 xfailed; ruff, mypy clean
• differential gate loop (AGENTS.md release step 1): 1.4.0, 2.0.0, 2.1.0, 2.2.0, 2.3.0 all exit 0

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.01%. Comparing base (6185e6f) to head (c200fff).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #632   +/-   ##
=======================================
  Coverage   99.01%   99.01%           
=======================================
  Files          46       46           
  Lines        4487     4487           
=======================================
  Hits         4443     4443           
  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.