ralphctl 0.2.2 → 0.2.3

package/README.md

@@ -206,9 +206,9 @@ Run `ralphctl <command> --help` for details on any command.
 | [Contributing](./CONTRIBUTING.md)              | Dev setup, code style, PR process          |
 | [Changelog](./CHANGELOG.md)                    | Version history                            |
 
-**Blog posts:** [Building ralphctl](https://lukasgrigis.dev/blog/building-ralphctl) (
-backstory) | [From task CLI to agent harness](https://lukasgrigis.dev/blog/ralphctl-agent-harness/) (evaluator
-deep-dive)
+**Blog posts:** [Building ralphctl](https://lukasgrigis.dev/blog/building-ralphctl) (backstory) | [From task CLI to agent harness](https://lukasgrigis.dev/blog/ralphctl-agent-harness/) (evaluator deep-dive)
+
+**Further reading:** [Harness Engineering for Coding Agent Users](https://martinfowler.com/articles/harness-engineering.html) — Martin Fowler (April 2026) | [Harness Design for Long-Running Application Development](https://www.anthropic.com/engineering/harness-design-long-running-apps) — Anthropic Engineering
 
 ---
 

package/dist/{add-SEDQ3VK7.mjs → add-DWNLZQ7Q.mjs}

@@ -2,12 +2,12 @@
 import {
   addSingleTicketInteractive,
   ticketAddCommand
-} from "./chunk-XPDI4SYI.mjs";
+} from "./chunk-QYF7QIZJ.mjs";
 import "./chunk-7TG3EAQ2.mjs";
-import "./chunk-LG6B7QVO.mjs";
-import "./chunk-KPTPKLXY.mjs";
+import "./chunk-7TBO6GOT.mjs";
+import "./chunk-ITRZMBLJ.mjs";
 import "./chunk-OEUJDSHY.mjs";
-import "./chunk-ZDEVRTGY.mjs";
+import "./chunk-GLDPHKEW.mjs";
 import "./chunk-EDJX7TT6.mjs";
 import "./chunk-QBXHAXHI.mjs";
 export {

package/dist/{add-TGJTRHIF.mjs → add-K7LNOYQ4.mjs}

@@ -2,12 +2,12 @@
 import {
   addCheckScriptToRepository,
   projectAddCommand
-} from "./chunk-Q3VWJARJ.mjs";
+} from "./chunk-LAERLCL5.mjs";
 import "./chunk-7LZ6GOGN.mjs";
 import "./chunk-7TG3EAQ2.mjs";
-import "./chunk-LG6B7QVO.mjs";
+import "./chunk-7TBO6GOT.mjs";
 import "./chunk-OEUJDSHY.mjs";
-import "./chunk-ZDEVRTGY.mjs";
+import "./chunk-GLDPHKEW.mjs";
 import "./chunk-EDJX7TT6.mjs";
 import "./chunk-QBXHAXHI.mjs";
 export {

package/dist/{chunk-LG6B7QVO.mjs → chunk-7TBO6GOT.mjs}

@@ -7,7 +7,7 @@ import {
   readValidatedJson,
   validateProjectPath,
   writeValidatedJson
-} from "./chunk-ZDEVRTGY.mjs";
+} from "./chunk-GLDPHKEW.mjs";
 import {
   ParseError,
   ProjectExistsError,

package/dist/{chunk-ZDEVRTGY.mjs → chunk-GLDPHKEW.mjs}

@@ -53,13 +53,20 @@ function getTasksFilePath(sprintId) {
 function getProgressFilePath(sprintId) {
   return join(getSprintDir(sprintId), "progress.md");
 }
+function assertSafeSegment(segment, label) {
+  if (!segment || segment.includes("/") || segment.includes("\\") || segment.includes("..") || segment.includes("\0")) {
+    throw new Error(`Path traversal detected in ${label}: ${segment}`);
+  }
+}
 function getRefinementDir(sprintId, ticketId) {
+  assertSafeSegment(ticketId, "ticket ID");
   return join(getSprintDir(sprintId), "refinement", ticketId);
 }
 function getPlanningDir(sprintId) {
   return join(getSprintDir(sprintId), "planning");
 }
 function getIdeateDir(sprintId, ticketId) {
+  assertSafeSegment(ticketId, "ticket ID");
   return join(getSprintDir(sprintId), "ideation", ticketId);
 }
 function getSchemaPath(schemaName) {
@@ -233,6 +240,7 @@ var TaskSchema = z.object({
   name: z.string().min(1),
   description: z.string().optional(),
   steps: z.array(z.string()).default([]),
+  verificationCriteria: z.array(z.string()).default([]),
   status: TaskStatusSchema.default("todo"),
   order: z.number().int().positive(),
   ticketId: z.string().optional(),
@@ -257,6 +265,7 @@ var ImportTaskSchema = z.object({
   // Required
   description: z.string().optional(),
   steps: z.array(z.string()).optional(),
+  verificationCriteria: z.array(z.string()).optional(),
   ticketId: z.string().optional(),
   blockedBy: z.array(z.string()).optional(),
   projectPath: z.string().min(1)

package/dist/{chunk-KPTPKLXY.mjs → chunk-ITRZMBLJ.mjs}

@@ -21,7 +21,7 @@ import {
   readValidatedJson,
   removeDir,
   writeValidatedJson
-} from "./chunk-ZDEVRTGY.mjs";
+} from "./chunk-GLDPHKEW.mjs";
 import {
   LockError,
   NoCurrentSprintError,

package/dist/{chunk-Q3VWJARJ.mjs → chunk-LAERLCL5.mjs}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-7TG3EAQ2.mjs";
 import {
   createProject
-} from "./chunk-LG6B7QVO.mjs";
+} from "./chunk-7TBO6GOT.mjs";
 import {
   ensureError,
   wrapAsync
@@ -16,7 +16,7 @@ import {
 import {
   expandTilde,
   validateProjectPath
-} from "./chunk-ZDEVRTGY.mjs";
+} from "./chunk-GLDPHKEW.mjs";
 import {
   IOError,
   ProjectExistsError

package/dist/{chunk-XXIHDQOH.mjs → chunk-ORVGM6EV.mjs}

@@ -11,7 +11,7 @@ import {
   getPendingRequirements,
   groupTicketsByProject,
   listTickets
-} from "./chunk-XPDI4SYI.mjs";
+} from "./chunk-QYF7QIZJ.mjs";
 import {
   EXIT_ALL_BLOCKED,
   EXIT_ERROR,
@@ -23,7 +23,7 @@ import {
 import {
   getProject,
   listProjects
-} from "./chunk-LG6B7QVO.mjs";
+} from "./chunk-7TBO6GOT.mjs";
 import {
   activateSprint,
   assertSprintStatus,
@@ -40,7 +40,7 @@ import {
   setAiProvider,
   summarizeProgressForContext,
   withFileLock
-} from "./chunk-KPTPKLXY.mjs";
+} from "./chunk-ITRZMBLJ.mjs";
 import {
   ensureError,
   unwrapOrThrow,
@@ -61,7 +61,7 @@ import {
   getTasksFilePath,
   readValidatedJson,
   writeValidatedJson
-} from "./chunk-ZDEVRTGY.mjs";
+} from "./chunk-GLDPHKEW.mjs";
 import {
   DependencyCycleError,
   IOError,
@@ -162,10 +162,13 @@ function buildEvaluatorPrompt(ctx) {
   const stepsSection = ctx.taskSteps.length > 0 ? `
 **Implementation Steps:**
 ${ctx.taskSteps.map((s) => `- ${s}`).join("\n")}` : "";
+  const criteriaSection = ctx.verificationCriteria.length > 0 ? `
+**Verification Criteria:**
+${ctx.verificationCriteria.map((c) => `- ${c}`).join("\n")}` : "";
   const checkSection = ctx.checkScriptSection ? `
 
 ${ctx.checkScriptSection}` : "";
-  return template.replaceAll("{{TASK_NAME}}", ctx.taskName).replace("{{TASK_DESCRIPTION_SECTION}}", descriptionSection).replace("{{TASK_STEPS_SECTION}}", stepsSection).replace("{{PROJECT_PATH}}", ctx.projectPath).replace("{{CHECK_SCRIPT_SECTION}}", checkSection);
+  return template.replaceAll("{{TASK_NAME}}", ctx.taskName).replace("{{TASK_DESCRIPTION_SECTION}}", descriptionSection).replace("{{TASK_STEPS_SECTION}}", stepsSection).replace("{{VERIFICATION_CRITERIA_SECTION}}", criteriaSection).replace("{{PROJECT_PATH}}", ctx.projectPath).replace("{{CHECK_SCRIPT_SECTION}}", checkSection);
 }
 
 // src/utils/requirements-export.ts
@@ -1087,6 +1090,7 @@ async function addTask(input3, sprintId) {
       name: input3.name,
       description: input3.description,
       steps: input3.steps ?? [],
+      verificationCriteria: input3.verificationCriteria ?? [],
       status: "todo",
       order: maxOrder + 1,
       ticketId: input3.ticketId,
@@ -1320,6 +1324,7 @@ function validateImportTasks(importTasks2, existingTasks, ticketIds) {
       name: t.name,
       description: void 0,
       steps: [],
+      verificationCriteria: [],
       status: "todo",
       order: existingTasks.length + i + 1,
       ticketId: void 0,
@@ -1355,7 +1360,7 @@ async function selectProject(message = "Select project:") {
       default: true
     });
     if (create) {
-      const { projectAddCommand } = await import("./add-TGJTRHIF.mjs");
+      const { projectAddCommand } = await import("./add-K7LNOYQ4.mjs");
       await projectAddCommand({ interactive: true });
       const updated = await listProjects();
       if (updated.length === 0) return null;
@@ -1428,7 +1433,7 @@ async function selectSprint(message = "Select sprint:", filter) {
       default: true
     });
     if (create) {
-      const { sprintCreateCommand } = await import("./create-DJHCP7LN.mjs");
+      const { sprintCreateCommand } = await import("./create-5MILNF7E.mjs");
       await sprintCreateCommand({ interactive: true });
       const updated = await listSprints();
       const refiltered = filter ? updated.filter((s) => filter.includes(s.status)) : updated;
@@ -1463,7 +1468,7 @@ async function selectTicket(message = "Select ticket:", filter) {
         default: true
       });
       if (create) {
-        const { ticketAddCommand } = await import("./add-SEDQ3VK7.mjs");
+        const { ticketAddCommand } = await import("./add-DWNLZQ7Q.mjs");
         await ticketAddCommand({ interactive: true });
         const updated = await listTickets();
         const refiltered = filter ? updated.filter(filter) : updated;
@@ -1658,6 +1663,7 @@ async function importTasksReplace(tasks, sprintId) {
       name: taskInput.name,
       description: taskInput.description,
       steps: taskInput.steps ?? [],
+      verificationCriteria: taskInput.verificationCriteria ?? [],
       status: "todo",
       order: newTasks.length + 1,
       ticketId: taskInput.ticketId,
@@ -2321,6 +2327,16 @@ function formatTask(ctx) {
       lines.push(`${String(i + 1)}. ${step}`);
     });
   }
+  if (ctx.task.verificationCriteria.length > 0) {
+    lines.push("");
+    lines.push("## Verification Criteria");
+    lines.push("");
+    lines.push("The task is done when all of the following are true:");
+    lines.push("");
+    ctx.task.verificationCriteria.forEach((criterion) => {
+      lines.push(`- ${criterion}`);
+    });
+  }
   return lines.join("\n");
 }
 function buildFullTaskContext(ctx, progressSummary, gitHistory, checkScript, checkStatus) {
@@ -2472,30 +2488,53 @@ function getEvaluatorModel(generatorModel, provider) {
   if (modelLower.includes("sonnet")) return "claude-haiku-4-5";
   return "claude-haiku-4-5";
 }
+var DIMENSION_NAMES = ["correctness", "completeness", "safety", "consistency"];
+var DIMENSION_PATTERNS = {
+  correctness: /\*\*correctness\*\*\s*:\s*(PASS|FAIL)\s*(?:—|-)\s*(.+)/i,
+  completeness: /\*\*completeness\*\*\s*:\s*(PASS|FAIL)\s*(?:—|-)\s*(.+)/i,
+  safety: /\*\*safety\*\*\s*:\s*(PASS|FAIL)\s*(?:—|-)\s*(.+)/i,
+  consistency: /\*\*consistency\*\*\s*:\s*(PASS|FAIL)\s*(?:—|-)\s*(.+)/i
+};
+function parseDimensionScores(output) {
+  const scores = [];
+  for (const dim of DIMENSION_NAMES) {
+    const match = DIMENSION_PATTERNS[dim].exec(output);
+    if (match?.[1] && match[2]) {
+      scores.push({
+        dimension: dim,
+        passed: match[1].toUpperCase() === "PASS",
+        finding: match[2].trim()
+      });
+    }
+  }
+  return scores;
+}
 function parseEvaluationResult(output) {
+  const dimensions = parseDimensionScores(output);
   if (output.includes("<evaluation-passed>")) {
-    return { passed: true, output };
+    return { passed: true, output, dimensions };
   }
   const failedMatch = /<evaluation-failed>([\s\S]*?)<\/evaluation-failed>/.exec(output);
   if (failedMatch) {
-    return { passed: false, output: failedMatch[1]?.trim() ?? output };
+    return { passed: false, output: failedMatch[1]?.trim() ?? output, dimensions };
   }
-  return { passed: false, output };
+  return { passed: false, output, dimensions };
 }
 function buildEvaluatorContext(task, checkScript) {
-  const checkScriptSection = checkScript ? `## Check Script
+  const checkScriptSection = checkScript ? `## Check Script (Computational Gate)
 
-You can run the following check script to verify the changes:
+Run this check script as the **first step** of your review \u2014 it is the same gate the harness uses post-task:
 
 \`\`\`
 ${checkScript}
 \`\`\`
 
-Run it to gain additional insight into whether the implementation is correct.` : null;
+If this script fails, the implementation fails regardless of code quality. Record the full output.` : null;
   return {
     taskName: task.name,
     taskDescription: task.description ?? "",
     taskSteps: task.steps,
+    verificationCriteria: task.verificationCriteria,
     projectPath: task.projectPath,
     checkScriptSection
   };
@@ -2520,6 +2559,7 @@ async function runEvaluation(task, generatorModel, checkScript, sprintId, provid
 }
 
 // src/ai/executor.ts
+var DEFAULT_MAX_TURNS = 200;
 function buildProviderArgs(options, provider) {
   if (provider.name !== "claude") {
     if (options.maxBudgetUsd != null) {
@@ -2528,6 +2568,9 @@ function buildProviderArgs(options, provider) {
     if (options.fallbackModel) {
       console.log(warning(`--fallback-model is only supported with the Claude provider \u2014 ignored`));
     }
+    if (options.maxTurns != null) {
+      console.log(warning(`--max-turns is only supported with the Claude provider \u2014 ignored`));
+    }
     return [];
   }
   const args = [];
@@ -2537,6 +2580,7 @@ function buildProviderArgs(options, provider) {
   if (options.fallbackModel) {
     args.push("--fallback-model", options.fallbackModel);
   }
+  args.push("--max-turns", String(options.maxTurns ?? DEFAULT_MAX_TURNS));
   return args;
 }
 async function executeTask(ctx, options, sprintId, resumeSessionId, provider, checkStatus) {
@@ -2672,6 +2716,8 @@ async function runEvaluationLoop(params) {
   const evalCheckScript = getEffectiveCheckScript(project, task.projectPath);
   const sprintDir = getSprintDir(sprintId);
   let evalResult = await runEvaluation(task, result.model, evalCheckScript, sprintId, provider);
+  let currentSessionId = result.sessionId;
+  let currentModel = result.model;
   for (let i = 0; i < evalIterations && !evalResult.passed; i++) {
     console.log(warning(`Evaluation failed for ${task.name} (iteration ${String(i + 1)}/${String(evalIterations)})`));
     console.log(muted(evalResult.output.slice(0, 500)));
@@ -2689,7 +2735,7 @@ Review the critique carefully. Fix each identified issue in the code, then:
 ${options.noCommit ? "" : "2. Commit the fix with a descriptive message\n"}${options.noCommit ? "2" : "3"}. Signal completion with <task-verified> and <task-complete>
 
 If the critique is about something outside your task scope, fix only what is within scope and signal completion.`,
-        resumeSessionId: result.sessionId ?? void 0,
+        resumeSessionId: currentSessionId ?? void 0,
         env: provider.getSpawnEnv()
       },
       {
@@ -2703,6 +2749,8 @@ If the critique is about something outside your task scope, fix only what is wit
       provider
     );
     resumeSpinner?.succeed(`Fix attempt completed: ${task.name}`);
+    if (resumeResult.sessionId) currentSessionId = resumeResult.sessionId;
+    if (resumeResult.model) currentModel = resumeResult.model;
     const fixResult = parseExecutionResult(resumeResult.stdout);
     if (!fixResult.success) {
       console.log(warning(`Generator could not fix issues after feedback: ${task.name}`));
@@ -2716,7 +2764,7 @@ If the critique is about something outside your task scope, fix only what is wit
         break;
       }
     }
-    evalResult = await runEvaluation(task, resumeResult.model ?? result.model, evalCheckScript, sprintId, provider);
+    evalResult = await runEvaluation(task, currentModel, evalCheckScript, sprintId, provider);
   }
   await updateTask(
     task.id,
@@ -3801,6 +3849,16 @@ function parseArgs3(args) {
         throw new Error("Invalid model name \u2014 must be 1-100 alphanumeric characters, dots, hyphens, or underscores");
       }
       options.fallbackModel = modelStr;
+    } else if (arg === "--max-turns") {
+      const turnsStr = args[++i];
+      if (!turnsStr) {
+        throw new Error("--max-turns requires a number");
+      }
+      const turns = parseInt(turnsStr, 10);
+      if (isNaN(turns) || turns <= 0) {
+        throw new Error("--max-turns must be a positive integer");
+      }
+      options.maxTurns = turns;
     } else if (arg === "--no-evaluate") {
       options.noEvaluate = true;
     } else if (!arg?.startsWith("-")) {

package/dist/{chunk-XPDI4SYI.mjs → chunk-QYF7QIZJ.mjs}

@@ -6,14 +6,14 @@ import {
 import {
   listProjects,
   projectExists
-} from "./chunk-LG6B7QVO.mjs";
+} from "./chunk-7TBO6GOT.mjs";
 import {
   assertSprintStatus,
   generateUuid8,
   getEditor,
   resolveSprintId,
   setEditor
-} from "./chunk-KPTPKLXY.mjs";
+} from "./chunk-ITRZMBLJ.mjs";
 import {
   ensureError,
   unwrapOrThrow,
@@ -24,7 +24,7 @@ import {
   getSprintFilePath,
   readValidatedJson,
   writeValidatedJson
-} from "./chunk-ZDEVRTGY.mjs";
+} from "./chunk-GLDPHKEW.mjs";
 import {
   IOError,
   IssueFetchError,

package/dist/{chunk-XQHEKKDN.mjs → chunk-V4ZUDZCG.mjs}

@@ -2,7 +2,7 @@
 import {
   createSprint,
   setCurrentSprint
-} from "./chunk-KPTPKLXY.mjs";
+} from "./chunk-ITRZMBLJ.mjs";
 import {
   emoji,
   field,

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import {
   addCheckScriptToRepository,
   projectAddCommand
-} from "./chunk-Q3VWJARJ.mjs";
+} from "./chunk-LAERLCL5.mjs";
 import {
   addTask,
   areAllTasksDone,
@@ -52,13 +52,13 @@ import {
   sprintStartCommand,
   updateTaskStatus,
   validateImportTasks
-} from "./chunk-XXIHDQOH.mjs";
+} from "./chunk-ORVGM6EV.mjs";
 import {
   escapableSelect
 } from "./chunk-7LZ6GOGN.mjs";
 import {
   sprintCreateCommand
-} from "./chunk-XQHEKKDN.mjs";
+} from "./chunk-V4ZUDZCG.mjs";
 import {
   addTicket,
   allRequirementsApproved,
@@ -73,7 +73,7 @@ import {
   removeTicket,
   ticketAddCommand,
   updateTicket
-} from "./chunk-XPDI4SYI.mjs";
+} from "./chunk-QYF7QIZJ.mjs";
 import {
   EXIT_ERROR,
   exitWithCode
@@ -84,7 +84,7 @@ import {
   listProjects,
   removeProject,
   removeProjectRepo
-} from "./chunk-LG6B7QVO.mjs";
+} from "./chunk-7TBO6GOT.mjs";
 import {
   DEFAULT_EVALUATION_ITERATIONS,
   assertSprintStatus,
@@ -107,7 +107,7 @@ import {
   setEditor,
   setEvaluationIterations,
   withFileLock
-} from "./chunk-KPTPKLXY.mjs";
+} from "./chunk-ITRZMBLJ.mjs";
 import {
   ensureError,
   wrapAsync
@@ -122,6 +122,7 @@ import {
   TaskStatusSchema,
   TasksSchema,
   assertSafeCwd,
+  ensureDir,
   expandTilde,
   fileExists,
   getDataDir,
@@ -133,7 +134,7 @@ import {
   getTasksFilePath,
   readValidatedJson,
   validateProjectPath
-} from "./chunk-ZDEVRTGY.mjs";
+} from "./chunk-GLDPHKEW.mjs";
 import {
   DomainError,
   NoCurrentSprintError,
@@ -3763,7 +3764,7 @@ async function interactiveMode() {
       continue;
     }
     if (command === "wizard") {
-      const { runWizard } = await import("./wizard-D7N5WZ5H.mjs");
+      const { runWizard } = await import("./wizard-RCQ4QQOL.mjs");
       await runWizard();
       continue;
     }
@@ -3898,6 +3899,87 @@ async function sprintSwitchCommand() {
   log.newline();
 }
 
+// src/commands/sprint/insights.ts
+import { writeFile as writeFile2 } from "fs/promises";
+import { join as join5 } from "path";
+async function sprintInsightsCommand(args) {
+  const exportFlag = args.includes("--export");
+  const positionalArgs = args.filter((a) => !a.startsWith("--"));
+  const sprintId = positionalArgs[0];
+  const sprintR = await wrapAsync(async () => {
+    if (sprintId) return getSprint(sprintId);
+    return getCurrentSprintOrThrow();
+  }, ensureError);
+  if (!sprintR.ok) {
+    showError(sprintR.error.message);
+    return;
+  }
+  const sprint = sprintR.value;
+  const tasks = await getTasks(sprint.id);
+  printHeader(`Sprint Insights: ${sprint.name}`, icons.sprint);
+  const evaluatedTasks = tasks.filter((t) => t.evaluated);
+  if (evaluatedTasks.length === 0) {
+    log.info("No evaluation data found for this sprint.");
+    return;
+  }
+  const totalTasks = tasks.length;
+  const evaluatedCount = evaluatedTasks.length;
+  const withOutput = evaluatedTasks.filter((t) => t.evaluationOutput && t.evaluationOutput.trim().length > 0);
+  console.log(`  Tasks evaluated: ${colors.accent(String(evaluatedCount))} / ${String(totalTasks)} total`);
+  log.newline();
+  if (withOutput.length > 0) {
+    console.log(`  ${colors.accent("Evaluation output:")}`);
+    for (const task of withOutput) {
+      const output = task.evaluationOutput ?? "";
+      const truncated = output.length > 200 ? output.slice(0, 200) + "..." : output;
+      console.log(`    ${icons.bullet} ${colors.accent(task.name)}: ${colors.muted(truncated)}`);
+    }
+    log.newline();
+  }
+  console.log(`  ${colors.accent("Harness recommendations:")}`);
+  if (withOutput.length > 1) {
+    console.log(
+      `    ${icons.bullet} Consider reviewing evaluation failure patterns and updating CLAUDE.md with lessons learned.`
+    );
+  }
+  if (withOutput.length > 0) {
+    console.log(
+      `    ${icons.bullet} Run: ${colors.muted("ralphctl sprint insights --export")} to save details to $RALPHCTL_ROOT/insights/<sprint-id>.md`
+    );
+  }
+  log.newline();
+  if (exportFlag) {
+    await exportInsights(sprint, tasks);
+  }
+}
+async function exportInsights(sprint, tasks) {
+  const dir = join5(getDataDir(), "insights");
+  await ensureDir(dir);
+  const filePath = join5(dir, `${sprint.id}.md`);
+  const evaluatedCount = tasks.filter((t) => t.evaluated).length;
+  const lines = [
+    `# Sprint Insights: ${sprint.name}`,
+    "",
+    `**Date:** ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    `**Sprint ID:** ${sprint.id}`,
+    `**Tasks evaluated:** ${String(evaluatedCount)} / ${String(tasks.length)} total`,
+    "",
+    "## Evaluation Details"
+  ];
+  for (const task of tasks) {
+    lines.push("");
+    lines.push(`### ${task.name} (${task.id})`);
+    lines.push(`**Status:** ${task.status}`);
+    lines.push(`**Evaluated:** ${task.evaluated ? "yes" : "no"}`);
+    lines.push("");
+    lines.push(task.evaluationOutput ?? "No evaluation output");
+    lines.push("");
+    lines.push("---");
+  }
+  await writeFile2(filePath, lines.join("\n"), "utf-8");
+  log.success(`Insights exported to ${colors.accent(filePath)}`);
+}
+
 // src/commands/sprint/index.ts
 function registerSprintCommands(program2) {
   const sprint = program2.command("sprint").description("Manage sprints");
@@ -3974,7 +4056,13 @@ Examples:
   sprint.command("health").description("Check sprint health").action(async () => {
     await sprintHealthCommand();
   });
-  sprint.command("start [id]").description("Run automated implementation loop").option("-s, --session", "Interactive AI session (collaborate with your AI provider)").option("-t, --step", "Step through tasks with approval between each").option("-c, --count <n>", "Limit to N tasks").option("--no-commit", "Skip automatic git commit after each task completes").option("--concurrency <n>", "Max parallel tasks (default: auto based on unique repos)").option("--max-retries <n>", "Max rate-limit retries per task (default: 5)").option("--fail-fast", "Stop launching new tasks on first failure").option("-f, --force", "Skip precondition checks (e.g., unplanned tickets)").option("--refresh-check", "Force re-run check scripts even if they already ran this sprint").option("-b, --branch", "Create sprint branch (ralphctl/<sprint-id>) in all repos").option("--branch-name <name>", "Use a custom branch name for sprint execution").option("--max-budget-usd <amount>", "Max USD budget per AI task (Claude only)").option("--fallback-model <model>", "Fallback model when primary is overloaded (Claude only)").addHelpText(
+  sprint.command("insights [id]").description("Analyze evaluation results and suggest improvements").option("--export", "Export insights to $RALPHCTL_ROOT/insights/<sprint-id>.md").action(async (id, opts) => {
+    const args = [];
+    if (id) args.push(id);
+    if (opts?.export) args.push("--export");
+    await sprintInsightsCommand(args);
+  });
+  sprint.command("start [id]").description("Run automated implementation loop").option("-s, --session", "Interactive AI session (collaborate with your AI provider)").option("-t, --step", "Step through tasks with approval between each").option("-c, --count <n>", "Limit to N tasks").option("--no-commit", "Skip automatic git commit after each task completes").option("--concurrency <n>", "Max parallel tasks (default: auto based on unique repos)").option("--max-retries <n>", "Max rate-limit retries per task (default: 5)").option("--fail-fast", "Stop launching new tasks on first failure").option("-f, --force", "Skip precondition checks (e.g., unplanned tickets)").option("--refresh-check", "Force re-run check scripts even if they already ran this sprint").option("-b, --branch", "Create sprint branch (ralphctl/<sprint-id>) in all repos").option("--branch-name <name>", "Use a custom branch name for sprint execution").option("--max-budget-usd <amount>", "Max USD budget per AI task (Claude only)").option("--fallback-model <model>", "Fallback model when primary is overloaded (Claude only)").option("--max-turns <number>", "Max agentic turns per task (Claude only, default: 200)").addHelpText(
     "after",
     `
 Exit Codes:
@@ -4012,6 +4100,7 @@ Branch Management:
       if (opts?.branchName) args.push("--branch-name", opts.branchName);
       if (opts?.maxBudgetUsd) args.push("--max-budget-usd", opts.maxBudgetUsd);
       if (opts?.fallbackModel) args.push("--fallback-model", opts.fallbackModel);
+      if (opts?.maxTurns) args.push("--max-turns", opts.maxTurns);
       await sprintStartCommand(args);
     }
   );
@@ -4234,7 +4323,7 @@ Checks performed:
 // package.json
 var package_default = {
   name: "ralphctl",
-  version: "0.2.2",
+  version: "0.2.3",
   description: "Agent harness for long-running AI coding tasks \u2014 orchestrates Claude Code & GitHub Copilot across repositories",
   homepage: "https://github.com/lukas-grigis/ralphctl",
   type: "module",
@@ -4299,10 +4388,10 @@ var package_default = {
   },
   devDependencies: {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/tabtab": "^3.0.4",
-    "@vitest/coverage-v8": "^4.1.1",
-    eslint: "^10.1.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    eslint: "^10.2.0",
     "eslint-config-prettier": "^10.1.8",
     globals: "^17.4.0",
     husky: "^9.1.7",
@@ -4311,8 +4400,8 @@ var package_default = {
     tsup: "^8.5.1",
     tsx: "^4.21.0",
     typescript: "^5.9.3",
-    "typescript-eslint": "^8.57.2",
-    vitest: "^4.1.1"
+    "typescript-eslint": "^8.58.0",
+    vitest: "^4.1.2"
   },
   "lint-staged": {
     "*.ts": [
@@ -4356,7 +4445,7 @@ registerCompletionCommands(program);
 registerDoctorCommands(program);
 async function main() {
   if (process.env["COMP_CWORD"] && process.env["COMP_POINT"] && process.env["COMP_LINE"]) {
-    const { handleCompletionRequest } = await import("./handle-CCTBNAJZ.mjs");
+    const { handleCompletionRequest } = await import("./handle-2BACSJLR.mjs");
     if (await handleCompletionRequest(program)) return;
   }
   if (process.argv.length <= 2 || process.argv[2] === "interactive") {

package/dist/{create-DJHCP7LN.mjs → create-5MILNF7E.mjs}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   sprintCreateCommand
-} from "./chunk-XQHEKKDN.mjs";
-import "./chunk-KPTPKLXY.mjs";
+} from "./chunk-V4ZUDZCG.mjs";
+import "./chunk-ITRZMBLJ.mjs";
 import "./chunk-OEUJDSHY.mjs";
-import "./chunk-ZDEVRTGY.mjs";
+import "./chunk-GLDPHKEW.mjs";
 import "./chunk-EDJX7TT6.mjs";
 import "./chunk-QBXHAXHI.mjs";
 export {

package/dist/{handle-CCTBNAJZ.mjs → handle-2BACSJLR.mjs}

@@ -7,7 +7,7 @@ async function handleCompletionRequest(program) {
     return false;
   }
   const tabtab = (await import("tabtab")).default;
-  const { resolveCompletions } = await import("./resolver-L52KR4GY.mjs");
+  const { resolveCompletions } = await import("./resolver-CFY6DIOP.mjs");
   const tabEnv = tabtab.parseEnv(env);
   const completions = await resolveCompletions(program, {
     line: tabEnv.line,