@ilya-lesikov/pi-pi 0.7.0 → 0.9.0

package/extensions/orchestrator/agents/planner.ts

@@ -1,5 +1,5 @@
 import type { VariantConfig } from "../config.js";
-import { loadAllContextFiles } from "../context.js";
+import { loadAllContextFiles, formatManifestBlock } from "../context.js";
 import { resolveModel, getModelInfo } from "../model-registry.js";
 import type { RepoInfo } from "../repo-utils.js";
 import { buildRepoContext } from "./repo-context.js";
@@ -8,7 +8,7 @@ import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-
 export function createPlannerAgent(
   variant: string,
   variants: Record<string, VariantConfig>,
-  taskArtifacts: { userRequest: string; research: string },
+  taskArtifacts: { userRequest: string; research: string; manifest?: { title: string; path: string }[] },
   outputPath: string,
   contextDirs: string[],
   phase?: string,
@@ -51,14 +51,15 @@ export function createPlannerAgent(
       "- ## 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.",
+      "- ## 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",
-      "- Describe outcomes, not code-level mechanics",
+      "- Describe outcomes, not code-level mechanics, EXCEPT in ## Pattern constraints where the concrete analog and conventions are required",
       "",
-      "subagent_type is REQUIRED when spawning subagents — calls without it are rejected:",
-    '- Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
-    '- Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
-    "Spawn multiple Explore agents in parallel for broad searches.",
+      "You may spawn ONLY explore/librarian subagents (subagent_type is REQUIRED — calls without it are rejected):",
+    '- Agent(subagent_type="explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+    '- Agent(subagent_type="librarian", ...) — external docs, library APIs, web research.',
+    "Spawn multiple explore agents in parallel for broad searches. Do NOT spawn task, advisor, deep-debugger, or reviewer.",
       "</task>",
       "",
       // --- dynamic suffix ---
@@ -74,7 +75,7 @@ export function createPlannerAgent(
       taskArtifacts.research,
       ...(repoContext ? [repoContext] : []),
       "",
-      "The artifacts above are already in your context. Do NOT re-read them from disk.",
+      formatManifestBlock(taskArtifacts.manifest ?? []),
     ].join("\n"),
   };
 }

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

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import { getDefaultConfig, resolvePreset } from "../config.js";
+import { DELEGATION_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 { createPlannerAgent } from "./planner.js";
+import { createPlanReviewerAgent } from "./plan-reviewer.js";
+import { createCodeReviewerAgent } from "./code-reviewer.js";
+import { createBrainstormReviewerAgent } from "./brainstorm-reviewer.js";
+
+const config = getDefaultConfig();
+
+describe("DELEGATION_BLOCK", () => {
+  it("covers all six free-form agents with lowercase registry names", () => {
+    for (const name of ["explore", "librarian", "task", "advisor", "deep-debugger", "reviewer"]) {
+      expect(DELEGATION_BLOCK).toContain(name);
+    }
+  });
+
+  it("states the reviewer and deep-debugger gating explicitly", () => {
+    expect(DELEGATION_BLOCK).toContain("ONLY when the user explicitly asks");
+    expect(DELEGATION_BLOCK).toMatch(/deep-debugger diagnoses/i);
+    expect(DELEGATION_BLOCK).toContain("must NOT write the actual fix");
+  });
+});
+
+describe("new free-form agent factories", () => {
+  it("advisor is read-only (no write/edit) and reasons in Diagnosis/Options/Recommendation", () => {
+    const a = createAdvisorAgent(config);
+    expect(a.frontmatter.tools).not.toContain("write");
+    expect(a.frontmatter.tools).not.toContain("edit");
+    expect(a.prompt).toContain("READ-ONLY");
+    expect(a.prompt).toContain("Diagnosis");
+    expect(a.prompt).toContain("Recommendation");
+  });
+
+  it("deep-debugger has write/edit but restricts writes to diagnosis only", () => {
+    const d = createDeepDebuggerAgent(config);
+    expect(d.frontmatter.tools).toContain("write");
+    expect(d.frontmatter.tools).toContain("edit");
+    expect(d.prompt).toContain("DIAGNOSIS ONLY");
+    expect(d.prompt).toContain("MUST NOT write the actual fix");
+  });
+
+  it("reviewer is read-only, retains bash for git diff, and is verdict-first", () => {
+    const r = createReviewerAgent(config);
+    expect(r.frontmatter.tools).toContain("bash");
+    expect(r.frontmatter.tools).not.toContain("write");
+    expect(r.frontmatter.tools).not.toContain("edit");
+    expect(r.prompt).toContain("git diff");
+    expect(r.prompt).toContain("VERY FIRST LINE");
+    expect(r.frontmatter.description).toContain("only when the user asks");
+  });
+});
+
+describe("task factory no longer bakes artifacts and stays explore/librarian-only", () => {
+  it("takes only config (no baked artifact arg) and does not inline USER REQUEST / SYNTHESIZED PLAN", () => {
+    expect(createTaskAgent.length).toBe(1);
+    const t = createTaskAgent(config);
+    expect(t.prompt).not.toContain("=== USER REQUEST ===");
+    expect(t.prompt).not.toContain("=== SYNTHESIZED PLAN ===");
+    expect(t.prompt).not.toContain("Do NOT re-read them from disk");
+    expect(t.prompt).toContain("ONLY explore/librarian");
+    expect(t.prompt).toContain("Do NOT spawn task, advisor, deep-debugger, or reviewer");
+  });
+});
+
+describe("phased factory prompts: manifest guidance replaces the do-not-re-read trailer", () => {
+  const planners = resolvePreset(config, "planners");
+  const planReviewers = resolvePreset(config, "planReviewers");
+  const codeReviewers = resolvePreset(config, "codeReviewers");
+  const brainstormReviewers = resolvePreset(config, "brainstormReviewers");
+  const manifest = [{ title: "Design Doc", path: "/t/artifacts/design.md" }];
+
+  it("planner lists manifest paths and restricts spawns to explore/librarian", () => {
+    const p = createPlannerAgent("opus", planners, { userRequest: "u", research: "r", manifest }, "/out.md", []);
+    expect(p.prompt).toContain("/t/artifacts/design.md");
+    expect(p.prompt).toContain("read them from disk with the read tool");
+    expect(p.prompt).toContain("Do NOT spawn task, advisor, deep-debugger, or reviewer");
+  });
+
+  it("plan-reviewer lists manifest paths and restricts spawns", () => {
+    const p = createPlanReviewerAgent(
+      "opus",
+      planReviewers,
+      { userRequest: "u", research: "r", synthesizedPlan: "p", manifest },
+      "/out.md",
+      [],
+    );
+    expect(p.prompt).toContain("/t/artifacts/design.md");
+    expect(p.prompt).toContain("Do NOT spawn task, advisor, deep-debugger, or reviewer");
+  });
+
+  it("code-reviewer lists manifest paths and restricts spawns", () => {
+    const c = createCodeReviewerAgent(
+      "opus",
+      codeReviewers,
+      { userRequest: "u", research: "r", synthesizedPlan: "p", manifest },
+      "/out.md",
+      [],
+    );
+    expect(c.prompt).toContain("/t/artifacts/design.md");
+    expect(c.prompt).toContain("Do NOT spawn task, advisor, deep-debugger, or reviewer");
+  });
+
+  it("brainstorm-reviewer restricts spawns and lists manifest paths when provided", () => {
+    const b = createBrainstormReviewerAgent(
+      "opus",
+      brainstormReviewers,
+      { userRequest: "u", research: "r", manifest },
+      "/out.md",
+      [],
+    );
+    expect(b.prompt).toContain("Do NOT spawn task, advisor, deep-debugger, or reviewer");
+    expect(b.prompt).toContain("/t/artifacts/design.md");
+    expect(b.prompt).toContain("read them from disk with the read tool");
+  });
+});

package/extensions/orchestrator/agents/reviewer.ts

@@ -0,0 +1,48 @@
+import type { PiPiConfig } from "../config.js";
+import { resolveModel } from "../model-registry.js";
+import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-routing.js";
+
+export function createReviewerAgent(config: PiPiConfig) {
+  return {
+    frontmatter: {
+      description: "Code reviewer for changes/diffs with severity-rated findings — spawn only when the user asks for a review (pi-pi)",
+      tools: `read, bash, grep, find, ls, lsp, ast_search, ${ALL_CBM_TOOLS}, ${EXA_TOOLS}`,
+      model: resolveModel(config.agents.subagents.simple.reviewer.model),
+      thinking: config.agents.subagents.simple.reviewer.thinking,
+      max_turns: 120,
+      prompt_mode: "replace",
+    },
+    prompt: [
+      "<constraints>",
+      "You are a code REVIEWER. You review implementation changes for bugs, correctness, and quality.",
+      "You are READ-ONLY: you MUST NOT implement, fix, or modify any source code.",
+      "Begin your review with the verdict on the VERY FIRST LINE: `VERDICT: APPROVE` or `VERDICT: NEEDS_CHANGES`.",
+      "</constraints>",
+      "",
+      PRINCIPLES_BLOCK,
+      "",
+      TOOLS_BLOCK,
+      "",
+      "<task>",
+      "Steps:",
+      "1. Run `git diff` to see all changes (try HEAD~1, main, or the appropriate base).",
+      "2. Run cbm_changes for symbol-level impact and blast radius.",
+      "3. Read changed files for full context; run lsp diagnostics on them.",
+      "4. Use lsp findReferences to check callers of modified functions.",
+      "",
+      "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.",
+      "",
+      "Format — verdict on the FIRST LINE, then:",
+      "VERDICT: APPROVE | NEEDS_CHANGES",
+      "- CRITICAL: (must fix — file:line evidence)",
+      "- MAJOR: (should fix — evidence)",
+      "- MINOR: (nice to have)",
+      "- OPEN QUESTIONS: (low-confidence / speculative)",
+      "",
+      "Return the full review as your result.",
+      "</task>",
+    ].join("\n"),
+  };
+}

package/extensions/orchestrator/agents/task.ts

@@ -2,11 +2,7 @@ import type { PiPiConfig } from "../config.js";
 import { resolveModel } from "../model-registry.js";
 import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK, FAILURE_RECOVERY } from "./tool-routing.js";
 
-export function createTaskAgent(
-  config: PiPiConfig,
-  subtaskDescription: string,
-  taskArtifacts: { userRequest: string; synthesizedPlan: string },
-) {
+export function createTaskAgent(config: PiPiConfig) {
   return {
     frontmatter: {
       description: "Implementation subtask (pi-pi)",
@@ -32,24 +28,14 @@ export function createTaskAgent(
       FAILURE_RECOVERY,
       "",
       "<task>",
-    "- subagent_type is REQUIRED when spawning subagents — calls without it are rejected:",
-    '  Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
-    '  Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
+      "- You may spawn ONLY explore/librarian subagents (subagent_type is REQUIRED — calls without it are rejected):",
+      '  Agent(subagent_type="explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
+      '  Agent(subagent_type="librarian", ...) — external docs, library APIs, web research.',
+      "  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",
+      "- 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>",
-      "",
-      // --- dynamic suffix ---
-      "=== YOUR SUBTASK ===",
-      subtaskDescription,
-      "",
-      "=== USER REQUEST (for context) ===",
-      taskArtifacts.userRequest,
-      "",
-      "=== SYNTHESIZED PLAN (for broader context) ===",
-      taskArtifacts.synthesizedPlan,
-      "",
-      "The artifacts above are already in your context. Do NOT re-read them from disk.",
     ].join("\n"),
   };
 }

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

@@ -7,8 +7,9 @@ export const PRINCIPLES_BLOCK = [
   "- 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. Mirror the codebase's naming, error handling, imports, and structure exactly.",
+  "- 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.",
   "- Think critically. Push back when something seems wrong, and state concerns before implementing.",
   "</principles>",
@@ -31,6 +32,12 @@ const TOOL_ROUTING_BODY = [
     "Pass the base branch (the branch this work will be merged into). Must call at the start of each task " +
     "before doing any work.",
   "",
+  "**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 " +
+    "branch/commit-range/uncommitted-changes review, and never run `git checkout` yourself.",
+  "",
   "Find code by concept or behavior:",
   "- Multi-repo: cbm_search, cbm_search_code, cbm_trace, cbm_changes accept optional project_path (absolute repo path). If omitted, they use the root project.",
   "- cbm_search: natural-language search (query='deploy release chart')",
@@ -76,3 +83,34 @@ const TOOL_ROUTING_BODY = [
 ];
 
 export const TOOLS_BLOCK = ["<tools>", ...TOOL_ROUTING_BODY, "</tools>"].join("\n");
+
+// Single source of truth for main-agent delegation guidance. Injected into the MAIN
+// agent prompt in every phase. Registry-consistent lowercase agent names.
+export const DELEGATION_BLOCK = [
+  "<delegation>",
+  "Prefer delegating over doing wide or deep work yourself. Subagents run in parallel, dig",
+  "deeper, and keep YOUR context clean. subagent_type is REQUIRED (calls without it are rejected).",
+  "",
+  "USE a subagent when:",
+  '- Locating code / mapping a flow ("where is X", "how does Y connect")        → explore',
+  "- External library / API / framework knowledge                               → librarian",
+  '- A judgment call (design tradeoff, "is this correct", "why is this broken")  → advisor',
+  "- A test/build that keeps failing after one real attempt                      → deep-debugger",
+  "- A self-contained, parallelizable implementation slice                       → task",
+  "- A code review of your changes — ONLY when the user explicitly asks          → reviewer",
+  "",
+  "If a task is broad or multi-part (investigate/analyze/refactor/audit/migrate a system,",
+  "subsystem, flow, or the codebase — anything not pinned to one known file/symbol), OPEN with",
+  "2–3 parallel `explore` subagents before reading code yourself. Use 4+ only for audits,",
+  "migrations, or multi-repo/system work. Give each explore an orthogonal prompt (no duplicate",
+  "mapping). explore FINDS; advisor JUDGES.",
+  "",
+  "Do NOT delegate when:",
+  "- You already know the exact file/symbol — just read/edit it directly.",
+  "- The task is a single narrow change or a trivial lookup (delegation overhead > work).",
+  "- You are mid-edit on a file you understand — keep going; don't spawn to \"map\" it.",
+  "- deep-debugger for a trivial/obvious error, or advisor for a plain lookup.",
+  "deep-debugger diagnoses only — it must NOT write the actual fix. Do NOT spawn reviewer unless",
+  "the user explicitly asks (the automatic review panel already covers implement/review phases).",
+  "</delegation>",
+].join("\n");

package/extensions/orchestrator/ai-comment-cleanup.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from "vitest";
+import { stripAiCommentsFromContent, isAiCommentOnlyChange } from "./ai-comment-cleanup.js";
+
+describe("stripAiCommentsFromContent", () => {
+  it("drops full-line AI_COMMENT markers in various comment syntaxes", () => {
+    const input = [
+      "const x = 1;",
+      "// AI_COMMENT: this is wrong",
+      "  # AI_COMMENT: python style",
+      "<!-- AI_COMMENT: markdown -->",
+      "-- AI_COMMENT: sql style",
+      "const y = 2;",
+    ].join("\n");
+    const { content, removed } = stripAiCommentsFromContent(input);
+    expect(removed).toBe(4);
+    expect(content).toBe(["const x = 1;", "const y = 2;"].join("\n"));
+  });
+
+  it("strips a trailing AI_COMMENT marker but keeps the code", () => {
+    const input = "const z = 3; // AI_COMMENT: off-by-one?";
+    const { content, removed } = stripAiCommentsFromContent(input);
+    expect(removed).toBe(1);
+    expect(content).toBe("const z = 3;");
+  });
+
+  it("leaves prose that merely mentions the token untouched", () => {
+    const input = "This paragraph explains what AI_COMMENT: means in docs.";
+    const { content, removed } = stripAiCommentsFromContent(input);
+    expect(removed).toBe(0);
+    expect(content).toBe(input);
+  });
+
+  it("is a no-op when no token present", () => {
+    const input = "line one\nline two";
+    expect(stripAiCommentsFromContent(input)).toEqual({ content: input, removed: 0 });
+  });
+
+  it("does NOT corrupt a marker that lives inside a string literal", () => {
+    const cases = [
+      `const s = "// AI_COMMENT: example";`,
+      `const AI_COMMENT_MARKER_SYNTAX = "// AI_COMMENT: ...";`,
+      `log('# AI_COMMENT: note');`,
+      "const t = `<!-- AI_COMMENT: x -->`;",
+    ];
+    for (const input of cases) {
+      expect(stripAiCommentsFromContent(input)).toEqual({ content: input, removed: 0 });
+    }
+  });
+
+  it("strips a real trailing marker even when the code has an earlier closed string", () => {
+    const input = `url = "http://x"; // AI_COMMENT: note`;
+    const { content, removed } = stripAiCommentsFromContent(input);
+    expect(removed).toBe(1);
+    expect(content).toBe(`url = "http://x";`);
+  });
+});
+
+describe("isAiCommentOnlyChange", () => {
+  it("allows inserting an AI_COMMENT marker line", () => {
+    const before = "const x = 1;\nconst y = 2;";
+    const after = "const x = 1;\n// AI_COMMENT: off-by-one?\nconst y = 2;";
+    expect(isAiCommentOnlyChange(before, after)).toBe(true);
+  });
+
+  it("allows removing an AI_COMMENT marker line", () => {
+    const before = "const x = 1;\n// AI_COMMENT: note\nconst y = 2;";
+    const after = "const x = 1;\nconst y = 2;";
+    expect(isAiCommentOnlyChange(before, after)).toBe(true);
+  });
+
+  it("allows a trailing AI_COMMENT marker", () => {
+    expect(isAiCommentOnlyChange("const x = 1;", "const x = 1; // AI_COMMENT: hm")).toBe(true);
+  });
+
+  it("rejects an actual code change", () => {
+    expect(isAiCommentOnlyChange("const x = 1;", "const x = 2;")).toBe(false);
+  });
+
+  it("rejects a fix disguised alongside a marker", () => {
+    const before = "const x = 1;";
+    const after = "const x = 2; // AI_COMMENT: fixed";
+    expect(isAiCommentOnlyChange(before, after)).toBe(false);
+  });
+
+  it("treats an identical write as allowed", () => {
+    expect(isAiCommentOnlyChange("same", "same")).toBe(true);
+  });
+});
+

package/extensions/orchestrator/ai-comment-cleanup.ts

@@ -0,0 +1,73 @@
+export const AI_COMMENT_TOKEN = "AI_COMMENT:";
+
+// Remove reviewer→user `AI_COMMENT:` markers from a single file's content.
+// - A line whose comment content is ONLY an AI_COMMENT marker is dropped entirely
+//   (covers `// AI_COMMENT: ...`, `#`, `--`, `;`, `<!-- ... -->`, `/* ... */`).
+// - A code line with a trailing `<comment-open> AI_COMMENT: ...` is stripped back
+//   to the code, dropping the trailing marker only.
+// Anything else containing the token is left untouched (do not corrupt prose).
+// True when `prefix` ends inside an unclosed string literal (single, double, or
+// backtick quote). Used to avoid stripping a `// AI_COMMENT:` that lives inside a
+// string rather than being a real trailing comment. Escaped quotes are honored.
+function insideStringLiteral(prefix: string): boolean {
+  let quote: string | null = null;
+  for (let i = 0; i < prefix.length; i++) {
+    const ch = prefix[i];
+    if (ch === "\\") {
+      i++;
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+    }
+  }
+  return quote !== null;
+}
+
+export function stripAiCommentsFromContent(content: string): { content: string; removed: number } {
+  if (!content.includes(AI_COMMENT_TOKEN)) return { content, removed: 0 };
+  const lines = content.split("\n");
+  const out: string[] = [];
+  let removed = 0;
+
+  const fullLineComment = /^\s*(?:\/\/+|#+|--|;+|\/\*|<!--)\s*AI_COMMENT:.*?(?:\*\/|-->)?\s*$/;
+  const trailingComment = /(\s*(?:\/\/+|#+|--|;+|\/\*|<!--)\s*AI_COMMENT:.*?(?:\*\/|-->)?)\s*$/;
+
+  for (const line of lines) {
+    if (!line.includes(AI_COMMENT_TOKEN)) {
+      out.push(line);
+      continue;
+    }
+    if (fullLineComment.test(line)) {
+      removed += 1;
+      continue;
+    }
+    const match = trailingComment.exec(line);
+    // Only strip a trailing marker when the code BEFORE the comment opener has
+    // balanced quotes — otherwise the "// AI_COMMENT:" is inside a string literal
+    // (e.g. `const s = "// AI_COMMENT: x"`) and stripping it would corrupt source.
+    if (match && !insideStringLiteral(line.slice(0, match.index))) {
+      const stripped = line.slice(0, match.index);
+      if (stripped.trim().length > 0) {
+        out.push(stripped);
+        removed += 1;
+        continue;
+      }
+    }
+    // Token present but not in a strippable trailing-comment position — leave as-is.
+    out.push(line);
+  }
+
+  return { content: out.join("\n"), removed };
+}
+
+// True when the change from `before` to `after` only inserts and/or removes
+// `AI_COMMENT:` markers — i.e. stripping all such markers from both sides yields
+// identical text. Used to enforce the review-phase read-only exception at the
+// tool-call gate (the agent may touch AI_COMMENT markers and nothing else).
+export function isAiCommentOnlyChange(before: string, after: string): boolean {
+  if (before === after) return true;
+  return stripAiCommentsFromContent(before).content === stripAiCommentsFromContent(after).content;
+}

package/extensions/orchestrator/command-handlers.test.ts

@@ -309,6 +309,29 @@ describe("transitionToNextPhase", () => {
     expect(cleanupSpy).toHaveBeenCalledTimes(1);
   });
 
+  it("does not re-run afterImplement when it already ran for this implement phase (#1)", async () => {
+    const pi = makePi();
+    const orchestrator = new Orchestrator(pi as any);
+    const taskDir = makeTempDir();
+    orchestrator.cwd = taskDir;
+    orchestrator.config = makeConfig() as any;
+    orchestrator.active = makeTransitionTask(taskDir, "implement");
+    orchestrator.active.state.repos = [{ path: taskDir, isRoot: true }];
+    orchestrator.active.state.afterImplementRan = true;
+    orchestrator.active.modifiedFiles = new Set([join(taskDir, "src", "root.ts")]);
+    const ctx = makeTransitionCtx();
+    vi.spyOn(machineModule, "validateExitCriteria").mockReturnValue({ ok: true });
+    const runSpy = vi.spyOn(commandsModule, "runAfterImplement").mockReturnValue([{ ok: true, command: "npm test", output: "ok" }]);
+    vi.spyOn(orchestrator, "cleanupActive").mockImplementation(async () => {
+      orchestrator.active = null;
+    });
+
+    const result = await transitionToNextPhase(orchestrator, ctx);
+
+    expect(result.ok).toBe(true);
+    expect(runSpy).not.toHaveBeenCalled();
+  });
+
   it("clears reviewCycle and review bookkeeping on the done transition (Issue 4)", async () => {
     const pi = makePi();
     const orchestrator = new Orchestrator(pi as any);
@@ -509,6 +532,30 @@ describe("transitionToNextPhase", () => {
     expect(cleanupSpy).toHaveBeenCalledTimes(1);
   });
 
+  it("completing a task (next === done) requests a discard transition", async () => {
+    const pi = makePi();
+    const orchestrator = new Orchestrator(pi as any);
+    const taskDir = makeTempDir();
+    orchestrator.cwd = taskDir;
+    orchestrator.config = makeConfig() as any;
+    orchestrator.active = makeTransitionTask(taskDir, "quick");
+    const ctx = makeTransitionCtx();
+    vi.spyOn(machineModule, "validateExitCriteria").mockReturnValue({ ok: true });
+    vi.spyOn(orchestrator, "cleanupActive").mockImplementation(async () => {
+      orchestrator.active = null;
+    });
+    vi.spyOn(orchestrator, "abortAllSubagents").mockImplementation(() => undefined);
+    const reqSpy = vi.spyOn(orchestrator.transitionController, "requestTransition").mockReturnValue(Promise.resolve());
+
+    const result = await transitionToNextPhase(orchestrator, ctx);
+
+    expect(result).toEqual({ ok: true });
+    const doneCall = reqSpy.mock.calls.find(([req]: any[]) => req.kind === "done");
+    expect(doneCall).toBeDefined();
+    expect((doneCall![0] as any).discard).toBe(true);
+    expect((doneCall![0] as any).summary).toContain("DISCARD");
+  });
+
   it("skips afterImplement when phase is not implement", async () => {
     const pi = makePi();
     const orchestrator = new Orchestrator(pi as any);

package/extensions/orchestrator/command-handlers.ts

@@ -13,6 +13,41 @@ function isEnabled(value: { enabled?: boolean }): boolean {
   return value.enabled !== false;
 }
 
+// Runs the configured afterImplement commands per repo (root + extra repos when
+// enabled), grouping by the repo each modified file belongs to. Returns an error
+// string when any command fails (same wording the transition surfaces), or null
+// on success. Shared by the guided/autonomous implement→done transition AND the
+// autonomous terminal handoff, which opens the guided menu instead of advancing.
+export function runAfterImplementForActive(orchestrator: Orchestrator): string | null {
+  if (!orchestrator.active) return null;
+  const repos = orchestrator.active.state.repos ?? [];
+  const grouped = groupFilesByRepo(repos, [...orchestrator.active.modifiedFiles]);
+  const afterResults: Array<{ ok: boolean; command: string; output: string }> = [];
+  for (const [repoPath] of grouped) {
+    if (!repoPath) continue;
+    const repo = repos.find((r) => r.path === repoPath);
+    if (!repo) continue;
+    if (repo.isRoot) {
+      afterResults.push(...runAfterImplement(
+        orchestrator.config.commands.afterImplement,
+        orchestrator.config.performance.commands.afterImplement,
+        orchestrator.cwd,
+      ));
+      continue;
+    }
+    if (!orchestrator.config.general.loadExtraRepoConfigs) continue;
+    const extraCommands = loadRepoAfterImplementCommands(repoPath);
+    if (!extraCommands || Object.keys(extraCommands).length === 0) continue;
+    afterResults.push(...runAfterImplement(extraCommands, orchestrator.config.performance.commands.afterImplement, repoPath));
+  }
+  const failures = afterResults.filter((r) => !r.ok);
+  if (failures.length > 0) {
+    const failureText = failures.map((f) => `${f.command}: ${f.output}`).join("\n");
+    return `afterImplement commands failed:\n${failureText}\n\nFix these issues before advancing.`;
+  }
+  return null;
+}
+
 export async function transitionToNextPhase(
   orchestrator: Orchestrator,
   ctx: any,
@@ -39,36 +74,16 @@ export async function transitionToNextPhase(
   const next = nextPhase(orchestrator.active.type, currentPhase);
   if (!next) return { ok: false, error: "No next phase available." };
 
-  if (currentPhase === "implement") {
-    const repos = orchestrator.active.state.repos ?? [];
-    const grouped = groupFilesByRepo(repos, [...orchestrator.active.modifiedFiles]);
-    const afterResults: Array<{ ok: boolean; command: string; output: string }> = [];
-    for (const [repoPath] of grouped) {
-      if (!repoPath) continue;
-      const repo = repos.find((r) => r.path === repoPath);
-      if (!repo) continue;
-      if (repo.isRoot) {
-        afterResults.push(...runAfterImplement(
-          orchestrator.config.commands.afterImplement,
-          orchestrator.config.performance.commands.afterImplement,
-          orchestrator.cwd,
-        ));
-        continue;
-      }
-      if (!orchestrator.config.general.loadExtraRepoConfigs) continue;
-      const extraCommands = loadRepoAfterImplementCommands(repoPath);
-      if (!extraCommands || Object.keys(extraCommands).length === 0) continue;
-      afterResults.push(...runAfterImplement(extraCommands, orchestrator.config.performance.commands.afterImplement, repoPath));
-    }
-    const failures = afterResults.filter((r) => !r.ok);
-    if (failures.length > 0) {
-      const failureText = failures.map((f) => `${f.command}: ${f.output}`).join("\n");
-      return { ok: false, error: `afterImplement commands failed:\n${failureText}\n\nFix these issues before advancing.` };
-    }
+  if (currentPhase === "implement" && !orchestrator.active.state.afterImplementRan) {
+    const afterError = runAfterImplementForActive(orchestrator);
+    if (afterError) return { ok: false, error: afterError };
+    orchestrator.active.state.afterImplementRan = true;
   }
 
   orchestrator.active.state.phase = next;
   orchestrator.active.state.reviewCycle = null;
+  orchestrator.active.state.plannotatorCursor = undefined;
+  orchestrator.active.state.afterImplementRan = false;
   orchestrator.active.state.reviewPass = 0;
   orchestrator.active.state.reviewApprovedClean = false;
   orchestrator.active.reviewPass = 0;
@@ -101,7 +116,8 @@ export async function transitionToNextPhase(
     // Route the task-done compaction through the controller as a "done" target.
     void orchestrator.transitionController.requestTransition({
       kind: "done",
-      summary: `Task "${name}" (${type}) completed.`,
+      discard: true,
+      summary: `Task "${name}" (${type}) is finished — DISCARD its entire conversation. Do NOT carry forward, reference, or act on any of this task's messages, phase, plan, or aborted turns; the next task starts from a clean slate.`,
     });
     ctx.ui.notify("Task completed!", "info");
     return { ok: true };
@@ -151,7 +167,7 @@ export function registerCommandHandlers(orchestrator: Orchestrator): void {
       const { showPpMenu } = await import("./pp-menu.js");
       const text = await showPpMenu(orchestrator, ctx, "command");
       if (text) {
-        orchestrator.safeSendUserMessage(`[PI-PI] ${text}`);
+        orchestrator.safeSendUserMessage(text.startsWith("[PI-PI]") ? text : `[PI-PI] ${text}`);
       }
     },
   });