| name | bounded-iteration |
| description | Bounded iterative execution for well-defined tasks with machine-verifiable completion criteria. Runs implementation → verify → retry cycles until success or a stop condition. Use for "run until done", "keep trying until tests pass", "iterate until it works", automated fix-verify loops, or any repetitive task with a clear pass/fail gate. Prefers human-in-the-loop by default; AFK mode requires isolation and explicit guardrails. |
Bounded Iteration
Outer control loop around an AI CLI: locked brief → limited actions → state → positive proof verify → stop. Persistence only counts when bounded by proof.
Not: design method, unsupervised shared-workspace edits, or a substitute for human judgment.
Elevated autonomy still obeys rules/autonomy-safety.md: reversible work inside locked scope may proceed; irreversible / high-blast-radius → stop and escalate.
When to use
| Scenario | Use? |
|---|
| Coverage / migrate tests / verifiable bulk edits | Yes |
| Risky refactor / auth / security | HITL only |
| Diagnosis / architecture design | No — design or investigate first |
Design-first handoff: references/swarm-integration.md.
Contract (required files)
| File | Purpose |
|---|
TASK.md | Scope, allow/forbid, acceptance, stop triggers |
PROMPT.md | Stable per-iteration instructions |
verify.sh | Machine gate (exit 0 pass / 2 retry / 3 verifier broken / 4 not verifiable) |
progress.txt | Human iteration log |
.ralph-state.json | Resume / oscillation (required AFK) |
.ralph-verify.json | Latest proof summary |
Templates: references/templates/. Deep procedure: references/procedure.md. Shell loops: references/loop-patterns.md.
Modes
- HITL (default): one iteration → human inspect → continue.
- AFK: only if task locked,
verify.sh trustworthy, workspace isolated/disposable, stop/cleanup configured. Not open-ended autonomy.
Defaults: MAX_ITER=10, ITERATION_TIMEOUT_SEC=900, REQUIRED_SUCCESS_STREAK=1 (use 2 if flaky).
Session flow (summary)
- Reject ambiguous tasks (AFK →
STOP_INPUT_AMBIGUOUS).
- Build handoff package from templates.
- One bounded AI iteration (narrow scope).
- Run
verify.sh; classify; feed failures back.
- Detect oscillation (same fingerprint ×3 or alternating) → stop.
- Cleanup/handoff; no destructive restore in shared workspaces.
Stop codes: STOP_SUCCESS, STOP_INPUT_AMBIGUOUS, STOP_UNSAFE_ACTION, STOP_VERIFY_BROKEN, STOP_MAX_ITER, STOP_MAX_COST, STOP_TIMEOUT, STOP_OSCILLATION, STOP_CONTEXT_LIMIT, STOP_MANUAL_INTERVENTION.
Positive proof: success needs signals like 18 tests passed, not empty output or "no errors seen."
Load references/procedure.md before first AFK run or when implementing verify.sh / state files.
Deliverable
