BACK_TO_COURSE
The Software Factory — Proof Before Commit
Run Limits: the Failure Ledger and the Budget
Stop Before a Loop Burns the Afternoon
The Failure Ledger
Every failing gate run writes a row to docs/.output/.state/telemetry/gate-failures.jsonl with a signature: a hash of the failing test names and details, normalized so paths, timestamps, ids and durations do not make the same failure look new. A focused test run outside the gate is recorded with node .claude/core/_lib/failure-ledger.js record.
- The same signature on a changed tree is a genuine repeat; on the same tree it is not counted again
- Flaky and environment failures never count; KILLED and TIMED OUT are neutral; a pass resets the streak
| Failure | Same signature? | Action |
|---|---|---|
| 1st | — | Fix directly, or re-dispatch with a PRIOR FAILURE block from the ledger |
| 2nd | yes, on a changed tree | One attempt by a deep-tier subagent, with both failures in its brief |
| 3rd | yes | Stop and ask the owner (needs-human when headless) |
The Budget Line
A run plan carries one line that caps the whole run:
**Budget:** attempts=3 gate-failures=6 dispatches=40 minutes=240
/run-todoscales it to the plan:minutes= 60 × open waves,dispatches= 8 × open stories,gate-failures= the larger of 6 and 2 × waves,attempts= 3/doruns with no budget unless--budgetis passed- before every fan-out or retry,
node .claude/core/_lib/failure-ledger.js budgetchecks it; a limit is spent only when usage goes over it - a spent limit (exit 12) stops the run and asks the owner; a raise is recorded in Owner Decisions, and a headless run ends
budget-exhausted
TIP
Gate failures and dispatches are counted from project-wide ledgers, so another session's failures in the same window count against your run too. A surprising budget stop is worth reading, not just raising.
QUIZ
The same gate failure signature appears for the second time, after the code changed. What happens?
Sign in to track lesson progress and earn a certificate.SIGN IN TO SAVE PROGRESS