The Software Factory — Proof Before Commit
`verify:` Bindings, the Red Run and Frozen Tests
One Command Per Criterion
A binding sits inline on the acceptance-criterion checkbox:
- [ ] AC2: an empty name is rejected verify: npx vitest run app/name.test.ts -t "AC2" => exit 0
- The form is
verify: <command> => exit N;=> exit 0is the default when the suffix is left off. - A name filter needs care when the root
package.jsonscript itself calls npm again ("test": "cd src && npm run test"): write the filter after a second--(npm run test -- app/name.test.ts -- -t "AC2"), or the nested npm swallows it and every test runs. A script that runs the runner directly takes one--. - The command starts with an allowlisted runner:
node,npx,npm,git,pytest,dotnet,cargoorgo. - Only the lowercase
verify:counts. A variant spelling is an error, not a silent manual criterion. - A criterion no command can prove is tagged
[manual]; one only CI can run is[CI-pending]. An untagged bullet with noverify:is a plan defect. node .claude/core/ac-verify.js list --todo <TODO>checks every binding without running it.
The Red Run
After the tests are written and before any implementation, ac-verify.js red runs the bindings and prints one line per criterion: expected | saw | file:line. That digest goes into the plan. It must be a real red:
- a check that already passes, or an infrastructure failure (a missing test helper, a
SyntaxError, no tests collected), exits non-zero: fix the test and run it again Cannot find moduleon a file the story itself creates counts as a real red- a check that is green by design (a live wiring check the suite already covers) is recorded as
green by design: {why}
Frozen Tests
ac-verify.js freeze hashes the story's test files and its verify: lines. While frozen, the path hook blocks every Write and Edit on those files — the Main Agent's included — and ac-verify.js check catches any other write. A changed frozen file means the story failed: it is restored, never re-baselined over. A test that is genuinely wrong is fixed through check → unfreeze → edit → freeze --reason "{why}".
The Re-Run
After the gate, ac-verify.js run executes every binding and writes a record per story. A criterion is met only when its command ran, exited with the expected code, and at least one test actually passed. A name filter that matches nothing runs no test and exits 0 — that run is vacuous, and a run where no test passed is never met. When a binding fails: fix the code, never the binding.
"Exit 0" is not proof. A test runner that found nothing to run exits 0 too. That is why ac-verify reads the runner's own summary and refuses to count a run in which no test passed.
A binding's `-t` filter matches no test name, and the command exits 0. What does ac-verify record?