@difflab/pi 0.4.0-rc.202609231122.7b4400b → 0.4.0

package/dist/cli.js

@@ -2331,11 +2331,7 @@ function run(command, args, options = {}) {
     const child = spawn(command, args, {
       cwd: options.cwd,
       env: options.env ?? process.env,
-      stdio: [
-        options.interactive ? "inherit" : options.input === undefined ? "ignore" : "pipe",
-        options.interactive ? "inherit" : "pipe",
-        "pipe"
-      ],
+      stdio: [options.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
       signal: options.signal
     });
     let stdout = "";
@@ -2352,8 +2348,6 @@ 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
@@ -2382,52 +2376,32 @@ function appendBounded(current, next) {
   return combined.length <= MAX_CAPTURED_OUTPUT_LENGTH ? combined : combined.slice(-MAX_CAPTURED_OUTPUT_LENGTH);
 }
 
-// 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/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/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/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/log.ts
 import { randomUUID } from "node:crypto";
@@ -2444,167 +2418,229 @@ async function appendLogEntry(logPath, event) {
   return entry;
 }
 
-// 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/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);
+// src/plan/log.ts
+async function appendPlanLog(logPath, event) {
+  return appendLogEntry(logPath, event);
 }
-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}`
+
+// 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()
   };
-}
-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) {
+  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));
+    }
+  }
   try {
-    return await realpath(path);
-  } catch {
-    return resolve(path);
+    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 });
   }
 }
 
-// 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")
+// 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;
       throw error;
-    await symlink(dest, link);
-  }
-  await removeLegacyStoreLink(join3(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 = 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}.`);
+    });
+    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 };
 }
-async function removeLegacyStoreLink(path, dest) {
-  try {
-    const entry = await lstat(path);
-    if (!entry.isSymbolicLink())
+async function readPlanAnnotations(record, options = {}) {
+  const state = await readAnnotationState(record).catch((error) => {
+    if (error.code === "ENOENT")
       return;
-    const target = await symlinkTarget(path);
-    if (target === await canonicalPath2(dest))
-      await unlink(path);
-  } catch (error) {
-    if (error.code !== "ENOENT")
-      throw error;
+    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;
+  try {
+    raw = JSON.parse(response.stdout);
+  } catch {
+    throw new Error("tuicr returned malformed comment JSON.");
   }
+  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" });
 }
-async function symlinkTarget(path) {
-  const target = await readlink(path);
-  return canonicalPath2(isAbsolute2(target) ? target : resolve2(dirname2(path), target));
+function annotationStatePath(record) {
+  return join2(record.dir, "annotations.json");
 }
-async function canonicalPath2(path) {
+async function readAnnotationState(record) {
+  const source = await readFile3(annotationStatePath(record), "utf8");
+  let value;
   try {
-    return await realpath2(path);
+    value = JSON.parse(source);
   } catch {
-    return resolve2(path);
+    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 value;
 }
-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}`;
+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)
+  };
 }
-
-// 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 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 }));
+  });
 }
-function resolveBundledTemplatesDir(moduleUrl = import.meta.url) {
-  return resolveBundledAssetDir("templates", moduleUrl);
+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);
 }
 
-// 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`;
+// 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
+  };
 }
-async function readOptionalFile(path) {
-  try {
-    return await readFile2(path, "utf8");
-  } catch (error) {
-    if (error.code === "ENOENT")
-      return;
-    throw error;
-  }
+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(" ");
 }
 
 // src/plan/markdown.ts
@@ -3953,7 +3989,7 @@ var handle = {
 };
 
 // ../../node_modules/mdast-util-to-markdown/lib/join.js
-var join6 = [joinDefaults];
+var join3 = [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;
@@ -6499,7 +6535,7 @@ function toMarkdown(tree, options) {
     handle: undefined,
     indentLines,
     indexStack: [],
-    join: [...join6],
+    join: [...join3],
     options: {},
     safe: safeBound,
     stack: [],
@@ -6803,7 +6839,7 @@ import { default as default2 } from "node:path";
 import { default as default3 } from "node:process";
 
 // ../../node_modules/vfile/lib/minurl.js
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { fileURLToPath } from "node:url";
 
 // ../../node_modules/vfile/lib/minurl.shared.js
 function isUrl(fileUrlOrPath) {
@@ -6889,7 +6925,7 @@ class VFile {
   }
   set path(path) {
     if (isUrl(path)) {
-      path = fileURLToPath2(path);
+      path = fileURLToPath(path);
     }
     assertNonEmpty(path, "path");
     if (this.path !== path) {
@@ -7244,6 +7280,25 @@ 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;
@@ -7291,6 +7346,8 @@ 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) {
@@ -7632,19 +7689,6 @@ 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();
 }
@@ -7676,6 +7720,173 @@ 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);
@@ -7691,7 +7902,7 @@ async function resolvePlan(cwd, query, filters = {}, options = {}) {
       continue;
     if (normalizedQuery && entry.name !== normalizedQuery && stripDate(entry.name) !== normalizedQuery)
       continue;
-    const dir = join7(root, entry.name);
+    const dir = join8(root, entry.name);
     await assertContained(root, dir);
     try {
       const record = await readRecord(dir);
@@ -7717,7 +7928,7 @@ function createPlanStore(options = {}) {
     async init(input) {
       const root = await plansDir(input.cwd, options.homeDir);
       const id = planRecordName(input.shortSlug, now());
-      const dir = join7(root, id);
+      const dir = join8(root, id);
       await assertContained(root, dirname4(dir));
       try {
         await mkdir3(dir);
@@ -7737,19 +7948,25 @@ 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, join7(dir, "PLAN.md"));
-        await atomicWrite(join7(dir, "PLAN.md"), source);
+        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}.`
+        });
         return {
           id,
           dir,
-          planPath: join7(dir, "PLAN.md"),
-          logPath: join7(dir, "logs.txt"),
-          implementationDir: join7(dir, "implementation"),
+          planPath: join8(dir, "PLAN.md"),
+          logPath: join8(dir, "logs.txt"),
+          implementationDir: join8(dir, "implementation"),
           document,
           source
         };
@@ -7769,7 +7986,7 @@ function createPlanStore(options = {}) {
     },
     async mutate(cwd, query, operation, update) {
       const initial = await this.read(cwd, query);
-      return withDirectoryLock(join7(initial.dir, ".lock"), async () => {
+      return withPlanLock(initial.dir, async () => {
         const current = await readRecord(initial.dir);
         const next = await update(structuredClone(current.document));
         if (next.id !== current.id)
@@ -7783,41 +8000,41 @@ function createPlanStore(options = {}) {
         parsePlanDocument(source, current.planPath);
         await atomicWrite(current.planPath, source);
         await ensureImplementationFiles(current.dir, document, options);
-        return { ...current, document, source, implementationDir: join7(current.dir, "implementation") };
+        return { ...current, document, source, implementationDir: join8(current.dir, "implementation") };
       }, { operation });
     },
     async log(cwd, query, event) {
       const record = await this.read(cwd, query);
-      return appendLogEntry(record.logPath, event);
+      return withPlanLock(record.dir, () => appendPlanLog(record.logPath, event), { operation: "append log" });
     }
   };
 }
 async function readRecord(dir) {
-  const planPath = join7(dir, "PLAN.md");
-  const logPath = join7(dir, "logs.txt");
-  const source = await readFile3(planPath, "utf8");
+  const planPath = join8(dir, "PLAN.md");
+  const logPath = join8(dir, "logs.txt");
+  const source = await readFile5(planPath, "utf8");
   const document = parsePlanDocument(source, planPath);
   return {
     id: basename3(dir),
     dir,
     planPath,
     logPath,
-    implementationDir: join7(dir, "implementation"),
+    implementationDir: join8(dir, "implementation"),
     document,
     source
   };
 }
 async function ensureImplementationFiles(dir, document, options) {
-  const implementationDir = join7(dir, "implementation");
+  const implementationDir = join8(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 = join7(implementationDir, `phase-${phase.id}.md`);
+    const path = join8(implementationDir, `phase-${phase.id}.md`);
     try {
-      await readFile3(path, "utf8");
+      await readFile5(path, "utf8");
     } catch (error) {
       if (error.code !== "ENOENT")
         throw error;
@@ -7831,6 +8048,25 @@ 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;
@@ -7848,8 +8084,7 @@ function normalizeSlug(value) {
     throw new Error(`Invalid plan slug: ${value}.`);
   }
   const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  if (!zx.id.safeParse(slug).success)
-    throw new Error(`Invalid plan slug: ${value}.`);
+  assertStableId(slug, "plan slug");
   return slug;
 }
 function normalizeQuery(value) {
@@ -7864,99 +8099,369 @@ 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/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
-    }
+
+// 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
   };
-  await writeReview(review);
-  return { code: result.code, review };
+  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
+      };
+    }
+    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;
 }
-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 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
+  };
 }
-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";
+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
+  };
+}
+function heartbeat(plan) {
+  return plan.execution?.active ? { ...plan, execution: { ...plan.execution, heartbeatAt: new Date().toISOString() } } : plan;
 }
-
 // src/cli/plan.ts
-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({
+var plans = createPlanController();
+function createPlanCliCommand(io = process, controller = plans) {
+  const program = new Command2().name("plan").description("Plan annotation commands").showHelpAfterError().exitOverride().configureOutput({
     writeOut: (message) => io.stdout.write(message),
     writeErr: (message) => io.stderr.write(message)
   });
-  addReviewCommand(program, io, planRuntime);
+  addAnnotationCommand(program, "annotate", io, controller);
+  addAnnotationCommand(program, "annotations", io, controller);
   return program;
 }
-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) => {
+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) => {
     const cwd = resolve4(options.cwd);
-    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}.
+    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)}
 `);
   });
 }
-async function resolveCliPlan(cwd, query, planRuntime) {
+async function resolveCliPlan(cwd, query, controller) {
   const branch = query ? undefined : (await runChecked("git", ["-C", cwd, "branch", "--show-current"])).stdout.trim();
-  const resolution = await planRuntime.context(cwd, query, query ? {} : { branch, statuses: ["draft", "ready", "in_progress", "blocked"] });
+  const resolution = await controller.context(cwd, query, query ? {} : { branch, statuses: ["draft", "ready", "in_progress", "blocked"] });
   if (resolution.record)
     return resolution.record;
   if (resolution.ambiguous)