Add the Ralph loop delivery standard (docs/ralph-loop.md + §9)

This commit is contained in:
timmy committed 2026-10-16 17:38:47 +00:00
1 parent 52b4f46959
commit 402f420936
2 files changed
+43

No files matched your search

+8
View File
@@ -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: <shell command>` 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.
+35
View File
@@ -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: <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.