pan-wizard 3.7.10 → 3.10.0

package/commands/pan/experiment.md

@@ -105,6 +105,8 @@ Spawn the external AI runtime against the experiment folder. **Synchronous** —
 
 **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.
 
+**Billing note (Claude runtime):** headless `claude -p` runs bill against the **Claude Agent SDK credit pool** — a monthly allotment separate from your interactive subscription limits (Anthropic split the two effective June 15, 2026). Experiment runs do not consume interactive-session quota, but heavy experimentation can exhaust the SDK pool independently. Captured metrics are tagged `billing_pool: "agent_sdk"` so you can reconcile experiment spend separately.
+
 ### `/pan:experiment status <slug>`
 
 Read the current `run-state.json` snapshot. Returns the full state object (`status`, `stop_reason`, `exit_code`, `elapsed_ms`, `events`).

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/profile.md

@@ -71,4 +71,6 @@ Final tier → provider-native model name
 - All rules are additive to the `quality` / `balanced` / `budget` profile you pick here — profile sets the floor, capability hints adjust upward or downward within that floor's band.
 
 **Inspecting routing:** use `pan-tools resolve-model <agent> --metadata '{"context_estimate":900000,"needs_thinking":true}'` to see what tier a given hint set resolves to.
+
+**Effort dimension (2026-06):** `resolve-model` also returns an `effort` level (`low`/`medium`/`high`/`xhigh`) per agent — the within-model reasoning-depth dial on current models. Profiles modulate it: `budget` steps each agent's base effort down one level (floor `low`); `quality`/`balanced` keep the base. Per-agent override: `.planning/config.json` → `"effort_overrides": { "pan-verifier": "xhigh" }`.
 </tier_decision_tree>

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

@@ -37,23 +37,33 @@ function buildCostRecord(data, cwd) {
   // 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.
+  //
+  // 2026-06: the SubagentStop payload carries no model id either, which left
+  // every hook record with model:null and /pan:cost unable to price it. The
+  // transcript's assistant messages carry message.model right next to the
+  // usage we already read — capture it whenever data.model is absent.
   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) {
+  let model = typeof data.model === 'string' && data.model ? data.model : null;
+  const needUsage = (inputTokens + outputTokens + cacheRead + cacheWrite) === 0;
+  if ((needUsage || !model) && 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;
+    if (needUsage) {
+      inputTokens = fromTranscript.input_tokens;
+      outputTokens = fromTranscript.output_tokens;
+      cacheRead = fromTranscript.cache_read_input_tokens;
+      cacheWrite = fromTranscript.cache_creation_input_tokens;
+    }
+    if (!model) model = fromTranscript.model;
   }
 
   const record = {
     ts: new Date().toISOString(),
     agent: data.agent_type || data.subagent_type || null,
     command: null,
-    model: data.model || null,
+    model,
     tier: null,
     input_tokens: inputTokens,
     output_tokens: outputTokens,
@@ -85,6 +95,7 @@ function readUsageFromTranscript(transcriptPath, sessionId) {
     output_tokens: 0,
     cache_read_input_tokens: 0,
     cache_creation_input_tokens: 0,
+    model: null,
   };
   if (!transcriptPath || typeof transcriptPath !== 'string') return totals;
   let raw;
@@ -94,6 +105,10 @@ function readUsageFromTranscript(transcriptPath, sessionId) {
     let entry;
     try { entry = JSON.parse(line); } catch { continue; }
     if (sessionId && entry.session_id && entry.session_id !== sessionId) continue;
+    // Assistant messages carry the model id alongside their usage — keep the
+    // last one seen (mid-session model switches resolve to the final model).
+    const entryModel = entry.message?.model || entry.model || null;
+    if (typeof entryModel === 'string' && entryModel) totals.model = entryModel;
     const usage = entry.usage
       || entry.message?.usage
       || entry.response?.usage
@@ -149,4 +164,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { buildCostRecord, appendRecord, METRICS_DIR, TOKENS_FILE };
+module.exports = { buildCostRecord, appendRecord, readUsageFromTranscript, METRICS_DIR, TOKENS_FILE };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.7.10",
+  "version": "3.10.0",
   "description": "A lightweight workflow automation and context engineering system for Claude Code, OpenCode, Gemini CLI, Codex, and Copilot CLI.",
   "bin": {
     "pan-wizard": "bin/install.js"
@@ -50,11 +50,11 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.58.2",
-    "@vscode/test-electron": "^2.5.2",
-    "esbuild": "^0.24.0"
+    "@vscode/test-electron": "^2.5.2"
   },
   "scripts": {
     "build:hooks": "node scripts/build-hooks.js",
+    "prepare": "node scripts/install-git-hooks.js",
     "release:check": "node scripts/release-check.js",
     "prepublishOnly": "node scripts/release-check.js",
     "test": "node --test tests/*.test.cjs",
@@ -62,6 +62,7 @@
     "test:all": "node --test tests/*.test.cjs tests/scenarios/*.test.cjs",
     "test:e2e": "node --test tests/scenarios/*.test.cjs",
     "test:vscode": "npx playwright test --config tests/e2e/playwright.config.mjs",
-    "test:watch": "node --test --watch tests/*.test.cjs"
+    "test:watch": "node --test --watch tests/*.test.cjs",
+    "build:plugin": "node scripts/build-plugin.js"
   }
 }

package/pan-wizard-core/bin/lib/codebase.cjs

@@ -5,6 +5,8 @@
  * Supports JS/TS (v0), with extensible language registry for Python/Go/Rust/Java/C# (v1).
  */
 
+// @pan: ADR-0021
+
 const fs = require('fs');
 const path = require('path');
 const { CODEBASE_DIR, DRIFT_MAX_FILE_SIZE } = require('./constants.cjs');