pan-wizard 3.32.0 → 3.34.0

package/bin/install.js

@@ -364,15 +364,10 @@ function getCommitAttribution(runtime) {
       result = settings.attribution.commit;
     }
   } else if (runtime === 'claude') {
-    // Claude Code
+    // Claude Code: `attribution: false`, `attribution.commit` and the deprecated
+    // `includeCoAuthoredBy`, resolved in the documented order (install-lib).
     const settings = readSettings(path.join(getGlobalDir('claude', explicitConfigDir), 'settings.json')) || {}; // unusable file = no info (read-only probe)
-    if (!settings.attribution || settings.attribution.commit === undefined) {
-      result = undefined;
-    } else if (settings.attribution.commit === '') {
-      result = null;
-    } else {
-      result = settings.attribution.commit;
-    }
+    result = lib.commitAttributionFromSettings(settings);
   } else if (runtime === 'copilot') {
     // Copilot CLI: user-editable settings live in settings.json; config.json is
     // legacy (auto-migrated by the CLI, now internal state) — fall back for old installs
@@ -450,6 +445,8 @@ function copyFlattenedCommands(srcDir, destDir, prefix, pathPrefix, runtime) {
       content = content.replace(globalClaudeRegex, pathPrefix);
       content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
       content = content.replace(opencodeDirRegex, pathPrefix);
+      // As in copyWithPathReplacement: no `pan-tools` bin is on PATH.
+      content = content.replace(/\bpan-tools\b(?=\s+[a-z])/g, `node ${pathPrefix}pan-wizard-core/bin/pan-tools.cjs`);
       content = processAttribution(content, getCommitAttribution(runtime));
       content = convertClaudeToOpencodeFrontmatter(content);
 
@@ -509,6 +506,7 @@ function copyCommandsAsCodexSkills(srcDir, skillsDir, prefix, pathPrefix, runtim
       content = content.replace(globalClaudeRegex, pathPrefix);
       content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
       content = content.replace(codexDirRegex, pathPrefix);
+      content = lib.rewriteAgentFileRefs(content, runtime, pathPrefix);
       // Codex executes commands literally; no `pan-tools` bin on PATH.
       const panToolsPath = `${pathPrefix}pan-wizard-core/bin/pan-tools.cjs`;
       content = content.replace(/\bpan-tools\b(?=\s+[a-z])/g, `node ${panToolsPath}`);
@@ -826,6 +824,7 @@ function copyCommandsAsCopilotSkills(srcDir, skillsDir, prefix, pathPrefix, runt
       const localClaudeRegex = /\.\/\.claude\//g;
       content = content.replace(globalClaudeRegex, pathPrefix);
       content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
+      content = lib.rewriteAgentFileRefs(content, runtime, pathPrefix);
       // Copilot CLI executes commands literally; there's no `pan-tools` bin on PATH.
       // Replace bare `pan-tools` invocations with the explicit node + .cjs path.
       const panToolsPath = `${pathPrefix}pan-wizard-core/bin/pan-tools.cjs`;
@@ -881,6 +880,11 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
         const localClaudeRegex = /\.\/\.claude\//g;
         content = content.replace(globalClaudeRegex, pathPrefix);
         content = content.replace(localClaudeRegex, `./${dirName}/`);
+        // No runtime puts a `pan-tools` bin on PATH: invoke it via node, as the Codex
+        // and Copilot converters already did. A bare `pan-tools <verb>` in an installed
+        // Claude, Gemini or OpenCode command or workflow was a call that could not run.
+        content = content.replace(/\bpan-tools\b(?=\s+[a-z])/g, `node ${pathPrefix}pan-wizard-core/bin/pan-tools.cjs`);
+        content = lib.rewriteAgentFileRefs(content, runtime, pathPrefix);
         content = processAttribution(content, getCommitAttribution(runtime));
 
         // Convert frontmatter for opencode compatibility
@@ -1249,6 +1253,16 @@ function uninstall(isGlobal, runtime = 'claude') {
     }
   }
 
+  // 4a'. Remove the OpenCode plugin (O12); the plugins directory goes too when
+  // nothing else is in it.
+  const opencodePlugin = path.join(targetDir, 'plugins', OPENCODE_PLUGIN_FILE);
+  if (fs.existsSync(opencodePlugin)) {
+    try { fs.unlinkSync(opencodePlugin); } catch {}
+    try { fs.rmdirSync(path.dirname(opencodePlugin)); } catch { /* not empty: the user's own plugins stay */ }
+    removedCount++;
+    console.log(`  ${green}✓${reset} Removed the PAN plugin`);
+  }
+
   // 4b. Codex: strip PAN entries from the shared .codex/hooks.json (foreign
   // hook registrations are preserved; the file is deleted only when nothing
   // but PAN content remained).
@@ -1847,6 +1861,8 @@ const PATCHES_DIR_NAME = 'pan-local-patches';
 // the patches tree stays self-contained.
 const EXTERNAL_PATCHES_SUBDIR = '_external';
 const MANIFEST_NAME = 'pan-file-manifest.json';
+// PAN's OpenCode plugin, installed as <opencode dir>/plugins/pan-wizard.js (O12).
+const OPENCODE_PLUGIN_FILE = 'pan-wizard.js';
 
 /**
  * Compute SHA256 hash of file contents
@@ -1968,6 +1984,11 @@ function writeManifest(configDir, runtime = 'claude', isGlobal = false) {
       }
     }
   }
+  // The OpenCode plugin (O12)
+  const opencodePlugin = path.join(configDir, 'plugins', OPENCODE_PLUGIN_FILE);
+  if (isOpencode && fs.existsSync(opencodePlugin)) {
+    manifest.files[`plugins/${OPENCODE_PLUGIN_FILE}`] = fileHash(opencodePlugin);
+  }
 
   try {
     fs.writeFileSync(path.join(configDir, MANIFEST_NAME), JSON.stringify(manifest, null, 2));
@@ -2253,7 +2274,9 @@ function install(isGlobal, runtime = 'claude') {
       // last; the per-runtime core remains for agents/hooks.
       const sharedCoreDest = path.join(agentsRoot, 'pan-wizard-core');
       copySharedCore(path.join(src, 'pan-wizard-core'), sharedCoreDest, corePrefix, pathPrefix, runtime);
-      try { fs.writeFileSync(path.join(sharedCoreDest, 'VERSION'), pkg.version); } catch { /* non-fatal */ }
+      // With its newline, as the per-runtime core writes it: `/pan:update` cats the file
+      // and prints the runtime flag next, which glued onto a bare version.
+      try { fs.writeFileSync(path.join(sharedCoreDest, 'VERSION'), pkg.version + '\n'); } catch { /* non-fatal */ }
 
       // Canonical agent-definition reference copies (ADR-0028 agent-ref
       // canonicalization): shared content references these instead of the
@@ -2456,6 +2479,9 @@ function install(isGlobal, runtime = 'claude') {
           // Always replace ~/.claude/ as it is the source of truth in the repo
           const dirRegex = /~\/\.claude\//g;
           content = content.replace(dirRegex, pathPrefix);
+          // As in copyWithPathReplacement: no `pan-tools` bin is on PATH.
+          content = content.replace(/\bpan-tools\b(?=\s+[a-z])/g, `node ${pathPrefix}pan-wizard-core/bin/pan-tools.cjs`);
+          content = lib.rewriteAgentFileRefs(content, runtime, pathPrefix);
           content = processAttribution(content, getCommitAttribution(runtime));
           // Codex custom agents are standalone TOML files (2026-06 format);
           // markdown in .codex/agents/ is not recognized. Handle before
@@ -2644,6 +2670,21 @@ function install(isGlobal, runtime = 'claude') {
     }
   }
 
+  // OpenCode plugin (memory optimisation O12). OpenCode runs no command hooks, but a
+  // plugin can add to the prompt it compacts a session with; PAN's keeps the phase
+  // in flight through a compaction, as hooks/pan-state-reinject.js does on the other
+  // hosts. CommonJS, beside the package.json written above.
+  if (isOpencode) {
+    try {
+      const pluginsDir = path.join(targetDir, 'plugins');
+      fs.mkdirSync(pluginsDir, { recursive: true });
+      fs.copyFileSync(path.join(src, 'pan-wizard-core', 'opencode', OPENCODE_PLUGIN_FILE), path.join(pluginsDir, OPENCODE_PLUGIN_FILE));
+      console.log(`  ${green}✓${reset} Installed the PAN plugin to plugins/ (keeps PAN's position through compaction)`);
+    } catch (e) {
+      pushInstallWarning('opencodePlugin', `plugins/${OPENCODE_PLUGIN_FILE}`, e);
+    }
+  }
+
   if (failures.length > 0) {
     console.error(`\n  ${yellow}Installation incomplete!${reset} Failed: ${failures.join(', ')}`);
     process.exit(1);
@@ -2744,6 +2785,28 @@ function install(isGlobal, runtime = 'claude') {
   const stateReinjectCommand = isGlobal
     ? buildHookCommand(targetDir, 'pan-state-reinject.js')
     : 'node ' + dirName + '/hooks/pan-state-reinject.js';
+  // Gemini and Copilot (M33): a marker before the compaction, the block on the next
+  // tool result. The inject mode names the host, whose output shapes differ.
+  const stateReinjectMarkCommand = `${stateReinjectCommand} --mark`;
+  const stateReinjectInjectCommand = `${stateReinjectCommand} --inject ${isCopilot ? 'copilot' : 'gemini'}`;
+
+  // Every hook command about to be registered must run a script that is there
+  // (market-ideas M24). The copy above skips the hooks when hooks/dist is absent (a
+  // source checkout without `npm run build:hooks`), and every hook was registered
+  // anyway, so each session event then ran a missing file. Fail before writing any
+  // runtime config. OpenCode registers no hooks.
+  if (!isOpencode) {
+    const entrypoints = lib.verifyHookEntrypoints([
+      updateCheckCommand, contextMonitorCommand, statuslineCommand, costLoggerCommand,
+      traceLoggerCommand, stopGuardCommand, stateReinjectCommand, stateReinjectMarkCommand, stateReinjectInjectCommand,
+    ], process.cwd());
+    if (!entrypoints.ok) {
+      console.error(`\n  ${red}✖ Hook verification FAILED — these hook commands would run a script that is not there:${reset}`);
+      for (const m of entrypoints.missing) console.error(`    - ${m}`);
+      console.error(`\n  No hooks were registered. In a source checkout, run ${cyan}npm run build:hooks${reset} first, then re-run the installer.\n`);
+      process.exit(1);
+    }
+  }
 
   if (isCodex) {
     // Codex hooks (2026-06): Claude-compatible PascalCase events in the shared
@@ -2773,12 +2836,12 @@ function install(isGlobal, runtime = 'claude') {
   // from any legacy config.json registration.
   if (isCopilot) {
     const hooksConfigPath = path.join(targetDir, 'hooks', 'pan.json');
-    const hooksConfig = buildCopilotHooksConfig({ updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand });
+    const hooksConfig = buildCopilotHooksConfig({ updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectMarkCommand, stateReinjectInjectCommand });
     try {
       fs.mkdirSync(path.dirname(hooksConfigPath), { recursive: true });
       fs.writeFileSync(hooksConfigPath, JSON.stringify(hooksConfig, null, 2) + '\n');
       // Same as the Codex case: a global Copilot install writes to ~/.copilot/, not .github/.
-      console.log(`  ${green}✓${reset} Configured hooks (${displayPath(hooksConfigPath)}: update check, context monitor, cost + trace loggers, stop guard)`);
+      console.log(`  ${green}✓${reset} Configured hooks (${displayPath(hooksConfigPath)}: update check, context monitor, cost + trace loggers, stop guard, state re-injection)`);
     } catch (e) {
       console.error(`  ${yellow}✗${reset} Failed to write Copilot hooks config: ${e.message}`);
     }
@@ -2872,19 +2935,27 @@ function install(isGlobal, runtime = 'claude') {
       { slot: 'subagentStop', hook: 'pan-trace-logger', command: traceLoggerCommand, label: 'trace logger hook' },
       { slot: 'stop', hook: 'pan-stop-guard', command: stopGuardCommand, label: 'auto-advance stop guard hook' },
       { slot: 'compact', hook: 'pan-state-reinject', command: stateReinjectCommand, label: 'state re-injection hook (after compaction)' },
+      // Gemini (M33): no start event follows a compaction, so a marker before it and
+      // the block on the next tool result.
+      { slot: 'compactMark', hook: 'pan-state-reinject', command: stateReinjectMarkCommand, label: 'state re-injection marker (before compaction)' },
+      { slot: 'compactInject', hook: 'pan-state-reinject', command: stateReinjectInjectCommand, label: 'state re-injection (first tool result after compaction)' },
     ];
+    // Every event a hook registers under on this runtime: a hook may have more than
+    // one (pan-state-reinject on Gemini), and the upgrade sweep must leave all of them.
+    const eventsOf = (hook) => registrations.filter((x) => x.hook === hook).map((x) => events[x.slot]).filter(Boolean);
     const unsupported = [];
     for (const r of registrations) {
       const event = events[r.slot] || null;
       // Upgrade path: an entry for this hook under any other event is dead (a key
       // the runtime does not have) or a stale duplicate. Keyed on the script, so a
       // hook that moved event is cleaned wherever an older install put it.
-      const removedFrom = lib.stripPanHookEntries(settings.hooks, [r.hook], event);
+      const keep = eventsOf(r.hook);
+      const removedFrom = lib.stripPanHookEntries(settings.hooks, [r.hook], keep);
       if (removedFrom.length > 0) {
-        console.log(`  ${green}✓${reset} Removed the ${r.label} from ${removedFrom.join(', ')}${event ? '' : ` (${runtime} has no event for it)`}`);
+        console.log(`  ${green}✓${reset} Removed the ${r.label} from ${removedFrom.join(', ')}${keep.length ? '' : ` (${runtime} has no event for it)`}`);
       }
       if (!event) {
-        unsupported.push(r.hook);
+        if (keep.length === 0 && !unsupported.includes(r.hook)) unsupported.push(r.hook);
         continue;
       }
       if (!Array.isArray(settings.hooks[event])) {
@@ -2903,7 +2974,7 @@ function install(isGlobal, runtime = 'claude') {
       delete settings.hooks;
     }
     if (isGemini && unsupported.length > 0) {
-      console.log(`  ${dim}ℹ Gemini CLI has no context-window metric for hooks, no subagent-completion event and no post-compaction event that adds context, so ${unsupported.join(', ')} ${unsupported.length === 1 ? 'is' : 'are'} not registered there${reset}`);
+      console.log(`  ${dim}ℹ Gemini CLI has no context-window metric for hooks and no subagent-completion event, so ${unsupported.join(', ')} ${unsupported.length === 1 ? 'is' : 'are'} not registered there${reset}`);
     }
   }
 

package/commands/pan/army.md

@@ -1,6 +1,7 @@
 ---
 name: army
 group: Army
+argument-hint: "<goal> [--source scan|backlog] [--max-cycles N] [--total-budget N] [--enforce-budget] [--verify-reserve F] [--squads a,b,c] [--no-build-worktrees] [--push] [--clean-seal] [--schedule <cadence>] [--daily-budget N] [--dry-run] [--continue] [--stop] [--status]"
 description: Bot-army campaign — Mission Control (the reasoning-tier conductor) delegates a whole-project goal to squads (architecture / build / quality / release), each squad working branch-per-agent worktrees under a hard safety harness, gated by CI + a human merge, looping plan→delegate→execute→review→integrate→learn until the goal ships or a stop condition fires.
 allowed-tools:
   - Read
@@ -25,7 +26,7 @@ The army is the campaign-scale sibling of `/pan:exec-phase --hierarchical` (one
 
 | Tier | Who | Model tier | Access |
 |------|-----|-----------|--------|
-| 0 · Mission Control | `pan-conductor` | `reasoning` (`mid` under `budget`) | delegation-first (Agent toolset) — instructed to route work, not write it |
+| 0 · Mission Control | `pan-conductor` | the session model (spawned with no `model`, so under every profile) | delegation-first (Agent toolset) — instructed to route work, not write it |
 | 1 · Architecture | design + planning agents — `squad show architecture` lists them | `reasoning` | `read-only` |
 | 1 · Build | `pan-executor` | `reasoning` | `read-write-bash` — one branch+worktree per agent |
 | 1 · Quality | adversarial review + debug agents — `squad show quality` lists them | `mid` | `read-only`, adversarial |
@@ -34,11 +35,11 @@ The army is the campaign-scale sibling of `/pan:exec-phase --hierarchical` (one
 
 **Where each row comes from.** The tier-1 rows mirror the `squads[]` records `pan-tools squad list` prints — label, `tier`, `access` (their member names come from `squad show <name>`, since `squad list` reports only a count). The Tier 0 and Tier 2 rows are PAN's hierarchy positions: the same command names them under its `coordinator` and `workers` keys, but reports nothing else about them, so the Model-tier and Access values on those two rows are written here rather than returned by the command. Resolve the roster at runtime — never hardcode it: `pan-tools squad list` and `pan-tools squad show <name>`.
 
-**Reading the Model-tier column.** These are PAN *tiers*, not model names. `reasoning` resolves to `inherit` — the model you launched with — while `mid` and `fast` map to the provider's mid/fast models (Sonnet and Haiku on Anthropic).
+**Reading the Model-tier column.** These are PAN *tiers*, not model names. `reasoning` resolves to `inherit` — the model you launched with — while `mid` and `fast` map to the provider's mid/fast models (Sonnet and Haiku on Anthropic). They are what `squad list` and `resolve-model` report: the army's spawns pass no model, so an agent spawned under its own type runs on its file's `model:` (the reviewer-class agents pin `opus` on Claude Code) or, without one, the session model.
 
-**Reading the Access column.** The backticked values on the tier-1 rows are the `access` labels `squad list` reports; tier 0 and tier 2 carry PAN's own. They are role contracts the conductor's prompt assigns when it delegates, not a sandbox: `squads.cjs` says of itself that it "modifies no agent and changes no execution path", so a label can differ from what an agent may actually do — expect that, since several `read-only` squad members hold `Write` to emit planning or verification artifacts. The binding grant is each agent's own `tools:` frontmatter (`grep '^tools:' agents/*.md`), and Mission Control's includes `Write` and `Bash`: routing rather than coding is how it is instructed to behave, not something the runtime prevents. The rail those grants do enforce is delegation depth — `grep -l '^tools:.*Task' agents/*.md` names every agent able to spawn another (today, `pan-conductor`), so a squad agent cannot fan out further.
+**Reading the Access column.** The backticked values on the tier-1 rows are the `access` labels `squad list` reports; tier 0 and tier 2 carry PAN's own. They are role contracts the conductor's prompt assigns when it delegates, not a sandbox: `squads.cjs` says of itself that it "modifies no agent and changes no execution path", so a label can differ from what an agent may actually do — expect that, since several `read-only` squad members hold `Write` to emit planning or verification artifacts. The binding grant is each agent's own `tools:` frontmatter (`grep '^tools:' ~/.claude/agents/*.md`), and Mission Control's includes `Write` and `Bash`: routing rather than coding is how it is instructed to behave, not something the runtime prevents. The rail those grants do enforce is delegation depth — `grep -l '^tools:.*Task' ~/.claude/agents/*.md` names every agent able to spawn another (today, `pan-conductor`), so a squad agent cannot fan out further.
 
-**Squad tier is not profile tier.** The tier column above is a `squads.cjs` grouping attribute — what `pan-tools squad list` reports — and it is not what resolves an agent's model; that comes from the active `model_profile` (`quality` and `balanced` are `reasoning` for every agent, and `budget` is the only profile that down-tiers), plus any `model:` pin in an agent's own frontmatter. So the `mid` on the Quality and Release rows does not describe what those agents run under the default profile — under `quality` and `balanced` they resolve `reasoning` like everything else. The tier-1 values above are the squad groupings; the tier-0 and tier-2 values are per-agent profile tiers. **`budget` resolves per agent, not per row:** it sends some workers to `fast` and others to `mid`, so no single value is true of the Tier 2 row — `MODEL_PROFILES` in `pan-wizard-core/bin/lib/core.cjs` is the table, and it is the one to read rather than a tier written into a doc. For the agents that pin a model outright, `grep -l '^model: opus' agents/*.md` lists them — the pin applies on Claude Code only, since the installer strips it for the other runtimes.
+**Squad tier is not profile tier.** The tier column above is a `squads.cjs` grouping attribute — what `pan-tools squad list` reports — and it is not an agent's profile tier, which is what `resolve-model` reports from the active `model_profile` (`quality` and `balanced` are `reasoning` for every agent, and `budget` is the only profile that down-tiers). The army applies neither: its spawns pass no model, so an agent runs on its own `model:` pin, else the session model, under every profile. So the `mid` on the Quality and Release rows does not describe what those agents run. The tier-1 values above are the squad groupings; the tier-2 value is the per-agent profile tier `resolve-model` reports. **`budget` resolves per agent, not per row:** `resolve-model` reports `fast` for some workers and `mid` for others, so no single value is true of the Tier 2 row — `MODEL_PROFILES` in `~/.claude/pan-wizard-core/bin/lib/core.cjs` is the table, and it is the one to read rather than a tier written into a doc. For the agents that pin a model outright, `grep -l '^model: opus' ~/.claude/agents/*.md` lists them — the pin applies on Claude Code only, since the installer strips it for the other runtimes.
 
 ---
 
@@ -75,6 +76,7 @@ Every cap the conductor enforces applies to the campaign, scaled up:
 
 ```
 /pan:army "<goal>" [--source scan|backlog] [--max-cycles N] [--total-budget N]
+          [--enforce-budget] [--verify-reserve F]
           [--squads a,b,c] [--no-build-worktrees] [--push] [--clean-seal]
           [--schedule <cadence>] [--daily-budget N]
           [--dry-run] [--continue] [--stop] [--status]
@@ -102,20 +104,20 @@ Every cap the conductor enforces applies to the campaign, scaled up:
 
 ```
 /pan:army
-  Phase 0  MUSTER   — squad list + roster validate · cache prime · baseline · loop-state · abort-file clear
+  Phase 0  MUSTER   — squad list + roster validate · baseline · loop-state · abort-file clear
   Phase 1  PLAN     — Mission Control (session model, xhigh effort) decomposes the goal into dependency-ordered missions
   Phase 2  DELEGATE — pick the next item (focus-auto --source) · route to the owning squad over the Agent toolset
   Phase 3  EXECUTE  — Build squad: one army/<task> worktree per agent (parallel); Architecture/Quality research in parallel (read-only)
   Phase 4  REVIEW   — Quality squad on the built tree: reviewer + hardener + meta → verdict ladder; a block is a hard gate
   Phase 5  INTEGRATE— Release squad: prepare squash-merge → CI/verification → ALWAYS-ASK human approval → tag → deploy hand-off
-  Phase 6  LEARN    — summaries return to Mission Control; retro/learn writes patterns to memory (this is "Dreaming")
+  Phase 6  LEARN    — summaries return to Mission Control; retro/learn patterns go into the next mission's plan (this is "Dreaming")
   → loop to Phase 2 until a stop condition; --clean-seal once at the end
 ```
 
 ### Phase 0 — Muster (once)
-1. **Onboarding gate (existing projects).** Run `pan-tools init new-project` to detect state. If `is_brownfield` (existing code) and `needs_codebase_map` (no `.planning/codebase/`), the army cannot plan blind — STOP and route through onboarding first: `/pan:map-codebase` (Architecture squad's `pan-document_code` maps the existing system into `.planning/codebase/`), then `/pan:new-project` to build `roadmap.md` + `requirements.md` *against the existing system*. Re-run `/pan:army` once a backlog exists. If a codebase map + roadmap already exist, continue.
+1. **Onboarding gate (existing projects).** Run `pan-tools init new-project` to detect state. If `is_brownfield` (existing code) and `needs_codebase_map` (no `.planning/codebase/`), the army cannot plan blind — STOP and route through onboarding first: `/pan:map-codebase` (its `pan-document_code` mappers — workers in `pan-tools squad list`, not Architecture squad members — map the existing system into `.planning/codebase/`), then `/pan:new-project` to build `roadmap.md` + `requirements.md` *against the existing system* — only when `project_exists` is false: it refuses an initialized project, which needs just the map. Re-run `/pan:army` once a backlog exists. If a codebase map + roadmap already exist, continue.
 2. `pan-tools squad list` and validate the roster is healthy.
-3. Prime the cache; capture baseline (`git status` clean of project source; tests green or STOP). On a brownfield repo, the baseline is the current `main` — every `army/<task>` branch forks from it, so the existing code is never edited in place.
+3. Capture the baseline (`git status` clean of project source; tests green or STOP). On a brownfield repo, the baseline is the commit you have checked out — every `army/<task>` branch forks from it (`worktree create` bases it on `HEAD`), so the existing code is never edited in place.
 4. Ensure `.planning/orchestration/` exists; clear any stale `abort` file; init loop-state.
 5. `--dry-run` → print the plan + per-squad delegation and STOP.
 
@@ -138,7 +140,7 @@ Spawn `pan-release`. It prepares the squash-merge, runs the configured `verifica
 **Phase report (opt-in build deliverable):** when `workflow.phase_reports.enabled` is `true`, generate the mission's self-contained per-phase HTML report **in the built tree, before staging the squash-merge** — `pan-tools report phase <N>` — so the report rides along in the merge as a phase deliverable. **Never run `report index` inside a squad worktree:** the timeline index is a single shared file that aggregates *all* phases, so a worktree would see only its own phase and concurrent squads would race on it. The index is a single-writer, post-merge concern (Phase 6). Never opens a browser.
 
 ### Phase 6 — Learn (Dreaming)
-Squad summaries return to Mission Control. Run `/pan:retro --write-memory` (and `/pan:learn` if traces exist) so recurring patterns persist into agent memory for the next mission. Strike the landed item; update loop-state. For a scheduled campaign, also `pan-tools campaign record-run --items <n> --points <p>` so the next-due time and the day's spend advance.
+Squad summaries return to Mission Control. Run `/pan:retro` (and `/pan:learn` if traces exist) and carry the recurring patterns into the next mission yourself: name them in the plan you hand the Architecture squad. Agent memory does not do this, because PAN does not load it into agents. A pattern that should outlast the campaign goes to the human at the merge gate as a proposed line for the project's instructions. Strike the landed item; update loop-state. For a scheduled campaign, also `pan-tools campaign record-run --items <n> --points <p>` so the next-due time and the day's spend advance.
 
 **Rebuild the timeline index (single writer).** When `workflow.phase_reports.enabled` and `workflow.phase_reports.index` are `true`, Mission Control — and *only* Mission Control, on the integration branch after the merge has landed — rebuilds the project index once against the now-merged set of phases: `pan-tools report index`, then commit it (the commit honors `commit_docs`). Doing this post-merge from the single conductor is what keeps `report-index.html` consistent while builds run in parallel worktrees.
 
@@ -161,7 +163,7 @@ Nothing under `pan-army-*` or on an `army/*` branch is a deliverable: the squash
 PAN is not a daemon — it cannot wake itself while the session is closed. `--schedule` arms a campaign and lets an external trigger drive it; the human merge gate is never relaxed.
 
 - **Arm:** `/pan:army "<goal>" --schedule daily --daily-budget 200` writes `.planning/orchestration/schedule.json` (cadence, daily budget, next-due) instead of running once.
-- **The trigger (you wire one):** a host scheduler (Claude Code routines / cron / scheduled-tasks) or a `/loop` runs `pan-tools campaign due` and, when it reports due, invokes `/pan:army --continue`. On next session open, a due campaign is surfaced as a nudge.
+- **The trigger (you wire one):** a host scheduler (Claude Code routines / cron / scheduled-tasks) or a `/loop` runs `pan-tools campaign due` and, when it reports due, invokes `/pan:army --continue`. Nothing surfaces a due campaign on its own: PAN does not wake itself, so without a trigger the campaign waits until you run `/pan:army --continue` (`pan-tools campaign due` says whether one is due).
 - **Resume (`--continue`):** read the schedule + `.planning/orchestration/` + focus-auto state. If `campaign due` is true and the day's `--daily-budget` isn't spent, run the next mission(s), then `campaign record-run` (advances next-due, accrues the day's spend). If not due or budget-spent, report next-due and STOP.
 - **Bounded spend:** point budgets (`--total-budget`, `--daily-budget`) are **advisory indicators by default** — they're tracked and surfaced, not hard stops. `--enforce-budget` (or config `budget.enforce`) makes `--total-budget` a hard stop; a scheduled campaign's `--daily-budget` pauses the day's run only when the schedule was armed with `--enforce-budget` (`campaign schedule --enforce-budget`; `--advisory-budget` turns it back off). The real bounds are `--max-cycles`, the conductor caps, the abort file, and the human merge gate at every integrate. A scheduled campaign runs the backlog down to staged, reviewed, green PRs over days.
 - **Verify reserve:** a fraction of `--total-budget` (`--verify-reserve`, default 0.15) is held back so the closing Quality re-review isn't starved. Surfaced always via `campaign status` / `focus auto --status` (`into_verify_reserve`, `new_work_budget_remaining`); under `--enforce-budget` the run stops taking on new missions early (`budget_reserve_reached`) and spends the reserve on the final `--clean-seal` verification before the last INTEGRATE.
@@ -171,7 +173,9 @@ Manage it: `pan-tools campaign status` (active/paused, spent today, next-due), `
 ---
 
 ## Completion contract
-The campaign is complete when ANY holds: `--max-cycles` reached · backlog empty · abort file present · context < 25% · a mission cannot pass Quality and can't be cleanly reverted (HARD STOP — preserve state, report). (Budget exhaustion is advisory by default — a stop condition only when `budget.enforce`/`--enforce-budget` is set; under enforcement, crossing into the verify reserve (`budget_reserve_reached`) stops new missions but the reserved points still fund the closing re-verification.) Always run `--clean-seal` (unless omitted) after the last item.
+The campaign is complete when ANY holds: `--max-cycles` reached · backlog empty · abort file present · a mission cannot pass Quality and can't be cleanly reverted (HARD STOP — preserve state, report). (Budget exhaustion is advisory by default — a stop condition only when `budget.enforce`/`--enforce-budget` is set; under enforcement, crossing into the verify reserve (`budget_reserve_reached`) stops new missions but the reserved points still fund the closing re-verification.) Before each new mission, run `pan-tools cost limits --raw`: `weekly_limit_reached` (Claude Code's 7-day usage window at `cost.weekly_limit_stop_pct`, default 90%) is a stop condition too, so the rest of the window stays the user's. Always run `--clean-seal` (unless omitted) after the last item.
+
+The context monitor's notes are not a stop condition: they give no figure and ask for a checkpoint. On the critical note, bring the mission's state in `.planning/orchestration/` up to date and carry on. After the host compacts, re-read the campaign with `pan-tools focus auto --status` and `.planning/orchestration/`: PAN's state re-injection carries state.md's position, not the campaign's.
 
 ## NEVER DO
 - Let Mission Control write code, or let a squad agent spawn further agents (depth cap).
@@ -184,7 +188,7 @@ The campaign is complete when ANY holds: `--max-cycles` reached · backlog empty
 - Plan on the session model Mission Control inherits, delegate over the Agent toolset, keep each squad's return a tight summary.
 - One worktree per Build agent; parallel research/verify; serial human-gated integrate.
 - Check the abort file + spawn/budget caps before every spawn.
-- Finish with the clean-build seal; write learnings back to memory.
+- Finish with the clean-build seal; carry the learnings into the next mission's plan.
 
 ## Examples
 ```

package/commands/pan/assumptions.md

@@ -2,7 +2,7 @@
 name: pan:assumptions
 group: Phase Management
 description: Surface Claude's assumptions about a phase approach before planning
-argument-hint: "[phase]"
+argument-hint: "<phase>"
 allowed-tools:
   - Read
   - Bash
@@ -70,7 +70,7 @@ GOOD: "Assumption: The project uses Express for routing — Evidence: require('e
    - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
    - Present assumptions clearly with file:line references where applicable
    - Prompt "What do you think?"
-5. Gather feedback and offer next steps
+6. Gather feedback and offer next steps
 </process>
 
 <success_criteria>

package/commands/pan/audit-deployment.md

@@ -54,8 +54,7 @@ Claude:   <target>/.claude/
 Gemini:   <target>/.gemini/
 OpenCode: <target>/.opencode/
 Codex:    <target>/.codex/
-Copilot:  <target>/.copilot/ (or ~/.copilot/)
-GitHub:   <target>/.github/
+Copilot:  <target>/.github/ (local install) or ~/.copilot/ (global)
 ```
 
 For the detected runtime config directory (CONFIG_DIR), audit ALL of the following:
@@ -88,14 +87,14 @@ For the detected runtime config directory (CONFIG_DIR), audit ALL of the followi
 - [ ] `CONFIG_DIR/agents/` — every manifest-listed agent file present
 - Verify key agents exist: pan-planner, pan-executor, pan-verifier, pan-debugger
 
-**1.6 Hooks**
+**1.6 Hooks** (not OpenCode: its install copies no hooks — check `CONFIG_DIR/plugins/pan-wizard.js` instead)
 - [ ] `CONFIG_DIR/hooks/pan-statusline.js` exists
 - [ ] `CONFIG_DIR/hooks/pan-check-update.js` exists
 - [ ] `CONFIG_DIR/hooks/pan-context-monitor.js` exists
 
 **1.7 Settings/Config**
 - [ ] Settings file exists (settings.json / opencode.json / config.json)
-- [ ] Hooks are registered — Claude `settings.json`: SessionStart, PostToolUse, SubagentStop, Stop, statusLine; Gemini `settings.json`: SessionStart and AfterAgent only (no statusLine); Codex: `.codex/hooks.json`; Copilot: `.github/hooks/pan.json`
+- [ ] Hooks are registered — Claude `settings.json`: SessionStart, PostToolUse, SubagentStop, Stop, statusLine; Gemini `settings.json`: SessionStart, AfterAgent, PreCompress and AfterTool (the last two for state re-injection; no statusLine); Codex: `.codex/hooks.json`; Copilot: `.github/hooks/pan.json`
 - [ ] Hook commands point to existing files
 
 **1.8 Manifest Integrity**
@@ -137,13 +136,13 @@ Check `.planning/` directory in the target:
 - Parse state.md "Current Position" — extract phase number
 - Count actual phase directories — do they match?
 - Check roadmap.md phase count vs actual directories
-- Verify no orphaned .continue-here-*.md files (paused but not resumed)
+- Check `.planning/phases/*/.continue-here*.md` (pause writes `.continue-here.md`): resuming does not delete it (only the transition workflow removes a completed phase's handoffs), so its presence alone does not mean the session was never resumed
 
 **2.5 Config Sanity**
 - Validate config.json values are within expected ranges
 - `model_profile`: "quality" | "balanced" | "budget"
 - `commit_docs`: boolean
-- `workflow.*` toggles (research, plan_check, verifier, ...): all boolean
+- `workflow.*` toggles (research, plan_check, verifier, ...): boolean — except `workflow.phase_reports`, an object (`enabled`, `open`, `theme`, `index`)
 - `budget`: `default_points` numeric, `enforce` boolean
 </step>
 
@@ -170,7 +169,7 @@ For each phase with plan files (`*-plan.md`, e.g. `01-01-plan.md`):
 - Check for PAN-style commit messages
 
 **3.4 Session Continuity**
-- Check for .continue-here-*.md files (indicates paused sessions)
+- Check for `.planning/phases/*/.continue-here*.md` files (a pause happened at some point; nothing removes them on resume)
 - Check state.md session logs for gaps
 - Look for evidence of context loss (repeated work, contradictory decisions)
 
@@ -250,7 +249,7 @@ Verification Coverage: <N>%
 If `--repair` flag was provided, attempt auto-fixes for repairable issues:
 - Regenerate missing settings.json with default hook config
 - Create missing .planning/config.json with defaults
-- Remove orphaned .continue-here-*.md files
+- Remove `.planning/phases/*/.continue-here*.md` files the user confirms are stale
 
 Report repairs performed.
 </step>
@@ -285,10 +284,10 @@ The spec MUST follow this exact format to be consumable by superplan.md:
 
 ## Success Criteria
 
-```
+~~~
 SC-1: <measurable criterion>
 SC-2: <measurable criterion>
-```
+~~~
 
 ## Design
 
@@ -313,9 +312,9 @@ SC-2: <measurable criterion>
 
 ### Dependency Graph
 
-```
+~~~
 A.1 ──> A.2 ──> A.3
-```
+~~~
 
 ## Test Plan
 

package/commands/pan/cost.md

@@ -2,7 +2,7 @@
 name: pan:cost
 group: Observability
 description: Show token usage and estimated cost across PAN commands and agents
-argument-hint: "[report|append|clear|rebuild] [--format json|table|chart] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--apply] [--no-main-thread]"
+argument-hint: "[report|append|clear|rebuild|limits] [--format json|table|chart] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--apply] [--no-main-thread]"
 allowed-tools:
   - Read
   - Bash
@@ -13,7 +13,7 @@ Report token usage and estimated cost across all PAN invocations in this project
 
 Reads `.planning/metrics/tokens.jsonl` — an append-only log where each line is one call (agent or command) with token counts and model. Cost is computed from a built-in rate table (overridable via `.planning/config.json` → `cost.rates`).
 
-Default output is JSON for piping. Use `--format table` for human-readable tables or `--format chart` for an ASCII bar chart of daily spend.
+Default output is JSON for piping. Use `--format table` for human-readable tables or `--format chart` for an ASCII bar chart of daily spend; both print text, with or without `--raw`.
 </objective>
 
 <execution_context>
@@ -33,7 +33,7 @@ pan-tools cost report [--format json|table|chart] [--since YYYY-MM-DD] [--until
 **Flags:**
 - `--format` — `json` (default, for tools) | `table` (aligned text columns) | `chart` (per-day ASCII bars).
 - `--since` — ISO date lower bound (inclusive). Records without `ts` always pass.
-- `--until` — ISO date upper bound (inclusive).
+- `--until` — ISO upper bound (inclusive): a bare date covers that whole day.
 
 **JSON output shape:**
 ```json
@@ -81,6 +81,10 @@ Delete the cost log. Useful at the start of a billing cycle.
 pan-tools cost clear
 ```
 
+### `limits`
+
+`pan-tools cost limits` shows Claude Code's 5-hour and 7-day usage windows as the status line last saw them, and whether the 7-day one has reached `cost.weekly_limit_stop_pct` (default 90%), where `/pan:focus-auto` and `/pan:army` stop. Interactive Claude Code sessions on a subscription only: headless runs and other runtimes have no reading.
+
 ### `rebuild`
 
 Rebuild the ledger from Claude Code's own transcripts (session file plus the per-agent files under `<session>/subagents/`, Workflow-tool subagents one level down). Rows written by hooks before v3.29 booked a slice of the parent session to whichever subagent stopped and counted turns once per content block; the rebuild replaces them with one exact row per agent transcript, typed from the main thread's `Agent` calls, plus one row per session for the main thread's own usage (`--no-main-thread` omits it). Rows whose session transcript is gone, and caller-appended rows, are kept. Dry-run by default — show the user the per-session before → after (and any `warnings`), then apply only on their say-so; the previous ledger is kept beside the new one as `tokens.jsonl.rebuilt-<date>` (a later copy never overwrites an earlier one). Run it **before** `/pan:hygiene --apply` on a poisoned ledger: quarantine moves the whole file aside, and a rebuild afterwards has no rows left to keep. The main-thread row is dated to the session's last record, so `--since`/`--until` windows and the per-day view see a session's own usage on its final day.
@@ -134,7 +138,7 @@ If `.planning/metrics/tokens.jsonl` is empty, `/pan:cost` returns zero totals
 | Runtime | Support |
 |---------|---------|
 | Claude Code | Full — data format + aggregation + all output formats |
-| OpenCode | Full aggregator; PAN registers no hooks on OpenCode, so records come from `pan-tools cost append` or an external script |
+| OpenCode | Full aggregator; PAN's only OpenCode hook is its plugin's compaction hook (`plugins/pan-wizard.js`), so cost records come from `pan-tools cost append` or an external script |
 | Gemini | Full aggregator; PAN registers no cost hook on Gemini CLI (no subagent-completion event), so records come from `pan-tools cost append` or an external script |
 | Codex | Full — `pan-cost-logger` registered on `SubagentStop` in `.codex/hooks.json` |
 | Copilot CLI | Full aggregator; `pan-cost-logger` registered on `subagentStop` in `.github/hooks/pan.json` (token counts depend on what the payload carries) |

package/commands/pan/debug.md

@@ -35,7 +35,7 @@ ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state load)
 ```
 
-Extract `commit_docs` from init JSON. Resolve debugger model:
+Extract `config.commit_docs` from the JSON (`state load` nests it under `config`). Resolve debugger model:
 ```bash
 DEBUGGER_MODEL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-debugger --raw)
 ```
@@ -125,7 +125,10 @@ Task(
 
 ## 4. Handle Agent Return
 
-**If `## ROOT CAUSE FOUND`:**
+**If `## DEBUG COMPLETE`** (the success return for `goal: find_and_fix`, after the user confirmed the fix at the `human-verify` checkpoint):
+- Display the root cause, the fix, its verification and the commit; the session file is now `.planning/debug/resolved/{slug}.md`
+
+**If `## ROOT CAUSE FOUND`** (returned only for `goal: find_root_cause_only`, which this command does not pass):
 - Display root cause and evidence summary
 - Offer options:
   - "Fix now" - spawn fix subagent
@@ -148,7 +151,7 @@ Task(
   - "Add more context" - gather more symptoms, spawn again
 
 <debug_handoff_schema>
-Debug session files (`.planning/debug/{slug}.md`) MUST contain structured state for cross-agent handoff:
+Debug session files (`.planning/debug/{slug}.md`) follow pan-debugger's own structure (agents/pan-debugger.md, "File Structure"): frontmatter `status: gathering | investigating | diagnosed | fixing | verifying | awaiting_human_verify | resolved`, then Current Focus, Symptoms, Reproduction, Eliminated, Evidence and Resolution. The YAML below names the facts a handoff needs; its field names and status values are not the file's:
 
 ```yaml
 # Required sections in debug session file
@@ -182,7 +185,7 @@ fix:                                 # Populated when applied
   tests_added: ["{test paths}"]
 ```
 
-**Why structured:** Each continuation agent starts with 0 context. Without structured state, it re-reads the entire investigation log and may re-test eliminated hypotheses. With structured state, it reads `hypotheses_tested` (skip these), checks `hypotheses_remaining` (do these next), and picks up exactly where the previous agent stopped.
+**Why structured:** Each continuation agent starts with 0 context. Without structured state, it re-reads the entire investigation log and may re-test eliminated hypotheses. With structured state, it skips the hypotheses under Eliminated, starts from Current Focus `next_action`, and picks up exactly where the previous agent stopped.
 </debug_handoff_schema>
 
 ## 5. Spawn Continuation Agent (After Checkpoint)
@@ -210,9 +213,9 @@ goal: find_and_fix
 </mode>
 
 <handoff_instructions>
-1. Parse the debug file's structured sections (symptoms, investigation, root_cause, fix)
-2. Do NOT re-test hypotheses marked "eliminated" — they are dead ends
-3. Start from hypotheses_remaining or the checkpoint's next action
+1. Parse the debug file's sections (frontmatter status, Current Focus, Symptoms, Reproduction, Eliminated, Evidence, Resolution — the format in templates/debug.md)
+2. Do NOT re-test hypotheses listed under Eliminated — they are dead ends
+3. Start from Current Focus `next_action` or the checkpoint's next action
 4. Update the debug file's structured sections as you progress
 </handoff_instructions>
 ```

package/commands/pan/design-phase.md

@@ -2,7 +2,7 @@
 name: pan:design-phase
 group: Phase Lifecycle
 description: Design a roadmap phase before planning — architecture, ADR, threat-lite, machine-checkable criteria — verified by an independent checker
-argument-hint: "[phase] [--spike] [--skip-design] [--redesign]"
+argument-hint: "<phase> [--spike] [--skip-design] [--redesign]"
 agent: pan-designer
 allowed-tools:
   - Read
@@ -57,7 +57,7 @@ ELSE (default):
    - If it PASSES → done.
    - If it finds gaps (iteration 1) → `pan-designer` revises (address genuine gaps only), re-check.
    - If it finds gaps (iteration 2) → final revision, record remaining gaps as caveats.
-   - **Max 2 revision iterations** (design → check → revise → check → final) — the same guardrail `plan-phase` uses with `pan-plan-checker`.
+   - **Max 2 revision iterations** (design → check → revise → check → final revision, not re-checked). `plan-phase` also caps its loop at 2 revisions, but checks a third time after the second.
    - **Record each check.** Save the checker's returned text verbatim to `{phase_dir}/{padded_phase}-design-check.md` with the Write tool. Record it and branch on the verdict it prints (`PASS` or `GAPS`):
      ```bash
      node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "{phase}" --agent pan-design-checker --file "{phase_dir}/{padded_phase}-design-check.md" --raw
@@ -81,5 +81,5 @@ Design FAILS if: phase not found in roadmap, or the designer returns empty/malfo
 </completion_contract>
 
 <handoff>
-`{phase}-design.md` is an **optional upstream input** to `/pan:plan-phase`, consumed by `pan-planner` exactly as `{phase}-context.md` is. `pan-plan-checker` verifies the plan conforms to it (Design Conformance dimension). A phase without a design.md still plans — the design step strengthens planning, it does not gate it.
+`{phase}-design.md` is an **optional upstream input** to `/pan:plan-phase`, consumed by `pan-planner` like `{phase}-context.md` — except that the plan-phase workflow does not list it in the planner's or checker's `<files_to_read>`, so both use it only when they find it in the phase directory. `pan-plan-checker` verifies the plan conforms to it (Design Conformance dimension). A phase without a design.md still plans — the design step strengthens planning, it does not gate it.
 </handoff>

package/commands/pan/discuss-phase.md

@@ -33,6 +33,8 @@ Extract implementation decisions that downstream agents need — researcher and
 <context>
 Phase number: $ARGUMENTS (required)
 
+**`--auto`** (or `workflow.auto_advance: true`): no questions — the workflow writes a minimal context.md from the roadmap goal, idea.md, project.md and requirements.md, then spawns plan-phase with `--auto`; the interactive steps below are skipped.
+
 Context files are resolved in-workflow using `init phase-op` and roadmap/state tool calls.
 </context>