pan-wizard 3.22.0 → 3.25.0

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);