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

package/agents/diffpi-planner.md

@@ -8,22 +8,22 @@ run_in_background: true
 model: openai-codex/gpt-5.6-sol
 model_fallbacks: meridian/claude-opus-4-8, meridian/claude-opus-5, deepseek/deepseek-v4-pro, qwen-token-plan/qwen3.7-plus
 thinking: high
-tools: read, grep, find, write, edit, Agent, get_subagent_result, steer_subagent, ask_user_question
+tools: read, grep, find, Agent, get_subagent_result, steer_subagent, ask_user_question, plan_context, plan_init, plan_apply_revision, plan_validate, plan_review
 metadata:
   model-tier: frontier
 ---
 
-You are the Diffpi planning agent. Execute the plan skill's direct file workflows to create repository-grounded plans and revise unfinished work. Read the selected workflow reference under `packages/pi/skills/plan/references/workflows/` before acting. Select one unique repository-root plan by its path and plan files, then read it before updating. Preserve the user's request and intent, including visible completed task information. Write authoritative plan files directly through successive normal read/write/edit calls. Do not edit source files or commit Git changes. After each iteration, invoke exactly one independently verified `diffpi-plan-reviewer` with explicit frontier/high selection, repair actionable findings, and rerun it within bounded attempts. If effective model or thinking selection cannot be verified, fail in preflight with the observed selection and required correction rather than using a cheap fallback.
+You are the Diffpi planning agent. Execute the plan skill's direct `plan_*` workflows to create repository-grounded plans and revise unfinished work. Read the selected workflow reference under `packages/pi/skills/plan/references/workflows/` before acting. Preserve incoming request text exactly when it is revision input. Do not emit command or copy-paste routing instructions, edit managed plan artifacts, edit source files, or commit Git changes. Author the entire plan and numbered briefs through one `plan_apply_revision` call per request.
 
 ## Plan quality
 
-- For NEW and UPDATE, identify the unique repository-root plan from its path and plan files and read it before changing it; do not use retired managed-plan lookup calls.
+- Call `plan_context` before changing, annotating, finalizing, or executing a plan.
 - Inspect the repository before proposing phases. Resolve research during planning; do not leave research tasks for implementation.
 - Keep stable lowercase phase and task IDs. Give each task explicit dependencies, file scopes, steps, and acceptance criteria.
 - Keep Design at 300 words or fewer when practical and never finalize it above 800 words.
 - Preserve completed work and evidence. Amend only draft, pending, or blocked work.
-- Read back every file after writing it and use the independent reviewer before marking a plan ready; a reviewer pass is not evidence that source code implements the plan.
-- The reviewer verifies the authoritative files after each iteration; do not require an immutable managed review read.
+- Call `plan_validate` after authoring and use strict validation before marking a plan ready.
+- Read the immutable plan review for the current plan revision before applying update instructions.
 
 Use `ask_user_question` for every interactive decision. Never ask a question in plain chat. When running in the background, do not ask questions. Record assumptions when safe; otherwise return a concise blocker that identifies the unresolved decision.
 

package/dist/cli.js

@@ -2384,8 +2384,8 @@ function appendBounded(current, next) {
 
 // src/plan/store.ts
 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";
+import { mkdir as mkdir3, readdir, readFile as readFile3, realpath as realpath3, rename as rename2, rm as rm2 } from "node:fs/promises";
+import { basename as basename3, dirname as dirname4, join as join7, resolve as resolve3, sep } from "node:path";
 
 // src/extensions/fsx.ts
 import { mkdir, rename, rm, writeFile } from "node:fs/promises";
@@ -2557,6 +2557,57 @@ 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);
 
@@ -3903,7 +3954,7 @@ var handle = {
 };
 
 // ../../node_modules/mdast-util-to-markdown/lib/join.js
-var join4 = [joinDefaults];
+var join6 = [joinDefaults];
 function joinDefaults(left, right, parent, state) {
   if (right.type === "code" && formatCodeAsIndented(right, state) && (left.type === "list" || left.type === right.type && formatCodeAsIndented(left, state))) {
     return false;
@@ -6449,7 +6500,7 @@ function toMarkdown(tree, options) {
     handle: undefined,
     indentLines,
     indexStack: [],
-    join: [...join4],
+    join: [...join6],
     options: {},
     safe: safeBound,
     stack: [],
@@ -6753,7 +6804,7 @@ import { default as default2 } from "node:path";
 import { default as default3 } from "node:process";
 
 // ../../node_modules/vfile/lib/minurl.js
-import { fileURLToPath } from "node:url";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // ../../node_modules/vfile/lib/minurl.shared.js
 function isUrl(fileUrlOrPath) {
@@ -6839,7 +6890,7 @@ class VFile {
   }
   set path(path) {
     if (isUrl(path)) {
-      path = fileURLToPath(path);
+      path = fileURLToPath2(path);
     }
     assertNonEmpty(path, "path");
     if (this.path !== path) {
@@ -7763,7 +7814,7 @@ async function resolvePlan(cwd, query, filters = {}, options = {}) {
       continue;
     if (normalizedQuery && entry.name !== normalizedQuery && stripDate(entry.name) !== normalizedQuery)
       continue;
-    const dir = join5(root, entry.name);
+    const dir = join7(root, entry.name);
     await assertContained(root, dir);
     try {
       const record = await readRecord(dir);
@@ -7798,30 +7849,26 @@ function createPlanStore(options = {}) {
     async init(input) {
       const root = await plansDir(input.cwd, options.homeDir);
       const id = planRecordName(input.shortSlug, now());
-      const dir = join5(root, id);
+      const dir = join7(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, join5(dir, "PLAN.md"));
+          issue_id: input.issueId?.trim() || "",
+          issue_url: input.issueUrl?.trim() || "",
+          created_at: timestamp,
+          updated_at: timestamp
+        });
+        const document = parsePlanDocument(source, join7(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, []);
@@ -7836,14 +7883,14 @@ function createPlanStore(options = {}) {
       if (request.mode === "create") {
         const root = await plansDir(cwd, options.homeDir);
         const id = planRecordName(request.shortSlug, now());
-        const dir = join5(root, id);
+        const dir = join7(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"));
+          parsePlanDocument(source, join7(dir, "PLAN.md"));
           await writeRevisionSnapshot(dir, document, source, request.request, request.briefs);
           await writeLatestView(dir, document, source, request.briefs);
           return await readRecord(dir);
@@ -7853,7 +7900,7 @@ function createPlanStore(options = {}) {
         }
       }
       const initial = await read(cwd, request.plan);
-      return withDirectoryLock(join5(initial.dir, ".lock"), async () => {
+      return withDirectoryLock(join7(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}.`);
@@ -7866,7 +7913,7 @@ function createPlanStore(options = {}) {
         try {
           await writeLatestView(current.dir, document, source, request.briefs);
         } catch (error) {
-          await rm2(join5(current.dir, "revisions", String(revision)), { recursive: true, force: true });
+          await rm2(join7(current.dir, "revisions", String(revision)), { recursive: true, force: true });
           throw error;
         }
         return await readRecord(current.dir);
@@ -7874,7 +7921,7 @@ function createPlanStore(options = {}) {
     },
     async mutate(cwd, query, operation, update) {
       const initial = await read(cwd, query);
-      return withDirectoryLock(join5(initial.dir, ".lock"), async () => {
+      return withDirectoryLock(join7(initial.dir, ".lock"), async () => {
         const current = await readRecord(initial.dir);
         const next = await update(structuredClone(current.document));
         if (next.id !== current.id)
@@ -7897,22 +7944,22 @@ function createPlanStore(options = {}) {
   };
 }
 async function readRecord(dir) {
-  const planPath = join5(dir, "PLAN.md");
-  const logPath = join5(dir, "logs.txt");
-  const source = await readFile2(planPath, "utf8");
+  const planPath = join7(dir, "PLAN.md");
+  const logPath = join7(dir, "logs.txt");
+  const source = await readFile3(planPath, "utf8");
   const document = parsePlanDocument(source, planPath);
   return {
     id: basename3(dir),
     dir,
     planPath,
     logPath,
-    implementationDir: join5(dir, "implementation"),
+    implementationDir: join7(dir, "implementation"),
     document,
     source
   };
 }
 async function createPlanDirectory(root, dir, id) {
-  await assertContained(root, dirname3(dir));
+  await assertContained(root, dirname4(dir));
   try {
     await mkdir3(dir);
   } catch (error) {
@@ -7926,17 +7973,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 = join5(planDir, "revisions");
+  const revisionsDir = join7(planDir, "revisions");
   await mkdir3(revisionsDir, { recursive: true });
-  const target = join5(revisionsDir, String(document.revision));
+  const target = join7(revisionsDir, String(document.revision));
   try {
-    await readFile2(join5(target, "metadata.json"), "utf8");
+    await readFile3(join7(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()}`);
+  const staging = join7(revisionsDir, `.tmp-${document.revision}-${randomUUID2()}`);
   await mkdir3(staging);
   try {
     const requestSource = request.kind === "annotation" ? `## Original annotation
@@ -7944,8 +7991,8 @@ ${request.text}
 
 ## LLM response
 ${request.response}` : request.text;
-    await atomicWrite(join5(staging, "request.md"), requestSource);
-    await atomicWrite(join5(staging, "metadata.json"), `${JSON.stringify({
+    await atomicWrite(join7(staging, "request.md"), requestSource);
+    await atomicWrite(join7(staging, "metadata.json"), `${JSON.stringify({
       schemaVersion: 1,
       id: document.id,
       revision: document.revision,
@@ -7955,7 +8002,7 @@ ${request.response}` : request.text;
       createdAt: document.updatedAt
     }, null, 2)}
 `);
-    await atomicWrite(join5(staging, "PLAN.md"), source);
+    await atomicWrite(join7(staging, "PLAN.md"), source);
     await writeImplementationDirectory(staging, document, briefs);
     await rename2(staging, target);
   } catch (error) {
@@ -7964,10 +8011,10 @@ ${request.response}` : request.text;
   }
 }
 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()}`);
+  const current = join7(planDir, "implementation");
+  const stagingRoot = join7(planDir, `.latest-${randomUUID2()}`);
+  const stagedImplementation = join7(stagingRoot, "implementation");
+  const backup = join7(planDir, `.implementation-backup-${randomUUID2()}`);
   await mkdir3(stagingRoot);
   await writeImplementationDirectory(stagingRoot, document, briefs);
   let backedUp = false;
@@ -7980,7 +8027,7 @@ async function writeLatestView(planDir, document, source, briefs) {
         throw error;
     }
     await rename2(stagedImplementation, current);
-    await atomicWrite(join5(planDir, "PLAN.md"), source);
+    await atomicWrite(join7(planDir, "PLAN.md"), source);
     if (backedUp)
       await rm2(backup, { recursive: true, force: true });
   } catch (error) {
@@ -7993,13 +8040,13 @@ async function writeLatestView(planDir, document, source, briefs) {
   }
 }
 async function writeImplementationDirectory(baseDir, document, briefs) {
-  const implementationDir = join5(baseDir, "implementation");
+  const implementationDir = join7(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));
+    await atomicWrite(join7(implementationDir, `phase-${index + 1}.md`), renderImplementationBrief(document.revision, index + 1, phase, brief));
   }
 }
 function normalizeRevision(current, request, id, revision, updatedAt) {
@@ -8151,8 +8198,8 @@ function titleFromSlug(value) {
   });
 }
 // src/plan/reviews.ts
-import { mkdir as mkdir4, readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
-import { dirname as dirname4, join as join6 } from "node:path";
+import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname5, join as join8 } from "node:path";
 async function createPlanReview(record, runtime = {}) {
   if (await readPlanReview(record))
     throw new Error(`Plan revision ${record.document.revision} already has a review.`);
@@ -8185,7 +8232,7 @@ async function readPlanReview(record) {
   const path = reviewPath(record);
   let source;
   try {
-    source = await readFile3(path, "utf8");
+    source = await readFile4(path, "utf8");
   } catch (error) {
     if (error.code === "ENOENT")
       return;
@@ -8202,10 +8249,10 @@ async function readPlanReview(record) {
   return { path, dump };
 }
 function reviewPath(record) {
-  return join6(record.dir, "reviews", `${record.document.revision}.json`);
+  return join8(record.dir, "reviews", `${record.document.revision}.json`);
 }
 async function writeReview(review) {
-  await mkdir4(dirname4(review.path), { recursive: true });
+  await mkdir4(dirname5(review.path), { recursive: true });
   await writeFile2(review.path, `${JSON.stringify(review.dump, null, 2)}
 `, {
     encoding: "utf8",