pan-wizard 3.26.0 → 3.28.0

package/pan-wizard-core/mcp/server.cjs

@@ -50,7 +50,36 @@ const META_SERVER_INFO_KEY = 'io.modelcontextprotocol/serverInfo';
 // claim to speak a version we don't. Newest first (the `server/discover` order).
 const SUPPORTED_VERSIONS_LIST = [MODERN_PROTOCOL_VERSION, '2025-06-18', '2025-03-26', '2024-11-05'];
 const SUPPORTED_PROTOCOL_VERSIONS = new Set(SUPPORTED_VERSIONS_LIST);
-const SERVER_INFO = { name: 'pan-mcp', version: '0.1.0' };
+/**
+ * The version the server reports in `initialize` / `server/discover`. Read from the
+ * package.json two levels up: the repository root in the source tree, the runtime
+ * directory in an install (the installer writes package.json beside pan-wizard-core/).
+ * The plugin bundles carry no package.json there, so fall back to the plugin manifest
+ * and finally to a marker that is visibly not a release. Never throws: a missing
+ * file must not stop the server from answering. Reality check R9: this was a literal
+ * '0.1.0' while the package shipped 3.x.
+ */
+function readPackageVersion(baseDir = path.join(__dirname, '..', '..')) {
+  // Order: the repo/runtime package.json when it carries a version; the install
+  // manifest every runtime writes (the runtime directory's package.json is a bare
+  // `{"type":"commonjs"}` marker with no version — measured on a fresh install,
+  // 2026-09-10, where the first version of this reader answered 0.0.0-unknown); the
+  // Claude plugin manifest; an Agent Plugins manifest.
+  const candidates = [
+    path.join(baseDir, 'package.json'),
+    path.join(baseDir, 'pan-file-manifest.json'),
+    path.join(baseDir, '.claude-plugin', 'plugin.json'),
+    path.join(baseDir, 'plugin.json'),
+  ];
+  for (const file of candidates) {
+    try {
+      const v = JSON.parse(fs.readFileSync(file, 'utf8')).version;
+      if (typeof v === 'string' && v.trim()) return v.trim();
+    } catch { /* try the next candidate */ }
+  }
+  return '0.0.0-unknown';
+}
+const SERVER_INFO = { name: 'pan-mcp', version: readPackageVersion() };
 
 /**
  * Default engine location: `bin/` is a sibling of this `mcp/` directory inside
@@ -75,6 +104,25 @@ function defaultPanToolsPath() {
   return path.join(__dirname, '..', 'bin', 'pan-tools.cjs');
 }
 
+/**
+ * A verdict payload: a JSON object with no error-family key. The family is `error`
+ * and any key ending in `_error` — the same definition core.cjs's reportsFailure()
+ * uses for the CLI exit code, mirrored here because the server stays engine-agnostic
+ * (it never requires the engine's modules; it spawns them). Plural collections such
+ * as `errors[]` are verdict DETAIL, not a failure signal. Returns the parsed object,
+ * or null when the text is not such a payload.
+ */
+function parseVerdict(text) {
+  if (typeof text !== 'string' || !text.trim()) return null;
+  let parsed;
+  try { parsed = JSON.parse(text); } catch { return null; }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  for (const k of Object.keys(parsed)) {
+    if (k === 'error' || k.endsWith('_error')) { if (parsed[k]) return null; }
+  }
+  return parsed;
+}
+
 /** Real spawn: shell-less execFile of `node <argv...>`. */
 function defaultSpawn(nodeArgs) {
   try {
@@ -154,7 +202,7 @@ function createServer(opts = {}) {
   const gitImpl = opts.gitImpl || makeDefaultGit(cwd);
   const env = opts.env || process.env;
 
-  function runVerb(verb, extraArgs) {
+  function runVerb(verb, extraArgs, verbCwd = cwd) {
     // Defense in depth: the verb always comes from the registry, but re-check the
     // forbidden pattern here so no future caller can smuggle a force/reset op past it.
     if (reg.FORBIDDEN_VERB.test(verb)) {
@@ -163,22 +211,46 @@ function createServer(opts = {}) {
     // No --raw: pan-tools' default output is structured JSON (which is what the MCP
     // client wants); --raw would instead emit a bare human scalar. Large results
     // arrive via the @file: overflow protocol, resolved here.
-    const r = spawn([panToolsPath, verb, ...extraArgs, '--cwd', cwd]);
+    const r = spawn([panToolsPath, verb, ...extraArgs, '--cwd', verbCwd]);
     if (r && r.ok) r.stdout = resolveOverflow(r.stdout);
     return r;
   }
 
+  /**
+   * Per-call project root (ADR-0045 D6). Every TOOL accepts an optional `cwd`;
+   * it must be an absolute path to an existing directory. Returns
+   * { cwd, input } with the field removed from the input handed to the tool, or
+   * { error } shaped for a -32602 — a bad root is a bad REQUEST, and nothing is
+   * spawned. Resources never come through here: their argv is static.
+   */
+  function resolveCallCwd(input) {
+    const src = input || {};
+    if (src.cwd === undefined) return { cwd, input: src };
+    let candidate;
+    try { candidate = reg.validateProjectCwd(src.cwd); }
+    catch (e) { return { error: { code: -32602, message: String((e && e.message) || e) } }; }
+    let isDir = false;
+    try { isDir = fs.statSync(candidate).isDirectory(); } catch { /* absent → not a directory */ }
+    if (!isDir) return { error: { code: -32602, message: `Invalid "cwd": not an existing directory: ${candidate}` } };
+    const { cwd: _omit, ...rest } = src;
+    return { cwd: path.resolve(candidate), input: rest };
+  }
+
   // Returns { error:{code,message} } for JSON-RPC protocol errors (unknown tool /
   // invalid arguments — a bad *request*), or { result:{content,isError} } where
   // isError:true signals a genuine tool *execution* failure (the verb ran and failed).
   function callTool(name, input) {
     const tool = reg.byToolName[name];
     if (!tool) return { error: { code: -32602, message: `Unknown tool: ${name}` } };
+    const call = resolveCallCwd(input);
+    if (call.error) return { error: call.error };
     // Native, in-process tools (orchestrator / merge gate) run a handler; a thrown
     // Error means bad params (-32602), matching the spawn-tool validation path.
+    // The git executor follows the per-call root unless a test injected one.
     if (typeof tool.handler === 'function') {
       try {
-        const out = tool.handler({ cwd, input: input || {}, env, gitImpl });
+        const gitForCall = opts.gitImpl ? gitImpl : (call.cwd === cwd ? gitImpl : makeDefaultGit(call.cwd));
+        const out = tool.handler({ cwd: call.cwd, input: call.input, env, gitImpl: gitForCall });
         const text = (out && out.text != null) ? out.text : JSON.stringify(out && out.json);
         return { result: { content: [{ type: 'text', text }], isError: !!(out && out.isError) } };
       } catch (e) {
@@ -186,9 +258,9 @@ function createServer(opts = {}) {
       }
     }
     let extra;
-    try { extra = tool.args ? tool.args(input || {}) : []; }
+    try { extra = tool.args ? tool.args(call.input) : []; }
     catch (e) { return { error: { code: -32602, message: String((e && e.message) || e) } }; }
-    const r = runVerb(tool.verb, extra);
+    const r = runVerb(tool.verb, extra, call.cwd);
     return { result: { content: [{ type: 'text', text: r.ok ? r.stdout : (r.stderr || 'error') }], isError: !r.ok } };
   }
 
@@ -206,7 +278,19 @@ function createServer(opts = {}) {
     // 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' } };
+    if (!r.ok) {
+      // A VERDICT is data, not a failed read. `validate health` (pan://health) exits
+      // non-zero when its verdict is `broken` — CLI-REFERENCE: verdict commands set
+      // their exit code explicitly, for shell gating — while still printing the full
+      // JSON report. Over MCP the report IS the resource, so accept stdout when it is
+      // a JSON object carrying no error-family key. Anything else (no JSON, or an
+      // `error`/`*_error` key) is a genuine read failure → JSON-RPC error.
+      const text = resolveOverflow(r.stdout);
+      if (parseVerdict(text) !== null) {
+        return { result: { contents: [{ uri, mimeType: 'application/json', text }] } };
+      }
+      return { error: { code: -32603, message: r.stderr || 'resource read failed' } };
+    }
     return { result: { contents: [{ uri, mimeType: 'application/json', text: r.stdout }] } };
   }
 
@@ -315,6 +399,6 @@ function main() {
 if (require.main === module) main();
 
 module.exports = {
-  createServer, defaultPanToolsPath, defaultSpawn, SERVER_INFO, toMcpTool, toMcpResource,
+  createServer, defaultPanToolsPath, defaultSpawn, parseVerdict, readPackageVersion, SERVER_INFO, toMcpTool, toMcpResource,
   PROTOCOL_VERSION, MODERN_PROTOCOL_VERSION, SUPPORTED_VERSIONS_LIST, META_PROTOCOL_VERSION_KEY,
 };

package/pan-wizard-core/mcp/tool-registry.cjs

@@ -39,7 +39,9 @@ const QUERY_RE = /^[\w .,:/&()-]{1,120}$/;    // find-phase query fragment
  *
  * 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
+ * (an error-family key in the JSON it prints, or no JSON at all — a non-zero exit BY
+ * ITSELF is a verdict signal for shell gating, and the reader accepts the JSON as data;
+ * see server.cjs readResource), 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.
@@ -62,7 +64,7 @@ const RESOURCES = [
     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.' },
+    description: 'Health check over .planning/: issue codes with severities. Reports an unhealthy project as DATA: the JSON verdict is the resource even when the CLI exits non-zero for shell gating, so it is readable on a broken or empty project.' },
   { 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'],
@@ -138,7 +140,51 @@ const FORBIDDEN_VERB = /(^|-)(push|reset|rebase|force)($|-)/;
 // tools into one advertised list. Required after SPAWN_TOOLS/FORBIDDEN_VERB so the
 // native module (which imports nothing back from here) composes cleanly — no cycle.
 const { NATIVE_TOOLS } = require('./native-tools.cjs');
-const TOOLS = [...SPAWN_TOOLS, ...NATIVE_TOOLS];
+
+// ─── Per-call project root (ADR-0045 D6, 2026-09) ───────────────────────────
+//
+// The server resolves its project as `opts.cwd || PAN_PROJECT_ROOT || process.cwd()`.
+// Under Claude Code the process cwd IS the project. Under an Agent Plugins client
+// the spec makes the PLUGIN ROOT the default working directory of a stdio server,
+// so every verb would read `.planning/` from inside the plugin cache and report an
+// empty project — cleanly, which is the worst kind of failure. So every TOOL takes
+// an optional `cwd`: the absolute path of the project to operate on, honoured for
+// that call only. Applied here, centrally, so a tool added later cannot miss it.
+//
+// Resources deliberately do NOT get it: their argv is a static array and the
+// safety argument of ADR-0041 is that no client input reaches it.
+const PROJECT_CWD_PROPERTY = Object.freeze({
+  type: 'string',
+  description: 'Absolute path of the PAN project to operate on. Optional: defaults to the directory the server was started in. Pass it when the server was launched from a plugin directory (Agent Plugins clients do this by default), or to address another project.',
+});
+
+const PROJECT_CWD_MAX = 1024;
+
+/**
+ * Shape-validate a per-call project root: a non-empty absolute path with no NUL,
+ * within a sane length. Existence is the SERVER's check (it has fs); this module
+ * stays pure. Throws a message fit for a -32602 on failure.
+ */
+function validateProjectCwd(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > PROJECT_CWD_MAX) {
+    throw new Error(`Invalid "cwd": must be a non-empty string of at most ${PROJECT_CWD_MAX} chars`);
+  }
+  if (value.includes('\0')) throw new Error('Invalid "cwd": contains a NUL byte');
+  // Absolute on either platform family: `/…`, `C:\…`, `C:/…`, or a UNC `\\host\share`.
+  if (!/^(?:\/|[A-Za-z]:[\\/]|\\\\)/.test(value)) throw new Error('Invalid "cwd": must be an absolute path');
+  return value;
+}
+
+/** Return a copy of a tool descriptor whose inputSchema also accepts `cwd`. Never mutates the source. */
+function withProjectCwd(tool) {
+  const schema = tool.inputSchema || { type: 'object', additionalProperties: false, properties: {} };
+  return {
+    ...tool,
+    inputSchema: { ...schema, properties: { ...(schema.properties || {}), cwd: PROJECT_CWD_PROPERTY } },
+  };
+}
+
+const TOOLS = [...SPAWN_TOOLS, ...NATIVE_TOOLS].map(withProjectCwd);
 
 const byToolName = Object.create(null);
 for (const t of TOOLS) byToolName[t.name] = t;
@@ -148,4 +194,5 @@ for (const r of RESOURCES) byResourceUri[r.uri] = r;
 module.exports = {
   TOOLS, SPAWN_TOOLS, NATIVE_TOOLS, RESOURCES, byToolName, byResourceUri, FORBIDDEN_VERB,
   AGENT_RE, PHASE_RE, QUERY_RE, str,
+  PROJECT_CWD_PROPERTY, validateProjectCwd, withProjectCwd,
 };

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

@@ -11,8 +11,8 @@ PAN uses three abstract tiers instead of hardcoded model names:
 | Tier | Purpose | Anthropic | OpenAI | Google |
 |------|---------|-----------|--------|--------|
 | `reasoning` | Architecture, planning, complex decisions | inherit (your session's top-tier model) | inherit | inherit |
-| `mid` | Execution, research, verification | Sonnet | mid | mid |
-| `fast` | Read-only extraction, budget tasks | Haiku | fast | fast |
+| `mid` | Execution, research, verification | Sonnet | mid | gemini-2.5-flash |
+| `fast` | Read-only extraction, budget tasks | Haiku | fast | gemini-2.5-flash-lite |
 
 **Why `inherit` for reasoning?** Host runtimes map "opus" to a specific model version. PAN returns `inherit` for reasoning-tier agents, so they use whatever top-tier model the user has configured. This avoids version conflicts and silent fallbacks.
 

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

@@ -152,6 +152,7 @@ Report final status.
 | E003 | error | roadmap.md not found | No |
 | E004 | error | state.md not found | Yes |
 | E005 | error | config.json parse error | Yes |
+| E006 | error | `.planning/` belongs to another tool (gsd-core markers found); PAN stops before E002-E005 and `--repair` writes nothing | No |
 | W001 | warning | project.md missing required section | No |
 | W002 | warning | state.md references invalid phase | Yes |
 | W003 | warning | config.json not found | Yes |

package/pan-wizard-core/workflows/milestone-audit.md

@@ -16,6 +16,35 @@ INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init milestone-op)
 
 Extract from init JSON: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `commit_docs`.
 
+**Also extract `planning_root` and `track`, and use `$PLANNING_ROOT` for every planning path in this workflow** — the project may hold several planning trees, and auditing the wrong one produces a confident, plausible, wrong report:
+
+```bash
+PLANNING_ROOT=$(printf '%s' "$INIT" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).planning_root))")
+```
+
+### 0a. Which tree am I auditing?
+
+**Always state the resolved `planning_root` at the top of the audit report.** If `planning_root_exists` is `false`, STOP — that is a mistyped `--track`, not an empty milestone.
+
+To audit a specific tree, pass `--track <name>`. To see every tree's milestone state before choosing:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init milestone-op --all-tracks
+```
+
+That returns `{track_count, ambiguous_tracks, tracks[]}`, one entry per planning tree, each with its own `planning_root`, `milestone_version`, `milestone_name`, and `milestone_basis`.
+
+### 0b. Refuse to audit an unresolvable milestone
+
+The init payload carries how the milestone was decided:
+
+- `milestone_basis` — `marked-current` (a `(current)` / 🚧 marker), `first-unshipped`, `last-shipped`, or `default`
+- `milestone_ambiguous` — **`true` means the roadmap marks more than one milestone current**
+
+**If `milestone_ambiguous` is `true`, STOP and report the planning-state error.** Do not audit. Two milestones marked current is a roadmap defect the owner must resolve; picking one silently is how an audit ends up describing a milestone that does not exist.
+
+If `milestone_basis` is `default`, there is no milestone heading in the roadmap at all — say so rather than auditing `v1.0 milestone`.
+
 Resolve integration checker model:
 ```bash
 CHECKER_MODEL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-integration-checker --raw)
@@ -103,7 +132,7 @@ For each phase's verification.md, extract the expanded requirements table:
 
 For each phase's summary.md, extract `requirements-completed` from YAML frontmatter:
 ```bash
-for summary in .planning/phases/*-*/*-summary.md; do
+for summary in "$PLANNING_ROOT"/phases/*-*/*-summary.md; do
   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs summary-extract "$summary" --fields requirements_completed | jq -r '.requirements_completed'
 done
 ```
@@ -129,7 +158,7 @@ For each REQ-ID, determine status using all three sources:
 
 ## 6. Aggregate into v{version}-milestone-audit.md
 
-Create `.planning/v{version}-milestone-audit.md` with:
+Create `{planning_root}/v{version}-milestone-audit.md` with:
 
 ```yaml
 ---
@@ -186,7 +215,7 @@ Output this markdown directly (not as a code block). Route based on status:
 ## ✓ Milestone {version} — Audit Passed
 
 **Score:** {N}/{M} requirements satisfied
-**Report:** .planning/v{version}-milestone-audit.md
+**Report:** {planning_root}/v{version}-milestone-audit.md
 
 All requirements covered. Cross-phase integration verified. E2E flows complete.
 
@@ -209,7 +238,7 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 ## ⚠ Milestone {version} — Gaps Found
 
 **Score:** {N}/{M} requirements satisfied
-**Report:** .planning/v{version}-milestone-audit.md
+**Report:** {planning_root}/v{version}-milestone-audit.md
 
 ### Unsatisfied Requirements
 
@@ -240,7 +269,7 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 ───────────────────────────────────────────────────────────────
 
 **Also available:**
-- cat .planning/v{version}-milestone-audit.md — see full report
+- cat {planning_root}/v{version}-milestone-audit.md — see full report
 - /pan:milestone-done {version} — proceed anyway (accept tech debt)
 
 ───────────────────────────────────────────────────────────────
@@ -252,7 +281,7 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 ## ⚡ Milestone {version} — Tech Debt Review
 
 **Score:** {N}/{M} requirements satisfied
-**Report:** .planning/v{version}-milestone-audit.md
+**Report:** {planning_root}/v{version}-milestone-audit.md
 
 All requirements met. No critical blockers. Accumulated tech debt needs review.
 

package/pan-zcode/README.md

@@ -13,7 +13,7 @@ ZCode through the one interface it speaks: **MCP**.
 
 ## How it fits
 
-```
+```text
 ZCode harness (GLM-5.2)          primary Agent drives everything; ported subagents fan out
         │  MCP · local stdio
 pan-wizard-core/mcp  (SHARED)    a thin, zero-dep bridge — verbs → MCP tools/resources

package/scripts/build-agent-plugin.js

@@ -0,0 +1,220 @@
+/**
+ * Build the PAN Wizard **Agent Plugins 1.0** bundle (ADR-0045) — the vendor-
+ * neutral package that Copilot CLI / VS Code, Codex, Cursor and Kiro load
+ * natively. Emits a self-contained directory at dist/pan-agent-plugin/:
+ *
+ *   plugin.json                   closed-schema manifest ($schema + name + metadata)
+ *   skills/pan-<name>/SKILL.md    every PAN command as an Agent Skill, from the
+ *                                 ONE unified-skills compiler (ADR-0028)
+ *   mcp.json                      the bundled bridge, launched as
+ *                                 `node ${PLUGIN_ROOT}/pan-wizard-core/mcp/server.cjs`
+ *   pan-wizard-core/              dispatcher + modules + workflows + templates +
+ *                                 references + learnings (internal stripped) +
+ *                                 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
+ *                                 shape with `${PLUGIN_ROOT}` paths and `async` observers
+ *                                 (developers.openai.com/plugins/build/plugins, 2026-09-10)
+ *   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
+ *                                   (VS-Code-verified; Copilot CLI live install is the gate)
+ *
+ * NOT emitted: Codex agents (no plugin agent component is documented) and any
+ * Antigravity variant (its manifest schema is closed and different — a separate
+ * layout, deferred until its file shapes are read from a primary source).
+ *
+ * Paths inside skill and core markdown use PAN's `{{PAN_PLUGIN_ROOT}}` token,
+ * defined for the model by the adapter note in every skill; `${PLUGIN_ROOT}`
+ * (the client-expanded variable) appears only in mcp.json, the one place the
+ * spec expands it.
+ *
+ * Usage: node scripts/build-agent-plugin.js   (or npm run build:agent-plugin)
+ * PAN_AGENT_PLUGIN_OUT=<dir> overrides the output directory (tests build into
+ * private temp dirs so parallel test files never race on dist/).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const OUT = process.env.PAN_AGENT_PLUGIN_OUT
+  ? path.resolve(process.env.PAN_AGENT_PLUGIN_OUT)
+  : path.join(ROOT, 'dist', 'pan-agent-plugin');
+const pkg = require(path.join(ROOT, 'package.json'));
+const lib = require(path.join(ROOT, 'bin', 'install-lib.cjs'));
+
+const TOKEN_PREFIX = `${lib.AGENT_PLUGIN_ROOT_TOKEN}/`;
+const REWRITE = {
+  // Core and agent references → inside the bundle.
+  corePrefix: TOKEN_PREFIX,
+  // Residual `~/.claude/…` → the consuming runtime's USER config dir; residual
+  // `./.claude/…` → its PROJECT dir. Neither is known at build time, so both are
+  // tokens the adapter note defines (install-lib AGENT_PLUGIN_RUNTIME_*_TOKEN).
+  pathPrefix: `${lib.AGENT_PLUGIN_RUNTIME_HOME_TOKEN}/`,
+  projectDirPrefix: `${lib.AGENT_PLUGIN_RUNTIME_DIR_TOKEN}/`,
+  attribution: undefined, // keep the documents' default attribution — no runtime to consult
+};
+
+/**
+ * Refuse to wipe a directory that is not a previous bundle build (same rule as
+ * build-plugin.js). Empty or absent directories, and our own previous output —
+ * recognised by a manifest carrying the Agent Plugins schema — are fair game.
+ */
+function assertSafeToReplace(dir) {
+  if (!fs.existsSync(dir)) return;
+  if (fs.readdirSync(dir).length === 0) return;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'plugin.json'), 'utf8'));
+    if (manifest && manifest.$schema === lib.AGENT_PLUGIN_MANIFEST_SCHEMA) return;
+  } catch { /* fall through to refusal */ }
+  throw new Error(`build-agent-plugin: refusing to replace ${dir} — it is non-empty and does not look like a previous bundle build (no Agent Plugins plugin.json)`);
+}
+
+/** commands/pan/**.md → skills/pan-<name>/SKILL.md, mirroring the installer's recursion. */
+function emitSkills(srcDir, skillsDir, prefix) {
+  let count = 0;
+  (function recurse(currentSrc, currentPrefix) {
+    for (const entry of fs.readdirSync(currentSrc, { withFileTypes: true })) {
+      const srcPath = path.join(currentSrc, entry.name);
+      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() });
+      fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content);
+      count++;
+    }
+  })(srcDir, prefix);
+  return count;
+}
+
+/** pan-wizard-core → bundle, markdown rewritten, everything else verbatim. */
+function emitCore(srcDir, destDir) {
+  (function recurse(currentSrc, currentDest) {
+    fs.mkdirSync(currentDest, { recursive: true });
+    for (const entry of fs.readdirSync(currentSrc, { withFileTypes: true })) {
+      const srcPath = path.join(currentSrc, entry.name);
+      const destPath = path.join(currentDest, entry.name);
+      if (entry.isDirectory()) recurse(srcPath, destPath);
+      else if (entry.name.endsWith('.md')) fs.writeFileSync(destPath, lib.rewriteSharedCoreMarkdown(fs.readFileSync(srcPath, 'utf8'), REWRITE));
+      else fs.copyFileSync(srcPath, destPath);
+    }
+  })(srcDir, destDir);
+
+  // learnings/internal is source-only — strip the files AND the index entries,
+  // exactly as the installer and the Claude plugin builder do.
+  fs.rmSync(path.join(destDir, 'learnings', 'internal'), { recursive: true, force: true });
+  const indexPath = path.join(destDir, 'learnings', 'index.json');
+  try {
+    const stripped = lib.stripInternalLearningsTopics(JSON.parse(fs.readFileSync(indexPath, 'utf8')));
+    if (stripped) fs.writeFileSync(indexPath, JSON.stringify(stripped, null, 2) + '\n');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  fs.writeFileSync(path.join(destDir, 'VERSION'), pkg.version);
+}
+
+/** Canonical agent reference copies under <core>/agents/ (ADR-0028). */
+function emitAgentReferenceCopies(agentsSrc, agentsRefDir) {
+  fs.mkdirSync(agentsRefDir, { recursive: true });
+  let count = 0;
+  for (const f of fs.readdirSync(agentsSrc).filter(n => n.endsWith('.md'))) {
+    fs.writeFileSync(path.join(agentsRefDir, f), lib.rewriteAgentReferenceCopy(fs.readFileSync(path.join(agentsSrc, f), 'utf8'), TOKEN_PREFIX));
+    count++;
+  }
+  return count;
+}
+
+/** Hook scripts: the built copies from hooks/dist when present, else the pure-Node sources. */
+function emitHookScripts(destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const dist = path.join(ROOT, 'hooks', 'dist');
+  const src = fs.existsSync(dist) ? dist : path.join(ROOT, 'hooks');
+  const names = fs.readdirSync(src).filter(n => /^pan-[a-z-]+\.js$/.test(n)).sort();
+  for (const n of names) fs.copyFileSync(path.join(src, n), path.join(destDir, n));
+  return names;
+}
+
+/** The four hook commands, anchored at the plugin root through whichever variable the consumer expands. */
+function hookCommands(rootVar) {
+  const cmd = (script) => `node ${rootVar}/hooks/${script}`;
+  return {
+    updateCheckCommand: cmd('pan-check-update.js'),
+    contextMonitorCommand: cmd('pan-context-monitor.js'),
+    costLoggerCommand: cmd('pan-cost-logger.js'),
+    traceLoggerCommand: cmd('pan-trace-logger.js'),
+  };
+}
+
+/** Copilot vendor directory: agents in Copilot's `.agent.md` format + plugin hooks. */
+function emitCopilotNamespace(agentsSrc, nsDir) {
+  const agentsDest = path.join(nsDir, 'agents');
+  fs.mkdirSync(agentsDest, { recursive: true });
+  let agents = 0;
+  for (const f of fs.readdirSync(agentsSrc).filter(n => n.endsWith('.md'))) {
+    let content = fs.readFileSync(path.join(agentsSrc, f), 'utf8');
+    // Core references → the bundle token; mentions → /pan-<name>; then the same
+    // two steps the installer applies to a Copilot agent (thinking frontmatter
+    // strip, Copilot frontmatter/tool-name conversion).
+    content = lib.rewriteAgentReferenceCopy(content, TOKEN_PREFIX);
+    content = lib.stripThinkingFrontmatter(content, 'copilot');
+    content = lib.convertClaudeToCopilotAgent(content);
+    fs.writeFileSync(path.join(agentsDest, f.replace(/\.md$/, '.agent.md')), content);
+    agents++;
+  }
+  fs.mkdirSync(path.join(nsDir, 'hooks'), { recursive: true });
+  fs.writeFileSync(
+    path.join(nsDir, 'hooks', 'hooks.json'),
+    JSON.stringify(lib.buildCopilotPluginHooksConfig(hookCommands('${CLAUDE_PLUGIN_ROOT}')), null, 2) + '\n'
+  );
+  return agents;
+}
+
+function main() {
+  assertSafeToReplace(OUT);
+  fs.rmSync(OUT, { recursive: true, force: true });
+  fs.mkdirSync(OUT, { recursive: true });
+
+  // 1. Manifest (closed schema — nothing beyond the ten permitted keys)
+  fs.writeFileSync(path.join(OUT, 'plugin.json'), JSON.stringify(lib.buildAgentPluginManifest(pkg), null, 2) + '\n');
+
+  // 2. Skills
+  const skills = emitSkills(path.join(ROOT, 'commands', 'pan'), path.join(OUT, 'skills'), 'pan');
+
+  // 3. Core (+ 4. canonical agent copies inside it)
+  const coreDest = path.join(OUT, 'pan-wizard-core');
+  emitCore(path.join(ROOT, 'pan-wizard-core'), coreDest);
+  const agents = emitAgentReferenceCopies(path.join(ROOT, 'agents'), path.join(coreDest, 'agents'));
+
+  // 5. MCP declaration
+  fs.writeFileSync(path.join(OUT, 'mcp.json'), JSON.stringify(lib.buildAgentPluginMcpConfig(), null, 2) + '\n');
+
+  // 6. Hooks: scripts once, at the root; a Codex hooks.json at the documented
+  //    default location (`hooks/hooks.json`, `${PLUGIN_ROOT}` expanded in commands,
+  //    observers async — the same builder the installer uses for .codex/hooks.json).
+  const hooksDir = path.join(OUT, 'hooks');
+  const hookScripts = emitHookScripts(hooksDir);
+  fs.writeFileSync(
+    path.join(hooksDir, 'hooks.json'),
+    JSON.stringify(lib.mergeCodexHooksConfig(null, hookCommands('${PLUGIN_ROOT}')), null, 2) + '\n'
+  );
+
+  // 7. Copilot vendor namespace
+  const copilotAgents = emitCopilotNamespace(path.join(ROOT, 'agents'), path.join(OUT, lib.COPILOT_PLUGIN_NAMESPACE));
+
+  console.log('PAN Agent Plugins bundle built at', path.relative(ROOT, OUT) || OUT);
+  console.log('  skills:', skills);
+  console.log('  agent reference copies:', agents);
+  console.log('  hook scripts:', hookScripts.length);
+  console.log(`  ${lib.COPILOT_PLUGIN_NAMESPACE}/agents:`, copilotAgents);
+  console.log('  version:', pkg.version);
+}
+
+main();