#250: what a check may rest on, and what mutation-proven may mean

[Polichinel]

Closes #250. Gate 3 of epic #241 — the two paragraphs that stop the next round.

Three amendments, all short, all bought with the two days this arc cost.

ADR-017 §7a — what a check may rest on

A check here may rest on a fact we own, on a fact another repository has declared in the public registry, or on an outcome we can observe. It may never rest on another repository's implementation.

ADR-003 already said declarations over inference. It had been applied rigorously to the product and not at all across the repository boundary — and every defect in C-89…C-92 sat on the wrong side of that line.

The evidence is in the clause: the source-reading check broke twice in 24 hours, and 8615574 / 0c493ae each introduce the named constant and add that repository's registry-binding test. The improvement and the breakage were one edit.

ADR-017 §7b — an ADR records a decision, never the current state of the code

This is the root cause the post-mortem identified.

Both ADR-016 and ADR-017 described what the code did when they were written — "this is the shape the registry check now has". Every such sentence needed an erratum the first time the code moved: nine stale claims in two days, one of which repealed a rule in ADR-017 on a premise false by six hours.

An ADR states a decision, its reasoning, and what would reverse it. It does not describe the current implementation. Where a reader needs to know what the code does now, the ADR names the test or module that answers.

ADR-014 §2 — what "mutation-proven" may mean

A diagnostic, not a process rule:

If a guard can only be proven against inputs you invented, that is the signal the guard is on the wrong side of a boundary — it is verifying a fact you do not own.

Measured: 13 forms proposed by the guard's author, 13 caught; 29 proposed independently, 15 missed.

Deliberately not adopted: independent mutants for every guard. The friction would exceed the disease for a single maintainer, and it is worth buying only for the silent-failure class.

Sizes

34 lines in ADR-014, 46 in ADR-017. Short on purpose — #250's own acceptance criterion was that the ADR-014 amendment fit in a screen.

C-93 resolved. The register's guards caught me retitling it in place without moving it, then caught the header counts — which is what they are for.

ruff check .    # clean
pytest -q       # 415 passed, 1 skipped, 40 xfailed

🤖 Generated with Claude Code