pan-wizard 3.28.0 → 3.30.0

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

@@ -182,10 +182,32 @@ function hasBraveSearchKey() {
   return fileAccessible(path.join(os.homedir(), '.pan-wizard', 'brave_api_key'));
 }
 
+/**
+ * Which workflow model a planning tree runs (PLANNING_MODEL_MARKERS). The phase model
+ * wins when its markers are present, since a phase project may also hold focus
+ * artifacts; `fragment` means entries exist but none of them mark a deliberate
+ * workflow, and `absent` that the directory could not be read.
+ *
+ * @param {string} planningDir - absolute path to the tree (e.g. planningPath(cwd))
+ * @returns {{model: 'phase'|'focus'|'campaign'|'fragment'|'empty'|'absent', evidence: string[], entries: number}}
+ */
+function detectPlanningModel(planningDir) {
+  const { PLANNING_MODEL_MARKERS } = require('./constants.cjs');
+  let entries;
+  try { entries = fs.readdirSync(planningDir); } catch { return { model: 'absent', evidence: [], entries: 0 }; }
+  const lower = new Set(entries.map(e => String(e).toLowerCase()));
+  for (const model of ['phase', 'focus', 'campaign']) {
+    const evidence = PLANNING_MODEL_MARKERS[model].filter(m => lower.has(m));
+    if (evidence.length) return { model, evidence, entries: entries.length };
+  }
+  return { model: entries.length ? 'fragment' : 'empty', evidence: [], entries: entries.length };
+}
+
 module.exports = {
   readJsonFile,
   removeQuotes,
   planningPath,
+  detectPlanningModel,
   planningRel,
   phasesPath,
   milestonesPath,

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

@@ -107,7 +107,7 @@ function validateRuntimeInstall(cwd, configDir, runtime) {
         }
       }
     }
-    // Copilot/Gemini statusLine
+    // statusLine (Claude, Copilot; PAN writes none for Gemini since 2026-09-23)
     if (settings.statusLine && settings.statusLine.command) {
       hookCommands.push(settings.statusLine.command);
     }

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

@@ -14,7 +14,7 @@ const {
   PLAN_SUFFIX, SUMMARY_SUFFIX, STANDARDS_FILE, STANDARDS_CATALOG, HEALTH_STATUS,
   BUILTIN_DRIFT_RULES, DRIFT_VERDICTS, BINARY_EXTENSIONS, DRIFT_MAX_FILES, DRIFT_MAX_FILE_SIZE, DRIFT_SEVERITY_WEIGHTS,
 } = require('./constants.cjs');
-const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, fileAccessible } = require('./utils.cjs');
+const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, fileAccessible, detectPlanningModel } = require('./utils.cjs');
 const { detectForeignPlanningTree } = require('./foreign-planning.cjs');
 // Drift detection lives in verify-drift.cjs; re-exported below so consumers of
 // verify.cjs are unaffected by the decomposition.
@@ -1320,19 +1320,33 @@ function cmdValidateHealth(cwd, options, raw) {
     return;
   }
 
+  // Check 1c: which workflow model is this tree running? Checks 2-8b below are the
+  // PHASE model's — a focus-model project (`/pan:focus`, no project/roadmap/state by
+  // design) and an orchestration campaign would each fail all of them and be called
+  // broken, which is what eight of fourteen field projects hit (sweep 2026-09-17).
+  // config.json is the one check every model shares.
+  const shape = detectPlanningModel(planningPath(cwd));
+  const phaseModel = shape.model === 'phase' || shape.model === 'fragment' || shape.model === 'empty';
+
   // Checks 2-8: individual structure and consistency checks
-  checkProjectFile(cwd, addIssue);
-  checkRoadmapFile(cwd, addIssue);
-  checkStateFile(cwd, addIssue, repairs);
+  if (phaseModel) {
+    checkProjectFile(cwd, addIssue);
+    checkRoadmapFile(cwd, addIssue);
+    checkStateFile(cwd, addIssue, repairs);
+  } else {
+    addIssue('info', 'I003', `${shape.model}-model project (${shape.evidence.join(', ')}) — the phase-model checks (project.md, roadmap.md, state.md, phases/) do not apply`, null);
+  }
   checkConfigFile(cwd, addIssue, repairs);
-  checkPhaseDirectories(cwd, addIssue);
-  checkPhaseContents(cwd, addIssue);
+  if (phaseModel) {
+    checkPhaseDirectories(cwd, addIssue);
+    checkPhaseContents(cwd, addIssue);
 
-  // Check 8b: cross-document state consistency
-  checkStateConsistency(cwd, addIssue, repairs);
+    // Check 8b: cross-document state consistency
+    checkStateConsistency(cwd, addIssue, repairs);
 
-  // Check 8c: verification gate (phases with verifier enabled need verification.md)
-  checkVerificationGate(cwd, addIssue);
+    // Check 8c: verification gate (phases with verifier enabled need verification.md)
+    checkVerificationGate(cwd, addIssue);
+  }
 
   // Check 9 (optional): standards compliance
   if (options.standards) {

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

@@ -203,6 +203,7 @@ const codebase = require('./lib/codebase.cjs');
 const memory = require('./lib/memory.cjs');
 const bus = require('./lib/bus.cjs');
 const cost = require('./lib/cost.cjs');
+const costRebuild = require('./lib/cost-rebuild.cjs');
 const preview = require('./lib/preview.cjs');
 const reviewDeep = require('./lib/review-deep.cjs');
 const knowledge = require('./lib/knowledge.cjs');
@@ -1207,8 +1208,14 @@ async function main() {
         cost.cmdCostAppend(cwd, rec, raw);
       } else if (subcommand === 'clear') {
         cost.cmdCostClear(cwd, raw);
+      } else if (subcommand === 'rebuild') {
+        costRebuild.cmdCostRebuild(cwd, {
+          apply: args.includes('--apply'),
+          mainThread: !args.includes('--no-main-thread'),
+          claudeDir: getArgValue(args, '--claude-dir'),
+        }, raw);
       } else {
-        error('Unknown cost subcommand. Available: report, append, clear');
+        error('Unknown cost subcommand. Available: report, append, clear, rebuild');
       }
       break;
     }

package/pan-wizard-core/references/model-profiles.md

@@ -11,8 +11,8 @@ PAN uses three abstract tiers instead of hardcoded model names:
 | Tier | Purpose | Anthropic | OpenAI | Google |
 |------|---------|-----------|--------|--------|
 | `reasoning` | Architecture, planning, complex decisions | inherit (your session's top-tier model) | inherit | inherit |
-| `mid` | Execution, research, verification | Sonnet | mid | gemini-2.5-flash |
-| `fast` | Read-only extraction, budget tasks | Haiku | fast | gemini-2.5-flash-lite |
+| `mid` | Execution, research, verification | Sonnet | gpt-6-sol | gemini-3.8-flash |
+| `fast` | Read-only extraction, budget tasks | Haiku | gpt-6-luna | gemini-3.5-flash-lite |
 
 **Why `inherit` for reasoning?** Host runtimes map "opus" to a specific model version. PAN returns `inherit` for reasoning-tier agents, so they use whatever top-tier model the user has configured. This avoids version conflicts and silent fallbacks.
 
@@ -39,7 +39,7 @@ At install time PAN also runs a **best-effort, advisory** capability check on th
 | Class | Example model IDs | Role in PAN | Context | Relative cost | Notes |
 |-------|-------------------|-------------|---------|---------------|-------|
 | Fable / Mythos | `claude-fable-5` | **Recommended flagship** — deepest long-horizon reasoning; best for the bot army's Mission Control + planning | 1M | ~2× Opus | Runs input safety classifiers (see caveat below); requires 30-day data retention |
-| Opus | `claude-opus-5`, `claude-opus-4-8` | **Cost-conscious pick** — same 1M context + thinking, about half the cost, no cyber classifier | 1M | 1× | The safe pick when you want Opus behavior without Fable's refusal surface |
+| Opus | `claude-opus-5-5`, `claude-opus-5`, `claude-opus-4-8` | **Cost-conscious pick** — same 1M context + thinking, about half the cost, no cyber classifier | 1M | 1× | The safe pick when you want Opus behavior without Fable's refusal surface |
 
 **Why the Fable class is the recommended flagship.** It is Anthropic's deepest class for demanding, long-horizon agentic work — exactly what PAN's hierarchical bot army (Mission Control → squads → workers) asks of its reasoning tier. Select the current release in that class in your host runtime and `inherit` routes the reasoning-tier agents to it automatically.
 
@@ -117,7 +117,7 @@ PAN auto-detects the LLM provider to map tiers to the right model names:
 
 1. **Explicit config** — `routing.provider` in config.json (if not `"auto"`)
 2. **Environment variable** — `PAN_PROVIDER` env var
-3. **Runtime directory** — `.claude/` → Anthropic, `.codex/` → OpenAI, `.gemini/` → Google
+3. **Runtime directory** — `.claude/` → Anthropic, `.codex/` → OpenAI, `.gemini/` → Google, `.opencode/` → OpenAI, `.github/` → default (first match wins)
 4. **Fallback** — Default provider map (Anthropic-style names)
 
 ---

package/pan-wizard-core/references/planning-config.md

@@ -4,24 +4,22 @@ Configuration options for `.planning/` directory behavior.
 
 <config_schema>
 ```json
-"planning": {
-  "commit_docs": true,
-  "search_gitignored": false
-},
-"git": {
-  "branching_strategy": "none",
-  "phase_branch_template": "pan/phase-{phase}-{slug}",
-  "milestone_branch_template": "pan/{milestone}-{slug}"
-}
+"commit_docs": true,
+"search_gitignored": false,
+"branching_strategy": "none",
+"phase_branch_template": "pan/phase-{phase}-{slug}",
+"milestone_branch_template": "pan/{milestone}-{slug}"
 ```
 
 | Option | Default | Description |
 |--------|---------|-------------|
 | `commit_docs` | `true` | Whether to commit planning artifacts to git |
 | `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
-| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
-| `git.phase_branch_template` | `"pan/phase-{phase}-{slug}"` | Branch template for phase strategy |
-| `git.milestone_branch_template` | `"pan/{milestone}-{slug}"` | Branch template for milestone strategy |
+| `branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
+| `phase_branch_template` | `"pan/phase-{phase}-{slug}"` | Branch template for phase strategy |
+| `milestone_branch_template` | `"pan/{milestone}-{slug}"` | Branch template for milestone strategy |
+
+These keys are top-level. The nested `planning.*` / `git.*` forms older versions wrote are read only when the top-level key is absent. A config `config-ensure-section` creates carries every top-level key, and one `/pan:new-project` writes carries a top-level `commit_docs` — so write the top-level key; a nested one is ignored whenever the top-level key exists.
 </config_schema>
 
 <commit_docs_behavior>
@@ -84,10 +82,8 @@ To use uncommitted mode:
 
 1. **Set config:**
    ```json
-   "planning": {
-     "commit_docs": false,
-     "search_gitignored": true
-   }
+   "commit_docs": false,
+   "search_gitignored": true
    ```
 
 2. **Add to .gitignore:**
@@ -101,7 +97,7 @@ To use uncommitted mode:
    git commit -m "chore: stop tracking planning docs"
    ```
 
-4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `milestone-done` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.
+4. **Branch merges:** PAN never merges branches; when you merge a phase or milestone branch yourself with `commit_docs: false`, keep `.planning/` out of the merge commit.
 
 </setup_uncommitted_mode>
 
@@ -113,24 +109,24 @@ To use uncommitted mode:
 |----------|---------------------|--------------|-------------|
 | `none` | Never | N/A | N/A |
 | `phase` | At `execute-phase` start | Single phase | User merges after phase |
-| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `milestone-done` |
+| `milestone` | At first `execute-phase` of milestone | Entire milestone | User merges after milestone |
 
-**When `git.branching_strategy: "none"` (default):**
+**When `branching_strategy: "none"` (default):**
 - All work commits to current branch
 - Standard PAN behavior
 
-**When `git.branching_strategy: "phase"`:**
+**When `branching_strategy: "phase"`:**
 - `execute-phase` creates/switches to a branch before execution
 - Branch name from `phase_branch_template` (e.g., `pan/phase-03-authentication`)
 - All plan commits go to that branch
 - User merges branches manually after phase completion
-- `milestone-done` offers to merge all phase branches
+- `milestone-done` does not merge — merge the phase branches yourself
 
-**When `git.branching_strategy: "milestone"`:**
+**When `branching_strategy: "milestone"`:**
 - First `execute-phase` of milestone creates the milestone branch
 - Branch name from `milestone_branch_template` (e.g., `pan/v1.0-mvp`)
 - All phases in milestone commit to same branch
-- `milestone-done` offers to merge milestone branch to main
+- `milestone-done` archives and tags but does not merge — merge the milestone branch yourself
 
 **Template variables:**
 

package/pan-wizard-core/workflows/health.md

@@ -162,6 +162,7 @@ Report final status.
 | W007 | warning | Phase on disk but not in ROADMAP | No |
 | I001 | info | Plan without SUMMARY (may be in progress) | No |
 | I002 | info | Phase in ROADMAP ahead of current phase, not planned yet | No |
+| I003 | info | Focus-model or campaign tree — the phase-model checks do not apply | No |
 | STATE_REQ_DRIFT | warning | state.md complete but REQUIREMENTS.md has unchecked boxes | Yes |
 | STATE_ROADMAP_DRIFT | warning | state.md complete but roadmap.md has unchecked plan boxes | Yes |
 | VERIFICATION_GATE_MISSING | warning | Phase has completed plans but no verification record | No |

package/pan-wizard-core/workflows/settings.md

@@ -31,7 +31,7 @@ Parse current values (default to `true` if not present):
 - `workflow.nyquist_validation` — validation architecture research during plan-phase
 - `model_profile` — which model each agent uses (default: `balanced`)
 - `routing.strategy` — how model tiers are adjusted at runtime (default: `static`)
-- `git.branching_strategy` — branching approach (default: `"none"`)
+- `branching_strategy` — branching approach (default: `"none"`; a top-level key — a nested `git.branching_strategy` is ignored when the top-level key exists, as it does in every config `config-ensure-section` creates — write the top-level key)
 </step>
 
 <step name="present_settings">
@@ -131,9 +131,7 @@ Merge new settings into existing config.json:
     "auto_advance": true/false,
     "nyquist_validation": true/false
   },
-  "git": {
-    "branching_strategy": "none" | "phase" | "milestone"
-  },
+  "branching_strategy": "none" | "phase" | "milestone",
   "routing": {
     "strategy": "static" | "complexity"
   }

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/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 {