The Software Factory — Proof Before Commit
Run Records, Traces and the Scoreboard
Every Run Leaves a Record
run-record.js
start opens a run and gives it a run id; wave records the current wave, story and plan; finish closes it with one result:
| Exit | Result |
|---|---|
| 0 | passed, or nothing-to-do |
| 1 | failed |
| 2 | invalid input |
| 10 | needs-human |
| 11 | blocked |
| 12 | budget-exhausted |
| 13 | killed |
finish --status passed is refused without the commit, the gate receipt and the ship token — and --ship-token OK only when that commit carries the Ship-Check: trailer. SKIP (with --receipt none) is accepted only for a commit carrying the audited Ship-Check-Skip: trailer. Either way, a run can only be recorded as shipped through the commit helper's check. The run's counters land in the plan as one **Run record:** line.
run-trace.js
snapshot appends a row as each wave closes; report assembles the whole run into run-trace.json and run-trace.md under docs/.output/.state/work/.
run-scoreboard.js
A read-only view across runs: gate pass rates and, per commit, whether it was sealed, skipped, missing or unknown (--rolling N, default 10; --json). It answers "are the agents good?" from records, not impressions.
test-cost.js
Every wave or story prints its test lines added per source line added. Above about 2:1, on a change with at least 20 source lines added, it prints TEST_COST_FLAG — a prompt for the reviewer to look for exact pins on values that are not contracts, never a gate.
Exit codes 10 to 13 mean the result was recorded successfully. A scheduler that sees one should read the record, not retry the run.
Why can't a run be recorded as passed with a commit made by a plain `git commit`?