ralphctl 0.2.4 → 0.2.5

package/README.md

@@ -99,6 +99,8 @@ Or run `ralphctl` with no arguments for an interactive menu that walks you throu
 - **Catch mistakes before they compound** — independent AI review after each task, iterating until quality passes or
   budget is exhausted
 - **Coordinate across repositories** — one sprint can span multiple repos with automatic dependency tracking
+- **Branch per sprint** — optional shared branch across every affected repo, with `sprint close --create-pr` to open
+  pull requests when you're done
 - **Run tasks in parallel** — one per repo, with rate-limit backoff and automatic session resume
 - **Separate the what from the how** — AI clarifies requirements first, then generates implementation tasks, with human
   approval gates
@@ -119,6 +121,15 @@ ralphctl config set provider copilot     # Use GitHub Copilot
 
 Auto-prompts on first AI command if not set. Both CLIs must be in your PATH and authenticated.
 
+Tune the generator-evaluator loop:
+
+```bash
+ralphctl config set evaluationIterations 2   # Up to 2 fix attempts per task (default: 1)
+ralphctl config set evaluationIterations 0   # Disable evaluation entirely
+```
+
+`sprint start --no-evaluate` skips evaluation for a single run without touching the global setting.
+
 <details>
 <summary>Provider differences</summary>
 
@@ -181,15 +192,16 @@ export RALPHCTL_ROOT="/path/to/custom/data-dir"
 
 ### Execution & Monitoring
 
-| Command                  | Description                       |
-| ------------------------ | --------------------------------- |
-| `ralphctl sprint start`  | Execute tasks with AI             |
-| `ralphctl sprint health` | Diagnose blockers and stale tasks |
-| `ralphctl status`        | Sprint overview with progress bar |
-| `ralphctl task list`     | List tasks in the current sprint  |
-| `ralphctl task next`     | Show the next unblocked task      |
-| `ralphctl sprint close`  | Close an active sprint            |
-| `ralphctl sprint delete` | Delete a sprint permanently       |
+| Command                    | Description                                            |
+| -------------------------- | ------------------------------------------------------ |
+| `ralphctl sprint start`    | Execute tasks with AI (`--branch` for a sprint branch) |
+| `ralphctl sprint health`   | Diagnose blockers and stale tasks                      |
+| `ralphctl sprint insights` | Analyze evaluator results across tasks                 |
+| `ralphctl status`          | Sprint overview with progress bar                      |
+| `ralphctl task list`       | List tasks in the current sprint                       |
+| `ralphctl task next`       | Show the next unblocked task                           |
+| `ralphctl sprint close`    | Close an active sprint (`--create-pr` for PRs)         |
+| `ralphctl sprint delete`   | Delete a sprint permanently                            |
 
 Run `ralphctl <command> --help` for details on any command.
 

package/dist/{chunk-U62BX47C.mjs → chunk-CSICORGV.mjs}

@@ -125,37 +125,91 @@ var promptDir = getPromptDir();
 function loadTemplate(name) {
   return readFileSync(join(promptDir, `${name}.md`), "utf-8");
 }
-function buildPlanPrompt(template, context, schema) {
-  const common = loadTemplate("plan-common");
-  return template.replace("{{COMMON}}", common).replace("{{CONTEXT}}", context).replace("{{SCHEMA}}", schema);
+function loadPartial(name) {
+  return loadTemplate(name).replace(/\s+$/, "");
 }
-function buildInteractivePrompt(context, outputFile, schema) {
-  const template = loadTemplate("plan-interactive");
-  return buildPlanPrompt(template, context, schema).replace("{{OUTPUT_FILE}}", outputFile);
+var UNREPLACED_TOKEN_RE = /\{\{[A-Z_]+\}\}/g;
+function composePrompt(template, substitutions) {
+  let result = template;
+  for (const [key, value] of Object.entries(substitutions)) {
+    result = result.replaceAll(`{{${key}}}`, value);
+  }
+  const remaining = result.match(UNREPLACED_TOKEN_RE);
+  if (remaining) {
+    throw new Error(`composePrompt: unreplaced placeholders: ${[...new Set(remaining)].join(", ")}`);
+  }
+  return result;
+}
+function buildPlanCommon(projectToolingSection) {
+  return composePrompt(loadPartial("plan-common"), {
+    PROJECT_TOOLING: projectToolingSection
+  });
+}
+function buildPlannerBase(projectToolingSection) {
+  return {
+    HARNESS_CONTEXT: loadPartial("harness-context"),
+    COMMON: buildPlanCommon(projectToolingSection),
+    VALIDATION: loadPartial("validation-checklist"),
+    SIGNALS: loadPartial("signals-planning")
+  };
+}
+function buildInteractivePrompt(context, outputFile, schema, projectToolingSection) {
+  return composePrompt(loadTemplate("plan-interactive"), {
+    ...buildPlannerBase(projectToolingSection),
+    CONTEXT: context,
+    OUTPUT_FILE: outputFile,
+    SCHEMA: schema
+  });
 }
-function buildAutoPrompt(context, schema) {
-  const template = loadTemplate("plan-auto");
-  return buildPlanPrompt(template, context, schema);
+function buildAutoPrompt(context, schema, projectToolingSection) {
+  return composePrompt(loadTemplate("plan-auto"), {
+    ...buildPlannerBase(projectToolingSection),
+    CONTEXT: context,
+    SCHEMA: schema
+  });
 }
 function buildTaskExecutionPrompt(progressFilePath, noCommit, contextFileName) {
   const template = loadTemplate("task-execution");
-  const commitStep = noCommit ? "" : "\n> **Before continuing:** Create a git commit with a descriptive message for the changes made.\n";
+  const commitStep = noCommit ? "" : "\n   - **Before continuing:** Create a git commit with a descriptive message for the changes made.";
   const commitConstraint = noCommit ? "" : "- **Must commit** \u2014 Create a git commit before signaling completion.\n";
-  return template.replaceAll("{{PROGRESS_FILE}}", progressFilePath).replaceAll("{{COMMIT_STEP}}", commitStep).replaceAll("{{COMMIT_CONSTRAINT}}", commitConstraint).replaceAll("{{CONTEXT_FILE}}", contextFileName);
+  return composePrompt(template, {
+    HARNESS_CONTEXT: loadPartial("harness-context"),
+    SIGNALS: loadPartial("signals-task"),
+    PROGRESS_FILE: progressFilePath,
+    COMMIT_STEP: commitStep,
+    COMMIT_CONSTRAINT: commitConstraint,
+    CONTEXT_FILE: contextFileName
+  });
 }
 function buildTicketRefinePrompt(ticketContent, outputFile, schema, issueContext = "") {
   const template = loadTemplate("ticket-refine");
-  return template.replace("{{TICKET}}", ticketContent).replace("{{OUTPUT_FILE}}", outputFile).replace("{{SCHEMA}}", schema).replace("{{ISSUE_CONTEXT}}", issueContext);
+  return composePrompt(template, {
+    TICKET: ticketContent,
+    OUTPUT_FILE: outputFile,
+    SCHEMA: schema,
+    ISSUE_CONTEXT: issueContext
+  });
 }
-function buildIdeatePrompt(ideaTitle, ideaDescription, projectName, repositories, outputFile, schema) {
-  const template = loadTemplate("ideate");
-  const common = loadTemplate("plan-common");
-  return template.replace("{{IDEA_TITLE}}", ideaTitle).replace("{{IDEA_DESCRIPTION}}", ideaDescription).replace("{{PROJECT_NAME}}", projectName).replace("{{REPOSITORIES}}", repositories).replace("{{OUTPUT_FILE}}", outputFile).replace("{{SCHEMA}}", schema).replace("{{COMMON}}", common);
+function buildIdeatePrompt(ideaTitle, ideaDescription, projectName, repositories, outputFile, schema, projectToolingSection) {
+  return composePrompt(loadTemplate("ideate"), {
+    ...buildPlannerBase(projectToolingSection),
+    IDEA_TITLE: ideaTitle,
+    IDEA_DESCRIPTION: ideaDescription,
+    PROJECT_NAME: projectName,
+    REPOSITORIES: repositories,
+    OUTPUT_FILE: outputFile,
+    SCHEMA: schema
+  });
 }
-function buildIdeateAutoPrompt(ideaTitle, ideaDescription, projectName, repositories, schema) {
-  const template = loadTemplate("ideate-auto");
-  const common = loadTemplate("plan-common");
-  return template.replace("{{IDEA_TITLE}}", ideaTitle).replace("{{IDEA_DESCRIPTION}}", ideaDescription).replace("{{PROJECT_NAME}}", projectName).replace("{{REPOSITORIES}}", repositories).replace("{{SCHEMA}}", schema).replace("{{COMMON}}", common);
+function buildIdeateAutoPrompt(ideaTitle, ideaDescription, projectName, repositories, schema, projectToolingSection) {
+  return composePrompt(loadTemplate("ideate-auto"), {
+    ...buildPlannerBase(projectToolingSection),
+    IDEA_TITLE: ideaTitle,
+    IDEA_DESCRIPTION: ideaDescription,
+    PROJECT_NAME: projectName,
+    REPOSITORIES: repositories,
+    SCHEMA: schema
+  });
 }
 function buildEvaluatorPrompt(ctx) {
   const template = loadTemplate("task-evaluation");
@@ -170,12 +224,27 @@ ${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("{{VERIFICATION_CRITERIA_SECTION}}", criteriaSection).replace("{{PROJECT_PATH}}", ctx.projectPath).replace("{{CHECK_SCRIPT_SECTION}}", checkSection).replace("{{PROJECT_TOOLING_SECTION}}", ctx.projectToolingSection);
+  return composePrompt(template, {
+    HARNESS_CONTEXT: loadPartial("harness-context"),
+    SIGNALS: loadPartial("signals-evaluation"),
+    TASK_NAME: ctx.taskName,
+    TASK_DESCRIPTION_SECTION: descriptionSection,
+    TASK_STEPS_SECTION: stepsSection,
+    VERIFICATION_CRITERIA_SECTION: criteriaSection,
+    PROJECT_PATH: ctx.projectPath,
+    CHECK_SCRIPT_SECTION: checkSection,
+    PROJECT_TOOLING: ctx.projectToolingSection
+  });
 }
 function buildEvaluationResumePrompt(ctx) {
   const template = loadTemplate("task-evaluation-resume");
   const commitInstruction = ctx.needsCommit ? "\n   - **Then commit the fix** with a descriptive message before signaling completion." : "";
-  return template.replace("{{CRITIQUE}}", ctx.critique).replace("{{COMMIT_INSTRUCTION}}", commitInstruction);
+  return composePrompt(template, {
+    HARNESS_CONTEXT: loadPartial("harness-context"),
+    SIGNALS: loadPartial("signals-task"),
+    CRITIQUE: ctx.critique,
+    COMMIT_INSTRUCTION: commitInstruction
+  });
 }
 
 // src/utils/requirements-export.ts
@@ -1060,7 +1129,7 @@ ${text}`;
 
 // src/commands/sprint/plan.ts
 import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 import { confirm as confirm3 } from "@inquirer/prompts";
 import { Result as Result5 } from "typescript-result";
 
@@ -1362,6 +1431,172 @@ function validateImportTasks(importTasks2, existingTasks, ticketIds) {
   return errors;
 }
 
+// src/ai/project-tooling.ts
+import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync2 } from "fs";
+import { join as join5 } from "path";
+var EMPTY_TOOLING = {
+  agents: [],
+  skills: [],
+  mcpServers: [],
+  hasClaudeMd: false,
+  hasAgentsMd: false,
+  hasCopilotInstructions: false
+};
+function safeListDir(path, predicate) {
+  try {
+    if (!existsSync2(path)) return [];
+    return readdirSync(path).filter(predicate).sort();
+  } catch {
+    return [];
+  }
+}
+var EVALUATOR_DENYLISTED_AGENTS = /* @__PURE__ */ new Set(["implementer", "planner"]);
+function detectAgents(projectPath) {
+  const agentsDir = join5(projectPath, ".claude", "agents");
+  return safeListDir(agentsDir, (name) => name.endsWith(".md")).map((name) => name.replace(/\.md$/, "")).filter((name) => !EVALUATOR_DENYLISTED_AGENTS.has(name));
+}
+function detectSkills(projectPath) {
+  const skillsDir = join5(projectPath, ".claude", "skills");
+  try {
+    if (!existsSync2(skillsDir)) return [];
+    return readdirSync(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+}
+function detectMcpServers(projectPath) {
+  const mcpFile = join5(projectPath, ".mcp.json");
+  if (!existsSync2(mcpFile)) return [];
+  try {
+    const raw = readFileSync2(mcpFile, "utf-8");
+    const parsed = JSON.parse(raw);
+    const servers = parsed.mcpServers;
+    if (!servers || typeof servers !== "object") return [];
+    return Object.keys(servers).sort();
+  } catch {
+    return [];
+  }
+}
+function detectProjectTooling(projectPath) {
+  if (!projectPath || !existsSync2(projectPath)) {
+    return EMPTY_TOOLING;
+  }
+  return {
+    agents: detectAgents(projectPath),
+    skills: detectSkills(projectPath),
+    mcpServers: detectMcpServers(projectPath),
+    hasClaudeMd: existsSync2(join5(projectPath, "CLAUDE.md")),
+    hasAgentsMd: existsSync2(join5(projectPath, "AGENTS.md")),
+    hasCopilotInstructions: existsSync2(join5(projectPath, ".github", "copilot-instructions.md"))
+  };
+}
+function detectProjectToolingAcrossPaths(projectPaths) {
+  if (projectPaths.length === 0) {
+    return EMPTY_TOOLING;
+  }
+  const agents = /* @__PURE__ */ new Set();
+  const skills = /* @__PURE__ */ new Set();
+  const mcpServers = /* @__PURE__ */ new Set();
+  let hasClaudeMd = false;
+  let hasAgentsMd = false;
+  let hasCopilotInstructions = false;
+  for (const path of projectPaths) {
+    const tooling = detectProjectTooling(path);
+    for (const agent of tooling.agents) agents.add(agent);
+    for (const skill of tooling.skills) skills.add(skill);
+    for (const server of tooling.mcpServers) mcpServers.add(server);
+    hasClaudeMd = hasClaudeMd || tooling.hasClaudeMd;
+    hasAgentsMd = hasAgentsMd || tooling.hasAgentsMd;
+    hasCopilotInstructions = hasCopilotInstructions || tooling.hasCopilotInstructions;
+  }
+  return {
+    agents: [...agents].sort(),
+    skills: [...skills].sort(),
+    mcpServers: [...mcpServers].sort(),
+    hasClaudeMd,
+    hasAgentsMd,
+    hasCopilotInstructions
+  };
+}
+function buildProjectToolingSection(paths) {
+  const tooling = typeof paths === "string" ? detectProjectTooling(paths) : detectProjectToolingAcrossPaths([...paths]);
+  return renderProjectToolingSection(tooling);
+}
+function renderProjectToolingSection(tooling) {
+  const hasAny = tooling.agents.length > 0 || tooling.skills.length > 0 || tooling.mcpServers.length > 0 || tooling.hasClaudeMd || tooling.hasAgentsMd || tooling.hasCopilotInstructions;
+  if (!hasAny) return "";
+  const lines = [];
+  lines.push("## Project Tooling (use these \u2014 they exist for a reason)");
+  lines.push("");
+  lines.push(
+    "This project ships with tooling that you should prefer over generic approaches. Verification and evaluation must adapt to the project\u2019s actual stack and the agents, skills, and MCP servers it has installed."
+  );
+  lines.push("");
+  if (tooling.agents.length > 0) {
+    lines.push("### Subagents available");
+    lines.push("");
+    lines.push("Delegate via the Task tool with `subagent_type=<name>` when the diff matches a specialty:");
+    for (const agent of tooling.agents) {
+      const hint = describeAgentHint(agent);
+      lines.push(`- \`${agent}\`${hint ? ` \u2014 ${hint}` : ""}`);
+    }
+    lines.push("");
+  }
+  if (tooling.skills.length > 0) {
+    lines.push("### Skills available");
+    lines.push("");
+    lines.push("Invoke via the Skill tool when the skill name matches the work in front of you:");
+    for (const skill of tooling.skills) {
+      lines.push(`- \`${skill}\``);
+    }
+    lines.push("");
+  }
+  if (tooling.mcpServers.length > 0) {
+    lines.push("### MCP servers available");
+    lines.push("");
+    lines.push(
+      "These give you tools beyond the filesystem. Use them to **interact with the running system**, not just read its source."
+    );
+    for (const server of tooling.mcpServers) {
+      const hint = describeMcpHint(server);
+      lines.push(`- \`${server}\`${hint ? ` \u2014 ${hint}` : ""}`);
+    }
+    lines.push("");
+  }
+  const instructionFiles = [];
+  if (tooling.hasClaudeMd) instructionFiles.push("`CLAUDE.md`");
+  if (tooling.hasAgentsMd) instructionFiles.push("`AGENTS.md`");
+  if (tooling.hasCopilotInstructions) instructionFiles.push("`.github/copilot-instructions.md`");
+  if (instructionFiles.length > 0) {
+    lines.push("### Project instructions");
+    lines.push("");
+    lines.push(
+      `Read ${instructionFiles.join(" / ")} for project-specific verification commands, conventions, and constraints. If no check script is configured, derive verification commands from these files (e.g. \`package.json\` scripts referenced there).`
+    );
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function describeAgentHint(name) {
+  const hints = {
+    auditor: "use for security-sensitive diffs (auth, input handling, file IO, secrets)",
+    reviewer: "use for general code-quality review of the diff",
+    tester: "use to assess test coverage and quality of new tests",
+    designer: "use for UI/UX/theming changes"
+  };
+  return hints[name] ?? null;
+}
+function describeMcpHint(name) {
+  const lower = name.toLowerCase();
+  if (lower.includes("playwright")) return "use for any UI/frontend task \u2014 click through the changed flow";
+  if (lower.includes("puppeteer")) return "use for browser automation on UI changes";
+  if (lower.includes("github")) return "use to inspect related PRs/issues for context";
+  if (lower.includes("postgres") || lower.includes("mysql") || lower.includes("sqlite")) {
+    return "use to verify database schema/migration changes against a real DB";
+  }
+  return null;
+}
+
 // src/interactive/selectors.ts
 import { checkbox, confirm as confirm2, input } from "@inquirer/prompts";
 async function selectProject(message = "Select project:") {
@@ -1775,7 +2010,7 @@ async function getSprintContext(sprintName, ticketsByProject, existingTasks) {
   return lines.join("\n");
 }
 async function invokeAiInteractive(prompt, repoPaths, planDir) {
-  const contextFile = join5(planDir, "planning-context.md");
+  const contextFile = join6(planDir, "planning-context.md");
   await writeFile3(contextFile, prompt, "utf-8");
   const provider = await getActiveProvider();
   const ticketCount = (prompt.match(/^####/gm) ?? []).length;
@@ -1943,8 +2178,9 @@ async function sprintPlanCommand(args) {
   const planDir = getPlanningDir(id);
   await mkdir2(planDir, { recursive: true });
   const ticketIds = new Set(sprint.tickets.map((t) => t.id));
+  const projectToolingSection = buildProjectToolingSection(selectedPaths);
   if (options.auto) {
-    const prompt = buildAutoPrompt(context, schema);
+    const prompt = buildAutoPrompt(context, schema, projectToolingSection);
     const spinner = createSpinner(`${providerName} is planning tasks...`);
     spinner.start();
     const outputR = await wrapAsync(() => invokeAiAuto(prompt, selectedPaths, planDir), ensureError);
@@ -2000,8 +2236,8 @@ async function sprintPlanCommand(args) {
     showSuccess(`Imported ${String(imported)}/${String(parsedTasks.length)} tasks.`);
     log.newline();
   } else {
-    const outputFile = join5(planDir, "tasks.json");
-    const prompt = buildInteractivePrompt(context, outputFile, schema);
+    const outputFile = join6(planDir, "tasks.json");
+    const prompt = buildInteractivePrompt(context, outputFile, schema, projectToolingSection);
     showInfo(`Starting interactive ${providerName} session...`);
     console.log(
       muted(
@@ -2327,12 +2563,12 @@ var RateLimitCoordinator = class {
 // src/ai/task-context.ts
 import { execSync } from "child_process";
 import { writeFile as writeFile4 } from "fs/promises";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 import { Result as Result7 } from "typescript-result";
 
 // src/ai/permissions.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { join as join6 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { join as join7 } from "path";
 import { homedir } from "os";
 import { Result as Result6 } from "typescript-result";
 function getProviderPermissions(projectPath, provider) {
@@ -2343,10 +2579,10 @@ function getProviderPermissions(projectPath, provider) {
   if (provider === "copilot") {
     return permissions;
   }
-  const projectSettingsPath = join6(projectPath, ".claude", "settings.local.json");
-  if (existsSync2(projectSettingsPath)) {
+  const projectSettingsPath = join7(projectPath, ".claude", "settings.local.json");
+  if (existsSync3(projectSettingsPath)) {
     const projectResult = Result6.try(() => {
-      const content = readFileSync2(projectSettingsPath, "utf-8");
+      const content = readFileSync3(projectSettingsPath, "utf-8");
       return JSON.parse(content);
     });
     if (projectResult.ok) {
@@ -2359,10 +2595,10 @@ function getProviderPermissions(projectPath, provider) {
       }
     }
   }
-  const userSettingsPath = join6(homedir(), ".claude", "settings.json");
-  if (existsSync2(userSettingsPath)) {
+  const userSettingsPath = join7(homedir(), ".claude", "settings.json");
+  if (existsSync3(userSettingsPath)) {
     const userResult = Result6.try(() => {
-      const content = readFileSync2(userSettingsPath, "utf-8");
+      const content = readFileSync3(userSettingsPath, "utf-8");
       return JSON.parse(content);
     });
     if (userResult.ok) {
@@ -2576,7 +2812,7 @@ function getContextFileName(sprintId, taskId) {
   return `.ralphctl-sprint-${sprintId}-task-${taskId}-context.md`;
 }
 async function writeTaskContextFile(projectPath, taskContent, instructions, sprintId, taskId) {
-  const contextFile = join7(projectPath, getContextFileName(sprintId, taskId));
+  const contextFile = join8(projectPath, getContextFileName(sprintId, taskId));
   const warning2 = `<!-- TEMPORARY FILE - DO NOT COMMIT -->
 <!-- This file is auto-generated by ralphctl for task execution context -->
 <!-- It will be automatically cleaned up after task completion -->
@@ -2643,140 +2879,6 @@ function runLifecycleHook(projectPath, script, event, timeoutOverrideMs) {
   return { passed: result.status === 0, output };
 }
 
-// src/ai/project-tooling.ts
-import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync3 } from "fs";
-import { join as join8 } from "path";
-var EMPTY_TOOLING = {
-  agents: [],
-  skills: [],
-  mcpServers: [],
-  hasClaudeMd: false,
-  hasAgentsMd: false,
-  hasCopilotInstructions: false
-};
-function safeListDir(path, predicate) {
-  try {
-    if (!existsSync3(path)) return [];
-    return readdirSync(path).filter(predicate).sort();
-  } catch {
-    return [];
-  }
-}
-var EVALUATOR_DENYLISTED_AGENTS = /* @__PURE__ */ new Set(["implementer", "planner"]);
-function detectAgents(projectPath) {
-  const agentsDir = join8(projectPath, ".claude", "agents");
-  return safeListDir(agentsDir, (name) => name.endsWith(".md")).map((name) => name.replace(/\.md$/, "")).filter((name) => !EVALUATOR_DENYLISTED_AGENTS.has(name));
-}
-function detectSkills(projectPath) {
-  const skillsDir = join8(projectPath, ".claude", "skills");
-  try {
-    if (!existsSync3(skillsDir)) return [];
-    return readdirSync(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
-  } catch {
-    return [];
-  }
-}
-function detectMcpServers(projectPath) {
-  const mcpFile = join8(projectPath, ".mcp.json");
-  if (!existsSync3(mcpFile)) return [];
-  try {
-    const raw = readFileSync3(mcpFile, "utf-8");
-    const parsed = JSON.parse(raw);
-    const servers = parsed.mcpServers;
-    if (!servers || typeof servers !== "object") return [];
-    return Object.keys(servers).sort();
-  } catch {
-    return [];
-  }
-}
-function detectProjectTooling(projectPath) {
-  if (!projectPath || !existsSync3(projectPath)) {
-    return EMPTY_TOOLING;
-  }
-  return {
-    agents: detectAgents(projectPath),
-    skills: detectSkills(projectPath),
-    mcpServers: detectMcpServers(projectPath),
-    hasClaudeMd: existsSync3(join8(projectPath, "CLAUDE.md")),
-    hasAgentsMd: existsSync3(join8(projectPath, "AGENTS.md")),
-    hasCopilotInstructions: existsSync3(join8(projectPath, ".github", "copilot-instructions.md"))
-  };
-}
-function renderProjectToolingSection(tooling) {
-  const hasAny = tooling.agents.length > 0 || tooling.skills.length > 0 || tooling.mcpServers.length > 0 || tooling.hasClaudeMd || tooling.hasAgentsMd || tooling.hasCopilotInstructions;
-  if (!hasAny) return "";
-  const lines = [];
-  lines.push("## Project Tooling (use these \u2014 they exist for a reason)");
-  lines.push("");
-  lines.push(
-    "This project ships with tooling that you should prefer over generic approaches. Verification and evaluation must adapt to the project\u2019s actual stack and the agents, skills, and MCP servers it has installed."
-  );
-  lines.push("");
-  if (tooling.agents.length > 0) {
-    lines.push("### Subagents available");
-    lines.push("");
-    lines.push("Delegate via the Task tool with `subagent_type=<name>` when the diff matches a specialty:");
-    for (const agent of tooling.agents) {
-      const hint = describeAgentHint(agent);
-      lines.push(`- \`${agent}\`${hint ? ` \u2014 ${hint}` : ""}`);
-    }
-    lines.push("");
-  }
-  if (tooling.skills.length > 0) {
-    lines.push("### Skills available");
-    lines.push("");
-    lines.push("Invoke via the Skill tool when the skill name matches the work in front of you:");
-    for (const skill of tooling.skills) {
-      lines.push(`- \`${skill}\``);
-    }
-    lines.push("");
-  }
-  if (tooling.mcpServers.length > 0) {
-    lines.push("### MCP servers available");
-    lines.push("");
-    lines.push(
-      "These give you tools beyond the filesystem. Use them to **interact with the running system**, not just read its source."
-    );
-    for (const server of tooling.mcpServers) {
-      const hint = describeMcpHint(server);
-      lines.push(`- \`${server}\`${hint ? ` \u2014 ${hint}` : ""}`);
-    }
-    lines.push("");
-  }
-  const instructionFiles = [];
-  if (tooling.hasClaudeMd) instructionFiles.push("`CLAUDE.md`");
-  if (tooling.hasAgentsMd) instructionFiles.push("`AGENTS.md`");
-  if (tooling.hasCopilotInstructions) instructionFiles.push("`.github/copilot-instructions.md`");
-  if (instructionFiles.length > 0) {
-    lines.push("### Project instructions");
-    lines.push("");
-    lines.push(
-      `Read ${instructionFiles.join(" / ")} for project-specific verification commands, conventions, and constraints. If no check script is configured, derive verification commands from these files (e.g. \`package.json\` scripts referenced there).`
-    );
-    lines.push("");
-  }
-  return lines.join("\n");
-}
-function describeAgentHint(name) {
-  const hints = {
-    auditor: "use for security-sensitive diffs (auth, input handling, file IO, secrets)",
-    reviewer: "use for general code-quality review of the diff",
-    tester: "use to assess test coverage and quality of new tests",
-    designer: "use for UI/UX/theming changes"
-  };
-  return hints[name] ?? null;
-}
-function describeMcpHint(name) {
-  const lower = name.toLowerCase();
-  if (lower.includes("playwright")) return "use for any UI/frontend task \u2014 click through the changed flow";
-  if (lower.includes("puppeteer")) return "use for browser automation on UI changes";
-  if (lower.includes("github")) return "use to inspect related PRs/issues for context";
-  if (lower.includes("postgres") || lower.includes("mysql") || lower.includes("sqlite")) {
-    return "use to verify database schema/migration changes against a real DB";
-  }
-  return null;
-}
-
 // src/ai/evaluator.ts
 var EVALUATOR_MAX_TURNS = 100;
 function getEvaluatorModel(generatorModel, provider) {
@@ -2831,8 +2933,7 @@ ${checkScript}
 \`\`\`
 
 If this script fails, the implementation fails regardless of code quality. Record the full output.` : null;
-  const tooling = detectProjectTooling(task.projectPath);
-  const projectToolingSection = renderProjectToolingSection(tooling);
+  const projectToolingSection = buildProjectToolingSection(task.projectPath);
   return {
     taskName: task.name,
     taskDescription: task.description ?? "",
@@ -4215,6 +4316,7 @@ export {
   parseRequirementsFile,
   runAiSession,
   sprintRefineCommand,
+  buildProjectToolingSection,
   getTaskImportSchema,
   parsePlanningBlocked,
   buildHeadlessAiRequest,

package/dist/cli.mjs

@@ -10,6 +10,7 @@ import {
   buildHeadlessAiRequest,
   buildIdeateAutoPrompt,
   buildIdeatePrompt,
+  buildProjectToolingSection,
   buildTicketRefinePrompt,
   exportRequirementsToMarkdown,
   extractJsonArray,
@@ -52,7 +53,7 @@ import {
   sprintStartCommand,
   updateTaskStatus,
   validateImportTasks
-} from "./chunk-U62BX47C.mjs";
+} from "./chunk-CSICORGV.mjs";
 import {
   escapableSelect
 } from "./chunk-7LZ6GOGN.mjs";
@@ -1338,8 +1339,16 @@ async function sprintIdeateCommand(args) {
   const schema = await getTaskImportSchema();
   const ideateDir = getIdeateDir(id, ticket.id);
   await mkdir(ideateDir, { recursive: true });
+  const projectToolingSection = buildProjectToolingSection(selectedPaths);
   if (options.auto) {
-    const prompt = buildIdeateAutoPrompt(ideaTitle, ideaDescription, projectName, repositoriesText, schema);
+    const prompt = buildIdeateAutoPrompt(
+      ideaTitle,
+      ideaDescription,
+      projectName,
+      repositoriesText,
+      schema,
+      projectToolingSection
+    );
     const spinner = createSpinner(`${providerName} is refining idea and planning tasks...`);
     spinner.start();
     const outputR = await wrapAsync(() => invokeAiAuto(prompt, selectedPaths, ideateDir), ensureError);
@@ -1419,7 +1428,15 @@ async function sprintIdeateCommand(args) {
     log.newline();
   } else {
     const outputFile = join(ideateDir, "output.json");
-    const prompt = buildIdeatePrompt(ideaTitle, ideaDescription, projectName, repositoriesText, outputFile, schema);
+    const prompt = buildIdeatePrompt(
+      ideaTitle,
+      ideaDescription,
+      projectName,
+      repositoriesText,
+      outputFile,
+      schema,
+      projectToolingSection
+    );
     showInfo(`Starting interactive ${providerName} session...`);
     console.log(muted(`  Exploring: ${selectedPaths.join(", ")}`));
     console.log(muted(`
@@ -3764,7 +3781,7 @@ async function interactiveMode() {
       continue;
     }
     if (command === "wizard") {
-      const { runWizard } = await import("./wizard-HWOH2HPV.mjs");
+      const { runWizard } = await import("./wizard-XZ7OGBCJ.mjs");
       await runWizard();
       continue;
     }
@@ -4323,7 +4340,7 @@ Checks performed:
 // package.json
 var package_default = {
   name: "ralphctl",
-  version: "0.2.4",
+  version: "0.2.5",
   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",

package/dist/prompts/harness-context.md

@@ -0,0 +1,5 @@
+<harness-context>
+Your context window will be automatically compacted as it approaches its limit, allowing you to continue working
+indefinitely. Do not stop early or rush completion due to token budget concerns — the harness manages session
+lifecycle. Focus on doing the work correctly within your designated role.
+</harness-context>

package/dist/prompts/ideate-auto.md

@@ -4,6 +4,10 @@ You are a combined requirements analyst and task planner working autonomously. T
 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.
 
+{{HARNESS_CONTEXT}}
+
+When finished, emit a signal from the `<signals>` block below.
+
 ## Two-Phase Protocol
 
 ### Phase 1: Refine Requirements (WHAT)
@@ -50,13 +54,34 @@ Analyze the idea and produce complete, implementation-agnostic requirements:
 
 ### Phase 2: Plan Implementation (HOW)
 
-Explore the selected repositories and produce implementation tasks:
+Phase 2 begins with reconnaissance — orient yourself in the codebase before generating tasks. Skip exploration and your
+plan will be guesswork.
+
+#### Step 0: Explore the Project
+
+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` and `AGENTS.md` when present. Follow any links to other documentation.
+   Check the `.claude/` directory for agents, rules, and memory (see "Project Resources" in the Planning Common
+   Context 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 the requirements call for; follow
+   their patterns
+6. **Extract verification commands** — find the exact build, test, lint, and typecheck commands from the repository
+   instruction files or project config
 
-1. **Explore codebase** — Read the repository instruction files (`CLAUDE.md`, `.github/copilot-instructions.md`, etc.)
-   when present, understand project structure, find patterns
-2. **Map requirements to implementation** — Determine which parts map to which repository
-3. **Create tasks** — Following the Planning Common Context guidelines below
-4. **Validate** — Ensure tasks are non-overlapping, properly ordered, and completable
+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 1: Generate the Plan
+
+1. **Map requirements to implementation** — Determine which parts of the approved requirements map to which repository
+2. **Create tasks** — Following the Planning Common Context guidelines below
+3. **Validate** — Ensure tasks are non-overlapping, properly ordered, and completable
 
 ### Blocker Handling
 
@@ -84,17 +109,7 @@ You have access to these repositories:
 
 {{COMMON}}
 
-## Pre-Output Validation
-
-Before outputting JSON, verify:
-
-1. **Requirements complete** — Problem statement, acceptance criteria, and scope boundaries are all present
-2. **No file overlap** — No two tasks modify the same files (or overlap is delineated in steps)
-3. **Correct order** — Foundations before dependents, all `blockedBy` references point to earlier tasks
-4. **Maximized parallelism** — Independent tasks do NOT block each other unnecessarily
-5. **Precise steps** — Every task has 3+ specific, actionable steps with file references
-6. **Verification steps** — Every task ends with project-appropriate verification commands
-7. **projectPath assigned** — Every task uses a path from the Selected Repositories
+{{VALIDATION}}
 
 ## Output Format
 
@@ -149,6 +164,8 @@ If you cannot produce a valid plan, output `<planning-blocked>reason</planning-b
 }
 ```
 
+{{SIGNALS}}
+
 ---
 
 Proceed autonomously: refine the idea into clear requirements, explore the codebase, then generate tasks. Output only

package/dist/prompts/ideate.md

@@ -3,6 +3,10 @@
 You are a combined requirements analyst and task planner. Your goal is to quickly turn a rough idea into refined
 requirements and a dependency-ordered set of implementation tasks in a single session.
 
+{{HARNESS_CONTEXT}}
+
+When finished, emit a signal from the `<signals>` block below.
+
 ## Two-Phase Protocol
 
 ### Phase 1: Refine Requirements (WHAT)
@@ -27,8 +31,16 @@ Focus: Clarify WHAT needs to be built (implementation-agnostic)
    - What are the acceptance criteria? (Given/When/Then format)
    - What edge cases and error states need handling?
    - What are the business constraints? (performance, compatibility, etc.)
-3. **Stop when ready** — Stop asking questions when the problem statement is clear, requirements have acceptance
-   criteria, scope boundaries are explicit, and major edge cases are addressed
+3. **Stop when ready** — Stop asking questions when ALL of these are true:
+   - The problem statement is clear and agreed upon
+   - Every functional requirement has at least one acceptance criterion
+   - Scope boundaries (in/out) are explicitly defined
+   - Major edge cases and error states are addressed
+   - No remaining ambiguity about what the feature should do — two developers reading these requirements would build
+     the same observable behavior
+
+   If the idea description already answers all of these, skip directly to Step 4.
+
 4. **Present requirements** — Show the complete refined requirements in readable markdown, then ask for approval using
    AskUserQuestion:
    ```
@@ -103,6 +115,8 @@ Focus: Determine HOW to implement the approved requirements
    - Ask: "Does this task breakdown look correct? Any changes needed?"
 7. **Wait for confirmation** — write the JSON to the output file after the user confirms
 
+{{VALIDATION}}
+
 ## Idea to Refine and Plan
 
 **Title:** {{IDEA_TITLE}}
@@ -176,6 +190,8 @@ Use this exact JSON Schema:
 - Tasks can reference each other via `id` and `blockedBy`
 - Only write after BOTH requirements AND task breakdown are approved
 
+{{SIGNALS}}
+
 ---
 
 Start with Phase 1: Read the idea above, identify what's clear vs ambiguous, then ask your first clarifying question.

package/dist/prompts/plan-auto.md

@@ -4,6 +4,10 @@ You are a task planning specialist. Your goal is to produce a dependency-ordered
 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.
 
+{{HARNESS_CONTEXT}}
+
+When finished, emit a signal from the `<signals>` block below.
+
 ## Protocol
 
 ### Step 1: Explore the Project
@@ -65,18 +69,7 @@ If you cannot produce a valid task breakdown, signal the issue instead of output
 
 ### Step 6: Pre-Output Validation
 
-Before outputting JSON, verify EVERY item on this checklist:
-
-1. **No file overlap** — No two tasks modify the same files (or overlap is explicitly delineated in steps)
-2. **Correct order** — Foundations before dependents
-3. **Valid dependencies** — All `blockedBy` references point to earlier tasks with real code dependencies
-4. **Maximized parallelism** — Independent tasks do NOT block each other unnecessarily
-5. **Precise steps** — Every task has 3+ specific, actionable steps with file references
-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. **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
+{{VALIDATION}}
 
 ## Output
 
@@ -142,3 +135,5 @@ JSON Schema:
   }
 ]
 ```
+
+{{SIGNALS}}

package/dist/prompts/plan-common.md

@@ -78,7 +78,7 @@ Aim for 2-4 criteria per task. Include at least one criterion that is computatio
 lint clean). For **UI/frontend tasks**, if the project has Playwright configured, add a browser-verifiable criterion —
 the evaluator will attempt visual verification using Playwright or browser tools when the project supports it.
 
-### Rules
+### Guidelines
 
 1. **Outcome-oriented** — Each task delivers a testable result
 2. **Merge create+use** — Never separate "create X" from "use X" — that is one task
@@ -108,7 +108,7 @@ the evaluator will attempt visual verification using Playwright or browser tools
 
 Tasks execute in dependency order — foundations before dependents.
 
-### Rules
+### Guidelines
 
 1. **Foundation first** — Shared utilities, types, schemas before anything that uses them
 2. **Declare all dependencies** — Use `blockedBy` to enforce order. Do not rely on array position alone.
@@ -205,3 +205,19 @@ commands.
 
 Start with an action verb (Add, Create, Update, Fix, Refactor, Remove, Migrate). Include the feature/concept, not files.
 Keep under 60 characters. Avoid vague verbs (Improve, Enhance, Handle).
+
+## Delegation to Available Tooling
+
+The "Project Tooling" section below (when present) lists subagents, skills, and MCP servers detected in the target
+repositories. Use these in your task planning:
+
+- **Surface tool delegation in task steps.** When a step's nature matches an available tool's specialization, write
+  the step so the executor knows to delegate. For example, if the tooling section lists a subagent specialized in
+  security review, security-sensitive task steps should explicitly recommend invoking it via the Task tool. Generic
+  pseudo-step: _"Delegate the final review of authentication changes to the `<name>` subagent via the Task tool."_
+- **Pull verification criteria from available tools.** UI tasks should add browser-verifiable criteria when a
+  Playwright or similar MCP is listed. Database tasks should reference DB-inspection MCPs when present.
+- **Do not invent tools.** Only reference tools that actually appear in the Project Tooling section. If the section is
+  empty or absent, omit delegation recommendations entirely — do not fabricate subagent names.
+
+{{PROJECT_TOOLING}}

package/dist/prompts/plan-interactive.md

@@ -4,6 +4,10 @@ You are a task planning specialist collaborating with the user. Your goal is to
 implementation tasks — each one a self-contained mini-spec that an AI agent can pick up cold and complete in a single
 session.
 
+{{HARNESS_CONTEXT}}
+
+When finished, emit a signal from the `<signals>` block below.
+
 ## Protocol
 
 ### Step 1: Explore the Project
@@ -47,7 +51,7 @@ selection.
 
 Using the confirmed repositories and your codebase exploration, create tasks. Use the tools available to you:
 
-Use available tools to search, explore, and read the codebase. When you need implementation decisions from the user, use AskUserQuestion:
+Use available tools to search, explore, and read the codebase. When you need implementation decisions from the user, use AskUserQuestion with:
 
 - **Recommended option first** with "(Recommended)" in the label
 - **2-4 options** with descriptions explaining trade-offs
@@ -109,18 +113,7 @@ If you encounter issues that prevent planning, communicate clearly:
 
 ### Step 7: Pre-Output Checklist
 
-Before writing the final JSON, verify every item:
-
-- [ ] Each task modifies 1-3 primary files (up to 5-7 total including tests)
-- [ ] No two tasks modify the same files without clear delineation in their steps
-- [ ] Tasks are ordered so foundations come before dependents
-- [ ] Every `blockedBy` reference points to an earlier task that produces code this task needs
-- [ ] Independent tasks do NOT block each other (parallelism maximized)
-- [ ] Every task has 3+ specific, actionable steps with file references
-- [ ] Steps reference concrete files and functions from the actual codebase
-- [ ] Each task includes verification using commands from the repository instruction files (if available)
-- [ ] Every task has 2-4 verificationCriteria that are testable and unambiguous
-- [ ] Every task has a `projectPath` from the project's repository paths
+{{VALIDATION}}
 
 ## Sprint Context
 
@@ -185,6 +178,8 @@ Use this exact JSON Schema:
 }
 ```
 
+{{SIGNALS}}
+
 ---
 
 Start by reading the repository instruction files and exploring the codebase, then discuss the approach with the user.

package/dist/prompts/signals-evaluation.md

@@ -0,0 +1,6 @@
+<signals>
+
+- `<evaluation-passed>` — All four dimensions pass; implementation accepted
+- `<evaluation-failed>critique</evaluation-failed>` — One or more dimensions fail; critique describes specific issues to fix
+
+</signals>

package/dist/prompts/signals-planning.md

@@ -0,0 +1,5 @@
+<signals>
+
+- `<planning-blocked>reason</planning-blocked>` — Cannot produce a valid plan; describe the blocker
+
+</signals>

package/dist/prompts/signals-task.md

@@ -0,0 +1,7 @@
+<signals>
+
+- `<task-verified>output</task-verified>` — Records verification results (required before completion)
+- `<task-complete>` — Marks task as done (ONLY after verified)
+- `<task-blocked>reason</task-blocked>` — Marks task as blocked (cannot proceed)
+
+</signals>

package/dist/prompts/task-evaluation-resume.md

@@ -1,22 +1,34 @@
 # Evaluator Feedback — Fix and Re-verify
 
-The independent code reviewer found issues with your implementation. Treat this as ground truth — do not argue with
-it. Read the critique carefully, fix each identified issue, then re-verify and signal completion.
+You are a task implementer responding to a code review. The independent reviewer's findings are
+authoritative — fix each issue precisely, re-verify, and signal completion.
+
+{{HARNESS_CONTEXT}}
+
+When finished, emit a signal from the `<signals>` block below.
+
+<constraints>
+
+- **Stay within scope** — fix only what the critique flags; do not expand the task or refactor neighboring code
+- **Fix, don't rewrite** — make minimal targeted changes; preserve the existing implementation structure where possible
+- **Don't argue with the critique** — treat reviewer findings as authoritative; if a finding is genuinely wrong, signal `<task-blocked>` instead of ignoring it
+
+</constraints>
 
 ## Critique
 
 {{CRITIQUE}}
 
-## What to do now
+## Fix Protocol
 
-1. **Fix each issue in the critique above.** Reference the file:line locations the reviewer cited. If a citation is
+1. **Address each issue** — Reference the file:line locations the reviewer cited. If a citation is
    wrong, find the actually-affected location and fix that.
-2. **Stay in scope.** If the critique calls out something outside your task scope, fix only what is within scope and
-   note the rest. Do not expand the task.
-3. **Re-run verification commands.** Run the project's check script (or the equivalent verification commands) and
-   confirm they pass.{{COMMIT_INSTRUCTION}}
-4. **Re-output verification results** wrapped in `<task-verified>...</task-verified>`.
-5. **Signal completion** with `<task-complete>` ONLY after all of the above pass.
-
-If the critique is unfixable (e.g. it asks for something that contradicts the spec, or requires changes you cannot
-make), signal `<task-blocked>reason</task-blocked>` instead of completing.
+2. **Re-run verification** — Run the project's check script (or the equivalent verification
+   commands) and confirm they pass.{{COMMIT_INSTRUCTION}}
+3. **Output verification results** — Wrap output in `<task-verified>...</task-verified>`.
+4. **Signal completion** — Output `<task-complete>` ONLY after all steps above pass.
+
+If an issue is unfixable (contradicts the spec, or requires changes outside your scope), signal
+`<task-blocked>reason</task-blocked>` instead of completing.
+
+{{SIGNALS}}

package/dist/prompts/task-evaluation.md

@@ -3,6 +3,10 @@
 You are an independent code reviewer evaluating whether an implementation satisfies its specification. Assume problems
 exist until you prove otherwise through investigation.
 
+{{HARNESS_CONTEXT}}
+
+When finished, emit a signal from the `<signals>` block below.
+
 <task-specification>
 
 These verification criteria are the pre-agreed definition of "done" — your primary grading rubric.
@@ -22,7 +26,7 @@ You are working in this project directory:
 {{PROJECT_PATH}}
 ```
 
-{{PROJECT_TOOLING_SECTION}}
+{{PROJECT_TOOLING}}
 
 ### Phase 1: Computational Verification (run before reasoning)
 
@@ -180,3 +184,5 @@ Each issue must reference which dimension it violates.]
 >    query: `WHERE name LIKE $1` with `%${query}%` as parameter.
 
 Be direct and specific — point to files, lines, and concrete problems.
+
+{{SIGNALS}}

package/dist/prompts/task-execution.md

@@ -6,13 +6,11 @@ completion. Do not expand scope beyond what the declared steps specify.
 Implement the task described in {{CONTEXT_FILE}}. The task directive and implementation steps are at the top of that
 file.
 
-<harness-context>
-Your context window will be automatically compacted as it approaches its limit, allowing you to continue working
-indefinitely. Do not stop tasks early or rush completion due to token budget concerns. The harness manages session
-lifecycle — focus on doing the work correctly.
-</harness-context>
+{{HARNESS_CONTEXT}}
 
-<rules>
+When finished, emit a signal from the `<signals>` block below.
+
+<constraints>
 
 - **One task only** — complete this task, then stop. The harness manages task sequencing; continuing to the next task
   would conflict with parallel execution.
@@ -29,7 +27,7 @@ lifecycle — focus on doing the work correctly.
 - **Leave task definitions unchanged** — the task name, description, steps, and other task files are immutable.
   {{COMMIT_CONSTRAINT}}
 
-</rules>
+</constraints>
 
 ## Phase 1: Reconnaissance (feedforward — understand before acting)
 
@@ -77,9 +75,9 @@ Proceed to Phase 2 once all reconnaissance steps pass.
    - If a step is unclear, attempt reasonable interpretation before marking blocked
    - If steps seem incomplete relative to ticket requirements, signal `<task-blocked>` rather than improvising —
      the planner may have intentionally scoped them this way to avoid conflicts
-3. **Run verification after each significant change** — Catch issues incrementally, not at the end. Run the check script
-   or relevant test commands after each meaningful code change. This is cheaper than debugging a pile of errors at the
-   end.
+3. **Smoke-test as you go** — Run relevant test or typecheck commands after each meaningful code change to catch issues
+   early. This is incremental sanity-checking, not the final gate. **The authoritative gate is Phase 3 step 2 below:
+   the full check script runs there and must pass.**
 
 ## Phase 3: Completion
 
@@ -88,8 +86,7 @@ Complete these steps IN ORDER:
 1. **Confirm all steps done** — Every task step has been completed
 2. **Run ALL verification commands** — Execute every verification command (see Check Script section in the context file
    or project instructions). Fix any failures before proceeding. The harness runs the check script as a post-task
-   gate — your task is not marked done unless it passes.
-   {{COMMIT_STEP}}
+   gate — your task is not marked done unless it passes.{{COMMIT_STEP}}
 3. **Update progress file** — Append to {{PROGRESS_FILE}} using this format:
 
    ```markdown
@@ -175,10 +172,4 @@ Signal `<task-blocked>Missing dependency: [what and which task]</task-blocked>`.
 Follow project patterns over steps if they conflict. If steps seem incomplete relative to requirements:
 `<task-blocked>Steps incomplete: [what appears missing]</task-blocked>`.
 
-<signals>
-
-- `<task-verified>output</task-verified>` — Records verification results (required before completion)
-- `<task-complete>` — Marks task as done (ONLY after verified)
-- `<task-blocked>reason</task-blocked>` — Marks task as blocked (cannot proceed)
-
-</signals>
+{{SIGNALS}}

package/dist/prompts/validation-checklist.md

@@ -0,0 +1,14 @@
+## Pre-Output Validation
+
+Before writing the JSON output, verify EVERY item:
+
+1. **Requirements complete** — Problem statement, acceptance criteria, and scope boundaries are all present (when applicable)
+2. **No file overlap** — No two tasks modify the same files (or overlap is explicitly delineated in steps)
+3. **Foundations before dependents** — Tasks are ordered so prerequisites come first
+4. **Valid dependencies** — All `blockedBy` references point to earlier tasks with real code dependencies
+5. **Maximized parallelism** — Independent tasks do NOT block each other unnecessarily
+6. **Precise steps** — Every task has 3+ specific, actionable steps with file references
+7. **Verification steps** — Every task ends with project-appropriate verification commands
+8. **`projectPath` assigned** — Every task uses a path from the available repositories
+9. **Verification criteria** — Every task has 2-4 `verificationCriteria` that are testable and unambiguous
+10. **Output format compliance** — Output matches the schema exactly: no markdown fences around JSON, no commentary, no surrounding text. The harness parses raw output as JSON.

package/dist/{wizard-HWOH2HPV.mjs → wizard-XZ7OGBCJ.mjs}

@@ -3,7 +3,7 @@ import {
   sprintPlanCommand,
   sprintRefineCommand,
   sprintStartCommand
-} from "./chunk-U62BX47C.mjs";
+} from "./chunk-CSICORGV.mjs";
 import "./chunk-7LZ6GOGN.mjs";
 import {
   sprintCreateCommand

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphctl",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Agent harness for long-running AI coding tasks — orchestrates Claude Code & GitHub Copilot across repositories",
   "homepage": "https://github.com/lukas-grigis/ralphctl",
   "type": "module",