pan-wizard 3.35.0 → 3.37.0

package/pan-wizard-core/bin/lib/phase.cjs

@@ -278,9 +278,9 @@ function cmdPhasePlanIndex(cwd, phase, raw, opts = {}) {
   const planFiles = filterPlanFiles(phaseFiles);
   const summaryFiles = filterSummaryFiles(phaseFiles);
 
-  const { plans, waves, incomplete, hasCheckpoints } = buildPlanIndex(phaseDir, planFiles, summaryFiles);
+  const { plans, waves, subWaves, incomplete, hasCheckpoints } = buildPlanIndex(phaseDir, planFiles, summaryFiles);
 
-  const result = { phase: normalized, plans, waves, incomplete, has_checkpoints: hasCheckpoints };
+  const result = { phase: normalized, plans, waves, sub_waves: subWaves, incomplete, has_checkpoints: hasCheckpoints };
   // `--failed <ids>` (market-ideas M28): the plans that must not run after those
   // failed, because a dependency, direct or transitive, is among them.
   if (opts.failed) {
@@ -336,6 +336,35 @@ function blockedPlans(plans, failedIds) {
  * @param {string[]} summaryFiles - List of summary filenames
  * @returns {{plans: Array, waves: Object, incomplete: string[], hasCheckpoints: boolean}}
  */
+/**
+ * Split one wave's plans into sub-waves so no two plans in a sub-wave modify the same
+ * file (program A3). Greedy, in plan order: each plan joins the first sub-wave it does
+ * not overlap. A plan that declares no files may touch anything, so it runs alone.
+ * @param {Array<{id: string, files_modified?: string[]}>} plans
+ * @returns {string[][]} plan ids per sub-wave
+ */
+function partitionWave(plans) {
+  const subs = [];
+  const norm = (p) => String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+  for (const p of plans) {
+    const files = (p.files_modified || []).map(norm);
+    const solo = files.length === 0;
+    let placed = false;
+    if (!solo) {
+      for (const sub of subs) {
+        if (sub.solo) continue;
+        if (files.some((x) => sub.files.has(x))) continue;
+        sub.ids.push(p.id);
+        for (const x of files) sub.files.add(x);
+        placed = true;
+        break;
+      }
+    }
+    if (!placed) subs.push({ ids: [p.id], files: new Set(files), solo });
+  }
+  return subs.map((x) => x.ids);
+}
+
 function buildPlanIndex(phaseDir, planFiles, summaryFiles) {
   const completedPlanIds = new Set(
     summaryFiles.map(summaryFile => summaryFile.replace('-summary.md', '').replace('summary.md', ''))
@@ -401,7 +430,14 @@ function buildPlanIndex(phaseDir, planFiles, summaryFiles) {
     waves[waveKey].push(planId);
   }
 
-  return { plans, waves, incomplete, hasCheckpoints };
+  // A3: within a wave, plans that share a file run in different sub-waves.
+  const subWaves = {};
+  for (const [w, ids] of Object.entries(waves)) {
+    subWaves[w] = partitionWave(ids.map((id) => plans.find((p) => p.id === id)));
+    subWaves[w].forEach((sub, i) => { for (const id of sub) plans.find((p) => p.id === id).sub_wave = i; });
+  }
+
+  return { plans, waves, subWaves, incomplete, hasCheckpoints };
 }
 
 /**
@@ -430,6 +466,30 @@ function appendPhaseChecklistEntry(content, phaseNum, name) {
   return lines.join('\n');
 }
 
+/**
+ * Add an inserted phase's "## Phases" checklist entry after its base phase's entry and
+ * that phase's existing decimals, so the list stays in numeric order (appending put 3.1
+ * after Phase 4; found by H7's property test). Falls back to appending when the base
+ * phase has no checklist entry.
+ *
+ * @param {string} content - Full roadmap.md content
+ * @param {string} basePhase - The integer phase inserted after, without leading zeros
+ * @param {string} phaseNum - The inserted phase's number as it should appear
+ * @param {string} name - Phase name/description
+ * @returns {string} Updated content
+ */
+function insertPhaseChecklistEntry(content, basePhase, phaseNum, name) {
+  const lines = content.split('\n');
+  const own = new RegExp(`^\\s*- \\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+0*${escapeRegex(basePhase)}(?:\\.\\d+)*:`, 'i');
+  let lastIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (own.test(lines[i])) lastIdx = i;
+  }
+  if (lastIdx === -1) return appendPhaseChecklistEntry(content, phaseNum, name);
+  lines.splice(lastIdx + 1, 0, `- [ ] **Phase ${phaseNum}: ${name}**`);
+  return lines.join('\n');
+}
+
 /**
  * Append a new phase to the end of the roadmap and create its directory.
  * @param {string} cwd - Working directory path
@@ -581,20 +641,24 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
   }
 
   const headerIdx = content.indexOf(headerMatch[0]);
-  const afterHeader = content.slice(headerIdx + headerMatch[0].length);
-  const nextPhaseMatch = afterHeader.match(/\n#{2,4}\s+Phase\s+\d/i);
-
-  let insertIdx;
-  if (nextPhaseMatch) {
-    insertIdx = headerIdx + headerMatch[0].length + nextPhaseMatch.index;
-  } else {
-    insertIdx = content.length;
+  const bodyStart = headerIdx + headerMatch[0].length;
+  const afterHeader = content.slice(bodyStart);
+  // The new section goes before the next phase that is not one of this phase's decimals:
+  // after 06.1 and 06.2, not straight after Phase 6, or the roadmap (and `roadmap analyze`,
+  // which lists phases in roadmap order) would read 6, 6.3, 6.2, 6.1 (found by H7's
+  // property test).
+  const ownDecimal = new RegExp(`^#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}\\.\\d`, 'i');
+  const headingRe = /\n(#{2,4}\s+Phase\s+\d[^\n]*)/gi;
+  let insertIdx = content.length;
+  let heading;
+  while ((heading = headingRe.exec(afterHeader)) !== null) {
+    if (!ownDecimal.test(heading[1])) { insertIdx = bodyStart + heading.index; break; }
   }
 
   // Insert the detail section, then the matching checklist entry — same reason as
   // cmdPhaseAdd: without it the inserted phase never appears in the "## Phases" list.
   const withEntry = content.slice(0, insertIdx) + phaseEntry + content.slice(insertIdx);
-  const updatedContent = appendPhaseChecklistEntry(withEntry, decimalPhase, description);
+  const updatedContent = insertPhaseChecklistEntry(withEntry, unpadded, decimalPhase, description);
   try {
     fs.writeFileSync(roadmapPath, updatedContent, 'utf-8');
   } catch (e) {
@@ -713,8 +777,14 @@ function markRequirementsCompleteForPhase(cwd, phaseNum, roadmapContent) {
     const reqIds = roadmapRequirementIds(roadmapContent, phaseNum);
     if (reqIds.length === 0) return;
     let reqContent = reqReadContent;
+    // V8: a requirement with EARS criteria is ticked only when its mapped tests pass;
+    // a legacy one (no criteria) keeps the old tick. Held ones are reported.
+    const decisions = require('./requirements-lint.cjs').tickDecisions(cwd, reqIds);
+    const held = [];
 
     for (const reqId of reqIds) {
+      const d = decisions.get(reqId);
+      if (d && !d.allowed) { held.push({ id: reqId, status: d.status }); continue; }
       const reqEscaped = escapeRegex(reqId);
       reqContent = reqContent.replace(
         new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi'),
@@ -731,7 +801,7 @@ function markRequirementsCompleteForPhase(cwd, phaseNum, roadmapContent) {
     } catch (e) {
       return { updated: false, error: 'Failed to write requirements.md: ' + e.message };
     }
-    return { updated: true };
+    return { updated: true, held };
   } catch {
     // requirements.md not found or unreadable — skip
     return { updated: false };
@@ -999,6 +1069,7 @@ function classifyPlanTier(frontmatter, config) {
 }
 
 module.exports = {
+  partitionWave,
   cmdPhasesList,
   cmdPhaseNextDecimal,
   cmdFindPhase,
@@ -1016,6 +1087,7 @@ module.exports = {
   renumberIntegerPhases,
   updateRoadmapAfterRemoval,
   markPhaseCompleteInRoadmap,
+  markRequirementsCompleteForPhase,
   updateStateAfterPhaseComplete,
   classifyPlanTier,
 };

package/pan-wizard-core/bin/lib/plan-lint.cjs

@@ -0,0 +1,310 @@
+'use strict';
+/**
+ * Plan intent checked in code: the parts of a plan check that are reading, not
+ * judgement, so the plan-checker is not spent on them.
+ *
+ * `verify review-focus <phase>` (program P4, M41). A plan names, under
+ * `## Review Focus`, at most five inputs or failure modes its requirements imply and
+ * no test exercises yet, each pinned to the task that owns the code and the test that
+ * task adds. A plan with none says so on one `None — <reason>` line. The reviewer gets
+ * the section through `review scope` (R1).
+ *
+ * `verify decisions <phase>` (program P2). The phase design records its decisions with
+ * ids (`DD-N`), and only the ones that pass the three-question test (hard to reverse,
+ * a reasonable engineer could choose otherwise, more than one task depends on it).
+ * Plans cite the ids they implement. A plan citing an id the design does not record
+ * relies on a decision nobody approved; a recorded decision no plan cites is approved
+ * design nobody builds. A design from before ids is `legacy`: a warning, never a refusal.
+ */
+const fs = require('fs');
+const path = require('path');
+const { output, error, toLf } = require('./core.cjs');
+const { getPlanId } = require('./constants.cjs');
+const { phaseFiles } = require('./verify-plan-set.cjs');
+const { sectionBody } = require('./verify-scope.cjs');
+
+const REVIEW_FOCUS_MAX = 5;
+const DECISION_ID_RE = /\bDD-\d+\b/g;
+
+function readText(file) {
+  try { return toLf(fs.readFileSync(file, 'utf-8')); } catch { return ''; }
+}
+
+/** The phase's plans as `{plan, file, text}`, or `{error, reason}`. */
+function phasePlans(cwd, phase) {
+  const pf = phaseFiles(cwd, phase);
+  if (pf.error) return pf;
+  return { pf, plans: pf.planFiles.map((file) => ({ plan: getPlanId(file), file, text: readText(path.join(pf.dir, file)) })) };
+}
+
+// ─── Review Focus (P4) ───────────────────────────────────────────────────────
+
+/**
+ * Text with HTML comments removed: repeated until nothing changes, since removing
+ * one can join the text around it into another, and an unclosed `<!--` hides the
+ * rest. A placeholder comment is not a Review Focus item.
+ */
+function stripComments(s) {
+  let prev;
+  do { prev = s; s = s.replace(/<!--[\s\S]*?-->/g, ''); } while (s !== prev);
+  const open = s.indexOf('<!--');
+  return open === -1 ? s : s.slice(0, open);
+}
+
+/** Check one plan's `## Review Focus`. */
+function reviewFocusOf(p) {
+  const body = sectionBody(p.text, 'Review Focus');
+  const out = { plan: p.plan, file: p.file, status: 'ok', items: 0 };
+  const errors = [];
+  if (body == null) {
+    errors.push({ code: 'review_focus_missing', plan: p.plan, detail: 'no `## Review Focus` section' });
+    return { ...out, status: 'missing', errors };
+  }
+  const text = stripComments(body).trim();
+  const items = text.split('\n').map((l) => l.match(/^\s*(?:[-*]|\d+[.)])\s+(.*\S)/)).filter(Boolean).map((m) => m[1]);
+  if (!items.length) {
+    // `None — <reason>`: the reason is what tells the checker the planner looked.
+    const none = text.match(/^none\b[\s—–:-]*(.*)$/im);
+    if (none && none[1].trim().split(/\s+/).length >= 3) return { ...out, status: 'none', errors };
+    errors.push({ code: 'review_focus_empty', plan: p.plan, detail: 'no items, and no `None — <reason>` line' });
+    return { ...out, status: 'invalid', errors };
+  }
+  out.items = items.length;
+  if (items.length > REVIEW_FOCUS_MAX) {
+    errors.push({ code: 'review_focus_too_many', plan: p.plan, detail: `${items.length} items; at most ${REVIEW_FOCUS_MAX}` });
+  }
+  const taskCount = (p.text.match(/<task\b/g) || []).length;
+  for (const item of items) {
+    const short = item.slice(0, 80);
+    const task = item.match(/\bTask\s+(\d+)\b/i);
+    if (!task) errors.push({ code: 'review_focus_no_task', plan: p.plan, detail: `names no owning task: ${short}` });
+    else if (Number(task[1]) < 1 || Number(task[1]) > taskCount) errors.push({ code: 'review_focus_unknown_task', plan: p.plan, detail: `Task ${task[1]} is not one of the plan's ${taskCount} tasks: ${short}` });
+    if (!/\btests?\b/i.test(item)) errors.push({ code: 'review_focus_no_test', plan: p.plan, detail: `names no test: ${short}` });
+  }
+  return { ...out, status: errors.length ? 'invalid' : 'ok', errors };
+}
+
+/**
+ * @returns {{phase, ok, plans: Array<{plan, file, status, items}>, errors}} or `{error, reason}`
+ */
+function checkReviewFocus(cwd, phase) {
+  const pp = phasePlans(cwd, phase);
+  if (pp.error) return pp;
+  const results = pp.plans.map(reviewFocusOf);
+  const errors = results.flatMap((r) => r.errors);
+  return { phase: pp.pf.info.phase_number, ok: errors.length === 0, plans: results.map(({ errors: _e, ...r }) => r), errors };
+}
+
+// ─── Decision spine (P2) ─────────────────────────────────────────────────────
+
+/** Decision ids a design records: the first cell of a table row, or the head of a list item. */
+function recordedDecisions(text) {
+  const ids = [];
+  for (const line of text.split('\n')) {
+    const m = line.match(/^\s*\|\s*\**(DD-\d+)\**\s*\|/) || line.match(/^\s*(?:[-*]|\d+[.)])\s+\**(DD-\d+)\**\b/) || line.match(/^#{2,6}\s+(DD-\d+)\b/);
+    if (m) ids.push(m[1]);
+  }
+  return ids;
+}
+
+/**
+ * @returns {{phase, ok, status: 'checked'|'no_design'|'legacy', design, decisions, cited, errors, warnings}} or `{error, reason}`
+ */
+function checkDecisions(cwd, phase) {
+  const pp = phasePlans(cwd, phase);
+  if (pp.error) return pp;
+  const base = { phase: pp.pf.info.phase_number, ok: true, design: null, decisions: [], cited: {}, errors: [], warnings: [] };
+  let designFile = null;
+  try { designFile = fs.readdirSync(pp.pf.dir).filter((f) => /-design\.md$/i.test(f)).sort()[0] || null; } catch { /* phaseFiles read it */ }
+  if (!designFile) return { ...base, status: 'no_design' };
+  const recorded = recordedDecisions(readText(path.join(pp.pf.dir, designFile)));
+  const design = path.posix.join(pp.pf.info.directory.replace(/\\/g, '/'), designFile);
+  if (!recorded.length) {
+    return { ...base, status: 'legacy', design, warnings: [{ code: 'decisions_without_ids', detail: `${designFile} records no DD-N decision ids; plans cannot cite them` }] };
+  }
+  const errors = [];
+  const seen = new Set();
+  for (const id of recorded) {
+    if (seen.has(id)) errors.push({ code: 'decision_duplicate', id, detail: `${id} is recorded more than once in ${designFile}` });
+    seen.add(id);
+  }
+  const cited = {};
+  for (const p of pp.plans) {
+    for (const id of new Set(p.text.match(DECISION_ID_RE) || [])) {
+      if (!seen.has(id)) errors.push({ code: 'decision_unrecorded', plan: p.plan, id, detail: `${p.plan} cites ${id}, which ${designFile} does not record` });
+      else (cited[id] = cited[id] || []).push(p.plan);
+    }
+  }
+  const decisions = [...seen].sort((a, b) => Number(a.slice(3)) - Number(b.slice(3)));
+  for (const id of decisions) {
+    if (!cited[id]) errors.push({ code: 'decision_uncited', id, detail: `${id} is recorded in ${designFile} and cited by no plan` });
+  }
+  return { ...base, ok: errors.length === 0, status: 'checked', design, decisions, cited, errors };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+// ─── Gate baselines (M48) ─────────────────────────────────────────────────────
+//
+// A plan's `<verify>` often names a grep or count gate. One that already passes
+// before any work proves nothing about the task; one whose pattern cannot compile
+// can never match (gsd-core v1.18.0 "gate baselines"). The simple grep forms are
+// interpreted here, in Node, never through a shell: the same on every platform,
+// and nothing a plan writes is executed. Anything else is listed as not checkable.
+
+const GATE_TOOLS = [['git', 'grep'], ['grep'], ['rg']];
+const GATE_FLAGS = new Set(['r', 'R', 'i', 'c', 'E', 'F', 'w', 'q', 'l', 'n', 's', 'H', 'h']);
+const REGRESSION_GUARD = /regression guard|already passes|must still pass/i;
+
+/** Split a command line on spaces, honouring quotes. Null on shell syntax. */
+function shellWords(cmd) {
+  const words = [];
+  let cur = '';
+  let quote = null;
+  let started = false;
+  for (const ch of cmd) {
+    if (quote) {
+      if (ch === quote) quote = null; else cur += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; started = true; continue; }
+    if (/[|;&<>`$()\\]/.test(ch)) return null;
+    if (/\s/.test(ch)) { if (started) { words.push(cur); cur = ''; started = false; } continue; }
+    cur += ch; started = true;
+  }
+  if (quote) return null;
+  if (started) words.push(cur);
+  return words;
+}
+
+/**
+ * Parse a simple grep gate: `grep|rg|git grep [flags] PATTERN [paths...]`.
+ * @returns {{tool, flags, pattern, paths}|null} null when the command is not one
+ */
+function parseGateCommand(cmd) {
+  const words = shellWords(String(cmd || '').trim());
+  if (!words || !words.length) return null;
+  const tool = GATE_TOOLS.find((t) => t.every((w, i) => words[i] === w));
+  if (!tool) return null;
+  const flags = {};
+  let pattern = null;
+  const paths = [];
+  let flagsDone = false;
+  for (const w of words.slice(tool.length)) {
+    if (!flagsDone && w === '--') { flagsDone = true; continue; }
+    if (!flagsDone && /^-[A-Za-z]+$/.test(w)) {
+      for (const f of w.slice(1)) { if (!GATE_FLAGS.has(f)) return null; flags[f] = true; }
+      continue;
+    }
+    if (!flagsDone && w.startsWith('-')) return null;
+    if (pattern === null) pattern = w; else paths.push(w);
+  }
+  if (pattern === null) return null;
+  return { tool: tool.join(' '), flags, pattern, paths };
+}
+
+/** A JS RegExp for a grep pattern: -F literal, -E extended, else basic (BRE). Null when it cannot compile. */
+function gateRegex(g) {
+  let src = g.pattern;
+  if (g.flags.F) src = src.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  else if (!g.flags.E && g.tool !== 'rg') {
+    // BRE: \( \) \{ \} \| \+ \? are the operators; their bare forms are literals.
+    src = src.replace(/\\([(){}|+?])|([(){}|+?])/g, (m, esc, bare) => (esc ? esc : '\\' + bare));
+  }
+  if (g.flags.w) src = `\\b(?:${src})\\b`;
+  try { return new RegExp(src, g.flags.i ? 'i' : ''); } catch { return null; }
+}
+
+function filesUnder(root, rel, recursive) {
+  const abs = path.join(root, rel);
+  let st;
+  try { st = fs.statSync(abs); } catch { return null; }
+  if (st.isFile()) return [abs];
+  if (!st.isDirectory() || !recursive) return [];
+  const out = [];
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (e.name === '.git' || e.name === 'node_modules') continue;
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p); else if (e.isFile()) out.push(p);
+    }
+  };
+  walk(abs);
+  return out;
+}
+
+/** Run a parsed gate against the tree as it is: passes_now | fails_now | target_missing | invalid. */
+function runGate(cwd, g) {
+  const re = gateRegex(g);
+  if (!re) return 'invalid';
+  const recursive = g.tool !== 'grep' || g.flags.r || g.flags.R;
+  const targets = g.paths.length ? g.paths : ['.'];
+  let anyTarget = false;
+  for (const t of targets) {
+    const files = filesUnder(cwd, t, recursive);
+    if (files === null) continue;
+    anyTarget = true;
+    for (const f of files) {
+      let text;
+      try { text = toLf(fs.readFileSync(f, 'utf-8')); } catch { continue; }
+      if (text.split('\n').some((line) => re.test(line))) return 'passes_now';
+    }
+  }
+  return anyTarget ? 'fails_now' : 'target_missing';
+}
+
+/** The gate commands in a plan: backticked spans inside each task's <verify>. */
+function gatesOf(text) {
+  const out = [];
+  const taskRe = /<task\b[^>]*>([\s\S]*?)<\/task>/g;
+  let t;
+  while ((t = taskRe.exec(text)) !== null) {
+    const name = ((t[1].match(/<name>([\s\S]*?)<\/name>/) || [])[1] || 'unnamed').trim();
+    const verify = (t[1].match(/<verify>([\s\S]*?)<\/verify>/) || [])[1] || '';
+    for (const m of verify.matchAll(/`([^`]+)`/g)) out.push({ task: name, command: m[1].trim(), guard: REGRESSION_GUARD.test(verify) });
+  }
+  return out;
+}
+
+function checkGates(cwd, phase) {
+  const pp = phasePlans(cwd, phase);
+  if (pp.error) return pp;
+  const gates = [];
+  const errors = [];
+  for (const p of pp.plans) {
+    for (const g of gatesOf(p.text)) {
+      const parsed = parseGateCommand(g.command);
+      const status = parsed ? runGate(cwd, parsed) : 'not_checkable';
+      gates.push({ plan: p.plan, task: g.task, command: g.command, status, ...(g.guard ? { regression_guard: true } : {}) });
+      if (status === 'passes_now' && !g.guard) errors.push({ code: 'gate_vacuous', plan: p.plan, task: g.task, command: g.command, detail: 'passes before any work, so it cannot show the task did anything; check for what the task adds, or mark it a regression guard' });
+      if (status === 'invalid') errors.push({ code: 'gate_invalid', plan: p.plan, task: g.task, command: g.command, detail: 'the pattern does not compile, so the gate can never match as written' });
+    }
+  }
+  return { phase: pp.pf.info.phase_number, ok: errors.length === 0, gates, errors };
+}
+
+function cmdVerifyGates(cwd, phase, raw) {
+  if (!phase) error('Usage: verify gates <phase>');
+  const r = checkGates(cwd, phase);
+  if (r.error) { output(r, raw); return; }
+  output(r, raw, r.ok ? 'valid' : 'invalid', r.ok ? 0 : 1);
+}
+
+function cmdVerifyReviewFocus(cwd, phase, raw) {
+  if (!phase) error('Usage: verify review-focus <phase>');
+  const r = checkReviewFocus(cwd, phase);
+  if (r.error) { output(r, raw); return; }
+  output(r, raw, r.ok ? 'valid' : 'invalid', r.ok ? 0 : 1);
+}
+
+function cmdVerifyDecisions(cwd, phase, raw) {
+  if (!phase) error('Usage: verify decisions <phase>');
+  const r = checkDecisions(cwd, phase);
+  if (r.error) { output(r, raw); return; }
+  output(r, raw, r.ok ? 'valid' : 'invalid', r.ok ? 0 : 1);
+}
+
+module.exports = {
+  REVIEW_FOCUS_MAX, checkReviewFocus, checkDecisions, recordedDecisions, cmdVerifyReviewFocus, cmdVerifyDecisions,
+  parseGateCommand, checkGates, cmdVerifyGates,
+};

package/pan-wizard-core/bin/lib/preview.cjs

@@ -152,6 +152,9 @@ function buildPhasePreview(cwd, phaseNum) {
     risk_signals,
     risk_score,
     plans: planContents.map(p => ({ file: p.file, bytes: Buffer.byteLength(p.content, 'utf-8') })),
+    // p10/p50/p90 dollars for this phase's plans, from the project's own cost ledger
+    // (P6); this phase's rows are left out of its own samples.
+    cost_forecast: require('./cost.cjs').costForecast(cwd, { plans: planFiles.length, excludePhase: phaseInfo.phase_number || phaseNum }),
   };
 }
 
@@ -368,7 +371,7 @@ function buildMilestoneETA(cwd) {
   const remaining = phaseList.filter(p => !p.completed);
 
   // Sample phase durations from summary frontmatter or commit metadata.
-  const durations = sampleCompletedPhaseDurations(cwd, completed);
+  const { durations, sources } = sampleCompletedPhaseDurations(cwd, completed, { withSources: true });
   const avg = durations.length > 0
     ? durations.reduce((a, b) => a + b, 0) / durations.length
     : 5.0; // default 5 days per phase when no history
@@ -405,6 +408,9 @@ function buildMilestoneETA(cwd) {
     sample_size: durations.length,
     eta_date: etaDate,
     confidence_pct: confidence,
+    // L6b: where the average came from — dated summaries, the phases' plan commits, or
+    // the 5-day default when there is no history at all.
+    eta_source: durations.length === 0 ? 'default' : (sources.every((s) => s === 'git') ? 'git' : (sources.every((s) => s === 'summary') ? 'summary' : 'mixed')),
     bottleneck,
   };
 }
@@ -417,8 +423,9 @@ function findPhaseDir(dirs, num) {
   return dirs.find(d => d.startsWith(`${num}-`) || d.startsWith(`${padded}-`));
 }
 
-function sampleCompletedPhaseDurations(cwd, completedPhases) {
+function sampleCompletedPhaseDurations(cwd, completedPhases, opts = {}) {
   const durations = [];
+  const sources = [];
   const phasesRoot = phasesPath(cwd);
   let dirs = [];
   try { dirs = fs.readdirSync(phasesRoot); } catch { return durations; }
@@ -438,10 +445,25 @@ function sampleCompletedPhaseDurations(cwd, completedPhases) {
     const completed_at = fm.completed || fm.finished || fm.done;
     if (started && completed_at) {
       const d = daysBetween(started, completed_at);
-      if (d && d > 0 && d < 60) durations.push(d);
+      if (d && d > 0 && d < 60) { durations.push(d); sources.push('summary'); continue; }
     }
+    // No dated summary (most have none): time the phase by its plan commits, oldest to newest.
+    const g = phaseCommitSpanDays(cwd, p.num);
+    if (g && g > 0 && g < 60) { durations.push(g); sources.push('git'); }
   }
-  return durations;
+  return opts.withSources ? { durations, sources } : durations;
+}
+
+/** Days between a phase's oldest and newest plan commit ({type}({phase}-{plan}): …), or null. */
+function phaseCommitSpanDays(cwd, phaseNum) {
+  const n = String(phaseNum);
+  const padded = n.includes('.') ? n.split('.').map((s, i) => (i === 0 ? s.padStart(2, '0') : s)).join('.') : n.padStart(2, '0');
+  const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const r = require('./core.cjs').execGit(cwd, ['log', '--format=%ct', '-E', `--grep=^[a-z]+\\((${esc(padded)}|${esc(n)})-[0-9]+\\):`]);
+  if (!r || r.exitCode !== 0 || !r.stdout) return null;
+  const times = r.stdout.split('\n').map(Number).filter(Number.isFinite);
+  if (times.length < 2) return null;
+  return Math.round(((Math.max(...times) - Math.min(...times)) / 86400) * 10) / 10;
 }
 
 function findBottleneckCandidate(cwd, remainingPhases) {

package/pan-wizard-core/bin/lib/requirements-lint.cjs

@@ -0,0 +1,130 @@
+'use strict';
+/**
+ * Requirements with EARS criteria, a requirements lint and a truth→test trace matrix
+ * (program V8).
+ *
+ * A v1 requirement (a checkbox line `- [ ] **ID**: …`) carries its acceptance criteria
+ * as indented sub-bullets in an EARS form, and the tests that check them as `Test:`
+ * sub-bullets:
+ *
+ *   - [ ] **AUTH-01**: User can sign in
+ *     - WHEN a user submits a correct email and password THE SYSTEM SHALL start a session
+ *     - Test: tests/auth.test.js
+ *
+ * `verify requirements` fails a v1 requirement with no criterion (`req_no_scenario`).
+ * `verify traceability` maps each requirement to its tests and runs them: `passed`, `failing`,
+ * or `not_checked` when a truth has no test (an untested truth is never read as met).
+ * `phase complete` ticks a requirement that has criteria only when its trace passes; a
+ * legacy requirement with no criteria keeps the old tick, so existing projects work.
+ */
+const fs = require('fs');
+const path = require('path');
+const { output, toLf } = require('./core.cjs');
+const { planningPath } = require('./utils.cjs');
+const { REQUIREMENTS_FILE } = require('./constants.cjs');
+const TG = require('./test-gate.cjs');
+
+// EARS forms: ubiquitous (THE <system> SHALL), event (WHEN … SHALL), state (WHILE …),
+// optional feature (WHERE …), unwanted behaviour (IF … THEN … SHALL).
+const EARS_RE = /^(?:(?:WHEN|WHILE|WHERE)\b[\s\S]*\bSHALL\b|IF\b[\s\S]*\bTHEN\b[\s\S]*\bSHALL\b|THE\s+\S[\s\S]*\bSHALL\b)/i;
+const REQ_RE = /^- (\[[ xX]\] )?\*\*([A-Z][A-Z0-9]*-\d+)\*\*:?\s*(.*)$/;
+const DEFAULT_TEST_TIMEOUT_MS = 3 * 60 * 1000;
+
+const isEars = (s) => EARS_RE.test(String(s || '').trim());
+
+/** The requirements in a requirements.md, with criteria and mapped tests. */
+function parseRequirements(raw) {
+  const lines = toLf(String(raw || '')).split('\n');
+  const out = [];
+  let cur = null;
+  for (const line of lines) {
+    const m = REQ_RE.exec(line);
+    if (m) {
+      cur = { id: m[2], v1: !!m[1], checked: !!m[1] && /x/i.test(m[1]), text: m[3].trim(), criteria: [], tests: [] };
+      out.push(cur);
+      continue;
+    }
+    if (!cur) continue;
+    const sub = /^\s{2,}- (.*)$/.exec(line);
+    if (!sub) { if (line.trim() !== '') cur = null; continue; }
+    const body = sub[1].trim();
+    const t = /^tests?:\s*(.+)$/i.exec(body);
+    if (t) { for (const p of t[1].split(',')) { const file = p.trim().replace(/`/g, '').split('#')[0].trim(); if (file) cur.tests.push(file); } continue; }
+    if (isEars(body)) cur.criteria.push(body);
+  }
+  return out;
+}
+
+function readRequirements(cwd) {
+  try { return fs.readFileSync(path.join(planningPath(cwd), REQUIREMENTS_FILE), 'utf-8'); } catch { return null; }
+}
+
+function lintRequirements(cwd) {
+  const text = readRequirements(cwd);
+  if (text === null) return { error: 'requirements_not_found', reason: '.planning/requirements.md is missing' };
+  const reqs = parseRequirements(text).filter((r) => r.v1);
+  const errors = reqs.filter((r) => r.criteria.length === 0).map((r) => ({ code: 'req_no_scenario', id: r.id, detail: 'no acceptance criterion in an EARS form (WHEN/WHILE/WHERE/IF … THE SYSTEM SHALL …)' }));
+  return { ok: errors.length === 0, requirements: reqs.map((r) => ({ id: r.id, criteria: r.criteria.length, tests: r.tests.length })), errors };
+}
+
+/** Run a requirement's mapped tests: passed | failing | not_checked | legacy. Pure over the cache. */
+function traceOf(cwd, req, cache, opts = {}) {
+  if (req.criteria.length === 0) return { id: req.id, status: 'legacy', tests: req.tests };
+  if (req.tests.length === 0) return { id: req.id, status: 'not_checked', tests: [], detail: 'no test is mapped to this requirement' };
+  const results = [];
+  for (const file of req.tests) {
+    if (!cache.has(file)) {
+      if (!fs.existsSync(path.join(cwd, file))) cache.set(file, { file, result: 'missing' });
+      else {
+        const fc = TG.fileCommand(cwd, file);
+        if (!fc.command) cache.set(file, { file, result: 'not_checked', detail: fc.reason });
+        else cache.set(file, { file, result: TG.runCommand(cwd, fc.command, opts.timeoutMs || DEFAULT_TEST_TIMEOUT_MS).exit === 0 ? 'passed' : 'failing' });
+      }
+    }
+    results.push(cache.get(file));
+  }
+  const status = results.some((r) => r.result === 'failing' || r.result === 'missing') ? 'failing'
+    : results.every((r) => r.result === 'passed') ? 'passed' : 'not_checked';
+  return { id: req.id, status, tests: results };
+}
+
+function traceMatrix(cwd, opts = {}) {
+  const text = readRequirements(cwd);
+  if (text === null) return { error: 'requirements_not_found', reason: '.planning/requirements.md is missing' };
+  let reqs = parseRequirements(text).filter((r) => r.v1);
+  if (opts.ids && opts.ids.length) reqs = reqs.filter((r) => opts.ids.includes(r.id));
+  const cache = new Map();
+  const requirements = reqs.map((r) => traceOf(cwd, r, cache, opts));
+  const count = (s) => requirements.filter((r) => r.status === s).length;
+  return { requirements, passed: count('passed'), failing: count('failing'), not_checked: count('not_checked'), legacy: count('legacy') };
+}
+
+/** Whether `phase complete` may tick each id. Legacy requirements may; the rest need a passing trace. */
+function tickDecisions(cwd, ids) {
+  const text = readRequirements(cwd);
+  if (text === null) return new Map(ids.map((id) => [id, { allowed: true, status: 'unknown' }]));
+  const byId = new Map(parseRequirements(text).map((r) => [r.id, r]));
+  const cache = new Map();
+  const out = new Map();
+  for (const id of ids) {
+    const r = byId.get(id);
+    if (!r) { out.set(id, { allowed: true, status: 'unknown' }); continue; }
+    const t = traceOf(cwd, r, cache);
+    out.set(id, { allowed: t.status === 'legacy' || t.status === 'passed', status: t.status });
+  }
+  return out;
+}
+
+function cmdVerifyRequirements(cwd, raw) {
+  const r = lintRequirements(cwd);
+  if (r.error) { output(r, raw, 'error', 1); return; }
+  output(r, raw, r.ok ? 'valid' : 'invalid', r.ok ? 0 : 1);
+}
+
+function cmdVerifyTrace(cwd, ids, raw) {
+  const r = traceMatrix(cwd, { ids });
+  if (r.error) { output(r, raw, 'error', 1); return; }
+  output(r, raw, r.failing ? 'failing' : (r.not_checked ? 'not_checked' : 'passed'), r.failing ? 1 : 0);
+}
+
+module.exports = { isEars, parseRequirements, lintRequirements, traceMatrix, tickDecisions, cmdVerifyRequirements, cmdVerifyTrace };