@difflab/pi 0.7.0-rc.202609280043.c43aa2b → 0.7.0-rc.202609280945.f13c54b

package/README.md

@@ -40,7 +40,7 @@ The skill selects and verifies the Planner or Orchestrator inline profile for fo
 
 `diffpi plan annotate <PLAN.md|directory>` opens the live plan in `tuicr --file`; it does not save a managed review. Zed setup installs the pinned `diffpi: annotate plan` task. Override the plan template at `~/.difflab/diffpi/templates/plan/PLAN.md`.
 
-`PLAN.md` keeps Design, numbered phases, phase prerequisites, and flat task checkboxes. Each brief contains ordered steps, nested verification, acceptance criteria, and one action-labeled phase file tree as its sole exact file scope. No per-task or `PLAN.md` file scopes. The Orchestrator alone updates execution status, runs project gates, and owns phase Git/CI actions. `--mode commit` creates one local conventional commit per completed phase. `--mode push` pushes each commit and waits for exact-SHA `watch_ci` results before advancing. Workers only edit source/test scopes derived from their task steps and the phase tree; uncertain or overlapping scopes are serialized.
+`PLAN.md` keeps Design, numbered phases, phase prerequisites, phase constraints (or `None`), and flat task checkboxes. Each brief places a single action-labeled file tree in a fenced `text` block under `## Files Affected` immediately after `## Objective` (not bullet paths); tasks have ordered steps, nested verification, and acceptance criteria. `## Implementation Constraints` accepts free-form guidance with optional Required Libraries & Technology Choices, Key Algorithm Specifications, and Core Invariants headings. No per-task or `PLAN.md` file scopes. Keep phase-wide guardrails in `PLAN.md` and implementation details in briefs without repeating or paraphrasing the guardrails. The Orchestrator alone updates execution status, runs project gates, and owns phase Git/CI actions. `--mode commit` creates one local conventional commit per completed phase. `--mode push` pushes each commit and waits for exact-SHA `watch_ci` results before advancing. Workers only edit source/test scopes derived from their task steps and the Files Affected tree; uncertain or overlapping scopes are serialized.
 
 ## Review
 

package/agents/diffpi-orchestrator.md

@@ -33,7 +33,7 @@ Work as the execution orchestrator for the plan skill. Coordinate live plan file
 
 For a background review dispatch, create exactly one named background `reviewer` child for the selected workflow; the child must not recurse or dispatch another review child. Keep review lifecycle decisions in this orchestration turn.
 
-For background plan execution, read the live plan and honor its execution state. Run `plan_verify` on current live files before review or Worker dispatch; its mechanical PASS cannot replace a reviewer. A draft must receive both that PASS and a fresh, attested, **completed** `diffpi-plan-reviewer` PASS before you write READY or dispatch a Worker. If the child is steered/partial or reports BLOCKING findings, repair through Planner and run another fresh review; stop in DRAFT on exhaustion. A repair alone is never approval. Process phases in dependency order. The phase brief's single file tree is the only declared file scope. Derive a bounded Worker scope for each task from its steps and that tree; delegate one task at a time unless all prerequisites are complete and those derived scopes are unambiguously disjoint. Missing or uncertain task-to-file mapping always serializes Workers. Delegated workers never commit or restructure the plan. Reload plan state and persist each result before scheduling more work.
+For background plan execution, read the live plan and honor its execution state. Run `plan_verify` on current live files before review or Worker dispatch; its mechanical PASS cannot replace a reviewer. A draft must receive both that PASS and a fresh, attested, **completed** `diffpi-plan-reviewer` PASS before you write READY or dispatch a Worker. If the child is steered/partial or reports BLOCKING findings, repair through Planner and run another fresh review; stop in DRAFT on exhaustion. A repair alone is never approval. Process phases in dependency order. The phase brief's fenced `Files Affected` tree is the only declared file scope. Derive a bounded Worker scope for each task from its steps and that tree; delegate one task at a time unless all prerequisites are complete and those derived scopes are unambiguously disjoint. Missing or uncertain task-to-file mapping always serializes Workers. Delegated workers never commit or restructure the plan. Reload plan state and persist each result before scheduling more work.
 
 After all phase tasks complete or skip, run project gates with bash or ctx_execute. A failure or warning blocks the phase. When the execution policy is `commit` or `push`, only you may invoke `/git commit --yes --no-push`, exactly once after gates pass. In `commit` mode, record the local SHA and do not push. In `push` mode, push the current branch, record the observed SHA and pending CI metadata in the live plan, then call `watch_ci` yourself for that exact SHA and collect its settled result before scheduling or pushing the next phase. Do not delegate CI monitoring to Worker. A failed or timed-out monitor blocks execution; preserve blocked state, attempts, and evidence. Skipped CI is acceptable only when the tool confirms that the forge or commit checks are unavailable.
 

package/agents/diffpi-plan-reviewer.md

@@ -23,10 +23,10 @@ Then, in one pass, read the current PLAN.md and every numbered phase brief selec
 
 Check all of these together:
 
-- Structure and parity: the live plan is directly under `.diffpi/plan/<YYMMDD[-ticket]-short-slug>/` (never nested `date/slug`), and `PLAN.md` uses `## Phases` and numbered `### Phase N:` headings, phase-only prerequisites, flat task checkboxes without nested task dependencies, ordered stable IDs, and exact task ID/title parity with every numbered brief.
-- Action-labeled trees: exactly one `## Phase File Tree` fenced `text` tree per brief; every file leaf starts with `[ADD]`, `[MODIFY]`, `[REMOVE]`, `[MOVE from: path]`, or `[VERIFY]` immediately after its tree branch (suffix labels are invalid). Verification is nested under its task.
-- Whole-plan quality: substantive intent, requirements, design, APIs/data flow, consequences, constraints, consistency, risks, and useful references.
-- Worker executability: every task has ordered steps, implementation constraints, acceptance criteria, and enough context for a lightweight Worker to act without guessing; the phase-level tree is the sole exact file scope.
+- Structure and parity: the live plan is directly under `.diffpi/plan/<YYMMDD[-ticket]-short-slug>/` (never nested `date/slug`), and `PLAN.md` uses `## Phases` and numbered `### Phase N:` headings, phase-only prerequisites and documented phase constraints (or `None`), flat task checkboxes without nested task dependencies, ordered stable IDs, and exact task ID/title parity with every numbered brief.
+- Files Affected: each brief has exactly one `## Files Affected` immediately after `## Objective` and before `## Tasks`. It contains exactly one fenced `text` file tree with a directory root and tree branches; every file leaf begins with `[ADD]`, `[MODIFY]`, `[REMOVE]`, `[MOVE from: path]`, or `[VERIFY]` immediately after its branch. Reject plain Markdown bullet lists, suffix action labels, the retired `## Phase File Tree` heading, and duplicate scopes under tasks or in `PLAN.md`. Verification is nested under its task.
+- Whole-plan quality: substantive intent, requirements, design, APIs/data flow, consequences, phase constraints in `PLAN.md`, consistency, risks, and useful references.
+- Worker executability: every task has ordered steps, acceptance criteria, and enough free-form `## Implementation Constraints` guidance for a lightweight Worker to act without guessing. Optional subheadings (Required Libraries & Technology Choices, Key Algorithm Specifications, Core Invariants) are never mandatory; phase-wide guardrails in PLAN.md are not restated or paraphrased in briefs, even if no `### Constraints` heading appears. The `Files Affected` tree is the sole exact file scope.
 
 Inspect the complete plan set in this single pass; do not substitute a brief sample or separate partial reviews. Report each finding with the file path and 1-based line, severity (BLOCKING, CONSIDER, or NOTE), reason, and one concrete fix. Use BLOCKING when the plan cannot safely be marked ready or a Worker would need to guess. Return an explicit pass only when all checks pass. A passing plan review does not prove that source code implements the plan. This review is read-only policy, not a sandbox; the caller must independently verify runtime status evidence. Never persist a `plan_review` artifact.
 

package/agents/diffpi-planner.md

@@ -22,7 +22,7 @@ You are the Diffpi planning agent. Execute the plan skill's direct file workflow
 
 - 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.
 - Inspect the repository before proposing phases. Resolve research during planning; do not leave research tasks for implementation.
-- Keep stable lowercase phase and task IDs. Put prerequisites on phases only; give each task ordered steps and acceptance criteria. Put exact file scopes ONLY in one action-labeled Phase File Tree per implementation brief, never under a task or in PLAN.md.
+- Keep stable lowercase phase and task IDs. Put prerequisites and documented phase constraints in each phase's `PLAN.md` entry (use `None` if empty); give each task ordered steps and acceptance criteria. Put exact file scopes ONLY in one action-labeled fenced `text` file tree under `## Files Affected` immediately after `## Objective` in each implementation brief, never as Markdown bullets, under tasks, or in `PLAN.md`. Keep PLAN.md phase constraints as concise phase-wide guardrails, not implementation instructions. `## Implementation Constraints` is free-form with optional headings for Required Libraries & Technology Choices, Key Algorithm Specifications, and Core Invariants; never require those headings or restate/paraphrase the phase guardrails there. Refer back to the phase ID instead.
 - 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.

package/dist/extensions/index.js

@@ -14803,183 +14803,8 @@ import { z as z5 } from "zod";
 
 // src/plan/verify.ts
 import { readFile as readFile6, readdir as readdir2, stat } from "node:fs/promises";
-import { basename as basename4, join as join12, resolve as resolve4 } from "node:path";
+import { basename as basename4, dirname as dirname5, join as join12, resolve as resolve4 } from "node:path";
 async function verifyLivePlan(requested, cwd = process.cwd()) {
-  return verifyLivePlanInternal(requested, cwd);
-}
-function linesOf(source) {
-  let fenced = false;
-  return source.split(/\r?\n/).map((line) => {
-    if (/^\s*```/.test(line)) {
-      fenced = !fenced;
-      return "";
-    }
-    return fenced ? "" : line;
-  });
-}
-function issue(issues, file, line, code, message) {
-  issues.push({ file, line, code, message });
-}
-function field(lines, start, end, name) {
-  const label = `- **${name}:**`;
-  for (let i = start;i < end; i++) {
-    if (lines[i]?.trimStart().startsWith(label)) {
-      return { value: lines[i].trimStart().slice(label.length).trim(), line: i + 1 };
-    }
-  }
-  return;
-}
-function heading(lines, text) {
-  return lines.flatMap((line, i) => line.trim() === text ? [i] : []);
-}
-function requireSection(lines, file, text, issues) {
-  const matches = heading(lines, text);
-  if (matches.length !== 1)
-    issue(issues, file, matches[0] === undefined ? 0 : matches[0] + 1, "section", `Expected exactly one ${text} section.`);
-  return matches[0] ?? -1;
-}
-function parsePlan(source, file, issues) {
-  const lines = linesOf(source);
-  for (const name of ["Intent", "Requirements", "Design", "Phases", "References"]) {
-    requireSection(lines, file, `## ${name}`, issues);
-  }
-  for (const name of ["Plan ID", "Branch", "Status"]) {
-    const entry = field(lines, 0, lines.length, name);
-    if (!entry?.value)
-      issue(issues, file, entry?.line ?? 0, "metadata", `Missing ${name}.`);
-    if (name === "Status" && entry?.value && !/^(?:DRAFT|READY|IN_PROGRESS|BLOCKED|COMPLETED)$/i.test(entry.value)) {
-      issue(issues, file, entry.line, "status", "Status must be DRAFT, READY, IN_PROGRESS, BLOCKED, or COMPLETED.");
-    }
-  }
-  const misplacedScope = lines.findIndex((line) => /^\s*(?:-\s+\*\*File scopes:\*\*|#{3,}\s+File Scopes\b)/i.test(line));
-  if (misplacedScope >= 0)
-    issue(issues, file, misplacedScope + 1, "file-scope", "File scope belongs only in each implementation brief’s Phase File Tree.");
-  const phaseHeading = /^### Phase (\d+):\s*(\S.*)$/;
-  const phaseLines = lines.flatMap((line, i) => phaseHeading.test(line) ? [i] : []);
-  if (!phaseLines.length)
-    issue(issues, file, 0, "phases", "Add at least one numbered phase.");
-  const phases = [];
-  const taskIds = new Set;
-  for (const [index, start] of phaseLines.entries()) {
-    const match = phaseHeading.exec(lines[start]);
-    const end = phaseLines[index + 1] ?? lines.length;
-    if (Number(match[1]) !== index + 1)
-      issue(issues, file, start + 1, "phase-order", "Phase numbers must start at 1 and be contiguous.");
-    const id = field(lines, start + 1, end, "Phase ID");
-    const prerequisite = field(lines, start + 1, end, "Prerequisites");
-    if (!id?.value)
-      issue(issues, file, id?.line ?? start + 1, "phase-id", "Phase ID is required.");
-    if (!prerequisite?.value)
-      issue(issues, file, prerequisite?.line ?? start + 1, "prerequisites", "Phase prerequisites are required (use None if empty).");
-    const prereqs = prerequisite?.value && !/^none$/i.test(prerequisite.value) ? prerequisite.value.split(",").map((value) => value.replaceAll("`", "").trim()) : [];
-    for (const required of prereqs) {
-      if (!phases.some((phase) => phase.id === required)) {
-        issue(issues, file, prerequisite?.line ?? start + 1, "prerequisites", `Prerequisite ${required || "(empty)"} must identify an earlier phase ID.`);
-      }
-    }
-    if (id?.value && phases.some((phase) => phase.id === id.value))
-      issue(issues, file, id.line, "phase-id", `Duplicate phase ID ${id.value}.`);
-    const tasks = [];
-    for (let i = start + 1;i < end; i++) {
-      const line = lines[i];
-      if (!/^\s*- \[[ xX]\]/.test(line))
-        continue;
-      const task = /^- \[[ xX]\] \*\*([a-z0-9]+(?:-[a-z0-9]+)*):?\*\* (\S.*)$/.exec(line);
-      if (!task) {
-        issue(issues, file, i + 1, "task-format", "Use a flat checkbox with a bold stable task ID and a title.");
-        continue;
-      }
-      if (taskIds.has(task[1]))
-        issue(issues, file, i + 1, "task-id", `Duplicate task ID ${task[1]}.`);
-      taskIds.add(task[1]);
-      tasks.push({ id: task[1], title: task[2].trim() });
-    }
-    if (!tasks.length)
-      issue(issues, file, start + 1, "tasks", "Each phase needs at least one task.");
-    phases.push({ id: id?.value ?? "", title: match[2].trim(), prerequisites: prereqs, tasks });
-  }
-  return phases;
-}
-function parseBrief(source, file, phase, number, issues) {
-  const lines = linesOf(source);
-  const title = lines[0]?.match(/^# Phase (\d+):\s*(\S.*)$/);
-  if (!title || Number(title[1]) !== number || title[2]?.trim() !== phase.title) {
-    issue(issues, file, 1, "phase-title", `Expected # Phase ${number}: ${phase.title}.`);
-  }
-  const id = field(lines, 0, lines.length, "Phase ID");
-  if (id?.value !== phase.id)
-    issue(issues, file, id?.line ?? 0, "phase-id", `Expected Phase ID ${phase.id}.`);
-  const prereqs = field(lines, 0, lines.length, "Prerequisites");
-  const expected = phase.prerequisites.length ? phase.prerequisites.join(", ") : "None";
-  if (prereqs?.value !== expected)
-    issue(issues, file, prereqs?.line ?? 0, "prerequisites", `Expected prerequisites ${expected}.`);
-  for (const section of ["Objective", "Tasks", "Implementation Constraints", "Phase File Tree"]) {
-    requireSection(lines, file, `## ${section}`, issues);
-  }
-  for (const section of ["Libraries and Algorithms", "Constraints"]) {
-    requireSection(lines, file, `### ${section}`, issues);
-  }
-  const taskHeading = /^### (\d+)\.\s*(\S.*)$/;
-  const tasksStart = heading(lines, "## Tasks")[0] ?? 0;
-  const tasksEnd = heading(lines, "## Implementation Constraints")[0] ?? lines.length;
-  const taskLines = lines.flatMap((line, i) => i > tasksStart && i < tasksEnd && taskHeading.test(line) ? [i] : []);
-  if (taskLines.length !== phase.tasks.length)
-    issue(issues, file, tasksStart + 1, "task-parity", `Expected ${phase.tasks.length} matching task sections, found ${taskLines.length}.`);
-  for (const [index, start] of taskLines.entries()) {
-    const end = taskLines[index + 1] ?? tasksEnd;
-    const match = taskHeading.exec(lines[start]);
-    const planTask = phase.tasks[index];
-    const id = field(lines, start + 1, end, "Task ID");
-    if (!planTask || Number(match[1]) !== index + 1 || match[2]?.trim() !== planTask.title || id?.value !== planTask.id) {
-      issue(issues, file, start + 1, "task-parity", `Task ${index + 1} must match its PLAN.md ID, title, and order.`);
-    }
-    const steps = field(lines, start + 1, end, "Steps");
-    const stepStart = steps ? steps.line : end;
-    if (!steps || !lines.slice(stepStart, end).some((line) => /^\s+1\.\s+\S/.test(line))) {
-      issue(issues, file, start + 1, "steps", "Add numbered implementation steps starting at 1.");
-    }
-    const verification = lines.findIndex((line, i) => i > start && i < end && /^\s*- \*\*Verify:\*\*/.test(line));
-    const inline = verification >= 0 && /\*\*Verify:\*\*\s*\S/.test(lines[verification]);
-    const nested = verification >= 0 && lines.slice(verification + 1, end).some((line) => /^\s{2,}-\s+\S/.test(line));
-    if (!inline && !nested) {
-      issue(issues, file, verification >= 0 ? verification + 1 : start + 1, "verification", "Nest a nonempty **Verify:** instruction under this task.");
-    }
-    const acceptance = field(lines, start + 1, end, "Acceptance");
-    if (!acceptance?.value)
-      issue(issues, file, start + 1, "task-detail", "Add nonempty Acceptance for this task.");
-    const misplacedScope = lines.findIndex((line, i) => i > start && i < end && /^\s*(?:-\s+\*\*File scopes:\*\*|#{3,}\s+File Scopes\b)/i.test(line));
-    if (misplacedScope >= 0)
-      issue(issues, file, misplacedScope + 1, "file-scope", "Put the phase’s file scope only in its Phase File Tree.");
-  }
-  const treeStart = heading(lines, "## Phase File Tree")[0];
-  if (treeStart === undefined)
-    return;
-  const treeEnd = lines.findIndex((line, i) => i > treeStart && /^## /.test(line));
-  const original = source.split(/\r?\n/).slice(treeStart, treeEnd < 0 ? undefined : treeEnd);
-  const opens = original.flatMap((line, i) => /^```text\s*$/.test(line) ? [i] : []);
-  if (opens.length !== 1) {
-    issue(issues, file, treeStart + 1, "tree", "Use exactly one fenced text tree for the phase.");
-    return;
-  }
-  const close = original.findIndex((line, i) => i > opens[0] && /^```\s*$/.test(line));
-  if (close < 0) {
-    issue(issues, file, treeStart + 1, "tree", "Close the fenced phase file tree.");
-    return;
-  }
-  let leaves = 0;
-  for (let i = opens[0] + 1;i < close; i++) {
-    const branch = /^\s*[│ ]*(?:├──|└──)\s+(.+)$/.exec(original[i]);
-    if (!branch || branch[1].trimEnd().endsWith("/"))
-      continue;
-    leaves++;
-    if (!/^\[(?:ADD|MODIFY|REMOVE|VERIFY|MOVE from: [^\]]+)\]\s+\S/.test(branch[1])) {
-      issue(issues, file, treeStart + i + 1, "tree-label", "Every file leaf must start with an action label after the tree branch.");
-    }
-  }
-  if (!leaves)
-    issue(issues, file, treeStart + 1, "tree", "Add at least one action-labeled file leaf.");
-}
-async function verifyLivePlanInternal(requested, cwd) {
   const path = resolve4(cwd, requested);
   let planPath = path;
   try {
@@ -14988,42 +14813,80 @@ async function verifyLivePlanInternal(requested, cwd) {
   } catch {}
   const issues = [];
   const briefPaths = [];
+  const planDir = dirname5(planPath);
   if (basename4(planPath) !== "PLAN.md") {
-    issue(issues, planPath, 0, "path", "Select a PLAN.md file or its directory.");
+    addIssue(issues, planPath, 0, "path", "Select PLAN.md or its directory.");
     return { planPath, briefPaths, ok: false, issues };
   }
+  if (!/^\d{6}(?:-[a-z0-9]+)+$/.test(basename4(planDir)) || basename4(dirname5(planDir)) !== "plan" || basename4(dirname5(dirname5(planDir))) !== ".diffpi")
+    addIssue(issues, planPath, 0, "layout", "Place PLAN.md under .diffpi/plan/<YYMMDD[-ticket]-short-slug>/.");
   let source;
   try {
     source = await readFile6(planPath, "utf8");
   } catch {
-    issue(issues, planPath, 0, "missing-plan", "PLAN.md is not readable.");
+    addIssue(issues, planPath, 0, "missing-plan", "PLAN.md is not readable.");
     return { planPath, briefPaths, ok: false, issues };
   }
-  const phases = parsePlan(source, planPath, issues);
-  const implementation = join12(resolve4(planPath, ".."), "implementation");
-  let entries;
+  const planLines = visibleLines(source);
+  checkHeadings(planLines, planPath, ["Intent", "Requirements", "Design", "Phases", "References"], issues);
+  const phases = planLines.flatMap((line, i) => /^### Phase \d+:\s*\S/.test(line) ? [i] : []);
+  if (!phases.length)
+    addIssue(issues, planPath, 0, "phases", "Add at least one numbered phase heading.");
+  for (const [index, line] of phases.entries()) {
+    if (!planLines[line]?.startsWith(`### Phase ${index + 1}: `))
+      addIssue(issues, planPath, line + 1, "phase-order", "Number phase headings from 1 without gaps.");
+  }
+  const implementation = join12(planDir, "implementation");
+  let rootEntries = [];
+  let briefEntries = [];
   try {
-    entries = await readdir2(implementation);
-  } catch {
-    entries = [];
+    rootEntries = await readdir2(planDir);
+    briefEntries = await readdir2(implementation);
+  } catch {}
+  for (const entry of rootEntries) {
+    if (entry !== "PLAN.md" && entry !== "implementation")
+      addIssue(issues, join12(planDir, entry), 0, "layout", "Only PLAN.md and implementation/ belong in the plan directory.");
   }
-  for (const entry of entries) {
-    const match = /^phase-(\d+)\.md$/.exec(entry);
-    if (match && (Number(match[1]) < 1 || Number(match[1]) > phases.length || entry !== `phase-${Number(match[1])}.md`)) {
-      issue(issues, join12(implementation, entry), 0, "extra-brief", "No matching numbered phase exists for this brief.");
-    }
+  for (const entry of briefEntries) {
+    const ordinal = /^phase-(\d+)\.md$/.exec(entry)?.[1];
+    if (!ordinal || !Number(ordinal) || Number(ordinal) > phases.length || entry !== `phase-${Number(ordinal)}.md`)
+      addIssue(issues, join12(implementation, entry), 0, "extra-brief", "Only matching numbered phase briefs belong in implementation/.");
   }
-  for (const [index, phase] of phases.entries()) {
+  for (let index = 0;index < phases.length; index++) {
     const brief = join12(implementation, `phase-${index + 1}.md`);
     briefPaths.push(brief);
     try {
-      parseBrief(await readFile6(brief, "utf8"), brief, phase, index + 1, issues);
+      const lines = visibleLines(await readFile6(brief, "utf8"));
+      if (!/^# Phase \d+:\s*\S/.test(lines[0] ?? "") || !lines[0]?.startsWith(`# Phase ${index + 1}: `))
+        addIssue(issues, brief, 1, "phase-title", `Start with # Phase ${index + 1}: <title>.`);
+      checkHeadings(lines, brief, ["Objective", "Files Affected", "Tasks", "Implementation Constraints"], issues);
     } catch {
-      issue(issues, brief, 0, "missing-brief", "Numbered phase brief is not readable.");
+      addIssue(issues, brief, 0, "missing-brief", "Numbered phase brief is not readable.");
     }
   }
   return { planPath, briefPaths, ok: issues.length === 0, issues };
 }
+function addIssue(issues, file, line, code, message) {
+  issues.push({ file, line, code, message });
+}
+function visibleLines(source) {
+  let fenced = false;
+  return source.split(/\r?\n/).map((line) => {
+    if (/^\s*```/.test(line)) {
+      fenced = !fenced;
+      return "";
+    }
+    return fenced ? "" : line;
+  });
+}
+function checkHeadings(lines, file, names, issues) {
+  const found = lines.flatMap((line, i) => line.startsWith("## ") ? [{ text: line, line: i + 1 }] : []);
+  const expected = names.map((name) => `## ${name}`);
+  if (found.map(({ text }) => text).join(`
+`) !== expected.join(`
+`))
+    addIssue(issues, file, found[0]?.line ?? 0, "headings", `Expected headings, in order: ${expected.join(", ")}.`);
+}
 
 // src/tools/plan.ts
 var schema8 = z5.object({ plan: z5.string().min(1), cwd: z5.string().optional() }).strict();
@@ -15198,7 +15061,7 @@ import { z as z11 } from "zod";
 // src/extensions/misex.ts
 import { mkdir as mkdir3, readFile as readFile7, writeFile as writeFile2 } from "node:fs/promises";
 import { homedir as homedir6 } from "node:os";
-import { basename as basename5, dirname as dirname5, join as join13 } from "node:path";
+import { basename as basename5, dirname as dirname6, join as join13 } from "node:path";
 var MISE_HOOK_START = "# >>> @difflab/pi mise >>>";
 var MISE_HOOK_END = "# <<< @difflab/pi mise <<<";
 var mise = {
@@ -15233,7 +15096,7 @@ var mise = {
     const separator = current.length === 0 || current.endsWith(`
 `) ? "" : `
 `;
-    await mkdir3(dirname5(hook.path), { recursive: true });
+    await mkdir3(dirname6(hook.path), { recursive: true });
     await writeFile2(hook.path, `${current}${separator}${hook.content}`, "utf8");
     return { path: hook.path, changed: true, planned: false };
   },
@@ -17350,7 +17213,7 @@ import { basename as basename6, join as join19 } from "node:path";
 // src/mcp.ts
 import { mkdir as mkdir5, readFile as readFile13, writeFile as writeFile6 } from "node:fs/promises";
 import { homedir as homedir8 } from "node:os";
-import { dirname as dirname6, join as join17 } from "node:path";
+import { dirname as dirname7, join as join17 } from "node:path";
 var mcp = {
   globalConfigPath(homeDir = homedir8()) {
     return join17(homeDir, ".config", "mcp", "mcp.json");
@@ -17366,7 +17229,7 @@ var mcp = {
     const next = { ...current, mcpServers: nextServers };
     const changed = JSON.stringify(current) !== JSON.stringify(next);
     if (changed && !options.dryRun) {
-      await mkdir5(dirname6(path), { recursive: true });
+      await mkdir5(dirname7(path), { recursive: true });
       await writeFile6(path, `${JSON.stringify(next, null, 2)}
 `, "utf8");
     }
@@ -17410,7 +17273,7 @@ function isRecord(value) {
 // src/pi.ts
 import { mkdir as mkdir6, writeFile as writeFile7 } from "node:fs/promises";
 import { homedir as homedir9 } from "node:os";
-import { dirname as dirname7, join as join18 } from "node:path";
+import { dirname as dirname8, join as join18 } from "node:path";
 var pi = {
   executableCheck: findPiExecutable,
   packageList: listPiPackages,
@@ -17427,7 +17290,7 @@ async function ensurePiAgent(filename, content, agentDir = resolvePiAgentDir(),
   const currentText = await readTextIfExists(path);
   const changed = currentText !== content;
   if (changed && !dryRun) {
-    await mkdir6(dirname7(path), { recursive: true });
+    await mkdir6(dirname8(path), { recursive: true });
     await writeFile7(path, content, "utf8");
   }
   return { path, changed, existed: currentText !== undefined, planned: changed && dryRun };
@@ -17464,7 +17327,7 @@ async function ensurePiConfig(path, update, dryRun = false) {
   const next = update(current);
   const changed = JSON.stringify(current) !== JSON.stringify(next);
   if (changed && !dryRun) {
-    await mkdir6(dirname7(path), { recursive: true });
+    await mkdir6(dirname8(path), { recursive: true });
     await writeFile7(path, `${JSON.stringify(next, null, 2)}
 `, "utf8");
   }

package/dist/index.js

@@ -2551,183 +2551,8 @@ function parseJsonObject(content, path) {
 }
 // src/plan/verify.ts
 import { readFile as readFile10, readdir as readdir2, stat } from "node:fs/promises";
-import { basename as basename5, join as join13, resolve as resolve4 } from "node:path";
+import { basename as basename5, dirname as dirname7, join as join13, resolve as resolve4 } from "node:path";
 async function verifyLivePlan(requested, cwd = process.cwd()) {
-  return verifyLivePlanInternal(requested, cwd);
-}
-function linesOf(source) {
-  let fenced = false;
-  return source.split(/\r?\n/).map((line) => {
-    if (/^\s*```/.test(line)) {
-      fenced = !fenced;
-      return "";
-    }
-    return fenced ? "" : line;
-  });
-}
-function issue(issues, file, line, code, message) {
-  issues.push({ file, line, code, message });
-}
-function field(lines, start, end, name) {
-  const label = `- **${name}:**`;
-  for (let i = start;i < end; i++) {
-    if (lines[i]?.trimStart().startsWith(label)) {
-      return { value: lines[i].trimStart().slice(label.length).trim(), line: i + 1 };
-    }
-  }
-  return;
-}
-function heading(lines, text) {
-  return lines.flatMap((line, i) => line.trim() === text ? [i] : []);
-}
-function requireSection(lines, file, text, issues) {
-  const matches = heading(lines, text);
-  if (matches.length !== 1)
-    issue(issues, file, matches[0] === undefined ? 0 : matches[0] + 1, "section", `Expected exactly one ${text} section.`);
-  return matches[0] ?? -1;
-}
-function parsePlan(source, file, issues) {
-  const lines = linesOf(source);
-  for (const name of ["Intent", "Requirements", "Design", "Phases", "References"]) {
-    requireSection(lines, file, `## ${name}`, issues);
-  }
-  for (const name of ["Plan ID", "Branch", "Status"]) {
-    const entry = field(lines, 0, lines.length, name);
-    if (!entry?.value)
-      issue(issues, file, entry?.line ?? 0, "metadata", `Missing ${name}.`);
-    if (name === "Status" && entry?.value && !/^(?:DRAFT|READY|IN_PROGRESS|BLOCKED|COMPLETED)$/i.test(entry.value)) {
-      issue(issues, file, entry.line, "status", "Status must be DRAFT, READY, IN_PROGRESS, BLOCKED, or COMPLETED.");
-    }
-  }
-  const misplacedScope = lines.findIndex((line) => /^\s*(?:-\s+\*\*File scopes:\*\*|#{3,}\s+File Scopes\b)/i.test(line));
-  if (misplacedScope >= 0)
-    issue(issues, file, misplacedScope + 1, "file-scope", "File scope belongs only in each implementation brief’s Phase File Tree.");
-  const phaseHeading = /^### Phase (\d+):\s*(\S.*)$/;
-  const phaseLines = lines.flatMap((line, i) => phaseHeading.test(line) ? [i] : []);
-  if (!phaseLines.length)
-    issue(issues, file, 0, "phases", "Add at least one numbered phase.");
-  const phases = [];
-  const taskIds = new Set;
-  for (const [index, start] of phaseLines.entries()) {
-    const match = phaseHeading.exec(lines[start]);
-    const end = phaseLines[index + 1] ?? lines.length;
-    if (Number(match[1]) !== index + 1)
-      issue(issues, file, start + 1, "phase-order", "Phase numbers must start at 1 and be contiguous.");
-    const id = field(lines, start + 1, end, "Phase ID");
-    const prerequisite = field(lines, start + 1, end, "Prerequisites");
-    if (!id?.value)
-      issue(issues, file, id?.line ?? start + 1, "phase-id", "Phase ID is required.");
-    if (!prerequisite?.value)
-      issue(issues, file, prerequisite?.line ?? start + 1, "prerequisites", "Phase prerequisites are required (use None if empty).");
-    const prereqs = prerequisite?.value && !/^none$/i.test(prerequisite.value) ? prerequisite.value.split(",").map((value) => value.replaceAll("`", "").trim()) : [];
-    for (const required of prereqs) {
-      if (!phases.some((phase) => phase.id === required)) {
-        issue(issues, file, prerequisite?.line ?? start + 1, "prerequisites", `Prerequisite ${required || "(empty)"} must identify an earlier phase ID.`);
-      }
-    }
-    if (id?.value && phases.some((phase) => phase.id === id.value))
-      issue(issues, file, id.line, "phase-id", `Duplicate phase ID ${id.value}.`);
-    const tasks = [];
-    for (let i = start + 1;i < end; i++) {
-      const line = lines[i];
-      if (!/^\s*- \[[ xX]\]/.test(line))
-        continue;
-      const task = /^- \[[ xX]\] \*\*([a-z0-9]+(?:-[a-z0-9]+)*):?\*\* (\S.*)$/.exec(line);
-      if (!task) {
-        issue(issues, file, i + 1, "task-format", "Use a flat checkbox with a bold stable task ID and a title.");
-        continue;
-      }
-      if (taskIds.has(task[1]))
-        issue(issues, file, i + 1, "task-id", `Duplicate task ID ${task[1]}.`);
-      taskIds.add(task[1]);
-      tasks.push({ id: task[1], title: task[2].trim() });
-    }
-    if (!tasks.length)
-      issue(issues, file, start + 1, "tasks", "Each phase needs at least one task.");
-    phases.push({ id: id?.value ?? "", title: match[2].trim(), prerequisites: prereqs, tasks });
-  }
-  return phases;
-}
-function parseBrief(source, file, phase, number, issues) {
-  const lines = linesOf(source);
-  const title = lines[0]?.match(/^# Phase (\d+):\s*(\S.*)$/);
-  if (!title || Number(title[1]) !== number || title[2]?.trim() !== phase.title) {
-    issue(issues, file, 1, "phase-title", `Expected # Phase ${number}: ${phase.title}.`);
-  }
-  const id = field(lines, 0, lines.length, "Phase ID");
-  if (id?.value !== phase.id)
-    issue(issues, file, id?.line ?? 0, "phase-id", `Expected Phase ID ${phase.id}.`);
-  const prereqs = field(lines, 0, lines.length, "Prerequisites");
-  const expected = phase.prerequisites.length ? phase.prerequisites.join(", ") : "None";
-  if (prereqs?.value !== expected)
-    issue(issues, file, prereqs?.line ?? 0, "prerequisites", `Expected prerequisites ${expected}.`);
-  for (const section of ["Objective", "Tasks", "Implementation Constraints", "Phase File Tree"]) {
-    requireSection(lines, file, `## ${section}`, issues);
-  }
-  for (const section of ["Libraries and Algorithms", "Constraints"]) {
-    requireSection(lines, file, `### ${section}`, issues);
-  }
-  const taskHeading = /^### (\d+)\.\s*(\S.*)$/;
-  const tasksStart = heading(lines, "## Tasks")[0] ?? 0;
-  const tasksEnd = heading(lines, "## Implementation Constraints")[0] ?? lines.length;
-  const taskLines = lines.flatMap((line, i) => i > tasksStart && i < tasksEnd && taskHeading.test(line) ? [i] : []);
-  if (taskLines.length !== phase.tasks.length)
-    issue(issues, file, tasksStart + 1, "task-parity", `Expected ${phase.tasks.length} matching task sections, found ${taskLines.length}.`);
-  for (const [index, start] of taskLines.entries()) {
-    const end = taskLines[index + 1] ?? tasksEnd;
-    const match = taskHeading.exec(lines[start]);
-    const planTask = phase.tasks[index];
-    const id = field(lines, start + 1, end, "Task ID");
-    if (!planTask || Number(match[1]) !== index + 1 || match[2]?.trim() !== planTask.title || id?.value !== planTask.id) {
-      issue(issues, file, start + 1, "task-parity", `Task ${index + 1} must match its PLAN.md ID, title, and order.`);
-    }
-    const steps = field(lines, start + 1, end, "Steps");
-    const stepStart = steps ? steps.line : end;
-    if (!steps || !lines.slice(stepStart, end).some((line) => /^\s+1\.\s+\S/.test(line))) {
-      issue(issues, file, start + 1, "steps", "Add numbered implementation steps starting at 1.");
-    }
-    const verification = lines.findIndex((line, i) => i > start && i < end && /^\s*- \*\*Verify:\*\*/.test(line));
-    const inline = verification >= 0 && /\*\*Verify:\*\*\s*\S/.test(lines[verification]);
-    const nested = verification >= 0 && lines.slice(verification + 1, end).some((line) => /^\s{2,}-\s+\S/.test(line));
-    if (!inline && !nested) {
-      issue(issues, file, verification >= 0 ? verification + 1 : start + 1, "verification", "Nest a nonempty **Verify:** instruction under this task.");
-    }
-    const acceptance = field(lines, start + 1, end, "Acceptance");
-    if (!acceptance?.value)
-      issue(issues, file, start + 1, "task-detail", "Add nonempty Acceptance for this task.");
-    const misplacedScope = lines.findIndex((line, i) => i > start && i < end && /^\s*(?:-\s+\*\*File scopes:\*\*|#{3,}\s+File Scopes\b)/i.test(line));
-    if (misplacedScope >= 0)
-      issue(issues, file, misplacedScope + 1, "file-scope", "Put the phase’s file scope only in its Phase File Tree.");
-  }
-  const treeStart = heading(lines, "## Phase File Tree")[0];
-  if (treeStart === undefined)
-    return;
-  const treeEnd = lines.findIndex((line, i) => i > treeStart && /^## /.test(line));
-  const original = source.split(/\r?\n/).slice(treeStart, treeEnd < 0 ? undefined : treeEnd);
-  const opens = original.flatMap((line, i) => /^```text\s*$/.test(line) ? [i] : []);
-  if (opens.length !== 1) {
-    issue(issues, file, treeStart + 1, "tree", "Use exactly one fenced text tree for the phase.");
-    return;
-  }
-  const close = original.findIndex((line, i) => i > opens[0] && /^```\s*$/.test(line));
-  if (close < 0) {
-    issue(issues, file, treeStart + 1, "tree", "Close the fenced phase file tree.");
-    return;
-  }
-  let leaves = 0;
-  for (let i = opens[0] + 1;i < close; i++) {
-    const branch = /^\s*[│ ]*(?:├──|└──)\s+(.+)$/.exec(original[i]);
-    if (!branch || branch[1].trimEnd().endsWith("/"))
-      continue;
-    leaves++;
-    if (!/^\[(?:ADD|MODIFY|REMOVE|VERIFY|MOVE from: [^\]]+)\]\s+\S/.test(branch[1])) {
-      issue(issues, file, treeStart + i + 1, "tree-label", "Every file leaf must start with an action label after the tree branch.");
-    }
-  }
-  if (!leaves)
-    issue(issues, file, treeStart + 1, "tree", "Add at least one action-labeled file leaf.");
-}
-async function verifyLivePlanInternal(requested, cwd) {
   const path = resolve4(cwd, requested);
   let planPath = path;
   try {
@@ -2736,42 +2561,80 @@ async function verifyLivePlanInternal(requested, cwd) {
   } catch {}
   const issues = [];
   const briefPaths = [];
+  const planDir = dirname7(planPath);
   if (basename5(planPath) !== "PLAN.md") {
-    issue(issues, planPath, 0, "path", "Select a PLAN.md file or its directory.");
+    addIssue(issues, planPath, 0, "path", "Select PLAN.md or its directory.");
     return { planPath, briefPaths, ok: false, issues };
   }
+  if (!/^\d{6}(?:-[a-z0-9]+)+$/.test(basename5(planDir)) || basename5(dirname7(planDir)) !== "plan" || basename5(dirname7(dirname7(planDir))) !== ".diffpi")
+    addIssue(issues, planPath, 0, "layout", "Place PLAN.md under .diffpi/plan/<YYMMDD[-ticket]-short-slug>/.");
   let source;
   try {
     source = await readFile10(planPath, "utf8");
   } catch {
-    issue(issues, planPath, 0, "missing-plan", "PLAN.md is not readable.");
+    addIssue(issues, planPath, 0, "missing-plan", "PLAN.md is not readable.");
     return { planPath, briefPaths, ok: false, issues };
   }
-  const phases = parsePlan(source, planPath, issues);
-  const implementation = join13(resolve4(planPath, ".."), "implementation");
-  let entries;
+  const planLines = visibleLines(source);
+  checkHeadings(planLines, planPath, ["Intent", "Requirements", "Design", "Phases", "References"], issues);
+  const phases = planLines.flatMap((line, i) => /^### Phase \d+:\s*\S/.test(line) ? [i] : []);
+  if (!phases.length)
+    addIssue(issues, planPath, 0, "phases", "Add at least one numbered phase heading.");
+  for (const [index, line] of phases.entries()) {
+    if (!planLines[line]?.startsWith(`### Phase ${index + 1}: `))
+      addIssue(issues, planPath, line + 1, "phase-order", "Number phase headings from 1 without gaps.");
+  }
+  const implementation = join13(planDir, "implementation");
+  let rootEntries = [];
+  let briefEntries = [];
   try {
-    entries = await readdir2(implementation);
-  } catch {
-    entries = [];
+    rootEntries = await readdir2(planDir);
+    briefEntries = await readdir2(implementation);
+  } catch {}
+  for (const entry of rootEntries) {
+    if (entry !== "PLAN.md" && entry !== "implementation")
+      addIssue(issues, join13(planDir, entry), 0, "layout", "Only PLAN.md and implementation/ belong in the plan directory.");
   }
-  for (const entry of entries) {
-    const match = /^phase-(\d+)\.md$/.exec(entry);
-    if (match && (Number(match[1]) < 1 || Number(match[1]) > phases.length || entry !== `phase-${Number(match[1])}.md`)) {
-      issue(issues, join13(implementation, entry), 0, "extra-brief", "No matching numbered phase exists for this brief.");
-    }
+  for (const entry of briefEntries) {
+    const ordinal = /^phase-(\d+)\.md$/.exec(entry)?.[1];
+    if (!ordinal || !Number(ordinal) || Number(ordinal) > phases.length || entry !== `phase-${Number(ordinal)}.md`)
+      addIssue(issues, join13(implementation, entry), 0, "extra-brief", "Only matching numbered phase briefs belong in implementation/.");
   }
-  for (const [index, phase] of phases.entries()) {
+  for (let index = 0;index < phases.length; index++) {
     const brief = join13(implementation, `phase-${index + 1}.md`);
     briefPaths.push(brief);
     try {
-      parseBrief(await readFile10(brief, "utf8"), brief, phase, index + 1, issues);
+      const lines = visibleLines(await readFile10(brief, "utf8"));
+      if (!/^# Phase \d+:\s*\S/.test(lines[0] ?? "") || !lines[0]?.startsWith(`# Phase ${index + 1}: `))
+        addIssue(issues, brief, 1, "phase-title", `Start with # Phase ${index + 1}: <title>.`);
+      checkHeadings(lines, brief, ["Objective", "Files Affected", "Tasks", "Implementation Constraints"], issues);
     } catch {
-      issue(issues, brief, 0, "missing-brief", "Numbered phase brief is not readable.");
+      addIssue(issues, brief, 0, "missing-brief", "Numbered phase brief is not readable.");
     }
   }
   return { planPath, briefPaths, ok: issues.length === 0, issues };
 }
+function addIssue(issues, file, line, code, message) {
+  issues.push({ file, line, code, message });
+}
+function visibleLines(source) {
+  let fenced = false;
+  return source.split(/\r?\n/).map((line) => {
+    if (/^\s*```/.test(line)) {
+      fenced = !fenced;
+      return "";
+    }
+    return fenced ? "" : line;
+  });
+}
+function checkHeadings(lines, file, names, issues) {
+  const found = lines.flatMap((line, i) => line.startsWith("## ") ? [{ text: line, line: i + 1 }] : []);
+  const expected = names.map((name) => `## ${name}`);
+  if (found.map(({ text }) => text).join(`
+`) !== expected.join(`
+`))
+    addIssue(issues, file, found[0]?.line ?? 0, "headings", `Expected headings, in order: ${expected.join(", ")}.`);
+}
 // src/setup.ts
 import { parseFrontmatter as parseFrontmatter3 } from "@earendil-works/pi-coding-agent";
 import { readdir as readdir3, readFile as readFile11 } from "node:fs/promises";

package/dist/plan/verify.d.ts

@@ -10,6 +10,6 @@ export interface PlanVerification {
     ok: boolean;
     issues: PlanVerificationIssue[];
 }
-/** Read-only, stateless verification of the current live-file plan format. */
+/** Read-only layout check. The independent reviewer judges all plan content. */
 export declare function verifyLivePlan(requested: string, cwd?: string): Promise<PlanVerification>;
 //# sourceMappingURL=verify.d.ts.map

package/dist/plan/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/plan/verify.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,qBAAqB,EAAE,CAAC;CACjC;AAED,8EAA8E;AAC9E,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,SAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAEtG"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/plan/verify.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,qBAAqB,EAAE,CAAC;CACjC;AAED,gFAAgF;AAChF,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,SAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiFtG"}

package/dist/tools/index.js

@@ -950,183 +950,8 @@ import { z as z4 } from "zod";
 
 // src/plan/verify.ts
 import { readFile as readFile4, readdir, stat } from "node:fs/promises";
-import { basename as basename3, join as join8, resolve as resolve3 } from "node:path";
+import { basename as basename3, dirname as dirname4, join as join8, resolve as resolve3 } from "node:path";
 async function verifyLivePlan(requested, cwd = process.cwd()) {
-  return verifyLivePlanInternal(requested, cwd);
-}
-function linesOf(source) {
-  let fenced = false;
-  return source.split(/\r?\n/).map((line) => {
-    if (/^\s*```/.test(line)) {
-      fenced = !fenced;
-      return "";
-    }
-    return fenced ? "" : line;
-  });
-}
-function issue(issues, file, line, code, message) {
-  issues.push({ file, line, code, message });
-}
-function field(lines, start, end, name) {
-  const label = `- **${name}:**`;
-  for (let i = start;i < end; i++) {
-    if (lines[i]?.trimStart().startsWith(label)) {
-      return { value: lines[i].trimStart().slice(label.length).trim(), line: i + 1 };
-    }
-  }
-  return;
-}
-function heading(lines, text) {
-  return lines.flatMap((line, i) => line.trim() === text ? [i] : []);
-}
-function requireSection(lines, file, text, issues) {
-  const matches = heading(lines, text);
-  if (matches.length !== 1)
-    issue(issues, file, matches[0] === undefined ? 0 : matches[0] + 1, "section", `Expected exactly one ${text} section.`);
-  return matches[0] ?? -1;
-}
-function parsePlan(source, file, issues) {
-  const lines = linesOf(source);
-  for (const name of ["Intent", "Requirements", "Design", "Phases", "References"]) {
-    requireSection(lines, file, `## ${name}`, issues);
-  }
-  for (const name of ["Plan ID", "Branch", "Status"]) {
-    const entry = field(lines, 0, lines.length, name);
-    if (!entry?.value)
-      issue(issues, file, entry?.line ?? 0, "metadata", `Missing ${name}.`);
-    if (name === "Status" && entry?.value && !/^(?:DRAFT|READY|IN_PROGRESS|BLOCKED|COMPLETED)$/i.test(entry.value)) {
-      issue(issues, file, entry.line, "status", "Status must be DRAFT, READY, IN_PROGRESS, BLOCKED, or COMPLETED.");
-    }
-  }
-  const misplacedScope = lines.findIndex((line) => /^\s*(?:-\s+\*\*File scopes:\*\*|#{3,}\s+File Scopes\b)/i.test(line));
-  if (misplacedScope >= 0)
-    issue(issues, file, misplacedScope + 1, "file-scope", "File scope belongs only in each implementation brief’s Phase File Tree.");
-  const phaseHeading = /^### Phase (\d+):\s*(\S.*)$/;
-  const phaseLines = lines.flatMap((line, i) => phaseHeading.test(line) ? [i] : []);
-  if (!phaseLines.length)
-    issue(issues, file, 0, "phases", "Add at least one numbered phase.");
-  const phases = [];
-  const taskIds = new Set;
-  for (const [index, start] of phaseLines.entries()) {
-    const match = phaseHeading.exec(lines[start]);
-    const end = phaseLines[index + 1] ?? lines.length;
-    if (Number(match[1]) !== index + 1)
-      issue(issues, file, start + 1, "phase-order", "Phase numbers must start at 1 and be contiguous.");
-    const id = field(lines, start + 1, end, "Phase ID");
-    const prerequisite = field(lines, start + 1, end, "Prerequisites");
-    if (!id?.value)
-      issue(issues, file, id?.line ?? start + 1, "phase-id", "Phase ID is required.");
-    if (!prerequisite?.value)
-      issue(issues, file, prerequisite?.line ?? start + 1, "prerequisites", "Phase prerequisites are required (use None if empty).");
-    const prereqs = prerequisite?.value && !/^none$/i.test(prerequisite.value) ? prerequisite.value.split(",").map((value) => value.replaceAll("`", "").trim()) : [];
-    for (const required of prereqs) {
-      if (!phases.some((phase) => phase.id === required)) {
-        issue(issues, file, prerequisite?.line ?? start + 1, "prerequisites", `Prerequisite ${required || "(empty)"} must identify an earlier phase ID.`);
-      }
-    }
-    if (id?.value && phases.some((phase) => phase.id === id.value))
-      issue(issues, file, id.line, "phase-id", `Duplicate phase ID ${id.value}.`);
-    const tasks = [];
-    for (let i = start + 1;i < end; i++) {
-      const line = lines[i];
-      if (!/^\s*- \[[ xX]\]/.test(line))
-        continue;
-      const task = /^- \[[ xX]\] \*\*([a-z0-9]+(?:-[a-z0-9]+)*):?\*\* (\S.*)$/.exec(line);
-      if (!task) {
-        issue(issues, file, i + 1, "task-format", "Use a flat checkbox with a bold stable task ID and a title.");
-        continue;
-      }
-      if (taskIds.has(task[1]))
-        issue(issues, file, i + 1, "task-id", `Duplicate task ID ${task[1]}.`);
-      taskIds.add(task[1]);
-      tasks.push({ id: task[1], title: task[2].trim() });
-    }
-    if (!tasks.length)
-      issue(issues, file, start + 1, "tasks", "Each phase needs at least one task.");
-    phases.push({ id: id?.value ?? "", title: match[2].trim(), prerequisites: prereqs, tasks });
-  }
-  return phases;
-}
-function parseBrief(source, file, phase, number, issues) {
-  const lines = linesOf(source);
-  const title = lines[0]?.match(/^# Phase (\d+):\s*(\S.*)$/);
-  if (!title || Number(title[1]) !== number || title[2]?.trim() !== phase.title) {
-    issue(issues, file, 1, "phase-title", `Expected # Phase ${number}: ${phase.title}.`);
-  }
-  const id = field(lines, 0, lines.length, "Phase ID");
-  if (id?.value !== phase.id)
-    issue(issues, file, id?.line ?? 0, "phase-id", `Expected Phase ID ${phase.id}.`);
-  const prereqs = field(lines, 0, lines.length, "Prerequisites");
-  const expected = phase.prerequisites.length ? phase.prerequisites.join(", ") : "None";
-  if (prereqs?.value !== expected)
-    issue(issues, file, prereqs?.line ?? 0, "prerequisites", `Expected prerequisites ${expected}.`);
-  for (const section of ["Objective", "Tasks", "Implementation Constraints", "Phase File Tree"]) {
-    requireSection(lines, file, `## ${section}`, issues);
-  }
-  for (const section of ["Libraries and Algorithms", "Constraints"]) {
-    requireSection(lines, file, `### ${section}`, issues);
-  }
-  const taskHeading = /^### (\d+)\.\s*(\S.*)$/;
-  const tasksStart = heading(lines, "## Tasks")[0] ?? 0;
-  const tasksEnd = heading(lines, "## Implementation Constraints")[0] ?? lines.length;
-  const taskLines = lines.flatMap((line, i) => i > tasksStart && i < tasksEnd && taskHeading.test(line) ? [i] : []);
-  if (taskLines.length !== phase.tasks.length)
-    issue(issues, file, tasksStart + 1, "task-parity", `Expected ${phase.tasks.length} matching task sections, found ${taskLines.length}.`);
-  for (const [index, start] of taskLines.entries()) {
-    const end = taskLines[index + 1] ?? tasksEnd;
-    const match = taskHeading.exec(lines[start]);
-    const planTask = phase.tasks[index];
-    const id = field(lines, start + 1, end, "Task ID");
-    if (!planTask || Number(match[1]) !== index + 1 || match[2]?.trim() !== planTask.title || id?.value !== planTask.id) {
-      issue(issues, file, start + 1, "task-parity", `Task ${index + 1} must match its PLAN.md ID, title, and order.`);
-    }
-    const steps = field(lines, start + 1, end, "Steps");
-    const stepStart = steps ? steps.line : end;
-    if (!steps || !lines.slice(stepStart, end).some((line) => /^\s+1\.\s+\S/.test(line))) {
-      issue(issues, file, start + 1, "steps", "Add numbered implementation steps starting at 1.");
-    }
-    const verification = lines.findIndex((line, i) => i > start && i < end && /^\s*- \*\*Verify:\*\*/.test(line));
-    const inline = verification >= 0 && /\*\*Verify:\*\*\s*\S/.test(lines[verification]);
-    const nested = verification >= 0 && lines.slice(verification + 1, end).some((line) => /^\s{2,}-\s+\S/.test(line));
-    if (!inline && !nested) {
-      issue(issues, file, verification >= 0 ? verification + 1 : start + 1, "verification", "Nest a nonempty **Verify:** instruction under this task.");
-    }
-    const acceptance = field(lines, start + 1, end, "Acceptance");
-    if (!acceptance?.value)
-      issue(issues, file, start + 1, "task-detail", "Add nonempty Acceptance for this task.");
-    const misplacedScope = lines.findIndex((line, i) => i > start && i < end && /^\s*(?:-\s+\*\*File scopes:\*\*|#{3,}\s+File Scopes\b)/i.test(line));
-    if (misplacedScope >= 0)
-      issue(issues, file, misplacedScope + 1, "file-scope", "Put the phase’s file scope only in its Phase File Tree.");
-  }
-  const treeStart = heading(lines, "## Phase File Tree")[0];
-  if (treeStart === undefined)
-    return;
-  const treeEnd = lines.findIndex((line, i) => i > treeStart && /^## /.test(line));
-  const original = source.split(/\r?\n/).slice(treeStart, treeEnd < 0 ? undefined : treeEnd);
-  const opens = original.flatMap((line, i) => /^```text\s*$/.test(line) ? [i] : []);
-  if (opens.length !== 1) {
-    issue(issues, file, treeStart + 1, "tree", "Use exactly one fenced text tree for the phase.");
-    return;
-  }
-  const close = original.findIndex((line, i) => i > opens[0] && /^```\s*$/.test(line));
-  if (close < 0) {
-    issue(issues, file, treeStart + 1, "tree", "Close the fenced phase file tree.");
-    return;
-  }
-  let leaves = 0;
-  for (let i = opens[0] + 1;i < close; i++) {
-    const branch = /^\s*[│ ]*(?:├──|└──)\s+(.+)$/.exec(original[i]);
-    if (!branch || branch[1].trimEnd().endsWith("/"))
-      continue;
-    leaves++;
-    if (!/^\[(?:ADD|MODIFY|REMOVE|VERIFY|MOVE from: [^\]]+)\]\s+\S/.test(branch[1])) {
-      issue(issues, file, treeStart + i + 1, "tree-label", "Every file leaf must start with an action label after the tree branch.");
-    }
-  }
-  if (!leaves)
-    issue(issues, file, treeStart + 1, "tree", "Add at least one action-labeled file leaf.");
-}
-async function verifyLivePlanInternal(requested, cwd) {
   const path = resolve3(cwd, requested);
   let planPath = path;
   try {
@@ -1135,42 +960,80 @@ async function verifyLivePlanInternal(requested, cwd) {
   } catch {}
   const issues = [];
   const briefPaths = [];
+  const planDir = dirname4(planPath);
   if (basename3(planPath) !== "PLAN.md") {
-    issue(issues, planPath, 0, "path", "Select a PLAN.md file or its directory.");
+    addIssue(issues, planPath, 0, "path", "Select PLAN.md or its directory.");
     return { planPath, briefPaths, ok: false, issues };
   }
+  if (!/^\d{6}(?:-[a-z0-9]+)+$/.test(basename3(planDir)) || basename3(dirname4(planDir)) !== "plan" || basename3(dirname4(dirname4(planDir))) !== ".diffpi")
+    addIssue(issues, planPath, 0, "layout", "Place PLAN.md under .diffpi/plan/<YYMMDD[-ticket]-short-slug>/.");
   let source;
   try {
     source = await readFile4(planPath, "utf8");
   } catch {
-    issue(issues, planPath, 0, "missing-plan", "PLAN.md is not readable.");
+    addIssue(issues, planPath, 0, "missing-plan", "PLAN.md is not readable.");
     return { planPath, briefPaths, ok: false, issues };
   }
-  const phases = parsePlan(source, planPath, issues);
-  const implementation = join8(resolve3(planPath, ".."), "implementation");
-  let entries;
+  const planLines = visibleLines(source);
+  checkHeadings(planLines, planPath, ["Intent", "Requirements", "Design", "Phases", "References"], issues);
+  const phases = planLines.flatMap((line, i) => /^### Phase \d+:\s*\S/.test(line) ? [i] : []);
+  if (!phases.length)
+    addIssue(issues, planPath, 0, "phases", "Add at least one numbered phase heading.");
+  for (const [index, line] of phases.entries()) {
+    if (!planLines[line]?.startsWith(`### Phase ${index + 1}: `))
+      addIssue(issues, planPath, line + 1, "phase-order", "Number phase headings from 1 without gaps.");
+  }
+  const implementation = join8(planDir, "implementation");
+  let rootEntries = [];
+  let briefEntries = [];
   try {
-    entries = await readdir(implementation);
-  } catch {
-    entries = [];
+    rootEntries = await readdir(planDir);
+    briefEntries = await readdir(implementation);
+  } catch {}
+  for (const entry of rootEntries) {
+    if (entry !== "PLAN.md" && entry !== "implementation")
+      addIssue(issues, join8(planDir, entry), 0, "layout", "Only PLAN.md and implementation/ belong in the plan directory.");
   }
-  for (const entry of entries) {
-    const match = /^phase-(\d+)\.md$/.exec(entry);
-    if (match && (Number(match[1]) < 1 || Number(match[1]) > phases.length || entry !== `phase-${Number(match[1])}.md`)) {
-      issue(issues, join8(implementation, entry), 0, "extra-brief", "No matching numbered phase exists for this brief.");
-    }
+  for (const entry of briefEntries) {
+    const ordinal = /^phase-(\d+)\.md$/.exec(entry)?.[1];
+    if (!ordinal || !Number(ordinal) || Number(ordinal) > phases.length || entry !== `phase-${Number(ordinal)}.md`)
+      addIssue(issues, join8(implementation, entry), 0, "extra-brief", "Only matching numbered phase briefs belong in implementation/.");
   }
-  for (const [index, phase] of phases.entries()) {
+  for (let index = 0;index < phases.length; index++) {
     const brief = join8(implementation, `phase-${index + 1}.md`);
     briefPaths.push(brief);
     try {
-      parseBrief(await readFile4(brief, "utf8"), brief, phase, index + 1, issues);
+      const lines = visibleLines(await readFile4(brief, "utf8"));
+      if (!/^# Phase \d+:\s*\S/.test(lines[0] ?? "") || !lines[0]?.startsWith(`# Phase ${index + 1}: `))
+        addIssue(issues, brief, 1, "phase-title", `Start with # Phase ${index + 1}: <title>.`);
+      checkHeadings(lines, brief, ["Objective", "Files Affected", "Tasks", "Implementation Constraints"], issues);
     } catch {
-      issue(issues, brief, 0, "missing-brief", "Numbered phase brief is not readable.");
+      addIssue(issues, brief, 0, "missing-brief", "Numbered phase brief is not readable.");
     }
   }
   return { planPath, briefPaths, ok: issues.length === 0, issues };
 }
+function addIssue(issues, file, line, code, message) {
+  issues.push({ file, line, code, message });
+}
+function visibleLines(source) {
+  let fenced = false;
+  return source.split(/\r?\n/).map((line) => {
+    if (/^\s*```/.test(line)) {
+      fenced = !fenced;
+      return "";
+    }
+    return fenced ? "" : line;
+  });
+}
+function checkHeadings(lines, file, names, issues) {
+  const found = lines.flatMap((line, i) => line.startsWith("## ") ? [{ text: line, line: i + 1 }] : []);
+  const expected = names.map((name) => `## ${name}`);
+  if (found.map(({ text }) => text).join(`
+`) !== expected.join(`
+`))
+    addIssue(issues, file, found[0]?.line ?? 0, "headings", `Expected headings, in order: ${expected.join(", ")}.`);
+}
 
 // src/tools/plan.ts
 var schema2 = z4.object({ plan: z4.string().min(1), cwd: z4.string().optional() }).strict();
@@ -1345,7 +1208,7 @@ import { z as z10 } from "zod";
 // src/extensions/misex.ts
 import { mkdir as mkdir3, readFile as readFile5, writeFile as writeFile2 } from "node:fs/promises";
 import { homedir as homedir3 } from "node:os";
-import { basename as basename4, dirname as dirname4, join as join9 } from "node:path";
+import { basename as basename4, dirname as dirname5, join as join9 } from "node:path";
 var MISE_HOOK_START = "# >>> @difflab/pi mise >>>";
 var MISE_HOOK_END = "# <<< @difflab/pi mise <<<";
 var mise = {
@@ -1380,7 +1243,7 @@ var mise = {
     const separator = current.length === 0 || current.endsWith(`
 `) ? "" : `
 `;
-    await mkdir3(dirname4(hook.path), { recursive: true });
+    await mkdir3(dirname5(hook.path), { recursive: true });
     await writeFile2(hook.path, `${current}${separator}${hook.content}`, "utf8");
     return { path: hook.path, changed: true, planned: false };
   },
@@ -3585,7 +3448,7 @@ function normalizeModelReference(value) {
 // src/mcp.ts
 import { mkdir as mkdir5, readFile as readFile12, writeFile as writeFile6 } from "node:fs/promises";
 import { homedir as homedir6 } from "node:os";
-import { dirname as dirname5, join as join14 } from "node:path";
+import { dirname as dirname6, join as join14 } from "node:path";
 var mcp = {
   globalConfigPath(homeDir = homedir6()) {
     return join14(homeDir, ".config", "mcp", "mcp.json");
@@ -3601,7 +3464,7 @@ var mcp = {
     const next = { ...current, mcpServers: nextServers };
     const changed = JSON.stringify(current) !== JSON.stringify(next);
     if (changed && !options.dryRun) {
-      await mkdir5(dirname5(path), { recursive: true });
+      await mkdir5(dirname6(path), { recursive: true });
       await writeFile6(path, `${JSON.stringify(next, null, 2)}
 `, "utf8");
     }
@@ -3645,7 +3508,7 @@ function isRecord(value) {
 // src/pi.ts
 import { mkdir as mkdir6, writeFile as writeFile7 } from "node:fs/promises";
 import { homedir as homedir7 } from "node:os";
-import { dirname as dirname6, join as join15 } from "node:path";
+import { dirname as dirname7, join as join15 } from "node:path";
 var pi = {
   executableCheck: findPiExecutable,
   packageList: listPiPackages,
@@ -3662,7 +3525,7 @@ async function ensurePiAgent(filename, content, agentDir = resolvePiAgentDir(),
   const currentText = await readTextIfExists(path);
   const changed = currentText !== content;
   if (changed && !dryRun) {
-    await mkdir6(dirname6(path), { recursive: true });
+    await mkdir6(dirname7(path), { recursive: true });
     await writeFile7(path, content, "utf8");
   }
   return { path, changed, existed: currentText !== undefined, planned: changed && dryRun };
@@ -3699,7 +3562,7 @@ async function ensurePiConfig(path, update, dryRun = false) {
   const next = update(current);
   const changed = JSON.stringify(current) !== JSON.stringify(next);
   if (changed && !dryRun) {
-    await mkdir6(dirname6(path), { recursive: true });
+    await mkdir6(dirname7(path), { recursive: true });
     await writeFile7(path, `${JSON.stringify(next, null, 2)}
 `, "utf8");
   }

package/package.json

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

package/skills/plan/SKILL.md

@@ -18,13 +18,13 @@ For foreground authoring, call `diffpi_modes_set({agent: "planner"})` using the
 
 ## Live-file contract
 
-Plans live under the initiating nested Git root in one flat `.diffpi/plan/<YYMMDD[-ticket]-short-slug>/` directory. The date and slug are parts of ONE directory name, never nested `date/slug` directories. Resolve collisions before writing. Use ordinary `read`/`write`/`edit` calls, read every file back, and preserve intent, IDs, completed evidence, order, dependencies, scopes, and constraints. Edit only live plan files; never managed records, plugin source, tests, or profiles. `INCOMPLETE` is a visible marker inside an open `DRAFT`, not a status enum.
+Plans live under the initiating nested Git root in one flat `.diffpi/plan/<YYMMDD[-ticket]-short-slug>/` directory. The date and slug are parts of ONE directory name, never nested `date/slug` directories. Resolve collisions before writing. Use ordinary `read`/`write`/`edit` calls, read every file back, and preserve intent, IDs, completed evidence, order, dependencies, scopes, and constraints. Document phase constraints in each phase's `PLAN.md` entry (use `None` if empty). Each brief puts its sole action-labeled, fenced `text` file tree under `## Files Affected` immediately after `## Objective` (never a bullet list); `## Implementation Constraints` is free-form with optional subheadings. Edit only live plan files; never managed records, plugin source, tests, or profiles. `INCOMPLETE` is a visible marker inside an open `DRAFT`, not a status enum.
 
 `new` and `update` run the stateless read-only `plan_verify` on the current files, then review the complete current draft with one reviewer profile. Repair actionable findings, rerun mechanical verification after each repair, and invoke the same named reviewer again in a fresh `Agent` call (never resume a finished child) within bounded attempts. They remain `DRAFT` after a successful review. Require the child to complete with an attested explicit PASS; partial, steered, stopped, missing, and BLOCKING reports never count. `finalize` and draft `go` write `READY` only after both a passing `plan_verify` on current files and that completed reviewer PASS; do not dispatch Workers or write ready after repairing a failed review without a new completed review. An already-ready plan is reread and mechanically verified too. `plan_verify` does not judge quality, change status, freeze files, or replace the reviewer. No retired managed-plan tools.
 
 ## Execution
 
-`go --mode no-commit|commit|push` defaults to `no-commit`. The Orchestrator is the only writer of plan status/checkboxes and coordinates Workers. A draft gets one mechanical `plan_verify` check and one reviewer per pass; both must pass on current files before ready. Schedule a phase only after all prerequisites complete; derive each bounded Worker's task scope from its steps and the phase's sole file tree. Serialize tasks with overlapping or uncertain derived scopes; independent tasks may run concurrently only when scopes are unambiguously disjoint and prerequisites are satisfied. Run project format, lint, test, and CI checks via `bash`/`ctx_execute` as appropriate. On any failure, preserve the exact command/output, attempts, and affected role and block.
+`go --mode no-commit|commit|push` defaults to `no-commit`. The Orchestrator is the only writer of plan status/checkboxes and coordinates Workers. A draft gets one mechanical `plan_verify` check and one reviewer per pass; both must pass on current files before ready. Schedule a phase only after all prerequisites complete; derive each bounded Worker's task scope from its steps and the phase's sole Files Affected tree. Serialize tasks with overlapping or uncertain derived scopes; independent tasks may run concurrently only when scopes are unambiguously disjoint and prerequisites are satisfied. Run project format, lint, test, and CI checks via `bash`/`ctx_execute` as appropriate. On any failure, preserve the exact command/output, attempts, and affected role and block.
 
 With `commit`, after gates pass make one phase commit. With `push`, push it and call `watch_ci` for that exact SHA; do not push the next phase until settled. `--bg` has one child only and that child does not redispatch. No stateful plan tools.
 

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

@@ -5,21 +5,20 @@ Build from repository evidence. Keep the result compact and useful to a Worker.
 ## PLAN.md
 
 - 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.
+- Give each phase a stable ID, title, objective, prerequisites, and documented phase-wide guardrails (use `None` if there are none). Prerequisites and phase constraints belong in `PLAN.md` only; keep detailed technology, algorithm, and invariant instructions for the brief instead of copying them into both places.
 - 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.
 
 ## Implementation brief
 
 - Give tasks ordered implementation steps. Add nested `Verify` bullets under the relevant task; verification is part of the task, not a separate task.
-- Put all exact file scopes in the single phase-level file tree; do not add per-task file scopes. Include 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]`.
+- Put `## Files Affected` immediately after `## Objective` and before `## Tasks`. It is the sole phase-level file scope: include exactly one fenced `text` file tree with a directory root and branches whose file leaves start with `[ADD]`, `[MODIFY]`, `[REMOVE]`, `[MOVE from: old/path]`, or `[VERIFY]`. Do not replace the tree with Markdown bullets or add per-task file scopes. Include acceptance criteria for every task.
+- Write `## Implementation Constraints` as useful free-form implementation guidance. Add `### Required Libraries & Technology Choices`, `### Key Algorithm Specifications`, or `### Core Invariants` only when useful; do not require any of them. Do not restate or paraphrase the phase-wide guardrails in `PLAN.md` here; refer to the phase ID when a connection is needed.
 - Read back each file after writing it. Normal successive write/edit calls are intentional: incomplete drafts remain visible until the plan is ready.
 
 ## Review and repair
 
-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.
+Template metadata such as managed revisions or snapshots is not part of the live-file contract. Leave historical plan files untouched; current plans use the direct-file format.
 
 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.
 

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

@@ -4,7 +4,7 @@
 
 1. Parse `--mode no-commit|commit|push`; default is `no-commit`. Select the shared inline profile with `diffpi_modes_set({agent: "orchestrator"})` and verify `diffpi_modes_status` on the next turn. If switching or evidence fails, stop with the exact error. Git/project tasks and gates run through `bash` (or `ctx_execute` for large output); there are no `task`, `format`, `lint`, `test`, `ci`, `git`, or `push` tools.
 2. Select and reread the current live `PLAN.md` and all numbered briefs. Run `plan_verify` on that exact plan directory; if it reports issues, stop in its current state and repair through Planner before trying again. If `DRAFT`, invoke exactly one named `diffpi-plan-reviewer` per pass with `Agent(run_in_background:false)`; do not impose a short turn limit. Independently verify runtime attestation and require a **completed** child result with an explicit PASS and no BLOCKING findings. A `steered`, partial, stopped, missing, or failed result is NOT a pass. On findings, hand repairs to Planner, reread live files, rerun `plan_verify`, then invoke the same named reviewer profile in a fresh `Agent` call (not `resume`) within bounded attempts. Write `READY` and dispatch Workers ONLY after a current mechanical PASS and a completed attested reviewer PASS; otherwise leave `DRAFT` and stop with exact evidence. Do not launch a duplicate background child or recursively dispatch. If already `READY`, reread and verify current files as-is.
-3. The Orchestrator alone writes live plan checkboxes/status. Schedule a phase only after every prerequisite is complete. Derive a bounded Worker scope per task from that phase brief's sole file tree and the task's steps; never invent separate per-task scope fields. Serialize when task-to-file ownership is uncertain or scopes overlap. Dispatch disjoint Workers concurrently only when prerequisites are complete and ownership is unambiguous. The Worker never edits plan files, commits, redispatches, asks questions, or falls back inline.
+3. The Orchestrator alone writes live plan checkboxes/status. Schedule a phase only after every prerequisite is complete. Derive a bounded Worker scope per task from that phase brief's sole fenced Files Affected tree and the task's steps; never invent separate per-task scope fields. Serialize when task-to-file ownership is uncertain or scopes overlap. Dispatch disjoint Workers concurrently only when prerequisites are complete and ownership is unambiguous. The Worker never edits plan files, commits, redispatches, asks questions, or falls back inline.
 4. Run the declared project format, lint, test, and CI gates through `bash`/`ctx_execute`. On Worker, gate, preflight, reviewer, or command failure, block; preserve the exact command/output, attempts, and affected role.
 5. In `no-commit`, continue only with verified gates. In `commit`, after all phase gates pass, make exactly one commit for that phase. In `push`, push that phase commit, obtain its exact SHA, and call `watch_ci` for that SHA; do not push or schedule the next phase until CI settles successfully.
 

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

@@ -4,7 +4,7 @@
 
 1. Select the shared inline profile with `diffpi_modes_set({agent: "planner"})` (not `plan:planner`) and verify `diffpi_modes_status` on the next turn; stop on unavailable switch or unverifiable evidence.
 2. Resolve the initiating nested Git root and a flat `.diffpi/plan/<YYMMDD[-ticket]-short-slug>/` directory (one date-prefixed directory, not `date/slug`). Check collisions and stop before writing an existing match. Research only after selection.
-3. Successively write `PLAN.md` and one numbered brief per phase. Preserve exact phase/task parity, dependencies, scopes, constraints, acceptance criteria, and one action-labeled tree per brief; read every file back.
+3. Successively write `PLAN.md` and one numbered brief per phase. Document each phase's high-level constraints in `PLAN.md` (use `None` if empty) without copying implementation details there. Do not repeat or paraphrase those phase constraints in a brief; reference the phase ID instead. Give each brief a `## Files Affected` section immediately after `## Objective` and before `## Tasks`, containing exactly one fenced `text` action-labeled file tree rather than Markdown bullets, with free-form `## Implementation Constraints` after tasks; optional implementation subheadings are not mandatory. Preserve phase/task parity, dependencies, scopes, and acceptance criteria; read every file back.
 4. Run read-only `plan_verify` against the live directory and repair structural issues before invoking exactly one reviewer. Verify its attestation and review the complete current draft. Repair actionable findings, rerun `plan_verify`, then invoke the same named reviewer profile in a fresh `Agent` call (not `resume`) within bounded attempts.
 5. Leave the plan marked `DRAFT` after a successful review. Do not write `READY`; only `/plan finalize` or draft `/plan go` may do that.
 

package/templates/plan/PLAN.md

@@ -37,6 +37,7 @@
 - **Phase ID:** <!-- assign a stable phase ID -->
 - **Prerequisites:** <!-- list phase IDs, or “None” -->
 - **Objective:** <!-- state the outcome -->
+- **Constraints:** <!-- phase guardrails or None; do not repeat them in briefs -->
 
 - [ ] <!-- assign a stable task ID --> Task title
 - [ ] <!-- assign a stable task ID --> Another task title

package/templates/plan/implementation.md

@@ -7,6 +7,17 @@
 
 {{phase_objective}}
 
+## Files Affected
+
+<!-- This is the sole file scope for this phase. Use one fenced text tree; label each file leaf [ADD], [MODIFY], [REMOVE], [MOVE from: path], or [VERIFY]. Do not repeat file scopes in tasks or PLAN.md. -->
+
+```text
+Phase {{phase_ordinal}}/
+├── [MODIFY] <!-- exact/path/to/implementation-file -->
+└── [VERIFY] <!-- exact/path/to/test-or-check -->
+{{phase_files_affected}}
+```
+
 ## Tasks
 
 <!-- Keep tasks flat and in phase order. Repeat this shape for each task. -->
@@ -25,21 +36,6 @@
 
 ## Implementation Constraints
 
-### Libraries and Algorithms
-
-{{phase_libraries}}
+<!-- Free-form implementation details, not a restatement of PLAN.md phase constraints. Add only useful optional headings: Required Libraries & Technology Choices, Key Algorithm Specifications, Core Invariants. Refer to the PLAN.md phase ID instead of repeating a phase guardrail. -->
 
-### Constraints
-
-{{phase_constraints}}
-
-## Phase File Tree
-
-<!-- This is the only file scope for the phase; do not repeat file scopes inside tasks or PLAN.md. Include exactly one tree. Label every file leaf with [ADD], [MODIFY], [REMOVE], [MOVE from: path], or [VERIFY]. -->
-
-```text
-Phase {{phase_ordinal}}/
-├── [MODIFY] <!-- exact/path/to/implementation-file -->
-└── [VERIFY] <!-- exact/path/to/test-or-check -->
-{{phase_file_tree}}
-```
+{{phase_implementation_constraints}}