444: a citation a commit adds says what it cites, and the backlog gets counted

[calef]

Lane: milestone/444-citations-say-what-they-cite, written by an agent; calef's account is the author GitHub shows.

Milestone 444, on calef's ruling of 2026-09-19: "add the gloss ratchet and launch a lane to address the 17% that fail today."

The ratchet

script/citations --ratchet, run by script/lint as "new citations say what they cite". It reads the diff against git merge-base HEAD origin/main, never the tree, so a lane is asked only about text it wrote. The rule is per number per file: a milestone N or §N on an added line passes if that number, under that scheme, is glossed somewhere in the same file. A paragraph naming §151 four times explains it once.

Proved both directions. Silent on the clean branch. A planted line citing three records reported exactly two of them and stayed quiet about the third, because the file already glossed that one; the transcript is in notes/citations.md's EXAMPLES and the line was removed in the next commit.

Priced before it was turned on, by replaying each lane's own diff over the 42 pull request merges from #953 to #1002: a median of 16 asks per pull request, 8 of the 42 silent, one outlier of 893 (#970, 24 proposal files at once).

What it cannot catch is written beside the check: a citation arriving in a merge commit, a grounded gloss that is still the wrong citation, the permanent per-file escape, a parenthetical that opens with the citation, and captured logs and the generated index being out of the corpus.

The census, which is the deliverable nobody has seen

script/citations --census, reporting only:

                    files  citations   named  unnamed  no record
roadmap proposals      23        196       5      101          0
roadmap blocks        439       5224     212     2351          0
decisions             188       1944      66      984          0
design/ (other)        25        444      38      224          0
notes/                175       3408     131     1660          0
Rust                  395       5867      33     2738          0
scripts                64        716      12      399          0
manifests              55        370       7      260          0
CI workflows           13         64       0       44          0
everything else        70        284       1      217          0
total                1447      18517     505     8978          0

505 of 9,483 (file, number) pairs carry a gloss: 5.3%. The "83% split-proof by habit" figure is true of the 560 citations that carry a gloss; over the whole population it is 5%. Both are honest and about different sets, and the second is the one that prices the backfill.

The zero was re-checked rather than believed. A git grep for citations turns up six-digit numbers; they come from binary bench captures through the "Binary file ... matches" trap script/decisions records, and the census skips a file containing a NUL byte.

The backfill, and what was left

25 pairs in README.md, CONTRIBUTING.md and SECURITY.md: the documents a stranger reads before they have a checkout. SECURITY.md earned the choice, where a person reporting a DMA escape met three bare decision numbers. notes/scripts.md (50) and notes/README.md (128) were looked at and deliberately left: their rows already describe the target, so the number is provenance rather than a pointer. Dated accounts and quotations were left under design/naming.md's rule that a dated record keeps its words. The remaining 8,953 pairs are re-derivable with script/citations --census --list, which is why no copy of the list exists.

Gates

script/lint 0, script/citations --check 0, script/citations --ratchet 0, script/roadmap --check 0, script/names 0 (refusals unchanged), /bin/dash -n script/citations clean. This lane took the nife-dev toolchain link. The index row for 444 is not written: script/roadmap --write is the integrator's at merge.

Names are provisional: --ratchet and --census, and the lint section title "new citations say what they cite".

🤖 Generated with Claude Code

https://claude.ai/code/session_01STu3VeDYnEHem3iKCbzBF2

[calef]

merge-drain: STALLED. #1003 took the call but is neither queued nor armed