@difflab/pi 0.4.0 → 0.5.0-rc.202609231313.eaf7fa0

package/dist/cli.js

@@ -2331,7 +2331,11 @@ function run(command, args, options = {}) {
     const child = spawn(command, args, {
       cwd: options.cwd,
       env: options.env ?? process.env,
-      stdio: [options.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+      stdio: [
+        options.interactive ? "inherit" : options.input === undefined ? "ignore" : "pipe",
+        options.interactive ? "inherit" : "pipe",
+        "pipe"
+      ],
       signal: options.signal
     });
     let stdout = "";
@@ -2348,6 +2352,8 @@ function run(command, args, options = {}) {
     });
     child.stderr?.on("data", (chunk) => {
       const text = chunk.toString();
+      if (options.interactive)
+        process.stderr.write(text);
       if (unbounded)
         stderrChunks.push(text);
       else
@@ -2376,32 +2382,52 @@ function appendBounded(current, next) {
   return combined.length <= MAX_CAPTURED_OUTPUT_LENGTH ? combined : combined.slice(-MAX_CAPTURED_OUTPUT_LENGTH);
 }
 
-// src/extensions/subagentx.ts
-import { z } from "zod";
-var escalationSchema = z.object({
-  correlation: z.object({
-    workflow: z.string().min(1),
-    executionId: z.string().min(1).optional(),
-    unitId: z.string().min(1).optional(),
-    parentUnitId: z.string().min(1).optional(),
-    metadata: z.record(z.string(), z.string()).optional()
-  }).strict(),
-  blocker: z.string().min(1),
-  attempts: z.array(z.string()),
-  evidence: z.array(z.string()),
-  needsUserDecision: z.boolean()
-}).strict();
-var ESCALATION_OPEN = "<diffpi-subagent-escalation>";
-var ESCALATION_CLOSE = "</diffpi-subagent-escalation>";
-function renderSubagentEscalation(value) {
-  return `${ESCALATION_OPEN}${JSON.stringify(escalationSchema.parse(value))}${ESCALATION_CLOSE}`;
+// src/plan/store.ts
+import { mkdir as mkdir3, readdir, readFile as readFile3, realpath as realpath3, rm as rm2 } from "node:fs/promises";
+import { basename as basename3, dirname as dirname4, join as join7, resolve as resolve3, sep } from "node:path";
+
+// src/extensions/fsx.ts
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+async function atomicWrite(path, content) {
+  const temp = join(dirname(path), `.${basename(path)}.${crypto.randomUUID()}.tmp`);
+  await writeFile(temp, content, { encoding: "utf8", mode: 384, flag: "wx" });
+  await rename(temp, path);
+}
+async function withDirectoryLock(lockDir, operation, options = {}) {
+  const waitMs = options.waitMs ?? 5000;
+  const pollMs = options.pollMs ?? 25;
+  const started = Date.now();
+  while (true) {
+    try {
+      await mkdir(lockDir);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST")
+        throw error;
+      if (Date.now() - started >= waitMs)
+        throw new Error(`Timed out waiting to ${options.operation ?? "acquire lock"}: ${lockDir}`);
+      await sleep(pollMs);
+    }
+  }
+  try {
+    return await operation();
+  } finally {
+    await rm(lockDir, { recursive: true, force: true });
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-// src/plan/annotations.ts
-import { spawn as spawn2 } from "node:child_process";
-import { readFile as readFile3, rename, writeFile as writeFile2 } from "node:fs/promises";
-import { basename, dirname, join as join2 } from "node:path";
-import { z as z2 } from "zod";
+// src/extensions/zodx.ts
+import { z } from "zod";
+var zx = {
+  cwd: z.string().optional(),
+  id: z.string().min(1).max(80).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+  revision: z.number().int().nonnegative(),
+  text: z.string().trim().min(1)
+};
 
 // src/log.ts
 import { randomUUID } from "node:crypto";
@@ -2418,229 +2444,167 @@ async function appendLogEntry(logPath, event) {
   return entry;
 }
 
-// src/plan/log.ts
-async function appendPlanLog(logPath, event) {
-  return appendLogEntry(logPath, event);
-}
+// src/store.ts
+import { createHash } from "node:crypto";
+import { lstat, mkdir as mkdir2, readlink, realpath as realpath2, symlink, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname as dirname2, isAbsolute as isAbsolute2, join as join3, resolve as resolve2 } from "node:path";
 
-// src/plan/lock.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
-import { mkdir, readFile as readFile2, rm, writeFile } from "node:fs/promises";
-import { hostname } from "node:os";
-import { join } from "node:path";
-async function withPlanLock(planDir, operation, options = {}) {
-  const lockDir = join(planDir, ".lock");
-  const waitMs = options.waitMs ?? 5000;
-  const pollMs = options.pollMs ?? 25;
-  const owner = {
-    token: randomUUID2(),
-    pid: process.pid,
-    hostname: hostname(),
-    operation: options.operation ?? "plan mutation",
-    acquiredAt: new Date().toISOString()
+// src/extensions/gitx.ts
+import { realpath } from "node:fs/promises";
+import { basename as basename2, isAbsolute, join as join2, resolve } from "node:path";
+async function gitToplevel(cwd) {
+  const result = await run("git", ["-C", cwd, "rev-parse", "--show-toplevel"]);
+  const top = result.stdout.trim();
+  return result.code === 0 && top ? top : resolve(cwd);
+}
+async function inspectGitRepository(cwd) {
+  const root = await gitToplevel(cwd);
+  const remoteResult = await run("git", ["-C", root, "remote", "get-url", "origin"]);
+  const remote = remoteResult.code === 0 ? remoteResult.stdout.trim() : "";
+  const commonResult = await run("git", ["-C", root, "rev-parse", "--git-common-dir"]);
+  const common = commonResult.stdout.trim();
+  const commonPath = commonResult.code === 0 && common ? resolve(isAbsolute(common) ? common : join2(root, common)) : root;
+  const commonDir = await canonicalPath(commonPath);
+  return {
+    root,
+    commonDir,
+    ...remote ? { remote } : {},
+    name: remote ? repositoryName(remote) : basename2(resolve(commonDir, "..")) || basename2(root),
+    identity: remote ? `remote:${normalizeRemote(remote)}` : `git-common-dir:${commonDir}`
   };
-  const started = Date.now();
-  while (true) {
-    try {
-      await mkdir(lockDir);
-      await writeFile(join(lockDir, "owner.json"), `${JSON.stringify(owner)}
-`, { mode: 384 });
-      break;
-    } catch (error) {
-      if (error.code !== "EEXIST")
-        throw error;
-      if (Date.now() - started >= waitMs) {
-        let existing = "unknown owner";
-        try {
-          existing = (await readFile2(join(lockDir, "owner.json"), "utf8")).trim();
-        } catch {}
-        throw new Error(`Timed out waiting for plan lock ${lockDir}; owner: ${existing}. Remove it only after confirming the owner is stale.`);
-      }
-      await new Promise((resolve) => setTimeout(resolve, pollMs));
-    }
-  }
+}
+function normalizeRemote(remote) {
+  return remote.trim().replace(/\.git\/?$/i, "").replace(/\/+$/, "").toLowerCase();
+}
+function repositoryName(remote) {
+  const normalized = remote.trim().replace(/\.git\/?$/i, "").replace(/\/+$/, "");
+  return normalized.split(/[/\\:]/).filter(Boolean).at(-1) ?? "";
+}
+async function canonicalPath(path) {
   try {
-    return await operation();
-  } finally {
-    let current;
-    try {
-      current = JSON.parse(await readFile2(join(lockDir, "owner.json"), "utf8"));
-    } catch {}
-    if (current?.token === owner.token)
-      await rm(lockDir, { recursive: true, force: true });
+    return await realpath(path);
+  } catch {
+    return resolve(path);
   }
 }
 
-// src/plan/annotations.ts
-var commentSchema = z2.object({
-  id: z2.string(),
-  content: z2.string(),
-  path: z2.string().optional(),
-  start_line: z2.number().int().optional(),
-  line: z2.number().int().optional(),
-  end_line: z2.number().int().optional()
-}).loose();
-async function annotatePlan(record, runtime = {}) {
-  const execute = runtime.execute ?? executeProcess;
-  const result = await execute("tuicr", ["--file", record.planPath], dirname(record.planPath), true);
-  const sessionSlug = [...result.stderr.matchAll(/^tuicr-session:\s*(\S+)\s*$/gm)].at(-1)?.[1];
-  if (result.code !== 0)
-    throw new Error(result.stderr.trim() || `tuicr exited with status ${result.code}.`);
-  if (!sessionSlug)
-    throw new Error("tuicr did not report a tuicr-session marker.");
-  const state = await withPlanLock(record.dir, async () => {
-    const previous = await readAnnotationState(record).catch((error) => {
-      if (error.code === "ENOENT")
-        return;
+// src/store.ts
+var STORE_LINK = ".diffpi";
+var LEGACY_STORE_LINK = join3(".pi", "diffpi");
+function storeGlobalRoot(homeDir = homedir()) {
+  return join3(homeDir, ".difflab", "diffpi", "projects");
+}
+async function ensureStore(cwd, homeDir = homedir()) {
+  const repository = await inspectGitRepository(cwd);
+  const root = repository.root;
+  const slug = projectSlug(repository);
+  const dest = join3(storeGlobalRoot(homeDir), slug);
+  const link = join3(root, STORE_LINK);
+  await mkdir2(dest, { recursive: true });
+  try {
+    await assertStoreLink(link, dest);
+  } catch (error) {
+    if (error.code !== "ENOENT")
       throw error;
-    });
-    const next = {
-      schemaVersion: 1,
-      sessionSlug,
-      updatedAt: new Date().toISOString(),
-      appliedCommentIds: previous?.appliedCommentIds ?? []
-    };
-    await atomicJson(annotationStatePath(record), next);
-    return next;
-  }, { operation: "save annotation session" });
-  return { sessionSlug, code: result.code, state };
+    await symlink(dest, link);
+  }
+  await removeLegacyStoreLink(join3(root, LEGACY_STORE_LINK), dest);
+  return { slug, root, dest, link, linked: true };
 }
-async function readPlanAnnotations(record, options = {}) {
-  const state = await readAnnotationState(record).catch((error) => {
-    if (error.code === "ENOENT")
-      return;
-    throw error;
-  });
-  if (!state)
-    return { comments: [], pending: [] };
-  const execute = options.runtime?.execute ?? executeProcess;
-  const response = await execute("tuicr", ["review", "comments", "--session", state.sessionSlug], record.dir, false);
-  if (response.code !== 0) {
-    if (/not found|no session|deleted/i.test(response.stderr))
-      return { state, comments: [], pending: [] };
-    throw new Error(response.stderr.trim() || "Cannot read tuicr comments.");
-  }
-  let raw;
+async function plansDir(cwd, homeDir = homedir()) {
+  const store = await ensureStore(cwd, homeDir);
+  const dir = join3(store.link, "plan");
+  await mkdir2(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 {
-    raw = JSON.parse(response.stdout);
-  } catch {
-    throw new Error("tuicr returned malformed comment JSON.");
+    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;
   }
-  if (!Array.isArray(raw))
-    throw new Error("tuicr comment output must be a JSON array.");
-  const lines = record.source.split(`
-`);
-  const applied = new Set(state.appliedCommentIds);
-  const comments = raw.map((value, index) => normalizeComment(value, index, lines, applied));
-  const pending = comments.filter((comment) => !comment.applied);
-  return { state, comments: options.includeApplied ? comments : pending, pending };
-}
-async function acknowledgePlanAnnotations(record, commentIds, summary) {
-  if (!summary.trim())
-    throw new Error("Annotation acknowledgement summary is required.");
-  return withPlanLock(record.dir, async () => {
-    const state = await readAnnotationState(record);
-    const next = {
-      ...state,
-      updatedAt: new Date().toISOString(),
-      appliedCommentIds: [...new Set([...state.appliedCommentIds, ...commentIds])]
-    };
-    await atomicJson(annotationStatePath(record), next);
-    await appendPlanLog(record.logPath, {
-      planRevision: record.document.revision,
-      kind: "annotation",
-      actor: "planner",
-      message: summary,
-      data: { commentIds: [...commentIds], sessionSlug: state.sessionSlug }
-    });
-    return next;
-  }, { operation: "acknowledge annotations" });
 }
-function annotationStatePath(record) {
-  return join2(record.dir, "annotations.json");
+async function symlinkTarget(path) {
+  const target = await readlink(path);
+  return canonicalPath2(isAbsolute2(target) ? target : resolve2(dirname2(path), target));
 }
-async function readAnnotationState(record) {
-  const source = await readFile3(annotationStatePath(record), "utf8");
-  let value;
+async function canonicalPath2(path) {
   try {
-    value = JSON.parse(source);
+    return await realpath2(path);
   } catch {
-    throw new Error(`Malformed annotation state: ${annotationStatePath(record)}.`);
-  }
-  if (value.schemaVersion !== 1 || typeof value.sessionSlug !== "string" || !Array.isArray(value.appliedCommentIds)) {
-    throw new Error(`Malformed annotation state: ${annotationStatePath(record)}.`);
+    return resolve2(path);
   }
-  return value;
 }
-function normalizeComment(value, index, lines, applied) {
-  const parsed = commentSchema.safeParse(value);
-  if (!parsed.success)
-    throw new Error(`Malformed tuicr comment at index ${index}.`);
-  const raw = parsed.data;
-  const line = raw.start_line ?? raw.line;
-  const endLine = raw.end_line ?? line;
-  const targetPath = raw.path;
-  const appliesToPlan = !targetPath || basename(targetPath) === basename("PLAN.md");
-  const validAnchor = appliesToPlan && line !== undefined && line > 0 && line <= lines.length;
-  return {
-    id: raw.id,
-    body: raw.content,
-    file: targetPath,
-    line,
-    endLine,
-    context: validAnchor ? lines.slice(line - 1, Math.min(endLine ?? line, lines.length)).join(`
-`) : undefined,
-    stale: line !== undefined && !validAnchor,
-    applied: applied.has(raw.id)
-  };
+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}`;
 }
-async function executeProcess(command, args, cwd, interactive) {
-  if (!interactive) {
-    const result = await run(command, args, { cwd, capture: "unbounded" });
-    return { code: result.code, stdout: result.stdout, stderr: result.stderr };
-  }
-  return new Promise((resolve, reject) => {
-    const child = spawn2(command, args, { cwd, stdio: ["inherit", "inherit", "pipe"] });
-    let stderr = "";
-    child.stderr.on("data", (chunk) => {
-      const text = chunk.toString();
-      stderr += text;
-      process.stderr.write(text);
-    });
-    child.on("error", reject);
-    child.on("close", (code) => resolve({ code: code ?? 1, stdout: "", stderr }));
-  });
+
+// src/templates.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { homedir as homedir2 } from "node:os";
+import { join as join5, normalize } from "node:path";
+
+// src/assets.ts
+import { existsSync } from "node:fs";
+import { dirname as dirname3, join as join4 } from "node:path";
+import { fileURLToPath } from "node:url";
+function resolveBundledAssetDir(name, moduleUrl = import.meta.url) {
+  const moduleDir = dirname3(fileURLToPath(moduleUrl));
+  const candidates = [join4(moduleDir, name), join4(moduleDir, "..", name), join4(moduleDir, "..", "..", name)];
+  return candidates.find((path) => existsSync(path)) ?? candidates[1];
 }
-async function atomicJson(path, value) {
-  const temp = join2(dirname(path), `.${basename(path)}.${crypto.randomUUID()}.tmp`);
-  await writeFile2(temp, `${JSON.stringify(value, null, 2)}
-`, { mode: 384, flag: "wx" });
-  await rename(temp, path);
+function resolveBundledTemplatesDir(moduleUrl = import.meta.url) {
+  return resolveBundledAssetDir("templates", moduleUrl);
 }
 
-// src/plan/execution.ts
-function createExecutionPacket(plan, coordinator) {
-  if (!plan.execution?.active)
-    throw new Error(`Plan ${plan.id} has no active execution.`);
-  return {
-    version: 1,
-    planId: plan.id,
-    executionId: plan.execution.id,
-    policy: plan.execution.policy,
-    cwd: plan.execution.cwd,
-    branch: plan.execution.branch,
-    coordinator
-  };
+// src/templates.ts
+async function loadTemplate(name, options = {}) {
+  const relative = templateRelativePath(name);
+  const userPath = join5(options.homeDir ?? homedir2(), ".difflab", "diffpi", "templates", relative);
+  const bundledPath = join5(options.bundledDir ?? resolveBundledTemplatesDir(), relative);
+  const user = await readOptionalFile(userPath);
+  if (user !== undefined)
+    return { name, path: userPath, source: "user", content: user };
+  const bundled = await readOptionalFile(bundledPath);
+  if (bundled !== undefined)
+    return { name, path: bundledPath, source: "bundled", content: bundled };
+  throw new Error(`Template "${name}" was not found at ${userPath} or ${bundledPath}.`);
+}
+function renderTemplate(content, variables) {
+  return content.replace(/\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g, (match, key) => variables[key] ?? match);
+}
+function templateRelativePath(name) {
+  const normalized = normalize(name.replaceAll("\\", "/")).replace(/^\.\//, "");
+  if (!normalized || normalized.startsWith("../") || normalized.includes("/../") || normalized.startsWith("/")) {
+    throw new Error(`Invalid template name: ${name}`);
+  }
+  return normalized.endsWith(".md") ? normalized : `${normalized}.md`;
 }
-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.",
-    "Persist every transition, progress event, issue, and deviation. Do not edit PLAN.md directly. Delegated implementation workers never commit or restructure the plan.",
-    "For commit-per-phase execution, commit after local gates, push immediately, record pending CI on the completed phase, and launch a bounded background Worker to call plan_watch_ci for the exact SHA 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(" ");
+async function readOptionalFile(path) {
+  try {
+    return await readFile2(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return;
+    throw error;
+  }
 }
 
 // src/plan/markdown.ts
@@ -3989,7 +3953,7 @@ var handle = {
 };
 
 // ../../node_modules/mdast-util-to-markdown/lib/join.js
-var join3 = [joinDefaults];
+var join6 = [joinDefaults];
 function joinDefaults(left, right, parent, state) {
   if (right.type === "code" && formatCodeAsIndented(right, state) && (left.type === "list" || left.type === right.type && formatCodeAsIndented(left, state))) {
     return false;
@@ -6535,7 +6499,7 @@ function toMarkdown(tree, options) {
     handle: undefined,
     indentLines,
     indexStack: [],
-    join: [...join3],
+    join: [...join6],
     options: {},
     safe: safeBound,
     stack: [],
@@ -6839,7 +6803,7 @@ import { default as default2 } from "node:path";
 import { default as default3 } from "node:process";
 
 // ../../node_modules/vfile/lib/minurl.js
-import { fileURLToPath } from "node:url";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // ../../node_modules/vfile/lib/minurl.shared.js
 function isUrl(fileUrlOrPath) {
@@ -6925,7 +6889,7 @@ class VFile {
   }
   set path(path) {
     if (isUrl(path)) {
-      path = fileURLToPath(path);
+      path = fileURLToPath2(path);
     }
     assertNonEmpty(path, "path");
     if (this.path !== path) {
@@ -7280,25 +7244,6 @@ function looksLikeAValue(value) {
 function isUint8Array2(value) {
   return Boolean(value && typeof value === "object" && "byteLength" in value && "byteOffset" in value);
 }
-// src/plan/ids.ts
-var STABLE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-function isStableId(value) {
-  return STABLE_ID.test(value) && value.length <= 80;
-}
-function assertStableId(value, label = "identifier") {
-  if (!isStableId(value))
-    throw new Error(`${label} must be a lowercase stable slug, not a path: ${value}`);
-}
-function assertUniqueIds(ids, label) {
-  const seen = new Set;
-  for (const id of ids) {
-    assertStableId(id, label);
-    if (seen.has(id))
-      throw new Error(`Duplicate ${label}: ${id}.`);
-    seen.add(id);
-  }
-}
-
 // src/plan/markdown.ts
 var PLAN_MARKER = /<!-- diffpi-plan: (\{[^\n]+\}) -->/;
 var PHASE_MARKER = /<!-- diffpi-phase: (\{[^\n]+\}) -->/g;
@@ -7346,8 +7291,6 @@ function validatePlanDocument(plan, options = {}) {
     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 && (options.pendingAnnotations ?? 0) > 0)
-    add("pending-annotations", "error", `${options.pendingAnnotations} annotations remain pending.`);
   return issues;
 }
 function renderPlanDocument(plan, previousSource) {
@@ -7689,6 +7632,19 @@ function parseCsv(value) {
     return [];
   return value.split(",").map((item) => item.trim()).filter(Boolean);
 }
+function assertStableId(value, label) {
+  if (!zx.id.safeParse(value).success)
+    throw new Error(`${label} must be a lowercase stable slug, not a path: ${value}`);
+}
+function assertUniqueIds(ids, label) {
+  const seen = new Set;
+  for (const id of ids) {
+    assertStableId(id, label);
+    if (seen.has(id))
+      throw new Error(`Duplicate ${label}: ${id}.`);
+    seen.add(id);
+  }
+}
 function cleanPlaceholder(value) {
   return value.replace(/<!--[^]*?-->/g, "").trim();
 }
@@ -7720,173 +7676,6 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-// src/plan/store.ts
-import { open, mkdir as mkdir3, readdir, readFile as readFile5, realpath as realpath3, rename as rename2, rm as rm2 } from "node:fs/promises";
-import { basename as basename3, dirname as dirname4, join as join8, resolve as resolve3, sep } from "node:path";
-
-// src/store.ts
-import { createHash } from "node:crypto";
-import { lstat, mkdir as mkdir2, readlink, realpath as realpath2, symlink, unlink } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname as dirname2, isAbsolute as isAbsolute2, join as join5, resolve as resolve2 } from "node:path";
-
-// src/extensions/gitx.ts
-import { realpath } from "node:fs/promises";
-import { basename as basename2, isAbsolute, join as join4, resolve } from "node:path";
-async function gitToplevel(cwd) {
-  const result = await run("git", ["-C", cwd, "rev-parse", "--show-toplevel"]);
-  const top = result.stdout.trim();
-  return result.code === 0 && top ? top : resolve(cwd);
-}
-async function inspectGitRepository(cwd) {
-  const root = await gitToplevel(cwd);
-  const remoteResult = await run("git", ["-C", root, "remote", "get-url", "origin"]);
-  const remote = remoteResult.code === 0 ? remoteResult.stdout.trim() : "";
-  const commonResult = await run("git", ["-C", root, "rev-parse", "--git-common-dir"]);
-  const common = commonResult.stdout.trim();
-  const commonPath = commonResult.code === 0 && common ? resolve(isAbsolute(common) ? common : join4(root, common)) : root;
-  const commonDir = await canonicalPath(commonPath);
-  return {
-    root,
-    commonDir,
-    ...remote ? { remote } : {},
-    name: remote ? repositoryName(remote) : basename2(resolve(commonDir, "..")) || basename2(root),
-    identity: remote ? `remote:${normalizeRemote(remote)}` : `git-common-dir:${commonDir}`
-  };
-}
-function normalizeRemote(remote) {
-  return remote.trim().replace(/\.git\/?$/i, "").replace(/\/+$/, "").toLowerCase();
-}
-function repositoryName(remote) {
-  const normalized = remote.trim().replace(/\.git\/?$/i, "").replace(/\/+$/, "");
-  return normalized.split(/[/\\:]/).filter(Boolean).at(-1) ?? "";
-}
-async function canonicalPath(path) {
-  try {
-    return await realpath(path);
-  } catch {
-    return resolve(path);
-  }
-}
-
-// src/store.ts
-var STORE_LINK = ".diffpi";
-var LEGACY_STORE_LINK = join5(".pi", "diffpi");
-function storeGlobalRoot(homeDir = homedir()) {
-  return join5(homeDir, ".difflab", "diffpi", "projects");
-}
-async function ensureStore(cwd, homeDir = homedir()) {
-  const repository = await inspectGitRepository(cwd);
-  const root = repository.root;
-  const slug = projectSlug(repository);
-  const dest = join5(storeGlobalRoot(homeDir), slug);
-  const link = join5(root, STORE_LINK);
-  await mkdir2(dest, { recursive: true });
-  try {
-    await assertStoreLink(link, dest);
-  } catch (error) {
-    if (error.code !== "ENOENT")
-      throw error;
-    await symlink(dest, link);
-  }
-  await removeLegacyStoreLink(join5(root, LEGACY_STORE_LINK), dest);
-  return { slug, root, dest, link, linked: true };
-}
-async function plansDir(cwd, homeDir = homedir()) {
-  const store = await ensureStore(cwd, homeDir);
-  const dir = join5(store.link, "plan");
-  await mkdir2(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(dirname2(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/templates.ts
-import { readFile as readFile4 } from "node:fs/promises";
-import { homedir as homedir2 } from "node:os";
-import { join as join7, normalize } from "node:path";
-
-// src/assets.ts
-import { existsSync } from "node:fs";
-import { dirname as dirname3, join as join6 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-function resolveBundledAssetDir(name, moduleUrl = import.meta.url) {
-  const moduleDir = dirname3(fileURLToPath2(moduleUrl));
-  const candidates = [join6(moduleDir, name), join6(moduleDir, "..", name), join6(moduleDir, "..", "..", name)];
-  return candidates.find((path) => existsSync(path)) ?? candidates[1];
-}
-function resolveBundledTemplatesDir(moduleUrl = import.meta.url) {
-  return resolveBundledAssetDir("templates", moduleUrl);
-}
-
-// src/templates.ts
-async function loadTemplate(name, options = {}) {
-  const relative = templateRelativePath(name);
-  const userPath = join7(options.homeDir ?? homedir2(), ".difflab", "diffpi", "templates", relative);
-  const bundledPath = join7(options.bundledDir ?? resolveBundledTemplatesDir(), relative);
-  const user = await readOptionalFile(userPath);
-  if (user !== undefined)
-    return { name, path: userPath, source: "user", content: user };
-  const bundled = await readOptionalFile(bundledPath);
-  if (bundled !== undefined)
-    return { name, path: bundledPath, source: "bundled", content: bundled };
-  throw new Error(`Template "${name}" was not found at ${userPath} or ${bundledPath}.`);
-}
-function renderTemplate(content, variables) {
-  return content.replace(/\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g, (match, key) => variables[key] ?? match);
-}
-function templateRelativePath(name) {
-  const normalized = normalize(name.replaceAll("\\", "/")).replace(/^\.\//, "");
-  if (!normalized || normalized.startsWith("../") || normalized.includes("/../") || normalized.startsWith("/")) {
-    throw new Error(`Invalid template name: ${name}`);
-  }
-  return normalized.endsWith(".md") ? normalized : `${normalized}.md`;
-}
-async function readOptionalFile(path) {
-  try {
-    return await readFile4(path, "utf8");
-  } catch (error) {
-    if (error.code === "ENOENT")
-      return;
-    throw error;
-  }
-}
-
 // src/plan/store.ts
 function planRecordName(shortSlug, date = new Date) {
   const slug = normalizeSlug(shortSlug);
@@ -7902,7 +7691,7 @@ async function resolvePlan(cwd, query, filters = {}, options = {}) {
       continue;
     if (normalizedQuery && entry.name !== normalizedQuery && stripDate(entry.name) !== normalizedQuery)
       continue;
-    const dir = join8(root, entry.name);
+    const dir = join7(root, entry.name);
     await assertContained(root, dir);
     try {
       const record = await readRecord(dir);
@@ -7928,7 +7717,7 @@ function createPlanStore(options = {}) {
     async init(input) {
       const root = await plansDir(input.cwd, options.homeDir);
       const id = planRecordName(input.shortSlug, now());
-      const dir = join8(root, id);
+      const dir = join7(root, id);
       await assertContained(root, dirname4(dir));
       try {
         await mkdir3(dir);
@@ -7948,25 +7737,19 @@ function createPlanStore(options = {}) {
           branch: input.branch,
           title: input.title?.trim() || titleFromSlug(input.shortSlug),
           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. -->",
           created_at: timestamp,
           updated_at: timestamp
         });
-        const document = parsePlanDocument(source, join8(dir, "PLAN.md"));
-        await atomicWrite(join8(dir, "PLAN.md"), source);
-        await ensureImplementationFiles(dir, document, options);
-        await atomicWrite(join8(dir, "logs.txt"), "");
-        await appendPlanLog(join8(dir, "logs.txt"), {
-          planRevision: document.revision,
-          kind: "created",
-          actor: "diffpi",
-          message: `Created plan ${id}.`
-        });
+        const document = parsePlanDocument(source, join7(dir, "PLAN.md"));
+        await atomicWrite(join7(dir, "PLAN.md"), source);
         return {
           id,
           dir,
-          planPath: join8(dir, "PLAN.md"),
-          logPath: join8(dir, "logs.txt"),
-          implementationDir: join8(dir, "implementation"),
+          planPath: join7(dir, "PLAN.md"),
+          logPath: join7(dir, "logs.txt"),
+          implementationDir: join7(dir, "implementation"),
           document,
           source
         };
@@ -7986,7 +7769,7 @@ function createPlanStore(options = {}) {
     },
     async mutate(cwd, query, operation, update) {
       const initial = await this.read(cwd, query);
-      return withPlanLock(initial.dir, async () => {
+      return withDirectoryLock(join7(initial.dir, ".lock"), async () => {
         const current = await readRecord(initial.dir);
         const next = await update(structuredClone(current.document));
         if (next.id !== current.id)
@@ -8000,41 +7783,41 @@ function createPlanStore(options = {}) {
         parsePlanDocument(source, current.planPath);
         await atomicWrite(current.planPath, source);
         await ensureImplementationFiles(current.dir, document, options);
-        return { ...current, document, source, implementationDir: join8(current.dir, "implementation") };
+        return { ...current, document, source, implementationDir: join7(current.dir, "implementation") };
       }, { operation });
     },
     async log(cwd, query, event) {
       const record = await this.read(cwd, query);
-      return withPlanLock(record.dir, () => appendPlanLog(record.logPath, event), { operation: "append log" });
+      return appendLogEntry(record.logPath, event);
     }
   };
 }
 async function readRecord(dir) {
-  const planPath = join8(dir, "PLAN.md");
-  const logPath = join8(dir, "logs.txt");
-  const source = await readFile5(planPath, "utf8");
+  const planPath = join7(dir, "PLAN.md");
+  const logPath = join7(dir, "logs.txt");
+  const source = await readFile3(planPath, "utf8");
   const document = parsePlanDocument(source, planPath);
   return {
     id: basename3(dir),
     dir,
     planPath,
     logPath,
-    implementationDir: join8(dir, "implementation"),
+    implementationDir: join7(dir, "implementation"),
     document,
     source
   };
 }
 async function ensureImplementationFiles(dir, document, options) {
-  const implementationDir = join8(dir, "implementation");
+  const implementationDir = join7(dir, "implementation");
   await mkdir3(implementationDir, { recursive: true });
   const template = await loadTemplate("plan/implementation", {
     homeDir: options.homeDir,
     bundledDir: options.bundledTemplatesDir
   });
   for (const phase of document.phases) {
-    const path = join8(implementationDir, `phase-${phase.id}.md`);
+    const path = join7(implementationDir, `phase-${phase.id}.md`);
     try {
-      await readFile5(path, "utf8");
+      await readFile3(path, "utf8");
     } catch (error) {
       if (error.code !== "ENOENT")
         throw error;
@@ -8048,25 +7831,6 @@ async function ensureImplementationFiles(dir, document, options) {
     }
   }
 }
-async function atomicWrite(path, content) {
-  const temp = join8(dirname4(path), `.${basename3(path)}.${process.pid}.${crypto.randomUUID()}.tmp`);
-  const file = await open(temp, "wx", 384);
-  try {
-    await file.writeFile(content, "utf8");
-    await file.sync();
-  } finally {
-    await file.close();
-  }
-  await rename2(temp, path);
-  try {
-    const directory = await open(dirname4(path), "r");
-    try {
-      await directory.sync();
-    } finally {
-      await directory.close();
-    }
-  } catch {}
-}
 async function assertContained(root, candidate) {
   const canonicalRoot = await realpath3(root);
   let canonicalCandidate;
@@ -8084,7 +7848,8 @@ function normalizeSlug(value) {
     throw new Error(`Invalid plan slug: ${value}.`);
   }
   const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  assertStableId(slug, "plan slug");
+  if (!zx.id.safeParse(slug).success)
+    throw new Error(`Invalid plan slug: ${value}.`);
   return slug;
 }
 function normalizeQuery(value) {
@@ -8099,369 +7864,99 @@ function stripDate(value) {
 function titleFromSlug(value) {
   return normalizeSlug(value).replace(/^(?:[a-z]+-\d+-)/, "").split("-").map((part) => part[0].toUpperCase() + part.slice(1)).join(" ");
 }
-
-// src/plan/controller.ts
-function createPlanController(options = {}) {
-  const store = createPlanStore(options);
-  const controller = {
-    context: store.context,
-    create: store.init,
-    read: store.read,
-    update: store.mutate,
-    appendLog: store.log,
-    updateStatus: (cwd, query, input) => updateStatus(store, cwd, query, input),
-    updateCi: (cwd, query, input) => updateCi(store, cwd, query, input),
-    retryCi: (cwd, query, input) => retryCi(store, cwd, query, input),
-    assertPhasePushEligible,
-    validate: validatePlanDocument,
-    countDesignWords,
-    annotate: annotatePlan,
-    annotations: readPlanAnnotations,
-    acknowledgeAnnotations: acknowledgePlanAnnotations,
-    executionPacket: createExecutionPacket,
-    executionPrompt: renderExecutionPrompt,
-    renderEscalation: renderSubagentEscalation,
-    assertStableId
-  };
-  return controller;
-}
-async function updateStatus(store, cwd, query, input) {
-  let escalation;
-  const record = await store.mutate(cwd, query, "update status", (plan) => {
-    if (input.target.type === "plan") {
-      if (plan.status !== input.expectedStatus)
-        throw new Error(`Expected plan status ${input.expectedStatus}, found ${plan.status}.`);
-      assertPlanTransition(plan.status, input.status);
-      if (input.status === "ready") {
-        const errors = validatePlanDocument(plan, { strict: true }).filter((issue) => issue.severity === "error");
-        if (errors.length)
-          throw new Error(`Plan cannot become ready: ${errors.map((issue) => issue.message).join(" ")}`);
-      }
-      if ((input.status === "blocked" || input.status === "completed") && plan.status === "in_progress")
-        assertExecutionOwner(plan, input.executionId);
-      if (input.status === "completed" && plan.phases.some((phase) => phase.status !== "completed" && phase.status !== "skipped"))
-        throw new Error("Every phase must be complete or skipped before the plan completes.");
-      if (input.status === "completed" && plan.execution?.policy === "commit-per-phase") {
-        const unsettled = plan.phases.filter((phase) => phase.status === "completed" && (!phase.commit?.pushedAt || !["passed", "skipped"].includes(phase.commit.ci?.status ?? "pending")));
-        if (unsettled.length)
-          throw new Error(`CI must settle successfully for phases: ${unsettled.map((phase) => phase.id).join(", ")}.`);
-      }
-      return {
-        ...heartbeat(plan),
-        status: input.status,
-        execution: input.status === "completed" || input.status === "blocked" ? plan.execution && { ...plan.execution, active: false, heartbeatAt: new Date().toISOString() } : plan.execution
-      };
+// src/plan/reviews.ts
+import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname5, join as join8 } from "node:path";
+async function createPlanReview(record, runtime = {}) {
+  if (await readPlanReview(record))
+    throw new Error(`Plan revision ${record.document.revision} already has a review.`);
+  const execute = runtime.execute ?? ((command, args, cwd, interactive) => run(command, args, { cwd, capture: "unbounded", interactive }));
+  const result = await execute("tuicr", ["--file", record.dir], record.dir, true);
+  const sourceId = [...result.stderr.matchAll(/^tuicr-session:\s*(\S+)\s*$/gm)].at(-1)?.[1];
+  if (result.code !== 0)
+    throw new Error(result.stderr.trim() || `tuicr exited with status ${result.code}.`);
+  if (!sourceId)
+    throw new Error("tuicr did not report a tuicr-session marker.");
+  const response = await execute("tuicr", ["review", "comments", "--session", sourceId], record.dir, false);
+  if (response.code !== 0)
+    throw new Error(response.stderr.trim() || "Cannot read the tuicr review.");
+  const review = {
+    path: reviewPath(record),
+    dump: {
+      schemaVersion: 1,
+      planId: record.id,
+      planRevision: record.document.revision,
+      source: "tuicr",
+      sourceId,
+      planSource: record.source,
+      content: response.stdout
     }
-    if (!input.target.id)
-      throw new Error("Target ID is required.");
-    const phase = input.target.type === "phase" ? getPhase(plan, input.target.id) : findTaskPhase(plan, input.target.id);
-    if (input.target.type === "phase") {
-      if (phase.status !== input.expectedStatus)
-        throw new Error(`Expected phase status ${input.expectedStatus}, found ${phase.status}.`);
-      if (phase.status === "completed")
-        throw new Error(`Completed phase ${phase.id} cannot transition again.`);
-      assertExecutionOwner(plan, input.executionId);
-      assertPhaseTransition(phase.status, input.status);
-      if (input.status === "in_progress" || input.status === "completed")
-        assertPhaseDependenciesSatisfied(plan, phase);
-      if (input.status === "completed") {
-        if (phase.tasks.some((task) => task.status !== "completed" && task.status !== "skipped"))
-          throw new Error("All phase tasks must be complete or skipped.");
-        if (phase.gate.status !== "passed")
-          throw new Error("Phase gates must pass before completion.");
-        if (plan.execution?.policy === "commit-per-phase")
-          assertPhasePushEligible(plan, phase.id, input.executionId);
-        if (plan.execution?.policy === "commit-per-phase" && !input.commit)
-          throw new Error("Commit-per-phase execution requires commit metadata before phase completion.");
-        if (plan.execution?.policy === "commit-per-phase" && (!input.commit?.pushedAt || input.commit.ci?.status !== "pending"))
-          throw new Error("Commit-per-phase execution requires a pushed commit with pending CI monitoring.");
-        if (plan.execution?.policy === "no-commit" && input.commit)
-          throw new Error("No-commit execution cannot record a phase commit.");
-      }
-      const updated = {
-        ...phase,
-        status: input.status,
-        revision: phase.revision + 1,
-        commit: input.commit ?? phase.commit,
-        blocker: input.blockedReason ? blocker(input) : phase.blocker
-      };
-      if (input.status === "blocked" && input.blockedReason)
-        escalation = escalationFor(plan, updated.id, undefined, input);
-      const phases = plan.phases.map((item) => {
-        if (item.id === updated.id)
-          return updated;
-        if (input.status === "completed" && plan.execution?.policy === "commit-per-phase" && input.commit && item.status !== "completed" && item.status !== "skipped" && item.gate.status === "passed")
-          return { ...item, gate: { ...item.gate, status: "stale" } };
-        return item;
-      });
-      return { ...heartbeat(plan), phases };
-    }
-    const task = getTask(phase, input.target.id);
-    if (task.status !== input.expectedStatus)
-      throw new Error(`Expected task status ${input.expectedStatus}, found ${task.status}.`);
-    assertExecutionOwner(plan, input.executionId);
-    assertTaskTransition(task, input.status, input.executionId, input.actor);
-    if (input.status === "in_progress" || input.status === "completed") {
-      if (phase.status !== "in_progress")
-        throw new Error(`Phase ${phase.id} is not in progress.`);
-      assertTaskDependenciesSatisfied(plan, task);
-    }
-    const updatedTask = {
-      ...task,
-      status: input.status,
-      revision: task.revision + 1,
-      owner: input.status === "in_progress" ? input.actor : task.owner,
-      executionId: input.status === "in_progress" ? input.executionId : task.executionId,
-      blocker: input.blockedReason ? blocker(input) : task.blocker
-    };
-    if (input.status === "blocked" && input.blockedReason)
-      escalation = escalationFor(plan, phase.id, task.id, input);
-    const updatedPhase = {
-      ...phase,
-      revision: phase.revision + 1,
-      tasks: phase.tasks.map((item) => item.id === updatedTask.id ? updatedTask : item)
-    };
-    return {
-      ...heartbeat(plan),
-      phases: plan.phases.map((item) => item.id === updatedPhase.id ? updatedPhase : item)
-    };
-  });
-  await store.log(cwd, record.id, {
-    planRevision: record.document.revision,
-    kind: input.status === "blocked" ? "blocker" : "status",
-    actor: input.actor,
-    message: input.message,
-    executionId: input.executionId,
-    phaseId: input.target.type === "phase" ? input.target.id : escalation?.correlation.parentUnitId ?? escalation?.correlation.unitId,
-    taskId: input.target.type === "task" ? input.target.id : undefined,
-    evidence: input.evidence
-  });
-  return { record, escalation };
-}
-async function updateCi(store, cwd, query, input) {
-  const record = await store.mutate(cwd, query, "update CI status", (plan) => {
-    assertExecutionOwner(plan, input.executionId);
-    if (plan.execution?.policy !== "commit-per-phase")
-      throw new Error("CI status applies only to commit-per-phase execution.");
-    const phase = getPhase(plan, input.phaseId);
-    if (phase.status !== "completed")
-      throw new Error(`Phase ${phase.id} must be completed before CI can settle.`);
-    if (!phase.commit || phase.commit.sha !== input.sha)
-      throw new Error(`Phase ${phase.id} is not committed at ${input.sha}.`);
-    const current = phase.commit.ci?.status;
-    if (current !== "pending")
-      throw new Error(`CI for phase ${phase.id} is already ${current ?? "untracked"}.`);
-    const timestamp = new Date().toISOString();
-    const updated = {
-      ...phase,
-      revision: phase.revision + 1,
-      commit: {
-        ...phase.commit,
-        ci: {
-          ...phase.commit.ci,
-          status: input.status,
-          startedAt: phase.commit.ci?.startedAt ?? timestamp,
-          completedAt: timestamp,
-          detail: input.detail
-        }
-      }
-    };
-    return {
-      ...heartbeat(plan),
-      phases: plan.phases.map((item) => item.id === updated.id ? updated : item)
-    };
-  });
-  await store.log(cwd, record.id, {
-    planRevision: record.document.revision,
-    kind: "gate",
-    actor: input.actor,
-    message: `CI ${input.status} for ${input.phaseId}: ${input.detail}`,
-    executionId: input.executionId,
-    phaseId: input.phaseId,
-    evidence: [input.sha]
-  });
-  return record;
-}
-async function retryCi(store, cwd, query, input) {
-  let previousDetail;
-  const record = await store.mutate(cwd, query, "retry CI", (plan) => {
-    assertExecutionOwner(plan, input.executionId);
-    if (plan.execution?.policy !== "commit-per-phase")
-      throw new Error("CI retry applies only to commit-per-phase execution.");
-    const phase = getPhase(plan, input.phaseId);
-    if (phase.status !== "completed")
-      throw new Error(`Phase ${phase.id} must be completed before CI can retry.`);
-    if (!phase.commit || phase.commit.sha !== input.sha)
-      throw new Error(`Phase ${phase.id} is not committed at ${input.sha}.`);
-    if (phase.commit.ci?.status !== "failed")
-      throw new Error(`CI for phase ${phase.id} cannot retry from ${phase.commit.ci?.status ?? "untracked"}.`);
-    previousDetail = phase.commit.ci.detail;
-    const updated = {
-      ...phase,
-      revision: phase.revision + 1,
-      commit: {
-        ...phase.commit,
-        ci: { status: "pending", startedAt: new Date().toISOString() }
-      }
-    };
-    return {
-      ...heartbeat(plan),
-      phases: plan.phases.map((item) => item.id === updated.id ? updated : item)
-    };
-  });
-  await store.log(cwd, record.id, {
-    planRevision: record.document.revision,
-    kind: "gate",
-    actor: input.actor,
-    message: `Retrying CI for ${input.phaseId}: ${input.reason}`,
-    executionId: input.executionId,
-    phaseId: input.phaseId,
-    evidence: [input.sha],
-    data: { previousStatus: "failed", previousDetail }
-  });
-  return record;
-}
-function assertPhasePushEligible(plan, phaseId, executionId) {
-  assertExecutionOwner(plan, executionId);
-  if (plan.execution?.policy !== "commit-per-phase")
-    return;
-  const phaseIndex = plan.phases.findIndex((phase) => phase.id === phaseId);
-  if (phaseIndex < 0)
-    throw new Error(`Unknown phase: ${phaseId}.`);
-  const unsettled = plan.phases.slice(0, phaseIndex).filter((phase) => {
-    if (phase.status === "skipped")
-      return false;
-    return phase.status !== "completed" || !phase.commit?.pushedAt || !["passed", "skipped"].includes(phase.commit.ci?.status ?? "pending");
-  });
-  if (unsettled.length)
-    throw new Error(`Prior phase CI must settle successfully before another push: ${unsettled.map((phase) => phase.id).join(", ")}.`);
-}
-function assertPhaseDependenciesSatisfied(plan, phase) {
-  const unsettled = phase.dependencies.map((id) => getPhase(plan, id)).filter((dependency) => !dependencySatisfied(dependency.status));
-  if (unsettled.length)
-    throw new Error(`Phase ${phase.id} has incomplete dependencies: ${unsettled.map((dependency) => `${dependency.id} (${dependency.status})`).join(", ")}.`);
-}
-function assertTaskDependenciesSatisfied(plan, task) {
-  const tasks = plan.phases.flatMap((phase) => phase.tasks);
-  const unsettled = task.dependencies.map((id) => {
-    const dependency = tasks.find((candidate) => candidate.id === id);
-    if (!dependency)
-      throw new Error(`Unknown task dependency: ${id}.`);
-    return dependency;
-  }).filter((dependency) => !dependencySatisfied(dependency.status));
-  if (unsettled.length)
-    throw new Error(`Task ${task.id} has incomplete dependencies: ${unsettled.map((dependency) => `${dependency.id} (${dependency.status})`).join(", ")}.`);
-}
-function dependencySatisfied(status) {
-  return status === "completed" || status === "skipped";
-}
-var PLAN_TRANSITIONS = {
-  draft: ["ready"],
-  ready: ["draft", "in_progress"],
-  in_progress: ["blocked", "completed"],
-  blocked: ["draft", "ready", "in_progress"],
-  completed: []
-};
-var WORK_TRANSITIONS = {
-  pending: ["in_progress", "skipped"],
-  in_progress: ["blocked", "completed"],
-  blocked: ["pending", "in_progress", "skipped"],
-  completed: [],
-  skipped: []
-};
-function assertPlanTransition(from, to) {
-  if (from !== to && !PLAN_TRANSITIONS[from].includes(to))
-    throw new Error(`Invalid plan status transition: ${from} -> ${to}.`);
-}
-function assertPhaseTransition(from, to) {
-  if (from !== to && !WORK_TRANSITIONS[from].includes(to))
-    throw new Error(`Invalid phase status transition: ${from} -> ${to}.`);
-}
-function assertTaskTransition(task, to, executionId, actor) {
-  if (task.status !== to && !WORK_TRANSITIONS[task.status].includes(to))
-    throw new Error(`Invalid task status transition: ${task.status} -> ${to}.`);
-  if (task.status === "in_progress" && task.executionId && executionId !== task.executionId)
-    throw new Error(`Task ${task.id} is owned by execution ${task.executionId}.`);
-  if (task.status === "in_progress" && task.owner && actor && actor !== task.owner)
-    throw new Error(`Task ${task.id} is owned by ${task.owner}.`);
-}
-function getPhase(plan, phaseId) {
-  const phase = plan.phases.find((item) => item.id === phaseId);
-  if (!phase)
-    throw new Error(`Unknown phase: ${phaseId}.`);
-  return phase;
-}
-function findTaskPhase(plan, taskId) {
-  const phase = plan.phases.find((item) => item.tasks.some((task) => task.id === taskId));
-  if (!phase)
-    throw new Error(`Unknown task: ${taskId}.`);
-  return phase;
-}
-function getTask(phase, taskId) {
-  const task = phase.tasks.find((item) => item.id === taskId);
-  if (!task)
-    throw new Error(`Unknown task: ${taskId}.`);
-  return task;
-}
-function assertExecutionOwner(plan, executionId) {
-  if (!plan.execution?.active || !executionId || plan.execution.id !== executionId)
-    throw new Error(`Execution ${executionId ?? "(missing)"} does not own this plan.`);
-}
-function blocker(input) {
-  return {
-    reason: input.blockedReason,
-    attempts: input.attempts,
-    evidence: input.evidence,
-    needsUserDecision: input.needsUserDecision
   };
+  await writeReview(review);
+  return { code: result.code, review };
 }
-function escalationFor(plan, phaseId, taskId, input) {
-  return {
-    correlation: {
-      workflow: "plan",
-      executionId: input.executionId,
-      unitId: taskId ?? phaseId,
-      parentUnitId: taskId ? phaseId : undefined,
-      metadata: { planId: plan.id }
-    },
-    blocker: input.blockedReason,
-    attempts: input.attempts ?? [],
-    evidence: input.evidence ?? [],
-    needsUserDecision: input.needsUserDecision ?? false
-  };
+async function readPlanReview(record) {
+  const path = reviewPath(record);
+  let source;
+  try {
+    source = await readFile4(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return;
+    throw error;
+  }
+  let dump;
+  try {
+    dump = JSON.parse(source);
+  } catch {
+    throw new Error(`Malformed plan review: ${path}.`);
+  }
+  if (!isPlanReviewDump(dump))
+    throw new Error(`Malformed plan review: ${path}.`);
+  return { path, dump };
+}
+function reviewPath(record) {
+  return join8(record.dir, "reviews", `${record.document.revision}.json`);
+}
+async function writeReview(review) {
+  await mkdir4(dirname5(review.path), { recursive: true });
+  await writeFile2(review.path, `${JSON.stringify(review.dump, null, 2)}
+`, {
+    encoding: "utf8",
+    mode: 384,
+    flag: "wx"
+  });
 }
-function heartbeat(plan) {
-  return plan.execution?.active ? { ...plan, execution: { ...plan.execution, heartbeatAt: new Date().toISOString() } } : plan;
+function isPlanReviewDump(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const review = value;
+  return review.schemaVersion === 1 && typeof review.planId === "string" && Number.isInteger(review.planRevision) && review.source === "tuicr" && typeof review.sourceId === "string" && typeof review.planSource === "string" && typeof review.content === "string";
 }
+
 // src/cli/plan.ts
-var plans = createPlanController();
-function createPlanCliCommand(io = process, controller = plans) {
-  const program = new Command2().name("plan").description("Plan annotation commands").showHelpAfterError().exitOverride().configureOutput({
+var plans = createPlanStore();
+var runtime = { context: plans.context, createPlanReview };
+function createPlanCliCommand(io = process, planRuntime = runtime) {
+  const program = new Command2().name("plan").description("Plan review commands").showHelpAfterError().exitOverride().configureOutput({
     writeOut: (message) => io.stdout.write(message),
     writeErr: (message) => io.stderr.write(message)
   });
-  addAnnotationCommand(program, "annotate", io, controller);
-  addAnnotationCommand(program, "annotations", io, controller);
+  addReviewCommand(program, io, planRuntime);
   return program;
 }
-function addAnnotationCommand(program, verb, io, controller) {
-  program.command(`${verb} [plan]`).description(verb === "annotate" ? "Open a plan in tuicr for annotation" : "Print plan annotations as JSON").option("--cwd <path>", "Repository working directory", process.cwd()).action(async (query, options) => {
+function addReviewCommand(program, io, planRuntime) {
+  program.command("annotate [plan]").description("Review a plan in tuicr and save the immutable plan review").option("--cwd <path>", "Repository working directory", process.cwd()).action(async (query, options) => {
     const cwd = resolve4(options.cwd);
-    const record = await resolveCliPlan(cwd, query, controller);
-    if (verb === "annotate") {
-      const result = await controller.annotate(record);
-      io.stdout.write(`Annotated ${record.id} in tuicr session ${result.sessionSlug}.
-`);
-      return;
-    }
-    const annotations = await controller.annotations(record, { includeApplied: true });
-    io.stdout.write(`${JSON.stringify(annotations, null, 2)}
+    const record = await resolveCliPlan(cwd, query, planRuntime);
+    const result = await planRuntime.createPlanReview(record);
+    io.stdout.write(`Saved review for ${record.id} to ${result.review.path}.
 `);
   });
 }
-async function resolveCliPlan(cwd, query, controller) {
+async function resolveCliPlan(cwd, query, planRuntime) {
   const branch = query ? undefined : (await runChecked("git", ["-C", cwd, "branch", "--show-current"])).stdout.trim();
-  const resolution = await controller.context(cwd, query, query ? {} : { branch, statuses: ["draft", "ready", "in_progress", "blocked"] });
+  const resolution = await planRuntime.context(cwd, query, query ? {} : { branch, statuses: ["draft", "ready", "in_progress", "blocked"] });
   if (resolution.record)
     return resolution.record;
   if (resolution.ambiguous)