@difflab/pi 0.5.0 → 0.6.0-rc.202609262054.4a8e556

package/dist/tools/index.js

@@ -503,6 +503,16 @@ function diffpiLaunchName(cwd, workflow) {
 }
 async function openFileAdjacent(path, opts) {
   const env = opts.env ?? process.env;
+  const mux = detectMux(env);
+  if (mux !== "none") {
+    const editor = await resolveEditor(env);
+    if (editor) {
+      const command = persistentEditorArgs(editor, path, opts.cwd, env.SHELL);
+      const opened = await openMuxTab(mux, command, opts.cwd, opts.name ?? "plan", [editor, path].join(" "), command);
+      if (opened)
+        return opened;
+    }
+  }
   const ide = detectIde(env);
   if (ide !== "unknown") {
     const ideCommand = { zed: "zed", vscode: "code", cursor: "cursor", windsurf: "windsurf", jetbrains: "idea" }[ide];
@@ -512,16 +522,6 @@ async function openFileAdjacent(path, opts) {
         return { launched: true, via: ide, command: `${ideCommand} ${path}` };
     }
   }
-  const mux = detectMux(env);
-  if (mux !== "none") {
-    const editor = await resolveEditor(env);
-    if (editor) {
-      const command = [editor, path];
-      const opened = await openMuxTab(mux, command, opts.cwd, opts.name ?? "plan", command.join(" "));
-      if (opened)
-        return opened;
-    }
-  }
   return { launched: false, via: "print", command: path, reason: "No supported IDE or multiplexer was available." };
 }
 async function openInNewTab(command, opts) {
@@ -556,10 +556,15 @@ async function openInNewTab(command, opts) {
 function screenWindowArgs(command, cwd, name) {
   return ["-X", "screen", "-t", name, "sh", "-lc", 'cd -- "$1" && shift && exec "$@"', "sh", cwd, ...command];
 }
+function persistentEditorArgs(editor, path, cwd, shell = "sh") {
+  return ["bash", "-lc", 'cd -- "$1" && shift && "$@"; exec "$0" -i', shell, cwd, editor, path];
+}
 async function resolveEditor(env) {
-  const configured = (env.VISUAL ?? env.EDITOR)?.trim().split(/\s+/)[0];
-  if (configured && await findExecutable(configured))
-    return configured;
+  for (const configured of [env.EDITOR, env.VISUAL]) {
+    const editor = configured?.trim();
+    if (editor && await findExecutable(editor))
+      return editor;
+  }
   for (const candidate of ["hx", "nvim", "vim"])
     if (await findExecutable(candidate))
       return candidate;
@@ -576,7 +581,7 @@ async function packageVersion() {
     throw new Error("Cannot resolve the installed @difflab/pi version.");
   return value.version;
 }
-async function openMuxTab(mux, command, cwd, name, printable) {
+async function openMuxTab(mux, command, cwd, name, printable, tmuxCommand) {
   if (mux === "zellij" && await findExecutable("zellij")) {
     const result = await run("zellij", ["action", "new-tab", "--cwd", cwd, "--name", name, "--", ...command]);
     if (result.code === 0)
@@ -586,7 +591,7 @@ async function openMuxTab(mux, command, cwd, name, printable) {
       return { launched: true, via: "zellij-run", command: printable };
   }
   if (mux === "tmux" && await findExecutable("tmux")) {
-    const result = await run("tmux", ["new-window", "-c", cwd, "-n", name, printable]);
+    const result = tmuxCommand ? await run("tmux", ["new-window", "-c", cwd, "-n", name, ...tmuxCommand]) : await run("tmux", ["new-window", "-c", cwd, "-n", name, printable]);
     if (result.code === 0)
       return { launched: true, via: "tmux", command: printable };
   }
@@ -1285,7 +1290,7 @@ function sanitize(value) {
 }
 
 // src/tools/plan.ts
-import { join as join14 } from "node:path";
+import { join as join15 } from "node:path";
 import { pathToFileURL } from "node:url";
 import { defineTool as defineTool5 } from "@earendil-works/pi-coding-agent";
 import { z as z7 } from "zod";
@@ -1522,6 +1527,9 @@ async function discoverMiseTasks(cwd) {
 
 // src/plan/markdown.ts
 var import_mdast_builder = __toESM(require_src(), 1);
+import { createHash as createHash2 } from "node:crypto";
+import { readFile as readFile5, readdir } from "node:fs/promises";
+import { join as join10 } from "node:path";
 
 // ../../node_modules/zwitch/index.js
 var own = {}.hasOwnProperty;
@@ -6161,6 +6169,8 @@ function isUint8Array2(value) {
 var PLAN_MARKER = /<!-- diffpi-plan: (\{[^\n]+\}) -->/;
 var PHASE_MARKER = /<!-- diffpi-phase: (\{[^\n]+\}) -->/g;
 var TASK_MARKER = /<!-- diffpi-task: (\{[^\n]+\}) -->/g;
+var BRIEF_MARKER = /<!-- diffpi-implementation: (\{[^\n]+\}) -->/;
+var BRIEF_TASK_MARKER = /<!-- diffpi-brief-task: (\{[^\n]+\}) -->/g;
 var SUPPORTED_SCHEMA = 1;
 function countDesignWords(plan) {
   return [plan.design.bigIdeas, plan.design.keyApiUpdates, plan.design.consequences].join(" ").trim().split(/\s+/).filter(Boolean).length;
@@ -6189,11 +6199,13 @@ function validatePlanDocument(plan, options = {}) {
         if (!taskIds.has(dependency))
           add("dangling-dependency", "error", `Task ${task.id} depends on missing ${dependency}.`);
       }
-      if (options.strict && task.acceptanceCriteria.length === 0)
-        add("acceptance", "error", `Task ${task.id} has no acceptance criteria.`, task.id);
+      if (options.strict && isPlaceholder(task.title))
+        add("placeholder", "error", `Task ${task.id} has placeholder content.`, task.id);
     }
     if (options.strict && phase.tasks.length === 0)
       add("empty-phase", "error", `Phase ${phase.id} has no tasks.`, phase.id);
+    if (options.strict && (isPlaceholder(phase.title) || isPlaceholder(phase.objective)))
+      add("placeholder", "error", `Phase ${phase.id} has placeholder content.`, phase.id);
   }
   for (const cycle of dependencyCycles(plan))
     add("dependency-cycle", "error", `Dependency cycle: ${cycle.join(" -> ")}.`);
@@ -6202,10 +6214,140 @@ function validatePlanDocument(plan, options = {}) {
     add("design-length", "warning", `Design is ${designWords} words; prefer 300 or fewer.`);
   if (options.strict && designWords > 800)
     add("design-too-long", "error", `Design is ${designWords} words; finalization allows at most 800.`);
-  if (options.strict && plan.phases.length === 0)
-    add("no-phases", "error", "Finalization requires at least one phase.");
+  if (options.strict) {
+    if (plan.phases.length === 0)
+      add("no-phases", "error", "Finalization requires at least one phase.");
+    if (isPlaceholder(plan.intent))
+      add("placeholder", "error", "Intent must contain concrete content.", "intent");
+    if (!plan.requirements.length || plan.requirements.some(isPlaceholder))
+      add("requirements", "error", "Requirements must contain concrete content.", "requirements");
+    for (const [key, value] of Object.entries(plan.design)) {
+      if (isPlaceholder(value))
+        add("design", "error", `Design/${key} must contain concrete content.`, `design.${key}`);
+    }
+  }
+  return issues;
+}
+function validatePlanBriefs(plan, briefs) {
+  const issues = [];
+  const phaseIds = plan.phases.map((phase) => phase.id);
+  const briefIds = briefs.map((brief) => brief.phaseId);
+  if (!sameIds(phaseIds, briefIds))
+    issues.push({
+      code: "brief-phase-ids",
+      severity: "error",
+      message: `Brief phase IDs must exactly match plan phases in order: ${phaseIds.join(", ")}.`
+    });
+  for (const [index, phase] of plan.phases.entries()) {
+    const brief = briefs[index];
+    if (!brief || brief.phaseId !== phase.id)
+      continue;
+    if (isPlaceholder(brief.summary))
+      issues.push({ code: "brief-placeholder", severity: "error", message: `Brief ${phase.id} needs a summary.` });
+    const taskIds = phase.tasks.map((task) => task.id);
+    const briefTaskIds = brief.tasks.map((task) => task.taskId);
+    if (!sameIds(taskIds, briefTaskIds))
+      issues.push({
+        code: "brief-task-ids",
+        severity: "error",
+        message: `Brief ${phase.id} task IDs must exactly match phase tasks in order: ${taskIds.join(", ")}.`
+      });
+    for (const task of brief.tasks) {
+      for (const [field, values] of [
+        ["ordered steps", task.steps],
+        ["file scopes", task.fileScopes],
+        ["acceptance criteria", task.acceptanceCriteria]
+      ]) {
+        if (!values.length || values.some(isPlaceholder))
+          issues.push({
+            code: "brief-incomplete",
+            severity: "error",
+            message: `Brief task ${task.taskId} needs concrete ${field}.`,
+            path: task.taskId
+          });
+      }
+    }
+    for (const [field, values] of [
+      ["API changes", brief.apiChanges],
+      ["libraries", brief.libraries],
+      ["constraints", brief.constraints]
+    ]) {
+      if (values.some(isPlaceholder))
+        issues.push({
+          code: "brief-placeholder",
+          severity: "error",
+          message: `Brief ${phase.id} has placeholder ${field}.`,
+          path: phase.id
+        });
+    }
+  }
+  return issues;
+}
+async function validatePlanRecord(record, options = {}) {
+  const issues = validatePlanDocument(record.document, options);
+  if (!options.strict)
+    return issues;
+  await validateImplementationDirectory(record.dir, record.document, issues, "latest");
+  if (options.checkSnapshots !== false)
+    await validateRevisionSnapshots(record, issues);
   return issues;
 }
+function renderImplementationBrief(planRevision, ordinal, phase, brief) {
+  const marker = { schemaVersion: 1, planRevision, ordinal, phaseId: phase.id };
+  const tasks = phase.tasks.map((task, index) => {
+    const details = brief.tasks[index];
+    if (!details || details.taskId !== task.id)
+      throw new Error(`Missing implementation details for ${task.id}.`);
+    return `<!-- diffpi-brief-task: ${json({ id: task.id })} -->
+### Task: ${task.title}
+
+#### Ordered Steps
+
+${bulletList(details.steps)}
+
+#### File Scopes
+
+${bulletList(details.fileScopes)}
+
+#### Acceptance Criteria
+
+${bulletList(details.acceptanceCriteria)}
+
+<!-- /diffpi-brief-task -->`;
+  }).join(`
+
+`);
+  return `<!-- diffpi-implementation: ${json(marker)} -->
+# Phase ${ordinal}: ${phase.title}
+
+- **Phase ID:** ${phase.id}
+- **Plan Revision:** ${planRevision}
+
+## Summary
+
+${brief.summary}
+
+## Objective
+
+${phase.objective}
+
+## Tasks
+
+${tasks}
+
+## API Changes
+
+${bulletList(brief.apiChanges, "None.")}
+
+## Libraries and Algorithms
+
+${bulletList(brief.libraries, "None.")}
+
+## Implementation Constraints
+
+${bulletList(brief.constraints, "None.")}
+`;
+}
 function renderPlanDocument(plan, previousSource) {
   if (previousSource && canPatch(previousSource, plan))
     return patchMarkers(previousSource, plan);
@@ -6214,6 +6356,8 @@ function renderPlanDocument(plan, previousSource) {
     id: plan.id,
     revision: plan.revision,
     branch: plan.branch,
+    issueId: plan.issueId,
+    issueUrl: plan.issueUrl,
     status: plan.status,
     execution: plan.execution,
     createdAt: plan.createdAt,
@@ -6222,6 +6366,8 @@ function renderPlanDocument(plan, previousSource) {
   const metadata = import_mdast_builder.list("unordered", [
     ["Plan ID", plan.id],
     ["Branch", plan.branch],
+    ...plan.issueId ? [["Issue", plan.issueId]] : [],
+    ...plan.issueUrl ? [["Issue URL", plan.issueUrl]] : [],
     ["Status", plan.status],
     ["Revision", String(plan.revision)]
   ].map(([label, value]) => import_mdast_builder.listItem(import_mdast_builder.paragraph([import_mdast_builder.strong(import_mdast_builder.text(`${label}:`)), import_mdast_builder.text(` ${value}`)]))));
@@ -6243,7 +6389,7 @@ function renderPlanDocument(plan, previousSource) {
     import_mdast_builder.heading(3, import_mdast_builder.text("Consequences")),
     import_mdast_builder.html(plan.design.consequences || "<!-- Describe trade-offs and limitations. -->"),
     import_mdast_builder.heading(2, import_mdast_builder.text("Implementation")),
-    ...plan.phases.length ? plan.phases.flatMap((phase) => [import_mdast_builder.html(renderPhase(phase))]) : [import_mdast_builder.html("<!-- Add phases with plan_add_phase. -->")],
+    ...plan.phases.length ? plan.phases.flatMap((phase) => [import_mdast_builder.html(renderPhase(phase))]) : [import_mdast_builder.html("<!-- Add phases with plan_apply_revision. -->")],
     import_mdast_builder.heading(2, import_mdast_builder.text("References")),
     references
   ]);
@@ -6317,10 +6463,7 @@ function renderTask(task) {
   const checked = task.status === "completed" || task.status === "skipped" ? "x" : " ";
   return `<!-- diffpi-task: ${json(marker)} -->
 - [${checked}] **${task.title}**
-${taskList("Steps", task.steps ?? [])}
   - Dependencies: ${list3(task.dependencies)}
-${taskList("File scopes", task.fileScopes)}
-${taskList("Acceptance criteria", task.acceptanceCriteria)}
 <!-- /diffpi-task -->`;
 }
 function parsePhases(input, ref) {
@@ -6370,10 +6513,7 @@ function parseTasks(input, ref) {
     return {
       ...marker,
       title,
-      steps: parseListValue(body, "Steps"),
-      dependencies: parseListValue(body, "Dependencies"),
-      fileScopes: parseListValue(body, "File scopes"),
-      acceptanceCriteria: parseListValue(body, "Acceptance criteria")
+      dependencies: parseListValue(body, "Dependencies")
     };
   });
   assertUniqueIds(tasks.map((task) => task.id), "task id");
@@ -6400,6 +6540,8 @@ function patchMarkers(source, plan) {
     id: plan.id,
     revision: plan.revision,
     branch: plan.branch,
+    issueId: plan.issueId,
+    issueUrl: plan.issueUrl,
     status: plan.status,
     execution: plan.execution,
     createdAt: plan.createdAt,
@@ -6449,19 +6591,12 @@ function contentShape(plan) {
     requirements: plan.requirements,
     design: plan.design,
     references: plan.references,
-    phases: plan.phases.map(({ id, title, objective, dependencies, tasks }) => ({
-      id,
-      title,
-      objective,
-      dependencies,
-      tasks: tasks.map(({ id: taskId, title: taskTitle, steps, dependencies: taskDependencies, fileScopes, acceptanceCriteria }) => ({
-        id: taskId,
-        title: taskTitle,
-        steps,
-        dependencies: taskDependencies,
-        fileScopes,
-        acceptanceCriteria
-      }))
+    phases: plan.phases.map((phase) => ({
+      id: phase.id,
+      title: phase.title,
+      objective: phase.objective,
+      dependencies: phase.dependencies,
+      tasks: phase.tasks.map(({ id, title, dependencies }) => ({ id, title, dependencies }))
     }))
   };
 }
@@ -6491,6 +6626,152 @@ function dependencyCycles(plan) {
     walk(id, []);
   return cycles;
 }
+async function validateRevisionSnapshots(record, issues) {
+  const revisionsDir = join10(record.dir, "revisions");
+  let entries;
+  try {
+    entries = await readdir(revisionsDir);
+  } catch {
+    issues.push({ code: "snapshot-missing", severity: "error", message: "Missing revisions directory." });
+    return;
+  }
+  const expected = Array.from({ length: record.document.revision + 1 }, (_, index) => String(index));
+  if (!sameIds(expected, entries.filter((entry) => /^\d+$/.test(entry)).sort((a, b) => Number(a) - Number(b))))
+    issues.push({
+      code: "snapshot-sequence",
+      severity: "error",
+      message: `Revision snapshots must be exactly ${expected.join(", ")}.`,
+      path: revisionsDir
+    });
+  for (const entry of entries) {
+    if (!/^\d+$/.test(entry))
+      issues.push({ code: "snapshot-entry", severity: "error", message: `Unexpected revisions entry: ${entry}.` });
+  }
+  for (const revision of expected) {
+    const dir = join10(revisionsDir, revision);
+    try {
+      const [request, metadataSource, planSource] = await Promise.all([
+        readFile5(join10(dir, "request.md"), "utf8"),
+        readFile5(join10(dir, "metadata.json"), "utf8"),
+        readFile5(join10(dir, "PLAN.md"), "utf8")
+      ]);
+      if (isPlaceholder(request))
+        issues.push({ code: "snapshot-request", severity: "error", message: `Revision ${revision} request is empty.` });
+      const metadata = JSON.parse(metadataSource);
+      const annotation = metadata.requestKind === "annotation" ? /^## Original annotation\n([\s\S]*?)\n\n## LLM response\n([\s\S]*)$/.exec(request) : undefined;
+      const requestText = annotation?.[1];
+      const responseText = annotation?.[2];
+      if (metadata.schemaVersion !== 1 || metadata.id !== record.id || metadata.revision !== Number(revision) || !["user", "annotation", "blocker"].includes(metadata.requestKind) || (metadata.requestKind === "annotation" ? !annotation || !requestText?.trim() || !responseText?.trim() || metadata.requestSha256 !== sha256(requestText) || metadata.originalAnnotationSha256 !== sha256(requestText) || metadata.responseSha256 !== sha256(responseText) : metadata.requestSha256 !== sha256(request)))
+        issues.push({
+          code: "snapshot-metadata",
+          severity: "error",
+          message: `Revision ${revision} metadata does not match its immutable request.`
+        });
+      const snapshotPlan = parsePlanDocument(planSource, join10(dir, "PLAN.md"));
+      if (snapshotPlan.id !== record.id || snapshotPlan.revision !== Number(revision))
+        issues.push({
+          code: "snapshot-plan",
+          severity: "error",
+          message: `Revision ${revision} PLAN.md has mismatched identity or revision.`
+        });
+      await validateImplementationDirectory(dir, snapshotPlan, issues, `revision ${revision}`);
+    } catch (error) {
+      issues.push({
+        code: "snapshot-missing",
+        severity: "error",
+        message: `Revision ${revision} is incomplete: ${error.message}`,
+        path: dir
+      });
+    }
+  }
+}
+async function validateImplementationDirectory(baseDir, plan, issues, label) {
+  const dir = join10(baseDir, "implementation");
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    issues.push({
+      code: "brief-directory",
+      severity: "error",
+      message: `${label} is missing implementation/.`,
+      path: dir
+    });
+    return;
+  }
+  const expected = plan.phases.map((_phase, index) => `phase-${index + 1}.md`);
+  const actual = entries.filter((entry) => entry.endsWith(".md")).sort((left, right) => left.localeCompare(right));
+  if (!sameIds([...expected].sort((left, right) => left.localeCompare(right)), actual))
+    issues.push({
+      code: "brief-filenames",
+      severity: "error",
+      message: `${label} briefs must use exactly: ${expected.join(", ") || "(none)"}.`,
+      path: dir
+    });
+  for (const [index, phase] of plan.phases.entries()) {
+    const path = join10(dir, `phase-${index + 1}.md`);
+    try {
+      validateBriefSource(await readFile5(path, "utf8"), plan.revision, index + 1, phase, path, issues);
+    } catch (error) {
+      issues.push({
+        code: "brief-missing",
+        severity: "error",
+        message: `${label} brief phase-${index + 1}.md is missing: ${error.message}`,
+        path
+      });
+    }
+  }
+}
+function validateBriefSource(source, planRevision, ordinal, phase, path, issues) {
+  const matches = source.match(new RegExp(BRIEF_MARKER.source, "g")) ?? [];
+  const markerMatch = source.match(BRIEF_MARKER);
+  if (matches.length !== 1 || !markerMatch) {
+    issues.push({ code: "brief-marker", severity: "error", message: `${path} needs one implementation marker.`, path });
+    return;
+  }
+  const marker = parseMarker(markerMatch[1], `${path} implementation`);
+  if (marker.schemaVersion !== 1 || marker.planRevision !== planRevision || marker.ordinal !== ordinal || marker.phaseId !== phase.id)
+    issues.push({
+      code: "brief-marker",
+      severity: "error",
+      message: `${path} marker must identify phase ${ordinal} (${phase.id}) at revision ${planRevision}.`,
+      path
+    });
+  const taskIds = [...source.matchAll(BRIEF_TASK_MARKER)].map((match) => parseMarker(match[1], `${path} task`).id);
+  if (!sameIds(phase.tasks.map((task) => task.id), taskIds))
+    issues.push({
+      code: "brief-task-ids",
+      severity: "error",
+      message: `${path} task markers must exactly match phase task IDs in order.`,
+      path
+    });
+  const prose = source.replace(BRIEF_MARKER, "").replace(BRIEF_TASK_MARKER, "").replace(/<!-- \/diffpi-brief-task -->/g, "");
+  if (/<!--[^]*?-->|\b(?:TODO|TBD)\b|define during implementation/i.test(prose))
+    issues.push({
+      code: "brief-placeholder",
+      severity: "error",
+      message: `${path} contains placeholder content.`,
+      path
+    });
+  try {
+    if (isPlaceholder(section(source, "Summary")))
+      throw new Error("Summary is empty.");
+    for (const task of phase.tasks) {
+      const taskStart = source.indexOf(`<!-- diffpi-brief-task: ${json({ id: task.id })} -->`);
+      const taskEnd = source.indexOf("<!-- /diffpi-brief-task -->", taskStart);
+      if (taskStart < 0 || taskEnd < 0)
+        throw new Error(`Task ${task.id} body is missing.`);
+      const body = source.slice(taskStart, taskEnd);
+      for (const heading of ["Ordered Steps", "File Scopes", "Acceptance Criteria"]) {
+        const content = briefSubsection(body, heading);
+        if (!parseBullets(content).length || parseBullets(content).some(isPlaceholder))
+          throw new Error(`Task ${task.id} ${heading} is incomplete.`);
+      }
+    }
+  } catch (error) {
+    issues.push({ code: "brief-incomplete", severity: "error", message: `${path}: ${error.message}`, path });
+  }
+}
 function section(source, heading) {
   const match = source.match(new RegExp(`^## ${escapeRegExp(heading)}\\s*$`, "m"));
   if (!match?.index) {
@@ -6515,6 +6796,14 @@ function subsection(source, parent, heading) {
 function parseBullets(input) {
   return [...input.matchAll(/^- (?!<!--)(.+)$/gm)].map((match) => match[1].trim());
 }
+function briefSubsection(source, heading) {
+  const match = source.match(new RegExp(`^#### ${escapeRegExp(heading)}\\s*$`, "m"));
+  if (match?.index === undefined)
+    throw new Error(`Missing required brief heading: ${heading}.`);
+  const rest = source.slice(match.index + match[0].length);
+  const end = rest.search(/^#### |^<!-- \/diffpi-brief-task -->/m);
+  return (end < 0 ? rest : rest.slice(0, end)).trim();
+}
 function parseListValue(body, label) {
   const match = new RegExp(`^ {2}- ${escapeRegExp(label)}:[ \\t]*(.*)$`, "m").exec(body);
   if (!match)
@@ -6561,6 +6850,16 @@ function assertUniqueIds(ids, label) {
 function cleanPlaceholder(value) {
   return value.replace(/<!--[^]*?-->/g, "").trim();
 }
+function isPlaceholder(value) {
+  const normalized = cleanPlaceholder(value).trim();
+  return normalized.length === 0 || /^(?:todo|tbd|none|n\/a)$/i.test(normalized) || /define during implementation|describe the|add requirements|add implementation/i.test(normalized);
+}
+function sameIds(expected, actual) {
+  return expected.length === actual.length && expected.every((value, index) => actual[index] === value);
+}
+function sha256(value) {
+  return createHash2("sha256").update(value).digest("hex");
+}
 function parseMarker(value, label) {
   try {
     return JSON.parse(value);
@@ -6568,15 +6867,14 @@ function parseMarker(value, label) {
     throw new Error(`Malformed ${label} marker JSON.`);
   }
 }
-function taskList(label, values) {
+function bulletList(values, empty = "") {
   if (!values.length)
-    return `  - ${label}: none`;
-  const items = values.flatMap((value) => {
+    return empty;
+  return values.flatMap((value) => {
     const [first = "", ...continuations] = value.split(`
 `);
-    return [`    - ${first}`, ...continuations.map((line) => `      ${line}`)];
-  });
-  return [`  - ${label}:`, ...items].join(`
+    return [`- ${first}`, ...continuations.map((line) => `  ${line}`)];
+  }).join(`
 `);
 }
 function list3(values) {
@@ -6902,13 +7200,13 @@ function heartbeat(plan) {
 }
 
 // src/plan/reviews.ts
-import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile3 } from "node:fs/promises";
-import { dirname as dirname5, join as join10 } from "node:path";
+import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile3 } from "node:fs/promises";
+import { dirname as dirname5, join as join11 } from "node:path";
 async function readPlanReview(record) {
   const path = reviewPath(record);
   let source;
   try {
-    source = await readFile5(path, "utf8");
+    source = await readFile6(path, "utf8");
   } catch (error) {
     if (error.code === "ENOENT")
       return;
@@ -6925,7 +7223,7 @@ async function readPlanReview(record) {
   return { path, dump };
 }
 function reviewPath(record) {
-  return join10(record.dir, "reviews", `${record.document.revision}.json`);
+  return join11(record.dir, "reviews", `${record.document.revision}.json`);
 }
 function isPlanReviewDump(value) {
   if (!value || typeof value !== "object")
@@ -6935,14 +7233,15 @@ function isPlanReviewDump(value) {
 }
 
 // src/plan/store.ts
-import { mkdir as mkdir6, readdir, readFile as readFile7, realpath as realpath3, rm as rm2 } from "node:fs/promises";
-import { basename as basename5, dirname as dirname7, join as join13, resolve as resolve3, sep } from "node:path";
+import { createHash as createHash3, randomUUID as randomUUID2 } from "node:crypto";
+import { mkdir as mkdir6, readdir as readdir2, readFile as readFile8, realpath as realpath3, rename as rename2, rm as rm2 } from "node:fs/promises";
+import { basename as basename5, dirname as dirname7, join as join14, resolve as resolve3, sep } from "node:path";
 
 // src/extensions/fsx.ts
 import { mkdir as mkdir5, rename, rm, writeFile as writeFile4 } from "node:fs/promises";
-import { basename as basename4, dirname as dirname6, join as join11 } from "node:path";
+import { basename as basename4, dirname as dirname6, join as join12 } from "node:path";
 async function atomicWrite(path, content) {
-  const temp = join11(dirname6(path), `.${basename4(path)}.${crypto.randomUUID()}.tmp`);
+  const temp = join12(dirname6(path), `.${basename4(path)}.${crypto.randomUUID()}.tmp`);
   await writeFile4(temp, content, { encoding: "utf8", mode: 384, flag: "wx" });
   await rename(temp, path);
 }
@@ -6973,13 +7272,13 @@ function sleep(ms) {
 }
 
 // src/templates.ts
-import { readFile as readFile6 } from "node:fs/promises";
+import { readFile as readFile7 } from "node:fs/promises";
 import { homedir as homedir4 } from "node:os";
-import { join as join12, normalize } from "node:path";
+import { join as join13, normalize } from "node:path";
 async function loadTemplate(name, options = {}) {
   const relative = templateRelativePath(name);
-  const userPath = join12(options.homeDir ?? homedir4(), ".difflab", "diffpi", "templates", relative);
-  const bundledPath = join12(options.bundledDir ?? resolveBundledTemplatesDir(), relative);
+  const userPath = join13(options.homeDir ?? homedir4(), ".difflab", "diffpi", "templates", relative);
+  const bundledPath = join13(options.bundledDir ?? resolveBundledTemplatesDir(), relative);
   const user = await readOptionalFile(userPath);
   if (user !== undefined)
     return { name, path: userPath, source: "user", content: user };
@@ -7000,7 +7299,7 @@ function templateRelativePath(name) {
 }
 async function readOptionalFile(path) {
   try {
-    return await readFile6(path, "utf8");
+    return await readFile7(path, "utf8");
   } catch (error) {
     if (error.code === "ENOENT")
       return;
@@ -7015,7 +7314,7 @@ function planRecordName(shortSlug, date = new Date) {
 }
 async function resolvePlan(cwd, query, filters = {}, options = {}) {
   const root = await plansDir(cwd, options.homeDir);
-  const entries = await readdir(root, { withFileTypes: true });
+  const entries = await readdir2(root, { withFileTypes: true });
   const normalizedQuery = query ? normalizeQuery(query) : undefined;
   const records = [];
   for (const entry of entries) {
@@ -7023,7 +7322,7 @@ async function resolvePlan(cwd, query, filters = {}, options = {}) {
       continue;
     if (normalizedQuery && entry.name !== normalizedQuery && stripDate(entry.name) !== normalizedQuery)
       continue;
-    const dir = join13(root, entry.name);
+    const dir = join14(root, entry.name);
     await assertContained(root, dir);
     try {
       const record = await readRecord(dir);
@@ -7042,6 +7341,15 @@ async function resolvePlan(cwd, query, filters = {}, options = {}) {
 }
 function createPlanStore(options = {}) {
   const now = options.now ?? (() => new Date);
+  const read = async (cwd, query, filters) => {
+    const result = await resolvePlan(cwd, query, filters, options);
+    if (!result.record) {
+      if (result.ambiguous)
+        throw new Error(`Plan query "${query}" is ambiguous: ${result.candidates.map((item) => item.id).join(", ")}.`);
+      throw new Error(`Plan "${query}" was not found.`);
+    }
+    return result.record;
+  };
   return {
     context(cwd, query, filters) {
       return resolvePlan(cwd, query, filters, options);
@@ -7049,120 +7357,318 @@ function createPlanStore(options = {}) {
     async init(input) {
       const root = await plansDir(input.cwd, options.homeDir);
       const id = planRecordName(input.shortSlug, now());
-      const dir = join13(root, id);
-      await assertContained(root, dirname7(dir));
-      try {
-        await mkdir6(dir);
-      } catch (error) {
-        if (error.code === "EEXIST")
-          throw new Error(`Plan ${id} already exists.`);
-        throw error;
-      }
+      const dir = join14(root, id);
+      await createPlanDirectory(root, dir, id);
       try {
         const timestamp = now().toISOString();
         const template = await loadTemplate("plan/PLAN", {
           homeDir: options.homeDir,
           bundledDir: options.bundledTemplatesDir
         });
+        const title = input.title?.trim() || titleFromSlug(input.shortSlug);
         const source = renderTemplate(template.content, {
           id,
           branch: input.branch,
-          title: input.title?.trim() || titleFromSlug(input.shortSlug),
+          title,
           intent: input.intent?.trim() || "<!-- Describe the intended outcome. -->",
-          issue_id: input.issueId?.trim() || "<!-- Add issue tracker ID. -->",
-          issue_url: input.issueUrl?.trim() || "<!-- Add issue tracker URL. -->",
+          issue_id: input.issueId?.trim() || "",
+          issue_url: input.issueUrl?.trim() || "",
           created_at: timestamp,
           updated_at: timestamp
         });
-        const document = parsePlanDocument(source, join13(dir, "PLAN.md"));
-        await atomicWrite(join13(dir, "PLAN.md"), source);
-        return {
-          id,
-          dir,
-          planPath: join13(dir, "PLAN.md"),
-          logPath: join13(dir, "logs.txt"),
-          implementationDir: join13(dir, "implementation"),
-          document,
-          source
-        };
+        const document = parsePlanDocument(source, join14(dir, "PLAN.md"));
+        const authoringRequest = input.request ?? { kind: "user", text: input.intent?.trim() || `Initialize phase-less plan ${title}.` };
+        await writeRevisionSnapshot(dir, document, source, authoringRequest, []);
+        await writeLatestView(dir, document, source, []);
+        return await readRecord(dir);
       } catch (error) {
         await rm2(dir, { recursive: true, force: true });
         throw error;
       }
     },
-    async read(cwd, query, filters) {
-      const result = await resolvePlan(cwd, query, filters, options);
-      if (!result.record) {
-        if (result.ambiguous)
-          throw new Error(`Plan query "${query}" is ambiguous: ${result.candidates.map((item) => item.id).join(", ")}.`);
-        throw new Error(`Plan "${query}" was not found.`);
+    read,
+    async applyRevision(cwd, request) {
+      if (request.mode === "create") {
+        const root = await plansDir(cwd, options.homeDir);
+        const id = planRecordName(request.shortSlug, now());
+        const dir = join14(root, id);
+        await createPlanDirectory(root, dir, id);
+        try {
+          const timestamp = now().toISOString();
+          const document = normalizeRevision(undefined, request, id, 0, timestamp);
+          assertCompleteRevision(document, request.briefs);
+          const source = renderPlanDocument(document);
+          parsePlanDocument(source, join14(dir, "PLAN.md"));
+          await writeRevisionSnapshot(dir, document, source, request.request, request.briefs);
+          await writeLatestView(dir, document, source, request.briefs);
+          return await readRecord(dir);
+        } catch (error) {
+          await rm2(dir, { recursive: true, force: true });
+          throw error;
+        }
       }
-      return result.record;
+      const initial = await read(cwd, request.plan);
+      return withDirectoryLock(join14(initial.dir, ".lock"), async () => {
+        const current = await readRecord(initial.dir);
+        if (current.document.revision !== request.expectedPlanRevision)
+          throw new Error(`Expected plan revision ${request.expectedPlanRevision}, found ${current.document.revision}.`);
+        const revision = current.document.revision + 1;
+        const document = normalizeRevision(current.document, request, current.id, revision, now().toISOString());
+        assertCompleteRevision(document, request.briefs);
+        const source = renderPlanDocument(document);
+        parsePlanDocument(source, current.planPath);
+        await writeRevisionSnapshot(current.dir, document, source, request.request, request.briefs);
+        try {
+          await writeLatestView(current.dir, document, source, request.briefs);
+        } catch (error) {
+          await rm2(join14(current.dir, "revisions", String(revision)), { recursive: true, force: true });
+          throw error;
+        }
+        return await readRecord(current.dir);
+      }, { operation: "apply revision" });
     },
     async mutate(cwd, query, operation, update) {
-      const initial = await this.read(cwd, query);
-      return withDirectoryLock(join13(initial.dir, ".lock"), async () => {
+      const initial = await read(cwd, query);
+      return withDirectoryLock(join14(initial.dir, ".lock"), async () => {
         const current = await readRecord(initial.dir);
         const next = await update(structuredClone(current.document));
         if (next.id !== current.id)
           throw new Error("A plan mutation cannot change the plan ID.");
         const document = {
           ...next,
-          revision: current.document.revision + 1,
+          revision: current.document.revision,
           updatedAt: now().toISOString()
         };
         const source = renderPlanDocument(document, current.source);
         parsePlanDocument(source, current.planPath);
         await atomicWrite(current.planPath, source);
-        await ensureImplementationFiles(current.dir, document, options);
-        return { ...current, document, source, implementationDir: join13(current.dir, "implementation") };
+        return { ...current, document, source };
       }, { operation });
     },
     async log(cwd, query, event) {
-      const record = await this.read(cwd, query);
+      const record = await read(cwd, query);
       return appendLogEntry(record.logPath, event);
     }
   };
 }
 async function readRecord(dir) {
-  const planPath = join13(dir, "PLAN.md");
-  const logPath = join13(dir, "logs.txt");
-  const source = await readFile7(planPath, "utf8");
+  const planPath = join14(dir, "PLAN.md");
+  const logPath = join14(dir, "logs.txt");
+  const source = await readFile8(planPath, "utf8");
   const document = parsePlanDocument(source, planPath);
   return {
     id: basename5(dir),
     dir,
     planPath,
     logPath,
-    implementationDir: join13(dir, "implementation"),
+    implementationDir: join14(dir, "implementation"),
     document,
     source
   };
 }
-async function ensureImplementationFiles(dir, document, options) {
-  const implementationDir = join13(dir, "implementation");
-  await mkdir6(implementationDir, { recursive: true });
-  const template = await loadTemplate("plan/implementation", {
-    homeDir: options.homeDir,
-    bundledDir: options.bundledTemplatesDir
-  });
-  for (const phase of document.phases) {
-    const path = join13(implementationDir, `phase-${phase.id}.md`);
+async function createPlanDirectory(root, dir, id) {
+  await assertContained(root, dirname7(dir));
+  try {
+    await mkdir6(dir);
+  } catch (error) {
+    if (error.code === "EEXIST")
+      throw new Error(`Plan ${id} already exists.`);
+    throw error;
+  }
+}
+async function writeRevisionSnapshot(planDir, document, source, request, briefs) {
+  if (!request.text.trim())
+    throw new Error("An exact non-empty authoring request is required.");
+  if (request.kind === "annotation" && !request.response?.trim())
+    throw new Error("Annotation requests require a non-empty response.");
+  const revisionsDir = join14(planDir, "revisions");
+  await mkdir6(revisionsDir, { recursive: true });
+  const target = join14(revisionsDir, String(document.revision));
+  try {
+    await readFile8(join14(target, "metadata.json"), "utf8");
+    throw new Error(`Revision ${document.revision} already exists and is immutable.`);
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+  const staging = join14(revisionsDir, `.tmp-${document.revision}-${randomUUID2()}`);
+  await mkdir6(staging);
+  try {
+    const requestSource = request.kind === "annotation" ? `## Original annotation
+${request.text}
+
+## LLM response
+${request.response}` : request.text;
+    await atomicWrite(join14(staging, "request.md"), requestSource);
+    await atomicWrite(join14(staging, "metadata.json"), `${JSON.stringify({
+      schemaVersion: 1,
+      id: document.id,
+      revision: document.revision,
+      requestKind: request.kind,
+      requestSha256: sha2562(request.text),
+      ...request.kind === "annotation" ? { originalAnnotationSha256: sha2562(request.text), responseSha256: sha2562(request.response) } : {},
+      createdAt: document.updatedAt
+    }, null, 2)}
+`);
+    await atomicWrite(join14(staging, "PLAN.md"), source);
+    await writeImplementationDirectory(staging, document, briefs);
+    await rename2(staging, target);
+  } catch (error) {
+    await rm2(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+async function writeLatestView(planDir, document, source, briefs) {
+  const current = join14(planDir, "implementation");
+  const stagingRoot = join14(planDir, `.latest-${randomUUID2()}`);
+  const stagedImplementation = join14(stagingRoot, "implementation");
+  const backup = join14(planDir, `.implementation-backup-${randomUUID2()}`);
+  await mkdir6(stagingRoot);
+  await writeImplementationDirectory(stagingRoot, document, briefs);
+  let backedUp = false;
+  try {
     try {
-      await readFile7(path, "utf8");
+      await rename2(current, backup);
+      backedUp = true;
     } catch (error) {
       if (error.code !== "ENOENT")
         throw error;
-      const tasks = phase.tasks.map((task) => `- ${task.id}: ${task.title}`).join("\\n") || "- Add implementation tasks.";
-      await atomicWrite(path, renderTemplate(template.content, {
-        phase_id: phase.id,
-        phase_title: phase.title,
-        phase_objective: phase.objective,
-        phase_tasks: tasks
-      }));
     }
+    await rename2(stagedImplementation, current);
+    await atomicWrite(join14(planDir, "PLAN.md"), source);
+    if (backedUp)
+      await rm2(backup, { recursive: true, force: true });
+  } catch (error) {
+    await rm2(current, { recursive: true, force: true });
+    if (backedUp)
+      await rename2(backup, current);
+    throw error;
+  } finally {
+    await rm2(stagingRoot, { recursive: true, force: true });
   }
 }
+async function writeImplementationDirectory(baseDir, document, briefs) {
+  const implementationDir = join14(baseDir, "implementation");
+  await mkdir6(implementationDir, { recursive: true });
+  for (const [index, phase] of document.phases.entries()) {
+    const brief = briefs[index];
+    if (!brief)
+      throw new Error(`Missing implementation brief for phase ${phase.id}.`);
+    await atomicWrite(join14(implementationDir, `phase-${index + 1}.md`), renderImplementationBrief(document.revision, index + 1, phase, brief));
+  }
+}
+function normalizeRevision(current, request, id, revision, updatedAt) {
+  if (current?.status === "completed")
+    throw new Error("Completed plans cannot be amended.");
+  if (current?.execution?.active && request.request.kind !== "blocker")
+    throw new Error("An active execution accepts only a blocker amendment.");
+  const currentPhases = new Map(current?.phases.map((phase) => [phase.id, phase]) ?? []);
+  for (const phase of current?.phases ?? []) {
+    if (!request.phases.some((candidate) => candidate.id === phase.id) && (phase.status === "completed" || phase.status === "in_progress"))
+      throw new Error(`${phase.status === "completed" ? "Completed" : "Active"} phase ${phase.id} cannot be removed.`);
+  }
+  const phases = request.phases.map((draft) => reconcilePhase(currentPhases.get(draft.id), draft, current));
+  const createdAt = current?.createdAt ?? updatedAt;
+  return {
+    schemaVersion: 1,
+    id,
+    revision,
+    title: request.title,
+    branch: current?.branch ?? (request.mode === "create" ? request.branch : ""),
+    issueId: current?.issueId ?? (request.mode === "create" ? request.issueId : undefined),
+    issueUrl: current?.issueUrl ?? (request.mode === "create" ? request.issueUrl : undefined),
+    intent: request.intent,
+    requirements: request.requirements,
+    design: request.design,
+    references: request.references,
+    phases,
+    status: nextPlanStatus(current),
+    execution: current?.execution,
+    createdAt,
+    updatedAt
+  };
+}
+function reconcilePhase(current, draft, plan) {
+  if (!current)
+    return {
+      ...draft,
+      revision: 0,
+      status: "pending",
+      gate: { phaseRevision: 0, status: "pending", results: [] },
+      tasks: draft.tasks.map(newTask)
+    };
+  if (current.status === "completed") {
+    if (JSON.stringify(phaseContent(current)) !== JSON.stringify(draft))
+      throw new Error(`Completed phase ${current.id} cannot be changed.`);
+    return current;
+  }
+  const byId = new Map(current.tasks.map((task) => [task.id, task]));
+  for (const task of current.tasks) {
+    if (!draft.tasks.some((candidate) => candidate.id === task.id) && (task.status === "completed" || task.status === "in_progress"))
+      throw new Error(`${task.status === "completed" ? "Completed" : "Active"} task ${task.id} cannot be removed.`);
+  }
+  const tasks = draft.tasks.map((task) => reconcileTask(byId.get(task.id), task));
+  const changed = JSON.stringify(phaseContent(current)) !== JSON.stringify(draft);
+  const revision = changed ? current.revision + 1 : current.revision;
+  const wasBlocked = current.status === "blocked";
+  return {
+    ...current,
+    ...draft,
+    revision,
+    tasks,
+    status: wasBlocked ? plan?.execution?.active ? "in_progress" : "pending" : current.status,
+    gate: changed || wasBlocked ? { phaseRevision: revision, status: "stale", results: [] } : current.gate,
+    blocker: wasBlocked ? undefined : current.blocker
+  };
+}
+function reconcileTask(current, draft) {
+  if (!current)
+    return newTask(draft);
+  const changed = JSON.stringify(taskContent(current)) !== JSON.stringify(draft);
+  if ((current.status === "completed" || current.status === "in_progress") && changed)
+    throw new Error(`${current.status === "completed" ? "Completed" : "Active"} task ${current.id} cannot be changed.`);
+  if (current.status === "completed" || current.status === "in_progress")
+    return current;
+  return {
+    ...current,
+    ...draft,
+    revision: changed ? current.revision + 1 : current.revision,
+    status: current.status === "blocked" ? "pending" : current.status,
+    owner: current.status === "blocked" ? undefined : current.owner,
+    executionId: current.status === "blocked" ? undefined : current.executionId,
+    blocker: current.status === "blocked" ? undefined : current.blocker
+  };
+}
+function newTask(draft) {
+  return { ...draft, revision: 0, status: "pending" };
+}
+function phaseContent(phase) {
+  return {
+    id: phase.id,
+    title: phase.title,
+    objective: phase.objective,
+    dependencies: phase.dependencies,
+    tasks: phase.tasks.map(taskContent)
+  };
+}
+function taskContent(task) {
+  return { id: task.id, title: task.title, dependencies: task.dependencies };
+}
+function nextPlanStatus(current) {
+  if (!current)
+    return "draft";
+  if (current.execution?.active)
+    return current.status === "blocked" ? "in_progress" : current.status;
+  return current.status === "ready" || current.status === "blocked" ? "draft" : current.status;
+}
+function assertCompleteRevision(document, briefs) {
+  const errors = [...validatePlanDocument(document, { strict: true }), ...validatePlanBriefs(document, briefs)].filter((issue) => issue.severity === "error");
+  if (errors.length)
+    throw new Error(`Invalid plan revision: ${errors.map((issue) => issue.message).join(" ")}`);
+}
+function sha2562(value) {
+  return createHash3("sha256").update(value).digest("hex");
+}
 async function assertContained(root, candidate) {
   const canonicalRoot = await realpath3(root);
   let canonicalCandidate;
@@ -7194,34 +7700,54 @@ function stripDate(value) {
   return value.replace(/^\d{6}-/, "");
 }
 function titleFromSlug(value) {
-  return normalizeSlug(value).replace(/^(?:[a-z]+-\d+-)/, "").split("-").map((part) => part[0].toUpperCase() + part.slice(1)).join(" ");
+  const slug = normalizeSlug(value).replace(/^(?:[a-z]+-\d+-)/, "");
+  return slug.replace(/(^|-)([a-z])/g, (_match, separator, letter) => {
+    return `${separator ? " " : ""}${letter.toUpperCase()}`;
+  });
 }
 
-// src/tools/plan-schema.ts
+// src/plan/schema.ts
 import { z as z6 } from "zod";
 var planStatusSchema = z6.enum(["draft", "ready", "in_progress", "blocked", "completed"]);
 var planUnitStatusSchema = z6.enum(["draft", "ready", "in_progress", "blocked", "completed", "pending", "skipped"]);
-var planTaskDraftSchema = z6.object({
-  id: zx.id,
-  title: zx.text,
-  steps: z6.array(zx.text).optional(),
-  dependencies: z6.array(zx.id).optional(),
-  fileScopes: z6.array(zx.text).optional(),
-  acceptanceCriteria: z6.array(zx.text).optional()
-}).strict();
+var planTaskDraftSchema = z6.object({ id: zx.id, title: zx.text, dependencies: z6.array(zx.id) }).strict();
 var planPhaseDraftSchema = z6.object({
   id: zx.id,
   title: zx.text,
   objective: zx.text,
-  dependencies: z6.array(zx.id).optional(),
-  tasks: z6.array(planTaskDraftSchema).optional()
+  dependencies: z6.array(zx.id),
+  tasks: z6.array(planTaskDraftSchema).min(1)
 }).strict();
-var planReferenceSchema = z6.object({ id: zx.id, value: zx.text }).strict();
-var planDesignSchema = z6.object({
-  bigIdeas: z6.string(),
-  keyApiUpdates: z6.string(),
-  consequences: z6.string()
+var planBriefSchema = z6.object({
+  phaseId: zx.id,
+  summary: zx.text,
+  apiChanges: z6.array(zx.text),
+  libraries: z6.array(zx.text),
+  constraints: z6.array(zx.text),
+  tasks: z6.array(z6.object({
+    taskId: zx.id,
+    steps: z6.array(zx.text).min(1),
+    fileScopes: z6.array(zx.text).min(1),
+    acceptanceCriteria: z6.array(zx.text).min(1)
+  }).strict()).min(1)
 }).strict();
+var planReferenceSchema = z6.object({ id: zx.id, value: zx.text }).strict();
+var planDesignSchema = z6.object({ bigIdeas: zx.text, keyApiUpdates: zx.text, consequences: zx.text }).strict();
+var planRequestSchema = z6.discriminatedUnion("kind", [
+  z6.object({ kind: z6.literal("annotation"), text: zx.text, response: zx.text }).strict(),
+  z6.object({ kind: z6.literal("user"), text: zx.text, response: zx.text.optional() }).strict(),
+  z6.object({ kind: z6.literal("blocker"), text: zx.text, response: zx.text.optional() }).strict()
+]);
+var revisionContentFields = {
+  request: planRequestSchema,
+  title: zx.text,
+  intent: zx.text,
+  requirements: z6.array(zx.text).min(1),
+  design: planDesignSchema,
+  references: z6.array(planReferenceSchema),
+  phases: z6.array(planPhaseDraftSchema).min(1),
+  briefs: z6.array(planBriefSchema).min(1)
+};
 var planContextParametersSchema = z6.object({
   cwd: zx.cwd,
   plan: z6.string().optional(),
@@ -7235,46 +7761,28 @@ var planInitParametersSchema = z6.object({
   title: zx.text.optional(),
   intent: zx.text.optional(),
   issueId: zx.text.optional(),
-  issueUrl: z6.string().url().optional(),
+  issueUrl: z6.url().optional(),
+  request: planRequestSchema.optional(),
   open: z6.boolean().optional()
 }).strict();
-var planUpdateOverviewParametersSchema = z6.object({
-  cwd: zx.cwd,
-  plan: zx.text,
-  expectedPlanRevision: zx.revision,
-  intent: zx.text.optional(),
-  requirements: z6.array(zx.text).optional(),
-  design: planDesignSchema.optional(),
-  references: z6.array(planReferenceSchema).optional()
-}).strict().refine((value) => value.intent || value.requirements || value.design || value.references, {
-  message: "At least one overview field is required."
-});
-var planAddPhaseParametersSchema = z6.object({
-  cwd: zx.cwd,
-  plan: zx.text,
-  expectedPlanRevision: zx.revision,
-  afterPhaseId: zx.id.optional(),
-  phase: planPhaseDraftSchema
-}).strict();
-var planRemovePhaseParametersSchema = z6.object({
-  cwd: zx.cwd,
-  plan: zx.text,
-  expectedPlanRevision: zx.revision,
-  phaseId: zx.id,
-  reason: zx.text
-}).strict();
-var planUpdatePhaseParametersSchema = z6.object({
-  cwd: zx.cwd,
-  plan: zx.text,
-  expectedPlanRevision: zx.revision,
-  phaseId: zx.id,
-  patch: z6.object({
-    title: zx.text.optional(),
-    objective: zx.text.optional(),
-    dependencies: z6.array(zx.id).optional(),
-    tasks: z6.array(planTaskDraftSchema).optional()
+var planApplyRevisionParametersSchema = z6.discriminatedUnion("mode", [
+  z6.object({
+    mode: z6.literal("create"),
+    cwd: zx.cwd,
+    shortSlug: zx.id,
+    branch: z6.string().min(1).optional(),
+    issueId: zx.text.optional(),
+    issueUrl: z6.url().optional(),
+    ...revisionContentFields
+  }).strict(),
+  z6.object({
+    mode: z6.literal("amend"),
+    cwd: zx.cwd,
+    plan: zx.text,
+    expectedPlanRevision: zx.revision,
+    ...revisionContentFields
   }).strict()
-}).strict();
+]);
 var planValidateParametersSchema = z6.object({ cwd: zx.cwd, plan: zx.text, strict: z6.boolean().optional() }).strict();
 var planLogProgressParametersSchema = z6.object({
   cwd: zx.cwd,
@@ -7374,116 +7882,17 @@ function createPlanTools(_pi, _modes, store = createPlanStore()) {
       }
     }),
     defineTool5({
-      name: "plan_update_overview",
-      label: "plan update overview",
-      description: "Replace selected plan overview fields using an expected plan revision.",
-      parameters: parameters(planUpdateOverviewParametersSchema),
-      executionMode: "sequential",
-      async execute(_id, input) {
-        const params = planUpdateOverviewParametersSchema.parse(input);
-        const record = await store.mutate(params.cwd ?? process.cwd(), params.plan, "update overview", (plan) => {
-          assertAuthoringRevision(plan, params.expectedPlanRevision);
-          assertAuthorable(plan);
-          return resetDraft({
-            ...plan,
-            intent: params.intent ?? plan.intent,
-            requirements: params.requirements ?? plan.requirements,
-            design: params.design ?? plan.design,
-            references: params.references ?? plan.references
-          });
-        });
-        return result2(`Updated ${record.id} to revision ${record.document.revision}.`, { record });
-      }
-    }),
-    defineTool5({
-      name: "plan_add_phase",
-      label: "plan add phase",
-      description: "Add an ordered phase with stable IDs.",
-      parameters: parameters(planAddPhaseParametersSchema),
-      executionMode: "sequential",
-      async execute(_id, input) {
-        const params = planAddPhaseParametersSchema.parse(input);
-        const record = await store.mutate(params.cwd ?? process.cwd(), params.plan, "add phase", (plan) => {
-          assertAuthoringRevision(plan, params.expectedPlanRevision);
-          assertAuthorable(plan);
-          if (allIds(plan).has(params.phase.id))
-            throw new Error(`Duplicate stable ID: ${params.phase.id}.`);
-          const phase = newPhase(params.phase);
-          const phases = [...plan.phases];
-          if (params.afterPhaseId) {
-            const index = phases.findIndex((item) => item.id === params.afterPhaseId);
-            if (index < 0)
-              throw new Error(`Unknown phase: ${params.afterPhaseId}.`);
-            phases.splice(index + 1, 0, phase);
-          } else
-            phases.push(phase);
-          assertNewIds(plan, phase);
-          return resetDraft({ ...plan, phases });
-        });
-        return result2(`Added phase ${params.phase.id} to ${record.id}.`, { record });
-      }
-    }),
-    defineTool5({
-      name: "plan_remove_phase",
-      label: "plan remove phase",
-      description: "Remove an unfinished phase that has no dependents.",
-      parameters: parameters(planRemovePhaseParametersSchema),
+      name: "plan_apply_revision",
+      label: "plan apply revision",
+      description: "Create mode writes a complete revision 0 without plan_init; amend mode atomically writes the next complete authoring revision.",
+      parameters: parameters(planApplyRevisionParametersSchema),
       executionMode: "sequential",
       async execute(_id, input) {
-        const params = planRemovePhaseParametersSchema.parse(input);
-        const record = await store.mutate(params.cwd ?? process.cwd(), params.plan, "remove phase", (plan) => {
-          assertAuthoringRevision(plan, params.expectedPlanRevision);
-          assertAuthorable(plan);
-          const phase = getPhase2(plan, params.phaseId);
-          if (phase.status === "completed" || phase.tasks.some((task) => task.status === "completed"))
-            throw new Error(`Completed phase ${phase.id} cannot be removed.`);
-          if (plan.phases.some((item) => item.dependencies.includes(phase.id)))
-            throw new Error(`Phase ${phase.id} has dependents and cannot be removed.`);
-          return resetDraft({ ...plan, phases: plan.phases.filter((item) => item.id !== phase.id) });
-        });
-        await store.log(params.cwd ?? process.cwd(), record.id, {
-          planRevision: record.document.revision,
-          kind: "updated",
-          actor: "planner",
-          message: `Removed phase ${params.phaseId}: ${params.reason}`,
-          phaseId: params.phaseId
-        });
-        return result2(`Removed phase ${params.phaseId}.`, { record });
-      }
-    }),
-    defineTool5({
-      name: "plan_update_phase",
-      label: "plan update phase",
-      description: "Update an unfinished phase and its ordered tasks.",
-      parameters: parameters(planUpdatePhaseParametersSchema),
-      executionMode: "sequential",
-      async execute(_id, input) {
-        const params = planUpdatePhaseParametersSchema.parse(input);
-        const record = await store.mutate(params.cwd ?? process.cwd(), params.plan, "update phase", (plan) => {
-          assertAuthoringRevision(plan, params.expectedPlanRevision);
-          assertAuthorable(plan, params.phaseId);
-          const existing = getPhase2(plan, params.phaseId);
-          if (existing.status === "completed")
-            throw new Error(`Completed phase ${existing.id} cannot be changed.`);
-          const tasks = params.patch.tasks ? reconcileTasks(existing.tasks, params.patch.tasks) : existing.tasks;
-          const updated = {
-            ...existing,
-            title: params.patch.title ?? existing.title,
-            objective: params.patch.objective ?? existing.objective,
-            dependencies: params.patch.dependencies ?? existing.dependencies,
-            tasks,
-            revision: existing.revision + 1,
-            status: existing.status === "blocked" ? "in_progress" : existing.status,
-            gate: { ...existing.gate, status: "stale" },
-            blocker: existing.status === "blocked" ? undefined : existing.blocker
-          };
-          assertNewIds({ ...plan, phases: plan.phases.filter((phase) => phase.id !== existing.id) }, updated);
-          return resetDraft({
-            ...plan,
-            phases: plan.phases.map((phase) => phase.id === existing.id ? updated : phase)
-          });
-        });
-        return result2(`Updated phase ${params.phaseId}.`, { record });
+        const params = planApplyRevisionParametersSchema.parse(input);
+        const workingDirectory = params.cwd ?? process.cwd();
+        const request = params.mode === "create" ? { ...params, branch: params.branch ?? await currentBranch(workingDirectory) } : params;
+        const record = await store.applyRevision(workingDirectory, request);
+        return result2(`Applied revision ${record.document.revision} to ${record.id}.`, { record });
       }
     }),
     defineTool5({
@@ -7495,7 +7904,7 @@ function createPlanTools(_pi, _modes, store = createPlanStore()) {
       async execute(_id, input) {
         const params = planValidateParametersSchema.parse(input);
         const record = await store.read(params.cwd ?? process.cwd(), params.plan);
-        const issues = validatePlanDocument(record.document, { strict: params.strict });
+        const issues = await validatePlanRecord(record, { strict: params.strict });
         const words = countDesignWords(record.document);
         return result2(issues.length ? issues.map((issue) => `- ${issue.severity}: ${issue.message}`).join(`
 `) : "Plan is valid.", { record, issues, designWordCount: words, ready: !issues.some((issue) => issue.severity === "error") });
@@ -7631,7 +8040,7 @@ function createPlanTools(_pi, _modes, store = createPlanStore()) {
         const resolution = await store.context(workingDirectory, params.plan);
         if (!resolution.record)
           throw new Error(resolution.ambiguous ? `Plan is ambiguous: ${resolution.candidates.map((item) => item.id).join(", ")}.` : "No matching plan.");
-        const cliPath = join14(resolveBundledAgentsDir(), "..", "dist", "cli.js");
+        const cliPath = join15(resolveBundledAgentsDir(), "..", "dist", "cli.js");
         const command = [
           process.execPath,
           cliPath,
@@ -7726,8 +8135,8 @@ function renderExecutionPrompt(packet) {
   return [
     `Execute the durable Diffpi plan using this packet: ${JSON.stringify(packet)}.`,
     "Call plan_context first and keep plan tools as the source of truth for eligibility, ownership, status, gates, and commits.",
-    "Use SubagentWorkflow for deterministic multi-task coordination: pipeline dependent work, parallelize only tasks with non-overlapping declared file scopes, and use structured schemas for worker outcomes.",
-    "The extension cannot launch workflow children over RPC, so the active orchestrator must invoke SubagentWorkflow itself.",
+    "Use bounded Agent delegation for eligible tasks. Run dependent tasks in order; parallelize only tasks with non-overlapping declared file scopes. Collect and verify worker results before changing plan state.",
+    "Use a multi-agent SubagentWorkflow only when the user explicitly opts into that orchestration.",
     "Persist every transition, progress event, issue, and deviation. Do not edit PLAN.md directly. Delegated implementation workers never commit or restructure the plan.",
     "In commit mode, create one local commit after each phase passes its gates and do not push. In push mode, commit and push each phase, record pending CI, and launch a bounded background Worker to call watch_ci for the exact SHA and then plan_record_ci for the phase while the next phase executes. Collect that monitor before the next push and collect all monitors before plan completion; failed or timed-out CI blocks execution."
   ].join(" ");
@@ -7791,81 +8200,6 @@ ${dirty.stdout.trim()}`);
     prompt: renderExecutionPrompt(packet)
   });
 }
-function newPhase(input) {
-  return {
-    id: input.id,
-    revision: 0,
-    title: input.title,
-    objective: input.objective,
-    dependencies: input.dependencies ?? [],
-    tasks: (input.tasks ?? []).map(newTask),
-    status: "pending",
-    gate: { phaseRevision: 0, status: "pending", results: [] }
-  };
-}
-function newTask(input) {
-  return {
-    id: input.id,
-    revision: 0,
-    title: input.title,
-    steps: input.steps,
-    dependencies: input.dependencies ?? [],
-    fileScopes: input.fileScopes ?? [],
-    acceptanceCriteria: input.acceptanceCriteria ?? [],
-    status: "pending"
-  };
-}
-function reconcileTasks(existing, drafts) {
-  const byId = new Map(existing.map((task) => [task.id, task]));
-  const requested = new Set(drafts.map((task) => task.id));
-  const protectedTask = existing.find((task) => (task.status === "completed" || task.status === "in_progress") && !requested.has(task.id));
-  if (protectedTask)
-    throw new Error(`${protectedTask.status === "completed" ? "Completed" : "Active"} task ${protectedTask.id} cannot be removed.`);
-  return drafts.map((draft) => {
-    const current = byId.get(draft.id);
-    if (current?.status === "completed" || current?.status === "in_progress")
-      return current;
-    return current ? {
-      ...newTask(draft),
-      revision: current.revision + 1,
-      status: current.status === "blocked" ? "pending" : current.status,
-      owner: current.status === "blocked" ? undefined : current.owner,
-      executionId: current.status === "blocked" ? undefined : current.executionId,
-      blocker: current.status === "blocked" ? undefined : current.blocker
-    } : newTask(draft);
-  });
-}
-function assertAuthoringRevision(plan, expected) {
-  if (plan.revision !== expected)
-    throw new Error(`Stale plan revision: expected ${expected}, found ${plan.revision}.`);
-}
-function assertAuthorable(plan, blockedPhaseId) {
-  if (plan.status === "completed")
-    throw new Error("Completed plans cannot be structurally changed.");
-  if (!plan.execution?.active)
-    return;
-  if (!blockedPhaseId)
-    throw new Error("An active execution owns this plan.");
-  const phase = getPhase2(plan, blockedPhaseId);
-  if (phase.status !== "blocked" && !phase.tasks.some((task) => task.status === "blocked"))
-    throw new Error("Planner may amend only blocked work during an active execution.");
-}
-function resetDraft(plan) {
-  if (plan.status === "blocked" && plan.execution?.active)
-    return { ...plan, status: "in_progress" };
-  return plan.status === "ready" || plan.status === "blocked" ? { ...plan, status: "draft" } : plan;
-}
-function allIds(plan) {
-  return new Set([plan.id, ...plan.phases.flatMap((phase) => [phase.id, ...phase.tasks.map((task) => task.id)])]);
-}
-function assertNewIds(plan, phase) {
-  const known = allIds(plan);
-  for (const candidate of [phase.id, ...phase.tasks.map((task) => task.id)]) {
-    if (known.has(candidate))
-      throw new Error(`Duplicate stable ID: ${candidate}.`);
-    known.add(candidate);
-  }
-}
 function getPhase2(plan, phaseId) {
   const phase = plan.phases.find((item) => item.id === phaseId);
   if (!phase)
@@ -7903,8 +8237,8 @@ function result2(text, details = {}) {
 
 // src/tools/review.ts
 import { existsSync as existsSync2 } from "node:fs";
-import { mkdir as mkdir7, readdir as readdir2, readFile as readFile11, rename as rename3, stat, unlink as unlink2, writeFile as writeFile7 } from "node:fs/promises";
-import { join as join16 } from "node:path";
+import { mkdir as mkdir7, readdir as readdir3, readFile as readFile12, rename as rename4, stat, unlink as unlink2, writeFile as writeFile7 } from "node:fs/promises";
+import { join as join17 } from "node:path";
 import { defineTool as defineTool6 } from "@earendil-works/pi-coding-agent";
 import { z as z11 } from "zod";
 
@@ -8075,7 +8409,7 @@ function renderThreadArtifact(title, target, threads, options = {}) {
   }
   lines.push("## Source comments", "");
   for (const thread of threads) {
-    lines.push(`### ${thread.file ?? "review"}:${thread.line ?? "n/a"} — ${thread.author ?? "unknown"}`, "", `Thread: ${thread.id}`, `Status: ${thread.resolved ? "resolved" : thread.addressed ? "addressed" : "open"}`, "", thread.body, "", "---", "");
+    lines.push(`### ${thread.file ?? "review"}:${thread.line ?? "n/a"} — ${thread.author ?? "unknown"}`, "", `Thread: ${thread.id}`, `Status: ${thread.resolved ? "resolved" : thread.addressed ? "addressed" : "open"}`, "", "**Source comment**", "", thread.body, "", "**Recorded response**", "", thread.reply?.trim() || "_No response recorded._", "", "---", "");
   }
   return `${lines.join(`
 `).trimEnd()}
@@ -8506,10 +8840,10 @@ function hasGitlabDraftNotes(input) {
 }
 
 // src/review/local-review-backend.ts
-import { readFile as readFile9, writeFile as writeFile5 } from "node:fs/promises";
+import { readFile as readFile10, writeFile as writeFile5 } from "node:fs/promises";
 
 // src/extensions/tuicrx.ts
-import { readFile as readFile8, realpath as realpath4 } from "node:fs/promises";
+import { readFile as readFile9, realpath as realpath4 } from "node:fs/promises";
 import { resolve as resolve4 } from "node:path";
 async function tuicrAvailable() {
   return Boolean(await findExecutable("tuicr"));
@@ -8606,7 +8940,7 @@ async function findMatchingSession(sessions, cwd, branch) {
   return;
 }
 async function readSession(path) {
-  const content = await readFile8(path, "utf8");
+  const content = await readFile9(path, "utf8");
   try {
     return JSON.parse(content);
   } catch {
@@ -8727,7 +9061,7 @@ function LocalReviewBackend(options) {
     },
     async listThreads() {
       try {
-        return parseThreadArtifact(await readFile9(options.artifactPath, "utf8"));
+        return parseThreadArtifact(await readFile10(options.artifactPath, "utf8"));
       } catch (error) {
         if (error.code === "ENOENT")
           return [];
@@ -8735,7 +9069,7 @@ function LocalReviewBackend(options) {
       }
     },
     async reply(input) {
-      const content = await readFile9(options.artifactPath, "utf8");
+      const content = await readFile10(options.artifactPath, "utf8");
       await writeFile5(options.artifactPath, upsertThreadReply(content, input.threadId, input.body, input.question, input.resolve), "utf8");
     },
     async publish() {
@@ -8756,9 +9090,9 @@ function createLocalReviewBackend(options) {
   return LocalReviewBackend(options);
 }
 // src/review/review-state.ts
-import { createHash as createHash2 } from "node:crypto";
-import { readFile as readFile10, rename as rename2, writeFile as writeFile6 } from "node:fs/promises";
-import { join as join15 } from "node:path";
+import { createHash as createHash4 } from "node:crypto";
+import { readFile as readFile11, rename as rename3, writeFile as writeFile6 } from "node:fs/promises";
+import { join as join16 } from "node:path";
 import { z as z10 } from "zod";
 var reviewPublicationStateSchema = z10.object({
   target: z10.string().optional(),
@@ -8782,9 +9116,9 @@ function unpublishedReviewComments(comments, knownFingerprints) {
 }
 async function loadReviewPublicationState(cwd, vcs, number, homeDir) {
   const target = `${vcs.provider}:${vcs.owner}/${vcs.repo}#${number}`;
-  const path = join15(await sessionsDir(cwd, homeDir), `review-publish-${digest(target).slice(0, 16)}.json`);
+  const path = join16(await sessionsDir(cwd, homeDir), `review-publish-${digest(target).slice(0, 16)}.json`);
   try {
-    const parsed = reviewPublicationStateSchema.parse(JSON.parse(await readFile10(path, "utf8")));
+    const parsed = reviewPublicationStateSchema.parse(JSON.parse(await readFile11(path, "utf8")));
     return { path, state: { ...parsed, target } };
   } catch (error) {
     if (error.code === "ENOENT") {
@@ -8800,10 +9134,10 @@ async function saveReviewPublicationState(path, state) {
   const temp = `${path}.${process.pid}.tmp`;
   await writeFile6(temp, `${JSON.stringify(state, null, 2)}
 `, "utf8");
-  await rename2(temp, path);
+  await rename3(temp, path);
 }
 function digest(value) {
-  return createHash2("sha256").update(value).digest("hex");
+  return createHash4("sha256").update(value).digest("hex");
 }
 // src/tools/review.ts
 var contextSchema = z11.object({
@@ -8845,6 +9179,17 @@ var completeSchema = localSchema.extend({
 function hasReviewDraft(comments, body) {
   return comments.length > 0 || body.trim().length > 0;
 }
+function reviewBrowserCommand(url, platform = process.platform) {
+  return platform === "darwin" ? { command: "open", args: [url] } : platform === "win32" ? { command: "cmd", args: ["/c", "start", "", url] } : { command: "xdg-open", args: [url] };
+}
+async function openReviewUrl(url, execute = run, platform = process.platform) {
+  const launch = reviewBrowserCommand(url, platform);
+  try {
+    return (await execute(launch.command, launch.args)).code === 0;
+  } catch {
+    return false;
+  }
+}
 function partitionReviewComments(comments, knownFingerprints, model) {
   const normalized = comments.map((comment) => {
     const published = { ...comment, body: withCommentProvenance(comment, model) };
@@ -8899,7 +9244,9 @@ function createReviewTools() {
         const review = await resolveReviewContext(resolveWorkingDirectory(params), params.target);
         const store = await ensureStore(review.cwd);
         const env = { ide: detectIde(), mux: detectMux(), shell: detectShell() };
-        const session = await resolveTuicrSession(review, Boolean(params.local || params.workingTree));
+        const session = await resolveTuicrSession(review, Boolean(params.local || params.workingTree)).catch(() => {
+          return;
+        });
         const baseRef = review.pr?.baseRef ?? (review.forge ? await review.forge.defaultBranch() : "local");
         const backend = params.local || params.workingTree ? "tuicr" : review.forge?.provider ?? "unsupported";
         return result3([
@@ -8923,6 +9270,21 @@ function createReviewTools() {
         });
       }
     }),
+    defineTool6({
+      name: "review_status",
+      label: "review status",
+      description: "Report local and remote review lifecycle status without requiring a forge or tuicr.",
+      promptSnippet: "Call review_status for review lifecycle state",
+      promptGuidelines: ["Use this for status even when no forge or tuicr binary is available."],
+      parameters: parameters2(localSchema),
+      executionMode: "parallel",
+      async execute(_id, input) {
+        const params = localSchema.parse(input);
+        const review = await resolveReviewContext(resolveWorkingDirectory(params), params.target);
+        const status = await collectReviewStatus(review);
+        return result3(status.text, status.details);
+      }
+    }),
     defineTool6({
       name: "review_new",
       label: "review new",
@@ -8966,6 +9328,31 @@ ${openMessage}`, {
         });
       }
     }),
+    defineTool6({
+      name: "review_open",
+      label: "review open",
+      description: "Open an existing remote PR/MR in the system browser; never creates one.",
+      promptSnippet: "Call review_open to open an existing PR/MR",
+      promptGuidelines: ["Direct users to review_new when no remote review exists."],
+      parameters: parameters2(localSchema),
+      executionMode: "sequential",
+      async execute(_id, input) {
+        const params = localSchema.parse(input);
+        const review = await resolveReviewContext(resolveWorkingDirectory(params), params.target);
+        if (params.local || params.workingTree)
+          return launchLocalReview(review, true);
+        if (!review.forge)
+          return result3(`${unsupportedForgeMessage()} Use review_new with local=true for an offline review.`);
+        if (!review.pr)
+          return result3("No remote PR/MR exists. Use review_new to create a draft review first.");
+        const opened = await openReviewUrl(review.pr.url);
+        return result3(`${opened ? "Opened" : "Open this URL"} PR/MR #${review.pr.number}: ${review.pr.url}`, {
+          pr: review.pr,
+          opened,
+          url: review.pr.url
+        });
+      }
+    }),
     defineTool6({
       name: "review_edit",
       label: "review edit",
@@ -9272,7 +9659,7 @@ ${params.body}`, {
           if (!existsSync2(artifact))
             return result3("No local review artifact. Run review_comments with local=true first.");
           const archived = await uniqueRecordPath(await completedReviewsDir(review.cwd), reviewSlug(session.slug));
-          await rename3(artifact, archived);
+          await rename4(artifact, archived);
           await unlink2(session.path);
           return result3(`Archived ${archived} and deleted the tuicr session ${session.slug}.`, {
             artifact: archived,
@@ -9332,7 +9719,7 @@ ${params.body}`, {
 async function syncLocalThreadArtifact(path, title, sessionSlug, threads) {
   let previous = [];
   try {
-    previous = parseThreadArtifact(await readFile11(path, "utf8"));
+    previous = parseThreadArtifact(await readFile12(path, "utf8"));
   } catch (error) {
     if (error.code !== "ENOENT")
       throw error;
@@ -9365,6 +9752,45 @@ function result3(text, details = {}) {
 function unsupportedForgeMessage() {
   return "No supported GitHub or GitLab remote was detected. Use local=true for an offline tuicr review.";
 }
+async function collectReviewStatus(review) {
+  const [porcelain, branch, localSession, remoteSession] = await Promise.all([
+    runChecked("git", ["-C", review.cwd, "status", "--porcelain"]),
+    runChecked("git", ["-C", review.cwd, "branch", "--show-current"]),
+    resolveTuicrSession(review, true).catch(() => {
+      return;
+    }),
+    resolveTuicrSession(review, false).catch(() => {
+      return;
+    })
+  ]);
+  const entries = porcelain.stdout.split("\\n").filter(Boolean);
+  const staged = entries.filter((line) => !line.startsWith("??") && line[0] !== " ").length;
+  const unstaged = entries.filter((line) => !line.startsWith("??") && line[1] !== " ").length;
+  const untracked = entries.filter((line) => line.startsWith("??")).length;
+  const remote = review.pr ? `yes (#${review.pr.number})` : "no";
+  const url = review.pr?.url ?? "none";
+  const text = [
+    `Branch: ${branch.stdout.trim() || review.vcs.branch}`,
+    `Worktree: ${entries.length ? "dirty" : "clean"} (staged=${staged}, unstaged=${unstaged}, untracked=${untracked})`,
+    `Local working-tree tuicr review: ${localSession ? `yes (${localSession.slug}, ${localSession.commentCount} comments)` : "no"}`,
+    `Remote PR/MR: ${remote}`,
+    `Remote URL: ${url}`,
+    `Remote tuicr session: ${remoteSession ? `yes (${remoteSession.slug}, ${remoteSession.commentCount} comments)` : "no"}`
+  ].join("\\n");
+  return {
+    text,
+    details: {
+      branch: branch.stdout.trim(),
+      staged,
+      unstaged,
+      untracked,
+      localSession,
+      remoteSession,
+      pr: review.pr,
+      url
+    }
+  };
+}
 function modelRoute(ctx) {
   if (!ctx.model)
     throw new Error("Cannot record review provenance because Pi did not provide an active model route.");
@@ -9588,11 +10014,11 @@ async function newReviewArtifactPath(cwd, target) {
 }
 async function localThreadArtifactPath(cwd, sessionSlug) {
   const dir = await reviewsDir(cwd);
-  return join16(dir, `${reviewSlug(sessionSlug) || "local-review"}.md`);
+  return join17(dir, `${reviewSlug(sessionSlug) || "local-review"}.md`);
 }
 async function readThreadArtifact(path) {
   try {
-    return parseThreadArtifact(await readFile11(path, "utf8"));
+    return parseThreadArtifact(await readFile12(path, "utf8"));
   } catch (error) {
     if (error.code === "ENOENT") {
       throw new Error(`Expected local reply overlay is missing: ${path}`);
@@ -9616,9 +10042,9 @@ async function findLatestThreadArtifact(cwd, review, target) {
       return [];
     return [
       (async () => {
-        const path = join16(dir, name);
+        const path = join17(dir, name);
         const info = await stat(path);
-        return { path, name, content: await readFile11(path, "utf8"), modified: info.mtimeMs };
+        return { path, name, content: await readFile12(path, "utf8"), modified: info.mtimeMs };
       })()
     ];
   }));
@@ -9632,7 +10058,7 @@ async function findLatestThreadArtifact(cwd, review, target) {
 }
 async function listReviewArtifactNames(dir) {
   try {
-    return await readdir2(dir);
+    return await readdir3(dir);
   } catch (error) {
     throw new Error(`Cannot read review artifacts in ${dir}.`, { cause: error });
   }
@@ -9641,10 +10067,10 @@ function deriveTitle(branch) {
   return branch.replace(/^(feature|feat|fix|bug|chore)\//, "").replace(/^eng-\d+-/i, "").replace(/[-_]+/g, " ").replace(/^\w/, (char) => char.toUpperCase());
 }
 function uniqueRecordPath(dir, base) {
-  let path = join16(dir, `${base}.md`);
+  let path = join17(dir, `${base}.md`);
   let count = 2;
   while (existsSync2(path))
-    path = join16(dir, `${base}-${count++}.md`);
+    path = join17(dir, `${base}-${count++}.md`);
   return path;
 }
 function artifactNameMatches(name, suffix) {
@@ -9665,21 +10091,21 @@ import { z as z13 } from "zod";
 
 // src/setup.ts
 import { parseFrontmatter as parseFrontmatter2 } from "@earendil-works/pi-coding-agent";
-import { readdir as readdir4, readFile as readFile14 } from "node:fs/promises";
+import { readdir as readdir5, readFile as readFile15 } from "node:fs/promises";
 import { homedir as homedir8 } from "node:os";
-import { basename as basename6, join as join20 } from "node:path";
+import { basename as basename6, join as join21 } from "node:path";
 
 // src/config.ts
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { z as z12 } from "zod";
 import { homedir as homedir5 } from "node:os";
-import { join as join17 } from "node:path";
+import { join as join18 } from "node:path";
 
 // src/fsx.ts
-import { readdir as readdir3, readFile as readFile12 } from "node:fs/promises";
+import { readdir as readdir4, readFile as readFile13 } from "node:fs/promises";
 async function readTextIfExists(path) {
   try {
-    return await readFile12(path, "utf8");
+    return await readFile13(path, "utf8");
   } catch (error) {
     if (isMissingPath(error))
       return;
@@ -9699,10 +10125,10 @@ var diffpiConfigSchema = z12.object({
   agents: z12.record(z12.string(), agentConfigSchema).optional()
 }).strict();
 function diffpiConfigPaths(homeDir = homedir5()) {
-  const directory = join17(homeDir, ".difflab", "diffpi");
+  const directory = join18(homeDir, ".difflab", "diffpi");
   return {
-    yaml: join17(directory, "config.yaml"),
-    json: join17(directory, "config.json")
+    yaml: join18(directory, "config.yaml"),
+    json: join18(directory, "config.json")
   };
 }
 async function loadDiffpiConfig(options = {}) {
@@ -9758,12 +10184,12 @@ function normalizeModelReference(value) {
 }
 
 // src/mcp.ts
-import { mkdir as mkdir8, readFile as readFile13, writeFile as writeFile8 } from "node:fs/promises";
+import { mkdir as mkdir8, readFile as readFile14, writeFile as writeFile8 } from "node:fs/promises";
 import { homedir as homedir6 } from "node:os";
-import { dirname as dirname8, join as join18 } from "node:path";
+import { dirname as dirname8, join as join19 } from "node:path";
 var mcp = {
   globalConfigPath(homeDir = homedir6()) {
-    return join18(homeDir, ".config", "mcp", "mcp.json");
+    return join19(homeDir, ".config", "mcp", "mcp.json");
   },
   async serversEnsure(servers, options = {}) {
     const path = options.path ?? mcp.globalConfigPath();
@@ -9806,7 +10232,7 @@ function getParsedConfig(content, path) {
 }
 async function getOptionalFile2(path) {
   try {
-    return await readFile13(path, "utf8");
+    return await readFile14(path, "utf8");
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT")
       return;
@@ -9820,7 +10246,7 @@ function isRecord(value) {
 // src/pi.ts
 import { mkdir as mkdir9, writeFile as writeFile9 } from "node:fs/promises";
 import { homedir as homedir7 } from "node:os";
-import { dirname as dirname9, join as join19 } from "node:path";
+import { dirname as dirname9, join as join20 } from "node:path";
 var pi = {
   executableCheck: findPiExecutable,
   packageList: listPiPackages,
@@ -9833,7 +10259,7 @@ var pi = {
   configEnsure: ensurePiConfig
 };
 async function ensurePiAgent(filename, content, agentDir = resolvePiAgentDir(), dryRun = false) {
-  const path = join19(agentDir, "agents", filename);
+  const path = join20(agentDir, "agents", filename);
   const currentText = await readTextIfExists(path);
   const changed = currentText !== content;
   if (changed && !dryRun) {
@@ -9842,10 +10268,10 @@ async function ensurePiAgent(filename, content, agentDir = resolvePiAgentDir(),
   }
   return { path, changed, existed: currentText !== undefined, planned: changed && dryRun };
 }
-async function checkGlobalPiSkill(name, agentDir = resolvePiAgentDir(), sharedSkillsDir = join19(homedir7(), ".agents", "skills")) {
-  const roots = [join19(agentDir, "skills"), sharedSkillsDir];
+async function checkGlobalPiSkill(name, agentDir = resolvePiAgentDir(), sharedSkillsDir = join20(homedir7(), ".agents", "skills")) {
+  const roots = [join20(agentDir, "skills"), sharedSkillsDir];
   for (const root of roots) {
-    if (await readTextIfExists(join19(root, name, "SKILL.md")) !== undefined)
+    if (await readTextIfExists(join20(root, name, "SKILL.md")) !== undefined)
       return true;
   }
   return false;
@@ -9895,7 +10321,7 @@ async function installPiPackage(executable, source) {
   await runChecked(executable, ["install", source]);
 }
 function resolvePiAgentDir(homeDir = homedir7()) {
-  return process.env.PI_CODING_AGENT_DIR ?? (process.env.XDG_CONFIG_HOME ? join19(process.env.XDG_CONFIG_HOME, "pi") : join19(homeDir, ".pi", "agent"));
+  return process.env.PI_CODING_AGENT_DIR ?? (process.env.XDG_CONFIG_HOME ? join20(process.env.XDG_CONFIG_HOME, "pi") : join20(homeDir, ".pi", "agent"));
 }
 function parseJsonObject(content, path) {
   if (!content?.trim())
@@ -9947,7 +10373,7 @@ var FORGE_DEPENDENCIES = {
 };
 async function ensureMise(options = {}) {
   const homeDir = options.homeDir ?? homedir8();
-  const current = await mise.executableCheck() ?? await mise.executableCheck(join20(homeDir, ".local", "bin", "mise"));
+  const current = await mise.executableCheck() ?? await mise.executableCheck(join21(homeDir, ".local", "bin", "mise"));
   if (current)
     return { executable: current, action: createSetupAction("mise", "ready", current) };
   reportProgress(options, "Installing mise");
@@ -9996,9 +10422,9 @@ async function ensureMiseDeps(miseExecutable, options = {}) {
 async function ensurePiPlugins(options = {}) {
   const actions = await ensurePiPackages(PI_PACKAGES, options);
   const agentDir = options.agentDir ?? pi.agentDir(options.homeDir);
-  const webSearch = await pi.configEnsure(join20(agentDir, "web-search.json"), (config) => ({ ...config, workflow: "auto-summary" }), options.dryRun);
+  const webSearch = await pi.configEnsure(join21(agentDir, "web-search.json"), (config) => ({ ...config, workflow: "auto-summary" }), options.dryRun);
   actions.push(getConfigSetupAction("web search settings", webSearch));
-  const lsp = await pi.configEnsure(join20(agentDir, "pi-lsp.json"), (config) => ({
+  const lsp = await pi.configEnsure(join21(agentDir, "pi-lsp.json"), (config) => ({
     ...config,
     progressive: { ...getRecord(config.progressive), enabled: true, inject: "none" }
   }), options.dryRun);
@@ -10009,11 +10435,11 @@ async function ensurePiAgents(options = {}) {
   const agentDir = options.agentDir ?? pi.agentDir(options.homeDir);
   const bundledAgentsDir = options.bundledAgentsDir ?? BUNDLED_AGENTS_DIR;
   const userConfig = await loadDiffpiConfig({ homeDir: options.homeDir });
-  const entries = (await readdir4(bundledAgentsDir, { withFileTypes: true })).filter((entry) => entry.isFile() && entry.name.startsWith("diffpi-") && entry.name.endsWith(".md")).sort((left, right) => left.name.localeCompare(right.name));
+  const entries = (await readdir5(bundledAgentsDir, { withFileTypes: true })).filter((entry) => entry.isFile() && entry.name.startsWith("diffpi-") && entry.name.endsWith(".md")).sort((left, right) => left.name.localeCompare(right.name));
   const actions = [];
   for (const entry of entries) {
     const id = basename6(entry.name, ".md").replace(/^diffpi-/, "");
-    const source = await readFile14(join20(bundledAgentsDir, entry.name), "utf8");
+    const source = await readFile15(join21(bundledAgentsDir, entry.name), "utf8");
     const content = materializeAgentModels(source, id, userConfig.config, options.availableModels);
     const result = await pi.agentEnsure(entry.name, content, agentDir, options.dryRun);
     actions.push(getConfigSetupAction(`pi agent ${id}`, result));
@@ -10022,7 +10448,7 @@ async function ensurePiAgents(options = {}) {
 }
 async function ensurePiSkills(miseExecutable, options = {}) {
   const agentDir = options.agentDir ?? pi.agentDir(options.homeDir);
-  const sharedSkillsDir = join20(options.homeDir ?? homedir8(), ".agents", "skills");
+  const sharedSkillsDir = join21(options.homeDir ?? homedir8(), ".agents", "skills");
   const actions = [];
   for (const source of PI_SKILL_SOURCES) {
     const missing = [];
@@ -10218,7 +10644,7 @@ function reportProgress(options, message) {
   options.onProgress?.(message);
 }
 async function packageVersion2() {
-  const source = await readFile14(join20(resolveBundledAgentsDir(), "..", "package.json"), "utf8");
+  const source = await readFile15(join21(resolveBundledAgentsDir(), "..", "package.json"), "utf8");
   let value;
   try {
     value = JSON.parse(source);