pan-wizard 3.13.1 → 3.14.0

package/README.md

@@ -576,7 +576,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 
 | Command | What it does |
 |---------|--------------|
-| `/pan:progress` | Where am I? What's next? (supports `health` subformat) |
+| `/pan:progress` | Where am I? What's next? |
 | `/pan:hud` (alias `/pan:dashboard`) | Render a self-contained HTML dashboard of project + bot-army state to `.planning/hud.html` (`--open`, `--out`, `--stdout`) |
 | `/pan:help` | Show all commands and usage guide |
 | `/pan:update` | Update PAN with changelog preview |
@@ -621,7 +621,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:todo-check` | List pending todos |
 | `/pan:debug [desc]` | Systematic debugging with persistent state |
 | `/pan:quick [--full]` | Execute ad-hoc task with PAN guarantees (`--full` adds plan-checking and verification) |
-| `/pan:health [--repair] [--standards] [--full] [--drift] [--links]` | Validate `.planning/` directory integrity. `--repair` auto-fixes; `--standards` checks compliance; `--full` runs tests + build; `--drift` runs convention drift; `--links` attaches doc-code link-graph summary |
+| `/pan:health [--repair]` | Validate `.planning/` directory integrity; `--repair` auto-fixes detected issues |
 | `/pan:hygiene [--apply] [--trace-age-days N]` | Scan for PAN version drift and stale project artifacts (legacy filenames, .tmp orphans, memory bloat, poisoned cost ledgers, trace debris, fragment planning dirs); `--apply` executes the safe fixes — ledgers are quarantined by rename, never deleted |
 | `/pan:links [--strict]` | Validate the doc-code link graph: inline `[[<id>]]` refs, `// @pan:` source anchors, `require-code-mention` contracts (ADR-0027, v3.8.0+) |
 | `/pan:phase-tests [N]` | Generate tests for a completed phase based on UAT criteria |
@@ -719,8 +719,7 @@ These spawn additional agents during planning/execution. They improve quality bu
 | `workflow.plan_check` | `true` | Verifies plans achieve phase goals before execution |
 | `workflow.verifier` | `true` | Confirms must-haves were delivered after execution |
 | `workflow.auto_advance` | `false` | Auto-chain discuss → plan → execute without stopping |
-| `workflow.nyquist_validation` | `true` | Map test coverage during planning (Nyquist layer) |
-| `workflow.standards_health` | `true` | Include standards compliance in health reports |
+| `workflow.nyquist_validation` | `false` | Map test coverage during planning (Nyquist layer) |
 
 Use `/pan:settings` to toggle these, or override per-invocation:
 - `/pan:plan-phase --skip-research`

package/hooks/dist/pan-context-monitor.js

@@ -21,6 +21,17 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+// Per-user bridge directory inside tmpdir, created 0700 so another user on a
+// shared host can't pre-plant a symlink at a predictable session path or read
+// the bridge files. Both hooks derive the same dir from the same uid, so the
+// statusline→context-monitor IPC channel is preserved.
+function bridgeDir() {
+  const uid = (typeof process.getuid === 'function' ? process.getuid() : process.env.USERNAME || 'win');
+  const dir = path.join(os.tmpdir(), `pan-hooks-${uid}`);
+  try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* best-effort */ }
+  return dir;
+}
+
 const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
 const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
 const STALE_SECONDS = 60;      // ignore metrics older than 60s
@@ -38,15 +49,18 @@ process.stdin.on('end', () => {
       process.exit(0);
     }
 
-    const tmpDir = os.tmpdir();
+    const tmpDir = bridgeDir();
     const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
 
-    // If no metrics file, this is a subagent or fresh session -- exit silently
-    if (!fs.existsSync(metricsPath)) {
+    // Read metrics directly; absence (subagent/fresh session) or a corrupt
+    // file just means "nothing to warn about" — exit silently. No
+    // existsSync-then-read gap.
+    let metrics;
+    try {
+      metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+    } catch {
       process.exit(0);
     }
-
-    const metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
     const now = Math.floor(Date.now() / 1000);
 
     // Ignore stale metrics
@@ -67,13 +81,11 @@ process.stdin.on('end', () => {
     let warnData = { callsSinceWarn: 0, lastLevel: null };
     let firstWarn = true;
 
-    if (fs.existsSync(warnPath)) {
-      try {
-        warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
-        firstWarn = false;
-      } catch (e) {
-        // Corrupted file, reset
-      }
+    try {
+      warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+      firstWarn = false;
+    } catch {
+      // No prior warning file (or corrupted) — treat as first warning.
     }
 
     warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;

package/hooks/dist/pan-statusline.js

@@ -39,7 +39,13 @@ function buildStatuslineOutput(data, deps) {
 
     if (session && d.skipBridge !== true) {
       try {
-        const bridgePath = pathMod.join(tmpDir, `claude-ctx-${session}.json`);
+        // Write the bridge file into a per-user 0700 subdir so another user on
+        // a shared host can't symlink-attack the predictable session path.
+        // Mirrors bridgeDir() in pan-context-monitor.js (the reader).
+        const uid = (typeof process.getuid === 'function' ? process.getuid() : process.env.USERNAME || 'win');
+        const bridgeSubdir = pathMod.join(tmpDir, `pan-hooks-${uid}`);
+        try { fsMod.mkdirSync(bridgeSubdir, { recursive: true, mode: 0o700 }); } catch { /* best-effort */ }
+        const bridgePath = pathMod.join(bridgeSubdir, `claude-ctx-${session}.json`);
         fsMod.writeFileSync(bridgePath, JSON.stringify({
           session_id: session,
           remaining_percentage: remaining,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.13.1",
+  "version": "3.14.0",
   "description": "Command a bot army for your codebase: an Opus Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"
@@ -62,10 +62,10 @@
     "prepare": "node scripts/install-git-hooks.js",
     "release:check": "node scripts/release-check.js",
     "prepublishOnly": "node scripts/release-check.js",
-    "test": "node --test tests/*.test.cjs",
-    "test:scenarios": "node --test tests/scenarios/*.test.cjs",
-    "test:all": "node --test tests/*.test.cjs tests/scenarios/*.test.cjs",
-    "test:e2e": "node --test tests/scenarios/*.test.cjs",
+    "test": "node scripts/run-tests.cjs tests",
+    "test:scenarios": "node scripts/run-tests.cjs tests/scenarios",
+    "test:all": "node scripts/run-tests.cjs tests tests/scenarios",
+    "test:e2e": "node scripts/run-tests.cjs tests/scenarios",
     "test:vscode": "npx playwright test --config tests/e2e/playwright.config.mjs",
     "test:watch": "node --test --watch tests/*.test.cjs",
     "build:plugin": "node scripts/build-plugin.js"

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

@@ -154,10 +154,23 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
   // After the loop, `current` points to the parent object and the
   // final segment is used as the property key for assignment.
   const keys = keyPath.split('.');
+
+  // Reject prototype-polluting segments up front so a key path like
+  // "__proto__.x" or "constructor.prototype.y" can never walk into or mutate
+  // Object.prototype. Inline literal guard (no helper) so the check is
+  // unambiguous — every remaining assignment is on a vetted key.
+  for (const key of keys) {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+      error(`Invalid config key "${keyPath}": __proto__/constructor/prototype are not allowed`);
+      return;
+    }
+  }
+
+  // Every segment is now vetted; walk the path building intermediate objects.
   let current = config;
   for (let i = 0; i < keys.length - 1; i++) {
     const key = keys[i];
-    if (current[key] === undefined || typeof current[key] !== 'object') {
+    if (!Object.prototype.hasOwnProperty.call(current, key) || typeof current[key] !== 'object' || current[key] === null) {
       current[key] = {};
     }
     current = current[key];

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

@@ -159,9 +159,13 @@ function output(result, raw, rawValue) {
     // Large payloads exceed Claude Code's Bash tool buffer (~50KB).
     // Write to tmpfile and output the path prefixed with @file: so callers can detect it.
     if (json.length > MAX_JSON_SIZE) {
-      const tmpPath = path.join(os.tmpdir(), `pan-${Date.now()}.json`);
+      // Create a fresh private directory (mkdtemp → unique, unguessable, owned
+      // by us) and write inside it, so a pre-planted file or symlink on a
+      // shared tmpdir can't be followed or overwritten.
       try {
-        fs.writeFileSync(tmpPath, json, 'utf-8');
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-'));
+        const tmpPath = path.join(tmpDir, 'out.json');
+        fs.writeFileSync(tmpPath, json, { encoding: 'utf-8', flag: 'wx' });
         process.stdout.write('@file:' + tmpPath);
       } catch {
         // Tmpfile write failed (disk full, permissions) — truncate and write to stdout

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

@@ -147,7 +147,13 @@ function cmdDocLintSchemaCheck(cwd, schemaPath, opts = {}) {
 const COUNT_PATTERNS = [
   // "52 commands", "21 agents", "30 modules", "2667 tests", etc.
   // Word boundaries + allowed plurals; case-insensitive matching.
-  { re: /(?<!\.)\b(\d+)\s+(commands?|agents?|modules?|workflows?|templates?|references?|specs?|adrs?|test\s+files?|test\s+suites?)\b/gi,
+  // Bare "N tests" / "N hooks" added (previously only "(N tests)" and
+  // "test files/suites" matched, so "3115 tests" slipped). Adjective-separated
+  // ("slash commands") and hyphen-compound ("sub-agents") variants are left
+  // uncaught on purpose — broadening to them also matched years ("2026
+  // multi-agent") and narrative, breaking the docs-clean invariant; the
+  // CLAUDE.md-table self-audit test is the stronger backstop for the counts.
+  { re: /(?<!\.)\b(\d+)\s+(commands?|agents?|modules?|workflows?|templates?|references?|specs?|adrs?|hooks?|test\s+files?|test\s+suites?|tests?)\b/gi,
     label: 'noun-phrase count' },
   // "27th module", "21st agent", "52nd command" — drift-prone ordinals
   { re: /(?<!\.)\b(\d+)(th|st|nd|rd)\s+(module|reference|agent|command|template|hook|workflow|spec|adr)\b/gi,
@@ -277,10 +283,89 @@ function cmdDocLintCounts(cwd, dir, opts = {}) {
   process.exit(violations.length > 0 ? 1 : 0);
 }
 
+// ─── Aspirational-flag checker (ADR-0036 review — closes the "documented CLI
+// flag that doesn't exist in the parser" gap). Heuristic: a `--flag` that
+// appears in a doc line referencing the PAN CLI but never appears as a literal
+// anywhere in the source is very likely fake or stale. Scoped to PAN-CLI lines
+// to avoid flagging unrelated tool flags (git/npm/node). ─────────────────────
+function collectSourceFlags(cwd, roots) {
+  const flags = new Set();
+  const walk = (dir) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const fp = path.join(dir, e.name);
+      if (e.isDirectory()) { if (e.name !== 'node_modules') walk(fp); }
+      else if (/\.(cjs|js|mjs)$/.test(e.name)) {
+        let c = ''; try { c = fs.readFileSync(fp, 'utf-8'); } catch { continue; }
+        for (const m of c.matchAll(/--[a-z][a-z0-9-]+/g)) flags.add(m[0]);
+      }
+    }
+  };
+  for (const r of roots) walk(path.join(cwd, r));
+  return flags;
+}
+
+function scanDocFlags(cwd, opts = {}) {
+  const sourceFlags = collectSourceFlags(cwd, opts.sourceRoots || ['pan-wizard-core/bin', 'bin']);
+  const docDirs = opts.docDirs || ['docs'];
+  const collected = [];
+  for (const d of docDirs) {
+    const abs = path.join(cwd, d);
+    if (!fs.existsSync(abs)) continue;
+    for (const f of walkMarkdownFiles(abs)) {
+      if (f.readError) continue;
+      collected.push({ rel: path.join(d, f.relativePath).replace(/\\/g, '/'), content: f.content });
+    }
+  }
+  for (const rel of (opts.files || [])) {
+    try { collected.push({ rel: rel.replace(/\\/g, '/'), content: fs.readFileSync(path.join(cwd, rel), 'utf-8') }); } catch { /* skip */ }
+  }
+  // Scope to `pan-tools <cmd>` lines ONLY — that is the surface whose flags are
+  // parsed in bin/ source. Slash-command flags (`/pan:exec-phase --gaps-only`)
+  // are a different surface: they are parsed by the command/workflow markdown
+  // prompts, so they legitimately never appear in bin/ source and must not be
+  // flagged here.
+  const CLI_CTX = /\bpan-tools\b/;
+  const violations = [];
+  for (const file of collected) {
+    // Skip frozen/aspirational docs (feature specs, ADRs, experiments, archive)
+    // — by design they describe proposed/future flags, same allowlist as counts.
+    if (isCountAllowed(file.rel)) continue;
+    const lines = file.content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      if (!CLI_CTX.test(lines[i])) continue;
+      // Lookbehind excludes mid-token double-dashes — notably markdown anchors
+      // like `#army--project-dashboard` — so only real ` --flag` tokens match.
+      for (const m of lines[i].matchAll(/(?<![\w#-])(--[a-z][a-z0-9-]+)/g)) {
+        if (!sourceFlags.has(m[1])) violations.push({ file: file.rel, line: i + 1, flag: m[1] });
+      }
+    }
+  }
+  return { source_flags: sourceFlags.size, doc_files: collected.length, violation_count: violations.length, violations };
+}
+
+function cmdDocLintFlags(cwd, opts = {}, raw) {
+  const r = scanDocFlags(cwd, opts);
+  if (raw) {
+    if (r.violation_count === 0) {
+      process.stdout.write(`OK — ${r.doc_files} docs scanned against ${r.source_flags} source flags, no aspirational CLI flags\n`);
+    } else {
+      for (const v of r.violations) process.stdout.write(`${v.file}:${v.line} — ${v.flag} (documented for the PAN CLI but not found in source)\n`);
+      process.stdout.write(`\n${r.violation_count} aspirational flag(s)\n`);
+    }
+  } else {
+    output(r, false);
+  }
+  process.exit(r.violation_count > 0 ? 1 : 0);
+}
+
 module.exports = {
   cmdDocLint,
   cmdDocLintSchemaCheck,
   cmdDocLintCounts,
+  scanDocFlags,
+  cmdDocLintFlags,
   isCountAllowed,
   COUNT_PATTERNS,
   DEFAULT_SCHEMA_PATH,

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

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, error, safeReadFile, loadConfig, scanPendingTodos, scanSourceTodos, toPosix, isGitRepo, execGit } = require('./core.cjs');
+const { output, error, safeReadFile, loadConfig, scanPendingTodos, scanSourceTodos, toPosix, isGitRepo, execGit, escapeRegex } = require('./core.cjs');
 const {
   PLANNING_DIR, PHASES_DIR, ROADMAP_FILE, PATTERNS_FILE, EFFORT_POINTS, PRIORITY_LEVELS, EFFORT_SIZES,
   FOCUS_MODES, FOCUS_TIERS, FOCUS_DIR,
@@ -457,7 +457,7 @@ function checkDocStaleness(cwd, opts) {
 function checkOldCommandNames(content, file, stale) {
   for (const [oldName, newName] of Object.entries(COMMAND_RENAME_MAP)) {
     // Match /pan:old-name or pan:old-name (command references)
-    const pattern = new RegExp(`pan:${oldName.replace(/-/g, '\\-')}\\b`);
+    const pattern = new RegExp(`pan:${escapeRegex(oldName)}\\b`);
     if (pattern.test(content)) {
       stale.push({ file, entity: 'renamed_command', old: oldName, new: newName });
     }
@@ -717,6 +717,45 @@ function focusAutoStop(cwd, raw) {
   }, raw);
 }
 
+// Anti-fake (ADR-0036 review): the regression breaker compares tests_after vs
+// tests_before, both historically agent-supplied CLI args that focus-auto never
+// re-ran — so a fabricated "tests green" passed unchecked. When verification is
+// enabled (config.focus.verify_tests), re-run the node:test suite and use the
+// REAL pass count; otherwise keep the supplied value but mark the cycle
+// tests_verified:false so the loop's trust is visible to the HUD/audit/human.
+//
+// Invocation is a fixed execFile('node', ['--test']) — NO shell and NO
+// configurable command string, so there is no command-injection surface (same
+// safe pattern verify.cjs uses). If no node:test suite is present, fall back to
+// the supplied value rather than mis-firing the regression breaker.
+function verifyTestCount(cwd, config, fallback) {
+  const focusCfg = (config && config.focus) || {};
+  if (!focusCfg.verify_tests) return { tests_after: fallback, verified: false };
+  const { execFileSync } = require('child_process');
+  const num = (out, re) => { const m = String(out || '').match(re); return m ? Number(m[1]) : null; };
+  const interpret = (out, exitCode) => {
+    // node --test summary lines use either the TAP marker ("# tests N") or the
+    // spec reporter's info marker ("ℹ tests N"), depending on Node version /
+    // reporter — match both so the count is captured regardless.
+    const total = num(out, /[#ℹ]\s*tests\s+(\d+)/);
+    if (!total) return { tests_after: fallback, verified: false }; // no node:test suite here
+    const passed = num(out, /[#ℹ]\s*pass\s+(\d+)/);
+    return { tests_after: passed !== null ? passed : (exitCode === 0 ? fallback : 0), verified: true, exit_code: exitCode };
+  };
+  // Strip any NODE_TEST_* context so the child runs as a standalone runner with
+  // predictable spec/TAP output — otherwise, when focus-auto is itself invoked
+  // from within a `node --test` process, the child inherits the nested-test
+  // context and emits a serialized format we can't parse.
+  const env = { ...process.env };
+  for (const k of Object.keys(env)) { if (k.startsWith('NODE_TEST')) delete env[k]; }
+  try {
+    const out = execFileSync('node', ['--test'], { cwd, timeout: 120000, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', env });
+    return interpret(out, 0);
+  } catch (err) {
+    return interpret(err && err.stdout, (err && err.status) || 1);
+  }
+}
+
 function focusAutoUpdate(cwd, raw, getVal) {
   const run = readAutoRun(cwd);
   if (!run) return error('No auto-run in progress. Cannot update.');
@@ -735,6 +774,12 @@ function focusAutoUpdate(cwd, raw, getVal) {
     timestamp: new Date().toISOString(),
   };
 
+  // Anti-fake: re-run the suite when verification is enabled; else record that
+  // this count was self-reported (tests_verified:false) so the trust is visible.
+  const tv = verifyTestCount(cwd, loadConfig(cwd), cycle.tests_after);
+  cycle.tests_after = tv.tests_after;
+  cycle.tests_verified = tv.verified;
+
   if (!run.cycles) run.cycles = [];
   run.cycles.push(cycle);
 
@@ -1016,6 +1061,7 @@ module.exports = {
   writeAutoRun,
   cmdFocusAuto,
   determineStopReason,
+  verifyTestCount,
   // Opus 4.7
   determineContinuation,
   classifyStageDependencies,

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

@@ -822,13 +822,29 @@ ${body}
 
 function openInBrowser(filePath) {
   const { execFileSync } = require('child_process');
+  // Only open a path we can resolve to an existing regular file, and refuse
+  // anything carrying shell/cmd metacharacters — on Windows `start` is a cmd
+  // builtin that re-parses its command line, so a crafted --out value must not
+  // be able to reach it. The allowlist check is the taint barrier; `resolved`
+  // is what actually gets opened.
+  let resolved;
+  try {
+    resolved = path.resolve(filePath);
+    if (!fs.statSync(resolved).isFile()) return false;
+  } catch {
+    return false;
+  }
+  // Allowlist barrier: only ordinary path characters may reach the opener.
+  // Anything outside this set (shell/cmd metacharacters, quotes, newlines) is
+  // rejected outright, so a crafted --out value cannot reach Windows `start`.
+  if (!/^[A-Za-z0-9 _.:\\/()-]+$/.test(resolved)) return false;
   try {
     if (process.platform === 'win32') {
-      execFileSync('cmd', ['/c', 'start', '', filePath], { stdio: 'ignore' });
+      execFileSync('cmd', ['/c', 'start', '', resolved], { stdio: 'ignore' });
     } else if (process.platform === 'darwin') {
-      execFileSync('open', [filePath], { stdio: 'ignore' });
+      execFileSync('open', [resolved], { stdio: 'ignore' });
     } else {
-      execFileSync('xdg-open', [filePath], { stdio: 'ignore' });
+      execFileSync('xdg-open', [resolved], { stdio: 'ignore' });
     }
     return true;
   } catch {

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

@@ -14,7 +14,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, error, safeReadFile, toPosix } = require('./core.cjs');
+const { output, error, safeReadFile, toPosix, escapeRegex } = require('./core.cjs');
 const { PLANNING_DIR } = require('./constants.cjs');
 const { planningPath } = require('./utils.cjs');
 const { listMemoryAgents, readMemory } = require('./memory.cjs');
@@ -56,7 +56,7 @@ function scoreRelevance(question, content) {
   const body = content.toLowerCase();
   let score = 0;
   for (const w of words) {
-    const count = (body.match(new RegExp(`\\b${w.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}\\b`, 'g')) || []).length;
+    const count = (body.match(new RegExp(`\\b${escapeRegex(w)}\\b`, 'g')) || []).length;
     score += count;
   }
   return score;

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

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output } = require('./core.cjs');
+const { output, escapeRegex } = require('./core.cjs');
 const { PLANNING_DIR } = require('./constants.cjs');
 
 // ─── Storage layout ──────────────────────────────────────────────────────────
@@ -1052,7 +1052,7 @@ function unpromotePattern(patternId, opts) {
   // Strip the pattern's body section. Pattern body is a `## P-<id> — ...` heading
   // followed by content until the next `## ` or end-of-file.
   const headingRe = new RegExp(
-    `\\n## ${patternId.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\b[^\\n]*[\\s\\S]*?(?=\\n## |$)`,
+    `\\n## ${escapeRegex(patternId)}\\b[^\\n]*[\\s\\S]*?(?=\\n## |$)`,
     ''
   );
   const newBody = parsed.body.replace(headingRe, '');

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

@@ -47,7 +47,7 @@ function renumberDecimalPhases(phasesDir, baseInt, removedDecimal) {
     const dirs = entries.filter(entry => entry.isDirectory()).map(entry => entry.name).sort((left, right) => comparePhaseNum(left, right));
 
     // Find sibling decimals with higher numbers than the removed one
-    const decPattern = new RegExp(`^${baseInt}\\.(\\d+)-(.+)$`);
+    const decPattern = new RegExp(`^${escapeRegex(String(baseInt))}\\.(\\d+)-(.+)$`);
     const toRename = [];
     for (const dir of dirs) {
       const decMatch = dir.match(decPattern);

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

@@ -133,7 +133,7 @@ function cmdPhaseNextDecimal(cwd, basePhase, raw) {
     const baseExists = dirs.some(dir => dir.startsWith(normalized + '-') || dir === normalized);
 
     // Find existing decimal phases for this base
-    const decimalPattern = new RegExp(`^${normalized}\\.(\\d+)`);
+    const decimalPattern = new RegExp(`^${escapeRegex(normalized)}\\.(\\d+)`);
     const existingDecimals = [];
 
     for (const dir of dirs) {
@@ -444,7 +444,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
   // Normalize input then strip leading zeros for flexible matching
   const normalizedAfter = normalizePhaseName(afterPhase);
   const unpadded = normalizedAfter.replace(/^0+/, '');
-  const afterPhaseEscaped = unpadded.replace(/\./g, '\\.');
+  const afterPhaseEscaped = escapeRegex(unpadded);
   const targetPattern = new RegExp(`#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:`, 'i');
   if (!targetPattern.test(content)) {
     error(`Phase ${afterPhase} not found in roadmap.md`);
@@ -458,7 +458,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
   try {
     const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
     const dirs = entries.filter(entry => entry.isDirectory()).map(entry => entry.name);
-    const decimalPattern = new RegExp(`^${normalizedBase}\\.(\\d+)`);
+    const decimalPattern = new RegExp(`^${escapeRegex(normalizedBase)}\\.(\\d+)`);
     for (const dir of dirs) {
       const decMatch = dir.match(decimalPattern);
       if (decMatch) existingDecimals.push(parseInt(decMatch[1], 10));
@@ -484,7 +484,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
   const phaseEntry = `\n### Phase ${decimalPhase}: ${description} (INSERTED)\n\n**Goal:** [Urgent work - to be planned]\n**Requirements**: TBD\n**Depends on:** Phase ${afterPhase}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run /pan:plan-phase ${decimalPhase} to break down)\n`;
 
   // Insert after the target phase section
-  const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:[^\\n]*\\n)`, 'i');
+  const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:[^\\n]*\\n)`, 'i'); // afterPhaseEscaped already run through escapeRegex above
   const headerMatch = content.match(headerPattern);
   if (!headerMatch) {
     error(`Could not find Phase ${afterPhase} header`);

package/pan-wizard-core/bin/lib/review-deep.cjs

@@ -198,7 +198,9 @@ function writeDeepReview(cwd, phaseNum, payload, opts) {
     lines.push('|----------|--------|----------|-------------|------|');
     for (const f of payload.findings) {
       const loc = f.file ? `\`${f.file}${f.line ? `:${f.line}` : ''}\`` : '—';
-      const desc = f.description.replace(/\|/g, '\\|');
+      // Neutralize markdown-table-breaking chars: escape pipes and flatten any
+      // newlines so a finding description can't corrupt the table structure.
+      const desc = String(f.description).replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ');
       lines.push(`| ${f.severity} | ${f.source} | ${f.category} | ${desc} | ${loc} |`);
     }
     lines.push('');

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

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
-const { safeReadFile, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, toPosix, output, error } = require('./core.cjs');
+const { safeReadFile, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, toPosix, output, error, escapeRegex } = require('./core.cjs');
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { writeStateMd, readStateSafe } = require('./state.cjs');
 const {
@@ -317,32 +317,22 @@ function cmdVerifyCommits(cwd, hashes, raw) {
  * @param {boolean} raw - If true, output raw value instead of JSON
  * @returns {void}
  */
-function cmdVerifyArtifacts(cwd, planFilePath, raw) {
-  if (!planFilePath) { error('plan file path required'); }
-  const fullPath = path.isAbsolute(planFilePath) ? planFilePath : path.join(cwd, planFilePath);
-  const content = safeReadFile(fullPath);
-  if (!content) { output({ error: 'File not found', path: planFilePath }, raw); return; }
-
-  const artifacts = parseMustHavesBlock(content, 'artifacts');
-  if (artifacts.length === 0) {
-    output({ error: 'No must_haves.artifacts found in frontmatter', path: planFilePath }, raw);
-    return;
-  }
-
+/**
+ * Pure substance check of must_haves.artifacts against disk — no output/exit,
+ * so `verify reconcile` can compose it. Returns {all_passed, passed, total, artifacts}.
+ */
+function checkArtifacts(cwd, planContent) {
+  const artifacts = parseMustHavesBlock(planContent, 'artifacts');
   const results = [];
   for (const artifact of artifacts) {
     if (typeof artifact === 'string') continue; // skip simple string items
     const artPath = artifact.path;
     if (!artPath) continue;
-
-    const artFullPath = path.join(cwd, artPath);
-    const fileContent = safeReadFile(artFullPath);
+    const fileContent = safeReadFile(path.join(cwd, artPath));
     const exists = fileContent !== null;
     const check = { path: artPath, exists, issues: [], passed: false };
-
     if (exists) {
       const lineCount = fileContent.split('\n').length;
-
       if (artifact.min_lines && lineCount < artifact.min_lines) {
         check.issues.push(`Only ${lineCount} lines, need ${artifact.min_lines}`);
       }
@@ -350,8 +340,8 @@ function cmdVerifyArtifacts(cwd, planFilePath, raw) {
         check.issues.push(`Missing pattern: ${artifact.contains}`);
       }
       if (artifact.exports) {
-        const exports = Array.isArray(artifact.exports) ? artifact.exports : [artifact.exports];
-        for (const exp of exports) {
+        const exps = Array.isArray(artifact.exports) ? artifact.exports : [artifact.exports];
+        for (const exp of exps) {
           if (!fileContent.includes(exp)) check.issues.push(`Missing export: ${exp}`);
         }
       }
@@ -359,43 +349,42 @@ function cmdVerifyArtifacts(cwd, planFilePath, raw) {
     } else {
       check.issues.push('File not found');
     }
-
     results.push(check);
   }
-
   const passed = results.filter(r => r.passed).length;
-  output({
-    all_passed: passed === results.length,
-    passed,
-    total: results.length,
-    artifacts: results,
-  }, raw, passed === results.length ? 'valid' : 'invalid');
+  return { all_passed: passed === results.length, passed, total: results.length, artifacts: results };
 }
 
-/**
- * Verify must_haves.key_links from a plan.md: source-to-target references and patterns.
- * @param {string} cwd - Working directory path
- * @param {string} planFilePath - Path to the plan.md file containing key link specs
- * @param {boolean} raw - If true, output raw value instead of JSON
- * @returns {void}
- */
-function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
+function cmdVerifyArtifacts(cwd, planFilePath, raw) {
   if (!planFilePath) { error('plan file path required'); }
   const fullPath = path.isAbsolute(planFilePath) ? planFilePath : path.join(cwd, planFilePath);
   const content = safeReadFile(fullPath);
   if (!content) { output({ error: 'File not found', path: planFilePath }, raw); return; }
-
-  const keyLinks = parseMustHavesBlock(content, 'key_links');
-  if (keyLinks.length === 0) {
-    output({ error: 'No must_haves.key_links found in frontmatter', path: planFilePath }, raw);
+  const r = checkArtifacts(cwd, content);
+  if (r.total === 0) {
+    output({ error: 'No must_haves.artifacts found in frontmatter', path: planFilePath }, raw);
     return;
   }
+  output(r, raw, r.all_passed ? 'valid' : 'invalid');
+}
 
+/**
+ * Verify must_haves.key_links from a plan.md: source-to-target references and patterns.
+ * @param {string} cwd - Working directory path
+ * @param {string} planFilePath - Path to the plan.md file containing key link specs
+ * @param {boolean} raw - If true, output raw value instead of JSON
+ * @returns {void}
+ */
+/**
+ * Pure wiring check of must_haves.key_links against disk — no output/exit.
+ * Returns {all_verified, verified, total, links}.
+ */
+function checkKeyLinks(cwd, planContent) {
+  const keyLinks = parseMustHavesBlock(planContent, 'key_links');
   const results = [];
   for (const link of keyLinks) {
     if (typeof link === 'string') continue;
     const check = { from: link.from, to: link.to, via: link.via || '', verified: false, detail: '' };
-
     const sourceContent = safeReadFile(path.join(cwd, link.from || ''));
     if (!sourceContent) {
       check.detail = 'Source file not found';
@@ -415,29 +404,142 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
           }
         }
       } catch {
-        // Regex compilation failed -- report the invalid pattern to the caller
         check.detail = `Invalid regex pattern: ${link.pattern}`;
       }
+    } else if (sourceContent.includes(link.to || '')) {
+      check.verified = true;
+      check.detail = 'Target referenced in source';
     } else {
-      // No pattern: just check source references target
-      if (sourceContent.includes(link.to || '')) {
-        check.verified = true;
-        check.detail = 'Target referenced in source';
-      } else {
-        check.detail = 'Target not referenced in source';
-      }
+      check.detail = 'Target not referenced in source';
     }
-
     results.push(check);
   }
-
   const verified = results.filter(r => r.verified).length;
-  output({
-    all_verified: verified === results.length,
-    verified,
-    total: results.length,
-    links: results,
-  }, raw, verified === results.length ? 'valid' : 'invalid');
+  return { all_verified: verified === results.length, verified, total: results.length, links: results };
+}
+
+function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
+  if (!planFilePath) { error('plan file path required'); }
+  const fullPath = path.isAbsolute(planFilePath) ? planFilePath : path.join(cwd, planFilePath);
+  const content = safeReadFile(fullPath);
+  if (!content) { output({ error: 'File not found', path: planFilePath }, raw); return; }
+  const r = checkKeyLinks(cwd, content);
+  if (r.total === 0) {
+    output({ error: 'No must_haves.key_links found in frontmatter', path: planFilePath }, raw);
+    return;
+  }
+  output(r, raw, r.all_verified ? 'valid' : 'invalid');
+}
+
+// ─── Reconcile: cross-check a written verification verdict against the
+// mechanical signals (ADR-0036 review — closes the rubber-stamp gap). ─────────
+
+function findPhaseDir(cwd, phaseNum) {
+  const base = phasesPath(cwd);
+  let entries;
+  try { entries = fs.readdirSync(base, { withFileTypes: true }); } catch { return null; }
+  const re = new RegExp('^0*' + String(phaseNum).replace(/[^0-9A-Za-z.]/g, '') + '-');
+  for (const e of entries) {
+    if (e.isDirectory() && re.test(e.name)) return path.join(base, e.name);
+  }
+  return null;
+}
+
+/**
+ * Re-derive the mechanical signals for a phase and check them against the
+ * verdict written in its -verification.md. A verification that CLAIMS a pass
+ * while artifacts fail substance checks or key-links are unwired is a
+ * contradiction (a rubber stamp) — reported deterministically, never trusted.
+ * When no must_haves are declared there are no mechanical signals to reconcile,
+ * so the verdict is passed through (reconciled: true, with a note).
+ */
+function reconcilePhase(cwd, phaseNum) {
+  const base = { phase: String(phaseNum), found: false, reconciled: true, contradictions: [] };
+  const dir = findPhaseDir(cwd, phaseNum);
+  if (!dir) return { ...base, note: 'phase directory not found' };
+  let files;
+  try { files = fs.readdirSync(dir); } catch { return { ...base, note: 'phase directory unreadable' }; }
+  const verFile = files.find(f => isVerificationFile(f));
+  if (!verFile) return { ...base, note: 'no verification.md — absence is covered by the verification gate, not reconcile' };
+  const verRaw = safeReadFile(path.join(dir, verFile)) || '';
+  const sm = verRaw.match(/^status:\s*([A-Za-z_-]+)/m);
+  const status = sm ? sm[1].toLowerCase() : 'unknown';
+  const claimsPass = /^(pass|passed|verified|complete|verified_pass)$/.test(status);
+  const planFile = files.find(f => isPlanFile(f));
+  const planContent = planFile ? (safeReadFile(path.join(dir, planFile)) || '') : '';
+  const artifacts = checkArtifacts(cwd, planContent);
+  const keyLinks = checkKeyLinks(cwd, planContent);
+  const signals = artifacts.total + keyLinks.total;
+  const contradictions = [];
+  if (claimsPass) {
+    if (artifacts.total > 0 && !artifacts.all_passed) {
+      contradictions.push(`verification status "${status}" but ${artifacts.total - artifacts.passed}/${artifacts.total} artifact substance check(s) FAIL`);
+    }
+    if (keyLinks.total > 0 && !keyLinks.all_verified) {
+      contradictions.push(`verification status "${status}" but ${keyLinks.total - keyLinks.verified}/${keyLinks.total} key-link(s) UNWIRED`);
+    }
+  }
+  return {
+    phase: String(phaseNum), found: true, verification_status: status, claims_pass: claimsPass,
+    mechanical_signals: signals, artifacts, key_links: keyLinks, contradictions,
+    reconciled: contradictions.length === 0,
+    note: signals === 0 ? 'no must_haves declared — mechanical reconciliation unavailable; verdict trusted' : undefined,
+  };
+}
+
+function cmdVerifyReconcile(cwd, phaseNum, raw) {
+  if (!phaseNum) { error('Usage: verify reconcile <phase>'); }
+  const r = reconcilePhase(cwd, phaseNum);
+  output(r, raw, r.reconciled ? 'valid' : 'invalid');
+  process.exit(r.reconciled ? 0 : 1);
+}
+
+// ─── Stub / fake-return scanner (ADR-0036 review — closes the hardcoded
+// "return {ok:true}" / "not implemented" gap the old anti-pattern grep missed,
+// which only blocked the literal `return {}` and `placeholder`/`coming soon`). ─
+const STUB_PATTERNS = [
+  { re: /\bnot[\s_-]?implemented\b/i, marker: 'not-implemented', severity: 'high' },
+  { re: /\bNotImplemented(Error)?\b/, marker: 'NotImplemented', severity: 'high' },
+  { re: /throw\s+new\s+\w*Error\s*\(\s*['"`][^'"`]*\b(unimplemented|not\s+implemented|stub|todo)\b/i, marker: 'throw-stub', severity: 'high' },
+  { re: /\bres(ponse)?\.status\(\s*501\s*\)/, marker: 'http-501', severity: 'high' },
+  { re: /\b(coming\s+soon|placeholder)\b/i, marker: 'placeholder', severity: 'medium' },
+  { re: /return\s*(\{\s*\}|\[\s*\])\s*;?\s*(\/\/.*)?$/, marker: 'empty-return', severity: 'medium' },
+  { re: /return\s*\{\s*ok\s*:\s*true\s*\}\s*;?\s*(\/\/.*)?$/, marker: 'fake-ok-return', severity: 'medium' },
+  { re: /\b(TODO|FIXME|XXX|HACK)\b/, marker: 'todo-marker', severity: 'low' },
+];
+const STUB_CODE_EXT = /\.(js|cjs|mjs|jsx|ts|tsx|py|go|rb|java|php|rs|c|cc|cpp|h|hpp|cs|kt|swift|scala)$/i;
+
+/**
+ * Scan source files for stub / fake-implementation markers. Defaults to the
+ * git-changed files (so it gates a handoff), or a caller-supplied file list.
+ * `high`-severity markers are the blocking set; TODO markers are informational.
+ * @returns {{scanned, findings: Array, blocking: number, total: number}}
+ */
+function scanStubs(cwd, opts = {}) {
+  let files = Array.isArray(opts.files) ? opts.files : getChangedFiles(cwd);
+  files = (files || []).filter(f => STUB_CODE_EXT.test(f));
+  const findings = [];
+  for (const rel of files) {
+    const content = safeReadFile(path.join(cwd, rel));
+    if (content === null) continue;
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      for (const { re, marker, severity } of STUB_PATTERNS) {
+        if (re.test(lines[i])) {
+          findings.push({ file: toPosix(rel), line: i + 1, marker, severity, text: lines[i].trim().slice(0, 160) });
+          break; // one finding per line
+        }
+      }
+    }
+  }
+  const blocking = findings.filter(f => f.severity === 'high').length;
+  return { scanned: files.length, findings, blocking, total: findings.length };
+}
+
+function cmdVerifyStubs(cwd, opts = {}, raw) {
+  const r = scanStubs(cwd, opts);
+  output(r, raw, r.blocking === 0 ? 'valid' : 'invalid');
+  if (opts.gate) process.exit(r.blocking > 0 ? 1 : 0);
 }
 
 /**
@@ -995,12 +1097,12 @@ function syncRequirementCheckboxes(cwd) {
   let fixed = 0;
   for (const phaseNum of completedPhases) {
     const reqMatch = roadmapContent.match(
-      new RegExp(`Phase\\s+${phaseNum.replace(/\./g, '\\.')}[\\s\\S]*?\\*\\*Requirements:\\*\\*\\s*([^\\n]+)`, 'i')
+      new RegExp(`Phase\\s+${escapeRegex(phaseNum)}[\\s\\S]*?\\*\\*Requirements:\\*\\*\\s*([^\\n]+)`, 'i')
     );
     if (!reqMatch) continue;
     const reqIds = reqMatch[1].replace(/[\[\]]/g, '').split(/[,\s]+/).map(id => id.trim()).filter(Boolean);
     for (const reqId of reqIds) {
-      const escaped = reqId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const escaped = escapeRegex(reqId);
       const re = new RegExp(`(- \\[) (\\]\\s*\\*\\*${escaped}\\*\\*)`, 'gi');
       const before = reqContent;
       reqContent = reqContent.replace(re, '$1x$2');
@@ -1284,8 +1386,11 @@ function runFullTestCheck(cwd) {
       stdio: ['pipe', 'pipe', 'pipe'],
       encoding: 'utf-8',
     });
-    const testMatch = result.match(/# tests (\d+)/);
-    const passMatch = result.match(/# pass (\d+)/);
+    // Match both TAP ("# tests N") and spec-reporter ("ℹ tests N") summaries —
+    // modern node --test defaults to the spec reporter, which the old "# "-only
+    // regex silently missed (returning tests: null).
+    const testMatch = result.match(/[#ℹ]\s*tests\s+(\d+)/);
+    const passMatch = result.match(/[#ℹ]\s*pass\s+(\d+)/);
     return {
       pass: true,
       exitCode: 0,
@@ -1344,6 +1449,12 @@ module.exports = {
   cmdVerifyCommits,
   cmdVerifyArtifacts,
   cmdVerifyKeyLinks,
+  checkArtifacts,
+  checkKeyLinks,
+  reconcilePhase,
+  cmdVerifyReconcile,
+  scanStubs,
+  cmdVerifyStubs,
   cmdValidateConsistency,
   cmdValidateHealth,
   cmdPreflight,

package/pan-wizard-core/bin/pan-tools.cjs

@@ -524,6 +524,10 @@ async function main() {
         verify.cmdVerifyArtifacts(cwd, args[2], raw);
       } else if (subcommand === 'key-links') {
         verify.cmdVerifyKeyLinks(cwd, args[2], raw);
+      } else if (subcommand === 'reconcile') {
+        verify.cmdVerifyReconcile(cwd, args[2], raw);
+      } else if (subcommand === 'stubs') {
+        verify.cmdVerifyStubs(cwd, { gate: args.includes('--gate') }, raw);
       } else {
         error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links');
       }
@@ -1303,6 +1307,12 @@ async function main() {
         docLint.cmdDocLintCounts(cwd, dir, { raw, exclude });
         break;
       }
+      if (subcommand === 'flags') {
+        const docDirs = [];
+        for (let k = 0; k < args.length; k++) if (args[k] === '--doc-dir') docDirs.push(args[k + 1]);
+        docLint.cmdDocLintFlags(cwd, { docDirs: docDirs.length ? docDirs : undefined }, raw);
+        break;
+      }
       // Default: lint a directory
       const dir = args[1];
       if (!dir || dir.startsWith('--')) { error('doc-lint <dir> required (or doc-lint schema-check <path>, doc-lint counts <dir>)'); }

package/pan-wizard-core/workflows/exec-phase.md

@@ -659,6 +659,20 @@ if [ -n "$VERIF" ]; then
 fi
 ```
 
+**Cross-check the written verdict against the mechanical signals (anti-rubber-stamp, ADR-0036).** The `status:` string above is authored by the verifier agent; `reconcile` re-derives the artifact/key-link checks from disk and exits non-zero when a claimed pass contradicts them:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify reconcile "${PHASE_NUMBER}" --raw
+RECONCILE_EXIT=$?
+```
+If `RECONCILE_EXIT` is non-zero:
+```
+⚠ Reconcile gate: Phase ${PHASE_NUMBER} verification says "passed" but the mechanical
+  checks disagree — artifacts fail substance checks or key-links are unwired.
+  This is a rubber-stamped verification. Do NOT auto-advance.
+  Re-run /pan:verify-phase and fix the failing artifacts/key-links.
+```
+STOP — do not auto-advance. Return to user.
+
 If `VERIF_STATUS` is not `passed`:
 ```
 ⚠ Verification gate: Phase ${PHASE_NUMBER} verification status is "${VERIF_STATUS:-missing}"

package/scripts/release-check.js

@@ -3,15 +3,16 @@
  * release-check.js — Pre-publish validation gate.
  *
  * Wired into `prepublishOnly` so `npm publish` fails BEFORE upload if any
- * gate is red. Runs five checks in order; first failure aborts.
+ * gate is red. Runs seven checks in order; first failure aborts.
  *
  *   1. build:hooks      — hook scripts copy/build cleanly
  *   2. test:all         — full test suite (unit + scenario) passes
  *   3. npm audit        — no known vulnerabilities in production deps
- *                         (we have zero runtime deps, but esbuild dev-dep is checked)
+ *                         (we have zero runtime deps, but the dev-deps are checked)
  *   4. doc-lint counts  — no drift-prone count violations in user-facing docs
- *   5. npm pack dry-run — package builds; size is sane
- *   6. smoke install    — npm pack + install into temp dir + run pan-tools list
+ *   5. links validate   — doc↔code link graph resolves (no broken references)
+ *   6. npm pack dry-run — package builds; size is sane
+ *   7. smoke install    — npm pack + install into temp dir + run pan-tools list
  *                         catches "ships but doesn't actually work" failures
  *
  * Usage:
@@ -56,7 +57,7 @@ function run(cmd, args, opts = {}) {
 }
 
 // Gate 1: build:hooks
-process.stderr.write('\n[release-check] Gate 1/6: build:hooks\n');
+process.stderr.write('\n[release-check] Gate 1/7: build:hooks\n');
 {
   const r = run('npm', ['run', 'build:hooks']);
   logGate('build:hooks', r.status === 0, r.status !== 0 ? `exit ${r.status}` : '');
@@ -64,7 +65,7 @@ process.stderr.write('\n[release-check] Gate 1/6: build:hooks\n');
 }
 
 // Gate 2: test:all
-process.stderr.write('\n[release-check] Gate 2/6: test:all\n');
+process.stderr.write('\n[release-check] Gate 2/7: test:all\n');
 {
   const r = run('npm', ['run', 'test:all']);
   logGate('test:all', r.status === 0, r.status !== 0 ? `exit ${r.status}` : '');
@@ -73,9 +74,9 @@ process.stderr.write('\n[release-check] Gate 2/6: test:all\n');
 
 // Gate 3: npm audit (production deps only)
 if (SKIP_AUDIT) {
-  process.stderr.write('\n[release-check] Gate 3/6: npm audit (SKIPPED)\n');
+  process.stderr.write('\n[release-check] Gate 3/7: npm audit (SKIPPED)\n');
 } else {
-  process.stderr.write('\n[release-check] Gate 3/6: npm audit --omit=dev\n');
+  process.stderr.write('\n[release-check] Gate 3/7: npm audit --omit=dev\n');
   const r = run('npm', ['audit', '--omit=dev', '--audit-level=high'], { capture: true });
   // npm audit exits non-zero on findings. We tolerate moderate; fail on high+.
   const ok = r.status === 0;
@@ -87,7 +88,7 @@ if (SKIP_AUDIT) {
 }
 
 // Gate 4: doc-lint counts on user-facing docs (count-SSoT enforcement)
-process.stderr.write('\n[release-check] Gate 4/6: doc-lint counts docs/\n');
+process.stderr.write('\n[release-check] Gate 4/7: doc-lint counts docs/\n');
 {
   const tools = path.join(REPO_ROOT, 'pan-wizard-core', 'bin', 'pan-tools.cjs');
   const docsDir = path.join(REPO_ROOT, 'docs');
@@ -100,6 +101,20 @@ process.stderr.write('\n[release-check] Gate 4/6: doc-lint counts docs/\n');
   }
 }
 
+// Gate 5: doc↔code link graph resolves (anti-fake — a doc cannot reference a
+// code anchor that doesn't exist; deterministic, self-enforcing exit 1).
+process.stderr.write('\n[release-check] Gate 5/7: links validate\n');
+{
+  const tools = path.join(REPO_ROOT, 'pan-wizard-core', 'bin', 'pan-tools.cjs');
+  const r = run('node', [tools, 'links', 'validate', '--raw'], { capture: true });
+  const ok = r.status === 0;
+  logGate('links validate', ok, ok ? 'doc↔code link graph resolves' : 'broken doc↔code references');
+  if (!ok) {
+    process.stderr.write((r.stdout || '') + '\n');
+    process.exit(1);
+  }
+}
+
 
 // npm runs lifecycle scripts (prepare) before pack; any of their stdout noise
 // lands ahead of the --json payload. npm pretty-prints the JSON array starting
@@ -111,8 +126,8 @@ function parseNpmJson(stdout) {
   return JSON.parse(stdout.slice(m));
 }
 
-// Gate 5: npm pack dry-run
-process.stderr.write('\n[release-check] Gate 5/6: npm pack --dry-run\n');
+// Gate 6: npm pack dry-run
+process.stderr.write('\n[release-check] Gate 6/7: npm pack --dry-run\n');
 {
   const r = run('npm', ['pack', '--dry-run', '--json'], { capture: true });
   if (r.status !== 0) {
@@ -137,11 +152,11 @@ process.stderr.write('\n[release-check] Gate 5/6: npm pack --dry-run\n');
   }
 }
 
-// Gate 6: smoke install — pack and install into temp dir, run pan-tools
+// Gate 7: smoke install — pack and install into temp dir, run pan-tools
 if (SKIP_SMOKE) {
-  process.stderr.write('\n[release-check] Gate 6/6: smoke install (SKIPPED)\n');
+  process.stderr.write('\n[release-check] Gate 7/7: smoke install (SKIPPED)\n');
 } else {
-  process.stderr.write('\n[release-check] Gate 6/6: smoke install (npm pack + install + sanity)\n');
+  process.stderr.write('\n[release-check] Gate 7/7: smoke install (npm pack + install + sanity)\n');
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-release-smoke-'));
   try {
     // Pack

package/scripts/run-tests.cjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Glob-free test runner. `node --test tests/*.test.cjs` relies on shell glob
+ * expansion: bash provides it (linux/macOS) and Node >=22 expands test-path
+ * globs itself, but Windows PowerShell does neither on Node 18/20 — the
+ * literal pattern "tests/*.test.cjs" matches no file and the run exits 1.
+ * This script expands the pattern deterministically on every platform.
+ *
+ * Usage: node scripts/run-tests.cjs <dir> [<dir> ...]
+ *   Runs every *.test.cjs DIRECTLY inside each listed directory (no recursion,
+ *   so `tests` and `tests/scenarios` stay separately addressable).
+ */
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const dirs = process.argv.slice(2);
+if (dirs.length === 0) {
+  console.error('Usage: node scripts/run-tests.cjs <dir> [<dir> ...]');
+  process.exit(1);
+}
+
+const files = [];
+for (const dir of dirs) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch (e) {
+    console.error(`run-tests: cannot read directory ${dir}: ${e.message}`);
+    process.exit(1);
+  }
+  for (const name of entries.sort()) {
+    if (name.endsWith('.test.cjs')) files.push(path.join(dir, name));
+  }
+}
+
+if (files.length === 0) {
+  console.error(`run-tests: no *.test.cjs files found in: ${dirs.join(', ')}`);
+  process.exit(1);
+}
+
+const result = spawnSync(process.execPath, ['--test', ...files], { stdio: 'inherit' });
+process.exit(result.status ?? 1);