@difflab/pi 0.6.0 → 0.7.0

package/dist/index.js

@@ -605,6 +605,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];
@@ -614,16 +624,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) {
@@ -658,10 +658,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;
@@ -678,7 +683,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)
@@ -688,7 +693,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 };
   }
@@ -1301,6 +1306,9 @@ function yymmdd(date = new Date) {
 function reviewRecordName(target, date = new Date) {
   return `${yymmdd(date)}-${reviewSlug(target) || "uncommitted"}`;
 }
+function isLocalResponse(body) {
+  return /^<!-- diffpi(?:-local-response:[A-Za-z0-9_-]+)? -->\n/m.test(body);
+}
 function dedupeFindings(findings) {
   const rank = { BLOCKING: 3, CONSIDER: 2, NOTE: 1 };
   const byKey = new Map;
@@ -1346,6 +1354,18 @@ function renderCommentBody(finding) {
   return `${prefix}${finding.body}${reference}`;
 }
 // src/review/review-markdown.ts
+import { z as z4 } from "zod";
+var reviewThreadRecordSchema = z4.object({
+  id: z4.string().min(1),
+  file: z4.string().nullable().optional().transform((value) => value ?? undefined),
+  line: z4.number().int().positive().nullable().optional().transform((value) => value ?? undefined),
+  body: z4.string(),
+  author: z4.string().optional(),
+  resolved: z4.boolean(),
+  addressed: z4.boolean().optional(),
+  question: z4.boolean(),
+  replies: z4.array(z4.string()).optional()
+});
 function renderReviewDoc(input) {
   const anchored = dedupeFindings(input.findings).filter((finding) => finding.line > 0);
   const lines = [`# Review: ${input.title}`, "", "## Metadata"];
@@ -1387,6 +1407,88 @@ function renderReviewDoc(input) {
 `).trimEnd()}
 `;
 }
+function renderThreadArtifact(title, target, threads, options = {}) {
+  const records = threads.map((thread) => ({
+    id: thread.id,
+    file: thread.file,
+    line: thread.line,
+    body: thread.body,
+    author: thread.author,
+    resolved: thread.resolved,
+    addressed: thread.addressed,
+    question: thread.question,
+    replies: thread.replies
+  }));
+  const payload = Buffer.from(JSON.stringify(records), "utf8").toString("base64url");
+  const lines = [
+    `<!-- diffpi-threads:${payload} -->`,
+    `# Review threads: ${title}`,
+    "",
+    "## Metadata",
+    "",
+    `- Target: ${target}`,
+    `- Pulled: ${options.timestamp ?? new Date().toISOString()}`
+  ];
+  if (options.number !== undefined)
+    lines.push(`- PR/MR: #${options.number}${options.url ? ` — ${options.url}` : ""}`);
+  lines.push("", "## Replies", "");
+  for (const thread of threads) {
+    const id = Buffer.from(thread.id, "utf8").toString("base64url");
+    lines.push(`### ${thread.file ?? "review"}:${thread.line ?? "n/a"} (${thread.id})`, "", `<!-- diffpi-reply-start:${id} -->`, thread.reply ?? "", `<!-- diffpi-reply-end:${id} -->`, "");
+  }
+  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"}`, "", "**Source comment**", "", thread.body, "", "**Recorded response**", "", thread.reply?.trim() || "_No response recorded._", "", "---", "");
+  }
+  return `${lines.join(`
+`).trimEnd()}
+`;
+}
+function parseThreadArtifact(content) {
+  const payload = content.match(/^<!-- diffpi-threads:([A-Za-z0-9_-]+) -->$/m)?.[1];
+  if (!payload)
+    throw new Error("This file is not a Diffpi thread artifact.");
+  let threads;
+  try {
+    const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    threads = z4.array(reviewThreadRecordSchema).parse(decoded);
+  } catch {
+    throw new Error("Cannot parse the Diffpi thread artifact payload.");
+  }
+  const replies = content.split(/^## Source comments$/m, 1)[0] ?? "";
+  return threads.map((thread) => {
+    const id = Buffer.from(thread.id, "utf8").toString("base64url");
+    const startMarker = `<!-- diffpi-reply-start:${id} -->
+`;
+    const endMarker = `
+<!-- diffpi-reply-end:${id} -->`;
+    const start = replies.indexOf(startMarker);
+    const end = start < 0 ? -1 : replies.indexOf(endMarker, start + startMarker.length);
+    const reply = start >= 0 && end >= 0 ? replies.slice(start + startMarker.length, end).trim() : "";
+    return reply ? { ...thread, reply } : thread;
+  });
+}
+function upsertThreadReply(content, threadId, body, question, resolved) {
+  const threads = parseThreadArtifact(content);
+  const thread = threads.find((candidate) => candidate.id === threadId);
+  if (!thread)
+    throw new Error(`Review thread ${threadId} was not found in the local artifact.`);
+  thread.reply = body;
+  thread.addressed = true;
+  if (question !== undefined)
+    thread.question = question;
+  if (resolved !== undefined)
+    thread.resolved = resolved;
+  const title = content.match(/^# Review threads: (.+)$/m)?.[1] ?? "review";
+  const target = content.match(/^- Target: (.+)$/m)?.[1] ?? "local";
+  const timestamp = content.match(/^- Pulled: (.+)$/m)?.[1];
+  const pr = content.match(/^- PR\/MR: #(\d+)(?: — (.+))?$/m);
+  return renderThreadArtifact(title, target, threads, {
+    timestamp,
+    number: pr ? Number.parseInt(pr[1], 10) : undefined,
+    url: pr?.[2]
+  });
+}
 // src/review/github-review-backend.ts
 function GitHubReviewBackend(vcs, number) {
   const pendingReview = async () => {
@@ -1448,6 +1550,9 @@ function GitHubReviewBackend(vcs, number) {
         id: thread.id,
         file: thread.path ?? undefined,
         line: thread.line ?? undefined,
+        rootCommentId: comment?.id,
+        commentIds: nodes.flatMap((node) => [node.id, node.databaseId?.toString()].filter((id) => Boolean(id))),
+        commentNodeIds: nodes.flatMap((node) => node.id ? [node.id] : []),
         body,
         author: comment?.author?.login,
         resolved: thread.isResolved,
@@ -1457,6 +1562,7 @@ function GitHubReviewBackend(vcs, number) {
     });
   };
   return {
+    kind: "remote",
     async stage(draft) {
       const pending = await pendingReview();
       if (!pending) {
@@ -1514,6 +1620,33 @@ function GitHubReviewBackend(vcs, number) {
         await ghChecked(args);
       }
     },
+    async readDraft() {
+      const pending = await pendingReview();
+      if (!pending)
+        return { comments: [], body: "" };
+      const review = await ghChecked(["api", `/repos/${vcs.owner}/${vcs.repo}/pulls/${number}/reviews/${pending.id}`]);
+      const comments = await ghChecked([
+        "api",
+        `/repos/${vcs.owner}/${vcs.repo}/pulls/${number}/reviews/${pending.id}/comments`
+      ]);
+      let reviewData;
+      let commentData;
+      try {
+        reviewData = JSON.parse(review.stdout);
+        commentData = JSON.parse(comments.stdout);
+      } catch {
+        throw new Error("Cannot parse the pending GitHub review as JSON.");
+      }
+      return {
+        body: reviewData.body ?? "",
+        comments: commentData.map((comment) => ({
+          file: comment.path,
+          line: comment.line ?? comment.original_line ?? undefined,
+          side: comment.side ?? undefined,
+          body: comment.body
+        }))
+      };
+    },
     listThreads,
     async reply(input) {
       const threads = await listThreads();
@@ -1530,14 +1663,32 @@ function GitHubReviewBackend(vcs, number) {
           `body=${input.body}`
         ]);
       }
-      if (input.resolve) {
+      if (input.resolve)
+        await this.setResolved?.(input.threadId, true);
+    },
+    async setResolved(threadId, resolved) {
+      await ghChecked([
+        "api",
+        "graphql",
+        "-f",
+        `query=${resolved ? GITHUB_RESOLVE_MUTATION : GITHUB_UNRESOLVE_MUTATION}`,
+        "-f",
+        `threadId=${threadId}`
+      ]);
+    },
+    async deleteThread(threadId) {
+      const thread = (await listThreads()).find((candidate) => candidate.id === threadId);
+      const commentNodeIds = thread?.commentNodeIds ?? (thread?.rootCommentId ? [thread.rootCommentId] : []);
+      if (!commentNodeIds.length)
+        throw new Error(`Cannot delete GitHub thread ${threadId}: comment node IDs are missing.`);
+      for (const commentId of commentNodeIds) {
         await ghChecked([
           "api",
           "graphql",
           "-f",
-          `query=${GITHUB_RESOLVE_MUTATION}`,
+          `query=${GITHUB_DELETE_COMMENT_MUTATION}`,
           "-f",
-          `threadId=${input.threadId}`
+          `commentId=${commentId}`
         ]);
       }
     },
@@ -1556,11 +1707,13 @@ function GitHubReviewBackend(vcs, number) {
 function githubReviewSubmissionEndpoint(owner, repo, id, pendingReviewId) {
   return pendingReviewId ? `/repos/${owner}/${repo}/pulls/${id}/reviews/${pendingReviewId}/events` : `/repos/${owner}/${repo}/pulls/${id}/reviews`;
 }
-var GITHUB_THREADS_QUERY = `query($owner:String!,$repo:String!,$number:Int!,$after:String){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviewThreads(first:100,after:$after){nodes{id,isResolved,path,line,comments(first:100){nodes{body,author{login}}}}pageInfo{hasNextPage,endCursor}}}}}`;
+var GITHUB_THREADS_QUERY = `query($owner:String!,$repo:String!,$number:Int!,$after:String){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviewThreads(first:100,after:$after){nodes{id,isResolved,path,line,comments(first:100){nodes{id,databaseId,body,author{login}}}}pageInfo{hasNextPage,endCursor}}}}}`;
 var GITHUB_ADD_THREAD_MUTATION = `mutation($reviewId:ID!,$body:String!,$path:String!,$line:Int!,$side:DiffSide!){addPullRequestReviewThread(input:{pullRequestReviewId:$reviewId,body:$body,path:$path,line:$line,side:$side}){thread{id}}}`;
 var GITHUB_ADD_FILE_THREAD_MUTATION = `mutation($reviewId:ID!,$body:String!,$path:String!){addPullRequestReviewThread(input:{pullRequestReviewId:$reviewId,body:$body,path:$path,subjectType:FILE}){thread{id}}}`;
 var GITHUB_REPLY_MUTATION = `mutation($threadId:ID!,$body:String!){addPullRequestReviewThreadReply(input:{pullRequestReviewThreadId:$threadId,body:$body}){comment{id}}}`;
 var GITHUB_RESOLVE_MUTATION = `mutation($threadId:ID!){resolveReviewThread(input:{threadId:$threadId}){thread{isResolved}}}`;
+var GITHUB_UNRESOLVE_MUTATION = `mutation($threadId:ID!){unresolveReviewThread(input:{threadId:$threadId}){thread{isResolved}}}`;
+var GITHUB_DELETE_COMMENT_MUTATION = `mutation($commentId:ID!){deletePullRequestReviewComment(input:{id:$commentId}){clientMutationId}}`;
 
 // src/review/gitlab-review-backend.ts
 function GitLabReviewBackend(vcs, number) {
@@ -1597,6 +1750,7 @@ function GitLabReviewBackend(vcs, number) {
     });
   };
   return {
+    kind: "remote",
     async stage(draft) {
       const endpoint = `${mergeRequestEndpoint()}/draft_notes`;
       if (draft.body.trim()) {
@@ -1625,6 +1779,36 @@ function GitLabReviewBackend(vcs, number) {
         });
       }
     },
+    async readDraft() {
+      const result = await glabChecked(["api", `${mergeRequestEndpoint()}/draft_notes`]);
+      let notes;
+      try {
+        notes = JSON.parse(result.stdout);
+      } catch {
+        throw new Error("Cannot parse GitLab draft notes as JSON.");
+      }
+      const comments = [];
+      const body = [];
+      for (const note of notes) {
+        if (!note.note)
+          continue;
+        const file = note.position?.new_path ?? note.position?.old_path;
+        const line = note.position?.new_line ?? note.position?.old_line;
+        if (file && line) {
+          comments.push({
+            file,
+            line,
+            side: note.position?.new_line ? "RIGHT" : "LEFT",
+            body: note.note
+          });
+        } else {
+          body.push(note.note);
+        }
+      }
+      return { comments, body: body.join(`
+
+`) };
+    },
     listThreads,
     async reply(input) {
       const endpoint = `${mergeRequestEndpoint()}/discussions/${encodeURIComponent(input.threadId)}`;
@@ -1636,7 +1820,15 @@ function GitLabReviewBackend(vcs, number) {
         });
       }
       if (input.resolve)
-        await glabChecked(["api", "--method", "PUT", `${endpoint}?resolved=true`]);
+        await this.setResolved?.(input.threadId, true);
+    },
+    async setResolved(threadId, resolved) {
+      const endpoint = `${mergeRequestEndpoint()}/discussions/${encodeURIComponent(threadId)}`;
+      await glabChecked(["api", "--method", "PUT", `${endpoint}?resolved=${resolved}`]);
+    },
+    async deleteThread(threadId) {
+      const endpoint = `${mergeRequestEndpoint()}/discussions/${encodeURIComponent(threadId)}`;
+      await glabChecked(["api", "--method", "DELETE", endpoint]);
     },
     async publish(event) {
       assertReviewEventSupported(vcs.provider, event);
@@ -1676,105 +1868,12 @@ function hasGitlabDraftNotes(input) {
   }
 }
 
-// src/review/review-backend.ts
-function createRemoteReviewBackend(vcs, number) {
-  if (vcs.provider === "github")
-    return GitHubReviewBackend(vcs, number);
-  if (vcs.provider === "gitlab")
-    return GitLabReviewBackend(vcs, number);
-  throw new Error("A remote review backend requires a GitHub or GitLab repository.");
-}
-// src/review/local-reviews.ts
-import { mkdir as mkdir4, readdir as readdir2, readFile as readFile6, unlink as unlink2, writeFile as writeFile3 } from "node:fs/promises";
-import { join as join9 } from "node:path";
-
-// src/store.ts
-import { createHash } from "node:crypto";
-import { lstat, mkdir as mkdir3, readlink, realpath as realpath2, symlink, unlink } from "node:fs/promises";
-import { homedir as homedir4 } from "node:os";
-import { dirname as dirname4, isAbsolute as isAbsolute2, join as join8, resolve as resolve2 } from "node:path";
-var STORE_LINK = ".diffpi";
-var LEGACY_STORE_LINK = join8(".pi", "diffpi");
-async function computeProjectSlug(cwd) {
-  return projectSlug(await inspectGitRepository(cwd));
-}
-function storeGlobalRoot(homeDir = homedir4()) {
-  return join8(homeDir, ".difflab", "diffpi", "projects");
-}
-async function ensureStore(cwd, homeDir = homedir4()) {
-  const repository = await inspectGitRepository(cwd);
-  const root = repository.root;
-  const slug = projectSlug(repository);
-  const dest = join8(storeGlobalRoot(homeDir), slug);
-  const link = join8(root, STORE_LINK);
-  await mkdir3(dest, { recursive: true });
-  try {
-    await assertStoreLink(link, dest);
-  } catch (error) {
-    if (error.code !== "ENOENT")
-      throw error;
-    await symlink(dest, link);
-  }
-  await removeLegacyStoreLink(join8(root, LEGACY_STORE_LINK), dest);
-  return { slug, root, dest, link, linked: true };
-}
-async function storeDir(cwd, homeDir = homedir4()) {
-  const store = await ensureStore(cwd, homeDir);
-  return store.dest;
-}
-async function plansDir(cwd, homeDir = homedir4()) {
-  const store = await ensureStore(cwd, homeDir);
-  const dir = join8(store.link, "plan");
-  await mkdir3(dir, { recursive: true });
-  return dir;
-}
-async function reviewsDir(cwd, homeDir = homedir4()) {
-  const store = await ensureStore(cwd, homeDir);
-  const dir = join8(store.link, "review");
-  await mkdir3(dir, { recursive: true });
-  return dir;
-}
-async function assertStoreLink(path, dest) {
-  const entry = await lstat(path);
-  if (!entry.isSymbolicLink())
-    throw new Error(`${path} exists and is not a symlink.`);
-  const target = await symlinkTarget(path);
-  if (target !== await canonicalPath2(dest))
-    throw new Error(`${path} points to ${target}, not ${dest}.`);
-}
-async function removeLegacyStoreLink(path, dest) {
-  try {
-    const entry = await lstat(path);
-    if (!entry.isSymbolicLink())
-      return;
-    const target = await symlinkTarget(path);
-    if (target === await canonicalPath2(dest))
-      await unlink(path);
-  } catch (error) {
-    if (error.code !== "ENOENT")
-      throw error;
-  }
-}
-async function symlinkTarget(path) {
-  const target = await readlink(path);
-  return canonicalPath2(isAbsolute2(target) ? target : resolve2(dirname4(path), target));
-}
-async function canonicalPath2(path) {
-  try {
-    return await realpath2(path);
-  } catch {
-    return resolve2(path);
-  }
-}
-function projectSlug(repository) {
-  const readable = repository.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "unnamed";
-  const digest = createHash("sha256").update(repository.identity).digest("hex").slice(0, 12);
-  return `${readable}-${digest}`;
-}
+// src/review/local-review-backend.ts
+import { readFile as readFile6, writeFile as writeFile3 } from "node:fs/promises";
 
 // src/extensions/tuicrx.ts
-import { readFile as readFile5, realpath as realpath3 } from "node:fs/promises";
-import { resolve as resolve3 } from "node:path";
+import { readFile as readFile5, realpath as realpath2 } from "node:fs/promises";
+import { resolve as resolve2 } from "node:path";
 async function tuicrAvailable() {
   return Boolean(await findExecutable("tuicr"));
 }
@@ -1850,7 +1949,7 @@ async function resolvePrSession(cwd, owner, repo, number) {
   });
 }
 async function findMatchingSession(sessions, cwd, branch) {
-  const repository = await canonicalPath3(await gitToplevel(cwd));
+  const repository = await canonicalPath2(await gitToplevel(cwd));
   for (const session of sessions) {
     if (session.kind !== "local")
       continue;
@@ -1858,7 +1957,7 @@ async function findMatchingSession(sessions, cwd, branch) {
       const data = await readSession(session.path);
       if (data.branch_name !== branch || !data.repo_path)
         continue;
-      if (await canonicalPath3(data.repo_path) === repository)
+      if (await canonicalPath2(data.repo_path) === repository)
         return session;
     } catch {}
   }
@@ -1872,33 +1971,53 @@ async function readSession(path) {
     throw new Error(`Cannot parse tuicr session JSON: ${path}`);
   }
 }
-function toLocalReviewThreads(session) {
-  const threads = [];
-  const add = (comment, location = {}) => {
+function toFindings(session, options = {}) {
+  const comments = [];
+  const include = (comment) => (!options.agentOnly || commentAuthor(comment)?.startsWith("Agent: ")) && (!options.excludeLocalResponses || !isLocalResponse(comment.content));
+  const publishableBody = (comment) => {
     const author = commentAuthor(comment);
-    threads.push({
-      id: comment.id ?? `local-${threads.length + 1}`,
-      ...location,
-      body: comment.content,
-      ...author ? { author } : {},
-      resolved: false,
-      question: /\?\s*$/.test(comment.content.trim())
-    });
+    const route = author?.match(/^Agent:\s*(.+)$/)?.[1];
+    return route ? withRemoteProvenance(comment.content, route) : comment.content;
   };
-  for (const comment of session.review_comments ?? [])
-    add(comment);
+  const bodyParts = (session.review_comments ?? []).flatMap((comment) => include(comment) ? [publishableBody(comment)] : []);
   for (const [file, entry] of Object.entries(session.files ?? {})) {
-    for (const comment of entry.file_comments ?? [])
-      add(comment, { file });
+    for (const fileComment of entry.file_comments ?? []) {
+      if (!include(fileComment))
+        continue;
+      const comment = {
+        file,
+        body: fileComment.content,
+        ...fileComment.id ? { sourceCommentId: String(fileComment.id) } : {}
+      };
+      const author = commentAuthor(fileComment);
+      if (author)
+        comment.author = author;
+      comments.push(comment);
+    }
     for (const [lineKey, lineComments] of Object.entries(entry.line_comments ?? {})) {
       const line = Number.parseInt(lineKey, 10);
       if (!Number.isFinite(line))
         continue;
-      for (const comment of lineComments)
-        add(comment, { file, line });
+      for (const lineComment of lineComments) {
+        if (!include(lineComment))
+          continue;
+        const comment = {
+          file,
+          line,
+          side: lineComment.side === "old" ? "LEFT" : "RIGHT",
+          body: lineComment.content,
+          ...lineComment.id ? { sourceCommentId: String(lineComment.id) } : {}
+        };
+        const author = commentAuthor(lineComment);
+        if (author)
+          comment.author = author;
+        comments.push(comment);
+      }
     }
   }
-  return threads;
+  return { comments, body: bodyParts.join(`
+
+`) };
 }
 async function requireTuicr() {
   if (!await tuicrAvailable())
@@ -1907,70 +2026,207 @@ async function requireTuicr() {
 function commentAuthor(comment) {
   return comment.username ?? comment.author;
 }
-async function canonicalPath3(path) {
+async function canonicalPath2(path) {
   try {
-    return await realpath3(path);
+    return await realpath2(path);
   } catch {
-    return resolve3(path);
+    return resolve2(path);
   }
 }
 
-// src/review/local-reviews.ts
-async function captureLocalReview(input) {
-  const id = reviewSlug(input.branch) || "local-review";
-  const dir = join9(await reviewsDir(input.cwd, input.homeDir), id);
-  await mkdir4(dir, { recursive: true });
-  const revision = await nextRevision(dir);
-  const output = await readFile6(input.session.path, "utf8");
-  const comments = toLocalReviewThreads(await readSession(input.session.path));
-  const dump = {
-    schemaVersion: 1,
-    id,
-    revision,
-    branch: input.branch,
-    base: input.base,
-    createdAt: (input.now ?? (() => new Date))().toISOString(),
-    diff: input.diff,
-    comments,
-    tuicr: { slug: input.session.slug, output }
+// src/review/local-review-backend.ts
+function LocalReviewBackend(options) {
+  return {
+    kind: "local",
+    async stage(draft) {
+      for (const comment of draft.comments) {
+        await addComment(options.session, comment.body, {
+          targetFile: comment.file,
+          line: comment.line,
+          side: comment.side === "LEFT" ? "old" : "new",
+          username: options.author
+        });
+      }
+      if (draft.body.trim())
+        await addComment(options.session, draft.body, { username: options.author });
+    },
+    async readDraft() {
+      return toFindings(await readSession(options.session), { excludeLocalResponses: true });
+    },
+    async listThreads() {
+      try {
+        return parseThreadArtifact(await readFile6(options.artifactPath, "utf8"));
+      } catch (error) {
+        if (error.code === "ENOENT")
+          return [];
+        throw error;
+      }
+    },
+    async reply(input) {
+      const content = await readFile6(options.artifactPath, "utf8");
+      await writeFile3(options.artifactPath, upsertThreadReply(content, input.threadId, input.body, input.question, input.resolve), "utf8");
+    },
+    async publish() {
+      throw new Error("Promote a local draft through a remote review backend before publishing it.");
+    }
   };
-  const path = join9(dir, `${revision}.json`);
-  await writeFile3(path, `${JSON.stringify(dump, null, 2)}
-`, { encoding: "utf8", flag: "wx" });
-  await unlink2(input.session.path);
-  return { path, dump };
-}
-async function readLocalReview(cwd, branch, revision, homeDir) {
-  const id = reviewSlug(branch) || "local-review";
-  const dir = join9(await reviewsDir(cwd, homeDir), id);
-  const selected = revision ?? await latestRevision(dir);
-  if (!selected)
-    return;
+}
+
+// src/review/review-backend.ts
+function createRemoteReviewBackend(vcs, number) {
+  if (vcs.provider === "github")
+    return GitHubReviewBackend(vcs, number);
+  if (vcs.provider === "gitlab")
+    return GitLabReviewBackend(vcs, number);
+  throw new Error("A remote review backend requires a GitHub or GitLab repository.");
+}
+function createLocalReviewBackend(options) {
+  return LocalReviewBackend(options);
+}
+// src/review/review-state.ts
+import { createHash as createHash2 } from "node:crypto";
+import { readFile as readFile7, rename, writeFile as writeFile4 } from "node:fs/promises";
+import { join as join9 } from "node:path";
+import { z as z5 } from "zod";
+
+// src/store.ts
+import { createHash } from "node:crypto";
+import { lstat, mkdir as mkdir3, readlink, realpath as realpath3, symlink, unlink } from "node:fs/promises";
+import { homedir as homedir4 } from "node:os";
+import { dirname as dirname4, isAbsolute as isAbsolute2, join as join8, resolve as resolve3 } from "node:path";
+var STORE_LINK = ".diffpi";
+var LEGACY_STORE_LINK = join8(".pi", "diffpi");
+async function computeProjectSlug(cwd) {
+  return projectSlug(await inspectGitRepository(cwd));
+}
+function storeGlobalRoot(homeDir = homedir4()) {
+  return join8(homeDir, ".difflab", "diffpi", "projects");
+}
+async function ensureStore(cwd, homeDir = homedir4()) {
+  const repository = await inspectGitRepository(cwd);
+  const root = repository.root;
+  const slug = projectSlug(repository);
+  const dest = join8(storeGlobalRoot(homeDir), slug);
+  const link = join8(root, STORE_LINK);
+  await mkdir3(dest, { recursive: true });
   try {
-    return JSON.parse(await readFile6(join9(dir, `${selected}.json`), "utf8"));
+    await assertStoreLink(link, dest);
   } catch (error) {
-    if (error.code === "ENOENT")
+    if (error.code !== "ENOENT")
+      throw error;
+    await symlink(dest, link);
+  }
+  await removeLegacyStoreLink(join8(root, LEGACY_STORE_LINK), dest);
+  return { slug, root, dest, link, linked: true };
+}
+async function storeDir(cwd, homeDir = homedir4()) {
+  const store = await ensureStore(cwd, homeDir);
+  return store.dest;
+}
+async function plansDir(cwd, homeDir = homedir4()) {
+  const store = await ensureStore(cwd, homeDir);
+  const dir = join8(store.link, "plan");
+  await mkdir3(dir, { recursive: true });
+  return dir;
+}
+async function reviewsDir(cwd, homeDir = homedir4()) {
+  const store = await ensureStore(cwd, homeDir);
+  const dir = join8(store.link, "review");
+  await mkdir3(dir, { recursive: true });
+  return dir;
+}
+async function sessionsDir(cwd, homeDir = homedir4()) {
+  const store = await ensureStore(cwd, homeDir);
+  const dir = join8(store.link, "sessions");
+  await mkdir3(dir, { recursive: true });
+  return dir;
+}
+async function assertStoreLink(path, dest) {
+  const entry = await lstat(path);
+  if (!entry.isSymbolicLink())
+    throw new Error(`${path} exists and is not a symlink.`);
+  const target = await symlinkTarget(path);
+  if (target !== await canonicalPath3(dest))
+    throw new Error(`${path} points to ${target}, not ${dest}.`);
+}
+async function removeLegacyStoreLink(path, dest) {
+  try {
+    const entry = await lstat(path);
+    if (!entry.isSymbolicLink())
       return;
-    throw error;
+    const target = await symlinkTarget(path);
+    if (target === await canonicalPath3(dest))
+      await unlink(path);
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
   }
 }
-async function nextRevision(dir) {
-  return await latestRevision(dir) + 1;
+async function symlinkTarget(path) {
+  const target = await readlink(path);
+  return canonicalPath3(isAbsolute2(target) ? target : resolve3(dirname4(path), target));
 }
-async function latestRevision(dir) {
+async function canonicalPath3(path) {
   try {
-    return (await readdir2(dir)).reduce((latest, name) => {
-      const match = name.match(/^(\d+)\.json$/);
-      return match ? Math.max(latest, Number(match[1])) : latest;
-    }, 0);
+    return await realpath3(path);
+  } catch {
+    return resolve3(path);
+  }
+}
+function projectSlug(repository) {
+  const readable = repository.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "unnamed";
+  const digest = createHash("sha256").update(repository.identity).digest("hex").slice(0, 12);
+  return `${readable}-${digest}`;
+}
+
+// src/review/review-state.ts
+var reviewPublicationStateSchema = z5.object({
+  target: z5.string().optional(),
+  bodies: z5.array(z5.string()).default([]),
+  comments: z5.array(z5.string()).default([]),
+  stagedComments: z5.array(z5.string()).default([]),
+  replies: z5.array(z5.string()).default([]),
+  overlayPath: z5.string().optional()
+});
+function reviewBodyFingerprint(body) {
+  return digest(body);
+}
+function reviewCommentFingerprint(comment) {
+  return digest([comment.file, String(comment.line), comment.side ?? "RIGHT", comment.body].join("\x00"));
+}
+function reviewReplyFingerprint(threadId, body) {
+  return digest(`${threadId}\x00${body}`);
+}
+function unpublishedReviewComments(comments, knownFingerprints) {
+  return comments.filter((comment) => !knownFingerprints.has(reviewCommentFingerprint(comment)));
+}
+async function loadReviewPublicationState(cwd, vcs, number, homeDir) {
+  const target = `${vcs.provider}:${vcs.owner}/${vcs.repo}#${number}`;
+  const path = join9(await sessionsDir(cwd, homeDir), `review-publish-${digest(target).slice(0, 16)}.json`);
+  try {
+    const parsed = reviewPublicationStateSchema.parse(JSON.parse(await readFile7(path, "utf8")));
+    return { path, state: { ...parsed, target } };
   } catch (error) {
-    if (error.code === "ENOENT")
-      return 0;
+    if (error.code === "ENOENT") {
+      return { path, state: { target, bodies: [], comments: [], stagedComments: [], replies: [] } };
+    }
+    if (error instanceof SyntaxError || error instanceof z5.ZodError) {
+      throw new Error(`Cannot parse review publication state: ${path}`);
+    }
     throw error;
   }
 }
+async function saveReviewPublicationState(path, state) {
+  const temp = `${path}.${process.pid}.tmp`;
+  await writeFile4(temp, `${JSON.stringify(state, null, 2)}
+`, "utf8");
+  await rename(temp, path);
+}
+function digest(value) {
+  return createHash2("sha256").update(value).digest("hex");
+}
 // src/mcp.ts
-import { mkdir as mkdir5, readFile as readFile7, writeFile as writeFile4 } from "node:fs/promises";
+import { mkdir as mkdir4, readFile as readFile8, writeFile as writeFile5 } from "node:fs/promises";
 import { homedir as homedir5 } from "node:os";
 import { dirname as dirname5, join as join10 } from "node:path";
 var mcp = {
@@ -1988,8 +2244,8 @@ var mcp = {
     const next = { ...current, mcpServers: nextServers };
     const changed = JSON.stringify(current) !== JSON.stringify(next);
     if (changed && !options.dryRun) {
-      await mkdir5(dirname5(path), { recursive: true });
-      await writeFile4(path, `${JSON.stringify(next, null, 2)}
+      await mkdir4(dirname5(path), { recursive: true });
+      await writeFile5(path, `${JSON.stringify(next, null, 2)}
 `, "utf8");
     }
     return { path, changed, existed: currentText !== undefined, planned: changed && options.dryRun === true };
@@ -2018,7 +2274,7 @@ function getParsedConfig(content, path) {
 }
 async function getOptionalFile2(path) {
   try {
-    return await readFile7(path, "utf8");
+    return await readFile8(path, "utf8");
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT")
       return;
@@ -2033,7 +2289,7 @@ import {
   getAgentDir,
   parseFrontmatter as parseFrontmatter2
 } from "@earendil-works/pi-coding-agent";
-import { readFile as readFile8 } from "node:fs/promises";
+import { readFile as readFile9 } from "node:fs/promises";
 import { homedir as homedir6 } from "node:os";
 import { basename as basename4, extname, join as join11 } from "node:path";
 async function discoverAgentModes(options) {
@@ -2232,7 +2488,7 @@ async function loadAgentModes(directory, source, modes, diagnostics, skillName)
   for (const entry of entries.filter((item) => item.isFile() && item.name.endsWith(".md")).sort((a, b) => a.name.localeCompare(b.name))) {
     const path = join11(directory, entry.name);
     try {
-      const content = await readFile8(path, "utf8");
+      const content = await readFile9(path, "utf8");
       const { frontmatter, body } = parseFrontmatter2(content.startsWith("\uFEFF") ? content.slice(1) : content);
       if (frontmatter.enabled === false || frontmatter.inline === false)
         continue;
@@ -2288,7 +2544,7 @@ function isModeBaseline(value) {
   return (model === undefined || typeof model.provider === "string" && typeof model.id === "string") && candidate.thinkingLevel !== undefined && THINKING_LEVELS.has(candidate.thinkingLevel) && Array.isArray(candidate.tools) && candidate.tools.every((tool) => typeof tool === "string");
 }
 // src/pi.ts
-import { mkdir as mkdir6, writeFile as writeFile5 } from "node:fs/promises";
+import { mkdir as mkdir5, writeFile as writeFile6 } from "node:fs/promises";
 import { homedir as homedir7 } from "node:os";
 import { dirname as dirname6, join as join12 } from "node:path";
 var pi = {
@@ -2307,8 +2563,8 @@ async function ensurePiAgent(filename, content, agentDir = resolvePiAgentDir(),
   const currentText = await readTextIfExists(path);
   const changed = currentText !== content;
   if (changed && !dryRun) {
-    await mkdir6(dirname6(path), { recursive: true });
-    await writeFile5(path, content, "utf8");
+    await mkdir5(dirname6(path), { recursive: true });
+    await writeFile6(path, content, "utf8");
   }
   return { path, changed, existed: currentText !== undefined, planned: changed && dryRun };
 }
@@ -2344,8 +2600,8 @@ async function ensurePiConfig(path, update, dryRun = false) {
   const next = update(current);
   const changed = JSON.stringify(current) !== JSON.stringify(next);
   if (changed && !dryRun) {
-    await mkdir6(dirname6(path), { recursive: true });
-    await writeFile5(path, `${JSON.stringify(next, null, 2)}
+    await mkdir5(dirname6(path), { recursive: true });
+    await writeFile6(path, `${JSON.stringify(next, null, 2)}
 `, "utf8");
   }
   return { path, changed, existed: currentText !== undefined, planned: changed && dryRun };
@@ -2378,16 +2634,17 @@ function parseJsonObject(content, path) {
   throw new Error(`Expected valid JSON object in ${path}.`);
 }
 // src/plan/store.ts
-import { mkdir as mkdir8, readdir as readdir3, readFile as readFile11, realpath as realpath4, rm as rm2 } from "node:fs/promises";
+import { createHash as createHash3, randomUUID as randomUUID2 } from "node:crypto";
+import { mkdir as mkdir7, readdir as readdir2, readFile as readFile12, realpath as realpath4, rename as rename3, rm as rm2 } from "node:fs/promises";
 import { basename as basename6, dirname as dirname8, join as join16, resolve as resolve4, sep } from "node:path";
 
 // src/extensions/fsx.ts
-import { mkdir as mkdir7, rename, rm, writeFile as writeFile6 } from "node:fs/promises";
+import { mkdir as mkdir6, rename as rename2, rm, writeFile as writeFile7 } from "node:fs/promises";
 import { basename as basename5, dirname as dirname7, join as join13 } from "node:path";
 async function atomicWrite(path, content) {
   const temp = join13(dirname7(path), `.${basename5(path)}.${crypto.randomUUID()}.tmp`);
-  await writeFile6(temp, content, { encoding: "utf8", mode: 384, flag: "wx" });
-  await rename(temp, path);
+  await writeFile7(temp, content, { encoding: "utf8", mode: 384, flag: "wx" });
+  await rename2(temp, path);
 }
 async function withDirectoryLock(lockDir, operation, options = {}) {
   const waitMs = options.waitMs ?? 5000;
@@ -2395,7 +2652,7 @@ async function withDirectoryLock(lockDir, operation, options = {}) {
   const started = Date.now();
   while (true) {
     try {
-      await mkdir7(lockDir);
+      await mkdir6(lockDir);
       break;
     } catch (error) {
       if (error.code !== "EEXIST")
@@ -2417,7 +2674,7 @@ function sleep(ms) {
 
 // src/log.ts
 import { randomUUID } from "node:crypto";
-import { appendFile, readFile as readFile9 } from "node:fs/promises";
+import { appendFile, readFile as readFile10 } from "node:fs/promises";
 async function appendLogEntry(logPath, event) {
   const entry = {
     ...event,
@@ -2431,7 +2688,7 @@ async function appendLogEntry(logPath, event) {
 }
 
 // src/templates.ts
-import { readFile as readFile10 } from "node:fs/promises";
+import { readFile as readFile11 } from "node:fs/promises";
 import { homedir as homedir8 } from "node:os";
 import { join as join14, normalize } from "node:path";
 async function loadTemplate(name, options = {}) {
@@ -2458,7 +2715,7 @@ function templateRelativePath(name) {
 }
 async function readOptionalFile(path) {
   try {
-    return await readFile10(path, "utf8");
+    return await readFile11(path, "utf8");
   } catch (error) {
     if (error.code === "ENOENT")
       return;
@@ -7135,11 +7392,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(" -> ")}.`);
@@ -7148,10 +7407,131 @@ 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;
 }
+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);
@@ -7160,6 +7540,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,
@@ -7168,6 +7550,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}`)]))));
@@ -7189,7 +7573,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
   ]);
@@ -7263,10 +7647,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) {
@@ -7316,10 +7697,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");
@@ -7346,6 +7724,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,
@@ -7395,19 +7775,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 }))
     }))
   };
 }
@@ -7507,6 +7880,13 @@ 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 parseMarker(value, label) {
   try {
     return JSON.parse(value);
@@ -7514,15 +7894,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) {
@@ -7542,7 +7921,7 @@ function planRecordName(shortSlug, date = new Date) {
 }
 async function resolvePlan(cwd, query, filters = {}, options = {}) {
   const root = await plansDir(cwd, options.homeDir);
-  const entries = await readdir3(root, { withFileTypes: true });
+  const entries = await readdir2(root, { withFileTypes: true });
   const normalizedQuery = query ? normalizeQuery(query) : undefined;
   const records = [];
   for (const entry of entries) {
@@ -7569,6 +7948,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);
@@ -7577,57 +7965,77 @@ function createPlanStore(options = {}) {
       const root = await plansDir(input.cwd, options.homeDir);
       const id = planRecordName(input.shortSlug, now());
       const dir = join16(root, id);
-      await assertContained(root, dirname8(dir));
-      try {
-        await mkdir8(dir);
-      } catch (error) {
-        if (error.code === "EEXIST")
-          throw new Error(`Plan ${id} already exists.`);
-        throw error;
-      }
+      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, join16(dir, "PLAN.md"));
-        await atomicWrite(join16(dir, "PLAN.md"), source);
-        return {
-          id,
-          dir,
-          planPath: join16(dir, "PLAN.md"),
-          logPath: join16(dir, "logs.txt"),
-          implementationDir: join16(dir, "implementation"),
-          document,
-          source
-        };
+        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 = join16(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, join16(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(join16(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(join16(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);
+      const initial = await read(cwd, query);
       return withDirectoryLock(join16(initial.dir, ".lock"), async () => {
         const current = await readRecord(initial.dir);
         const next = await update(structuredClone(current.document));
@@ -7635,18 +8043,17 @@ function createPlanStore(options = {}) {
           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: join16(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);
     }
   };
@@ -7654,7 +8061,7 @@ function createPlanStore(options = {}) {
 async function readRecord(dir) {
   const planPath = join16(dir, "PLAN.md");
   const logPath = join16(dir, "logs.txt");
-  const source = await readFile11(planPath, "utf8");
+  const source = await readFile12(planPath, "utf8");
   const document = parsePlanDocument(source, planPath);
   return {
     id: basename6(dir),
@@ -7666,29 +8073,208 @@ async function readRecord(dir) {
     source
   };
 }
-async function ensureImplementationFiles(dir, document, options) {
-  const implementationDir = join16(dir, "implementation");
-  await mkdir8(implementationDir, { recursive: true });
-  const template = await loadTemplate("plan/implementation", {
-    homeDir: options.homeDir,
-    bundledDir: options.bundledTemplatesDir
-  });
-  for (const phase of document.phases) {
-    const path = join16(implementationDir, `phase-${phase.id}.md`);
+async function createPlanDirectory(root, dir, id) {
+  await assertContained(root, dirname8(dir));
+  try {
+    await mkdir7(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 = join16(planDir, "revisions");
+  await mkdir7(revisionsDir, { recursive: true });
+  const target = join16(revisionsDir, String(document.revision));
+  try {
+    await readFile12(join16(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 = join16(revisionsDir, `.tmp-${document.revision}-${randomUUID2()}`);
+  await mkdir7(staging);
+  try {
+    const requestSource = request.kind === "annotation" ? `## Original annotation
+${request.text}
+
+## LLM response
+${request.response}` : request.text;
+    await atomicWrite(join16(staging, "request.md"), requestSource);
+    await atomicWrite(join16(staging, "metadata.json"), `${JSON.stringify({
+      schemaVersion: 1,
+      id: document.id,
+      revision: document.revision,
+      requestKind: request.kind,
+      requestSha256: sha256(request.text),
+      ...request.kind === "annotation" ? { originalAnnotationSha256: sha256(request.text), responseSha256: sha256(request.response) } : {},
+      createdAt: document.updatedAt
+    }, null, 2)}
+`);
+    await atomicWrite(join16(staging, "PLAN.md"), source);
+    await writeImplementationDirectory(staging, document, briefs);
+    await rename3(staging, target);
+  } catch (error) {
+    await rm2(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+async function writeLatestView(planDir, document, source, briefs) {
+  const current = join16(planDir, "implementation");
+  const stagingRoot = join16(planDir, `.latest-${randomUUID2()}`);
+  const stagedImplementation = join16(stagingRoot, "implementation");
+  const backup = join16(planDir, `.implementation-backup-${randomUUID2()}`);
+  await mkdir7(stagingRoot);
+  await writeImplementationDirectory(stagingRoot, document, briefs);
+  let backedUp = false;
+  try {
     try {
-      await readFile11(path, "utf8");
+      await rename3(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 rename3(stagedImplementation, current);
+    await atomicWrite(join16(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 rename3(backup, current);
+    throw error;
+  } finally {
+    await rm2(stagingRoot, { recursive: true, force: true });
+  }
+}
+async function writeImplementationDirectory(baseDir, document, briefs) {
+  const implementationDir = join16(baseDir, "implementation");
+  await mkdir7(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(join16(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 sha256(value) {
+  return createHash3("sha256").update(value).digest("hex");
 }
 async function assertContained(root, candidate) {
   const canonicalRoot = await realpath4(root);
@@ -7721,11 +8307,14 @@ 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/setup.ts
 import { parseFrontmatter as parseFrontmatter3 } from "@earendil-works/pi-coding-agent";
-import { readdir as readdir4, readFile as readFile12 } from "node:fs/promises";
+import { readdir as readdir3, readFile as readFile13 } from "node:fs/promises";
 import { homedir as homedir9 } from "node:os";
 import { basename as basename7, join as join17 } from "node:path";
 var MISE_DEPENDENCIES = [
@@ -7828,11 +8417,11 @@ async function ensurePiAgents(options = {}) {
   const agentDir = options.agentDir ?? pi.agentDir(options.homeDir);
   const bundledAgentsDir = options.bundledAgentsDir ?? BUNDLED_AGENTS_DIR2;
   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 readdir3(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 = basename7(entry.name, ".md").replace(/^diffpi-/, "");
-    const source = await readFile12(join17(bundledAgentsDir, entry.name), "utf8");
+    const source = await readFile13(join17(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));
@@ -8037,7 +8626,7 @@ function reportProgress(options, message) {
   options.onProgress?.(message);
 }
 async function packageVersion2() {
-  const source = await readFile12(join17(resolveBundledAgentsDir(), "..", "package.json"), "utf8");
+  const source = await readFile13(join17(resolveBundledAgentsDir(), "..", "package.json"), "utf8");
   let value;
   try {
     value = JSON.parse(source);
@@ -8062,11 +8651,11 @@ export {
   addComment,
   assertGitHubMergeReady,
   assertReviewEventSupported,
-  captureLocalReview,
   checkConventionalSubject,
   computeProjectSlug,
   createForge,
   createForgeBackend,
+  createLocalReviewBackend,
   createModeController,
   createPlanStore,
   createRemoteReviewBackend,
@@ -8099,6 +8688,7 @@ export {
   launch,
   listSessions,
   loadDiffpiConfig,
+  loadReviewPublicationState,
   loadTemplate,
   localReviewAuthor,
   mcp,
@@ -8107,28 +8697,37 @@ export {
   openInNewTab,
   parseGitlabDiffRefs,
   parseRemote,
+  parseThreadArtifact,
   pi,
   plansDir,
-  readLocalReview,
   readSession,
   renderReviewDoc,
   renderTemplate,
+  renderThreadArtifact,
   resolveAgentMode,
   resolveAgentModelPreferences,
   resolvePrSession,
   resolveReviewSession,
   resolveSession,
+  reviewBodyFingerprint,
+  reviewCommentFingerprint,
   reviewRecordName,
+  reviewReplyFingerprint,
   reviewSlug,
   reviewsDir,
   runMiseGates,
+  saveReviewPublicationState,
+  sessionsDir,
   setupPi,
   severitySchema,
   storeDir,
   storeGlobalRoot,
   templateRelativePath,
+  toFindings,
   toReviewComments,
   tuicrAvailable,
+  unpublishedReviewComments,
+  upsertThreadReply,
   withRemoteProvenance,
   yymmdd,
   zedKeymapPath,