@difflab/pi 0.5.0 → 0.6.0-rc.202609270756.7689e22

package/dist/index.js

@@ -605,6 +605,16 @@ function diffpiLaunchName(cwd, workflow) {
 }
 async function openFileAdjacent(path, opts) {
   const env = opts.env ?? process.env;
+  const mux = detectMux(env);
+  if (mux !== "none") {
+    const editor = await resolveEditor(env);
+    if (editor) {
+      const command = persistentEditorArgs(editor, path, opts.cwd, env.SHELL);
+      const opened = await openMuxTab(mux, command, opts.cwd, opts.name ?? "plan", [editor, path].join(" "), command);
+      if (opened)
+        return opened;
+    }
+  }
   const ide = detectIde(env);
   if (ide !== "unknown") {
     const ideCommand = { zed: "zed", vscode: "code", cursor: "cursor", windsurf: "windsurf", jetbrains: "idea" }[ide];
@@ -614,16 +624,6 @@ async function openFileAdjacent(path, opts) {
         return { launched: true, via: ide, command: `${ideCommand} ${path}` };
     }
   }
-  const mux = detectMux(env);
-  if (mux !== "none") {
-    const editor = await resolveEditor(env);
-    if (editor) {
-      const command = [editor, path];
-      const opened = await openMuxTab(mux, command, opts.cwd, opts.name ?? "plan", command.join(" "));
-      if (opened)
-        return opened;
-    }
-  }
   return { launched: false, via: "print", command: path, reason: "No supported IDE or multiplexer was available." };
 }
 async function openInNewTab(command, opts) {
@@ -658,10 +658,15 @@ async function openInNewTab(command, opts) {
 function screenWindowArgs(command, cwd, name) {
   return ["-X", "screen", "-t", name, "sh", "-lc", 'cd -- "$1" && shift && exec "$@"', "sh", cwd, ...command];
 }
+function persistentEditorArgs(editor, path, cwd, shell = "sh") {
+  return ["bash", "-lc", 'cd -- "$1" && shift && "$@"; exec "$0" -i', shell, cwd, editor, path];
+}
 async function resolveEditor(env) {
-  const configured = (env.VISUAL ?? env.EDITOR)?.trim().split(/\s+/)[0];
-  if (configured && await findExecutable(configured))
-    return configured;
+  for (const configured of [env.EDITOR, env.VISUAL]) {
+    const editor = configured?.trim();
+    if (editor && await findExecutable(editor))
+      return editor;
+  }
   for (const candidate of ["hx", "nvim", "vim"])
     if (await findExecutable(candidate))
       return candidate;
@@ -678,7 +683,7 @@ async function packageVersion() {
     throw new Error("Cannot resolve the installed @difflab/pi version.");
   return value.version;
 }
-async function openMuxTab(mux, command, cwd, name, printable) {
+async function openMuxTab(mux, command, cwd, name, printable, tmuxCommand) {
   if (mux === "zellij" && await findExecutable("zellij")) {
     const result = await run("zellij", ["action", "new-tab", "--cwd", cwd, "--name", name, "--", ...command]);
     if (result.code === 0)
@@ -688,7 +693,7 @@ async function openMuxTab(mux, command, cwd, name, printable) {
       return { launched: true, via: "zellij-run", command: printable };
   }
   if (mux === "tmux" && await findExecutable("tmux")) {
-    const result = await run("tmux", ["new-window", "-c", cwd, "-n", name, printable]);
+    const result = tmuxCommand ? await run("tmux", ["new-window", "-c", cwd, "-n", name, ...tmuxCommand]) : await run("tmux", ["new-window", "-c", cwd, "-n", name, printable]);
     if (result.code === 0)
       return { launched: true, via: "tmux", command: printable };
   }
@@ -1433,7 +1438,7 @@ function renderThreadArtifact(title, target, threads, options = {}) {
   }
   lines.push("## Source comments", "");
   for (const thread of threads) {
-    lines.push(`### ${thread.file ?? "review"}:${thread.line ?? "n/a"} — ${thread.author ?? "unknown"}`, "", `Thread: ${thread.id}`, `Status: ${thread.resolved ? "resolved" : thread.addressed ? "addressed" : "open"}`, "", thread.body, "", "---", "");
+    lines.push(`### ${thread.file ?? "review"}:${thread.line ?? "n/a"} — ${thread.author ?? "unknown"}`, "", `Thread: ${thread.id}`, `Status: ${thread.resolved ? "resolved" : thread.addressed ? "addressed" : "open"}`, "", "**Source comment**", "", thread.body, "", "**Recorded response**", "", thread.reply?.trim() || "_No response recorded._", "", "---", "");
   }
   return `${lines.join(`
 `).trimEnd()}
@@ -2629,7 +2634,8 @@ function parseJsonObject(content, path) {
   throw new Error(`Expected valid JSON object in ${path}.`);
 }
 // src/plan/store.ts
-import { mkdir as mkdir7, readdir as readdir2, readFile as readFile12, realpath as realpath4, rm as rm2 } from "node:fs/promises";
+import { createHash as createHash3, randomUUID as randomUUID2 } from "node:crypto";
+import { mkdir as mkdir7, readdir as readdir2, readFile as readFile12, realpath as realpath4, rename as rename3, rm as rm2 } from "node:fs/promises";
 import { basename as basename6, dirname as dirname8, join as join16, resolve as resolve4, sep } from "node:path";
 
 // src/extensions/fsx.ts
@@ -7386,11 +7392,13 @@ function validatePlanDocument(plan, options = {}) {
         if (!taskIds.has(dependency))
           add("dangling-dependency", "error", `Task ${task.id} depends on missing ${dependency}.`);
       }
-      if (options.strict && task.acceptanceCriteria.length === 0)
-        add("acceptance", "error", `Task ${task.id} has no acceptance criteria.`, task.id);
+      if (options.strict && isPlaceholder(task.title))
+        add("placeholder", "error", `Task ${task.id} has placeholder content.`, task.id);
     }
     if (options.strict && phase.tasks.length === 0)
       add("empty-phase", "error", `Phase ${phase.id} has no tasks.`, phase.id);
+    if (options.strict && (isPlaceholder(phase.title) || isPlaceholder(phase.objective)))
+      add("placeholder", "error", `Phase ${phase.id} has placeholder content.`, phase.id);
   }
   for (const cycle of dependencyCycles(plan))
     add("dependency-cycle", "error", `Dependency cycle: ${cycle.join(" -> ")}.`);
@@ -7399,10 +7407,131 @@ function validatePlanDocument(plan, options = {}) {
     add("design-length", "warning", `Design is ${designWords} words; prefer 300 or fewer.`);
   if (options.strict && designWords > 800)
     add("design-too-long", "error", `Design is ${designWords} words; finalization allows at most 800.`);
-  if (options.strict && plan.phases.length === 0)
-    add("no-phases", "error", "Finalization requires at least one phase.");
+  if (options.strict) {
+    if (plan.phases.length === 0)
+      add("no-phases", "error", "Finalization requires at least one phase.");
+    if (isPlaceholder(plan.intent))
+      add("placeholder", "error", "Intent must contain concrete content.", "intent");
+    if (!plan.requirements.length || plan.requirements.some(isPlaceholder))
+      add("requirements", "error", "Requirements must contain concrete content.", "requirements");
+    for (const [key, value] of Object.entries(plan.design)) {
+      if (isPlaceholder(value))
+        add("design", "error", `Design/${key} must contain concrete content.`, `design.${key}`);
+    }
+  }
+  return issues;
+}
+function validatePlanBriefs(plan, briefs) {
+  const issues = [];
+  const phaseIds = plan.phases.map((phase) => phase.id);
+  const briefIds = briefs.map((brief) => brief.phaseId);
+  if (!sameIds(phaseIds, briefIds))
+    issues.push({
+      code: "brief-phase-ids",
+      severity: "error",
+      message: `Brief phase IDs must exactly match plan phases in order: ${phaseIds.join(", ")}.`
+    });
+  for (const [index, phase] of plan.phases.entries()) {
+    const brief = briefs[index];
+    if (!brief || brief.phaseId !== phase.id)
+      continue;
+    if (isPlaceholder(brief.summary))
+      issues.push({ code: "brief-placeholder", severity: "error", message: `Brief ${phase.id} needs a summary.` });
+    const taskIds = phase.tasks.map((task) => task.id);
+    const briefTaskIds = brief.tasks.map((task) => task.taskId);
+    if (!sameIds(taskIds, briefTaskIds))
+      issues.push({
+        code: "brief-task-ids",
+        severity: "error",
+        message: `Brief ${phase.id} task IDs must exactly match phase tasks in order: ${taskIds.join(", ")}.`
+      });
+    for (const task of brief.tasks) {
+      for (const [field, values] of [
+        ["ordered steps", task.steps],
+        ["file scopes", task.fileScopes],
+        ["acceptance criteria", task.acceptanceCriteria]
+      ]) {
+        if (!values.length || values.some(isPlaceholder))
+          issues.push({
+            code: "brief-incomplete",
+            severity: "error",
+            message: `Brief task ${task.taskId} needs concrete ${field}.`,
+            path: task.taskId
+          });
+      }
+    }
+    for (const [field, values] of [
+      ["API changes", brief.apiChanges],
+      ["libraries", brief.libraries],
+      ["constraints", brief.constraints]
+    ]) {
+      if (values.some(isPlaceholder))
+        issues.push({
+          code: "brief-placeholder",
+          severity: "error",
+          message: `Brief ${phase.id} has placeholder ${field}.`,
+          path: phase.id
+        });
+    }
+  }
   return issues;
 }
+function renderImplementationBrief(planRevision, ordinal, phase, brief) {
+  const marker = { schemaVersion: 1, planRevision, ordinal, phaseId: phase.id };
+  const tasks = phase.tasks.map((task, index) => {
+    const details = brief.tasks[index];
+    if (!details || details.taskId !== task.id)
+      throw new Error(`Missing implementation details for ${task.id}.`);
+    return `<!-- diffpi-brief-task: ${json({ id: task.id })} -->
+### Task: ${task.title}
+
+#### Ordered Steps
+
+${bulletList(details.steps)}
+
+#### File Scopes
+
+${bulletList(details.fileScopes)}
+
+#### Acceptance Criteria
+
+${bulletList(details.acceptanceCriteria)}
+
+<!-- /diffpi-brief-task -->`;
+  }).join(`
+
+`);
+  return `<!-- diffpi-implementation: ${json(marker)} -->
+# Phase ${ordinal}: ${phase.title}
+
+- **Phase ID:** ${phase.id}
+- **Plan Revision:** ${planRevision}
+
+## Summary
+
+${brief.summary}
+
+## Objective
+
+${phase.objective}
+
+## Tasks
+
+${tasks}
+
+## API Changes
+
+${bulletList(brief.apiChanges, "None.")}
+
+## Libraries and Algorithms
+
+${bulletList(brief.libraries, "None.")}
+
+## Implementation Constraints
+
+${bulletList(brief.constraints, "None.")}
+`;
+}
 function renderPlanDocument(plan, previousSource) {
   if (previousSource && canPatch(previousSource, plan))
     return patchMarkers(previousSource, plan);
@@ -7411,6 +7540,8 @@ function renderPlanDocument(plan, previousSource) {
     id: plan.id,
     revision: plan.revision,
     branch: plan.branch,
+    issueId: plan.issueId,
+    issueUrl: plan.issueUrl,
     status: plan.status,
     execution: plan.execution,
     createdAt: plan.createdAt,
@@ -7419,6 +7550,8 @@ function renderPlanDocument(plan, previousSource) {
   const metadata = import_mdast_builder.list("unordered", [
     ["Plan ID", plan.id],
     ["Branch", plan.branch],
+    ...plan.issueId ? [["Issue", plan.issueId]] : [],
+    ...plan.issueUrl ? [["Issue URL", plan.issueUrl]] : [],
     ["Status", plan.status],
     ["Revision", String(plan.revision)]
   ].map(([label, value]) => import_mdast_builder.listItem(import_mdast_builder.paragraph([import_mdast_builder.strong(import_mdast_builder.text(`${label}:`)), import_mdast_builder.text(` ${value}`)]))));
@@ -7440,7 +7573,7 @@ function renderPlanDocument(plan, previousSource) {
     import_mdast_builder.heading(3, import_mdast_builder.text("Consequences")),
     import_mdast_builder.html(plan.design.consequences || "<!-- Describe trade-offs and limitations. -->"),
     import_mdast_builder.heading(2, import_mdast_builder.text("Implementation")),
-    ...plan.phases.length ? plan.phases.flatMap((phase) => [import_mdast_builder.html(renderPhase(phase))]) : [import_mdast_builder.html("<!-- Add phases with plan_add_phase. -->")],
+    ...plan.phases.length ? plan.phases.flatMap((phase) => [import_mdast_builder.html(renderPhase(phase))]) : [import_mdast_builder.html("<!-- Add phases with plan_apply_revision. -->")],
     import_mdast_builder.heading(2, import_mdast_builder.text("References")),
     references
   ]);
@@ -7514,10 +7647,7 @@ function renderTask(task) {
   const checked = task.status === "completed" || task.status === "skipped" ? "x" : " ";
   return `<!-- diffpi-task: ${json(marker)} -->
 - [${checked}] **${task.title}**
-${taskList("Steps", task.steps ?? [])}
   - Dependencies: ${list3(task.dependencies)}
-${taskList("File scopes", task.fileScopes)}
-${taskList("Acceptance criteria", task.acceptanceCriteria)}
 <!-- /diffpi-task -->`;
 }
 function parsePhases(input, ref) {
@@ -7567,10 +7697,7 @@ function parseTasks(input, ref) {
     return {
       ...marker,
       title,
-      steps: parseListValue(body, "Steps"),
-      dependencies: parseListValue(body, "Dependencies"),
-      fileScopes: parseListValue(body, "File scopes"),
-      acceptanceCriteria: parseListValue(body, "Acceptance criteria")
+      dependencies: parseListValue(body, "Dependencies")
     };
   });
   assertUniqueIds(tasks.map((task) => task.id), "task id");
@@ -7597,6 +7724,8 @@ function patchMarkers(source, plan) {
     id: plan.id,
     revision: plan.revision,
     branch: plan.branch,
+    issueId: plan.issueId,
+    issueUrl: plan.issueUrl,
     status: plan.status,
     execution: plan.execution,
     createdAt: plan.createdAt,
@@ -7646,19 +7775,12 @@ function contentShape(plan) {
     requirements: plan.requirements,
     design: plan.design,
     references: plan.references,
-    phases: plan.phases.map(({ id, title, objective, dependencies, tasks }) => ({
-      id,
-      title,
-      objective,
-      dependencies,
-      tasks: tasks.map(({ id: taskId, title: taskTitle, steps, dependencies: taskDependencies, fileScopes, acceptanceCriteria }) => ({
-        id: taskId,
-        title: taskTitle,
-        steps,
-        dependencies: taskDependencies,
-        fileScopes,
-        acceptanceCriteria
-      }))
+    phases: plan.phases.map((phase) => ({
+      id: phase.id,
+      title: phase.title,
+      objective: phase.objective,
+      dependencies: phase.dependencies,
+      tasks: phase.tasks.map(({ id, title, dependencies }) => ({ id, title, dependencies }))
     }))
   };
 }
@@ -7758,6 +7880,13 @@ function assertUniqueIds(ids, label) {
 function cleanPlaceholder(value) {
   return value.replace(/<!--[^]*?-->/g, "").trim();
 }
+function isPlaceholder(value) {
+  const normalized = cleanPlaceholder(value).trim();
+  return normalized.length === 0 || /^(?:todo|tbd|none|n\/a)$/i.test(normalized) || /define during implementation|describe the|add requirements|add implementation/i.test(normalized);
+}
+function sameIds(expected, actual) {
+  return expected.length === actual.length && expected.every((value, index) => actual[index] === value);
+}
 function parseMarker(value, label) {
   try {
     return JSON.parse(value);
@@ -7765,15 +7894,14 @@ function parseMarker(value, label) {
     throw new Error(`Malformed ${label} marker JSON.`);
   }
 }
-function taskList(label, values) {
+function bulletList(values, empty = "") {
   if (!values.length)
-    return `  - ${label}: none`;
-  const items = values.flatMap((value) => {
+    return empty;
+  return values.flatMap((value) => {
     const [first = "", ...continuations] = value.split(`
 `);
-    return [`    - ${first}`, ...continuations.map((line) => `      ${line}`)];
-  });
-  return [`  - ${label}:`, ...items].join(`
+    return [`- ${first}`, ...continuations.map((line) => `  ${line}`)];
+  }).join(`
 `);
 }
 function list3(values) {
@@ -7820,6 +7948,15 @@ async function resolvePlan(cwd, query, filters = {}, options = {}) {
 }
 function createPlanStore(options = {}) {
   const now = options.now ?? (() => new Date);
+  const read = async (cwd, query, filters) => {
+    const result = await resolvePlan(cwd, query, filters, options);
+    if (!result.record) {
+      if (result.ambiguous)
+        throw new Error(`Plan query "${query}" is ambiguous: ${result.candidates.map((item) => item.id).join(", ")}.`);
+      throw new Error(`Plan "${query}" was not found.`);
+    }
+    return result.record;
+  };
   return {
     context(cwd, query, filters) {
       return resolvePlan(cwd, query, filters, options);
@@ -7828,57 +7965,77 @@ function createPlanStore(options = {}) {
       const root = await plansDir(input.cwd, options.homeDir);
       const id = planRecordName(input.shortSlug, now());
       const dir = join16(root, id);
-      await assertContained(root, dirname8(dir));
-      try {
-        await mkdir7(dir);
-      } catch (error) {
-        if (error.code === "EEXIST")
-          throw new Error(`Plan ${id} already exists.`);
-        throw error;
-      }
+      await createPlanDirectory(root, dir, id);
       try {
         const timestamp = now().toISOString();
         const template = await loadTemplate("plan/PLAN", {
           homeDir: options.homeDir,
           bundledDir: options.bundledTemplatesDir
         });
+        const title = input.title?.trim() || titleFromSlug(input.shortSlug);
         const source = renderTemplate(template.content, {
           id,
           branch: input.branch,
-          title: input.title?.trim() || titleFromSlug(input.shortSlug),
+          title,
           intent: input.intent?.trim() || "<!-- Describe the intended outcome. -->",
-          issue_id: input.issueId?.trim() || "<!-- Add issue tracker ID. -->",
-          issue_url: input.issueUrl?.trim() || "<!-- Add issue tracker URL. -->",
+          issue_id: input.issueId?.trim() || "",
+          issue_url: input.issueUrl?.trim() || "",
           created_at: timestamp,
           updated_at: timestamp
         });
         const document = parsePlanDocument(source, join16(dir, "PLAN.md"));
-        await atomicWrite(join16(dir, "PLAN.md"), source);
-        return {
-          id,
-          dir,
-          planPath: join16(dir, "PLAN.md"),
-          logPath: join16(dir, "logs.txt"),
-          implementationDir: join16(dir, "implementation"),
-          document,
-          source
-        };
+        const authoringRequest = input.request ?? { kind: "user", text: input.intent?.trim() || `Initialize phase-less plan ${title}.` };
+        await writeRevisionSnapshot(dir, document, source, authoringRequest, []);
+        await writeLatestView(dir, document, source, []);
+        return await readRecord(dir);
       } catch (error) {
         await rm2(dir, { recursive: true, force: true });
         throw error;
       }
     },
-    async read(cwd, query, filters) {
-      const result = await resolvePlan(cwd, query, filters, options);
-      if (!result.record) {
-        if (result.ambiguous)
-          throw new Error(`Plan query "${query}" is ambiguous: ${result.candidates.map((item) => item.id).join(", ")}.`);
-        throw new Error(`Plan "${query}" was not found.`);
+    read,
+    async applyRevision(cwd, request) {
+      if (request.mode === "create") {
+        const root = await plansDir(cwd, options.homeDir);
+        const id = planRecordName(request.shortSlug, now());
+        const dir = join16(root, id);
+        await createPlanDirectory(root, dir, id);
+        try {
+          const timestamp = now().toISOString();
+          const document = normalizeRevision(undefined, request, id, 0, timestamp);
+          assertCompleteRevision(document, request.briefs);
+          const source = renderPlanDocument(document);
+          parsePlanDocument(source, join16(dir, "PLAN.md"));
+          await writeRevisionSnapshot(dir, document, source, request.request, request.briefs);
+          await writeLatestView(dir, document, source, request.briefs);
+          return await readRecord(dir);
+        } catch (error) {
+          await rm2(dir, { recursive: true, force: true });
+          throw error;
+        }
       }
-      return result.record;
+      const initial = await read(cwd, request.plan);
+      return withDirectoryLock(join16(initial.dir, ".lock"), async () => {
+        const current = await readRecord(initial.dir);
+        if (current.document.revision !== request.expectedPlanRevision)
+          throw new Error(`Expected plan revision ${request.expectedPlanRevision}, found ${current.document.revision}.`);
+        const revision = current.document.revision + 1;
+        const document = normalizeRevision(current.document, request, current.id, revision, now().toISOString());
+        assertCompleteRevision(document, request.briefs);
+        const source = renderPlanDocument(document);
+        parsePlanDocument(source, current.planPath);
+        await writeRevisionSnapshot(current.dir, document, source, request.request, request.briefs);
+        try {
+          await writeLatestView(current.dir, document, source, request.briefs);
+        } catch (error) {
+          await rm2(join16(current.dir, "revisions", String(revision)), { recursive: true, force: true });
+          throw error;
+        }
+        return await readRecord(current.dir);
+      }, { operation: "apply revision" });
     },
     async mutate(cwd, query, operation, update) {
-      const initial = await this.read(cwd, query);
+      const initial = await read(cwd, query);
       return withDirectoryLock(join16(initial.dir, ".lock"), async () => {
         const current = await readRecord(initial.dir);
         const next = await update(structuredClone(current.document));
@@ -7886,18 +8043,17 @@ function createPlanStore(options = {}) {
           throw new Error("A plan mutation cannot change the plan ID.");
         const document = {
           ...next,
-          revision: current.document.revision + 1,
+          revision: current.document.revision,
           updatedAt: now().toISOString()
         };
         const source = renderPlanDocument(document, current.source);
         parsePlanDocument(source, current.planPath);
         await atomicWrite(current.planPath, source);
-        await ensureImplementationFiles(current.dir, document, options);
-        return { ...current, document, source, implementationDir: join16(current.dir, "implementation") };
+        return { ...current, document, source };
       }, { operation });
     },
     async log(cwd, query, event) {
-      const record = await this.read(cwd, query);
+      const record = await read(cwd, query);
       return appendLogEntry(record.logPath, event);
     }
   };
@@ -7917,30 +8073,209 @@ async function readRecord(dir) {
     source
   };
 }
-async function ensureImplementationFiles(dir, document, options) {
-  const implementationDir = join16(dir, "implementation");
-  await mkdir7(implementationDir, { recursive: true });
-  const template = await loadTemplate("plan/implementation", {
-    homeDir: options.homeDir,
-    bundledDir: options.bundledTemplatesDir
-  });
-  for (const phase of document.phases) {
-    const path = join16(implementationDir, `phase-${phase.id}.md`);
+async function createPlanDirectory(root, dir, id) {
+  await assertContained(root, dirname8(dir));
+  try {
+    await mkdir7(dir);
+  } catch (error) {
+    if (error.code === "EEXIST")
+      throw new Error(`Plan ${id} already exists.`);
+    throw error;
+  }
+}
+async function writeRevisionSnapshot(planDir, document, source, request, briefs) {
+  if (!request.text.trim())
+    throw new Error("An exact non-empty authoring request is required.");
+  if (request.kind === "annotation" && !request.response?.trim())
+    throw new Error("Annotation requests require a non-empty response.");
+  const revisionsDir = join16(planDir, "revisions");
+  await mkdir7(revisionsDir, { recursive: true });
+  const target = join16(revisionsDir, String(document.revision));
+  try {
+    await readFile12(join16(target, "metadata.json"), "utf8");
+    throw new Error(`Revision ${document.revision} already exists and is immutable.`);
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+  const staging = join16(revisionsDir, `.tmp-${document.revision}-${randomUUID2()}`);
+  await mkdir7(staging);
+  try {
+    const requestSource = request.kind === "annotation" ? `## Original annotation
+${request.text}
+
+## LLM response
+${request.response}` : request.text;
+    await atomicWrite(join16(staging, "request.md"), requestSource);
+    await atomicWrite(join16(staging, "metadata.json"), `${JSON.stringify({
+      schemaVersion: 1,
+      id: document.id,
+      revision: document.revision,
+      requestKind: request.kind,
+      requestSha256: sha256(request.text),
+      ...request.kind === "annotation" ? { originalAnnotationSha256: sha256(request.text), responseSha256: sha256(request.response) } : {},
+      createdAt: document.updatedAt
+    }, null, 2)}
+`);
+    await atomicWrite(join16(staging, "PLAN.md"), source);
+    await writeImplementationDirectory(staging, document, briefs);
+    await rename3(staging, target);
+  } catch (error) {
+    await rm2(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+async function writeLatestView(planDir, document, source, briefs) {
+  const current = join16(planDir, "implementation");
+  const stagingRoot = join16(planDir, `.latest-${randomUUID2()}`);
+  const stagedImplementation = join16(stagingRoot, "implementation");
+  const backup = join16(planDir, `.implementation-backup-${randomUUID2()}`);
+  await mkdir7(stagingRoot);
+  await writeImplementationDirectory(stagingRoot, document, briefs);
+  let backedUp = false;
+  try {
     try {
-      await readFile12(path, "utf8");
+      await rename3(current, backup);
+      backedUp = true;
     } catch (error) {
       if (error.code !== "ENOENT")
         throw error;
-      const tasks = phase.tasks.map((task) => `- ${task.id}: ${task.title}`).join("\\n") || "- Add implementation tasks.";
-      await atomicWrite(path, renderTemplate(template.content, {
-        phase_id: phase.id,
-        phase_title: phase.title,
-        phase_objective: phase.objective,
-        phase_tasks: tasks
-      }));
     }
+    await rename3(stagedImplementation, current);
+    await atomicWrite(join16(planDir, "PLAN.md"), source);
+    if (backedUp)
+      await rm2(backup, { recursive: true, force: true });
+  } catch (error) {
+    await rm2(current, { recursive: true, force: true });
+    if (backedUp)
+      await rename3(backup, current);
+    throw error;
+  } finally {
+    await rm2(stagingRoot, { recursive: true, force: true });
   }
 }
+async function writeImplementationDirectory(baseDir, document, briefs) {
+  const implementationDir = join16(baseDir, "implementation");
+  await mkdir7(implementationDir, { recursive: true });
+  for (const [index, phase] of document.phases.entries()) {
+    const brief = briefs[index];
+    if (!brief)
+      throw new Error(`Missing implementation brief for phase ${phase.id}.`);
+    await atomicWrite(join16(implementationDir, `phase-${index + 1}.md`), renderImplementationBrief(document.revision, index + 1, phase, brief));
+  }
+}
+function normalizeRevision(current, request, id, revision, updatedAt) {
+  if (current?.status === "completed")
+    throw new Error("Completed plans cannot be amended.");
+  if (current?.execution?.active && request.request.kind !== "blocker")
+    throw new Error("An active execution accepts only a blocker amendment.");
+  const currentPhases = new Map(current?.phases.map((phase) => [phase.id, phase]) ?? []);
+  for (const phase of current?.phases ?? []) {
+    if (!request.phases.some((candidate) => candidate.id === phase.id) && (phase.status === "completed" || phase.status === "in_progress"))
+      throw new Error(`${phase.status === "completed" ? "Completed" : "Active"} phase ${phase.id} cannot be removed.`);
+  }
+  const phases = request.phases.map((draft) => reconcilePhase(currentPhases.get(draft.id), draft, current));
+  const createdAt = current?.createdAt ?? updatedAt;
+  return {
+    schemaVersion: 1,
+    id,
+    revision,
+    title: request.title,
+    branch: current?.branch ?? (request.mode === "create" ? request.branch : ""),
+    issueId: current?.issueId ?? (request.mode === "create" ? request.issueId : undefined),
+    issueUrl: current?.issueUrl ?? (request.mode === "create" ? request.issueUrl : undefined),
+    intent: request.intent,
+    requirements: request.requirements,
+    design: request.design,
+    references: request.references,
+    phases,
+    status: nextPlanStatus(current),
+    execution: current?.execution,
+    createdAt,
+    updatedAt
+  };
+}
+function reconcilePhase(current, draft, plan) {
+  if (!current)
+    return {
+      ...draft,
+      revision: 0,
+      status: "pending",
+      gate: { phaseRevision: 0, status: "pending", results: [] },
+      tasks: draft.tasks.map(newTask)
+    };
+  if (current.status === "completed") {
+    if (JSON.stringify(phaseContent(current)) !== JSON.stringify(draft))
+      throw new Error(`Completed phase ${current.id} cannot be changed.`);
+    return current;
+  }
+  const byId = new Map(current.tasks.map((task) => [task.id, task]));
+  for (const task of current.tasks) {
+    if (!draft.tasks.some((candidate) => candidate.id === task.id) && (task.status === "completed" || task.status === "in_progress"))
+      throw new Error(`${task.status === "completed" ? "Completed" : "Active"} task ${task.id} cannot be removed.`);
+  }
+  const tasks = draft.tasks.map((task) => reconcileTask(byId.get(task.id), task));
+  const changed = JSON.stringify(phaseContent(current)) !== JSON.stringify(draft);
+  const revision = changed ? current.revision + 1 : current.revision;
+  const wasBlocked = current.status === "blocked";
+  return {
+    ...current,
+    ...draft,
+    revision,
+    tasks,
+    status: wasBlocked ? plan?.execution?.active ? "in_progress" : "pending" : current.status,
+    gate: changed || wasBlocked ? { phaseRevision: revision, status: "stale", results: [] } : current.gate,
+    blocker: wasBlocked ? undefined : current.blocker
+  };
+}
+function reconcileTask(current, draft) {
+  if (!current)
+    return newTask(draft);
+  const changed = JSON.stringify(taskContent(current)) !== JSON.stringify(draft);
+  if ((current.status === "completed" || current.status === "in_progress") && changed)
+    throw new Error(`${current.status === "completed" ? "Completed" : "Active"} task ${current.id} cannot be changed.`);
+  if (current.status === "completed" || current.status === "in_progress")
+    return current;
+  return {
+    ...current,
+    ...draft,
+    revision: changed ? current.revision + 1 : current.revision,
+    status: current.status === "blocked" ? "pending" : current.status,
+    owner: current.status === "blocked" ? undefined : current.owner,
+    executionId: current.status === "blocked" ? undefined : current.executionId,
+    blocker: current.status === "blocked" ? undefined : current.blocker
+  };
+}
+function newTask(draft) {
+  return { ...draft, revision: 0, status: "pending" };
+}
+function phaseContent(phase) {
+  return {
+    id: phase.id,
+    title: phase.title,
+    objective: phase.objective,
+    dependencies: phase.dependencies,
+    tasks: phase.tasks.map(taskContent)
+  };
+}
+function taskContent(task) {
+  return { id: task.id, title: task.title, dependencies: task.dependencies };
+}
+function nextPlanStatus(current) {
+  if (!current)
+    return "draft";
+  if (current.execution?.active)
+    return current.status === "blocked" ? "in_progress" : current.status;
+  return current.status === "ready" || current.status === "blocked" ? "draft" : current.status;
+}
+function assertCompleteRevision(document, briefs) {
+  const errors = [...validatePlanDocument(document, { strict: true }), ...validatePlanBriefs(document, briefs)].filter((issue) => issue.severity === "error");
+  if (errors.length)
+    throw new Error(`Invalid plan revision: ${errors.map((issue) => issue.message).join(" ")}`);
+}
+function sha256(value) {
+  return createHash3("sha256").update(value).digest("hex");
+}
 async function assertContained(root, candidate) {
   const canonicalRoot = await realpath4(root);
   let canonicalCandidate;
@@ -7972,7 +8307,10 @@ function stripDate(value) {
   return value.replace(/^\d{6}-/, "");
 }
 function titleFromSlug(value) {
-  return normalizeSlug(value).replace(/^(?:[a-z]+-\d+-)/, "").split("-").map((part) => part[0].toUpperCase() + part.slice(1)).join(" ");
+  const slug = normalizeSlug(value).replace(/^(?:[a-z]+-\d+-)/, "");
+  return slug.replace(/(^|-)([a-z])/g, (_match, separator, letter) => {
+    return `${separator ? " " : ""}${letter.toUpperCase()}`;
+  });
 }
 // src/setup.ts
 import { parseFrontmatter as parseFrontmatter3 } from "@earendil-works/pi-coding-agent";