@ilya-lesikov/pi-pi 0.8.0 → 0.9.0

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

@@ -8,7 +8,7 @@ import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-
 export function createCodeReviewerAgent(
   variant: string,
   variants: Record<string, VariantConfig>,
-  taskArtifacts: { userRequest: string; research: string; synthesizedPlan: string; manifest?: { title: string; path: string }[] },
+  taskArtifacts: { userRequest: string; research: string; synthesizedPlan?: string; manifest?: { title: string; path: string }[] },
   outputPath: string,
   contextDirs: string[],
   phase?: string,
@@ -21,6 +21,9 @@ export function createCodeReviewerAgent(
   const contextFiles = loadAllContextFiles(contextDirs, "codeReviewer", "system", phase, getModelInfo(variantConfig.model));
   const contextBlock = contextFiles.map((f) => f.content).join("\n\n");
   const repoContext = buildRepoContext(repos);
+  // A standalone review task (phase "review") has no synthesized plan: review the
+  // diff against USER_REQUEST.md/RESEARCH.md, not an implementation plan.
+  const hasPlan = typeof taskArtifacts.synthesizedPlan === "string" && taskArtifacts.synthesizedPlan.trim().length > 0;
 
   return {
     frontmatter: {
@@ -53,11 +56,15 @@ export function createCodeReviewerAgent(
       "3. Read changed files for full context",
       "4. Run lsp diagnostics on changed files",
       "5. Use lsp findReferences to check callers of modified functions",
-      "6. Check the implementation against the plan",
+      hasPlan
+        ? "6. Check the implementation against the plan"
+        : "6. Check the changes against USER_REQUEST.md and RESEARCH.md (there is no implementation plan for a standalone review)",
       "",
       "Review criteria:",
       "- Bugs: logic errors, off-by-ones, null handling, race conditions",
-      "- Correctness: does it match the plan and user request?",
+      hasPlan
+        ? "- Correctness: does it match the plan and user request?"
+        : "- Correctness: does it match the user request and the reviewed scope?",
       "- Quality: error handling, edge cases, type safety",
       "- Missing: untested paths, unhandled errors, incomplete implementations",
       "",
@@ -81,6 +88,16 @@ export function createCodeReviewerAgent(
       "- MINOR: (nice to have)",
       "- OPEN QUESTIONS: (low-confidence concerns, speculative follow-ups)",
       "",
+      "After the findings, include a machine-readable ANCHORS block so the synthesizer can place",
+      "the findings at their exact locations (in source AI_COMMENT markers and/or GitHub PR line comments).",
+      "Emit one line per actionable finding (CRITICAL/MAJOR/MINOR), in this EXACT format:",
+      "ANCHORS:",
+      "<relative/path/from/repo/root>:<line> — <severity>: <one-line finding>",
+      "Rules:",
+      "- Use the repo-relative path (as `git diff` shows it) and a single 1-based line number on the NEW side of the diff.",
+      "- One finding per line; omit findings you cannot pin to a concrete file:line (keep those in OPEN QUESTIONS).",
+      "- If there are no actionable findings, write `ANCHORS:` followed by `(none)`.",
+      "",
       "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.',
@@ -97,8 +114,7 @@ export function createCodeReviewerAgent(
       "=== RESEARCH ===",
       taskArtifacts.research,
       "",
-      "=== SYNTHESIZED PLAN ===",
-      taskArtifacts.synthesizedPlan,
+      ...(hasPlan ? ["=== SYNTHESIZED PLAN ===", taskArtifacts.synthesizedPlan as string, ""] : []),
       ...(repoContext ? [repoContext] : []),
       "",
       formatManifestBlock(taskArtifacts.manifest ?? []),

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { completionLine, constraintsBlock } from "./constraints.js";
+import { closingBlockInstruction, completionLine, constraintsBlock } from "./constraints.js";
 
 describe("completionLine", () => {
   it("guided plan and implement instruct calling pp_phase_complete on completion", () => {
@@ -28,6 +28,44 @@ describe("completionLine", () => {
       expect(completionLine(phase, "autonomous")).toContain("call pp_phase_complete");
     }
   });
+
+  it("guided handoff phases require the standardized closing block", () => {
+    for (const phase of ["brainstorm", "review", "debug"] as const) {
+      const line = completionLine(phase, "guided");
+      expect(line).toContain("the standardized block");
+      expect(line).toContain("Advance via the /pp menu");
+    }
+  });
+
+  it("autonomous phases do not emit the prose closing block", () => {
+    expect(completionLine("brainstorm", "autonomous")).not.toContain("Advance via the /pp menu");
+  });
+});
+
+describe("closingBlockInstruction", () => {
+  it("spells out the exact block with a blank line between summary and advance, no rules", () => {
+    const block = closingBlockInstruction("brainstorm");
+    expect(block).toContain("Advance via the /pp menu to move into plan");
+    expect(block).not.toContain("────");
+    expect(block).toContain("/pp");
+    expect(block).toContain("✅ <one-sentence summary of what this phase produced>\n\n▶ Advance via the /pp menu to move into plan.");
+  });
+
+  it("prepends the Review Summary schema ONLY for the review phase, before the closing block", () => {
+    const review = closingBlockInstruction("review");
+    expect(review).toContain("## Review Summary");
+    expect(review).toContain("| # | Severity | Location | Finding |");
+    expect(review).toContain("BLOCKER");
+    // The ✅/▶ lines must remain the final lines of the block.
+    expect(review.trimEnd().endsWith("▶ Advance via the /pp menu to move into plan.")).toBe(true);
+    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) {
+      expect(closingBlockInstruction(phase)).not.toContain("## Review Summary");
+    }
+  });
 });
 
 describe("constraintsBlock", () => {

package/extensions/orchestrator/agents/constraints.ts

@@ -3,6 +3,14 @@ import type { Phase, TaskMode } from "../state.js";
 const READONLY_CONSTRAINT =
   "You MUST NOT edit, create, or delete any project file (source, tests, config, docs) — only files under .pp/state/ may be written — and you MUST NOT run state-changing shell commands. If you find a fix worth making, record it in your output; do NOT apply it here.";
 
+// The review phase is read-only EXCEPT for publishing findings: the main agent may
+// insert or remove `AI_COMMENT:` markers in source files (file comments), and may
+// run `gh` to post/read GitHub PR line comments AND bundled pull-request reviews
+// (PR comments) — and nothing else (no fixes, no other edits, no other state-changing
+// commands). This is the reviewer→user mirror of the user→reviewer `AI_REVIEW:` markers.
+const REVIEW_READONLY_CONSTRAINT =
+  "You MUST NOT edit, create, or delete any project file (source, tests, config, docs) — only files under .pp/state/ may be written — and you MUST NOT run state-changing shell commands, WITH ONE EXCEPTION: when publishing review findings you MAY insert or remove `AI_COMMENT:` markers in source files (in each file's native comment syntax) and MAY run `gh` to post or read GitHub PR comments — including line comments and bundled pull-request reviews (a review body plus its line comments) — and nothing else. Do NOT apply fixes or make any other source change. If you find a fix worth making, record it in your output.";
+
 const IMPLEMENT_CONSTRAINT =
   "Implement only the approved plan. Do NOT add scope or change plan items without recording why in the plan. If the same fix fails 3 times, stop and re-plan — do NOT keep retrying the same approach.";
 
@@ -16,9 +24,62 @@ export function isReadOnlyPhase(phase: Phase): boolean {
 export function phaseConstraint(phase: Phase): string {
   if (phase === "implement") return IMPLEMENT_CONSTRAINT;
   if (phase === "quick") return QUICK_CONSTRAINT;
+  if (phase === "review") return REVIEW_READONLY_CONSTRAINT;
   return READONLY_CONSTRAINT;
 }
 
+// Guided phases that stop and hand back to the user (brainstorm, review, debug) 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
+// (the review-cycle synthesis in review.ts and the ordinary review-task close here). Counts
+// reconcile with the `ANCHORS:` block: when it is `(none)`, Anchored=0 and every finding is
+// Un-anchorable. Location is `file:line`, or `file:—` for un-anchorable findings.
+export const REVIEW_SUMMARY_SCHEMA = [
+  "## Review Summary",
+  "",
+  "Scope: <repos/PR/branch/range + change size>",
+  "",
+  "| Repo | PR | Findings | Anchored | Un-anchorable |",
+  "|------|----|----------|----------|---------------|",
+  "| <owner/repo> | #<n> | <total> | <in-diff> | <not-in-diff> |",
+  "",
+  "### Findings",
+  "| # | Severity | Location | Finding |",
+  "|---|----------|----------|---------|",
+  "| 1 | BLOCKER | <file:line or file:—> | <one line> |",
+  "",
+  "Next step: /pp → Next → Publish to post these as GitHub PR comments or file comments.",
+].join("\n");
+
+// Instruction wrapping REVIEW_SUMMARY_SCHEMA: severity vocabulary is fixed and the summary
+// degrades gracefully to a single-repo / no-PR row when only one repo (or no PR) was resolved.
+export const reviewSummaryInstruction = [
+  "Before the closing block, print a structured Review Summary in EXACTLY this shape (fill in the values; severity is one of BLOCKER / MAJOR / MINOR, uppercase):",
+  "",
+  REVIEW_SUMMARY_SCHEMA,
+  "",
+  "Counts MUST reconcile with the `ANCHORS:` block: an `(none)` block means Anchored=0 and every finding is Un-anchorable. Fill the table from whatever repos/PR you resolved; degrade to a single-repo / no-PR row when there is only one repo or no PR.",
+].join("\n");
+
+export function closingBlockInstruction(phase: Phase): string {
+  const next = NEXT_PHASE_LABEL[phase] ?? "the next phase";
+  const summary = phase === "review" ? reviewSummaryInstruction + "\n\n" : "";
+  return [
+    summary +
+    "End that turn with EXACTLY this block, verbatim, as the final lines of your message (fill the summary line with one sentence; change nothing else):",
+    "✅ <one-sentence summary of what this phase produced>",
+    "",
+    `▶ Advance via the /pp menu to move into ${next}.`,
+  ].join("\n");
+}
+
 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.";
@@ -27,12 +88,12 @@ export function completionLine(phase: Phase, mode: TaskMode): string {
     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.";
   }
   if (phase === "brainstorm") {
-    return "This is a conversation. Do NOT call pp_phase_complete yourself — keep going until the user ends it or advances via the /pp menu.";
+    return "This is a conversation. Do NOT call pp_phase_complete yourself — keep going until the user ends it or advances via the /pp menu. When you have delivered a complete answer and are handing back for the user to advance, close with the standardized block. " + closingBlockInstruction(phase);
   }
   if (phase === "plan" || phase === "implement") {
     return "When you judge this phase complete, call pp_phase_complete — the extension opens the advance gate for the user to review and confirm. Do NOT instead stop and ask the user to run /pp manually.";
   }
-  return "When the work is complete, stop and let the user review and advance it via the /pp menu. Do NOT advance on your own or call pp_phase_complete unprompted.";
+  return "When the work is complete, stop and let the user review and advance it via the /pp menu. Do NOT advance on your own or call pp_phase_complete unprompted. Close with the standardized block. " + closingBlockInstruction(phase);
 }
 
 const PHASE_IDENTITY: Record<string, string> = {

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

@@ -32,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')",
@@ -82,19 +88,29 @@ export const TOOLS_BLOCK = ["<tools>", ...TOOL_ROUTING_BODY, "</tools>"].join("\
 // 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 preserve your context. subagent_type is REQUIRED (calls without it are rejected).",
-  "",
-  '- Find or locate code ("where is X", "how does Y connect", map a flow)      → explore',
-  "- External library / API / documentation knowledge                          → librarian",
-  '- Judgment call (design tradeoff, "is this correct", "why is this broken")   → advisor',
-  "- Root-cause a test or build that keeps failing after a quick attempt        → deep-debugger",
-  "- A parallel, self-contained implementation subtask                          → task",
-  "- A code review of your changes — ONLY when the user explicitly asks for one → reviewer",
-  "",
-  "explore FINDS; advisor JUDGES. Spawn several explores in parallel for broad searches.",
-  "Don't use advisor for lookups, or deep-debugger for trivial errors. deep-debugger diagnoses",
-  "only — it must NOT write the actual fix. Do NOT spawn reviewer unless the user explicitly",
-  "asks for a review (the automatic review panel already covers implement/review phases).",
+  "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 };

package/extensions/orchestrator/config.test.ts

@@ -122,10 +122,16 @@ describe("validateConfig", () => {
     );
   });
 
+  it("throws for invalid injectAgentsMd value", () => {
+    expect(() => validateConfig({ general: { injectAgentsMd: "yes" } })).toThrow(
+      "config.general.injectAgentsMd",
+    );
+  });
+
   it("accepts valid partial config", () => {
     expect(() =>
       validateConfig({
-        general: { autoCommit: false },
+        general: { autoCommit: false, injectAgentsMd: false },
         commands: {
           afterEdit: { fmt: { run: "npm run fmt", globs: ["**/*.ts"] } },
           afterImplement: { test: { run: "npm test" } },
@@ -192,6 +198,39 @@ describe("loadConfig", () => {
     expect(config.performance.commands.afterEdit).toBe(1234);
     expect(config.performance.commands.afterImplement).toBe(300000);
     expect(config.general.autoCommit).toBe(false);
+    expect(config.general.injectAgentsMd).toBe(true);
+  });
+
+  it("defaults injectAgentsMd to true and honors an explicit override", () => {
+    const cwd = makeTempDir();
+    const defaults = loadConfig(cwd, "/nonexistent/global/config.json");
+    expect(defaults.general.injectAgentsMd).toBe(true);
+
+    const cwd2 = makeTempDir();
+    const ppDir = join(cwd2, ".pp");
+    mkdirSync(ppDir, { recursive: true });
+    writeFileSync(join(ppDir, "config.json"), JSON.stringify({ general: { injectAgentsMd: false } }), "utf-8");
+    const overridden = loadConfig(cwd2, "/nonexistent/global/config.json");
+    expect(overridden.general.injectAgentsMd).toBe(false);
+  });
+
+  it("defaults mainTurnStale to 10m and normalizes an override to ms", () => {
+    const cwd = makeTempDir();
+    const defaults = loadConfig(cwd, "/nonexistent/global/config.json");
+    expect(defaults.performance.internals.mainTurnStale).toBe(600000);
+
+    const cwd2 = makeTempDir();
+    const ppDir = join(cwd2, ".pp");
+    mkdirSync(ppDir, { recursive: true });
+    writeFileSync(join(ppDir, "config.json"), JSON.stringify({ performance: { internals: { mainTurnStale: "90s" } } }), "utf-8");
+    const overridden = loadConfig(cwd2, "/nonexistent/global/config.json");
+    expect(overridden.performance.internals.mainTurnStale).toBe(90000);
+  });
+
+  it("rejects an invalid mainTurnStale duration", () => {
+    expect(() => validateConfig({ performance: { internals: { mainTurnStale: "soon" } } })).toThrow(
+      "config.performance.internals.mainTurnStale",
+    );
   });
 
   it("creates default config when config.json does not exist", () => {