@ilya-lesikov/pi-pi 0.7.0 → 0.9.0

package/extensions/orchestrator/phases/brainstorm.ts

@@ -4,7 +4,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resolvePreset, type PiPiConfig, type VariantConfig } from "../config.js";
 import { registerAgentDefinitions, spawnViaRpc, waitForCompletion } from "../agents/registry.js";
 import { createBrainstormReviewerAgent } from "../agents/brainstorm-reviewer.js";
-import { getContextDirs } from "../context.js";
+import { getContextDirs, getArtifactManifest } from "../context.js";
 import type { RepoInfo } from "../repo-utils.js";
 import type { TaskType } from "../state.js";
 import type { PhaseSend } from "../transition-controller.js";
@@ -26,13 +26,8 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
     "",
     "# Your job:",
     "1. Clarify the problem with the user if needed",
-    "2. Spawn subagents for research (subagent_type is REQUIRED — calls without it are rejected):",
-    '   - Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups.',
-    '   - Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
-    '   - Agent(subagent_type="Task", ...) — only when you need a subtask that writes files or runs complex multi-step commands.',
-    "   Explore is fast and cheap. Use it liberally for codebase questions. Spawn multiple in parallel.",
-    "3. Use bash to run commands, check logs, reproduce issues",
-    "4. Use tools to trace the bug:",
+    "2. Delegate research to subagents where useful (see the delegation guidance in your system prompt), and use bash to run commands, check logs, reproduce issues",
+    "3. Use tools to trace the bug:",
     "   - cbm_search/cbm_search_code: find relevant code by concept or text",
     "   - lsp goToDefinition, findReferences, hover: precise navigation and type info",
     "   - lsp goToImplementation: check interface implementors",
@@ -60,6 +55,7 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
       "  <Unresolved 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 .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`,
@@ -84,11 +80,7 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
       "",
       "# How to work:",
       "- Discuss the topic with the user. Ask clarifying questions. Propose approaches. Analyze tradeoffs.",
-    "- Spawn subagents for research (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.',
-    '  Agent(subagent_type="Task", ...) — only when you need a subtask that writes files or runs complex multi-step commands.',
-    "  Spawn multiple Explore agents in parallel for broad searches.",
+      "- Delegate research to subagents where useful (see the delegation guidance in your system prompt).",
       "- Use tools directly for quick lookups (cbm_search, lsp, ast_search, grep, etc.)",
       "- Present findings to the user and discuss them. Don't just dump raw results.",
       "",
@@ -115,25 +107,25 @@ 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",
-    "2. Spawn subagents for research (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.',
-    '   - Agent(subagent_type="Task", ...) — only when you need a subtask that writes files or runs complex multi-step commands.',
-    "   Spawn multiple Explore agents in parallel for broad searches.",
+    "2. Delegate research to subagents where useful (see the delegation guidance in your system prompt) — spawn multiple explores in parallel for broad searches",
     "3. Use tools to understand code structure:",
     "   - cbm_search: natural-language search across all symbols",
     "   - cbm_search_code: graph-augmented grep (deduplicates into functions)",
     "   - 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:`,
@@ -152,13 +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");
@@ -210,7 +203,7 @@ export async function spawnBrainstormReviewers(
     const agent = createBrainstormReviewerAgent(
       variant,
       reviewerVariants,
-      { userRequest, research, artifacts: artifacts.length > 0 ? artifacts : undefined },
+      { userRequest, research, artifacts: artifacts.length > 0 ? artifacts : undefined, manifest: getArtifactManifest(taskDir) },
       outputPath,
       contextDirs,
       "brainstorm",
@@ -261,7 +254,7 @@ export async function spawnBrainstormReviewers(
           `${reviewOutputFiles.length} brainstorm reviewer(s) completed (round ${round}). Reviews in ${reviewsDir}:`,
           ...reviewOutputFiles.map((f) => `  - ${f}`),
           "",
-          "Read all reviews and update USER_REQUEST.md and RESEARCH.md if needed.",
+          "Read all reviews and update USER_REQUEST.md, RESEARCH.md, and any artifacts/ files if needed.",
         ].join("\n"),
         display: true,
       },

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

@@ -0,0 +1,11 @@
+import { describe, it, expect } from "vitest";
+import { implementationSystemPrompt } from "./implementation.js";
+
+describe("implementationSystemPrompt self-complete directive", () => {
+  it("instructs the agent to call pp_phase_complete when the implement phase is complete", () => {
+    const prompt = implementationSystemPrompt("/tmp/task", "/tmp");
+    expect(prompt).toContain("pp_phase_complete");
+    expect(prompt).toContain("Do NOT instead ask the user to run /pp manually");
+    expect(prompt).not.toContain("do NOT wait for the user");
+  });
+});

package/extensions/orchestrator/phases/implementation.ts

@@ -11,7 +11,7 @@ export function implementationSystemPrompt(taskDir: string, cwd: string): string
     "# Instructions:",
     "1. Review the synthesized plan in your context",
     "2. Implement each item in order",
-    "3. Check off items in the plan (change - [ ] to - [x]) as you complete them",
+    "3. Check off items in the plan (change - [ ] to - [x]) as you complete them — use pp_edit_state_file (NOT the generic edit) to update the plan compactly",
     "4. After editing files, run lsp diagnostics to check for errors; use lsp codeActions for auto-fixes",
     "5. Before modifying code, understand it first:",
     "   - cbm_search/cbm_search_code: find relevant functions and their context",
@@ -21,11 +21,7 @@ export function implementationSystemPrompt(taskDir: string, cwd: string): string
     "   - cbm_trace: trace dependencies across the codebase",
     "   - ast_search: find structural patterns (e.g. error handling conventions)",
     "6. After completing changes, run cbm_changes to verify blast radius",
-    "7. Spawn subagents as needed (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.',
-    '   - Agent(subagent_type="Task", ...) — parallelizable, self-contained implementation subtasks.',
-    "   Spawn multiple Explore agents in parallel for broad searches.",
+    "7. Delegate to subagents where useful (see the delegation guidance in your system prompt) — spawn multiple explores in parallel for broad searches, and use task for parallelizable self-contained implementation subtasks",
     "",
     "# Commits:",
     "After completing a logical unit of work (a plan item, a bug fix, a test), call pp_commit",
@@ -34,5 +30,7 @@ export function implementationSystemPrompt(taskDir: string, cwd: string): string
     "Don't batch all changes into one commit.",
     "",
     "Fix issues found by lsp diagnostics before moving on.",
+    "",
+    "When you judge the implement phase complete, call pp_phase_complete — the extension opens the advance gate for the user to review and confirm. Do NOT instead ask the user to run /pp manually.",
   ].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/planning.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from "vitest";
+import { planningSystemPrompt } from "./planning.js";
+
+describe("planningSystemPrompt self-complete directive", () => {
+  it("guided synthesis instructs the agent to call pp_phase_complete when synthesis is complete", () => {
+    const prompt = planningSystemPrompt("/tmp/task", "guided");
+    expect(prompt).toContain("pp_phase_complete");
+    expect(prompt).toContain("Do NOT instead ask the user to run /pp manually");
+  });
+
+  it("autonomous synthesis does not add the guided self-complete directive", () => {
+    const prompt = planningSystemPrompt("/tmp/task", "autonomous");
+    expect(prompt).not.toContain("pp_phase_complete");
+    expect(prompt).not.toContain("Do NOT instead ask the user to run /pp manually");
+  });
+});

package/extensions/orchestrator/phases/planning.ts

@@ -5,7 +5,7 @@ import { resolvePreset, type PiPiConfig, type VariantConfig } from "../config.js
 import { registerAgentDefinitions, spawnViaRpc, waitForCompletion } from "../agents/registry.js";
 import { createPlannerAgent } from "../agents/planner.js";
 import { createPlanReviewerAgent } from "../agents/plan-reviewer.js";
-import { getContextDirs, getLatestSynthesizedPlan } from "../context.js";
+import { getContextDirs, getLatestSynthesizedPlan, getArtifactManifest } from "../context.js";
 import type { RepoInfo } from "../repo-utils.js";
 import { validatePlan } from "../validate-artifacts.js";
 import type { TaskMode } from "../state.js";
@@ -21,6 +21,10 @@ export function planningSystemPrompt(taskDir: string, mode: TaskMode): string {
     mode === "autonomous"
       ? "   If planner outputs CONTRADICT each other on a locked decision, resolve it by favoring USER_REQUEST.md, RECORD the contradiction and your chosen resolution in the plan, and proceed — do NOT stall waiting for the user (there is none)."
       : "   If planner outputs CONTRADICT each other on a locked decision, surface the contradiction to the user and let them decide — do NOT silently invent a compromise.";
+  const synthesizeCompletionRule =
+    mode === "autonomous"
+      ? ""
+      : "When you judge the plan synthesis complete, call pp_phase_complete — the extension opens the advance gate for the user to review and confirm. Do NOT instead ask the user to run /pp manually.";
   return [
     "[PI-PI — PLAN PHASE]",
     "",
@@ -46,9 +50,12 @@ export function planningSystemPrompt(taskDir: string, mode: TaskMode): string {
     "- ## 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 this section whenever the task adds a type, function, parser, annotation, config key, enum, or any user-facing value. For each, name the CLOSEST EXISTING analog in the codebase (found by behavior, not filename) and the exact conventions the implementer MUST mirror: data shape (prefer one existing shape over inventing parallel/duplicated state), spelling/casing of user-facing values (match existing values — never invent a new casing), and parser/validation/error-handling shape. These are acceptance criteria, not suggestions. Omit the section only if the task adds none of the above.",
     "- ## Blockers: unresolved issues blocking implementation (omit if none)",
+    "Write/update the synthesized plan with pp_write_state_file / pp_edit_state_file (NOT the generic write/edit) — they keep the output compact and validate structure.",
     "- No other top-level sections allowed",
-    "- Describe outcomes, not code-level mechanics",
+    "- Describe outcomes, not code-level mechanics, EXCEPT in ## Pattern constraints where naming the concrete analog and conventions is required",
+    ...(synthesizeCompletionRule ? ["", synthesizeCompletionRule] : []),
   ].join("\n");
 }
 
@@ -84,7 +91,7 @@ export async function spawnPlanners(
 
   for (const [variant] of enabledVariants) {
     const outputPath = join(plansDir, `${timestamp}_${variant}.md`);
-    const agent = createPlannerAgent(variant, plannerVariants, { userRequest, research }, outputPath, contextDirs, "plan", repos);
+    const agent = createPlannerAgent(variant, plannerVariants, { userRequest, research, manifest: getArtifactManifest(taskDir) }, outputPath, contextDirs, "plan", repos);
 
     registerAgentDefinitions(pi, [{ type: "planner", variant, ...agent }]);
 
@@ -211,7 +218,7 @@ export async function spawnPlanReviewers(
     const agent = createPlanReviewerAgent(
       variant,
       reviewerVariants,
-      { userRequest, research, synthesizedPlan },
+      { userRequest, research, synthesizedPlan, manifest: getArtifactManifest(taskDir) },
       outputPath,
       contextDirs,
       "plan",

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,34 +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",
-    "",
-    "Spawn subagents as needed (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.",
-    "",
-    "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)",
+    "- 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.",
+    "",
+    "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

@@ -23,6 +23,14 @@ describe("reviewSystemPrompt apply_feedback wording", () => {
     expect(auto).not.toContain("pp_phase_complete");
   });
 
+  it("brainstorm apply-feedback prompt permits artifact updates and steers to the compact tools", () => {
+    const prompt = reviewSystemPrompt("/tmp/task", 1, "brainstorm", "autonomous");
+    expect(prompt).toContain("artifacts/");
+    expect(prompt).toContain("pp_write_state_file");
+    // The no-new-sections rule for the two structured files is retained.
+    expect(prompt).toContain("Do NOT add, rename, or remove sections in USER_REQUEST.md or RESEARCH.md");
+  });
+
   it("autonomous plan feedback folds into a new synthesized plan, not a separate fix-plan file", () => {
     // Re-review and the transition read only the latest `*synthesized*` plan, so
     // plan-phase feedback must land there.
@@ -37,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

@@ -4,7 +4,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resolvePreset, type PiPiConfig, type VariantConfig } from "../config.js";
 import { registerAgentDefinitions, spawnViaRpc, waitForCompletion } from "../agents/registry.js";
 import { createCodeReviewerAgent } from "../agents/code-reviewer.js";
-import { getContextDirs, getLatestSynthesizedPlan } from "../context.js";
+import { getContextDirs, getLatestSynthesizedPlan, getArtifactManifest } from "../context.js";
 import type { RepoInfo } from "../repo-utils.js";
 import type { PhaseSend } from "../transition-controller.js";
 
@@ -38,13 +38,48 @@ export function reviewSystemPrompt(taskDir: string, pass: number, phase?: string
       "# Your job:",
       `1. Read ALL reviewer outputs from ${reviewsDir}/`,
       "2. Identify valid gaps and inaccuracies that would block planning",
-      "3. If changes are needed: update ONLY the content within existing sections of USER_REQUEST.md / RESEARCH.md",
+      "3. If changes are needed: update the content within existing sections of USER_REQUEST.md / RESEARCH.md, and add/update artifacts/ files as needed",
       "4. If reviewers found no actionable gaps (e.g. task already done, minor suggestions only): do NOT modify the files",
       "5. Ignore suggestions that don't affect downstream planning quality",
       "",
       "USER_REQUEST.md MUST keep exactly: # User Request, ## Problem, ## Constraints",
       "RESEARCH.md MUST keep exactly: ## Affected Code, ## Architecture Context, ## Constraints & Edge Cases, ## Open Questions (optional)",
       "Any other sections will fail validation.",
+      "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.",
+    ].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");
   }
 
@@ -101,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");
@@ -131,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",
@@ -159,7 +197,7 @@ export async function spawnCodeReviewers(
     const agent = createCodeReviewerAgent(
       variant,
       reviewerVariants,
-      { userRequest, research, synthesizedPlan },
+      { userRequest, research, synthesizedPlan, manifest: getArtifactManifest(taskDir) },
       outputPath,
       contextDirs,
       reviewerPhase,

package/extensions/orchestrator/plannotator.ts

@@ -46,7 +46,8 @@ export function cancelPendingPlannotatorWait(orchestrator: Orchestrator): void {
 export function waitForPlannotatorResult(
   orchestrator: Orchestrator,
   reviewId: string | null,
-): Promise<{ approved: boolean; feedback?: string }> {
+  timeoutMs: number | null = PLANNOTATOR_RESULT_TIMEOUT_MS,
+): Promise<{ approved: boolean; feedback?: string; error?: string }> {
   cancelPendingPlannotatorWait(orchestrator);
   const pi = orchestrator.pi;
   return new Promise((resolve, reject) => {
@@ -54,7 +55,7 @@ export function waitForPlannotatorResult(
     const unsub = pi.events.on("plannotator:review-result", (data: any) => {
       if (reviewId && data?.reviewId && data.reviewId !== reviewId) return;
       cleanup();
-      resolve({ approved: !!data?.approved, feedback: data?.feedback });
+      resolve({ approved: !!data?.approved, feedback: data?.feedback, error: data?.error });
     });
     orchestrator.plannotatorUnsub = unsub;
     function cleanup() {
@@ -66,9 +67,11 @@ export function waitForPlannotatorResult(
         orchestrator.plannotatorTimer = null;
       }
     }
-    orchestrator.plannotatorTimer = setTimeout(() => {
-      cleanup();
-      reject(new Error("Plannotator review timed out"));
-    }, PLANNOTATOR_RESULT_TIMEOUT_MS);
+    if (timeoutMs !== null) {
+      orchestrator.plannotatorTimer = setTimeout(() => {
+        cleanup();
+        reject(new Error("Plannotator review timed out"));
+      }, timeoutMs);
+    }
   });
 }