@ilya-lesikov/pi-pi 0.8.0 → 0.9.0

package/extensions/orchestrator/phases/brainstorm.ts

@@ -107,8 +107,10 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
     "",
     registerReposInstruction,
     "",
-    "Your job is to produce USER_REQUEST.md and RESEARCH.md — complete enough that",
-    "downstream agents can work without re-exploring the codebase or re-interviewing the user.",
+    "This is a clarify + research + DESIGN phase. Your job is to produce USER_REQUEST.md and RESEARCH.md — complete enough that",
+    "downstream agents can work without re-exploring the codebase or re-interviewing the user. That means not just describing what",
+    "exists, but exploring the design space: weigh the viable approaches and their tradeoffs so the plan phase inherits a clear",
+    "direction rather than an open-ended problem.",
     "",
     "# Steps:",
     "1. Clarify requirements with the user if anything is ambiguous",
@@ -119,9 +121,11 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
     "   - lsp documentSymbol, goToDefinition, findReferences, goToImplementation, hover",
     "   - cbm_trace: trace call chains for dependency understanding",
     "   - ast_search: find structural patterns across the codebase",
-    "4. Ask the user follow-up questions as needed",
-    "5. Write findings into RESEARCH.md as results come back — don't wait for all subagents",
-    "6. Keep USER_REQUEST.md current: update it whenever the user's request changes or clarifies, so it reflects what the user actually wants — don't write it once and leave it stale",
+    "4. Explore design options: identify the viable approaches, weigh their tradeoffs, and land on a recommended direction (capture the reasoning in RESEARCH.md / an artifact)",
+    "5. Ask the user follow-up questions as needed",
+    "6. Actively drive every Open Question to resolution — chase down answers via research or by asking the user; the Open Questions section should be empty (or every entry marked DECIDED) before you hand off, not a passive backlog",
+    "7. Write findings into RESEARCH.md as results come back — don't wait for all subagents",
+    "8. Keep USER_REQUEST.md current: update it whenever the user's request changes or clarifies, so it reflects what the user actually wants — don't write it once and leave it stale",
     "",
     "Produce two files:",
     `- ${taskDir}/USER_REQUEST.md — MUST follow this exact structure:`,
@@ -140,14 +144,14 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
     "  - MUST: <hard requirements discovered from code>",
     "  - RISK: <things that could break>",
     "  ## Open Questions",
-    "  <Unresolved items needing user input. Omit section if none.>",
+    "  <Unresolved items needing user input. Drive these to resolution before advancing — omit the section only when genuinely none remain.>",
     "",
     "These files are validated programmatically. Missing sections or unexpected sections will be rejected.",
     "Use pp_write_state_file / pp_edit_state_file (NOT the generic write/edit) for .pp state files — they keep the output compact and validate structure.",
     "",
     "# Optional: focused analysis artifacts",
     `You may also write additional analysis files to ${taskDir}/artifacts/<name>.md`,
-    "for deep dives on specific topics (e.g. architecture analysis, API comparison, risk assessment).",
+    "for deep dives on specific topics (e.g. architecture analysis, API comparison, design-option/tradeoff analysis, risk assessment).",
     "Each artifact must start with # <Title>. Content is freeform. These are reviewed alongside USER_REQUEST.md and RESEARCH.md.",
     "Do NOT duplicate content already in RESEARCH.md — artifacts are for supplementary deep dives.",
   ].join("\n");

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

@@ -297,6 +297,42 @@ Fix bug.
     expect(validateExitCriteria(pass, "debug", "debug")).toEqual({ ok: true });
   });
 
+  it("validates review phase — requires artifacts and an ANCHORS-bearing final_pass file", () => {
+    const missing = makeTempDir();
+    expect(validateExitCriteria(missing, "review", "review")).toEqual({
+      ok: false,
+      reason: "USER_REQUEST.md does not exist or is empty",
+    });
+
+    const noAnchors = makeTempDir();
+    writeFileSync(join(noAnchors, "USER_REQUEST.md"), VALID_USER_REQUEST, "utf-8");
+    writeFileSync(join(noAnchors, "RESEARCH.md"), VALID_RESEARCH, "utf-8");
+    const res1 = validateExitCriteria(noAnchors, "review", "review");
+    expect(res1.ok).toBe(false);
+    expect((res1 as { reason: string }).reason).toContain("ANCHORS");
+
+    const emptyAnchorsFile = makeTempDir();
+    writeFileSync(join(emptyAnchorsFile, "USER_REQUEST.md"), VALID_USER_REQUEST, "utf-8");
+    writeFileSync(join(emptyAnchorsFile, "RESEARCH.md"), VALID_RESEARCH, "utf-8");
+    mkdirSync(join(emptyAnchorsFile, "code-reviews"), { recursive: true });
+    writeFileSync(join(emptyAnchorsFile, "code-reviews", "1_final_pass-1.md"), "no anchors here", "utf-8");
+    expect(validateExitCriteria(emptyAnchorsFile, "review", "review").ok).toBe(false);
+
+    const zeroFindings = makeTempDir();
+    writeFileSync(join(zeroFindings, "USER_REQUEST.md"), VALID_USER_REQUEST, "utf-8");
+    writeFileSync(join(zeroFindings, "RESEARCH.md"), VALID_RESEARCH, "utf-8");
+    mkdirSync(join(zeroFindings, "code-reviews"), { recursive: true });
+    writeFileSync(join(zeroFindings, "code-reviews", "1_final_pass-1.md"), "# Review\nANCHORS: (none)\n", "utf-8");
+    expect(validateExitCriteria(zeroFindings, "review", "review")).toEqual({ ok: true });
+
+    const withFindings = makeTempDir();
+    writeFileSync(join(withFindings, "USER_REQUEST.md"), VALID_USER_REQUEST, "utf-8");
+    writeFileSync(join(withFindings, "RESEARCH.md"), VALID_RESEARCH, "utf-8");
+    mkdirSync(join(withFindings, "code-reviews"), { recursive: true });
+    writeFileSync(join(withFindings, "code-reviews", "1_final_pass-2.md"), "ANCHORS:\n- src/a.ts:12 must fix\n", "utf-8");
+    expect(validateExitCriteria(withFindings, "review", "review")).toEqual({ ok: true });
+  });
+
   it("returns unknown phase error for done", () => {
     const dir = makeTempDir();
     expect(validateExitCriteria(dir, "implement", "done")).toEqual({

package/extensions/orchestrator/phases/machine.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 import type { TaskType, Phase } from "../state.js";
-import { getLatestSynthesizedPlan } from "../context.js";
+import { getLatestSynthesizedPlan, hasFinalPassAnchors } from "../context.js";
 import { validatePlan, validateResearch, validateUserRequest } from "../validate-artifacts.js";
 
 const USER_REQUEST_TEMPLATE = [
@@ -156,6 +156,16 @@ export function validateExitCriteria(
         };
       }
 
+      if (!hasFinalPassAnchors(taskDir)) {
+        return {
+          ok: false,
+          reason:
+            "No ANCHORS-bearing final review file exists. Write the review findings to " +
+            "`code-reviews/*_final_pass-*.md` with an `ANCHORS:` block (use `ANCHORS: (none)` " +
+            "if there are no findings) before completing the review.",
+        };
+      }
+
       return { ok: true };
     }
 

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

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+import { reviewSystemPrompt } from "./review-task.js";
+
+describe("review-task reviewSystemPrompt", () => {
+  it("mandates writing an ANCHORS-bearing final_pass file via the generic write tool", () => {
+    const prompt = reviewSystemPrompt("/tmp/task", "/tmp/cwd");
+    expect(prompt).toContain("/tmp/task/code-reviews/<unix-epoch-seconds>_final_pass-1.md");
+    expect(prompt).toContain("ANCHORS:");
+    expect(prompt).toContain("<relative/path/from/repo/root>:<line> — <one-line finding>");
+    expect(prompt).toContain("(none)");
+    expect(prompt).toContain("GENERIC write tool");
+  });
+
+  it("still captures the structured USER_REQUEST.md / RESEARCH.md deliverables", () => {
+    const prompt = reviewSystemPrompt("/tmp/task", "/tmp/cwd");
+    expect(prompt).toContain("USER_REQUEST.md");
+    expect(prompt).toContain("RESEARCH.md");
+    expect(prompt).toContain("pp_write_state_file");
+  });
+});

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

@@ -4,31 +4,59 @@ export function reviewSystemPrompt(taskDir: string, cwd: string): string {
     "",
     `First, register all git repositories you'll work in using pp_register_repo (including the root: ${cwd}). For each, determine the base branch by examining the current branch and remote tracking.`,
     "",
-    "You are reviewing code changes. USER_REQUEST.md describes what to review.",
-    "Read it first to understand the scope.",
+    "You are reviewing code changes. The user will describe what to review in their first chat message",
+    "(e.g. a branch, a commit range, uncommitted changes, or a GitHub PR URL). There is NO pre-seeded",
+    "USER_REQUEST.md — you must capture the user's request and your findings into the state files yourself.",
+    "If the scope is ambiguous, ask the user before diving in.",
+    "",
+    "If the review scope is a GitHub PR: for each registered repo, resolve the PR with `gh pr view --json number,headRefName,headRefOid,url`, then call pp_checkout_pr_head with that repo's `headRefName`/`headRefOid` to land it on the PR head BEFORE analyzing it. If the tool HALTS (dirty tree, different branch, or diverged branch), relay its message to the user and wait for them to resolve it before continuing. For a branch, commit-range, or uncommitted-changes review, do NOT call pp_checkout_pr_head.",
     "",
     "Use available tools to analyze the changes:",
     "- git diff, git log, git show for examining commits and diffs",
     "- read, lsp, grep, find for understanding the code",
     "- gh pr view for GitHub PR context if a PR URL is mentioned",
+    "- cbm_search/cbm_search_code, lsp goToDefinition/findReferences/hover, cbm_trace, ast_search for deeper analysis",
     "",
     "Delegate to subagents where useful (see the delegation guidance in your system prompt) — spawn multiple explores in parallel for broad searches.",
     "",
-    "Write your findings:",
-    `- ${taskDir}/USER_REQUEST.md — update with a clear problem statement of issues found`,
-    `- ${taskDir}/RESEARCH.md — detailed technical analysis`,
-    "",
-    "USER_REQUEST.md format:",
-    "- # User Request",
-    "- ## Problem",
-    "- ## Constraints",
-    "",
-    "RESEARCH.md format:",
-    "- ## Affected Code",
-    "- ## Architecture Context",
-    "- ## Constraints & Edge Cases",
-    "- ## Open Questions (optional)",
+    "Produce two files:",
+    `- ${taskDir}/USER_REQUEST.md — MUST follow this exact structure:`,
+    "  # User Request",
+    "  <1-3 sentence distillation of what the user asked you to review>",
+    "  ## Problem",
+    "  <What is being reviewed and why, in the user's words. PR/issue link if provided.>",
+    "  ## Constraints",
+    "  <Boundaries the user explicitly stated. Only user-stated info, no agent findings.>",
+    `- ${taskDir}/RESEARCH.md — MUST follow this exact structure:`,
+    "  ## Affected Code",
+    "  <file:symbol — one-line role, per line>",
+    "  ## Architecture Context",
+    "  <Dense bullets. How the changed pieces connect. Sub-group by subsystem for complex reviews.>",
+    "  ## Constraints & Edge Cases",
+    "  - MUST: <hard requirements the change must satisfy>",
+    "  - RISK: <bugs, regressions, edge cases the change could break>",
+    "  ## Open Questions",
+    "  <Low-confidence concerns or items needing user input. Omit section if none.>",
+    "",
+    "These files are validated programmatically. Missing sections or unexpected sections will be rejected.",
+    "Use pp_write_state_file / pp_edit_state_file (NOT the generic write/edit) for these .pp state files — they keep the output compact and validate structure.",
+    "Keep USER_REQUEST.md current: update it whenever the user clarifies the review scope, so it never goes stale.",
+    "",
+    "# Optional: focused analysis artifacts",
+    `You may also write additional analysis files to ${taskDir}/artifacts/<name>.md`,
+    "for deep dives on specific findings (e.g. a subtle bug, a design concern, a risk assessment).",
+    "Each artifact must start with # <Title>. Content is freeform. These are reviewed alongside USER_REQUEST.md and RESEARCH.md.",
+    "Do NOT duplicate content already in RESEARCH.md — artifacts are for supplementary deep dives.",
     "",
     "Focus on: correctness, edge cases, style consistency, missing tests, potential bugs.",
+    "You are investigating and documenting findings — you do NOT apply fixes in this phase.",
+    "",
+    "# Required: findings file with an ANCHORS block",
+    `When you finish reviewing, you MUST write your findings to ${taskDir}/code-reviews/<unix-epoch-seconds>_final_pass-1.md (use the GENERIC write tool, NOT pp_write_state_file — code-reviews/ is not a managed state path; the <unix-epoch-seconds> prefix, e.g. the output of \`date +%s\`, keeps it ordered against automated review-cycle files). Create the code-reviews/ directory if it does not exist.`,
+    "That file MUST include a machine-readable `ANCHORS:` block for the accepted findings — one line per finding in EXACTLY this format (the /pp Publish step consumes these lines):",
+    "ANCHORS:",
+    "<relative/path/from/repo/root>:<line> — <one-line finding>",
+    "Use the real file:line for each finding — do NOT invent locations. Write `ANCHORS:` followed by `(none)` if there are no anchorable accepted findings.",
+    "This is a normal deliverable of every review, independent of any automated review cycle: without it, publishing has nothing to anchor.",
   ].join("\n");
 }

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

@@ -45,6 +45,32 @@ describe("reviewSystemPrompt apply_feedback wording", () => {
     expect(impl).toContain("Implement the fixes");
   });
 
+  it("standalone review phase omits the fix-plan/implement/afterImplement tail", () => {
+    const prompt = reviewSystemPrompt("/tmp/task", 1, "review", "guided");
+    expect(prompt).toContain("REVIEW CYCLE");
+    expect(prompt).toContain("standalone review");
+    expect(prompt).not.toContain("Create a fix plan");
+    expect(prompt).not.toContain("Implement the fixes");
+    expect(prompt).not.toContain("Run afterImplement commands");
+    expect(prompt).toContain("code-reviews/");
+  });
+
+  it("standalone review synthesis emits an ANCHORS block and defers publishing to the user", () => {
+    const prompt = reviewSystemPrompt("/tmp/task", 1, "review", "guided");
+    expect(prompt).toContain("ANCHORS:");
+    expect(prompt).toContain("Do NOT publish findings now");
+    expect(prompt).not.toContain("do NOT call `gh` yourself");
+  });
+
+  it("review-cycle synthesis does NOT embed the Review Summary schema (delivered via the closing block)", () => {
+    // The schema is injected once by constraintsBlock -> closingBlockInstruction("review"),
+    // which is always prepended to the phase prompt; repeating it here would duplicate it.
+    for (const mode of ["guided", "autonomous"] as const) {
+      const prompt = reviewSystemPrompt("/tmp/task", 1, "review", mode);
+      expect(prompt).not.toContain("## Review Summary");
+    }
+  });
+
   it("points each phase at the directory its reviewers actually write to", () => {
     // plan reviewers write to plan-reviews (planning.ts) and outputs load from
     // plan-reviews (context.ts); the prompt must match, not code-reviews.

package/extensions/orchestrator/phases/review.ts

@@ -49,6 +49,40 @@ export function reviewSystemPrompt(taskDir: string, pass: number, phase?: string
     ].join("\n");
   }
 
+  // A standalone review task's "review" phase has nothing to implement: the output
+  // is the synthesized findings. So it must NOT get the "create a fix plan /
+  // implement / run afterImplement" tail that implement-phase review uses. The user
+  // publishes findings (as file comments and/or GitHub PR comments) via the /pp
+  // "Publish" menu after synthesis — which consumes the ANCHORS: block below.
+  if (phase === "review") {
+    return [
+      `[PI-PI — REVIEW CYCLE (pass ${pass})]`,
+      "",
+      "Reviewer outputs are ready.",
+      `Read them from ${reviewsDir}/ and synthesize the findings.`,
+      "",
+      "You are a SYNTHESIZER: merge the reviewer outputs. Do NOT write your own review from scratch.",
+      `- Do NOT create the ${reviewsDirName}/ directory yourself — the extension manages it.`,
+      "- This is a standalone review: do NOT create a fix plan, implement fixes, run afterImplement commands, or commit.",
+      "- Do NOT publish findings now (no source edits, no `gh`); the user triggers publishing from the /pp menu.",
+      "",
+      "# Your job (in this order):",
+      `1. Read ALL reviewer outputs from ${reviewsDir}/`,
+      `2. Synthesize into ${reviewsDir}/<unix-epoch-seconds>_final_pass-${pass}.md (prefix with the current Unix epoch seconds, e.g. \`date +%s\`, so the file orders chronologically)`,
+      "3. Present the synthesis to the user",
+      "",
+      "In the synthesized final-review file you MUST include a machine-readable `ANCHORS:` block for the accepted findings — one line per finding in EXACTLY this format (a later publish step consumes these lines):",
+      "ANCHORS:",
+      "<relative/path/from/repo/root>:<line> — <one-line finding>",
+      "Use the `ANCHORS:` blocks the reviewers emitted as the source of file:line — do NOT invent locations. Write `ANCHORS:` followed by `(none)` if there are no anchorable accepted findings.",
+      "",
+      "PRIVACY: phrase every finding as a self-contained observation about the code. Do NOT reference private or internal details, `the ticket`, issue trackers, or internal design docs — these findings are published as PR/file comments. Say what is wrong in the code, not that it violates a private document's goal.",
+      // The Review Summary schema is delivered by the standardized closing block
+      // (constraints.ts closingBlockInstruction, gated to phase==="review"), which is
+      // always prepended to this prompt — so it is intentionally NOT repeated here.
+    ].join("\n");
+  }
+
   // In autonomous plan/implement the phase does NOT complete until the agent
   // re-calls pp_phase_complete: that is what finalizes the pass and advances the
   // phase. Telling it to "present to the user" and wait causes the plan phase to
@@ -102,7 +136,7 @@ export function reviewSystemPrompt(taskDir: string, pass: number, phase?: string
     "",
     "# Your job (in this order):",
     `1. Read ALL reviewer outputs from ${reviewsDir}/`,
-    `2. Synthesize into ${reviewsDir}/<timestamp>_final_pass-${pass}.md`,
+    `2. Synthesize into ${reviewsDir}/<unix-epoch-seconds>_final_pass-${pass}.md (prefix with the current Unix epoch seconds, e.g. \`date +%s\`, so the file orders chronologically)`,
     finalStep,
     ...tail,
   ].join("\n");
@@ -132,8 +166,11 @@ export async function spawnCodeReviewers(
 
   const userRequest = readFileSync(urPath, "utf-8");
   const research = readFileSync(resPath, "utf-8");
-  const synthesizedPlan = getLatestSynthesizedPlan(taskDir);
-  if (!synthesizedPlan) {
+  // A standalone review task (phase "review") has no synthesized plan by design —
+  // reviewers assess the diff against USER_REQUEST.md/RESEARCH.md instead. The
+  // plan is only required where one legitimately exists (the implement phase).
+  const synthesizedPlan = phase === "review" ? undefined : (getLatestSynthesizedPlan(taskDir) ?? undefined);
+  if (phase !== "review" && !synthesizedPlan) {
     send(
       { customType: "pp-code-reviews-error", content: "Cannot start code review: no synthesized plan found.", display: true },
       "context",

package/extensions/orchestrator/pp-menu.test.ts

@@ -1,11 +1,34 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { join } from "path";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
 import { getDefaultConfig, GLOBAL_CONFIG_PATH, parseDuration } from "./config.js";
 import * as configModule from "./config.js";
 import * as flantInfra from "./flant-infra.js";
-import { formatDuration, formatSourceTags, getConfigSourceInfo, pickMaxReviewPasses, showUsage } from "./pp-menu.js";
+import { formatDuration, formatSourceTags, getConfigSourceInfo, pickMaxReviewPasses, publishGuard, publishFileCommentsBanner, publishPrCommentsBanner, showActiveTaskMenu, showUsage } from "./pp-menu.js";
 import { createUsageTracker } from "./usage-tracker.js";
 
+// Drives showActiveTaskMenu's submenu navigation by scripting selectOption answers.
+const askQueue: string[] = [];
+const askQuestions: string[] = [];
+vi.mock("../../3p/pi-ask-user/index.js", () => ({
+  isCancel: (r: any) => r?.__cancel === true,
+  askUser: vi.fn(async (_ctx: any, opts: any) => {
+    askQuestions.push(opts.question);
+    const next = askQueue.shift();
+    if (next === undefined || next === "__ESC__") return { __cancel: true, reason: "user" };
+    return { kind: "selection", selections: [next] };
+  }),
+}));
+
+// Scripts per-repo Plannotator outcomes for the #3a interleaved cursor tests.
+const plannotatorResults: Array<{ approved: boolean; feedback?: string }> = [];
+vi.mock("./plannotator.js", () => ({
+  cancelPendingPlannotatorWait: () => {},
+  openPlannotator: vi.fn(async () => ({ opened: true, reviewId: "rev" })),
+  waitForPlannotatorResult: vi.fn(async () => plannotatorResults.shift() ?? { approved: true }),
+}));
+
 const USAGE_TRACKER_SYMBOL = Symbol.for("pi-pi:usage-tracker");
 
 afterEach(() => {
@@ -205,3 +228,186 @@ describe("pickMaxReviewPasses", () => {
     expect(await pickMaxReviewPasses(makeInputCtx([""]), 3)).toBeNull();
   });
 });
+
+describe("publishGuard", () => {
+  let taskDir: string;
+
+  afterEach(() => {
+    if (taskDir) rmSync(taskDir, { recursive: true, force: true });
+  });
+
+  function makeTask(): string {
+    taskDir = mkdtempSync(join(tmpdir(), "pp-guard-"));
+    return taskDir;
+  }
+
+  it("blocks publishing when no review has run (no code-reviews dir)", () => {
+    const dir = makeTask();
+    const msg = publishGuard(dir);
+    expect(msg).toBeTruthy();
+    expect(msg).toContain("review pass");
+  });
+
+  it("blocks publishing when a final_pass file exists but carries no ANCHORS block", () => {
+    const dir = makeTask();
+    mkdirSync(join(dir, "code-reviews"));
+    writeFileSync(join(dir, "code-reviews", "20260101-000000_final_pass-1.md"), "# Findings\n\nSome prose without anchors.\n");
+    expect(publishGuard(dir)).toBeTruthy();
+  });
+
+  it("allows publishing when the latest final_pass file has an ANCHORS block", () => {
+    const dir = makeTask();
+    mkdirSync(join(dir, "code-reviews"));
+    writeFileSync(join(dir, "code-reviews", "20260101-000000_final_pass-1.md"), "ANCHORS:\nsrc/a.ts:10 — bug\n");
+    expect(publishGuard(dir)).toBeUndefined();
+  });
+
+  it("resolves the newest final_pass file by name and honors its ANCHORS block", () => {
+    const dir = makeTask();
+    mkdirSync(join(dir, "code-reviews"));
+    writeFileSync(join(dir, "code-reviews", "20260101-000000_final_pass-1.md"), "ANCHORS:\nsrc/a.ts:10 — bug\n");
+    writeFileSync(join(dir, "code-reviews", "20260102-000000_final_pass-2.md"), "# Findings\n\nno anchors here\n");
+    expect(publishGuard(dir)).toBeTruthy();
+  });
+});
+
+describe("publish banners", () => {
+  it("PR banner posts one bundled COMMENT review per repo, pre-validated against the diff", () => {
+    const banner = publishPrCommentsBanner("/tmp/task");
+    expect(banner).toContain("pulls/<number>/reviews");
+    expect(banner).toContain("event=COMMENT");
+    expect(banner).not.toContain("event=APPROVE");
+    expect(banner).toContain("never APPROVE or REQUEST_CHANGES");
+    expect(banner).toContain("PRE-VALIDATE");
+    expect(banner).toContain("all-or-nothing");
+    expect(banner).toContain("Findings not anchorable to the diff:");
+    expect(banner).toContain("(generated by pi-pi)");
+  });
+
+  it("PR banner idempotency matches on path+line+footer+body", () => {
+    const banner = publishPrCommentsBanner("/tmp/task");
+    expect(banner).toContain("footer, AND body text all match");
+    expect(banner).toContain("Two distinct findings on the same line are NOT duplicates");
+  });
+
+  it("both banners carry the privacy instruction", () => {
+    for (const banner of [publishPrCommentsBanner("/tmp/task"), publishFileCommentsBanner("/tmp/task")]) {
+      expect(banner).toContain("PRIVACY:");
+      expect(banner).toContain("the ticket");
+      expect(banner).toContain("self-contained");
+    }
+  });
+});
+
+describe("showActiveTaskMenu Publish/Next Back navigation (#6)", () => {
+  let taskDir: string;
+
+  afterEach(() => {
+    askQueue.length = 0;
+    askQuestions.length = 0;
+    if (taskDir) rmSync(taskDir, { recursive: true, force: true });
+  });
+
+  function makeReviewOrchestrator(): any {
+    taskDir = mkdtempSync(join(tmpdir(), "pp-nav-"));
+    return {
+      active: {
+        type: "review",
+        dir: taskDir,
+        state: { phase: "review", step: "llm_work", mode: "guided" },
+      },
+      transitionController: {
+        isRunning: () => false,
+        abortMainAgent: () => {},
+      },
+      cancelPendingRetry: () => {},
+      abortAllSubagents: () => {},
+    };
+  }
+
+  const ctx = { ui: { notify: () => {} }, waitForIdle: async () => {}, abort: () => {} };
+
+  it("Publish 'Back' re-renders the Next submenu instead of the top-level menu", async () => {
+    const orchestrator = makeReviewOrchestrator();
+    // /pp -> Next -> Publish -> Back (should return to Next) -> Back (to top-level) -> Back (exit).
+    askQueue.push("Next", "Publish", "Back", "Back", "Back");
+    const result = await showActiveTaskMenu(orchestrator, ctx, "/pp", "tool");
+    expect(result).toBe("");
+    // After Publish's Back we must see the "Next" submenu rendered again before the
+    // top-level menu reappears: questions = [top, Next, Publish, Next(again), top].
+    const nextRenders = askQuestions.filter((q) => q === "Next").length;
+    expect(nextRenders).toBe(2);
+    expect(askQuestions[askQuestions.length - 1]).toContain("/pp");
+  });
+
+  it("Next 'Back' returns straight to the top-level menu", async () => {
+    const orchestrator = makeReviewOrchestrator();
+    askQueue.push("Next", "Back", "Back");
+    const result = await showActiveTaskMenu(orchestrator, ctx, "/pp", "tool");
+    expect(result).toBe("");
+    expect(askQuestions.filter((q) => q === "Next").length).toBe(1);
+    // Top-level rendered twice (initial + after Next's Back), Next once.
+    expect(askQuestions.filter((q) => q.startsWith("/pp")).length).toBe(2);
+  });
+
+  it("Review submenu 'Editor review' Back returns to Review, not the top-level menu (#3d)", async () => {
+    const orchestrator = makeReviewOrchestrator();
+    // /pp -> Review -> Review on my own -> Editor review Back (should return to
+    // Review) -> Review Back (to top-level) -> top-level Back (exit).
+    askQueue.push("Review", "Review on my own", "Back", "Back", "Back");
+    const result = await showActiveTaskMenu(orchestrator, ctx, "/pp", "tool");
+    expect(result).toBe("");
+    // Review submenu rendered twice (initial + after the Editor-review Back).
+    expect(askQuestions.filter((q) => q === "Review").length).toBe(2);
+    // Top-level rendered twice (initial + after Review's explicit Back).
+    expect(askQuestions.filter((q) => q.startsWith("/pp")).length).toBe(2);
+  });
+
+  it("resumes the per-repo Plannotator cursor and interleaves fixes (#3a)", async () => {
+    const orchestrator = makeReviewOrchestrator();
+    orchestrator.active.type = "implement";
+    orchestrator.active.state.phase = "implement";
+    orchestrator.active.state.repos = [
+      { path: "/repo/a", isRoot: true },
+      { path: "/repo/b", isRoot: false },
+    ];
+    orchestrator.active.state.plannotatorCursor = { repoPaths: ["/repo/a", "/repo/b"], index: 0 };
+    orchestrator.pi = { exec: vi.fn(async () => ({ code: 0, stdout: "", stderr: "" })) };
+    orchestrator.config = getDefaultConfig();
+
+    // First repo: choose a diff scope, Plannotator returns NEEDS_CHANGES → the
+    // menu exits with a work instruction and the cursor advances to repo b.
+    plannotatorResults.push({ approved: false, feedback: "fix the thing" });
+    askQueue.push("Uncommitted changes");
+    const first = await showActiveTaskMenu(orchestrator, ctx, "/pp", "tool");
+    expect(first).toContain("Plannotator requested changes");
+    expect(first).toContain("fix the thing");
+    expect(orchestrator.active.state.plannotatorCursor).toEqual({ repoPaths: ["/repo/a", "/repo/b"], index: 1 });
+
+    // Next /pp resumes at repo b; APPROVED → cursor is cleared and the loop ends,
+    // falling through to the normal menu (top-level Back exits).
+    plannotatorResults.push({ approved: true });
+    askQueue.push("Uncommitted changes", "Back");
+    const second = await showActiveTaskMenu(orchestrator, ctx, "/pp", "tool");
+    expect(second).toBe("");
+    expect(orchestrator.active.state.plannotatorCursor).toBeUndefined();
+  });
+
+  it("blocks a second review while one is already running (#3b)", async () => {
+    const orchestrator = makeReviewOrchestrator();
+    orchestrator.active.state.reviewCycle = { kind: "auto", step: "await_reviewers", pass: 1 };
+    // isRunning() true so the top-level "Review" option is offered.
+    orchestrator.transitionController.isRunning = () => true;
+    let notified = "";
+    const notifyCtx = { ui: { notify: (t: string) => { notified = t; } }, waitForIdle: async () => {}, abort: () => {} };
+    // Pick Review (blocked → notify + back to top-level menu), then Back to exit.
+    askQueue.push("Review", "Back");
+    const result = await showActiveTaskMenu(orchestrator, notifyCtx, "/pp", "tool");
+    expect(result).toBe("");
+    expect(notified).toBe("A review is already running");
+    // The live cycle is untouched (not finalized/nulled) and the top-level menu
+    // re-rendered rather than /pp exiting.
+    expect(orchestrator.active.state.reviewCycle).toEqual({ kind: "auto", step: "await_reviewers", pass: 1 });
+    expect(askQuestions.filter((q) => q.startsWith("/pp")).length).toBe(2);
+  });
+});