pan-wizard 3.15.1 → 3.18.0

package/README.md

@@ -201,6 +201,29 @@ npm run test:all        # All tests (unit + scenario)
 
 </details>
 
+<details>
+<summary><strong>Experimental: ZCode support (preview) — ZCode is beta</strong></summary>
+
+**PAN-Z** is an experimental, separate subsystem that brings the PAN workflow to
+[ZCode](https://zcode.z.ai), z.ai's GLM coding-agent harness. ZCode has no
+slash-commands or hooks to host PAN directly, so PAN-Z instead exposes PAN's engine to
+ZCode over **MCP**: PAN's agents become ZCode subagents, and the deterministic engine —
+including a model-proof human merge gate — is reached as MCP tools.
+
+> **ZCode is beta**, and its on-disk formats change frequently. PAN-Z is a **preview**:
+> two facts (whether a subagent can call MCP tools, and whether local MCP calls are
+> metered) can only be confirmed on a live ZCode install. See
+> [`pan-zcode/README.md`](pan-zcode/README.md) and
+> [`pan-zcode/KNOWN-BETA-RISKS.md`](pan-zcode/KNOWN-BETA-RISKS.md).
+
+```bash
+# From an installed pan-wizard package, build the ZCode bundle into a target dir
+node "$(npm root -g)/pan-wizard/pan-zcode/bin/install-zcode.js" --target ./zcode-bundle
+# then finish setup inside ZCode per the generated INSTALL-ZCODE.md
+```
+
+</details>
+
 ### Recommended: Skip Permissions Mode
 
 PAN is designed for frictionless automation. Run Claude Code with:
@@ -553,7 +576,7 @@ You're never locked in. The system adapts.
 
 PAN is not a replacement for your IDE or AI agent — it's the orchestration layer that handles everything *around* them: breaking work into context-safe chunks, researching before planning, verifying after execution, and maintaining state across sessions.
 
-> For the full comparison across 8 tools and 15+ dimensions, see [COMPARISON.md](docs/COMPARISON.md).
+> For the full comparison across the major AI coding tools and many dimensions, see [COMPARISON.md](docs/COMPARISON.md).
 
 ---
 

package/commands/pan/army.md

@@ -125,9 +125,13 @@ Spawn the Quality squad on the built tree (parallel, read-only). Merge findings
 ### Phase 5 — Integrate (Release, human-gated)
 Spawn `pan-release`. It prepares the squash-merge, runs the configured `verification`, and surfaces an **always-ask** approval request. A human approves the merge to the protected branch; release then tags and records the rollback target. `--push` pushes the approved result.
 
+**Phase report (opt-in build deliverable):** when `workflow.phase_reports.enabled` is `true`, generate the mission's self-contained per-phase HTML report **in the built tree, before staging the squash-merge** — `pan-tools report phase <N>` — so the report rides along in the merge as a phase deliverable. **Never run `report index` inside a squad worktree:** the timeline index is a single shared file that aggregates *all* phases, so a worktree would see only its own phase and concurrent squads would race on it. The index is a single-writer, post-merge concern (Phase 6). Never opens a browser.
+
 ### Phase 6 — Learn (Dreaming)
 Squad summaries return to Mission Control. Run `/pan:retro --write-memory` (and `/pan:learn` if traces exist) so recurring patterns persist into agent memory for the next mission. Strike the landed item; update loop-state. For a scheduled campaign, also `pan-tools campaign record-run --items <n> --points <p>` so the next-due time and the day's spend advance.
 
+**Rebuild the timeline index (single writer).** When `workflow.phase_reports.enabled` and `workflow.phase_reports.index` are `true`, Mission Control — and *only* Mission Control, on the integration branch after the merge has landed — rebuilds the project index once against the now-merged set of phases: `pan-tools report index`, then commit it (the commit honors `commit_docs`). Doing this post-merge from the single conductor is what keeps `report-index.html` consistent while builds run in parallel worktrees.
+
 ---
 
 ## Scheduled, self-resuming campaigns (ADR-0034)

package/commands/pan/focus-doc-audit.md

@@ -156,7 +156,7 @@ For each target document, extract every verifiable claim.
 | Category | Pattern | Example |
 |----------|---------|---------|
 | **Version claim** | `v1.2.3`, `version 1.2`, `Version: X` | "Currently at v3.1.0" |
-| **Count claim** | Number + noun | "42 test suites", "15 API endpoints" |
+| **Count claim** | Number + noun | "42 database tables", "15 API endpoints" |
 | **File path claim** | Path-like strings | "`src/core/handler.ts`" |
 | **Command claim** | Code block with shell prefix or instruction | "`npm run build`" |
 | **Feature claim** | "supports X", "includes Y", "provides Z" | "Supports hot reloading" |

package/commands/pan/report.md

@@ -2,7 +2,7 @@
 name: pan:report
 group: Observability
 description: Generate a self-contained HTML report for one phase, or a project-level timeline index linking every phase report
-argument-hint: "phase <N> | index | all [--out <file>] [--open] [--stdout]"
+argument-hint: "phase <N> | index [--bundle] | all [--out <file>] [--open] [--stdout]"
 allowed-tools:
   - Read
   - Bash
@@ -24,7 +24,7 @@ Reports are honest by construction: the `verify reconcile` verdict is shown besi
 
 ```
 pan-tools report phase <N> [--out <file>] [--open] [--stdout]
-pan-tools report index      [--out <file>] [--open] [--stdout]
+pan-tools report index      [--out <file>] [--open] [--stdout] [--bundle]
 pan-tools report all        [--open]
 ```
 
@@ -37,6 +37,7 @@ pan-tools report all        [--open]
 - `--out <file>` — write to a custom path instead of the default (relative paths resolve against the project root).
 - `--open` — best-effort: launch the written file in the default browser (cross-platform; silently no-ops if no opener is available, and never opens when nothing was written).
 - `--stdout` — print the HTML to stdout instead of writing a file (for `phase`/`index`).
+- `--bundle` (on `index`) — emit one self-contained `.planning/report-bundle.html`: the timeline plus every phase report inlined under in-page anchors, with no links to sibling files. This is the form to email or attach — a single file that stays whole when moved off-disk.
 
 **Behaviour worth knowing:**
 - **Deterministic writes.** Re-running with unchanged phase data rewrites nothing (the only volatile value, the generated-at timestamp, is ignored when comparing) — so reports produce no git churn.
@@ -61,7 +62,7 @@ pan-tools report all        [--open]
 
 **Review a phase:** run `pan-tools report phase <N> --open` to see one phase's objective, what changed, and its verification verdict at a glance.
 
-**Share the project:** `pan-tools report index` builds the timeline entry point — send `.planning/report-index.html` and the linked phase files, or open the index and click through.
+**Share the project:** `pan-tools report index` builds the timeline entry point — send `.planning/report-index.html` and the linked phase files, or open the index and click through. To hand someone a single file instead, `pan-tools report index --bundle` inlines every phase into one `.planning/report-bundle.html` that survives being emailed or moved.
 
 **Refresh everything:** `pan-tools report all` after a milestone regenerates every report; unchanged ones are skipped, so only what actually moved is rewritten.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.15.1",
+  "version": "3.18.0",
   "description": "Command a bot army for your codebase: an Opus Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"
@@ -12,7 +12,8 @@
     "agents",
     "hooks/dist",
     "scripts",
-    "assets"
+    "assets",
+    "pan-zcode"
   ],
   "keywords": [
     "claude",

package/pan-wizard-core/bin/lib/config.cjs

@@ -53,6 +53,8 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       verifier: true,
       nyquist_validation: false,
       phase_record_compact: false,
+      // M2: opt-in per-phase HTML reports at the verify→complete gate.
+      phase_reports: { enabled: false, open: false, theme: 'auto', index: true },
     },
     parallelization: true,
     brave_search: hasBraveSearch,

package/pan-wizard-core/bin/lib/focus.cjs

@@ -809,11 +809,48 @@ function focusAutoUpdate(cwd, raw, getVal) {
   }, raw);
 }
 
+/**
+ * Whether opt-in HTML phase reports are enabled for this project.
+ * Reads the raw config.json (loadConfig doesn't surface the workflow block);
+ * absent / malformed config → disabled.
+ */
+function phaseReportsEnabled(cwd) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(planningPath(cwd), 'config.json'), 'utf-8'));
+    return !!(raw.workflow && raw.workflow.phase_reports && raw.workflow.phase_reports.enabled);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Regenerate every phase report + index as part of a focus-auto checkpoint,
+ * when the feature is enabled. Best-effort and side-effect-light: never opens a
+ * browser, and silently no-ops for phase-less / focus-auto-only projects. The
+ * fresh HTML lands in .planning/ so the checkpoint's `git add` sweeps it in.
+ */
+function maybeRenderPhaseReports(cwd) {
+  if (!phaseReportsEnabled(cwd)) return;
+  try {
+    const { renderAllToDisk } = require('./phase-report.cjs');
+    renderAllToDisk(cwd, {});
+  } catch {
+    // Report generation must never block the checkpoint commit.
+  }
+}
+
 function focusAutoCheckpointCommit(cwd, cycle, run) {
   if (!isGitRepo(cwd)) return null;
   const config = loadConfig(cwd);
   const autoCommit = config.focus && config.focus.auto_commit !== undefined ? config.focus.auto_commit : true;
   if (!autoCommit) return null;
+  // commit_docs is the global switch for committing planning artifacts; focus-auto
+  // is a planning-doc committer, so honor it. commit_docs=false → hands the .planning
+  // commit (and any report regeneration) back to the user.
+  if (config.commit_docs === false) return null;
+  // Enabled projects: refresh the HTML reports before staging so the committed
+  // .planning/ snapshot reflects this cycle.
+  maybeRenderPhaseReports(cwd);
   const status = execGit(cwd, ['status', '--porcelain', PLANNING_DIR + '/']);
   if (status.exitCode !== 0 || !status.stdout) return null;
   execGit(cwd, ['add', PLANNING_DIR + '/']);

package/pan-wizard-core/bin/lib/phase-report.cjs

@@ -44,6 +44,7 @@ const cost = require('./cost.cjs');
 
 const REPORT_SUFFIX = '-report.html';
 const INDEX_FILE = 'report-index.html';
+const BUNDLE_FILE = 'report-bundle.html';
 
 // ─── small helpers ─────────────────────────────────────────────────────────────
 
@@ -548,7 +549,8 @@ function indexHero(d) {
   </section>`;
 }
 
-function indexTimeline(d) {
+function indexTimeline(d, hrefFn) {
+  const href = hrefFn || ((p) => p.href);
   const rows = d.phases.map((p, i) => {
     const color = STATUS_DOT[p.status] || '#C9C0AE';
     const isLast = i === d.phases.length - 1;
@@ -560,7 +562,7 @@ function indexTimeline(d) {
     return `
     <div class="trow">
       <div class="rail"><span class="rd" style="background:${color}"></span>${isLast ? '' : `<span class="rl" style="background:${railColor}"></span>`}</div>
-      <a class="tcard" href="${esc(p.href)}">
+      <a class="tcard" href="${esc(href(p))}">
         <div>
           <div class="tt">${esc(p.number)}${p.name ? ' · ' + esc(p.name) : ''}</div>
           <div class="tsub"><span class="mini">${mini}</span><span>${p.plansTotal ? p.plansDone + ' / ' + p.plansTotal + ' plans' : 'no plans'}</span>${p.has_report ? '' : '<span>· report pending</span>'}</div>
@@ -577,6 +579,33 @@ function renderIndexHtml(d) {
   return docShell(`PanWizard · ${d.project} — timeline`, body, d.generated_at);
 }
 
+/**
+ * Bundle: the timeline index plus EVERY phase report inlined into one
+ * self-contained document, cross-linked by in-page #phase-NN anchors. Because
+ * navigation is anchors (not sibling files), the links never dangle when the
+ * single file is emailed or copied on its own. (indexData, phaseDatas) are pure.
+ */
+function renderBundleHtml(indexData, phaseDatas) {
+  const anchorHref = (p) => '#phase-' + encodeURIComponent(String(p.number));
+  const sections = (phaseDatas || []).filter(Boolean).map(d => `
+  <section id="phase-${esc(d.phase.number)}" style="margin-top:26px;border-top:1px solid var(--border);padding-top:8px">
+    <div class="crumbs"><a href="#top">↑ back to timeline</a></div>
+    ${reportHero(d)}
+    ${reportMetrics(d)}
+    <div class="grid"><div class="gcol">${reportObjective(d)}</div><div class="gcol">${reportVerification(d)}</div></div>
+    ${reportChanges(d)}
+    ${reportGaps(d)}
+  </section>`).join('\n');
+  const body = [
+    '<span id="top"></span>',
+    indexTopBar(indexData),
+    indexHero(indexData),
+    indexTimeline(indexData, anchorHref),
+    sections,
+  ].filter(Boolean).join('\n');
+  return docShell(`PanWizard · ${indexData.project} — full report`, body, indexData.generated_at);
+}
+
 // ─── side effects (the only impure layer) ────────────────────────────────────────
 
 /**
@@ -667,6 +696,19 @@ function cmdReport(cwd, opts = {}, raw) {
   if (action === 'index') {
     const data = collectIndexData(cwd, { now });
     if (!data) return error('No phases found — nothing to index (phase-less / focus-auto project). Use `pan-tools hud` instead.');
+    if (opts.bundle) {
+      const phaseDatas = data.phases.map(p => collectPhaseData(cwd, p.number, { now })).filter(Boolean);
+      const html = renderBundleHtml(data, phaseDatas);
+      if (opts.stdout) { process.stdout.write(html); return; }
+      const outPath = opts.out ? path.resolve(cwd, opts.out) : path.join(planningPath(cwd), BUNDLE_FILE);
+      const res = writeIfChanged(outPath, html);
+      const opened = opts.open && res.written ? openInBrowser(outPath) : false;
+      return output(
+        { action: 'bundle', phases: phaseDatas.length, path: toPosix(outPath), bytes: Buffer.byteLength(html), written: res.written, opened },
+        raw,
+        `bundle ${res.written ? 'written' : 'unchanged'}: ${toPosix(outPath)}`,
+      );
+    }
     const html = renderIndexHtml(data);
     if (opts.stdout) { process.stdout.write(html); return; }
     const outPath = opts.out ? path.resolve(cwd, opts.out) : path.join(planningPath(cwd), INDEX_FILE);
@@ -680,42 +722,62 @@ function cmdReport(cwd, opts = {}, raw) {
   }
 
   if (action === 'all') {
-    const dirs = listPhaseDirs(cwd);
-    if (!dirs.length) return error('No phases found — nothing to report.');
-    const reports = [];
-    for (const dirName of dirs) {
-      const { number } = parsePhaseDir(dirName);
-      const data = collectPhaseData(cwd, number, { now });
-      if (!data) continue;
-      const outPath = path.join(data.phase.dir, `${data.phase.number}${REPORT_SUFFIX}`);
-      const res = writeIfChanged(outPath, renderPhaseHtml(data));
-      reports.push({ phase: data.phase.number, path: toPosix(outPath), written: res.written });
-    }
-    const idx = collectIndexData(cwd, { now });
-    let index = { path: null, written: false };
-    if (idx) {
-      const outPath = path.join(planningPath(cwd), INDEX_FILE);
-      const res = writeIfChanged(outPath, renderIndexHtml(idx));
-      index = { path: toPosix(outPath), written: res.written };
-    }
+    const res = renderAllToDisk(cwd, { now });
+    if (!res) return error('No phases found — nothing to report.');
     return output(
-      { action, reports, index },
+      { action, reports: res.reports, index: res.index },
       raw,
-      `generated ${reports.length} phase report(s)${index.path ? ' + index' : ''}`,
+      `generated ${res.reports.length} phase report(s)${res.index.path ? ' + index' : ''}`,
     );
   }
 
   return error('Unknown report action. Available: phase <N>, index, all');
 }
 
+/**
+ * Regenerate every phase report + the timeline index straight to disk.
+ * Programmatic sibling of `cmdReport('all')` with NO stdout side effects and
+ * no browser opening — used by focus-auto / army in-tree checkpoints, which
+ * emit their own JSON and must not have report output interleaved into it.
+ * @param {string} cwd
+ * @param {{now?:Date}} opts
+ * @returns {{reports:Array<{phase:string,path:string,written:boolean}>, index:{path:string|null,written:boolean}}|null}
+ *   null when the project has no phases (phase-less / focus-auto-only).
+ */
+function renderAllToDisk(cwd, opts = {}) {
+  const now = opts.now;
+  const dirs = listPhaseDirs(cwd);
+  if (!dirs.length) return null;
+  const reports = [];
+  for (const dirName of dirs) {
+    const { number } = parsePhaseDir(dirName);
+    const data = collectPhaseData(cwd, number, { now });
+    if (!data) continue;
+    const outPath = path.join(data.phase.dir, `${data.phase.number}${REPORT_SUFFIX}`);
+    const res = writeIfChanged(outPath, renderPhaseHtml(data));
+    reports.push({ phase: data.phase.number, path: toPosix(outPath), written: res.written });
+  }
+  const idx = collectIndexData(cwd, { now });
+  let index = { path: null, written: false };
+  if (idx) {
+    const outPath = path.join(planningPath(cwd), INDEX_FILE);
+    const res = writeIfChanged(outPath, renderIndexHtml(idx));
+    index = { path: toPosix(outPath), written: res.written };
+  }
+  return { reports, index };
+}
+
 module.exports = {
   REPORT_SUFFIX,
   INDEX_FILE,
+  BUNDLE_FILE,
   collectPhaseData,
   collectIndexData,
   renderPhaseHtml,
   renderIndexHtml,
+  renderBundleHtml,
   cmdReport,
+  renderAllToDisk,
   // exported for focused unit tests
   resolvePhase,
   extractPhaseGoal,

package/pan-wizard-core/bin/pan-tools.cjs

@@ -890,6 +890,7 @@ async function main() {
           out: getArgValue(args, '--out'),
           open: args.includes('--open'),
           stdout: args.includes('--stdout'),
+          bundle: args.includes('--bundle'),
         }, raw);
       } else if (subcommand === 'all') {
         phaseReport.cmdReport(cwd, { action: 'all', open: args.includes('--open') }, raw);

package/pan-wizard-core/templates/config.json

@@ -7,7 +7,8 @@
     "verifier": true,
     "auto_advance": false,
     "nyquist_validation": false,
-    "phase_record_compact": false
+    "phase_record_compact": false,
+    "phase_reports": { "enabled": false, "open": false, "theme": "auto", "index": true }
   },
   "planning": {
     "commit_docs": true,

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

@@ -602,8 +602,24 @@ The CLI handles:
 
 Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`.
 
+**Phase reports (opt-in build deliverable):** when `workflow.phase_reports.enabled` is `true`, generate the self-contained per-phase HTML report — and, when `workflow.phase_reports.index` is `true`, the project timeline index — at this verify→complete gate so they ship with the phase and ride the commit below. Disabled by default; phase-less projects are skipped automatically by `report`. Never opens a browser here (that's reserved for a manual `pan-tools report --open`).
+
+```bash
+REPORT_FILES=""
+if [ "$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.phase_reports.enabled 2>/dev/null || echo false)" = "true" ]; then
+  if node ~/.claude/pan-wizard-core/bin/pan-tools.cjs report phase "${PHASE_NUMBER}" >/dev/null 2>&1; then
+    REPORT_FILES="{phase_dir}/*-report.html"
+    if [ "$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.phase_reports.index 2>/dev/null || echo true)" = "true" ]; then
+      node ~/.claude/pan-wizard-core/bin/pan-tools.cjs report index >/dev/null 2>&1 && REPORT_FILES="$REPORT_FILES .planning/report-index.html"
+    fi
+  fi
+fi
+```
+
+The report files are appended to the completion commit's `--files` list (`$REPORT_FILES`, empty when disabled), so `cmdCommit` still honors `commit_docs` + gitignore + safety checks with no new commit logic:
+
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(phase-{X}): complete phase execution" --files .planning/roadmap.md .planning/state.md .planning/requirements.md {phase_dir}/*-verification.md
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(phase-{X}): complete phase execution" --files .planning/roadmap.md .planning/state.md .planning/requirements.md {phase_dir}/*-verification.md $REPORT_FILES
 ```
 
 **Circular optimization — finalize trace session:**

package/pan-zcode/KNOWN-BETA-RISKS.md

@@ -0,0 +1,36 @@
+# PAN-Z — Known Beta Risks & M0 Open Questions
+
+ZCode is a fast-moving, closed Beta: three subsystems PAN-Z touches (subagent
+frontmatter, plugin/skill layout, MCP config path) changed within a single ~12-day
+window on ZCode's changelog. This ledger tracks what the design deliberately does **not**
+hard-depend on, and the go/no-go facts that can only be settled on a real ZCode install
+(the **M0 verify spike**). Re-check these before trusting any on-disk format.
+
+## M0 — go/no-go (settle empirically on a real ZCode)
+
+| # | Question | If NO → fallback (already in the design) |
+|---|----------|------------------------------------------|
+| 1 | Can a **subagent call MCP tools**? | Primary Agent makes every `pan-mcp` call and feeds results into subagent prompts. Determinism unaffected. |
+| 2 | Are **local stdio MCP calls metered** against the MCP-Calls quota? | Read verbs are MCP *resources*, not tools; batch/cache; never make a hosted z.ai MCP load-bearing. |
+| 3 | Exact **subagent frontmatter schema** / plugin layout / MCP config path? | Drive ZCode's own Import / Settings; treat `pan-zcode/lib/convert-agent.cjs` output as a labelled fallback, not a contract. |
+| 4 | Any **file-based / headless** way to register an MCP server, or GUI-only? | `install-zcode.js` emits a bundle + `INSTALL-ZCODE.md`; the human finishes in ZCode's UI. |
+| 5 | Any **lifecycle hook** that can hard-gate a spawn? | Enforce caps at the MCP-tool-call boundary (the orchestrator), not pre-spawn. |
+
+## Standing constraints (confirmed by the review)
+
+- **The merge gate is not self-sufficient.** Under ZCode Full Access, a raw Bash
+  `git push` bypasses `pan_confirm_merge`. Non-bypassability rests on **server-side
+  branch protection**; the MCP gate is the second, in-process lock. `INSTALL-ZCODE.md`
+  mandates branch protection and "never Full Access during install."
+- **No subagent nesting.** The army flattens to one delegation layer (PAN already caps
+  nesting at 2, so this is tolerable). `Task` is dropped from ported subagents.
+- **User-global subagents only.** No repo-scoped rosters or per-project model profiles.
+- **Genuinely lost:** scheduled self-resuming multi-day campaigns (no headless/daemon),
+  background execution, committable permissions, and custom slash-commands.
+
+## Format-drift policy
+
+Do **not** rely on a passive "write the file and hope" strategy. All three churning
+formats are GUI-owned implementation details: prefer ZCode's authoring surfaces, keep the
+converter output clearly labelled best-effort, and re-verify against this ledger on every
+ZCode version bump.

package/pan-zcode/README.md

@@ -0,0 +1,58 @@
+# PAN-Z — a ZCode-native PAN subsystem
+
+PAN-Z gives [ZCode](https://zcode.z.ai) (z.ai's GLM-5.2 coding harness) the PAN Wizard
+workflow — the multi-phase lifecycle, the bot-army with a human merge gate, deterministic
+state tracking — **without** cloning PAN's slash-commands or hooks (ZCode has neither).
+
+Instead of porting the command surface, PAN-Z **reuses PAN's engine in place** and reaches
+ZCode through the one interface it speaks: **MCP**.
+
+> Design + verified feasibility: [`docs/specs/pan_zcode_mcp_bridge_featureai.md`](../docs/specs/pan_zcode_mcp_bridge_featureai.md).
+> The architecture was confirmed by a 38-agent adversarial review; four optimistic
+> assumptions were refuted and their fixes folded into the design.
+
+## How it fits
+
+```
+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  (reused as-is)  the deterministic engine; .planning/ stays the state store
+```
+
+## 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
+  **zero-dependency** JSON-RPC 2.0 stdio MCP server; reads → resources, actions → tools with
+  accurate hints; shell-less `execFile` spawn; `@file:` overflow protocol; protocol-version
+  negotiation; strict per-arg validation).
+- **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`.
+- **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.
+- **M4 — bundle + install.** `bin/install-zcode.js` — assembles `agents/` + `pan-mcp.json` +
+  manifest + `INSTALL-ZCODE.md` into a `--target` dir; refuses to write inside the source repo;
+  drives ZCode's own Import to finish.
+- **M5 — hardening + docs.** Full test matrix + [`KNOWN-BETA-RISKS.md`](KNOWN-BETA-RISKS.md)
+  (the beta-churn ledger + the M0 go/no-go questions).
+
+Tests: `tests/pan-zcode-mcp.test.cjs`, `tests/pan-zcode-orchestration.test.cjs`,
+`tests/pan-zcode-install.test.cjs`.
+
+## Still pending — M0 (needs a real ZCode install)
+
+Two go/no-go facts can only be settled empirically: **can a subagent call MCP tools?** and **are
+local stdio MCP calls metered?** Both have folded-in fallbacks (see `KNOWN-BETA-RISKS.md`), so the
+design holds either way — but confirm them before relying on the richer paths.
+
+## Zero dependencies
+
+Like the rest of PAN, this subsystem ships **no runtime dependencies**. The MCP protocol is
+implemented directly rather than via an SDK. If protocol drift ever makes that costly, the
+escape hatch is to vendor an MCP SDK **inside this package only**, leaving `pan-wizard-core`
+untouched.

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

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * PAN-Z M4 — assemble the ZCode bundle and emit a pull-based install.
+ *
+ * Produces, into an explicit --target directory:
+ *   agents/*.md              PAN agents converted to ZCode subagents (best-effort)
+ *   pan-mcp.json             the MCP server registration (command/args/env)
+ *   pan-zcode-manifest.json  what was generated
+ *   INSTALL-ZCODE.md         how to finish setup inside ZCode
+ *
+ * It NEVER writes to a real ~/.zcode on its own and NEVER writes inside the PAN
+ * source repo — ZCode's on-disk formats churn weekly, so the human finishes setup by
+ * driving ZCode's own "Import from Claude Code" / Settings surfaces using this bundle.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { convertAgentsDir } = require('../lib/convert-agent.cjs');
+
+/** The MCP registration ZCode reads (Claude-compatible: command/args/env). */
+function mcpServerConfig(panToolsPath, serverPath, projectRoot) {
+  return {
+    mcpServers: {
+      'pan-mcp': {
+        command: 'node',
+        args: [serverPath],
+        env: { PAN_TOOLS_PATH: panToolsPath, PAN_PROJECT_ROOT: projectRoot || '.' },
+      },
+    },
+  };
+}
+
+const INSTRUCTIONS = `# Install PAN-Z into ZCode
+
+PAN-Z bridges PAN's engine to ZCode over MCP. Finish setup inside ZCode:
+
+1. **Register the MCP server.** Add the contents of \`pan-mcp.json\` to ZCode's MCP
+   configuration (Settings → MCP), or point ZCode's MCP config at this file. This
+   exposes the \`pan_*\` tools (state, plan, verify, report, next-action, merge gate).
+
+2. **Import the subagents.** The \`agents/\` folder holds PAN agents in ZCode subagent
+   form. Prefer ZCode's **Import from Claude Code** / Settings → Subagents to register
+   them, since ZCode owns the on-disk format (it is a fast-moving Beta). These files are
+   a fallback, not a contract.
+
+3. **Protect your branches.** The merge gate (\`pan_confirm_merge\`) is one lock; the
+   real, non-bypassable one is **server-side branch protection** on your remote. Enable
+   required reviews so a raw push under Full Access cannot merge. Approve a staged merge
+   by setting \`PAN_MERGE_APPROVAL=<request-id>\` in the MCP server's environment.
+
+4. **Never run the install/import step in ZCode Full Access mode.**
+
+Not yet resolved (the M0 verify spike, on your real ZCode): whether a subagent can call
+MCP tools, and whether local stdio MCP calls are metered. Until confirmed, the primary
+Agent makes every pan-mcp call.
+`;
+
+/** Real path of the nearest EXISTING ancestor of p, with the not-yet-created tail re-attached. */
+function realpathNearest(p) {
+  const tail = [];
+  let cur = path.resolve(p);
+  for (;;) {
+    try {
+      const real = fs.realpathSync(cur);
+      return tail.length ? path.join(real, ...tail) : real;
+    } catch {
+      const parent = path.dirname(cur);
+      if (parent === cur) return path.resolve(p); // hit the root; nothing existed
+      tail.unshift(path.basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+function assertNotInSourceRepo(destDir, repoRoot) {
+  // Resolve symlinks/junctions (a --target under a junction into the repo would else
+  // slip past) and case-fold on case-insensitive filesystems (NTFS/APFS) so a
+  // case-variant path can't bypass the guard.
+  const ci = process.platform === 'win32' || process.platform === 'darwin';
+  const norm = (p) => { const r = realpathNearest(p); return ci ? r.toLowerCase() : r; };
+  const d = norm(destDir);
+  const r = norm(repoRoot);
+  if (d === r || d.startsWith(r + path.sep)) {
+    throw new Error('Refusing to write the PAN-Z bundle inside the PAN source repo. Choose a --target outside it.');
+  }
+}
+
+/**
+ * Build the bundle.
+ * @param {{repoRoot:string, destDir:string, projectRoot?:string}} o
+ * @returns {{agents:number, destDir:string, mcp:Object, files:string[]}}
+ */
+function buildBundle(o) {
+  const repoRoot = path.resolve(o.repoRoot);
+  const destDir = path.resolve(o.destDir);
+  assertNotInSourceRepo(destDir, repoRoot);
+
+  const agentsSrc = path.join(repoRoot, 'agents');
+  const serverPath = path.join(repoRoot, 'pan-zcode', 'mcp', 'server.cjs');
+  const panToolsPath = path.join(repoRoot, 'pan-wizard-core', 'bin', 'pan-tools.cjs');
+
+  fs.mkdirSync(destDir, { recursive: true });
+  const agents = fs.existsSync(agentsSrc) ? convertAgentsDir(agentsSrc, path.join(destDir, 'agents')) : [];
+
+  const mcp = mcpServerConfig(panToolsPath, serverPath, o.projectRoot);
+  fs.writeFileSync(path.join(destDir, 'pan-mcp.json'), JSON.stringify(mcp, null, 2), 'utf8');
+
+  const manifest = {
+    subsystem: 'pan-zcode',
+    agents: agents.map((a) => a.name),
+    mcp_config: 'pan-mcp.json',
+    server: serverPath,
+    pan_tools: panToolsPath,
+  };
+  fs.writeFileSync(path.join(destDir, 'pan-zcode-manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+  fs.writeFileSync(path.join(destDir, 'INSTALL-ZCODE.md'), INSTRUCTIONS, 'utf8');
+
+  return { agents: agents.length, destDir, mcp, files: ['agents/', 'pan-mcp.json', 'pan-zcode-manifest.json', 'INSTALL-ZCODE.md'] };
+}
+
+function getArg(args, name) {
+  const i = args.indexOf(name);
+  return i !== -1 && i + 1 < args.length ? args[i + 1] : null;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const target = getArg(args, '--target');
+  if (!target) {
+    console.error('Usage: install-zcode.js --target <dir> [--project-root <dir>]');
+    console.error('Writes the PAN-Z ZCode bundle to <dir> (outside the PAN source repo).');
+    process.exit(2);
+  }
+  const repoRoot = path.resolve(__dirname, '..', '..');
+  try {
+    const res = buildBundle({ repoRoot, destDir: target, projectRoot: getArg(args, '--project-root') });
+    console.log(`pan-zcode bundle written to ${res.destDir} (${res.agents} subagents + MCP config).`);
+    console.log('Next: open INSTALL-ZCODE.md and finish setup inside ZCode.');
+  } catch (e) {
+    console.error(`install-zcode: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = { buildBundle, mcpServerConfig, assertNotInSourceRepo };