Make a ledger rule that explains nothing say why (#372)

[derek73]

Closes part of #372: a rule that stops explaining anything is invisible. Reverting a fix leaves its rule inert and the run exits 0 — demonstrated in the issue, where reverting #370's fix failed 5 unit tests but produced no ledger or differential failure at all.

[[change]] rules gain an optional dormant = "<reason>". Two tiers fail without it:

• static — tests/v2/test_ledger_guards.py fails in CI when a rule's name_regex reaches no corpus name. No baseline wheel needed, so it is cheap and early.
• dynamic — compare.py fails the run when a rule explained no diff. Always on, not behind a flag: a check nobody passes a flag to is a check that does not exist.

Both directions fail — a rule declaring dormant that explains a diff is a false statement in the ledger, and is reported too.

When a rule explains nothing the harness says which kind, because the three have three different fixes: reverted (matched no diffing name), shadowed by <issue> (an earlier rule claimed every diff it would have), or refused by a [[never]] exclusion.

The two rules that legitimately explain nothing today — fix(suffix-delimiter-rendering) and the ambiguous-surname-acronym data change — now carry their reason.

Measured

Gates unmoved: 108 intentional / 0 unexplained at 1.4.0, 1 / 0 at 2.1.0, both exit 0. Suite 3214.

Every guard was demonstrated failing by mutation, on its own assert:

Mutation	Result
Drop a dormant declaration	static guard fails, naming the rule
Point a live rule's regex at nothing	harness exits 1, reports reverted
Declare a firing rule dormant	harness exits 1, reports no longer dormant
Drop the dormancy terms from main()'s return	new wiring tests fail
Delete both report loops	new wiring tests fail

The last two exist because review found the wiring commit had no regression coverage: reverting the exit-code fold left all 116 tests green. dormant_rules() was well unit-tested as a pure function while the composition was not — the gap _run_main's own docstring was written about.

dormant_rules() is pure over (rules, explained, diffing) so pytest exercises all three diagnoses without a wheel. It sorts internally: main() classifies against _sorted_rules, and a diagnosis computed against a different order would name a rule that did not actually win.

One pre-existing test fixture had a permanently shadowed rule, which the new check correctly flagged; it is declared dormant so the test keeps pinning sort order alone.

Deliberately out of scope

#372 stays open for these:

• Ambiguity reporting. Measured: 28% of claimed (name × role) pairs already have two or more matching rules — 432 of them fix(comma-family) under fix(suffix-routing) alone. A report firing on 28% of what it inspects is wallpaper. The shadowed diagnosis above delivers the slice that costs something.
• A specificity floor for fields-only rules. There is exactly one such rule in any ledger, naming 3 of 7 roles. The check would fire on nothing, and nothing would reveal it was vacuous.
• Narrowing fix(suffix-routing) / fix(comma-family). Needs this detector first, to have a success criterion at all: "did narrowing wake a shadowed rule?" is answerable, "does this rule describe that diff?" is judgement.

Known gap, documented

expected_since_2.0.0.toml is never run by the release checklist, so its rules get static coverage only — and the static tier exempts on the mere presence of dormant without checking the reason is still true. A wrong dormant is caught in the ledgers the checklist runs and is unauditable in the ones it does not. Recorded in tools/differential/README.md; closing it means widening the checklist or sweeping every ledger.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.51%. Comparing base (e6a9085) to head (44d57ae).
⚠️ Report is 17 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #373   +/-   ##
=======================================
  Coverage   98.51%   98.51%           
=======================================
  Files          44       44           
  Lines        2895     2895           
=======================================
  Hits         2852     2852           
  Misses         43       43           

☔ 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.