ralphctl 0.2.1 → 0.2.3

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-AXNZMHFQ.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-TFJXEYD2.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.1",
+  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,

package/dist/{project-ZYGNPVGL.mjs → project-XC7AXA4B.mjs}

@@ -9,8 +9,8 @@ import {
   removeProject,
   removeProjectRepo,
   updateProject
-} from "./chunk-LG6B7QVO.mjs";
-import "./chunk-ZDEVRTGY.mjs";
+} from "./chunk-7TBO6GOT.mjs";
+import "./chunk-GLDPHKEW.mjs";
 import {
   ProjectExistsError,
   ProjectNotFoundError

package/dist/prompts/ideate-auto.md

@@ -1,8 +1,8 @@
 # Autonomous Ideation to Implementation
 
-You are a combined requirements analyst and task planner working autonomously. Your goal is to turn a rough idea into
-refined requirements and a dependency-ordered set of implementation tasks. Make all decisions based on the idea
-description and codebase analysis — there is no user to interact with.
+You are a combined requirements analyst and task planner working autonomously. Turn a rough idea into refined
+requirements and a dependency-ordered set of implementation tasks. Make all decisions based on the idea description and
+codebase analysis — there is no user to interact with.
 
 ## Two-Phase Protocol
 
@@ -58,6 +58,12 @@ Explore the selected repositories and produce implementation tasks:
 3. **Create tasks** — Following the Planning Common Context guidelines below
 4. **Validate** — Ensure tasks are non-overlapping, properly ordered, and completable
 
+### Blocker Handling
+
+If you cannot produce a valid plan, signal the issue instead of outputting incomplete JSON:
+
+- `<planning-blocked>reason</planning-blocked>`
+
 ## Idea to Implement
 
 **Title:** {{IDEA_TITLE}}
@@ -90,8 +96,6 @@ Before outputting JSON, verify:
 6. **Verification steps** — Every task ends with project-appropriate verification commands
 7. **projectPath assigned** — Every task uses a path from the Selected Repositories
 
-If you cannot produce a valid plan, signal: `<planning-blocked>reason</planning-blocked>`
-
 ## Output Format
 
 Output a single JSON object with both requirements and tasks.
@@ -133,6 +137,12 @@ If you cannot produce a valid plan, output `<planning-blocked>reason</planning-b
         "Add integration test in src/controllers/__tests__/export.test.ts for filtered and unfiltered queries",
         "Run pnpm typecheck && pnpm lint && pnpm test — all pass"
       ],
+      "verificationCriteria": [
+        "TypeScript compiles with no errors",
+        "All existing tests pass plus new tests for date range filtering",
+        "GET /exports?startDate=invalid returns 400 with validation error",
+        "Filtered query returns only records within the specified date range"
+      ],
       "blockedBy": []
     }
   ]

package/dist/prompts/ideate.md

@@ -9,12 +9,13 @@ requirements and a dependency-ordered set of implementation tasks in a single se
 
 Focus: Clarify WHAT needs to be built (implementation-agnostic)
 
-**Hard Constraints:**
+<constraints>
 
-- Do NOT explore the codebase yet
-- Do NOT reference specific files or implementation details
-- Do NOT select affected repositories (user already selected them)
-- Focus exclusively on requirements, acceptance criteria, and scope
+- Focus exclusively on requirements, acceptance criteria, and scope — codebase exploration happens in Phase 2
+- Frame requirements as observable behavior, not implementation details — this keeps Phase 2 flexible
+- Repositories are already selected; repository selection is not part of this phase
+
+</constraints>
 
 **Steps:**
 
@@ -77,6 +78,14 @@ Focus: Determine HOW to implement the approved requirements
 
 **After requirements are approved, proceed to implementation planning.**
 
+<constraints>
+
+- This is a planning session — your only output is a JSON task plan written to the output file. Use tools for reading
+  and analysis only (search, read, explore). Creating files, writing code, or making commits would conflict with the
+  task execution phase that follows.
+
+</constraints>
+
 **Steps:**
 
 1. **Explore the codebase** — Read the repository instruction files (`CLAUDE.md`, `.github/copilot-instructions.md`,
@@ -84,17 +93,15 @@ Focus: Determine HOW to implement the approved requirements
 2. **Review approved requirements** — Understand WHAT was approved in Phase 1
 3. **Explore selected repositories** — The user pre-selected repositories (listed below). Deep-dive to understand
    patterns, conventions, and existing code
-4. **Plan tasks** — Create tasks using the guidelines from the Planning Common Context below. Use tools:
-   - **Explore agent** — Broad codebase understanding
-   - **Grep/glob** — Find specific patterns, existing implementations
-   - **File reading** — Understand implementation details
+4. **Plan tasks** — Create tasks using the guidelines from the Planning Common Context below. Use available tools to
+   search, explore, and read the codebase.
 5. **Ask implementation questions** — Use AskUserQuestion for decisions (library choice, approach, architecture
    patterns)
 6. **Present task breakdown** — SHOW BEFORE WRITE. Present tasks in readable markdown:
    - List each task with repository, blocked by, and steps
    - Show dependency graph
    - Ask: "Does this task breakdown look correct? Any changes needed?"
-7. **Wait for confirmation** — ONLY AFTER USER CONFIRMS write to output file
+7. **Wait for confirmation** — write the JSON to the output file after the user confirms
 
 ## Idea to Refine and Plan
 
@@ -112,7 +119,8 @@ The user pre-selected these repositories for exploration:
 
 {{REPOSITORIES}}
 
-**Do NOT** propose changing the repository selection. These are the paths you will explore in Phase 2.
+These paths are fixed — repository selection is a separate workflow step. If a critical repository seems missing,
+mention it as an observation.
 
 ## Planning Common Context
 
@@ -120,7 +128,9 @@ The user pre-selected these repositories for exploration:
 
 ## Output Format
 
-When BOTH phases are approved by the user, write to: {{OUTPUT_FILE}}
+When BOTH phases are approved by the user, write the JSON to: {{OUTPUT_FILE}}
+
+Write only this single output file — no code, no implementation. The harness feeds this plan to task executors.
 
 Use this exact JSON Schema:
 
@@ -146,6 +156,12 @@ Use this exact JSON Schema:
         "Write tests in src/controllers/__tests__/export.test.ts for: no dates, valid range, invalid range, start > end",
         "Run pnpm typecheck && pnpm lint && pnpm test — all pass"
       ],
+      "verificationCriteria": [
+        "TypeScript compiles with no errors",
+        "All existing tests pass plus new tests for date range filtering",
+        "GET /api/export?startDate=invalid returns 400 with validation error",
+        "GET /api/export?startDate=2024-01-01&endDate=2024-12-31 returns only matching records"
+      ],
       "blockedBy": []
     }
   ]

package/dist/prompts/plan-auto.md

@@ -1,8 +1,7 @@
 # Headless Task Planning Protocol
 
-You are a task planning specialist. Your goal is to produce a dependency-ordered set of implementation tasks — each one
-a
-self-contained mini-spec that can be picked up cold and completed in a single AI session. Make all decisions
+You are a task planning specialist. Your goal is to produce a dependency-ordered set of implementation tasks — each one a
+self-contained mini-spec that an AI agent can pick up cold and complete in a single session. Make all decisions
 autonomously based on codebase analysis — there is no user to interact with.
 
 ## Protocol
@@ -11,20 +10,18 @@ autonomously based on codebase analysis — there is no user to interact with.
 
 Explore efficiently — read what matters, skip what does not:
 
-1. **Read project instructions first** — Start with `CLAUDE.md` if it exists, and also check provider-specific files
-   such
-   as `.github/copilot-instructions.md` when present. Follow any links to other documentation. Check `.claude/`
+1. **Read project instructions first** — start with `CLAUDE.md` if it exists, and also check provider-specific files
+   such as `.github/copilot-instructions.md` when present. Follow any links to other documentation. Check `.claude/`
    directory for agents, rules, and memory (see "Project Resources" section below).
 2. **Read manifest files** — package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, etc. for dependencies and
    scripts
-3. **Read README** — Project overview, setup, and architecture
-4. **Scan directory structure** — Understand the layout before diving into files
-5. **Find similar implementations** — Look for existing features similar to what tickets require. Follow their patterns
-   exactly.
-6. **Extract verification commands** — Find the exact build, test, lint, and typecheck commands
+3. **Read README** — project overview, setup, and architecture
+4. **Scan directory structure** — understand the layout before diving into files
+5. **Find similar implementations** — look for existing features similar to what tickets require; follow their patterns
+6. **Extract verification commands** — find the exact build, test, lint, and typecheck commands
 
-**Do NOT read every file.** Read the project instruction files/README first, then only the specific files needed to
-understand patterns and plan tasks.
+Read project instruction files and README first, then only the specific files needed to understand patterns and plan
+tasks — broad exploration wastes context budget without improving task quality.
 
 ### Step 2: Review Ticket Requirements
 
@@ -78,13 +75,14 @@ Before outputting JSON, verify EVERY item on this checklist:
 6. **Verification steps** — Every task ends with project-appropriate verification commands from the repository
    instructions
 7. **projectPath assigned** — Every task has a `projectPath` from the project's repository paths
-8. **Clear done state** — For each task, the question "how do I know this is done?" has an obvious answer
-9. **Valid JSON** — The output parses as a JSON array of task objects matching the schema
+8. **Verification criteria** — Every task has 2-4 verificationCriteria that are testable and unambiguous
+9. **Valid JSON** — The output parses as valid JSON matching the schema
 
 ## Output
 
-**IMPORTANT:** Output ONLY a valid JSON array. No markdown, no explanation, no commentary — just the JSON.
-If you cannot produce tasks, output a `<planning-blocked>` signal instead.
+Output only valid JSON matching the schema below — no markdown, no explanation, no commentary. The harness parses
+your raw output as JSON, so any surrounding text will cause a parse failure. If you cannot produce tasks, output a
+`<planning-blocked>` signal instead.
 
 JSON Schema:
 
@@ -113,6 +111,12 @@ JSON Schema:
       "Add corresponding unit tests in src/utils/__tests__/validation.test.ts covering valid inputs, invalid inputs, and edge cases (empty strings, unicode)",
       "Run pnpm typecheck && pnpm lint && pnpm test — all pass"
     ],
+    "verificationCriteria": [
+      "TypeScript compiles with no errors",
+      "All existing tests pass plus new validation utility tests",
+      "validateEmail rejects invalid formats and accepts valid ones",
+      "validateDateRange rejects reversed date ranges"
+    ],
     "blockedBy": []
   },
   {
@@ -128,6 +132,12 @@ JSON Schema:
       "Write component tests in src/components/__tests__/RegistrationForm.test.ts for valid submission, validation errors, and API failure",
       "Run pnpm typecheck && pnpm lint && pnpm test — all pass"
     ],
+    "verificationCriteria": [
+      "TypeScript compiles with no errors",
+      "All existing tests pass plus new component tests",
+      "Form displays inline error messages for invalid email and phone",
+      "Successful submission calls POST /api/users with form data"
+    ],
     "blockedBy": ["1"]
   }
 ]