fix(ralph-loop): finalize continue/reset loop strategies and docs

[edxeth]

Summary

• Finalized Ralph loop strategy behavior so omitted --strategy follows ralph_loop.default_strategy (with config fallback to continue).
• Stabilized reset-iteration flow (fresh top-level session per iteration with deterministic iteration titles) and preserved continue-mode session continuity.
• Documented the missing strategy surface in docs/*: --strategy=continue|reset, default_strategy, precedence rules, and practical guidance for when to use each loop style.

Why this change

The Ralph loop strategy switch is not cosmetic: continue and reset represent opposing operating philosophies.

• continue = hot-context continuity in one thread (great for HITL and debugging continuity).
• reset = fresh-context iteration isolation (great for longer AFK runs and reducing context-rot pressure).

Given that these modes are meaningfully different, docs now explicitly call out behavioral and philosophical differences so users can intentionally choose the right loop style.

What changed

Runtime / hook behavior

• Follow-up fixes in this branch ensure strategy semantics stay coherent across reset/continue loop execution.
• Omitted --strategy now resolves via config (ralph_loop.default_strategy) rather than hardcoded behavior.
• Reset iterations keep deterministic iteration session titles and are handled as fresh top-level sessions.

Documentation

Updated:

• docs/reference/features.md
  • Added full /ralph-loop flag docs including --strategy.
  • Added explicit continue vs reset comparison table and usage guidance.
  • Added config snippet including default_strategy.
• docs/reference/configuration.md
  • Added dedicated ralph_loop subsection including default_strategy.
  • Added precedence rules (--strategy flag > config > fallback).

Validation and real-world testing

I validated this branch against real loop usage patterns and edge paths, including both strategies:

• Continue strategy behavior (same-session continuation and prompt injection flow)
• Reset strategy behavior (fresh-session iteration flow, title updates, TUI session switching)
• Loop-state handling and completion/continuation boundaries
• Hook interactions around continuation and reset timing/race conditions

Executed:

• bun test src/hooks/ralph-loop/index.test.ts src/hooks/ralph-loop/session-reset-strategy.test.ts src/hooks/ralph-loop/reset-strategy-race-condition.test.ts src/plugin/chat-message.test.ts
• bun run typecheck
• bun run build

References

• Geoffrey Huntley — everything is a ralph loop: https://ghuntley.com/loop/
• Geoffrey Huntley — Ralph Wiggum as a software engineer: https://ghuntley.com/ralph/
• AI Hero — 11 Tips For AI Coding With Ralph Wiggum: https://www.aihero.dev/tips-for-ai-coding-with-ralph-wiggum
• AI Hero — Why the Anthropic Ralph plugin sucks (use a bash loop instead): https://www.aihero.dev/why-the-anthropic-ralph-plugin-sucks

[cubic-dev-ai]

2 issues found across 16 files

Confidence score: 3/5

• There is a concrete user-facing risk in src/hooks/ralph-loop/command-arguments.ts: slicing rawArguments by a trimmed promptCandidate can misalign flags parsing when leading/trailing spaces exist.
• Dead code in src/hooks/ralph-loop/ralph-loop-event-handler.ts for session.stop suggests some behavior is unreachable; likely low functional impact but indicates mismatch with Opencode SDK events.
• Pay close attention to src/hooks/ralph-loop/command-arguments.ts and src/hooks/ralph-loop/ralph-loop-event-handler.ts - correct the slice alignment and remove the unused session.stop handler.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/hooks/ralph-loop/command-arguments.ts">

<violation number="1" location="src/hooks/ralph-loop/command-arguments.ts:21">
P1: Incorrect string slicing logic for `flagsSource` when `promptCandidate` has leading/trailing spaces. The code uses `rawArguments.slice(promptCandidate.length)` but `promptCandidate` is trimmed, causing the slice to start inside the original string rather than after the prompt. This leaks prompt content into flag parsing and can incorrectly parse flags that appear inside the prompt text.</violation>
</file>

<file name="src/hooks/ralph-loop/ralph-loop-event-handler.ts">

<violation number="1" location="src/hooks/ralph-loop/ralph-loop-event-handler.ts:189">
P2: Custom agent: **Opencode Compatibility**

The Opencode SDK does not emit a `session.stop` event. This block is dead code and should be removed. Session aborts are correctly handled through your existing `session.error` and `message.updated` event handlers.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

2 issues found across 16 files

Confidence score: 3/5

• There’s some regression risk: src/hooks/ralph-loop/ralph-loop-event-handler.ts assumes error messages are on the error object, but the Opencode SDK nests them under .data.message, which could break error handling.
• Test reliability risk in src/hooks/ralph-loop/session-reset-strategy.test.ts: assigning undefined to process.env becomes the string "undefined", potentially polluting subsequent tests.
• Pay close attention to src/hooks/ralph-loop/ralph-loop-event-handler.ts and src/hooks/ralph-loop/session-reset-strategy.test.ts - error handling compatibility and environment variable cleanup.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/hooks/ralph-loop/ralph-loop-event-handler.ts">

<violation number="1" location="src/hooks/ralph-loop/ralph-loop-event-handler.ts:216">
P1: Custom agent: **Opencode Compatibility**

Error messages in Opencode SDK are nested inside `.data.message`, not directly on the error object.</violation>
</file>

<file name="src/hooks/ralph-loop/session-reset-strategy.test.ts">

<violation number="1" location="src/hooks/ralph-loop/session-reset-strategy.test.ts:11">
P1: Assigning potentially undefined values to process.env causes test pollution - Node.js converts undefined to string "undefined". Use conditional assignment: if undefined, use `delete process.env[key]` instead.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/hooks/ralph-loop/reset-iteration-prompt-builder.ts">

<violation number="1" location="src/hooks/ralph-loop/reset-iteration-prompt-builder.ts:23">
P1: Prompt injection vulnerability: Unescaped closing tag in XML-style prompt block</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 10 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/hooks/ralph-loop/continuation-prompt-builder.ts">

<violation number="1" location="src/hooks/ralph-loop/continuation-prompt-builder.ts:24">
P1: Unsafe string replacement with user input containing $ characters can corrupt prompts. Use a replacement function: `.replace("{{PROMPT}}", () => state.raw_task_arguments ?? state.prompt)` to prevent JavaScript from interpreting $$, $&, and $` as special substitution patterns.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}