pan-wizard 3.34.0 → 3.36.0

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) {
@@ -823,6 +851,26 @@ function cmdPhaseComplete(cwd, phaseNum, raw, opts) {
     error(`Phase ${phaseNum} not found`);
   }
 
+  // The phase gate (V1). In `enforce` mode a refusal stops here unless --force
+  // --reason, which records a decision; in `warn` mode the reasons travel with the
+  // result. A --force without a reason is refused in either mode.
+  const { phaseGate, recordGateOverride } = require('./phase-gate.cjs');
+  const force = !!(opts && opts.force);
+  const forceReason = opts && typeof opts.reason === 'string' ? opts.reason.trim() : '';
+  if (force && !forceReason) {
+    output({ error: 'reason_required', reason: 'phase complete --force needs --reason "<why the gate is being overridden>"' }, raw);
+    return;
+  }
+  const gate = phaseGate(cwd, phaseNum);
+  let gateOverride = null;
+  if (!gate.error && !gate.ok) {
+    if (gate.mode === 'enforce' && !force) {
+      output({ error: 'phase_gate_refused', reason: gate.reasons.map((r) => `${r.code}: ${r.detail}`).join(' | '), gate }, raw);
+      return;
+    }
+    if (force) gateOverride = recordGateOverride(cwd, gate, forceReason);
+  }
+
   const planCount = phaseInfo.plans.length;
   const summaryCount = phaseInfo.summaries.length;
 
@@ -886,6 +934,8 @@ function cmdPhaseComplete(cwd, phaseNum, raw, opts) {
     date: today,
     roadmap_updated: fileAccessible(roadmapPath),
     state_updated: fileAccessible(statePath),
+    gate: gate.error ? { error: gate.error } : { ok: gate.ok, mode: gate.mode, reasons: gate.reasons, not_checked: gate.not_checked },
+    ...(gateOverride ? { gate_override: gateOverride } : {}),
   };
   if (roadmapResult && roadmapResult.requirements_warning) {
     result.requirements_warning = roadmapResult.requirements_warning;
@@ -982,6 +1032,8 @@ module.exports = {
   cmdFindPhase,
   cmdPhasePlanIndex,
   blockedPlans,
+  buildPlanIndex,
+  dependencyNames,
   cmdPhaseAdd,
   cmdPhaseInsert,
   cmdPhaseRemove,

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 }),
   };
 }
 
@@ -161,7 +164,8 @@ function buildPhasePreview(cwd, phaseNum) {
  * Produce a dependency graph + mermaid source + parallel-batch recommendation.
  *
  * Dependency detection:
- *  - plan frontmatter `depends_on: [phase:NN, phase:MM]` (explicit)
+ *  - the roadmap's `**Depends on:** Phase N` line (explicit)
+ *  - plan frontmatter `depends_on: [phase:NN, phase:MM]` (explicit; bare plan ids are not phases)
  *  - mentions of prior phases in plan text (heuristic, flagged as "hidden")
  *
  * @param {string} cwd - Project root
@@ -195,6 +199,13 @@ function buildPhaseDependencyGraph(cwd) {
     }
   }
 
+  // Graph keys are the roadmap checklist's numbers; a dependency written "01" or
+  // "Phase 1" resolves to the key whose unpadded form matches.
+  const unpad = (n) => String(n).trim().replace(/^0+(?=\d)/, '');
+  const keyByUnpadded = new Map(phaseList.map(p => [unpad(p.num), p.num]));
+  const keyOf = (n) => keyByUnpadded.get(unpad(n)) || unpad(n);
+  const { phaseDependencies } = require('./roadmap.cjs');
+
   for (const p of phaseList) {
     graph[p.num] = {
       num: p.num,
@@ -204,6 +215,15 @@ function buildPhaseDependencyGraph(cwd) {
       hidden_deps: [],
     };
 
+    const addExplicit = (d) => {
+      const key = keyOf(d);
+      if (key !== keyOf(p.num) && !graph[p.num].explicit_deps.includes(key)) graph[p.num].explicit_deps.push(key);
+    };
+
+    // Explicit via the roadmap: the phase's `**Depends on:** Phase N` line.
+    const roadmapPhase = getRoadmapPhaseInternal(cwd, p.num);
+    for (const d of phaseDependencies(roadmapPhase && roadmapPhase.section)) addExplicit(d);
+
     // Read plan files for depends_on frontmatter + prior-phase mentions.
     const dir = phaseDirs[p.num];
     if (!dir) continue;
@@ -212,35 +232,18 @@ function buildPhaseDependencyGraph(cwd) {
     try { files = fs.readdirSync(fullDir).filter(isPlanFile); } catch { continue; }
 
     // LF, so the frontmatter match below also finds a CRLF plan's depends_on.
-    const phaseText = toLf(files.map(f => safeReadFile(path.join(fullDir, f)) || '').join('\n'));
-
-    // Explicit via frontmatter. Parse depends_on as freeform string (either
-    // inline `[phase:1, phase:2]`, or block-list). Extract all digit runs.
-    const fmMatch = phaseText.match(/^---\n([\s\S]*?)\n---/);
-    if (fmMatch) {
-      const depsLine = fmMatch[1].match(/^depends_on:\s*(.+)$/m);
-      if (depsLine) {
-        const digitRuns = depsLine[1].match(/\d+(?:\.\d+)?/g) || [];
-        for (const d of digitRuns) {
-          if (d !== p.num && !graph[p.num].explicit_deps.includes(d)) {
-            graph[p.num].explicit_deps.push(d);
-          }
-        }
-      }
-      // Also support block-list form:
-      //   depends_on:
-      //     - phase:1
-      //     - phase:2
-      const blockMatch = fmMatch[1].match(/^depends_on:\s*\n((?:\s*-\s*.+\n?)*)/m);
-      if (blockMatch && !depsLine) {
-        const items = blockMatch[1].match(/^\s*-\s*(.+)$/gm) || [];
-        for (const item of items) {
-          const d = item.match(/\d+(?:\.\d+)?/);
-          if (d && d[0] !== p.num && !graph[p.num].explicit_deps.includes(d[0])) {
-            graph[p.num].explicit_deps.push(d[0]);
-          }
-        }
-      }
+    const planTexts = files.map(f => toLf(safeReadFile(path.join(fullDir, f)) || ''));
+    const phaseText = planTexts.join('\n');
+
+    // Explicit via each plan's frontmatter. A plan's `depends_on` names plan ids
+    // inside its own phase (`["01"]`), so only `phase:N` entries are phase
+    // dependencies, inline (`[phase:1, phase:2]`) or as a block list.
+    for (const text of planTexts) {
+      const fmMatch = text.match(/^---\n([\s\S]*?)\n---/);
+      if (!fmMatch) continue;
+      const depsBlock = fmMatch[1].match(/^depends_on:[^\n]*(?:\n[ \t]*-[^\n]*)*/m);
+      if (!depsBlock) continue;
+      for (const m of depsBlock[0].matchAll(/\bphase[:\s]*(\d+(?:\.\d+)?)/gi)) addExplicit(m[1]);
     }
 
     // Hidden via mentions: "phase N", "from phase N", "as in phase N".
@@ -248,7 +251,8 @@ function buildPhaseDependencyGraph(cwd) {
     let mm;
     const mentions = new Set();
     while ((mm = mentionRe.exec(phaseText)) !== null) {
-      if (mm[1] !== p.num) mentions.add(mm[1]);
+      const k = keyOf(mm[1]);
+      if (k !== keyOf(p.num)) mentions.add(k);
     }
     graph[p.num].hidden_deps = [...mentions].filter(d => !graph[p.num].explicit_deps.includes(d));
   }

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