pan-wizard 3.27.0 → 3.29.0

package/scripts/build-agent-plugin.js

@@ -0,0 +1,220 @@
+/**
+ * Build the PAN Wizard **Agent Plugins 1.0** bundle (ADR-0045) — the vendor-
+ * neutral package that Copilot CLI / VS Code, Codex, Cursor and Kiro load
+ * natively. Emits a self-contained directory at dist/pan-agent-plugin/:
+ *
+ *   plugin.json                   closed-schema manifest ($schema + name + metadata)
+ *   skills/pan-<name>/SKILL.md    every PAN command as an Agent Skill, from the
+ *                                 ONE unified-skills compiler (ADR-0028)
+ *   mcp.json                      the bundled bridge, launched as
+ *                                 `node ${PLUGIN_ROOT}/pan-wizard-core/mcp/server.cjs`
+ *   pan-wizard-core/              dispatcher + modules + workflows + templates +
+ *                                 references + learnings (internal stripped) +
+ *                                 canonical agent reference copies under agents/
+ *
+ *   hooks/pan-*.js                PAN's hook scripts (pure Node), shared by every vendor
+ *   hooks/hooks.json              Codex: default plugin hooks location; matcher-group
+ *                                 shape with `${PLUGIN_ROOT}` paths and `async` observers
+ *                                 (developers.openai.com/plugins/build/plugins, 2026-09-10)
+ *   com.github.copilot/           Copilot's reverse-domain namespace (ADR-0045 D5):
+ *     agents/pan-*.agent.md         agents in Copilot's format
+ *     hooks/hooks.json              flat PascalCase format, `${CLAUDE_PLUGIN_ROOT}` paths
+ *                                   (VS-Code-verified; Copilot CLI live install is the gate)
+ *
+ * NOT emitted: Codex agents (no plugin agent component is documented) and any
+ * Antigravity variant (its manifest schema is closed and different — a separate
+ * layout, deferred until its file shapes are read from a primary source).
+ *
+ * Paths inside skill and core markdown use PAN's `{{PAN_PLUGIN_ROOT}}` token,
+ * defined for the model by the adapter note in every skill; `${PLUGIN_ROOT}`
+ * (the client-expanded variable) appears only in mcp.json, the one place the
+ * spec expands it.
+ *
+ * Usage: node scripts/build-agent-plugin.js   (or npm run build:agent-plugin)
+ * PAN_AGENT_PLUGIN_OUT=<dir> overrides the output directory (tests build into
+ * private temp dirs so parallel test files never race on dist/).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const OUT = process.env.PAN_AGENT_PLUGIN_OUT
+  ? path.resolve(process.env.PAN_AGENT_PLUGIN_OUT)
+  : path.join(ROOT, 'dist', 'pan-agent-plugin');
+const pkg = require(path.join(ROOT, 'package.json'));
+const lib = require(path.join(ROOT, 'bin', 'install-lib.cjs'));
+
+const TOKEN_PREFIX = `${lib.AGENT_PLUGIN_ROOT_TOKEN}/`;
+const REWRITE = {
+  // Core and agent references → inside the bundle.
+  corePrefix: TOKEN_PREFIX,
+  // Residual `~/.claude/…` → the consuming runtime's USER config dir; residual
+  // `./.claude/…` → its PROJECT dir. Neither is known at build time, so both are
+  // tokens the adapter note defines (install-lib AGENT_PLUGIN_RUNTIME_*_TOKEN).
+  pathPrefix: `${lib.AGENT_PLUGIN_RUNTIME_HOME_TOKEN}/`,
+  projectDirPrefix: `${lib.AGENT_PLUGIN_RUNTIME_DIR_TOKEN}/`,
+  attribution: undefined, // keep the documents' default attribution — no runtime to consult
+};
+
+/**
+ * Refuse to wipe a directory that is not a previous bundle build (same rule as
+ * build-plugin.js). Empty or absent directories, and our own previous output —
+ * recognised by a manifest carrying the Agent Plugins schema — are fair game.
+ */
+function assertSafeToReplace(dir) {
+  if (!fs.existsSync(dir)) return;
+  if (fs.readdirSync(dir).length === 0) return;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'plugin.json'), 'utf8'));
+    if (manifest && manifest.$schema === lib.AGENT_PLUGIN_MANIFEST_SCHEMA) return;
+  } catch { /* fall through to refusal */ }
+  throw new Error(`build-agent-plugin: refusing to replace ${dir} — it is non-empty and does not look like a previous bundle build (no Agent Plugins plugin.json)`);
+}
+
+/** commands/pan/**.md → skills/pan-<name>/SKILL.md, mirroring the installer's recursion. */
+function emitSkills(srcDir, skillsDir, prefix) {
+  let count = 0;
+  (function recurse(currentSrc, currentPrefix) {
+    for (const entry of fs.readdirSync(currentSrc, { withFileTypes: true })) {
+      const srcPath = path.join(currentSrc, entry.name);
+      if (entry.isDirectory()) { recurse(srcPath, `${currentPrefix}-${entry.name}`); continue; }
+      if (!entry.name.endsWith('.md')) continue;
+      const skillName = `${currentPrefix}-${entry.name.replace(/\.md$/, '')}`;
+      const skillDir = path.join(skillsDir, skillName);
+      fs.mkdirSync(skillDir, { recursive: true });
+      let content = fs.readFileSync(srcPath, 'utf8');
+      content = lib.rewriteUnifiedSkillCommandContent(content, REWRITE);
+      content = lib.convertClaudeCommandToUnifiedSkill(content, skillName, { adapterNote: lib.agentPluginSkillAdapterNote() });
+      fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content);
+      count++;
+    }
+  })(srcDir, prefix);
+  return count;
+}
+
+/** pan-wizard-core → bundle, markdown rewritten, everything else verbatim. */
+function emitCore(srcDir, destDir) {
+  (function recurse(currentSrc, currentDest) {
+    fs.mkdirSync(currentDest, { recursive: true });
+    for (const entry of fs.readdirSync(currentSrc, { withFileTypes: true })) {
+      const srcPath = path.join(currentSrc, entry.name);
+      const destPath = path.join(currentDest, entry.name);
+      if (entry.isDirectory()) recurse(srcPath, destPath);
+      else if (entry.name.endsWith('.md')) fs.writeFileSync(destPath, lib.rewriteSharedCoreMarkdown(fs.readFileSync(srcPath, 'utf8'), REWRITE));
+      else fs.copyFileSync(srcPath, destPath);
+    }
+  })(srcDir, destDir);
+
+  // learnings/internal is source-only — strip the files AND the index entries,
+  // exactly as the installer and the Claude plugin builder do.
+  fs.rmSync(path.join(destDir, 'learnings', 'internal'), { recursive: true, force: true });
+  const indexPath = path.join(destDir, 'learnings', 'index.json');
+  try {
+    const stripped = lib.stripInternalLearningsTopics(JSON.parse(fs.readFileSync(indexPath, 'utf8')));
+    if (stripped) fs.writeFileSync(indexPath, JSON.stringify(stripped, null, 2) + '\n');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  fs.writeFileSync(path.join(destDir, 'VERSION'), pkg.version);
+}
+
+/** Canonical agent reference copies under <core>/agents/ (ADR-0028). */
+function emitAgentReferenceCopies(agentsSrc, agentsRefDir) {
+  fs.mkdirSync(agentsRefDir, { recursive: true });
+  let count = 0;
+  for (const f of fs.readdirSync(agentsSrc).filter(n => n.endsWith('.md'))) {
+    fs.writeFileSync(path.join(agentsRefDir, f), lib.rewriteAgentReferenceCopy(fs.readFileSync(path.join(agentsSrc, f), 'utf8'), TOKEN_PREFIX));
+    count++;
+  }
+  return count;
+}
+
+/** Hook scripts: the built copies from hooks/dist when present, else the pure-Node sources. */
+function emitHookScripts(destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const dist = path.join(ROOT, 'hooks', 'dist');
+  const src = fs.existsSync(dist) ? dist : path.join(ROOT, 'hooks');
+  const names = fs.readdirSync(src).filter(n => /^pan-[a-z-]+\.js$/.test(n)).sort();
+  for (const n of names) fs.copyFileSync(path.join(src, n), path.join(destDir, n));
+  return names;
+}
+
+/** The four hook commands, anchored at the plugin root through whichever variable the consumer expands. */
+function hookCommands(rootVar) {
+  const cmd = (script) => `node ${rootVar}/hooks/${script}`;
+  return {
+    updateCheckCommand: cmd('pan-check-update.js'),
+    contextMonitorCommand: cmd('pan-context-monitor.js'),
+    costLoggerCommand: cmd('pan-cost-logger.js'),
+    traceLoggerCommand: cmd('pan-trace-logger.js'),
+  };
+}
+
+/** Copilot vendor directory: agents in Copilot's `.agent.md` format + plugin hooks. */
+function emitCopilotNamespace(agentsSrc, nsDir) {
+  const agentsDest = path.join(nsDir, 'agents');
+  fs.mkdirSync(agentsDest, { recursive: true });
+  let agents = 0;
+  for (const f of fs.readdirSync(agentsSrc).filter(n => n.endsWith('.md'))) {
+    let content = fs.readFileSync(path.join(agentsSrc, f), 'utf8');
+    // Core references → the bundle token; mentions → /pan-<name>; then the same
+    // two steps the installer applies to a Copilot agent (thinking frontmatter
+    // strip, Copilot frontmatter/tool-name conversion).
+    content = lib.rewriteAgentReferenceCopy(content, TOKEN_PREFIX);
+    content = lib.stripThinkingFrontmatter(content, 'copilot');
+    content = lib.convertClaudeToCopilotAgent(content);
+    fs.writeFileSync(path.join(agentsDest, f.replace(/\.md$/, '.agent.md')), content);
+    agents++;
+  }
+  fs.mkdirSync(path.join(nsDir, 'hooks'), { recursive: true });
+  fs.writeFileSync(
+    path.join(nsDir, 'hooks', 'hooks.json'),
+    JSON.stringify(lib.buildCopilotPluginHooksConfig(hookCommands('${CLAUDE_PLUGIN_ROOT}')), null, 2) + '\n'
+  );
+  return agents;
+}
+
+function main() {
+  assertSafeToReplace(OUT);
+  fs.rmSync(OUT, { recursive: true, force: true });
+  fs.mkdirSync(OUT, { recursive: true });
+
+  // 1. Manifest (closed schema — nothing beyond the ten permitted keys)
+  fs.writeFileSync(path.join(OUT, 'plugin.json'), JSON.stringify(lib.buildAgentPluginManifest(pkg), null, 2) + '\n');
+
+  // 2. Skills
+  const skills = emitSkills(path.join(ROOT, 'commands', 'pan'), path.join(OUT, 'skills'), 'pan');
+
+  // 3. Core (+ 4. canonical agent copies inside it)
+  const coreDest = path.join(OUT, 'pan-wizard-core');
+  emitCore(path.join(ROOT, 'pan-wizard-core'), coreDest);
+  const agents = emitAgentReferenceCopies(path.join(ROOT, 'agents'), path.join(coreDest, 'agents'));
+
+  // 5. MCP declaration
+  fs.writeFileSync(path.join(OUT, 'mcp.json'), JSON.stringify(lib.buildAgentPluginMcpConfig(), null, 2) + '\n');
+
+  // 6. Hooks: scripts once, at the root; a Codex hooks.json at the documented
+  //    default location (`hooks/hooks.json`, `${PLUGIN_ROOT}` expanded in commands,
+  //    observers async — the same builder the installer uses for .codex/hooks.json).
+  const hooksDir = path.join(OUT, 'hooks');
+  const hookScripts = emitHookScripts(hooksDir);
+  fs.writeFileSync(
+    path.join(hooksDir, 'hooks.json'),
+    JSON.stringify(lib.mergeCodexHooksConfig(null, hookCommands('${PLUGIN_ROOT}')), null, 2) + '\n'
+  );
+
+  // 7. Copilot vendor namespace
+  const copilotAgents = emitCopilotNamespace(path.join(ROOT, 'agents'), path.join(OUT, lib.COPILOT_PLUGIN_NAMESPACE));
+
+  console.log('PAN Agent Plugins bundle built at', path.relative(ROOT, OUT) || OUT);
+  console.log('  skills:', skills);
+  console.log('  agent reference copies:', agents);
+  console.log('  hook scripts:', hookScripts.length);
+  console.log(`  ${lib.COPILOT_PLUGIN_NAMESPACE}/agents:`, copilotAgents);
+  console.log('  version:', pkg.version);
+}
+
+main();

package/scripts/build-plugin.js

@@ -8,6 +8,9 @@
  *   agents/pan-*.md               agent definitions
  *   hooks/hooks.json              PAN hooks with ${CLAUDE_PLUGIN_ROOT} paths
  *   hooks/pan-*.js                hook scripts
+ *   .mcp.json                     MCP bridge declaration (${CLAUDE_PLUGIN_ROOT} path)
+ *   workflows/pan-*.js            native workflow scripts, agentType namespaced
+ *                                 `<plugin>:<agent>` (plugin agents load scoped)
  *   pan-wizard-core/              dispatcher + modules + workflows + templates
  *
  * Distribution status: built ALONGSIDE the loose-file installer. Marketplace
@@ -38,7 +41,28 @@ const fs = require('fs');
 const path = require('path');
 
 const ROOT = path.join(__dirname, '..');
-const OUT = path.join(ROOT, 'dist', 'pan-wizard-plugin');
+// Output directory. `PAN_PLUGIN_OUT` overrides the default so that callers which
+// may run CONCURRENTLY — test files under `node --test`, which runs files in
+// parallel — each build into their own directory instead of racing on one:
+// one process's `rmSync` below landed in the middle of another's copy
+// (ENOENT mid-tree, and an empty stdout for plugin-path.js) on 2026-09-10.
+const OUT = process.env.PAN_PLUGIN_OUT
+  ? path.resolve(process.env.PAN_PLUGIN_OUT)
+  : path.join(ROOT, 'dist', 'pan-wizard-plugin');
+
+/**
+ * Refuse to wipe a directory that is not a previous plugin build. The default
+ * path is ours by construction; an override is a user-supplied path, and
+ * `rmSync(recursive)` on the wrong one is unrecoverable. A directory that does
+ * not exist yet, is empty, or carries our own manifest is fair game.
+ */
+function assertSafeToReplace(dir) {
+  if (!fs.existsSync(dir)) return;
+  const entries = fs.readdirSync(dir);
+  if (entries.length === 0) return;
+  if (fs.existsSync(path.join(dir, '.claude-plugin', 'plugin.json'))) return;
+  throw new Error(`build-plugin: refusing to replace ${dir} — it is non-empty and does not look like a previous plugin build (no .claude-plugin/plugin.json)`);
+}
 const pkg = require(path.join(ROOT, 'package.json'));
 const lib = require(path.join(ROOT, 'bin', 'install-lib.cjs'));
 
@@ -73,13 +97,15 @@ function copyTree(srcDir, destDir, transformMd) {
 
 function main() {
   // Clean output
+  assertSafeToReplace(OUT);
   fs.rmSync(OUT, { recursive: true, force: true });
   fs.mkdirSync(path.join(OUT, '.claude-plugin'), { recursive: true });
 
   // 1. Manifest
+  const manifest = lib.buildPluginManifest(pkg);
   fs.writeFileSync(
     path.join(OUT, '.claude-plugin', 'plugin.json'),
-    JSON.stringify(lib.buildPluginManifest(pkg), null, 2) + '\n'
+    JSON.stringify(manifest, null, 2) + '\n'
   );
 
   // 2. Commands (Claude flavor, plugin-root-relative paths)
@@ -109,7 +135,7 @@ function main() {
   // deliberately bypasses rewriteContent().
   fs.writeFileSync(
     path.join(OUT, 'commands', 'pan-plugin-selftest.md'),
-    lib.buildPluginSelfTestCommand(CONTENT_PREFIX.replace(/\/$/, ''))
+    lib.buildPluginSelfTestCommand(CONTENT_PREFIX.replace(/\/$/, ''), manifest.name)
   );
 
   // 4b. MCP registration. The server itself rides along inside pan-wizard-core
@@ -125,12 +151,31 @@ function main() {
   fs.rmSync(path.join(OUT, 'pan-wizard-core', 'learnings', 'internal'), { recursive: true, force: true });
   fs.writeFileSync(path.join(OUT, 'pan-wizard-core', 'VERSION'), pkg.version);
 
+  // 6. Native workflows. A plugin loads `workflows/` at its root and exposes each
+  // script as `/<plugin>:<meta.name>`. Until 2026-09 the builder never wrote this
+  // directory, so the plugin shipped LESS than a loose-file install (which has
+  // written `.claude/workflows/` since 2026-06). One thing differs from that
+  // install: the scripts spawn PAN agents by name, and plugin agents load under a
+  // SCOPED name — `agents/pan-reviewer.md` here is `pan-wizard:pan-reviewer`
+  // (plugins-reference, read 2026-09-10) — so a bare `agentType: 'pan-…'` that
+  // resolves in a loose install would not resolve inside the plugin. The rewrite
+  // is applied to the plugin copy only; the installer keeps bare names.
+  fs.mkdirSync(path.join(OUT, 'workflows'), { recursive: true });
+  const workflowScripts = lib.buildNativeWorkflowScripts();
+  for (const { name, content } of workflowScripts) {
+    fs.writeFileSync(
+      path.join(OUT, 'workflows', name),
+      lib.namespaceWorkflowAgentTypes(content, manifest.name)
+    );
+  }
+
   // Sanity report
   const count = (p) => { try { return fs.readdirSync(p).length; } catch { return 0; } };
   console.log('PAN plugin built at', path.relative(ROOT, OUT));
   console.log('  commands/pan:', count(path.join(OUT, 'commands', 'pan')));
   console.log('  agents:', count(path.join(OUT, 'agents')));
   console.log('  hooks:', count(path.join(OUT, 'hooks')));
+  console.log('  workflows:', workflowScripts.length);
   console.log('  version:', pkg.version);
 }
 

package/scripts/coverage-gate.cjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * coverage-gate.cjs — did the shipped code actually run under the tests?
+ *
+ * Runs the whole suite under Node's own coverage instrumentation (no dependency:
+ * `node --test --experimental-test-coverage`, lcov reporter; the child processes
+ * the tests spawn — pan-tools, the installer, the hooks — are captured through the
+ * inherited NODE_V8_COVERAGE), then enforces:
+ *   - line and function floors overall and per module group (tests/fixtures/
+ *     coverage-policy.json — a floor sits a point below the measured baseline, so
+ *     a real regression fails and normal churn does not);
+ *   - every dispatcher `case` arm executed at least once — the binary rule that
+ *     catches "a verb no test dispatches", which a percentage hides. An arm may be
+ *     allowlisted in the policy with a reason (interactive, network, a P2 item).
+ * The never-called functions are printed, ranked, so a gap has a name.
+ *
+ *   node scripts/coverage-gate.cjs             run the suite, evaluate, exit 1 on a violation
+ *   node scripts/coverage-gate.cjs --lcov f    evaluate an existing lcov file (no run)
+ *   node scripts/coverage-gate.cjs --json      machine-readable result
+ *
+ * Node < 22 lacks the coverage include/exclude flags: the gate reports "skipped"
+ * and exits 0 there, so the 18/20 CI jobs stay green and the 22 job carries it.
+ * Wired as release-check Gate 9 and as an advisory CI step on the Node 22 job.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { parseCaseArms } = require('./test-surface.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const POLICY_REL = path.join('tests', 'fixtures', 'coverage-policy.json');
+const DISPATCHER_REL = 'pan-wizard-core/bin/pan-tools.cjs';
+const TEST_DIRS = ['tests', 'tests/scenarios'];
+const INCLUDE = ['pan-wizard-core/**/*.cjs', 'pan-wizard-core/**/*.js', 'bin/**', 'hooks/*.js', 'scripts/**'];
+const EXCLUDE = ['tests/**', '**/node_modules/**'];
+const MIN_NODE_MAJOR = 22;
+
+const DEFAULT_POLICY = Object.freeze({
+  floors: { overall_lines: 92, overall_functions: 93, groups: { lib: 92, installer: 90, hooks: 90, mcp: 95 } },
+  arms_allow: [],
+});
+
+// ─── lcov ───────────────────────────────────────────────────────────────────
+
+/** Parse lcov text into [{ path, lines: Map(line→hits), fn: Map(name→line), fnda: Map(name→hits), lf, lh, brf, brh }]. */
+function parseLcov(text) {
+  const files = [];
+  let cur = null;
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const ci = raw.indexOf(':');
+    const k = ci >= 0 ? raw.slice(0, ci) : raw;
+    const v = ci >= 0 ? raw.slice(ci + 1) : '';
+    if (k === 'SF') { cur = { path: v.split('\\').join('/'), lines: new Map(), fn: new Map(), fnda: new Map(), lf: 0, lh: 0, brf: 0, brh: 0 }; continue; }
+    if (!cur) continue;
+    if (k === 'DA') { const [ln, c] = v.split(',').map(Number); cur.lines.set(ln, c); }
+    else if (k === 'FN') { const i = v.indexOf(','); cur.fn.set(v.slice(i + 1), Number(v.slice(0, i))); }
+    else if (k === 'FNDA') { const i = v.indexOf(','); cur.fnda.set(v.slice(i + 1), Number(v.slice(0, i))); }
+    else if (k === 'LF') cur.lf = Number(v); else if (k === 'LH') cur.lh = Number(v);
+    else if (k === 'BRF') cur.brf = Number(v); else if (k === 'BRH') cur.brh = Number(v);
+    else if (raw === 'end_of_record') { files.push(cur); cur = null; }
+  }
+  return files;
+}
+
+function relPath(p, root = ROOT) {
+  const r = root.split('\\').join('/');
+  const i = p.indexOf(r);
+  return i >= 0 ? p.slice(i + r.length).replace(/^\//, '') : p;
+}
+
+function groupOf(rel) {
+  if (/^pan-wizard-core\/bin\/lib\//.test(rel)) return 'lib';
+  if (/^pan-wizard-core\/mcp\//.test(rel)) return 'mcp';
+  if (/^pan-wizard-core\/bin\//.test(rel)) return 'cli';
+  if (/^pan-wizard-core\/workflows\//.test(rel)) return 'native-workflows';
+  if (/^bin\//.test(rel)) return 'installer';
+  if (/^hooks\//.test(rel)) return 'hooks';
+  if (/^scripts\//.test(rel)) return 'scripts';
+  return 'other';
+}
+
+/**
+ * Which case arms executed. An arm is executed when the first instrumented line
+ * after its label (before the next arm at the same or a shallower indent) ran; a
+ * label immediately followed by another label shares that arm's body (fallthrough).
+ */
+function armCoverage(dispatcherSrc, dispatcherFile) {
+  const arms = parseCaseArms(dispatcherSrc);
+  const byLine = new Map(arms.map((a) => [a.line, a]));
+  const lines = dispatcherSrc.split(/\r?\n/);
+  const da = dispatcherFile ? dispatcherFile.lines : new Map();
+  const result = [];
+  for (const a of arms) {
+    let verdict = null;
+    for (let ln = a.line + 1; ln <= lines.length; ln++) {
+      const nxt = byLine.get(ln);
+      if (nxt && nxt.indent <= a.indent) {
+        if (nxt.indent === a.indent && /^\s*case\s+'/.test(lines[ln - 1])) verdict = 'fallthrough';
+        break;
+      }
+      if (da.has(ln)) { verdict = da.get(ln) > 0; break; }
+    }
+    result.push({ id: a.parent ? `${a.parent} > ${a.label}` : a.label, line: a.line, verdict });
+  }
+  // A fallthrough label takes the verdict of the arm it shares.
+  for (let i = 0; i < result.length; i++) {
+    if (result[i].verdict === 'fallthrough') {
+      let j = i + 1;
+      while (j < result.length && result[j].verdict === 'fallthrough') j++;
+      result[i].verdict = j < result.length ? result[j].verdict : null;
+    }
+  }
+  return result;
+}
+
+function validatePolicy(policy) {
+  const errors = [];
+  for (const a of policy.arms_allow || []) {
+    if (!a || typeof a.arm !== 'string') errors.push(`arms_allow entry without an arm: ${JSON.stringify(a)}`);
+    else if (!a.reason || !String(a.reason).trim()) errors.push(`arms_allow entry "${a.arm}" has no reason`);
+  }
+  return errors;
+}
+
+/**
+ * Evaluate parsed lcov against the policy and the dispatcher source.
+ * Pure. Returns { ok, violations[], groups, overall, arms, never_called, policy_errors }.
+ */
+function evaluateCoverage(lcovFiles, { dispatcherSrc, policy = DEFAULT_POLICY, root = ROOT } = {}) {
+  const violations = [];
+  const policyErrors = validatePolicy(policy);
+  violations.push(...policyErrors.map((e) => `policy: ${e}`));
+  if (!lcovFiles.length) violations.push('lcov parsed no files — malformed or empty coverage output (failing closed)');
+
+  const groups = {};
+  const overall = { lf: 0, lh: 0, ff: 0, fh: 0 };
+  const neverCalled = [];
+  let dispatcherFile = null;
+  for (const f of lcovFiles) {
+    const rel = relPath(f.path, root);
+    if (rel.endsWith(DISPATCHER_REL) || rel === DISPATCHER_REL) dispatcherFile = f;
+    const g = groupOf(rel);
+    const fns = [...f.fn.keys()];
+    const fh = fns.filter((n) => (f.fnda.get(n) || 0) > 0).length;
+    const acc = groups[g] = groups[g] || { files: 0, lf: 0, lh: 0, ff: 0, fh: 0 };
+    acc.files++; acc.lf += f.lf; acc.lh += f.lh; acc.ff += fns.length; acc.fh += fh;
+    overall.lf += f.lf; overall.lh += f.lh; overall.ff += fns.length; overall.fh += fh;
+    for (const n of fns) if (!((f.fnda.get(n) || 0) > 0)) neverCalled.push(`${rel}:${f.fn.get(n)} ${n || '(anonymous)'}`);
+  }
+  const pct = (h, t) => (t ? Math.round((h / t) * 1000) / 10 : 100);
+  const overallPct = { lines: pct(overall.lh, overall.lf), functions: pct(overall.fh, overall.ff) };
+  const floors = policy.floors || DEFAULT_POLICY.floors;
+  if (lcovFiles.length) {
+    if (overallPct.lines < floors.overall_lines) violations.push(`overall line coverage ${overallPct.lines}% is below the floor ${floors.overall_lines}%`);
+    if (overallPct.functions < floors.overall_functions) violations.push(`overall function coverage ${overallPct.functions}% is below the floor ${floors.overall_functions}%`);
+    for (const [g, floor] of Object.entries(floors.groups || {})) {
+      const acc = groups[g];
+      if (!acc) { violations.push(`group "${g}" has no files under coverage — include globs or layout changed`); continue; }
+      const p = pct(acc.lh, acc.lf);
+      if (p < floor) violations.push(`${g} line coverage ${p}% is below the floor ${floor}%`);
+    }
+  }
+
+  let arms = [];
+  if (dispatcherSrc) {
+    arms = armCoverage(dispatcherSrc, dispatcherFile);
+    const allow = new Map((policy.arms_allow || []).map((a) => [a.arm, a.reason]));
+    if (!dispatcherFile && lcovFiles.length) violations.push('the dispatcher was not in the coverage output — no test ran pan-tools.cjs?');
+    for (const a of arms) {
+      if (a.verdict === true) continue;
+      if (allow.has(a.id)) { a.allowlisted = allow.get(a.id); continue; }
+      violations.push(`dispatcher arm never executed: ${a.id} (line ${a.line}) — add a test that dispatches it, or allowlist it in ${POLICY_REL} with a reason`);
+    }
+    for (const [arm] of allow) if (!arms.some((a) => a.id === arm)) violations.push(`policy: arms_allow names an arm that no longer exists: ${arm}`);
+    for (const [arm, reason] of allow) { const a = arms.find((x) => x.id === arm); if (a && a.verdict === true) violations.push(`policy: arm "${arm}" is executed now — remove its allowlist entry (${reason})`); }
+  }
+
+  const groupTable = Object.fromEntries(Object.entries(groups).map(([g, a]) => [g, { files: a.files, lines: pct(a.lh, a.lf), functions: pct(a.fh, a.ff) }]));
+  return { ok: violations.length === 0, violations, overall: overallPct, groups: groupTable, arms, never_called: neverCalled.sort(), policy_errors: policyErrors };
+}
+
+// ─── Running the suite ──────────────────────────────────────────────────────
+
+function expandTestFiles(root = ROOT, dirs = TEST_DIRS) {
+  const files = [];
+  for (const dir of dirs) {
+    const abs = path.join(root, dir);
+    let entries = [];
+    try { entries = fs.readdirSync(abs); } catch { continue; }
+    for (const f of entries) if (f.endsWith('.test.cjs')) files.push(path.join(abs, f));
+  }
+  return files.sort();
+}
+
+function runSuiteWithCoverage(root = ROOT, lcovPath) {
+  const specLog = lcovPath + '.spec.log';
+  const args = ['--test', '--experimental-test-coverage'];
+  for (const g of INCLUDE) args.push(`--test-coverage-include=${g}`);
+  for (const g of EXCLUDE) args.push(`--test-coverage-exclude=${g}`);
+  args.push('--test-reporter=lcov', `--test-reporter-destination=${lcovPath}`, '--test-reporter=spec', `--test-reporter-destination=${specLog}`);
+  args.push(...expandTestFiles(root));
+  const r = spawnSync(process.execPath, args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 });
+  return { status: r.status, specLog, stderr: r.stderr || '' };
+}
+
+function loadPolicy(root = ROOT) {
+  try { return JSON.parse(fs.readFileSync(path.join(root, POLICY_REL), 'utf8')); } catch { return DEFAULT_POLICY; }
+}
+
+function render(result) {
+  const lines = [];
+  lines.push(`coverage gate — ${result.ok ? 'OK' : 'FAIL'}`);
+  lines.push(`  overall: lines ${result.overall.lines}% · functions ${result.overall.functions}%`);
+  for (const [g, a] of Object.entries(result.groups).sort()) lines.push(`  ${g.padEnd(18)} files ${String(a.files).padStart(3)}  lines ${String(a.lines).padStart(5)}%  functions ${String(a.functions).padStart(5)}%`);
+  const executed = result.arms.filter((a) => a.verdict === true).length;
+  const allowed = result.arms.filter((a) => a.allowlisted).length;
+  lines.push(`  dispatcher arms: ${executed}/${result.arms.length} executed${allowed ? `, ${allowed} allowlisted` : ''}`);
+  if (result.never_called.length) {
+    lines.push(`  never-called functions: ${result.never_called.length} (first 12)`);
+    for (const n of result.never_called.slice(0, 12)) lines.push(`    ${n}`);
+  }
+  for (const v of result.violations) lines.push(`  ✖ ${v}`);
+  return lines.join('\n');
+}
+
+function main(argv) {
+  const major = Number(process.versions.node.split('.')[0]);
+  const lcovArg = argv.includes('--lcov') ? argv[argv.indexOf('--lcov') + 1] : null;
+  if (!lcovArg && major < MIN_NODE_MAJOR) {
+    console.log(`coverage gate — skipped on Node ${process.versions.node} (needs ${MIN_NODE_MAJOR}+ for coverage include/exclude flags)`);
+    return 0;
+  }
+  let lcovPath = lcovArg;
+  let tmp = null;
+  if (!lcovPath) {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-coverage-'));
+    lcovPath = path.join(tmp, 'coverage.lcov');
+    const r = runSuiteWithCoverage(ROOT, lcovPath);
+    if (r.status !== 0) {
+      console.error(`coverage gate — the suite itself failed (exit ${r.status}); see ${r.specLog}`);
+      return 1;
+    }
+  }
+  let text = '';
+  try { text = fs.readFileSync(lcovPath, 'utf8'); } catch (e) { console.error(`coverage gate — cannot read ${lcovPath}: ${e.message}`); return 1; }
+  const result = evaluateCoverage(parseLcov(text), { dispatcherSrc: fs.readFileSync(path.join(ROOT, DISPATCHER_REL), 'utf8'), policy: loadPolicy(ROOT), root: ROOT });
+  if (argv.includes('--json')) console.log(JSON.stringify(result, null, 2));
+  else console.log(render(result));
+  if (tmp && !argv.includes('--keep')) { try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* best-effort */ } }
+  return result.ok ? 0 : 1;
+}
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));
+
+module.exports = { parseLcov, groupOf, armCoverage, evaluateCoverage, validatePolicy, expandTestFiles, render, DEFAULT_POLICY, POLICY_REL, INCLUDE, EXCLUDE, MIN_NODE_MAJOR };

package/scripts/generate-skills-docs.py

@@ -48,7 +48,7 @@ GROUP_ORDER = [
 # Dev skill categorization (filename -> category)
 DEV_CATEGORIES = {
     "Development Workflow": [
-        "pandev", "execplan", "superplan", "featureAI", "review",
+        "pandev", "execplan", "superplan", "featureAI", "review", "reality-check",
     ],
     "Testing & Verification": [
         "test", "quick", "pantest", "check", "check-platform", "auditai",

package/scripts/install-git-hooks.js

@@ -52,6 +52,11 @@ try {
 
 // 3. Confirm the hook file is executable on Unix. On Windows the bit doesn't
 //    matter — Git Bash treats `.sh` and shebanged scripts as executable.
+//    The file is TRACKED as 100755, so this is a safety net rather than the source
+//    of truth: it used to be tracked 100644, and since npm ci runs this script
+//    through `prepare`, every Linux and macOS checkout was left with a one-bit dirty
+//    tree that nothing looked at until CI began asserting the tree is unchanged
+//    (2026-09-17).
 const hookFile = path.join(REPO_ROOT, HOOKS_DIR, 'pre-commit');
 if (process.platform !== 'win32') {
   try {