bmalph 2.9.0 → 2.10.0

package/README.md

@@ -279,12 +279,12 @@ BMAD (add Epic 2) → bmalph implement → Ralph sees changes + picks up Epic 2
 
 ### run options
 
-| Flag                   | Description                                                                 |
-| ---------------------- | --------------------------------------------------------------------------- |
-| `--driver <platform>`  | Override platform driver (claude-code, codex, opencode, copilot, cursor)    |
-| `--review/--no-review` | Enable/disable periodic code review (Claude Code only, prompted by default) |
-| `--interval <ms>`      | Dashboard refresh interval in milliseconds (default: 2000)                  |
-| `--no-dashboard`       | Run Ralph without the dashboard overlay                                     |
+| Flag                  | Description                                                                              |
+| --------------------- | ---------------------------------------------------------------------------------------- |
+| `--driver <platform>` | Override platform driver (claude-code, codex, opencode, copilot, cursor)                 |
+| `--review [mode]`     | Quality review: `enhanced` (every 5 loops) or `ultimate` (every story). Claude Code only |
+| `--interval <ms>`     | Dashboard refresh interval in milliseconds (default: 2000)                               |
+| `--no-dashboard`      | Run Ralph without the dashboard overlay                                                  |
 
 ### watch options
 
@@ -416,7 +416,7 @@ Safety mechanisms:
 
 - **Circuit breaker** — prevents infinite loops on failing stories
 - **Response analyzer** — detects stuck or repeating outputs
-- **Code review** — optional periodic review every 5 loops (`--review`, Claude Code only). A read-only session analyzes git diffs and feeds structured findings into the next implementation loop
+- **Code review** — optional quality review (`--review [mode]`, Claude Code only). Enhanced: periodic review every 5 loops. Ultimate: review after every completed story. A read-only session analyzes git diffs and feeds structured findings into the next implementation loop
 - **Completion** — loop exits when all `@fix_plan.md` items are checked off
 
 Cursor-specific runtime checks:

package/dist/cli.js

@@ -105,7 +105,8 @@ program
     .option("--driver <platform>", "Override platform driver (claude-code, codex, opencode, copilot, cursor)")
     .option("--interval <ms>", "Dashboard refresh interval in milliseconds (default: 2000)")
     .option("--no-dashboard", "Run Ralph without the dashboard overlay")
-    .option("--review", "Enable periodic code review loop (~10-14% more tokens)")
+    .option("--review [mode]", "Quality review: enhanced (~10-14% tokens) or ultimate (~20-30%)")
+    .option("--no-review", "Disable code review")
     .action(async (opts) => runCommand({ ...opts, projectDir: await resolveAndValidateProjectDir() }));
 void program.parseAsync();
 //# sourceMappingURL=cli.js.map

package/dist/commands/run.js

@@ -24,10 +24,13 @@ async function executeRun(options) {
     if (platform.experimental) {
         console.log(chalk.yellow(`Warning: ${platform.displayName} support is experimental`));
     }
-    const reviewEnabled = await resolveReviewMode(options.review, platform);
-    if (reviewEnabled) {
+    const reviewMode = await resolveReviewMode(options.review, platform);
+    if (reviewMode === "enhanced") {
         console.log(chalk.cyan("Enhanced mode: code review every 5 implementation loops"));
     }
+    else if (reviewMode === "ultimate") {
+        console.log(chalk.cyan("Ultimate mode: code review after every completed story"));
+    }
     const interval = parseInterval(options.interval);
     let useDashboard = dashboard;
     if (useDashboard) {
@@ -43,10 +46,10 @@ async function executeRun(options) {
     }
     const ralph = spawnRalphLoop(projectDir, platform.id, {
         inheritStdio: !useDashboard,
-        ...(reviewEnabled && { reviewEnabled }),
+        reviewMode,
     });
     if (useDashboard) {
-        await startRunDashboard({ projectDir, interval, ralph, reviewEnabled });
+        await startRunDashboard({ projectDir, interval, ralph, reviewMode });
         if (ralph.state === "stopped") {
             applyRalphExitCode(ralph.exitCode);
         }
@@ -70,34 +73,44 @@ function resolvePlatform(driverOverride, configPlatform) {
     }
     return getPlatform(id);
 }
+const VALID_REVIEW_MODES = new Set(["enhanced", "ultimate"]);
 async function resolveReviewMode(reviewFlag, platform) {
-    if (reviewFlag === true) {
+    if (reviewFlag === false) {
+        return "off";
+    }
+    if (reviewFlag === true || typeof reviewFlag === "string") {
         if (platform.id !== "claude-code") {
             throw new Error("--review requires Claude Code (other drivers lack read-only enforcement)");
         }
-        return true;
-    }
-    if (reviewFlag === false) {
-        return false;
+        if (reviewFlag === true) {
+            return "enhanced";
+        }
+        if (!VALID_REVIEW_MODES.has(reviewFlag)) {
+            throw new Error(`Unknown review mode: ${reviewFlag}. Valid modes: enhanced, ultimate`);
+        }
+        return reviewFlag;
     }
     if (platform.id !== "claude-code") {
-        return false;
+        return "off";
     }
     if (!process.stdin.isTTY) {
-        return false;
+        return "off";
     }
     const { default: select } = await import("@inquirer/select");
-    const mode = await select({
+    return select({
         message: "Quality mode:",
         choices: [
-            { name: "Standard — current behavior (no extra cost)", value: "standard" },
+            { name: "Standard — no code review (no extra cost)", value: "off" },
             {
                 name: "Enhanced — periodic code review every 5 loops (~10-14% more tokens)",
                 value: "enhanced",
             },
+            {
+                name: "Ultimate — review after every completed story (~20-30% more tokens)",
+                value: "ultimate",
+            },
         ],
-        default: "standard",
+        default: "off",
     });
-    return mode === "enhanced";
 }
 //# sourceMappingURL=run.js.map

package/dist/installer/template-files.js

@@ -55,6 +55,25 @@ const REVIEW_TEMPLATE_BLOCK = `# ===============================================
 # PERIODIC CODE REVIEW
 # =============================================================================
 
+# Review mode: off, enhanced, or ultimate (set via 'bmalph run --review [mode]')
+# - off:      no code review (default)
+# - enhanced: periodic review every REVIEW_INTERVAL loops (~10-14% more tokens)
+# - ultimate: review after every completed story (~20-30% more tokens)
+# The review agent analyzes git diffs and outputs findings for the next implementation loop.
+# Currently supported on Claude Code only.
+REVIEW_MODE="\${REVIEW_MODE:-off}"
+
+# (Legacy) Enables review — prefer REVIEW_MODE instead
+REVIEW_ENABLED="\${REVIEW_ENABLED:-false}"
+
+# Number of implementation loops between review sessions (enhanced mode only)
+REVIEW_INTERVAL="\${REVIEW_INTERVAL:-5}"
+
+`;
+const PREVIOUS_REVIEW_TEMPLATE_BLOCK = `# =============================================================================
+# PERIODIC CODE REVIEW
+# =============================================================================
+
 # Enable periodic code review loops (set via 'bmalph run --review' or manually)
 # When enabled, Ralph runs a read-only review session every REVIEW_INTERVAL loops.
 # The review agent analyzes git diffs and outputs findings for the next implementation loop.
@@ -229,11 +248,21 @@ async function isRalphrcCustomized(filePath, platformId) {
     if (matchesManagedPermissionVariants(content, templateWithoutReview)) {
         return false;
     }
+    // Check variants with previous review block (pre-ultimate installs)
+    const templateWithPreviousReview = currentTemplate.replace(REVIEW_TEMPLATE_BLOCK, PREVIOUS_REVIEW_TEMPLATE_BLOCK);
+    if (matchesManagedPermissionVariants(content, templateWithPreviousReview)) {
+        return false;
+    }
     // Check variants without both quality gates and review blocks
     const templateWithoutQGAndReview = templateWithoutQG.replace(REVIEW_TEMPLATE_BLOCK, "");
     if (matchesManagedPermissionVariants(content, templateWithoutQGAndReview)) {
         return false;
     }
+    // Check variants without quality gates but with previous review block
+    const templateWithoutQGButPreviousReview = templateWithoutQG.replace(REVIEW_TEMPLATE_BLOCK, PREVIOUS_REVIEW_TEMPLATE_BLOCK);
+    if (matchesManagedPermissionVariants(content, templateWithoutQGButPreviousReview)) {
+        return false;
+    }
     const legacyTemplate = normalizeManagedRalphrcContent(renderLegacyRalphrcTemplate(platformId));
     return content !== legacyTemplate;
 }

package/dist/run/ralph-process.js

@@ -125,9 +125,14 @@ export async function validateRalphLoop(projectDir) {
 }
 export function spawnRalphLoop(projectDir, platformId, options) {
     const env = { ...process.env, PLATFORM_DRIVER: platformId };
-    if (options.reviewEnabled) {
-        env.REVIEW_ENABLED = "true";
-        env.REVIEW_INTERVAL = "5";
+    if (options.reviewMode) {
+        env.REVIEW_MODE = options.reviewMode;
+        if (options.reviewMode !== "off") {
+            env.REVIEW_ENABLED = "true";
+            if (options.reviewMode === "enhanced") {
+                env.REVIEW_INTERVAL = "5";
+            }
+        }
     }
     const child = spawn(cachedBashCommand ?? "bash", [BASH_RALPH_LOOP_PATH], {
         cwd: projectDir,

package/dist/run/run-dashboard.js

@@ -2,9 +2,9 @@ import { createRefreshCallback } from "../watch/dashboard.js";
 import { createTerminalFrameWriter } from "../watch/frame-writer.js";
 import { FileWatcher } from "../watch/file-watcher.js";
 import { renderFooterLine } from "../watch/renderer.js";
-export function renderStatusBar(ralph, reviewEnabled) {
+export function renderStatusBar(ralph, reviewMode) {
     const pid = ralph.child.pid ?? "?";
-    const badge = reviewEnabled ? " [review]" : "";
+    const badge = reviewMode === "ultimate" ? " [ultimate]" : reviewMode === "enhanced" ? " [review]" : "";
     switch (ralph.state) {
         case "running":
             return `Ralph: running (PID ${pid})${badge} | q: stop/detach`;
@@ -18,12 +18,12 @@ export function renderQuitPrompt() {
     return "Stop (s) | Detach (d) | Cancel (c)";
 }
 export async function startRunDashboard(options) {
-    const { projectDir, interval, ralph, reviewEnabled } = options;
+    const { projectDir, interval, ralph, reviewMode } = options;
     const frameWriter = createTerminalFrameWriter();
     let showingPrompt = false;
     let stopped = false;
     const footerRenderer = (lastUpdated, cols) => {
-        const leftText = showingPrompt ? renderQuitPrompt() : renderStatusBar(ralph, reviewEnabled);
+        const leftText = showingPrompt ? renderQuitPrompt() : renderStatusBar(ralph, reviewMode);
         return renderFooterLine(leftText, `Updated: ${lastUpdated.toISOString().slice(11, 19)}`, cols);
     };
     const refresh = createRefreshCallback(projectDir, (frame) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmalph",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "Unified AI Development Framework - BMAD phases with Ralph execution loop",
   "type": "module",
   "bin": {

package/ralph/drivers/DRIVER_INTERFACE.md

@@ -0,0 +1,422 @@
+# Ralph Driver Interface Contract
+
+## Overview
+
+The Ralph loop loads a platform driver by sourcing `ralph/drivers/${PLATFORM_DRIVER}.sh`
+inside `load_platform_driver()` (`ralph_loop.sh` line 296). The `PLATFORM_DRIVER` variable
+defaults to `"claude-code"` and can be overridden via `.ralphrc`.
+
+After sourcing, `ralph_loop.sh` immediately calls three functions to populate core globals:
+
+1. `driver_valid_tools` -- populates `VALID_TOOL_PATTERNS`
+2. `driver_cli_binary` -- stored in `CLAUDE_CODE_CMD`
+3. `driver_display_name` -- stored in `DRIVER_DISPLAY_NAME`
+
+**File naming convention:** `${PLATFORM_DRIVER}.sh` (e.g., `claude-code.sh`, `codex.sh`).
+
+**Scope:** This documents the sourceable driver contract used by `ralph_loop.sh`. Helper
+scripts like `cursor-agent-wrapper.sh` are out of scope.
+
+**Calling conventions:**
+
+- Data is returned via stdout (`echo`).
+- Booleans are returned via exit status (`0` = true, `1` = false).
+- Some functions mutate global arrays as side effects.
+
+---
+
+## Required Hooks
+
+Called unconditionally by `ralph_loop.sh` with no `declare -F` guard or default stub.
+Omitting any of these will break the loop at runtime.
+
+### `driver_name()`
+
+```bash
+driver_name()
+```
+
+No arguments. Echo a short lowercase identifier (e.g., `"claude-code"`, `"codex"`).
+Used at line 2382 to gate platform-specific logic.
+
+### `driver_display_name()`
+
+```bash
+driver_display_name()
+```
+
+No arguments. Echo a human-readable name (e.g., `"Claude Code"`, `"OpenAI Codex"`).
+Stored in `DRIVER_DISPLAY_NAME`, used in log messages and tmux pane titles.
+
+### `driver_cli_binary()`
+
+```bash
+driver_cli_binary()
+```
+
+No arguments. Echo the CLI executable name or resolved path (e.g., `"claude"`, `"codex"`).
+Stored in `CLAUDE_CODE_CMD`. Most drivers return a static string; cursor resolves
+dynamically.
+
+### `driver_valid_tools()`
+
+```bash
+driver_valid_tools()
+```
+
+No arguments. Must populate the global `VALID_TOOL_PATTERNS` array with the platform's
+recognized tool name patterns. Used by `validate_allowed_tools()`.
+
+### `driver_build_command(prompt_file, loop_context, session_id)`
+
+```bash
+driver_build_command "$prompt_file" "$loop_context" "$session_id"
+```
+
+Three string arguments:
+
+| Argument | Description |
+|----------|-------------|
+| `$1` prompt_file | Path to the prompt file (e.g., `.ralph/PROMPT.md`) |
+| `$2` loop_context | Context string for session continuity (may be empty) |
+| `$3` session_id | Session ID for resume (empty string = new session) |
+
+Must populate the global `CLAUDE_CMD_ARGS` array with the complete CLI command and
+arguments. Return `0` on success, `1` on failure (e.g., prompt file not found).
+
+**Reads globals:** `CLAUDE_OUTPUT_FORMAT`, `CLAUDE_PERMISSION_MODE` (claude-code only),
+`CLAUDE_ALLOWED_TOOLS` (claude-code only), `CLAUDE_USE_CONTINUE`.
+
+---
+
+## Optional Overrides with Loop Defaults
+
+`ralph_loop.sh` defines default stubs at lines 284 and 288. All existing drivers override
+them, but a minimal driver can rely on the defaults.
+
+### `driver_supports_tool_allowlist()`
+
+```bash
+driver_supports_tool_allowlist()
+```
+
+No arguments. Return `0` if the driver supports `--allowedTools` filtering, `1` otherwise.
+
+**Default:** returns `1` (false). Currently only `claude-code` returns `0`.
+
+### `driver_permission_denial_help()`
+
+```bash
+driver_permission_denial_help()
+```
+
+No arguments. Print platform-specific troubleshooting guidance when the loop detects a
+permission denial.
+
+**Reads:** `RALPHRC_FILE`, `DRIVER_DISPLAY_NAME`.
+
+**Default:** generic guidance text.
+
+---
+
+## Optional Capability Hooks
+
+Guarded by `declare -F` checks or wrapper functions in `ralph_loop.sh` (lines 1917-1954,
+1576-1583). Safe to omit -- documented fallback behavior applies.
+
+### `driver_supports_sessions()`
+
+```bash
+driver_supports_sessions()
+```
+
+No arguments. Return `0` if the driver supports session resume, `1` otherwise.
+
+**If not defined:** assumed true (`0`).
+
+Implemented by all 5 drivers; `copilot` returns `1`.
+
+### `driver_supports_live_output()`
+
+```bash
+driver_supports_live_output()
+```
+
+No arguments. Return `0` if the driver supports structured streaming output (stream-json
+or JSONL), `1` otherwise.
+
+**If not defined:** assumed true (`0`).
+
+`copilot` returns `1`; all others return `0`.
+
+### `driver_prepare_live_command()`
+
+```bash
+driver_prepare_live_command()
+```
+
+No arguments. Transform `CLAUDE_CMD_ARGS` into `LIVE_CMD_ARGS` for streaming mode.
+
+**If not defined:** `LIVE_CMD_ARGS` is copied from `CLAUDE_CMD_ARGS` unchanged.
+
+| Driver | Behavior |
+|--------|----------|
+| claude-code | Replaces `json` with `stream-json` and adds `--verbose --include-partial-messages` |
+| codex | Copies as-is (output is already suitable) |
+| opencode | Copies as-is (output is already suitable) |
+| cursor | Replaces `json` with `stream-json` |
+
+### `driver_stream_filter()`
+
+```bash
+driver_stream_filter()
+```
+
+No arguments. Echo a `jq` filter expression that transforms raw streaming events into
+displayable text.
+
+**If not defined:** returns `"empty"` (no output).
+
+Each driver has a platform-specific filter; `copilot` returns `'.'` (passthrough).
+
+### `driver_extract_session_id_from_output(output_file)`
+
+```bash
+driver_extract_session_id_from_output "$output_file"
+```
+
+One argument: path to the CLI output log file. Echo the extracted session ID.
+
+Tried first in the session save chain before the generic `jq` extractor. Only `opencode`
+implements this (uses `sed` to extract from a `"session"` JSON object).
+
+### `driver_fallback_session_id(output_file)`
+
+```bash
+driver_fallback_session_id "$output_file"
+```
+
+One argument: path to the output file (caller passes it at line 1583; the only
+implementation in `opencode` ignores it).
+
+Last-resort session ID recovery when both driver-specific and generic extractors fail.
+Only `opencode` implements this (queries `opencode session list --format json`).
+
+---
+
+## Conventional Metadata Hooks
+
+Present in every driver but NOT called by `ralph_loop.sh`. Consumed by bmalph's TypeScript
+doctor/preflight checks in `src/platform/`. A new driver should implement these for
+`bmalph doctor` compatibility.
+
+### `driver_min_version()`
+
+```bash
+driver_min_version()
+```
+
+No arguments. Echo the minimum required CLI version as a semver string.
+
+### `driver_check_available()`
+
+```bash
+driver_check_available()
+```
+
+No arguments. Return `0` if the CLI binary is installed and reachable, `1` otherwise.
+
+---
+
+## Global Variables
+
+### Written by drivers
+
+| Variable             | Written by                       | Type  | Description                                          |
+|----------------------|----------------------------------|-------|------------------------------------------------------|
+| `VALID_TOOL_PATTERNS`| `driver_valid_tools()`           | array | Valid tool name patterns for allowlist validation     |
+| `CLAUDE_CMD_ARGS`    | `driver_build_command()`         | array | Complete CLI command with all arguments               |
+| `LIVE_CMD_ARGS`      | `driver_prepare_live_command()`  | array | Modified command for live streaming                   |
+
+### Read by drivers (set by ralph_loop.sh or .ralphrc)
+
+| Variable                | Used in                                    | Description                                    |
+|-------------------------|--------------------------------------------|------------------------------------------------|
+| `CLAUDE_OUTPUT_FORMAT`  | `driver_build_command()`                   | `"json"` or `"text"`                           |
+| `CLAUDE_PERMISSION_MODE`| `driver_build_command()` (claude-code)     | Permission mode flag, default `"bypassPermissions"` |
+| `CLAUDE_ALLOWED_TOOLS`  | `driver_build_command()` (claude-code)     | Comma-separated tool allowlist                 |
+| `CLAUDE_USE_CONTINUE`   | `driver_build_command()`                   | `"true"` or `"false"`, gates session resume    |
+| `RALPHRC_FILE`          | `driver_permission_denial_help()`          | Path to `.ralphrc` config file                 |
+| `DRIVER_DISPLAY_NAME`   | `driver_permission_denial_help()`          | Human-readable driver name                     |
+
+### Environment globals (cursor-specific)
+
+| Variable      | Used in                              | Description                         |
+|---------------|--------------------------------------|-------------------------------------|
+| `OS`, `OSTYPE`| `driver_running_on_windows()`        | OS detection                        |
+| `LOCALAPPDATA`| `driver_localappdata_cli_binary()`   | Windows local app data path         |
+| `PATH`        | `driver_find_windows_path_candidate()`| Manual PATH scanning on Windows    |
+
+### Set by ralph_loop.sh from driver output
+
+| Variable             | Source                  | Description                   |
+|----------------------|-------------------------|-------------------------------|
+| `CLAUDE_CODE_CMD`    | `driver_cli_binary()`   | CLI binary name/path          |
+| `DRIVER_DISPLAY_NAME`| `driver_display_name()` | Human-readable display name   |
+
+---
+
+## Capability Matrix
+
+| Capability                                              | claude-code | codex       | opencode    | copilot     | cursor      |
+|---------------------------------------------------------|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|
+| Tool allowlist (`driver_supports_tool_allowlist`)       | yes         | no          | no          | no          | no          |
+| Session continuity (`driver_supports_sessions`)         | yes         | yes         | yes         | no          | yes         |
+| Structured live output (`driver_supports_live_output`)  | yes         | yes         | yes         | no          | yes         |
+| Live command transform (`driver_prepare_live_command`)   | transform   | passthrough | passthrough | --          | transform   |
+| Stream filter (`driver_stream_filter`)                  | complex jq  | JSONL select| JSONL select| passthrough | complex jq  |
+| Custom session extraction (`driver_extract_session_id_from_output`) | --  | --    | yes         | --          | --          |
+| Fallback session lookup (`driver_fallback_session_id`)  | --          | --          | yes         | --          | --          |
+| Dynamic binary resolution (`driver_cli_binary`)         | static      | static      | static      | static      | dynamic     |
+
+---
+
+## Creating a New Driver
+
+### Minimal driver skeleton
+
+```bash
+#!/usr/bin/env bash
+# ralph/drivers/my-platform.sh
+# Driver for My Platform CLI
+#
+# Sourced by ralph_loop.sh via load_platform_driver().
+# PLATFORM_DRIVER must be set to "my-platform" in .ralphrc.
+
+# ---------------------------------------------------------------------------
+# Required hooks (5) -- omitting any of these breaks the loop
+# ---------------------------------------------------------------------------
+
+# Short lowercase identifier used to gate platform-specific logic.
+driver_name() {
+  echo "my-platform"
+}
+
+# Human-readable name for log messages and tmux pane titles.
+driver_display_name() {
+  echo "My Platform"
+}
+
+# CLI executable name or resolved path.
+driver_cli_binary() {
+  echo "my-platform"
+}
+
+# Populate VALID_TOOL_PATTERNS with recognized tool name patterns.
+# Used by validate_allowed_tools() to check allowlist entries.
+driver_valid_tools() {
+  VALID_TOOL_PATTERNS=(
+    "Read"
+    "Write"
+    "Edit"
+    "Bash"
+    # Add your platform's tool patterns here
+  )
+}
+
+# Build the complete CLI command array.
+# $1 = prompt_file  Path to .ralph/PROMPT.md
+# $2 = loop_context Context string for session continuity (may be empty)
+# $3 = session_id   Session ID for resume (empty = new session)
+driver_build_command() {
+  local prompt_file="$1"
+  local loop_context="$2"
+  local session_id="$3"
+
+  if [[ ! -f "$prompt_file" ]]; then
+    return 1
+  fi
+
+  CLAUDE_CMD_ARGS=(
+    "my-platform"
+    "--prompt" "$prompt_file"
+    "--output-format" "${CLAUDE_OUTPUT_FORMAT:-json}"
+  )
+
+  # Append session resume flag if continuing a session
+  if [[ "$CLAUDE_USE_CONTINUE" == "true" && -n "$session_id" ]]; then
+    CLAUDE_CMD_ARGS+=("--session" "$session_id")
+  fi
+
+  # Append context if provided
+  if [[ -n "$loop_context" ]]; then
+    CLAUDE_CMD_ARGS+=("--context" "$loop_context")
+  fi
+
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# Optional overrides (2) -- loop provides default stubs
+# ---------------------------------------------------------------------------
+
+# Return 0 if the platform supports --allowedTools filtering, 1 otherwise.
+driver_supports_tool_allowlist() {
+  return 1
+}
+
+# Print troubleshooting guidance on permission denial.
+driver_permission_denial_help() {
+  echo "Permission denied. Check that $DRIVER_DISPLAY_NAME has the required permissions."
+  echo "See $RALPHRC_FILE for configuration options."
+}
+
+# ---------------------------------------------------------------------------
+# Metadata hooks (2) -- used by bmalph doctor, not called by ralph_loop.sh
+# ---------------------------------------------------------------------------
+
+# Minimum required CLI version (semver).
+driver_min_version() {
+  echo "1.0.0"
+}
+
+# Return 0 if the CLI binary is installed and reachable, 1 otherwise.
+driver_check_available() {
+  command -v my-platform &>/dev/null
+}
+```
+
+### Checklist
+
+- [ ] All 5 required hooks implemented (`driver_name`, `driver_display_name`,
+      `driver_cli_binary`, `driver_valid_tools`, `driver_build_command`)
+- [ ] `driver_valid_tools` populates `VALID_TOOL_PATTERNS` with your platform's tool names
+- [ ] `driver_build_command` handles all three arguments correctly
+      (`prompt_file`, `loop_context`, `session_id`)
+- [ ] `driver_check_available` returns `0` only when the CLI is installed
+- [ ] File named `${platform_id}.sh` matching the `PLATFORM_DRIVER` value in `.ralphrc`
+- [ ] Register corresponding platform definition in `src/platform/` for bmalph CLI integration
+- [ ] Tested with `bmalph doctor`
+
+---
+
+## Session ID Recovery Chain
+
+When the loop needs to persist a session ID for resume, it follows a three-step priority
+chain (`ralph_loop.sh` lines 1574-1588):
+
+1. **`driver_extract_session_id_from_output($output_file)`** -- Driver-specific extraction.
+   If the function exists (`declare -F` guard) and echoes a non-empty string, that value
+   is used. Only `opencode` implements this (uses `sed` to extract from a `"session"` JSON
+   object).
+
+2. **`extract_session_id_from_output($output_file)`** -- Generic `jq` extractor from
+   `response_analyzer.sh`. Searches the output file for `.sessionId`,
+   `.metadata.session_id`, and `.session_id` in that order.
+
+3. **`driver_fallback_session_id($output_file)`** -- CLI-based last-resort recovery. If the
+   function exists and the previous steps produced nothing, this is called. Only `opencode`
+   implements this (queries `opencode session list --format json`).
+
+The first step that returns a non-empty string wins. If all three steps fail, no session ID
+is saved and the next iteration starts a fresh session.

package/ralph/drivers/codex.sh

@@ -46,7 +46,7 @@ driver_permission_denial_help() {
 }
 
 # Build Codex CLI command
-# Codex uses: codex exec [--resume <id>] --json "prompt"
+# Codex uses: codex exec [resume <id>] --json "prompt"
 driver_build_command() {
     local prompt_file=$1
     local loop_context=$2
@@ -67,7 +67,7 @@ driver_build_command() {
 
     # Session resume — gated on CLAUDE_USE_CONTINUE to respect --no-continue flag
     if [[ "$CLAUDE_USE_CONTINUE" == "true" && -n "$session_id" ]]; then
-        CLAUDE_CMD_ARGS+=("--resume" "$session_id")
+        CLAUDE_CMD_ARGS+=("resume" "$session_id")
     fi
 
     # Build prompt with context

package/ralph/lib/response_analyzer.sh

@@ -762,14 +762,14 @@ parse_json_response() {
     local summary_has_no_work_pattern="false"
     if [[ "$response_shape" == "codex_jsonl" || "$response_shape" == "opencode_jsonl" || "$response_shape" == "cursor_stream_jsonl" ]] && [[ "$explicit_exit_signal_found" != "true" && -n "$summary" ]]; then
         for keyword in "${COMPLETION_KEYWORDS[@]}"; do
-            if echo "$summary" | grep -qi "$keyword"; then
+            if echo "$summary" | grep -qiw "$keyword"; then
                 summary_has_completion_keyword="true"
                 break
             fi
         done
 
         for pattern in "${NO_WORK_PATTERNS[@]}"; do
-            if echo "$summary" | grep -qi "$pattern"; then
+            if echo "$summary" | grep -qiw "$pattern"; then
                 summary_has_no_work_pattern="true"
                 break
             fi
@@ -1035,13 +1035,15 @@ analyze_response() {
 
     # Text parsing fallback (original logic)
 
-    # Track whether an explicit EXIT_SIGNAL was found in RALPH_STATUS block
-    # If explicit signal found, heuristics should NOT override Claude's intent
-    local explicit_exit_signal_found=false
-
-    # 1. Check for explicit structured output (if Claude follows schema)
+    # 1. Check for explicit structured output (RALPH_STATUS block)
+    # When a status block is present, it is authoritative — skip all heuristics.
+    # A structurally valid but field-empty block results in exit_signal=false,
+    # confidence=0 by design (AI produced a block but provided no signal).
+    local ralph_status_block_found=false
     local ralph_status_json=""
     if ralph_status_json=$(extract_ralph_status_block_json "$output_content" 2>/dev/null); then
+        ralph_status_block_found=true
+
         local status
         status=$(printf '%s' "$ralph_status_json" | jq -r -j '.status' 2>/dev/null)
         local exit_sig_found
@@ -1062,14 +1064,14 @@ analyze_response() {
 
         # If EXIT_SIGNAL is explicitly provided, respect it
         if [[ "$exit_sig_found" == "true" ]]; then
-            explicit_exit_signal_found=true
             if [[ "$exit_sig" == "true" ]]; then
                 has_completion_signal=true
                 exit_signal=true
                 confidence_score=100
             else
-                # Explicit EXIT_SIGNAL: false - Claude says to continue
+                # Explicit EXIT_SIGNAL: false — Claude says to continue
                 exit_signal=false
+                confidence_score=80
             fi
         elif [[ "$status" == "COMPLETE" ]]; then
             # No explicit EXIT_SIGNAL but STATUS is COMPLETE
@@ -1077,68 +1079,93 @@ analyze_response() {
             exit_signal=true
             confidence_score=100
         fi
+        # is_test_only and is_stuck stay false (defaults) — status block is authoritative
     fi
 
-    # 2. Detect completion keywords in natural language output
-    for keyword in "${COMPLETION_KEYWORDS[@]}"; do
-        if grep -qi "$keyword" "$output_file"; then
-            has_completion_signal=true
-            ((confidence_score+=10))
-            break
-        fi
-    done
+    if [[ "$ralph_status_block_found" != "true" ]]; then
+        # No status block found — fall back to heuristic analysis
 
-    # 3. Detect test-only loops
-    local test_command_count=0
-    local implementation_count=0
-    local error_count=0
+        # 2. Detect completion keywords in natural language output
+        for keyword in "${COMPLETION_KEYWORDS[@]}"; do
+            if grep -qiw "$keyword" "$output_file"; then
+                has_completion_signal=true
+                ((confidence_score+=10))
+                break
+            fi
+        done
 
-    test_command_count=$(grep -c -i "running tests\|npm test\|bats\|pytest\|jest" "$output_file" 2>/dev/null | head -1 || echo "0")
-    implementation_count=$(grep -c -i "implementing\|creating\|writing\|adding\|function\|class" "$output_file" 2>/dev/null | head -1 || echo "0")
+        # 3. Detect test-only loops
+        local test_command_count=0
+        local implementation_count=0
+        local error_count=0
 
-    # Strip whitespace and ensure it's a number
-    test_command_count=$(echo "$test_command_count" | tr -d '[:space:]')
-    implementation_count=$(echo "$implementation_count" | tr -d '[:space:]')
+        test_command_count=$(grep -c -i "running tests\|npm test\|bats\|pytest\|jest" "$output_file" 2>/dev/null | head -1 || echo "0")
+        implementation_count=$(grep -c -i "implementing\|creating\|writing\|adding\|function\|class" "$output_file" 2>/dev/null | head -1 || echo "0")
 
-    # Convert to integers with default fallback
-    test_command_count=${test_command_count:-0}
-    implementation_count=${implementation_count:-0}
-    test_command_count=$((test_command_count + 0))
-    implementation_count=$((implementation_count + 0))
+        # Strip whitespace and ensure it's a number
+        test_command_count=$(echo "$test_command_count" | tr -d '[:space:]')
+        implementation_count=$(echo "$implementation_count" | tr -d '[:space:]')
 
-    if [[ $test_command_count -gt 0 ]] && [[ $implementation_count -eq 0 ]]; then
-        is_test_only=true
-        work_summary="Test execution only, no implementation"
-    fi
+        # Convert to integers with default fallback
+        test_command_count=${test_command_count:-0}
+        implementation_count=${implementation_count:-0}
+        test_command_count=$((test_command_count + 0))
+        implementation_count=$((implementation_count + 0))
 
-    # 4. Detect stuck/error loops
-    # Use two-stage filtering to avoid counting JSON field names as errors
-    # Stage 1: Filter out JSON field patterns like "is_error": false
-    # Stage 2: Count actual error messages in specific contexts
-    # Pattern aligned with ralph_loop.sh to ensure consistent behavior
-    error_count=$(grep -v '"[^"]*error[^"]*":' "$output_file" 2>/dev/null | \
-                  grep -cE '(^Error:|^ERROR:|^error:|\]: error|Link: error|Error occurred|failed with error|[Ee]xception|Fatal|FATAL)' \
-                  2>/dev/null || echo "0")
-    error_count=$(echo "$error_count" | tr -d '[:space:]')
-    error_count=${error_count:-0}
-    error_count=$((error_count + 0))
+        if [[ $test_command_count -gt 0 ]] && [[ $implementation_count -eq 0 ]]; then
+            is_test_only=true
+            work_summary="Test execution only, no implementation"
+        fi
 
-    if [[ $error_count -gt 5 ]]; then
-        is_stuck=true
-    fi
+        # 4. Detect stuck/error loops
+        # Use two-stage filtering to avoid counting JSON field names as errors
+        # Stage 1: Filter out JSON field patterns like "is_error": false
+        # Stage 2: Count actual error messages in specific contexts
+        # Pattern aligned with ralph_loop.sh to ensure consistent behavior
+        error_count=$(grep -v '"[^"]*error[^"]*":' "$output_file" 2>/dev/null | \
+                      grep -cE '(^Error:|^ERROR:|^error:|\]: error|Link: error|Error occurred|failed with error|[Ee]xception|Fatal|FATAL)' \
+                      2>/dev/null || echo "0")
+        error_count=$(echo "$error_count" | tr -d '[:space:]')
+        error_count=${error_count:-0}
+        error_count=$((error_count + 0))
+
+        if [[ $error_count -gt 5 ]]; then
+            is_stuck=true
+        fi
 
-    # 5. Detect "nothing to do" patterns
-    for pattern in "${NO_WORK_PATTERNS[@]}"; do
-        if grep -qi "$pattern" "$output_file"; then
-            has_completion_signal=true
-            ((confidence_score+=15))
-            work_summary="No work remaining"
-            break
+        # 5. Detect "nothing to do" patterns
+        for pattern in "${NO_WORK_PATTERNS[@]}"; do
+            if grep -qiw "$pattern" "$output_file"; then
+                has_completion_signal=true
+                ((confidence_score+=15))
+                work_summary="No work remaining"
+                break
+            fi
+        done
+
+        # 7. Analyze output length trends (detect declining engagement)
+        if [[ -f "$RALPH_DIR/.last_output_length" ]]; then
+            local last_length
+            last_length=$(cat "$RALPH_DIR/.last_output_length")
+            if [[ "$last_length" -gt 0 ]]; then
+                local length_ratio=$((output_length * 100 / last_length))
+                if [[ $length_ratio -lt 50 ]]; then
+                    # Output is less than 50% of previous - possible completion
+                    ((confidence_score+=10))
+                fi
+            fi
         fi
-    done
 
-    # 6. Check for file changes (git integration)
-    # Fix #141: Detect both uncommitted changes AND committed changes
+        # 9. Determine exit signal based on confidence (heuristic)
+        if [[ $confidence_score -ge 40 || "$has_completion_signal" == "true" ]]; then
+            exit_signal=true
+        fi
+    fi
+
+    # Always persist output length for next iteration (both paths)
+    echo "$output_length" > "$RALPH_DIR/.last_output_length"
+
+    # 6. Check for file changes (git integration) — always runs
     if command -v git &>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
         local loop_start_sha=""
         local current_sha=""
@@ -1174,19 +1201,7 @@ analyze_response() {
         fi
     fi
 
-    # 7. Analyze output length trends (detect declining engagement)
-    if [[ -f "$RALPH_DIR/.last_output_length" ]]; then
-        local last_length=$(cat "$RALPH_DIR/.last_output_length")
-        local length_ratio=$((output_length * 100 / last_length))
-
-        if [[ $length_ratio -lt 50 ]]; then
-            # Output is less than 50% of previous - possible completion
-            ((confidence_score+=10))
-        fi
-    fi
-    echo "$output_length" > "$RALPH_DIR/.last_output_length"
-
-    # 8. Extract work summary from output
+    # 8. Extract work summary from output — always runs
     if [[ -z "$work_summary" ]]; then
         # Try to find summary in output
         work_summary=$(grep -i "summary\|completed\|implemented" "$output_file" | head -1 | cut -c 1-100)
@@ -1195,21 +1210,6 @@ analyze_response() {
         fi
     fi
 
-    # Explicit EXIT_SIGNAL=false means "continue working", so completion
-    # heuristics must not register a done signal.
-    if [[ "$explicit_exit_signal_found" == "true" && "$exit_signal" == "false" ]]; then
-        has_completion_signal=false
-    fi
-
-    # 9. Determine exit signal based on confidence (heuristic)
-    # IMPORTANT: Only apply heuristics if no explicit EXIT_SIGNAL was found in RALPH_STATUS
-    # Claude's explicit intent takes precedence over natural language pattern matching
-    if [[ "$explicit_exit_signal_found" != "true" ]]; then
-        if [[ $confidence_score -ge 40 || "$has_completion_signal" == "true" ]]; then
-            exit_signal=true
-        fi
-    fi
-
     local has_permission_denials=false
     local permission_denial_count=0
     local denied_commands_json='[]'

package/ralph/ralph_loop.sh

@@ -76,6 +76,7 @@ _env_QUALITY_GATE_TIMEOUT="${QUALITY_GATE_TIMEOUT:-}"
 _env_QUALITY_GATE_ON_COMPLETION_ONLY="${QUALITY_GATE_ON_COMPLETION_ONLY:-}"
 _env_REVIEW_ENABLED="${REVIEW_ENABLED:-}"
 _env_REVIEW_INTERVAL="${REVIEW_INTERVAL:-}"
+_env_REVIEW_MODE="${REVIEW_MODE:-}"
 
 # Now set defaults (only if not already set by environment)
 MAX_CALLS_PER_HOUR="${MAX_CALLS_PER_HOUR:-100}"
@@ -116,6 +117,11 @@ REVIEW_FINDINGS_FILE="$RALPH_DIR/.review_findings.json"
 REVIEW_PROMPT_FILE="$RALPH_DIR/REVIEW_PROMPT.md"
 REVIEW_LAST_SHA_FILE="$RALPH_DIR/.review_last_sha"
 
+# REVIEW_MODE is derived in initialize_runtime_context() after .ralphrc is loaded.
+# This ensures backwards compat: old .ralphrc files with only REVIEW_ENABLED=true
+# still map to enhanced mode. Env vars always win via the snapshot/restore mechanism.
+REVIEW_MODE="${REVIEW_MODE:-off}"
+
 # Valid tool patterns for --allowed-tools validation
 # Default: Claude Code tools. Platform driver overwrites via driver_valid_tools() in main().
 # Validation runs in main() after load_platform_driver so the correct patterns are in effect.
@@ -267,6 +273,7 @@ load_ralphrc() {
     [[ -n "$_env_QUALITY_GATE_ON_COMPLETION_ONLY" ]] && QUALITY_GATE_ON_COMPLETION_ONLY="$_env_QUALITY_GATE_ON_COMPLETION_ONLY"
     [[ -n "$_env_REVIEW_ENABLED" ]] && REVIEW_ENABLED="$_env_REVIEW_ENABLED"
     [[ -n "$_env_REVIEW_INTERVAL" ]] && REVIEW_INTERVAL="$_env_REVIEW_INTERVAL"
+    [[ -n "$_env_REVIEW_MODE" ]] && REVIEW_MODE="$_env_REVIEW_MODE"
 
     normalize_claude_permission_mode
     RALPHRC_FILE="$config_file"
@@ -317,6 +324,14 @@ initialize_runtime_context() {
         fi
     fi
 
+    # Derive REVIEW_MODE after .ralphrc load so backwards-compat works:
+    # old .ralphrc files with only REVIEW_ENABLED=true map to enhanced mode.
+    if [[ "$REVIEW_MODE" == "off" && "$REVIEW_ENABLED" == "true" ]]; then
+        REVIEW_MODE="enhanced"
+    fi
+    # Keep REVIEW_ENABLED in sync for any code that checks it
+    [[ "$REVIEW_MODE" != "off" ]] && REVIEW_ENABLED="true" || REVIEW_ENABLED="false"
+
     # Load platform driver after config so PLATFORM_DRIVER can be overridden.
     load_platform_driver
     RUNTIME_CONTEXT_LOADED=true
@@ -357,7 +372,7 @@ get_tmux_base_index() {
 # Setup tmux session with monitor
 setup_tmux_session() {
     local session_name="ralph-$(date +%s)"
-    local ralph_home="${RALPH_HOME:-$HOME/.ralph}"
+    local ralph_home="${RALPH_HOME:-$SCRIPT_DIR}"
     local project_dir="$(pwd)"
 
     initialize_runtime_context
@@ -1282,27 +1297,44 @@ build_loop_context() {
     echo "${context:0:500}"
 }
 
-# Check if a periodic code review should run this iteration
+# Check if a code review should run this iteration
 # Returns 0 (true) when review is due, 1 (false) otherwise
+# Args: $1 = loop_count, $2 = fix_plan_completed_delta (optional, for ultimate mode)
 should_run_review() {
-    [[ "$REVIEW_ENABLED" != "true" ]] && return 1
+    [[ "$REVIEW_MODE" == "off" ]] && return 1
     local loop_count=$1
+    local fix_plan_delta=${2:-0}
+
     # Never review on first loop (no implementation yet)
     (( loop_count < 1 )) && return 1
-    (( loop_count % REVIEW_INTERVAL != 0 )) && return 1
+
     # Skip if circuit breaker is not CLOSED
     if [[ -f "$RALPH_DIR/.circuit_breaker_state" ]]; then
         local cb_state
         cb_state=$(jq -r '.state // "CLOSED"' "$RALPH_DIR/.circuit_breaker_state" 2>/dev/null)
         [[ "$cb_state" != "CLOSED" ]] && return 1
     fi
+
+    # Mode-specific trigger
+    case "$REVIEW_MODE" in
+        enhanced)
+            (( loop_count % REVIEW_INTERVAL != 0 )) && return 1
+            ;;
+        ultimate)
+            (( fix_plan_delta < 1 )) && return 1
+            ;;
+        *)
+            # Unknown mode — treat as off
+            return 1
+            ;;
+    esac
+
     # Skip if no changes since last review (committed or uncommitted)
     if command -v git &>/dev/null && git rev-parse --git-dir &>/dev/null 2>&1; then
         local current_sha last_sha
         current_sha=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
         last_sha=""
         [[ -f "$REVIEW_LAST_SHA_FILE" ]] && last_sha=$(cat "$REVIEW_LAST_SHA_FILE" 2>/dev/null)
-        # Check for new commits OR uncommitted workspace changes
         local has_uncommitted
         has_uncommitted=$(git status --porcelain 2>/dev/null | head -1)
         if [[ "$current_sha" == "$last_sha" && -z "$has_uncommitted" ]]; then
@@ -1313,7 +1345,8 @@ should_run_review() {
 }
 
 # Build review findings context for injection into the next implementation loop
-# Returns a compact string (max 500 chars) with unresolved findings
+# Returns a compact string (max 500-700 chars) with unresolved findings
+# HIGH/CRITICAL findings get a PRIORITY prefix and a higher char cap (700)
 build_review_context() {
     if [[ ! -f "$REVIEW_FINDINGS_FILE" ]]; then
         echo ""
@@ -1330,7 +1363,15 @@ build_review_context() {
         return
     fi
 
-    local context="REVIEW FINDINGS ($severity, $issues_found issues): $summary"
+    # HIGH/CRITICAL findings: instruct the AI to fix them before picking a new story
+    local context=""
+    local max_len=500
+    if [[ "$severity" == "HIGH" || "$severity" == "CRITICAL" ]]; then
+        context="PRIORITY: Fix these code review findings BEFORE picking a new story. "
+        max_len=700
+    fi
+    context+="REVIEW FINDINGS ($severity, $issues_found issues): $summary"
+
     # Include top details if space allows
     local top_details
     top_details=$(jq -r '(.details[:2] // []) | map("- [\(.severity)] \(.file): \(.issue)") | join("; ")' "$REVIEW_FINDINGS_FILE" 2>/dev/null | head -c 150)
@@ -1338,7 +1379,7 @@ build_review_context() {
         context+=" Details: $top_details"
     fi
 
-    echo "${context:0:500}"
+    echo "${context:0:$max_len}"
 }
 
 # Execute a periodic code review loop (read-only, no file modifications)
@@ -2499,8 +2540,18 @@ main() {
 
             update_status "$loop_count" "$(cat "$CALL_COUNT_FILE")" "completed" "success"
 
-            # Periodic code review check
-            if should_run_review "$loop_count"; then
+            # Consume review findings after successful execution — the AI has received
+            # the context via --append-system-prompt. Deleting here (not in
+            # build_review_context) ensures findings survive transient loop failures.
+            rm -f "$REVIEW_FINDINGS_FILE"
+
+            # Code review check
+            local fix_plan_delta=0
+            if [[ -f "$RESPONSE_ANALYSIS_FILE" ]]; then
+                fix_plan_delta=$(jq -r '.analysis.fix_plan_completed_delta // 0' "$RESPONSE_ANALYSIS_FILE" 2>/dev/null || echo "0")
+                [[ ! "$fix_plan_delta" =~ ^-?[0-9]+$ ]] && fix_plan_delta=0
+            fi
+            if should_run_review "$loop_count" "$fix_plan_delta"; then
                 run_review_loop "$loop_count"
             fi
 

package/ralph/templates/ralphrc.template

@@ -129,13 +129,18 @@ QUALITY_GATE_ON_COMPLETION_ONLY="${QUALITY_GATE_ON_COMPLETION_ONLY:-false}"
 # PERIODIC CODE REVIEW
 # =============================================================================
 
-# Enable periodic code review loops (set via 'bmalph run --review' or manually)
-# When enabled, Ralph runs a read-only review session every REVIEW_INTERVAL loops.
+# Review mode: off, enhanced, or ultimate (set via 'bmalph run --review [mode]')
+# - off:      no code review (default)
+# - enhanced: periodic review every REVIEW_INTERVAL loops (~10-14% more tokens)
+# - ultimate: review after every completed story (~20-30% more tokens)
 # The review agent analyzes git diffs and outputs findings for the next implementation loop.
 # Currently supported on Claude Code only.
+REVIEW_MODE="${REVIEW_MODE:-off}"
+
+# (Legacy) Enables review — prefer REVIEW_MODE instead
 REVIEW_ENABLED="${REVIEW_ENABLED:-false}"
 
-# Number of implementation loops between review sessions (default: 5)
+# Number of implementation loops between review sessions (enhanced mode only)
 REVIEW_INTERVAL="${REVIEW_INTERVAL:-5}"
 
 # =============================================================================