@ilya-lesikov/pi-pi 0.11.0 → 0.12.0

package/3p/pi-subagents/src/agent-manager.ts

@@ -174,6 +174,7 @@ export class AgentManager {
       // have no inline surface — stay visible instead of vanishing.
       isBackground: options.isBackground,
       invocation: options.invocation,
+      resolvedModelId: options.model ? `${options.model.provider}/${options.model.id}` : undefined,
     };
     this.agents.set(id, record);
 

package/3p/pi-subagents/src/index.ts

@@ -381,6 +381,7 @@ export default function (pi: ExtensionAPI) {
       toolUses: record.toolUses,
       durationMs,
       tokens,
+      modelId: record.resolvedModelId,
     };
   }
 

package/3p/pi-subagents/src/types.ts

@@ -126,6 +126,14 @@ export interface AgentRecord {
   isBackground?: boolean;
   /** Resolved spawn params, captured for UI display. Fixed at spawn time. */
   invocation?: AgentInvocation;
+  /**
+   * Fully-qualified model id (`provider/id`) this agent ran under, captured at
+   * spawn from the resolved model. Surfaced in lifecycle events so usage can be
+   * attributed to a real model instead of falling back to the description.
+   * Absent when the caller supplied no explicit model (the agent inherits the
+   * parent model).
+   */
+  resolvedModelId?: string;
 }
 
 export interface AgentInvocation {

package/extensions/orchestrator/agents/advisor.ts

@@ -8,7 +8,7 @@ export function createAdvisorAgent(entry: PoolEntry) {
   const info = getModelInfo(model);
   return {
     frontmatter: {
-      description: "Deep-reasoning advisor for design decisions and 'why is this broken' analysis (pi-pi)",
+      description: "Deep-reasoning advisor that investigates ONE hard judgment call — a design/architecture tradeoff or a 'why is this broken' — and returns a reasoned, evidence-backed recommendation; best for genuine judgment, not for locating code (use explore), fetching external docs (use librarian), or applying edits (pi-pi)",
       tools,
       model,
       thinking: entry.thinking,
@@ -34,6 +34,7 @@ export function createAdvisorAgent(entry: PoolEntry) {
       "- Scope recommendations by effort: name the quick fix vs the thorough one.",
       "- Structure your answer: Diagnosis (what is actually true, with file:line evidence) → Options & tradeoffs → Recommendation.",
       "- Be honest about uncertainty. If evidence is thin, say so and state what would resolve it.",
+      "- Take a position. On every judgment, say where you land AND what evidence would change your mind. Do NOT validate or hedge without committing to a view — empty agreement and non-answers are worthless to the caller. This targets the behavior, not any wordlist, so it holds in any language (illustrative anti-patterns: 'that could work', 'it depends' offered with no position taken).",
       "</task>",
     ].join("\n"),
   };

package/extensions/orchestrator/agents/code-reviewer.ts

@@ -76,6 +76,7 @@ export function createCodeReviewerAgent(
       "Evidence requirements:",
       "- Every CRITICAL or MAJOR finding MUST cite file:line or backtick-quoted code",
       "- Never assert a problem without reading the actual code first",
+      "- You are read-only and MUST NOT run tests/builds: support findings ONLY with what your granted tools produce — the diff, the code you read, and lsp diagnostics. A concern that would need a test run, build, or runtime output you cannot obtain is NOT a finding — move it to Open Questions and state what evidence would settle it.",
       "- If you can't prove it with evidence, move it to Open Questions",
       "",
       "Perspectives to check:",

package/extensions/orchestrator/agents/constraints.test.ts

@@ -11,8 +11,8 @@ describe("completionLine", () => {
     }
   });
 
-  it("guided review and debug stay hands-off (no unprompted self-complete)", () => {
-    for (const phase of ["review", "debug"] as const) {
+  it("guided review stays hands-off (no unprompted self-complete)", () => {
+    for (const phase of ["review"] as const) {
       const line = completionLine(phase, "guided");
       expect(line).toContain("Do NOT advance on your own or call pp_phase_complete unprompted");
     }
@@ -23,8 +23,8 @@ describe("completionLine", () => {
     expect(line).toContain("Do NOT call pp_phase_complete yourself");
   });
 
-  it("guided brainstorm/review/debug carve out a /pp banner exception", () => {
-    for (const phase of ["brainstorm", "review", "debug"] as const) {
+  it("guided brainstorm/review carve out a /pp banner exception", () => {
+    for (const phase of ["brainstorm", "review"] as const) {
       expect(completionLine(phase, "guided")).toContain(
         "a /pp menu banner",
       );
@@ -36,7 +36,7 @@ describe("completionLine", () => {
     for (const phase of ["plan", "implement"] as const) {
       expect(completionLine(phase, "guided")).not.toContain("a /pp menu banner");
     }
-    for (const phase of ["brainstorm", "review", "debug", "plan", "implement"] as const) {
+    for (const phase of ["brainstorm", "review", "plan", "implement"] as const) {
       expect(completionLine(phase, "autonomous")).not.toContain("a /pp menu banner");
     }
   });
@@ -48,7 +48,7 @@ describe("completionLine", () => {
   });
 
   it("guided handoff phases require the standardized closing block", () => {
-    for (const phase of ["brainstorm", "review", "debug"] as const) {
+    for (const phase of ["brainstorm", "review"] as const) {
       const line = completionLine(phase, "guided");
       expect(line).toContain("the standardized block");
       expect(line).toContain("Advance via the /pp menu");
@@ -58,6 +58,18 @@ describe("completionLine", () => {
   it("autonomous phases do not emit the prose closing block", () => {
     expect(completionLine("brainstorm", "autonomous")).not.toContain("Advance via the /pp menu");
   });
+
+  it("quick phase does not self-complete for a mere question/answer", () => {
+    const line = completionLine("quick", "guided");
+    expect(line).toContain("ONLY after you have actually performed the requested work");
+    expect(line).toMatch(/do NOT call pp_phase_complete/i);
+    expect(line).toContain("/pp");
+  });
+
+  it("quick phase still self-completes after real work", () => {
+    const line = completionLine("quick", "guided");
+    expect(line).toContain("call pp_phase_complete");
+  });
 });
 
 describe("closingBlockInstruction", () => {
@@ -79,8 +91,8 @@ describe("closingBlockInstruction", () => {
     expect(review.indexOf("## Review Summary")).toBeLessThan(review.indexOf("✅ <one-sentence summary"));
   });
 
-  it("does NOT emit the Review Summary schema for brainstorm or debug closes", () => {
-    for (const phase of ["brainstorm", "debug"] as const) {
+  it("does NOT emit the Review Summary schema for brainstorm closes", () => {
+    for (const phase of ["brainstorm"] as const) {
       expect(closingBlockInstruction(phase)).not.toContain("## Review Summary");
     }
   });
@@ -98,11 +110,32 @@ describe("constraintsBlock", () => {
     expect(block).toContain("call pp_phase_complete");
   });
 
-  it("guided brainstorm/review/debug blocks embed the /pp banner exception", () => {
-    for (const phase of ["brainstorm", "review", "debug"] as const) {
+  it("guided brainstorm/review blocks embed the /pp banner exception", () => {
+    for (const phase of ["brainstorm", "review"] as const) {
       const block = constraintsBlock(phase, "guided");
       expect(block).toContain("a /pp menu banner");
       expect(block).toContain("e.g. an auto-review loop");
     }
   });
+
+  it("guided phases tell the agent to ask rather than silently assume", () => {
+    for (const phase of ["brainstorm", "plan", "implement", "review"] as const) {
+      const block = constraintsBlock(phase, "guided");
+      expect(block).toContain("do NOT silently assume");
+      expect(block).toContain("ask the");
+      expect(block).not.toContain("artifacts/ASSUMPTIONS.md");
+    }
+  });
+
+  it("autonomous phases record unverified assumptions in artifacts/ASSUMPTIONS.md with the fixed fields", () => {
+    for (const phase of ["brainstorm", "plan", "implement", "review"] as const) {
+      const block = constraintsBlock(phase, "autonomous");
+      expect(block).toContain("artifacts/ASSUMPTIONS.md");
+      for (const field of ["statement", "confidence", "basis", "invalidation test", "decision impact"]) {
+        expect(block).toContain(field);
+      }
+      expect(block).toContain("_No open assumptions._");
+      expect(block).toContain("never fabricate");
+    }
+  });
 });

package/extensions/orchestrator/agents/constraints.ts

@@ -26,8 +26,30 @@ const UNIVERSAL_RULES = [
   "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, then get explicit approval. Don't silently invent and bury such choices.",
 ].join("\n");
 
+// Assumption-surfacing (#B). Interactive phases: ask instead of guessing. Autonomous
+// phases have no one to ask, so every unverified assumption is logged to the optional
+// artifacts/ASSUMPTIONS.md (absent = none) with a fixed field shape, and the end-of-run
+// summary lists them all. Mode-aware because the two behaviors are mutually exclusive.
+function assumptionsRule(mode: TaskMode): string {
+  if (mode === "autonomous") {
+    return (
+      "Assumptions: there is no one to ask, so do NOT silently assume. Whenever you commit to an " +
+      "unverified assumption, append it to artifacts/ASSUMPTIONS.md (create it on first use) as one list " +
+      "item with these exact fields — statement, confidence (low/med/high), basis, invalidation test, " +
+      "decision impact — and a status marker (open/resolved); update the marker to resolved when you later " +
+      "confirm or refute it, keeping the entry. If a phase has no open assumptions the file may be absent " +
+      "or contain only `_No open assumptions._` — never fabricate entries."
+    );
+  }
+  return (
+    "Assumptions: do NOT silently assume. When a decision hinges on something you are not sure of, ask the " +
+    "user (a focused ask_user) rather than guessing. If you must proceed on an unverified assumption, state " +
+    "it plainly to the user so they can correct it."
+  );
+}
+
 export function isReadOnlyPhase(phase: Phase): boolean {
-  return phase === "brainstorm" || phase === "debug" || phase === "review" || phase === "plan";
+  return phase === "brainstorm" || phase === "review" || phase === "plan";
 }
 
 export function phaseConstraint(phase: Phase): string {
@@ -37,13 +59,12 @@ export function phaseConstraint(phase: Phase): string {
   return READONLY_CONSTRAINT;
 }
 
-// Guided phases that stop and hand back to the user (brainstorm, review, debug) end their turn
+// Guided phases that stop and hand back to the user (brainstorm, review) end their turn
 // with prose rather than a tool call. To keep that handoff consistent, the model must close with
 // this exact block. NEXT_PHASE_LABEL supplies the phase the /pp menu advances into.
 const NEXT_PHASE_LABEL: Partial<Record<Phase, string>> = {
   brainstorm: "plan",
   review: "plan",
-  debug: "plan",
 };
 
 // The structured summary a review must print when it finishes, on BOTH review finish paths
@@ -91,7 +112,7 @@ export function closingBlockInstruction(phase: Phase): string {
 
 export function completionLine(phase: Phase, mode: TaskMode): string {
   if (phase === "quick") {
-    return "When the user's request is complete, call pp_phase_complete. Do NOT stop and wait for the user before then.";
+    return "Call pp_phase_complete ONLY after you have actually performed the requested work (an edit, a command, a produced artifact). If the turn merely answered a question or provided information with no action taken, do NOT call pp_phase_complete — end the turn with your answer, at most suggesting the user run /pp if they want to start a tracked task. When you did do the requested work, call pp_phase_complete and do NOT stop to wait for the user before then.";
   }
   if (mode === "autonomous") {
     return "There is no user driving this phase. The moment its work is complete, call pp_phase_complete — do NOT pause, ask for confirmation, or wait for input. Never end a turn with prose: every turn ends in a tool call.";
@@ -107,7 +128,6 @@ export function completionLine(phase: Phase, mode: TaskMode): string {
 
 const PHASE_IDENTITY: Record<string, string> = {
   brainstorm: "You clarify the request and research the codebase to produce USER_REQUEST.md and RESEARCH.md.",
-  debug: "You diagnose the problem and research the codebase to produce USER_REQUEST.md and RESEARCH.md — investigation only, no fixes.",
   plan: "You synthesize the planner outputs into one plan — you do not write a plan from scratch, and you do not implement.",
   implement: "You implement the approved plan.",
   review: "You review the code changes to produce USER_REQUEST.md and RESEARCH.md capturing the findings — you do not apply fixes.",
@@ -123,6 +143,7 @@ export function constraintsBlock(phase: Phase, mode: TaskMode): string {
     "These rules override your default helpfulness and any next step you infer. Strict compliance is required.",
     phaseConstraint(phase),
     UNIVERSAL_RULES,
+    assumptionsRule(mode),
     completionLine(phase, mode),
     "</constraints>",
   ].join("\n");

package/extensions/orchestrator/agents/deep-debugger.ts

@@ -8,7 +8,7 @@ export function createDeepDebuggerAgent(entry: PoolEntry) {
   const info = getModelInfo(model);
   return {
     frontmatter: {
-      description: "Deep root-cause analysis for HARD, persistent failures — not every error (pi-pi)",
+      description: "Diagnoses the root cause of a HARD, persistent failure and returns a diagnosis (it does NOT apply the fix) — best when a bug resists the obvious fix; not every error, and not for trivial/obvious failures (pi-pi)",
       tools,
       model,
       thinking: entry.thinking,
@@ -29,11 +29,12 @@ export function createDeepDebuggerAgent(entry: PoolEntry) {
       toolsBlock(parseToolNames(tools)),
       "",
       "<task>",
-      "- Reproduce/inspect first: run the failing command, read the actual error and stack trace, check recent changes (git diff, cbm_changes).",
-      "- Form competing hypotheses. For each, gather evidence FOR and AGAINST with tool calls. Do not commit to the first plausible cause.",
-      "- Trace the failure to its true root, not the surface symptom. Use lsp findReferences / cbm_trace to follow the chain.",
-      "- Report: Symptom → Hypotheses considered (with evidence) → Root cause (with file:line proof) → Minimal recommended fix.",
-      "- If you cannot prove the root cause, say so: report the narrowed-down suspects and the single most useful next probe.",
+      "Work the phases in order — no fix recommendation until root cause is established:",
+      "1. INVESTIGATE: reproduce/inspect first — run the failing command, read the actual error and stack trace, check recent changes (git diff, cbm_changes). Trace the failure to its true root, not the surface symptom, using lsp findReferences / cbm_trace to follow the chain to its source.",
+      "2. PATTERN ANALYSIS: form competing hypotheses; for each, gather evidence FOR and AGAINST with tool calls. Do not commit to the first plausible cause.",
+      "3. HYPOTHESIS: commit to a SINGLE hypothesis stated as 'X is the root cause because Y', then test it by changing ONE variable at a time — don't change several things at once.",
+      "4. RECOMMEND: report Symptom → Hypotheses considered (with evidence) → Root cause (with file:line proof) → Minimal recommended fix.",
+      "Apply this discipline ESPECIALLY under time pressure or when the issue looks simple enough to 'just fix' — that is when skipping investigation causes the most wasted work. If you cannot prove the root cause, say so plainly (do NOT pretend to know): report the narrowed-down suspects and the single most useful next probe.",
       "</task>",
     ].join("\n"),
   };

package/extensions/orchestrator/agents/explore.ts

@@ -9,7 +9,7 @@ export function createExploreAgent(config: PiPiConfig) {
   const info = getModelInfo(model);
   return {
     frontmatter: {
-      description: "Codebase explorer (pi-pi)",
+      description: "Finds where code lives and how a flow connects across files — best for locating symbols, tracing usages, and mapping a subsystem; not for design judgment or applying edits (pi-pi)",
       tools,
       model,
       thinking,

package/extensions/orchestrator/agents/librarian.ts

@@ -9,7 +9,7 @@ export function createLibrarianAgent(config: PiPiConfig) {
   const info = getModelInfo(model);
   return {
     frontmatter: {
-      description: "External docs researcher (pi-pi)",
+      description: "Researches external libraries, APIs, and framework docs from the web and installed packages — best when the answer lives outside this repo; not for searching this codebase (use explore) or applying edits (pi-pi)",
       tools,
       model,
       thinking,

package/extensions/orchestrator/agents/planner.ts

@@ -54,7 +54,7 @@ export function createPlannerAgent(
       "- 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 whenever the task adds a type, function, parser, annotation, config key, enum, or user-facing value. For each, name the CLOSEST EXISTING analog (found by behavior, not filename) and the conventions the implementer MUST mirror: data shape (prefer one existing shape over parallel/duplicated state), spelling/casing of user-facing values (match existing — never invent a new casing), and parser/validation/error-handling shape. Acceptance criteria, not suggestions. Omit only if the task adds none of the above.",
       "- ## Blockers: unresolved issues blocking implementation (omit if none)",
       "- No other top-level sections allowed",

package/extensions/orchestrator/agents/prompts.test.ts

@@ -1,10 +1,12 @@
 import { describe, expect, it } from "vitest";
 import { getDefaultConfig, resolvePreset } from "../config.js";
-import { delegationBlock, toolsBlock, parseToolNames } from "./tool-routing.js";
+import { delegationBlock, toolsBlock, parseToolNames, PRINCIPLES_BLOCK, IMPLEMENTATION_PRINCIPLES_BLOCK } from "./tool-routing.js";
 import { createAdvisorAgent } from "./advisor.js";
 import { createDeepDebuggerAgent } from "./deep-debugger.js";
 import { createReviewerAgent } from "./reviewer.js";
 import { createTaskAgent } from "./task.js";
+import { createExploreAgent } from "./explore.js";
+import { createLibrarianAgent } from "./librarian.js";
 import { createPlannerAgent } from "./planner.js";
 import { createPlanReviewerAgent } from "./plan-reviewer.js";
 import { createCodeReviewerAgent } from "./code-reviewer.js";
@@ -61,6 +63,66 @@ describe("toolsBlock only advertises granted tools", () => {
   });
 });
 
+describe("PRINCIPLES_BLOCK degrees-of-freedom split", () => {
+  it("implementation-only code-style rules live in the implementation block, not the shared block", () => {
+    for (const phrase of [
+      "NEVER comment a private (non-exported) symbol",
+      "volatile detail",
+      "Prefer fewer, larger functions",
+      "inline it",
+      "Keep everything as private as possible",
+      "DO NOT WRITE COMMENTS",
+      "No temporary artifacts",
+      "Smallest viable change",
+      "Understand before modifying",
+    ]) {
+      expect(IMPLEMENTATION_PRINCIPLES_BLOCK).toContain(phrase);
+      expect(PRINCIPLES_BLOCK).not.toContain(phrase);
+    }
+  });
+
+  it("shared reasoning/evidence rules stay in the shared block", () => {
+    for (const phrase of ["Verify, don't assume", "Evidence over claims", "Match existing patterns", "Think critically"]) {
+      expect(PRINCIPLES_BLOCK).toContain(phrase);
+    }
+  });
+
+  const planners = resolvePreset(config, "planners");
+  const artifacts = { userRequest: "u", research: "r", manifest: [] as { title: string; path: string }[] };
+  const readOnlyFactories: [string, { prompt: string }][] = [
+    ["explore", createExploreAgent(config)],
+    ["librarian", createLibrarianAgent(config)],
+    ["advisor", createAdvisorAgent({ model: "anthropic/claude-fable-latest", thinking: "high" })],
+    ["deep-debugger", createDeepDebuggerAgent({ model: "openai/gpt-latest", thinking: "high" })],
+    ["reviewer", createReviewerAgent({ model: "openai/gpt-latest", thinking: "high" })],
+    ["planner", createPlannerAgent("opus", planners, artifacts, "/out.md", [])],
+    ["plan-reviewer", createPlanReviewerAgent("opus", resolvePreset(config, "planReviewers"), { userRequest: "u", research: "r", synthesizedPlan: "p", manifest: [] }, "/out.md", [])],
+    ["code-reviewer", createCodeReviewerAgent("opus", resolvePreset(config, "codeReviewers"), { userRequest: "u", research: "r", synthesizedPlan: "p", manifest: [] }, "/out.md", [])],
+    ["brainstorm-reviewer", createBrainstormReviewerAgent("opus", resolvePreset(config, "brainstormReviewers"), artifacts, "/out.md", [])],
+  ];
+
+  it("the shared block is embedded in ALL ten agent factory prompts", () => {
+    const all = [...readOnlyFactories.map(([, f]) => f), createTaskAgent(config)];
+    for (const f of all) {
+      expect(f.prompt).toContain("Evidence over claims");
+      expect(f.prompt).toContain("Verify, don't assume");
+    }
+  });
+
+  it("read-only factories do NOT carry implementation-only code-style rules", () => {
+    for (const [, f] of readOnlyFactories) {
+      expect(f.prompt).not.toContain("Keep everything as private as possible");
+      expect(f.prompt).not.toContain("NEVER comment a private (non-exported) symbol");
+    }
+  });
+
+  it("the edit-capable task factory DOES carry implementation-only code-style rules", () => {
+    const t = createTaskAgent(config);
+    expect(t.prompt).toContain("Keep everything as private as possible");
+    expect(t.prompt).toContain("NEVER comment a private (non-exported) symbol");
+  });
+});
+
 describe("new free-form agent factories", () => {
   it("advisor is read-only (no write/edit) and reasons in Diagnosis/Options/Recommendation", () => {
     const a = createAdvisorAgent({ model: "anthropic/claude-fable-latest", thinking: "high" });
@@ -160,3 +222,75 @@ describe("phased factory prompts: manifest guidance replaces the do-not-re-read
     expect(b.prompt).toContain("read them from disk with the read tool");
   });
 });
+
+describe("routing-contract descriptions (what / when / exclusion)", () => {
+  it("explore, librarian, and task descriptions state a fit and an exclusion, third person, with the (pi-pi) suffix", () => {
+    const descs = {
+      explore: createExploreAgent(config).frontmatter.description,
+      librarian: createLibrarianAgent(config).frontmatter.description,
+      task: createTaskAgent(config).frontmatter.description,
+    };
+    for (const d of Object.values(descs)) {
+      expect(d).toContain("best");
+      expect(d).toMatch(/not for|not when/i);
+      expect(d.endsWith("(pi-pi)")).toBe(true);
+    }
+    expect(descs.explore).toMatch(/locat|find|trac/i);
+    expect(descs.librarian).toMatch(/external|docs|librar/i);
+    expect(descs.task).toMatch(/implementation|slice/i);
+  });
+
+  it("extends the advisor / deep-debugger / reviewer descriptions with what+when+exclusion, preserving protected exclusions", () => {
+    const advisor = createAdvisorAgent({ model: "anthropic/claude-fable-latest", thinking: "high" }).frontmatter.description;
+    const debugger_ = createDeepDebuggerAgent({ model: "openai/gpt-latest", thinking: "high" }).frontmatter.description;
+    const reviewer = createReviewerAgent({ model: "openai/gpt-latest", thinking: "high" }).frontmatter.description;
+    for (const d of [advisor, debugger_, reviewer]) {
+      expect(d).toMatch(/not for|not every|not as|never/i);
+      expect(d.endsWith("(pi-pi)")).toBe(true);
+    }
+    expect(debugger_).toContain("not every error");
+    expect(reviewer).toContain("only when the user asks");
+    expect(advisor).toMatch(/judgment|tradeoff|why is this broken/i);
+  });
+
+  it("delegationBlock remains the sole owner of numeric routing thresholds", () => {
+    const pools = {
+      advisors: [{ name: "advisor_x_high", model: "anthropic/claude-fable-latest", family: "fable", tier: "xsmart", thinking: "high" }],
+      reviewers: [{ name: "reviewer_y_high", model: "openai/gpt-latest", family: "gpt", tier: "smart", thinking: "high" }],
+      deepDebuggers: [{ name: "deep-debugger_z_high", model: "openai/gpt-latest", family: "gpt", tier: "smart", thinking: "high" }],
+    };
+    expect(delegationBlock("opus", pools)).toContain("2–3 parallel");
+    expect(delegationBlock("opus", pools)).toContain("4+ only");
+    for (const d of [createExploreAgent(config).frontmatter.description, createTaskAgent(config).frontmatter.description]) {
+      expect(d).not.toMatch(/2–3|4\+/);
+    }
+  });
+});
+
+describe("affordance-aligned evidence gates", () => {
+  it("the edit-capable task delegate carries the evidence gate + N/A path", () => {
+    const t = createTaskAgent(config);
+    expect(t.prompt).toContain("Verification gate");
+    expect(t.prompt).toContain("not applicable");
+    expect(t.prompt).toMatch(/in any language/i);
+  });
+
+  it("read-only reviewer / code-reviewer restrict evidence to what their tools can produce", () => {
+    const r = createReviewerAgent({ model: "openai/gpt-latest", thinking: "high" });
+    const c = createCodeReviewerAgent("opus", resolvePreset(config, "codeReviewers"), { userRequest: "u", research: "r", synthesizedPlan: "p", manifest: [] }, "/out.md", []);
+    for (const p of [r.prompt, c.prompt]) {
+      expect(p).toMatch(/MUST NOT run tests|not run test suites/i);
+      expect(p).toMatch(/OPEN QUESTIONS|Open Questions/);
+    }
+  });
+});
+
+describe("advisor anti-sycophancy", () => {
+  it("requires taking a position + naming what would change it, behavior-framed with any quoted phrase marked as an example", () => {
+    const a = createAdvisorAgent({ model: "anthropic/claude-fable-latest", thinking: "high" }).prompt;
+    expect(a).toContain("Take a position");
+    expect(a).toMatch(/what evidence would change|what would change/i);
+    expect(a).toMatch(/in any language|targets the behavior/i);
+    expect(a).toMatch(/illustrative anti-patterns[^\n]{0,40}'that could work'/);
+  });
+});

package/extensions/orchestrator/agents/reviewer.ts

@@ -8,7 +8,7 @@ export function createReviewerAgent(entry: PoolEntry) {
   const info = getModelInfo(model);
   return {
     frontmatter: {
-      description: "Code reviewer for changes/diffs with severity-rated findings — spawn only when the user asks for a review (pi-pi)",
+      description: "Read-only code reviewer that inspects a change/diff and returns severity-rated findings with file:line anchors (never edits) — best for a focused review of completed work; spawn only when the user asks for a review, not as a routine step (pi-pi)",
       tools,
       model,
       thinking: entry.thinking,
@@ -38,7 +38,7 @@ export function createReviewerAgent(entry: PoolEntry) {
       "",
       "Review criteria: logic errors, off-by-ones, null/edge handling, race conditions; correctness vs intent; error handling and type safety; missing or untested paths.",
       "",
-      "Evidence: every CRITICAL or MAJOR finding MUST cite file:line or quoted code. Never assert a problem without reading the code. Low-confidence concerns go under OPEN QUESTIONS.",
+      "Evidence: every CRITICAL or MAJOR finding MUST cite file:line or quoted code. Never assert a problem without reading the code. You are read-only and MUST NOT run tests/builds, so support each finding ONLY with what your granted tools can produce — the diff, the code you read, and lsp diagnostics. If a concern cannot be proven with those (it would need a test run, build, or runtime output you cannot obtain), do NOT assert it as a finding: move it to OPEN QUESTIONS and state what evidence would settle it.",
       "",
       "Format — verdict on the FIRST LINE, then:",
       "VERDICT: APPROVE | NEEDS_CHANGES",

package/extensions/orchestrator/agents/task.ts

@@ -1,6 +1,6 @@
 import type { PiPiConfig } from "../config.js";
 import { getModelInfo, resolveModel } from "../model-registry.js";
-import { toolsBlock, parseToolNames, identityBlock, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK, FAILURE_RECOVERY } from "./tool-routing.js";
+import { toolsBlock, parseToolNames, identityBlock, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK, IMPLEMENTATION_PRINCIPLES_BLOCK, FAILURE_RECOVERY } from "./tool-routing.js";
 
 export function createTaskAgent(config: PiPiConfig) {
   const model = resolveModel(config.agents.subagents.simple.task.model);
@@ -9,7 +9,7 @@ export function createTaskAgent(config: PiPiConfig) {
   const info = getModelInfo(model);
   return {
     frontmatter: {
-      description: "Implementation subtask (pi-pi)",
+      description: "Carries out a self-contained, parallelizable implementation slice end to end — best for a well-scoped chunk you could hand off; not for open-ended design, whole-task ownership, or work you're mid-edit on yourself (pi-pi)",
       tools,
       model,
       thinking,
@@ -29,6 +29,8 @@ export function createTaskAgent(config: PiPiConfig) {
       "",
       PRINCIPLES_BLOCK,
       "",
+      IMPLEMENTATION_PRINCIPLES_BLOCK,
+      "",
       toolsBlock(parseToolNames(tools)),
       "",
       FAILURE_RECOVERY,
@@ -40,6 +42,8 @@ export function createTaskAgent(config: PiPiConfig) {
       "  Do NOT spawn task, advisor, deep-debugger, or reviewer subagents.",
       "- Before modifying a function, use lsp findReferences to understand all callers",
       "- After editing files, run lsp diagnostics and fix errors before moving on",
+      "- Verification gate: before reporting your subtask done, produce fresh tool output that proves it (lsp diagnostics clean, a passing test, expected cbm_changes) and cite it. The gate is on whether that proving evidence EXISTS, not on wording, so it holds in any language. If a claim cannot be proven with your granted tools, say so and state why (\"not applicable — <reason>\") rather than implying verification.",
+      "- Test-first policy (conditional): for a behavior change or bug fix where an automated test is feasible, write/reproduce the FAILING test first, then make it pass; otherwise state the verification method before editing. No universal test-first mandate and no delete-untested-code rule — choose the path that produces real evidence.",
       "- Your subtask and task context (USER_REQUEST, RESEARCH, and a manifest of additional documents) are provided in the spawn message. Read the manifested files from disk if relevant.",
       "</task>",
     ].join("\n"),

package/extensions/orchestrator/agents/tool-routing.ts

@@ -4,10 +4,6 @@ export const EXA_TOOLS = "exa_search, exa_fetch";
 export const PRINCIPLES_BLOCK = [
   "<principles>",
   "- Verify, don't assume. Check actual state with tools before making changes. Never guess paths, types, or APIs.",
-  "- Understand before modifying. Read the code, trace callers, check types BEFORE editing. Compiling ≠ correct.",
-  "- Smallest viable change. Do what was asked, nothing more. Don't broaden scope, don't refactor adjacent code.",
-  "- No temporary artifacts. No console.log, TODO, HACK, debugger, or commented-out code left behind.",
-  "- DO NOT WRITE COMMENTS. This is a hard rule, not a preference. Almost every comment an LLM writes is noise: it restates the code, repeats the function/variable name, narrates the obvious, or labels sections. NEVER write any of those. The ONLY allowed comments are (1) a genuine WHY that the code cannot express — a non-obvious constraint, workaround, or gotcha a reader would otherwise get wrong, or (2) required public-API/doc-comment syntax. If a comment restates WHAT the code does, delete it. When unsure, do not comment. Match the existing comment density of the surrounding code — if neighbors have none, add none.",
   "- Evidence over claims. 'It should work' is not proof. Show fresh tool output (lsp diagnostics, test results, build output).",
   "- Match existing patterns. Before adding a type, function, or user-facing value, find how the codebase already solves the most similar problem — search by behavior, not by filename — and mirror its shape, naming, error handling, and conventions. Reading one neighboring file is not enough.",
   "- Be concise and dense: minimum words, no preamble/filler/restatement. Don't narrate what you're about to do or just did.",
@@ -15,6 +11,24 @@ export const PRINCIPLES_BLOCK = [
   "</principles>",
 ].join("\n");
 
+// Implementation-only code-style rules. Injected ONLY into agents that edit project
+// source (the task subagent, and the main agent in edit-capable phases). Read-only
+// judges (explore, librarian, advisor, reviewer, code-reviewer, plan-reviewer,
+// brainstorm-reviewer, planner, deep-debugger) do NOT carry these — the deep-debugger
+// has write/edit for throwaway diagnostics only, so it is intentionally read-only for
+// PROJECT-SOURCE purposes and receives only the shared block above.
+export const IMPLEMENTATION_PRINCIPLES_BLOCK = [
+  "<implementation_principles>",
+  "- Understand before modifying. Read the code, trace callers, check types BEFORE editing. Compiling ≠ correct.",
+  "- Smallest viable change. Do what was asked, nothing more. Don't broaden scope, don't refactor adjacent code.",
+  "- No temporary artifacts. No console.log, TODO, HACK, debugger, or commented-out code left behind.",
+  "- DO NOT WRITE COMMENTS. This is a hard rule, not a preference. Almost every comment an LLM writes is noise: it restates the code, repeats the function/variable name, narrates the obvious, or labels sections. NEVER write any of those. The ONLY allowed comments are (1) a genuine WHY that the code cannot express — a non-obvious constraint, workaround, or gotcha a reader would otherwise get wrong, or (2) required public-API/doc-comment syntax. If a comment restates WHAT the code does, delete it. When unsure, do not comment. Match the existing comment density of the surrounding code — if neighbors have none, add none.",
+  "- NEVER comment a private (non-exported) symbol. Also NEVER write a comment that embeds volatile detail that drifts out of date — flag/option names, constant values, or a restatement of what a flag/function does. A WHY comment survives refactors; a WHAT comment rots. If the only thing a comment adds is a name or a value already in the code, delete it.",
+  "- Prefer fewer, larger functions over many tiny ones. Do NOT extract a helper used in only one place just to name a step — inline it. Extract only when it removes real duplication or the extracted unit is independently meaningful and reused. A one-line or single-caller helper is usually noise.",
+  "- Keep everything as private as possible. Default to non-exported/file-local (or the language's most restricted visibility). Export or widen visibility ONLY when a symbol genuinely needs cross-module use — never 'just in case' or to make a test reach an internal.",
+  "</implementation_principles>",
+].join("\n");
+
 export const FAILURE_RECOVERY = [
   "# Failure recovery",
   "",
@@ -54,8 +68,10 @@ const TOOL_SEGMENTS: ToolSegment[] = [
         text:
           "**pp_checkout_pr_head** (review phase, PR-scoped only): after resolving a repo's PR (e.g. `gh pr view " +
           "--json headRefName,headRefOid`), call this once per repo to land it on its PR head before reviewing. " +
-          "The extension fast-forwards a clean branch to the head; if the tree is dirty, on a different branch, or " +
-          "diverged it HALTS and returns a message to relay to the user. Do NOT call it for a " +
+          "On a clean tree the extension fast-forwards the PR head's branch when behind, or switches to it from a " +
+          "different branch after fetching origin and verifying the fetched tip matches the PR head commit; if the " +
+          "tree is dirty, HEAD is detached, the branch has diverged, or the head is on a fork/unfetchable ref it " +
+          "HALTS and returns a message to relay to the user. Do NOT call it for a " +
           "branch/commit-range/uncommitted-changes review, and never run `git checkout` yourself.",
       },
     ],