pan-wizard 3.24.0 → 3.26.0

package/{pan-zcode → pan-wizard-core}/mcp/server.cjs

@@ -1,10 +1,15 @@
 'use strict';
 
 /**
- * PAN-Z MCP bridge server (M1).
+ * PAN MCP bridge server.
  *
- * A dependency-free JSON-RPC 2.0 server over stdio implementing the small MCP
- * surface ZCode needs: server/discover / initialize / tools/list / tools/call /
+ * Canonical home: `pan-wizard-core/mcp/`, so it ships with the engine to every
+ * install and every runtime. It was originally written for the PAN-Z/ZCode
+ * preview (`pan-zcode/`), which remains a CONSUMER rather than the owner — the
+ * protocol layer is harness-neutral and must not be forked per consumer.
+ *
+ * A dependency-free JSON-RPC 2.0 server over stdio implementing a small MCP
+ * surface: server/discover / initialize / tools/list / tools/call /
  * resources/list / resources/read / ping. It is a DUAL-ERA server (see the MCP
  * 2026-07-28 versioning spec): legacy clients open with the `initialize`
  * handshake; modern clients (2026-07-28+) declare their protocol version in each
@@ -47,9 +52,27 @@ const SUPPORTED_VERSIONS_LIST = [MODERN_PROTOCOL_VERSION, '2025-06-18', '2025-03
 const SUPPORTED_PROTOCOL_VERSIONS = new Set(SUPPORTED_VERSIONS_LIST);
 const SERVER_INFO = { name: 'pan-mcp', version: '0.1.0' };
 
-/** Default engine location: pan-wizard-core is a sibling of pan-zcode/. */
+/**
+ * Default engine location: `bin/` is a sibling of this `mcp/` directory inside
+ * pan-wizard-core. That holds in the source repo AND in every install, because
+ * the installer copies pan-wizard-core wholesale, so the two stay siblings
+ * wherever the tree lands. Callers can still override via `opts.panToolsPath`
+ * (an out-of-tree engine, a test fixture, a pinned version) or PAN_TOOLS_PATH.
+ *
+ * This replaced `join(__dirname, '..', '..', 'pan-wizard-core', 'bin', …)`,
+ * carried over from when the module lived in `pan-zcode/mcp/`. Do NOT record
+ * that as a bug the relocation fixed — from this directory the two forms
+ * resolve to the identical path (the grandparent of `mcp/` contains
+ * `pan-wizard-core/` in both the source tree and an install). The old form is
+ * merely over-specified: it requires the grandparent to hold a directory
+ * *named* `pan-wizard-core`, so it breaks if the core is vendored or renamed,
+ * while the sibling form only requires the layout it actually depends on.
+ * Covered by the "engine path resolution" suite in tests/pan-zcode-mcp.test.cjs,
+ * which exists because every other test injects a spawn or passes an explicit
+ * path — so this function had zero coverage when the module moved.
+ */
 function defaultPanToolsPath() {
-  return path.join(__dirname, '..', '..', 'pan-wizard-core', 'bin', 'pan-tools.cjs');
+  return path.join(__dirname, '..', 'bin', 'pan-tools.cjs');
 }
 
 /** Real spawn: shell-less execFile of `node <argv...>`. */
@@ -176,7 +199,13 @@ function createServer(opts = {}) {
   function readResource(uri) {
     const res = reg.byResourceUri[uri];
     if (!res) return { unknown: true };
-    const r = runVerb(res.verb, []);
+    // A resource's argv tail is a STATIC array on its descriptor (for verbs whose
+    // read is a subcommand, e.g. `validate health`). It never derives from the
+    // request: resources take no client parameters, so there is no input path into
+    // this argv. Guard the type anyway — a descriptor typo must not spread a
+    // non-array into the spawn.
+    const tail = Array.isArray(res.args) ? res.args : [];
+    const r = runVerb(res.verb, tail);
     if (!r.ok) return { error: { code: -32603, message: r.stderr || 'resource read failed' } };
     return { result: { contents: [{ uri, mimeType: 'application/json', text: r.stdout }] } };
   }

package/{pan-zcode → pan-wizard-core}/mcp/tool-registry.cjs

@@ -28,12 +28,45 @@ const AGENT_RE = /^[a-z][a-z0-9_-]{1,60}$/;   // agent type, e.g. pan-planner
 const PHASE_RE = /^[0-9]{1,3}$/;              // phase number, e.g. 03
 const QUERY_RE = /^[\w .,:/&()-]{1,120}$/;    // find-phase query fragment
 
-/** Read-only aggregators → MCP resources (no side effects). */
+/**
+ * Read-only aggregators → MCP resources (no side effects).
+ *
+ * Optional `args` is a STATIC argv tail for verbs whose read lives in a
+ * subcommand (`validate health`, `links validate`, `cost report`). It is
+ * deliberately a fixed array and never a function of client input — a resource
+ * takes no parameters, and that is precisely what makes the surface safe: there
+ * is no path from an LLM tool-call to these argv elements.
+ *
+ * THE RULE FOR ADDING ONE — a resource must be readable on ANY project, including
+ * a bare directory with no `.planning/`. If "no data yet" is reported as an error
+ * (non-zero exit / an error-family key), it is a TOOL, not a resource: a client
+ * that lists resources and reads them should not collect failures for a young
+ * project. `preview` is the worked example — `preview phases` exits non-zero
+ * without a roadmap, so it is exposed as a tool below rather than as a resource.
+ * Check before adding: run the verb in an empty dir and read `$?`.
+ */
 const RESOURCES = [
   { uri: 'pan://state',    name: 'Project state', verb: 'state',    description: 'Current PAN project state snapshot derived from .planning/.' },
-  { uri: 'pan://roadmap',  name: 'Roadmap',       verb: 'roadmap',  description: 'The project roadmap: phases, goals, success criteria.' },
-  { uri: 'pan://phases',   name: 'Phases',        verb: 'phases',   description: 'Phase inventory with per-phase status.' },
+  // NOTE: there is deliberately no `pan://roadmap`. One existed and was DEAD from
+  // M1 until 2026-08 — its descriptor named the bare verb `roadmap`, which requires
+  // a subcommand, so every read returned "Unknown roadmap subcommand". Nothing
+  // caught it because the protocol tests inject a fake spawn, so no test had ever
+  // run a resource against the real engine. It is now `pan_roadmap_analyze` in
+  // TOOLS: `roadmap analyze` exits non-zero on a project with no roadmap.md, which
+  // fails the resource rule above. Removing the URI breaks no consumer — no
+  // consumer can have depended on a read that always errored.
+  // `phases` alone is not a verb — the subcommand is `list`. This descriptor named
+  // the bare verb and was DEAD from M1 alongside pan://roadmap, for the same reason
+  // and found by the same test. Returns {directories, count}.
+  { uri: 'pan://phases',   name: 'Phases',        verb: 'phases',   args: ['list'],
+    description: 'Phase inventory: the phase directories present, with a count.' },
   { uri: 'pan://progress', name: 'Progress',      verb: 'progress', description: 'Requirement and plan completion progress.' },
+  { uri: 'pan://health',   name: 'Project health', verb: 'validate', args: ['health'],
+    description: 'Health check over .planning/: issue codes with severities. Reports an unhealthy project as DATA (exit 0), so it is readable even on a broken or empty one.' },
+  { uri: 'pan://links',    name: 'Doc-code links', verb: 'links',   args: ['validate'],
+    description: 'Doc↔code link graph verdict: forward links, backlink contracts, and anchor targets, with finding codes.' },
+  { uri: 'pan://cost',     name: 'Token cost',     verb: 'cost',    args: ['report'],
+    description: 'Aggregated token spend from the .planning/metrics ledger. Reads as zeros on a project with no recorded calls.' },
 ];
 
 /** Actionable pan-tools verbs → MCP tools (each spawns `node pan-tools.cjs <verb>`). */
@@ -58,6 +91,30 @@ const SPAWN_TOOLS = [
     },
     args: (i) => [str('query', i && i.query, QUERY_RE, 120)],
   },
+  {
+    name: 'pan_roadmap_analyze', title: 'Analyze the roadmap', verb: 'roadmap',
+    description: 'The roadmap read: milestones, phases, goals and success criteria with completion analysis. A tool rather than a resource because it reports a project with no roadmap.md as an error.',
+    readOnly: true, destructive: false,
+    inputSchema: { type: 'object', additionalProperties: false, properties: {} },
+    args: () => ['analyze'],
+  },
+  {
+    name: 'pan_preview_phases', title: 'Preview all phases (dependency graph)', verb: 'preview',
+    description: 'Phase dependency graph: a mermaid DAG, the parallel-executable batches, and any hidden dependencies. Errors on a project with no roadmap, which is why this is a tool rather than a resource.',
+    readOnly: true, destructive: false,
+    inputSchema: { type: 'object', additionalProperties: false, properties: {} },
+    args: () => ['phases'],
+  },
+  {
+    name: 'pan_preview_phase', title: 'Preview one phase (blast radius)', verb: 'preview',
+    description: 'Blast radius for a single phase: what it touches and what depends on it, before any work starts.',
+    readOnly: true, destructive: false,
+    inputSchema: {
+      type: 'object', additionalProperties: false, required: ['phase'],
+      properties: { phase: { type: 'string', description: 'Phase number, e.g. 03' } },
+    },
+    args: (i) => ['phase', str('phase', i && i.phase, PHASE_RE, 3)],
+  },
   {
     name: 'pan_report_phase', title: 'Generate a phase HTML report', verb: 'report',
     description: 'Render the self-contained HTML report for one phase (a build deliverable). Writes only its own file; non-destructive and idempotent.',

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

@@ -88,11 +88,18 @@ This step provides awareness; the hard gate is enforced by exec-phase.
 
 This step catches test regressions that goal-backward analysis cannot detect.
 
-1. Detect test command:
+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.
+
 ```bash
-TEST_CMD=$(node -e "const p=require('./package.json'); console.log(p.scripts && p.scripts.test || 'echo no test')")
+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')}")
 ```
 
+   **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.
+
 2. Run test suite and capture results:
 ```bash
 TEST_OUTPUT=$(npm test 2>&1)
@@ -102,13 +109,25 @@ TEST_PASS=$(echo "$TEST_OUTPUT" | grep -E "^ℹ pass" | awk '{print $NF}')
 TEST_FAIL=$(echo "$TEST_OUTPUT" | grep -E "^ℹ fail" | awk '{print $NF}')
 ```
 
-3. Evaluate results:
+3. Evaluate results.
+
+**Check `TEST_EXIT` FIRST, before any count.** A suite that did not run emits no
+`ℹ 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.
 
 | Condition | Action |
 |-----------|--------|
-| All tests pass (`TEST_FAIL` = 0) | Record counts, continue to must-haves |
-| Tests regress (failures exist) | Set `test_gate_status: failed`, include failure details in verification report |
-| No test command found | Record as `test_gate_status: skipped`, continue |
+| `TEST_EXIT` = 0 **and** `TEST_FAIL` = 0 (a real number) | Record counts, continue to must-haves |
+| `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` |
+
+**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`.
 
 4. Store test gate results for inclusion in verification.md:
 ```

package/pan-zcode/README.md

@@ -16,27 +16,35 @@ ZCode through the one interface it speaks: **MCP**.
 ```
 ZCode harness (GLM-5.2)          primary Agent drives everything; ported subagents fan out
         │  MCP · local stdio
-pan-zcode/mcp  (this subsystem)  a thin, zero-dep bridge — verbs → MCP tools/resources
-        │  spawn: node pan-tools.cjs <verb> --raw --cwd <root>
+pan-wizard-core/mcp  (SHARED)    a thin, zero-dep bridge — verbs → MCP tools/resources
+        │  spawn: node pan-tools.cjs <verb> --cwd <root>
 pan-wizard-core  (reused as-is)  the deterministic engine; .planning/ stays the state store
 ```
 
+**The bridge is no longer part of this subsystem.** It was written here, but it lives at
+`pan-wizard-core/mcp/` so it ships with the engine to every install and every runtime — PAN-Z
+is now a **consumer** of it, alongside the main installer. `install-zcode.js` emits an MCP
+registration pointing at that shared path. **Never fork a copy back under `pan-zcode/`**: one
+protocol layer, many consumers, or the two drift the way the per-runtime command trees did
+before ADR-0028.
+
 **Scope boundary (by design):** the bridge exposes `pan-tools` verbs as MCP tools/resources and nothing more. It intentionally does **not** carry rich agent *session state* — diffs, streaming, live thread lifecycle — because MCP can't faithfully represent it (the reason OpenAI built the Codex harness as a native Rust core rather than over MCP). Keep the bridge to tool/resource exposure; the CLI's JSON contract is the tool contract. See `KNOWN-BETA-RISKS.md`.
 
 ## Status — M1–M5 built (M0 is the human verify spike)
 
-- **M1 — bridge core.** `mcp/tool-registry.cjs` (pure verb→tool/resource map, with a hard
-  guardrail against exposing a force/reset/rebase/push verb) + `mcp/server.cjs` (a
+- **M1 — bridge core.** `pan-wizard-core/mcp/tool-registry.cjs` (pure verb→tool/resource map, with a hard
+  guardrail against exposing a force/reset/rebase/push verb) + `pan-wizard-core/mcp/server.cjs` (a
   **zero-dependency** JSON-RPC 2.0 stdio MCP server; reads → resources, actions → tools with
   accurate hints; shell-less `execFile` spawn; `@file:` overflow protocol; strict per-arg
   validation). **Dual-era** per the MCP 2026-07-28 stateless spec (ADR-0041): legacy clients
   use the `initialize` handshake; modern clients declare their protocol version in each
   request's `_meta`, probe `server/discover`, and get `UnsupportedProtocolVersionError`
   (`-32022`) on a version mismatch.
-- **M2 — determinism grafts.** `mcp/merge-gate.cjs` (two-step, model-proof merge: a human-origin
-  env token that ignores agent-supplied approval; never force/reset/push) + `mcp/orchestrator.cjs`
-  (the deterministic `next-action` state machine with safety caps + regression circuit-breaker),
-  exposed as native MCP tools via `mcp/native-tools.cjs`.
+- **M2 — determinism grafts.** `pan-wizard-core/mcp/merge-gate.cjs` (two-step, model-proof merge: a
+  human-origin env token that ignores agent-supplied approval; never force/reset/push) +
+  `pan-wizard-core/mcp/orchestrator.cjs` (the deterministic `next-action` state machine with safety
+  caps + regression circuit-breaker), exposed as native MCP tools via
+  `pan-wizard-core/mcp/native-tools.cjs`.
 - **M3 — content port.** `lib/convert-agent.cjs` — Claude agents → ZCode subagents (reusing the
   installer's frontmatter helpers): drops `Task` (no nesting), maps PAN tiers → `inherit`,
   preserves the body; plus a command → skill wrapper.
@@ -59,7 +67,7 @@ A third M0 checkpoint (added 2026-08): **which protocol era does the real ZCode
 The bridge is now dual-era (ADR-0041), so it answers both a legacy `initialize` handshake and a
 modern `server/discover` probe. Confirm on a real install which path ZCode takes and that the
 version it declares is in our supported list; if ZCode ever declares a revision newer than
-`2026-07-28`, add it to `SUPPORTED_VERSIONS_LIST` in `mcp/server.cjs` once its method shapes are
+`2026-07-28`, add it to `SUPPORTED_VERSIONS_LIST` in `pan-wizard-core/mcp/server.cjs` once its method shapes are
 implemented.
 
 ## Zero dependencies

package/pan-zcode/bin/install-zcode.js

@@ -98,7 +98,10 @@ function buildBundle(o) {
   assertNotInSourceRepo(destDir, repoRoot);
 
   const agentsSrc = path.join(repoRoot, 'agents');
-  const serverPath = path.join(repoRoot, 'pan-zcode', 'mcp', 'server.cjs');
+  // The MCP protocol layer lives in pan-wizard-core/mcp/ (it ships with the
+  // engine to every install and every runtime). PAN-Z is a CONSUMER of it, not
+  // its owner — never fork a copy back under pan-zcode/, or the two drift.
+  const serverPath = path.join(repoRoot, 'pan-wizard-core', 'mcp', 'server.cjs');
   const panToolsPath = path.join(repoRoot, 'pan-wizard-core', 'bin', 'pan-tools.cjs');
 
   fs.mkdirSync(destDir, { recursive: true });

package/scripts/build-plugin.js

@@ -11,10 +11,23 @@
  *   pan-wizard-core/              dispatcher + modules + workflows + templates
  *
  * Distribution status: built ALONGSIDE the loose-file installer. Marketplace
- * publishing is gated on one live verification — whether ${CLAUDE_PLUGIN_ROOT}
+ * publishing WAS gated on one live verification — whether ${CLAUDE_PLUGIN_ROOT}
  * expands inside command markdown content (documented for hook/MCP configs
- * only). Until then, content references core paths relative to the plugin
- * root, which matches the documented plugin working layout.
+ * only).
+ *
+ * ANSWERED 2026-08-14, Claude Code 2.1.233 on Windows, by installing this plugin
+ * from the `command`-source marketplace in `marketplace/` and running
+ * `/pan-plugin-selftest`: **it does expand.** The command body reached the model
+ * with a real absolute path — no placeholder text survived — and invoking
+ * pan-tools through that path worked. So the CONTENT_PREFIX rewrite below is
+ * correct as it stands, and the gate is lifted.
+ *
+ * One measurement from the same run that constrains how far to take this: the
+ * `CLAUDE_PLUGIN_ROOT` environment variable is NOT exported into the Bash tool's
+ * environment (it read as empty). Textual substitution and shell expansion are
+ * therefore NOT interchangeable — generated content must keep using the
+ * substituted form, because `$CLAUDE_PLUGIN_ROOT` evaluated by a shell at runtime
+ * expands to nothing. Re-measure before relying on the shell form anywhere.
  *
  * Usage: node scripts/build-plugin.js  (or npm run build:plugin)
  */
@@ -88,6 +101,25 @@ function main() {
     }
   }
 
+  // 2b. Plugin-only self-test command. NOT copied from commands/pan/ — it is
+  // generated here so the shipped command set stays unchanged and no ordinary
+  // install gains a diagnostic. It answers the one question gating publication:
+  // whether CONTENT_PREFIX expands inside command markdown. The placeholder must
+  // reach the plugin UNEXPANDED or the probe measures nothing, so this write
+  // deliberately bypasses rewriteContent().
+  fs.writeFileSync(
+    path.join(OUT, 'commands', 'pan-plugin-selftest.md'),
+    lib.buildPluginSelfTestCommand(CONTENT_PREFIX.replace(/\/$/, ''))
+  );
+
+  // 4b. MCP registration. The server itself rides along inside pan-wizard-core
+  // (step 5 copies it wholesale), but shipping it is not the same as declaring
+  // it — without this file the plugin carried the bridge and never registered it.
+  fs.writeFileSync(
+    path.join(OUT, '.mcp.json'),
+    JSON.stringify(lib.buildPluginMcpConfig(), null, 2) + '\n'
+  );
+
   // 5. Core (strip source-only internal learnings, same policy as the installer)
   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 });

package/scripts/deprecate-old-versions.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * Deprecate published versions that have fallen far enough behind.
+ *
+ * WHY. Old releases stay installable forever, and `npm install pan-wizard@3.20.0`
+ * silently gives someone a build from several cycles ago with none of the fixes
+ * since. Deprecation is the honest signal: the version keeps working, keeps
+ * resolving, and anyone installing it sees a warning telling them what to move to.
+ *
+ * WHY DEPRECATE AND NEVER UNPUBLISH. Unpublishing removes a tarball other people
+ * may depend on and is refused by npm outside a 72-hour window anyway. Deprecation
+ * is additive, reversible (`npm deprecate <pkg>@<ver> ""` clears it), and breaks
+ * nobody. **This script must never gain an unpublish path.**
+ *
+ * THE RULE. Keep the newest N stable releases (default 3 — the one just published
+ * plus the two behind it) and deprecate every stable release older than those.
+ * Prereleases are never counted as "kept": once a stable release exists that
+ * supersedes them they are deprecated too, since an rc is not something anyone
+ * should be installing after the real release shipped.
+ *
+ * SAFETY, in the order it matters:
+ *   - DRY RUN BY DEFAULT. `--apply` is required to change anything.
+ *   - The version being released is never deprecated, even if the arithmetic
+ *     somehow selects it — an explicit guard, not a consequence.
+ *   - Already-deprecated versions are skipped, so re-running is a no-op.
+ *   - A failure to deprecate NEVER fails the build. By the time this runs the
+ *     publish has already succeeded; turning a housekeeping failure into a red
+ *     release would be strictly worse than leaving an old version undeprecated.
+ *
+ * Usage:
+ *   node scripts/deprecate-old-versions.js                 # dry run, keep 3
+ *   node scripts/deprecate-old-versions.js --apply         # actually deprecate
+ *   node scripts/deprecate-old-versions.js --keep 5 --apply
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+const PKG = 'pan-wizard';
+const DEFAULT_KEEP = 3;
+
+/**
+ * Parse a semver string into comparable parts. Returns null for anything that is
+ * not `major.minor.patch[-prerelease]`, so junk sorts out rather than throwing.
+ */
+function parse(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(String(v || '').trim());
+  if (!m) return null;
+  return {
+    version: v,
+    nums: [Number(m[1]), Number(m[2]), Number(m[3])],
+    pre: m[4] || null,
+  };
+}
+
+/**
+ * Compare two parsed versions, ascending. Prerelease-aware: 3.26.0-rc.1 sorts
+ * BELOW 3.26.0, which the update-check hook's comparator deliberately does not do
+ * (it ignores the suffix). Getting this backwards would deprecate a real release
+ * in favour of its own release candidate, so it is implemented here rather than
+ * reused.
+ */
+function compare(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a.nums[i] !== b.nums[i]) return a.nums[i] - b.nums[i];
+  }
+  if (a.pre === b.pre) return 0;
+  if (a.pre === null) return 1;   // release > prerelease
+  if (b.pre === null) return -1;
+  return a.pre < b.pre ? -1 : 1;  // lexical is good enough for rc.1 < rc.2
+}
+
+/**
+ * Decide what to deprecate. PURE — no network, no process — so the rule is
+ * testable without touching a registry.
+ *
+ * @param {string[]} published   every version on the registry
+ * @param {string} current       the version just released (never deprecated)
+ * @param {number} keep          how many newest STABLE releases to leave alone
+ * @param {string[]} [already]   versions already carrying a deprecation message
+ * @returns {{deprecate:string[], keep:string[], reason:Object<string,string>}}
+ */
+function selectVersionsToDeprecate(published, current, keep = DEFAULT_KEEP, already = []) {
+  const parsed = (published || []).map(parse).filter(Boolean).sort(compare);
+  const skip = new Set(already || []);
+  const stable = parsed.filter((p) => !p.pre);
+  // The newest `keep` stable releases are protected.
+  const kept = new Set(stable.slice(-keep).map((p) => p.version));
+  // The current release is protected regardless of where the arithmetic lands it.
+  kept.add(current);
+
+  const reason = {};
+  const deprecate = [];
+  for (const p of parsed) {
+    if (kept.has(p.version)) continue;
+    if (skip.has(p.version)) continue;
+    reason[p.version] = p.pre
+      ? `prerelease superseded by ${current}`
+      : `more than ${keep - 1} releases behind ${current}`;
+    deprecate.push(p.version);
+  }
+  return { deprecate, keep: [...kept].sort(), reason };
+}
+
+/** Message a deprecated version carries. Points at what to install instead. */
+function buildMessage(current) {
+  return `No longer maintained — install pan-wizard@${current} or later (npm i pan-wizard@latest).`;
+}
+
+// ─── IO layer ───────────────────────────────────────────────────────────────
+
+/**
+ * Run npm.
+ *
+ * WINDOWS: `npm` is a `.cmd` shim, so `execFileSync('npm', …)` fails ENOENT and
+ * `'npm.cmd'` fails EINVAL — the shim can only be launched through a shell. This
+ * is the same scar `runner.cjs` carries as its `shell: 'win32'` opt-in, and the
+ * first version of this script reproduced the bug: a local dry run reported
+ * "could not read the registry" and returned, so the fail-open path made a real
+ * platform bug look like a benign skip.
+ *
+ * QUOTING: with `shell: true` node CONCATENATES arguments rather than escaping
+ * them, so anything containing a space must be quoted or it arrives as several
+ * arguments — which matters here because the deprecation message is a sentence.
+ * Every argument is program-controlled (package name, versions read from the
+ * registry, our own message), so this is a correctness problem rather than an
+ * injection one, but it still has to be right. `assertQuotable` refuses a value
+ * carrying a double quote instead of emitting a broken command line.
+ */
+function assertQuotable(a) {
+  if (String(a).includes('"')) {
+    throw new Error(`refusing to shell-quote an argument containing a double quote: ${a}`);
+  }
+  return a;
+}
+
+function runNpm(args, opts = {}) {
+  const win = process.platform === 'win32';
+  const argv = win ? args.map((a) => (/\s/.test(a) ? `"${assertQuotable(a)}"` : a)) : args;
+  return execFileSync('npm', argv, {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], shell: win, ...opts,
+  });
+}
+
+/**
+ * `npm view <pkg> <field> --json` prints NOTHING when the field is unset across
+ * every version — which is exactly the healthy starting state for `deprecated`
+ * (nothing deprecated yet). `JSON.parse('')` throws, and the fail-open handler
+ * then reported "could not read the registry", turning the normal case into an
+ * apparent failure. Empty means absent, not broken.
+ */
+function npmJson(args, fallback = null) {
+  const out = runNpm(args);
+  if (!out || !out.trim()) return fallback;
+  return JSON.parse(out);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const apply = args.includes('--apply');
+  const keepIdx = args.indexOf('--keep');
+  const keep = keepIdx > -1 ? Number(args[keepIdx + 1]) : DEFAULT_KEEP;
+  const current = require('../package.json').version;
+
+  if (!Number.isInteger(keep) || keep < 1) {
+    console.error(`deprecate: --keep must be a positive integer, got ${keep}`);
+    process.exit(1);
+  }
+
+  // A prerelease must never trigger a deprecation sweep: it is not the thing
+  // users are being pointed at, and treating it as "the new release" would
+  // deprecate the current stable one.
+  if (parse(current) && parse(current).pre) {
+    console.log(`deprecate: ${current} is a prerelease — skipping (sweeps run for stable releases only).`);
+    return;
+  }
+
+  let published = [];
+  let deprecatedAlready = [];
+  try {
+    published = npmJson(['view', PKG, 'versions', '--json'], []);
+    if (!Array.isArray(published)) published = [published];
+    const map = npmJson(['view', PKG, 'deprecated', '--json'], {});
+    // 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.`);
+    return; // never fail the build over housekeeping
+  }
+
+  const { deprecate, keep: kept, reason } = selectVersionsToDeprecate(published, current, keep, deprecatedAlready);
+  const message = buildMessage(current);
+
+  console.log(`deprecate: current=${current} keep=${keep}`);
+  console.log(`  protected: ${kept.join(', ')}`);
+  if (deprecate.length === 0) {
+    console.log('  nothing to deprecate.');
+    return;
+  }
+  console.log(`  ${apply ? 'deprecating' : 'WOULD deprecate (dry run — pass --apply)'}: ${deprecate.length}`);
+  for (const v of deprecate) console.log(`    ${v}  — ${reason[v]}`);
+
+  if (!apply) return;
+
+  let failed = 0;
+  for (const v of deprecate) {
+    try {
+      runNpm(['deprecate', `${PKG}@${v}`, message]);
+      console.log(`  ✓ ${v}`);
+    } catch (e) {
+      failed++;
+      console.error(`  ✗ ${v}: ${String(e.stderr || e.message).split('\n')[0]}`);
+    }
+  }
+  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.`);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = { selectVersionsToDeprecate, buildMessage, parse, compare, assertQuotable };

package/scripts/plugin-path.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Print the absolute path of the built PAN plugin directory — the contract a
+ * Claude Code plugin-marketplace `command` source requires (v2.1.229+).
+ *
+ * WHY THIS EXISTS. PAN builds a plugin (`npm run build:plugin`) and has shipped
+ * it nowhere, because marketplace publishing is gated on one unverified
+ * question: does `${CLAUDE_PLUGIN_ROOT}` expand inside *command markdown*? It is
+ * documented as substituted in hook and MCP configs, not in content. A `command`
+ * source needs no hosting, so it turns that question into a local experiment —
+ * install the plugin from this script's output and run `/pan-plugin-selftest`.
+ *
+ * THE CONTRACT, verbatim from code.claude.com/docs/en/plugin-marketplaces:
+ *   - Claude Code runs the command "through the platform shell, `sh` on macOS and
+ *     Linux or `cmd.exe` on Windows, from the user's home directory". So NOTHING
+ *     here may depend on the working directory; every path is derived from
+ *     __dirname.
+ *   - "The command must print exactly one line on stdout and exit with code 0."
+ *     The plugin build is chatty, so its stdout is relayed to STDERR and only the
+ *     path reaches stdout. A stray console.log here breaks the install.
+ *   - The printed directory must hold plugin content at its top level, must not
+ *     be the directory Claude Code started in or one of its parents, and on
+ *     Windows must not be a UNC path.
+ *
+ * Rebuilding on every run is deliberate: Claude Code re-runs the command once per
+ * session in the background, so a source edit is picked up without reinstalling.
+ * In `copy` mode the version is a hash of the directory contents, so an unchanged
+ * build counts as up to date.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+
+const ROOT = path.join(__dirname, '..');
+const PLUGIN_DIR = path.join(ROOT, 'dist', 'pan-wizard-plugin');
+
+// Top-level markers Claude Code accepts as proof of plugin content.
+const PLUGIN_MARKERS = ['.claude-plugin', 'skills', 'commands', 'agents', 'hooks'];
+
+function fail(message) {
+  // stderr only — stdout is reserved for the single path line.
+  process.stderr.write(`plugin-path: ${message}\n`);
+  process.exit(1);
+}
+
+function build() {
+  try {
+    // Relay the builder's stdout to stderr so stdout stays single-line.
+    const out = execFileSync(process.execPath, [path.join(ROOT, 'scripts', 'build-plugin.js')], {
+      cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (out) process.stderr.write(out);
+  } catch (err) {
+    const detail = (err.stderr || err.stdout || err.message || '').toString().trim();
+    fail(`plugin build failed: ${detail.split('\n').slice(-3).join(' | ')}`);
+  }
+}
+
+function main() {
+  build();
+
+  if (!fs.existsSync(PLUGIN_DIR)) fail(`build produced no directory at ${PLUGIN_DIR}`);
+
+  const top = fs.readdirSync(PLUGIN_DIR);
+  if (!PLUGIN_MARKERS.some((m) => top.includes(m))) {
+    fail(`no plugin content at the top level of ${PLUGIN_DIR} (need one of ${PLUGIN_MARKERS.join(', ')})`);
+  }
+
+  const resolved = path.resolve(PLUGIN_DIR);
+
+  // Windows UNC paths are refused by Claude Code; catch it here with a clear
+  // message rather than letting the install fail opaquely.
+  if (process.platform === 'win32' && /^\\\\/.test(resolved)) {
+    fail(`refusing a UNC path (Claude Code rejects it): ${resolved}`);
+  }
+
+  // Exactly one line, nothing else.
+  process.stdout.write(`${resolved}\n`);
+}
+
+main();

package/pan-wizard-core/learnings/internal/.gitkeep

@@ -1,2 +0,0 @@
-# Placeholder so git tracks the empty directory.
-# This tier is NOT shipped to user installs — see ../README.md.