Domdhi logoDOMDHI.OS
BACK_TO_COURSE

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 0 is the default when the suffix is left off.
  • A name filter needs care when the root package.json script 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, cargo or go.
  • 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 no verify: 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 module on 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.

WARNING

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

QUIZ

A binding's `-t` filter matches no test name, and the command exits 0. What does ac-verify record?

Sign in to track lesson progress and earn a certificate.SIGN IN TO SAVE PROGRESS