pan-wizard 3.35.0 → 3.37.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,1054 @@
+# PAN Wizard — Architecture Guide
+
+A deep dive into how PAN Wizard is structured, how data flows between layers, and why key design decisions were made.
+
+**Other docs:** [Agents](AGENTS.md) · [Hooks](HOOKS.md) · [CLI Reference](CLI-REFERENCE.md) · [Development](DEVELOPMENT.md)
+
+---
+
+## Table of Contents
+
+- [System Overview](#system-overview)
+- [Layer 1: Commands](#layer-1-commands)
+- [Layer 2: Workflows](#layer-2-workflows)
+- [Layer 3: Agents](#layer-3-agents)
+- [Layer 4: Core Library](#layer-4-core-library)
+- [Layer 5: Persistent State](#layer-5-persistent-state)
+- [Additional Components](#additional-components)
+  - [References](#references)
+  - [Templates](#templates)
+  - [Hooks](#hooks)
+  - [Installer](#installer)
+- [Data Flow](#data-flow)
+- [Module Dependency Graph](#module-dependency-graph)
+- [Cross-Platform Runtime Support](#cross-platform-runtime-support)
+- [Key Design Decisions](#key-design-decisions)
+
+---
+
+## System Overview
+
+PAN Wizard is organized as a 5-layer architecture. Each layer has a single responsibility and communicates with adjacent layers through well-defined interfaces.
+
+```text
++-------------------------------------------------------------------+
+|                  USER (Claude Code / OpenCode / Gemini /           |
+|                        Codex / Copilot CLI)                        |
++-------------------------------------------------------------------+
+        |  /pan:command arg1 arg2
+        v
++-------------------------------------------------------------------+
+|  LAYER 1: COMMANDS          commands/pan/*.md                   |
+|  Thin orchestrators — parse args, read state, route to workflows  |
++-------------------------------------------------------------------+
+        |  references workflow
+        v
++-------------------------------------------------------------------+
+|  LAYER 2: WORKFLOWS    pan-wizard-core/workflows/*.md            |
+|  XML-structured multi-step procedures — the core logic layer      |
++-------------------------------------------------------------------+
+        |  spawns via Task tool              |  calls via bash
+        v                                   v
++---------------------------+   +-------------------------------+
+|  LAYER 3: AGENTS          |   |  LAYER 4: CORE LIBRARY        |
+|  agents/*.md              |   |  pan-wizard-core/bin/lib/*.cjs |
+|  Specialized AI roles,    |   |  Core CJS modules + CLI entry  |
+|  each in a fresh context  |   |  Zero external dependencies   |
++---------------------------+   +-------------------------------+
+        |                                   |
+        +----------------+------------------+
+                         |  reads / writes
+                         v
++-------------------------------------------------------------------+
+|  LAYER 5: PERSISTENT STATE              .planning/                |
+|  project.md, roadmap.md, state.md, config.json, phase dirs        |
++-------------------------------------------------------------------+
+```
+
+**Key principle:** Information flows downward through layers. Commands invoke workflows. Workflows spawn agents and call the core library. Agents and the core library read/write persistent state. No layer communicates upward except by returning results.
+
+### Model-capability integration
+
+PAN Wizard consumes these frontier-model capabilities across existing layers without changing the layer contracts. **There is no runtime capability gate.** PAN emits the capability unconditionally; whether it takes effect is decided by two things outside PAN's control — the **host runtime** (extended thinking directives are Claude-only; the installer rewrites or drops them for the other four) and the **model you launched the session with** (a 1M-context model can absorb a single-shot codebase map; a smaller-context one cannot). No module gates a *feature* on the model name — every workflow, mode selection, and routing decision runs the same code path whatever model you are on. (Some places do read a model name for non-gating reasons — the installer's advisory warning, described below; `cost.cjs`'s `resolveRate()`, which resolves a per-million-token price from the model ID recorded in the metrics log so `/pan:cost` can report spend; `hooks/pan-cost-logger.js`'s `tierForModel()`, which stamps a tier label onto every ledger row it writes; and the statusline hook, which displays the model's name. Those are reporting and display reads, not behavior — none of them change what PAN does. One read does steer routing: on an OpenCode install, `core.cjs`'s `opencodeConfiguredProvider()` takes the provider prefix of OpenCode's configured `model` so `resolve-model` names that provider's models; it picks ids, never whether a feature runs. Another sizes a measurement: `hooks/pan-context-monitor.js` uses the model id to find where the host compacts (a per-model `autoCompactWindow` setting) and, without a fresh status-line bridge, the context window itself (`modelWindowFor()` on the newest transcript record). That sets when its note fires, and for an id it cannot place it says nothing rather than guess. To find the current set rather than trust this list: `grep -rn "model" --include=*.cjs --include=*.js bin/ pan-wizard-core/bin/lib/ hooks/ | grep -iv comment`.)
+
+- **Prompt caching (Layer 4/3 boundary):** the host caches each agent's prompt prefix by itself, and nothing PAN runs can mark another agent's prompt for caching. What PAN controls is how much every agent re-reads. `buildCachedContext(cwd)` names the stable `.planning/` set, and `context-budget` and hygiene's `cache-context` check measure it against thresholds (ADR-0044). Phase agents read a phase's `roadmap slice` rather than the whole roadmap and requirements. `pan-tools cache prime` reports the set and a stable sha but primes nothing (ADR-0023, amended).
+- **Reasoning effort (Layer 3):** agents carry `effort:` frontmatter (`low`–`xhigh`; the adaptive-thinking-era replacement for the retired `thinking_budget`). Claude Code consumes it natively; the installer maps it to Codex's native `model_reasoning_effort`, and for OpenCode, Gemini and Copilot strips it and injects an effort-scaled prose preamble. Profiles modulate the base via `resolveEffortInternal()`.
+- **Whole-project ingest (Layer 1/3):** `/pan:map-codebase` Stage 0 calls `pan-tools codebase estimate-size`; repos ≤700K tokens go single-shot, else sharded across parallel mappers. The mode is chosen from repo size alone — there is no model check in `codebase.cjs` — so the single-shot path assumes a model with a 1M-context window; lower `--threshold` (or take the sharded path) on smaller-context models. The `pan-document_code` agent has a `<mode>` block so it knows which shape it was spawned with.
+- **Cross-phase memory (Layer 5):** `.planning/memory/<agent>.md` stores append-only per-agent lessons, recorded by hand (`memory append`, the gated `memory record`) or by `/pan:retro --write-memory`. **PAN's workflows do not load it into agents** (ADR-0036, amended `2026-10-04`). The harness found that a recorded lesson changed no phase's work beyond what `state.md`, the summaries and the code already carried. What carries knowledge between phases is that state discipline, and the project's own instructions for anything durable. `/pan:knowledge` reads the store for a person.
+- **Capability-aware routing (Layer 4):** `resolveModelInternal(cwd, agent, {context_estimate, needs_thinking, cache_warm})` (through `adjustTierForCapabilities()` in `core.cjs`) adjusts tier upward for large context or thinking-heavy work, downward for warm cache + small context.
+
+Memory and caching are file-based, so they work on all 5 runtimes. Extended thinking is Claude-only. (The flat `.claude/skills/pan-*.md` shims earlier installs wrote were retired on `2026-09-23`: Claude Code loads skills only as `skills/<name>/SKILL.md` directories, and the `/pan:<name>` commands already reach the model the way skills do.)
+
+**The model-name read that users actually see** is the installer's, and it only prints advice. `detectModelCapabilities()` in `bin/install-lib.cjs` is a hand-maintained substring table over literal model-ID fragments (`opus-5`, `sonnet-4-6`, `gpt-5`, `gemini-3`, … — read the function for the current set rather than trusting this sample); `install.js` calls it once, post-install, against the `model` field in `settings.json`, and prints a note if that model is known to lack 1M context or extended thinking. That warning is the table's only consumer — it gates no feature and blocks nothing. `--skip-warnings` suppresses it.
+
+Because it is a name table and not a live probe, it is written to lean forward-compatible. Generations the table knows map exactly. The forward threshold per family is the **last reduced-capability release the table records** for it — not the newest release it lists: any Claude ID whose parsed release number is strictly newer than that boundary inherits its family's modern profile instead of reading as capability-less. Major and point are compared as a pair (so a two-digit point release sorts above a one-digit one), which is what makes a *later point release inside an already-tabled major* forward-compatible too, not just a new major — neither draws a false "lacks 1M context" note. An ID resolves either by matching an explicit branch in the table or — for Claude names — by carrying a family plus a readable release number strictly newer than that family's last reduced-capability release; anything that resolves neither way reads as `tier: 'unknown'` with every capability flag false. Note that "its family's modern profile" means the newest profile the table records for that family, not the top-tier one: a newer Haiku inherits the newest Haiku profile (1M context and thinking, at the fast tier), never Opus's. It stays a best-effort advisory heuristic — a genuinely new family can still read as unknown and trigger the note until a branch is added.
+
+### Spec B v2
+
+Spec B v2 shipped a wave of new core modules (bus, cost, preview, review-deep, knowledge, whatif) and user-facing commands (cost, preview, review-deep, knowledge, what-if). None touch the focus system (`/pan:focus-*`); they interoperate via read boundaries + optional flags. See ADR-0024.
+
+- **`bus.cjs` (Y-7 infrastructure):** file-backed message channels at `.planning/bus/<channel>.jsonl` for agent-to-agent coordination. Consumed by `review-deep.cjs` (audit trail) and `pan-conductor` (orchestrator trace). Three drain modes: peek / consume / archive.
+- **`cost.cjs` (Y-6):** per-call cost aggregation. Reads `.planning/metrics/tokens.jsonl` (append-only log), outputs JSON/table/chart. Auto-populated from v3.4 by the `pan-cost-logger` SubagentStop hook.
+- **`preview.cjs` (Y-1):** foresight data layer. Three modes — `buildPhasePreview` (blast radius), `buildPhaseDependencyGraph` (mermaid DAG + parallel batches), `buildMilestoneETA` (velocity + confidence + bottleneck).
+- **`review-deep.cjs` (Y-2):** merges outputs from `pan-reviewer` + `pan-hardener` + `pan-meta-reviewer` into one verdict ladder (ok / ok_with_minor / fix_before_merge / review_required / block). Publishes audit to the `review-handoff` bus channel.
+- **`knowledge.cjs` (Y-3):** three modes — `ask` (retrieval-grounded Q&A), `discuss` (multi-turn sessions at `.planning/conversations/<phase>/`), `playbook` (clusters agent memory into categorized lessons at `.planning/playbook.md`).
+- **`whatif.cjs` (Y-4):** git worktree lifecycle for counterfactual phase replay. Agent explores in isolated worktree, command writes `.planning/counterfactuals/<phase>-<slug>.md` in main tree, cleans up worktree.
+
+Hierarchical orchestration: `pan-conductor` spawns executor/reviewer/verifier sub-agents for `/pan:exec-phase <N> --hierarchical`, bounded by a 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; on the other four runtimes the flag is a no-op that warns and falls back to flat exec.
+
+Automatic cost instrumentation: `hooks/pan-cost-logger.js` fires on Claude Code's `SubagentStop` event, appends to `.planning/metrics/tokens.jsonl`, flows into `/pan:cost` without caller instrumentation.
+
+### Bot-army model (ADR-0032/0033/0034/0035)
+
+PAN's agents run as a coordinated army when `/pan:army` drives a whole-project goal. The tiers reuse existing primitives — nothing here relaxes the `pan-conductor` safety harness:
+
+- **Tier 0 — Mission Control:** the reasoning-tier `pan-conductor`, elevated to campaign scope. It plans the goal and delegates to squads rather than implementing; that split is a prompt-level convention, not a tool restriction — `agents/pan-conductor.md` grants `Read, Write, Bash, Glob, Grep, Task`, and nothing narrows the grant at runtime. It declares no `model:`, so it runs on the session's model. Inherits every harness cap (nesting depth 2, spawn/budget ceiling, abort kill-switch).
+- **Tier 1 — Squads (`squads.cjs`):** role-scoped groupings of existing agents — Architecture (design), Build (code), Quality (adversarial review), Release (`pan-release`, human-gated) — each carrying an intended `access` contract the conductor is told to honour when delegating. Those `access` values are advisory metadata: the module's own header says it "modifies no agent and changes no execution path", so the enforced grant remains each agent's `tools:` frontmatter. A drift test pins squad roster ⇄ agent files ⇄ `AGENT_BASE_EFFORT`.
+- **Build isolation (`worktree.cjs`):** each Build agent gets its own `army/<task>` branch + git worktree, so parallel builders never share a tree or file. Generalized from `whatif.cjs`.
+- **Human-gated ship:** `pan-release` prepares a squash-merge and surfaces an `always-ask` approval; a human merges to the protected branch. Recovery is `git revert` / previous tag — never force-push.
+- **Learn step (= "Dreaming"):** `/pan:retro` (and `/pan:learn` when traces exist) report the recurring patterns, and Mission Control carries them into the next mission's plan. A pattern that should outlast the campaign goes to the human at the merge gate as a proposed line for the project's instructions; agent memory is not loaded into agents.
+- **Scheduled campaigns (`campaign.cjs`, ADR-0034):** `/pan:army --schedule <cadence>` arms a self-resuming campaign with a per-day budget. PAN owns the schedule descriptor + due-check; an external trigger (host scheduler / `/loop`; a session-open nudge is documented in ADR-0034 but not built) fires `/pan:army --continue` when due. It is not a daemon and never lowers the human merge gate — autonomy runs up to the merge, a human at the merge.
+- **Observability HUD (`hud.cjs`, ADR-0035):** `/pan:hud` renders a single self-contained `.planning/hud.html` aggregating mission, roadmap, command stack (Mission Control → squads → agents), campaign schedule, safety harness, active worktrees, telemetry, and requirements/quality. A read-only **view** — it owns no state and writes only its own file, so it can never corrupt planning data. Army-only panels appear only when a campaign is scheduled or army worktrees exist.
+
+### Optimization, git and distill additions
+
+New core modules, commands, agents, hooks, and workflows layered on the existing architecture without breaking changes:
+
+- **Circular optimization loop:** `optimize.cjs` + `pan-optimizer` agent + `/pan:learn` + `/pan:learn --optimize` commands. The trace → learn → apply cycle turns a session's recurring failures into ranked suggestions, each naming where a person should make the fix (the project's instructions, a test, an agent prompt); `optimize apply` records them and changes nothing an agent reads. Powered by the `pan-trace-logger.js` SubagentStop hook, which auto-creates day-scoped trace sessions with zero setup.
+- **`/pan:git` family:** `git.cjs` gives phase-aware git subcommands (commit/branch/push/status/log/stash/diff/rollback/tag/sync) with the same safety checks as `pan-tools commit` (deleted-file detection, sensitive-file blocking via `runCommitSafetyChecks`), except that a blocked `git commit` leaves what it staged in the index, where `pan-tools commit` unstages its own additions. Branch naming follows `pan/phase-N` convention.
+- **Distill optimizer:** `distill.cjs` + `pan-distiller` agent + `distill` focus-auto category implement the SOTA agentic-refactoring pipeline (deterministic-first, LLM-on-narrow-spans, cross-session pattern memory). 5 passes: deterministic static analysis → AST-style → cross-file graph → LLM judgment on flagged spans only → cross-session memory at `.planning/memory/distill-patterns.md`. Bloat budget gate (touched_LOC / essential_LOC, default 2.0x threshold).
+- **Circular loop blind-spot fixes (W1+W2+W3):** exec-phase records the reviewer's verdict with `pan-tools findings record`, which logs `verdict_failed` on NEEDS_FIXES (counted as a reviewer correction); a `load_phase_memory` step injected `.planning/memory/*.md` rules into executor context before Wave 1 (retired `2026-10-04` with the rest of the agent-memory injection, ADR-0036 amended); `logTraceEvent` auto-inherits phase number from session metadata.
+
+### Self-Improvement Loop additions
+
+A cross-project meta-learning loop. PAN drives autonomous external builds against fresh ideas in isolated folders, harvests the resulting telemetry back to source, and promotes generalizable findings into shipped artifacts that future installs read automatically. Closes the deferred MEMORY note "Cross-Session Learning (PATTERNS.md auto-capture)".
+
+**Core modules backing the loop:**
+- `pan-wizard-core/bin/lib/experiment.cjs` — scaffolds isolated experiment folders at `~/pan-experiments/<slug>/` with `.planning/idea.md` + manifest. Refuses to scaffold inside source repo (mirrors installer guard). Exports `harvestExperiment` (copy telemetry back to `<source>/experiments/<slug>/`) and `pruneExperiment` (soft-rename or hard-delete). Now also runs `initExperimentGit()` to inherit `user.email`/`user.name` from PAN source so autonomous-loop commits don't silently fail (P-EXP-001 fix).
+- `pan-wizard-core/bin/lib/runner.cjs` — spawns external AI runtime via `spawnSync` (sync with native timeout). `RUNTIME_RUNNERS` adapter map: claude/codex/gemini/opencode supported; copilot is `null` (no adapter yet, although `copilot -p` runs headless; the PAN Harness drives it that way). DEFAULT_TIMEOUT_MS bumped to 60 min after typical 3-plan phases timed out at 30 min.
+- `pan-wizard-core/bin/lib/learn-lint.cjs` — `pan-tools learn lint` integrity checks for the patterns store. Catches L-001 duplicate IDs across files, L-002 dangling pattern cross-references, L-003 empty `source_experiments` while body cites a known experiment, L-004 universal-scope rule prose using PAN-internal terms, L-005 revision marker without `superseded_by` frontmatter on the base, L-006 universal-scope pattern citing an internal pattern id, L-007 a pattern whose `cites` no longer holds (the cited file or symbol is gone). Wired into `/check`. Exits non-zero on errors.
+- `pan-wizard-core/bin/lib/learn-index.cjs` — `pan-tools learn build-index` generates `pan-wizard-core/learnings/index.json` with topic→agent-relevance map, byte/token-est sizes. `pan-tools learn topics-for --agent <role> [--token-budget N]` returns the budget-aware selected subset. Workflow files (`plan-phase.md`, `exec-phase.md`, `verify-phase.md`, `execute-plan.md`) now call `topics-for` instead of skim-the-folder, addressing the P-RES-002 distractor-density anti-pattern PAN was previously shipping.
+
+**One new agent:** `pan-experiment-runner` — observation-only watchdog. Tools restricted to `[Read, Bash, Glob, Grep]`. Cannot edit experiment files; reports back to the orchestrating user.
+
+**One new command:** `commands/pan/experiment.md` with subcommands new/list/manifest/run/status/stop/harvest/prune.
+
+**One new template:** `pan-wizard-core/templates/idea.md` — structured idea-doc shape consumed by `experiment new`.
+
+**Two-tier learnings layout** (new top-level dir under `pan-wizard-core/`):
+- `learnings/universal/` — AI-derived patterns shipped to all 5 runtime installs alongside `references/`
+- `learnings/internal/` — PAN-development-specific patterns; **source-only** (installer strips this)
+
+The two-tier split prevents PAN-internal patterns ("always commit individually because of source repo's hooks") from leaking to user installs as universal advice. Negative test in `tests/scenarios/learnings-installed.test.cjs` enforces the split.
+
+**Extended `optimize.cjs`:** `promotePattern` / `listPromotedPatterns` / `unpromotePattern` write findings into topic files under `learnings/{universal,internal}/`. Topic files use markdown with structured frontmatter (zero-deps minimal parser; not standard YAML).
+
+**Workflow cross-references:** the long workflows now reference `learnings/universal/` after `references/guardrails.md`. They load only the topics `learn topics-for --cue` picks for the task; a new topic file joins that choice once `pan-tools learn build-index` has indexed it.
+
+**Manual promote gate:** `pan-tools learn promote --pattern <id> --scope <s> --topic <t> --summary ... --rule ...` requires explicit human input. There is no auto-promote: every promotion goes through this gate.
+
+The `references/<topic>.md` + workflow-cross-reference pattern (proven with `guardrails.md`) is now joined by `learnings/<scope>/<topic>.md` for the AI-derived counterpart. Together they form a complete behavioral surface: human-authored canonical rules (`references/`) + AI-derived advisory patterns (`learnings/universal/`).
+
+### Evidence loop (ADR-0049)
+
+PAN's judges emit their verdict in a machine-readable form, the verbs record it, and the workflows branch on the record:
+- **The verdict.** The plan checker, reviewer and design checker end their report with a `pan-verdict` block. The verifier's verdict is its verification.md frontmatter.
+- **The record.** `pan-tools findings record` writes the verdict and its findings to `.planning/findings.jsonl` and logs it to the trace. It works on every runtime, because it is a verb rather than a hook.
+- **Dispositions.** Findings the phase continues past get one, with a reason. `findings debt` gives the milestone audit its tech debt.
+- **Learned suppressions.** A finding dismissed with a reason is filtered when the same judge raises it again, for as long as its file is unchanged; once the file changes it comes back open. Security and logic findings, and findings with no file, are never suppressed. `findings suppressions` lists what is being filtered.
+- **Tool failures.** On Claude Code the trace hook also records the failed tool calls inside each subagent's own transcript, redacted.
+
+`optimize learn` ranks tool failures by the spawns they recur in and counts each judge's failures and retries, and `optimize revert` undoes an apply exactly.
+
+### Reasoning-trace handoff (P-RES-003)
+
+The serial pipeline (planner → researcher → executor → verifier) hands work file-mediated. Plan and summary artifacts traditionally carried only OUTPUTS, not the reasoning that produced them. Per Cognition (June 2025) "Don't build multi-agents", silent decisions in upstream artifacts force downstream agents to reconcile contradictions blindly. PAN now passes the reasoning trace explicitly:
+
+- **`pan-wizard-core/references/handoff-decisions.md`** — schema for `## Plan Decisions` (in plan.md) and `## Implementation Decisions` (in summary.md). Plan Decisions buckets: Locked / Open / Considered+rejected; Implementation Decisions buckets: Taken / Deviations / Open questions.
+- **`agents/pan-planner.md`** — emits `## Plan Decisions` between objective and tasks.
+- **`agents/pan-executor.md`** — reads Plan Decisions before coding, writes Implementation Decisions when deviating from the plan.
+- **`agents/pan-verifier.md`** — Step 1b consumes the reasoning trace; Step 1c reads `.planning/codebase/conventions.md` per P-RES-005 (repo-norm violation detection).
+- **`agents/pan-plan-checker.md`** — Dimension 11 (Spec Sufficiency for Handoff, P-RES-004) + Dimension 12 (Decision Trace Completeness, P-RES-003) verify that plans carry enough decision context for downstream agents.
+- **Summary templates** (`templates/summary-{minimal,standard,complex}.md`) — all three variants carry the Implementation Decisions section.
+
+### Production-readiness gates
+
+- **`verifyInstall()`** (in `bin/install-lib.cjs`, called post-install by `bin/install.js`) — post-install manifest walk checks every entry in `pan-file-manifest.json` exists on disk and is non-empty; missing or 0-byte files fail with exit 1. **`verifyHookEntrypoints()`** then checks that every hook command about to be registered runs a script that exists and has content; a miss (a source checkout without `npm run build:hooks`) fails with exit 1 before any runtime config is written, so no dead hook is registered. `INSTALL_WARNINGS` collector hardens `copyWithPathReplacement` (mkdir failures hard-throw; per-file failures collected as warnings rather than silently swallowed).
+- **`scripts/release-check.js`** — multi-gate pre-publish validation (build:hooks → test:all → npm audit → doc-lint counts → links validate → npm pack + zero-dependency check → smoke install → distribution bundles → coverage gate). Wired to `package.json prepublishOnly` so `npm publish` cannot ship a broken release.
+- **`pan-tools commit --fail-on-error`** — routes a git refusal through `error()` (bare message on stderr) rather than a `commit_failed` JSON body (closes P-EXP-001 silent-failure surface where missing git identity in fresh experiment folders looked successful). Since `output()` derives the exit code from the payload, `commit_failed` exits non-zero with or without the flag — see CLI-REFERENCE "Error Shape".
+
+### Behavioral Guardrails Layer
+
+A consolidated AI-behavior rules surface, adopted from Google `agents-cli` patterns. Additive only; zero breaking changes.
+
+- **`references/guardrails.md`** — single grep-friendly file naming the top anti-patterns (silent model swaps, skipping verification, scope creep, manual focus picks, lagging docs), the **Code Preservation Principle** (surgical edits — preserve config values, comments, formatting outside the user's explicit target), and the **Stop-the-Line Rule** (regressions halt feature work).
+- **`## Re-Read Checkpoints`** sections in long workflows (`exec-phase`, `plan-phase`, `verify-phase`, `execute-plan`) — explicit boundaries where the agent is directed to re-read specific sections, preventing context-compaction drift across long autonomous sessions.
+- **Phase 0 Clarify gates** — MANDATORY in `new-project.md` (problem/success/scope/constraints check before scaffolding), recommended in `plan-phase.md` (phase-scope check). `--auto` mode short-circuits when a PRD is provided.
+- **Agent cross-references** — `pan-reviewer` flags Code Preservation violations at high severity; `pan-planner` enforces guardrails in generated `<deviation_rules>` blocks.
+
+The `references/` directory's role is now both **structural** (existing patterns: tdd, verification, checkpoints, model-profiles, etc.) and **behavioral** (guardrails). The `references/<topic>.md` + workflow-cross-reference pattern is the established way to add behavioral layers without bloating workflow files.
+
+---
+
+## Layer 1: Commands
+
+**Location:** `commands/pan/*.md`
+
+Commands are Markdown files that become slash commands in the user's runtime, invoked as `/pan:filename` (Claude Code, Gemini), `/pan-filename` (OpenCode, Copilot CLI), or `$pan-filename` (Codex).
+
+Commands are thin orchestrators that:
+
+- Parse user-provided arguments
+- Read current state from `.planning/`
+- Reference the appropriate workflow
+- Route results back to the user
+
+Most commands do no heavy work directly: their substantive logic lives in workflows (Layer 2) or the core library (Layer 4). The self-contained commands below are the exception: they carry their own orchestration in the command file.
+
+### Command Categories
+
+| Category | Commands |
+|----------|----------|
+| **Getting Started** | new-project, map-codebase |
+| **Phase Lifecycle** | discuss-phase, design-phase, plan-phase (`--research-only`), exec-phase, verify-phase |
+| **Phase Management** | add-phase, insert-phase, remove-phase, assumptions, phase-tests, phase-budget |
+| **Session & Progress** | progress, quick, pause, resume |
+| **Milestone** | milestone-new, milestone-done (`--cleanup`), milestone-audit (`--gaps`) |
+| **Focus** | focus-auto (`--step scan\|plan\|exec\|drift`), focus-docs (`--sync`), focus-design |
+| **System** | help, health, settings (`--profile`), update, debug, todo-add, todo-check |
+| **Deployment** | retro |
+| **Community** | patches |
+| **Spec B v2** | cost, preview, review-deep, knowledge, what-if |
+| **Optimization & Git** | learn (`--optimize`), git |
+| **Self-Improvement Loop** | experiment |
+| **Bot Army & Observability** | army, hud, report, hygiene, links |
+
+### Command-Only Files (No Workflow)
+
+These commands are self-contained in their `.md` file and do not delegate to a separate workflow; so are `army`, `autodev`, `cost`, `experiment`, `git`, `hud`, `hygiene`, `knowledge`, `links`, `preview`, `report`, `review-deep` and `what-if`, none of which references a workflow file (`autodev` runs `pan-tools autodev`, whose lean execute unit reads `exec-lean.md` in its own session):
+
+| Command | Reason |
+|---------|--------|
+| `phase-budget.md` | Calls `pan-tools.cjs context-budget` directly; no multi-step workflow |
+| `patches.md` | User-guided manual process; no automated workflow |
+| `debug.md` | Self-contained debug orchestrator; spawns pan-debugger directly |
+| `design-phase.md` | Self-contained design orchestrator; spawns pan-designer and pan-design-checker directly (max 2 revision iterations) |
+| `milestone-done.md` | Self-contained milestone close-out (archive, tag, offer `/pan:milestone-new`); only `--cleanup` loads a workflow (`milestone-cleanup.md`) |
+| `focus-auto.md` | Self-contained auto-runner; calls `pan-tools focus auto` for state management. `--step` loads one stage workflow instead (see the mapping below) |
+| `focus-design.md` | Self-contained multi-phase feature investigation pipeline |
+
+---
+
+## Layer 2: Workflows
+
+**Location:** `pan-wizard-core/workflows/*.md`
+
+Workflows are Markdown files with XML-structured multi-step procedures. Each workflow defines:
+
+- What files to read for context
+- What `pan-tools.cjs` commands to run for bootstrapping
+- What agents to spawn (and in what order / parallelism)
+- What verification steps to perform
+- How to commit results
+
+Commands reference workflows. Workflows are the procedural backbone of the system.
+
+### Command-to-Workflow Mapping
+
+Some workflows have different names than their corresponding commands. This is intentional — workflows use descriptive internal names while commands use user-facing names:
+
+| Command | Workflow | Reason |
+|---------|----------|--------|
+| `resume.md` | `resume-project.md` | Command is user action; workflow is system operation |
+| `exec-phase.md` | `exec-phase.md` + `execute-plan.md` | Orchestrator + per-plan worker |
+| (no command) | `transition.md` | Internal phase-to-phase transition logic |
+| `verify-phase.md --uat` | `uat-walkthrough.md` (which follows `diagnose-issues.md` for the gaps it finds) | Folded-in command keeps its workflow behind a flag |
+| `plan-phase.md --research-only` | `research-phase.md` | Same |
+| `milestone-done.md --cleanup` | `milestone-cleanup.md` | Same |
+| `milestone-audit.md --gaps` | `milestone-gaps.md` | Same |
+| `learn.md --optimize` | `optimize.md` | Same |
+| `settings.md --profile` | `profile.md` | Same |
+| `focus-auto.md --step scan\|plan\|exec\|drift` | `focus-scan.md`, `focus-plan.md`, `focus-exec.md`, `focus-drift-walking.md` | Same |
+| `focus-docs.md` (`--sync`) | `focus-doc-audit.md` (`focus-sync.md`) | Same |
+
+### Internal Workflows
+
+No user command runs these workflows directly: `execute-plan.md`, `transition.md` and `diagnose-issues.md` are invoked by other workflows, and `exec-lean.md` by autodev's execute unit for a lean phase:
+
+| Workflow | Purpose |
+|----------|---------|
+| `execute-plan.md` | Per-plan execution worker (spawned by `exec-phase.md` per plan) |
+| `transition.md` | Phase-to-phase transition logic |
+| `exec-lean.md` | A lean phase in one session: the executor's work, then one reviewer pass and the verifier (autodev's execute unit, `autodev.cjs`) |
+| `diagnose-issues.md` | One debugger per failed UAT truth, root cause only; followed by `uat-walkthrough.md` (`/pan:verify-phase --uat`) for the gaps it records, and ported to the native `/pan-diagnose-issues` script on Claude Code |
+
+---
+
+## Layer 3: Agents
+
+**Location:** `agents/*.md`
+
+Agents are Markdown files that define specialized AI roles. Each agent runs as a subagent in a fresh context window, spawned by workflows via the `Task` tool.
+
+| Agent | Role | Spawned By |
+|-------|------|-----------|
+| `pan-project-researcher` | Answers at most five open questions that block building (opt-in research) | `/pan:new-project`, `/pan:milestone-new` |
+| `pan-roadmapper` | Creates phased roadmaps from requirements | `/pan:new-project`, `/pan:milestone-new` |
+| `pan-document_code` | Analyzes existing codebase (one focus area per mapper, or the whole repo in single-shot mode) | `/pan:map-codebase` (parallel when sharded; one agent in single-shot mode) |
+| `pan-designer` | Designs specs before planning | `/pan:design-phase` |
+| `pan-design-checker` | Validates design specs | `/pan:design-phase`, `/pan:focus-design` |
+| `pan-phase-researcher` | Answers at most five open questions that block planning a phase (opt-in: `--research` or `workflow.research`) | `/pan:plan-phase`, `/pan:plan-phase --research-only` |
+| `pan-planner` | Creates executable plan.md files | `/pan:plan-phase`, `/pan:quick` |
+| `pan-plan-checker` | Validates plans against goals across multiple dimensions | `/pan:plan-phase`, `/pan:quick --full` |
+| `pan-executor` | Executes plans with atomic commits | `/pan:exec-phase`, `/pan:quick`, `/pan:army` (Build squad) |
+| `pan-verifier` | Verifies phase delivered what it promised | `/pan:exec-phase`, `/pan:quick --full`, autodev's `exec-lean.md` (lean phase) |
+| `pan-reviewer` | Read-only code review (conventions, security, quality) | `/pan:exec-phase` (kept on a lean phase, which skips only test generation), autodev's `exec-lean.md` |
+| `pan-integration-checker` | Verifies cross-phase wiring and E2E flows | `/pan:milestone-audit` |
+| `pan-debugger` | Systematic bug investigation | `/pan:debug`, `/pan:verify-phase --uat` (the `diagnose-issues` workflow, one debugger per failed truth), native `/pan-diagnose-issues` script (Claude Code) |
+| `pan-previewer` | Foresight — blast radius / dependency graph / milestone ETA | `/pan:preview` |
+| `pan-hardener` | OWASP Top 10 + STRIDE security audit | `/pan:review-deep`, `/pan:exec-phase --deep-review`, `/pan:focus-auto` (security category Pass 3, and `--step exec --deep-review`) |
+| `pan-meta-reviewer` | Reviews reviewer + hardener output; flags missed issues | `/pan:review-deep`, `/pan:exec-phase --deep-review`, `/pan:focus-auto --step exec --deep-review` |
+| `pan-knowledge` | Grounded Q&A / multi-turn discussion / playbook generation | `/pan:knowledge` |
+| `pan-counterfactual` | Explores alternative phase approaches in isolated worktree | `/pan:what-if` |
+| `pan-conductor` | Top-level hierarchical exec orchestrator with safety harness | `/pan:exec-phase --hierarchical`, `/pan:army` (Mission Control) |
+| `pan-optimizer` | Reads trace events; identifies error/gap/redundancy patterns; produces ranked optimization report with auto-apply JSON block | `/pan:learn` (`/pan:learn --optimize apply` records its suggestions) |
+| `pan-distiller` | Read-only LLM judgment on AI code-bloat findings; receives only flagged spans (max 50 lines context); proposes minimal diff rewrite | `/pan:focus-auto --category distill` |
+| `pan-experiment-runner` | Observation-only watchdog that drives an external AI session against an isolated experiment folder; reports back to the orchestrator | — (no shipped command spawns it directly; `/pan:experiment run` drives the runtime through `runner.cjs`; listed among the tier-2 `workers` Mission Control may delegate to under `/pan:army`) |
+| `pan-release` | Release squad agent: prepares the squash-merge, surfaces an always-ask approval; a human merges to the protected branch | `/pan:army` (Release squad) |
+
+Every agent starts with zero context and receives only what it needs. This is PAN's key quality guarantee — agents never suffer from context degradation.
+
+For deep dives on each agent's inputs, outputs, behaviors, and unique features, see [AGENTS.md](AGENTS.md).
+
+---
+
+## Layer 4: Core Library
+
+**Location:** `pan-wizard-core/bin/lib/*.cjs`
+**CLI entry:** `pan-wizard-core/bin/pan-tools.cjs`
+
+The Node.js runtime layer. Zero external dependencies — only Node.js built-in modules (`fs`, `path`, `child_process`, `os`, `crypto`; the CLI entry also loads `module` to turn on Node's compile cache). Commands and workflows call `pan-tools.cjs` via bash and parse JSON output.
+
+### CLI Interface
+
+```bash
+node pan-tools.cjs <command> [subcommand] [args...] [--raw] [--cwd <path>]
+```
+
+All output is JSON by default. Pass `--raw` for human-readable output. When JSON output exceeds ~50KB, it is written to a tmpfile and the path is returned with an `@file:` prefix.
+
+### CLI Command Categories
+
+The dispatcher in `pan-tools.cjs` routes top-level commands (plus `init` sub-cases) to the modules:
+
+| Category | Example Commands |
+|----------|-----------------|
+| **State** | `state load`, `state update`, `state get`, `state json`, `state advance-plan`, `state record-metric`, `state init`, `state section`, `state quick-task`, `state apply` |
+| **Phase** | `phases list`, `phase add`, `phase insert`, `phase remove`, `phase complete [--force --reason <r>]`, `phase gate <N>`, `phase next-decimal` |
+| **Roadmap** | `roadmap get-phase`, `roadmap analyze`, `roadmap update-plan-progress`, `roadmap slice <N> [--write]`, `roadmap compact [--apply] [--keep N]` |
+| **Config** | `config-get`, `config-set`, `config-ensure-section` |
+| **Frontmatter** | `frontmatter get`, `frontmatter set`, `frontmatter merge`, `frontmatter validate` |
+| **Template** | `template select`, `template fill` |
+| **Scaffold** | `scaffold context`, `scaffold uat`, `scaffold verification`, `scaffold phase-dir` |
+| **Verify** | `verify plan-structure`, `verify phase-completeness`, `verify references`, `verify commits`, `verify artifacts`, `verify key-links`, `verify reconcile`, `verify stubs`, `verify scope`, `verify stale`, `verify plan-set`, `verify test-integrity`, `verify red`, `verify mutate`, `verify review-focus`, `verify decisions`, `verify gates`, `verify requirements`, `verify traceability` |
+| **Test** | `test run [--baseline]`, `test detect` |
+| **Review / Research** | `review scope <phase>`, `review cross-family <phase>`, `review vote`, `research lint <phase\|path>`, `research check <questions> <research> [--market]` |
+| **Size** (right-sized ceremony) | `size phase <N> [--quality] [--full]`, `size task "<description>" \| --file <path>`, `size phase-plan <N>`, `size quick-plan --out <file> [--num N] "<description>"`, `size plan-check <N>` |
+| **Validate** | `validate consistency`, `validate health`, `validate deployment` |
+| **Init** | `init execute-phase`, `init plan-phase`, `init new-project`, `init quick`, `init progress` (compound commands for each major workflow) |
+| **Milestone** | `milestone complete`, `requirements mark-complete` |
+| **Focus** | `focus scan`, `focus plan`, `focus sync`, `focus exec`, `focus auto`, `focus design`, `focus classify-stages`, `focus reflection` |
+| **Memory** (E-4) | `memory read`, `memory append`, `memory list`, `memory compact`, `memory select`, `memory record`, `memory prune`, `memory budget`, `memory optimize`, `memory rebuild` |
+| **Cache** (E-1) | `cache prime [--summary]` |
+| **Codebase** (E-2 extended) | `codebase detect-languages`, `codebase analyze-imports`, `codebase best-practices`, `codebase estimate-size` |
+| **Cost** (Spec B v2 Y-6) | `cost report`, `cost append`, `cost clear`, `cost rebuild`, `cost limits`, `cost budget`; `usage` (installed commands and agents used, never used, unfinished) |
+| **Bus** (Spec B v2 Y-7) | `bus publish`, `bus drain`, `bus list` |
+| **Preview** (Spec B v2 Y-1) | `preview phase <N>`, `preview phases`, `preview milestone` |
+| **Review-Deep** (Spec B v2 Y-2) | `review-deep merge`, `review-deep analyze` |
+| **Findings** (evidence loop, ADR-0049) | `findings record`, `findings list`, `findings dispose`, `findings debt`, `findings suppressions`, `findings prove` |
+| **Knowledge** (Spec B v2 Y-3) | `knowledge ask`, `knowledge discuss`, `knowledge playbook` |
+| **What-if** (Spec B v2 Y-4) | `whatif prepare`, `whatif report`, `whatif cleanup` |
+| **Optimize** | `optimize trace init/end/current/list/log`, `optimize learn [--sessions N]`, `optimize apply`, `optimize revert <apply_id>` / `--last`, `optimize list`, `optimize stats`, `learn` (alias) |
+| **Git** | `git commit`, `git branch`, `git push`, `git status`, `git log`, `git stash`, `git diff`, `git rollback`, `git tag`, `git sync` |
+| **Distill** | `distill scan`, `distill analyze`, `distill report` |
+| **Squads** (ADR-0032) | `squad list`, `squad show <name>` |
+| **Worktree** (ADR-0033) | `worktree list`, `worktree create <task>`, `worktree remove <path>`, `worktree cleanup` |
+| **Campaign** (ADR-0034) | `campaign schedule`, `campaign status`, `campaign due`, `campaign record-run` |
+| **HUD** (ADR-0035) | `hud [--out <f>] [--open] [--stdout]` |
+| **Report** | `report phase <N>` and `report index` (`[--out <f>] [--open] [--stdout]`; `index` also `--bundle`), `report all [--open]` |
+| **Standards** | `standards list`, `standards select`, `standards remove`, `standards status`, `standards recommend`, `standards phase-track`, `standards tools` |
+| **Operations** | `preflight`, `dashboard`, `learnings extract`, `learnings list`, `learnings prune`, `deps validate` |
+| **Learnings & lint** | `learn promote/unpromote/list-promoted/build-index/topics-for/lint`, `skills index/align`, `hygiene scan/clean`, `links validate`, `doc-lint` |
+| **Autonomy** | `autodev run`, `autodev resume`, `autodev status`, `autodev report`, `autodev replay`, `next-action`, `worktree preflight` |
+| **UAT / Debug / Merge** | `uat record`, `uat status`, `debug repro`, `debug similar`, `merge request`, `merge confirm` |
+| **Utility** | `resolve-model`, `models check`, `generate-slug`, `current-timestamp`, `context-budget`, `websearch`, `progress`, `todo`, `version` |
+
+### Module Inventory
+
+| Module | Responsibility |
+|--------|----------------|
+| `constants.cjs` | Shared path constants, file patterns, regex patterns. Foundation module. |
+| `core.cjs` | Model profile table, `output()`/`error()` helpers, `toPosix()`, `safeReadFile()`, `loadConfig()`, `resolveModelInternal()`, `findPhaseInternal()`, `generateSlugInternal()`, `scanPendingTodos()`, `execGit()`, and the line-ending helpers `toLf()`/`dominantEol()`/`withEol()` (parse planning files on LF, write them back in their own ending) |
+| `utils.cjs` | Shared utilities: `readJsonFile()`, `planningPath()`, `listPhaseDirs()`, `filterPlanFiles()`, `filterSummaryFiles()`, `classifyPhaseStatus()`, `planningRel()` |
+| `frontmatter.cjs` | YAML-like frontmatter CRUD: `extractFrontmatter()`, `reconstructFrontmatter()`, get/set/merge/validate |
+| `config.cjs` | Config CRUD: create default `config.json`, get/set with dot-notation paths (e.g., `workflow.auto_advance`), standards catalog (list, select, remove, status, recommend, phase-track, tools) |
+| `state.cjs` | state.md operations: load, get, update, patch, json output (`state load` and `state json` carry `contract: "1.0"`, `STATE_CONTRACT` in constants.cjs, as `progress` JSON does), `readStateSafe()`, frontmatter sync; writes serialize through lock.cjs (ADR-0030) |
+| `lock.cjs` | Advisory file locking (`withFileLock`, stale-steal) + atomic temp-rename writes (`writeFileAtomic`) for .planning/ concurrency (ADR-0030) |
+| `init.cjs` | Compound init commands: bootstrap all file paths and config for execute-phase, plan-phase, progress, phase-op, and the other major workflows |
+| `phase.cjs` | Phase CRUD facade: list, add, insert (decimal numbering), complete, next-decimal; re-exports phase-remove.cjs |
+| `phase-remove.cjs` | Phase removal + decimal/integer renumbering cascade, roadmap reference rewriting; extracted from phase.cjs |
+| `roadmap.cjs` | roadmap.md parsing: get-phase, analyze, update-plan-progress, and `roadmap slice` (`buildRoadmapSlice`): a line for every phase, this phase's section, its dependencies' goals and its requirement lines, written with `--write` to `XX-roadmap-slice.md` for phase agents to read in place of the whole roadmap and requirements. A section `roadmap compact` left as a stub is read back from `roadmap-history.md`. |
+| `verify.cjs` | Verification suite facade: verify-summary, validate-consistency, validate-health; re-exports the verify-* submodules below |
+| `verify-drift.cjs` | Convention-drift detection (drift-check); extracted from verify.cjs |
+| `verify-retro.cjs` | Milestone retrospective (retro); extracted from verify.cjs |
+| `verify-deploy.cjs` | Deployment validation (validate deployment); extracted from verify.cjs |
+| `verify-preflight.cjs` | Pre-execution gates (preflight, deps validate); extracted from verify.cjs |
+| `milestone.cjs` | Milestone lifecycle: complete (archive roadmap/requirements, create milestones.md), requirements mark-complete |
+| `commands.cjs` | Utility commands facade: history-digest, summary-extract, scaffold, progress, todo, websearch, commit, rollback-snapshot; re-exports commands-learnings.cjs |
+| `commands-learnings.cjs` | Error patterns (PAT-NNN), session history, learnings (LEARN-NNN) lifecycle + shared phase-summary collector; extracted from commands.cjs |
+| `template.cjs` | `template select` picks a plan's summary template (minimal/standard/complex) from its task count, file mentions and decisions; `template fill` writes pre-filled plan, summary and verification files from skeletons it builds itself. Reads no file under `pan-wizard-core/templates/`. |
+| `context-budget.cjs` | Context window utilization estimation: token counting, budget status (healthy/warning/critical), phase file scanning |
+| `focus.cjs` | Strategic project management: work item scanning, priority classification, capacity-budgeted batch planning, doc staleness checking, execution pipeline data layer. Also: `classifyStageDependencies()`, `determineContinuation()` (reflection gate). |
+| `codebase.cjs` | Codebase analysis: `detect-languages`, `analyze-imports`, `best-practices` scoring across 5 categories, plus `estimateRepoTokenSize()` for single-shot mode decision. |
+| `memory.cjs` | Cross-phase agent memory store (E-4): `readMemory`, `appendMemory`, `compactMemory`, `listMemoryAgents`, plus cited, verified, expiring entries (`selectMemory`, `pruneMemory`) and the gated `recordLesson`. Append-only files at `.planning/memory/<agent>.md`. Agent-name validated against `^[a-zA-Z0-9_-]+$` to block path traversal. No workflow loads it into agents (ADR-0036, amended `2026-10-04`). |
+| `bus.cjs` | (Y-7) File-backed message channels at `.planning/bus/<channel>.jsonl`: `publish`, `readChannel`, `drain` (peek/consume/archive modes), `listChannels`. Agent audit trail for hierarchical exec and review-deep coordination. |
+| `cost.cjs` | (Y-6) Per-call cost aggregation: `appendRecord`, `readRecords`, `aggregate`, `computeCost`, `renderTable`, `renderChart`. Log at `.planning/metrics/tokens.jsonl`. Ships a default per-model rate table (kept current in `cost.cjs`, matched by exact id then family prefix) plus per-tier fallbacks; override via `cost.rates` config, which wins over a managed Claude Code `modelPricing` block (its `overrides` rows × its `multiplier`; the multiplier also scales the built-in rates). |
+| `cost-rebuild.cjs` | `cost rebuild` (reads `cost.cjs`, `core.cjs`, `utils.cjs`): regenerates the ledger from Claude Code's transcripts under `<config dir>/projects/<encoded cwd>/` — `sumTranscriptUsage` (one turn per `message.id`), `mapAgentsFromParent` (agent id → type/model from the main thread's `Agent` calls), `listAgentFiles` (direct and Workflow-tool subagents), `planRebuild` (dry run: per-session before → after), `applyRebuild` (moves the old ledger aside, idempotent). Supersedes hook rows of rebuilt sessions; keeps rows whose transcript is gone and caller-appended rows. |
+| `preview.cjs` | (Y-1) Foresight data layer: `buildPhasePreview` (blast radius), `buildPhaseDependencyGraph` (mermaid DAG + Kahn parallel batches + hidden-dep detection), `buildMilestoneETA` (velocity + ETA + confidence + bottleneck). |
+| `review-deep.cjs` | (Y-2) Merges reviewer + hardener + meta-reviewer findings: `parseReviewFindings`, `mergeReviews` (verdict ladder), `writeDeepReview`. A report ending in a valid `pan-verdict` block is read from the block (verdict.cjs) instead of the bullet grammar. Publishes audit to `review-handoff` bus channel. |
+| `knowledge.cjs` | (Y-3) Grounded Q&A + session state + playbook: `ask` (keyword-scored retrieval over CITATION_ROOTS), `loadSession`/`appendTurn` (`.planning/conversations/<phase>/`), `buildPlaybook`/`writePlaybook` (clusters memory into categorized sections). |
+| `whatif.cjs` | (Y-4) Counterfactual phase replay: `scenarioSlug`, `buildCounterfactualContext`, `writeCounterfactualReport`, `createWorktree`/`cleanupWorktree` (git worktree lifecycle). Output at `.planning/counterfactuals/<phase>-<slug>.md`. |
+| `optimize.cjs` | Circular optimization loop: `initTraceSession`, `logTraceEvent` (auto-inherits session phase per W3 fix; opens the day's auto-session when none is active), `analyzeEvents` (surfaces `reviewer_corrections`, `memory_primed_count`, `tool_error_patterns` and per-judge `verdict_stats`), `generateLocalReport` (`generatePooledReport` for `optimize learn --sessions N`), `applyReportRecommendations` (records a report's suggestion notes in `optimization/suggestions.md` and config notes in `config-suggestions.md`, for a person to act on; an older report's `memory`/`memory_append` actions still write, but only inside `.planning/memory/` (one naming another file is skipped), with a warning that no workflow loads it, and its `memory_entry` actions go through `memory record`; logs each action in `optimization/applied.jsonl` under an `apply_id`, and skips an action an earlier apply already wrote), `revertApply` (`optimize revert <apply_id>` / `--last`: deletes the files an apply created and cuts the text it appended, refusing a file changed since or also written by a later apply). Token telemetry falls back to wall-clock timing when `usage` block unavailable. |
+| `git.cjs` | Phase-aware git workflow: `cmdGitCommit` (reuses `runCommitSafetyChecks`), `cmdGitBranch` (create/switch/list/delete with `pan/phase-N` naming), `cmdGitPush` (remote-validated, explicit `--force`), `cmdGitStatus`, `cmdGitLog`, `cmdGitStash` (named save/pop/list/drop), `cmdGitDiff`, `cmdGitRollback` (find pan-rollback-* tags + reset), `cmdGitTag`, `cmdGitSync` (pull + optional rebase). |
+| `distill.cjs` | AI code-bloat 5-pass optimizer: Pass 1 deterministic (`findPhantomTryCatch`, `findUnusedImports`, `findMagicNumbers`, `findLongFunctions`, `findWideParamLists`), Pass 2 AST-style (`findSingleInstanceFactories`, `findDeepNesting`), Pass 3 cross-file (`findRepeatedBlocks`, `findUnreferencedExports`), Pass 4 LLM judgment via `pan-distiller` agent on flagged spans only, Pass 5 cross-session memory (`readPatternsMemory`, `writePatternsMemory`, `detectRegressedPatterns`). Bloat budget gate: `computeBloatBudget`. |
+| `doc-lint.cjs` | Markdown frontmatter + structure linter (vendored from the whooo experiment). Adapter over `pan-wizard-core/bin/lib/doc-lint/{frontmatter,schema,validate,walk,reporter}.js`. Validates `commands/pan/*.md` and other PAN-shipped markdown against schemas in `pan-wizard-core/references/schemas/`. Subcommands: `doc-lint <dir>` (lint), `doc-lint schema-check` (verify schema yaml), `doc-lint counts <dir>` (drift-prone counts), `doc-lint flags` (documented `pan-tools` flags the source does not parse). |
+| `experiment.cjs` | Self-improvement loop scaffolding. `newExperiment` (slug + idea path → scaffold `<root>/<slug>/.planning/`, copy idea, write manifest, optionally run installer), `listExperiments`, `getExperimentManifest`, `harvestExperiment` (copies the experiment's `idea.md`, `experiment.json`, `state.md`, `run-state.json`, `agent-history.json`, `optimization/` (traces included) and `phases/` into `<source>/experiments/<slug>/`), `pruneExperiment`. Hard `PAN_SOURCE_ROOT` guard prevents scaffolding inside the source repo. |
+| `runner.cjs` | External agent runner. `runExperiment` spawns the runtime adapter (Claude/Codex/Gemini/OpenCode) via `spawnSync` against an experiment folder, observes via `run-state.json`, enforces timeout + circuit breaker. `RUNTIME_RUNNERS` adapter map (per-runtime headless invocation, `shell: 'win32'` for `.cmd` shims, arg quoting). The `captureMetrics: true` opt switches the claude adapter to `--output-format json` and `parseClaudeJsonEnvelope` extracts cost/turns/tokens into `runState.metrics`. Reads state.md milestone status to distinguish `success` from `incomplete`. |
+| `learn-lint.cjs` | Learnings-store integrity linter for `pan-wizard-core/learnings/{universal,internal}/`. `cmdLearnLint(sourceRoot, {scope, strict})` (over `lintPatterns()`) runs L-001 (duplicate IDs across files), L-002 (dangling pattern cross-references), L-003 (empty `source_experiments` while body cites a known experiment), L-004 (universal-scope rule prose using PAN-internal terms), L-005 (revision marker `-rN` without `superseded_by` frontmatter on the base), L-006 (universal-scope pattern citing an internal pattern id, which dangles after install), L-007 (a pattern's `cites` no longer holds: the cited file or symbol is gone, checked with `memory.cjs`'s `citationProblem`). Wired into `/check`. |
+| `learn-index.cjs` | Learnings index + agent-relevance queries. `buildIndex()` walks both scopes and `writeIndex()` writes `pan-wizard-core/learnings/index.json` (`learn build-index` runs both) with topic→`{patterns, size_tokens_est, agent_relevance}` per topic; the curated `RELEVANCE` table assigns `high\|medium\|low` per `(topic, agent_role)` for `planner / executor / verifier / reviewer`. `topicsForAgent(index, {agent, minRelevance, tokenBudget, cue})` returns budget-aware topic selection: with a cue (the phase goal and the files it touches) topics are ranked by how well their names, summaries and rules match it, and by role relevance only when nothing matches. Workflow files (`plan-phase.md`, `exec-phase.md`, `verify-phase.md`, `execute-plan.md`) call `learn topics-for --cue` to load only the learnings that fit the task instead of skim-the-folder. |
+| `links.cjs` | Doc–code link graph (ADR-0027). `validateAll(cwd, opts)` runs three passes: forward links (inline `[[<id>]]` + `must_haves.key_links`) → finding codes F-001..F-004; backlink contract for docs with `require-code-mention: true` frontmatter → B-001/B-002; anchor-target existence for `// @pan: <id>` source comments → A-001/A-002/A-004. `resolveDocId` handles `ADR-NNNN` glob, relative `.md` paths, and `<doc>#section` slug match. `cmdLinksValidate` goes through `core.output()` with an explicit exit code (`1` on fail — the verdict payload has no `error` key), which also gives it the `@file:` large-output protocol the former hand-rolled bypass lacked. Reuses `doc-lint/walk.js` and `frontmatter.cjs` — zero new dependencies. Wired into `validate health --links` for advisory pre-flight. |
+| `squads.cjs` | **(ADR-0032)** Bot-army squad registry + resolver: `SQUADS` (architecture/build/quality/release with tier + advisory access contract), `listSquads`, `getSquad`, `squadForAgent`, `validateRoster` (drift guard: every member is a real agent, every agent placed). `cmdSquadList` / `cmdSquadShow`. Registry only — modifies no agent and no execution path. |
+| `worktree.cjs` | **(ADR-0033)** Branch-per-agent isolation for the Build squad: `createTaskWorktree` / `removeTaskWorktree` / `listArmyWorktrees` (army/`<task>`-prefixed; removal refuses non-army branches). Generalized from `whatif.cjs`. `cmdWorktreeList` / `cmdWorktreeCreate` / `cmdWorktreeRemove`. |
+| `campaign.cjs` | **(ADR-0034)** Scheduled self-resuming campaigns: `parseCadence`, `writeSchedule`/`readSchedule`, `isRunDue` (enabled/paused/budget/next-due), `recordRun` (advance next-due + per-day spend), `isDreamDue`. Descriptor at `.planning/orchestration/schedule.json`. PAN owns the due-check; the host scheduler fires `/pan:army --continue`. Never relaxes the human merge gate. |
+| `hud.cjs` | **(ADR-0035)** Single-page HTML army + project dashboard. `collectHudData` (pure: aggregates state.md, roadmap/phases, squad registry, campaign schedule, army worktrees, cost ledger, requirements, verification, git log), `renderHud` (self-contained HTML — no server/network/external assets), `cmdHud`. A read-only **view**: owns no state, writes only its HTML file (`.planning/hud.html`, or the `--out` path). Army-only panels degrade gracefully when no campaign/worktrees exist. Reads `squads.cjs` + `campaign.cjs` + `worktree.cjs` + `cost.cjs`. |
+| `skill-align.cjs` | **(ADR-0038)** Skill-Aligned Decomposition pass. `buildSkillIndex(root)` walks commands/templates/references + learnings topics on the fly (nothing persisted); `alignTasks(root, tasks, opts)` scores draft planner tasks via `scoreRelevance` (glue-word stop-list, capped scoring head) and returns per-task top-k matches plus a deduped, token-budgeted `vocabulary` hint list with explicit `dropped` overflow. Advisory + fail-open: missing roots are skipped and reported. Used by `pan-planner`'s `skill_alignment` step. `cmdSkillsIndex` / `cmdSkillsAlign`. |
+| `hygiene.cjs` | Project cleanup + version alignment. `scanHygiene` runs the checks named by its finding ids: `version-alignment` (per-runtime manifest version vs latest, untracked installs), `legacy-filenames`, `tmp-orphans`, `memory-bloat`, `memory-stale` (entries `memory select` leaves out: cited code gone, or unused past the expiry window — fix `prune-memory`), `memory-format` (an `info` finding for a memory file with no `## Entries` list, which is never loaded), `host-memory` (read-only, once per project: Claude Code's auto-memory index past its 200-line / 25 KB session-start load limit, or holding content where a pointer belongs; PAN never writes that store, MI-010), `poisoned-ledger` (via `cost.cjs isSuspectRecord`, gated on record count *or* token mass), `stale-traces`, `stale-reports`, `cache-context` (cached-context bloat, plus the prompt-cache lifetime recommendation — `info`, raised to `warn` once the re-written tokens reach `TTL_WARN_TOKENS`), `planning-fragment`, `foreign-planning-tree` (via `foreign-planning.cjs` — a tree that belongs to another tool gets that one warning and no per-tree checks), and `shared-planning-tree` (an `info` finding for a tree another tool writes into beside PAN; the per-tree checks still run). `cleanHygiene` applies only the safe subset (case-hop renames, orphan deletion, `compactMemory`, `pruneMemory` (archive-first), `state compact` and `roadmap compact` (history-first), ledger quarantine-by-rename, pruning of old trace sessions and optimization reports) — dry-run by default, `--apply` to execute; installer re-runs and fragment removal always stay manual. `cmdHygieneScan` / `cmdHygieneClean`. |
+| `phase-report.cjs` | Per-phase graphical HTML report + project-level timeline index (`pan-tools report phase <N>` \| `index` \| `all`). Three layers mirroring hud.cjs: `collectPhaseData`/`collectIndexData` (pure `.planning/` reads), `renderPhaseHtml`/`renderIndexHtml` (pure self-contained docs), `cmdReport` and `renderAllToDisk` (the regeneration `report all` and focus-auto's checkpoint run) as the only side-effecting layer. Reuses hud.cjs's rendering foundation verbatim so both surfaces render identically. |
+| `agents-md.cjs` | AGENTS.md universal rules layer (ADR-0028 Phase 3). Single source of truth for the marker-fenced PAN section and PAN's `CLAUDE.md` block: the `@AGENTS.md` import plus a `# Compact instructions` section that tells Claude Code's compaction summary what to keep for PAN work to resume (an older import-only block is updated in place); lives under the core so the installer AND an installed `memory rebuild` regenerate byte-identical content. User content outside the markers is never touched. |
+| `memory-rebuild.cjs` | `memory rebuild [--apply]` (dry-run by default; refuses inside the source repo): regenerates the derived tools memory — the marker-fenced PAN section of `AGENTS.md`, the `CLAUDE.md` `@AGENTS.md` bridge on Claude installs, and `state.md`'s frontmatter from its body (a stacked-frontmatter `state.md` is reported as refused) — and warns on directive-like lines in `AGENTS.md`/`CLAUDE.md` (ADR-0040). |
+| `memory-optimize.cjs` | Memory compaction and the quarantine path for entries carrying injected directives (ADR-0040). |
+| `suggest.cjs` | **(2026-08)** "Did you mean" corrections for an unknown command. PURE. `buildSubcommandIndex()` parses the dispatcher's own `Unknown <group> subcommand. Available:` strings (and the `Unknown init workflow:` / `<group> subcommand required. Available:` variants) — load-bearing text a user sees, so it cannot rot quietly — and `suggestCommand()` resolves a namespace miss (`trace` → `pan-tools optimize trace`) or a near-miss typo. Runs on the ERROR PATH ONLY, so a healthy invocation pays nothing, and fails open to the plain message. |
+| `planning-root.cjs` | **(ADR-0043)** Resolves WHICH planning tree a command acts on (`--track` / `--planning-dir` / `PAN_TRACK` / `PAN_PLANNING_DIR`, default `.planning`), discovers tracks under `.planning/tracks/`, and reports each resolution's provenance so a wrong target is visible instead of passing for a healthy project. Leaf module — Node builtins only; `utils.planningPath()` / `utils.planningRel()` are the primary path constructors built on it; commands, hygiene, init and verify also read its root helpers directly. No CLI surface. |
+| `state-compact.cjs` | **(ADR-0044)** `state compact [--apply] [--keep-days N]`: archives settled history out of `state.md` into `state-history.md` so it stops being re-read into every agent call. Archive first, then rewrite, nothing deleted; live sections and frontmatter-source fields are protected; dry-run by default. |
+| `roadmap-compact.cjs` | `roadmap compact [--apply] [--keep N]`: moves shipped phases' detail sections out of `roadmap.md` into `roadmap-history.md`, the way `state compact` bounds `state.md`. History first, then rewrite, nothing deleted; a stub keeps each heading, its Goal, Depends on and Requirements lines and any `model_tier` override; the current phase and the `keep` most recently shipped (default 2) stay; dry-run by default, and it declines when nothing would shrink. Readers that need a full section (`roadmap get-phase`, `roadmap slice`, phase reports, the per-phase `model_tier` lookup) find it in the history. |
+| `foreign-planning.cjs` | **(2026-09)** `detectForeignPlanningTree(dir)` / `detectForeignPlanningTreeAt(cwd)`: does another tool write to this `.planning/`? Answered from POSITIVE markers PAN never writes (`FOREIGN_PLANNING_MARKERS` in `constants.cjs`); never throws. **gsd-core owns its tree:** markers `HANDOFF.json`, `.gsd-allow-shrink`, two or more gsd-only directories, or its flat dotted config keys. `hygiene.cjs` gives one `foreign-planning-tree` warning, runs no per-tree checks, and `applyFix` refuses the rename. `verify.cjs` reports `E006` in `validate health` and stops before `E002`–`E005`. `init new-project` refuses. **planning-with-files shares it** (`coexists: true`): markers `.active_plan`, `.attestation`, `ledger-*.jsonl`, a dated task directory holding `task_plan.md`, or two of its directories (`sessions/`, dated task directories without the plan file). Hygiene raises a `shared-planning-tree` info finding and runs PAN's own checks, health reports `I004`, and init proceeds and reports it. |
+| `verdict.cjs` | **(evidence loop, ADR-0049)** The `pan-verdict` contract. PURE. `parseVerdictText()` reads the last fenced `pan-verdict` block of a judge's report, or a verification.md frontmatter through its own list-of-mappings reader, which the general frontmatter parser flattens to strings. `validateVerdict()` enforces the contract and records near-misses in their closest valid form, with warnings. `findingId()` and `recordSig()` give findings and artifacts stable identities. |
+| `findings.cjs` | **(evidence loop, ADR-0049)** The findings ledger `.planning/findings.jsonl` (verdict, finding and disposition rows; append-only; folded on read). `recordVerdict()` is idempotent per artifact, numbers attempts per agent and phase, closes earlier findings only on evidence (a judge's `resolved` answer or a passing code fact, never silence), keeps a reworded finding's id, and logs `verdict_*` / `verdict_retry` trace events. Learned suppressions: a dismissed finding is filtered on re-report while its file is unchanged (scoped to its phase, or to any phase once the same judge dismissed it in two phases), and retires when the file changes; security findings (any `pan-hardener` finding, or a security term in the summary), logic findings (`defect`, `contradicts`, `missing`, `partial`) and findings with no file are never suppressed. Also `disposeFindings()` (reason required for deferred, dismissed and decision), `listFindings()` and `findingsDebt()` (milestone-audit's tech debt). Backs `findings record/list/dispose/debt/suppressions` and `pan://findings`. |
+| `plan-lint.cjs` | **(program P2, P4)** Plan intent checked in code. `verify review-focus <phase>`: every plan has a `## Review Focus` with at most five items, each naming a task and a test, or one `None — <reason>` line. `verify decisions <phase>`: a plan citing a `DD-N` id the phase design does not record, and a recorded decision no plan cites, are flagged; a design from before ids is `legacy` (a warning). `verify gates <phase>`: a task's `<verify>` command that already passes before any work is flagged. |
+| `research-lint.cjs` | **(program P3)** `research lint <phase\|path>`: reads a research file's `## Claims` table. A claim with no source or no valid checked date is an error; one older than its type's freshness window (versions, prices and security 30 days, APIs 90, general claims 180, practices 365) is `stale`. The plan-checker weighs the result. |
+| `usage.cjs` | **(program L9)** `usage`: local census of installed commands and agents against the cost ledger and trace sessions (used, never used, unfinished). Reads `cost.cjs` `readRecords` and the trace sessions' `session.json`; writes nothing. |
+| `phase-gate.cjs` | **(program V1)** `phase gate <N>`: whether a phase may be marked complete, in code. Refuses (one reason code each) on a plan without a summary, no verification, a failed one (with code facts applied), `human_needed` without a recorded approval, a stale verification, a reconcile contradiction, a failed test gate, open critical/high findings, committed stubs, or a test-integrity violation; what it could not check is listed in `not_checked`. `workflow.phase_gate` is `enforce` by default (also when unset or unrecognised): a refusal stops `phase complete` unless `--force --reason`, which records the override as a decision; `warn` reports the reasons and proceeds. `phase complete`, the native `pan-exec-waves` script and the MCP merge request all use it. |
+| `test-gate.cjs` | **(program V2)** `test run` / `test detect`: the engine runs the project's tests in any language (`workflow.test_command`, else package.json, pytest, go, cargo, Maven, Gradle, make), parses the runner's own output into counts and failing-test ids, and writes `{NN}-test-baseline.json` before execution and `{NN}-test-run.json` after. A failure the baseline already had is pre-existing; a new one is a regression; a suite that did not run is failed, never skipped. The verifier copies its status, reconcile cross-checks it, and the verdict recorder and the phase gate take it as a code fact. |
+| `mutate.cjs` | **(program V5)** `verify mutate --phase N`: per-language mutation operators (JS/TS, C-family, Python) applied one at a time to the lines the phase changed, in a worktree at HEAD, with a seeded sample, a flake pre-check, and survivors written to `{NN}-mutation.json`. `workflow.mutation_gate`: `report` (default), `off`, `gate` (opt-in: a score below `workflow.mutation_floor`, 0.6, fails). `scripts/mutation-probe.cjs` imports its operator table. |
+| `verify-red.cjs` | **(program V4)** `verify red <phase>`: each test file the phase's plan commits added or changed must fail in a throwaway worktree at the phase's base (the parent of its oldest plan commit) and pass at HEAD; a test that passes at the base is `not_red` (tautological, or testing something the phase did not change). Runs one file at a time through test-gate's `fileCommand`; exports `withWorktree` for the mutation report. |
+| `verify-integrity.cjs` | **(program V3)** `verify test-integrity <phase>`: walks the phase's plan commits and reports a deleted test, a skip or only marker added (JS, Python, Go, Rust, Java), assertions dropped, an assertion edited in a test no plan declares, a rewritten snapshot, or an assertion that cannot fail; a renamed test is a warning. Uses verify-scope's `committedFiles()`. |
+| `verify-plan-set.cjs` | **(program V7)** `verify plan-set <phase>`: the plan checks code can make, before the plan checker runs (requirement coverage, same-wave file overlap, missing, self and future references, cycles, wave gaps). `planCheckStatus()` binds a passing plan check to the plans it checked through the `plans_sha` the recorder stores with every plan-checker verdict; `planDrift()` lists planned files changed since a plan's `planned_commit`. `init execute-phase` carries both as `plan_check` and `plan_drift`. |
+| `verify-scope.cjs` | **(evidence loop)** `scopePhase()`: the files a phase changed (plan commits by subject, plus summary key-files) that its plans did not declare in `files_modified`. The planning tree, lockfiles and PAN's runtime directories are excluded. Backs `verify scope`. `reviewScope()` backs `review scope <phase>`: the changed files with each plan's objective, must_haves and Review Focus, the claimed requirements' text, and `unlisted` files no summary lists, for the reviewer's `<intent>` block. Also `verificationFreshness()`: whether a phase's verification still describes the code (`fresh`, `stale`, `unverified` or `unknown`, from the covered files changed since `verified_commit`), which backs `verify stale` and the per-phase `verification` state in `progress` output. Re-exported by verify.cjs; commands.cjs reads `verificationFreshness` directly. |
+| `autodev.cjs` | **(program A1)** `autodev run/resume/status`: the deterministic outer loop — reads `.planning/`, asks `next-action` for the next unit, decides in code whether to stop, runs each unit in a fresh headless host session; ledger and state under `.planning/autodev/`. A phase `sizing.cjs` sizes lean runs its execute unit in one session through `workflows/exec-lean.md` (`LEAN_WORKFLOW`, `unitPrompt`): the session does the executor's work, then one `pan-reviewer` pass, then the verifier; the cost and trace hooks attribute that session to command `exec-lean`. |
+| `autodev-report.cjs` | **(program A5)** `autodev replay` (re-runs the stop logic over `blackbox.jsonl`) and `autodev report` (`dossier.md`/`dossier.html` beside the ledger). |
+| `failure-class.cjs` | **(program A4)** Classifies a failed autodev unit and routes it: retry with the error tail, fresh restart, tier escalation, quarantine, ask a human, or stop on budget. No CLI surface. |
+| `ci.cjs` | **(program A2)** CI as autodev's oracle: `gh pr checks` (`--ci`), or the project's own `npm run ci:local`/`npm test` (`--ci local`); fix rounds and a breaker. No CLI surface of its own. |
+| `hosts.cjs` | **(program A0)** One table of how PAN runs each host CLI: the autonomous runner argv, the model family, the read-only review argv, the headless harness argv. No CLI surface. |
+| `next-action.cjs` | **(program L7)** `next-action`: reads roadmap.md and the phase directories into the MCP orchestrator's snapshot and maps its decision to a command. |
+| `sizing.cjs` | Right-sized ceremony: decides lean or full per phase and quick task (`size phase/task`). A phase is lean when every requirement mapped to it is precisely specified (an acceptance criterion or a named artifact) and there are at most `LEAN_CEILING_FACTOR` (3) × `workflow.lean_max_requirements` (default 5) of them; above `lean_max_requirements` the engine splits the lean phase into plans of at most that many tasks, each in its own wave (`size phase-plan`, `planLeanPhase`). Writes a lean quick task's plan (`size quick-plan`) and checks lean plans in code (`size plan-check`). The `quality` profile, `workflow.ceremony: full`, `--quality` and `--full` keep the full path. |
+| `cross-family.cjs` | **(program R4)** `review cross-family <phase>`: one read-only review on another host's CLI, off unless `workflow.cross_family_review` names a host. |
+| `review-vote.cjs` | **(program R2)** `review vote`: merges k reviewer passes; a finding survives only with a quorum. |
+| `merge.cjs` | **(program L6a)** `merge request` / `merge confirm`: the human merge gate on the CLI; confirm only in an interactive terminal. |
+| `uat.cjs` | **(program L8)** `uat record` / `uat status`: UAT results written through the engine into `{phase}-uat.md`. |
+| `debug-cases.cjs` | **(program P5)** `debug repro <slug>` / `debug similar "<symptom>"`: a debug session's reproduction as its closing check, and the resolved case base. |
+| `state-write.cjs` | **(program A7b)** `state init`, `state section`, `state quick-task`, `state apply`: the writers of state.md as a whole or by section. |
+| `requirements-lint.cjs` | **(program V8)** `verify requirements` (EARS criteria) and `verify traceability` (runs each requirement's mapped tests); `phase complete` ticks through it. |
+
+---
+
+## Layer 5: Persistent State
+
+**Location:** `.planning/` directory
+
+Markdown and JSON files that survive context resets. This is the single source of truth for project state.
+
+The tree below shows the core files. Depending on which features a project has used it also carries a phase's `.continue-here.md` (from `/pan:pause`), `learnings.md`, `standards.md`, `state-history.md`, `roadmap-history.md`, `playbook.md`, `hud.html`, `report-index.html`, `report-bundle.html` and the `milestones/`, `memory/`, `bus/`, `metrics/`, `optimization/`, `orchestration/`, `counterfactuals/`, `conversations/`, `reviews/`, `bridge/`, `focus/` and `tracks/` directories.
+
+```text
+.planning/
+  project.md            Project definition, scope, and constraints
+  requirements.md       Scoped requirements with unique IDs (REQ-01, etc.)
+  roadmap.md            Phase list with status, success criteria, progress
+  state.md              Current execution state (frontmatter + body)
+  config.json           User configuration (models, workflow toggles)
+  milestones.md         Completed milestone archive
+  patterns.md           Error patterns (PAT-NNN); read when present, no verb or hook writes it
+  session-history.md    Session summaries (last 20 entries); read when present, no verb or hook writes it
+  research/             Opt-in research from /pan:new-project --research or /pan:milestone-new
+    questions.md        At most five open questions that block building, written by the orchestrator
+    research-summary.md One answer row per question (pan-project-researcher; older projects: summary.md)
+  codebase/             Brownfield analysis from /pan:map-codebase
+    stack.md            Current tech stack
+    integrations.md     External services and APIs
+    architecture.md     System design and patterns
+    structure.md        Directory layout guide
+    conventions.md      Coding patterns and style
+    testing.md          Test infrastructure and patterns
+    concerns.md         Tech debt and risks
+    relationships.md    Module and component dependency map
+    best-practices.md   Recommended patterns for this codebase
+  todos/
+    pending/            Captured ideas awaiting work
+    completed/          Completed todos (`pan-tools todo complete` moves files here)
+  debug/                Active debug sessions
+    resolved/           Archived debug sessions
+  quick/                Quick mode task plans and summaries
+  findings.jsonl        Judges' verdicts, findings and dispositions (append-only; `pan-tools findings`)
+  phases/
+    XX-<slug>/
+      XX-context.md     Implementation preferences from discuss-phase
+      XX-research.md    Phase research: answers to at most 5 open questions (opt-in)
+      XX-roadmap-slice.md  This phase's roadmap and requirements lines (`pan-tools roadmap slice <N> --write`), read by phase agents
+      XX-validation.md  Test coverage mapping (Nyquist layer)
+      XX-YY-plan.md     Atomic execution plans
+      XX-YY-summary.md  Post-execution summaries
+      XX-verification.md  Goal-backward verification results
+      XX-review.md      The reviewer's report, saved by exec-phase (read by /pan:review-deep)
+      XX-plan-check.md  The plan checker's report, saved by plan-phase
+      XX-design-check.md  The design checker's report, saved by design-phase
+      XX-uat.md         User acceptance test results
+```
+
+### File Lifecycle
+
+| File | Created By | Updated By | Read By |
+|------|-----------|-----------|---------|
+| `project.md` | `/pan:new-project` | `/pan:milestone-new`, `/pan:milestone-done`, the phase transition (`transition.md`) | Orchestrators, the roadmapper, the phase researcher, and executors (plans carry `@.planning/project.md`) |
+| `requirements.md` | `/pan:new-project` | `pan-roadmapper`, `pan-executor` (mark complete) | The roadmapper and milestone work, whole; phase agents read their phase's requirement lines in the roadmap slice |
+| `roadmap.md` | `pan-roadmapper` | `pan-executor` (progress), phase commands, `roadmap compact` (moves shipped phases' detail to `roadmap-history.md`) | The roadmapper, milestone work and orchestrators, whole; the planner, plan checker, researcher, executors and verifier read the phase's slice (`XX-roadmap-slice.md`); the designer and design checker take the phase boundary from `roadmap.md` |
+| `state.md` | `pan-roadmapper` | `pan-executor`, pan-tools CLI | Orchestrators, agents |
+| `config.json` | `/pan:new-project` | `/pan:settings` | Orchestrators (model resolution, workflow toggles) |
+| `research.md` | `pan-phase-researcher` | — (immutable after creation) | `pan-planner` |
+| `plan.md` | `pan-planner` | `pan-planner` (revision loop, on the plan checker's issues; the checker has no Write tool) | `pan-executor` |
+| `summary.md` | `pan-executor` | — (immutable after creation) | `pan-verifier`, `pan-integration-checker` |
+| `verification.md` | `pan-verifier` | Re-verification overwrites | `/pan:plan-phase --gaps` |
+| `patterns.md` | `appendErrorPattern()`, which no verb, hook or workflow calls today | `appendErrorPattern()` (auto-increment PAT-NNN) | `readErrorPatterns()` (`progress health`, `learnings extract`, `focus scan`, `focus plan`), `preflight` (counts the entries), `/pan:focus-auto --step scan` |
+| `session-history.md` | `appendSessionSummary()`, which no verb, hook or workflow calls today | `appendSessionSummary()` (keeps last 20) | `progress health` |
+
+---
+
+## Additional Components
+
+### References
+
+**Location:** `pan-wizard-core/references/*.md`
+
+Context documents loaded by agents and workflows at runtime. These provide domain knowledge that agents need but that should not be baked into their system prompts.
+
+| Reference | Purpose |
+|-----------|---------|
+| `checkpoints.md` | Checkpoint types and protocols for human interaction points |
+| `continuation-format.md` | Standard format for presenting next steps after commands |
+| `decimal-phase-calculation.md` | Algorithm for calculating next decimal phase number |
+| `design-methodology.md` | Design methodology for the design phase (architecture, ADR, threat-lite) |
+| `git-integration.md` | Commit points, commit message formats, why per-task commits |
+| `git-planning-commit.md` | How to commit `.planning/` artifacts (respects `commit_docs` config) |
+| `guardrails.md` | Behavioral guardrails — anti-patterns, Code Preservation Principle, Stop-the-Line Rule |
+| `handoff-decisions.md` | Planner → executor decision-trace handoff (locked / open / rejected decisions) |
+| `model-profile-resolution.md` | How to resolve model profiles once at orchestration start |
+| `model-profiles.md` | Model profile table (quality/balanced/budget per agent) |
+| `phase-argument-parsing.md` | Normalize phase arguments across commands |
+| `planning-config.md` | Configuration options for `.planning/` directory behavior |
+| `questioning.md` | Project initialization philosophy: dream extraction, not requirements gathering |
+| `tdd.md` | TDD patterns and red-green-refactor discipline |
+| `ui-brand.md` | Visual patterns for user-facing output (stage banners, formatting) |
+| `verdict-contract.md` | The `pan-verdict` block the plan checker, reviewer and design checker end their reports with (fields, classes, severities, per-judge mapping) |
+| `verification-patterns.md` | How to verify artifacts are real implementations, not stubs |
+
+### Templates
+
+**Location:** `pan-wizard-core/templates/`
+
+Scaffold templates for all planning files. Agents, workflows and commands read them by path when they write planning files; `template select` returns the summary template's path, while `template fill` and `scaffold` write skeletons of their own. Templates cover: project.md, roadmap.md, state.md, summaries (minimal/standard/complex), research outputs, codebase mapping, plans, verification, UAT, debug, discovery, milestones, retrospectives, and more.
+
+### Hooks
+
+**Location:** `hooks/` (source), `hooks/dist/` (copied build output)
+
+The shipped hooks (copied to `hooks/dist/` by `npm run build:hooks` — pure Node.js, zero deps, no bundling):
+
+| Hook | Event Type | Function |
+|------|-----------|----------|
+| `pan-statusline.js` | statusLine | Renders the status line (model, task, directory, context bar) and writes the context metrics, with token counts and the model id, to the bridge file the context monitor reads |
+| `pan-context-monitor.js` | PostToolUse | Reads the bridge file, or the session transcript when no fresh bridge exists (headless `claude -p`, a status line that is not PAN's; a subagent's call reads the subagent's own transcript), and injects a note when the room left before the host compacts is ≤35% (WARNING) or ≤25% (CRITICAL) |
+| `pan-check-update.js` | SessionStart | Background check for PAN updates with caching |
+| `pan-cost-logger.js` | SubagentStop | Appends subagent cost record to `.planning/metrics/tokens.jsonl` (consumed by `/pan:cost`) |
+| `pan-trace-logger.js` | SubagentStop | Appends decision/redundancy events, plus redacted `error`/`tool_error` events for the failed tool calls in a subagent's own transcript (Claude Code), to `.planning/optimization/traces/<session>/trace.jsonl` (consumed by `/pan:learn`, `/pan:learn --optimize`); auto-creates day-scoped trace session |
+| `pan-guard.js` | PreToolUse (Gemini CLI: BeforeTool; Copilot CLI: preToolUse) | Reports, or under `hooks.guard: enforce` denies, a credential written into a file, a direct write to PAN's state and a judge writing outside the planning tree; reports undeclared test edits (program A7, A7b) |
+| `pan-stop-guard.js` | Stop (Copilot CLI: agentStop; Gemini CLI: AfterAgent) | Blocks a session stop once when the auto-advance chain dropped at a phase boundary (autonomy armed in config, no failure/gaps/blocker in state, roadmap phases unbuilt) and instructs the agent to continue the chain; fail-open, one-shot, escape hatch `workflow.stop_guard: false` — see `docs/HOOKS.md` |
+| `pan-state-reinject.js` | SessionStart, matcher `compact` (Gemini CLI: PreCompress, then AfterTool; Copilot CLI: preCompact, then postToolUse) | After a context compaction, injects the phase, plan, status and stop point from `state.md` as `additionalContext`; on Gemini and Copilot in two steps, a marker before the compaction and the block on the next tool result; silent without work in flight, never writes into the project (the marker sits in the per-user temp directory) — see `docs/HOOKS.md` |
+
+The statusline hook produces metrics; the context monitor consumes them. They communicate through a bridge file (`<os-tmpdir>/pan-hooks-{uid}/claude-ctx-{session_id}.json`, a per-user 0700 dir) to avoid coupling. Where no fresh bridge exists (a headless `claude -p` run renders no status line), the monitor reads the session transcript the hook payload names instead. The two SubagentStop hooks (cost-logger and trace-logger) fire in parallel after every sub-agent completion (recording nothing for Claude Code's own helper agents, which carry no agent type and no transcript) and write to independent log files.
+
+**Runtime support:** Claude Code and Gemini CLI register hooks in `settings.json`, each in its own event vocabulary — Gemini's names differ (`AfterAgent` for the stop guard), and Gemini runs the update check, the guard (`BeforeTool`), the stop guard, and the state re-injection in two steps (`PreCompress` leaves a marker, the next `AfterTool` injects the position, because no Gemini post-compaction event adds context). No Gemini hook sees context usage or a subagent's completion, so the context monitor and the loggers do not run there. The context monitor is registered on Claude Code only: its numbers come from Claude Code's status-line bridge or a Claude-shaped transcript, so Codex and Copilot CLI get no `PostToolUse`/`postToolUse` entry for it. Copilot CLI registers hooks in `.github/hooks/pan.json` (its `version: 1` schema with `type: "command"` entries and `sessionStart`/`preToolUse`/`postToolUse`/`preCompact`/`subagentStop`/`agentStop` events, with the state re-injection in the same two steps as on Gemini, `preCompact` then `postToolUse`; since June 2026 — not `config.json`; Copilot also runs the hooks in `.claude/settings.json`, so where both are installed the `.github/hooks` copies defer to the Claude registration and each hook runs once). Codex registers hooks in `.codex/hooks.json` (Claude-compatible PascalCase events, PAN entries merged non-destructively alongside any user hooks; loads once the project is trusted). The Copilot statusline registers in the documented settings read paths — `~/.copilot/settings.json` (global) or `.github/copilot/settings.json` (repo-level) — and is experimental on Copilot's side (`copilot --experimental`). OpenCode runs no command hooks; PAN installs one plugin there, `.opencode/plugins/pan-wizard.js`, whose `experimental.session.compacting` hook adds PAN's position to the compaction prompt (see `docs/HOOKS.md`).
+
+### Installer
+
+**Location:** `bin/install.js`
+
+Interactive CLI that copies commands, agents, hooks, and core library to the correct locations for each of the 5 supported runtimes. Handles format conversion at install time — no runtime conversion needed.
+
+| Runtime | Target Directory (Global) | Target Directory (Local) | Format |
+|---------|--------------------------|-------------------------|--------|
+| Claude Code | `~/.claude/` | `.claude/` | `commands/pan/*.md`, `agents/*.md` |
+| OpenCode | `~/.config/opencode/` | `.opencode/` | `commands/*.md`, `agents/*.md` |
+| Gemini CLI | `~/.gemini/` | `.gemini/` | `commands/pan/*.toml`, `agents/*.md` |
+| Codex | `~/.codex/` | `.codex/` | `.agents/skills/pan-*/SKILL.md` (shared tree, outside config dir), `agents/*.toml` |
+| Copilot CLI | `~/.copilot/` | `.github/` | `skills/pan-*/SKILL.md`, `agents/*.agent.md` |
+
+**Install-time conversions:**
+- **Codex:** Commands converted to `SKILL.md` format with skill adapter headers; hooks registered in `.codex/hooks.json` (Codex has supported hooks since 2026-06)
+- **Copilot CLI:** Commands converted to `SKILL.md` with YAML frontmatter; agents converted to `.agent.md` with tools list; hooks registered in `.github/hooks/pan.json` (`version: 1` schema, `type: "command"` entries); tool names mapped (Claude → Copilot CLI: `Read→read`, `Bash→bash`, `Grep→search`, `WebSearch→web`, `Task→agent`, etc.)
+- **OpenCode:** Slash command prefix converted from `/pan:` to `/pan-`
+
+---
+
+## Data Flow
+
+### Example: `/pan:plan-phase 1`
+
+A complete trace from user input to approved plans:
+
+```text
+User                  Command                 Workflow
+  |                     |                       |
+  |  /pan:plan-phase 1  |                       |
+  |-------------------->|                       |
+  |                     |  read plan-phase.md   |
+  |                     |---------------------->|
+  |                     |                       |
+  |                     |     pan-tools.cjs     |    Core Library
+  |                     |     init plan-phase   |        |
+  |                     |     "1"               |        |
+  |                     |       +--------------------------->|
+  |                     |       |  JSON: paths, config,  |  |
+  |                     |       |  model assignments     |  |
+  |                     |       |<---------------------------|
+  |                     |                       |
+  |                     |  spawn (opt-in)       |    Agents
+  |                     |  pan-phase-researcher |        |
+  |                     |       +--------------------------->|
+  |                     |       |  write research.md     |  |
+  |                     |       |<---------------------------|
+  |                     |                       |
+  |                     |  spawn pan-planner    |        |
+  |                     |  with state.md +      |        |
+  |                     |  roadmap slice +      |        |
+  |                     |  context.md +         |        |
+  |                     |  research.md          |        |
+  |                     |       +--------------------------->|
+  |                     |       |  create plan.md        |  |
+  |                     |       |<---------------------------|
+  |                     |                       |
+  |                     |  spawn                |        |
+  |                     |  pan-plan-checker     |        |
+  |                     |       +--------------------------->|
+  |                     |       |  pass / fail           |  |
+  |                     |       |<---------------------------|
+  |                     |                       |
+  |                     |  if fail: loop back   |
+  |                     |  to planner (1 or 2x) |
+  |                     |                       |
+  |  Plans approved     |                       |
+  |<--------------------|                       |
+```
+
+**Step by step:**
+
+1. User types `/pan:plan-phase 1`
+2. Claude reads `commands/pan/plan-phase.md`
+3. Command references workflow: `pan-wizard-core/workflows/plan-phase.md`
+4. Workflow calls `pan-tools.cjs init plan-phase "1"` to bootstrap context
+5. pan-tools returns JSON with all file paths, config, and model assignments
+6. Only when research was asked for (`--research`, or `workflow.research: true`, off by default): the workflow writes the phase's open questions and spawns one `pan-phase-researcher` to answer them
+7. Researcher writes research.md (`pan-tools research check` verifies it); if Nyquist is enabled the workflow then writes validation.md from the template using the researcher's Validation Architecture section
+8. On a lean phase (`pan-tools size phase` — every requirement precisely specified) the engine writes and checks the plans itself (`size phase-plan`, `size plan-check`) and steps 8–11 run only if it declines. Otherwise the workflow spawns `pan-planner` with state.md + the phase's roadmap slice (`XX-roadmap-slice.md`, from `pan-tools roadmap slice <N> --write`) + context.md + research.md
+9. Planner creates plan.md files (typically 2-3 per phase)
+10. Workflow spawns `pan-plan-checker` to validate plans across multiple dimensions
+11. If checker finds blockers, loop back to planner with feedback (`MAX_CHECKS` in `plan-phase.md`: 2 checks, one revision, on the sized ceremony; 3 checks, two revisions, under the `quality` profile, `workflow.ceremony: full` or `--quality`)
+12. Plans approved — phase is ready for `/pan:exec-phase`
+
+### Example: `/pan:exec-phase 1`
+
+```text
+User                  Workflow                   Agents
+  |                     |                          |
+  |  /pan:exec-phase 1  |                          |
+  |-------------------->|                          |
+  |                     |  init execute-phase "1"  |
+  |                     |  → JSON: plans           |
+  |                     |  phase-plan-index "1"    |
+  |                     |  → JSON: waves           |
+  |                     |  test run --baseline     |
+  |                     |                          |
+  |                     |  Wave 1 (parallel):      |
+  |                     |    pan-executor Plan-01 ----------->| commit
+  |                     |    pan-executor Plan-02 ----------->| commit
+  |                     |                          |
+  |                     |  Wave 2 (sequential):    |
+  |                     |    pan-executor Plan-03 ----------->| commit
+  |                     |                          |
+  |                     |  Post-execution:         |
+  |                     |    pan-reviewer ---------------------->|
+  |                     |    → XX-review.md        |          |
+  |                     |    pan-verifier ---------------------->|
+  |                     |    → verification.md     |          |
+  |                     |  phase complete "1"      |
+  |                     |  → phase gate (enforce)  |
+  |                     |                          |
+  |  Phase complete     |                          |
+  |<--------------------|                          |
+```
+
+---
+
+## Module Dependency Graph
+
+```text
+pan-tools.cjs (CLI entry point — routes to all modules)
+  │
+  │  LAYER 1: Foundation (no internal deps)
+  ├── constants.cjs
+  ├── planning-root.cjs   (ADR-0043 — which .planning tree a command acts on)
+  ├── lock.cjs            (ADR-0030 — advisory file locking, used by state.cjs)
+  │
+  │  LAYER 2: Core (depends on constants, utils + Node.js builtins; roadmap-compact lazily)
+  ├── core.cjs
+  │     ├── constants.cjs
+  │     ├── utils.cjs (planningPath / planningRel)
+  │     └── roadmap-compact.cjs (lazy, inside a function — a compacted phase's section)
+  │
+  │  LAYER 3: Utilities
+  ├── utils.cjs
+  │     ├── constants.cjs
+  │     ├── planning-root.cjs
+  │     └── core.cjs (lazy, inside a function — comparePhaseNum)
+  │
+  │  LAYER 4: Functional modules
+  ├── frontmatter.cjs
+  │     ├── core.cjs
+  │     └── constants.cjs
+  │
+  ├── config.cjs
+  │     ├── core.cjs
+  │     ├── constants.cjs
+  │     └── utils.cjs
+  │
+  ├── context-budget.cjs
+  │     ├── core.cjs
+  │     ├── utils.cjs
+  │     ├── constants.cjs
+  │     └── cost.cjs (lazy)
+  │
+  ├── roadmap.cjs
+  │     ├── core.cjs
+  │     ├── constants.cjs
+  │     ├── utils.cjs
+  │     └── roadmap-compact.cjs (lazy)
+  │
+  ├── state.cjs
+  │     ├── core.cjs
+  │     ├── frontmatter.cjs
+  │     ├── constants.cjs
+  │     ├── utils.cjs
+  │     ├── lock.cjs
+  │     └── memory-optimize.cjs (lazy)
+  │
+  ├── template.cjs
+  │     ├── core.cjs
+  │     ├── constants.cjs
+  │     ├── utils.cjs
+  │     └── frontmatter.cjs
+  │
+  ├── verify.cjs (facade)
+  │     ├── core.cjs
+  │     ├── frontmatter.cjs
+  │     ├── state.cjs
+  │     ├── constants.cjs
+  │     ├── utils.cjs
+  │     ├── planning-root.cjs, foreign-planning.cjs
+  │     ├── config.cjs (also lazily, for the defaults), links.cjs (lazy)
+  │     ├── roadmap.cjs (roadmapRequirementIds — the --repair requirements sync)
+  │     ├── test-gate.cjs (lazy — the recorded test run for reconcile, a full run for `validate health --full`)
+  │     └── verify-{drift,retro,deploy,preflight,scope}.cjs (re-exported)
+  │
+  ├── phase.cjs (facade)
+  │     ├── core.cjs
+  │     ├── frontmatter.cjs
+  │     ├── state.cjs
+  │     ├── constants.cjs
+  │     ├── utils.cjs
+  │     ├── roadmap.cjs
+  │     ├── phase-gate.cjs (lazy — `phase complete` runs the gate first)
+  │     └── phase-remove.cjs (re-exported)
+  │
+  ├── milestone.cjs
+  │     ├── core.cjs
+  │     ├── frontmatter.cjs
+  │     ├── state.cjs
+  │     ├── constants.cjs
+  │     └── utils.cjs
+  │
+  │  LAYER 5: Aggregator modules (depend on multiple Layer 4 modules)
+  ├── commands.cjs
+  │     ├── core.cjs
+  │     ├── frontmatter.cjs
+  │     ├── constants.cjs
+  │     ├── utils.cjs
+  │     ├── context-budget.cjs
+  │     ├── planning-root.cjs
+  │     ├── verify-scope.cjs (verificationFreshness)
+  │     ├── hygiene.cjs (lazy — compareVersions)
+  │     ├── cost.cjs (lazy — the ledger path the commit guard exempts)
+  │     └── commands-learnings.cjs (re-exported)
+  │
+  ├── focus.cjs
+  │     ├── core.cjs
+  │     ├── constants.cjs
+  │     ├── frontmatter.cjs
+  │     ├── roadmap.cjs
+  │     ├── commands.cjs
+  │     ├── utils.cjs
+  │     ├── cost.cjs (weeklyLimitStop; also lazily)
+  │     ├── memory-optimize.cjs (lazy)
+  │     └── phase-report.cjs (lazy)
+  │
+  ├── init.cjs
+  │     ├── core.cjs
+  │     ├── constants.cjs
+  │     ├── utils.cjs
+  │     ├── frontmatter.cjs
+  │     ├── phase.cjs
+  │     ├── verify-plan-set.cjs (plan_check / plan_drift)
+  │     ├── codebase.cjs
+  │     ├── planning-root.cjs
+  │     └── foreign-planning.cjs
+  │
+  │  Evidence loop (ADR-0049)
+  ├── verdict.cjs        (pure; depends on: crypto only)
+  ├── findings.cjs       (depends on: core, utils, verdict; optimize, test-gate and verify-plan-set lazily)
+  │
+  │  LAYER 6: Spec B v2 modules, with the older codebase.cjs and memory.cjs
+  ├── bus.cjs            (depends on: core, utils)
+  ├── cost.cjs           (depends on: core, utils — shared infrastructure: read by commands, context-budget, cost-rebuild, focus, hud, hygiene, memory, optimize, phase-report, preview, usage)
+  ├── preview.cjs        (depends on: utils, frontmatter, verify; core, constants, cost and roadmap lazily — the last two for the cost forecast and phase dependencies)
+  ├── review-deep.cjs    (depends on: core, utils, bus, verdict — a report's pan-verdict block)
+  ├── knowledge.cjs      (depends on: core, utils, memory)
+  ├── whatif.cjs         (depends on: core, utils)
+  ├── codebase.cjs       (depends on: core, constants, utils — read by init)
+  ├── memory.cjs         (depends on: core, constants, utils; cost, memory-optimize, findings and optimize lazily — read by knowledge, verify-retro, hygiene, memory-optimize, optimize, learn-lint)
+  │
+  │  LAYER 7: optimization, git, distill
+  ├── optimize.cjs       (depends on: core, utils; cost and memory lazily — recordLesson, citationProblem)
+  ├── git.cjs            (depends on: core, commands — for runCommitSafetyChecks reuse)
+  ├── distill.cjs        (depends on: core, utils)
+  │
+  │  LAYER 8: bot army (ADR-0032/0033/0034/0035) — lock.cjs (ADR-0030, concurrency) is drawn in Layer 1
+  ├── squads.cjs         (depends on: core — registry, no agent/exec coupling)
+  ├── worktree.cjs       (depends on: core — git worktree lifecycle)
+  ├── campaign.cjs       (depends on: core, constants, utils — schedule descriptor)
+  ├── hud.cjs            (depends on: core, constants, utils, squads, campaign, worktree, cost — read-only aggregating view)
+  │
+  │  LAYER 9: skill alignment, hygiene
+  ├── skill-align.cjs    (depends on: core, constants, knowledge — scoreRelevance reuse, learn-index — topics)
+  ├── hygiene.cjs        (depends on: core, constants, utils, memory — compaction, cost — suspect-record quarantine, context-budget, planning-root, state-compact and roadmap-compact (lazy), foreign-planning)
+  │
+  │  LAYER 10: the cached-context bound (ADR-0044) and foreign-tree detection (2026-09) — planning-root.cjs (ADR-0043) sits in Layer 1
+  ├── state-compact.cjs  (depends on: core, constants, utils; state lazily — writeStateMd; read lazily by hygiene)
+  ├── foreign-planning.cjs (depends on: constants — FOREIGN_PLANNING_MARKERS, utils — planningPath; consumed by hygiene, verify, init)
+  ├── roadmap-compact.cjs (depends on: core, constants, utils; read lazily by core, roadmap and phase-report for a compacted phase's section, and by hygiene to offer and run the compaction)
+  │
+  │  Modules the layers above do not draw
+  ├── memory-optimize.cjs (depends on: core, utils, state, memory; read by memory-rebuild, and lazily by state, memory and focus)
+  ├── memory-rebuild.cjs (depends on: core, utils, state, agents-md, memory-optimize)
+  ├── agents-md.cjs      (no internal deps; read by memory-rebuild and bin/install-lib.cjs)
+  ├── phase-report.cjs   (depends on: core, constants, utils, frontmatter, verify, hud, cost; roadmap-compact lazily; read lazily by focus)
+  ├── cost-rebuild.cjs   (depends on: core, utils, cost)
+  ├── links.cjs          (depends on: core, frontmatter, doc-lint/walk.js; read lazily by verify)
+  ├── doc-lint.cjs       (depends on: core, doc-lint/*.js)
+  ├── learn-lint.cjs     (memory lazily, for citationProblem; read by learn-index)
+  ├── learn-index.cjs    (depends on: learn-lint; read by skill-align)
+  ├── experiment.cjs     (no internal deps; read by runner)
+  ├── runner.cjs         (depends on: experiment)
+  ├── suggest.cjs        (no internal deps; the dispatcher's error path)
+  ├── phase-gate.cjs     (depends on: core, constants, utils; verdict, findings, verify, verify-scope, verify-integrity, test-gate and optimize lazily; read by phase)
+  ├── test-gate.cjs      (depends on: core, utils; read by findings, verify, verify-red, mutate, phase-gate)
+  ├── verify-integrity.cjs (depends on: core, constants, frontmatter, verify-scope; read by verify-red, mutate, phase-gate)
+  ├── verify-red.cjs     (depends on: core, test-gate, verify-integrity, verify-scope; read by mutate)
+  ├── mutate.cjs         (depends on: core; test-gate, verify-integrity and verify-red lazily)
+  ├── verify-plan-set.cjs (depends on: core, constants, utils, frontmatter, roadmap, phase; findings and verdict lazily; read by init, plan-lint, findings)
+  ├── plan-lint.cjs      (depends on: core, constants, verify-plan-set, verify-scope)
+  ├── research-lint.cjs  (depends on: core, verify-scope)
+  ├── usage.cjs          (depends on: core, cost, utils)
+  └── re-exported submodules: verify-drift (core, constants, utils), verify-retro (core, frontmatter, constants, utils; memory lazily), verify-deploy (core), verify-preflight (core, state, constants, utils; focus lazily), verify-scope (core, frontmatter, constants, utils; roadmap lazily; also read by commands, verify-integrity, verify-red, phase-gate, plan-lint, research-lint), phase-remove (core, state, constants, utils), commands-learnings (core, frontmatter, constants, utils)
+```
+
+**Key observations:**
+- `constants.cjs` is the foundation for the planning-file modules (core, utils, config, state, phase, verify, focus, init …); many leaf modules reach it only through core/utils, and `planning-root.cjs` and `lock.cjs` require nothing internal
+- `core.cjs` depends on `constants.cjs` and `utils.cjs` (plus Node.js builtins, and `roadmap-compact.cjs` lazily, to read a compacted phase's section back from the history) and provides the `output()`/`error()` I/O contract — including the point where nearly every exit code is decided (doc-lint's `--raw` branches, `state load --raw` and `--help` exit directly): `error()` is stderr + exit 1, while `output()` derives its code from the payload (a truthy top-level key in the **error family** — `error` or `*_error` — exits non-zero) unless a command passes one explicitly or opts out with `EXIT_OK`. Sites that report a failure as `<verb>: false` carry an error-family key so this one derivation covers them too, including payloads built by pure functions elsewhere and passed straight through by the dispatcher. See CLI-REFERENCE "Error Shape".
+- `frontmatter.cjs` is widely depended upon (state, verify, phase, milestone, commands, template all use it)
+- Of the modules in Layers 6 and 7 only `preview`, `review-deep`, `whatif`, `git` and `distill` are leaves: `cost.cjs` and `memory.cjs` are shared infrastructure with many consumers, `bus.cjs` feeds review-deep, `codebase.cjs` feeds init, `knowledge.cjs` feeds skill-align and `optimize.cjs` feeds findings and memory (lazily, for trace events) — remove those with care
+- `git.cjs` reuses `runCommitSafetyChecks` from `commands.cjs`; `optimize.cjs` reads `cost.cjs`; `optimize.cjs` and `distill.cjs` also use `utils.cjs` (`git.cjs` does not)
+- Cycles exist — `core ⇄ utils`, `core ⇄ roadmap-compact` (with `utils` on the same loop), `state ⇄ memory-optimize`, `memory ⇄ memory-optimize`, `memory ⇄ optimize` (with `findings` on the same loop), `state-compact → state → … → commands → hygiene → state-compact`, `findings ⇄ verify-plan-set` (with `phase → phase-gate → findings` on the same loop) and `verify → verify-preflight → focus → phase-report → verify` — all but the first two meet in one larger knot, and each is broken by a lazy in-function `require`: the load-time (top-level) require graph is a DAG
+- `pan-tools.cjs` requires every module with a CLI surface (the foundation and the re-exported submodules load transitively) but is itself a script (no `module.exports`)
+
+---
+
+## Cross-Platform Runtime Support
+
+PAN installs to 5 runtimes with format conversion at install time. The core workflow is identical across all — only the file format and invocation syntax differ.
+
+### Command Syntax by Runtime
+
+| Runtime | Prefix | Example |
+|---------|--------|---------|
+| Claude Code | `/pan:` | `/pan:new-project` |
+| OpenCode | `/pan-` | `/pan-new-project` |
+| Gemini CLI | `/pan:` | `/pan:new-project` |
+| Codex | `$pan-` | `$pan-new-project` |
+| Copilot CLI | `/pan-` | `/pan-new-project` |
+
+### File Format by Runtime
+
+| Component | Claude / OpenCode / Gemini | Codex | Copilot CLI |
+|-----------|---------------------------|-------|-------------|
+| Commands | `commands/pan/*.md` (Claude) · `commands/pan-*.md` (OpenCode) · `commands/pan/*.toml` (Gemini) | `.agents/skills/pan-*/SKILL.md` | `skills/pan-*/SKILL.md` |
+| Agents | `agents/*.md` | `agents/*.toml` | `agents/*.agent.md` |
+| Hooks | `hooks/*.js` in `settings.json` (Claude, Gemini) · OpenCode: no command hooks, the plugin `plugins/pan-wizard.js` | `hooks/*.js` in `.codex/hooks.json` (since 2026-06) | `hooks/*.js` in `.github/hooks/pan.json` |
+| Config | `settings.json` (Claude, Gemini) · `.mcp.json` at the repo root (Claude's MCP registration) · `opencode.json` (OpenCode) | `config.toml` (PAN writes nothing there; the installer prints an MCP snippet to add by hand) | `.github/copilot/settings.json` (statusline) · `.github/mcp.json` (MCP) · `.github/hooks/pan.json` (hooks) |
+
+### Tool Name Mapping (Copilot CLI)
+
+Copilot CLI uses different tool names than Claude Code. The installer maps them at install time:
+
+| Claude Code | Copilot CLI |
+|------------|-------------|
+| Read | read |
+| Write, Edit | edit |
+| Bash | bash |
+| Glob | glob |
+| Grep | search |
+| WebSearch, WebFetch | web |
+| TodoWrite | todo |
+| Task (Agent) | agent |
+
+### The MCP bridge — a second doorway into the same engine
+
+The five runtimes above are reached by install-time **format conversion**: the same
+command/agent content, rewritten per runtime. The MCP bridge is the **inverse** approach —
+rather than converting content *into* a host, it exposes PAN's engine *to* any MCP client.
+
+It works because `pan-tools` was already stateless: every invocation reads `.planning/`,
+writes `.planning/`, and exits. That is the shape the MCP `2026-07-28` stateless core wants,
+so the bridge reimplements nothing — it spawns a verb and returns its JSON. As the server's
+own header puts it, the CLI's JSON contract **is** the tool contract.
+
+- **Location:** `pan-wizard-core/mcp/` — under the core, so it ships with the engine to every
+  install and every runtime. Zero-dependency (the protocol is hand-rolled, not an SDK) and
+  **dual-era**: it answers both the legacy `initialize` handshake and modern per-request
+  `_meta` version negotiation with a `server/discover` probe (ADR-0041).
+- **Two surfaces, one rule.** Read-only aggregators are MCP **resources** (cheaper,
+  side-effect-free); anything actionable is a **tool** with accurate `readOnlyHint` /
+  `destructiveHint`. The dividing rule: *a resource must be readable on any project,
+  including a bare directory* — if "no data yet" is an error, it is a tool. Enumerate the
+  live surface rather than trusting a list here:
+  ```bash
+  grep -oE "uri: 'pan://[a-z]+'" pan-wizard-core/mcp/tool-registry.cjs
+  grep -oE "name: 'pan_[a-z_]+'" pan-wizard-core/mcp/tool-registry.cjs pan-wizard-core/mcp/native-tools.cjs
+  ```
+- **Safety is structural, not advisory:** shell-less `execFile` with an argv array, the verb
+  always chosen from the registry allowlist, every argument validated against a whitelist
+  regex with a length bound (except `attempt`, an integer range; the per-call `cwd`, an existing absolute directory; and `pan_next_action`'s phase snapshot and `pan_request_merge`'s CI/verify flags, which never reach a process argument), a `FORBIDDEN_VERB` guard that refuses to expose any
+  history-rewriting or force git op (recovery is revert-only), and a merge gate that requires
+  an out-of-band human token an agent-supplied value cannot satisfy.
+- **The project root travels with the call.** Every tool accepts an optional `cwd` — the
+  absolute path of the project to operate on, validated as an existing directory and used for
+  that call only; without it the server falls back to `PAN_PROJECT_ROOT` when set, else the directory it was started in.
+  Resources never take it: their argv is static, which is the whole of their safety argument.
+  The reason is the Agent Plugins format (ADR-0045): its clients launch a stdio server in the
+  **plugin root** by default, so a server that trusted its own cwd would read `.planning/`
+  from inside the plugin cache and report an empty project — cleanly. The decoration is applied
+  centrally in the registry, so a tool added later cannot miss it.
+- **Registration** is per-runtime and non-destructive; the verified path/shape table is
+  `MCP_REGISTRATION` in `bin/install-lib.cjs`, deliberately sitting beside `HOOK_EVENT_MAP`
+  because it is the same class of problem. Paths there are **config-dir-relative**, except Claude's `.mcp.json`, which sits at the repo root. Codex and
+  Claude-global are intentionally *not* written — the table records why for each.
+
+#### Experimental: ZCode via PAN-Z (preview)
+
+[ZCode](https://zcode.z.ai) (z.ai's GLM harness, **beta**) has no custom slash-commands,
+hooks, or project config, so it cannot host the converted content at all — MCP is the only
+interface it speaks. **PAN-Z** (`pan-zcode/`) is therefore a **consumer of the shared bridge
+above**, not the owner of it: it ports PAN's agents to ZCode subagents and emits an MCP
+registration pointing at `pan-wizard-core/mcp/server.cjs`. It remains a **separate, opt-in
+subsystem with its own installer** (`pan-zcode/bin/install-zcode.js`) — deliberately **not** a
+sixth target of `bin/install.js` — and its ZCode-runtime behaviors are still gated behind an
+empirical verify spike (see `pan-zcode/KNOWN-BETA-RISKS.md`).
+
+---
+
+## Key Design Decisions
+
+### 1. CommonJS (.cjs), not ESM
+
+Node's built-in `node:test` runner, which PAN's own suite uses, and the hook copy pipeline work more reliably with CommonJS. All library modules use the `.cjs` extension to make this explicit and avoid ambiguity with package.json `type` settings.
+
+### 2. Zero Runtime Dependencies
+
+The core library uses only Node.js built-in modules (`fs`, `path`, `child_process`, `os`, `crypto`; the CLI entry also loads `module` for Node's compile cache). This keeps installation fast, eliminates supply chain risk, and ensures the tool works offline after install.
+
+### 3. Markdown-as-Code
+
+Commands, workflows, agents, and references are all Markdown files. They are not executed by a runtime — they are "executed" by being read into the AI's context window. This means:
+
+- No parser to maintain
+- Authors write in natural language with XML structure markers
+- Version control diffs are human-readable
+- Any text editor can modify the system's behavior
+
+### 4. JSON CLI Bridge
+
+Workflows call `pan-tools.cjs` via bash and parse the JSON output. This keeps the Node.js layer thin and independently testable. The CLI never maintains state between invocations — every call is stateless, reading from and writing to `.planning/` files.
+
+### 5. Cross-Platform Path Handling
+
+`toPosix()` in `core.cjs` normalizes all file paths to forward slashes in JSON output. File-based input (reading arguments from files rather than command-line strings) avoids `$` shell expansion issues across Windows, Linux, and macOS.
+
+### 6. Large Output Handling
+
+When JSON output from `pan-tools.cjs` exceeds approximately 50KB, it is written to a temporary file and the file path is returned with an `@file:` prefix. This prevents shell buffer overflow and keeps context consumption predictable.
+
+### 7. Model Resolution via "inherit"
+
+`resolveModelInternal()` / `resolveModelDetailed()` in `core.cjs` (behind `resolve-model`) return `"inherit"` for reasoning-tier agents instead of a literal model string like `"opus"`. This lets the runtime use whatever top-tier model the user has configured in their environment, rather than hard-coding a specific model identifier.
+
+### 8. Install-Time Format Conversion
+
+All format differences between runtimes (SKILL.md vs commands/*.md, .agent.md vs .md, tool name mappings, hook config format) are resolved at install time by the installer. Agents never need to know which runtime they're running on — the format is already correct. The core library reads the runtime it is running under in two places, both from its own install path: `hostRuntime()` in `core.cjs`, which recognises an OpenCode install so `resolve-model` returns OpenCode's `provider/model` ids, and `panVersionInfo()` in `commands.cjs`, which names the install directory so `version --check` reads that runtime's update-check cache.
+
+### 9. File-Mediated Agent Communication
+
+Agents never communicate directly. All data flows through `.planning/` files on disk. This makes every intermediate artifact inspectable, enables parallel execution (researchers, mappers, executors), and means failed agents can be re-run without losing sibling work. See [AGENTS.md](AGENTS.md#how-agents-collaborate) for details.
+
+### 10. Layered Architecture with Strict Boundaries
+
+- Commands (Layer 1) delegate substantive logic to workflows; self-contained commands (`debug`, `phase-budget`, the `focus-*` family) call `pan-tools` directly for bootstrap data
+- Workflows (Layer 2) never import agent `.md` files — they spawn agents via Task tool
+- Agents (Layer 3) never import other agents — they communicate via `.planning/` files
+- Core modules (Layer 4) call `output()` only on the CLI path: from `cmd*` entry points and a few CLI-only handlers they dispatch to (`focusAuto*` in focus.cjs, `renderHealthReport` in commands.cjs, `_notGitRepo`/`_noRemote` in git.cjs)
+- No upward dependencies (a core module never requires pan-tools.cjs)