pan-wizard 3.14.0 → 3.15.1

package/commands/pan/git.md

@@ -102,7 +102,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git branch delete --name featur
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git branch current
 ```
 
-**Phase naming convention:** `pan/phase-{N}` — matches `phase_branch_template` in `.planning/config.json`
+**Phase naming convention:** `pan/phase-{N}` — the branch is named `pan/phase-{N}` directly (hardcoded; not derived from any config template)
 
 ---
 

package/commands/pan/hud.md

@@ -46,7 +46,7 @@ pan-tools hud [--out <file>] [--open] [--stdout]
 
 <panels>
 
-The dashboard is composed of up to ten panels. Panels render only when they have data — a plain (non-army) project still gets a complete, useful page.
+Panels render only when they have data — a plain (non-army) project still gets a complete, useful page.
 
 | Panel | What it shows | Source |
 |-------|---------------|--------|
@@ -56,11 +56,12 @@ The dashboard is composed of up to ten panels. Panels render only when they have
 | **Safety harness** *(army)* | Merge gate, abort switch (pause), active worktrees, daily budget, concurrency | config + pause file + worktrees + schedule |
 | **Worktrees** *(army)* | Active `army/*` branches and their paths | `git worktree list` |
 | **Roadmap** | Every phase with status + completion | phases on disk |
+| **Planning activity** *(fallback)* | Document count by `.planning/` folder + most-recently-updated docs — for projects with no phase/roadmap layout | `.planning/**/*.md` |
 | **Telemetry** | Total spend, tokens, cache-hit rate, by-squad breakdown | cost ledger |
 | **Requirements & quality** | Requirements done/open + last verification artifacts | `requirements.md`, phase `*-verification.md` / `*-uat.md` |
 | **Recent activity** | Last commits (the army's committed output) | `git log` |
 
-*(army)* panels appear only when a campaign is scheduled or army worktrees exist — graceful degradation per ADR-0035.
+*(army)* panels appear only when a campaign is scheduled or army worktrees exist — graceful degradation per ADR-0035. The *(fallback)* **Planning activity** panel appears only when there is no phase/roadmap layout, so it fills the gap for focus-auto and imported projects instead of leaving a bare page. Telemetry shows an honest advisory (never a fabricated `$0.00`) when the cost ledger is poisoned or every record is unpriced.
 
 </panels>
 

package/commands/pan/report.md

@@ -0,0 +1,70 @@
+---
+name: pan:report
+group: Observability
+description: Generate a self-contained HTML report for one phase, or a project-level timeline index linking every phase report
+argument-hint: "phase <N> | index | all [--out <file>] [--open] [--stdout]"
+allowed-tools:
+  - Read
+  - Bash
+---
+
+<objective>
+Render **self-contained HTML reports** — no server, no network, no external CSS or JS — for the phases of a project. A per-phase report captures one phase's story (objective, roadmap position, what changed, verification and gaps); the timeline index rolls every phase into one navigable page that links to each report.
+
+Like `pan:hud`, these are *views*, not a new source of truth: every value is read from what PAN already tracks on disk (the phase's `plan`/`summary`/`verification` artifacts and their frontmatter, `roadmap.md`, and the cost ledger). The command only writes the rendered file(s), so it can never corrupt planning data. Reports reuse the HUD's visual language, so they look like part of the same product.
+
+Reports are honest by construction: the `verify reconcile` verdict is shown beside the (rubber-stampable) self-reported verification status, status is framed as a current-disk snapshot, and any spend is gated so a poisoned or unpriced ledger never renders a fake `$0`.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/bin/lib/phase-report.cjs
+</execution_context>
+
+<usage>
+
+```
+pan-tools report phase <N> [--out <file>] [--open] [--stdout]
+pan-tools report index      [--out <file>] [--open] [--stdout]
+pan-tools report all        [--open]
+```
+
+**Sub-actions:**
+- `phase <N>` — one phase report, written to `.planning/phases/<NN-slug>/<NN>-report.html` (a sibling of that phase's `verification.md`).
+- `index` — the project timeline, written to `.planning/report-index.html`; each row links to a phase report.
+- `all` — regenerate every phase report plus the index in one pass.
+
+**Flags:**
+- `--out <file>` — write to a custom path instead of the default (relative paths resolve against the project root).
+- `--open` — best-effort: launch the written file in the default browser (cross-platform; silently no-ops if no opener is available, and never opens when nothing was written).
+- `--stdout` — print the HTML to stdout instead of writing a file (for `phase`/`index`).
+
+**Behaviour worth knowing:**
+- **Deterministic writes.** Re-running with unchanged phase data rewrites nothing (the only volatile value, the generated-at timestamp, is ignored when comparing) — so reports produce no git churn.
+- **Phase-less projects.** A project with no phase/roadmap layout (a focus-auto project) has nothing to report; `index` exits with a message pointing you to `pan:hud`, whose planning-activity view covers those projects.
+
+**JSON result shape** (`report phase`, when not `--stdout`):
+```json
+{
+  "action": "phase",
+  "phase": "03",
+  "path": ".planning/phases/03-auth-sessions/03-report.html",
+  "bytes": 16183,
+  "status": "complete",
+  "written": true,
+  "opened": false
+}
+```
+
+</usage>
+
+<workflow>
+
+**Review a phase:** run `pan-tools report phase <N> --open` to see one phase's objective, what changed, and its verification verdict at a glance.
+
+**Share the project:** `pan-tools report index` builds the timeline entry point — send `.planning/report-index.html` and the linked phase files, or open the index and click through.
+
+**Refresh everything:** `pan-tools report all` after a milestone regenerates every report; unchanged ones are skipped, so only what actually moved is rewritten.
+
+**Pipe it:** `pan-tools report phase <N> --stdout > phase.html`, or feed the JSON result into another tool.
+
+</workflow>

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

@@ -1,62 +1,62 @@
-#!/usr/bin/env node
-// Check for PAN updates in background, write result to cache
-// Called by SessionStart hook - runs once per session
-
-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');
-
-// 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
-if (!fs.existsSync(cacheDir)) {
-  fs.mkdirSync(cacheDir, { recursive: true });
-}
-
-// 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');
-
-  const cacheFile = ${JSON.stringify(cacheFile)};
-  const projectVersionFile = ${JSON.stringify(projectVersionFile)};
-  const globalVersionFile = ${JSON.stringify(globalVersionFile)};
-
-  // Check project directory first (local install), then global
-  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();
-    }
-  } catch (e) {}
-
-  let latest = null;
-  try {
-    latest = execSync('npm view pan-wizard version', { encoding: 'utf8', timeout: 10000, windowsHide: true }).trim();
-  } catch (e) {}
-
-  const result = {
-    update_available: latest && installed !== latest,
-    installed,
-    latest: latest || 'unknown',
-    checked: Math.floor(Date.now() / 1000)
-  };
-
-  fs.writeFileSync(cacheFile, JSON.stringify(result));
-`], {
-  stdio: 'ignore',
-  windowsHide: true,
-  detached: true  // Required on Windows for proper process detachment
-});
-
-child.unref();
+#!/usr/bin/env node
+// Check for PAN updates in background, write result to cache
+// Called by SessionStart hook - runs once per session
+
+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');
+
+// 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
+if (!fs.existsSync(cacheDir)) {
+  fs.mkdirSync(cacheDir, { recursive: true });
+}
+
+// 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');
+
+  const cacheFile = ${JSON.stringify(cacheFile)};
+  const projectVersionFile = ${JSON.stringify(projectVersionFile)};
+  const globalVersionFile = ${JSON.stringify(globalVersionFile)};
+
+  // Check project directory first (local install), then global
+  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();
+    }
+  } catch (e) {}
+
+  let latest = null;
+  try {
+    latest = execSync('npm view pan-wizard version', { encoding: 'utf8', timeout: 10000, windowsHide: true }).trim();
+  } catch (e) {}
+
+  const result = {
+    update_available: latest && installed !== latest,
+    installed,
+    latest: latest || 'unknown',
+    checked: Math.floor(Date.now() / 1000)
+  };
+
+  fs.writeFileSync(cacheFile, JSON.stringify(result));
+`], {
+  stdio: 'ignore',
+  windowsHide: true,
+  detached: true  // Required on Windows for proper process detachment
+});
+
+child.unref();

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

@@ -1,134 +1,134 @@
-#!/usr/bin/env node
-// Context Monitor - PostToolUse hook
-// Reads context metrics from the statusline bridge file and injects
-// warnings when context usage is high. This makes the AGENT aware of
-// context limits (the statusline only shows the user).
-//
-// How it works:
-// 1. The statusline hook writes metrics to /tmp/claude-ctx-{session_id}.json
-// 2. This hook reads those metrics after each tool use
-// 3. When remaining context drops below thresholds, it injects a warning
-//    as additionalContext, which the agent sees in its conversation
-//
-// Thresholds:
-//   WARNING  (remaining <= 35%): Agent should wrap up current task
-//   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
-//
-// Debounce: 5 tool uses between warnings to avoid spam
-// Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-// Per-user bridge directory inside tmpdir, created 0700 so another user on a
-// shared host can't pre-plant a symlink at a predictable session path or read
-// the bridge files. Both hooks derive the same dir from the same uid, so the
-// statusline→context-monitor IPC channel is preserved.
-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;
-}
-
-const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
-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;
-
-    if (!sessionId) {
-      process.exit(0);
-    }
-
-    const tmpDir = bridgeDir();
-    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);
-
-    // Ignore stale metrics
-    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
-      process.exit(0);
-    }
-
-    const remaining = metrics.remaining_percentage;
-    const usedPct = metrics.used_pct;
-
-    // No warning needed
-    if (remaining > WARNING_THRESHOLD) {
-      process.exit(0);
-    }
-
-    // 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;
-
-    try {
-      warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
-      firstWarn = false;
-    } catch {
-      // No prior warning file (or corrupted) — treat as first warning.
-    }
-
-    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
-
-    const isCritical = remaining <= CRITICAL_THRESHOLD;
-    const currentLevel = isCritical ? 'critical' : 'warning';
-
-    // 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);
-    }
-
-    // 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.';
-    }
-
-    const output = {
-      hookSpecificOutput: {
-        hookEventName: "PostToolUse",
-        additionalContext: message
-      }
-    };
-
-    process.stdout.write(JSON.stringify(output));
-  } catch (e) {
-    // Silent fail -- never block tool execution
-    process.exit(0);
-  }
-});
+#!/usr/bin/env node
+// Context Monitor - PostToolUse hook
+// Reads context metrics from the statusline bridge file and injects
+// warnings when context usage is high. This makes the AGENT aware of
+// context limits (the statusline only shows the user).
+//
+// How it works:
+// 1. The statusline hook writes metrics to /tmp/claude-ctx-{session_id}.json
+// 2. This hook reads those metrics after each tool use
+// 3. When remaining context drops below thresholds, it injects a warning
+//    as additionalContext, which the agent sees in its conversation
+//
+// Thresholds:
+//   WARNING  (remaining <= 35%): Agent should wrap up current task
+//   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+//
+// Debounce: 5 tool uses between warnings to avoid spam
+// Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Per-user bridge directory inside tmpdir, created 0700 so another user on a
+// shared host can't pre-plant a symlink at a predictable session path or read
+// the bridge files. Both hooks derive the same dir from the same uid, so the
+// statusline→context-monitor IPC channel is preserved.
+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;
+}
+
+const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
+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;
+
+    if (!sessionId) {
+      process.exit(0);
+    }
+
+    const tmpDir = bridgeDir();
+    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);
+
+    // Ignore stale metrics
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
+      process.exit(0);
+    }
+
+    const remaining = metrics.remaining_percentage;
+    const usedPct = metrics.used_pct;
+
+    // No warning needed
+    if (remaining > WARNING_THRESHOLD) {
+      process.exit(0);
+    }
+
+    // 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;
+
+    try {
+      warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+      firstWarn = false;
+    } catch {
+      // No prior warning file (or corrupted) — treat as first warning.
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const currentLevel = isCritical ? 'critical' : 'warning';
+
+    // 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);
+    }
+
+    // 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.';
+    }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: message
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail -- never block tool execution
+    process.exit(0);
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.14.0",
+  "version": "3.15.1",
   "description": "Command a bot army for your codebase: an Opus Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"