pan-wizard 3.22.0 → 3.24.0

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

@@ -47,7 +47,7 @@ Exit.
 
 Read the phase artifacts (in order of priority):
 1. `${phase_dir}/*-summary.md` — what was implemented, files changed
-2. `${phase_dir}/context.md` — acceptance criteria, decisions
+2. `${phase_dir}/*-context.md` — acceptance criteria, decisions
 3. `${phase_dir}/*-verification.md` — user-verified scenarios (if UAT was done)
 
 If no summary.md exists:
@@ -341,7 +341,7 @@ If there are passing tests to commit:
 
 ```bash
 git add {test files}
-git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command"
+git commit -m "test(phase-${phase_number}): add unit and E2E tests from phase-tests command"
 ```
 
 Present next steps:

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

@@ -542,6 +542,10 @@ Check for auto-advance trigger:
    ```bash
    AUTO_CFG=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
    ```
+3. **If `--auto` flag present AND `AUTO_CFG` is not true — persist it** (same as discuss-phase's auto_advance step), so the rest of the chain and the P-1809 stop guard see the run as autonomous on disk (P-1810):
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.auto_advance true
+   ```
 
 **If `--auto` flag present OR `AUTO_CFG` is true:**
 

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

@@ -1,5 +1,5 @@
 <purpose>
-Switch the model profile used by PAN agents. Controls which Claude model each agent uses, balancing quality vs token spend.
+Switch the model profile used by PAN agents. Controls which model tier each agent uses, balancing quality vs token spend.
 </purpose>
 
 <required_reading>
@@ -88,20 +88,23 @@ Agents will now use:
 
 [Show table from MODEL_PROFILES in pan-tools.cjs for selected profile]
 
-Example:
-| Agent | Model |
-|-------|-------|
-| pan-planner | opus |
-| pan-executor | sonnet |
-| pan-verifier | haiku |
+Example (`budget` — the only profile that steps agents below the reasoning
+tier; `quality` and `balanced` put every agent on `reasoning`):
+| Agent | Tier |
+|-------|------|
+| pan-planner | mid |
+| pan-executor | mid |
+| pan-verifier | fast |
 | ... | ... |
 
 Cost estimate:
 [Run: node ~/.claude/pan-wizard-core/bin/pan-tools.cjs estimate-cost]
 Show the average cost multiplier for each profile (quality/balanced/budget)
-and highlight the selected profile. Example:
-  quality: 15.0× avg | balanced: 4.3× avg | budget: 2.2× avg
-                                              ^^^^^^^^^^^^^^^^ selected
+and highlight the selected profile — read the numbers from the command output,
+don't hardcode them (`quality` and `balanced` report the same multiplier).
+Example shape:
+  quality: <n>× avg | balanced: <n>× avg | budget: <n>× avg
+                                           ^^^^^^^^^^^^^^^^ selected
 
 Next spawned agents will use the new profile.
 ```

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

@@ -26,7 +26,7 @@ If `found` is false: Error and exit.
 ## Step 2: Check Existing Research
 
 ```bash
-ls .planning/phases/${PHASE}-*/research.md 2>/dev/null
+ls .planning/phases/*/*-research.md 2>/dev/null | grep -E "/0*${PHASE}-[^/]*/"
 ```
 
 If exists: Offer update/view/skip options.

package/pan-wizard-core/workflows/resume-project.md

@@ -67,7 +67,7 @@ ls .planning/phases/*/.continue-here*.md 2>/dev/null
 
 # Check for plans without summaries (incomplete execution)
 for plan in .planning/phases/*/*-plan.md; do
-  summary="${plan/PLAN/SUMMARY}"
+  summary="${plan%-plan.md}-summary.md"
   [ ! -f "$summary" ] && echo "Incomplete: $plan"
 done 2>/dev/null
 

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

@@ -1,5 +1,5 @@
 <purpose>
-Interactive configuration of PAN workflow agents (research, plan_check, verifier) and model profile selection via multi-question prompt. Updates .planning/config.json with user preferences. Optionally saves settings as global defaults (~/.pan-wizard-core/defaults.json) for future projects.
+Interactive configuration of PAN workflow agents (research, plan_check, verifier) and model profile selection via multi-question prompt. Updates .planning/config.json with user preferences. Optionally saves settings as global defaults (~/.pan-wizard/defaults.json) for future projects.
 </purpose>
 
 <required_reading>
@@ -44,9 +44,9 @@ AskUserQuestion([
     header: "Model",
     multiSelect: false,
     options: [
-      { label: "Quality", description: "Opus everywhere except verification (highest cost)" },
-      { label: "Balanced (Recommended)", description: "Opus for planning, Sonnet for execution/verification" },
-      { label: "Budget", description: "Sonnet for writing, Haiku for research/verification (lowest cost)" }
+      { label: "Quality", description: "reasoning tier for every agent — identical to balanced, so switching between the two changes nothing" },
+      { label: "Balanced (Recommended)", description: "reasoning tier for every agent (quality and balanced are identical post-COST-RESET); use budget to step down" },
+      { label: "Budget", description: "mid tier for writing, fast tier for research/verification (lowest cost)" }
     ]
   },
   {
@@ -153,20 +153,20 @@ AskUserQuestion([
     header: "Defaults",
     multiSelect: false,
     options: [
-      { label: "Yes", description: "New projects start with these settings (saved to ~/.pan-wizard-core/defaults.json)" },
+      { label: "Yes", description: "New projects start with these settings (saved to ~/.pan-wizard/defaults.json)" },
       { label: "No", description: "Only apply to this project" }
     ]
   }
 ])
 ```
 
-If "Yes": write the same config object (minus project-specific fields like `brave_search`) to `~/.pan-wizard-core/defaults.json`:
+If "Yes": write the same config object (minus project-specific fields like `brave_search`) to `~/.pan-wizard/defaults.json`:
 
 ```bash
-mkdir -p ~/.gsd
+mkdir -p ~/.pan-wizard
 ```
 
-Write `~/.pan-wizard-core/defaults.json` with:
+Write `~/.pan-wizard/defaults.json` with:
 ```json
 {
   "mode": <current>,
@@ -222,6 +222,6 @@ Quick commands:
 - [ ] Current config read
 - [ ] User presented with 7 settings (profile + 5 workflow toggles + git branching)
 - [ ] Config updated with model_profile, workflow, and git sections
-- [ ] User offered to save as global defaults (~/.pan-wizard-core/defaults.json)
+- [ ] User offered to save as global defaults (~/.pan-wizard/defaults.json)
 - [ ] Changes confirmed to user
 </success_criteria>

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

@@ -76,9 +76,20 @@ cat .planning/config.json 2>/dev/null
 
 </config-check>
 
+**Detect AUTO mode (P-1807 — gate parity with the rest of the chain):**
+
+```bash
+HAS_AUTO_FLAG=$(echo "$ARGUMENTS" | grep -c -- '--auto' || true)
+AUTO_CFG=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
+```
+
+**AUTO is active** when `HAS_AUTO_FLAG` > 0 (the `--auto` flag exec-phase passes through), OR `AUTO_CFG` is `true`, OR config `mode` is `yolo`. Every `<if auto>` gate in this workflow keys on this condition — the same trigger `exec-phase.md` (offer_next), `plan-phase.md` (step 14) and `discuss-phase.md` (auto_advance) use.
+
+**P-1807 (2026-08, PanLoop finding 0):** these gates were previously `mode: yolo` alone. This file never read `--auto` or `workflow.auto_advance`, so on the template-default `mode: interactive`, exec-phase would announce "AUTO-ADVANCING → TRANSITION", this workflow would update state to the next phase, then route to the interactive "Next Up" menu and exit cleanly — the P-1801 Task spawn below was unreachable, and every autonomous run built exactly one phase while reporting success. Do not narrow these gates back to `mode` alone.
+
 **If all plans complete:**
 
-<if mode="yolo">
+<if auto (HAS_AUTO_FLAG > 0, or AUTO_CFG true, or mode yolo)>
 
 ```
 ⚡ Auto-approved: Transition Phase [X] → Phase [X+1]
@@ -91,7 +102,7 @@ Proceed directly to cleanup_handoff step.
 
 </if>
 
-<if mode="interactive" OR="custom with gates.confirm_transition true">
+<if NOT auto — mode="interactive" OR="custom with gates.confirm_transition true">
 
 Ask: "Phase [X] complete — all [Y] plans finished. Ready to mark done and move to Phase [X+1]?"
 
@@ -157,8 +168,9 @@ Extract from result: `completed_phase`, `plans_executed`, `next_phase`, `next_ph
 
 <step name="archive_prompts">
 
-If prompts were generated for the phase, they stay in place.
-The `completed/` subfolder pattern from create-meta-prompts handles archival.
+If prompts were generated for the phase, they stay in place — plans and
+summaries remain in the phase directory as the durable record. No separate
+archival step is performed.
 
 </step>
 
@@ -361,6 +373,8 @@ Resume file: None
 
 <step name="offer_next_phase">
 
+**AUTO-mode terminal contract (P-1807):** when AUTO is active (the condition from `verify_completion`), this step has exactly two valid endings — **Route A ends with a `Task(...)` call actually issued** (not described, not deferred: issued), or **Route B reaches the milestone boundary**. Updating state.md and presenting a "Next Up" menu is NOT a valid AUTO ending — field runs (PanLoop, 2026-08-08) show that exact exit four times in five even with the gates fixed. If you notice you are composing a menu while AUTO is active, stop and execute the Route A spawn. Do not end your turn between the state update and the spawn.
+
 **MANDATORY: Verify milestone status before presenting next steps.**
 
 **Use the transition result from `pan-tools phase complete`:**
@@ -392,10 +406,12 @@ ls .planning/phases/*[X+1]*/*-context.md 2>/dev/null
 
 **If next phase exists:**
 
-<if mode="yolo">
+<if auto (HAS_AUTO_FLAG > 0, or AUTO_CFG true, or mode yolo — the P-1807 condition from verify_completion)>
 
 **P-1801 fix (v3.7.6):** In auto mode, **spawn the next phase as a Task subagent** — same pattern as `plan-phase.md`'s auto-advance to exec-phase. Prose-based "DO NOT exit. Read X" instructions (the v3.7.4 P-1701 attempt) were not behaviorally binding: the orchestrator returned from sub-agent calls and exited cleanly at the phase boundary. A `Task(...)` invocation is a tool call the orchestrator cannot ignore — control flow is forced into the next phase's workflow.
 
+**P-1807 (2026-08):** this gate was `mode: yolo` alone, which made the P-1801 spawn unreachable for `--auto` / `workflow.auto_advance` runs on interactive-mode projects — the exact symptom P-1801 fixed, reintroduced one gate higher. If exec-phase announced AUTO-ADVANCING, this branch MUST run and MUST end in the `Task(...)` call below; exiting after the state update is the regression.
+
 Cost trade-off: each Task spawn restarts context (loses the cumulative cache reads from the previous phase). Acceptable because: (1) cross-phase cache value is low — phase N's plan/research is mostly irrelevant to phase N+1's executor — and (2) reliability beats marginal cost optimization for autonomous runs.
 
 **If context.md exists for the next phase:**
@@ -489,7 +505,7 @@ Task(
 
 </if>
 
-<if mode="interactive" OR="custom with gates.confirm_transition true">
+<if NOT auto — mode="interactive" OR="custom with gates.confirm_transition true">
 
 **If context.md does NOT exist:**
 
@@ -551,7 +567,7 @@ Task(
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.auto_advance false
 ```
 
-<if mode="yolo">
+<if auto (HAS_AUTO_FLAG > 0, or AUTO_CFG true, or mode yolo — the P-1807 condition from verify_completion)>
 
 ```
 Phase {X} marked complete.
@@ -565,7 +581,7 @@ Exit skill and invoke SlashCommand("/pan:milestone-done {version}")
 
 </if>
 
-<if mode="interactive" OR="custom with gates.confirm_transition true">
+<if NOT auto — mode="interactive" OR="custom with gates.confirm_transition true">
 
 ```
 ## ✓ Phase {X}: {Phase Name} Complete

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

@@ -12,28 +12,31 @@ Read all files referenced by the invoking prompt's execution_context before star
 Detect whether PAN is installed locally or globally by checking both locations and validating install integrity:
 
 ```bash
-# Check local first (takes priority only if valid)
-# Paths templated at install time for runtime compatibility
-LOCAL_VERSION_FILE="./.claude/pan-wizard-core/VERSION"
-LOCAL_MARKER_FILE="./.claude/pan-wizard-core/workflows/update.md"
-GLOBAL_VERSION_FILE="$HOME/.claude/pan-wizard-core/VERSION"
-GLOBAL_MARKER_FILE="$HOME/.claude/pan-wizard-core/workflows/update.md"
-
-if [ -f "$LOCAL_VERSION_FILE" ] && [ -f "$LOCAL_MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$LOCAL_VERSION_FILE"; then
-  cat "$LOCAL_VERSION_FILE"
-  echo "LOCAL"
-elif [ -f "$GLOBAL_VERSION_FILE" ] && [ -f "$GLOBAL_MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$GLOBAL_VERSION_FILE"; then
-  cat "$GLOBAL_VERSION_FILE"
-  echo "GLOBAL"
+# There is ONE install location per install. The installer templates the
+# canonical ~/.claude/ prefix to this install's real path, and the SHAPE of that
+# templated prefix reveals the scope: a --local install is cwd-relative ("./…"),
+# a --global install is an absolute path. Deriving scope from the single
+# templated path avoids the collapsed dual-path detection that mis-ran every
+# global update as --local (N2 regression fix, ADR audit 2026-08).
+VERSION_FILE="~/.claude/pan-wizard-core/VERSION"
+MARKER_FILE="~/.claude/pan-wizard-core/workflows/update.md"
+case "$VERSION_FILE" in
+  ./*) SCOPE="LOCAL" ;;
+  *)   SCOPE="GLOBAL" ;;
+esac
+
+if [ -f "$VERSION_FILE" ] && [ -f "$MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$VERSION_FILE"; then
+  cat "$VERSION_FILE"
+  echo "$SCOPE"
 else
   echo "UNKNOWN"
 fi
 ```
 
-Parse output:
-- If last line is "LOCAL": local install is valid; installed version is first line; use `--local`
-- If last line is "GLOBAL": local missing/invalid, global install is valid; installed version is first line; use `--global`
-- If "UNKNOWN": proceed to install step (treat as version 0.0.0)
+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)
 
 **If VERSION file missing:**
 ```
@@ -166,7 +169,7 @@ Clear the update cache so statusline indicator disappears:
 
 **If LOCAL install:**
 ```bash
-rm -f ./.claude/cache/pan-update-check.json
+rm -f ~/.claude/cache/pan-update-check.json
 ```
 
 **If GLOBAL install:**
@@ -184,9 +187,9 @@ Format completion message (changelog was already shown in confirmation step):
 ║  PAN Updated: v1.5.10 → v1.5.15                           ║
 ╚═══════════════════════════════════════════════════════════╝
 
-⚠️  Restart Claude Code to pick up the new commands.
+⚠️  Restart your AI coding tool to pick up the new commands.
 
-[View full changelog](https://github.com/pan-wizard-core/blob/main/CHANGELOG.md)
+[View full changelog](https://github.com/oharms/PanWizard/blob/main/CHANGELOG.md)
 ```
 </step>
 

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

@@ -50,7 +50,7 @@ Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `has_plans`,
 Then load phase details and list plans/summaries:
 ```bash
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${phase_number}"
-grep -E "^| ${phase_number}" .planning/requirements.md 2>/dev/null
+grep -E "^\|[^|]*\| *Phase +${phase_number} " .planning/requirements.md 2>/dev/null
 ls "$phase_dir"/*-summary.md "$phase_dir"/*-plan.md 2>/dev/null
 ```
 
@@ -63,7 +63,12 @@ Extract **phase goal** from roadmap.md (the outcome to verify, not tasks) and **
 If `phase_number` > 1:
 ```bash
 PREV=$((phase_number - 1))
-PREV_VERIF=$(ls .planning/phase-${PREV}*/*-verification.md 2>/dev/null | head -1)
+# 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,
+# find-phase prints the resolved directory path (empty if not found).
+PREV_DIR=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs find-phase "${PREV}" --raw 2>/dev/null)
+PREV_VERIF=$([ -n "$PREV_DIR" ] && ls "$PREV_DIR"/*-verification.md 2>/dev/null | head -1)
 ```
 
 If `PREV_VERIF` is empty:

package/pan-zcode/README.md

@@ -28,8 +28,11 @@ pan-wizard-core  (reused as-is)  the deterministic engine; .planning/ stays the
 - **M1 — bridge core.** `mcp/tool-registry.cjs` (pure verb→tool/resource map, with a hard
   guardrail against exposing a force/reset/rebase/push verb) + `mcp/server.cjs` (a
   **zero-dependency** JSON-RPC 2.0 stdio MCP server; reads → resources, actions → tools with
-  accurate hints; shell-less `execFile` spawn; `@file:` overflow protocol; protocol-version
-  negotiation; strict per-arg validation).
+  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),
@@ -52,6 +55,13 @@ Two go/no-go facts can only be settled empirically: **can a subagent call MCP to
 local stdio MCP calls metered?** Both have folded-in fallbacks (see `KNOWN-BETA-RISKS.md`), so the
 design holds either way — but confirm them before relying on the richer paths.
 
+A third M0 checkpoint (added 2026-08): **which protocol era does the real ZCode client speak?**
+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
+implemented.
+
 ## Zero dependencies
 
 Like the rest of PAN, this subsystem ships **no runtime dependencies**. The MCP protocol is

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

@@ -48,7 +48,7 @@ PAN-Z bridges PAN's engine to ZCode over MCP. Finish setup inside ZCode:
 3. **Protect your branches.** The merge gate (\`pan_confirm_merge\`) is one lock; the
    real, non-bypassable one is **server-side branch protection** on your remote. Enable
    required reviews so a raw push under Full Access cannot merge. Approve a staged merge
-   by setting \`PAN_MERGE_APPROVAL=<request-id>\` in the MCP server's environment.
+   by setting \`PAN_MERGE_APPROVAL=<approval_token>\` in the MCP server's environment.
 
 4. **Never run the install/import step in ZCode Full Access mode.**
 

package/pan-zcode/mcp/native-tools.cjs

@@ -43,7 +43,7 @@ const NATIVE_TOOLS = [
   {
     name: 'pan_confirm_merge',
     title: 'Confirm a human-approved merge',
-    description: 'Perform a squash-merge ONLY if CI is green, verify passed, and a human-origin approval token (env PAN_MERGE_APPROVAL equal to the request id) is present. Any agent-supplied approval is ignored; never force-pushes or rewrites history.',
+    description: 'Perform a squash-merge ONLY if CI is green, verify passed, and a human-origin approval token (env PAN_MERGE_APPROVAL equal to the request\'s approval_token) is present. Any agent-supplied approval is ignored; never force-pushes or rewrites history.',
     readOnly: false, destructive: true,
     inputSchema: {
       type: 'object', additionalProperties: false, required: ['branch'],

package/pan-zcode/mcp/server.cjs

@@ -4,8 +4,12 @@
  * PAN-Z MCP bridge server (M1).
  *
  * A dependency-free JSON-RPC 2.0 server over stdio implementing the small MCP
- * surface ZCode needs: initialize / tools/list / tools/call / resources/list /
- * resources/read / ping. Each pan-tools verb is reached by spawning
+ * surface ZCode needs: 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
+ * request's `_meta` and MAY probe `server/discover` first. Each pan-tools verb is
+ * reached by spawning
  *   node <pan-tools.cjs> <verb> [args] --raw --cwd <root>
  * and returning its JSON — the CLI's JSON contract IS the tool contract, so the
  * PAN engine (pan-wizard-core) is reused byte-for-byte with no refactor.
@@ -26,11 +30,21 @@ const os = require('os');
 const path = require('path');
 const reg = require('./tool-registry.cjs');
 
+// Legacy `initialize` default: when a handshake-era client omits protocolVersion
+// we answer with this (never a modern version — a legacy client can't speak it).
 const PROTOCOL_VERSION = '2025-06-18';
-// Versions whose method shapes this server actually implements. During
-// `initialize` we echo the client's requested version only if it's one of these,
-// otherwise we answer with our latest — never claim to speak a version we don't.
-const SUPPORTED_PROTOCOL_VERSIONS = new Set(['2025-06-18', '2025-03-26', '2024-11-05']);
+// The modern (per-request `_meta`, stateless) revision this bridge speaks.
+const MODERN_PROTOCOL_VERSION = '2026-07-28';
+// `_meta` key a modern client uses to declare its protocol version per request.
+const META_PROTOCOL_VERSION_KEY = 'io.modelcontextprotocol/protocolVersion';
+// `_meta` key under which a server identifies itself in modern results.
+const META_SERVER_INFO_KEY = 'io.modelcontextprotocol/serverInfo';
+// Every version whose method shapes this server actually implements — the modern
+// revision plus the legacy handshake revisions. Used both for the legacy
+// `initialize` echo and for modern per-request version negotiation; we never
+// claim to speak a version we don't. Newest first (the `server/discover` order).
+const SUPPORTED_VERSIONS_LIST = [MODERN_PROTOCOL_VERSION, '2025-06-18', '2025-03-26', '2024-11-05'];
+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/. */
@@ -77,7 +91,11 @@ function resolveOverflow(stdout) {
 }
 
 function rpcResult(id, result) { return { jsonrpc: '2.0', id, result }; }
-function rpcError(id, code, message) { return { jsonrpc: '2.0', id, error: { code, message } }; }
+function rpcError(id, code, message, data) {
+  const error = { code, message };
+  if (data !== undefined) error.data = data;
+  return { jsonrpc: '2.0', id, error };
+}
 
 function toMcpTool(t) {
   return {
@@ -173,26 +191,67 @@ function createServer(opts = {}) {
     // the dispatch — this also stops any request-method sent id-less from emitting
     // an id-less response frame.
     if (id === undefined || id === null) return null;
+
+    // Era detection: a modern client (2026-07-28+) declares its protocol version
+    // in `_meta` on every request; a legacy client uses the `initialize` handshake
+    // and carries no such field. Gating modern behavior on this presence keeps the
+    // legacy path byte-for-byte unchanged.
+    const requestedVersion = params && params._meta && params._meta[META_PROTOCOL_VERSION_KEY];
+    const isModern = typeof requestedVersion === 'string';
+
+    // Stateless per-request version negotiation: if a modern client asks for a
+    // version we don't implement, answer with UnsupportedProtocolVersionError
+    // listing what we do support, so it can retry on a mutually-supported version.
+    if (isModern && !SUPPORTED_PROTOCOL_VERSIONS.has(requestedVersion)) {
+      return rpcError(id, -32022, 'Unsupported protocol version',
+        { supported: SUPPORTED_VERSIONS_LIST, requested: requestedVersion });
+    }
+
+    // Modern results MUST carry a `resultType`; legacy results MUST NOT change
+    // shape (clients treat an absent resultType as "complete"). Stamp it only on
+    // the modern path.
+    const reply = (result) => rpcResult(id,
+      isModern && result && typeof result === 'object' && result.resultType === undefined
+        ? { resultType: 'complete', ...result }
+        : result);
+
     switch (method) {
+      // Modern stateless discovery probe (MUST be implemented). Also the stdio
+      // backward-compat probe: a dual-era client sends this first; a real
+      // DiscoverResult identifies us as modern-capable, and its supportedVersions
+      // let the client pick a version before issuing any tools/resources call.
+      case 'server/discover':
+        return rpcResult(id, {
+          resultType: 'complete',
+          supportedVersions: SUPPORTED_VERSIONS_LIST,
+          capabilities: { tools: {}, resources: {} },
+          instructions: 'PAN Wizard engine bridge: planning, verification, and orchestration tools backed by the pan-tools CLI. All tools are read-only except the gated pan_confirm_merge.',
+          ttlMs: 3600000,
+          cacheScope: 'public',
+          _meta: { [META_SERVER_INFO_KEY]: SERVER_INFO },
+        });
       case 'initialize': {
         const requested = params && params.protocolVersion;
-        const negotiated = SUPPORTED_PROTOCOL_VERSIONS.has(requested) ? requested : PROTOCOL_VERSION;
+        // A legacy handshake must not negotiate a modern (per-request `_meta`)
+        // revision, so only echo legacy versions; anything else falls back.
+        const negotiated = (requested && requested !== MODERN_PROTOCOL_VERSION
+          && SUPPORTED_PROTOCOL_VERSIONS.has(requested)) ? requested : PROTOCOL_VERSION;
         return rpcResult(id, { protocolVersion: negotiated, capabilities: { tools: {}, resources: {} }, serverInfo: SERVER_INFO });
       }
       case 'ping':
-        return rpcResult(id, {});
+        return reply({});
       case 'tools/list':
-        return rpcResult(id, { tools: reg.TOOLS.map(toMcpTool) });
+        return reply({ tools: reg.TOOLS.map(toMcpTool) });
       case 'resources/list':
-        return rpcResult(id, { resources: reg.RESOURCES.map(toMcpResource) });
+        return reply({ resources: reg.RESOURCES.map(toMcpResource) });
       case 'tools/call': {
         const out = callTool(params && params.name, params && params.arguments);
-        return out.error ? rpcError(id, out.error.code, out.error.message) : rpcResult(id, out.result);
+        return out.error ? rpcError(id, out.error.code, out.error.message) : reply(out.result);
       }
       case 'resources/read': {
         const out = readResource(params && params.uri);
         if (out.unknown) return rpcError(id, -32602, `Unknown resource: ${params && params.uri}`);
-        return out.error ? rpcError(id, out.error.code, out.error.message) : rpcResult(id, out.result);
+        return out.error ? rpcError(id, out.error.code, out.error.message) : reply(out.result);
       }
       default:
         return rpcError(id, -32601, `Method not found: ${method}`);
@@ -226,4 +285,7 @@ function main() {
 
 if (require.main === module) main();
 
-module.exports = { createServer, defaultPanToolsPath, defaultSpawn, PROTOCOL_VERSION, SERVER_INFO, toMcpTool, toMcpResource };
+module.exports = {
+  createServer, defaultPanToolsPath, defaultSpawn, SERVER_INFO, toMcpTool, toMcpResource,
+  PROTOCOL_VERSION, MODERN_PROTOCOL_VERSION, SUPPORTED_VERSIONS_LIST, META_PROTOCOL_VERSION_KEY,
+};

package/scripts/build-hooks.js

@@ -21,7 +21,8 @@ const HOOKS_TO_COPY = [
   'pan-context-monitor.js',
   'pan-statusline.js',
   'pan-cost-logger.js',
-  'pan-trace-logger.js'
+  'pan-trace-logger.js',
+  'pan-stop-guard.js'
 ];
 
 function build() {

package/scripts/generate-skills-docs.py

@@ -232,8 +232,6 @@ def generate_full_text(shipped: list[Skill], dev: list[Skill], version: str) ->
     w("Every skill (slash command) available in PAN Wizard, reproduced in full.")
     w("This is the actual prompt text that Claude receives when a skill is invoked.")
     w("")
-    w(f"**Version:** {version}")
-    w("")
     w("> Auto-generated by `scripts/generate-skills-docs.py` — do not edit manually.")
     w("> For canonical counts (commands / agents / modules / etc.), see `CLAUDE.md`.")
     w("")
@@ -330,8 +328,6 @@ def generate_reference(shipped: list[Skill], dev: list[Skill], version: str) ->
     w("Complete catalog of every skill (slash command) available in PAN Wizard, organized by purpose.")
     w("Each entry shows the command, what it does, what tools it uses, and when to reach for it.")
     w("")
-    w(f"**Version:** {version}")
-    w("")
     w("> Auto-generated by `scripts/generate-skills-docs.py` — do not edit manually.")
     w("> For canonical counts (commands / agents / modules / etc.), see `CLAUDE.md`.")
     w("")

package/scripts/run-tests.cjs

@@ -6,18 +6,24 @@
  * literal pattern "tests/*.test.cjs" matches no file and the run exits 1.
  * This script expands the pattern deterministically on every platform.
  *
- * Usage: node scripts/run-tests.cjs <dir> [<dir> ...]
+ * Usage: node scripts/run-tests.cjs [--watch] <dir> [<dir> ...]
  *   Runs every *.test.cjs DIRECTLY inside each listed directory (no recursion,
  *   so `tests` and `tests/scenarios` stay separately addressable).
+ *   --watch re-runs on change. It must go through this script too: since Node 21
+ *   a bare `node --test --watch tests/` treats `tests/` as a glob pattern, fails
+ *   to match the directory as a file, and crashes having run nothing (audit L36 /
+ *   N8) — so the same deterministic expansion has to feed --watch.
  */
 
 const { spawnSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 
-const dirs = process.argv.slice(2);
+const argv = process.argv.slice(2);
+const watch = argv[0] === '--watch';
+const dirs = watch ? argv.slice(1) : argv;
 if (dirs.length === 0) {
-  console.error('Usage: node scripts/run-tests.cjs <dir> [<dir> ...]');
+  console.error('Usage: node scripts/run-tests.cjs [--watch] <dir> [<dir> ...]');
   process.exit(1);
 }
 
@@ -40,5 +46,6 @@ if (files.length === 0) {
   process.exit(1);
 }
 
-const result = spawnSync(process.execPath, ['--test', ...files], { stdio: 'inherit' });
+const nodeArgs = watch ? ['--test', '--watch', ...files] : ['--test', ...files];
+const result = spawnSync(process.execPath, nodeArgs, { stdio: 'inherit' });
 process.exit(result.status ?? 1);