bmalph 2.8.0 → 2.10.0

package/dist/utils/constants.js

@@ -53,6 +53,28 @@ export const CONFIG_FILE = "bmalph/config.json";
 /** Ralph status file path */
 export const RALPH_STATUS_FILE = ".ralph/status.json";
 // =============================================================================
+// Ralph status mapping
+// =============================================================================
+/**
+ * Maps raw Ralph bash status strings to normalized status values.
+ * Single source of truth — used by both validate.ts and ralph-runtime-state.ts.
+ */
+export const RALPH_STATUS_MAP = {
+    running: "running",
+    halted: "blocked",
+    stopped: "blocked",
+    completed: "completed",
+    success: "completed",
+    graceful_exit: "completed",
+    paused: "blocked",
+    error: "blocked",
+};
+// =============================================================================
+// Gitignore entries managed by bmalph
+// =============================================================================
+/** Entries bmalph adds to .gitignore during init and checks during doctor */
+export const GITIGNORE_ENTRIES = [".ralph/logs/", "_bmad-output/"];
+// =============================================================================
 // Dashboard constants
 // =============================================================================
 /** Default dashboard refresh interval in milliseconds */

package/dist/utils/github.js

@@ -132,9 +132,10 @@ export class GitHubClient {
                 typeof data.sha !== "string" ||
                 !("commit" in data) ||
                 !data.commit ||
-                typeof data.commit?.message !== "string" ||
-                !data.commit?.author ||
-                typeof data.commit?.author?.date !== "string") {
+                typeof data.commit.message !==
+                    "string" ||
+                !data.commit.author ||
+                typeof data.commit.author.date !== "string") {
                 return {
                     success: false,
                     error: {

package/dist/utils/ralph-runtime-state.js

@@ -1,22 +1,12 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { RALPH_DIR, RALPH_STATUS_FILE } from "./constants.js";
+import { RALPH_DIR, RALPH_STATUS_FILE, RALPH_STATUS_MAP } from "./constants.js";
 import { isEnoent } from "./errors.js";
 import { validateCircuitBreakerState, validateRalphLoopStatus, validateRalphSession, } from "./validate.js";
 const RALPH_SESSION_FILE = ".ralph_session";
 const CIRCUIT_BREAKER_STATE_FILE = ".circuit_breaker_state";
 const CAMEL_CASE_CORE_KEYS = ["loopCount", "tasksCompleted", "tasksTotal"];
 const SNAKE_CASE_CORE_KEYS = ["loop_count", "tasks_completed", "tasks_total"];
-const RAW_RALPH_STATUS_MAP = {
-    running: "running",
-    halted: "blocked",
-    stopped: "blocked",
-    completed: "completed",
-    success: "completed",
-    graceful_exit: "completed",
-    paused: "blocked",
-    error: "blocked",
-};
 export async function readRalphRuntimeStatus(projectDir) {
     const path = join(projectDir, RALPH_STATUS_FILE);
     const raw = await readRuntimeJson(path);
@@ -149,9 +139,9 @@ function validateRalphSnakeCaseStatus(data) {
     if (typeof data.status !== "string") {
         throw new Error("ralphSnakeCaseStatus.status must be a string");
     }
-    const mappedStatus = RAW_RALPH_STATUS_MAP[data.status] ?? undefined;
+    const mappedStatus = RALPH_STATUS_MAP[data.status];
     if (mappedStatus === undefined) {
-        throw new Error(`ralphSnakeCaseStatus.status must be one of: ${Object.keys(RAW_RALPH_STATUS_MAP).join(", ")}`);
+        throw new Error(`ralphSnakeCaseStatus.status must be one of: ${Object.keys(RALPH_STATUS_MAP).join(", ")}`);
     }
     if ("tasks_completed" in data && typeof data.tasks_completed !== "number") {
         throw new Error("ralphSnakeCaseStatus.tasks_completed must be a number");

package/dist/utils/validate.js

@@ -1,5 +1,5 @@
 import { PLATFORM_IDS } from "../platform/types.js";
-import { DEFAULT_INTERVAL_MS, MAX_PROJECT_NAME_LENGTH, MIN_INTERVAL_MS } from "./constants.js";
+import { DEFAULT_INTERVAL_MS, MAX_PROJECT_NAME_LENGTH, MIN_INTERVAL_MS, RALPH_STATUS_MAP, } from "./constants.js";
 const VALID_STATUSES = ["planning", "implementing", "completed"];
 // Invalid filesystem characters (Windows + POSIX)
 const INVALID_FS_CHARS = /[<>:"/\\|?*]/;
@@ -178,21 +178,15 @@ export function validateRalphLoopStatus(data) {
         tasksTotal: data.tasksTotal,
     };
 }
-const BASH_STATUS_MAP = {
-    running: "running",
-    halted: "blocked",
-    stopped: "blocked",
-    completed: "completed",
-    success: "completed",
-    graceful_exit: "completed",
-};
 // Loose normalization helper for non-runtime consumers and legacy tests.
 // Runtime-file parsing uses the stricter contract in ralph-runtime-state.ts.
 export function normalizeRalphStatus(data) {
     assertObject(data, "normalizeRalphStatus");
     const loopCount = typeof data.loop_count === "number" ? data.loop_count : 0;
     const rawStatus = typeof data.status === "string" ? data.status : undefined;
-    const status = (rawStatus !== undefined ? BASH_STATUS_MAP[rawStatus] : undefined) ?? "unknown";
+    const status = (rawStatus !== undefined
+        ? RALPH_STATUS_MAP[rawStatus]
+        : undefined) ?? "unknown";
     return {
         loopCount,
         status,

package/dist/watch/dashboard.js

@@ -72,6 +72,7 @@ export async function startDashboard(options) {
             }
             resolve();
         };
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- setRawMode absent in pseudo-TTY
         if (process.stdin.isTTY && process.stdin.setRawMode) {
             process.stdin.setRawMode(true);
             process.stdin.resume();

package/dist/watch/renderer.js

@@ -311,6 +311,23 @@ export function renderAnalysisPanel(analysis, cols) {
     ];
     return box("Last Analysis", lines, cols);
 }
+export function renderReviewPanel(review, cols) {
+    if (!review) {
+        return "";
+    }
+    const safeSeverity = sanitizeExternalText(review.severity);
+    const severityColor = safeSeverity === "CRITICAL" || safeSeverity === "HIGH"
+        ? chalk.red
+        : safeSeverity === "MEDIUM"
+            ? chalk.yellow
+            : chalk.green;
+    const safeSummary = sanitizeExternalText(review.summary);
+    const lines = [
+        `Severity: ${severityColor(safeSeverity)}    Issues: ${String(review.issuesFound)}`,
+        safeSummary ? chalk.dim(safeSummary.slice(0, 70)) : "",
+    ].filter(Boolean);
+    return box("Review Findings", lines, cols);
+}
 export function renderLogsPanel(logs, cols) {
     if (logs.length === 0) {
         return box("Recent Activity", [chalk.dim("No activity yet")], cols);
@@ -358,10 +375,12 @@ function hasAnyData(state) {
         state.analysis !== null ||
         state.execution !== null ||
         state.session !== null ||
+        state.review !== null ||
         state.recentLogs.length > 0 ||
         state.liveLog.length > 0);
 }
 export function renderDashboard(state, cols, options = {}) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- columns is undefined in non-TTY
     const width = cols ?? process.stdout.columns ?? 80;
     const referenceTime = state.lastUpdated.getTime();
     const footerRenderer = options.footerRenderer ?? renderFooter;
@@ -381,6 +400,10 @@ export function renderDashboard(state, cols, options = {}) {
     const rightPanel = renderStoriesPanel(state.stories, width);
     sections.push(renderSideBySide(leftPanel, rightPanel, width));
     sections.push(renderAnalysisPanel(state.analysis, width));
+    const reviewPanel = renderReviewPanel(state.review, width);
+    if (reviewPanel) {
+        sections.push(reviewPanel);
+    }
     if (state.execution !== null) {
         sections.push(renderLiveLogPanel(state.liveLog, width));
     }

package/dist/watch/state-reader.js

@@ -10,13 +10,14 @@ const LOG_LINE_PATTERN = /^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\] \[(\w+)\] (
 const DEFAULT_MAX_LOG_LINES = 8;
 const TAIL_BYTES = 4096;
 export async function readDashboardState(projectDir) {
-    const [loop, circuitBreaker, stories, analysis, execution, session, recentLogs, liveLog] = await Promise.all([
+    const [loop, circuitBreaker, stories, analysis, execution, session, review, recentLogs, liveLog] = await Promise.all([
         readLoopInfo(projectDir),
         readCircuitBreakerInfo(projectDir),
         readStoryProgress(projectDir),
         readAnalysisInfo(projectDir),
         readExecutionProgress(projectDir),
         readSessionInfo(projectDir),
+        readReviewInfo(projectDir),
         readRecentLogs(projectDir),
         readLiveLog(projectDir),
     ]);
@@ -28,6 +29,7 @@ export async function readDashboardState(projectDir) {
         analysis,
         execution,
         session,
+        review,
         recentLogs,
         liveLog,
         ralphCompleted,
@@ -157,6 +159,23 @@ export async function readSessionInfo(projectDir) {
         lastUsed: result.value.last_used,
     };
 }
+export async function readReviewInfo(projectDir) {
+    try {
+        const data = await readJsonFile(join(projectDir, RALPH_DIR, ".review_findings.json"));
+        if (data === null)
+            return null;
+        const issuesFound = typeof data.issues_found === "number" ? data.issues_found : 0;
+        if (issuesFound === 0)
+            return null;
+        const severity = typeof data.severity === "string" ? data.severity : "LOW";
+        const summary = typeof data.summary === "string" ? data.summary : "";
+        return { issuesFound, severity, summary };
+    }
+    catch (err) {
+        debug(`Failed to read review info: ${formatError(err)}`);
+        return null;
+    }
+}
 const LIVE_LOG_MAX_LINES = 5;
 const LIVE_LOG_TAIL_BYTES = 2048;
 export async function readLiveLog(projectDir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmalph",
-  "version": "2.8.0",
+  "version": "2.10.0",
   "description": "Unified AI Development Framework - BMAD phases with Ralph execution loop",
   "type": "module",
   "bin": {
@@ -22,6 +22,9 @@
     "fmt:fix": "prettier --write .",
     "type-check": "tsc --noEmit",
     "ci": "npm run type-check && npm run lint && npm run fmt:check && npm run build && npm run test:all",
+    "clean": "rm -rf dist",
+    "rebuild": "npm run clean && npm run build",
+    "prepack": "npm run build",
     "prepublishOnly": "npm run lint && npm run build && npm run test:all",
     "update-bundled": "bash scripts/update-bundled.sh"
   },
@@ -55,13 +58,16 @@
   "files": [
     "bin/",
     "dist/",
+    "!dist/**/*.map",
     "bmad/",
     "ralph/",
     "slash-commands/",
     "bundled-versions.json"
   ],
   "dependencies": {
-    "@inquirer/prompts": "^8.3.0",
+    "@inquirer/confirm": "^5.1.9",
+    "@inquirer/input": "^4.1.9",
+    "@inquirer/select": "^4.2.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.2"
   },

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.