@ilya-lesikov/pi-pi 0.1.0

package/extensions/orchestrator/phases/brainstorm.ts

@@ -0,0 +1,273 @@
+import { readFileSync, existsSync, mkdirSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { PiPiConfig } from "../config.js";
+import { registerAgentDefinitions, spawnViaRpc, waitForCompletion } from "../agents/registry.js";
+import { createBrainstormReviewerAgent } from "../agents/brainstorm-reviewer.js";
+import type { TaskType } from "../state.js";
+
+export function brainstormSystemPrompt(taskType: TaskType, taskDescription: string, taskDir: string): string {
+  if (taskType === "debug") {
+    return [
+      "[PI-PI — DEBUG PHASE]",
+      `Problem: ${taskDescription}`,
+      "",
+    "Read-only diagnosis mode.",
+    "",
+    "# FORBIDDEN — do NOT do any of these:",
+    "- Do NOT modify project source code (no write or edit tools on project files)",
+    "- Do NOT create or modify any files outside the task directory",
+    "- Do NOT implement fixes — only diagnose and recommend",
+    "- If the user asks you to implement a fix or start coding — call pp_phase_complete instead. It will offer \"Implement a fix\" as an option. Do NOT implement directly in this session.",
+    "",
+    "# Your job:",
+    "1. Clarify the problem with the user if needed",
+    '2. Spawn explore subagents via Agent(subagent_type="Explore", ...) for codebase research',
+    "3. Use bash to run commands, check logs, reproduce issues",
+    "4. Use tools to trace the bug:",
+    "   - cbm_search/cbm_search_code: find relevant code by concept or text",
+    "   - lsp goToDefinition, findReferences, hover: precise navigation and type info",
+    "   - lsp goToImplementation: check interface implementors",
+    "   - lsp diagnostics: find type errors",
+    "   - cbm_trace: trace call chains to/from suspect functions",
+    "   - ast_search: find structural patterns (e.g. error handling, goroutines)",
+      "",
+      "IMPORTANT: Always specify subagent_type. Use Explore for codebase, Librarian for external docs.",
+      "",
+      "Produce two files:",
+      `- ${taskDir}/USER_REQUEST.md — the fix request. MUST follow this exact structure:`,
+      "  # User Request",
+      "  <1-3 sentence distillation of the fix needed>",
+      "  ## Problem",
+      "  <What's broken, from the user's perspective / your diagnosis>",
+      "  ## Constraints",
+      "  <User-stated boundaries or critical constraints discovered during diagnosis>",
+      `- ${taskDir}/RESEARCH.md — MUST follow this exact structure:`,
+      "  ## Affected Code",
+      "  <file:symbol — one-line role, per line>",
+      "  ## Architecture Context",
+      "  <Dense bullets. How affected pieces connect. Sub-group by subsystem for complex tasks.>",
+      "  ## Constraints & Edge Cases",
+      "  - MUST: <hard requirements discovered from code>",
+      "  - RISK: <things that could break>",
+      "  ## Open Questions",
+      "  <Unresolved items needing user input. Omit section if none.>",
+      "",
+      "These files are validated programmatically. Missing sections or unexpected sections will be rejected.",
+      "",
+      "# Optional: focused analysis artifacts",
+      `You may also write additional analysis files to ${taskDir}/artifacts/<name>.md`,
+      "for deep dives on specific topics (e.g. architecture analysis, API comparison, risk assessment).",
+      "Each artifact must start with # <Title>. Content is freeform. These are reviewed alongside USER_REQUEST.md and RESEARCH.md.",
+      "Do NOT duplicate content already in RESEARCH.md — artifacts are for supplementary deep dives.",
+      "",
+      "When both required files are complete, call pp_phase_complete with a brief summary.",
+    ].join("\n");
+  }
+
+  if (taskType === "brainstorm") {
+    return [
+      "[PI-PI — BRAINSTORM]",
+      `Topic: ${taskDescription}`,
+      "",
+      "# This is a conversation, not a task.",
+      "Your primary job is to TALK WITH THE USER. Explore ideas, analyze tradeoffs, answer questions, discuss approaches.",
+      "Do NOT rush to produce artifacts or finish. Stay in the conversation until the user is satisfied.",
+      "",
+      "# How to work:",
+      "- Discuss the topic with the user. Ask clarifying questions. Propose approaches. Analyze tradeoffs.",
+      '- Spawn subagents for research: Agent(subagent_type="Explore", ...) for codebase, Agent(subagent_type="Librarian", ...) for external docs.',
+      "  IMPORTANT: Always specify subagent_type. Do NOT omit it.",
+      "- Use tools directly for quick lookups (cbm_search, lsp, ast_search, grep, etc.)",
+      "- Present findings to the user and discuss them. Don't just dump raw results.",
+      "- Do NOT modify project source code.",
+      "",
+      "# When to finish:",
+      "Do NOT call pp_phase_complete on your own. The user will tell you when they're done,",
+      "or use /pp to advance. Keep the conversation going until then.",
+      "If the user asks you to implement, write code, or start building — tell them to use /pp which will offer \"Start implementation\" as an option. Do NOT implement directly in this session.",
+      "",
+      "# Optional artifacts (only when the conversation naturally produces them):",
+      "If the discussion leads to a clear action plan or the user asks you to capture conclusions,",
+      "write them to:",
+      `- ${taskDir}/USER_REQUEST.md — MUST use structure: # User Request, ## Problem, ## Constraints`,
+      `- ${taskDir}/RESEARCH.md — MUST use structure: ## Affected Code, ## Architecture Context, ## Constraints & Edge Cases, ## Open Questions (optional)`,
+      "These files are validated. Missing or unexpected sections will be rejected.",
+      "Do NOT create these files preemptively. Only write them when there's substance to capture.",
+      "",
+      "# Optional: focused analysis artifacts",
+      `You may also write additional analysis files to ${taskDir}/artifacts/<name>.md`,
+      "for deep dives on specific topics (e.g. architecture analysis, API comparison, risk assessment).",
+      "Each artifact must start with # <Title>. Content is freeform. These are reviewed alongside USER_REQUEST.md and RESEARCH.md.",
+      "Do NOT duplicate content already in RESEARCH.md — artifacts are for supplementary deep dives.",
+      "",
+      "Do NOT modify any files except .md files in the task directory.",
+    ].join("\n");
+  }
+
+  return [
+    "[PI-PI — BRAINSTORM PHASE]",
+    `Task: ${taskDescription}`,
+    "",
+    "Your job is to produce USER_REQUEST.md and RESEARCH.md — complete enough that",
+    "downstream agents can work without re-exploring the codebase or re-interviewing the user.",
+    "",
+    "# FORBIDDEN — do NOT do any of these:",
+    "- Do NOT modify project source code (no write or edit tools on project files)",
+    "- Do NOT create or modify any files outside the task directory",
+    "- Do NOT start implementing — only research and document",
+    "- If the user asks you to implement or start coding — tell them to use /pp which will offer phase advancement. Do NOT implement directly in this session.",
+    "",
+    "# Steps:",
+    "1. Clarify requirements with the user if anything is ambiguous",
+    '2. Spawn explore subagents via Agent(subagent_type="Explore", ...) for codebase research',
+    '3. Spawn librarian subagents via Agent(subagent_type="Librarian", ...) for external docs/library research',
+    "4. Use tools to understand code structure:",
+    "   - cbm_search: natural-language search across all symbols",
+    "   - cbm_search_code: graph-augmented grep (deduplicates into functions)",
+    "   - lsp documentSymbol, goToDefinition, findReferences, goToImplementation, hover",
+    "   - cbm_trace: trace call chains for dependency understanding",
+    "   - ast_search: find structural patterns across the codebase",
+    "5. Ask the user follow-up questions as needed",
+    "6. Write findings into RESEARCH.md as results come back — don't wait for all subagents",
+    "",
+    "IMPORTANT: Always specify subagent_type. Use Explore for codebase, Librarian for external docs.",
+    "",
+    "Produce two files:",
+    `- ${taskDir}/USER_REQUEST.md — MUST follow this exact structure:`,
+    "  # User Request",
+    "  <1-3 sentence distillation of what the user wants>",
+    "  ## Problem",
+    "  <What's broken / what's missing, in the user's words. Issue link if provided.>",
+    "  ## Constraints",
+    "  <Boundaries the user explicitly stated. Only user-stated info, no agent findings.>",
+    `- ${taskDir}/RESEARCH.md — MUST follow this exact structure:`,
+    "  ## Affected Code",
+    "  <file:symbol — one-line role, per line>",
+    "  ## Architecture Context",
+    "  <Dense bullets. How affected pieces connect. Sub-group by subsystem for complex tasks.>",
+    "  ## Constraints & Edge Cases",
+    "  - MUST: <hard requirements discovered from code>",
+    "  - RISK: <things that could break>",
+    "  ## Open Questions",
+    "  <Unresolved items needing user input. Omit section if none.>",
+    "",
+    "These files are validated programmatically. Missing sections or unexpected sections will be rejected.",
+    "",
+    "# Optional: focused analysis artifacts",
+    `You may also write additional analysis files to ${taskDir}/artifacts/<name>.md`,
+    "for deep dives on specific topics (e.g. architecture analysis, API comparison, risk assessment).",
+    "Each artifact must start with # <Title>. Content is freeform. These are reviewed alongside USER_REQUEST.md and RESEARCH.md.",
+    "Do NOT duplicate content already in RESEARCH.md — artifacts are for supplementary deep dives.",
+    "",
+    "Do NOT modify any files except .md files in the task directory.",
+    "When both files are produced and thorough, call pp_phase_complete with a brief summary.",
+  ].join("\n");
+}
+
+export async function spawnBrainstormReviewers(
+  pi: ExtensionAPI,
+  cwd: string,
+  taskDir: string,
+  taskId: string,
+  config: PiPiConfig,
+  round: number,
+): Promise<{ spawned: number; files: string[]; agentIds: string[]; failedVariants: string[] }> {
+  const urPath = join(taskDir, "USER_REQUEST.md");
+  const resPath = join(taskDir, "RESEARCH.md");
+  if (!existsSync(urPath) || !existsSync(resPath)) return { spawned: 0, files: [], agentIds: [], failedVariants: [] };
+
+  const userRequest = readFileSync(urPath, "utf-8");
+  const research = readFileSync(resPath, "utf-8");
+
+  const artifactsDir = join(taskDir, "artifacts");
+  const artifacts: { name: string; content: string }[] = [];
+  if (existsSync(artifactsDir)) {
+    for (const f of readdirSync(artifactsDir).filter((f) => f.endsWith(".md")).sort()) {
+      artifacts.push({ name: `artifacts/${f}`, content: readFileSync(join(artifactsDir, f), "utf-8") });
+    }
+  }
+
+  const reviewsDir = join(taskDir, "brainstorm-reviews");
+  if (!existsSync(reviewsDir)) {
+    mkdirSync(reviewsDir, { recursive: true });
+  }
+
+  const timestamp = Math.floor(Date.now() / 1000);
+  const enabledVariants = Object.entries(config.brainstormReviewers).filter(([, v]) => v.enabled);
+  const reviewFiles: string[] = [];
+  const agentIds: string[] = [];
+  const failedVariants: string[] = [];
+  const results: Promise<void>[] = [];
+
+  for (const [variant] of enabledVariants) {
+    const outputPath = join(reviewsDir, `${timestamp}_${variant}_round-${round}.md`);
+    reviewFiles.push(outputPath);
+    const agent = createBrainstormReviewerAgent(variant, config, { userRequest, research, artifacts: artifacts.length > 0 ? artifacts : undefined }, outputPath);
+
+    registerAgentDefinitions(pi, [{ type: "brainstorm_reviewer", variant, ...agent }]);
+
+    results.push(
+      (async () => {
+        try {
+          const { id } = await spawnViaRpc(pi, `brainstorm_reviewer_${variant}`, "Begin brainstorm artifact review.", {
+            description: `Brainstorm reviewer (${variant})`,
+            validateCompletion: () => {
+              if (!existsSync(outputPath) || statSync(outputPath).size === 0) {
+                return `You finished without writing your review file. Write your review to: ${outputPath}`;
+              }
+            },
+          });
+          agentIds.push(id);
+          await waitForCompletion(pi, id);
+        } catch (err: any) {
+          failedVariants.push(variant);
+          pi.sendMessage(
+            {
+              customType: "pp-brainstorm-reviewer-error",
+              content: `Brainstorm reviewer variant "${variant}" failed: ${err.message}`,
+              display: true,
+            },
+            { deliverAs: "steer" },
+          );
+        }
+      })(),
+    );
+  }
+
+  await Promise.allSettled(results);
+
+  const reviewOutputFiles = existsSync(reviewsDir)
+    ? readdirSync(reviewsDir).filter((f) => f.includes(`round-${round}`) && f.endsWith(".md"))
+    : [];
+
+  if (reviewOutputFiles.length > 0) {
+    pi.sendMessage(
+      {
+        customType: "pp-brainstorm-reviews-done",
+        content: [
+          `${reviewOutputFiles.length} brainstorm reviewer(s) completed (round ${round}). Reviews in ${reviewsDir}:`,
+          ...reviewOutputFiles.map((f) => `  - ${f}`),
+          "",
+          "Read all reviews and update USER_REQUEST.md and RESEARCH.md if needed.",
+        ].join("\n"),
+        display: true,
+      },
+      { deliverAs: "steer" },
+    );
+  } else if (enabledVariants.length > 0) {
+    pi.sendMessage(
+      {
+        customType: "pp-brainstorm-reviews-error",
+        content: [
+          `All brainstorm reviewer variants failed (round ${round}) — no reviews were produced.`,
+          "Proceeding without automatic brainstorm review.",
+        ].join("\n"),
+        display: true,
+      },
+      { deliverAs: "steer" },
+    );
+  }
+
+  return { spawned: enabledVariants.length, files: reviewFiles, agentIds, failedVariants };
+}

package/extensions/orchestrator/phases/implementation.ts

@@ -0,0 +1,40 @@
+export function implementationSystemPrompt(taskDir: string): string {
+  return [
+    "[PI-PI — IMPLEMENT PHASE]",
+    "",
+    "The plan has been approved. Implement it.",
+    "",
+    "# FORBIDDEN — do NOT do any of these:",
+    "- Do NOT skip plan items without the user's approval",
+    "",
+    "USER_REQUEST.md, RESEARCH.md, and the synthesized plan are already provided in your context above — do NOT re-read them from disk.",
+    "",
+    "# Instructions:",
+    "1. Review the synthesized plan in your context",
+    "2. Implement each item in order",
+    "3. Check off items in the plan (change - [ ] to - [x]) as you complete them",
+    "4. After editing files, run lsp diagnostics to check for errors; use lsp codeActions for auto-fixes",
+    "5. Before modifying code, understand it first:",
+    "   - cbm_search/cbm_search_code: find relevant functions and their context",
+    "   - lsp goToDefinition, findReferences, hover: precise navigation",
+    "   - lsp goToImplementation: check interface implementors",
+    "   - lsp incomingCalls/outgoingCalls: understand call chains",
+    "   - cbm_trace: trace dependencies across the codebase",
+    "   - ast_search: find structural patterns (e.g. error handling conventions)",
+    "6. After completing changes, run cbm_changes to verify blast radius",
+    '7. For parallelizable, self-contained subtasks, delegate via Agent(subagent_type="Task", ...)',
+    '8. For codebase research, use Agent(subagent_type="Explore", ...)',
+    '9. For external docs research, use Agent(subagent_type="Librarian", ...)',
+    "",
+    "If a fix fails 3 times, STOP and re-plan the approach — do not keep pushing.",
+    "",
+    "# Commits:",
+    "After completing a logical unit of work (a plan item, a bug fix, a test), call pp_commit",
+    "with a descriptive message (what changed and why). Don't batch all changes into one commit.",
+    "",
+    "Constraints:",
+    "- Fix issues found by lsp diagnostics before moving on",
+    "",
+    "When all plan items are checked off, call pp_phase_complete with a brief summary.",
+  ].join("\n");
+}

package/extensions/orchestrator/phases/machine.test.ts

@@ -0,0 +1,293 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import { canTransition, nextPhase, phasePipeline, validateExitCriteria } from "./machine.js";
+
+const tempDirs: string[] = [];
+
+const VALID_USER_REQUEST = `# User Request
+Fix the auth bug.
+
+## Problem
+Auth tokens expire incorrectly.
+
+## Constraints
+Must be backward compatible.
+`;
+
+const VALID_RESEARCH = `## Affected Code
+src/auth.ts:validateToken — validates JWT tokens
+
+## Architecture Context
+- Auth middleware calls validateToken on every request
+
+## Constraints & Edge Cases
+- MUST: Existing tokens must remain valid
+- RISK: Token refresh flow may break
+`;
+
+function makeValidPlan(checklist: string[]): string {
+  return `# Plan
+
+## Scope
+Fix token validation in auth middleware. Does not change token format.
+
+## Checklist
+${checklist.join("\n")}
+`;
+}
+
+function makeTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "pi-pi-machine-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("canTransition", () => {
+  it("handles implement transitions", () => {
+    expect(canTransition("implement", "brainstorm", "plan")).toBe(true);
+    expect(canTransition("implement", "plan", "implement")).toBe(true);
+    expect(canTransition("implement", "implement", "done")).toBe(true);
+
+    expect(canTransition("implement", "brainstorm", "done")).toBe(false);
+    expect(canTransition("implement", "plan", "done")).toBe(false);
+    expect(canTransition("implement", "done", "implement")).toBe(false);
+  });
+
+  it("handles debug transitions", () => {
+    expect(canTransition("debug", "debug", "done")).toBe(true);
+    expect(canTransition("debug", "debug", "plan")).toBe(false);
+    expect(canTransition("debug", "done", "debug")).toBe(false);
+  });
+
+  it("handles brainstorm transitions", () => {
+    expect(canTransition("brainstorm", "brainstorm", "done")).toBe(true);
+    expect(canTransition("brainstorm", "brainstorm", "plan")).toBe(false);
+    expect(canTransition("brainstorm", "done", "brainstorm")).toBe(false);
+  });
+});
+
+describe("nextPhase", () => {
+  it("returns implement next phase and terminal null", () => {
+    expect(nextPhase("implement", "brainstorm")).toBe("plan");
+    expect(nextPhase("implement", "plan")).toBe("implement");
+    expect(nextPhase("implement", "implement")).toBe("done");
+    expect(nextPhase("implement", "done")).toBeNull();
+  });
+
+  it("returns debug next phase and terminal null", () => {
+    expect(nextPhase("debug", "debug")).toBe("done");
+    expect(nextPhase("debug", "done")).toBeNull();
+  });
+
+  it("returns brainstorm next phase and terminal null", () => {
+    expect(nextPhase("brainstorm", "brainstorm")).toBe("done");
+    expect(nextPhase("brainstorm", "done")).toBeNull();
+  });
+});
+
+describe("phasePipeline", () => {
+  it("returns implement pipeline", () => {
+    expect(phasePipeline("implement")).toEqual(["brainstorm", "plan", "implement", "done"]);
+  });
+
+  it("returns debug pipeline", () => {
+    expect(phasePipeline("debug")).toEqual(["debug", "done"]);
+  });
+
+  it("returns brainstorm pipeline", () => {
+    expect(phasePipeline("brainstorm")).toEqual(["brainstorm", "done"]);
+  });
+});
+
+describe("validateExitCriteria", () => {
+  it("validates brainstorm artifacts", () => {
+    const missing = makeTempDir();
+    expect(validateExitCriteria(missing, "implement", "brainstorm")).toEqual({
+      ok: false,
+      reason: "USER_REQUEST.md does not exist or is empty",
+    });
+
+    const emptyResearch = makeTempDir();
+    writeFileSync(join(emptyResearch, "USER_REQUEST.md"), VALID_USER_REQUEST, "utf-8");
+    writeFileSync(join(emptyResearch, "RESEARCH.md"), "\n  \n", "utf-8");
+    expect(validateExitCriteria(emptyResearch, "implement", "brainstorm")).toEqual({
+      ok: false,
+      reason: "RESEARCH.md does not exist or is empty",
+    });
+
+    const pass = makeTempDir();
+    writeFileSync(join(pass, "USER_REQUEST.md"), VALID_USER_REQUEST, "utf-8");
+    writeFileSync(join(pass, "RESEARCH.md"), VALID_RESEARCH, "utf-8");
+    expect(validateExitCriteria(pass, "implement", "brainstorm")).toEqual({ ok: true });
+  });
+
+  it("validates plan artifacts", () => {
+    const missing = makeTempDir();
+    expect(validateExitCriteria(missing, "implement", "plan")).toEqual({
+      ok: false,
+      reason: "No synthesized plan found in plans/",
+    });
+
+    const noSynth = makeTempDir();
+    mkdirSync(join(noSynth, "plans"), { recursive: true });
+    writeFileSync(join(noSynth, "plans", "draft.md"), "draft", "utf-8");
+    expect(validateExitCriteria(noSynth, "implement", "plan")).toEqual({
+      ok: false,
+      reason: "No synthesized plan found in plans/",
+    });
+
+    const pass = makeTempDir();
+    mkdirSync(join(pass, "plans"), { recursive: true });
+    writeFileSync(
+      join(pass, "plans", "synthesized-plan.md"),
+      makeValidPlan(["- [ ] P1. Fix token expiry check — Done when: expired tokens are rejected consistently"]),
+      "utf-8",
+    );
+    expect(validateExitCriteria(pass, "implement", "plan")).toEqual({ ok: true });
+  });
+
+  it("validates implement checkboxes", () => {
+    const missing = makeTempDir();
+    expect(validateExitCriteria(missing, "implement", "implement")).toEqual({
+      ok: false,
+      reason: "No synthesized plan found",
+    });
+
+    const noSynth = makeTempDir();
+    mkdirSync(join(noSynth, "plans"), { recursive: true });
+    writeFileSync(join(noSynth, "plans", "plan.md"), "content", "utf-8");
+    expect(validateExitCriteria(noSynth, "implement", "implement")).toEqual({
+      ok: false,
+      reason: "No synthesized plan found",
+    });
+
+    const unchecked = makeTempDir();
+    mkdirSync(join(unchecked, "plans"), { recursive: true });
+    writeFileSync(
+      join(unchecked, "plans", "2026-04-20_synthesized.md"),
+      makeValidPlan([
+        "- [ ] P1. First item — Done when: first item remains unchecked",
+        "- [ ] P2. Second item — Done when: second item remains unchecked",
+        "- [x] P3. Completed item — Done when: completed item is checked",
+      ]),
+      "utf-8",
+    );
+    expect(validateExitCriteria(unchecked, "implement", "implement")).toEqual({
+      ok: false,
+      reason: "2 plan items still unchecked",
+    });
+
+    const checked = makeTempDir();
+    mkdirSync(join(checked, "plans"), { recursive: true });
+    writeFileSync(
+      join(checked, "plans", "synthesized-plan.md"),
+      makeValidPlan(["- [x] P1. Done item — Done when: all checklist items are checked"]),
+      "utf-8",
+    );
+    expect(validateExitCriteria(checked, "implement", "implement")).toEqual({ ok: true });
+  });
+
+  it("picks the numerically latest synthesized plan for implement validation", () => {
+    const dir = makeTempDir();
+    mkdirSync(join(dir, "plans"), { recursive: true });
+    writeFileSync(
+      join(dir, "plans", "2_synthesized.md"),
+      makeValidPlan(["- [x] P1. Older checked item — Done when: old plan stays checked"]),
+      "utf-8",
+    );
+    writeFileSync(
+      join(dir, "plans", "11_synthesized.md"),
+      makeValidPlan(["- [ ] P1. Latest unchecked item — Done when: latest plan has an unchecked item"]),
+      "utf-8",
+    );
+    expect(validateExitCriteria(dir, "implement", "implement")).toEqual({
+      ok: false,
+      reason: "1 plan items still unchecked",
+    });
+  });
+
+  it("passes implement validation when the numerically latest plan is fully checked", () => {
+    const dir = makeTempDir();
+    mkdirSync(join(dir, "plans"), { recursive: true });
+    writeFileSync(
+      join(dir, "plans", "2_synthesized.md"),
+      makeValidPlan(["- [ ] P1. Older unchecked item — Done when: old plan keeps one unchecked item"]),
+      "utf-8",
+    );
+    writeFileSync(
+      join(dir, "plans", "11_synthesized.md"),
+      makeValidPlan(["- [x] P1. Latest checked item — Done when: latest plan is fully checked"]),
+      "utf-8",
+    );
+    expect(validateExitCriteria(dir, "implement", "implement")).toEqual({ ok: true });
+  });
+
+  it("counts unchecked items only within checklist section", () => {
+    const dir = makeTempDir();
+    mkdirSync(join(dir, "plans"), { recursive: true });
+    writeFileSync(
+      join(dir, "plans", "synthesized-plan.md"),
+      `# Plan
+
+## Scope
+Fix bug.
+
+## Checklist
+- [x] Main task — Done when: implemented
+
+## Blockers
+- [ ] waiting on external team
+`,
+      "utf-8",
+    );
+    expect(validateExitCriteria(dir, "implement", "implement")).toEqual({ ok: true });
+  });
+
+  it("handles brainstorm phase for brainstorm task — always passes", () => {
+    const dir = makeTempDir();
+    expect(validateExitCriteria(dir, "brainstorm", "brainstorm")).toEqual({ ok: true });
+  });
+
+  it("validates brainstorm phase for implement task — requires artifacts", () => {
+    const missing = makeTempDir();
+    expect(validateExitCriteria(missing, "implement", "brainstorm")).toEqual({
+      ok: false,
+      reason: "USER_REQUEST.md does not exist or is empty",
+    });
+
+    const pass = makeTempDir();
+    writeFileSync(join(pass, "USER_REQUEST.md"), VALID_USER_REQUEST, "utf-8");
+    writeFileSync(join(pass, "RESEARCH.md"), VALID_RESEARCH, "utf-8");
+    expect(validateExitCriteria(pass, "implement", "brainstorm")).toEqual({ ok: true });
+  });
+
+  it("validates debug artifacts", () => {
+    const missing = makeTempDir();
+    expect(validateExitCriteria(missing, "debug", "debug")).toEqual({
+      ok: false,
+      reason: "USER_REQUEST.md does not exist or is empty",
+    });
+
+    const pass = makeTempDir();
+    writeFileSync(join(pass, "USER_REQUEST.md"), VALID_USER_REQUEST, "utf-8");
+    writeFileSync(join(pass, "RESEARCH.md"), VALID_RESEARCH, "utf-8");
+    expect(validateExitCriteria(pass, "debug", "debug")).toEqual({ ok: true });
+  });
+
+  it("returns unknown phase error for done", () => {
+    const dir = makeTempDir();
+    expect(validateExitCriteria(dir, "implement", "done")).toEqual({
+      ok: false,
+      reason: "Unknown phase: done",
+    });
+  });
+});