tests(differential): a pin names exactly one rule (#508)

[derek73]

A _CROSS_RULE_WINNERS pin now names exactly one rule. The winner guard resolves each pin to one rule's issue — exact where a rule's issue equals the pin, else the single rule whose issue starts with it, refused otherwise — and compares classify()'s answer to it exactly instead of by prefix. Closes #508.

What was wrong

The guard compared with startswith, so a pin was satisfied by any rule whose issue extended it. Measured 2026-09-05 over the 51 rows on master:

• 31 pins are a rule's full issue string reaching only that rule; 17 are short family prefixes reaching exactly one rule. Both are fine and unchanged.
• 2 pins are a full issue string that is ALSO a strict prefix of a sibling's: Bob Jones, author and Bob Jones, compositeur, whose winner's issue the …, the C1 example rule extends. Their comment rested the pin on the C1 regex being unable to reach the string, an argument nothing executed.
• 1 pin is a short prefix reaching three rules: Andrews, M.D. on the bare fix(comma-family).

All three are at 1.4.0 and were latent. What the prefix could not do was fail when it stopped holding: forcing classify() to answer the C1 string for Bob Jones, compositeur passed the old guard and fails the new one (the mutation control in the first commit).

The two commits

1. tests(differential): a pin names exactly one rule — _pinned_rule (exact, else unique prefix, else refused naming the rules it reached), the winner guard compares exactly against the resolved rule, a new pytest-speed guard refuses an ambiguous pin on its own so the failure names the pin rather than a classification, the resolver's control table on hand-built issue lists (exact over prefix, a family prefix, the two refusals, literal case), Andrews, M.D. spelled out to the lone-post-comma rule that wins it (measured: the only rule admitting its recorded shape), and the Bob Jones comment corrected to what now holds.
2. docs(design): a pin names one rule — the dated decisions entry with the 31 / 17 / 2 / 1 breakdown and recipe, the decision, four declined shapes (exact everywhere, an allowlist, a word-boundary prefix, refusing shared prefixes at the ledger), and the finding that Should file order decide between rules whose fields overlap without nesting? (マイケル・ジャクソン goes to whichever of two rules comes first, and the contest check never sees the pair) #498's "a key means a winner is pinned" was hollow for three rows; one sentence in mechanisms.md#CROSS-RULE-OUTCOME-PINS.

Verification

Nothing the gate reads changed: intentional 352 / 247 / 155 / 14 byte-identical at both commits. Full suite green; ruff and mypy clean. Hand-corrupted pins in memory (a bare family prefix; a nonexistent rule) fail both guards naming the pin; resolver mutations (drop the exact branch; accept several) each fail the negative control. One reviewer over both commits, then a three-reviewer pass over the PR; every finding is fixed in place. The most useful: no committed test had pinned exact-versus-prefix, so a revert to startswith survived the suite. test_the_winner_guard_refuses_a_longer_sibling_of_the_pin now forces classify() to answer the C1 string for Bob Jones, compositeur and is the one test that fails under that revert. The resolver also refuses an empty pin, quotes case literally, and tells a reader whose pin reaches no rule that the rule was reworded rather than pointing them at the several-rules case.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.66%. Comparing base (449a7bc) to head (9444269).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #509   +/-   ##
=======================================
  Coverage   98.66%   98.66%           
=======================================
  Files          45       45           
  Lines        3219     3219           
=======================================
  Hits         3176     3176           
  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.