Repository navigation
Check ledger rule citations as verbatim excerpts, fix the stale ones - #632
Merged
Merged
Conversation
derek73
added a commit
that referenced
this pull request
Oct 10, 2026
The first commit checked only the colon form's first quote, and the review of #632 found the rest of the class: `rules.md#X -- "..."`, `rules.md#X's Accepted clause ("...")`, `rules.md#S2 consumes "..."` and a second quote chained by "and" all passed unread, 23 of them stale. The scanner now: - reads a quote after the ID in any of those shapes (_LEAD_RE), and every quote chained to it; a reference with no quote must still name a real rule, section, mechanism or decisions entry - quotes against a rule's statement AND its Accepted: clauses (example and pointer lines excluded), a section letter's Background (`rules.md#H Background`), a decisions entry's text - matches lowercase decisions keys, merges the `### differential- ledger, ...` arc headings onto their one key, rejects empty "[...]" fragments, reads `--` as the em dash and a nested ' as ", follows `#:` comment continuations and IDs wrapped at a hyphen - skips this module's own illustrative comments - records the retired excerpts as a negative control, and asserts the sweep reaches each shape (non-colon, chained, decisions, elided) The colon form alone still defines a citing module for implemented:. Fixed: P5 (the reserve's numeral clause and the join-after-the-run wording, #614), P2 (S2's once-read run), M2 (#601 replaced the walk with the clause-free trailing run; the 'Jane Doe Jr. nee Smith Ma' paragraph gains a dated note that #601 moved it to fix(#601/#602)), S2 ("OPENS THE STRING"), A1's segmenter clause, a decisions.md#S2 citation of rules.md#S2's Accepted clause, and four ledgers crediting AGENTS.md's "a reader would hesitate too" to rules.md#A1. Four ledgers' paraphrase of decisions.md#S2 now quotes its headline and names #544's second exception. With Accepted text quotable, the first commit's H5 and S2 rewrites go back to the original, more exact Accepted-clause quotes. Co-Authored-By: Claude Opus 5.5 <[email protected]>
derek73
added a commit
that referenced
this pull request
Oct 11, 2026
Scanner (tests/v2/test_doc_citations.py):
- a section's Background is read whole, not its first line; a wrapped
no-boundary: marker's continuation lines are no longer quotable
- each citation records its lead, and the reach test asserts every
lead shape is live ('s, parenthesis, dash, bare words) rather than
any one of them; a new test pins what is quotable (an Accepted
clause, a Background's wrapped line) and what is not (an example
line, a no-boundary: continuation)
- the docstring states the limits: case folds, and a quote more than
four words from its ID and chained to nothing is not checked -- the
measured alternative, every quote in the paragraph, flags 139, nearly
all names written in double quotes
- _RETIRED_EXCERPTS drops its P6 row (no version ever routed a
decisions quote to a rule) and says which direction it guards
Ledgers: fourteen stale quotes the check does not reach, found by the
review -- C1's paired-initials sentences in all five (#563 made the
speaking word an UNAMBIGUOUS suffix), N3 in three, P2 in one. Dated
landing paragraphs for P2 (#424) and P5 (#425) now say they describe
the rule as it then stood instead of quoting today's text as their
reason; the M2 rule's opener names all four names #601 moved, not one.
AGENTS.md: the count is measured, not summed from commit messages --
27 stale quotes and 5 quoteless colon citations, the current check
over e4b653a -- and the sentence states the four-word reach.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
test_citations_are_verbatim_excerpts swept only *.py, so the `# rules.md#X: "..."` comments in tools/differential/expected_since_*.toml -- which AGENTS.md puts under the same excerpt discipline -- were checked by nothing; #631's review found five stale by hand. The sweep now reads the ledgers too. They are not "citing modules": test_implemented_matches_citing_modules still counts .py files only. Two scanner corrections the ledgers were the first input to reach: - a decisions.md#X citation was looked up in rules.md's statements (the regex accepted the doc name and dropped it), so a decisions.md#P6 quote was checked against rules.md#P6. It now must name a real decisions entry, and a quote OPENING it must be verbatim in that entry; a paraphrase pointer stays legal, the entry being a record rather than a statement. - an excerpt may elide with "[...]"; each fragment must be verbatim and in order. The fifteen failures (five citations, copied across ledgers): - H5 and S2 (1.4.0) quoted Accepted clauses; now quote statements that carry the same claim. - C1's "The part is read as its words stand" is now a longer sentence. - 2.2.0/2.3.0 S2 paraphrased with no quote; now quotes the sentence. - T3 paraphrased a mechanism that is not there: '王·Smith' is one word (the dot has a Latin neighbour) and '王Smith' reads the same; it now cites T3 and W4 for why no script order applies. Adds a reach assertion so a glob matching nothing cannot pass the excerpt test vacuously, and an elision-order test. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The first commit checked only the colon form's first quote, and the review of #632 found the rest of the class: `rules.md#X -- "..."`, `rules.md#X's Accepted clause ("...")`, `rules.md#S2 consumes "..."` and a second quote chained by "and" all passed unread, 23 of them stale. The scanner now: - reads a quote after the ID in any of those shapes (_LEAD_RE), and every quote chained to it; a reference with no quote must still name a real rule, section, mechanism or decisions entry - quotes against a rule's statement AND its Accepted: clauses (example and pointer lines excluded), a section letter's Background (`rules.md#H Background`), a decisions entry's text - matches lowercase decisions keys, merges the `### differential- ledger, ...` arc headings onto their one key, rejects empty "[...]" fragments, reads `--` as the em dash and a nested ' as ", follows `#:` comment continuations and IDs wrapped at a hyphen - skips this module's own illustrative comments - records the retired excerpts as a negative control, and asserts the sweep reaches each shape (non-colon, chained, decisions, elided) The colon form alone still defines a citing module for implemented:. Fixed: P5 (the reserve's numeral clause and the join-after-the-run wording, #614), P2 (S2's once-read run), M2 (#601 replaced the walk with the clause-free trailing run; the 'Jane Doe Jr. nee Smith Ma' paragraph gains a dated note that #601 moved it to fix(#601/#602)), S2 ("OPENS THE STRING"), A1's segmenter clause, a decisions.md#S2 citation of rules.md#S2's Accepted clause, and four ledgers crediting AGENTS.md's "a reader would hesitate too" to rules.md#A1. Four ledgers' paraphrase of decisions.md#S2 now quotes its headline and names #544's second exception. With Accepted text quotable, the first commit's H5 and S2 rewrites go back to the original, more exact Accepted-clause quotes. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Scanner (tests/v2/test_doc_citations.py):
- a section's Background is read whole, not its first line; a wrapped
no-boundary: marker's continuation lines are no longer quotable
- each citation records its lead, and the reach test asserts every
lead shape is live ('s, parenthesis, dash, bare words) rather than
any one of them; a new test pins what is quotable (an Accepted
clause, a Background's wrapped line) and what is not (an example
line, a no-boundary: continuation)
- the docstring states the limits: case folds, and a quote more than
four words from its ID and chained to nothing is not checked -- the
measured alternative, every quote in the paragraph, flags 139, nearly
all names written in double quotes
- _RETIRED_EXCERPTS drops its P6 row (no version ever routed a
decisions quote to a rule) and says which direction it guards
Ledgers: fourteen stale quotes the check does not reach, found by the
review -- C1's paired-initials sentences in all five (#563 made the
speaking word an UNAMBIGUOUS suffix), N3 in three, P2 in one. Dated
landing paragraphs for P2 (#424) and P5 (#425) now say they describe
the rule as it then stood instead of quoting today's text as their
reason; the M2 rule's opener names all four names #601 moved, not one.
AGENTS.md: the count is measured, not summed from commit messages --
27 stale quotes and 5 quoteless colon citations, the current check
over e4b653a -- and the sentence states the four-word reach.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
e4b653a lived on #631's branch, which the squash merge leaves to be deleted; 8e6e524, master after #631, has the identical tree. Co-Authored-By: Claude Opus 5.5 <[email protected]>
derek73
force-pushed
the
fix/ledger-citation-excerpts
branch
from
October 11, 2026 03:34
f481c72 to
c200fff
Compare
derek73
changed the base branch from
fix/issue-627-lone-particle-count
to
master
October 11, 2026 03:34
Codecov Report✅ All modified and coverable lines are covered by tests. 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. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
test_citations_are_verbatim_excerptsswept only*.py, and only the colon form's first quote. So the rule citations intools/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)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.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.decisions.md#X:was looked up in rules.md's statements, sodecisions.md#P6: "…"was checked against rules.md#P6.### 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_moduleskeeps its population: colon-form.pycitations only.'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 wrappedno-boundary:marker); and_RETIRED_EXCERPTS, the recorded negative control for the quotable text.Stale citations fixed
_script_segment.py)T3: measured,
王·Smithnever divides (the dot has a Latin neighbour) and王Smithreads 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 tofix(#601),Jane Doe Jr. nee Smith Matofix(#601/#602)) in a dated note rather than rewriting its history. Noissuestrings 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🤖 Generated with Claude Code