pan-wizard 3.36.0 → 3.37.0

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).');
+}

package/scripts/land.cjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * land.cjs — land a branch on main without a pull request (`npm run land -- <branch>`;
+ * local-first plan, phase 3). GitHub stays the mirror: main is pushed there, never forced.
+ *
+ * Refuses unless:
+ *   - a full `npm run ci:local` passed on the branch's current HEAD, from a tree with no
+ *     uncommitted changes, with no gate skipped (scripts/local-ci.cjs records the verdict in
+ *     the git directory, pan-ci-local/<sha>.json, shared by every worktree);
+ *   - the branch contains origin/main, so the squash commit's tree is exactly the tree
+ *     ci:local passed (merge or rebase main into the branch and run ci:local again if not);
+ *   - the checkout that has main (or a temporary one) is clean and main can fast-forward
+ *     to origin/main.
+ *
+ * Then: fetch origin, fast-forward main to origin/main, `git merge --squash <branch>`, commit
+ * with the branch's summary (the title is its first commit's subject, or --title; the body
+ * lists every commit), and `git push origin main`. A rejected push leaves the commit on the
+ * local main and says so; nothing is forced, and the branch itself is left alone.
+ *
+ * Usage:
+ *   node scripts/land.cjs <branch> [--title "..."] [--dry-run] [--no-push] [--allow-skips]
+ *        [--remote origin] [--main main]
+ * Exit 0 landed (or the dry run would land), 1 refused or failed, 2 usage.
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function git(cwd, args, opts = {}) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, ...opts });
+  return { ok: r.status === 0, out: (r.stdout || '').trim(), err: (r.stderr || '').trim() || (r.error ? r.error.message : '') };
+}
+
+function parseArgs(argv) {
+  const a = { branch: null, title: null, dryRun: false, push: true, allowSkips: false, remote: 'origin', main: 'main' };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === '--title') a.title = argv[++i];
+    else if (k === '--dry-run') a.dryRun = true;
+    else if (k === '--no-push') a.push = false;
+    else if (k === '--allow-skips') a.allowSkips = true;
+    else if (k === '--remote') a.remote = argv[++i];
+    else if (k === '--main') a.main = argv[++i];
+    else if (k.startsWith('--')) throw new Error(`unknown option: ${k}`);
+    else if (!a.branch) a.branch = k;
+    else throw new Error(`one branch at a time (got ${a.branch} and ${k})`);
+  }
+  if (!a.branch) throw new Error('usage: land.cjs <branch> [--title T] [--dry-run] [--no-push] [--allow-skips]');
+  return a;
+}
+
+/** Why ci:local's verdict does not clear `sha` for landing, or null when it does. Pure. */
+function verdictProblem(verdict, sha, { allowSkips = false } = {}) {
+  if (!verdict) return `no ci:local verdict for ${sha.slice(0, 9)} — run \`npm run ci:local\` on the branch at that commit`;
+  if (verdict.headFull !== sha) return `the verdict is for ${String(verdict.headFull).slice(0, 9)}, not ${sha.slice(0, 9)}`;
+  if (verdict.options && (verdict.options.only || verdict.options.fast)) return 'the verdict is from a partial run (--only or --fast); run the full ci:local';
+  if (verdict.dirtyAtStart !== false) return 'ci:local ran with uncommitted changes, so it did not test this commit alone; commit or stash them and run it again';
+  if (verdict.status !== 'pass') return `ci:local failed on ${sha.slice(0, 9)}: ${(verdict.gates || []).filter(g => g.status === 'fail').map(g => g.id).join(', ') || 'see its report'}`;
+  const skipped = (verdict.gates || []).filter(g => g.status === 'skip').map(g => g.id);
+  if (skipped.length && !allowSkips) return `ci:local skipped ${skipped.join(', ')}; install what they need, or pass --allow-skips`;
+  return null;
+}
+
+/** The squash commit's message: a title, and the branch's commits as the body. Pure. */
+function commitMessage(branch, subjects, title) {
+  const head = title || subjects[0] || `Land ${branch}`;
+  const body = subjects.length > 1 || (title && subjects.length) ? `\n\nSquashed from ${branch}:\n${subjects.map(s => `- ${s}`).join('\n')}` : '';
+  return `${head}${body}\n`;
+}
+
+// The worktree that has `main` checked out, if any.
+function mainCheckout(cwd, main) {
+  const list = git(cwd, ['worktree', 'list', '--porcelain']).out;
+  for (const block of list.split(/\n\n+/)) {
+    const wt = (block.match(/^worktree (.+)$/m) || [])[1];
+    if (wt && new RegExp(`^branch refs/heads/${main.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`, 'm').test(block)) return path.resolve(wt);
+  }
+  return null;
+}
+
+function land(argv, cwd = process.cwd(), log = console.log) {
+  let o;
+  try { o = parseArgs(argv); } catch (e) { log(`land: ${e.message}`); return 2; }
+  const refuse = (why) => { log(`land: refused — ${why}`); return 1; };
+
+  const sha = git(cwd, ['rev-parse', '--verify', `refs/heads/${o.branch}^{commit}`]);
+  if (!sha.ok) return refuse(`no local branch ${o.branch}`);
+  if (o.branch === o.main) return refuse(`${o.branch} is the branch it would land on`);
+
+  const common = path.resolve(cwd, git(cwd, ['rev-parse', '--git-common-dir']).out);
+  let verdict = null;
+  try { verdict = JSON.parse(fs.readFileSync(path.join(common, 'pan-ci-local', `${sha.out}.json`), 'utf8')); } catch { /* none */ }
+  const problem = verdictProblem(verdict, sha.out, o);
+  if (problem) return refuse(problem);
+
+  const fetched = git(cwd, ['fetch', o.remote, o.main]);
+  if (!fetched.ok) return refuse(`git fetch ${o.remote} ${o.main}: ${fetched.err}`);
+  const upstream = `refs/remotes/${o.remote}/${o.main}`;
+  if (!git(cwd, ['merge-base', '--is-ancestor', upstream, sha.out]).ok) {
+    return refuse(`${o.branch} does not contain ${o.remote}/${o.main}; merge or rebase it onto ${o.remote}/${o.main}, then run ci:local again`);
+  }
+  const subjects = git(cwd, ['log', '--reverse', '--format=%s', `${upstream}..${sha.out}`]).out.split('\n').filter(Boolean);
+  if (!subjects.length) return refuse(`${o.branch} has nothing that ${o.remote}/${o.main} lacks`);
+  const message = commitMessage(o.branch, subjects, o.title);
+
+  let where = mainCheckout(cwd, o.main);
+  if (where && git(where, ['status', '--porcelain']).out) return refuse(`the checkout with ${o.main} (${where}) has uncommitted changes`);
+  if (o.dryRun) {
+    log(`land: would squash ${subjects.length} commit(s) of ${o.branch} (${sha.out.slice(0, 9)}) onto ${o.remote}/${o.main} in ${where || 'a temporary worktree'}${o.push ? ` and push ${o.main} to ${o.remote}` : ''}:\n\n${message}`);
+    return 0;
+  }
+
+  let temp = null;
+  if (!where) {
+    temp = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-land-'));
+    const hasMain = git(cwd, ['rev-parse', '--verify', `refs/heads/${o.main}`]).ok;
+    const add = git(cwd, hasMain ? ['worktree', 'add', temp, o.main] : ['worktree', 'add', '-b', o.main, temp, upstream]);
+    if (!add.ok) { fs.rmSync(temp, { recursive: true, force: true }); return refuse(`could not check out ${o.main}: ${add.err}`); }
+    where = temp;
+  }
+  try {
+    const ff = git(where, ['merge', '--ff-only', upstream]);
+    if (!ff.ok) return refuse(`local ${o.main} cannot fast-forward to ${o.remote}/${o.main} (it has commits ${o.remote} lacks): ${ff.err}`);
+    const sq = git(where, ['merge', '--squash', sha.out]);
+    if (!sq.ok) { git(where, ['reset', '--merge']); return refuse(`the squash merge failed: ${sq.err}`); }
+    // The branch contains main, so the result is the branch's tree: anything else is a bug here.
+    const tree = git(where, ['write-tree']).out;
+    const want = git(cwd, ['rev-parse', `${sha.out}^{tree}`]).out;
+    if (tree !== want) { git(where, ['reset', '--hard', upstream]); return refuse(`the squashed tree ${tree.slice(0, 9)} is not the tree ci:local passed (${want.slice(0, 9)})`); }
+    const commit = git(where, ['commit', '--no-verify', '-F', '-'], { input: message });
+    if (!commit.ok) { git(where, ['reset', '--merge']); return refuse(`git commit: ${commit.err}`); }
+    const landed = git(where, ['rev-parse', 'HEAD']).out;
+    log(`land: ${o.branch} squashed onto ${o.main} as ${landed.slice(0, 9)}`);
+    if (!o.push) { log(`land: not pushed (--no-push); push with \`git push ${o.remote} ${o.main}\``); return 0; }
+    // Never forced: a push the remote rejects (it moved, or branch protection) stops here.
+    const push = git(where, ['push', o.remote, `refs/heads/${o.main}:refs/heads/${o.main}`]);
+    if (!push.ok) { log(`land: the push to ${o.remote} was rejected; ${landed.slice(0, 9)} is on the local ${o.main} only:\n${push.err}`); return 1; }
+    log(`land: pushed ${o.main} to ${o.remote}`);
+    return 0;
+  } finally {
+    if (temp) { git(cwd, ['worktree', 'remove', '--force', temp]); fs.rmSync(temp, { recursive: true, force: true }); }
+  }
+}
+
+module.exports = { parseArgs, verdictProblem, commitMessage, mainCheckout, land };
+
+if (require.main === module) process.exit(land(process.argv.slice(2)));