ralph-review 0.2.2 → 0.2.3

package/src/commands/run.ts

@@ -5,7 +5,7 @@ import { parseCommand } from "@/lib/cli-parser";
 import { loadEffectiveConfig } from "@/lib/config";
 import { collectIssueItems, runDiagnostics } from "@/lib/diagnostics";
 import { getTmuxInstallHint } from "@/lib/diagnostics/tmux-install";
-import type { DiagnosticsReport } from "@/lib/diagnostics/types";
+import type { DiagnosticItem, DiagnosticsReport } from "@/lib/diagnostics/types";
 import { type CycleResult, runReviewCycle } from "@/lib/engine";
 import { formatReviewType } from "@/lib/format";
 import { formatHandoffNote } from "@/lib/handoff-note";
@@ -19,6 +19,7 @@ import {
 } from "@/lib/priority-list";
 import { runFixSession } from "@/lib/review-workflow/remediation/run-fix-session";
 import type { FixSessionResult } from "@/lib/review-workflow/remediation/types";
+import { mapSessionStatusToFinalStatus } from "@/lib/review-workflow/session-status";
 import {
   createSessionId,
   createSessionState,
@@ -108,20 +109,6 @@ export function formatRunAgentsNote(config: Config, reviewOptions: ReviewOptions
   return lines.join("\n");
 }
 
-function mapSessionStatusToFinalStatus(
-  status: FixSessionResult["sessionStatus"]
-): CycleResult["finalStatus"] {
-  if (status === "failed") {
-    return "failed";
-  }
-
-  if (status === "interrupted") {
-    return "interrupted";
-  }
-
-  return "completed";
-}
-
 function hasAutoFixPriorityMatches(result: CycleResult, priorities: Priority[]): boolean {
   return (
     result.artifact?.findings.some((finding) => priorities.includes(finding.priority)) ?? false
@@ -257,6 +244,32 @@ export interface RunRuntimeOverrides
   timer?: Partial<RunRuntime["timer"]>;
 }
 
+function createRunCommandContext(overrides: RunRuntimeOverrides): {
+  runtime: RunRuntime;
+  projectPath: string;
+} {
+  const runtime = createRunRuntime(overrides);
+  return {
+    runtime,
+    projectPath: runtime.process.env.RR_PROJECT_PATH || runtime.process.cwd(),
+  };
+}
+
+function logPreflightItems(
+  runtime: RunRuntime,
+  items: DiagnosticItem[],
+  heading: string,
+  severity: "error" | "warn"
+): void {
+  runtime.prompt.log[severity](heading);
+  for (const item of items) {
+    runtime.prompt.log.message(`  ${item.summary}`);
+    item.remediation.forEach((remediation) => {
+      runtime.prompt.log.message(`    -> ${remediation}`);
+    });
+  }
+}
+
 export function createRunRuntime(overrides: RunRuntimeOverrides = {}): RunRuntime {
   const defaults: RunRuntime = {
     prompt: {
@@ -449,8 +462,7 @@ export async function runForeground(
   args: string[] = [],
   overrides: RunRuntimeOverrides = {}
 ): Promise<void> {
-  const runtime = createRunRuntime(overrides);
-  const projectPath = runtime.process.env.RR_PROJECT_PATH || runtime.process.cwd();
+  const { runtime, projectPath } = createRunCommandContext(overrides);
   const config = await runtime.loadConfig(projectPath);
   if (!config) {
     runtime.prompt.log.error("Failed to load config");
@@ -714,8 +726,7 @@ export async function startReview(
   args: string[],
   overrides: RunRuntimeOverrides = {}
 ): Promise<void> {
-  const runtime = createRunRuntime(overrides);
-  const projectPath = runtime.process.env.RR_PROJECT_PATH || runtime.process.cwd();
+  const { runtime, projectPath } = createRunCommandContext(overrides);
   // Parse options using command definition
   const runDef = runtime.getCommandDef("run");
   if (!runDef) {
@@ -856,25 +867,13 @@ export async function startReview(
   const warnings = issues.filter((item) => item.severity === "warning");
 
   if (errors.length > 0) {
-    runtime.prompt.log.error("Cannot run review:");
-    for (const item of errors) {
-      runtime.prompt.log.message(`  ${item.summary}`);
-      item.remediation.forEach((remediation) => {
-        runtime.prompt.log.message(`    -> ${remediation}`);
-      });
-    }
+    logPreflightItems(runtime, errors, "Cannot run review:", "error");
     runtime.process.exit(1);
     return;
   }
 
   if (warnings.length > 0) {
-    runtime.prompt.log.warn("Preflight warnings:");
-    for (const item of warnings) {
-      runtime.prompt.log.message(`  ${item.summary}`);
-      item.remediation.forEach((remediation) => {
-        runtime.prompt.log.message(`    -> ${remediation}`);
-      });
-    }
+    logPreflightItems(runtime, warnings, "Preflight warnings:", "warn");
   }
 
   const config = diagnostics.config ?? (await runtime.loadConfig(projectPath));

package/src/commands/stop.ts

@@ -1,5 +1,8 @@
 import * as p from "@clack/prompts";
-import { getCommandDef } from "@/cli";
+import {
+  createInteractiveCommandDeps,
+  type InteractiveCommandDeps,
+} from "@/commands/interactive-deps";
 import { parseCommand } from "@/lib/cli-parser";
 import { listProjectPendingHandoffs } from "@/lib/handoff";
 import { formatHandoffNote } from "@/lib/handoff-note";
@@ -22,19 +25,9 @@ interface StopOptions {
   session?: string;
 }
 
-interface StopDeps {
-  getCommandDef: typeof getCommandDef;
-  logError: (message: string) => void;
-  exit: (code: number) => void;
-  isTTY: () => boolean;
-}
+type StopDeps = InteractiveCommandDeps;
 
-const DEFAULT_STOP_DEPS: StopDeps = {
-  getCommandDef,
-  logError: (message: string) => p.log.error(message),
-  exit: (code: number) => process.exit(code),
-  isTTY: () => process.stdout.isTTY === true,
-};
+const DEFAULT_STOP_DEPS = createInteractiveCommandDeps();
 
 type ResolvedStopHandoff = {
   handoffStatus: Extract<HandoffStatus, "applied-auto" | "pending-apply" | "apply-conflicted">;

package/src/commands/update.ts

@@ -1,5 +1,6 @@
 import * as p from "@clack/prompts";
 import { getCommandDef } from "@/cli";
+import type { SpinnerFactory } from "@/cli-io";
 import { type CommandDef, parseCommand } from "@/lib/cli-parser";
 import {
   getDefaultSelfUpdateDependencies,
@@ -16,10 +17,7 @@ interface UpdateRuntime extends SelfUpdateDependencies {
   getCommandDef: (name: string) => CommandDef | undefined;
   parseCommand: typeof parseCommand;
   performSelfUpdate: typeof performSelfUpdate;
-  spinner: () => {
-    start: (message: string) => void;
-    stop: (message: string) => void;
-  };
+  spinner: SpinnerFactory;
   log: {
     error: (message: string) => void;
     info: (message: string) => void;

package/src/lib/agents/claude.ts

@@ -3,7 +3,7 @@
  */
 
 import type { AgentConfig, AgentRole, ReviewOptions } from "@/lib/types";
-import { createLineFormatter, parseJsonlEvent } from "./core";
+import { createLineFormatter, extractLastParsedValue, parseJsonlEvent } from "./core";
 import type {
   AssistantContentBlock,
   AssistantEvent,
@@ -128,21 +128,9 @@ export function formatClaudeEventForDisplay(event: ClaudeStreamEvent): string |
 }
 
 export function extractClaudeResult(output: string): string | null {
-  if (!output.trim()) {
-    return null;
-  }
-
-  const lines = output.split("\n");
-  let lastResult: string | null = null;
-
-  for (const line of lines) {
-    const event = parseClaudeStreamEvent(line);
-    if (event && isResultEvent(event)) {
-      lastResult = event.result;
-    }
-  }
-
-  return lastResult;
+  return extractLastParsedValue(output, parseClaudeStreamEvent, (event) =>
+    isResultEvent(event) ? event.result : null
+  );
 }
 
 export const formatClaudeLine = createLineFormatter(

package/src/lib/agents/core.ts

@@ -46,6 +46,22 @@ export function createLineFormatter<T>(
   };
 }
 
+export function extractLastParsedValue<T>(
+  output: string,
+  parser: (line: string) => T | null,
+  selectValue: (event: T) => string | null
+): string | null {
+  if (!output.trim()) {
+    return null;
+  }
+
+  return output.split("\n").reduce<string | null>((lastResult, line) => {
+    const event = parser(line);
+    const value = event ? selectValue(event) : null;
+    return value ?? lastResult;
+  }, null);
+}
+
 export function stripSystemReminders(text: unknown): string {
   const normalized = typeof text === "string" ? text : String(text ?? "");
   return normalized.replace(/<system-reminder>[\s\S]*?<\/system-reminder>\s*/g, "").trim();

package/src/lib/agents/droid.ts

@@ -11,6 +11,7 @@ import {
 import {
   createLineFormatter,
   defaultBuildEnv,
+  extractLastParsedValue,
   parseJsonlEvent,
   stripSystemReminders,
 } from "./core";
@@ -109,21 +110,9 @@ export function formatDroidEventForDisplay(event: DroidStreamEvent): string | nu
 }
 
 export function extractDroidResult(output: string): string | null {
-  if (!output.trim()) {
-    return null;
-  }
-
-  const lines = output.split("\n");
-  let lastResult: string | null = null;
-
-  for (const line of lines) {
-    const event = parseDroidStreamEvent(line);
-    if (event?.type === "completion") {
-      lastResult = event.finalText;
-    }
-  }
-
-  return lastResult;
+  return extractLastParsedValue(output, parseDroidStreamEvent, (event) =>
+    event.type === "completion" ? event.finalText : null
+  );
 }
 
 export const formatDroidLine = createLineFormatter(

package/src/lib/cli-parser.ts

@@ -162,6 +162,23 @@ function consumeOptionValue(
   throw new Error(`Option --${opt.name} requires a value`);
 }
 
+function assignOptionValue(
+  values: Record<string, unknown>,
+  opt: OptionDef,
+  argv: string[],
+  currentIndex: number,
+  inlineValue?: string
+): number {
+  if (opt.type === "boolean") {
+    values[opt.name] = true;
+    return currentIndex;
+  }
+
+  const { value, nextIndex } = consumeOptionValue(opt, argv, currentIndex, inlineValue);
+  values[opt.name] = parseValue(opt, value);
+  return nextIndex;
+}
+
 export function parseCommand<T = Record<string, unknown>>(
   def: CommandDef,
   argv: string[]
@@ -216,13 +233,7 @@ export function parseCommand<T = Record<string, unknown>>(
         throw new CliError(def.name, "unknown_option", arg, validOptions, suggestion);
       }
 
-      if (opt.type === "boolean") {
-        values[opt.name] = true;
-      } else {
-        const { value, nextIndex } = consumeOptionValue(opt, argv, i, inlineValue);
-        i = nextIndex;
-        values[opt.name] = parseValue(opt, value);
-      }
+      i = assignOptionValue(values, opt, argv, i, inlineValue);
 
       i++;
       continue;
@@ -249,13 +260,7 @@ export function parseCommand<T = Record<string, unknown>>(
         throw new CliError(def.name, "unknown_option", `-${alias}`, validOptions);
       }
 
-      if (opt.type === "boolean") {
-        values[opt.name] = true;
-      } else {
-        const { value, nextIndex } = consumeOptionValue(opt, argv, i);
-        i = nextIndex;
-        values[opt.name] = parseValue(opt, value);
-      }
+      i = assignOptionValue(values, opt, argv, i);
 
       i++;
       continue;

package/src/lib/handoff.ts

@@ -386,8 +386,8 @@ export async function listProjectPendingHandoffs(
   );
 }
 
-export async function applyPendingHandoff(
-  storageRoot: string = CONFIG_DIR,
+async function requirePendingHandoff(
+  storageRoot: string,
   projectPath: string,
   handoffId: string
 ): Promise<PendingHandoffArtifact> {
@@ -396,7 +396,19 @@ export async function applyPendingHandoff(
     throw new Error(`Pending review handoff "${handoffId}" was not found.`);
   }
 
-  return await applyPendingHandoffArtifact(storageRoot, artifact, "manual");
+  return artifact;
+}
+
+export async function applyPendingHandoff(
+  storageRoot: string = CONFIG_DIR,
+  projectPath: string,
+  handoffId: string
+): Promise<PendingHandoffArtifact> {
+  return await applyPendingHandoffArtifact(
+    storageRoot,
+    await requirePendingHandoff(storageRoot, projectPath, handoffId),
+    "manual"
+  );
 }
 
 export async function discardPendingHandoff(
@@ -404,10 +416,7 @@ export async function discardPendingHandoff(
   projectPath: string,
   handoffId: string
 ): Promise<PendingHandoffArtifact> {
-  const artifact = await readPendingHandoff(storageRoot, projectPath, handoffId);
-  if (!artifact) {
-    throw new Error(`Pending review handoff "${handoffId}" was not found.`);
-  }
+  const artifact = await requirePendingHandoff(storageRoot, projectPath, handoffId);
 
   if (artifact.state === "apply-conflicted") {
     throw new Error(

package/src/lib/logging/session-log.ts

@@ -517,6 +517,7 @@ function applyEntryToSummary(
     const unresolvedFindings = entry.fixResults.filter(
       (result) => result.status === "unresolved"
     ).length;
+    const skippedFindings = entry.fixResults.filter((result) => result.status === "skipped").length;
     const failed = entry.error !== undefined;
     const interrupted = entry.error?.message.toLowerCase().includes("interrupt") === true;
 
@@ -528,7 +529,7 @@ function applyEntryToSummary(
     next.totalResolvedSelectedFindings = resolvedFindings;
     next.totalUnresolvedSelectedFindings = unresolvedFindings;
     next.totalFixes = resolvedFindings;
-    next.totalSkipped = unresolvedFindings;
+    next.totalSkipped = skippedFindings + unresolvedFindings;
 
     if (entry.duration !== undefined) {
       next.totalDuration = (summary.totalDuration ?? 0) + entry.duration;

package/src/lib/prompts/defaults/review.md

@@ -89,6 +89,6 @@ Use this strict framing protocol:
 
 * **Do not** wrap the JSON in markdown fences or extra prose.
 * The code_location field is required and must include absolute_file_path and line_range.
-* Line ranges must be as short as possible for interpreting the issue (avoid ranges over 5–10 lines; pick the most suitable subrange).
+* Line ranges must use integer `start` and `end` values with `end >= start`, and must be as short as possible for interpreting the issue (avoid ranges over 5–10 lines; pick the most suitable subrange).
 * The code_location should overlap with the diff.
 * Do not generate a PR fix.

package/src/lib/prompts/protocol.ts

@@ -11,7 +11,8 @@ export function createReviewerStructuredOutputInstructions(): string {
   - ${REVIEW_SUMMARY_START_TOKEN}
   - ${REVIEW_SUMMARY_END_TOKEN}
 - Do not include markdown fences.
-- Do not include any text before the start token or after the end token.`;
+- Do not include any text before the start token or after the end token.
+- For each finding code_location.line_range, start and end MUST be integers and end MUST be greater than or equal to start.`;
 }
 
 export function createFixerStructuredOutputInstructions(): string {

package/src/lib/review-workflow/findings/artifact.ts

@@ -79,7 +79,9 @@ function isFixResultArray(value: unknown): value is FindingFixResult[] {
 
     return (
       isFindingId(entry.findingId) &&
-      (entry.status === "resolved" || entry.status === "unresolved") &&
+      (entry.status === "resolved" ||
+        entry.status === "skipped" ||
+        entry.status === "unresolved") &&
       typeof entry.summary === "string"
     );
   });

package/src/lib/review-workflow/findings/types.ts

@@ -19,7 +19,7 @@ export interface StoredFinding {
 
 export interface FindingFixResult {
   findingId: FindingId;
-  status: "resolved" | "unresolved";
+  status: "resolved" | "skipped" | "unresolved";
   summary: string;
 }
 

package/src/lib/review-workflow/remediation/prompt.ts

@@ -213,7 +213,7 @@ ${formatSelectedFindings(options.selectedFindings)}
 
 ## Required workflow
 1. Verify each selected finding independently against the real code.
-2. Decide resolved vs unresolved for each finding before making edits.
+2. Decide resolved vs skipped vs unresolved for each finding before making edits.
 3. Apply fixes only for findings you can prove.
 4. Keep edits as local and minimal as possible.
 5. Return one result entry for every selected finding ID.
@@ -231,8 +231,8 @@ ${FIX_SUMMARY_START_TOKEN}
   "decision": "<NO_CHANGES_NEEDED | APPLY_SELECTIVELY | APPLY_MOST>",
   "results": {
     "F001": {
-      "status": "<resolved | unresolved>",
-      "summary": "<what changed or why the finding remains unresolved>"
+      "status": "<resolved | skipped | unresolved>",
+      "summary": "<what changed or why the finding was skipped or remains unresolved>"
     }
   }
 }
@@ -240,11 +240,11 @@ ${FIX_SUMMARY_END_TOKEN}
 
 JSON rules:
 - Use the selected finding IDs as the object keys under \`results\`.
-- Return \`resolved\` only when the selected finding is fully addressed or already satisfied by the current code.
-- Return \`unresolved\` when the finding still needs follow-up, including when you skip it for lack of proof or cannot safely remediate it.
+- Return \`resolved\` only when the selected finding is verified and fixed; intentional edits may be included in a handoff.
+- Return \`skipped\` only when the selected finding is not actionable or not proven and does not require a code change.
+- Return \`unresolved\` when the finding is likely actionable or you attempted a fix but cannot safely complete and verify it.
 - You must return one result entry for every selected finding ID.
 - Do not include any finding that was not selected.
-- Use \`resolved\` only when you verified the issue and applied a real code change.
-- Use \`unresolved\` when the finding was unproven, out of scope, or did not require a safe change.
+- Missing result entries will be treated as \`unresolved\`.
 - The delimited JSON block must be the final output.`;
 }

package/src/lib/review-workflow/remediation/run-batch-fix-phase.ts

@@ -19,7 +19,7 @@ import type { Config } from "@/lib/types";
 import type { FixDecision } from "@/lib/types/domain";
 
 interface BatchFixerResultEntry {
-  status: "resolved" | "unresolved";
+  status: "resolved" | "skipped" | "unresolved";
   summary: string;
 }
 
@@ -66,7 +66,9 @@ function isBatchFixerResultEntry(value: unknown): value is BatchFixerResultEntry
 
   const candidate = value as Record<string, unknown>;
   return (
-    (candidate.status === "resolved" || candidate.status === "unresolved") &&
+    (candidate.status === "resolved" ||
+      candidate.status === "skipped" ||
+      candidate.status === "unresolved") &&
     typeof candidate.summary === "string"
   );
 }
@@ -124,6 +126,30 @@ function toFixResults(
   });
 }
 
+async function appendBatchFixLog(
+  deps: RunBatchFixPhaseDependencies,
+  options: RunBatchFixPhaseOptions,
+  startedAt: number,
+  fixResults: FindingFixResult[],
+  error?: unknown
+): Promise<void> {
+  await deps.appendLog(options.artifact.logPath, {
+    type: "batch_fix",
+    timestamp: Date.now(),
+    duration: Date.now() - startedAt,
+    selectedFindingIds: options.selection.selectedFindingIds,
+    fixResults,
+    ...(error === undefined
+      ? {}
+      : {
+          error: {
+            phase: "fixer" as const,
+            message: error instanceof Error ? error.message : String(error),
+          },
+        }),
+  });
+}
+
 export async function runBatchFixPhase(
   options: RunBatchFixPhaseOptions,
   deps: RunBatchFixPhaseDependencies = DEFAULT_RUN_BATCH_FIX_PHASE_DEPENDENCIES
@@ -168,13 +194,7 @@ export async function runBatchFixPhase(
     const fixResults = toFixResults(options.selection.selectedFindingIds, parsed);
 
     deps.discardCheckpoint(options.worktree.worktreeProjectPath, checkpoint);
-    await deps.appendLog(options.artifact.logPath, {
-      type: "batch_fix",
-      timestamp: Date.now(),
-      duration: Date.now() - startedAt,
-      selectedFindingIds: options.selection.selectedFindingIds,
-      fixResults,
-    });
+    await appendBatchFixLog(deps, options, startedAt, fixResults);
 
     return {
       phase: "batch-fix",
@@ -183,17 +203,7 @@ export async function runBatchFixPhase(
     };
   } catch (error) {
     deps.rollbackToCheckpoint(options.worktree.worktreeProjectPath, checkpoint);
-    await deps.appendLog(options.artifact.logPath, {
-      type: "batch_fix",
-      timestamp: Date.now(),
-      duration: Date.now() - startedAt,
-      selectedFindingIds: options.selection.selectedFindingIds,
-      fixResults: [],
-      error: {
-        phase: "fixer",
-        message: error instanceof Error ? error.message : String(error),
-      },
-    });
+    await appendBatchFixLog(deps, options, startedAt, [], error);
     throw error;
   }
 }