troupe-standup/docs/ralph-loop.md

The Ralph loop — delivery standard

Named after the loop in "Hyperoptimized Engineer 2026": the interface tests itself, and the agent fixes until the completion check passes. This is the troupe's delivery law — no deliverable is "done" on a claim. It is done when its CHECK exits 0.

The contract

Every wizard deliverable ends with one line:

CHECK: <shell command>

The command must exit 0 when the work is correct, and non-zero when it is not. It is the machine-enforced definition of "done": a test run, a sha256sum, a curl status, a grep count, a git cat-file, a census — anything a shell can verify against the actual artifact.

The loop (enforced by ralph-loop.sh)

1. Run the wizard on its task.
2. Extract the CHECK: line from its output.
3. Run the CHECK (60s timeout, in the troupe repo).
4. Exit 0 → GREEN. Shipped.
5. Non-zero → RED. Feed the failure output back to the wizard — "fix it and re-emit a CHECK".
6. Repeat, max 3 iterations. After 3 REDs → ESCALATE to Timmy. Never silently pass.

Rules

• A missing CHECK: line counts as RED.
• The CHECK must be a real verification, not a tautology (echo ok, true, exit 0). It must exercise the actual artifact — the thing that was just built, fixed, or claimed.
• VERDICT: format: VERDICT: <status> — check "<cmd>" = <exit code> after <N> iterations.
• No invented green. The runner runs the CHECK itself; a wizard cannot claim a pass it did not earn.
• A red CHECK is not a failure of the wizard — it is the loop doing its job. Fix and re-emit.