pan-wizard 3.35.0 → 3.36.0

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

@@ -85,65 +85,58 @@ This step provides awareness; the hard gate is enforced by exec-phase.
 </step>
 
 <step name="run_test_suite">
-**Run the project's test suite as a verification gate.**
+**Run the project's test suite as a verification gate, through the engine.**
 
-This step catches test regressions that goal-backward analysis cannot detect.
-
-1. Detect whether a test script exists. **This decides `skipped` vs `failed` later**, so
-   it must be answered BEFORE running anything — `npm test` on a project with no `test`
-   script exits non-zero with "Missing script", which is indistinguishable from a crash
-   once you are only looking at the exit code.
+This step catches test regressions that goal-backward analysis cannot detect. The engine
+runs the suite, not you: it finds the project's test command in any language
+(`workflow.test_command` in config.json, else package.json's test script, pytest, `go test
+./...`, cargo, Maven, Gradle or `make test`), reads the runner's own output, compares it with
+the baseline exec-phase recorded before the first wave, and writes the result to the phase
+directory as `{NN}-test-run.json`.
 
 ```bash
-HAS_TEST=$(node -e "try{const p=require('./package.json');process.stdout.write(p.scripts&&p.scripts.test?'yes':'no')}catch(e){process.stdout.write('no')}")
+TEST_RUN=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs test run --phase "${phase_number}")
 ```
 
-   **If `HAS_TEST` is `no`:** record `test_gate_status: skipped` and go to step 4. Do not
-   run the suite, and do not report a crash — there is nothing to run.
+Read from the JSON: `status`, `reason`, `command`, `total`, `passed`, `failed`,
+`regressions`, `preexisting_failures` and `record`.
 
-2. Run test suite and capture results:
-```bash
-TEST_OUTPUT=$(npm test 2>&1)
-TEST_EXIT=$?
-TEST_COUNT=$(echo "$TEST_OUTPUT" | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
-TEST_PASS=$(echo "$TEST_OUTPUT" | grep -E "^(ℹ|#) pass" | awk '{print $NF}')
-TEST_FAIL=$(echo "$TEST_OUTPUT" | grep -E "^(ℹ|#) fail" | awk '{print $NF}')
-```
+**Copy the status; do not judge it.** Write `test_gate: <status>` into the verification.md
+frontmatter exactly as the record says. Reconcile compares the two, so a verification whose
+`test_gate` disagrees with the record is refused at the phase gate, and a failed record
+lowers a `passed` verification to `gaps_found` whatever the frontmatter says.
 
-3. Evaluate results.
+| `status` | What it means | What you do |
+|----------|---------------|-------------|
+| `passed` | The suite ran and nothing that passed at the baseline fails now | Record the counts. If `preexisting_failures` is not empty, list them as known failures the phase inherited, not as gaps |
+| `failed` | A test that passed at the baseline fails now (`regressions`), or the suite did not run at all (a crash, a build error, a timeout: `reason` says `suite did not run`) | Set the overall status to `gaps_found` and list each regression, or the reason, as a gap |
+| `skipped` | There was nothing to run: no test command, or one that ran no tests | Add a `not_checked` entry: `check: "tests"`, `reason:` the record's `reason` |
 
-**Check `TEST_EXIT` FIRST, before any count.** A suite that did not run emits no
-`ℹ fail` / `# fail` line at all, so `TEST_FAIL` comes back EMPTY — not `0`. Reading an empty
-value as "no failures" scores a crashed suite as a pass, which is the worst
-direction this gate can fail in: a phase ships green on a project whose tests never
-executed. Empty is not zero. Judge the exit code, then the counts.
+A suite that exists and did not run is `failed`, never `skipped`: the engine decides that
+from the exit code and the runner's output, and you copy it.
+
+**If test gate FAILED:** Continue verification (gather full picture) but set overall status to `gaps_found` regardless of goal-backward results. Include test failures as gaps in the report.
+</step>
 
-| Condition | Action |
-|-----------|--------|
-| `TEST_EXIT` = 0 **and** `TEST_FAIL` = 0 (a real number) | Record counts, continue to must-haves |
-| `TEST_EXIT` = 0 **and** no `ℹ`/`#` count lines (a runner other than Node's built-in one) | Set `test_gate_status: passed`; record the runner's own summary line as the counts |
-| `TEST_EXIT` ≠ 0 **and** failures were reported | Set `test_gate_status: failed`, include failure details |
-| `TEST_EXIT` ≠ 0 **and** `TEST_FAIL` is empty/absent — the suite CRASHED or could not run (syntax error, missing module, bad import, no runner) | Set `test_gate_status: failed`, and record the reason as `suite did not run`. **Never `skipped`, never `passed`.** A suite that cannot execute is stronger evidence of a broken phase than one that runs and fails |
-| `HAS_TEST` = `no` (handled in step 1) | Record as `test_gate_status: skipped`, continue. This is the ONLY legitimate route to `skipped` |
+<step name="mutation_report">
+**Measure whether the tests pin the code the phase wrote** (a report, never a gate).
 
-**The distinction that matters:** *no test command exists* is a project that never had
-tests — a known, acceptable gap. *A test command exists and did not run* is a broken
-project. They must never share a verdict; the first is `skipped`, the second is
-`failed`.
+Only when the test gate passed: a mutant cannot be read against a suite that already fails.
+With `workflow.mutation_gate: off` the command runs nothing and says so.
 
-4. Store test gate results for inclusion in verification.md:
-```
-TEST_GATE_STATUS: passed | failed | skipped
-TEST_TOTAL: ${TEST_COUNT}
-TEST_PASSED: ${TEST_PASS}
-TEST_FAILED: ${TEST_FAIL}
+```bash
+MUTATION=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify mutate --phase "${phase_number}" --max 5)
 ```
-   Write `test_gate: ${TEST_GATE_STATUS}` into the verification.md frontmatter. When it is
-   `skipped`, also add a `not_checked` entry (`check: "tests"`, `reason: "no test script in
-   package.json"`). The recorder reads both: a pass whose tests never ran is recorded as a
-   pass with tests not checked, never as a plain pass.
 
-**If test gate FAILED:** Continue verification (gather full picture) but set overall status to `gaps_found` regardless of goal-backward results. Include test failures as gaps in the report.
+The engine flips one comparison, boolean or `+ 1` at a time on the lines the phase's plan
+commits changed, in a throwaway worktree at HEAD, and runs the suite against each mutant. Read
+`checked`, `sampled`, `killed`, `survivors` (file, line, the swap) and `aborted`.
+
+Write a **Test strength** section in verification.md: `killed/sampled`, and each survivor as
+`file:line — before → after`, framed as a test the phase could add. A survivor is a lead, not a
+gap: it never changes the status. `aborted: flaky` (the unmutated suite passed once and failed
+once) is worth reporting as a finding of its own; `checked: false` with its `reason` goes in
+`not_checked` as `check: "mutation"`.
 </step>
 
 <step name="establish_must_haves">

package/scripts/build-help.cjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Generate /pan:help's command index from command frontmatter (program L5).
+ *
+ *   node scripts/build-help.cjs            # print the block
+ *   node scripts/build-help.cjs --write    # rewrite the block in pan-wizard-core/workflows/help.md
+ *   node scripts/build-help.cjs --check    # exit 1 when the committed block is stale
+ *
+ * The block between GENERATED_START and GENERATED_END in help.md lists every
+ * commands/pan/*.md by its frontmatter `group` and `description`, so help cannot leave
+ * a command out. tests/help-generated.test.cjs fails when it is stale.
+ */
+const fs = require('fs');
+const path = require('path');
+const { extractFrontmatter } = require('../pan-wizard-core/bin/lib/frontmatter.cjs');
+
+const ROOT = path.join(__dirname, '..');
+const HELP_REL = path.join('pan-wizard-core', 'workflows', 'help.md');
+const GENERATED_START = '<!-- generated:command-index:start (scripts/build-help.cjs --write) -->';
+const GENERATED_END = '<!-- generated:command-index:end -->';
+
+// The order a new user reads the groups in; groups not listed follow, alphabetically.
+const GROUP_ORDER = [
+  'Getting Started', 'Phase Lifecycle', 'Phase Management', 'Session & Progress',
+  'Milestone', 'Milestone Lifecycle', 'Focus', 'Foresight', 'Review', 'Validation',
+  'Observability', 'Knowledge', 'Self-Improvement', 'Git Workflow', 'Army',
+  'External tools', 'System', 'Community',
+];
+
+/** Every shipped command as {name, group, description}, sorted by name. */
+function readCommands(root = ROOT) {
+  const dir = path.join(root, 'commands', 'pan');
+  return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).sort().map((f) => {
+    const fm = extractFrontmatter(fs.readFileSync(path.join(dir, f), 'utf-8')) || {};
+    return {
+      // The file name is the command (`/pan:<file>`); some frontmatter names omit the prefix.
+      name: `pan:${f.replace(/\.md$/, '')}`,
+      group: String(fm.group || '').trim(),
+      description: String(fm.description || '').replace(/\s+/g, ' ').trim(),
+    };
+  });
+}
+
+// Backslashes first, so one in a description cannot turn the escaped pipe after it back into a cell break.
+const cell = (s) => s.replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+
+/** The markdown command index, grouped. Throws on a command with no group or description. */
+function renderCommandIndex(commands) {
+  const groups = new Map();
+  for (const c of commands) {
+    if (!c.group) throw new Error(`${c.name} has no group in its frontmatter`);
+    if (!c.description) throw new Error(`${c.name} has no description in its frontmatter`);
+    if (!groups.has(c.group)) groups.set(c.group, []);
+    groups.get(c.group).push(c);
+  }
+  const rank = (g) => { const i = GROUP_ORDER.indexOf(g); return i === -1 ? GROUP_ORDER.length : i; };
+  const order = [...groups.keys()].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+  const out = [];
+  for (const g of order) {
+    out.push(`### ${g}`, '| Command | Description |', '|---------|-------------|');
+    for (const c of groups.get(g).sort((a, b) => a.name.localeCompare(b.name))) out.push(`| \`/${c.name}\` | ${cell(c.description)} |`);
+    out.push('');
+  }
+  return out.join('\n').trimEnd();
+}
+
+/** The generated block's content in a help.md text, or null when the markers are missing. */
+function extractBlock(text) {
+  const t = String(text).replace(/\r\n/g, '\n');
+  const a = t.indexOf(GENERATED_START);
+  const b = t.indexOf(GENERATED_END);
+  if (a === -1 || b === -1 || b < a) return null;
+  return t.slice(a + GENERATED_START.length, b).trim();
+}
+
+/** help.md with its block replaced by `block`. Throws when the markers are missing. */
+function replaceBlock(text, block) {
+  const t = String(text).replace(/\r\n/g, '\n');
+  const a = t.indexOf(GENERATED_START);
+  const b = t.indexOf(GENERATED_END);
+  if (a === -1 || b === -1 || b < a) throw new Error(`${HELP_REL} has no generated command-index markers`);
+  return t.slice(0, a + GENERATED_START.length) + '\n' + block + '\n' + t.slice(b);
+}
+
+function main(argv) {
+  const file = path.join(ROOT, HELP_REL);
+  const block = renderCommandIndex(readCommands(ROOT));
+  if (argv.includes('--write')) {
+    fs.writeFileSync(file, replaceBlock(fs.readFileSync(file, 'utf-8'), block));
+    process.stdout.write(`wrote the command index into ${HELP_REL}\n`);
+  } else if (argv.includes('--check')) {
+    if (extractBlock(fs.readFileSync(file, 'utf-8')) !== block) {
+      process.stderr.write(`${HELP_REL}'s command index is stale: run node scripts/build-help.cjs --write\n`);
+      process.exitCode = 1;
+    } else {
+      process.stdout.write(`${HELP_REL}'s command index is up to date\n`);
+    }
+  } else {
+    process.stdout.write(block + '\n');
+  }
+}
+
+if (require.main === module) main(process.argv.slice(2));
+
+module.exports = { GROUP_ORDER, GENERATED_START, GENERATED_END, readCommands, renderCommandIndex, extractBlock, replaceBlock };

package/scripts/mutation-probe.cjs

@@ -51,86 +51,13 @@ const TARGETS = [
   { file: 'pan-wizard-core/bin/pan-tools.cjs', tests: ['tests/dispatcher.test.cjs', 'tests/dispatcher-arms.test.cjs'] },
 ];
 
-/**
- * The mutation operators. Each is a plain textual swap with a token that must appear
- * OUTSIDE a string or comment to be worth mutating (see mutableLine). They are deliberately
- * few and blunt: the point is to find unconstrained logic, not to enumerate every possible
- * defect.
- */
-const OPERATORS = [
-  { id: 'gte→gt', find: ' >= ', replace: ' > ' },
-  { id: 'gt→gte', find: ' > ', replace: ' >= ' },
-  { id: 'lte→lt', find: ' <= ', replace: ' < ' },
-  { id: 'lt→lte', find: ' < ', replace: ' <= ' },
-  { id: 'eq→neq', find: ' === ', replace: ' !== ' },
-  { id: 'neq→eq', find: ' !== ', replace: ' === ' },
-  { id: 'and→or', find: ' && ', replace: ' || ' },
-  { id: 'or→and', find: ' || ', replace: ' && ' },
-  { id: 'true→false', find: 'return true', replace: 'return false' },
-  { id: 'false→true', find: 'return false', replace: 'return true' },
-  { id: 'plus→minus', find: ' + 1', replace: ' - 1' },
-];
-
-/**
- * Is this line worth mutating? Skips comments, and skips a line whose only occurrence of
- * the token is inside a string literal — mutating a message changes nothing a test should
- * be pinning, and a survivor there would be noise.
- *
- * Crude but conservative: a line containing a quote is only mutated when the token also
- * occurs before the first quote.
- */
-function mutableLine(line, token) {
-  const trimmed = line.trim();
-  if (!trimmed || trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) return false;
-  const at = line.indexOf(token);
-  if (at === -1) return false;
-  const firstQuote = Math.min(
-    ...["'", '"', '`'].map((q) => { const i = line.indexOf(q); return i === -1 ? Infinity : i; }),
-  );
-  return at < firstQuote;
-}
-
-/**
- * Every mutation available in a source file: one per (line, operator) pair, first
- * occurrence on the line.
- *
- * @returns {Array<{line: number, op: string, before: string, after: string}>}
- */
-function mutationsFor(src) {
-  const lines = src.split(/\r?\n/);
-  const out = [];
-  lines.forEach((line, i) => {
-    for (const op of OPERATORS) {
-      if (!mutableLine(line, op.find)) continue;
-      out.push({ line: i + 1, op: op.id, before: line, after: line.replace(op.find, op.replace) });
-    }
-  });
-  return out;
-}
-
-/** Apply one mutation to a source string, by line number. Throws if the line moved. */
-function applyMutation(src, mutation) {
-  const eol = src.includes('\r\n') ? '\r\n' : '\n';
-  const lines = src.split(/\r?\n/);
-  const idx = mutation.line - 1;
-  if (lines[idx] !== mutation.before) {
-    throw new Error(`line ${mutation.line} is not what the mutation was built from`);
-  }
-  lines[idx] = mutation.after;
-  return lines.join(eol);
-}
-
-/** Deterministic shuffle, so a run is reproducible from its seed. */
-function sample(items, n, seed) {
-  let s = seed >>> 0;
-  const rand = () => { s = (s * 1664525 + 1013904223) >>> 0; return s / 0x100000000; };
-  const copy = items.slice();
-  for (let i = copy.length - 1; i > 0; i--) {
-    const j = Math.floor(rand() * (i + 1));
-    [copy[i], copy[j]] = [copy[j], copy[i]];
-  }
-  return copy.slice(0, n);
-}
+// The operators, the line filter, mutation and the seeded sample live in the shipped
+// mutation report (pan-wizard-core/bin/lib/mutate.cjs, program V5), which a user's phase
+// diff is measured with; this probe applies the JavaScript table to PAN itself.
+const M = require('../pan-wizard-core/bin/lib/mutate.cjs');
+const OPERATORS = M.OPERATORS.js;
+const { mutableLine, applyMutation, sample } = M;
+const mutationsFor = (src) => M.mutationsFor(src, { family: 'js' });
 
 function parseArgs(argv) {
   const a = { max: 20, seed: 1, json: false, targets: [], timeoutMs: 600000, help: false };

package/scripts/test-surface.cjs

@@ -19,7 +19,9 @@
  * Modes:
  *   node scripts/test-surface.cjs            summary
  *   node scripts/test-surface.cjs --write    write tests/fixtures/surface.json (the committed registry)
- *   node scripts/test-surface.cjs --check    exit 1 when the committed registry differs from the code
+ *   node scripts/test-surface.cjs --check    exit 1 when the committed registry differs from the code, or
+ *                                            a command, agent, verb or config key has no user (liveness, L1)
+ *   node scripts/test-surface.cjs --liveness who uses each command, agent, verb, subcommand and config key
  *   node scripts/test-surface.cjs --map      which test files reference each surface row; lists the misses
  *   node scripts/test-surface.cjs --scaffold <dir>   one todo stub per unreferenced row (for a suite rebuilt from scratch)
  *
@@ -297,6 +299,153 @@ function scaffold(missingRows, outDir) {
 
 function readJson(p) { return JSON.parse(fs.readFileSync(p, 'utf8')); }
 
+// ─── Liveness (program L1) ──────────────────────────────────────────────────
+//
+// The map above asks "does a test name it?". Liveness asks "does anything USE it?":
+//   - every shipped command and agent is named by a harness scenario, so some behavioural
+//     run exercises it as a user would;
+//   - every pan-tools verb and subcommand has a caller in what PAN ships: a prompt
+//     (commands, agents, workflows, references, templates), a native workflow's prompt
+//     (bin/install-lib.cjs), or an MCP tool or resource (the bridge registry);
+//   - every config default has a reader: code under the core, hooks, installer or MCP
+//     bridge that reads the key, or a shipped prompt that runs `config-get <key>`.
+// An orphan either gains a user or sits in tests/fixtures/liveness-allowlist.json with a
+// reason; `--check` fails on an orphan without one, and on an entry no longer needed.
+
+const LIVENESS_ALLOWLIST_REL = path.join('tests', 'fixtures', 'liveness-allowlist.json');
+const PROMPT_DIRS = Object.freeze(['commands/pan', 'agents', 'pan-wizard-core/workflows', 'pan-wizard-core/references', 'pan-wizard-core/templates']);
+const NATIVE_WORKFLOW_SOURCES = Object.freeze(['bin/install-lib.cjs']);
+const READER_DIRS = Object.freeze(['pan-wizard-core/bin', 'pan-wizard-core/mcp', 'pan-wizard-core/opencode', 'hooks', 'bin']);
+const SCENARIO_DIR = 'harness/scenarios';
+
+/** Every file under rel (recursively) whose name matches re, as posix paths; skips dist/ and node_modules/. */
+function walkFiles(root, rel, re) {
+  const out = [];
+  const walk = (r) => {
+    let ents;
+    try { ents = fs.readdirSync(path.join(root, r), { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const p = path.posix.join(r, e.name);
+      if (e.isDirectory()) { if (e.name !== 'dist' && e.name !== 'node_modules') walk(p); } else if (re.test(e.name)) out.push(p);
+    }
+  };
+  walk(rel);
+  return out.sort();
+}
+
+/**
+ * The verbs and `verb sub` pairs a text invokes: the script path (`pan-tools.cjs <verb>`),
+ * a backticked `pan-tools <verb>`, or `pan-tools <verb>` as a shell command (opening a
+ * line, or after `|`, `;`, `&` or `(`), then the verb and an optional subcommand. Prose
+ * that mentions pan-tools is not a call.
+ */
+function pantoolsCalls(text) {
+  const out = new Set();
+  const re = /(?:pan-tools\.cjs["']?|`pan-tools|(?:^|[|;&(])[ \t]*pan-tools)[ \t]+([a-z][a-z0-9-]*)(?:[ \t]+([a-z][a-z0-9-]*))?/gm;
+  let m;
+  while ((m = re.exec(text))) { out.add(m[1]); if (m[2]) out.add(`${m[1]} ${m[2]}`); }
+  return out;
+}
+
+/** The text a liveness check reads, from the tree. Tests pass a hand-built object instead. */
+function loadLivenessInputs(root = ROOT) {
+  const read = (rel) => fs.readFileSync(path.join(root, rel), 'utf8');
+  const prompts = PROMPT_DIRS.flatMap((d) => walkFiles(root, d, /\.(md|js)$/)).map((file) => ({ file, src: read(file) }));
+  const native = NATIVE_WORKFLOW_SOURCES.filter((f) => fs.existsSync(path.join(root, f))).map((file) => ({ file, src: read(file) }));
+  const registry = require(path.join(root, SOURCES.mcpRegistry));
+  const mcp = [...(registry.TOOLS || []), ...(registry.RESOURCES || [])].map((t) => ({ name: t.name || t.uri, verb: t.verb, sub: (t.args && t.args[0]) || null }));
+  const scenarios = walkFiles(root, SCENARIO_DIR, /\.json$/).map((file) => ({ file, src: read(file) }));
+  const configSrc = path.posix.normalize(SOURCES.config);
+  const readers = READER_DIRS.flatMap((d) => walkFiles(root, d, /\.(c?js|mjs)$/)).map((file) => ({ file, src: read(file), isConfig: file === configSrc }));
+  return { prompts, native, mcp, scenarios, readers };
+}
+
+/** The body of buildConfigDefaults in config.cjs: where defaults are written, which is not a read. */
+function stripDefaultsBuilder(src) {
+  const start = src.indexOf('function buildConfigDefaults');
+  if (start === -1) return src;
+  const open = src.indexOf('{', start);
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    if (src[i] === '{') depth++;
+    else if (src[i] === '}' && --depth === 0) return src.slice(0, start) + src.slice(i + 1);
+  }
+  return src;
+}
+
+/**
+ * Who uses each piece of the surface. Pure over `surface` (extractSurface) and `inputs`
+ * (loadLivenessInputs). Returns one row per command, agent, verb, subcommand and config
+ * key: `{id, kind, users: string[]}`; a row with no users is an orphan.
+ */
+function liveness(surface, inputs) {
+  const rows = [];
+  const scen = inputs.scenarios;
+  const named = (re) => scen.filter((s) => re.test(s.src)).map((s) => s.file);
+  for (const f of surface.content['commands/pan'] || []) {
+    const name = f.replace(/\.md$/, '');
+    // /pan:<name> (Claude, Gemini), /pan-<name> or pan-<name> as a skill (Codex, Copilot, OpenCode), or the file itself.
+    rows.push({ id: `command:${name}`, kind: 'command', users: named(new RegExp(`(?:/pan[:-]|commands/pan/|\\bpan-)${esc(name)}(?![a-z0-9-])`)) });
+  }
+  for (const f of surface.content.agents || []) {
+    const name = f.replace(/\.md$/, '');
+    rows.push({ id: `agent:${name}`, kind: 'agent', users: named(new RegExp(`(?<![a-z0-9-])${esc(name)}(?![a-z0-9-])`)) });
+  }
+  const callers = new Map();
+  const add = (key, who) => { if (!callers.has(key)) callers.set(key, new Set()); callers.get(key).add(who); };
+  for (const t of [...inputs.prompts, ...inputs.native]) for (const c of pantoolsCalls(t.src)) add(c, t.file);
+  // A registry entry with no verb (one served by the bridge itself) calls nothing.
+  for (const t of inputs.mcp.filter((x) => x.verb)) { add(t.verb, `mcp:${t.name}`); if (t.sub) add(`${t.verb} ${t.sub}`, `mcp:${t.name}`); }
+  for (const v of surface.verbs) {
+    const direct = callers.get(v) || new Set();
+    // A verb is alive when it is called, bare or through any of its subcommands.
+    const viaSub = [...callers.entries()].filter(([k]) => k.startsWith(`${v} `)).flatMap(([, s]) => [...s]);
+    rows.push({ id: `caller:verb:${v}`, kind: 'verb', users: [...new Set([...direct, ...viaSub])].sort() });
+  }
+  for (const s of surface.subcommands) rows.push({ id: `caller:sub:${s}`, kind: 'sub', users: [...(callers.get(s) || [])].sort() });
+  const readerText = inputs.readers.map((r) => ({ file: r.file, src: r.isConfig ? stripDefaultsBuilder(r.src) : r.src }));
+  const promptText = [...inputs.prompts, ...inputs.native];
+  for (const key of surface.config_keys) {
+    const last = esc(key.split('.').pop());
+    const codeRe = new RegExp(`['"\`]${esc(key)}['"\`]|\\.${last}\\b|\\[['"]${last}['"]\\]|['"]${last}['"]`);
+    // A prompt reads a key with `config-get <key>`, or names the full dotted key in backticks
+    // for the agent to check in the config or the init payload (`workflow.x: true`).
+    const promptRe = new RegExp(`config-get[ \\t]+["']?${esc(key)}\\b|\`${esc(key)}[\`:= ]`);
+    const users = [...readerText.filter((r) => codeRe.test(r.src)).map((r) => r.file), ...promptText.filter((p) => promptRe.test(p.src)).map((p) => p.file)];
+    rows.push({ id: `reader:config:${key}`, kind: 'config', users: [...new Set(users)].sort() });
+  }
+  return rows;
+}
+
+/**
+ * Orphans not allowlisted, and allowlist entries that are wrong (no reason, no such row, or
+ * a row that has users now). `--check` fails when either list is non-empty.
+ */
+function livenessProblems(rows, allowlist) {
+  const allow = new Map(allowlist.map((a) => [a.id, a]));
+  const problems = [];
+  for (const a of allowlist) {
+    if (!a.reason || !String(a.reason).trim()) problems.push(`liveness allowlist entry ${a.id} has no reason`);
+    const row = rows.find((r) => r.id === a.id);
+    if (!row) problems.push(`liveness allowlist entry ${a.id} names nothing that exists — remove it`);
+    else if (row.users.length) problems.push(`liveness allowlist entry ${a.id} has a user now (${row.users[0]}) — remove the entry`);
+  }
+  const hint = { command: 'name it in a harness scenario', agent: 'name it in a harness scenario', verb: 'call it from a shipped prompt', sub: 'call it from a shipped prompt', config: 'read it in code, or drop the default' };
+  for (const r of rows) if (!r.users.length && !allow.has(r.id)) problems.push(`orphan ${r.id} — ${hint[r.kind]}, or allowlist it in ${LIVENESS_ALLOWLIST_REL} with a reason`);
+  return problems;
+}
+
+/** What `--check` decides: registry drift plus liveness problems. Pure. */
+function checkReport(committed, surface, inputs, allowlist) {
+  const drift = diffSurface(committed, surface);
+  const live = livenessProblems(liveness(surface, inputs), allowlist);
+  return { drift, live, ok: !drift.added.length && !drift.removed.length && !live.length };
+}
+
+function readLivenessAllowlist(root = ROOT) {
+  try { return readJson(path.join(root, LIVENESS_ALLOWLIST_REL)); } catch { return []; }
+}
+
 // ─── CLI ────────────────────────────────────────────────────────────────────
 
 function main(argv) {
@@ -310,13 +459,25 @@ function main(argv) {
   if (argv.includes('--check')) {
     let committed;
     try { committed = readJson(registryPath); } catch { console.error(`no committed registry at ${REGISTRY_REL} — run --write`); return 1; }
-    const d = diffSurface(committed, surface);
-    if (!d.added.length && !d.removed.length) { console.log('surface registry matches the code'); return 0; }
-    console.error(`surface registry is stale — run \`node scripts/test-surface.cjs --write\` and commit it`);
-    for (const x of d.added) console.error(`  + ${x}`);
-    for (const x of d.removed) console.error(`  - ${x}`);
+    const { drift: d, live, ok } = checkReport(committed, surface, loadLivenessInputs(ROOT), readLivenessAllowlist(ROOT));
+    if (ok) { console.log('surface registry matches the code; every command, agent, verb and config key is alive'); return 0; }
+    if (d.added.length || d.removed.length) {
+      console.error(`surface registry is stale — run \`node scripts/test-surface.cjs --write\` and commit it`);
+      for (const x of d.added) console.error(`  + ${x}`);
+      for (const x of d.removed) console.error(`  - ${x}`);
+    }
+    if (live.length) {
+      console.error('liveness: orphans without a user or an allowlist reason');
+      for (const x of live) console.error(`  ${x}`);
+    }
     return 1;
   }
+  if (argv.includes('--liveness')) {
+    const rows = liveness(surface, loadLivenessInputs(ROOT));
+    for (const r of rows) console.log(`${r.users.length ? 'ok    ' : 'ORPHAN'} ${r.id.padEnd(48)} ${r.users.slice(0, 2).join(', ')}${r.users.length > 2 ? ` +${r.users.length - 2}` : ''}`);
+    console.log(`liveness rows: ${rows.length} · orphans: ${rows.filter((r) => !r.users.length).length}`);
+    return 0;
+  }
   const rows = mapSurface(surfaceRows(surface), loadTestSources(ROOT));
   const missing = rows.filter((r) => !r.hits.length);
   if (argv.includes('--scaffold')) {
@@ -339,4 +500,5 @@ module.exports = {
   ROOT, REGISTRY_REL, ALLOWLIST_REL, SOURCES, EXTRA_HOOK_ROWS,
   parseTopLevelCommands, parseGroupSubcommands, parseCaseArms, parseInstallerFlags, flattenKeys, hookMatrix,
   extractSurface, surfaceRows, referencePattern, mapSurface, listTestFiles, loadTestSources, diffSurface, scaffold,
+  LIVENESS_ALLOWLIST_REL, pantoolsCalls, loadLivenessInputs, stripDefaultsBuilder, liveness, livenessProblems, checkReport, readLivenessAllowlist,
 };