A ledger rule's explained set is printed but never checked, so a diff can shrink underneath it and every run stays green

[derek73]

compare.py computes by_issue -- the exact set of names each rule explained -- prints it (tools/differential/compare.py:868), and then passes only set(by_issue) to dormant_rules. Membership is checked; the counts never are. The only property any run asserts about a rule's reach is "it explained at least one name."

The shape

classify() takes the first rule whose declared fields are a superset of the observed diff. A rule therefore keeps matching when the diff beneath it shrinks -- and shrinking is the common direction, since most parser fixes move fewer fields, not more.

Freiherr von Richthofen V is the case that already happened. #410 narrowed its diff from {given, family, suffix} to {family, suffix}; the fix(#424) a title-led chain before the numeral is the one name piece rule declared all three, so it kept claiming the name and no run named the movement. docs/design/decisions.md#H1 records it:

a shrinking diff kept matching and no run ever named it. A real movement behind a green gate

That rule's fields are ["family", "suffix"] today, narrowed by hand during #410, and it explains exactly 1 name. The instance is closed. The mechanism that let it hide is not.

Why no existing guard sees it

• dormant (Make a ledger rule that explains nothing say why (#372) #373) covers one point on the scale: zero. A rule that explained 8 names and now explains 3 is not dormant, and nothing reports it.
• _CORPUS_CLAIMS measures what a rule's name_regex reaches, not what it explains -- the two differ by the fields test and by rule order. It is a unit test with no baseline worker, so it cannot measure explanation even in principle: the diff set only exists inside a compare.py run.
• _CROSS_RULE_WINNERS pins which rule wins for a hand-picked list of contested names. A wall around known arguments, not a census.

This is the gap #451 reports from the other side. #451's rule hides growth because it has no name_regex; fix(#424) hid a shrink despite having one. Both are "a rule broader than the diff it explains", which decisions.md#H1 already calls "the lesson worth keeping rather than either fix."

Sketch

A per-rule declared reach in the ledger, checked by compare.py against the run's own by_issue:

[[change]]
issue = "fix(#424) a title-led chain before the numeral is the one name piece"
name_regex = "(?i)^freiherr\\s+von\\s+richthofen\\s+v$"
fields = ["family", "suffix"]
explains = 1

Open in the design, not decided here:

• It generalizes dormant. dormant is explains = 0 carrying a reason. Whether the keys merge or sit side by side is part of the design.
• Count, or count plus digest? _Claim already documents why a bare count is weak -- "swapping feat(Support smart quotes (“Jack”), guillemets («Petit»), and CJK brackets as nickname delimiters #273)'s delimiter class for a single accented letter holds the count at 6 while claiming six entirely different names." A digest closes that, at the cost of an unreadable field in a file that is otherwise all prose.
• The cost to weigh. The corpora grow: corpus_issues.jsonl is append-only from the tracker, corpus_rules.jsonl is generated from rules.md, so one harvest moves numbers across many rules at once. _CORPUS_CLAIMS and _CORPUS_FLOORS both already accept a version of this cost, and the discipline is set: "Re-measure rather than adjust them if a parser change moves one: a diff shape that shifted is a finding, not a number to update."
• Where it must live. compare.py, not tests/v2/test_ledger_guards.py -- the guards file has no baseline worker.
• Not this. A specificity floor on role count was declined in Ledger rules classify diffs they do not describe, and a rule that stops explaining anything is invisible #372/Make a ledger rule that explains nothing say why (#372) #373 as vacuous. This is not that proposal.

Relationship to #451

Independent and deliberately unbundled. #451's bundle retires the fields-only rule and lands without this; this closes the half of the shape a name_regex does not protect against. Bundling them would make #451's commits unbisectable.

[derek73]

A sibling proposal from #451's review: a reach ceiling

#451 landed the ban on fields-only rules (#453), and its review surfaced a check that belongs with this issue rather than beside it.

The ban closed the shape, not the property. validate_rules now requires a name_regex, but that bounds nothing by itself: the only width check is the sentinel probe, which rejects a pattern only when it matches all four of _SENTINELS. Measured over the 1090-name corpus:

name_regex = "[a-z]"           passes validation, reaches  941 / 1090
name_regex = " "               passes validation, reaches 1027 / 1090
name_regex = "[^　-鿿]" passes validation, reaches 1063 / 1090

Any of those plus a fields list is the retired catch-all with a fig leaf. What #451 bought is that such a rule now carries a _CORPUS_CLAIMS reach and digest — so its breadth is visible once, to whoever reviews the recorded number, rather than never. And _CORPUS_CLAIMS is by its own docstring "inert for a brand-new rule, whose author simply records whatever number it produces". So the reviewer is the check.

Why here and not its own issue. This issue is "nothing counts what a rule explains". The ceiling is "nothing bounds what a rule reaches". They are the two halves of the same gap — a rule can be too wide on either axis, and neither has a mechanism — and whoever implements the declared-reach modifier will already be in compare.py's validation and _CORPUS_CLAIMS. Splitting them across two issues would mean two designs for one question.

Sketch. No rule may claim more than N% of the corpus without an explicit roster opt-in. Measured today, the maximum is 25.6% — the two comma rules at 279/1090 — with the next highest at 9.9%. A 30% ceiling costs nothing now and is the check that is actually scoped to see this:

expected_since_1.4.0.toml  fix(comma-precomma-family) …   279   25.6%
expected_since_1.4.0.toml  fix(comma-family) lone post-…  279   25.6%
expected_since_1.4.0.toml  fix(#271/#272/#298) native-…   108    9.9%

Open in the design, not decided:

• Ceiling on reach, or on reach × fields? A rule reaching 279 names but narrowing to two roles is not the hazard; one reaching 279 across five roles is. _Claim already records both.
• Where it lives. validate_rules fails at startup and knows nothing about the corpus; test_ledger_guards.py has the corpus but is a unit test. The corpus floors precedent (_CORPUS_FLOORS) puts a corpus-shaped constant in compare.py.
• The opt-in's shape. The two comma rules would need one on day one, so the roster is not hypothetical — and an opt-out that nobody has to justify is the failure dormant was designed against.

Not urgent: no rule is near the ceiling today, and the reviewer-reads-the-number path is a real improvement over what #451 replaced. Filed so the second half of the gap is written down beside the first.

[derek73]

Reopening: the explained-reach half landed in #455 (merged 6ac31f4), but this issue also carries the reach ceiling proposal, which has not been built. GitHub auto-closed on a Closes #452 in a commit message that was scoped in its own next clause — my bookkeeping error, not a decision.

Landed: compare.py now fails the run when a rule's declared fields do not equal the union of the diffs it explains. Fourteen over-declared rules narrowed first (3 at 1.4.0, 5 at 2.0.0, 6 at 2.1.0), so the check was silent on arrival.

Still open here: the reach ceiling — no rule may claim more than N% of the corpus without an explicit opt-in. That bounds what a rule reaches; the landed check bounds what it explains. Measurements are in the comment above: today's maximum is 25.6% (the two comma rules at 279/1090), next highest 9.9%, so a 30% ceiling costs nothing now.