pan-wizard 3.25.0 → 3.27.0

package/README.md

@@ -659,7 +659,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:debug [desc]` | Systematic debugging with persistent state |
 | `/pan:quick [--full]` | Execute ad-hoc task with PAN guarantees (`--full` adds plan-checking and verification) |
 | `/pan:health [--repair]` | Validate `.planning/` directory integrity; `--repair` auto-fixes detected issues |
-| `/pan:hygiene [--apply] [--trace-age-days N]` | Scan for PAN version drift and stale project artifacts (legacy filenames, .tmp orphans, memory bloat, poisoned cost ledgers, trace debris, fragment planning dirs); `--apply` executes the safe fixes — ledgers are quarantined by rename, never deleted |
+| `/pan:hygiene [--apply] [--trace-age-days N] [--all-tracks]` | Scan for PAN version drift and stale project artifacts (legacy filenames, .tmp orphans, memory bloat, poisoned cost ledgers, trace and report debris, cached-context bloat, fragment planning dirs); `--apply` executes the safe fixes — ledgers are quarantined by rename, never deleted, and settled `state.md` history is archived rather than dropped |
 | `/pan:links [--strict]` | Validate the doc-code link graph: inline `[[<id>]]` refs, `// @pan:` source anchors, `require-code-mention` contracts (ADR-0027, v3.8.0+) |
 | `/pan:phase-tests [N]` | Generate tests for a completed phase based on UAT criteria |
 | `/pan:milestone-cleanup` | Archive accumulated phase directories from completed milestones |

package/bin/install-lib.cjs

@@ -469,6 +469,13 @@ User interaction (runtimes without a native question tool):
 }
 
 /** Claude command → runtime-neutral SKILL.md (ADR-0028 Phase 1) */
+/**
+ * `compatibility` value for emitted unified skills — the spec's optional field
+ * for environment requirements (max 500 chars). Kept short and factual: these
+ * are the two things a host cannot infer and that every PAN skill depends on.
+ */
+const SKILL_COMPATIBILITY = 'Requires Node.js (skills invoke the bundled pan-tools CLI) and a project with a .planning/ directory, created by /pan-new-project or /pan-map-codebase.';
+
 function convertClaudeCommandToUnifiedSkill(content, skillName) {
   // Normalize command mentions to the readable /pan-<name> form; the adapter
   // header tells each runtime to map that onto its own invocation syntax.
@@ -483,7 +490,14 @@ function convertClaudeCommandToUnifiedSkill(content, skillName) {
   description = toSingleLine(description);
   const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
   const adapter = getUnifiedSkillAdapterHeader(skillName);
-  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
+  // `compatibility` is the spec's optional field for stating environment
+  // requirements, and PAN has real ones: the skill bodies shell out to
+  // `pan-tools` (Node) and every workflow reads/writes `.planning/`. Declaring
+  // them beats the alternative, which is a host discovering it mid-run.
+  // Deliberately NOT emitting `allowed-tools`: it is marked experimental in the
+  // spec, and ADR-0028's frontmatter rule is that anything unverified stays out
+  // until a live per-runtime check confirms no parser rejects it.
+  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\ncompatibility: ${yamlQuote(SKILL_COMPATIBILITY)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
 }
 
 /** Generate Copilot CLI skill adapter header */
@@ -869,6 +883,146 @@ const HOOK_EVENT_MAP = Object.freeze({
   opencode: null,
 });
 
+// ─── MCP server registration (2026-08) ──────────────────────────────────────
+
+/**
+ * Cross-runtime MCP registration map. Every path and shape below was verified
+ * against primary docs on 2026-08-12 — do NOT edit from memory, and re-verify
+ * before trusting: this table's ancestor (`HOOK_EVENT_MAP`) exists because PAN
+ * shipped two DEAD config paths that had been written from secondary sources.
+ *
+ * `register: false` means PAN deliberately does not write the file and prints a
+ * copy-pasteable snippet instead. That is a risk decision, not an omission:
+ *   - **codex** — MCP lives in `config.toml`, which PAN does not touch anywhere
+ *     else and cannot merge non-destructively without a TOML parser (PAN is
+ *     zero-dep and only ever *generates* TOML). Hand-merging a user's config
+ *     risks their settings for no gain over a printed snippet.
+ *   - **claude global** — user scope is `~/.claude.json`, a large file keyed by
+ *     every project path the user has opened. PAN writes the project-scoped
+ *     `.mcp.json` instead, which is the documented shareable surface.
+ *
+ * Shape notes that differ per runtime and are easy to get wrong:
+ *   - claude/copilot/gemini use `mcpServers`; **opencode uses `mcp`**.
+ *   - claude/copilot/gemini take `command` + `args[]`; **opencode takes a single
+ *     `command` ARRAY** ([cmd, ...args]) and names its env block `environment`.
+ *   - copilot/opencode want `type: "local"`; claude/gemini infer stdio from
+ *     `command` and are not given a `type` here.
+ */
+const MCP_REGISTRATION = Object.freeze({
+  claude: Object.freeze({
+    register: true, key: 'mcpServers', localPath: '.mcp.json', globalPath: null,
+    why: 'Project-scoped .mcp.json at the repo root (code.claude.com/docs/en/mcp). Needs one interactive approval; workspace trust gates it.',
+  }),
+  copilot: Object.freeze({
+    // PATHS HERE ARE RELATIVE TO THE RUNTIME'S CONFIG DIR, not the repo root.
+    // Copilot's config dir already *is* `.github/`, so this is `mcp.json` — it
+    // resolves to `.github/mcp.json` on disk. Writing `.github/mcp.json` here
+    // produced `.github/.github/mcp.json`, a file Copilot never reads; the
+    // doubling is pinned by a test because it installs and verifies "cleanly".
+    register: true, key: 'mcpServers', localPath: 'mcp.json', globalPath: 'mcp-config.json',
+    why: 'docs.github.com add-mcp-servers: project-level .github/mcp.json (also .mcp.json up-tree), user-level ~/.copilot/mcp-config.json.',
+  }),
+  gemini: Object.freeze({
+    register: true, key: 'mcpServers', localPath: 'settings.json', globalPath: 'settings.json',
+    why: 'Gemini reads mcpServers from .gemini/settings.json (workspace) or ~/.gemini/settings.json (user) — the same file PAN already writes hooks into.',
+  }),
+  opencode: Object.freeze({
+    register: true, key: 'mcp', localPath: 'opencode.json', globalPath: 'opencode.json',
+    why: 'opencode.ai/docs: opencode.json `mcp` block, type "local", command as one array, env block named `environment`. PAN already writes this file.',
+  }),
+  codex: Object.freeze({
+    // Config-dir-relative like the others (resolves to `.codex/config.toml`).
+    // These are documentation-only while register is false — but they follow the
+    // convention anyway, so that flipping register:true later cannot inherit the
+    // path-doubling bug Copilot's row shipped with.
+    register: false, key: 'mcp_servers', localPath: 'config.toml', globalPath: 'config.toml',
+    why: 'TOML-only surface ([mcp_servers.NAME] in config.toml, verified learn.chatgpt.com). PAN has no TOML merge and is zero-dep; a printed snippet is safer than hand-editing a user config.',
+  }),
+});
+
+/**
+ * Build one PAN MCP server entry in the shape a given runtime expects.
+ *
+ * @param {string} runtime - claude | copilot | gemini | opencode | codex
+ * @param {string} serverPath - absolute path to pan-wizard-core/mcp/server.cjs
+ * @param {string} panToolsPath - absolute path to pan-wizard-core/bin/pan-tools.cjs
+ * @param {string} [projectRoot] - value for PAN_PROJECT_ROOT; omitted when falsy
+ * @returns {object} the entry (NOT wrapped in its container key)
+ */
+function buildMcpServerEntry(runtime, serverPath, panToolsPath, projectRoot) {
+  const env = { PAN_TOOLS_PATH: panToolsPath };
+  if (projectRoot) env.PAN_PROJECT_ROOT = projectRoot;
+
+  if (runtime === 'opencode') {
+    // Single command ARRAY + `environment` — opencode's shape is the outlier.
+    return { type: 'local', command: ['node', serverPath], enabled: true, environment: env };
+  }
+  const entry = { command: 'node', args: [serverPath], env };
+  // Copilot's documented example carries an explicit local type; Claude and
+  // Gemini infer stdio from `command`, and Claude's `type` vocabulary does not
+  // include "local", so it must NOT be added there.
+  if (runtime === 'copilot') entry.type = 'local';
+  return entry;
+}
+
+/**
+ * Merge PAN's MCP server into an existing config object, non-destructively.
+ * Foreign servers are preserved; the PAN entry is replaced wholesale so a
+ * reinstall is idempotent and a path change takes effect.
+ *
+ * @param {object|null} existing - parsed config, or null when absent/unusable
+ * @param {string} runtime
+ * @param {object} entry - from buildMcpServerEntry
+ * @param {string} [serverName='pan'] - registration key
+ * @returns {object} merged config to serialize
+ */
+function mergeMcpRegistration(existing, runtime, entry, serverName = 'pan') {
+  const spec = MCP_REGISTRATION[runtime];
+  if (!spec) throw new Error(`mergeMcpRegistration: unknown runtime "${runtime}"`);
+  const config = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
+  const key = spec.key;
+  if (!config[key] || typeof config[key] !== 'object' || Array.isArray(config[key])) config[key] = {};
+  config[key][serverName] = entry;
+  return config;
+}
+
+/**
+ * Remove PAN's MCP server from a config object, preserving foreign entries.
+ * Empties the container key when PAN was its only member, so uninstall does not
+ * leave `{"mcpServers":{}}` behind.
+ *
+ * @returns {{config: object, removed: boolean}}
+ */
+function stripMcpRegistration(existing, runtime, serverName = 'pan') {
+  const spec = MCP_REGISTRATION[runtime];
+  if (!spec) throw new Error(`stripMcpRegistration: unknown runtime "${runtime}"`);
+  const config = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
+  const bag = config[spec.key];
+  if (!bag || typeof bag !== 'object' || !(serverName in bag)) return { config, removed: false };
+  delete bag[serverName];
+  if (Object.keys(bag).length === 0) delete config[spec.key];
+  return { config, removed: true };
+}
+
+/**
+ * The copy-pasteable TOML a user adds by hand for Codex (register: false).
+ * Emitting a snippet rather than merging is the deliberate choice recorded in
+ * MCP_REGISTRATION — keep this in the shape verified at learn.chatgpt.com
+ * (`[mcp_servers.NAME]` with a nested `[mcp_servers.NAME.env]` table).
+ */
+function buildCodexMcpSnippet(serverPath, panToolsPath, projectRoot, serverName = 'pan') {
+  const lines = [
+    `[mcp_servers.${serverName}]`,
+    'command = "node"',
+    `args = [${JSON.stringify(serverPath)}]`,
+    '',
+    `[mcp_servers.${serverName}.env]`,
+    `PAN_TOOLS_PATH = ${JSON.stringify(panToolsPath)}`,
+  ];
+  if (projectRoot) lines.push(`PAN_PROJECT_ROOT = ${JSON.stringify(projectRoot)}`);
+  return lines.join('\n');
+}
+
 /**
  * Merge PAN hook registrations into a `.codex/hooks.json` config.
  *
@@ -1301,6 +1455,127 @@ function buildPluginHooksConfig() {
   };
 }
 
+/**
+ * Build the plugin-only self-test command that answers PAN's one gated question:
+ * does `${CLAUDE_PLUGIN_ROOT}` expand inside plugin COMMAND MARKDOWN? It is
+ * documented as substituted in hook and MCP configs; content is unverified, and
+ * that is what has kept `dist/pan-wizard-plugin/` from being published.
+ *
+ * Emitted ONLY into the plugin build, never into `commands/pan/`, so the shipped
+ * command set is unchanged and no install gains a diagnostic.
+ *
+ * THE PROBE MUST SEPARATE TWO THINGS that a naive test conflates. If the body
+ * simply ran `node "${CLAUDE_PLUGIN_ROOT}/…"` and it worked, that proves nothing
+ * about markdown: the shell would expand `${CLAUDE_PLUGIN_ROOT}` on its own if the
+ * variable happens to be exported into the tool environment. So probe 1 asks for
+ * the RAW CHARACTERS with no shell involved, probe 2 checks the environment
+ * separately, and the verdict table maps the pair onto what PAN may rely on.
+ *
+ * @param {string} placeholder - the literal PAN rewrites content to, injected
+ *   rather than hardcoded so this file stays the single source of that string.
+ * @returns {string} markdown for `commands/pan-plugin-selftest.md` in the plugin
+ */
+function buildPluginSelfTestCommand(placeholder = '${CLAUDE_PLUGIN_ROOT}') {
+  // Sentinels the agent quotes between. Deliberately ugly so they cannot occur
+  // naturally in surrounding prose or be mistaken for instructions.
+  const OPEN = 'PAN_PROBE_BEGIN>>>';
+  const CLOSE = '<<<PAN_PROBE_END';
+  return `---
+description: Diagnose whether the plugin-root placeholder expands in plugin command markdown
+---
+
+# PAN plugin self-test
+
+Answer three questions and print the verdict table. **Do not fix anything.** This
+command is a measurement; a "fail" here is the result, not a problem to repair.
+
+## Probe 1 — textual substitution in markdown (the question that matters)
+
+Between the sentinels below sits one token. Report **the exact characters you see
+there, verbatim**. Do not run a shell. Do not resolve, expand, guess at, or tidy
+the value — if it looks like a placeholder, say so and quote it literally; if it
+looks like an absolute path, quote that path.
+
+${OPEN}${placeholder}${CLOSE}
+
+Record it as \`probe1\`.
+
+## Probe 2 — the environment variable, measured separately
+
+Run exactly this and record stdout as \`probe2\` (empty output is a valid, expected result):
+
+\`\`\`bash
+node -e "process.stdout.write(process.env.CLAUDE_PLUGIN_ROOT || '')"
+\`\`\`
+
+## Probe 3 — does the engine actually resolve through the placeholder path
+
+Run this and record whether it prints JSON or errors, as \`probe3\`:
+
+\`\`\`bash
+node "${placeholder}/pan-wizard-core/bin/pan-tools.cjs" --help
+\`\`\`
+
+## Verdict
+
+Print this table, filled in:
+
+| probe | result |
+|---|---|
+| 1 — markdown substitution | \`probe1\` verbatim |
+| 2 — env var | \`probe2\` or "(empty)" |
+| 3 — engine through placeholder | ok / failed, with the error's first line |
+
+Then state which case holds:
+
+- **case A — markdown IS substituted** (probe 1 returned an absolute path). Plugin
+  content may reference the plugin root directly, and PAN's existing content
+  rewrite is correct as it stands. This unblocks marketplace publishing.
+- **case B — markdown is NOT substituted, but the env var is set** (probe 1
+  returned the literal token, probe 2 non-empty). Content must not rely on textual
+  substitution; a *shell* command inside content would still work, because the
+  shell expands the variable. Anything read as a path by something other than a
+  shell — an \`@\` file import, for instance — would break.
+  **Note:** on the one environment measured so far (Claude Code 2.1.233, Windows)
+  probe 2 came back EMPTY, so this case did not occur and its shell-expansion
+  premise is unverified. If you land here, confirm the variable really is visible
+  to the Bash tool before relying on it — otherwise you are actually in case C.
+- **case C — neither** (probe 1 literal, probe 2 empty). Plugin content cannot
+  address the plugin root at all. PAN would need content that resolves paths at
+  runtime instead, and marketplace publishing stays gated.
+
+Finish with the case letter on its own line, exactly like \`VERDICT: case A\`,
+so the result is greppable out of the transcript.
+`;
+}
+
+/**
+ * Build the plugin's MCP registration (`.mcp.json` at the plugin root).
+ *
+ * Plugins may declare MCP servers in a plugin-root `.mcp.json`, and unlike
+ * command markdown — where `${CLAUDE_PLUGIN_ROOT}` expansion is unverified and
+ * is why marketplace publishing is still gated — hook and MCP *configs* are the
+ * documented place the variable is substituted. So the same form
+ * `buildPluginHooksConfig()` relies on is correct here.
+ *
+ * No `env` block: a plugin serves whatever project the session is in, so pinning
+ * PAN_PROJECT_ROOT would be wrong, and the server resolves its engine from its
+ * own location (see `defaultPanToolsPath`) with `cwd` falling back to the
+ * process cwd. Nothing to configure per install.
+ *
+ * @returns {Object} a `.mcp.json` object for the plugin root
+ */
+function buildPluginMcpConfig() {
+  return {
+    mcpServers: {
+      pan: {
+        command: 'node',
+        args: ['${CLAUDE_PLUGIN_ROOT}/pan-wizard-core/mcp/server.cjs'],
+      },
+    },
+  };
+}
+
 // ─── Native Claude Code workflows (2026-06) ─────────────────────────────────
 //
 // Claude Code discovers deterministic orchestration scripts in
@@ -1510,10 +1785,17 @@ module.exports = {
   buildCopilotHooksConfig,
   HOOK_EVENT_MAP,
   mergeCodexHooksConfig,
+  MCP_REGISTRATION,
+  buildMcpServerEntry,
+  mergeMcpRegistration,
+  stripMcpRegistration,
+  buildCodexMcpSnippet,
   removeCodexPanHooks,
   buildNativeWorkflowScripts,
   buildPluginManifest,
   buildPluginHooksConfig,
+  buildPluginMcpConfig,
+  buildPluginSelfTestCommand,
   // Install verification (v3.7.10)
   verifyInstall,
   // AGENTS.md universal rules layer (ADR-0028 Phase 3)

package/bin/install.js

@@ -1611,6 +1611,39 @@ function uninstall(isGlobal, runtime = 'claude') {
     }
   }
 
+  // 7b. Strip the MCP registration. Foreign servers and every other key in the
+  // file are preserved; a file PAN created and that holds nothing else is
+  // removed rather than left as `{}`. An unparseable config is left ALONE —
+  // never rewrite JSON we could not read (the readSettings null-vs-{} contract).
+  {
+    const mcpPath = mcpConfigPathFor(runtime, isGlobal, targetDir);
+    if (mcpPath) {
+      const existing = readSettings(mcpPath);
+      if (existing === null) {
+        try {
+          if (fs.existsSync(mcpPath)) {
+            console.log(`  ${yellow}✗${reset} ${displayPath(mcpPath)} is not valid JSON — left untouched (remove the "pan" server by hand)`);
+          }
+        } catch { /* stat failed — nothing to report */ }
+      } else {
+        try {
+          const { config, removed } = lib.stripMcpRegistration(existing, runtime);
+          if (removed) {
+            if (Object.keys(config).length === 0) {
+              fs.unlinkSync(mcpPath);
+              console.log(`  ${green}✓${reset} Removed ${displayPath(mcpPath)} (only the PAN server remained)`);
+            } else {
+              fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n');
+              console.log(`  ${green}✓${reset} Removed PAN MCP server from ${displayPath(mcpPath)}`);
+            }
+          }
+        } catch (e) {
+          console.error(`  ${yellow}✗${reset} Failed to strip MCP registration from ${displayPath(mcpPath)}: ${e.message}`);
+        }
+      }
+    }
+  }
+
   // 8. Clean up empty PAN directories
   const dirsToClean = [
     path.join(targetDir, 'agents'),
@@ -2017,6 +2050,96 @@ function reportLocalPatches(configDir, runtime = 'claude') {
   return meta.files || [];
 }
 
+/**
+ * Resolve where a runtime's MCP registration file lives, per MCP_REGISTRATION.
+ *
+ * Returns null when this runtime/scope combination is deliberately not written
+ * (see the table's `register` flag and the claude-global note). `targetDir` is
+ * the runtime's config dir (.claude/, .github/, .gemini/, .opencode/ …).
+ *
+ * The important asymmetry: Claude's project surface is `.mcp.json` at the REPO
+ * ROOT, not inside `.claude/`. Every other runtime keeps its MCP config inside
+ * its own config dir, so only Claude escapes targetDir.
+ */
+function mcpConfigPathFor(runtime, isGlobal, targetDir) {
+  const spec = lib.MCP_REGISTRATION[runtime];
+  if (!spec || !spec.register) return null;
+  if (runtime === 'claude') {
+    // No global path by design — ~/.claude.json is a per-project-keyed user file.
+    return isGlobal ? null : path.join(process.cwd(), spec.localPath);
+  }
+  const rel = isGlobal ? spec.globalPath : spec.localPath;
+  if (!rel) return null;
+  return path.join(targetDir, rel);
+}
+
+/**
+ * Register PAN's MCP bridge for one runtime, non-destructively.
+ *
+ * Reuses readSettings() so an existing-but-unusable config is distinguished from
+ * an absent one (null vs {}) — the distinction that exists because an earlier
+ * installer destroyed unparseable settings files. An unusable file is left
+ * ALONE and reported; PAN never rewrites JSON it could not parse.
+ *
+ * Codex gets a printed TOML snippet rather than a write (MCP_REGISTRATION.codex
+ * records why). Gemini/OpenCode share a settings file PAN already writes, so the
+ * merge preserves everything else in it.
+ */
+function registerMcpServer(runtime, isGlobal, targetDir) {
+  const spec = lib.MCP_REGISTRATION[runtime];
+  if (!spec) return;
+
+  // Absolute paths into the core copy this install just wrote.
+  const coreDir = path.join(targetDir, 'pan-wizard-core');
+  const serverPath = path.join(coreDir, 'mcp', 'server.cjs');
+  const enginePath = path.join(coreDir, 'bin', 'pan-tools.cjs');
+  // A global install serves many projects, so it must NOT pin PAN_PROJECT_ROOT;
+  // the server falls back to process.cwd() per project. Local installs pin it.
+  const projectRoot = isGlobal ? null : process.cwd();
+
+  if (!fs.existsSync(serverPath)) {
+    pushInstallWarning('mcpRegister', serverPath, new Error('MCP server missing; skipped registration'));
+    return;
+  }
+
+  if (!spec.register) {
+    const snippet = lib.buildCodexMcpSnippet(serverPath, enginePath, projectRoot);
+    const where = isGlobal ? '~/.codex/config.toml' : '.codex/config.toml';
+    console.log(`  ${cyan}i${reset} MCP: add PAN to ${where} by hand (TOML is not safely mergeable):`);
+    console.log(snippet.split('\n').map((l) => `      ${dim}${l}${reset}`).join('\n'));
+    return;
+  }
+
+  const configPath = mcpConfigPathFor(runtime, isGlobal, targetDir);
+  if (!configPath) {
+    if (runtime === 'claude' && isGlobal) {
+      console.log(`  ${cyan}i${reset} MCP: run ${cyan}claude mcp add pan --scope user -- node "${serverPath}"${reset} to register globally`);
+    }
+    return;
+  }
+
+  const existing = readSettings(configPath);
+  if (existing === null) {
+    // Exists but unparseable — do not touch it.
+    pushInstallWarning('mcpRegister', configPath, new Error('config exists but is not valid JSON; left untouched'));
+    console.log(`  ${yellow}✗${reset} MCP: ${displayPath(configPath)} is not valid JSON — left untouched, register PAN by hand`);
+    return;
+  }
+
+  try {
+    const entry = lib.buildMcpServerEntry(runtime, serverPath, enginePath, projectRoot);
+    const merged = lib.mergeMcpRegistration(existing, runtime, entry);
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(merged, null, 2) + '\n');
+    console.log(`  ${green}✓${reset} Registered MCP server (${displayPath(configPath)})`);
+    if (runtime === 'claude') {
+      console.log(`      ${dim}Claude prompts once to approve a project-scoped server.${reset}`);
+    }
+  } catch (e) {
+    pushInstallWarning('mcpRegister', configPath, e);
+  }
+}
+
 function install(isGlobal, runtime = 'claude') {
   const isOpencode = runtime === 'opencode';
   const isGemini = runtime === 'gemini';
@@ -2286,6 +2409,10 @@ function install(isGlobal, runtime = 'claude') {
     failures.push('pan-wizard-core');
   }
 
+  // Register the MCP bridge now that pan-wizard-core (which contains mcp/) has
+  // landed — the registration points at files inside it, so it must come after.
+  registerMcpServer(runtime, isGlobal, targetDir);
+
   // Copy agents to agents directory
   try {
     const agentsSrc = path.join(src, 'agents');

package/commands/pan/hygiene.md

@@ -2,7 +2,7 @@
 name: pan:hygiene
 group: System
 description: Scan the project for PAN version drift and stale artifacts (legacy filenames, memory bloat, poisoned ledgers, trace debris) and apply safe cleanups
-argument-hint: "[--apply] [--trace-age-days N]"
+argument-hint: "[--apply] [--trace-age-days N] [--all-tracks] [--track <name>]"
 allowed-tools:
   - Read
   - Bash
@@ -17,12 +17,18 @@ Keep a PAN-managed project aligned with the latest PAN version and free of accum
 ## 1. Scan
 
 ```bash
-SCAN=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs hygiene scan)
+SCAN=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs hygiene scan --all-tracks)
 ```
 
-Parse JSON: `findings[]` (`check`, `severity`, `path`, `detail`, `fixable`), `installs[]`, `latest_version`, `summary`.
+Pass `--all-tracks` by default: a project may hold several planning trees (`.planning/` plus `.planning/tracks/<name>/`), and scanning only the root tree reports "clean" for debris sitting in a sibling track. Use `--track <name>` to scan one specific tree instead.
 
-Display the findings grouped by severity (critical → warn → info). If `summary.total` is 0: report "Project is clean and aligned" and stop.
+Parse JSON: `findings[]` (`check`, `severity`, `path`, `detail`, `fixable`, `track`), `installs[]`, `latest_version`, `roots_scanned[]`, `summary` (including `summary.by_track`).
+
+Display the findings grouped by severity (critical → warn → info), labelling each with its `track` when more than one tree was scanned.
+
+**Always state which trees were scanned** — read `roots_scanned[]` and name them. If `summary.total` is 0, report "Project is clean and aligned" *together with* the list of trees that were read. A clean verdict without its scope is what let stale debris hide in an unscanned track; never report one without the other.
+
+If any root has `planning_root_exists: false`, say so plainly — that is a mistyped `--track`, not a clean tree.
 
 ## 2. Version drift (manual remediation)
 
@@ -41,7 +47,7 @@ Hygiene never runs the installer itself.
 **Without `--apply` in $ARGUMENTS:** run the dry-run and present what WOULD change:
 
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs hygiene clean
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs hygiene clean --all-tracks
 ```
 
 Then ask the user (AskUserQuestion, header "Apply fixes", options: "Apply safe fixes" / "Skip") unless running headless — in auto/headless contexts, report the dry-run only and stop.
@@ -49,14 +55,14 @@ Then ask the user (AskUserQuestion, header "Apply fixes", options: "Apply safe f
 **With `--apply` (or after user confirmation):**
 
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs hygiene clean --apply
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs hygiene clean --all-tracks --apply
 ```
 
-Safe fixes are: lowercase renames of legacy planning filenames, deletion of aged .tmp orphans, memory-log compaction, poisoned-ledger quarantine (rename in place — never deleted), and pruning of trace sessions past retention (newest 5 always kept). Pass through `--trace-age-days N` if provided.
+Safe fixes are: lowercase renames of legacy planning filenames, deletion of aged .tmp orphans, memory-log compaction, poisoned-ledger quarantine (rename in place — never deleted), pruning of trace sessions **and optimization reports** past retention (newest 5 of each always kept), and **state.md compaction** (`compact-state`) — settled history is archived to `state-history.md` so it stops being re-read into every agent call. Nothing is deleted by any of these: the ledger is renamed, and state history is written to the archive before state.md is rewritten. Each fix is applied inside its own tree's scope, so a track's debris is cleaned in that track. Pass through `--trace-age-days N` and any `--track <name>` if provided.
 
 ## 4. Report
 
-Summarize: fixes executed / failed / left manual, plus the installer command if version drift remains. Recommend re-running `/pan:hygiene` after the installer to confirm alignment.
+Summarize: the trees scanned, fixes executed / failed / left manual (attributed per track), plus the installer command if version drift remains. If a `cache-context` finding appeared, state the per-call token cost it represents — that block is re-read on **every** agent call, so it is the project's largest recurring expense. Recommend re-running `/pan:hygiene` after the installer to confirm alignment.
 
 </process>
 

package/commands/pan/milestone-audit.md

@@ -2,7 +2,7 @@
 name: pan:milestone-audit
 group: Milestone
 description: Audit milestone completion against original intent before archiving
-argument-hint: "[version]"
+argument-hint: "[version] [--track <name>] [--all-tracks]"
 allowed-tools:
   - Read
   - Glob
@@ -26,9 +26,11 @@ Version: $ARGUMENTS (optional — defaults to current milestone)
 
 Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
 
-**Completed Work:**
-Glob: .planning/phases/*/*-summary.md
-Glob: .planning/phases/*/*-verification.md
+**Planning tree:** the project may hold several. `init milestone-op` reports the `planning_root` it resolved; use that root for every glob below rather than assuming `.planning/`. Pass `--track <name>` to audit a specific tree, or run `init milestone-op --all-tracks` first to see every tree's milestone state.
+
+**Completed Work:** (relative to the resolved `planning_root`)
+Glob: {planning_root}/phases/*/*-summary.md
+Glob: {planning_root}/phases/*/*-verification.md
 </context>
 
 <citation_requirement>
@@ -57,4 +59,8 @@ Do not trust summary files at face value. If a verification.md says "all tests p
 <process>
 Execute the audit-milestone workflow from @~/.claude/pan-wizard-core/workflows/milestone-audit.md end-to-end.
 Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing).
+
+Two gates are non-negotiable because they guard against auditing the wrong thing:
+- **State the resolved `planning_root` in the report.** An audit that does not name the tree it read cannot be checked.
+- **Stop if `milestone_ambiguous` is true.** More than one milestone marked current is a roadmap defect for the owner to fix; auditing one of them silently is how a report ends up describing a milestone that does not exist.
 </process>