@ilya-lesikov/pi-pi 0.10.0 → 0.12.0

package/extensions/orchestrator/orchestrator.ts

@@ -441,8 +441,6 @@ export class Orchestrator {
     switch (this.active.state.phase) {
       case "brainstorm":
         return brainstormSystemPrompt(this.active.type, this.active.description, this.active.dir, this.cwd);
-      case "debug":
-        return brainstormSystemPrompt(this.active.type, this.active.description, this.active.dir, this.cwd);
       case "plan":
         return planningSystemPrompt(this.active.dir, mode);
       case "implement":
@@ -592,8 +590,7 @@ export class Orchestrator {
     log.info({ s: "task", dir, taskId: this.active.taskId, phase: state.phase, step: state.step }, "task activated");
 
     const modelConfig = this.config.agents.orchestrators[
-      type === "debug" ? "debug"
-      : type === "brainstorm" ? "brainstorm"
+      type === "brainstorm" ? "brainstorm"
       : type === "review" ? "review"
       : type === "quick" ? "quick"
       : "implement"
@@ -611,7 +608,7 @@ export class Orchestrator {
     this.injectContextAndArtifacts(this.active.dir, this.active.state.phase);
 
     this.phaseStartTime = Date.now();
-    const isGenericDescription = ["implement", "debug", "brainstorm", "review"].includes(this.active.description);
+    const isGenericDescription = ["implement", "brainstorm", "review"].includes(this.active.description);
     const isGenericQuickDescription = this.active.description === "quick";
     const hasInheritedTaskContext = Boolean(fromTaskDir && type === "implement");
     const isWaitingForPlanners = this.active.state.phase === "plan" && this.active.state.step === "await_planners";
@@ -829,7 +826,6 @@ export class Orchestrator {
   // block. Mirrors the phase→model selection in injectContextAndArtifacts.
   mainAgentConfigForPhase(phase: Phase | undefined): { model: string; thinking: string } {
     const o = this.config.agents.orchestrators;
-    if (phase === "debug" && this.active?.type === "debug") return o.debug;
     if (phase === "brainstorm" && this.active?.type === "brainstorm") return o.brainstorm;
     if (phase === "review" && this.active?.type === "review") return o.review;
     if (phase === "plan") return o.plan;
@@ -840,9 +836,7 @@ export class Orchestrator {
     const log = getLogger();
     log.debug({ s: "context", taskDir, phase }, "injecting context and artifacts");
     const modelSpec =
-      phase === "debug" && this.active?.type === "debug"
-        ? this.config.agents.orchestrators.debug.model
-      : phase === "brainstorm" && this.active?.type === "brainstorm"
+      phase === "brainstorm" && this.active?.type === "brainstorm"
         ? this.config.agents.orchestrators.brainstorm.model
       : phase === "review" && this.active?.type === "review"
         ? this.config.agents.orchestrators.review.model

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

@@ -6,19 +6,37 @@ import { brainstormSystemPrompt, spawnBrainstormReviewers } from "./brainstorm.j
 import { getDefaultConfig } from "../config.js";
 
 describe("brainstormSystemPrompt", () => {
-  it("debug prompt body is pure procedure (no completion/menu restatements)", () => {
-    const prompt = brainstormSystemPrompt("debug", "fix a bug", "/tmp/task", "/tmp");
-    expect(prompt).toContain("DEBUG PHASE");
-    expect(prompt).not.toContain("pp_phase_complete");
-    expect(prompt).not.toContain("/pp");
-  });
-
   it("brainstorm prompt body is pure procedure (no completion/menu restatements)", () => {
     const prompt = brainstormSystemPrompt("brainstorm", "explore ideas", "/tmp/task", "/tmp");
     expect(prompt).toContain("conversation");
     expect(prompt).not.toContain("pp_phase_complete");
     expect(prompt).not.toContain("/pp");
   });
+
+  it("conversation branch uses the Socratic one-at-a-time-with-second-push clarify policy", () => {
+    const prompt = brainstormSystemPrompt("brainstorm", "explore ideas", "/tmp/task", "/tmp");
+    expect(prompt).toContain("CLARIFY ONE AT A TIME");
+    expect(prompt).toContain("push once more");
+    expect(prompt).not.toContain("batch them into one focused round");
+  });
+
+  it("task branch also carries the Socratic clarify policy and degrades to recorded assumptions when autonomous", () => {
+    const prompt = brainstormSystemPrompt("task", "do the thing", "/tmp/task", "/tmp");
+    expect(prompt).toContain("CLARIFY ONE AT A TIME");
+    expect(prompt).toContain("artifacts/ASSUMPTIONS.md");
+  });
+
+  it("both branches state anti-sycophancy as a behavior, with the quoted phrase adjacent to an example marker", () => {
+    for (const t of ["brainstorm", "task"] as const) {
+      const prompt = brainstormSystemPrompt(t, "x", "/tmp/task", "/tmp");
+      expect(prompt).toContain("take a position");
+      expect(prompt).toMatch(/what evidence would change|what would change it/i);
+      // The quoted anti-pattern phrase must sit right after an explicit example
+      // marker on the same line — a stray "e.g." elsewhere in the prompt must not
+      // satisfy this.
+      expect(prompt).toMatch(/(illustrative anti-patterns|Examples of the anti-pattern)[^\n]{0,60}'that could work'/);
+    }
+  });
 });
 
 describe("spawnBrainstormReviewers missing prerequisites", () => {

package/extensions/orchestrator/phases/brainstorm.ts

@@ -19,75 +19,44 @@ function isEnabled(value: { enabled?: boolean } | undefined): boolean {
 // advisor to consult by default (Claude-driven → a GPT-family advisor; GPT-driven
 // → a Claude-family advisor). Advisors are model-named pool subagents; pick one
 // from the roster in the delegation guidance.
-export function interactiveFlowBlock(driverFamily: string, defaultAdvisor: string): string {
+//
+// The clarify step is caller-selected. "socratic" (brainstorm) elicits design intent
+// one question at a time with a second push, because the first answer to a design
+// question is usually the polished/surface one. "scope" (review-task intake) is
+// factual up-front scoping (which repo/branch/PR/range), not design elicitation, so
+// it deliberately keeps the batch-it-up-front behavior. `conversational` selects the
+// wording for the free-form brainstorm conversation (which is driven by the user turn
+// by turn) over the one-shot phase task; it never emits `/pp` or `pp_phase_complete`.
+export function interactiveFlowBlock(
+  driverFamily: string,
+  defaultAdvisor: string,
+  opts: { clarify?: "socratic" | "scope"; conversational?: boolean } = {},
+): string {
+  const { clarify = "socratic", conversational = false } = opts;
+  const clarifyStep =
+    clarify === "scope"
+      ? "1. CLARIFY SCOPE UP-FRONT: if what to review is ambiguous (which repo/branch/PR/commit-range, what to focus on), ask up front before diving in. This is factual scoping, not design elicitation — ask them up front in quick succession (still one focused question per ask_user call, never bundled into one prompt) rather than dripping them out across the work. If the scope is clear, skip straight to step 2."
+      : "1. CLARIFY ONE AT A TIME: if the request is ambiguous, ask ONE focused question, then WAIT for the answer before asking the next — do NOT batch a list. The first answer to a design question is usually the polished/surface one; push once more on it (\"what would that actually look like / what breaks if…\") to reach the real answer before moving on. Skip any question the request already answers. If running autonomously with no user to ask, do NOT block: make the strongest-supported assumption and record it via the assumptions rule in your constraints (artifacts/ASSUMPTIONS.md) instead of asking.";
+  const workStep = conversational
+    ? "2. WORK AUTONOMOUSLY IN THE MIDDLE: once the topic is clear, research/explore/design without stopping to ask. Delegate to subagents (parallel explores for broad searches) and use tools directly for quick lookups. Do NOT interrupt with piecemeal mid-flow questions — collect uncertainties and raise them together at a natural checkpoint. The one-at-a-time push above is for the clarify stage, not license to interrupt mid-work."
+    : "2. WORK AUTONOMOUSLY: research, explore, and design without stopping to ask. Delegate to subagents (parallel explores for broad searches). Do NOT interrupt mid-flow with questions — collect uncertainties for step 4 instead. Only a genuine blocker (you cannot proceed at all) justifies an ask here. The one-at-a-time push above is for the clarify stage, not license to interrupt mid-work.";
+  const presentStep = conversational
+    ? "6. PRESENT RESULTS: give conclusions as a clear, structured summary (findings, decisions, recommended direction) — don't just dump raw results."
+    : "6. PRESENT RESULTS: end with a structured summary (what you found, the decisions, the recommended direction) and hand back with the standard closing block.";
   return [
-    "# Flow (minimize interruptions):",
-    "1. CLARIFY UP-FRONT: if the request is ambiguous, ask your clarifying question(s) now, at the very start — batch them. If it's clear, skip straight to step 2.",
-    "2. WORK AUTONOMOUSLY: research, explore, and design without stopping to ask. Delegate to subagents (parallel explores for broad searches). Do NOT interrupt mid-flow with questions — collect uncertainties for step 4 instead. Only a genuine blocker (you cannot proceed at all) justifies an ask here.",
+    conversational ? "# Flow (minimize interruptions — the streamlined flow, adapted to conversation):" : "# Flow (minimize interruptions):",
+    clarifyStep,
+    workStep,
     `3. CONSULT AN ADVISOR: before presenting, get an independent second opinion from an advisor whose model family differs from yours. You run on ${driverFamily}, so default to ${defaultAdvisor}. Escalate to more advisors for hard or high-stakes calls.`,
-    "4. CLARIFY AT THE END: surface any remaining decisions as focused asks — one at a time.",
+    "4. CLARIFY AT THE END: surface any remaining decisions as focused asks — one at a time. Don't bury unresolved questions inside an approval prompt or the summary.",
     "5. APPROVE COMMITTED SPECIFICS: before finalizing, when your output commits to concrete, costly-to-reverse or opinion-heavy choices — exact wording, structure, naming, default values, or interface signatures — show the ACTUAL proposed text/values inline in your message, then ask for explicit approval. Don't silently invent and bury them.",
-    "6. PRESENT RESULTS: end with a structured summary (what you found, the decisions, the recommended direction) and hand back with the standard closing block.",
+    presentStep,
+    ...(conversational ? ["This is still a conversation: the user drives it and may steer at any time. The flow shapes HOW you work between their messages — it does not forbid responding to what they say."] : []),
   ].join("\n");
 }
 
 export function brainstormSystemPrompt(taskType: TaskType, taskDescription: string, taskDir: string, cwd: string): string {
   const registerReposInstruction = `First, register all git repositories you'll work in using pp_register_repo (including the root: ${cwd}). For each, determine the base branch by examining the current branch and remote tracking.`;
-  if (taskType === "debug") {
-    return [
-      "[PI-PI — DEBUG PHASE]",
-      `Problem: ${taskDescription}`,
-      "",
-      registerReposInstruction,
-      "",
-    "Read-only diagnosis mode. You MAY use write/edit for diagnosis only (repro/test/analysis files) — never to implement the actual fix or feature.",
-      "",
-      interactiveFlowBlock("GPT", "a Claude-family advisor"),
-      "",
-    "# Your job:",
-    "1. Clarify the problem with the user if needed",
-    "2. Delegate research to subagents where useful (see the delegation guidance in your system prompt), and use bash to run commands, check logs, reproduce issues",
-    "3. 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)",
-      "",
-      "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.>",
-      "",
-      "This is the LAST interactive phase. If the task continues in autonomous mode, the downstream plan/implement phases cannot ask the user anything — so resolve every Open Question now (answer it, or mark it DECIDED:/ASSUMED: with rationale). Do NOT defer questions to the plan phase.",
-      "These files are validated programmatically. Missing sections or unexpected sections will be rejected.",
-      "Use pp_write_state_file / pp_edit_state_file (NOT the generic write/edit) for .pp state files — they keep the output compact and validate structure.",
-      "",
-      "# 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.",
-      "",
-      "Keep USER_REQUEST.md current: update it whenever the user's request changes or clarifies, so it never goes stale.",
-    ].join("\n");
-  }
-
   if (taskType === "brainstorm") {
     return [
       "[PI-PI — BRAINSTORM]",
@@ -99,17 +68,12 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
       "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.",
       "",
-      "# Flow (minimize interruptions — the streamlined flow, adapted to conversation):",
-      "1. CLARIFY UP-FRONT: if the topic is ambiguous, ask your clarifying question(s) at the very start — batch them into one focused round rather than dripping them out.",
-      "2. WORK AUTONOMOUSLY IN THE MIDDLE: once the topic is clear, research/explore/design without stopping to ask. Delegate to subagents (parallel explores for broad searches) and use tools directly for quick lookups. Do NOT interrupt with piecemeal mid-flow questions — collect uncertainties and raise them together at a natural checkpoint.",
-      "3. CONSULT AN ADVISOR: before landing on a recommendation, get an independent second opinion from an advisor whose model family differs from yours. You run on Claude, so default to a GPT-family advisor. Escalate to more advisors for hard or high-stakes calls.",
-      "4. CLARIFY AT THE END: before finalizing, surface any remaining open decisions as focused asks — one at a time. Don't bury unresolved questions inside an approval prompt or the summary.",
-      "5. APPROVE COMMITTED SPECIFICS: when you commit to concrete, costly-to-reverse or opinion-heavy choices — exact wording, structure, naming, default values, or interface signatures — show the ACTUAL proposed text/values inline, then get explicit approval. Don't silently invent and bury them.",
-      "6. PRESENT RESULTS: give conclusions as a clear, structured summary (findings, decisions, recommended direction) — don't just dump raw results.",
-      "This is still a conversation: the user drives it and may steer at any time. The flow shapes HOW you work between their messages — it does not forbid responding to what they say.",
+      interactiveFlowBlock("Claude", "a GPT-family advisor", { clarify: "socratic", conversational: true }),
       "",
       "# How to work:",
-      "- Discuss the topic with the user. Propose approaches. Analyze tradeoffs.",
+      "- Discuss the topic with the user. Propose approaches. Analyze tradeoffs. When you give a judgment, take a position and say what evidence would change it — do NOT hedge without landing anywhere or offer empty validation (e.g. agreeing just to be agreeable). Examples of the anti-pattern to avoid: 'that could work', 'it depends' with no position taken.",
+      "- Scope triage up front: if the topic spans multiple independent subsystems, flag that immediately and help decompose it into sub-problems rather than treating it as one blob.",
+      "- Explore 2-3 viable approaches with tradeoffs; lead with your recommended one and say why. Do NOT dismiss a topic as 'too simple to need design' — that is where unexamined assumptions cause the most wasted work.",
       "- Delegate research to subagents where useful (see the delegation guidance in your system prompt).",
       "- Use tools directly for quick lookups (cbm_search, lsp, ast_search, grep, etc.)",
       "",
@@ -152,7 +116,7 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
     "   - lsp documentSymbol, goToDefinition, findReferences, goToImplementation, hover",
     "   - cbm_trace: trace call chains for dependency understanding",
     "   - ast_search: find structural patterns across the codebase",
-    "4. Explore design options: identify the viable approaches, weigh their tradeoffs, and land on a recommended direction (capture the reasoning in RESEARCH.md / an artifact)",
+    "4. Explore design options: identify 2-3 viable approaches, weigh their tradeoffs, and lead with a recommended direction + why (capture the reasoning in RESEARCH.md / an artifact). If the task spans multiple independent subsystems, triage that up front and decompose it rather than treating it as one blob. Do NOT dismiss anything as 'too simple to need design' — unexamined assumptions in 'simple' work cause the most wasted effort. When you give a judgment, take a position and state what evidence would change it; do NOT hedge without landing anywhere or offer empty validation (illustrative anti-patterns, any language: 'that could work', 'it depends' with no position).",
     "5. Ask the user follow-up questions as needed",
     "6. Actively drive every Open Question to resolution — chase down answers via research or by asking the user; the Open Questions section should be empty (or every entry marked DECIDED:/ASSUMED: with rationale) before you hand off, not a passive backlog. This is the LAST interactive phase: if the task continues in autonomous mode, the downstream plan/implement phases cannot ask the user anything, so a deferred question becomes an unanswered one. Resolve or explicitly ASSUME each now — do NOT defer to the plan phase.",
     "7. Write findings into RESEARCH.md as results come back — don't wait for all subagents",

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

@@ -9,3 +9,25 @@ describe("implementationSystemPrompt self-complete directive", () => {
     expect(prompt).not.toContain("do NOT wait for the user");
   });
 });
+
+describe("implement-phase verification gate + conditional test-first", () => {
+  const prompt = implementationSystemPrompt("/tmp/task", "/tmp");
+
+  it("gates completion claims on fresh evidence with an explicit not-applicable path", () => {
+    expect(prompt).toContain("Verification gate");
+    expect(prompt).toMatch(/fresh tool output|proving evidence/i);
+    expect(prompt).toContain("not applicable");
+  });
+
+  it("states the gate as behavior, not a language-specific phrase list", () => {
+    expect(prompt).toMatch(/in any language|holds in any language/i);
+  });
+
+  it("adopts conditional test-first, not universal TDD or delete-untested-code", () => {
+    expect(prompt).toContain("Test-first policy");
+    expect(prompt).toMatch(/FAILING test first/);
+    expect(prompt).toContain("There is no rule to delete untested code");
+    expect(prompt).not.toMatch(/NO PRODUCTION CODE/i);
+    expect(prompt).toMatch(/not feasible|infeasible/);
+  });
+});

package/extensions/orchestrator/phases/implementation.ts

@@ -25,6 +25,12 @@ export function implementationSystemPrompt(taskDir: string, cwd: string): string
     "6. After completing changes, run cbm_changes to verify blast radius",
     "7. Delegate to subagents where useful (see the delegation guidance in your system prompt) — spawn multiple explores in parallel for broad searches, and use task for parallelizable self-contained implementation subtasks",
     "",
+    "# Verification gate (before claiming any item done):",
+    "A completion claim is only valid when fresh tool output proves it. For each item, before you check it off: (1) identify what tool output would prove the claim (lsp diagnostics clean, a test run passing, cbm_changes showing the expected blast radius, a command exit code); (2) actually produce that output this turn; (3) cite it. This gates on whether the proving evidence EXISTS — not on how you phrase the claim — so it holds in any language. If a claim genuinely cannot be proven with your granted tools, say so explicitly and state why (\"not applicable — <reason>\", e.g. no runnable harness in this repo) rather than implying it was verified.",
+    "",
+    "# Test-first policy (conditional, not universal TDD):",
+    "For a behavior change or a bug fix where an automated test is feasible, write or reproduce the FAILING test first, then make it pass. For work where an automated test is not feasible (config, migrations, docs, pure refactor, no usable harness), state the verification method BEFORE editing instead. There is no rule to delete untested code and no requirement to test-first when a test is infeasible — pick the path that actually produces evidence.",
+    "",
     "# 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). Prefix it with a conventional-commit",

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

@@ -63,12 +63,6 @@ describe("canTransition", () => {
     expect(canTransition("implement", "done", "implement")).toBe(false);
   });
 
-  it("handles debug transitions", () => {
-    expect(canTransition("debug", "debug", "plan")).toBe(true);
-    expect(canTransition("debug", "debug", "done")).toBe(false);
-    expect(canTransition("debug", "done", "debug")).toBe(false);
-  });
-
   it("handles brainstorm transitions", () => {
     expect(canTransition("brainstorm", "brainstorm", "plan")).toBe(true);
     expect(canTransition("brainstorm", "brainstorm", "done")).toBe(false);
@@ -89,11 +83,6 @@ describe("nextPhase", () => {
     expect(nextPhase("implement", "done")).toBeNull();
   });
 
-  it("returns debug next phase and terminal null", () => {
-    expect(nextPhase("debug", "debug")).toBe("plan");
-    expect(nextPhase("debug", "done")).toBeNull();
-  });
-
   it("returns brainstorm next phase and terminal null", () => {
     expect(nextPhase("brainstorm", "brainstorm")).toBe("plan");
     expect(nextPhase("brainstorm", "done")).toBeNull();
@@ -110,10 +99,6 @@ describe("phasePipeline", () => {
     expect(phasePipeline("implement")).toEqual(["brainstorm", "plan", "implement", "done"]);
   });
 
-  it("returns debug pipeline", () => {
-    expect(phasePipeline("debug")).toEqual(["debug", "plan", "implement", "done"]);
-  });
-
   it("returns brainstorm pipeline", () => {
     expect(phasePipeline("brainstorm")).toEqual(["brainstorm", "plan", "implement", "done"]);
   });
@@ -285,19 +270,6 @@ Fix bug.
     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("validates review phase — requires artifacts and an ANCHORS-bearing final_pass file", () => {
     const missing = makeTempDir();
     expect(validateExitCriteria(missing, "review", "review")).toEqual({

package/extensions/orchestrator/phases/machine.ts

@@ -60,11 +60,6 @@ const TRANSITIONS: Record<TaskType, Record<string, string[]>> = {
     plan: ["implement"],
     implement: ["done"],
   },
-  debug: {
-    debug: ["plan"],
-    plan: ["implement"],
-    implement: ["done"],
-  },
   brainstorm: {
     brainstorm: ["plan"],
     plan: ["implement"],
@@ -217,37 +212,6 @@ export function validateExitCriteria(
       return { ok: true };
     }
 
-    case "debug": {
-      const ur = join(taskDir, "USER_REQUEST.md");
-      const res = join(taskDir, "RESEARCH.md");
-      if (isMissingOrEmpty(ur)) {
-        return { ok: false, reason: "USER_REQUEST.md does not exist or is empty" };
-      }
-      if (isMissingOrEmpty(res)) {
-        return { ok: false, reason: "RESEARCH.md does not exist or is empty" };
-      }
-      const urContent = readFileSync(ur, "utf-8");
-      const resContent = readFileSync(res, "utf-8");
-
-      const userRequestValidation = validateUserRequest(urContent);
-      if (!userRequestValidation.ok) {
-        return {
-          ok: false,
-          reason: formatValidationErrors("USER_REQUEST.md", userRequestValidation.errors, USER_REQUEST_TEMPLATE),
-        };
-      }
-
-      const researchValidation = validateResearch(resContent);
-      if (!researchValidation.ok) {
-        return {
-          ok: false,
-          reason: formatValidationErrors("RESEARCH.md", researchValidation.errors, RESEARCH_TEMPLATE),
-        };
-      }
-
-      return { ok: true };
-    }
-
     case "quick": {
       return { ok: true };
     }
@@ -261,8 +225,6 @@ export function phasePipeline(taskType: TaskType): Phase[] {
   switch (taskType) {
     case "implement":
       return ["brainstorm", "plan", "implement", "done"];
-    case "debug":
-      return ["debug", "plan", "implement", "done"];
     case "brainstorm":
       return ["brainstorm", "plan", "implement", "done"];
     case "review":

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

@@ -3,7 +3,13 @@ import { mkdtempSync, rmSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 import { planningSystemPrompt, spawnPlanReviewers } from "./planning.js";
-import { getDefaultConfig } from "../config.js";
+import { createPlannerAgent } from "../agents/planner.js";
+import { getDefaultConfig, resolvePreset } from "../config.js";
+
+function plannerPlanFormatLines(): string {
+  const p = createPlannerAgent("opus", resolvePreset(getDefaultConfig(), "planners"), { userRequest: "u", research: "r", manifest: [] }, "/out.md", []);
+  return p.prompt;
+}
 
 describe("planningSystemPrompt self-complete directive", () => {
   it("guided synthesis instructs the agent to call pp_phase_complete when synthesis is complete", () => {
@@ -19,6 +25,26 @@ describe("planningSystemPrompt self-complete directive", () => {
   });
 });
 
+describe("plan no-placeholders rule is behavior-framed and lockstep across both surfaces", () => {
+  const behavior = "an item that defers a decision instead of stating a concrete outcome is a plan failure";
+  it("phrases the rule on behavior, with TBD/TODO marked as an illustrative example only", () => {
+    for (const prompt of [planningSystemPrompt("/tmp/task", "guided"), plannerPlanFormatLines()]) {
+      expect(prompt).toContain(behavior);
+      // The English placeholder tokens must appear only as an example, adjacent
+      // to an explicit example marker — never as the literal matching rule.
+      expect(prompt).toMatch(/'TBD'\/'TODO'\/'decide later' is only an illustrative example/);
+    }
+  });
+
+  it("keeps the plan-format guidance identical between planning.ts and planner.ts", () => {
+    const fromPhase = planningSystemPrompt("/tmp/task", "guided");
+    const fromAgent = plannerPlanFormatLines();
+    const line = (p: string) => p.split("\n").find((l) => l.includes(behavior));
+    expect(line(fromPhase)).toBeDefined();
+    expect(line(fromPhase)).toBe(line(fromAgent));
+  });
+});
+
 describe("spawnPlanReviewers missing prerequisites", () => {
   async function run(setup: (dir: string) => void) {
     const taskDir = mkdtempSync(join(tmpdir(), "pi-pi-plan-spawn-"));

package/extensions/orchestrator/phases/planning.ts

@@ -52,7 +52,7 @@ export function planningSystemPrompt(taskDir: string, mode: TaskMode): string {
     "- Start with # Plan",
     "- ## Scope: 2-4 lines — what changes, what doesn't, critical constraints",
     "- ## Checklist: each item is - [ ] <outcome> — Done when: <observable condition>",
-    "  Each item = one independently verifiable outcome. No code snippets or file-by-file instructions.",
+    "  Each item = one independently verifiable outcome, right-sized to the smallest chunk worth verifying on its own. No code snippets or file-by-file instructions. Nest these INSIDE the Done-when condition (do not add sections or code): (a) a verification method — how the outcome is proven (test passes, diagnostics clean, command output); (b) for items meant for parallel delegation, the interface it consumes/produces (what earlier outcomes it depends on, what later ones depend on it); (c) NO unresolved items — an item that defers a decision instead of stating a concrete outcome is a plan failure; resolve it now (in any language: a placeholder such as 'TBD'/'TODO'/'decide later' is only an illustrative example of the deferral to avoid, not the literal thing being matched).",
     "- ## Pattern constraints: include this section whenever the task adds a type, function, parser, annotation, config key, enum, or any user-facing value. For each, name the CLOSEST EXISTING analog in the codebase (found by behavior, not filename) and the exact conventions the implementer MUST mirror: data shape (prefer one existing shape over inventing parallel/duplicated state), spelling/casing of user-facing values (match existing values — never invent a new casing), and parser/validation/error-handling shape. These are acceptance criteria, not suggestions. Omit the section only if the task adds none of the above.",
     "- ## Blockers: unresolved issues blocking implementation (omit if none)",
     "Write/update the synthesized plan with pp_write_state_file / pp_edit_state_file (NOT the generic write/edit) — they keep the output compact and validate structure.",

package/extensions/orchestrator/phases/review-task.test.ts

@@ -17,4 +17,11 @@ describe("review-task reviewSystemPrompt", () => {
     expect(prompt).toContain("RESEARCH.md");
     expect(prompt).toContain("pp_write_state_file");
   });
+
+  it("keeps up-front factual scope-clarify intake, NOT the brainstorm Socratic policy", () => {
+    const prompt = reviewSystemPrompt("/tmp/task", "/tmp/cwd");
+    expect(prompt).toContain("CLARIFY SCOPE UP-FRONT");
+    expect(prompt).toContain("If the scope is ambiguous, ask the user before diving in.");
+    expect(prompt).not.toContain("CLARIFY ONE AT A TIME");
+  });
 });

package/extensions/orchestrator/phases/review-task.ts

@@ -6,7 +6,7 @@ export function reviewSystemPrompt(taskDir: string, cwd: string): string {
     "",
     `First, register all git repositories you'll work in using pp_register_repo (including the root: ${cwd}). For each, determine the base branch by examining the current branch and remote tracking.`,
     "",
-    interactiveFlowBlock("Claude", "a GPT-family advisor"),
+    interactiveFlowBlock("Claude", "a GPT-family advisor", { clarify: "scope" }),
     "",
     "You are reviewing code changes. The user will describe what to review in their first chat message",
     "(e.g. a branch, a commit range, uncommitted changes, or a GitHub PR URL). There is NO pre-seeded",

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

@@ -23,16 +23,6 @@ describe("reviewSystemPrompt apply_feedback wording", () => {
     expect(auto).not.toContain("pp_phase_complete");
   });
 
-  it("debug uses the artifact-review branch: DEBUG header, brainstorm-reviews dir, no code-review tail", () => {
-    const prompt = reviewSystemPrompt("/tmp/task", 1, "debug", "guided");
-    expect(prompt).toContain("DEBUG REVIEW CYCLE");
-    expect(prompt).toContain("Debug reviewer outputs are ready.");
-    expect(prompt).toContain("/tmp/task/brainstorm-reviews/");
-    expect(prompt).not.toContain("code-reviews");
-    expect(prompt).not.toContain("Create a fix plan");
-    expect(prompt).not.toContain("pp_phase_complete");
-  });
-
   it("brainstorm apply-feedback prompt permits artifact updates and steers to the compact tools", () => {
     const prompt = reviewSystemPrompt("/tmp/task", 1, "brainstorm", "autonomous");
     expect(prompt).toContain("artifacts/");
@@ -41,6 +31,17 @@ describe("reviewSystemPrompt apply_feedback wording", () => {
     expect(prompt).toContain("Do NOT add, rename, or remove sections in USER_REQUEST.md or RESEARCH.md");
   });
 
+  it("the brainstorm synthesis path (which edits state files) carries the verify-before-accepting gate", () => {
+    // phase !== "review" AND edit-capable (mutates USER_REQUEST/RESEARCH/artifacts),
+    // so plan ① requires the gate here too; its evidence is the research/artifacts,
+    // not tool output.
+    for (const mode of ["autonomous", "guided"] as const) {
+      const prompt = reviewSystemPrompt("/tmp/task", 1, "brainstorm", mode);
+      expect(prompt).toContain("Before accepting a finding, verify it against the actual");
+      expect(prompt).toMatch(/reject it with your reasoning rather than agreeing performatively/);
+    }
+  });
+
   it("autonomous plan feedback folds into a new synthesized plan, not a separate fix-plan file", () => {
     // Re-review and the transition read only the latest `*synthesized*` plan, so
     // plan-phase feedback must land there.
@@ -55,6 +56,42 @@ describe("reviewSystemPrompt apply_feedback wording", () => {
     expect(impl).toContain("Implement the fixes");
   });
 
+  it("EVERY edit-capable synthesis path carries the verify-before-accepting fix gate; standalone review does not", () => {
+    for (const args of [
+      ["implement", "autonomous"],
+      ["implement", "guided"],
+      ["plan", "guided"],
+      ["plan", "autonomous"],
+    ] as const) {
+      const prompt = reviewSystemPrompt("/tmp/task", 1, args[0], args[1]);
+      expect(prompt).toContain("Before accepting a finding, verify it against the actual");
+      expect(prompt).toMatch(/reject it with your technical reasoning rather than agreeing performatively/);
+      expect(prompt).toContain("blocking-severity first");
+    }
+    const standalone = reviewSystemPrompt("/tmp/task", 1, "review", "guided");
+    expect(standalone).not.toContain("Before accepting a finding, verify it against the actual");
+  });
+
+  it("plan-phase fix gate demands plan-text evidence (not afterImplement/lsp) in BOTH modes", () => {
+    for (const mode of ["guided", "autonomous"] as const) {
+      const plan = reviewSystemPrompt("/tmp/task", 1, "plan", mode);
+      expect(plan).toContain("corrected plan text");
+      expect(plan).toContain("a code fix is out of scope in the plan phase");
+    }
+    const impl = reviewSystemPrompt("/tmp/task", 1, "implement", "guided");
+    expect(impl).toContain("afterImplement");
+  });
+
+  it("plan-phase feedback lands in a new synthesized plan (never a fix-plan file or code changes) in BOTH modes", () => {
+    for (const mode of ["guided", "autonomous"] as const) {
+      const plan = reviewSystemPrompt("/tmp/task", 1, "plan", mode);
+      expect(plan).toContain("NEW synthesized plan");
+      expect(plan).not.toContain("Create a fix plan");
+      expect(plan).not.toContain("Implement the fixes");
+      expect(plan).not.toContain("Run afterImplement commands");
+    }
+  });
+
   it("standalone review phase omits the fix-plan/implement/afterImplement tail", () => {
     const prompt = reviewSystemPrompt("/tmp/task", 1, "review", "guided");
     expect(prompt).toContain("REVIEW CYCLE");