pan-wizard 3.21.1 → 3.24.0

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/KNOWN-BETA-RISKS.md

@@ -27,6 +27,14 @@ hard-depend on, and the go/no-go facts that can only be settled on a real ZCode
 - **User-global subagents only.** No repo-scoped rosters or per-project model profiles.
 - **Genuinely lost:** scheduled self-resuming multi-day campaigns (no headless/daemon),
   background execution, committable permissions, and custom slash-commands.
+- **Bridge scope is tool/resource exposure ONLY — never agent session state.** The MCP
+  server exposes `pan-tools` verbs as `tools/call` + `resources/read`; it deliberately
+  does not represent rich agent session state (diffs, streaming, live thread lifecycle).
+  This is by design, not an omission: MCP cannot faithfully carry that state — a point
+  OpenAI made explicitly when it built the Codex "harness" as a native Rust core rather
+  than over MCP (2026). Do NOT extend the bridge to stream diffs or proxy session state
+  through it; keep the CLI's JSON contract as the tool contract. (Codex-adapter audit,
+  2026-07-30.)
 
 ## Format-drift policy
 

package/pan-zcode/README.md

@@ -21,13 +21,18 @@ pan-zcode/mcp  (this subsystem)  a thin, zero-dep bridge — verbs → MCP tools
 pan-wizard-core  (reused as-is)  the deterministic engine; .planning/ stays the state store
 ```
 
+**Scope boundary (by design):** the bridge exposes `pan-tools` verbs as MCP tools/resources and nothing more. It intentionally does **not** carry rich agent *session state* — diffs, streaming, live thread lifecycle — because MCP can't faithfully represent it (the reason OpenAI built the Codex harness as a native Rust core rather than over MCP). Keep the bridge to tool/resource exposure; the CLI's JSON contract is the tool contract. See `KNOWN-BETA-RISKS.md`.
+
 ## Status — M1–M5 built (M0 is the human verify spike)
 
 - **M1 — bridge core.** `mcp/tool-registry.cjs` (pure verb→tool/resource map, with a hard
   guardrail against exposing a force/reset/rebase/push verb) + `mcp/server.cjs` (a
   **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),
@@ -50,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);