pan-wizard 3.33.0 → 3.34.0

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,
@@ -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)
 ```
 
@@ -328,7 +330,7 @@ Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execu
 
 **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:
 ```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-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)