pan-wizard 3.5.2 → 3.8.0

package/bin/install.js

@@ -39,6 +39,14 @@ const PAN_SOURCE_ROOT = path.resolve(__dirname, '..');
 // Windows paths are case-insensitive; normalize for comparison
 const normPath = p => process.platform === 'win32' ? p.toLowerCase() : p;
 
+// IMPROVEMENT-TODO P0 (v3.7.10): warning collector for non-fatal install
+// failures. Replaces silent `catch {}` blocks in copy paths. Surfaced at end
+// of install if non-empty. Required failures still throw / exit non-zero.
+const INSTALL_WARNINGS = [];
+function pushInstallWarning(stage, file, err) {
+  INSTALL_WARNINGS.push({ stage, file, error: err && (err.message || String(err)) });
+}
+
 // Parse args
 const args = process.argv.slice(2);
 const hasGlobal = args.includes('--global') || args.includes('-g');
@@ -472,13 +480,17 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
   const isCodex = runtime === 'codex';
   const dirName = getDirName(runtime);
 
-  // Clean install: remove existing destination to prevent orphaned files
+  // Clean install: remove existing destination to prevent orphaned files.
+  // mkdirSync failure is FATAL — without destDir, every subsequent file write
+  // would fail too. We throw instead of silent-swallowing.
   try {
     if (fs.existsSync(destDir)) {
       fs.rmSync(destDir, { recursive: true });
     }
     fs.mkdirSync(destDir, { recursive: true });
-  } catch {}
+  } catch (err) {
+    throw new Error(`copyWithPathReplacement: cannot prepare ${destDir}: ${err.message}`);
+  }
 
   const entries = fs.readdirSync(srcDir, { withFileTypes: true });
 
@@ -522,9 +534,18 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
         } else {
           fs.writeFileSync(destPath, content);
         }
-      } catch {}
+      } catch (err) {
+        // Per-file write failure: collect warning. verifyInstall() at end of
+        // install will catch the missing file and fail the install if it was
+        // required. This stops the silent-failure surface that bit whoocache.
+        pushInstallWarning('copyWithPathReplacement(md)', destPath, err);
+      }
     } else {
-      try { fs.copyFileSync(srcPath, destPath); } catch {}
+      try {
+        fs.copyFileSync(srcPath, destPath);
+      } catch (err) {
+        pushInstallWarning('copyWithPathReplacement(copy)', destPath, err);
+      }
     }
   }
 }
@@ -1444,6 +1465,20 @@ function install(isGlobal, runtime = 'claude') {
     const skillSrc = path.join(src, 'pan-wizard-core');
     const skillDest = path.join(targetDir, 'pan-wizard-core');
     copyWithPathReplacement(skillSrc, skillDest, pathPrefix, runtime);
+
+    // v3.7.0+ self-improvement loop two-tier delivery:
+    // learnings/universal/ ships to all 5 runtimes (consumed by user-project workflows).
+    // learnings/internal/ stays source-only — strip it from the installed copy.
+    // Spec: docs/specs/self_improvement_loop_featureai.md §3.6
+    const internalLearningsDir = path.join(skillDest, 'learnings', 'internal');
+    if (fs.existsSync(internalLearningsDir)) {
+      try {
+        fs.rmSync(internalLearningsDir, { recursive: true, force: true });
+      } catch {
+        // Best-effort: install proceeds even if cleanup fails
+      }
+    }
+
     if (verifyInstalled(skillDest, 'pan-wizard-core')) {
       console.log(`  ${green}✓${reset} Installed pan-wizard-core`);
     } else {
@@ -1607,30 +1642,44 @@ function install(isGlobal, runtime = 'claude') {
   }
 
   // Write file manifest for future modification detection
-  writeManifest(targetDir, runtime);
+  const manifest = writeManifest(targetDir, runtime);
   console.log(`  ${green}✓${reset} Wrote file manifest (${MANIFEST_NAME})`);
 
   // Report any backed-up local patches
   reportLocalPatches(targetDir, runtime);
 
-  // Post-install self-check: verify critical files exist before declaring success
-  const selfCheckIssues = [];
-  const panToolsPath = path.join(targetDir, 'pan-wizard-core', 'bin', 'pan-tools.cjs');
-  if (!fs.existsSync(panToolsPath)) selfCheckIssues.push('pan-tools.cjs missing');
-  const manifestFullPath = path.join(targetDir, MANIFEST_NAME);
-  if (fs.existsSync(manifestFullPath)) {
-    try {
-      const mfst = JSON.parse(fs.readFileSync(manifestFullPath, 'utf8'));
-      const fileCount = Object.keys(mfst.files || {}).length;
-      if (fileCount < 50) selfCheckIssues.push(`manifest has only ${fileCount} files (expected 150+)`);
-    } catch { selfCheckIssues.push('manifest unreadable'); }
-  } else {
-    selfCheckIssues.push('manifest missing');
+  // Post-install verification: walk every manifest entry, assert file present.
+  // Catches silent copy/write failures from earlier stages (IMPROVEMENT-TODO P0).
+  // Missing files = exit 1; warnings = log but continue.
+  const verifyResult = lib.verifyInstall(targetDir, manifest);
+  if (verifyResult.warnings.length > 0) {
+    console.error(`\n  ${yellow}⚠ Install verification warnings:${reset}`);
+    for (const w of verifyResult.warnings) console.error(`    - ${w}`);
+  }
+  if (!verifyResult.ok) {
+    console.error(`\n  ${red}✖ Install verification FAILED — ${verifyResult.missing.length} file(s) missing:${reset}`);
+    // Limit output to first 20 missing to avoid screen-flooding
+    const sample = verifyResult.missing.slice(0, 20);
+    for (const m of sample) console.error(`    - ${m}`);
+    if (verifyResult.missing.length > sample.length) {
+      console.error(`    ... and ${verifyResult.missing.length - sample.length} more`);
+    }
+    console.error(`\n  Run ${cyan}pan-tools validate deployment${reset} for full diagnostics, then re-run the installer.\n`);
+    process.exit(1);
   }
-  if (selfCheckIssues.length > 0) {
-    console.error(`\n  ${yellow}⚠ Post-install check found issues:${reset}`);
-    for (const issue of selfCheckIssues) console.error(`    - ${issue}`);
-    console.error(`  Run ${cyan}pan-tools validate deployment${reset} for full diagnostics.\n`);
+  console.log(`  ${green}✓${reset} Verified ${Object.keys(manifest.files || {}).length} installed files`);
+
+  // Surface non-fatal install warnings collected during copy/write phases.
+  // verifyInstall above already exited 1 on missing required files; warnings
+  // here are for partial failures that didn't ultimately leave gaps.
+  if (INSTALL_WARNINGS.length > 0) {
+    console.error(`\n  ${yellow}⚠ ${INSTALL_WARNINGS.length} non-fatal install warning(s):${reset}`);
+    for (const w of INSTALL_WARNINGS.slice(0, 10)) {
+      console.error(`    [${w.stage}] ${w.file}: ${w.error}`);
+    }
+    if (INSTALL_WARNINGS.length > 10) {
+      console.error(`    ... and ${INSTALL_WARNINGS.length - 10} more`);
+    }
   }
 
   if (isCodex) {

package/commands/pan/debug.md

@@ -2,7 +2,7 @@
 name: pan:debug
 group: System
 description: Systematic debugging with persistent state across context resets
-argument-hint: [issue description]
+argument-hint: "[issue description]"
 allowed-tools:
   - Read
   - Bash

package/commands/pan/experiment.md

@@ -0,0 +1,219 @@
+---
+name: experiment
+group: Self-Improvement
+description: Manage external experiments — scaffold, run, harvest, promote findings back to PAN
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+---
+
+# /pan:experiment — Cross-Project Self-Improvement Loop
+
+> **Self-protection:** This command **scaffolds external project folders OUTSIDE the PAN source repo** to drive autonomous AI coding sessions against fresh ideas, then harvests the resulting telemetry back into `pan-wizard-core/learnings/`. It is a **PAN-development tool**, not a feature for end-users of PAN to invoke on their own projects.
+
+**Spec:** `docs/specs/self_improvement_loop_featureai.md`
+**ADR:** ADR-0026 (pending W4)
+**Status:** v3.7.0 W1+W2+W3 — scaffolding (`new`/`list`/`manifest`) + external runner (`run`/`status`/`stop`) + harvest (`harvest`/`prune`); W4 adds promote integration with `/pan:learn`.
+
+---
+
+## When to use this
+
+- You have an idea for a small project. You want to know **how PAN drives that build** — what shortcuts the AI takes, where verification fails, which guardrails fire.
+- You want the resulting telemetry to **flow back into PAN's shipped artifacts** so the next release is smarter.
+- You're testing a behavioral change (new `references/` doc, new workflow rule) by running it against a real, isolated build.
+
+## When NOT to use this
+
+- Building production user features. Use `/pan:new-project` and `/pan:exec-phase` directly.
+- Validating a single-file change. The experiment loop is heavy — use `npm test` and `/pan:check`.
+- Inside the PAN source repo. The command **refuses** to scaffold experiments inside `d:\PanWizard\` (or wherever the source is cloned). The experiment root defaults to `~/pan-experiments/`.
+
+---
+
+## Subcommands (W1 shipped)
+
+### `/pan:experiment new <slug> --idea <path>`
+
+Scaffold a new experiment folder. Creates:
+
+```
+<root>/<slug>/
+├── .planning/
+│   ├── idea.md              ← copied from --idea path
+│   └── experiment.json      ← manifest (slug, runtime, created_at, etc.)
+└── .claude/ (or .codex/, .gemini/, .opencode/, .github/)   ← PAN install for chosen runtime
+```
+
+**Flags:**
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--idea <path>` | required | Path to the idea.md doc; copied into the experiment |
+| `--runtime <r>` | `claude` | Which AI coding runtime to install: claude / codex / gemini / opencode / copilot |
+| `--root <path>` | `~/pan-experiments/` | Override the experiment root directory |
+| `--budget <pts>` | `80` | Optional budget cap (saved to manifest, enforced by W2 runner) |
+| `--skip-installer` | `false` | Don't run the PAN installer (dev-only) |
+
+**Slug rules:** lowercase letters, digits, hyphens. Max 40 chars. No leading/trailing hyphen.
+
+**Returns:** JSON with `experiment_id`, `path`, `runtime`, `idea_path`, `created_at`. On failure, returns `{ error: "..." }`.
+
+### `/pan:experiment list`
+
+Enumerate all experiments under the root. Returns `{ experiments: [...], count }` sorted newest-first.
+
+**Flags:**
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--root <path>` | `~/pan-experiments/` | Override the root |
+| `--raw` | `false` | Human-readable output instead of JSON |
+
+### `/pan:experiment manifest <slug>`
+
+Read the manifest for a single experiment. Returns the JSON shape written by `new`.
+
+**Flags:**
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--root <path>` | `~/pan-experiments/` | Override the root |
+
+---
+
+## Subcommands (W2 shipped)
+
+### `/pan:experiment run <slug>`
+
+Spawn the external AI runtime against the experiment folder. **Synchronous** — blocks until the external session exits, hits the timeout, or is stopped.
+
+**Flags:**
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--timeout <sec>` | `1800` (30 min) | Hard timeout in seconds; runner sends SIGTERM at deadline |
+| `--prompt <text>` | `/pan:new-project --auto @.planning/idea.md` | Prompt passed to the external runtime |
+| `--root <path>` | `~/pan-experiments/` | Override the experiment root |
+
+**Returns:** `{ status: "done"\|"failed", stop_reason: "success"\|"error"\|"timeout"\|"manual", exit_code, elapsed_ms, started_at, ended_at }`. Run-state is also persisted to `<experiment>/.planning/run-state.json`.
+
+**Runtime support:** claude / codex / gemini / opencode (via `RUNTIME_RUNNERS` adapter map in `runner.cjs`). GitHub Copilot CLI is **unsupported** for the `run` subcommand — no documented headless prompt mode. Copilot users can still scaffold and harvest manually.
+
+### `/pan:experiment status <slug>`
+
+Read the current `run-state.json` snapshot. Returns the full state object (`status`, `stop_reason`, `exit_code`, `elapsed_ms`, `events`).
+
+### `/pan:experiment stop <slug>`
+
+Gracefully halt a running experiment. Reads pid from `run-state.json`, sends SIGTERM, writes `status: failed, stop_reason: manual` to the run state. Returns the updated state.
+
+If the experiment has already finished, returns the existing run state without error.
+
+## Subcommands (W3 shipped)
+
+### `/pan:experiment harvest <slug>`
+
+Copy the experiment's telemetry into `<source-repo>/experiments/<slug>/` so it can be analyzed and promoted into shipped artifacts.
+
+**What gets harvested** (skipped silently if absent):
+
+- `.planning/idea.md` — the original idea doc
+- `.planning/experiment.json` — scaffold manifest
+- `.planning/state.md` — final project state
+- `.planning/run-state.json` — runner result (status, exit_code, elapsed_ms)
+- `.planning/agent-history.json` — every agent spawn during the build
+- `.planning/optimization/` — full trace data (sessions, reports)
+- `.planning/phases/` — phases the external session created
+
+A `harvest.json` manifest is written at the destination capturing source path, timestamp, total bytes, and the list of harvested paths.
+
+**Flags:**
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--root <path>` | `~/pan-experiments/` | Override the experiment root |
+| `--source-root <path>` | PAN source repo | Override harvest destination |
+| `--force` | `false` | Overwrite an existing harvest at the destination |
+
+**Returns:** `{ experiment_id, harvest_path, harvested_paths: [...], total_bytes, harvested_at, pan_version }`. On conflict without `--force`, returns `{ error }`.
+
+### `/pan:experiment prune <slug>`
+
+Remove the experiment folder after harvest.
+
+**Modes:**
+
+- **Soft** (default): rename to `<root>/<slug>-archived-<ISO-timestamp>` so the data is retained but the slug is freed for reuse
+- **Hard** (`--hard` flag): permanently delete
+
+**Flags:**
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--root <path>` | `~/pan-experiments/` | Override the experiment root |
+| `--hard` | `false` | Permanent deletion (irreversible) |
+
+**Returns:** `{ pruned: <slug>, mode: "soft"|"hard", archive_path? }`.
+
+## Subcommands (W4 — coming soon)
+
+| Subcommand | Wave | Purpose |
+|------------|------|---------|
+| `archive <slug>` | W4 | Alias for `prune` (kept for clarity in scripts) |
+| `delete <slug> --confirm` | W4 | Alias for `prune --hard` with confirmation prompt |
+
+W4 also adds:
+- `/pan:learn --experiment <slug>` — runs pan-optimizer over harvested data
+- `pan-tools learn promote --pattern <id> --scope universal --topic <name>` — extracts a finding into `pan-wizard-core/learnings/{universal,internal}/<topic>.md`
+- `pan-tools learn unpromote/list-promoted` — rollback and inventory
+
+---
+
+## CLI mapping (`pan-tools experiment <sub>`)
+
+```bash
+pan-tools experiment new <slug> --idea <path> [--runtime r] [--root path] [--budget n]
+pan-tools experiment list [--root path] [--raw]
+pan-tools experiment manifest <slug> [--root path]
+```
+
+Examples:
+
+```bash
+# Scaffold a new experiment
+echo "# Idea: Build a markdown linter CLI" > my-idea.md
+# (fill in problem, success, scope, constraints — see template at pan-wizard-core/templates/idea.md)
+pan-tools experiment new md-lint --idea my-idea.md --runtime claude --budget 60
+
+# List all experiments
+pan-tools experiment list
+
+# Inspect one
+pan-tools experiment manifest md-lint
+```
+
+---
+
+## Safety guards
+
+- **Never inside source repo.** `newExperiment` refuses to write to `d:\PanWizard\` (or wherever the PAN source is). Mirrors `bin/install.js` `PAN_SOURCE_ROOT` guard.
+- **No clobber.** Refuses to scaffold over an existing experiment folder of the same slug.
+- **Slug validation.** Lowercase + digits + hyphens, max 40 chars. Rejects uppercase, spaces, special characters.
+- **Idea path validation.** Errors if the `--idea` file doesn't exist.
+
+## Related
+
+- `pan-wizard-core/templates/idea.md` — idea doc template
+- `pan-wizard-core/bin/lib/experiment.cjs` — implementation
+- `pan-wizard-core/learnings/README.md` — where harvested findings go
+- `docs/specs/self_improvement_loop_featureai.md` — full design
+
+## Runtime support
+
+Works in all 5 runtimes (Claude / Codex / Gemini / OpenCode / Copilot). The W2 external runner (subprocess invocation of the external session) supports Claude / Codex / Gemini / OpenCode; GitHub Copilot CLI lacks a headless prompt mode and is opt-out for the `run` subcommand.

package/commands/pan/health.md

@@ -2,7 +2,7 @@
 name: pan:health
 group: System
 description: Diagnose planning directory health and optionally repair issues
-argument-hint: [--repair]
+argument-hint: "[--repair]"
 allowed-tools:
   - Read
   - Bash

package/commands/pan/learn.md

@@ -1,3 +1,15 @@
+---
+name: pan:learn
+group: Self-Improvement
+description: Analyze trace sessions or harvested experiments via pan-optimizer; generate ranked optimization reports
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Task
+---
+
 # /pan:learn
 
 Analyze the most recent trace session and generate an optimization report.
@@ -6,11 +18,13 @@ Analyze the most recent trace session and generate an optimization report.
 ```
 /pan:learn
 /pan:learn --session <session-id>
+/pan:learn --experiment <slug>
 /pan:learn --apply
 ```
 
 **Flags:**
 - `--session <id>` — analyze a specific session instead of the most recent
+- `--experiment <slug>` *(v3.7.0+, W3)* — analyze a harvested experiment instead of the current project's traces. Reads from `<source-repo>/experiments/<slug>/.planning/optimization/` and writes the report to `<source-repo>/experiments/<slug>/learnings/report-<timestamp>.md`. Used by the self-improvement loop. Run `/pan:experiment harvest <slug>` first.
 - `--apply` — automatically apply safe optimizations after generating the report (equivalent to running `/pan:optimize apply` immediately after)
 
 **What it does:**
@@ -56,6 +70,6 @@ The optimization report in `.planning/optimization/reports/` contains:
 → Needs review: 2 prompt improvements, 1 workflow gap
 ```
 
-**See also:** `/pan:optimize`, `/pan:exec-phase`
+**See also:** `/pan:optimize`, `/pan:exec-phase`, `/pan:experiment` (v3.7.0+ self-improvement loop)
 
 Follow the workflow at `.claude/workflows/learn.md` (or `pan-wizard-core/workflows/learn.md`).

package/commands/pan/links.md

@@ -0,0 +1,102 @@
+---
+name: pan:links
+group: Validation
+description: Validate the doc-code link graph — inline wiki-style refs, source-comment anchors, and require-code-mention contracts (ADR-0027, v3.8.0+)
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+---
+
+# /pan:links
+
+Validate the doc-code link graph. Walks `docs/`, `pan-wizard-core/`, `commands/`, and `agents/` for inline `[[<id>]]` references and `// @pan: <id>` source-comment anchors. Reports broken refs, stale anchors, and uncovered backlink contracts.
+
+**Usage:**
+```
+/pan:links
+/pan:links --strict
+/pan:links --doc-root <path> [--doc-root <path>...]
+/pan:links --source-root <path> [--source-root <path>...]
+```
+
+**Flags:**
+- `--strict` — fail (exit 1) on warnings, not only errors. Default is advisory: warnings do not flip status.
+- `--doc-root <path>` — override default doc roots. Repeatable.
+- `--source-root <path>` — override default source roots. Repeatable.
+- `--raw` — human-readable output instead of JSON.
+
+**What it does:**
+
+Three sequential passes share one walk pair:
+
+1. **Forward links** — every `[[<id>]]` in body text and every `must_haves.key_links` entry must resolve. Section anchors (`[[ADR-0021#Decision]]`) check that the named heading exists.
+2. **Backlink contract** — docs with `require-code-mention: true` in frontmatter must have at least one `@pan:` source anchor that resolves to them.
+3. **Anchor-target existence** — every `// @pan: <id>` comment must point to a real doc.
+
+**Doc-id forms accepted:**
+
+- `ADR-NNNN` — resolves via glob to `docs/decisions/ADR-NNNN-*.md`
+- `<path>.md` — exact path relative to repo root
+- `<path>` (no extension) — tries `<path>.md` then `<path>/README.md`
+- Any of the above with `#section` — verifies a heading whose slug matches
+
+**Source-anchor grammar:**
+
+```
+// @pan: ADR-0027         (JS / TS / CJS)
+# @pan: ADR-0027          (Python / shell)
+<!-- @pan: ADR-0027 -->   (Markdown / HTML)
+```
+
+Anchors cluster at the top of a file under a single banner; comment leader must be the line's first non-whitespace token.
+
+**Exit codes:**
+
+- `0` — pass
+- `1` — fail (errors present, or warnings present under `--strict`)
+
+**Output (JSON):**
+
+```json
+{
+  "ok": true,
+  "summary": {
+    "total_findings": 0,
+    "errors": 0,
+    "warnings": 0,
+    "status": "pass",
+    "doc_files_scanned": 280,
+    "source_files_scanned": 170,
+    "anchors_found": 4,
+    "forward_links_found": 12,
+    "backlink_contracts_checked": 3
+  },
+  "findings": []
+}
+```
+
+**Finding codes:**
+
+| Code | Severity | Meaning |
+|---|---|---|
+| F-001 | error | Inline `[[<id>]]` does not resolve |
+| F-002 | error | `[[<doc>#<section>]]` resolves the file but the section is missing |
+| F-003 | warning | `must_haves.key_links` entry's `from` or `to` does not exist |
+| F-004 | warning | `must_haves.key_links` regex pattern is invalid |
+| B-001 | error | Doc has `require-code-mention: true` but no `@pan:` anchors resolve to it |
+| B-002 | warning | Doc is anchored by exactly one source file (single-source informational) |
+| A-001 | error | `@pan:` anchor target does not resolve |
+| A-002 | warning | `@pan:` anchor section is missing in the resolved file |
+| A-004 | warning | `@pan:` anchor has empty id |
+
+**Composing with `validate health`:**
+
+`validate health --links` includes the link-graph summary as a `link_graph` field in the health report. Used as a pre-flight check before release. Errors degrade the health report to a warning-level issue (`LINKS_ERR`); non-blocking unless `--strict` is added to a separate `links validate` invocation.
+
+**See also:**
+
+- ADR-0027 — Doc–Code Link Graph
+- `docs/specs/doc_code_link_graph_featureai.md` — wire-level spec
+- `pan-tools doc-lint` — frontmatter schema validator (orthogonal concern)
+- `pan-tools verify-key-links` — legacy frontmatter-only link verifier (subsumed; both still ship)

package/commands/pan/optimize.md

@@ -1,3 +1,16 @@
+---
+name: pan:optimize
+group: Self-Improvement
+description: Manage the circular optimization loop — apply recommendations, view stats, list reports, manage trace sessions
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+---
+
 # /pan:optimize
 
 Manage the circular optimization loop: apply recommendations, view stats, list reports.

package/commands/pan/patches.md

@@ -1,6 +1,15 @@
 ---
+name: pan:patches
+group: System
 description: Reapply local modifications after a PAN update
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
 ---
 
 <purpose>

package/commands/pan/phase-tests.md

@@ -12,10 +12,7 @@ allowed-tools:
   - Grep
   - Task
   - AskUserQuestion
-argument-instructions: |
-  Parse the argument as a phase number (integer, decimal, or letter-suffix), plus optional free-text instructions.
-  Example: /pan:phase-tests 12
-  Example: /pan:phase-tests 12 focus on edge cases in the pricing module
+argument-instructions: "Parse <phase> as a phase number (integer, decimal like 1.1, or letter-suffix like 1a) followed by optional free-text instructions. Examples: /pan:phase-tests 12 — /pan:phase-tests 12 focus on edge cases in the pricing module"
 ---
 <objective>
 Generate unit and E2E tests for a completed phase, using its summary.md, context.md, and verification.md as specifications.

package/commands/pan/todo-add.md

@@ -2,7 +2,7 @@
 name: pan:todo-add
 group: System
 description: Capture idea or task as todo from current conversation context
-argument-hint: [optional description]
+argument-hint: "[optional description]"
 allowed-tools:
   - Read
   - Write

package/commands/pan/todo-check.md

@@ -2,7 +2,7 @@
 name: pan:todo-check
 group: System
 description: List pending todos and select one to work on
-argument-hint: [area filter]
+argument-hint: "[area filter]"
 allowed-tools:
   - Read
   - Write

package/hooks/dist/pan-cost-logger.js

@@ -33,16 +33,32 @@ function buildCostRecord(data, cwd) {
   // Only log actual subagent stops; ignore other Stop variants.
   if (data.hook_event_name && data.hook_event_name !== 'SubagentStop') return null;
 
+  // P-1805 (v3.7.8): if data.usage is missing/empty (Claude Code headless mode
+  // doesn't include it in the SubagentStop payload), fall back to reading the
+  // transcript_path JSONL and summing usage across the subagent's messages.
+  // Same approach as pan-trace-logger.js for consistency.
+  let inputTokens = extractNumber(data.usage, 'input_tokens');
+  let outputTokens = extractNumber(data.usage, 'output_tokens');
+  let cacheRead = extractNumber(data.usage, 'cache_read_input_tokens');
+  let cacheWrite = extractNumber(data.usage, 'cache_creation_input_tokens');
+  if ((inputTokens + outputTokens + cacheRead + cacheWrite) === 0 && data.transcript_path) {
+    const fromTranscript = readUsageFromTranscript(data.transcript_path, data.session_id);
+    inputTokens = fromTranscript.input_tokens;
+    outputTokens = fromTranscript.output_tokens;
+    cacheRead = fromTranscript.cache_read_input_tokens;
+    cacheWrite = fromTranscript.cache_creation_input_tokens;
+  }
+
   const record = {
     ts: new Date().toISOString(),
     agent: data.agent_type || data.subagent_type || null,
     command: null,
     model: data.model || null,
     tier: null,
-    input_tokens: extractNumber(data.usage, 'input_tokens') || 0,
-    output_tokens: extractNumber(data.usage, 'output_tokens') || 0,
-    cache_read_tokens: extractNumber(data.usage, 'cache_read_input_tokens') || 0,
-    cache_write_tokens: extractNumber(data.usage, 'cache_creation_input_tokens') || 0,
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    cache_read_tokens: cacheRead,
+    cache_write_tokens: cacheWrite,
     cost_usd: null,
     phase: data.phase || null,
     session: data.session_id || null,
@@ -58,6 +74,40 @@ function extractNumber(obj, key) {
   return typeof v === 'number' ? v : 0;
 }
 
+/**
+ * P-1805 (v3.7.8): read transcript JSONL and sum usage across all assistant
+ * messages belonging to the subagent's session. Mirrors the helper in
+ * pan-trace-logger.js. Returns zeros if transcript missing/unreadable.
+ */
+function readUsageFromTranscript(transcriptPath, sessionId) {
+  const totals = {
+    input_tokens: 0,
+    output_tokens: 0,
+    cache_read_input_tokens: 0,
+    cache_creation_input_tokens: 0,
+  };
+  if (!transcriptPath || typeof transcriptPath !== 'string') return totals;
+  let raw;
+  try { raw = fs.readFileSync(transcriptPath, 'utf-8'); } catch { return totals; }
+  for (const line of raw.split('\n')) {
+    if (!line) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (sessionId && entry.session_id && entry.session_id !== sessionId) continue;
+    const usage = entry.usage
+      || entry.message?.usage
+      || entry.response?.usage
+      || (entry.type === 'assistant' && entry.message?.usage)
+      || null;
+    if (!usage || typeof usage !== 'object') continue;
+    totals.input_tokens += extractNumber(usage, 'input_tokens');
+    totals.output_tokens += extractNumber(usage, 'output_tokens');
+    totals.cache_read_input_tokens += extractNumber(usage, 'cache_read_input_tokens');
+    totals.cache_creation_input_tokens += extractNumber(usage, 'cache_creation_input_tokens');
+  }
+  return totals;
+}
+
 /**
  * Append record to .planning/metrics/tokens.jsonl. Silently succeeds
  * even if the file or directory can't be written — hook must not block.