Domdhi logoDOMDHI.OS
BACK_TO_COURSE

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.

INFO

Exit codes 10 to 13 mean the result was recorded successfully. A scheduler that sees one should read the record, not retry the run.

QUIZ

Why can't a run be recorded as passed with a commit made by a plain `git commit`?

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