@difflab/pi 0.6.0 → 0.7.0-rc.202609271854.6af8600

package/dist/cli.js

@@ -2383,8 +2383,9 @@ function appendBounded(current, next) {
 }
 
 // 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";
+import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
+import { mkdir as mkdir3, readdir, readFile as readFile2, realpath as realpath3, rename as rename2, rm as rm2 } from "node:fs/promises";
+import { basename as basename3, dirname as dirname3, join as join5, resolve as resolve3, sep } from "node:path";
 
 // src/extensions/fsx.ts
 import { mkdir, rename, rm, writeFile } from "node:fs/promises";
@@ -2556,57 +2557,6 @@ function projectSlug(repository) {
   return `${readable}-${digest}`;
 }
 
-// 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];
-}
-function resolveBundledTemplatesDir(moduleUrl = import.meta.url) {
-  return resolveBundledAssetDir("templates", moduleUrl);
-}
-
-// 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`;
-}
-async function readOptionalFile(path) {
-  try {
-    return await readFile2(path, "utf8");
-  } catch (error) {
-    if (error.code === "ENOENT")
-      return;
-    throw error;
-  }
-}
-
 // src/plan/markdown.ts
 var import_mdast_builder = __toESM(require_src(), 1);
 
@@ -3953,7 +3903,7 @@ var handle = {
 };
 
 // ../../node_modules/mdast-util-to-markdown/lib/join.js
-var join6 = [joinDefaults];
+var join4 = [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 +6449,7 @@ function toMarkdown(tree, options) {
     handle: undefined,
     indentLines,
     indexStack: [],
-    join: [...join6],
+    join: [...join4],
     options: {},
     safe: safeBound,
     stack: [],
@@ -6803,7 +6753,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 +6839,7 @@ class VFile {
   }
   set path(path) {
     if (isUrl(path)) {
-      path = fileURLToPath2(path);
+      path = fileURLToPath(path);
     }
     assertNonEmpty(path, "path");
     if (this.path !== path) {
@@ -7276,11 +7226,13 @@ function validatePlanDocument(plan, options = {}) {
         if (!taskIds.has(dependency))
           add("dangling-dependency", "error", `Task ${task.id} depends on missing ${dependency}.`);
       }
-      if (options.strict && task.acceptanceCriteria.length === 0)
-        add("acceptance", "error", `Task ${task.id} has no acceptance criteria.`, task.id);
+      if (options.strict && isPlaceholder(task.title))
+        add("placeholder", "error", `Task ${task.id} has placeholder content.`, task.id);
     }
     if (options.strict && phase.tasks.length === 0)
       add("empty-phase", "error", `Phase ${phase.id} has no tasks.`, phase.id);
+    if (options.strict && (isPlaceholder(phase.title) || isPlaceholder(phase.objective)))
+      add("placeholder", "error", `Phase ${phase.id} has placeholder content.`, phase.id);
   }
   for (const cycle of dependencyCycles(plan))
     add("dependency-cycle", "error", `Dependency cycle: ${cycle.join(" -> ")}.`);
@@ -7289,10 +7241,131 @@ function validatePlanDocument(plan, options = {}) {
     add("design-length", "warning", `Design is ${designWords} words; prefer 300 or fewer.`);
   if (options.strict && designWords > 800)
     add("design-too-long", "error", `Design is ${designWords} words; finalization allows at most 800.`);
-  if (options.strict && plan.phases.length === 0)
-    add("no-phases", "error", "Finalization requires at least one phase.");
+  if (options.strict) {
+    if (plan.phases.length === 0)
+      add("no-phases", "error", "Finalization requires at least one phase.");
+    if (isPlaceholder(plan.intent))
+      add("placeholder", "error", "Intent must contain concrete content.", "intent");
+    if (!plan.requirements.length || plan.requirements.some(isPlaceholder))
+      add("requirements", "error", "Requirements must contain concrete content.", "requirements");
+    for (const [key, value] of Object.entries(plan.design)) {
+      if (isPlaceholder(value))
+        add("design", "error", `Design/${key} must contain concrete content.`, `design.${key}`);
+    }
+  }
   return issues;
 }
+function validatePlanBriefs(plan, briefs) {
+  const issues = [];
+  const phaseIds = plan.phases.map((phase) => phase.id);
+  const briefIds = briefs.map((brief) => brief.phaseId);
+  if (!sameIds(phaseIds, briefIds))
+    issues.push({
+      code: "brief-phase-ids",
+      severity: "error",
+      message: `Brief phase IDs must exactly match plan phases in order: ${phaseIds.join(", ")}.`
+    });
+  for (const [index, phase] of plan.phases.entries()) {
+    const brief = briefs[index];
+    if (!brief || brief.phaseId !== phase.id)
+      continue;
+    if (isPlaceholder(brief.summary))
+      issues.push({ code: "brief-placeholder", severity: "error", message: `Brief ${phase.id} needs a summary.` });
+    const taskIds = phase.tasks.map((task) => task.id);
+    const briefTaskIds = brief.tasks.map((task) => task.taskId);
+    if (!sameIds(taskIds, briefTaskIds))
+      issues.push({
+        code: "brief-task-ids",
+        severity: "error",
+        message: `Brief ${phase.id} task IDs must exactly match phase tasks in order: ${taskIds.join(", ")}.`
+      });
+    for (const task of brief.tasks) {
+      for (const [field, values] of [
+        ["ordered steps", task.steps],
+        ["file scopes", task.fileScopes],
+        ["acceptance criteria", task.acceptanceCriteria]
+      ]) {
+        if (!values.length || values.some(isPlaceholder))
+          issues.push({
+            code: "brief-incomplete",
+            severity: "error",
+            message: `Brief task ${task.taskId} needs concrete ${field}.`,
+            path: task.taskId
+          });
+      }
+    }
+    for (const [field, values] of [
+      ["API changes", brief.apiChanges],
+      ["libraries", brief.libraries],
+      ["constraints", brief.constraints]
+    ]) {
+      if (values.some(isPlaceholder))
+        issues.push({
+          code: "brief-placeholder",
+          severity: "error",
+          message: `Brief ${phase.id} has placeholder ${field}.`,
+          path: phase.id
+        });
+    }
+  }
+  return issues;
+}
+function renderImplementationBrief(planRevision, ordinal, phase, brief) {
+  const marker = { schemaVersion: 1, planRevision, ordinal, phaseId: phase.id };
+  const tasks = phase.tasks.map((task, index) => {
+    const details = brief.tasks[index];
+    if (!details || details.taskId !== task.id)
+      throw new Error(`Missing implementation details for ${task.id}.`);
+    return `<!-- diffpi-brief-task: ${json({ id: task.id })} -->
+### Task: ${task.title}
+
+#### Ordered Steps
+
+${bulletList(details.steps)}
+
+#### File Scopes
+
+${bulletList(details.fileScopes)}
+
+#### Acceptance Criteria
+
+${bulletList(details.acceptanceCriteria)}
+
+<!-- /diffpi-brief-task -->`;
+  }).join(`
+
+`);
+  return `<!-- diffpi-implementation: ${json(marker)} -->
+# Phase ${ordinal}: ${phase.title}
+
+- **Phase ID:** ${phase.id}
+- **Plan Revision:** ${planRevision}
+
+## Summary
+
+${brief.summary}
+
+## Objective
+
+${phase.objective}
+
+## Tasks
+
+${tasks}
+
+## API Changes
+
+${bulletList(brief.apiChanges, "None.")}
+
+## Libraries and Algorithms
+
+${bulletList(brief.libraries, "None.")}
+
+## Implementation Constraints
+
+${bulletList(brief.constraints, "None.")}
+`;
+}
 function renderPlanDocument(plan, previousSource) {
   if (previousSource && canPatch(previousSource, plan))
     return patchMarkers(previousSource, plan);
@@ -7301,6 +7374,8 @@ function renderPlanDocument(plan, previousSource) {
     id: plan.id,
     revision: plan.revision,
     branch: plan.branch,
+    issueId: plan.issueId,
+    issueUrl: plan.issueUrl,
     status: plan.status,
     execution: plan.execution,
     createdAt: plan.createdAt,
@@ -7309,6 +7384,8 @@ function renderPlanDocument(plan, previousSource) {
   const metadata = import_mdast_builder.list("unordered", [
     ["Plan ID", plan.id],
     ["Branch", plan.branch],
+    ...plan.issueId ? [["Issue", plan.issueId]] : [],
+    ...plan.issueUrl ? [["Issue URL", plan.issueUrl]] : [],
     ["Status", plan.status],
     ["Revision", String(plan.revision)]
   ].map(([label, value]) => import_mdast_builder.listItem(import_mdast_builder.paragraph([import_mdast_builder.strong(import_mdast_builder.text(`${label}:`)), import_mdast_builder.text(` ${value}`)]))));
@@ -7330,7 +7407,7 @@ function renderPlanDocument(plan, previousSource) {
     import_mdast_builder.heading(3, import_mdast_builder.text("Consequences")),
     import_mdast_builder.html(plan.design.consequences || "<!-- Describe trade-offs and limitations. -->"),
     import_mdast_builder.heading(2, import_mdast_builder.text("Implementation")),
-    ...plan.phases.length ? plan.phases.flatMap((phase) => [import_mdast_builder.html(renderPhase(phase))]) : [import_mdast_builder.html("<!-- Add phases with plan_add_phase. -->")],
+    ...plan.phases.length ? plan.phases.flatMap((phase) => [import_mdast_builder.html(renderPhase(phase))]) : [import_mdast_builder.html("<!-- Add phases with plan_apply_revision. -->")],
     import_mdast_builder.heading(2, import_mdast_builder.text("References")),
     references
   ]);
@@ -7404,10 +7481,7 @@ function renderTask(task) {
   const checked = task.status === "completed" || task.status === "skipped" ? "x" : " ";
   return `<!-- diffpi-task: ${json(marker)} -->
 - [${checked}] **${task.title}**
-${taskList("Steps", task.steps ?? [])}
   - Dependencies: ${list3(task.dependencies)}
-${taskList("File scopes", task.fileScopes)}
-${taskList("Acceptance criteria", task.acceptanceCriteria)}
 <!-- /diffpi-task -->`;
 }
 function parsePhases(input, ref) {
@@ -7457,10 +7531,7 @@ function parseTasks(input, ref) {
     return {
       ...marker,
       title,
-      steps: parseListValue(body, "Steps"),
-      dependencies: parseListValue(body, "Dependencies"),
-      fileScopes: parseListValue(body, "File scopes"),
-      acceptanceCriteria: parseListValue(body, "Acceptance criteria")
+      dependencies: parseListValue(body, "Dependencies")
     };
   });
   assertUniqueIds(tasks.map((task) => task.id), "task id");
@@ -7487,6 +7558,8 @@ function patchMarkers(source, plan) {
     id: plan.id,
     revision: plan.revision,
     branch: plan.branch,
+    issueId: plan.issueId,
+    issueUrl: plan.issueUrl,
     status: plan.status,
     execution: plan.execution,
     createdAt: plan.createdAt,
@@ -7536,19 +7609,12 @@ function contentShape(plan) {
     requirements: plan.requirements,
     design: plan.design,
     references: plan.references,
-    phases: plan.phases.map(({ id, title, objective, dependencies, tasks }) => ({
-      id,
-      title,
-      objective,
-      dependencies,
-      tasks: tasks.map(({ id: taskId, title: taskTitle, steps, dependencies: taskDependencies, fileScopes, acceptanceCriteria }) => ({
-        id: taskId,
-        title: taskTitle,
-        steps,
-        dependencies: taskDependencies,
-        fileScopes,
-        acceptanceCriteria
-      }))
+    phases: plan.phases.map((phase) => ({
+      id: phase.id,
+      title: phase.title,
+      objective: phase.objective,
+      dependencies: phase.dependencies,
+      tasks: phase.tasks.map(({ id, title, dependencies }) => ({ id, title, dependencies }))
     }))
   };
 }
@@ -7648,6 +7714,13 @@ function assertUniqueIds(ids, label) {
 function cleanPlaceholder(value) {
   return value.replace(/<!--[^]*?-->/g, "").trim();
 }
+function isPlaceholder(value) {
+  const normalized = cleanPlaceholder(value).trim();
+  return normalized.length === 0 || /^(?:todo|tbd|none|n\/a)$/i.test(normalized) || /define during implementation|describe the|add requirements|add implementation/i.test(normalized);
+}
+function sameIds(expected, actual) {
+  return expected.length === actual.length && expected.every((value, index) => actual[index] === value);
+}
 function parseMarker(value, label) {
   try {
     return JSON.parse(value);
@@ -7655,15 +7728,14 @@ function parseMarker(value, label) {
     throw new Error(`Malformed ${label} marker JSON.`);
   }
 }
-function taskList(label, values) {
+function bulletList(values, empty = "") {
   if (!values.length)
-    return `  - ${label}: none`;
-  const items = values.flatMap((value) => {
+    return empty;
+  return values.flatMap((value) => {
     const [first = "", ...continuations] = value.split(`
 `);
-    return [`    - ${first}`, ...continuations.map((line) => `      ${line}`)];
-  });
-  return [`  - ${label}:`, ...items].join(`
+    return [`- ${first}`, ...continuations.map((line) => `  ${line}`)];
+  }).join(`
 `);
 }
 function list3(values) {
@@ -7691,7 +7763,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 = join5(root, entry.name);
     await assertContained(root, dir);
     try {
       const record = await readRecord(dir);
@@ -7710,6 +7782,15 @@ async function resolvePlan(cwd, query, filters = {}, options = {}) {
 }
 function createPlanStore(options = {}) {
   const now = options.now ?? (() => new Date);
+  const read = async (cwd, query, filters) => {
+    const result = await resolvePlan(cwd, query, filters, options);
+    if (!result.record) {
+      if (result.ambiguous)
+        throw new Error(`Plan query "${query}" is ambiguous: ${result.candidates.map((item) => item.id).join(", ")}.`);
+      throw new Error(`Plan "${query}" was not found.`);
+    }
+    return result.record;
+  };
   return {
     context(cwd, query, filters) {
       return resolvePlan(cwd, query, filters, options);
@@ -7717,120 +7798,322 @@ 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);
-      await assertContained(root, dirname4(dir));
-      try {
-        await mkdir3(dir);
-      } catch (error) {
-        if (error.code === "EEXIST")
-          throw new Error(`Plan ${id} already exists.`);
-        throw error;
-      }
+      const dir = join5(root, id);
+      await createPlanDirectory(root, dir, id);
       try {
         const timestamp = now().toISOString();
-        const template = await loadTemplate("plan/PLAN", {
-          homeDir: options.homeDir,
-          bundledDir: options.bundledTemplatesDir
-        });
-        const source = renderTemplate(template.content, {
+        const title = input.title?.trim() || titleFromSlug(input.shortSlug);
+        const document = {
+          schemaVersion: 1,
           id,
+          revision: 0,
+          title,
           branch: input.branch,
-          title: input.title?.trim() || titleFromSlug(input.shortSlug),
+          ...input.issueId?.trim() ? { issueId: input.issueId.trim() } : {},
+          ...input.issueUrl?.trim() ? { issueUrl: input.issueUrl.trim() } : {},
           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);
-        return {
-          id,
-          dir,
-          planPath: join7(dir, "PLAN.md"),
-          logPath: join7(dir, "logs.txt"),
-          implementationDir: join7(dir, "implementation"),
-          document,
-          source
+          requirements: [],
+          design: { bigIdeas: "", keyApiUpdates: "", consequences: "" },
+          phases: [],
+          references: [],
+          status: "draft",
+          createdAt: timestamp,
+          updatedAt: timestamp
         };
+        const source = renderPlanDocument(document);
+        parsePlanDocument(source, join5(dir, "PLAN.md"));
+        const authoringRequest = input.request ?? { kind: "user", text: input.intent?.trim() || `Initialize phase-less plan ${title}.` };
+        await writeRevisionSnapshot(dir, document, source, authoringRequest, []);
+        await writeLatestView(dir, document, source, []);
+        return await readRecord(dir);
       } catch (error) {
         await rm2(dir, { recursive: true, force: true });
         throw error;
       }
     },
-    async read(cwd, query, filters) {
-      const result = await resolvePlan(cwd, query, filters, options);
-      if (!result.record) {
-        if (result.ambiguous)
-          throw new Error(`Plan query "${query}" is ambiguous: ${result.candidates.map((item) => item.id).join(", ")}.`);
-        throw new Error(`Plan "${query}" was not found.`);
-      }
-      return result.record;
+    read,
+    async applyRevision(cwd, request) {
+      if (request.mode === "create") {
+        const root = await plansDir(cwd, options.homeDir);
+        const id = planRecordName(request.shortSlug, now());
+        const dir = join5(root, id);
+        await createPlanDirectory(root, dir, id);
+        try {
+          const timestamp = now().toISOString();
+          const document = normalizeRevision(undefined, request, id, 0, timestamp);
+          assertCompleteRevision(document, request.briefs);
+          const source = renderPlanDocument(document);
+          parsePlanDocument(source, join5(dir, "PLAN.md"));
+          await writeRevisionSnapshot(dir, document, source, request.request, request.briefs);
+          await writeLatestView(dir, document, source, request.briefs);
+          return await readRecord(dir);
+        } catch (error) {
+          await rm2(dir, { recursive: true, force: true });
+          throw error;
+        }
+      }
+      const initial = await read(cwd, request.plan);
+      return withDirectoryLock(join5(initial.dir, ".lock"), async () => {
+        const current = await readRecord(initial.dir);
+        if (current.document.revision !== request.expectedPlanRevision)
+          throw new Error(`Expected plan revision ${request.expectedPlanRevision}, found ${current.document.revision}.`);
+        const revision = current.document.revision + 1;
+        const document = normalizeRevision(current.document, request, current.id, revision, now().toISOString());
+        assertCompleteRevision(document, request.briefs);
+        const source = renderPlanDocument(document);
+        parsePlanDocument(source, current.planPath);
+        await writeRevisionSnapshot(current.dir, document, source, request.request, request.briefs);
+        try {
+          await writeLatestView(current.dir, document, source, request.briefs);
+        } catch (error) {
+          await rm2(join5(current.dir, "revisions", String(revision)), { recursive: true, force: true });
+          throw error;
+        }
+        return await readRecord(current.dir);
+      }, { operation: "apply revision" });
     },
     async mutate(cwd, query, operation, update) {
-      const initial = await this.read(cwd, query);
-      return withDirectoryLock(join7(initial.dir, ".lock"), async () => {
+      const initial = await read(cwd, query);
+      return withDirectoryLock(join5(initial.dir, ".lock"), async () => {
         const current = await readRecord(initial.dir);
         const next = await update(structuredClone(current.document));
         if (next.id !== current.id)
           throw new Error("A plan mutation cannot change the plan ID.");
         const document = {
           ...next,
-          revision: current.document.revision + 1,
+          revision: current.document.revision,
           updatedAt: now().toISOString()
         };
         const source = renderPlanDocument(document, current.source);
         parsePlanDocument(source, current.planPath);
         await atomicWrite(current.planPath, source);
-        await ensureImplementationFiles(current.dir, document, options);
-        return { ...current, document, source, implementationDir: join7(current.dir, "implementation") };
+        return { ...current, document, source };
       }, { operation });
     },
     async log(cwd, query, event) {
-      const record = await this.read(cwd, query);
+      const record = await read(cwd, query);
       return appendLogEntry(record.logPath, event);
     }
   };
 }
 async function readRecord(dir) {
-  const planPath = join7(dir, "PLAN.md");
-  const logPath = join7(dir, "logs.txt");
-  const source = await readFile3(planPath, "utf8");
+  const planPath = join5(dir, "PLAN.md");
+  const logPath = join5(dir, "logs.txt");
+  const source = await readFile2(planPath, "utf8");
   const document = parsePlanDocument(source, planPath);
   return {
     id: basename3(dir),
     dir,
     planPath,
     logPath,
-    implementationDir: join7(dir, "implementation"),
+    implementationDir: join5(dir, "implementation"),
     document,
     source
   };
 }
-async function ensureImplementationFiles(dir, document, options) {
-  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 = join7(implementationDir, `phase-${phase.id}.md`);
+async function createPlanDirectory(root, dir, id) {
+  await assertContained(root, dirname3(dir));
+  try {
+    await mkdir3(dir);
+  } catch (error) {
+    if (error.code === "EEXIST")
+      throw new Error(`Plan ${id} already exists.`);
+    throw error;
+  }
+}
+async function writeRevisionSnapshot(planDir, document, source, request, briefs) {
+  if (!request.text.trim())
+    throw new Error("An exact non-empty authoring request is required.");
+  if (request.kind === "annotation" && !request.response?.trim())
+    throw new Error("Annotation requests require a non-empty response.");
+  const revisionsDir = join5(planDir, "revisions");
+  await mkdir3(revisionsDir, { recursive: true });
+  const target = join5(revisionsDir, String(document.revision));
+  try {
+    await readFile2(join5(target, "metadata.json"), "utf8");
+    throw new Error(`Revision ${document.revision} already exists and is immutable.`);
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+  const staging = join5(revisionsDir, `.tmp-${document.revision}-${randomUUID2()}`);
+  await mkdir3(staging);
+  try {
+    const requestSource = request.kind === "annotation" ? `## Original annotation
+${request.text}
+
+## LLM response
+${request.response}` : request.text;
+    await atomicWrite(join5(staging, "request.md"), requestSource);
+    await atomicWrite(join5(staging, "metadata.json"), `${JSON.stringify({
+      schemaVersion: 1,
+      id: document.id,
+      revision: document.revision,
+      requestKind: request.kind,
+      requestSha256: sha256(request.text),
+      ...request.kind === "annotation" ? { originalAnnotationSha256: sha256(request.text), responseSha256: sha256(request.response) } : {},
+      createdAt: document.updatedAt
+    }, null, 2)}
+`);
+    await atomicWrite(join5(staging, "PLAN.md"), source);
+    await writeImplementationDirectory(staging, document, briefs);
+    await rename2(staging, target);
+  } catch (error) {
+    await rm2(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+async function writeLatestView(planDir, document, source, briefs) {
+  const current = join5(planDir, "implementation");
+  const stagingRoot = join5(planDir, `.latest-${randomUUID2()}`);
+  const stagedImplementation = join5(stagingRoot, "implementation");
+  const backup = join5(planDir, `.implementation-backup-${randomUUID2()}`);
+  await mkdir3(stagingRoot);
+  await writeImplementationDirectory(stagingRoot, document, briefs);
+  let backedUp = false;
+  try {
     try {
-      await readFile3(path, "utf8");
+      await rename2(current, backup);
+      backedUp = true;
     } catch (error) {
       if (error.code !== "ENOENT")
         throw error;
-      const tasks = phase.tasks.map((task) => `- ${task.id}: ${task.title}`).join("\\n") || "- Add implementation tasks.";
-      await atomicWrite(path, renderTemplate(template.content, {
-        phase_id: phase.id,
-        phase_title: phase.title,
-        phase_objective: phase.objective,
-        phase_tasks: tasks
-      }));
     }
+    await rename2(stagedImplementation, current);
+    await atomicWrite(join5(planDir, "PLAN.md"), source);
+    if (backedUp)
+      await rm2(backup, { recursive: true, force: true });
+  } catch (error) {
+    await rm2(current, { recursive: true, force: true });
+    if (backedUp)
+      await rename2(backup, current);
+    throw error;
+  } finally {
+    await rm2(stagingRoot, { recursive: true, force: true });
   }
 }
+async function writeImplementationDirectory(baseDir, document, briefs) {
+  const implementationDir = join5(baseDir, "implementation");
+  await mkdir3(implementationDir, { recursive: true });
+  for (const [index, phase] of document.phases.entries()) {
+    const brief = briefs[index];
+    if (!brief)
+      throw new Error(`Missing implementation brief for phase ${phase.id}.`);
+    await atomicWrite(join5(implementationDir, `phase-${index + 1}.md`), renderImplementationBrief(document.revision, index + 1, phase, brief));
+  }
+}
+function normalizeRevision(current, request, id, revision, updatedAt) {
+  if (current?.status === "completed")
+    throw new Error("Completed plans cannot be amended.");
+  if (current?.execution?.active && request.request.kind !== "blocker")
+    throw new Error("An active execution accepts only a blocker amendment.");
+  const currentPhases = new Map(current?.phases.map((phase) => [phase.id, phase]) ?? []);
+  for (const phase of current?.phases ?? []) {
+    if (!request.phases.some((candidate) => candidate.id === phase.id) && (phase.status === "completed" || phase.status === "in_progress"))
+      throw new Error(`${phase.status === "completed" ? "Completed" : "Active"} phase ${phase.id} cannot be removed.`);
+  }
+  const phases = request.phases.map((draft) => reconcilePhase(currentPhases.get(draft.id), draft, current));
+  const createdAt = current?.createdAt ?? updatedAt;
+  return {
+    schemaVersion: 1,
+    id,
+    revision,
+    title: request.title,
+    branch: current?.branch ?? (request.mode === "create" ? request.branch : ""),
+    issueId: current?.issueId ?? (request.mode === "create" ? request.issueId : undefined),
+    issueUrl: current?.issueUrl ?? (request.mode === "create" ? request.issueUrl : undefined),
+    intent: request.intent,
+    requirements: request.requirements,
+    design: request.design,
+    references: request.references,
+    phases,
+    status: nextPlanStatus(current),
+    execution: current?.execution,
+    createdAt,
+    updatedAt
+  };
+}
+function reconcilePhase(current, draft, plan) {
+  if (!current)
+    return {
+      ...draft,
+      revision: 0,
+      status: "pending",
+      gate: { phaseRevision: 0, status: "pending", results: [] },
+      tasks: draft.tasks.map(newTask)
+    };
+  if (current.status === "completed") {
+    if (JSON.stringify(phaseContent(current)) !== JSON.stringify(draft))
+      throw new Error(`Completed phase ${current.id} cannot be changed.`);
+    return current;
+  }
+  const byId = new Map(current.tasks.map((task) => [task.id, task]));
+  for (const task of current.tasks) {
+    if (!draft.tasks.some((candidate) => candidate.id === task.id) && (task.status === "completed" || task.status === "in_progress"))
+      throw new Error(`${task.status === "completed" ? "Completed" : "Active"} task ${task.id} cannot be removed.`);
+  }
+  const tasks = draft.tasks.map((task) => reconcileTask(byId.get(task.id), task));
+  const changed = JSON.stringify(phaseContent(current)) !== JSON.stringify(draft);
+  const revision = changed ? current.revision + 1 : current.revision;
+  const wasBlocked = current.status === "blocked";
+  return {
+    ...current,
+    ...draft,
+    revision,
+    tasks,
+    status: wasBlocked ? plan?.execution?.active ? "in_progress" : "pending" : current.status,
+    gate: changed || wasBlocked ? { phaseRevision: revision, status: "stale", results: [] } : current.gate,
+    blocker: wasBlocked ? undefined : current.blocker
+  };
+}
+function reconcileTask(current, draft) {
+  if (!current)
+    return newTask(draft);
+  const changed = JSON.stringify(taskContent(current)) !== JSON.stringify(draft);
+  if ((current.status === "completed" || current.status === "in_progress") && changed)
+    throw new Error(`${current.status === "completed" ? "Completed" : "Active"} task ${current.id} cannot be changed.`);
+  if (current.status === "completed" || current.status === "in_progress")
+    return current;
+  return {
+    ...current,
+    ...draft,
+    revision: changed ? current.revision + 1 : current.revision,
+    status: current.status === "blocked" ? "pending" : current.status,
+    owner: current.status === "blocked" ? undefined : current.owner,
+    executionId: current.status === "blocked" ? undefined : current.executionId,
+    blocker: current.status === "blocked" ? undefined : current.blocker
+  };
+}
+function newTask(draft) {
+  return { ...draft, revision: 0, status: "pending" };
+}
+function phaseContent(phase) {
+  return {
+    id: phase.id,
+    title: phase.title,
+    objective: phase.objective,
+    dependencies: phase.dependencies,
+    tasks: phase.tasks.map(taskContent)
+  };
+}
+function taskContent(task) {
+  return { id: task.id, title: task.title, dependencies: task.dependencies };
+}
+function nextPlanStatus(current) {
+  if (!current)
+    return "draft";
+  if (current.execution?.active)
+    return current.status === "blocked" ? "in_progress" : current.status;
+  return current.status === "ready" || current.status === "blocked" ? "draft" : current.status;
+}
+function assertCompleteRevision(document, briefs) {
+  const errors = [...validatePlanDocument(document, { strict: true }), ...validatePlanBriefs(document, briefs)].filter((issue) => issue.severity === "error");
+  if (errors.length)
+    throw new Error(`Invalid plan revision: ${errors.map((issue) => issue.message).join(" ")}`);
+}
+function sha256(value) {
+  return createHash2("sha256").update(value).digest("hex");
+}
 async function assertContained(root, candidate) {
   const canonicalRoot = await realpath3(root);
   let canonicalCandidate;
@@ -7862,11 +8145,14 @@ function stripDate(value) {
   return value.replace(/^\d{6}-/, "");
 }
 function titleFromSlug(value) {
-  return normalizeSlug(value).replace(/^(?:[a-z]+-\d+-)/, "").split("-").map((part) => part[0].toUpperCase() + part.slice(1)).join(" ");
+  const slug = normalizeSlug(value).replace(/^(?:[a-z]+-\d+-)/, "");
+  return slug.replace(/(^|-)([a-z])/g, (_match, separator, letter) => {
+    return `${separator ? " " : ""}${letter.toUpperCase()}`;
+  });
 }
 // src/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";
+import { mkdir as mkdir4, readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname4, join as join6 } from "node:path";
 async function createPlanReview(record, runtime = {}) {
   if (await readPlanReview(record))
     throw new Error(`Plan revision ${record.document.revision} already has a review.`);
@@ -7899,7 +8185,7 @@ async function readPlanReview(record) {
   const path = reviewPath(record);
   let source;
   try {
-    source = await readFile4(path, "utf8");
+    source = await readFile3(path, "utf8");
   } catch (error) {
     if (error.code === "ENOENT")
       return;
@@ -7916,10 +8202,10 @@ async function readPlanReview(record) {
   return { path, dump };
 }
 function reviewPath(record) {
-  return join8(record.dir, "reviews", `${record.document.revision}.json`);
+  return join6(record.dir, "reviews", `${record.document.revision}.json`);
 }
 async function writeReview(review) {
-  await mkdir4(dirname5(review.path), { recursive: true });
+  await mkdir4(dirname4(review.path), { recursive: true });
   await writeFile2(review.path, `${JSON.stringify(review.dump, null, 2)}
 `, {
     encoding: "utf8",