pan-wizard 3.36.0 → 3.37.0

package/pan-wizard-core/bin/lib/next-action.cjs

@@ -0,0 +1,112 @@
+'use strict';
+/**
+ * One next-action router (program L7): `pan-tools next-action`.
+ *
+ * progress, resume and transition each kept their own routing table over the same
+ * facts. They now ask this verb, which reads the disk (roadmap.md and the phase
+ * directories) into the snapshot the MCP orchestrator's state machine
+ * (mcp/orchestrator.cjs `nextAction`) keys on, and maps its decision to the command
+ * that carries it out.
+ *
+ * Run facts on disk: a phase is `verified` when it has a verification file, and
+ * finished (`merged` in the state machine's words) when its roadmap checkbox is ticked,
+ * which `phase complete` does. Two interactive routes come before the machine: diagnosed
+ * UAT gaps are planned first, and a project between milestones (roadmap but no
+ * requirements.md) starts the next one.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output } = require('./core.cjs');
+const { planningPath } = require('./utils.cjs');
+const { enumerateRoadmapPhases, enrichPhaseWithDiskStatus } = require('./roadmap.cjs');
+const { nextAction } = require('../../mcp/orchestrator.cjs');
+
+function escapeRegex(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function phaseDir(cwd, number) {
+  const root = path.join(planningPath(cwd), 'phases');
+  const num = String(number);
+  const padded = num.includes('.') ? num : num.padStart(2, '0');
+  try {
+    const d = fs.readdirSync(root, { withFileTypes: true })
+      .find((e) => e.isDirectory() && (e.name === padded || e.name.startsWith(`${padded}-`) || e.name.startsWith(`${num}-`)));
+    return d ? path.join(root, d.name) : null;
+  } catch { return null; }
+}
+
+function listDir(dir) {
+  try { return fs.readdirSync(dir); } catch { return []; }
+}
+
+/**
+ * The state machine's snapshot, read from disk.
+ * @returns {{phases: Array<{number, status, verified, merged, uat_gaps}>, roadmap: boolean, requirements: boolean}}
+ */
+function diskSnapshot(cwd) {
+  const planning = planningPath(cwd);
+  let content = null;
+  try { content = fs.readFileSync(path.join(planning, 'roadmap.md'), 'utf8').replace(/\r\n/g, '\n'); } catch {}
+  const requirements = fs.existsSync(path.join(planning, 'requirements.md'));
+  if (content === null) return { phases: [], roadmap: false, requirements };
+  const phases = enumerateRoadmapPhases(content).map((raw) => {
+    const p = enrichPhaseWithDiskStatus(cwd, raw);
+    const dir = phaseDir(cwd, p.number);
+    const files = dir ? listDir(dir) : [];
+    const ticked = new RegExp(`-\\s*\\[x\\]\\s*.*Phase\\s+${escapeRegex(p.number)}\\b`, 'i').test(content);
+    const uatGaps = files.filter((f) => /uat\.md$/i.test(f)).some((f) => {
+      try { return /^status:\s*diagnosed\s*$/m.test(fs.readFileSync(path.join(dir, f), 'utf8')); } catch { return false; }
+    });
+    return {
+      number: p.number,
+      status: p.disk_status === 'no_directory' ? 'empty' : p.disk_status,
+      verified: files.some((f) => f === 'verification.md' || f.endsWith('-verification.md')),
+      merged: ticked,
+      uat_gaps: uatGaps,
+    };
+  });
+  return { phases, roadmap: true, requirements };
+}
+
+const COMMANDS = {
+  plan: (n) => `/pan:plan-phase ${n}`,
+  execute: (n) => `/pan:exec-phase ${n}`,
+  verify: (n) => `/pan:verify-phase ${n}`,
+  complete_phase: (n) => `pan-tools phase complete ${n}`,
+  plan_gaps: (n) => `/pan:plan-phase ${n} --gaps`,
+  audit_milestone: () => '/pan:milestone-audit',
+  new_milestone: () => '/pan:milestone-new',
+  new_project: () => '/pan:new-project',
+};
+
+/**
+ * Decide the next step for the project at `cwd`.
+ * @returns {{action: string, phase: string|null, reason: string, command: string|null, done: boolean}}
+ */
+function routeNextAction(cwd) {
+  const snap = diskSnapshot(cwd);
+  const result = (action, phase, reason, done = false) => ({
+    action, phase: phase == null ? null : String(phase), reason,
+    command: COMMANDS[action] ? COMMANDS[action](phase) : null, done,
+  });
+  if (!snap.roadmap) return result('new_project', null, 'no_roadmap');
+  if (!snap.requirements) return result('new_milestone', null, 'between_milestones');
+
+  const open = snap.phases.find((p) => !(p.verified && p.merged));
+  if (open && open.uat_gaps) return result('plan_gaps', open.number, 'uat_gaps_diagnosed');
+
+  const d = nextAction({ phases: snap.phases });
+  if (d.action === 'request_merge') return result('complete_phase', d.args.phase, d.reason);
+  if (d.action === 'stop' && d.reason === 'all_complete') return result('audit_milestone', null, 'all_phases_complete');
+  if (d.action === 'stop') return result('stop', null, d.reason, d.done);
+  return result(d.action, d.args && d.args.phase, d.reason);
+}
+
+function cmdNextAction(cwd, raw) {
+  const r = routeNextAction(cwd);
+  output(r, raw, r.command || r.action);
+}
+
+module.exports = { diskSnapshot, routeNextAction, cmdNextAction };

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

@@ -2,7 +2,7 @@
 // optimize.cjs — Circular optimization loop: trace → learn → apply → repeat.
 //
 // Every agent spawn is logged to a trace session. After a build, /pan:learn
-// invokes pan-optimizer to analyze the trace. /pan:optimize apply writes memory
+// invokes pan-optimizer to analyze the trace. /pan:learn --optimize apply writes memory
 // entries, config notes, and prompt suggestions back into the project, making
 // the next run smarter.
 
@@ -1044,7 +1044,7 @@ function revertApply(cwd, which) {
 const LESSON_TARGET = "the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section)";
 
 // Derive suggestion notes from a raw JSON analysis when no optimizer agent
-// report is available (fallback for /pan:optimize apply on a JSON file).
+// report is available (fallback for /pan:learn --optimize apply on a JSON file).
 function deriveActionsFromAnalysis(analysis) {
   const actions = [];
   const { memory_miss_patterns, gap_patterns, summary } = analysis;

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 };
 }
 
 /**
@@ -741,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'),
@@ -759,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 };
@@ -1027,6 +1069,7 @@ function classifyPlanTier(frontmatter, config) {
 }
 
 module.exports = {
+  partitionWave,
   cmdPhasesList,
   cmdPhaseNextDecimal,
   cmdFindPhase,
@@ -1044,6 +1087,7 @@ module.exports = {
   renumberIntegerPhases,
   updateRoadmapAfterRemoval,
   markPhaseCompleteInRoadmap,
+  markRequirementsCompleteForPhase,
   updateStateAfterPhaseComplete,
   classifyPlanTier,
 };

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

@@ -144,6 +144,152 @@ function checkDecisions(cwd, phase) {
 
 // ─── 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);
@@ -158,4 +304,7 @@ function cmdVerifyDecisions(cwd, phase, raw) {
   output(r, raw, r.ok ? 'valid' : 'invalid', r.ok ? 0 : 1);
 }
 
-module.exports = { REVIEW_FOCUS_MAX, checkReviewFocus, checkDecisions, recordedDecisions, cmdVerifyReviewFocus, cmdVerifyDecisions };
+module.exports = {
+  REVIEW_FOCUS_MAX, checkReviewFocus, checkDecisions, recordedDecisions, cmdVerifyReviewFocus, cmdVerifyDecisions,
+  parseGateCommand, checkGates, cmdVerifyGates,
+};

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

@@ -371,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
@@ -408,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,
   };
 }
@@ -420,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; }
@@ -441,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 };