pan-wizard 3.35.0 → 3.37.0

package/scripts/local-schedule.cjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * local-schedule.cjs — the weekly checks GitHub used to run on a schedule, run by this
+ * machine's Windows Task Scheduler instead (local-first plan, phase 2).
+ *
+ *   codescan      Sunday 03:00   a whole-tree code scan through local-ci.cjs: the CodeQL CLI
+ *                                (security-extended) when installed, else Semgrep in Docker
+ *   outdated      Monday 09:00   `npm outdated`, in place of Dependabot's pull requests
+ *   market-watch  Monday 09:10   harness/autopilot/market-watch.cjs (the WATCH triggers)
+ *
+ * Usage:
+ *   node scripts/local-schedule.cjs --install [--root <checkout>] [--node <node.exe>]
+ *   node scripts/local-schedule.cjs --uninstall          removes exactly the tasks --install adds
+ *   node scripts/local-schedule.cjs --list               the tasks, their last result, the latest reports
+ *   node scripts/local-schedule.cjs --run <job>          what a task runs; also by hand
+ *
+ * Tasks are registered for the current user (schtasks, no admin) from an XML definition, so
+ * a run missed while the machine was off starts when it is next on. Each task runs this
+ * script with `--run <job>` in the checkout given by --root, by default the repository's
+ * main worktree (a linked worktree is deleted when its branch lands). Reports go to
+ * <checkout>/.ci-local/scheduled/<job>/ (gitignored): a <stamp>.md summary, a <stamp>.log,
+ * and last-run.json, which harness/autopilot/state-of-pan.cjs links. Off Windows, --install
+ * prints the equivalent crontab lines instead. Requiring this file runs nothing.
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SCRIPT_ROOT = path.resolve(__dirname, '..');
+const TASK_PREFIX = 'PanWizard-';
+const DAYS = { SUN: 'Sunday', MON: 'Monday', TUE: 'Tuesday', WED: 'Wednesday', THU: 'Thursday', FRI: 'Friday', SAT: 'Saturday' };
+const CRON_DAY = { SUN: 0, MON: 1, TUE: 2, WED: 3, THU: 4, FRI: 5, SAT: 6 };
+
+const JOBS = [
+  { id: 'codescan', day: 'SUN', time: '03:00', description: 'PAN Wizard: weekly whole-tree code scan (CodeQL CLI, else Semgrep in Docker)' },
+  { id: 'outdated', day: 'MON', time: '09:00', description: 'PAN Wizard: weekly npm outdated report (in place of Dependabot)' },
+  { id: 'market-watch', day: 'MON', time: '09:10', description: 'PAN Wizard: weekly market watcher (harness/autopilot/market-watch.cjs)' },
+];
+
+const taskName = (job) => `${TASK_PREFIX}${job.id}`;
+
+function xmlEscape(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+// The first `day` on or after `from`, at `time`, as a local timestamp without a zone (what
+// Task Scheduler's StartBoundary takes).
+function startBoundary(day, time, from = new Date()) {
+  const d = new Date(from.getFullYear(), from.getMonth(), from.getDate());
+  while (d.getDay() !== CRON_DAY[day]) d.setDate(d.getDate() + 1);
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${time}:00`;
+}
+
+/** The Task Scheduler definition for one job. Pure. */
+function taskXml(job, { root, node, from }) {
+  // A Task Scheduler definition is a Windows path whichever host builds it.
+  const script = path.win32.join(root, 'scripts', 'local-schedule.cjs');
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>${xmlEscape(job.description)}</Description>
+    <Author>PAN Wizard scripts/local-schedule.cjs</Author>
+  </RegistrationInfo>
+  <Triggers>
+    <CalendarTrigger>
+      <StartBoundary>${startBoundary(job.day, job.time, from)}</StartBoundary>
+      <Enabled>true</Enabled>
+      <ScheduleByWeek>
+        <DaysOfWeek><${DAYS[job.day]} /></DaysOfWeek>
+        <WeeksInterval>1</WeeksInterval>
+      </ScheduleByWeek>
+    </CalendarTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <ExecutionTimeLimit>PT4H</ExecutionTimeLimit>
+    <Enabled>true</Enabled>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${xmlEscape(node)}</Command>
+      <Arguments>${xmlEscape(`"${script}" --run ${job.id}`)}</Arguments>
+      <WorkingDirectory>${xmlEscape(root)}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+
+/** The schtasks calls --install makes, one per job, each with the XML it registers. Pure. */
+function installPlan({ root, node, from }) {
+  return JOBS.map((job) => ({ name: taskName(job), xml: taskXml(job, { root, node, from }), args: ['/Create', '/TN', taskName(job), '/XML', '<xml file>', '/F'] }));
+}
+
+/** The schtasks calls --uninstall makes: a delete for every task --install creates. Pure. */
+function uninstallPlan() {
+  return JOBS.map((job) => ({ name: taskName(job), args: ['/Delete', '/TN', taskName(job), '/F'] }));
+}
+
+function cronLines({ root, node }) {
+  return JOBS.map((job) => {
+    const [h, m] = job.time.split(':').map(Number);
+    return `${m} ${h} * * ${CRON_DAY[job.day]} cd '${root}' && '${node}' scripts/local-schedule.cjs --run ${job.id}`;
+  });
+}
+
+const schtasks = (args) => spawnSync('schtasks', args, { encoding: 'utf8', windowsHide: true });
+
+// The repository's main worktree: the first entry `git worktree list` prints.
+function mainWorktree(cwd) {
+  const r = spawnSync('git', ['worktree', 'list', '--porcelain'], { cwd, encoding: 'utf8' });
+  const m = r.status === 0 && r.stdout.match(/^worktree (.+)$/m);
+  return m ? path.resolve(m[1].trim()) : cwd;
+}
+
+function reportDir(root, job) {
+  return path.join(root, '.ci-local', 'scheduled', job);
+}
+
+/** The latest run of each job in `root`, from its last-run.json: { job: {status, at, report} }. */
+function latestReports(root) {
+  const out = {};
+  for (const job of JOBS) {
+    try { out[job.id] = JSON.parse(fs.readFileSync(path.join(reportDir(root, job.id), 'last-run.json'), 'utf8')); } catch { /* never ran */ }
+  }
+  return out;
+}
+
+function stamp(d = new Date()) {
+  return d.toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15);
+}
+
+function runCapture(cmd, args, opts) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', windowsHide: true, maxBuffer: 256 * 1024 * 1024, timeout: 4 * 60 * 60 * 1000, ...opts });
+  return { status: r.error ? null : r.status, out: `${r.stdout || ''}${r.stderr || ''}${r.error ? `\n${r.error.message}\n` : ''}` };
+}
+
+// Each job returns { status: 'pass'|'fail'|'report', summary: markdown, log }.
+const RUNNERS = {
+  codescan(root) {
+    const out = path.join(reportDir(root, 'codescan'), 'ci-local');
+    const r = runCapture(process.execPath, [path.join(root, 'scripts', 'local-ci.cjs'), '--root', root, '--out', out, '--only', 'codescan', '--codescan-all'], { cwd: root });
+    let gate = null;
+    try { gate = JSON.parse(fs.readFileSync(path.join(out, 'report.json'), 'utf8')).gates.find((g) => g.id === 'codescan'); } catch { /* no report */ }
+    const status = r.status === 0 ? (gate && gate.status === 'skip' ? 'skip' : 'pass') : 'fail';
+    return { status, log: r.out, summary: `- ${gate ? `${gate.title}: ${gate.status.toUpperCase()}${gate.detail ? ` — ${gate.detail}` : ''}` : `local-ci exited ${r.status}`}\n- gate log: ${gate && gate.log ? path.join(out, 'logs', 'codescan.log') : '—'}\n` };
+  },
+  outdated(root) {
+    // npm outdated exits 1 when anything is outdated: that is the report, not a failure.
+    const r = runCapture('npm outdated --json --long', [], { cwd: root, shell: true });
+    let data = {};
+    try { data = JSON.parse(r.out.slice(r.out.indexOf('{'))); } catch { if (r.status !== 0 && r.status !== 1) return { status: 'fail', log: r.out, summary: `- npm outdated failed (exit ${r.status})\n` }; }
+    const names = Object.keys(data).sort();
+    const lines = names.length
+      ? ['| Package | Type | Current | Wanted | Latest |', '|---|---|---|---|---|', ...names.map((n) => { const p = data[n]; return `| ${n} | ${p.type || ''} | ${p.current || '—'} | ${p.wanted} | ${p.latest} |`; })]
+      : ['- every dependency is current'];
+    return { status: names.length ? 'report' : 'pass', log: r.out, summary: lines.join('\n') + '\n' };
+  },
+  'market-watch'(root) {
+    const r = runCapture(process.execPath, [path.join(root, 'harness', 'autopilot', 'market-watch.cjs')], { cwd: root });
+    return { status: r.status === 0 ? 'pass' : 'fail', log: r.out, summary: `- exit ${r.status}; fired triggers go to harness/autopilot/state/inbox.md\n\n\`\`\`\n${r.out.trim().split(/\r?\n/).slice(-20).join('\n')}\n\`\`\`\n` };
+  },
+};
+
+function runJob(id, root) {
+  const job = JOBS.find((j) => j.id === id);
+  if (!job) throw new Error(`unknown job ${id}; one of ${JOBS.map((j) => j.id).join(', ')}`);
+  const dir = reportDir(root, id);
+  fs.mkdirSync(dir, { recursive: true });
+  const at = new Date();
+  const s = stamp(at);
+  const r = RUNNERS[id](root);
+  const report = path.join(dir, `${s}.md`);
+  fs.writeFileSync(path.join(dir, `${s}.log`), r.log);
+  fs.writeFileSync(report, `# ${id} — ${at.toISOString()}\n\nStatus: **${r.status}**\n\n${r.summary}`);
+  const last = { job: id, status: r.status, at: at.toISOString(), report: path.relative(root, report).replace(/\\/g, '/') };
+  fs.writeFileSync(path.join(dir, 'last-run.json'), JSON.stringify(last, null, 2) + '\n');
+  return last;
+}
+
+function install({ root, node, exec = schtasks, from }) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-schedule-'));
+  const done = [];
+  try {
+    for (const step of installPlan({ root, node, from })) {
+      const file = path.join(tmp, `${step.name}.xml`);
+      // Task Scheduler reads its XML as UTF-16 with a byte-order mark.
+      fs.writeFileSync(file, Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(step.xml, 'utf16le')]));
+      const r = exec(step.args.map((a) => (a === '<xml file>' ? file : a)));
+      if (r.status !== 0) throw new Error(`schtasks ${step.args.slice(0, 3).join(' ')}: ${(r.stderr || r.stdout || '').trim()}`);
+      done.push(step.name);
+    }
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+  return done;
+}
+
+function uninstall({ exec = schtasks } = {}) {
+  const removed = [];
+  for (const step of uninstallPlan()) {
+    if (exec(['/Query', '/TN', step.name]).status !== 0) continue;
+    const r = exec(step.args);
+    if (r.status !== 0) throw new Error(`schtasks /Delete ${step.name}: ${(r.stderr || r.stdout || '').trim()}`);
+    removed.push(step.name);
+  }
+  return removed;
+}
+
+function list({ root, exec = schtasks }) {
+  const latest = latestReports(root);
+  const lines = [];
+  for (const job of JOBS) {
+    const q = exec(['/Query', '/TN', taskName(job), '/FO', 'LIST', '/V']);
+    const field = (k) => ((q.stdout || '').match(new RegExp(`^${k}:\\s*(.*)$`, 'm')) || [])[1] || '—';
+    // 267011 is SCHED_S_TASK_HAS_NOT_RUN; its Last Run Time is a 1999 placeholder.
+    const last = field('Last Result') === '267011' ? 'never run' : `${field('Last Run Time')} (result ${field('Last Result')})`;
+    lines.push(q.status === 0
+      ? `${taskName(job)}  ${DAYS[job.day]} ${job.time}  next: ${field('Next Run Time')}  last: ${last}`
+      : `${taskName(job)}  not installed`);
+    const l = latest[job.id];
+    lines.push(`  latest report: ${l ? `${l.at.slice(0, 16)} ${l.status} — ${l.report}` : 'none yet'}`);
+  }
+  return lines.join('\n');
+}
+
+function main(argv) {
+  const get = (k) => { const i = argv.indexOf(k); return i >= 0 ? argv[i + 1] : null; };
+  const root = path.resolve(get('--root') || mainWorktree(SCRIPT_ROOT));
+  const node = get('--node') || process.execPath;
+  if (argv.includes('--run')) {
+    const last = runJob(get('--run'), root);
+    console.log(`${last.job}: ${last.status} — ${last.report}`);
+    return last.status === 'fail' ? 1 : 0;
+  }
+  if (argv.includes('--list')) {
+    if (process.platform !== 'win32') { console.log(cronLines({ root, node }).join('\n')); return 0; }
+    console.log(list({ root }));
+    return 0;
+  }
+  if (argv.includes('--uninstall')) {
+    if (process.platform !== 'win32') { console.log('remove these lines with `crontab -e`:\n' + cronLines({ root, node }).join('\n')); return 0; }
+    const removed = uninstall();
+    console.log(removed.length ? `removed: ${removed.join(', ')}` : 'nothing to remove');
+    return 0;
+  }
+  if (argv.includes('--install')) {
+    if (/fnm_multishells/i.test(node)) { console.error(`local-schedule: ${node} is an fnm session shim that disappears with its shell; pass --node <a stable node.exe>`); return 2; }
+    if (!fs.existsSync(path.join(root, 'scripts', 'local-schedule.cjs'))) console.error(`local-schedule: warning — ${root} has no scripts/local-schedule.cjs yet (it lands with this branch); the tasks fail until it does`);
+    if (process.platform !== 'win32') { console.log('add these lines with `crontab -e`:\n' + cronLines({ root, node }).join('\n')); return 0; }
+    const done = install({ root, node });
+    console.log(`installed for ${os.userInfo().username}, running in ${root}: ${done.join(', ')}`);
+    console.log(list({ root }));
+    return 0;
+  }
+  console.error('usage: local-schedule.cjs --install [--root DIR] [--node PATH] | --uninstall | --list | --run <codescan|outdated|market-watch>');
+  return 2;
+}
+
+module.exports = { JOBS, TASK_PREFIX, taskName, taskXml, installPlan, uninstallPlan, cronLines, startBoundary, latestReports, reportDir, runJob, install, uninstall, list, main };
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));

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/prompt-lint.cjs

@@ -13,10 +13,16 @@
  *   pasted-source       an @-include of engine source (`*.cjs` / `*.js`) into a prompt
  *   oversized-question  an AskUserQuestion block offering more than four options (the
  *                       host's limit: two to four)
+ *   oversized-ask       an AskUserQuestion call asking more than four questions at once
+ *                       (the host's limit; program L6b, settings asked ten)
  *   untyped-spawn       a Task( spawn without `model=`, or a general-purpose spawn told
  *                       to read a role file instead of naming the agent type
  *   dev-skill           a shipped prompt sending the user to a dev-only skill of this
  *                       repository (.claude/commands/*.md), which no install carries
+ *   refused-write       a write instruction whose target file is named summary.md,
+ *                       report.md, findings.md or analysis.md: Claude Code refuses a
+ *                       subagent's Write to those names in any directory ("Subagents
+ *                       should return findings as text"; reproduced 2026-10-19, MI-127)
  *
  *   node scripts/prompt-lint.cjs            # report the current tree, exit 1 on a finding
  */
@@ -98,6 +104,20 @@ function lintText(rel, raw, ctx) {
     }
   }
 
+  // oversized-ask: more than four questions in one call.
+  const askCallRe = /AskUserQuestion\(\s*\[/g;
+  while ((m = askCallRe.exec(text))) {
+    let depth = 0;
+    let end = -1;
+    for (let i = m.index + m[0].length - 1; i < text.length; i++) {
+      if (text[i] === '[') depth++;
+      else if (text[i] === ']') { depth--; if (depth === 0) { end = i; break; } }
+    }
+    if (end < 0) continue;
+    const questions = (text.slice(m.index, end).match(/\bquestion\s*:/g) || []).length;
+    if (questions > 4) hit('oversized-ask', m.index, `${questions} questions in one call`);
+  }
+
   // oversized-question
   const askRe = /AskUserQuestion/g;
   while ((m = askRe.exec(text))) {
@@ -133,6 +153,18 @@ function lintText(rel, raw, ctx) {
     });
   }
 
+  // refused-write
+  // A line that writes, creates or outputs a path ending in a refused name. Reads of
+  // such a path (an older project's file, a template) are not flagged.
+  const REFUSED = /(?:^|[\s`'"(])((?:[\w.{}$~-]+\/)+(summary|report|findings|analysis)\.md)\b/i;
+  const WRITES = /\b(write|writes|written|writing|create|creates|save|saves)\b|\*\*output:?\*\*|\boutput:/i;
+  let offset = 0;
+  for (const l of text.split('\n')) {
+    const r = REFUSED.exec(l);
+    if (r && !/(?:^|\/)templates\//.test(r[1]) && WRITES.test(l)) hit('refused-write', offset, r[1]);
+    offset += l.length + 1;
+  }
+
   // dev-skill
   if (ctx.dev.length) {
     // Every regex metacharacter escaped, backslash included (inline: CodeQL does not follow a helper).

package/scripts/prompt-rules.cjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * The prompt-rule registry (program H6).
+ *
+ * A normative line in a shipped prompt (MUST, NEVER, SHALL, always, never, do not) is a
+ * rule. Each gets a stable id, `<file without .md>:<first 8 hex of sha1(text)>`, so it
+ * moves with its text and not its line number. The registry, tests/fixtures/prompt-rules.json,
+ * lists them. A harness scenario claims the rules it exercises with `covers: [ids]`.
+ *
+ *   --write   regenerate the registry. Rules already marked `baseline` keep the mark;
+ *             with --baseline every rule gets it (how the registry was first created).
+ *   --check   exit 1 when the registry is stale, when a rule that is neither baseline nor
+ *             claimed has no reason in tests/fixtures/prompt-rules-allowlist.json, or when
+ *             a scenario claims a rule that does not exist.
+ *   --list    print the rules (id, file, text) as JSON.
+ *
+ * `harness run --prompt-mutant <id>` deletes one rule's line from the packed package
+ * (applyMutant) and runs only the scenarios that cover it: a rule whose removal changes
+ * nothing is decorative.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const PROMPT_DIRS = ['agents', 'commands', 'pan-wizard-core/workflows', 'pan-wizard-core/references'];
+const REGISTRY = 'tests/fixtures/prompt-rules.json';
+const ALLOWLIST = 'tests/fixtures/prompt-rules-allowlist.json';
+const NORMATIVE_RE = /\b(MUST|NEVER|SHALL|must not|never|always|Always|Never|[Dd]o not|[Dd]on't)\b/;
+
+function normalise(line) {
+  return line.trim().replace(/^(?:[-*+]|\d+\.)\s+/, '').replace(/^>\s*/, '').replace(/\s+/g, ' ').trim();
+}
+
+function listFiles(root) {
+  const out = [];
+  const walk = (rel) => {
+    const abs = path.join(root, rel);
+    if (!fs.existsSync(abs)) return;
+    for (const e of fs.readdirSync(abs, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const r = `${rel}/${e.name}`;
+      if (e.isDirectory()) walk(r); else if (e.name.endsWith('.md')) out.push(r);
+    }
+  };
+  for (const d of PROMPT_DIRS) walk(d);
+  return out;
+}
+
+/** The rules of one file's text. */
+function rulesOf(file, text) {
+  const rules = [];
+  const seen = new Map();
+  let fence = null;
+  let frontmatter = false;
+  text.replace(/\r\n/g, '\n').split('\n').forEach((line, i) => {
+    if (i === 0 && line === '---') { frontmatter = true; return; }
+    if (frontmatter) { if (line === '---') frontmatter = false; return; }
+    const f = line.match(/^\s*(```+|~~~+)/);
+    if (f) { if (!fence) fence = f[1]; else if (line.trim().startsWith(fence)) fence = null; return; }
+    if (fence || !NORMATIVE_RE.test(line)) return;
+    const t = normalise(line);
+    if (t.length < 8 || /^\|/.test(t) || /^#/.test(t)) return;
+    const base = `${file.replace(/\.md$/, '')}:${crypto.createHash('sha1').update(t).digest('hex').slice(0, 8)}`;
+    const n = (seen.get(base) || 0) + 1;
+    seen.set(base, n);
+    rules.push({ id: n === 1 ? base : `${base}~${n}`, file, line: i + 1, text: t });
+  });
+  return rules;
+}
+
+function extractRules(root) {
+  return listFiles(root).flatMap((f) => rulesOf(f, fs.readFileSync(path.join(root, f), 'utf8')));
+}
+
+function readJson(p, fallback) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return fallback; }
+}
+
+function loadScenarios(root) {
+  const dir = path.join(root, 'harness', 'scenarios');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((n) => n.endsWith('.json')).sort().map((n) => readJson(path.join(dir, n), null)).filter(Boolean);
+}
+
+function coveringScenarios(scenarios, id) {
+  return scenarios.filter((s) => Array.isArray(s.covers) && s.covers.includes(id));
+}
+
+function writeRegistry(root, opts = {}) {
+  const prev = new Map((readJson(path.join(root, REGISTRY), { rules: [] }).rules || []).map((r) => [r.id, r]));
+  const rules = extractRules(root).map(({ id, file, text }) => ({ id, file, text, baseline: !!(opts.baseline || (prev.get(id) && prev.get(id).baseline)) }));
+  const p = path.join(root, REGISTRY);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify({ rules }, null, 1) + '\n');
+  return { rules: rules.length, baseline: rules.filter((r) => r.baseline).length };
+}
+
+function checkRegistry(root) {
+  const reg = readJson(path.join(root, REGISTRY), { rules: [] }).rules || [];
+  const now = extractRules(root);
+  const regIds = new Set(reg.map((r) => r.id));
+  const nowIds = new Set(now.map((r) => r.id));
+  const stale = reg.length !== now.length || now.some((r) => !regIds.has(r.id));
+  const scenarios = loadScenarios(root);
+  const claimed = new Set(scenarios.flatMap((s) => (Array.isArray(s.covers) ? s.covers : [])));
+  const allow = new Map((readJson(path.join(root, ALLOWLIST), []) || []).filter((e) => e && e.id && e.reason).map((e) => [e.id, e.reason]));
+  const unclaimed = reg.filter((r) => !r.baseline && !claimed.has(r.id) && !allow.has(r.id));
+  const dangling = [];
+  for (const s of scenarios) for (const id of (Array.isArray(s.covers) ? s.covers : [])) if (!nowIds.has(id)) dangling.push({ scenario: s.id, id });
+  return { rules: now.length, stale, unclaimed, dangling, claimed: [...claimed].filter((id) => nowIds.has(id)).length };
+}
+
+/** Delete the first line whose normalised text is the rule. Null when it is not there. */
+function generateMutant(content, ruleText) {
+  const eol = /\r\n/.test(content) ? '\r\n' : '\n';
+  const lines = content.split(/\r?\n/);
+  const i = lines.findIndex((l) => normalise(l) === ruleText);
+  if (i < 0) return null;
+  lines.splice(i, 1);
+  return { content: lines.join(eol), removed: i + 1 };
+}
+
+/** Apply rule `id`'s mutant to the extracted package at `packageDir`. */
+function applyMutant(root, packageDir, id) {
+  const rule = (readJson(path.join(root, REGISTRY), { rules: [] }).rules || []).find((r) => r.id === id) || extractRules(root).find((r) => r.id === id);
+  if (!rule) return { error: 'unknown_rule', reason: `no rule ${id} in ${REGISTRY}` };
+  const target = path.join(packageDir, rule.file);
+  let content;
+  try { content = fs.readFileSync(target, 'utf8'); } catch { return { error: 'file_not_in_package', reason: `${rule.file} is not in the package` }; }
+  const m = generateMutant(content, rule.text);
+  if (!m) return { error: 'rule_not_found', reason: `${rule.file} no longer holds the rule` };
+  fs.writeFileSync(target, m.content);
+  return { id, file: rule.file, line: m.removed, text: rule.text };
+}
+
+module.exports = { extractRules, rulesOf, writeRegistry, checkRegistry, generateMutant, applyMutant, coveringScenarios, normalise, REGISTRY, ALLOWLIST };
+
+if (require.main === module) {
+  const root = path.join(__dirname, '..');
+  const argv = process.argv.slice(2);
+  if (argv.includes('--write')) {
+    const r = writeRegistry(root, { baseline: argv.includes('--baseline') });
+    console.log(`wrote ${REGISTRY}: ${r.rules} rules, ${r.baseline} baseline`);
+  } else if (argv.includes('--list')) {
+    console.log(JSON.stringify(extractRules(root), null, 1));
+  } else {
+    const r = checkRegistry(root);
+    const problems = [];
+    if (r.stale) problems.push(`${REGISTRY} is stale: run node scripts/prompt-rules.cjs --write`);
+    for (const u of r.unclaimed) problems.push(`unclaimed rule ${u.id} (${u.file}): "${u.text.slice(0, 80)}" — add it to a scenario's covers, or to ${ALLOWLIST} with a reason`);
+    for (const d of r.dangling) problems.push(`scenario ${d.scenario} covers ${d.id}, which is no rule`);
+    if (problems.length) { console.log(problems.join('\n')); process.exit(1); }
+    console.log(`prompt-rule registry current: ${r.rules} rules, ${r.claimed} claimed by a scenario`);
+  }
+}

package/scripts/run-tests.cjs

@@ -46,6 +46,12 @@ if (files.length === 0) {
   process.exit(1);
 }
 
-const nodeArgs = watch ? ['--test', '--watch', ...files] : ['--test', ...files];
+// PAN_TEST_CONCURRENCY caps how many test files run at once (scripts/local-ci.cjs sets it).
+// Node's default is one per core but one: on a 40-core machine that is 39 files at a time,
+// and the suite's wall-clock checks were never meant for that. The flag needs Node 20.10+.
+const [major, minor] = process.versions.node.split('.').map(Number);
+const cap = Number(process.env.PAN_TEST_CONCURRENCY);
+const concurrency = cap > 0 && (major > 20 || (major === 20 && minor >= 10)) ? [`--test-concurrency=${cap}`] : [];
+const nodeArgs = watch ? ['--test', '--watch', ...concurrency, ...files] : ['--test', ...concurrency, ...files];
 const result = spawnSync(process.execPath, nodeArgs, { stdio: 'inherit' });
 process.exit(result.status ?? 1);

package/scripts/test-quality-lint.cjs

@@ -13,7 +13,7 @@
  *   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;
+ *   Q6  a wall-clock upper bound of two seconds or less 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
@@ -143,7 +143,7 @@ const RULES = [
   },
   {
     id: 'Q6',
-    title: 'wall-clock upper bound under two seconds',
+    title: 'wall-clock upper bound of two seconds or less',
     fix: 'assert the behaviour, not the speed; if timing is the contract, bound it generously and allowlist with the reason',
     detect(lines) {
       const out = [];
@@ -151,7 +151,7 @@ const RULES = [
         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() });
+        if (m && Number(m[1]) <= 2000) out.push({ line: i + 1, text: raw.trim() });
       });
       return out;
     },