pan-wizard 3.22.0 → 3.24.0

package/commands/pan/research-phase.md

@@ -21,7 +21,7 @@ Research how to implement a phase. Spawns pan-phase-researcher agent with phase
 
 **Orchestrator role:** Parse phase, validate against roadmap, check existing research, gather context, spawn researcher agent, present results.
 
-**Why subagent:** Research burns context fast (WebSearch, Context7 queries, source verification). Fresh 200k context for investigation. Main context stays lean for user interaction.
+**Why subagent:** Research burns context fast (WebSearch, Context7 queries, source verification). A fresh context window for investigation. Main context stays lean for user interaction.
 </objective>
 
 <context>

package/commands/pan/retro.md

@@ -14,7 +14,7 @@ Analyze completed milestone work to identify process improvement opportunities.
 
 Examines roadmap phases (planned vs completed, gap closures), verification results (pass rates, common gaps), and estimation accuracy. Output guides future planning improvements.
 
-This is a reflection command — it does not modify any files.
+This is a reflection command — **read-only by default**: with no flags it does not modify any files. Passing `--write-memory` (as `/pan:army` does) is the one exception — it appends recurring-pattern entries to agent memory so they persist into the next mission.
 </objective>
 
 <execution_context>
@@ -24,6 +24,9 @@ This is a reflection command — it does not modify any files.
 <context>
 No arguments required. Operates on the current `.planning/` directory.
 
+**Flags:**
+- `--write-memory` — after analysis, append recurring-pattern entries to agent memory (used by `/pan:army`). Without this flag the command is strictly read-only.
+
 The retro command is typically run after `/pan:milestone-done` to reflect on the milestone before starting the next one.
 </context>
 

package/commands/pan/review-deep.md

@@ -117,7 +117,7 @@ Verdict is driven by the highest-severity finding across all three sources. Meta
 | Codex | Same | Same | Full |
 | Copilot | Same | Same | Full |
 
-The merger CLI (`pan-tools review-deep merge`) is pure Node.js and works identically across runtimes. Only the *quality* of the hardener and meta-reviewer outputs varies with model capability — Opus 4.7 with extended thinking produces the richest findings.
+The merger CLI (`pan-tools review-deep merge`) is pure Node.js and works identically across runtimes. Only the *quality* of the hardener and meta-reviewer outputs varies with model capability — an Opus-class model with extended thinking produces the richest findings.
 
 </runtime_compatibility>
 

package/commands/pan/settings.md

@@ -21,11 +21,11 @@ Routes to the settings workflow which handles:
 </objective>
 
 <execution_context>
-@./.claude/pan-wizard-core/workflows/settings.md
+@~/.claude/pan-wizard-core/workflows/settings.md
 </execution_context>
 
 <process>
-**Follow the settings workflow** from `@./.claude/pan-wizard-core/workflows/settings.md`.
+**Follow the settings workflow** from `@~/.claude/pan-wizard-core/workflows/settings.md`.
 
 The workflow handles all logic including:
 1. Config file creation with defaults if missing

package/commands/pan/what-if.md

@@ -113,7 +113,7 @@ git branch -D <branch_name>
 - `<parent>/pan-whatif-<phase>-<slug>-<ts>/` — the worktree (temporary, deleted after report)
 - branch `pan-whatif/<phase>-<slug>-<ts>` — the worktree's branch (deleted after report)
 
-Filename + branch include a timestamp so running what-if multiple times on the same phase+scenario produces distinct reports without overwriting.
+The worktree dir and branch include a timestamp, so concurrent/repeat runs never collide there. The **report** is keyed on phase+slug only (no timestamp), so re-running what-if on the same phase+scenario **overwrites** the previous report at `.planning/counterfactuals/<phase>-<slug>.md`. Rename or copy a report you want to keep before re-running the same scenario.
 
 </output_paths>
 

package/hooks/dist/pan-check-update.js

@@ -1,62 +1,173 @@
 #!/usr/bin/env node
 // Check for PAN updates in background, write result to cache
 // Called by SessionStart hook - runs once per session
+//
+// Structure (M58, ADR audit 2026-08): the update-check logic used to live in
+// an inline `node -e` string that was never parsed, linted, or executed by any
+// test — a syntax error or field rename crashed the detached child silently
+// forever. The logic now lives in exported pure functions (below) that are
+// syntax-checked at load and unit-tested (tests/check-update-hook.test.cjs).
+// The parent process still spawns a detached child so the ~10s `npm view`
+// never blocks SessionStart; the child re-runs THIS file with `--run-check`.
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { spawn } = require('child_process');
 
-const homeDir = os.homedir();
-const cwd = process.cwd();
-const cacheDir = path.join(homeDir, '.claude', 'cache');
-const cacheFile = path.join(cacheDir, 'pan-update-check.json');
+// ── Pure logic (exported for tests) ─────────────────────────────────────────
 
-// VERSION file locations (check project first, then global)
-const projectVersionFile = path.join(cwd, '.claude', 'pan-wizard-core', 'VERSION');
-const globalVersionFile = path.join(homeDir, '.claude', 'pan-wizard-core', 'VERSION');
+// Parse a version string into numeric [major, minor, patch, ...] components,
+// dropping a leading 'v' and any pre-release/build metadata after '-' or '+'.
+// Returns null when the string has no parseable numeric core.
+function parseVersion(v) {
+  if (typeof v !== 'string') return null;
+  const core = v.trim().replace(/^v/, '').split(/[-+]/)[0];
+  if (!core) return null;
+  const parts = core.split('.').map((n) => parseInt(n, 10));
+  if (parts.length === 0 || parts.some((n) => Number.isNaN(n))) return null;
+  return parts;
+}
 
-// Ensure cache directory exists
-if (!fs.existsSync(cacheDir)) {
-  fs.mkdirSync(cacheDir, { recursive: true });
+// -1 if a < b, 0 if equal, 1 if a > b, null if either is unparseable.
+function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa || !pb) return null;
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
 }
 
-// Run check in background (spawn background process, windowsHide prevents console flash)
-const child = spawn(process.execPath, ['-e', `
-  const fs = require('fs');
-  const { execSync } = require('child_process');
+// L38: only flag an update when the installed version is strictly OLDER than
+// npm latest. The old `installed !== latest` check flagged an update for ANY
+// difference, so a source checkout ahead of the npm 'latest' dist-tag showed a
+// permanent "update" badge that nudged the user to DOWNGRADE. Also skip the
+// '0.0.0' sentinel (no VERSION file found → we don't know what's installed).
+function isUpdateAvailable(installed, latest) {
+  if (!latest) return false;
+  if (!installed || installed === '0.0.0') return false;
+  const cmp = compareVersions(installed, latest);
+  // Unparseable tag: fall back to strict inequality (matches historical
+  // behavior for odd tags; the '0.0.0' sentinel is already excluded above).
+  if (cmp === null) return installed !== latest;
+  return cmp < 0;
+}
 
-  const cacheFile = ${JSON.stringify(cacheFile)};
-  const projectVersionFile = ${JSON.stringify(projectVersionFile)};
-  const globalVersionFile = ${JSON.stringify(globalVersionFile)};
+// Build the cache record consumed by the statusline.
+function computeUpdateResult(installed, latest, nowSeconds) {
+  return {
+    update_available: isUpdateAvailable(installed, latest),
+    installed,
+    latest: latest || 'unknown',
+    checked: nowSeconds != null ? nowSeconds : Math.floor(Date.now() / 1000),
+  };
+}
 
-  // Check project directory first (local install), then global
+// Resolve the installed version: project VERSION wins over global VERSION.
+// Falls back to the '0.0.0' sentinel when neither is readable.
+function resolveInstalledVersion(fsMod, projectVersionFile, globalVersionFile) {
   let installed = '0.0.0';
   try {
-    if (fs.existsSync(projectVersionFile)) {
-      installed = fs.readFileSync(projectVersionFile, 'utf8').trim();
-    } else if (fs.existsSync(globalVersionFile)) {
-      installed = fs.readFileSync(globalVersionFile, 'utf8').trim();
+    if (fsMod.existsSync(projectVersionFile)) {
+      installed = fsMod.readFileSync(projectVersionFile, 'utf8').trim();
+    } else if (fsMod.existsSync(globalVersionFile)) {
+      installed = fsMod.readFileSync(globalVersionFile, 'utf8').trim();
     }
-  } catch (e) {}
+  } catch (e) { /* fall through to sentinel */ }
+  return installed || '0.0.0';
+}
 
+// Perform the full check and write the cache file. `fetchLatest` is injectable
+// so tests never touch the network; it returns the latest version or null.
+function runCheck(opts) {
+  const {
+    fsMod = fs,
+    cacheFile,
+    projectVersionFile,
+    globalVersionFile,
+    fetchLatest,
+    nowSeconds,
+  } = opts;
+  const installed = resolveInstalledVersion(fsMod, projectVersionFile, globalVersionFile);
   let latest = null;
   try {
-    latest = execSync('npm view pan-wizard version', { encoding: 'utf8', timeout: 10000, windowsHide: true }).trim();
-  } catch (e) {}
+    latest = fetchLatest ? fetchLatest() : null;
+  } catch (e) {
+    latest = null;
+  }
+  const result = computeUpdateResult(installed, latest, nowSeconds);
+  fsMod.writeFileSync(cacheFile, JSON.stringify(result));
+  return result;
+}
 
-  const result = {
-    update_available: latest && installed !== latest,
-    installed,
-    latest: latest || 'unknown',
-    checked: Math.floor(Date.now() / 1000)
-  };
+// Default network fetch — queried only in the detached child, never in tests.
+function defaultFetchLatest() {
+  const { execSync } = require('child_process');
+  return execSync('npm view pan-wizard version', {
+    encoding: 'utf8',
+    timeout: 10000,
+    windowsHide: true,
+  }).trim();
+}
+
+// ── Runtime entry point ──────────────────────────────────────────────────────
+
+function main() {
+  const homeDir = os.homedir();
+  const cwd = process.cwd();
+  const cacheDir = path.join(homeDir, '.claude', 'cache');
+  const cacheFile = path.join(cacheDir, 'pan-update-check.json');
+
+  // VERSION file locations (check project first, then global)
+  const projectVersionFile = path.join(cwd, '.claude', 'pan-wizard-core', 'VERSION');
+  const globalVersionFile = path.join(homeDir, '.claude', 'pan-wizard-core', 'VERSION');
+
+  // Ensure cache directory exists
+  try {
+    if (!fs.existsSync(cacheDir)) {
+      fs.mkdirSync(cacheDir, { recursive: true });
+    }
+  } catch (e) { /* best-effort — a write failure below is swallowed too */ }
+
+  if (process.argv.includes('--run-check')) {
+    // Child mode: perform the (possibly slow) npm check synchronously, then
+    // exit. Never surface errors — a hook must not crash the session.
+    try {
+      runCheck({
+        cacheFile,
+        projectVersionFile,
+        globalVersionFile,
+        fetchLatest: defaultFetchLatest,
+      });
+    } catch (e) { /* silent */ }
+    return;
+  }
 
-  fs.writeFileSync(cacheFile, JSON.stringify(result));
-`], {
-  stdio: 'ignore',
-  windowsHide: true,
-  detached: true  // Required on Windows for proper process detachment
-});
+  // Parent mode: run the check in a detached background child so the 10s
+  // `npm view` never blocks SessionStart. windowsHide prevents a console flash.
+  const child = spawn(process.execPath, [__filename, '--run-check'], {
+    stdio: 'ignore',
+    windowsHide: true,
+    detached: true, // Required on Windows for proper process detachment
+  });
+  child.unref();
+}
+
+if (require.main === module) {
+  main();
+}
 
-child.unref();
+module.exports = {
+  parseVersion,
+  compareVersions,
+  isUpdateAvailable,
+  computeUpdateResult,
+  resolveInstalledVersion,
+  runCheck,
+};

package/hooks/dist/pan-context-monitor.js

@@ -16,6 +16,10 @@
 //
 // Debounce: 5 tool uses between warnings to avoid spam
 // Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
+//
+// The decision logic lives in the pure, exported buildContextWarning() so it is
+// unit-tested (tests/context-monitor-hook.test.cjs) rather than only reachable
+// via stdin (M59, ADR audit 2026-08).
 
 const fs = require('fs');
 const os = require('os');
@@ -28,8 +32,25 @@ const path = require('path');
 function bridgeDir() {
   const uid = (typeof process.getuid === 'function' ? process.getuid() : process.env.USERNAME || 'win');
   const dir = path.join(os.tmpdir(), `pan-hooks-${uid}`);
-  try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* best-effort */ }
-  return dir;
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // mkdirSync{recursive} is a silent no-op on an EXISTING dir, so on a shared
+    // host an attacker can pre-plant pan-hooks-<uid> and read the session id /
+    // swap in a symlink. Verify WE own it, it isn't a symlink, and it isn't
+    // group/other-accessible; fail CLOSED (null) otherwise — the bridge is
+    // best-effort observability, so skipping beats a leak (M60, ADR audit 2026-08).
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink()) return null; // cross-platform
+    // POSIX ownership/mode checks ONLY where they're meaningful. Windows fakes
+    // mode bits — a dir just created with mode 0o700 lstats as 0o666 — so
+    // applying the mode/uid gate there returned null on every call and disabled
+    // the bridge entirely (N15). The finding's threat model is shared Unix hosts.
+    if (typeof process.getuid === 'function') {
+      if (st.uid !== process.getuid()) return null;
+      if ((st.mode & 0o077) !== 0) return null;
+    }
+    return dir;
+  } catch { return null; }
 }
 
 const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
@@ -37,98 +58,151 @@ const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
 const STALE_SECONDS = 60;      // ignore metrics older than 60s
 const DEBOUNCE_CALLS = 5;      // min tool uses between warnings
 
-let input = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => input += chunk);
-process.stdin.on('end', () => {
-  try {
-    const data = JSON.parse(input);
-    const sessionId = data.session_id;
+// Pure decision function (exported for tests).
+//
+//   metrics    — { remaining_percentage, used_pct?, timestamp? } from the bridge
+//   warnState  — { callsSinceWarn, lastLevel } from the prior warn file, or null
+//                on the first warning (no file yet / corrupt file)
+//   nowSeconds — current unix time in seconds
+//
+// Returns one of:
+//   { action: 'exit' }                                   — nothing to do
+//   { action: 'debounce', warnState }                    — persist counter, no warn
+//   { action: 'emit', level, warnState, message }        — persist + emit warning
+function buildContextWarning(metrics, warnState, nowSeconds) {
+  if (!metrics || typeof metrics !== 'object') return { action: 'exit' };
+
+  // Ignore stale metrics (statusline stopped updating — e.g. session ended).
+  if (metrics.timestamp != null && (nowSeconds - metrics.timestamp) > STALE_SECONDS) {
+    return { action: 'exit' };
+  }
 
-    if (!sessionId) {
-      process.exit(0);
-    }
+  const remaining = Number(metrics.remaining_percentage);
+  if (!Number.isFinite(remaining)) return { action: 'exit' };
 
-    const tmpDir = bridgeDir();
-    const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
+  // No warning needed
+  if (remaining > WARNING_THRESHOLD) return { action: 'exit' };
 
-    // Read metrics directly; absence (subagent/fresh session) or a corrupt
-    // file just means "nothing to warn about" — exit silently. No
-    // existsSync-then-read gap.
-    let metrics;
-    try {
-      metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
-    } catch {
-      process.exit(0);
-    }
-    const now = Math.floor(Date.now() / 1000);
+  const firstWarn = warnState == null || typeof warnState !== 'object';
+  const prev = firstWarn ? { callsSinceWarn: 0, lastLevel: null } : warnState;
+  const callsSinceWarn = (prev.callsSinceWarn || 0) + 1;
 
-    // Ignore stale metrics
-    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
-      process.exit(0);
-    }
+  const isCritical = remaining <= CRITICAL_THRESHOLD;
+  const currentLevel = isCritical ? 'critical' : 'warning';
 
-    const remaining = metrics.remaining_percentage;
-    const usedPct = metrics.used_pct;
+  // Emit immediately on first warning, then debounce subsequent ones.
+  // Severity escalation (WARNING -> CRITICAL) bypasses debounce.
+  const severityEscalated = currentLevel === 'critical' && prev.lastLevel === 'warning';
+  if (!firstWarn && callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+    // Bump the counter but leave lastLevel untouched, then exit without warning.
+    return {
+      action: 'debounce',
+      warnState: { callsSinceWarn, lastLevel: prev.lastLevel || null },
+    };
+  }
 
-    // No warning needed
-    if (remaining > WARNING_THRESHOLD) {
-      process.exit(0);
-    }
+  // L39: report Usage and Remaining on the SAME scale so they are internally
+  // consistent (sum to 100). The bridge's used_pct is the statusline's
+  // 80%-rescaled figure (80% real usage displays as 100%); pairing it with the
+  // raw remaining produced self-contradictory numbers like
+  // "Usage at 94%. Remaining: 25%". Derive used from remaining instead.
+  const rem = Math.round(remaining);
+  const used = 100 - rem;
+
+  let message;
+  if (isCritical) {
+    message = `CONTEXT MONITOR CRITICAL: Usage at ${used}%. Remaining: ${rem}%. ` +
+      'STOP new work immediately. Save state NOW and inform the user that context is nearly exhausted. ' +
+      'If using PAN, run /pan:pause to save execution state.';
+  } else {
+    message = `CONTEXT MONITOR WARNING: Usage at ${used}%. Remaining: ${rem}%. ` +
+      'Begin wrapping up current task. Do not start new complex work. ' +
+      'If using PAN, consider /pan:pause to save state.';
+  }
 
-    // Debounce: check if we warned recently
-    const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
-    let warnData = { callsSinceWarn: 0, lastLevel: null };
-    let firstWarn = true;
+  return {
+    action: 'emit',
+    level: currentLevel,
+    warnState: { callsSinceWarn: 0, lastLevel: currentLevel },
+    message,
+  };
+}
 
+function main() {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => input += chunk);
+  process.stdin.on('end', () => {
     try {
-      warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
-      firstWarn = false;
-    } catch {
-      // No prior warning file (or corrupted) — treat as first warning.
-    }
+      const data = JSON.parse(input);
+      const sessionId = data.session_id;
 
-    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+      if (!sessionId) {
+        process.exit(0);
+      }
 
-    const isCritical = remaining <= CRITICAL_THRESHOLD;
-    const currentLevel = isCritical ? 'critical' : 'warning';
+      const tmpDir = bridgeDir();
+      if (!tmpDir) process.exit(0); // insecure/unavailable bridge dir — fail closed (M60)
+      const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
+
+      // Read metrics directly; absence (subagent/fresh session) or a corrupt
+      // file just means "nothing to warn about" — exit silently. No
+      // existsSync-then-read gap.
+      let metrics;
+      try {
+        metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+      } catch {
+        process.exit(0);
+      }
+      const now = Math.floor(Date.now() / 1000);
+
+      // Load prior warn state (null when no file / corrupt → treated as first warn).
+      const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
+      let warnData = null;
+      try {
+        warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+      } catch {
+        warnData = null;
+      }
 
-    // Emit immediately on first warning, then debounce subsequent ones
-    // Severity escalation (WARNING -> CRITICAL) bypasses debounce
-    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
-    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
-      // Update counter and exit without warning
-      fs.writeFileSync(warnPath, JSON.stringify(warnData));
-      process.exit(0);
-    }
+      const decision = buildContextWarning(metrics, warnData, now);
 
-    // Reset debounce counter
-    warnData.callsSinceWarn = 0;
-    warnData.lastLevel = currentLevel;
-    fs.writeFileSync(warnPath, JSON.stringify(warnData));
-
-    // Build warning message
-    let message;
-    if (isCritical) {
-      message = `CONTEXT MONITOR CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
-        'STOP new work immediately. Save state NOW and inform the user that context is nearly exhausted. ' +
-        'If using PAN, run /pan:pause to save execution state.';
-    } else {
-      message = `CONTEXT MONITOR WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
-        'Begin wrapping up current task. Do not start new complex work. ' +
-        'If using PAN, consider /pan:pause to save state.';
-    }
+      if (decision.action === 'exit') {
+        process.exit(0);
+      }
 
-    const output = {
-      hookSpecificOutput: {
-        hookEventName: "PostToolUse",
-        additionalContext: message
+      if (decision.action === 'debounce') {
+        fs.writeFileSync(warnPath, JSON.stringify(decision.warnState));
+        process.exit(0);
       }
-    };
 
-    process.stdout.write(JSON.stringify(output));
-  } catch (e) {
-    // Silent fail -- never block tool execution
-    process.exit(0);
-  }
-});
+      // action === 'emit'
+      fs.writeFileSync(warnPath, JSON.stringify(decision.warnState));
+
+      const output = {
+        hookSpecificOutput: {
+          hookEventName: "PostToolUse",
+          additionalContext: decision.message
+        }
+      };
+
+      process.stdout.write(JSON.stringify(output));
+    } catch (e) {
+      // Silent fail -- never block tool execution
+      process.exit(0);
+    }
+  });
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  buildContextWarning,
+  bridgeDir,
+  WARNING_THRESHOLD,
+  CRITICAL_THRESHOLD,
+  STALE_SECONDS,
+  DEBOUNCE_CALLS,
+};