pan-wizard 3.35.0 → 3.37.0

package/docs/FAQ.md

@@ -0,0 +1,254 @@
+<div align="center">
+<img src="../assets/pan-avatar.png" alt="PanWizard" width="90" />
+</div>
+
+# Frequently Asked Questions
+
+## General
+
+### What runtimes does PAN support?
+
+| Runtime | Command prefix | Config location | Status |
+|---------|---------------|-----------------|--------|
+| Claude Code | `/pan:*` | `~/.claude/` or `./.claude/` | Full support |
+| OpenCode | `/pan-*` | `~/.config/opencode/` or `./.opencode/` | Commands; no hooks (a plugin keeps the phase through compaction) |
+| Gemini CLI | `/pan:*` | `~/.gemini/` or `./.gemini/` | Commands; no context monitor, cost or trace capture |
+| Codex | `$pan-*` | `~/.codex/` or `./.codex/` | Skills-based |
+| Copilot CLI | `/pan-*` | `~/.copilot/` or `./.github/` | Skills-based |
+
+### How much does PAN cost?
+
+PAN itself is free and open source. Token costs depend on your Claude/model usage:
+
+| Profile | Model resolution | Best for |
+|---------|----------------------|----------|
+| `quality` | Every agent at the session model (reasoning tier); the full ceremony on every phase | Critical architecture work |
+| `balanced` (default) | The session model for every agent except the two researchers and the plan-checker, which run on the mid tier; the ceremony is sized (a precisely specified phase is planned and checked by the engine) | Normal development |
+| `budget` | The only profile that down-tiers: mid for the planning, orchestration and code-writing agents, fast for research, review, verification and utility agents | High-volume work, prototyping |
+
+Reduce costs further by disabling optional agents:
+```text
+/pan:settings
+```
+Research is off by default; toggle off `plan_check` or `verifier` for familiar domains.
+
+### How do I estimate token costs for a phase?
+
+Each phase goes through several agent stages. Approximate token usage per stage:
+
+| Stage | Agents spawned | Approximate tokens | Skippable? |
+|-------|---------------|-------------------|------------|
+| Research (new-project) | 1 project researcher, at most 5 questions | small, bounded | Off by default: runs only with `--research` (or `--research market`) or idea frontmatter `research_enabled: true` |
+| Research (plan-phase) | 1 phase researcher, at most 5 questions | small, bounded | Off by default: runs only with `--research` or `workflow.research: true` |
+| Planning | 1 planner + 1 plan-checker (2 checks on the sized ceremony, 3 under `quality`); a precisely specified small phase is planned and checked by the engine, with neither | 20-40K | Checker skippable (`plan_check: false`) |
+| Execution | 1 executor per plan (fresh context each) | 20-80K per plan | No |
+| Verification | 1 verifier | 10-20K | Yes (`verifier: false`) |
+
+**Profile multiplier:** the numbers above assume the default `balanced` profile, where the agents that plan, write and judge code are on the reasoning tier and inherit the model you launched with (a few review agents pin their own), while the researchers and the plan-checker run on the mid tier and the ceremony is sized. `quality` keeps every agent on the reasoning tier and runs the full ceremony on everything. `budget` is the only profile that down-tiers the rest: mid for the planning, orchestration and code-writing agents, fast for research, review, verification and the utility agents. On PAN's relative cost scale (`pan-tools estimate-cost`, reasoning = 15×, mid = 3×, fast = 1×) that puts `quality` at ~15× baseline, `balanced` a little under it, and `budget` at ~1.6×.
+
+**Optimization tips:**
+- Leave research off for familiar domains (it is off by default; `/pan:plan-phase N --research` turns it on for one phase)
+- Disable plan-checker for trusted plans: `workflow.plan_check: false`
+- Disable verifier for prototyping: `workflow.verifier: false`
+- Use `budget` profile for high-volume phases: `/pan:settings --profile budget`
+- Use `--prd <file>` to skip discuss-phase when you have specs ready
+
+### Can PAN search the web?
+
+Yes. PAN research agents can use Brave Search API for domain research. Setup:
+
+1. Get a free API key from the [Brave Search API](https://brave.com/search/api/)
+2. Set the `BRAVE_API_KEY` environment variable — the `websearch` verb reads only the env var. Optionally also create `~/.pan-wizard/brave_api_key`, which pre-sets `brave_search: true` in a config `config-ensure-section` creates (`/pan:new-project` does not set `brave_search`)
+3. Set `brave_search: true` with `pan-tools config-set brave_search true` (`/pan:settings` has no Brave question)
+
+When enabled, the phase researcher (`/pan:plan-phase`, `/pan:plan-phase --research-only`) uses Brave Search; it reads the setting from `init`. `/pan:new-project` and `/pan:milestone-new` do not pass the setting to their researchers, so those use the built-in web search.
+
+### Is my code sent anywhere?
+
+No. PAN runs entirely within your local Claude Code (or other runtime) session. It uses standard tool calls — no PAN servers, no telemetry, no data collection. Your code stays on your machine and in your Claude session. The only network calls PAN itself makes are the periodic update check, which runs `npm view pan-wizard version` against the npm registry and sends nothing about your project, `/pan:update` when you run it (it checks npm, fetches the changelog from GitHub and reinstalls from npm), `/pan:git push` and `/pan:git sync` when you run them, `/pan:army --push` after you approve a merge and the tag push `/pan:milestone-done` offers (all to your own git remote), and web research through the Brave Search API — only after you opt in with `brave_search: true` and a key, and then only the research queries. The MCP bridge PAN registers is a local stdio process; it opens no sockets.
+
+### How do I uninstall PAN?
+
+```bash
+# Global installs
+npx pan-wizard --claude --global --uninstall
+npx pan-wizard --opencode --global --uninstall
+npx pan-wizard --gemini --global --uninstall
+npx pan-wizard --codex --global --uninstall
+npx pan-wizard --copilot --global --uninstall
+
+# Local installs
+npx pan-wizard --claude --local --uninstall
+npx pan-wizard --opencode --local --uninstall
+npx pan-wizard --gemini --local --uninstall
+npx pan-wizard --codex --local --uninstall
+npx pan-wizard --copilot --local --uninstall
+```
+
+This removes all PAN commands, agents, hooks, and settings while preserving your other configurations.
+
+## Workflow
+
+### Can I use PAN with an existing project?
+
+Yes. Run `/pan:map-codebase` first — it maps your stack, architecture, conventions, and concerns (one agent for small repos, several in parallel above the size threshold). Then `/pan:new-project` will focus questions on what you're *adding* rather than what already exists.
+
+### Does PAN commit to git automatically?
+
+Yes. Each task gets its own atomic commit immediately after completion; consecutive trivial tasks of one type may share one (never `feat` or `fix`). Commit messages follow conventional format with phase numbers (e.g., `feat(03-02): add login endpoint`).
+
+`commit_docs: false` (plus gitignoring `.planning/`) stops only the planning-doc commits; the per-task code commits are always made.
+
+### What happens when context runs out?
+
+The host compacts the session on its own before the window fills, and PAN restores the planning position afterwards (on Claude Code, Codex, Gemini CLI, Copilot CLI and OpenCode). Before that, on Claude Code, PAN's context monitor tells the agent compaction is coming: it reads PAN's status line, or the session transcript where no status line runs (headless `claude -p`). Gemini CLI and OpenCode do not run the monitor, and on Codex, which gets no PAN status line and whose transcript has another shape than the Claude Code records the monitor reads, it stays silent. Under PAN's Copilot CLI registration it stays silent: Copilot's documented hook payload names the session `sessionId`, and the monitor reads only `session_id`. In a project that also has the Claude Code install, that copy steps aside for the Claude Code registration, and what Copilot passes that one has not been observed. It measures the room left before the host compacts, not before the window is full:
+- At **35% of that room left**: a note asking for a checkpoint in `.planning/state.md` at the next natural stopping point
+- At **25% left**: the same, before the next step
+
+The note carries no countdown and asks the agent to keep working at full quality: compaction is safe, because the state is restored afterwards. Between sessions, use `/pan:resume` to restore full context.
+
+### Can I skip steps in the workflow?
+
+Yes. The full workflow is `discuss → plan → execute → verify`, but:
+- Skip `discuss-phase` if you're fine with Claude's defaults
+- Skip `/pan:verify-phase` unless you want a re-check: `/pan:exec-phase` already runs the verifier (turn it off with `workflow.verifier: false`)
+- Use `/pan:quick` for one-off tasks that don't need full planning
+- Research is off by default; `/pan:plan-phase N --research` adds it for one phase, and `--skip-research` leaves it out when `workflow.research` is `true`
+
+### Why won't PAN mark my phase complete?
+
+The phase gate refused. `phase complete` checks the phase first (a summary for every plan, a passing and fresh verification, no open critical or high finding, among other checks), and `workflow.phase_gate` defaults to `enforce`, so a failed check stops the completion and lists each reason. `pan-tools phase gate <N>` runs the check alone. Fix the reasons, complete once anyway with `pan-tools phase complete <N> --force --reason "<why>"` (the override is recorded), or make the gate advisory with `pan-tools config-set workflow.phase_gate warn`. See [Phase gate refuses to complete a phase](TROUBLESHOOTING.md#phase-gate-refuses-to-complete-a-phase).
+
+### How do I fix a plan that doesn't match my vision?
+
+Run `/pan:discuss-phase [N]` before planning. Most misalignment comes from Claude making assumptions that your preferences (captured in context.md) would prevent.
+
+You can also run `/pan:assumptions [N]` to preview Claude's intended approach before committing to a plan.
+
+### Can I use PAN without `--dangerously-skip-permissions`?
+
+Yes. Add granular permissions to `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(date:*)", "Bash(echo:*)", "Bash(cat:*)", "Bash(ls:*)",
+      "Bash(mkdir:*)", "Bash(wc:*)", "Bash(head:*)", "Bash(tail:*)",
+      "Bash(sort:*)", "Bash(grep:*)", "Bash(tr:*)", "Bash(git add:*)",
+      "Bash(git commit:*)", "Bash(git status:*)", "Bash(git log:*)",
+      "Bash(git diff:*)", "Bash(git tag:*)"
+    ]
+  }
+}
+```
+
+Note: you'll be prompted to approve agent spawning and other operations, which can slow down automated workflows.
+
+## Spec B v2 and Later Features
+
+### How do I see what PAN is costing me?
+
+Run `/pan:cost report`. Since v3.4, on Claude Code, Codex and Copilot CLI (Gemini CLI has no subagent-completion event, and PAN registers no hooks on OpenCode), a SubagentStop hook auto-captures every sub-agent completion into `.planning/metrics/tokens.jsonl` — so `/pan:cost` works without any manual instrumentation. Use `--format table` for human-readable output, `--format chart` for a daily bar chart, or `--since YYYY-MM-DD --until YYYY-MM-DD` to scope to a billing window.
+
+Each phase also has a spend budget, `cost.phase_budget_usd` ($20 by default, in API-equivalent dollars): `/pan:exec-phase` notes in its wave report when a phase reaches 80% of it and again when it reaches the whole of it, and `/pan:plan-phase` ends with the spend so far and, once the ledger holds enough runs, a p10/p50/p90 forecast. It only warns and never stops a run. Change it with `/pan:settings` (`0` turns it off); `pan-tools cost budget --phase N` shows the figures.
+
+### What's the difference between `pan-reviewer` and `/pan:review-deep`?
+
+`pan-reviewer` runs by default during `/pan:exec-phase` (skip it with `--skip-review` or `--fast`) — it flags convention, security-pattern and code-quality issues on changed files. `/pan:review-deep` is opt-in (run standalone or with `--deep-review`) and adds two more agents: `pan-hardener` runs an OWASP Top 10 + STRIDE security audit, and `pan-meta-reviewer` cross-checks the reviewer + hardener output for missed issues or overstated severities. Costs roughly 3× a normal review; recommended for auth/payment/PII/migration phases.
+
+### When should I use `/pan:exec-phase --hierarchical`?
+
+Only when the phase has ≥4 autonomous plans that genuinely parallelize and the total work is large enough to amortize the ~20-30% orchestration overhead. `pan-conductor` spawns sub-agents in waves with a strict safety harness (2-level nesting cap, 12-spawn cap, budget ceiling, `.planning/orchestration/abort` kill-switch). Claude Code only — it needs native sub-agent spawning; the other four runtimes fall back to flat exec with a warning. There's no model gate, so switching models won't turn it on or off. For single-plan or checkpoint-heavy phases, skip the flag — flat exec is cheaper and more predictable.
+
+### What is `/pan:army` and how is it different from a normal phase?
+
+**It's the difference between building a feature and shipping a project.** `/pan:army` runs a whole-project goal as a coordinated bot army, where `/pan:exec-phase` runs one phase. `pan-conductor` becomes Mission Control — it plans and delegates rather than implementing — handing work to role-scoped squads: Architecture (design), Build (code, one `army/<task>` git worktree per agent so parallel builders never collide), Quality (adversarial review), and Release (`pan-release`, always-ask). Each cycle is plan → delegate → execute → review → integrate → learn, looping until the goal ships or a stop condition fires. Nothing reaches a protected branch without green checks and a human's approval; recovery is `git revert` / previous tag. It runs under the same safety harness as hierarchical exec. It is built for Claude Code, because the squads are spawned as native sub-agents; unlike `--hierarchical`, which warns and runs flat on the other runtimes, `/pan:army` has no runtime check or fallback, so use the flat phase commands there. That's a runtime limit, not a model one — Mission Control runs on whatever model you launched the session with. Inspect the roster with `pan-tools squad list`; start with `/pan:army "<goal>" --dry-run` to preview the plan and delegation before anything runs.
+
+### Can the army run on a schedule / unattended?
+
+Within a run, yes — it self-drives the loop. Across days, `/pan:army --schedule daily --daily-budget 200` arms a self-resuming campaign. PAN isn't a daemon, so it doesn't wake itself: it writes a schedule descriptor and you point an external trigger at it — a host scheduler (Claude Code routines / cron / scheduled tasks) or a `/loop` — which polls `pan-tools campaign due` and runs `/pan:army --continue` when due. Each day's spend is tracked against `--daily-budget` (advisory — `campaign due` reports `budget_exhausted_today` only when the schedule is armed with `pan-tools campaign schedule --enforce-budget`, which `/pan:army --schedule … --enforce-budget` does for you; `--advisory-budget` turns it back off. Otherwise only the `/pan:army --continue` prompt tells the conductor to stop once the day's spend is used up) and the campaign resumes the next day; `pan-tools campaign status` shows where it stands. Crucially, scheduling changes nothing about safety: the merge to a protected branch is still an `always-ask` human gate, so a scheduled campaign burns the backlog down to staged, reviewed, green PRs and waits for you at every merge.
+
+### Is `/pan:army` safe to let loose on my repo?
+
+It's bounded by design, but treat it like hierarchical exec with a longer leash. Be precise about which rails are which. **Tool-enforced:** squad agents cannot spawn further agents, because the Agent/`Task` tool is granted to the coordinator alone — `grep -l '^tools:.*Task' agents/*.md` shows who has it. **Instructed, not enforced:** Mission Control is told to delegate rather than implement, but its frontmatter grants `Write` and `Bash`, so nothing at the tool level stops it editing a file; the same goes for the per-squad `access` labels, which `squads.cjs` publishes as advisory metadata ("modifies no agent and changes no execution path"). **Harness rails the conductor re-checks before every spawn:** per-cycle spawn and budget ceilings, and the `.planning/orchestration/abort` kill-switch. **Human-gated:** the Release agent surfaces an `always-ask` request rather than merging — and branch protection on your repo is what turns that convention into something a bot cannot bypass. Parallel builders are isolated in separate git worktrees, and recovery is always revert / previous tag — never a force-push or history rewrite. Set protected-branch rules on your repo and configure `build` / `verification` in `.planning/config.json` so the release gate runs your real checks. Live multi-agent battle-testing on a real project is still recommended before relying on it unattended.
+
+### How do I watch what the army is doing?
+
+Run `/pan:hud` (or its old name `/pan:dashboard`) — it renders a single self-contained HTML page at `.planning/hud.html` and opens it with `/pan:hud --open`. The dashboard is a *view*, not a new source of truth: every panel aggregates state PAN already tracks. Army campaigns light up extra panels — a command stack (Mission Control over the four squads with per-squad token/call drill-down), the campaign cadence + daily-budget bar, the safety harness (merge gate, abort switch, active worktrees), and the live `army/*` worktree list — alongside the always-present roadmap, telemetry, requirements, and recent-commits panels. The army panels appear only when a campaign is scheduled or army worktrees exist; a plain project still gets a complete page. The file has no server, network, or external dependencies, so you can send `.planning/hud.html` to anyone. Re-run after each cycle for a fresh snapshot. (ADR-0035)
+
+### How do I ask PAN a question about my project?
+
+Run `/pan:knowledge ask "why does phase 4 have a race condition fix?"`. The command retrieves candidate files from `.planning/` + `docs/` + top-level docs, scores them by keyword frequency, and the `pan-knowledge` agent answers with inline citations. For multi-turn design discussions, use `/pan:knowledge discuss <phase> "topic"` — session state persists to `.planning/conversations/<phase>/session.json`.
+
+### Can I preview a phase before running it?
+
+Yes. `/pan:preview phase <N>` analyzes the phase's plan files, extracts mentioned file paths, checks for risk keywords (drop / delete / migrate / rename / breaking / auth), and scores the phase 1-10. For cross-phase planning, `/pan:preview phases` emits a mermaid dependency graph + parallelizable-batches recommendation. For milestone-level forecasting, `/pan:preview milestone` projects an ETA with a confidence percentage from historical phase durations.
+
+### Does PAN have an MCP server of its own?
+
+Yes. Every install registers PAN's **MCP bridge** where the runtime's config can be merged safely (a Claude `--global` install prints the `claude mcp add` command for you to run instead, and Codex always gets a printed TOML snippet), a zero-dependency stdio server under `pan-wizard-core/mcp/` that exposes the `pan-tools` engine to any MCP client as tools and read-only resources (`pan://…`). Registration is automatic and non-destructive — `.mcp.json` at the project root for Claude Code, the runtime's own config for Copilot, Gemini and OpenCode, a printed TOML snippet for Codex — and every tool takes an optional `cwd`, so a client that launches the server somewhere else (Agent Plugins hosts start it in the plugin root) still operates on your project. History-rewriting git verbs are refused in code, and the merge gate needs a human-supplied token an agent cannot produce. Details: the "MCP server registration" section of the [User Guide](USER-GUIDE.md) and the bridge section of [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## v3.5 Features
+
+### How does the circular optimization loop work?
+
+`/pan:learn` and `/pan:learn --optimize` form a self-improvement cycle. The `pan-trace-logger.js` SubagentStop hook (Claude Code, Codex and Copilot CLI — not Gemini CLI or OpenCode) auto-captures every sub-agent completion into `.planning/optimization/traces/<session>/trace.jsonl` with zero setup — it creates day-scoped sessions automatically. After a phase or campaign, run `/pan:learn` to invoke the `pan-optimizer` agent which clusters error/gap/redundancy patterns and produces a structured report at `.planning/optimization/reports/`. Run `/pan:learn --optimize apply` to record its suggestions in `.planning/optimization/suggestions.md`. Each names where it belongs: the project's instructions (`CLAUDE.md` or `AGENTS.md`, outside PAN's section), a test, or the code. Once a person puts it there, the next session's agents read it. PAN's workflows do not load agent memory into agents (ADR-0036, amended `2026-10-04`). `/pan:plan-phase`, `/pan:design-phase`, `/pan:exec-phase` and `/pan:verify-phase` also record each judge's verdict with `pan-tools findings record`, which logs `verdict_passed`, `verdict_failed` or `verdict_needs_human` (and `verdict_retry` after a failed attempt) to the trace, so the optimizer can track real quality signal — not just "tasks completed."
+
+### What does `/pan:focus-auto --category distill` do?
+
+The `distill` focus-auto category targets **AI-generated code bloat** via a 5-pass pipeline (deterministic-first, LLM-on-narrow-spans). Pass 1 deterministically catches phantom try/catch (a try around a call the matcher treats as non-throwing, such as `Number()` or `parseInt()`, flagged `review_required` because both throw on a Symbol or an object whose `toString` throws; a try around `JSON.parse` is load-bearing and is not flagged), unused imports, magic numbers, long functions, wide param lists. Pass 2 detects single-instance factory classes and deep nesting via AST-style analysis. Pass 3 finds repeated 5+ line blocks and unreferenced exports across files. Pass 4 spawns the `pan-distiller` agent with **only the flagged spans** (not full files) — it validates each pattern, refines the safety tier (`safe` / `review_required` / `risky`), and proposes a minimal diff. Pass 5 writes findings to `.planning/memory/distill-patterns.md` so the next session's `distill analyze` flags recurring patterns (its `regressed` list: findings already recorded in an earlier session; the file records detections, not fixes). A bloat budget (touched_LOC / essential_LOC, default 2.0×) flags a cycle for review when its ratio exceeds the threshold (`bloat_budget.over_budget` in `distill analyze`).
+
+### What does `/pan:git` give me that raw `git` doesn't?
+
+Phase-aware naming + safety guardrails. `/pan:git commit --type feat --message "..."` runs deleted-file detection and sensitive-file checks on the staged paths (`.env`, `.pem`, `.key`, credentials, secret, password, token by default; `commit.sensitive_patterns` replaces the list) before allowing the commit. `/pan:git branch create --phase 3` auto-names the branch `pan/phase-3`. `/pan:git push` validates the remote exists and requires explicit `--force` for force-push. `/pan:git rollback` lists `pan-rollback-*` snapshot tags and resets to one (with `--dry-run` preview); the tags come from `pan-tools rollback-snapshot <phase>`, which no workflow runs for you. Subcommands: commit, branch, push, status, log, stash, diff, rollback, tag, sync. Works on any git repo regardless of whether `.planning/` exists.
+
+## Customization
+
+### Can I customize agent behavior?
+
+Yes. Agent files are Markdown in `~/.claude/agents/` (global) or `.claude/agents/` (local). Edit them directly. Changes take effect on next agent spawn.
+
+After a PAN update, your local modifications may be overwritten. Use `/pan:patches` to restore them.
+
+### Can I add my own commands?
+
+Yes. Create a `.md` file in `.claude/commands/` (or `~/.claude/commands/` for a global install) following the existing pattern — not inside `commands/pan/`, which every PAN update deletes and rewrites without backing up files it did not install. The filename becomes the slash command. Commands should be thin orchestrators — read state via `pan-tools.cjs`, spawn agents for heavy work.
+
+### How do I change which model each agent uses?
+
+Switch profiles globally:
+```text
+/pan:settings --profile budget
+```
+
+Or override specific agents in `.planning/config.json`. The values are tiers, not model ids: `opus` (or `reasoning`) is the model you launched with, `sonnet`/`mid` and `haiku`/`fast` the provider's mid and fast models, and anything else falls back to `mid`:
+```json
+{
+  "model_profile": "balanced",
+  "model_overrides": {
+    "pan-executor": "opus",
+    "pan-planner": "haiku"
+  }
+}
+```
+
+## Troubleshooting
+
+### Commands not found after install
+
+1. Restart your runtime to reload commands
+2. Verify files exist in `~/.claude/commands/pan/` (global) or `.claude/commands/pan/` (local) — after a `--unified-skills` install, in `~/.claude/skills/pan-*/SKILL.md` (global) or `.claude/skills/pan-*/SKILL.md` (local) (commands are then `/pan-<name>`)
+3. For Codex, check `~/.agents/skills/pan-*/SKILL.md` (global) or `./.agents/skills/pan-*/SKILL.md` (local)
+4. Re-run `npx pan-wizard` to reinstall
+
+### Context degradation during long sessions
+
+Clear context between major commands: `/clear` in Claude Code. PAN is designed around fresh contexts — every subagent gets a clean context window. Use `/pan:resume` or `/pan:progress` to restore state after clearing.
+
+### Docker or containerized environments
+
+If Claude Code in the container reads its config from somewhere other than the installing user's `~/.claude`, set `CLAUDE_CONFIG_DIR` to that directory before installing (a global install writes absolute paths either way):
+```bash
+CLAUDE_CONFIG_DIR=/home/youruser/.claude npx pan-wizard --global
+```

package/docs/FIELD-HARVEST-2026-07.md

@@ -0,0 +1,88 @@
+# Field Harvest — d:\ drive sweep, 2026-07-09
+
+A systematic sweep of every project directory on the dev drive for harvestable training material from past PAN-driven work. Method: four parallel read-only scouts over 22 directories, consolidated against the pre-sweep library (32 topics / 66 patterns), curated through the manual promote gate (`learn promote`), linted strict (L-001..L-005, zero warnings).
+
+**Outcome (pass 1): 20 new patterns across 13 new universal topics + 1 internal addition.**
+**Outcome (pass 2, same day — deep-mine of the lending project audit rounds, follow-up 2): 7 more patterns across 2 new topics (`audit-convergence`, `fix-campaigns`) plus 2 additions to `adversarial-verification`. Library now 47 topics / 93 patterns.**
+
+This doc is repo-only (docs/ is not shipped); it records exact evidence paths — the shipped pattern files deliberately describe sources qualitatively so user machine paths don't leak into installs.
+
+## Directory verdicts
+
+| Directory | Verdict | Yield |
+|---|---|---|
+| `<lending-project>` | PAN (focus/orchestration model) | **Richest single source.** Mock/fake-code audit + round-2 fix plan → P-HON-001/002, P-ADV-001 |
+| `<platform-project>` (nested!) | PAN (full phase model) | v2.0 milestone audit → P-INT-001/002; dispatch postmortem → P-SSOT-001 |
+| `<compliance-project>` | PAN + army campaign v1.1 | mission-F NO-GO → P-MIG-001; concerns.md → P-XTT-001; deep reviews → P-SVC-001 |
+| `<spec-factory>` | PAN-adjacent spec factory | FACTORY_ROADMAP/EVAL-STANDARD/MCP-STANDARD/SOP → P-GLD-001, P-MCP-001, P-HON-003, P-RES-008 |
+| `d:\mph_factory` | Autonomous harness (non-PAN) | RULES.md R1–R7 → P-TI-001; frozen-artifact isolation → P-ISO-001 |
+| `d:\mph_factory_limits` | Autonomous harness (non-PAN) | RULES.md L1–L9 → P-FLK-002, P-WKC-001, P-ISO-001 |
+| `d:\montyhall_Door_One` | PAN (focus model) | cycle-close flaky finding → P-FLK-001 |
+| `d:\montyhall_learning_corpus` | Training-corpus build | manifest + exclusion audit → P-GLD-002 |
+| `d:\tmp\wt-worktree-smoke` | PAN (full campaign run) | campaign.md M6 post-mortem → P-SSOT-002 |
+| `<forecasting-project>` | PAN (phase model) | Verification-report corpus; P-1605 already harvested; no net-new |
+| `<external-tooling-repo>` | External (external monorepo) | Worktree-aware-tools design — recorded below, not promoted |
+| `<compliance-project>-worktrees` | Duplicate snapshot of the compliance project | none (dedupe) |
+| `d:\.planning` (drive root) | Stray codebase-map run, mixes two projects | junk — safe to delete |
+| `<forecasting-design-docs>`, `<business-docs>{, Archive}` | Design/business docs, not agent-workflow | none |
+| `<misc-project-a>`, `<misc-project-b>`, `d:\temp`, `d:\tools`, `d:\Base` | Empty / SQL dacpac / scratch / k8s CLIs / Fineract upstream | none |
+
+## Promoted patterns → exact evidence
+
+| Pattern | Topic | Evidence source |
+|---|---|---|
+| P-HON-001 fabrication on live paths | live-path-honesty | `<lending-project>\docs\specs\mock-fake-code-audit-2026-07-02.md` (H1, H2, M9, M12) |
+| P-HON-002 honest-empty + demo gating | live-path-honesty | same audit (H3: enabled-unless-literal-`'false'`); `<lending-project>\.planning\orchestration\round2-fix-plan.md:29` |
+| P-HON-003 scaffold ≠ deliverable | live-path-honesty | `<spec-factory>\SOP\procedures.md:75-84`; `eval\conformance_eval.py` (`code_unimplemented`) |
+| P-TI-001 no dumbing down tests | test-integrity | `d:\mph_factory\RULES.md` R1–R6 (user standing instruction at line 84) |
+| P-ADV-001 adversarial verify per finding | adversarial-verification | `mock-fake-code-audit-2026-07-02.md:4-7` (80→36; 34→23); `<lending-project>\.planning\orchestration\{army-campaign.json,round2-findings.json}` |
+| P-INT-001 intra-phase PASS ≠ integrated | integration-verification | `<platform-project>\.planning\v2.0-milestone-audit.md` (FR-114, FR-110, NFR-036) |
+| P-INT-002 regenerate derived artifacts | integration-verification | same audit, NFR-052 (stale traceability matrix) |
+| P-SSOT-001 one classification predicate | single-source-of-truth | `<platform-project>\.planning\debug\dispatch-transient-no-redelivery.md:96-145` |
+| P-SSOT-002 re-sync parallel truth copies | single-source-of-truth | `d:\tmp\wt-worktree-smoke\.planning\orchestration\campaign.md` (M6) |
+| P-MIG-001 no unattended destructive DDL | migration-safety | `<compliance-project>\.planning\orchestration\mission-F-decision.md:11-13,24` |
+| P-FLK-001 isolated re-run triage | flaky-triage | `d:\montyhall_Door_One\.planning\cycle-close\FLAKY-GCConcurrentMarkTests-2026-05-31.md` |
+| P-FLK-002 windowed stats + 2-of-3 | flaky-triage | `d:\mph_factory_limits\RULES.md` L3/L4 |
+| P-XTT-001 artifact over exit code | external-tool-truth | `<compliance-project>\.planning\codebase\concerns.md:75-78` (az acr build / cp1252) |
+| P-GLD-001 human-verified golden sets | golden-sets | `<spec-factory>\eval\EVAL-STANDARD.md:5-41`; `FACTORY_ROADMAP.md:32` |
+| P-GLD-002 execution-gated curation | golden-sets | `d:\montyhall_learning_corpus\{manifest.json,README.md,excluded.jsonl}` (6,332 gated / 4,204 excluded w/ reasons) |
+| P-ISO-001 frozen-artifact isolation | harness-isolation | `d:\mph_factory\README.md`; `d:\mph_factory_limits\RULES.md` L1 |
+| P-WKC-001 workaround catalog | workaround-catalog | `d:\mph_factory_limits\RULES.md` L9 (LIMFAC-009 5-day gap); `docs\env_overlay_catalog.md` |
+| P-SVC-001 authed-CRUD security spine | service-security | `<compliance-project>\.planning\reviews\04\deep-review.md:26-57`; `reviews\07-11-milestone\deep-review.md:29-34` |
+| P-MCP-001 MCP surface = injection channel | mcp-security | `<spec-factory>\FACTORY_ROADMAP.md:24-30`; `mcp\MCP-SECURITY-STANDARD.md` |
+| P-RES-008 retrieval-first over fine-tune (internal) | external-research | `<spec-factory>\FACTORY_ROADMAP.md:9-22` (BEAVER ~10.8%; Tencent 53.8 vs 44.2 EM) |
+
+## Candidates found but NOT promoted (with reasons)
+
+- **Merge-base diff for parallel branches** (the compliance project missions.md) — duplicate of shipped **P-350**.
+- **Plan-cheap/build-strong + worktree-per-agent + human-gated merge** (bot-army.md, round2-fix-plan.md) — duplicate of **P-330/P-340**.
+- **Telemetry capture/sanity** — duplicate of **P-360**.
+- **Produce-not-apply posture** (FACTORY.md) — corroborates existing army human-gate doctrine; no new rule content.
+- **Reality-Score triage** `RS=(UV+TC+RR)/JS` (`<lending-project>\.planning\focus\scan-2026-06-17-delta.md:63`) — promising prioritization heuristic but single-project, no outcome data yet. Revisit if a second project adopts it.
+- **Two-source observability agreement / oracle_disagreement** (`mph_factory_limits\RULES.md` L2/L7) — sound but niche; fold into flaky-triage later if it recurs.
+- **Worktree-aware agent tools** (`<external-tooling-repo>'s worktree-awareness design spec`) — a design spec, not a validated lesson. **Actionable elsewhere:** informs `worktree.cjs`/army — treat a worktree as a project *variant* (two-phase resolution, per-worktree state namespace). Candidate ADR input, not a learning.
+- **EP-ledger mechanism** (`montyhall_Door_One\.claude\memory\error_patterns.md`) — mechanism already exists as PAN's memory layer; contents are language-specific.
+- **PAN verify-report format refinements** (the forecasting project `08-verification.md`, Door_One cc25 verification) — already canonical in templates/workflows; diff for template polish someday, not a pattern.
+
+## Follow-ups — all implemented 2026-07-09 (same day)
+
+1. **`d:\.planning` stray** — backed up to session scratchpad; deletion outside the repo sandbox was blocked, so removal is a one-liner for the operator: `Remove-Item -Recurse -Force d:\.planning`. The general case is now automated: `hygiene scan` detects fragment `.planning/` dirs (artifacts present, no workflow spine).
+2. **Second-pass deep-mine — DONE.** Both code-quality audits and the full `round2-findings.json` were mined; 7 novel workflow patterns promoted (below).
+3. **the spec-factory project suspect telemetry — VERIFIED.** `isSuspectRecord` (v3.12.4) flags all 119/119 records (max cache_read 835M). Aggregates were already protected; the missing piece — cleaning up the poisoned file itself — is now `hygiene clean`'s `quarantine-ledger` fix (rename in place, never delete). Live test: `the lending project` ledger is 1,195/1,509 (79%) suspect.
+4. **the external tooling repo worktree-awareness — RECORDED** as ADR-0039 (worktree = project variant; two-phase resolution; per-variant state namespace). Design rule, binding on the first feature that keys mutable state off a project path.
+
+Additionally, follow-ups 1 and 3 generalized into the **hygiene system** (`hygiene.cjs`, `pan-tools hygiene scan|clean`, `/pan:hygiene`): version alignment across runtime installs, legacy uppercase filenames, .tmp orphans, memory-log bloat, poisoned ledgers, stale trace sessions, fragment planning dirs.
+
+## Pass 2 — promoted patterns → exact evidence
+
+| Pattern | Topic | Evidence source |
+|---|---|---|
+| P-ADV-002 anti-double-jeopardy git provenance | adversarial-verification | `<lending-project>\.planning\orchestration\round2-findings.json` (confirm clause at :169, refute at :267) |
+| P-ADV-003 reachable trigger + precedent severity + false-positive taxonomy | adversarial-verification | same register (:180, :316); `code-quality-audit-2026-07-02.md:4` (confirmation bar) |
+| P-AUD-001 convergence stopping rule + model escalation | audit-convergence | `code-quality-audit-round4-2026-07-02.md:9-10` (108/9-HIGH → 16/0-HIGH; fable-5→opus-4-8; fan-out tapered 152→39) |
+| P-AUD-002 lens rotation with prior-scope exclusion | audit-convergence | `code-quality-audit-2026-07-02.md:3,8`; `…round4…md:3` |
+| P-FIX-001 defect-class handover clustering | fix-campaigns | `code-quality-audit-2026-07-02.md:156` (8 clusters from 108 findings, "fix the class once") |
+| P-FIX-002 suggestedFix is untrusted | fix-campaigns | `code-quality-audit-round4-2026-07-02.md:63-67` (broken nginx guidance rejected; BLOCK on a bad fix) |
+| P-FIX-003 fix-regression lens (inert/half-wired/sibling) | fix-campaigns | `…round4…md:18` (inert "amount-honest" fix re-opened a MED on Live; 3 total fix-regressions) |
+
+Pass-2 non-promoted: fix-by-sibling-convergence (folded conceptually into `single-source-of-truth`), model-escalation-as-lever (folded into P-AUD-001).

package/docs/FIELD-REPORT-army-2026-06.md

@@ -0,0 +1,121 @@
+# Field Report — Production PAN Campaigns (2026-06)
+
+Optimizations for PAN itself, mined from real projects that ran PAN hard (not test fixtures): **three deep dives** plus a **fleet sweep of all six D: installs** (see the sweep section below). Read-only inspection of each project's `.planning/` artifacts, git history, and installed hooks — nothing in those projects was modified.
+
+| Project | How it used PAN | Key artifact |
+|---|---|---|
+| `<compliance-project>` | `/pan:army` campaign v1.1 — main-loop Mission Control, 5 missions landed | `orchestration/missions.md` |
+| `<lending-project>` | `/pan:focus-auto` backlog loop — ~40 batches over weeks | `metrics/tokens.jsonl` (1012 records) |
+| `<forecasting-project>` | phase-based exec + army design | `bot-army.md`, `metrics/tokens.jsonl` (106 records) |
+
+Project-specific numbers below are case-study **evidence**, not PAN's own counts (those live only in `CLAUDE.md`).
+
+---
+
+## 1. ⭐⭐ Cost telemetry is broken — absent in one mode, *corrupted* in the others
+
+This is the biggest finding, and it took all three projects to see it.
+
+**Absent (main-loop army).** the compliance project ran a full 5-mission campaign and produced **zero** `tokens.jsonl` / traces / bus events — even though the cost+trace hooks are installed, registered on `SubagentStop`, and **verified working in isolation** (a synthetic payload appends a correct record). `SubagentStop` only fires for Task-spawned subagents; a main-loop Mission Control's own work never triggers it, so the campaign ran blind.
+
+**Corrupted (where it *is* captured).** the lending project and the forecasting project *do* have `tokens.jsonl` — and the data is unusable:
+
+- the lending project: **7.9 trillion** cache-read tokens across 1012 records; **cache-hit pinned at 100%**; a *single* subagent record claims `input=16.8M, output=38.6M, cache_read=13.3 billion` (impossible for one agent); **933/1012 records inflated**, and the top records are **byte-identical** (same session `224ff330…`).
+- the forecasting project: same shape, milder (max single-record cache_read 376M; 76/106 inflated) — severity tracks session length.
+
+**Root cause** (`hooks/pan-cost-logger.js` + `pan-trace-logger.js`, `readUsageFromTranscript`): when the `SubagentStop` payload lacks `usage` (headless/Task spawns), the hook falls back to **summing `usage` across every assistant message in the transcript** filtered by `session_id`. Three compounding faults:
+1. **Subagents share the parent `session_id`**, so the filter never isolates one subagent — every `SubagentStop` sums the *entire, still-growing* transcript.
+2. **`cache_read_input_tokens` is cumulative per turn** (each turn re-reads the cached prefix), so summing across N turns multiplies the cached context by N → billions.
+3. The same cumulative total is then **written once per `SubagentStop` firing** → the ledger stores the transcript-sum many times over (hence the byte-identical rows).
+
+Net: `/pan:cost`, the HUD telemetry panels, and `/pan:learn --optimize` all consume garbage wherever capture "works," and get nothing where the army is main-loop driven. Cost-in-USD would be astronomically wrong (trillions of tokens × rate).
+
+**Fix in PAN:**
+- **Attribute per-subagent deltas, not whole-transcript sums.** Track a per-session high-water mark (last-processed message index / byte offset / ts) under `.planning/metrics/`; on each `SubagentStop` sum only messages appended since the previous firing.
+- **Prefer the payload's own `data.usage`** when present; use the transcript only for the final turn, never a cumulative sum.
+- **Don't sum `cache_read` across turns as independent** — record the last turn's figure (or per-turn deltas), and **sanity-cap**: a record whose `cache_read ≫ input` (the 100%-hit tell) is almost certainly miscounted — drop or flag it.
+- **Dedup** writes by `(session, last-message-ts)`.
+- **Capture actively too** (see the army case): the campaign Learn step should append a per-mission record so observability survives the main-loop pattern.
+
+→ Folded into **P-360** (campaign telemetry must be both *captured* and *trustworthy*).
+
+## 2. ⭐ Two-dot diff caused a false Quality block
+**Evidence (the compliance project, Mission D):** a Quality BLOCK was a false positive — the reviewer diffed `main..HEAD` (two-dot) *after* an earlier parallel mission merged and moved `main` past D's fork, so already-merged code showed as **phantom deletions**. The army diagnosed it itself and wrote a process note. A false block burns a cycle; the mirror case can wave a bad change through.
+**Fix:** reviewers/hardener/integration-checker and the `/pan:army` Quality + Release steps diff the **merge-base** (`<fork-sha>..HEAD` / three-dot `main...HEAD`), never two-dot; `worktree.cjs` stamps the fork sha at creation. → promoted as **P-350**.
+
+## 3. The campaign ledger has no canonical home — tooling is blind to it
+**Evidence:** three projects, three conventions: the compliance project `orchestration/missions.md` (live campaign log), the forecasting project `.planning/bot-army.md` (army design/governance doc), and PAN's own `campaign status` / HUD read `schedule.json` (absent in both). So the richest artifacts of each campaign are invisible to PAN's tools, and `campaign status` reports "no campaign" while a real one ran.
+**Fix:** define one canonical, machine-readable campaign-state file the army writes and `campaign status` + the HUD read. The hand-authored `missions.md` table is an excellent human view — standardize its schema and have tooling parse it (or emit a structured sibling), rather than inventing a third format.
+
+## 4. Velocity metrics never populated
+**Evidence (the compliance project):** `state.md → Performance Metrics` reads "Total plans completed: 0 · Average duration: —" despite 11 phases / 34 plans plus the campaign.
+**Fix:** record per-plan / per-mission duration + counts at completion (exec-phase + army Learn) so velocity, the HUD, and estimation feedback have data.
+
+## 5. Minor
+- **Bookkeeping commit overhead** — the compliance project adds a `chore(army): record Mission X landed` commit per mission (already batched C+D once); fold into the merge commit.
+- **`tier` null on hook records** — even valid cost records carry `tier:null`, so `/pan:cost` by-tier and the HUD tier view stay empty; resolve `tier` from the agent name in the hook.
+- **Stray test worktree** — the forecasting project has `D:/tmp/wt-worktree-smoke` lingering; worktree cleanup should sweep abandoned smoke/test trees.
+
+---
+
+## Fleet sweep — all six installs (2026-06-28)
+
+A read-only pass over every D: install that has PAN, to test whether the findings generalize. They do — and three new ones surfaced.
+
+| Project | How PAN is used | cost records | inflated | max 1-record cache-read | dup rows | `state.md` |
+|---|---|---|---|---|---|---|
+| the compliance project | army (main-loop) | **0** | — | — | — | ✓ phase |
+| the forecasting project | phase + army | 158 | 128 | 0.8 B | 15 | ✓ phase |
+| the lending project | focus-auto (36 batches) | 1012 | 956 | **13.3 B** | 76 | — |
+| montyhall_Door_One | custom loop (~10k inbox) | 379 | 305 | 9.2 B | 45 | — |
+| the spec-factory project | optimize-only | 119 | 119 | 0.8 B | 2 | — |
+| lugh | optimize-only | 19 | 9 | 1.2 B | 1 | — |
+
+**Confirmations:**
+- **The cost over-count is universal** — every install that captured telemetry (5/5) is inflated; severity scales with loop length (lugh's 19 records → the lending project' 1012 records / 13.3 B). Not a one-project fluke.
+- **The optimize/trace loop itself works** — `optimization/traces` has real content (the forecasting project 12, others 1–2). The corruption is specific to **cost** (`tokens.jsonl`), not traces. (Correction to an earlier assumption.)
+- **Campaign-ledger sprawl is worse than thought** — four filenames in the wild: `missions.md`, `mission-F-decision.md`, `campaign.md`, `bot-army.md` — none read by `campaign status`/HUD.
+
+**New findings:**
+
+### 6. ⭐ PAN's observability assumes the phase lifecycle, but most real usage isn't phase-shaped
+**4 of 6 installs have no `state.md` at all.** Real usage clusters into three modes, only one of which PAN's state/progress/HUD/velocity tooling understands:
+- **phase + army** (the compliance project, the forecasting project) — has `state.md`;
+- **focus-auto / backlog loop** (the lending project — 36 batches, weeks long) — no `state.md`;
+- **optimize-only** (the spec-factory project, lugh — only `metrics/` + `optimization/`) — no planning state at all.
+
+The `/pan:hud` I built, `state-snapshot`, `progress`, and velocity all key off `state.md` phase fields — so for **the majority of real projects they render near-empty or degrade**. 
+**Fix:** the HUD/progress layer should detect the active mode and reflect focus-auto batches / optimize sessions when there's no phase state — observability should follow how PAN is actually used, not assume phases.
+
+### 7. `bus.cjs` has zero adoption fleet-wide
+**0 of 6** installs have a single `bus/` channel. A shipped module + three commands (`bus publish|drain|list`) with no real-world use — and the HUD's activity feed (which could read it) will therefore always be empty.
+**Fix:** either wire the bus into army/focus coordination so it earns its place (and the HUD activity panel populates from real agent messages), or acknowledge that file-based coordination won and slim the surface.
+
+### 8. A ~10k-item autonomous loop was hand-built *on top of* PAN — mine it
+montyhall_Door_One runs a bespoke `/focus-loop` (user-local command) with a harness PAN doesn't provide: a durable **work-queue** (`inbox/` — **9,981 files**), **heartbeat** liveness, **cycle-close**, **parity** cross-checks, and **snapshots** (77). P-310 already harvested its parallel-research→serial-build shape; the **queue + heartbeat + snapshot + parity** infrastructure is unharvested and is the blueprint for making PAN's own `focus-auto`/army loops robust at the ~10k-item scale users actually push them to.
+**Fix:** evaluate folding a durable work-queue + heartbeat/liveness + cycle snapshots into `focus-auto` / the army loop, rather than every serious user re-inventing them.
+
+## What worked (validated — preserve)
+
+- **Risk-ascending mission ordering** with the risky migration deferred behind an explicit-go gate (the compliance project F).
+- **Adversarial Quality caught real bugs** before merge — a DoS/disposed-stream and an authorization leak (the compliance project A, E).
+- **Human-gated ship + rollback discipline** — per-mission rollback targets, always-ask merges, no force-push.
+- **Brownfield onboarding-first** — codebase maps built before any squad coded.
+- **Branch/worktree-per-task isolation** and clean squash-merge-per-mission history.
+- **`/pan:focus-auto` sustained a weeks-long backlog campaign** (the lending project, ~40 batches) — the loop scales over time.
+
+## Patterns promoted to the shipped store
+`pan-wizard-core/learnings/universal/autonomous-loop.md` — every future campaign inherits them:
+- **P-350** — review against the merge-base, never two-dot, when the base moves.
+- **P-360** — campaign telemetry must be both *captured* (active per-step record, not just the passive hook) and *trustworthy* (never naive-sum a shared-session transcript; cache-read is cumulative-per-turn).
+
+## Quick-win checklist
+- [ ] **Fix the cost-logger transcript over-count** (per-subagent delta + cache-read handling + dedup + sanity-cap) — `hooks/pan-cost-logger.js`, `pan-trace-logger.js`. *(universal — 5/5 installs affected)*
+- [ ] Merge-base review + fork-sha stamping (P-350) — reviewers, `/pan:army`, `worktree.cjs`.
+- [ ] Active per-mission telemetry + Phase-0 probe (P-360) — `/pan:army`.
+- [ ] **Mode-aware observability** — HUD/`progress`/velocity reflect focus-auto batches & optimize sessions when there's no `state.md` (4/6 installs). *(finding 6)*
+- [ ] Canonical campaign-state file read by `campaign status` + HUD (retire the `missions.md`/`campaign.md`/`bot-army.md` sprawl). *(finding 3/5)*
+- [ ] Decide `bus.cjs`'s fate — wire it into army/focus coordination (and the HUD activity feed) or slim it; zero adoption fleet-wide. *(finding 7)*
+- [ ] Evaluate folding a durable work-queue + heartbeat + cycle snapshots into `focus-auto`/army loops — the harness montyhall hand-built at ~10k-item scale. *(finding 8)*
+- [ ] Per-plan duration/counts → velocity (exec-phase + Learn).
+- [ ] (minor) fold bookkeeping commits · resolve `tier` on hook records · sweep stray worktrees.