From 402f420936bebe79dafde4b485aade5b936ed9ef Mon Sep 17 00:00:00 2001 From: Timmy Date: Fri, 16 Oct 2026 15:22:08 +0000 Subject: [PATCH] =?UTF-8?q?Add=20the=20Ralph=20loop=20delivery=20standard?= =?UTF-8?q?=20(docs/ralph-loop.md=20+=20=C2=A79)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- STANDING-AGREEMENT.md | 8 ++++++++ docs/ralph-loop.md | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 docs/ralph-loop.md diff --git a/STANDING-AGREEMENT.md b/STANDING-AGREEMENT.md index ed40856..16368d0 100644 --- a/STANDING-AGREEMENT.md +++ b/STANDING-AGREEMENT.md @@ -100,3 +100,11 @@ These apply to Zeph and to Timmy equally. They are the price of being trusted wi Changes to this file go through a pull request to it. Alexander's decisions bind; Timmy's decisions bind within the boundaries above; beyond them, ask, and asking goes through this repo. + +## 9. The Ralph loop — delivery standard + +Every deliverable ends with a `CHECK: ` that exits 0 when the work is correct. The runner +(`ralph-loop.sh`, spec in `docs/ralph-loop.md`) runs that CHECK and enforces the loop: green ships; red feeds +the failure back and the wizard fixes + re-emits, max 3 iterations, then escalation to Timmy. A missing +`CHECK:` counts as red. A `CHECK:` that is a tautology (`true`, `echo ok`, `exit 0`) is a fault, not a +verification. No deliverable is done on a claim — it is done when its CHECK exits 0. diff --git a/docs/ralph-loop.md b/docs/ralph-loop.md new file mode 100644 index 0000000..6175599 --- /dev/null +++ b/docs/ralph-loop.md @@ -0,0 +1,35 @@ +# 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: +``` + +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: — check "" = after 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.