pan-wizard 3.25.0 → 3.27.0

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

@@ -0,0 +1,179 @@
+'use strict';
+
+/**
+ * The deterministic orchestrator ("next-action" state machine).
+ *
+ * A host with no workflow engine cannot machine-intercept a subagent spawn, so
+ * PAN's sequencing + safety harness (waves, regression circuit-breaker,
+ * spawn/budget caps, the human merge gate) cannot live in agent prose or a
+ * pre-spawn hook. The fix: keep the state machine here and expose ONE
+ * `next-action` tool the primary Agent polls before each step. Enforcement then
+ * happens at the (gateable) MCP-tool-call boundary, not at the (un-gateable)
+ * spawn event.
+ *
+ * `nextAction` is a PURE function of a snapshot, so its decisions are
+ * reproducible and unit-testable.
+ *
+ * ─── THE VOCABULARY, and why it is what it is ──────────────────────────────
+ *
+ * An external audit (2026-08-15) found this machine keyed on statuses that
+ * NOTHING IN PAN EMITS. It expected `executed` and `verified`; the only producer
+ * of a phase status is `classifyPhaseStatus()` (bin/lib/utils.cjs), which emits
+ *
+ *     complete · partial · planned · researched · discussed · empty
+ *
+ * The consequences were severe and all three were reproduced before this rewrite:
+ *
+ *   1. `verify` and `request_merge` were UNREACHABLE. A phase ran
+ *      planned → execute → complete and the machine moved to the next one, so
+ *      **the human merge gate — the safety centrepiece — was skipped entirely.**
+ *   2. `partial` had no entry and fell through to `plan`, re-planning a
+ *      half-executed phase forever (a live-lock).
+ *   3. `pan://progress` reports Title Case (`"Planned"`), so a caller following
+ *      this file's own instruction to assemble the snapshot from the MCP
+ *      resources got `undefined` → `plan` on every cycle, forever.
+ *
+ * The suite was green throughout because its fixtures spoke `executed`/`verified`
+ * — a vocabulary no producer emits. The fixture was MORE capable than reality and
+ * therefore produced false confidence. Fixtures here must use the real vocabulary.
+ *
+ * ─── The model now ─────────────────────────────────────────────────────────
+ *
+ * Disk status answers "how far did the artifacts get?". It cannot answer "was
+ * this verified?" or "was it merged?" — those are RUN facts, known to the caller
+ * that just performed them, and no file on disk records them. So a phase carries
+ * its disk status plus two optional booleans:
+ *
+ *     { number, status, verified?: boolean, merged?: boolean }
+ *
+ * which makes the full ladder reachable from the vocabulary PAN actually emits:
+ *
+ *     planned                        → execute
+ *     partial                        → execute   (RESUME, never re-plan)
+ *     empty | discussed | researched → plan
+ *     complete & !verified           → verify
+ *     complete &  verified & !merged → request_merge
+ *     complete &  verified &  merged → (skip; this phase is finished)
+ */
+
+// Budget is advisory by default (enforceBudget:false) — it never stops the loop
+// unless the caller opts in. maxCycles remains a hard safety stop.
+const DEFAULT_CAPS = { maxCycles: 25, budget: Infinity, enforceBudget: false };
+
+/**
+ * Disk status → next action, for statuses that precede execution.
+ * Keys are the REAL `classifyPhaseStatus()` vocabulary. `complete` is absent on
+ * purpose: what follows completion depends on the run facts, not on disk.
+ *
+ * The two legacy keys are retained as aliases so a caller written against the
+ * old contract keeps working, but nothing in PAN produces them.
+ */
+const PHASE_NEXT = {
+  // real disk vocabulary
+  empty: 'plan',
+  discussed: 'plan',
+  researched: 'plan',
+  planned: 'execute',
+  partial: 'execute',
+  // legacy aliases — no producer emits these; kept for callers written against
+  // the pre-2026-08 contract. Do NOT use them in new fixtures.
+  none: 'plan',
+  executed: 'verify',
+  verified: 'request_merge',
+};
+
+/** Statuses meaning "the artifacts are all there". */
+const COMPLETE_STATUS = 'complete';
+
+/**
+ * Normalise a status to the lowercase vocabulary the table keys on.
+ *
+ * `pan://progress` emits Title Case (`"Planned"`) while `roadmap analyze` emits
+ * lowercase (`"planned"`); this file's docs point callers at the resources, so
+ * the Title Case form is the one a compliant caller will actually send. Folding
+ * case here is what makes the documented assembly path work at all.
+ */
+function normalizeStatus(status) {
+  return typeof status === 'string' ? status.trim().toLowerCase() : '';
+}
+
+/** True when a phase still needs work of any kind. */
+function isPhaseOpen(phase) {
+  if (!phase || typeof phase !== 'object') return false;
+  const status = normalizeStatus(phase.status);
+  if (status !== COMPLETE_STATUS) return true;
+  // Complete on disk, but the run facts decide whether it is actually finished.
+  return !(phase.verified === true && phase.merged === true);
+}
+
+/**
+ * Decide the next deterministic action.
+ *
+ * @param {Object} state snapshot:
+ *   { phases:[{number, status, verified?, merged?}], cycles?, points_used?,
+ *     tests_before?, tests_after?, awaiting_approval?, aborted? }
+ *   `phases` is REQUIRED. A snapshot without a usable one is reported as
+ *   `no_phases` / `done:false` — never as success (see below).
+ * @param {Object} [caps] { maxCycles, budget, enforceBudget }
+ * @returns {{action:string, args?:Object, reason:string, done:boolean}}
+ *   action ∈ plan | execute | verify | request_merge | await_approval | stop
+ */
+function nextAction(state, caps) {
+  const c = Object.assign({}, DEFAULT_CAPS, caps || {});
+  state = state || {};
+
+  // Hard stops first — safety caps and the circuit-breaker outrank all progress.
+  if (state.aborted) return { action: 'stop', reason: 'aborted', done: true };
+  if (
+    typeof state.tests_before === 'number' &&
+    typeof state.tests_after === 'number' &&
+    state.tests_after < state.tests_before
+  ) {
+    return { action: 'stop', reason: 'regression', done: true };
+  }
+  if ((state.cycles || 0) >= c.maxCycles) return { action: 'stop', reason: 'max_cycles', done: true };
+  if (c.enforceBudget && (state.points_used || 0) >= c.budget) return { action: 'stop', reason: 'budget_cap', done: true };
+
+  // The human merge gate is a barrier: while a merge awaits approval, do nothing else.
+  if (state.awaiting_approval) return { action: 'await_approval', reason: 'human_gate', done: false };
+
+  // A MISSING OR MISSHAPEN `phases` IS NOT SUCCESS.
+  //
+  // This previously collapsed to `[]`, and `[].find(...)` is indistinguishable
+  // from "every phase is complete" — so `{}`, a wrong key, or a non-array all
+  // returned all_complete/done:true. An orchestrator wrong in the "keep working"
+  // direction wastes tokens and gets noticed; one wrong in the `done:true`
+  // direction silently stops the loop and reports success. `no_phases` carries
+  // `done:false` precisely so a caller cannot mistake "I could not read this"
+  // for "the work is finished".
+  const hasPhases = Array.isArray(state.phases)
+    && state.phases.some((p) => p && typeof p === 'object' && (p.status !== undefined || p.number !== undefined));
+  if (!hasPhases) {
+    return { action: 'stop', reason: 'no_phases', done: false };
+  }
+
+  // Advance the first phase that is not finished.
+  const phase = state.phases.find(isPhaseOpen);
+  if (!phase) return { action: 'stop', reason: 'all_complete', done: true };
+
+  const status = normalizeStatus(phase.status);
+  const args = { phase: phase.number };
+
+  // Complete on disk: the run facts decide. This is the branch that makes the
+  // merge gate reachable — without it a completed phase was simply skipped.
+  if (status === COMPLETE_STATUS) {
+    if (phase.verified !== true) return { action: 'verify', args, reason: 'phase_complete_unverified', done: false };
+    return { action: 'request_merge', args, reason: 'phase_verified_unmerged', done: false };
+  }
+
+  const action = PHASE_NEXT[status];
+  if (!action) {
+    // An unknown status is a caller/producer mismatch, not a licence to re-plan.
+    // Say so, rather than silently defaulting the way the old `|| 'plan'` did —
+    // that default is what turned Title Case into an infinite plan loop.
+    return { action: 'plan', args, reason: `phase_unknown_status_${status || 'missing'}`, done: false };
+  }
+  return { action, args, reason: `phase_${status}`, done: false };
+}
+
+module.exports = { nextAction, DEFAULT_CAPS, PHASE_NEXT, normalizeStatus, isPhaseOpen };

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

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

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

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

package/pan-wizard-core/workflows/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-wizard-core/workflows/verify-phase.md

@@ -88,11 +88,18 @@ This step provides awareness; the hard gate is enforced by exec-phase.
 
 This step catches test regressions that goal-backward analysis cannot detect.
 
-1. Detect test command:
+1. Detect whether a test script exists. **This decides `skipped` vs `failed` later**, so
+   it must be answered BEFORE running anything — `npm test` on a project with no `test`
+   script exits non-zero with "Missing script", which is indistinguishable from a crash
+   once you are only looking at the exit code.
+
 ```bash
-TEST_CMD=$(node -e "const p=require('./package.json'); console.log(p.scripts && p.scripts.test || 'echo no test')")
+HAS_TEST=$(node -e "try{const p=require('./package.json');process.stdout.write(p.scripts&&p.scripts.test?'yes':'no')}catch(e){process.stdout.write('no')}")
 ```
 
+   **If `HAS_TEST` is `no`:** record `test_gate_status: skipped` and go to step 4. Do not
+   run the suite, and do not report a crash — there is nothing to run.
+
 2. Run test suite and capture results:
 ```bash
 TEST_OUTPUT=$(npm test 2>&1)
@@ -102,13 +109,25 @@ TEST_PASS=$(echo "$TEST_OUTPUT" | grep -E "^ℹ pass" | awk '{print $NF}')
 TEST_FAIL=$(echo "$TEST_OUTPUT" | grep -E "^ℹ fail" | awk '{print $NF}')
 ```
 
-3. Evaluate results:
+3. Evaluate results.
+
+**Check `TEST_EXIT` FIRST, before any count.** A suite that did not run emits no
+`ℹ fail` line at all, so `TEST_FAIL` comes back EMPTY — not `0`. Reading an empty
+value as "no failures" scores a crashed suite as a pass, which is the worst
+direction this gate can fail in: a phase ships green on a project whose tests never
+executed. Empty is not zero. Judge the exit code, then the counts.
 
 | Condition | Action |
 |-----------|--------|
-| All tests pass (`TEST_FAIL` = 0) | Record counts, continue to must-haves |
-| Tests regress (failures exist) | Set `test_gate_status: failed`, include failure details in verification report |
-| No test command found | Record as `test_gate_status: skipped`, continue |
+| `TEST_EXIT` = 0 **and** `TEST_FAIL` = 0 (a real number) | Record counts, continue to must-haves |
+| `TEST_EXIT` ≠ 0 **and** failures were reported | Set `test_gate_status: failed`, include failure details |
+| `TEST_EXIT` ≠ 0 **and** `TEST_FAIL` is empty/absent — the suite CRASHED or could not run (syntax error, missing module, bad import, no runner) | Set `test_gate_status: failed`, and record the reason as `suite did not run`. **Never `skipped`, never `passed`.** A suite that cannot execute is stronger evidence of a broken phase than one that runs and fails |
+| `HAS_TEST` = `no` (handled in step 1) | Record as `test_gate_status: skipped`, continue. This is the ONLY legitimate route to `skipped` |
+
+**The distinction that matters:** *no test command exists* is a project that never had
+tests — a known, acceptable gap. *A test command exists and did not run* is a broken
+project. They must never share a verdict; the first is `skipped`, the second is
+`failed`.
 
 4. Store test gate results for inclusion in verification.md:
 ```

package/pan-zcode/README.md

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

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

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

package/scripts/build-plugin.js

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