pan-wizard 3.35.0 → 3.37.0

package/pan-wizard-core/workflows/uat-walkthrough.md

@@ -0,0 +1,90 @@
+<purpose>
+Walk the user through user acceptance testing for one phase, one test at a time, on any runtime. Record each answer through the engine, so every runtime leaves the same `{phase_num}-uat.md`. When the walkthrough finds issues, diagnose them, then hand the gaps to `/pan:plan-phase {phase_num} --gaps`.
+</purpose>
+
+<core_principle>
+The user is the oracle here. You present what they should be able to observe, they say whether they observed it, and the engine writes it down. Never mark a test passed on their behalf, and never rephrase their report: an issue is recorded in their words.
+</core_principle>
+
+<process>
+
+<step name="initialize">
+```bash
+INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${PHASE_ARG}")
+```
+Take `phase_dir`, `phase_number` and `phase_name` from the JSON. Look for an existing session:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs uat status "${PHASE_NUMBER}"
+```
+
+- **A session exists with tests pending:** resume at the first pending test.
+- **A session exists and is complete:** show its summary. If it has gaps, go to `diagnose`; otherwise go to `done`.
+- **No session (`uat_not_found`):** go to `build_tests`.
+</step>
+
+<step name="build_tests">
+Create the file, then fill in its tests:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs scaffold uat --phase "${PHASE_NUMBER}"
+```
+
+Read the phase's summaries (`{phase_dir}/*-summary.md`) and its plans' `must_haves`. Write one test per user-observable truth into the file's `## Tests` section, each as:
+
+```markdown
+### N. <short name>
+expected: <what the user should be able to see or do, concretely: the command, the screen, the output>
+result: [pending]
+```
+
+Keep to what a person can observe without reading the code. Write the test list once, in full, then leave every result to the engine.
+</step>
+
+<step name="walk">
+For each pending test, in order:
+
+1. Show the test: its name and its `expected` behaviour, with the exact steps to observe it.
+2. Ask for the result:
+   ```
+   AskUserQuestion([
+     { question: "Test N: <name>. Did you observe the expected behaviour?", header: "UAT", multiSelect: false, options: [
+       { label: "Pass", description: "It behaves as expected" },
+       { label: "Issue", description: "Something differs; describe what you saw" },
+       { label: "Skip", description: "Cannot test this now" }
+     ] }
+   ])
+   ```
+   Runtimes without AskUserQuestion ask the same question in plain text and take the answer from the reply.
+3. Record it, in the user's own words for an issue:
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs uat record "${PHASE_NUMBER}" --test N --result pass
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs uat record "${PHASE_NUMBER}" --test N --result issue --reported "<their words>" --severity major
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs uat record "${PHASE_NUMBER}" --test N --result skipped --reason "<why>"
+   ```
+   Severity: `blocker` (cannot use the feature), `major` (wrong behaviour), `minor` (works, but rough), `cosmetic`.
+
+When no test is pending, the engine marks the session `complete`.
+</step>
+
+<step name="diagnose">
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs uat status "${PHASE_NUMBER}"
+```
+
+If `gaps` is empty, go to `done`. Otherwise follow the diagnose-issues workflow (@~/.claude/pan-wizard-core/workflows/diagnose-issues.md). On Claude Code the native `/pan-diagnose-issues {phase_num}` script does the same in parallel. Diagnosis fills each gap's `root_cause`, `artifacts`, `missing` and `debug_session`, and the engine keeps those fields across any later re-record.
+</step>
+
+<step name="done">
+Report the summary (`passed`, `issues`, `skipped`). With gaps:
+
+```
+UAT found {issues} issue(s), diagnosed in {phase_num}-uat.md.
+
+Next: /pan:plan-phase {phase_num} --gaps
+```
+
+Without gaps: "UAT passed. Continue with `/pan:exec-phase {phase_num}` (transition) or the next phase."
+</step>
+
+</process>

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

@@ -197,7 +197,7 @@ Format completion message (changelog was already shown in confirmation step):
 
 ⚠️  Restart your AI coding tool to pick up the new commands.
 
-[View full changelog](https://github.com/oharms/PanWizard/blob/main/CHANGELOG.md)
+Full changelog: ~/.claude/pan-wizard-core/CHANGELOG.md
 ```
 </step>
 

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

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

package/scripts/build-agent-plugin.js

@@ -15,9 +15,17 @@
  *                                 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
+ *   hooks/hooks.json              Codex's default plugin hooks location; matcher-group
  *                                 shape with `${PLUGIN_ROOT}` paths and `async` observers
- *                                 (developers.openai.com/plugins/build/plugins, 2026-09-10)
+ *                                 (developers.openai.com/plugins/build/plugins, 2026-09-10).
+ *                                 NOT LOADED BY CODEX for this bundle: a root plugin.json
+ *                                 with the agent-plugins.org schema makes Codex treat the
+ *                                 plugin as an Agent Plugin, and its loader then skips
+ *                                 hooks entirely (codex-rs/core-plugins/src/loader.rs,
+ *                                 "Enforce Agent Plugin runtime boundaries" #37027,
+ *                                 2026-08-05; same at rust-v0.163.0; read 2026-10-19, R55).
+ *                                 Codex users get PAN's hooks from a `--codex` install
+ *                                 (.codex/hooks.json). Kept for the other consumers.
  *   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
@@ -90,25 +98,35 @@ function emitSkills(srcDir, skillsDir, prefix) {
       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() });
-      const { skill, reference } = lib.splitOversizedSkill(content, skillName);
-      fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skill);
-      if (reference) {
-        const refPath = path.join(skillDir, ...lib.AGENT_PLUGIN_SKILL_REFERENCE.split('/'));
-        fs.mkdirSync(path.dirname(refPath), { recursive: true });
-        fs.writeFileSync(refPath, reference);
-        split++;
-      }
+      if (emitSkill(fs.readFileSync(srcPath, 'utf8'), skillsDir, skillName)) split++;
       count++;
     }
   })(srcDir, prefix);
+  // Renamed commands keep their old names as aliases, as the installer writes them (L7).
+  const { COMMAND_ALIASES } = require(path.join(ROOT, 'pan-wizard-core', 'bin', 'lib', 'constants.cjs'));
+  for (const [oldName, alias] of Object.entries(COMMAND_ALIASES)) {
+    const target = fs.readFileSync(path.join(srcDir, `${alias.to}.md`), 'utf8');
+    if (emitSkill(lib.renderCommandAlias(target, oldName, alias), skillsDir, `${prefix}-${oldName}`)) split++;
+    count++;
+  }
   return { count, split };
 }
 
+/** One command → skills/<name>/SKILL.md (plus a reference file when split). Returns true when split. */
+function emitSkill(content, skillsDir, skillName) {
+  const skillDir = path.join(skillsDir, skillName);
+  fs.mkdirSync(skillDir, { recursive: true });
+  content = lib.rewriteUnifiedSkillCommandContent(content, REWRITE);
+  content = lib.convertClaudeCommandToUnifiedSkill(content, skillName, { adapterNote: lib.agentPluginSkillAdapterNote() });
+  const { skill, reference } = lib.splitOversizedSkill(content, skillName);
+  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skill);
+  if (!reference) return false;
+  const refPath = path.join(skillDir, ...lib.AGENT_PLUGIN_SKILL_REFERENCE.split('/'));
+  fs.mkdirSync(path.dirname(refPath), { recursive: true });
+  fs.writeFileSync(refPath, reference);
+  return true;
+}
+
 /** pan-wizard-core → bundle, markdown rewritten, everything else verbatim. */
 function emitCore(srcDir, destDir) {
   (function recurse(currentSrc, currentDest) {
@@ -133,6 +151,8 @@ function emitCore(srcDir, destDir) {
     if (err.code !== 'ENOENT') throw err;
   }
   fs.writeFileSync(path.join(destDir, 'VERSION'), pkg.version);
+  // `/pan:update` points at the installed changelog, as a loose-file install carries it.
+  fs.copyFileSync(path.join(ROOT, 'CHANGELOG.md'), path.join(destDir, 'CHANGELOG.md'));
 }
 
 /** Canonical agent reference copies under <core>/agents/ (ADR-0028). */

package/scripts/build-help.cjs

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

package/scripts/build-plugin.js

@@ -111,7 +111,14 @@ function main() {
   );
 
   // 2. Commands (Claude flavor, plugin-root-relative paths)
-  copyTree(path.join(ROOT, 'commands', 'pan'), path.join(OUT, 'commands', 'pan'), rewriteContent);
+  // Commands are user-invoked only on Claude Code (M49): out of the model's listing.
+  copyTree(path.join(ROOT, 'commands', 'pan'), path.join(OUT, 'commands', 'pan'), (c) => lib.withClaudeUserInvokedOnly(rewriteContent(c)));
+  // Renamed commands keep their old names as aliases, as the installer writes them (L7).
+  const { COMMAND_ALIASES } = require(path.join(ROOT, 'pan-wizard-core', 'bin', 'lib', 'constants.cjs'));
+  for (const [oldName, alias] of Object.entries(COMMAND_ALIASES)) {
+    const target = fs.readFileSync(path.join(ROOT, 'commands', 'pan', `${alias.to}.md`), 'utf8');
+    fs.writeFileSync(path.join(OUT, 'commands', 'pan', `${oldName}.md`), lib.withClaudeUserInvokedOnly(rewriteContent(lib.renderCommandAlias(target, oldName, alias))));
+  }
 
   // 3. Agents
   copyTree(path.join(ROOT, 'agents'), path.join(OUT, 'agents'), rewriteContent);
@@ -152,6 +159,8 @@ function main() {
   copyTree(path.join(ROOT, 'pan-wizard-core'), path.join(OUT, 'pan-wizard-core'), rewriteContent);
   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);
+  // `/pan:update` points at the installed changelog, as a loose-file install carries it.
+  fs.copyFileSync(path.join(ROOT, 'CHANGELOG.md'), path.join(OUT, 'pan-wizard-core', 'CHANGELOG.md'));
 
   // 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

package/scripts/deprecate-old-versions.js

@@ -156,6 +156,58 @@ function npmJson(args, fallback = null) {
   return JSON.parse(out);
 }
 
+/**
+ * Turn npm's stderr into the error that matters.
+ *
+ * WHY. npm writes warnings before the error, and on a GitHub runner the first
+ * line is setup-node's `npm warn Unknown user config "always-auth"` — present on
+ * every call, unrelated to any failure. Reporting only the first line made all 69
+ * failures across the 3.35.0 and 3.36.0 releases say that, hiding the cause. The
+ * real error is the `npm error code X` line plus the first other `npm error` line,
+ * skipping npm's closing "A complete log of this run..." pointer.
+ */
+function summarizeNpmError(stderr) {
+  const lines = String(stderr || '').split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  let code = null;
+  let detail = null;
+  for (const l of lines) {
+    const m = /^npm (?:error|ERR!)\s*(.*)$/.exec(l);
+    if (!m) continue;
+    const rest = m[1].trim();
+    const c = /^code\s+(\S+)$/.exec(rest);
+    if (c) { code = code || c[1]; continue; }
+    if (!detail && rest && !/^A complete log of this run/i.test(rest)) detail = rest;
+  }
+  if (!detail) detail = lines.find((l) => !/^npm (warn|notice)\b/i.test(l)) || null;
+  return { code, detail };
+}
+
+/** Auth refusals: every further call with the same credential fails the same way. */
+const AUTH_CODES = new Set(['E401', 'E403', 'EOTP', 'ENEEDAUTH']);
+function isAuthFailure(code) {
+  return AUTH_CODES.has(code);
+}
+
+/**
+ * What the owner has to change, per auth failure. `npm deprecate` cannot use the
+ * OIDC trusted-publishing credential (npm grants that for `npm publish` only), so
+ * it runs on the NPM_TOKEN secret, and each hint points at that secret.
+ */
+const AUTH_HINTS = {
+  E401: 'NPM_TOKEN is missing, expired or revoked — write-enabled granular tokens expire (90 days at most); create a new one and update the secret',
+  ENEEDAUTH: 'NPM_TOKEN is missing or empty — add it as a repository secret',
+  EOTP: 'NPM_TOKEN cannot get past 2FA — create the granular token with "Bypass 2FA" enabled',
+  E403: 'NPM_TOKEN has no write access to pan-wizard — give the granular token Read and write on the pan-wizard package',
+};
+
+/** One line for the log: `CODE: detail (hint)`, falling back to what npm or node said. */
+function formatNpmError(stderr, fallback = '') {
+  const { code, detail } = summarizeNpmError(stderr);
+  const text = detail || String(fallback || '').split('\n')[0] || 'unknown error';
+  const head = code ? `${code}: ${text}` : text;
+  return AUTH_HINTS[code] ? `${head} (${AUTH_HINTS[code]})` : head;
+}
+
 function main() {
   const args = process.argv.slice(2);
   const apply = args.includes('--apply');
@@ -185,7 +237,7 @@ function main() {
     // npm returns a bare string for a single version, or {version: message}.
     deprecatedAlready = (map && typeof map === 'object') ? Object.keys(map) : [];
   } catch (e) {
-    console.error(`deprecate: could not read the registry (${String(e.message).split('\n')[0]}). Nothing changed.`);
+    console.error(`deprecate: could not read the registry (${formatNpmError(e.stderr, e.message)}). Nothing changed.`);
     return; // never fail the build over housekeeping
   }
 
@@ -210,16 +262,31 @@ function main() {
       console.log(`  ✓ ${v}`);
     } catch (e) {
       failed++;
-      console.error(`  ✗ ${v}: ${String(e.stderr || e.message).split('\n')[0]}`);
+      console.error(`  ✗ ${v}: ${formatNpmError(e.stderr, e.message)}`);
+      // An auth refusal repeats identically for every remaining version — say it
+      // once and stop rather than printing the same line 35 times.
+      if (isAuthFailure(summarizeNpmError(e.stderr).code)) {
+        const skipped = deprecate.length - deprecate.indexOf(v) - 1;
+        if (skipped > 0) console.error(`  stopping: authentication refused — ${skipped} remaining version(s) not attempted.`);
+        break;
+      }
     }
   }
   if (failed) {
     // Reported, not fatal. The publish already succeeded; a red build here would
     // imply the release failed, which is false and worse than the omission.
     console.error(`deprecate: ${failed} of ${deprecate.length} failed — release is unaffected.`);
+    // continue-on-error hides a failed step inside the log; an annotation puts it
+    // on the run's summary page where the owner actually looks.
+    if (process.env.GITHUB_ACTIONS === 'true') {
+      console.log(`::warning title=Deprecation sweep failed::${failed} of ${deprecate.length} old versions were not deprecated — see the "Deprecate superseded versions" step log`);
+    }
   }
 }
 
 if (require.main === module) main();
 
-module.exports = { selectVersionsToDeprecate, buildMessage, parse, compare, assertQuotable };
+module.exports = {
+  selectVersionsToDeprecate, buildMessage, parse, compare, assertQuotable,
+  summarizeNpmError, formatNpmError, isAuthFailure,
+};

package/scripts/generate-skills-docs.py

@@ -517,7 +517,7 @@ def generate_reference(shipped: list[Skill], dev: list[Skill], version: str) ->
     w("| Continuous improvement | `focus-auto --category <cat>` |")
     w("| Execute micro-prompts | `focus-auto --category prompts` |")
     w("| Feature investigation | `focus-design \"description\"` |")
-    w("| Doc hygiene | `focus-drift-walking` or `focus-doc-audit` |")
+    w("| Doc hygiene | `focus-auto --step drift` or `focus-docs` |")
     w("")
 
     return "\n".join(lines)

package/scripts/git-hooks/pre-push

@@ -0,0 +1,27 @@
+#!/bin/sh
+# PAN Wizard pre-push hook — the fast subset of the local CI (scripts/local-ci.cjs --fast):
+# the suite on the current Node, the harness at tier 0, and gitleaks.
+#
+# Opt-in. core.hooksPath points every clone at this directory, so the hook is always
+# present; it does nothing until you turn it on for this clone:
+#   npm run hooks:pre-push              (git config pan.prePush true)
+#   npm run hooks:pre-push -- --off     (turn it off again)
+#
+# Bypass once:  SKIP_PREPUSH=1 git push   or   git push --no-verify
+#
+# Exit codes:
+#   0  off, bypassed, or every gate passed (a skipped gate is listed, not passed)
+#   1  a gate failed — read the summary and .ci-local/logs/ before pushing
+
+if [ "$(git config --bool pan.prePush 2>/dev/null)" != "true" ]; then
+  exit 0
+fi
+
+if [ "${SKIP_PREPUSH:-}" = "1" ]; then
+  echo "[pre-push] SKIP_PREPUSH=1 — local CI bypassed." >&2
+  exit 0
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+echo "[pre-push] local CI, fast subset (SKIP_PREPUSH=1 to bypass)…" >&2
+exec node "$REPO_ROOT/scripts/local-ci.cjs" --fast

package/scripts/install-git-hooks.js

@@ -57,12 +57,14 @@ try {
 //    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');
+// pre-push is tracked here too but stays inert until `npm run hooks:pre-push` opts in.
 if (process.platform !== 'win32') {
-  try {
-    fs.chmodSync(hookFile, 0o755);
-  } catch {
-    // Best effort.
+  for (const name of ['pre-commit', 'pre-push']) {
+    try {
+      fs.chmodSync(path.join(REPO_ROOT, HOOKS_DIR, name), 0o755);
+    } catch {
+      // Best effort.
+    }
   }
 }
 

package/scripts/install-pre-push.cjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * install-pre-push.cjs — turn the local-CI pre-push hook on or off for this clone
+ * (`npm run hooks:pre-push`, `npm run hooks:pre-push -- --off`).
+ *
+ * The hook itself is tracked at scripts/git-hooks/pre-push, where core.hooksPath already
+ * points (scripts/install-git-hooks.js). It is inert until `pan.prePush` is true in this
+ * clone's git config, so a fresh clone never runs the local CI on push unless its owner
+ * asked for it. This script sets or clears that key, and makes sure core.hooksPath is set.
+ *
+ * Exit 0 on success, 1 when git refuses.
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const off = process.argv.includes('--off');
+
+function git(args) {
+  const r = spawnSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8' });
+  if (r.status !== 0 && !(off && args.includes('--unset'))) {
+    console.error(`[pre-push] git ${args.join(' ')} failed: ${(r.stderr || r.error && r.error.message || '').trim()}`);
+    process.exit(1);
+  }
+  return r;
+}
+
+if (off) {
+  git(['config', '--local', '--unset', 'pan.prePush']);
+  console.error('[pre-push] off — git push no longer runs the local CI.');
+} else {
+  git(['config', '--local', 'core.hooksPath', 'scripts/git-hooks']);
+  git(['config', '--local', 'pan.prePush', 'true']);
+  console.error('[pre-push] on — git push runs `node scripts/local-ci.cjs --fast` first (SKIP_PREPUSH=1 to bypass once; --off to remove).');
+}