proof

Proof

Iron Law

NO ENGINEERING CLAIM WITHOUT A NAMED PROOF.

A proof is a named check that would fail if the claim were false. "The tests pass" does not count until you can say which test would break if you were wrong.

When to Use

• As the completion gate before any reply that says or implies the work is done, fixed, ready to commit, ready for a PR, or passing.
• Writing or reviewing behavior tests for any change or flaky test.
• Turning an agreed spec, model, contract, or root cause into Proof Contracts and runnable checks.

When NOT to Use

• Edits with no behavior surface: formatting, typos, comments, renames and moves that tooling already confirms.
• A bug whose cause is not pinned down: debugging first.
• Design, naming, structure: code-review. Benchmarks: performance. Test runner setup: scaffolding.

Rules

1. Every non-trivial claim owes a check. If you cannot point to one, mark the claim unproven and say which evidence is missing. Silence is not proof.
2. Match the proof to the claim: a behavior change needs a runnable check at the boundary, a new endpoint a contract test, a bug fix a regression test that fails before and passes after, a refactor the same behavior before and after, a data claim an invariant.
3. Test at boundaries, in the caller's words: where the data's shape, value, state, or error visibly changes, and always at the outermost boundary the caller sees (endpoint, CLI, UI, public API). Boundary tests survive refactors; unit-test only non-trivial pure logic.
4. One behavior per test. Real collaborators inside; mock only true system edges (network, clock, filesystem) or write the reason. Never test the framework, the language, or static text.
5. A flaky test is a bug in the test, the code, or the environment. Fix it. No sleeps, no retries.
6. Red before green when the failing test is itself the evidence: a reproducible bug, a behavior change with a clear observable, a contract change. A test that passes on its first run proves nothing; verify the red as deliberately as the green.
7. Prove artifacts the way the system uses them: run, load, parse, render, or inspect config, wiring, generated output, and documents. Never assert literal text.
8. For a removal, prove the behavior that remains and confirm the old code is gone with a search. Test the removal itself only when it now returns an explicit rejection (404, 410, deprecation error): that is new behavior.
9. Narrowest check first: one test by name or line, then the file. Once a failing test is known, iterate on that failure until it is green. Run the whole package or suite after major changes, before completion or commit, or when targeted green evidence suggests wider breakage. An unrelated broad failure is reported separately, not treated as blocking.
10. "Done" is a claim. Before saying it: re-read the latest request and any corrections, look at every named file as it stands after your last edit, run the chosen check fresh, and report proven, partly proven, blocked, or unproven. Smoke and helper-only checks are partial, not acceptance.