>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588782. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The Ralph Loop runs with <code>max_iterations: 0</code> (unlimited) by default, fires on every agent stop, has no built-in completion criteria, cannot be stopped by setting <code>active: false</code> in the state file, and has a ZSH glob quoting bug that breaks URL arguments containing <code>?</code>, <code>=</code>, or <code>&amp;amp;</code>. Collectively this makes the loop impossible to start reliably (with URL args) or stop automatically.</p> <p>In a recorded session, the user had to manually cancel the loop three times via <code>/ralph-loop:cancel-ralph</code>, each cancellation discarding accumulated context. The "WARNING: This loop cannot be stopped manually! It will run infinitely" message is alarming and reflects a real architectural gap.</p> <p>An unlimited, unstopping loop amplifies every other problem in this sprint: it drives context window growth (4-03), allows regression cycles to continue indefinitely, and keeps the dual browser systems (4-01) in conflict until manual intervention.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Start a Ralph Loop with a URL containing <code>?param=1</code> in ZSH: <code>./setup-ralph-loop.sh https://site.acquia.site/page?param=1</code> &mdash; observe "no matches found" error from glob expansion.</li> <li>Start a Ralph Loop with the URL properly quoted; observe state file contains <code>active: true, iteration: 1, max_iterations: 0, completion_promise: null</code>.</li> <li>Edit the state file mid-run to set <code>active: false</code>; observe loop continues firing on next agent stop (the hook script only checks for file existence, not the <code>active</code> field).</li> <li>Observe loop runs indefinitely until user cancels via <code>/ralph-loop:cancel-ralph</code>. Each cancellation discards accumulated context.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Three independent fixes:</p> <p><strong>1. Fix ZSH glob quoting in <code>setup-ralph-loop.sh</code></strong>:</p> <pre># In the script: use "$@" (quoted) for all arg references, not $@ # OR: prefix invocations with `noglob` in user-facing docs: noglob ./setup-ralph-loop.sh "https://site.acquia.site/page?param=1"</pre><p><strong>2. Add <code>active: false</code> stop support to the hook script</strong>:</p> <pre>STATE_FILE=".claude/ralph-loop.local.md" # or wherever state lives if [[ $(grep 'active: false' "$STATE_FILE") ]]; then echo "Ralph Loop: active=false detected, stopping loop." exit 0 fi</pre><p><strong>3. Add <code>max_iterations: 3</code> as the documented default</strong> in Ralph Loop configuration. Users can override to 0 for truly unlimited runs, but default must be safe:</p> <pre>active: true iteration: 1 max_iterations: 3 # default safety cap; set to 0 for unlimited completion_promise: null completion_criteria: - type: "all_pages_pass" check: "visual-verifier returns PASS for all pages" - type: "no_open_issues" check: "docs/migration/issues/ contains no unresolved issue files"</pre><p>The hook checks <code>completion_criteria</code> after each iteration. If all criteria pass, the loop stops automatically and logs "LOOP_COMPLETE: all criteria met."</p> <p><strong>Document cancellation procedure</strong> prominently in the skill: the only reliable external stop is <code>/ralph-loop:cancel-ralph</code>. Until fix #2 lands, do not try to stop by writing <code>active: false</code> &mdash; the hook does not check this field.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Locate the ralph-loop hook script (may be in <code>.claude/settings.json</code> as a stop hook, or a separate shell script): <code>find .claude -name "*.sh" -o -name "*.json" | xargs grep -l "ralph"</code>.</li> <li>Fix ZSH quoting in <code>setup-ralph-loop.sh</code> (or equivalent): wrap URL arguments in quotes; use <code>noglob</code> or <code>setopt noglob</code> before argument parsing.</li> <li>Add <code>active</code> field check to the hook script.</li> <li>Update <code>.claude/ralph-loop.local.md</code> (or loop configuration template): add <code>max_iterations: 3</code> default; add <code>completion_criteria</code> parameter.</li> <li>Update <code>.claude/skills/ralph-loop/SKILL.md</code> (or help docs): document the correct cancellation procedure; document the ZSH quoting workaround.</li> <li>Verify: a loop with <code>?param=1</code> URL does not error; setting <code>active: false</code> stops the loop on the next iteration; <code>max_iterations: 3</code> stops cleanly after 3 iterations.</li> <li>Confirm <code>/ralph-loop:help</code> output explains <code>max_iterations</code> and the ZSH quoting requirement.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>New optional fields in the Ralph Loop state file: <code>max_iterations</code> (was implicit-0; now explicit-3 default), <code>completion_criteria</code> (new). Hook reads <code>active</code> field where it previously checked file existence only &mdash; backwards-compatible (existing state files without <code>active: false</code> behave identically).</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>Ralph Loop state file gains <code>completion_criteria</code> as a list of <code>{type, check}</code> records. <code>max_iterations</code> default changes from 0 (implicit unlimited) to 3.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-4-Cost-and-Context/02-ralph-loop-no-completion-condition.md</code> (id: P2-4)</li> <li>State-file evidence: <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half1/issues-found.md</code> (A8 &mdash; three cancellations, infinite-loop warning)</li> <li><code>active: false</code> dead-end: <code>RESEARCH-2026-04-28/03-efi-ed-source/Q1-records-1-to-2884/issues-found.md</code> (Anti-Pattern 17)</li> <li>ZSH glob quoting: <code>RESEARCH-2026-04-28/02-edu-site-mockup-ai/fc6fc3db/issues-found.md</code> (ISSUE-5)</li> <li>Consolidated root cause: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> (P2-4)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Where exactly is the ralph-loop hook script? May be in <code>.claude/settings.json</code> as a <code>stop</code> hook, or a separate shell script. Locate before editing.</li> <li>The <code>active: false</code> fix requires the hook to read the state file on every agent stop. Confirm the state file is small enough (&lt; 1KB) that this overhead is negligible.</li> <li>Should <code>max_iterations: 3</code> be the default for all Ralph Loop uses, or only for the visual-fidelity phase? May warrant a per-purpose default with a parameter override.</li> </ul>