pan-wizard 3.33.0 → 3.35.0

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

@@ -4,7 +4,7 @@
 
 1. `.planning/state.md`
 2. `.planning/project.md`
-3. `.planning/roadmap.md`
+3. The current phase's roadmap slice (`.planning/phases/XX-current/XX-roadmap-slice.md`) — not the whole roadmap.md (Route A takes the next phase from `phase complete` and `roadmap get-phase`)
 4. Current phase's plan files (`*-plan.md`)
 5. Current phase's summary files (`*-summary.md`)
 
@@ -152,9 +152,11 @@ If found, delete them — phase is complete, handoffs are stale.
 **Delegate roadmap.md and state.md updates to pan-tools:**
 
 ```bash
-TRANSITION=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase complete "${current_phase}")
+TRANSITION=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase complete "${current_phase}")   # skip when exec-phase invoked this workflow: its `phase complete` already ran — reuse that result
 ```
 
+`phase complete` runs the phase gate first. Exit 1 with `error: phase_gate_refused` (`workflow.phase_gate: enforce`) means the phase was not marked complete: show `gate.reasons` and stop the transition. With `gate.ok` false under `warn`, the phase was marked complete: show the reasons as warnings before continuing.
+
 The CLI handles:
 - Marking the phase checkbox as `[x]` complete with today's date
 - Updating plan count to final (e.g., "3/3 plans complete")
@@ -358,9 +360,9 @@ Then Edit state.md (still under the P-1604 batched-write policy — fold this Ed
 **Format:**
 
 ```markdown
-Last session: [today]
-Stopped at: Phase [X] complete, ready to plan Phase [X+1]
-Resume file: None
+**Last session:** [today]
+**Stopped At:** Phase [X] complete, ready to plan Phase [X+1]
+**Resume File:** None
 ```
 
 **Step complete when:**
@@ -396,12 +398,12 @@ This returns all phases with goals, disk status, and completion info.
 
 **Route A: More phases remain in milestone**
 
-Read roadmap.md to get the next phase's name and goal.
+Take the name from `next_phase_name` (the `phase complete` result) and the goal from `roadmap get-phase "${next_phase}"`, not the whole roadmap.md.
 
 **Check if next phase has context.md:**
 
 ```bash
-ls .planning/phases/*[X+1]*/*-context.md 2>/dev/null
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${next_phase}"   # has_context is true when the next phase has a context.md
 ```
 
 **If next phase exists:**
@@ -448,11 +450,12 @@ Task(
     <instructions>
     1. Read plan-phase.md from execution_context for your complete workflow.
     2. Follow ALL steps: initialize, validate_phase, load context.md, handle research (P-1401 bypass if applicable), spawn pan-planner, optionally spawn pan-plan-checker, then auto-advance to exec-phase via Task (per plan-phase.md step 14).
-    3. After exec-phase completes and verification passes, exec-phase will return to its own auto-advance handler which spawns transition.md — that transition will spawn Phase ${NEXT_PHASE}+1 via this same pattern, recursing until milestone-done.
-    4. Do NOT use the Skill tool or /pan: commands. Do NOT exit early — let the recursion run.
+    3. plan-phase step 14 spawns exec-phase with --no-transition, so exec-phase returns without running transition.md and the chain ends there: on PHASE COMPLETE plan-phase prints `/pan:discuss-phase {next} --auto` as the next step; on GAPS FOUND it stops and reports the gaps.
+    4. Do NOT use the Skill tool or /pan: commands. Do NOT exit early — wait for the exec-phase Task to return.
     </instructions>
   ",
   subagent_type="general-purpose",
+  model="$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-conductor --raw)",
   description="Plan Phase ${NEXT_PHASE}"
 )
 ```
@@ -495,12 +498,13 @@ Task(
     </instructions>
   ",
   subagent_type="general-purpose",
+  model="$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-conductor --raw)",
   description="Discuss Phase ${NEXT_PHASE}"
 )
 ```
 
 **Handle next-phase Task return:**
-- **PHASE COMPLETE** (the spawned chain reached verification + roadmap update for ${NEXT_PHASE} and beyond, and either hit milestone-done or recursed further) → Done. Workflow chain finished.
+- **PHASE COMPLETE** (the spawned chain reached verification + roadmap update for ${NEXT_PHASE} and stopped at that phase's boundary; plan-phase printed `/pan:discuss-phase {next} --auto`) → Done. Workflow chain finished.
 - **GAPS FOUND / FAILED / TIMEOUT** → Display the failure, stop the recursion, return status to user. Do NOT attempt to skip ahead.
 
 </if>
@@ -574,10 +578,10 @@ Phase {X} marked complete.
 
 🎉 Milestone {version} is 100% complete — all {N} phases finished!
 
-⚡ Auto-continuing: Complete milestone and archive
+Auto-advance stops at the milestone boundary. Next: /pan:milestone-done {version}
 ```
 
-Exit skill and invoke SlashCommand("/pan:milestone-done {version}")
+Stop here and show `/pan:milestone-done {version}` as the next step: the milestone boundary ends the auto chain (auto-advance was cleared above).
 
 </if>
 

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

@@ -24,19 +24,32 @@ case "$VERSION_FILE" in
   ./*) SCOPE="LOCAL" ;;
   *)   SCOPE="GLOBAL" ;;
 esac
+# The same templated path names the runtime: the installer rewrites ~/.claude/ to
+# this runtime's own directory. With no runtime flag the installer installs Claude
+# Code only, so the flag must be passed.
+case "$VERSION_FILE" in
+  *.codex/*)  RUNTIME="--codex" ;;
+  *.gemini/*) RUNTIME="--gemini" ;;
+  *opencode/*) RUNTIME="--opencode" ;;
+  *.github/*|*.copilot/*) RUNTIME="--copilot" ;;
+  *)          RUNTIME="--claude" ;;
+esac
 
 if [ -f "$VERSION_FILE" ] && [ -f "$MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$VERSION_FILE"; then
   cat "$VERSION_FILE"
+  echo "$RUNTIME"
   echo "$SCOPE"
 else
   echo "UNKNOWN"
+  echo "$RUNTIME"
+  echo "$SCOPE"
 fi
 ```
 
-Parse output (there is ONE install; scope is derived from the shape of the single templated prefix):
-- If last line is "LOCAL": this install is local-scoped (templated prefix is `./`-relative); installed version is first line; use `--local`
-- If last line is "GLOBAL": this install is global-scoped (templated prefix is an absolute path); installed version is first line; use `--global`
-- If "UNKNOWN": the VERSION/marker files are missing or invalid; proceed to install step (treat as version 0.0.0)
+Parse output (there is ONE install; scope and runtime are derived from the single templated prefix). The output is three lines: the installed version (or `UNKNOWN`), the runtime flag (`--claude`, `--codex`, `--gemini`, `--opencode` or `--copilot`) and the scope. Remember the runtime flag: the install step writes it into its command.
+- If last line is "LOCAL": this install is local-scoped (templated prefix is `./`-relative); use `--local`
+- If last line is "GLOBAL": this install is global-scoped (templated prefix is an absolute path); use `--global`
+- If the first line is "UNKNOWN": the VERSION/marker files are missing or invalid; proceed to install step (treat as version 0.0.0) — the runtime and scope lines still apply
 
 **If VERSION file missing:**
 ```
@@ -63,7 +76,7 @@ npm view pan-wizard version 2>/dev/null
 ```
 Couldn't check for updates (offline or npm unavailable).
 
-To update manually: `npx pan-wizard --global`
+To update manually: `npx -y pan-wizard@latest {runtime_flag} --global` (`--local` for a local install), with the runtime flag and scope step 1 printed
 ```
 
 Exit.
@@ -155,28 +168,23 @@ Run the update using the install type detected in step 1:
 
 **If LOCAL install:**
 ```bash
-npx -y pan-wizard@latest --local
+npx -y pan-wizard@latest {runtime_flag} --local
 ```
 
-**If GLOBAL install (or unknown):**
+**If GLOBAL install:**
 ```bash
-npx -y pan-wizard@latest --global
+npx -y pan-wizard@latest {runtime_flag} --global
 ```
 
-Capture output. If install fails, show error and exit.
+`{runtime_flag}` is the runtime line step 1 printed: write the flag itself into the command. A variable set in step 1's shell call is gone in this one (each Bash call starts a new shell), and an empty `""` argument in its place installs Claude Code only. A `--config-dir` or `--unified-skills` install is not recognised from its path: for those, re-run the installer with your original flags instead.
 
-Clear the update cache so statusline indicator disappears:
+Capture output. If install fails, show error and exit.
 
-**If LOCAL install:**
-```bash
-rm -f ~/.claude/cache/pan-update-check.json
-```
+Clear the update cache so the statusline indicator disappears. The update-check hook keeps it under your home directory for every install, local or global, in the runtime's own config directory: `.claude` (Claude Code), `.codex` (Codex), `.gemini` (Gemini CLI) or `.copilot` (Copilot CLI); OpenCode runs no update-check hook, so there is nothing to clear there:
 
-**If GLOBAL install:**
 ```bash
-rm -f ~/.claude/cache/pan-update-check.json
+rm -f "$HOME/<config dir from the list above>/cache/pan-update-check.json"
 ```
-(Paths are templated at install time for runtime compatibility)
 </step>
 
 <step name="display_result">

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

@@ -22,7 +22,7 @@ Then verify each level against the actual codebase.
 @~/.claude/pan-wizard-core/references/guardrails.md
 @~/.claude/pan-wizard-core/templates/verification-report.md
 
-> **Also see:** `~/.claude/pan-wizard-core/learnings/universal/` — AI-derived patterns from prior experiments. **Don't skim the whole folder.** Run `pan-tools learn topics-for --agent verifier --token-budget 5000 --raw` to load only the topics tagged relevant for verification at the configured budget. Per P-RES-002 (distractor-density research), reading every topic degrades reasoning even at modest token counts.
+> **Also see:** `~/.claude/pan-wizard-core/learnings/universal/` — AI-derived patterns from prior experiments. **Don't skim the whole folder.** Run `pan-tools learn topics-for --agent verifier --cue "<phase goal; the files it touches>" --token-budget 5000 --raw` to load the topics that match this task, within the budget; if none matches, it falls back to the topics tagged relevant for verification. Per P-RES-002 (distractor-density research), reading every topic degrades reasoning even at modest token counts.
 </required_reading>
 
 ## Re-Read Checkpoints
@@ -47,14 +47,15 @@ INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${PHASE_A
 
 Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `has_plans`, `plan_count`.
 
-Then load phase details and list plans/summaries:
+Then load phase details, write the phase's roadmap slice, and list plans/summaries:
 ```bash
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${phase_number}"
-grep -E "^\|[^|]*\| *Phase +${phase_number} " .planning/requirements.md 2>/dev/null
+SLICE_PATH=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap slice "${phase_number}" --write --raw)
+grep -E "^\|[^|]*\| *Phase +0*${phase_number#0} " .planning/requirements.md 2>/dev/null
 ls "$phase_dir"/*-summary.md "$phase_dir"/*-plan.md 2>/dev/null
 ```
 
-Extract **phase goal** from roadmap.md (the outcome to verify, not tasks) and **requirements** from requirements.md if it exists.
+Extract the **phase goal** and success criteria from `get-phase` (the outcome to verify, not tasks), and the phase's **requirements** from `$SLICE_PATH` (its `## Its requirements` lines). Do not read roadmap.md or requirements.md whole: on a long project they are the largest files in `.planning/`, and the slice carries what verification needs from them. If `SLICE_PATH` is empty, grep requirements.md for the phase's IDs instead.
 </step>
 
 <step name="check_prior_verification">
@@ -62,7 +63,7 @@ Extract **phase goal** from roadmap.md (the outcome to verify, not tasks) and **
 
 If `phase_number` > 1:
 ```bash
-PREV=$((phase_number - 1))
+case "$phase_number" in *.*) PREV="${phase_number%%.*}" ;; *[A-Za-z]) PREV="${phase_number%[A-Za-z]}" ;; *) PREV=$((10#$phase_number - 1)) ;; esac
 # Resolve the previous phase's directory via find-phase (handles zero-padding
 # and the .planning/phases/ layout), like exec-phase does — do NOT glob
 # .planning/phase-N*/ (wrong dir, unpadded, matches nothing). With --raw,
@@ -104,15 +105,15 @@ HAS_TEST=$(node -e "try{const p=require('./package.json');process.stdout.write(p
 ```bash
 TEST_OUTPUT=$(npm test 2>&1)
 TEST_EXIT=$?
-TEST_COUNT=$(echo "$TEST_OUTPUT" | grep -E "^ℹ tests" | awk '{print $NF}')
-TEST_PASS=$(echo "$TEST_OUTPUT" | grep -E "^ℹ pass" | awk '{print $NF}')
-TEST_FAIL=$(echo "$TEST_OUTPUT" | grep -E "^ℹ fail" | awk '{print $NF}')
+TEST_COUNT=$(echo "$TEST_OUTPUT" | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
+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.
 
 **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
+`ℹ fail` / `# 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.
@@ -120,6 +121,7 @@ executed. Empty is not zero. Judge the exit code, then the counts.
 | Condition | Action |
 |-----------|--------|
 | `TEST_EXIT` = 0 **and** `TEST_FAIL` = 0 (a real number) | Record counts, continue to must-haves |
+| `TEST_EXIT` = 0 **and** no `ℹ`/`#` count lines (a runner other than Node's built-in one) | Set `test_gate_status: passed`; record the runner's own summary line as the counts |
 | `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` |
@@ -150,13 +152,13 @@ TEST_FAILED: ${TEST_FAIL}
 Use pan-tools to extract must_haves from each PLAN:
 
 ```bash
-for plan in "$PHASE_DIR"/*-plan.md; do
+for plan in "$phase_dir"/*-plan.md; do
   MUST_HAVES=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs frontmatter get "$plan" --field must_haves)
   echo "=== $plan ===" && echo "$MUST_HAVES"
 done
 ```
 
-Returns JSON: `{ truths: [...], artifacts: [...], key_links: [...] }`
+Returns `{ "must_haves": { truths: [...], artifacts: [...], key_links: [...] } }`: each truth a string, each artifact an object (`path`, `provides`, …), each key link an object (`from`, `to`, `via`).
 
 Aggregate all must_haves across plans for phase-level verification.
 
@@ -165,7 +167,7 @@ Aggregate all must_haves across plans for phase-level verification.
 If no must_haves in frontmatter (MUST_HAVES returns error or empty), check for Success Criteria:
 
 ```bash
-PHASE_DATA=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${phase_number}" --raw)
+PHASE_DATA=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${phase_number}")
 ```
 
 Parse the `success_criteria` array from the JSON output. If non-empty:
@@ -200,7 +202,7 @@ For each truth: identify supporting artifacts → check artifact status → chec
 Use pan-tools for artifact verification against must_haves in each PLAN:
 
 ```bash
-for plan in "$PHASE_DIR"/*-plan.md; do
+for plan in "$phase_dir"/*-plan.md; do
   ARTIFACT_RESULT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify artifacts "$plan")
   echo "=== $plan ===" && echo "$ARTIFACT_RESULT"
 done
@@ -232,7 +234,7 @@ WIRED = imported AND used. ORPHANED = exists but not imported/used.
 Use pan-tools for key link verification against must_haves in each PLAN:
 
 ```bash
-for plan in "$PHASE_DIR"/*-plan.md; do
+for plan in "$phase_dir"/*-plan.md; do
   LINKS_RESULT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify key-links "$plan")
   echo "=== $plan ===" && echo "$LINKS_RESULT"
 done
@@ -242,8 +244,8 @@ Parse JSON result: `{ all_verified, verified, total, links: [{from, to, via, ver
 
 **Link status from result:**
 - `verified=true` → WIRED
-- `verified=false` with "not found" → NOT_WIRED
-- `verified=false` with "Pattern not found" → PARTIAL
+- `verified=false` with detail "Source file not found" or "Target not referenced in source" → NOT_WIRED
+- `verified=false` with detail `Pattern "…" not found in source or target` → PARTIAL
 
 **Fallback patterns (if key_links not in must_haves):**
 
@@ -260,7 +262,7 @@ Record status and evidence for each key link.
 <step name="verify_requirements">
 If requirements.md exists:
 ```bash
-grep -E "Phase ${PHASE_NUM}" .planning/requirements.md 2>/dev/null
+grep -E "^\|[^|]*\| *Phase +0*${phase_number#0} " .planning/requirements.md 2>/dev/null
 ```
 
 For each requirement: parse description → identify supporting truths/artifacts → status: ✓ SATISFIED / ✗ BLOCKED / ? NEEDS HUMAN.
@@ -309,7 +311,7 @@ If gaps_found:
 
 <step name="create_report">
 ```bash
-REPORT_PATH="$PHASE_DIR/${PHASE_NUM}-verification.md"
+REPORT_PATH="$phase_dir/${phase_number}-verification.md"
 VERIFIED_COMMIT=$(git rev-parse HEAD 2>/dev/null)
 ```
 
@@ -326,9 +328,9 @@ If human_needed: list items requiring human testing.
 
 Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execute fixes, re-verify | `human_needed` → present to user.
 
-**Record the verification.** The record adds its findings to the ledger and logs the outcome to the trace (`verdict_passed`, `verdict_failed` or `verdict_needs_human`). A re-verification is the next attempt, and it closes the gaps it no longer reports:
+**Record the verification.** The record adds its findings to the ledger and logs the outcome to the trace (`verdict_passed`, `verdict_failed` or `verdict_needs_human`). A re-verification is the next attempt. It closes the gaps it lists under `re_verification.gaps_closed`; a gap it neither reports nor answers stays open:
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "${PHASE_NUMBER}" --file "$REPORT_PATH" 2>/dev/null || true
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "${phase_number}" --file "$REPORT_PATH" 2>/dev/null || true
 ```
 Recording the same report twice is a no-op, so exec-phase recording it again after this workflow returns is safe.
 </step>

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

@@ -11,7 +11,7 @@ hard-depend on, and the go/no-go facts that can only be settled 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. |
+| 2 | Are **local stdio MCP calls metered** against the MCP-Calls quota? | The read-only aggregators (`pan://state`, `pan://phases`, `pan://progress`, `pan://health`, `pan://links`, `pan://cost`, `pan://findings`) are MCP *resources*; reads that take an argument or fail without a roadmap (`pan_find_phase`, `pan_resolve_model`, `pan_roadmap_analyze`, `pan_preview_phases`, `pan_preview_phase`) and the per-step `pan_next_action` poll are tools, which a metered quota would count; 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. |
@@ -21,7 +21,7 @@ hard-depend on, and the go/no-go facts that can only be settled on a real ZCode
 - **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."
+  mandates branch protection and "Never run the install/import step in ZCode Full Access mode."
 - **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.

package/pan-zcode/README.md

@@ -1,6 +1,6 @@
 # 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
+PAN-Z gives [ZCode](https://zcode.z.ai) (z.ai's GLM 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).
 
@@ -14,7 +14,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
+ZCode harness (GLM)              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
         │  spawn: node pan-tools.cjs <verb> --cwd <root>
@@ -28,13 +28,13 @@ registration pointing at that shared path. **Never fork a copy back under `pan-z
 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`.
+**Scope boundary (by design):** the bridge exposes `pan-tools` verbs as MCP tools/resources, plus the in-process `next-action` and merge-gate tools (M2), 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.** `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
+  **zero-dependency** JSON-RPC 2.0 stdio MCP server; read-only aggregators readable on any project → resources; reads that take an argument or fail without a roadmap, and 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
@@ -73,6 +73,6 @@ implemented.
 ## 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.
+implemented directly, in the shared bridge under `pan-wizard-core/mcp/`, rather than via an
+SDK; `pan-zcode/` holds no protocol code of its own, so a dependency added here would not
+reach the bridge.

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

@@ -38,7 +38,7 @@ 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).
+   exposes the \`pan_*\` tools (roadmap analysis, phase lookup and previews, model resolution, phase report, next-action, merge gate) and the \`pan://\` resources (state, phases, progress, health, links, cost, findings).
 
 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

package/scripts/build-hooks.js

@@ -18,6 +18,7 @@ const DIST_DIR = path.join(HOOKS_DIR, 'dist');
 // Hooks to copy (pure Node.js, no bundling needed)
 const HOOKS_TO_COPY = [
   'pan-check-update.js',
+  'pan-guard.js',
   'pan-context-monitor.js',
   'pan-statusline.js',
   'pan-cost-logger.js',

package/scripts/build-plugin.js

@@ -77,7 +77,9 @@ function rewriteContent(content) {
     .replace(/~\/\.claude\/agents\//g, `${CONTENT_PREFIX}agents/`)
     .replace(/\.\/\.claude\/agents\//g, `${CONTENT_PREFIX}agents/`)
     .replace(/~\/\.claude\//g, CONTENT_PREFIX)
-    .replace(/\.\/\.claude\//g, CONTENT_PREFIX);
+    .replace(/\.\/\.claude\//g, CONTENT_PREFIX)
+    // No `pan-tools` bin is on PATH under a plugin either: invoke it via node.
+    .replace(/\bpan-tools\b(?=\s+[a-z])/g, `node ${CONTENT_PREFIX}pan-wizard-core/bin/pan-tools.cjs`);
 }
 
 function copyTree(srcDir, destDir, transformMd) {

package/scripts/generate-skills-docs.py

@@ -222,6 +222,13 @@ def get_version() -> str:
 # SKILLS-FULL-TEXT.md generator
 # ---------------------------------------------------------------------------
 
+def wrapper_fence(content: str) -> str:
+    """A backtick fence longer than any fence inside the content, so the skill's own
+    code blocks cannot close the block that wraps it."""
+    longest = max((len(m.group(1)) for m in re.finditer(r"^ {0,3}(`{3,})", content, re.M)), default=0)
+    return "`" * max(3, longest + 1)
+
+
 def generate_full_text(shipped: list[Skill], dev: list[Skill], version: str) -> str:
     """Generate the complete full-text document."""
     lines = []
@@ -247,9 +254,10 @@ def generate_full_text(shipped: list[Skill], dev: list[Skill], version: str) ->
         w("")
         w(f"### {skill.command} ({skill.line_count} lines)")
         w("")
-        w("```markdown")
+        fence = wrapper_fence(skill.content)
+        w(f"{fence}markdown")
         w(skill.content.rstrip())
-        w("```")
+        w(fence)
         w("")
 
     w("")
@@ -265,9 +273,10 @@ def generate_full_text(shipped: list[Skill], dev: list[Skill], version: str) ->
         w("")
         w(f"### {skill.command} ({skill.line_count} lines)")
         w("")
-        w("```markdown")
+        fence = wrapper_fence(skill.content)
+        w(f"{fence}markdown")
         w(skill.content.rstrip())
-        w("```")
+        w(fence)
         w("")
 
     return "\n".join(lines)
@@ -382,11 +391,11 @@ def generate_reference(shipped: list[Skill], dev: list[Skill], version: str) ->
                 w(s.description)
                 w("")
             if s.argument_hint:
-                w(f"```")
+                w("```text")
                 w(f"{s.command} {s.argument_hint}")
                 w(f"```")
             else:
-                w(f"```")
+                w("```text")
                 w(f"{s.command}")
                 w(f"```")
             w("")

package/scripts/prompt-lint.cjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Prompt-contract lint (program L2): the contract a shipped prompt has with the
+ * engine and the host, checked in code. Applied to commands/pan, agents and
+ * pan-wizard-core/workflows by tests/prompt-lint.test.cjs, with
+ * tests/fixtures/prompt-lint-allowlist.json (every entry names its reason, usually
+ * the plan item that fixes it).
+ *
+ *   unknown-verb        a `pan-tools <verb> [<sub>]` call naming a verb or a subcommand
+ *                       the engine does not have (tests/fixtures/surface.json)
+ *   tool-not-granted    an agent told to use a tool its frontmatter `tools:` does not grant
+ *   pasted-source       an @-include of engine source (`*.cjs` / `*.js`) into a prompt
+ *   oversized-question  an AskUserQuestion block offering more than four options (the
+ *                       host's limit: two to four)
+ *   untyped-spawn       a Task( spawn without `model=`, or a general-purpose spawn told
+ *                       to read a role file instead of naming the agent type
+ *   dev-skill           a shipped prompt sending the user to a dev-only skill of this
+ *                       repository (.claude/commands/*.md), which no install carries
+ *
+ *   node scripts/prompt-lint.cjs            # report the current tree, exit 1 on a finding
+ */
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const TOOLS = ['Write', 'Edit', 'WebSearch', 'WebFetch', 'Task'];
+
+function surface(root = ROOT) {
+  const s = JSON.parse(fs.readFileSync(path.join(root, 'tests', 'fixtures', 'surface.json'), 'utf8'));
+  const subs = new Map();
+  for (const entry of s.subcommands) {
+    const [verb, sub] = entry.split(' ');
+    if (!subs.has(verb)) subs.set(verb, new Set());
+    subs.get(verb).add(sub);
+  }
+  return { verbs: new Set(s.verbs), subs };
+}
+
+function devSkills(root = ROOT) {
+  try {
+    return fs.readdirSync(path.join(root, '.claude', 'commands')).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, ''));
+  } catch { return []; }
+}
+
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+
+function frontmatterTools(text) {
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return null;
+  const m = fm[1].match(/^tools:[ \t]*(.+)$/m);
+  return m ? new Set(m[1].split(',').map((t) => t.trim().replace(/\*$/, '')).filter(Boolean)) : null;
+}
+
+/**
+ * Lint one file's text.
+ * @param {string} rel - repository-relative path (decides which rules apply)
+ * @param {string} raw - file content
+ * @param {{verbs: Set, subs: Map, dev: string[]}} ctx
+ * @returns {Array<{rule, file, line, text}>}
+ */
+function lintText(rel, raw, ctx) {
+  const text = raw.replace(/\r\n/g, '\n');
+  const out = [];
+  const hit = (rule, index, snippet) => out.push({ rule, file: rel, line: lineOf(text, index), text: String(snippet).trim().slice(0, 140) });
+
+  // unknown-verb
+  // An invocation, not prose: the script path (`pan-tools.cjs <verb>`) or a backticked `pan-tools <verb>`.
+  const callRe = /(?:pan-tools\.cjs"?|`pan-tools)[ \t]+([a-z][a-z0-9-]*)(?:[ \t]+([a-z][a-z0-9-]*))?/g;
+  let m;
+  while ((m = callRe.exec(text))) {
+    const [, verb, sub] = m;
+    if (!ctx.verbs.has(verb)) { hit('unknown-verb', m.index, m[0]); continue; }
+    const known = ctx.subs.get(verb);
+    if (known && sub && !known.has(sub) && !ctx.verbs.has(sub)) hit('unknown-verb', m.index, m[0]);
+  }
+
+  // pasted-source
+  const incRe = /^@\S+\.(?:cjs|mjs|js)\s*$/gm;
+  while ((m = incRe.exec(text))) hit('pasted-source', m.index, m[0]);
+
+  // tool-not-granted (agents only)
+  if (rel.startsWith('agents/')) {
+    const granted = frontmatterTools(text);
+    if (granted) {
+      for (const tool of TOOLS) {
+        if (granted.has(tool)) continue;
+        const re = new RegExp(`\\b(?:use|using|with|via|call|run)\\s+(?:the\\s+)?\`?${tool}\`?(?:\\s+tool)?\\b|\\bthe\\s+\`?${tool}\`?\\s+tool\\b`, 'g');
+        let mm;
+        while ((mm = re.exec(text))) {
+          // "Never use Edit or Write tools" is the rule being kept, not broken.
+          const before = text.slice(Math.max(0, mm.index - 24), mm.index).toLowerCase();
+          if (/\b(never|not|don't|do not|no)\s*$/.test(before)) continue;
+          hit('tool-not-granted', mm.index, `${tool} (granted: ${[...granted].join(', ')}): ${mm[0]}`);
+          break;
+        }
+      }
+    }
+  }
+
+  // oversized-question
+  const askRe = /AskUserQuestion/g;
+  while ((m = askRe.exec(text))) {
+    const window = text.slice(m.index, m.index + 6000);
+    const optRe = /options\s*:\s*\[/g;
+    let o;
+    while ((o = optRe.exec(window))) {
+      let depth = 0;
+      let end = -1;
+      for (let i = o.index + o[0].length - 1; i < window.length; i++) {
+        if (window[i] === '[') depth++;
+        else if (window[i] === ']') { depth--; if (depth === 0) { end = i; break; } }
+      }
+      if (end < 0) break;
+      const labels = (window.slice(o.index, end).match(/\blabel\s*:/g) || []).length;
+      if (labels > 4) hit('oversized-question', m.index + o.index, `${labels} options in one question`);
+      optRe.lastIndex = end;
+    }
+    askRe.lastIndex = m.index + 1;
+  }
+
+  // untyped-spawn (workflows and commands)
+  if (!rel.startsWith('agents/')) {
+    const lines = text.split('\n');
+    lines.forEach((l, i) => {
+      if (!/^\s*Task\(/.test(l)) return;
+      let j = i;
+      while (j < lines.length - 1 && !/^\s*\)\s*$/.test(lines[j]) && !/description="[^"]*"\s*\)\s*$/.test(lines[j])) j++;
+      const block = lines.slice(i, j + 1).join('\n');
+      const at = lines.slice(0, i).join('\n').length + 1;
+      if (!/\bmodel\s*=/.test(block)) hit('untyped-spawn', at, 'a Task( spawn without model=');
+      else if (/subagent_type="general-purpose"/.test(block) && /agents\/pan-[a-z-]+\.md for your role/.test(block)) hit('untyped-spawn', at, 'general-purpose spawn told to read a role file');
+    });
+  }
+
+  // dev-skill
+  if (ctx.dev.length) {
+    // Every regex metacharacter escaped, backslash included (inline: CodeQL does not follow a helper).
+    const names = ctx.dev.map((d) => d.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&'));
+    const devRe = new RegExp(`(^|[\\s\`'"(])/(${names.join('|')})(?=[\\s\`'".,;:)]|$)`, 'gm');
+    while ((m = devRe.exec(text))) hit('dev-skill', m.index + m[1].length, m[0]);
+  }
+  return out;
+}
+
+/** The shipped prompt files, repository-relative. */
+function shippedPrompts(root = ROOT) {
+  const list = [];
+  for (const dir of ['commands/pan', 'agents', 'pan-wizard-core/workflows']) {
+    for (const f of fs.readdirSync(path.join(root, dir)).filter((x) => x.endsWith('.md')).sort()) list.push(`${dir}/${f}`);
+  }
+  return list;
+}
+
+function lintTree(root = ROOT) {
+  const ctx = { ...surface(root), dev: devSkills(root) };
+  return shippedPrompts(root).flatMap((rel) => lintText(rel, fs.readFileSync(path.join(root, rel), 'utf8'), ctx));
+}
+
+if (require.main === module) {
+  const findings = lintTree();
+  for (const f of findings) process.stdout.write(`${f.rule} ${f.file}:${f.line} — ${f.text}\n`);
+  process.stdout.write(`${findings.length} finding(s)\n`);
+  process.exitCode = findings.length ? 1 : 0;
+}
+
+module.exports = { lintText, lintTree, shippedPrompts, surface, devSkills, frontmatterTools };