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

package/dist/tools/index.js

@@ -1290,7 +1290,7 @@ function sanitize(value) {
 }
 
 // src/tools/plan.ts
-import { join as join14 } from "node:path";
+import { join as join15 } from "node:path";
 import { pathToFileURL } from "node:url";
 import { defineTool as defineTool5 } from "@earendil-works/pi-coding-agent";
 import { z as z7 } from "zod";
@@ -7234,8 +7234,8 @@ function isPlanReviewDump(value) {
 
 // src/plan/store.ts
 import { createHash as createHash3, randomUUID as randomUUID2 } from "node:crypto";
-import { mkdir as mkdir6, readdir as readdir2, readFile as readFile7, realpath as realpath3, rename as rename2, rm as rm2 } from "node:fs/promises";
-import { basename as basename5, dirname as dirname7, join as join13, resolve as resolve3, sep } from "node:path";
+import { mkdir as mkdir6, readdir as readdir2, readFile as readFile8, realpath as realpath3, rename as rename2, rm as rm2 } from "node:fs/promises";
+import { basename as basename5, dirname as dirname7, join as join14, resolve as resolve3, sep } from "node:path";
 
 // src/extensions/fsx.ts
 import { mkdir as mkdir5, rename, rm, writeFile as writeFile4 } from "node:fs/promises";
@@ -7271,6 +7271,42 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// src/templates.ts
+import { readFile as readFile7 } from "node:fs/promises";
+import { homedir as homedir4 } from "node:os";
+import { join as join13, normalize } from "node:path";
+async function loadTemplate(name, options = {}) {
+  const relative = templateRelativePath(name);
+  const userPath = join13(options.homeDir ?? homedir4(), ".difflab", "diffpi", "templates", relative);
+  const bundledPath = join13(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 readFile7(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);
@@ -7286,7 +7322,7 @@ async function resolvePlan(cwd, query, filters = {}, options = {}) {
       continue;
     if (normalizedQuery && entry.name !== normalizedQuery && stripDate(entry.name) !== normalizedQuery)
       continue;
-    const dir = join13(root, entry.name);
+    const dir = join14(root, entry.name);
     await assertContained(root, dir);
     try {
       const record = await readRecord(dir);
@@ -7321,30 +7357,26 @@ function createPlanStore(options = {}) {
     async init(input) {
       const root = await plansDir(input.cwd, options.homeDir);
       const id = planRecordName(input.shortSlug, now());
-      const dir = join13(root, id);
+      const dir = join14(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 title = input.title?.trim() || titleFromSlug(input.shortSlug);
-        const document = {
-          schemaVersion: 1,
+        const source = renderTemplate(template.content, {
           id,
-          revision: 0,
-          title,
           branch: input.branch,
-          ...input.issueId?.trim() ? { issueId: input.issueId.trim() } : {},
-          ...input.issueUrl?.trim() ? { issueUrl: input.issueUrl.trim() } : {},
+          title,
           intent: input.intent?.trim() || "<!-- Describe the intended outcome. -->",
-          requirements: [],
-          design: { bigIdeas: "", keyApiUpdates: "", consequences: "" },
-          phases: [],
-          references: [],
-          status: "draft",
-          createdAt: timestamp,
-          updatedAt: timestamp
-        };
-        const source = renderPlanDocument(document);
-        parsePlanDocument(source, join13(dir, "PLAN.md"));
+          issue_id: input.issueId?.trim() || "",
+          issue_url: input.issueUrl?.trim() || "",
+          created_at: timestamp,
+          updated_at: timestamp
+        });
+        const document = parsePlanDocument(source, join14(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, []);
@@ -7359,14 +7391,14 @@ function createPlanStore(options = {}) {
       if (request.mode === "create") {
         const root = await plansDir(cwd, options.homeDir);
         const id = planRecordName(request.shortSlug, now());
-        const dir = join13(root, id);
+        const dir = join14(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, join13(dir, "PLAN.md"));
+          parsePlanDocument(source, join14(dir, "PLAN.md"));
           await writeRevisionSnapshot(dir, document, source, request.request, request.briefs);
           await writeLatestView(dir, document, source, request.briefs);
           return await readRecord(dir);
@@ -7376,7 +7408,7 @@ function createPlanStore(options = {}) {
         }
       }
       const initial = await read(cwd, request.plan);
-      return withDirectoryLock(join13(initial.dir, ".lock"), async () => {
+      return withDirectoryLock(join14(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}.`);
@@ -7389,7 +7421,7 @@ function createPlanStore(options = {}) {
         try {
           await writeLatestView(current.dir, document, source, request.briefs);
         } catch (error) {
-          await rm2(join13(current.dir, "revisions", String(revision)), { recursive: true, force: true });
+          await rm2(join14(current.dir, "revisions", String(revision)), { recursive: true, force: true });
           throw error;
         }
         return await readRecord(current.dir);
@@ -7397,7 +7429,7 @@ function createPlanStore(options = {}) {
     },
     async mutate(cwd, query, operation, update) {
       const initial = await read(cwd, query);
-      return withDirectoryLock(join13(initial.dir, ".lock"), async () => {
+      return withDirectoryLock(join14(initial.dir, ".lock"), async () => {
         const current = await readRecord(initial.dir);
         const next = await update(structuredClone(current.document));
         if (next.id !== current.id)
@@ -7420,16 +7452,16 @@ function createPlanStore(options = {}) {
   };
 }
 async function readRecord(dir) {
-  const planPath = join13(dir, "PLAN.md");
-  const logPath = join13(dir, "logs.txt");
-  const source = await readFile7(planPath, "utf8");
+  const planPath = join14(dir, "PLAN.md");
+  const logPath = join14(dir, "logs.txt");
+  const source = await readFile8(planPath, "utf8");
   const document = parsePlanDocument(source, planPath);
   return {
     id: basename5(dir),
     dir,
     planPath,
     logPath,
-    implementationDir: join13(dir, "implementation"),
+    implementationDir: join14(dir, "implementation"),
     document,
     source
   };
@@ -7449,17 +7481,17 @@ async function writeRevisionSnapshot(planDir, document, source, request, briefs)
     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 = join13(planDir, "revisions");
+  const revisionsDir = join14(planDir, "revisions");
   await mkdir6(revisionsDir, { recursive: true });
-  const target = join13(revisionsDir, String(document.revision));
+  const target = join14(revisionsDir, String(document.revision));
   try {
-    await readFile7(join13(target, "metadata.json"), "utf8");
+    await readFile8(join14(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 = join13(revisionsDir, `.tmp-${document.revision}-${randomUUID2()}`);
+  const staging = join14(revisionsDir, `.tmp-${document.revision}-${randomUUID2()}`);
   await mkdir6(staging);
   try {
     const requestSource = request.kind === "annotation" ? `## Original annotation
@@ -7467,8 +7499,8 @@ ${request.text}
 
 ## LLM response
 ${request.response}` : request.text;
-    await atomicWrite(join13(staging, "request.md"), requestSource);
-    await atomicWrite(join13(staging, "metadata.json"), `${JSON.stringify({
+    await atomicWrite(join14(staging, "request.md"), requestSource);
+    await atomicWrite(join14(staging, "metadata.json"), `${JSON.stringify({
       schemaVersion: 1,
       id: document.id,
       revision: document.revision,
@@ -7478,7 +7510,7 @@ ${request.response}` : request.text;
       createdAt: document.updatedAt
     }, null, 2)}
 `);
-    await atomicWrite(join13(staging, "PLAN.md"), source);
+    await atomicWrite(join14(staging, "PLAN.md"), source);
     await writeImplementationDirectory(staging, document, briefs);
     await rename2(staging, target);
   } catch (error) {
@@ -7487,10 +7519,10 @@ ${request.response}` : request.text;
   }
 }
 async function writeLatestView(planDir, document, source, briefs) {
-  const current = join13(planDir, "implementation");
-  const stagingRoot = join13(planDir, `.latest-${randomUUID2()}`);
-  const stagedImplementation = join13(stagingRoot, "implementation");
-  const backup = join13(planDir, `.implementation-backup-${randomUUID2()}`);
+  const current = join14(planDir, "implementation");
+  const stagingRoot = join14(planDir, `.latest-${randomUUID2()}`);
+  const stagedImplementation = join14(stagingRoot, "implementation");
+  const backup = join14(planDir, `.implementation-backup-${randomUUID2()}`);
   await mkdir6(stagingRoot);
   await writeImplementationDirectory(stagingRoot, document, briefs);
   let backedUp = false;
@@ -7503,7 +7535,7 @@ async function writeLatestView(planDir, document, source, briefs) {
         throw error;
     }
     await rename2(stagedImplementation, current);
-    await atomicWrite(join13(planDir, "PLAN.md"), source);
+    await atomicWrite(join14(planDir, "PLAN.md"), source);
     if (backedUp)
       await rm2(backup, { recursive: true, force: true });
   } catch (error) {
@@ -7516,13 +7548,13 @@ async function writeLatestView(planDir, document, source, briefs) {
   }
 }
 async function writeImplementationDirectory(baseDir, document, briefs) {
-  const implementationDir = join13(baseDir, "implementation");
+  const implementationDir = join14(baseDir, "implementation");
   await mkdir6(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(join13(implementationDir, `phase-${index + 1}.md`), renderImplementationBrief(document.revision, index + 1, phase, brief));
+    await atomicWrite(join14(implementationDir, `phase-${index + 1}.md`), renderImplementationBrief(document.revision, index + 1, phase, brief));
   }
 }
 function normalizeRevision(current, request, id, revision, updatedAt) {
@@ -8008,7 +8040,7 @@ function createPlanTools(_pi, _modes, store = createPlanStore()) {
         const resolution = await store.context(workingDirectory, params.plan);
         if (!resolution.record)
           throw new Error(resolution.ambiguous ? `Plan is ambiguous: ${resolution.candidates.map((item) => item.id).join(", ")}.` : "No matching plan.");
-        const cliPath = join14(resolveBundledAgentsDir(), "..", "dist", "cli.js");
+        const cliPath = join15(resolveBundledAgentsDir(), "..", "dist", "cli.js");
         const command = [
           process.execPath,
           cliPath,
@@ -8808,10 +8840,10 @@ function hasGitlabDraftNotes(input) {
 }
 
 // src/review/local-review-backend.ts
-import { readFile as readFile9, writeFile as writeFile5 } from "node:fs/promises";
+import { readFile as readFile10, writeFile as writeFile5 } from "node:fs/promises";
 
 // src/extensions/tuicrx.ts
-import { readFile as readFile8, realpath as realpath4 } from "node:fs/promises";
+import { readFile as readFile9, realpath as realpath4 } from "node:fs/promises";
 import { resolve as resolve4 } from "node:path";
 async function tuicrAvailable() {
   return Boolean(await findExecutable("tuicr"));
@@ -8908,7 +8940,7 @@ async function findMatchingSession(sessions, cwd, branch) {
   return;
 }
 async function readSession(path) {
-  const content = await readFile8(path, "utf8");
+  const content = await readFile9(path, "utf8");
   try {
     return JSON.parse(content);
   } catch {
@@ -9029,7 +9061,7 @@ function LocalReviewBackend(options) {
     },
     async listThreads() {
       try {
-        return parseThreadArtifact(await readFile9(options.artifactPath, "utf8"));
+        return parseThreadArtifact(await readFile10(options.artifactPath, "utf8"));
       } catch (error) {
         if (error.code === "ENOENT")
           return [];
@@ -9037,7 +9069,7 @@ function LocalReviewBackend(options) {
       }
     },
     async reply(input) {
-      const content = await readFile9(options.artifactPath, "utf8");
+      const content = await readFile10(options.artifactPath, "utf8");
       await writeFile5(options.artifactPath, upsertThreadReply(content, input.threadId, input.body, input.question, input.resolve), "utf8");
     },
     async publish() {
@@ -9059,8 +9091,8 @@ function createLocalReviewBackend(options) {
 }
 // src/review/review-state.ts
 import { createHash as createHash4 } from "node:crypto";
-import { readFile as readFile10, rename as rename3, writeFile as writeFile6 } from "node:fs/promises";
-import { join as join15 } from "node:path";
+import { readFile as readFile11, rename as rename3, writeFile as writeFile6 } from "node:fs/promises";
+import { join as join16 } from "node:path";
 import { z as z10 } from "zod";
 var reviewPublicationStateSchema = z10.object({
   target: z10.string().optional(),
@@ -9084,9 +9116,9 @@ function unpublishedReviewComments(comments, knownFingerprints) {
 }
 async function loadReviewPublicationState(cwd, vcs, number, homeDir) {
   const target = `${vcs.provider}:${vcs.owner}/${vcs.repo}#${number}`;
-  const path = join15(await sessionsDir(cwd, homeDir), `review-publish-${digest(target).slice(0, 16)}.json`);
+  const path = join16(await sessionsDir(cwd, homeDir), `review-publish-${digest(target).slice(0, 16)}.json`);
   try {
-    const parsed = reviewPublicationStateSchema.parse(JSON.parse(await readFile10(path, "utf8")));
+    const parsed = reviewPublicationStateSchema.parse(JSON.parse(await readFile11(path, "utf8")));
     return { path, state: { ...parsed, target } };
   } catch (error) {
     if (error.code === "ENOENT") {
@@ -9107,42 +9139,6 @@ async function saveReviewPublicationState(path, state) {
 function digest(value) {
   return createHash4("sha256").update(value).digest("hex");
 }
-// src/templates.ts
-import { readFile as readFile11 } from "node:fs/promises";
-import { homedir as homedir4 } from "node:os";
-import { join as join16, normalize } from "node:path";
-async function loadTemplate(name, options = {}) {
-  const relative = templateRelativePath(name);
-  const userPath = join16(options.homeDir ?? homedir4(), ".difflab", "diffpi", "templates", relative);
-  const bundledPath = join16(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 readFile11(path, "utf8");
-  } catch (error) {
-    if (error.code === "ENOENT")
-      return;
-    throw error;
-  }
-}
-
 // src/tools/review.ts
 var contextSchema = z11.object({
   cwd: z11.string().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@difflab/pi",
-  "version": "0.7.0-rc.202609271854.6af8600",
+  "version": "0.7.0",
   "description": "Tools and skills for the pi coding agent",
   "repository": {
     "type": "git",

package/skills/plan/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: plan
 description: Create, revise, annotate, finalize, and execute durable Diffpi plans. Use for /skill:plan, /plan, or natural-language planning requests.
-allowed-tools: read grep find write edit symbol_search module_report read_symbol ask_user_question Agent get_subagent_result steer_subagent plan_context plan_annotate plan_start_execution plan_update_status plan_log_progress plan_run_gates plan_record_ci watch_ci
+allowed-tools: read grep find symbol_search module_report read_symbol ask_user_question Agent get_subagent_result steer_subagent plan_context plan_init plan_apply_revision plan_validate plan_review plan_annotate plan_start_execution plan_update_status plan_log_progress plan_run_gates plan_record_ci watch_ci
 ---
 
 # Plan
 
-This skill owns the workflow. `/plan` only forwards its raw arguments to `/skill:plan`. Do not emit another command to paste or rely on a command handler to select an agent, parse flags, or inject a workflow. For NEW and UPDATE, use ordinary file tools to edit the authoritative live PLAN.md and implementation brief files. Never use file tools to alter immutable legacy snapshots, revisions, reviews, or logs; remaining references to those managed artifacts are transitional guidance pending phase 4.
+This skill owns the workflow. `/plan` only forwards its raw arguments to `/skill:plan`. Do not emit another command to paste or rely on a command handler to select an agent, parse flags, or inject a workflow. Call plan tools directly; never edit managed PLAN.md, implementation briefs, revisions, reviews, or logs with file tools.
 
-Identify the first explicit verb (`init`, `new`, `update`, `annotate`, `finalize`, `go`, `help`) or infer one from the user's request. For NEW and UPDATE, select one unique repository-root plan by path and its plan files, and read it before acting; ask only for a material decision if the plan remains ambiguous. Read exactly the corresponding [workflow reference](references/workflows/) before acting. Preserve the user's request and intent, including visible completed task information; this is authoring input, not a managed revision transaction.
+Identify the first explicit verb (`init`, `new`, `update`, `annotate`, `finalize`, `go`, `help`) or infer one from the user's request. If the verb or required plan is ambiguous, call `plan_context` and ask only for a material decision using `ask_user_question`. Read exactly the corresponding [workflow reference](references/workflows/) before acting. Preserve the exact incoming user request (and applied review feedback) as revision input; do not paraphrase it.
 
-`new` creates a complete plan without launching an editor; `init` creates a phase-less draft and opens it. For NEW and UPDATE content changes, write the authoritative live PLAN.md and numbered briefs directly through successive normal read/write/edit calls, then read back each file. Invoke exactly one independently verified frontier/high-thinking `diffpi-plan-reviewer` per iteration; repair actionable findings and rerun it within bounded attempts. If effective model/thinking selection cannot be verified, fail preflight with the exact observed selection and required correction; do not silently promise runtime verification. Phase/task status and execution gates remain managed-tool concerns. The remaining init/annotate/finalize/go references retain old managed-tool calls only as transitional guidance until phase 4 replaces them; they must not be presented as Planner capabilities. `go` calls `plan_start_execution` before any code change; if the plan is draft or on the wrong branch, stop.
+`new` creates a complete plan without launching an editor; `init` creates a phase-less draft and opens it. For content changes, build a complete candidate and apply it **once per user request** with `plan_apply_revision`. Phase/task status and gates use their dedicated tools and do not constitute a new content revision. Strict `plan_validate` checks document and brief structure, not whether source code implements the plan. `go` calls `plan_start_execution` before any code change; if the plan is draft or on the wrong branch, stop.
 
 `--bg` requests one named background agent through `Agent` (Planner for authoring, Orchestrator for execution); pass the verb, exact arguments, cwd, and a `background: true` instruction. Remove `--bg` from the child's request and explicitly forbid redispatch. Return after launching it. A background child must not ask user questions. If `Agent` is unavailable, stop and report that background execution cannot be started; never silently execute inline. Without `--bg`, execute in the current turn: author as Planner, coordinate go as Orchestrator and delegate bounded Worker tasks; do not assume an inline mode switch occurred. Do not launch a multi-agent workflow unless the user explicitly opts into one.
 
-Operational references: [init](references/workflows/init.md), [new](references/workflows/new.md), [update](references/workflows/update.md), [annotate](references/workflows/annotate.md), [finalize](references/workflows/finalize.md), [go](references/workflows/go.md), [help](references/workflows/help.md). NEW and UPDATE use direct authoritative file writes. The init/annotate/finalize/go references are transitional managed-tool guidance until phase 4 replaces them.
+Operational references: [init](references/workflows/init.md), [new](references/workflows/new.md), [update](references/workflows/update.md), [annotate](references/workflows/annotate.md), [finalize](references/workflows/finalize.md), [go](references/workflows/go.md), [help](references/workflows/help.md).

package/skills/plan/references/design-quality.md

@@ -1,30 +1,41 @@
 # Plan authoring quality
 
-Build from repository evidence. Keep the result compact and useful to a Worker.
+Build the design from repository evidence, not generic slogans. Keep it concise enough to scan, but never shrink a section into an uninformative one-line paragraph just to reach a word count.
 
-## PLAN.md
+## Big Ideas
 
-- Keep intent, requirements, design, references, and numbered phases in `PLAN.md`.
-- Give each phase a stable ID, title, objective, and prerequisites. Prerequisites belong to phases only.
-- Put each discrete implementation action in a flat task checkbox with a stable task ID and title. Do not put dependency metadata, steps, file scopes, or acceptance criteria under the checkbox.
-- Preserve phase/task ID and order parity in every implementation brief.
+Use outcome-oriented bullets. Each bullet says what will become different and why it belongs in this plan; do not repeat the phase titles. For example:
 
-## Implementation brief
+- Keep task status and phase ordering in `PLAN.md` so readers can see progress without reading implementation instructions.
+- Write one numbered brief per phase so Workers receive concrete steps and file/API contracts.
+- Reject incomplete briefs at finalization instead of handing placeholders to execution agents.
 
-- Give tasks ordered implementation steps. Add nested `Verify` bullets under the relevant task; verification is part of the task, not a separate task.
-- List exact file scopes and acceptance criteria for every task.
-- Put libraries and algorithms under **Implementation Constraints**.
-- Include exactly one fenced `text` phase-level directory tree. Label every file leaf with one of `[ADD]`, `[MODIFY]`, `[REMOVE]`, `[MOVE from: path]`, or `[VERIFY]`.
-- Read back each file after writing it. Normal successive write/edit calls are intentional: incomplete drafts remain visible until the plan is ready.
+## Key API Addition/Updates
 
-## Review and repair
+Use explanatory paragraphs and illustrative fenced examples showing the actual public call and data contract. Explain which previous call is removed, who calls the new API, what arguments/return value mean, and how errors are surfaced. Do not invent details that the repository has not established; call out a genuine unresolved choice instead. For example:
 
-Template metadata such as revision snapshots and managed markers is not an authoring requirement. Treat their removal as a legacy compatibility change: the existing managed parser will stop recognizing these templates until the follow-on source migration adds a replacement contract. Report that break explicitly; do not preserve metadata in the templates solely to hide it.
+```ts
+await plan_apply_revision({
+  mode: 'amend', // use 'create' with shortSlug instead for revision 0
+  plan,
+  expectedPlanRevision,
+  request: { kind: 'user', text: exactRequest },
+  title,
+  intent,
+  requirements,
+  design: { bigIdeas, keyApiUpdates, consequences },
+  references,
+  phases,
+  briefs,
+});
+```
 
-After writing the current `PLAN.md` and all numbered briefs, independently invoke exactly one VERIFIED frontier/high-thinking `diffpi-plan-reviewer` in read-only mode. The reviewer checks structure and parity, action labels, whole-plan quality, consistency and risk, and whether every task is executable by a lightweight Worker without guessing, in one pass. Do not replace this with cheap separate reviewers or tiered checks.
+Follow the example with a paragraph describing revision creation and validation, then another covering old mutators or callers being replaced. `mode: 'create'` instead takes `shortSlug` (and optional branch/issue fields) and writes revision 0 directly; `mode: 'amend'` takes `plan` and `expectedPlanRevision` and writes the next revision. Both modes require the same `request`, overview fields, ordered `phases`, and matching `briefs`; there is no `inputs` field and no separate `complete` field. If no public API changes, say so explicitly and show the relevant internal interface or data flow instead.
 
-The Planner repairs actionable findings and reruns the same reviewer within bounded attempts. A passing review does not prove that source code implements the plan. `annotate` is optional human review; it does not replace the automated reviewer.
+## Consequences
 
-## Contracts and consequences
+Write distinct before/after paragraphs: how a user invokes the workflow, what a client or Worker reads/calls, and how failure looks. Describe concrete behavior: editor launch, status transitions, validation, snapshots, and review visibility as applicable. Include at least one trade-off, such as storage cost or compatibility break; do not substitute a generic maintainability claim.
 
-Describe real API or data-flow changes. If there is no public API change, say so and show the relevant internal contract. Explain before/after invocation, what readers or Workers consume, validation and failure visibility, and at least one concrete trade-off. Do not use scaffold placeholders in a plan marked ready.
+## PLAN.md versus briefs
+
+Under each PLAN.md phase, make **each discrete implementation action a separate stable task checkbox**. Do not embed Steps, File scopes, or Acceptance criteria below its checkbox. In `implementation/phase-<ordinal>.md`, relist every stable task ID and title and provide ordered implementation steps, exact affected files, API/data-contract changes, algorithms/libraries, constraints, and acceptance criteria. A lightweight Worker must be able to implement the task from the brief without guessing. Before finalization, inspect each rendered brief and require strict validation; no scaffold comments or “define during implementation” placeholders are acceptable.

package/skills/plan/references/workflows/new.md

@@ -1,7 +1,7 @@
 # New
 
-1. Resolve the initiating nested Git root and the requested slug/branch, then inspect for a plan collision. If a matching plan already exists, stop. Only after confirming no matching plan exists, research and create the plan; do not read a nonexistent plan. If the goal is unspecified in foreground mode, ask one material question; background work must report a blocker instead.
-2. Research repository files, APIs, tests, and constraints. Follow [plan authoring quality](../design-quality.md). Draft the complete PLAN.md and one numbered brief per phase. Preserve the user's request and intent in the visible plan content, including any visible completed task information; this is authoring input, not a revision transaction.
-3. Write the plan directory directly with normal `write`/`edit` calls. Write PLAN.md and briefs incrementally so incomplete files remain visible. Do not call `plan_apply_revision`, `plan_validate`, or edit managed snapshots. Include exact scopes, ordered steps, constraints, acceptance criteria, task parity, one action-labeled tree per brief, and nested verification.
-4. Read back every written file. Invoke exactly one `diffpi-plan-reviewer` over PLAN.md and all numbered briefs in a single pass. Before relying on its result, verify the effective model is the explicit frontier model (prefer `openai-codex/gpt-5.6-sol`, or an available equivalent), thinking is high, and tools are read/search-only. If selection cannot be verified, fail preflight with the exact observed model/thinking/tools and required correction; do not silently promise runtime verification or use a cheap fallback.
-5. Repair actionable findings directly, then rerun the same reviewer within bounded attempts. A pass checks plan quality only; it does not prove source implementation. Report plan and brief paths, review evidence, and any compatibility caveat. Policy governs the plan-file source scope; this is not a Pi sandbox guarantee.
+1. Call `plan_context` for the supplied slug and branch. If a matching plan already exists, stop rather than silently overwriting it. If the goal is unspecified in foreground mode, use `ask_user_question` for the material scope decision; in background mode, state a blocker if no safe assumption exists.
+2. Research the relevant repository files, APIs, tests, and constraints before drafting. Follow [plan authoring quality](../design-quality.md): substantive Big Ideas bullets, illustrated API contracts, explicit before/after consequences, one stable PLAN.md task per implementation action, and a fully specified numbered brief per phase. Each brief must use numbered phase files, preserve exact phase/task IDs and order parity with PLAN.md, give ordered steps, exact file scopes, API/data contracts, algorithms/libraries, constraints, and acceptance criteria; inspect every rendered brief strictly for accuracy and completeness.
+3. Preserve the exact user request as a typed revision input. Build the **complete** candidate overview, ordered phases and task IDs, and matching briefs in memory. Call `plan_apply_revision` **once** with `mode: "create"`, the short slug, `request: {kind: "user", text: <exact incoming request>}`, a full overview and phase list, and one complete brief per phase; `create` writes revision 0 directly, so `/plan new` works without `plan_init`; do not create a phase-less shell first or open an editor.
+4. Validate the result strictly and inspect the generated brief paths. If any placeholders, missing task steps, mismatched IDs, or incomplete sections remain, report the failure rather than claiming readiness. A validation result is structural, not a check that source code already implements the plan.
+5. Report the plan ID and paths. Continue discussing changes in the same conversation; a later user request is a separate revision. Offer `annotate` for human review and `finalize` when ready, without making the user paste a command merely to continue this request.

package/skills/plan/references/workflows/update.md

@@ -1,7 +1,7 @@
 # Update
 
-1. Select exactly one unique repository-root plan by its path and plan files. Read the current PLAN.md, all numbered briefs, and the incoming request. Preserve the user's intent and all visible completed task information, including IDs, ownership, evidence, and dependencies.
-2. Research affected repository files and follow [plan authoring quality](../design-quality.md). Build the entire resulting PLAN.md and numbered briefs in memory, preserving exact phase/task order parity. Do not guess among plans or rewrite historical records.
-3. Apply the update through successive direct `write`/`edit` calls to the authoritative plan files. Do not call `plan_apply_revision`, `plan_validate`, or edit managed snapshots. Read back each file after writing. New files remain visible while incomplete.
-4. Invoke exactly one `diffpi-plan-reviewer` over the current PLAN.md and every numbered brief in one pass. Verify its effective model is the explicit frontier model (prefer `openai-codex/gpt-5.6-sol`, or an available equivalent), thinking is high, and capabilities are read/search-only. If effective selection cannot be verified, fail preflight with the exact observed model/thinking/tools and required correction; never silently promise runtime verification or accept a cheap fallback.
-5. Repair actionable findings directly and rerun the same reviewer within bounded attempts. Report changed files, review evidence, remaining blocker, and compatibility caveat. A passing review is structural/semantic plan evidence only, not proof source code implements the plan. Policy governs the plan-file source scope; this is not a Pi sandbox guarantee.
+1. Call `plan_context` for the slug/branch; never guess among multiple candidates. Call `plan_review` once for the selected current revision before interpreting the request. A review of an older revision is stale; do not reapply it.
+2. Preserve the exact incoming request in `request.text` and select `request.kind` (`user`, `annotation`, or `blocker`) according to the trigger. When applying a plan review, read its full feedback; when unblocking execution, preserve the worker's blocker in the request. For annotation requests, include the exact LLM response/outcome in `request.response` and classify every comment as applied, answered, or unresolved with a concrete reason. Do not use vague “later” or “follow-up” deferrals unless the user explicitly requested that deferral. Research affected source files. Follow [plan authoring quality](../design-quality.md), including substantive Design sections and complete per-task implementation briefs. For both new and amended content, briefs must use numbered phase files, exact phase/task ID and order parity, ordered steps, exact file scopes, API/data contracts, algorithms/libraries, constraints, and acceptance criteria; strictly inspect every rendered brief for accuracy and completeness.
+3. Build the **entire resulting plan and numbered briefs in memory**, preserving completed task IDs, ownership, evidence, and dependencies. For a single authoring request, call `plan_apply_revision` with `mode: "amend"` exactly once, passing `plan`, `expectedPlanRevision`, `request`, the entire overview, ordered phases, and matching briefs. Do not mutate overview/phase/task content with separate tools, edit managed files by hand, or create a revision per comment.
+4. In foreground mode, ask only for missing decisions that materially affect scope; background work must not ask. Strictly validate the saved plan and briefs; stop with precise errors if they are incomplete. Do not treat structural validation as evidence that implementation already meets requirements.
+5. Report the one new revision and its snapshot path, what changed, and any remaining blocker. Further chat instructions form a future separate revision; `annotate` reviews the plan and `finalize` marks it ready.

package/templates/plan/PLAN.md

@@ -1,10 +1,13 @@
+<!-- diffpi-plan: {"schemaVersion":1,"id":"{{id}}","revision":0,"branch":"{{branch}}","issueId":"{{issue_id}}","issueUrl":"{{issue_url}}","status":"draft","createdAt":"{{created_at}}","updatedAt":"{{updated_at}}"} -->
+
 # {{title}}
 
 - **Plan ID:** {{id}}
 - **Branch:** {{branch}}
-- **Status:** draft
 - **Issue:** {{issue_id}}
 - **Issue URL:** {{issue_url}}
+- **Status:** draft
+- **Revision:** 0
 
 ## Intent
 
@@ -12,35 +15,26 @@
 
 ## Requirements
 
-<!-- Add concrete requirements. -->
+<!-- Add requirements. -->
 
 ## Design
 
 ### Big Ideas
 
-<!-- Describe the outcome-oriented design. -->
+<!-- Describe the main approach. -->
 
 ### Key API Addition/Updates
 
-<!-- Describe public or internal contract changes. -->
+<!-- Describe public API changes. -->
 
 ### Consequences
 
-<!-- Describe before/after behavior, risks, and trade-offs. -->
-
-## Phases
-
-<!-- Use numbered phases. State prerequisites on the phase only; do not add task dependencies here. -->
-
-### Phase 1: <!-- phase title -->
+<!-- Describe trade-offs and limitations. -->
 
-- **Phase ID:** <!-- assign a stable phase ID -->
-- **Prerequisites:** <!-- list phase IDs, or “None” -->
-- **Objective:** <!-- state the outcome -->
+## Implementation
 
-- [ ] <!-- assign a stable task ID --> Task title
-- [ ] <!-- assign a stable task ID --> Another task title
+<!-- Add phases with one complete plan_apply_revision request. -->
 
 ## References
 
-<!-- Add repository or external references. -->
+<!-- Add references. -->