pan-wizard 3.35.0 → 3.36.0

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

@@ -12,6 +12,21 @@ const { writeStateMd, readStateSafe } = require('./state.cjs');
 const { ROADMAP_FILE, STATE_FILE, isSummaryFile } = require('./constants.cjs');
 const { planningPath, phasesPath, fileAccessible } = require('./utils.cjs');
 
+/**
+ * A regex source matching a phase number as any roadmap writes it: `phase insert` writes
+ * padded decimals (`Phase 01.1`) and `phase add` unpadded integers (`Phase 3`), so "1.1"
+ * must match both `1.1` and `01.1` (found by H7's property test: removing 1.1 deleted its
+ * directory and left its roadmap section behind).
+ * @param {string} num - a phase number, padded or not ("1.1", "01.1", "3")
+ */
+function phaseNumPattern(num) {
+  const [int, ...rest] = String(num).split('.');
+  return `0*${escapeRegex(String(parseInt(int, 10)))}${rest.map((d) => `\\.${escapeRegex(d)}`).join('')}`;
+}
+
+/** Write `next` in the style `matched` was written in: padded to two digits, or not. */
+const samePadding = (matched, next) => (/^0\d/.test(matched) ? String(next).padStart(2, '0') : String(next));
+
 /**
  * Delete a phase directory from disk.
  * @param {string} phaseDir - Absolute path to the phase directory to remove
@@ -200,7 +215,7 @@ function removePhaseSection(content, phaseNum) {
       fenced.fill(true, top.open, i + 1);
     } else if (!top || f[2].trim()) stack.push({ fence: f[1], open: i });
   }
-  const headRe = new RegExp(`^(#{2,4})\\s*Phase\\s+${escapeRegex(phaseNum)}\\s*:`, 'i');
+  const headRe = new RegExp(`^(#{2,4})\\s*Phase\\s+${phaseNumPattern(phaseNum)}\\s*:`, 'i');
   const start = lines.findIndex((l, i) => !fenced[i] && headRe.test(l));
   if (start === -1) return content;
   const levelEndRe = new RegExp(`^#{1,${lines[start].match(headRe)[1].length}}\\s`);
@@ -258,7 +273,7 @@ function updateRoadmapAfterRemoval(cwd, phaseNum, isDecimal, normalized) {
   } catch { return; }
 
   roadmapContent = removePhaseSection(roadmapContent, phaseNum);
-  const targetEscaped = escapeRegex(phaseNum);
+  const targetEscaped = phaseNumPattern(phaseNum);
 
   // Remove checkbox list items referencing this phase
   const checkboxPattern = new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${targetEscaped}[:\\s][^\\n]*`, 'gi');
@@ -291,14 +306,14 @@ function updateRoadmapAfterRemoval(cwd, phaseNum, isDecimal, normalized) {
 
       // Phase headings: ## Phase 18: or ### Phase 18.1: -> ## Phase 17: / ### Phase 17.1:
       roadmapContent = roadmapContent.replace(
-        new RegExp(`(#{2,4}\\s*Phase\\s+)${oldStr}((?:\\.\\d+)?\\s*:)`, 'gi'),
-        `$1${newStr}$2`
+        new RegExp(`(#{2,4}\\s*Phase\\s+)(0*)${oldStr}((?:\\.\\d+)?\\s*:)`, 'gi'),
+        (_, head, zeros, tail) => `${head}${samePadding(zeros + oldStr, newNum)}${tail}`
       );
 
       // Inline phase references: "Phase 18:", "Phase 18 " or "Phase 18.1:" -> "Phase 17..."
       roadmapContent = roadmapContent.replace(
-        new RegExp(`(Phase\\s+)${oldStr}((?:\\.\\d+)?[:\\s])`, 'g'),
-        `$1${newStr}$2`
+        new RegExp(`(Phase\\s+)(0*)${oldStr}((?:\\.\\d+)?[:\\s])`, 'g'),
+        (_, head, zeros, tail) => `${head}${samePadding(zeros + oldStr, newNum)}${tail}`
       );
 
       // Plan references in padded form: 18-01 / 18.1-01 -> 17-01 / 17.1-01, never inside a date (2026-10-01)
@@ -309,26 +324,65 @@ function updateRoadmapAfterRemoval(cwd, phaseNum, isDecimal, normalized) {
 
       // Progress table row numbers: | 18. or | 18.1. -> | 17. / | 17.1.
       roadmapContent = roadmapContent.replace(
-        new RegExp(`(\\|\\s*)${oldStr}((?:\\.\\d+)?)\\.\\s`, 'g'),
-        `$1${newStr}$2. `
+        new RegExp(`(\\|\\s*)(0*)${oldStr}((?:\\.\\d+)?)\\.\\s`, 'g'),
+        (_, head, zeros, dec) => `${head}${samePadding(zeros + oldStr, newNum)}${dec}. `
       );
 
       // Depends-on references: "Depends on:** Phase 18" -> "Phase 17"
       roadmapContent = roadmapContent.replace(
-        new RegExp(`(Depends on:\\*\\*\\s*Phase\\s+)${oldStr}\\b`, 'gi'),
-        `$1${newStr}`
+        new RegExp(`(Depends on:\\*\\*\\s*Phase\\s+)(0*)${oldStr}\\b`, 'gi'),
+        (_, head, zeros) => `${head}${samePadding(zeros + oldStr, newNum)}`
       );
     }
+  } else {
+    // Decimal removal: the siblings above it move down one (06.3 -> 06.2), as their
+    // directories already did. Upward, so a renamed reference is never renamed twice.
+    const [baseStr, removedStr] = normalized.split('.');
+    const base = escapeRegex(String(parseInt(baseStr, 10)));
+    for (let dec = parseInt(removedStr, 10) + 1; dec <= 99; dec++) {
+      const was = `(0*${base})\\.${dec}`;
+      roadmapContent = roadmapContent
+        .replace(new RegExp(`(Phase\\s+)${was}([:\\s])`, 'gi'), (_, head, int, tail) => `${head}${int}.${dec - 1}${tail}`)
+        .replace(new RegExp(`(\\|\\s*)${was}\\.\\s`, 'g'), (_, head, int) => `${head}${int}.${dec - 1}. `)
+        .replace(new RegExp(`(?<![\\d.-])${was}-(\\d{2})(?!\\d)`, 'g'), (_, int, plan) => `${int}.${dec - 1}-${plan}`);
+    }
   }
 
   try { fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8'); } catch { /* best-effort */ }
 }
 
+/**
+ * The decimal phases inserted after an integer phase, from its directories and its
+ * roadmap headings (a phase can be in the roadmap before it has a directory).
+ * @param {string} phasesDir - the phases directory
+ * @param {string} roadmapPath - roadmap.md
+ * @param {number} baseInt - the integer phase
+ * @returns {{num: string, dir: string|null}[]} in numeric order, e.g. [{num: '3.1', dir: '03.1-fix'}]
+ */
+function findDecimalPhases(phasesDir, roadmapPath, baseInt) {
+  const found = new Map();
+  const dirRe = new RegExp(`^0*${baseInt}\\.(\\d+)(?:-|$)`);
+  try {
+    for (const entry of fs.readdirSync(phasesDir, { withFileTypes: true })) {
+      const m = entry.isDirectory() && entry.name.match(dirRe);
+      if (m) found.set(Number(m[1]), entry.name);
+    }
+  } catch { /* no phases directory: the roadmap alone decides */ }
+  let text = '';
+  try { text = fs.readFileSync(roadmapPath, 'utf8'); } catch { /* unreadable: directories alone */ }
+  for (const m of text.matchAll(new RegExp(`^#{2,4}\\s*Phase\\s+0*${baseInt}\\.(\\d+)\\s*:`, 'gim'))) {
+    if (!found.has(Number(m[1]))) found.set(Number(m[1]), null);
+  }
+  return [...found.entries()].sort((a, b) => a[0] - b[0]).map(([dec, dir]) => ({ num: `${baseInt}.${dec}`, dir }));
+}
+
 /**
  * Remove a phase directory, renumber subsequent phases, and update ROADMAP/STATE.
+ * An integer phase that still has decimal phases is refused unless `withDecimals`.
  * @param {string} cwd - Working directory path
  * @param {string} targetPhase - Phase number to remove
- * @param {Object} options - Options (force: skip executed-work check)
+ * @param {Object} options - Options (force: skip executed-work check; withDecimals: remove
+ *   the integer phase's decimal phases with it)
  * @param {boolean} raw - If true, output raw value instead of JSON
  * @returns {void}
  */
@@ -393,6 +447,21 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     }
   }
 
+  // An integer phase's decimal phases (3.1, 3.2 …) were inserted after it. Removing the
+  // integer alone orphaned them: they stayed on disk and in the roadmap and, once the
+  // phases above were renumbered, read as decimals of a different phase, listed before
+  // their new base. So they go with it only when asked; otherwise refuse, naming them.
+  const decimals = isDecimal ? [] : findDecimalPhases(phasesDir, roadmapPath, parseInt(normalized, 10));
+  if (decimals.length && !options.withDecimals) {
+    error(`Phase ${targetPhase} has decimal phases ${decimals.map((d) => d.num).join(', ')} inserted after it. Remove them first, or pass --with-decimals to remove them with it.`);
+  }
+  if (!force) {
+    for (const d of decimals) {
+      const executed = d.dir ? fs.readdirSync(path.join(phasesDir, d.dir)).filter(isSummaryFile).length : 0;
+      if (executed) error(`Phase ${d.num} has ${executed} executed plan(s). Use --force to remove anyway.`);
+    }
+  }
+
   // Check for executed work (summary.md files)
   if (targetDir && !force) {
     const targetPath = path.join(phasesDir, targetDir);
@@ -403,6 +472,16 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     }
   }
 
+  // --with-decimals: every check has passed, so remove the decimals first, highest first,
+  // which leaves no sibling above any of them to renumber.
+  const removedDecimals = [];
+  for (const d of decimals.slice().reverse()) {
+    if (d.dir) removePhaseFromDisk(path.join(phasesDir, d.dir));
+    updateRoadmapAfterRemoval(cwd, d.num, true, normalizePhaseName(d.num));
+    updateStateAfterPhaseRemoval(cwd);
+    removedDecimals.unshift(d.num);
+  }
+
   // Delete target directory
   let removeWarning = null;
   if (targetDir) {
@@ -449,6 +528,7 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     roadmap_updated: true,
     state_updated: stateUpdated,
   };
+  if (removedDecimals.length) result.removed_decimals = removedDecimals;
   if (renameError) result.rename_warning = renameError;
   if (removeWarning) result.remove_warning = removeWarning;
 

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

@@ -430,6 +430,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 +605,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) {

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

@@ -0,0 +1,161 @@
+'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 ─────────────────────────────────────────────────────────────────────
+
+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 };

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 }),
   };
 }
 

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

@@ -0,0 +1,121 @@
+'use strict';
+/**
+ * Research claims with provenance and freshness (program P3).
+ *
+ * A research file lists the claims a plan will rest on in a `## Claims` table:
+ *
+ *   | Claim | Type | Source | Checked |
+ *   | jose 6 supports EdDSA | version | https://github.com/panva/jose/releases | 2026-10-12 |
+ *
+ * `research lint <phase|path>` reads it. A claim with no source, or with no date (or
+ * a date that is not YYYY-MM-DD, or is in the future), is an error: nobody can tell
+ * where it came from or when it was true. A claim older than the freshness window for
+ * its type is `stale`, not an error: what a version or a price was two months ago
+ * says little about today, while a practice lasts for years. The plan-checker weighs
+ * stale claims against what the plans rest on.
+ */
+const fs = require('fs');
+const path = require('path');
+const { output, error, toLf, toPosix, findPhaseInternal } = require('./core.cjs');
+const { sectionBody } = require('./verify-scope.cjs');
+
+// Days a claim of each type stays fresh. Versions, prices and security advisories
+// move monthly; an API surface quarterly; an engineering practice yearly.
+const FRESHNESS_DAYS = Object.freeze({ version: 30, pricing: 30, security: 30, api: 90, general: 180, practice: 365 });
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+// A template placeholder (`[Official docs URL]`, `<url>`) or a stand-in is no source.
+const PLACEHOLDER_RE = /^(\[.*\]|<.*>|-+|n\/?a|none|tbd|todo|\?+|unknown)$/i;
+
+function utcDay(s) {
+  if (!DATE_RE.test(s)) return null;
+  const t = Date.parse(s + 'T00:00:00Z');
+  return Number.isNaN(t) ? null : t;
+}
+
+/** The research file a phase number or a path names, or `{error, reason}`. */
+function resolveResearch(cwd, target) {
+  const asPath = path.resolve(cwd, String(target));
+  if (/\.md$/i.test(String(target))) {
+    if (!fs.existsSync(asPath)) return { error: 'file_not_found', reason: `no file at ${target}` };
+    return { abs: asPath };
+  }
+  const info = findPhaseInternal(cwd, target);
+  if (!info || !info.found) return { error: 'phase_not_found', reason: `no phase directory for phase ${target}` };
+  const dir = path.join(cwd, info.directory);
+  let files = [];
+  try { files = fs.readdirSync(dir); } catch { /* read as empty */ }
+  const file = files.filter((f) => /-research\.md$/i.test(f) || /^research\.md$/i.test(f)).sort()[0];
+  if (!file) return { error: 'no_research', reason: `phase ${target} has no research file` };
+  return { abs: path.join(dir, file) };
+}
+
+/** Table rows of the `## Claims` section as arrays of cells, header and rule dropped. */
+function claimRows(body) {
+  const rows = body.split('\n').map((l) => l.trim()).filter((l) => l.startsWith('|'))
+    .map((l) => l.replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim()));
+  if (!rows.length) return { header: null, rows: [] };
+  const header = rows[0].map((c) => c.toLowerCase());
+  return { header, rows: rows.slice(1).filter((r) => !r.every((c) => /^:?-+:?$/.test(c) || c === '')) };
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} target  a phase number, or a path to a research markdown file
+ * @param {{now?: string}} [opts]  `now` (YYYY-MM-DD) fixes "today" for a reproducible lint
+ */
+function lintResearch(cwd, target, opts = {}) {
+  const at = resolveResearch(cwd, target);
+  if (at.error) return at;
+  const rel = path.relative(path.resolve(cwd), at.abs);
+  const file = rel && !rel.startsWith('..') ? toPosix(rel) : toPosix(at.abs);
+  const now = opts.now ? utcDay(opts.now) : utcDay(new Date().toISOString().slice(0, 10));
+  if (now == null) return { error: 'invalid_now', reason: '--now must be YYYY-MM-DD' };
+
+  const text = toLf(fs.readFileSync(at.abs, 'utf-8'));
+  const base = { file, ok: true, claims: 0, errors: [], warnings: [], stale: [], windows: FRESHNESS_DAYS };
+  const body = sectionBody(text, 'Claims');
+  if (body == null) {
+    return { ...base, ok: false, errors: [{ code: 'claims_missing', detail: 'no `## Claims` table (claim · type · source · checked)' }] };
+  }
+  const { header, rows } = claimRows(body);
+  const col = (name, fallback) => {
+    const i = header ? header.findIndex((h) => h.startsWith(name)) : -1;
+    return i === -1 ? fallback : i;
+  };
+  const C = { claim: col('claim', 0), type: col('type', 1), source: col('source', 2), checked: col('checked', 3) };
+  const errors = [];
+  const warnings = [];
+  const stale = [];
+  rows.forEach((r, i) => {
+    const row = i + 1;
+    const claim = r[C.claim] || '';
+    const rawType = (r[C.type] || '').toLowerCase();
+    const source = r[C.source] || '';
+    const checked = r[C.checked] || '';
+    let type = rawType;
+    if (!Object.prototype.hasOwnProperty.call(FRESHNESS_DAYS, rawType)) {
+      warnings.push({ code: 'claim_unknown_type', row, claim, detail: `type "${rawType}" is not one of ${Object.keys(FRESHNESS_DAYS).join(', ')}; read as general` });
+      type = 'general';
+    }
+    if (!source || PLACEHOLDER_RE.test(source)) errors.push({ code: 'claim_no_source', row, claim, detail: 'no source' });
+    const day = utcDay(checked);
+    if (day == null) {
+      errors.push({ code: 'claim_no_date', row, claim, detail: checked ? `"${checked}" is not a YYYY-MM-DD date` : 'no checked date' });
+      return;
+    }
+    if (day > now) { errors.push({ code: 'claim_future_date', row, claim, detail: `checked ${checked}, after today` }); return; }
+    const age = Math.round((now - day) / DAY_MS);
+    if (age > FRESHNESS_DAYS[type]) stale.push({ row, claim, type, checked, age_days: age, window_days: FRESHNESS_DAYS[type] });
+  });
+  return { ...base, ok: errors.length === 0, claims: rows.length, errors, warnings, stale };
+}
+
+function cmdResearchLint(cwd, target, opts, raw) {
+  if (!target) error('Usage: research lint <phase|path> [--now YYYY-MM-DD]');
+  const r = lintResearch(cwd, target, opts);
+  if (r.error) { output(r, raw); return; }
+  output(r, raw, r.ok ? 'valid' : 'invalid', r.ok ? 0 : 1);
+}
+
+module.exports = { FRESHNESS_DAYS, lintResearch, cmdResearchLint };

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

@@ -773,5 +773,6 @@ module.exports = {
   roadmapRequirementIds,
   phaseRequirementIds,
   phaseDependencies,
+  requirementLines,
   ROADMAP_SLICE_SUFFIX,
 };