Guarded Ralph loop

# AGENTS.md: guarded agent loop (Ralph style)

This repository may be worked on by an agent running in a loop: the same prompt, a fresh context each pass,
progress kept in files. These rules apply on every pass.

## Each pass
- Read `.ralph/prompt.md`, then `.ralph/plan.md` and the last 20 lines of `.ralph/progress.md`. Nothing else carries over.
- Pick ONE unchecked item from the plan. Do only that item.
- Run the check command from the prompt before you finish. Do not tick an item while checks fail.
- Tick the item in `.ralph/plan.md` and append one line to `.ralph/progress.md`: date, item, result, next step.
- Commit with a message naming the item. One item, one commit.
- When every item is ticked and checks pass, create `.ralph/DONE` containing one line of evidence (the check output summary).

## Never
- Never edit `.ralph/prompt.md`, the check command, CI config or tests you were not asked to change, to make a pass look green.
- Never delete or skip a failing test. Fix it, or write the blocker into `.ralph/progress.md` and stop.
- Never push, deploy, merge or touch the default branch. The loop runs on its own branch; a human lands it.
- Never install new dependencies unless the plan item says so.
- If the same item fails twice in a row, write `BLOCKED: <reason>` in `.ralph/progress.md` and stop without creating `.ralph/DONE`.

## Starting a loop
Use the `ralph-loop` skill. It sets up `.ralph/`, a branch and the guarded runner with limits.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `ralph-loop`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Guarded Ralph loop" v1.0.0 — https://loadout.jnw-it.com/loadouts/ralph-loop-guarded/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `ralph-loop`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Guarded Ralph loop" v1.0.0 — https://loadout.jnw-it.com/loadouts/ralph-loop-guarded/ -->

---
name: ralph-loop
description: Set up and run a guarded Ralph-style loop (fresh agent process per pass, state in files, iteration and no-progress limits, independent check). Use when a task is a long list of similar, checkable steps.
---

# Guarded Ralph loop

A Ralph loop re-runs one prompt in a fresh agent process until the work is done. Fresh context each pass is the point:
state lives in files, not in the conversation. The guard rails stop the classic failures: endless loops, a pass that
"fixes" the tests, and quiet drift.

## When to use it
- Good fit: migrations, porting, test backfill, lint clean-up, one checklist item per pass, each provable by a command.
- Bad fit: design work, anything without a check command, anything touching production.

## Set up
1. Create a branch: `git switch -c ralph/<task>`. The runner refuses to start on main, master or a detached HEAD.
2. `mkdir -p .ralph` and copy `references/PROMPT.md` to `.ralph/prompt.md`. Fill in the goal, constraints and check command.
3. Write `.ralph/plan.md` as a checklist, one small item per line (`- [ ] ...`). Ask the human to approve it.
4. Copy `scripts/ralph.sh` into the repository (for example `scripts/ralph.sh`) and make it executable.
5. Add `.ralph/log/` to `.gitignore`. Keep `prompt.md`, `plan.md` and `progress.md` committed.

## Run
Set the agent command and the check, then start. The prompt file path is in `$RALPH_PROMPT`.

    AGENT_CMD='claude -p --permission-mode acceptEdits --max-budget-usd 3 < "$RALPH_PROMPT"' \
    CHECK_CMD='npm test' MAX_ITER=15 scripts/ralph.sh

Other agents (one process per pass in each case):
- Codex: `AGENT_CMD='codex exec --sandbox workspace-write - < "$RALPH_PROMPT"'`
- Antigravity CLI: `AGENT_CMD='agy -p "$(cat "$RALPH_PROMPT")" --cwd .'`

Limits (environment variables): `MAX_ITER` (default 10), `MAX_NO_PROGRESS` passes without a new commit or diff
(default 2), `PASS_TIMEOUT` seconds per pass (default 1800). Create `.ralph/STOP` to stop after the current pass.

Exit codes: 0 done and checks green, 2 iteration limit, 3 no progress, 4 stopped by `.ralph/STOP`, 5 refused to start.

## Guard rails the runner enforces
- `.ralph/DONE` only counts if `CHECK_CMD` passes after the pass. A false DONE is removed and logged.
- The check runs outside the agent, every pass. The agent cannot mark its own homework.
- `.ralph/prompt.md` is hashed at start; a pass that edits it ends the loop (exit 5).
- Each pass's output goes to `.ralph/log/pass-N.txt` for review.

## In-session alternatives
Claude Code `/goal` and Codex `/goal` keep one session working towards a condition, judged by a separate evaluator
(Claude) or the goal tracker (Codex). They are convenient, but the context is not cleared between turns. Use this runner
when you want a clean context per pass and limits enforced outside the agent; use `/goal` for shorter jobs.

## After the loop
Review `git log --oneline` and `.ralph/progress.md`, run the full test suite yourself, and open a pull request. Never let
the loop merge its own work.

Self-test: `bash scripts/selftest.sh` runs the runner against fake agents and checks every exit path.

# Loop prompt (copy to .ralph/prompt.md)

Goal: <one sentence: the end state>

Read first: AGENTS.md, .ralph/plan.md, the last 20 lines of .ralph/progress.md.

Each pass:
1. Pick the first unchecked item in .ralph/plan.md. Do only that item.
2. Run the check: <command, for example npm test>. It must pass before you tick the item.
3. Tick the item, append one line to .ralph/progress.md (date, item, result, next step) and commit.
4. If every item is ticked and the check passes, write the check summary to .ralph/DONE.

Constraints:
- Do not edit .ralph/prompt.md, tests you were not asked to change, CI config or lockfiles.
- No new dependencies unless the item says so. No pushes, deploys or merges.
- If the item fails twice, append "BLOCKED: <reason>" to .ralph/progress.md and stop.

#!/usr/bin/env bash
# Guarded Ralph loop: one fresh agent process per pass, state in .ralph/, hard limits, check run outside the agent.
# Exit codes: 0 done, 2 iteration limit, 3 no progress, 4 stopped by .ralph/STOP, 5 refused to start or prompt edited.
set -uo pipefail

: "${AGENT_CMD:?set AGENT_CMD, for example: claude -p --permission-mode acceptEdits < \"\$RALPH_PROMPT\"}"
: "${CHECK_CMD:?set CHECK_CMD, for example: npm test}"
MAX_ITER="${MAX_ITER:-10}"
MAX_NO_PROGRESS="${MAX_NO_PROGRESS:-2}"
PASS_TIMEOUT="${PASS_TIMEOUT:-1800}"
DIR=".ralph"
export RALPH_PROMPT="$DIR/prompt.md"

say() { printf 'ralph: %s\n' "$*"; }
log() { printf '%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$*" >> "$DIR/progress.md"; }
state() { printf '%s %s' "$(git rev-parse HEAD 2>/dev/null)" "$(git status --porcelain=v1 -- . ":(exclude)$DIR/log" | sha256sum | cut -c1-16)"; }

git rev-parse --is-inside-work-tree >/dev/null 2>&1 || { say "not a git repository"; exit 5; }
branch="$(git symbolic-ref --quiet --short HEAD || true)"
case "$branch" in
  ""|main|master) say "refusing to run on '${branch:-detached HEAD}'; create a ralph/<task> branch first"; exit 5 ;;
esac
[ -f "$RALPH_PROMPT" ] || { say "missing $RALPH_PROMPT"; exit 5; }
mkdir -p "$DIR/log"
prompt_hash="$(sha256sum "$RALPH_PROMPT" | cut -c1-64)"
no_progress=0

for ((i = 1; i <= MAX_ITER; i++)); do
  if [ -f "$DIR/STOP" ]; then say "stop file found before pass $i"; log "stopped by .ralph/STOP"; exit 4; fi
  before="$(state)"
  say "pass $i/$MAX_ITER"
  timeout "$PASS_TIMEOUT" bash -c "$AGENT_CMD" > "$DIR/log/pass-$i.txt" 2>&1
  rc=$?
  [ "$rc" -eq 124 ] && log "pass $i timed out after ${PASS_TIMEOUT}s"

  if [ "$(sha256sum "$RALPH_PROMPT" | cut -c1-64)" != "$prompt_hash" ]; then
    say "pass $i edited $RALPH_PROMPT; stopping"; log "pass $i edited the prompt; loop stopped"; exit 5
  fi

  if [ -f "$DIR/DONE" ]; then
    if bash -c "$CHECK_CMD" > "$DIR/log/check-$i.txt" 2>&1; then
      say "done after $i pass(es); check passed"; log "done after $i passes; check passed"; exit 0
    fi
    say "pass $i wrote DONE but the check fails; removing DONE"; rm -f "$DIR/DONE"; log "pass $i: false DONE removed (check failed)"
  fi

  if [ "$(state)" = "$before" ]; then
    no_progress=$((no_progress + 1))
    say "no change in pass $i ($no_progress/$MAX_NO_PROGRESS)"
    if [ "$no_progress" -ge "$MAX_NO_PROGRESS" ]; then log "no progress for $no_progress passes; loop stopped"; exit 3; fi
  else
    no_progress=0
  fi
done
say "iteration limit ($MAX_ITER) reached"; log "iteration limit $MAX_ITER reached"; exit 2

#!/usr/bin/env bash
# Runs ralph.sh against fake agents in throwaway repositories and checks every exit path.
set -u
here="$(cd "$(dirname "$0")" && pwd)"
runner="$here/ralph.sh"
pass=0; failed=0

repo() {
  local d; d="$(mktemp -d)"
  ( cd "$d" && git init -q -b main && git config user.email t@example.com && git config user.name t \
    && mkdir .ralph && echo "goal" > .ralph/prompt.md && echo "- [ ] a" > .ralph/plan.md && : > .ralph/progress.md \
    && git add -A && git commit -qm init && git switch -qc ralph/test )
  echo "$d"
}
expect() { # name, want-exit, dir, env...
  local name="$1" want="$2" d="$3"; shift 3
  ( cd "$d" && env MAX_ITER=4 PASS_TIMEOUT=20 "$@" bash "$runner" > out.txt 2>&1 ); local got=$?
  if [ "$got" -eq "$want" ]; then pass=$((pass + 1)); else failed=$((failed + 1)); echo "FAIL: $name (exit $got, wanted $want)"; cat "$d/out.txt"; fi
}

d="$(repo)"; ( cd "$d" && git switch -q main )
expect "refuses main" 5 "$d" AGENT_CMD=true CHECK_CMD=true

d="$(repo)"
expect "idle agent stops on no progress" 3 "$d" AGENT_CMD=true CHECK_CMD=true

d="$(repo)"
expect "busy agent hits the iteration limit" 2 "$d" 'AGENT_CMD=date +%s%N >> work.txt && git add work.txt && git commit -qm pass' CHECK_CMD=true

d="$(repo)"
expect "DONE with a green check exits 0" 0 "$d" 'AGENT_CMD=echo ok > .ralph/DONE' CHECK_CMD=true

d="$(repo)"
expect "false DONE is removed and the loop goes on" 3 "$d" 'AGENT_CMD=echo ok > .ralph/DONE' CHECK_CMD=false
grep -q "false DONE removed" "$d/.ralph/progress.md" && pass=$((pass + 1)) || { failed=$((failed + 1)); echo "FAIL: false DONE not logged"; }

d="$(repo)"
expect "editing the prompt stops the loop" 5 "$d" 'AGENT_CMD=echo cheat >> .ralph/prompt.md' CHECK_CMD=true

d="$(repo)"; touch "$d/.ralph/STOP"
expect "STOP file stops the loop" 4 "$d" AGENT_CMD=true CHECK_CMD=true

d="$(repo)"
expect "a pass that hangs is timed out" 3 "$d" 'AGENT_CMD=sleep 30' CHECK_CMD=true PASS_TIMEOUT=1
grep -q "timed out" "$d/.ralph/progress.md" && pass=$((pass + 1)) || { failed=$((failed + 1)); echo "FAIL: timeout not logged"; }

if [ "$failed" -eq 0 ]; then echo "ok: $pass cases"; else echo "failed: $failed of $((pass + failed))"; exit 1; fi