pan-wizard 3.28.0 → 3.30.0

package/scripts/mutation-probe.cjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Mutation probe — does the suite NOTICE when the code is wrong?
+ *
+ * Coverage says a line executed. It does not say an assertion depended on it. This probe
+ * answers the harder question by breaking the code on purpose: apply one small mutation,
+ * run the tests that claim to cover that file, and see whether anything turns red. A
+ * mutation the suite does not catch is a **survivor** — a line that runs during the tests
+ * and that no assertion actually constrains.
+ *
+ * Phase 6 of docs/specs/testing-system-redesign-2026-09.md. That phase proposed Stryker as
+ * a devDependency; this is the same idea without one, for a specific reason: nearly every
+ * test here asserts through a SPAWNED `pan-tools` process, so a mutation-testing framework
+ * built around in-process instrumentation would have to re-run whole subprocess suites per
+ * mutant anyway. What it would add over this file is a mutant catalogue and an HTML report,
+ * at the cost of a large dependency tree in a repo whose headline claim is zero
+ * dependencies. So: a sampled probe, dependency-free, and REPORT-ONLY.
+ *
+ * **This is not a gate and must never become one.** A survivor is a question ("should an
+ * assertion pin this?"), and some survivors are correct — equivalent mutants, defensive
+ * branches, log strings. Release-check does not run it and CI does not run it.
+ *
+ * Safety: mutations are applied inside a throwaway `git worktree`, never in your checkout.
+ * The worktree is removed at the end, including after a crash.
+ *
+ *   node scripts/mutation-probe.cjs                      # default targets, 20 mutants
+ *   node scripts/mutation-probe.cjs --max 50
+ *   node scripts/mutation-probe.cjs --target hooks/pan-cost-logger.js
+ *   node scripts/mutation-probe.cjs --seed 7 --json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync, spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+
+/**
+ * What to probe, and which tests are supposed to catch a break in it. The spec names the
+ * hooks and the dispatcher first: the hooks because they are the code that writes the
+ * ledger every field number comes from, the dispatcher because its arms are the surface a
+ * user and an orchestrator hit.
+ */
+const TARGETS = [
+  { file: 'hooks/pan-cost-logger.js', tests: ['tests/cost-logger-hook.test.cjs', 'tests/cost-logger.test.cjs'] },
+  { file: 'hooks/pan-trace-logger.js', tests: ['tests/trace-logger.test.cjs'] },
+  { file: 'pan-wizard-core/bin/lib/cost.cjs', tests: ['tests/cost.test.cjs'] },
+  { file: 'pan-wizard-core/bin/lib/cost-rebuild.cjs', tests: ['tests/cost-rebuild.test.cjs'] },
+  { 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);
+}
+
+function parseArgs(argv) {
+  const a = { max: 20, seed: 1, json: false, targets: [], timeoutMs: 600000, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i]; const v = argv[i + 1];
+    if (k === '--max') { a.max = Math.max(1, Number(v) || 1); i++; }
+    else if (k === '--seed') { a.seed = Number(v) || 1; i++; }
+    else if (k === '--target') { a.targets.push(v); i++; }
+    else if (k === '--timeout') { a.timeoutMs = Math.max(30000, Number(v) || 30000); i++; }
+    else if (k === '--json') a.json = true;
+    else if (k === '--help' || k === '-h') a.help = true;
+    else throw new Error(`unknown argument: ${k}`);
+  }
+  return a;
+}
+
+/**
+ * Run one target's tests inside `cwd`. A mutation is CAUGHT when they fail.
+ * A test run that cannot start at all counts as caught too — the code is broken enough
+ * that nothing ran, which is not a survivor.
+ */
+function testsFail(cwd, tests, timeoutMs) {
+  const r = spawnSync(process.execPath, ['--test', ...tests], {
+    cwd, encoding: 'utf-8', timeout: timeoutMs, stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (r.error && r.error.code === 'ETIMEDOUT') return true; // an infinite loop is a detection
+  return r.status !== 0;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write('node scripts/mutation-probe.cjs [--max n] [--seed n] [--target <file>]... [--timeout ms] [--json]\n');
+    return 0;
+  }
+
+  const targets = args.targets.length
+    ? TARGETS.filter((t) => args.targets.some((want) => t.file.endsWith(want.replace(/\\/g, '/'))))
+    : TARGETS;
+  if (!targets.length) {
+    process.stderr.write(`no known target matched ${args.targets.join(', ')}\nknown: ${TARGETS.map((t) => t.file).join(', ')}\n`);
+    return 1;
+  }
+
+  // Build the candidate list from the real sources, then sample across all targets so one
+  // large file cannot crowd the others out.
+  const candidates = [];
+  for (const t of targets) {
+    const src = fs.readFileSync(path.join(ROOT, t.file), 'utf-8');
+    for (const m of mutationsFor(src)) candidates.push({ ...m, ...t });
+  }
+  const chosen = sample(candidates, args.max, args.seed);
+
+  // Everything happens in a throwaway worktree: the probe never edits your checkout.
+  const wt = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-mutation-'));
+  let created = false;
+  const survivors = [];
+  let caught = 0;
+  try {
+    execFileSync('git', ['worktree', 'add', '--detach', wt, 'HEAD'], { cwd: ROOT, stdio: 'ignore' });
+    created = true;
+    // The hooks are copied to hooks/dist by the build; tests that spawn the built copy
+    // need it present in the worktree.
+    spawnSync(process.execPath, ['scripts/build-hooks.js'], { cwd: wt, stdio: 'ignore' });
+
+    let i = 0;
+    for (const m of chosen) {
+      i += 1;
+      const file = path.join(wt, m.file);
+      const original = fs.readFileSync(file, 'utf-8');
+      let mutated;
+      try {
+        mutated = applyMutation(original, m);
+      } catch {
+        continue; // the worktree's copy differs from the working tree — skip, do not guess
+      }
+      if (mutated === original) continue;
+      try {
+        fs.writeFileSync(file, mutated);
+        // A hook mutation must reach the built copy the tests spawn.
+        if (m.file.startsWith('hooks/')) spawnSync(process.execPath, ['scripts/build-hooks.js'], { cwd: wt, stdio: 'ignore' });
+        const detected = testsFail(wt, m.tests, args.timeoutMs);
+        if (detected) caught += 1;
+        else survivors.push(m);
+        if (!args.json) {
+          process.stdout.write(`  [${String(i).padStart(2)}/${chosen.length}] ${detected ? 'caught  ' : 'SURVIVED'} ${m.file}:${m.line} ${m.op}\n`);
+        }
+      } finally {
+        fs.writeFileSync(file, original);
+        if (m.file.startsWith('hooks/')) spawnSync(process.execPath, ['scripts/build-hooks.js'], { cwd: wt, stdio: 'ignore' });
+      }
+    }
+  } finally {
+    if (created) {
+      try { execFileSync('git', ['worktree', 'remove', '--force', wt], { cwd: ROOT, stdio: 'ignore' }); } catch { /* fall through */ }
+    }
+    fs.rmSync(wt, { recursive: true, force: true });
+    try { execFileSync('git', ['worktree', 'prune'], { cwd: ROOT, stdio: 'ignore' }); } catch { /* best effort */ }
+  }
+
+  const ran = caught + survivors.length;
+  const report = {
+    candidates: candidates.length,
+    sampled: chosen.length,
+    ran,
+    caught,
+    survived: survivors.length,
+    score: ran ? Number(((caught / ran) * 100).toFixed(1)) : null,
+    seed: args.seed,
+    survivors: survivors.map((s) => ({ file: s.file, line: s.line, op: s.op, code: s.before.trim().slice(0, 120) })),
+  };
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    return 0;
+  }
+
+  process.stdout.write(`\nmutation probe — REPORT ONLY, never a gate\n`);
+  process.stdout.write(`  ${report.caught} caught / ${report.ran} run (${report.score === null ? 'n/a' : report.score + '%'}), from ${report.candidates} candidates, seed ${report.seed}\n`);
+  if (survivors.length) {
+    process.stdout.write(`\n  survivors — the suite ran this line and no assertion constrained it:\n`);
+    for (const s of report.survivors) process.stdout.write(`    ${s.file}:${s.line}  ${s.op}\n      ${s.code}\n`);
+    process.stdout.write('\n  Each is a question, not a verdict: some are equivalent mutants or defensive\n  branches where no assertion is owed. Pin the ones that describe real behaviour.\n');
+  } else {
+    process.stdout.write('\n  no survivors in this sample\n');
+  }
+  return 0;
+}
+
+module.exports = { mutationsFor, applyMutation, mutableLine, sample, OPERATORS, TARGETS };
+
+if (require.main === module) {
+  try {
+    process.exit(main());
+  } catch (e) {
+    process.stderr.write(`mutation probe failed: ${e.message}\n`);
+    process.exit(1);
+  }
+}

package/scripts/release-check.js

@@ -3,7 +3,7 @@
  * release-check.js — Pre-publish validation gate.
  *
  * Wired into `prepublishOnly` so `npm publish` fails BEFORE upload if any
- * gate is red. Runs eight checks in order; first failure aborts.
+ * gate is red. Runs nine checks in order; first failure aborts.
  *
  *   1. build:hooks      — hook scripts copy/build cleanly
  *   2. test:all         — full test suite (unit + scenario) passes
@@ -11,9 +11,13 @@
  *                         (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. links validate   — doc↔code link graph resolves (no broken references)
- *   6. npm pack dry-run — package builds; size is sane
+ *   6. npm pack dry-run — package builds; size is sane; zero runtime dependencies
  *   7. smoke install    — npm pack + install into temp dir + run pan-tools list
  *                         catches "ships but doesn't actually work" failures
+ *   8. bundles          — both plugin builders build; dist/pan-agent-plugin is fresh
+ *   9. coverage gate    — the suite under Node's coverage: every dispatcher arm
+ *                         executed, line/function floors per module group
+ *                         (scripts/coverage-gate.cjs; skipped on Node < 22)
  *
  * Usage:
  *   node scripts/release-check.js              # all gates
@@ -57,7 +61,7 @@ function run(cmd, args, opts = {}) {
 }
 
 // Gate 1: build:hooks
-process.stderr.write('\n[release-check] Gate 1/8: build:hooks\n');
+process.stderr.write('\n[release-check] Gate 1/9: build:hooks\n');
 {
   const r = run('npm', ['run', 'build:hooks']);
   logGate('build:hooks', r.status === 0, r.status !== 0 ? `exit ${r.status}` : '');
@@ -65,7 +69,7 @@ process.stderr.write('\n[release-check] Gate 1/8: build:hooks\n');
 }
 
 // Gate 2: test:all
-process.stderr.write('\n[release-check] Gate 2/8: test:all\n');
+process.stderr.write('\n[release-check] Gate 2/9: test:all\n');
 {
   const r = run('npm', ['run', 'test:all']);
   logGate('test:all', r.status === 0, r.status !== 0 ? `exit ${r.status}` : '');
@@ -74,9 +78,9 @@ process.stderr.write('\n[release-check] Gate 2/8: test:all\n');
 
 // Gate 3: npm audit (production deps only)
 if (SKIP_AUDIT) {
-  process.stderr.write('\n[release-check] Gate 3/8: npm audit (SKIPPED)\n');
+  process.stderr.write('\n[release-check] Gate 3/9: npm audit (SKIPPED)\n');
 } else {
-  process.stderr.write('\n[release-check] Gate 3/8: npm audit --omit=dev\n');
+  process.stderr.write('\n[release-check] Gate 3/9: 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;
@@ -88,7 +92,7 @@ if (SKIP_AUDIT) {
 }
 
 // Gate 4: doc-lint counts on user-facing docs (count-SSoT enforcement)
-process.stderr.write('\n[release-check] Gate 4/8: doc-lint counts docs/\n');
+process.stderr.write('\n[release-check] Gate 4/9: 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');
@@ -103,7 +107,7 @@ process.stderr.write('\n[release-check] Gate 4/8: 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/8: links validate\n');
+process.stderr.write('\n[release-check] Gate 5/9: 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 });
@@ -125,7 +129,7 @@ process.stderr.write('\n[release-check] Gate 5/8: links validate\n');
 
 // Gate 6: npm pack — produces a non-empty, sanely-sized tarball (read the file,
 // never parse stdout)
-process.stderr.write('\n[release-check] Gate 6/8: npm pack (size sanity)\n');
+process.stderr.write('\n[release-check] Gate 6/9: npm pack (size sanity)\n');
 {
   const tmp6 = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-release-pack-'));
   const r = run('npm', ['pack', '--pack-destination', tmp6], { capture: true });
@@ -149,9 +153,9 @@ process.stderr.write('\n[release-check] Gate 6/8: npm pack (size sanity)\n');
 
 // Gate 7: smoke install — pack and install into temp dir, run pan-tools
 if (SKIP_SMOKE) {
-  process.stderr.write('\n[release-check] Gate 7/8: smoke install (SKIPPED)\n');
+  process.stderr.write('\n[release-check] Gate 7/9: smoke install (SKIPPED)\n');
 } else {
-  process.stderr.write('\n[release-check] Gate 7/8: smoke install (npm pack + install + sanity)\n');
+  process.stderr.write('\n[release-check] Gate 7/9: smoke install (npm pack + install + sanity)\n');
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-release-smoke-'));
   try {
     // Pack — read the .tgz npm writes to tmpDir; never parse its stdout (see note).
@@ -201,7 +205,7 @@ if (SKIP_SMOKE) {
 // temp dirs (never dist/) so the gate cannot race a concurrently running test and
 // leaves the checkout untouched. A bundle that fails to build is a release that
 // ships a broken marketplace entry.
-process.stderr.write('\n[release-check] Gate 8/8: distribution bundles (build:plugin + build:agent-plugin)\n');
+process.stderr.write('\n[release-check] Gate 8/9: distribution bundles (build:plugin + build:agent-plugin)\n');
 {
   const tmp8 = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-release-bundles-'));
   try {
@@ -238,6 +242,23 @@ process.stderr.write('\n[release-check] Gate 8/8: distribution bundles (build:pl
   }
 }
 
+// Gate 9: coverage gate — the whole suite once more, under Node's own coverage
+// instrumentation, then: every dispatcher case arm executed (or allowlisted with a
+// reason in tests/fixtures/coverage-policy.json) and line/function floors per module
+// group. Gate 2 says the tests pass; this gate says the shipped code ran. On Node
+// below 22 the script reports "skipped" and exits 0 — the CI Node-22 job carries it.
+process.stderr.write('\n[release-check] Gate 9/9: coverage gate (dispatcher arms + coverage floors)\n');
+{
+  const r = run('node', [path.join(REPO_ROOT, 'scripts', 'coverage-gate.cjs')], { capture: true });
+  const text = ((r.stdout || '') + (r.stderr || '')).trim();
+  const first = text.split('\n')[0] || '';
+  logGate('coverage gate', r.status === 0, first.replace(/^coverage gate — /, ''));
+  if (r.status !== 0) {
+    process.stderr.write(text + '\n');
+    process.exit(1);
+  }
+}
+
 // Summary
 process.stderr.write('\n[release-check] Summary:\n');
 for (const c of checks) {

package/scripts/test-quality-lint.cjs

@@ -0,0 +1,240 @@
+'use strict';
+/**
+ * test-quality-lint.cjs — the assertion shapes that proved vacuous, as lint rules.
+ *
+ * Each rule came from a test that passed while the feature it named was broken
+ * (audit of 2026-09-17, spec docs/specs/testing-system-redesign-2026-09.md §3.1):
+ *   Q1  an OR-shaped liveness assert — `assert.ok(a.length > 0 || b.length > 0)` is
+ *       satisfied by a crash with a stack trace;
+ *   Q2  an in-process call to a lib module's `cmd*` function — they end in output()/
+ *       error(), which exit the process, so the test child dies and node --test
+ *       reports the file as one passing test;
+ *   Q3  `assert.ok(true)` / `assert(true)`;
+ *   Q4  a runPanTools result asserted only by `.output.length`;
+ *   Q5  a platform conditional that bare-`return`s (counted as a pass) instead of
+ *       `t.skip(reason)`;
+ *   Q6  a wall-clock upper bound under two seconds on a spawned process;
+ *   Q7  a read of the developer's real HOME / USERPROFILE / os.homedir();
+ *   Q8  a committed `test.todo` (scaffold stubs must be filled before commit);
+ *   Q9  an OR of bare property reads inside assert.ok — `assert.ok(a.x || a.y)` asks only
+ *       whether one of them exists, which an empty object, the wrong field, or a payload
+ *       that means failure all satisfy. Q1 covers the result-status fields; this covers
+ *       the same vacuity for arbitrary ones.
+ *
+ * `lintTestSource(src, file)` is pure; tests/test-quality.test.cjs applies it to the
+ * suite with tests/fixtures/test-quality-allowlist.json (entries { file, rule,
+ * count, reason } — allowed occurrences per file and rule; an entry that allows more
+ * than the file has is stale and fails too).
+ */
+
+function stripComments(line) {
+  // Good enough for test sources: drop a trailing // comment that is not inside
+  // quotes, and ignore the body lines of a /** … */ block comment.
+  if (/^\s*(\*|\/\*)/.test(line)) return '';
+  let inS = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (inS) { if (c === '\\') i++; else if (c === inS) inS = null; continue; }
+    if (c === '\'' || c === '"' || c === '`') inS = c;
+    else if (c === '/' && line[i + 1] === '/') return line.slice(0, i);
+  }
+  return line;
+}
+
+/** Join an assert statement that spans lines until its parentheses balance (max 8 lines). */
+function statementAt(lines, i) {
+  let text = lines[i];
+  let depth = 0;
+  for (let j = i; j < Math.min(lines.length, i + 8); j++) {
+    const t = stripComments(lines[j]);
+    if (j > i) text += ' ' + t.trim();
+    for (const c of t) { if (c === '(') depth++; else if (c === ')') depth--; }
+    if (depth <= 0 && j > i) break;
+    if (depth <= 0 && j === i && /\)\s*;?\s*$/.test(t)) break;
+  }
+  return text;
+}
+
+const TIME_WORDS = /\b(ms|elapsed|duration|took|Date\.now|hrtime|performance\.now|timing)\b/;
+
+// The result-status fields whose bare truthiness a liveness assert ORs together:
+// `result.output || result.error`, `!r.success || r.error`, `parsed.error || parsed.state`.
+// A crash satisfies every one of them — stderr is non-empty. An OR between two
+// content checks (`x.includes('a') || x.includes('b')`) is a legitimate either-format
+// assert and is not this rule's business.
+const STATUS_FIELD = /^!?\(?\s*[\w$.]*\b(success|error|output|stderr|stdout|reason|state|status)\b\s*\)?$/;
+const LENGTH_LIVENESS = /^!?\(?\s*[\w$.]*\.(?:output|error|stderr|stdout)\.length\s*>\s*0\s*\)?$/;
+
+function isLivenessOr(inner) {
+  const operands = inner.split(/\|\|/).map((s) => s.trim());
+  if (operands.length < 2) return false;
+  const bare = operands.filter((o) => STATUS_FIELD.test(o) || LENGTH_LIVENESS.test(o));
+  return bare.length >= 2;
+}
+
+const RULES = [
+  {
+    id: 'Q1',
+    title: 'OR-shaped liveness assert',
+    fix: 'assert the exit code and parse the JSON payload (or assert each branch on its own)',
+    detect(lines) {
+      const out = [];
+      lines.forEach((raw, i) => {
+        const line = stripComments(raw);
+        if (!/\bassert(?:\.ok)?\s*\(/.test(line)) return;
+        const stmt = statementAt(lines, i);
+        // The asserted expression: everything before the message argument.
+        let inner = stmt.slice(stmt.indexOf('(') + 1).replace(/\)\s*;?\s*$/, '');
+        const msg = inner.search(/,\s*(['"`])/);
+        if (msg >= 0) inner = inner.slice(0, msg);
+        if (isLivenessOr(inner)) out.push({ line: i + 1, text: raw.trim() });
+      });
+      return out;
+    },
+  },
+  {
+    id: 'Q2',
+    title: 'in-process call to a lib cmd* function',
+    fix: 'go through runPanTools (or the module’s pure functions) — cmd* functions end in output()/error(), which exit the process',
+    detect(lines) {
+      const out = [];
+      lines.forEach((raw, i) => {
+        const line = stripComments(raw);
+        if (/\bcmd[A-Z][A-Za-z0-9]*\s*\(/.test(line) && !/^\s*(const|let|var)\s+\{/.test(line)) out.push({ line: i + 1, text: raw.trim() });
+      });
+      return out;
+    },
+  },
+  {
+    id: 'Q3',
+    title: 'assert(true)',
+    fix: 'assert a specific value',
+    detect(lines) {
+      const out = [];
+      lines.forEach((raw, i) => { if (/\bassert(?:\.ok)?\(\s*true\s*[,)]/.test(stripComments(raw))) out.push({ line: i + 1, text: raw.trim() }); });
+      return out;
+    },
+  },
+  {
+    id: 'Q4',
+    title: 'CLI output asserted only by its length',
+    fix: 'parse the JSON payload and assert its fields; assert success/exit code',
+    detect(lines) {
+      const out = [];
+      lines.forEach((raw, i) => { if (/assert\.ok\(\s*[A-Za-z_$][\w$.]*\.output\.length\s*[><!=]/.test(stripComments(raw))) out.push({ line: i + 1, text: raw.trim() }); });
+      return out;
+    },
+  },
+  {
+    id: 'Q5',
+    title: 'platform conditional that bare-returns',
+    fix: 'use t.skip(reason) so the skip is reported, never counted as a pass',
+    detect(lines) {
+      const out = [];
+      lines.forEach((raw, i) => {
+        const line = stripComments(raw);
+        if (!/process\.platform/.test(line) || !/\bif\s*\(/.test(line)) return;
+        const window = [line, lines[i + 1] || '', lines[i + 2] || ''].map(stripComments).join(' ');
+        if (/\bskip\s*\(/.test(window) || /\btodo\s*\(/.test(window)) return;
+        if (/\)\s*\{?\s*return\b/.test(line) || /^\s*return\s*;?\s*\}?\s*$/.test(stripComments(lines[i + 1] || ''))) out.push({ line: i + 1, text: raw.trim() });
+      });
+      return out;
+    },
+  },
+  {
+    id: 'Q6',
+    title: 'wall-clock upper bound under two seconds',
+    fix: 'assert the behaviour, not the speed; if timing is the contract, bound it generously and allowlist with the reason',
+    detect(lines) {
+      const out = [];
+      lines.forEach((raw, i) => {
+        const line = stripComments(raw);
+        if (!/\bassert(?:\.ok)?\s*\(/.test(line) || !TIME_WORDS.test(line)) return;
+        const m = /<\s*=?\s*(\d{2,4})\b/.exec(line);
+        if (m && Number(m[1]) < 2000) out.push({ line: i + 1, text: raw.trim() });
+      });
+      return out;
+    },
+  },
+  {
+    id: 'Q7',
+    title: 'read of the real HOME',
+    fix: 'sandbox with withFakeHome() from tests/helpers.cjs, or pass an explicit config dir',
+    detect(lines) {
+      const out = [];
+      lines.forEach((raw, i) => {
+        const line = stripComments(raw);
+        if (/os\.homedir\(\)|process\.env\.(?:HOME|USERPROFILE)\b(?!\s*=[^=])/.test(line)) out.push({ line: i + 1, text: raw.trim() });
+      });
+      return out;
+    },
+  },
+  {
+    id: 'Q8',
+    title: 'committed todo',
+    fix: 'fill the stub or delete it; todo stubs are scaffold output, not tests',
+    detect(lines) {
+      const out = [];
+      lines.forEach((raw, i) => { if (/\b(?:test|it|describe)\.todo\s*\(|\{\s*todo\s*:/.test(stripComments(raw))) out.push({ line: i + 1, text: raw.trim() }); });
+      return out;
+    },
+  },
+  {
+    id: 'Q9',
+    title: 'OR of bare property reads in assert.ok',
+    fix: 'assert the specific field and its expected value, not that one of several exists',
+    detect(lines) {
+      const out = [];
+      lines.forEach((raw, i) => {
+        const line = stripComments(raw);
+        const m = line.match(/assert\.ok\(\s*([^;]*?)\s*(?:,\s*['"`][^;]*)?\)\s*;/);
+        if (!m || !m[1].includes('||')) return;
+        const expr = m[1];
+        // A comparison, a call, a negation or a length check is making a claim about a
+        // value; only a bare existence test is vacuous in this way.
+        if (/[=<>]|\(|\)|!|\.length|typeof|Array\.isArray/.test(expr)) return;
+        const operands = expr.split('||').map((s) => s.trim());
+        if (operands.length < 2) return;
+        if (!operands.every((o) => /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)+$/.test(o))) return;
+        out.push({ line: i + 1, text: raw.trim() });
+      });
+      return out;
+    },
+  },
+];
+
+/** Findings for one test source: [{ rule, title, fix, line, text }]. */
+function lintTestSource(src, file = '') {
+  const lines = src.split(/\r?\n/);
+  const findings = [];
+  for (const rule of RULES) {
+    for (const f of rule.detect(lines)) findings.push({ rule: rule.id, title: rule.title, fix: rule.fix, file, line: f.line, text: f.text });
+  }
+  return findings;
+}
+
+/**
+ * Apply an allowlist ([{ file, rule, count, reason }]) to findings.
+ * Returns { remaining, stale } — stale entries allow more than the file has, or
+ * carry no reason. Both fail the suite: an allowlist is a debt register, not a bin.
+ */
+function applyAllowlist(findings, allowlist) {
+  const remaining = [];
+  const stale = [];
+  const byKey = new Map();
+  for (const f of findings) { const k = `${f.file}|${f.rule}`; byKey.set(k, (byKey.get(k) || []).concat(f)); }
+  const seen = new Set();
+  for (const entry of allowlist || []) {
+    const k = `${entry.file}|${entry.rule}`;
+    seen.add(k);
+    const have = (byKey.get(k) || []).length;
+    if (!entry.reason || !String(entry.reason).trim()) stale.push({ ...entry, why: 'no reason given' });
+    else if (have === 0) stale.push({ ...entry, why: 'file has no such finding any more — remove the entry' });
+    else if (have < (entry.count || 0)) stale.push({ ...entry, why: `allows ${entry.count} but the file has ${have} — lower the count` });
+    else if (have > (entry.count || 0)) remaining.push(...(byKey.get(k) || []).slice(entry.count || 0));
+  }
+  for (const [k, list] of byKey) if (!seen.has(k)) remaining.push(...list);
+  return { remaining, stale };
+}
+
+module.exports = { RULES, lintTestSource, applyAllowlist, stripComments };