pan-wizard 3.32.0 → 3.34.0

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,
@@ -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` |
@@ -136,6 +138,10 @@ TEST_TOTAL: ${TEST_COUNT}
 TEST_PASSED: ${TEST_PASS}
 TEST_FAILED: ${TEST_FAIL}
 ```
+   Write `test_gate: ${TEST_GATE_STATUS}` into the verification.md frontmatter. When it is
+   `skipped`, also add a `not_checked` entry (`check: "tests"`, `reason: "no test script in
+   package.json"`). The recorder reads both: a pass whose tests never ran is recorded as a
+   pass with tests not checked, never as a plain pass.
 
 **If test gate FAILED:** Continue verification (gather full picture) but set overall status to `gaps_found` regardless of goal-backward results. Include test failures as gaps in the report.
 </step>
@@ -146,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.
 
@@ -161,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:
@@ -196,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
@@ -228,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
@@ -238,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):**
 
@@ -256,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.
@@ -284,7 +290,7 @@ Format each as: Test Name → What to do → Expected result → Why can't verif
 </step>
 
 <step name="determine_status">
-**passed:** All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns, AND test gate passed or skipped.
+**passed:** All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns, AND test gate passed or skipped. A skipped gate is listed in `not_checked` with its reason, and the report to the user says the tests did not run.
 
 **gaps_found:** Any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, blocker found, OR test gate FAILED (test regressions detected).
 
@@ -305,10 +311,11 @@ 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)
 ```
 
-Fill template sections: frontmatter (phase/timestamp/status/score), **test gate results** (status/total/passed/failed), goal achievement, artifact table, wiring table, requirements coverage, anti-patterns, human verification, gaps summary, fix plans (if gaps_found), metadata.
+Fill template sections: frontmatter (phase/timestamp/`verified_commit: ${VERIFIED_COMMIT}`/status/score/`test_gate`), **test gate results** (status/total/passed/failed), goal achievement, artifact table, wiring table, requirements coverage, anti-patterns, human verification, gaps summary, fix plans (if gaps_found), metadata.
 
 See ~/.claude/pan-wizard-core/templates/verification-report.md for complete template.
 </step>
@@ -323,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-agent-plugin.js

@@ -5,7 +5,9 @@
  *
  *   plugin.json                   closed-schema manifest ($schema + name + metadata)
  *   skills/pan-<name>/SKILL.md    every PAN command as an Agent Skill, from the
- *                                 ONE unified-skills compiler (ADR-0028)
+ *                                 ONE unified-skills compiler (ADR-0028); a skill
+ *                                 over Codex's 8,000-byte plugin cut is a pointer
+ *                                 page plus references/instructions.md (S8)
  *   mcp.json                      the bundled bridge, launched as
  *                                 `node ${PLUGIN_ROOT}/pan-wizard-core/mcp/server.cjs`
  *   pan-wizard-core/              dispatcher + modules + workflows + templates +
@@ -74,9 +76,14 @@ function assertSafeToReplace(dir) {
   throw new Error(`build-agent-plugin: refusing to replace ${dir} — it is non-empty and does not look like a previous bundle build (no Agent Plugins plugin.json)`);
 }
 
-/** commands/pan/**.md → skills/pan-<name>/SKILL.md, mirroring the installer's recursion. */
+/**
+ * commands/pan/**.md → skills/pan-<name>/SKILL.md, mirroring the installer's recursion.
+ * A skill longer than Codex loads from a plugin (8,000 bytes) is split: a pointer
+ * SKILL.md plus references/instructions.md (lib.splitOversizedSkill, market-ideas S8).
+ */
 function emitSkills(srcDir, skillsDir, prefix) {
   let count = 0;
+  let split = 0;
   (function recurse(currentSrc, currentPrefix) {
     for (const entry of fs.readdirSync(currentSrc, { withFileTypes: true })) {
       const srcPath = path.join(currentSrc, entry.name);
@@ -88,11 +95,18 @@ function emitSkills(srcDir, skillsDir, prefix) {
       let content = fs.readFileSync(srcPath, 'utf8');
       content = lib.rewriteUnifiedSkillCommandContent(content, REWRITE);
       content = lib.convertClaudeCommandToUnifiedSkill(content, skillName, { adapterNote: lib.agentPluginSkillAdapterNote() });
-      fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content);
+      const { skill, reference } = lib.splitOversizedSkill(content, skillName);
+      fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skill);
+      if (reference) {
+        const refPath = path.join(skillDir, ...lib.AGENT_PLUGIN_SKILL_REFERENCE.split('/'));
+        fs.mkdirSync(path.dirname(refPath), { recursive: true });
+        fs.writeFileSync(refPath, reference);
+        split++;
+      }
       count++;
     }
   })(srcDir, prefix);
-  return count;
+  return { count, split };
 }
 
 /** pan-wizard-core → bundle, markdown rewritten, everything else verbatim. */
@@ -214,7 +228,7 @@ function main() {
   const copilotAgents = emitCopilotNamespace(path.join(ROOT, 'agents'), path.join(OUT, lib.COPILOT_PLUGIN_NAMESPACE));
 
   console.log('PAN Agent Plugins bundle built at', path.relative(ROOT, OUT) || OUT);
-  console.log('  skills:', skills);
+  console.log('  skills:', skills.count, `(${skills.split} as a short SKILL.md + ${lib.AGENT_PLUGIN_SKILL_REFERENCE})`);
   console.log('  agent reference copies:', agents);
   console.log('  hook scripts:', hookScripts.length);
   console.log(`  ${lib.COPILOT_PLUGIN_NAMESPACE}/agents:`, copilotAgents);

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)

package/scripts/test-surface.cjs

@@ -69,6 +69,10 @@ const EVENT_HOOKS = Object.freeze({
   subagentStop: ['pan-cost-logger.js', 'pan-trace-logger.js'],
   stop: ['pan-stop-guard.js'],
   compact: ['pan-state-reinject.js'],
+  // Gemini and Copilot (market-ideas M33): the marker before a compaction, and the
+  // block on the next tool result — the same script in two modes.
+  compactMark: ['pan-state-reinject.js'],
+  compactInject: ['pan-state-reinject.js'],
 });
 
 // ─── Parsers (pure) ─────────────────────────────────────────────────────────