pan-wizard 3.35.0 → 3.37.0

package/docs/decisions/ADR-0020-ai-drift-prevention.md

@@ -0,0 +1,55 @@
+# ADR-0020: AI Drift Prevention System
+
+## Status
+Accepted (shipped in v2.6.0 — 2026-03-08)
+
+## Context
+AI coding assistants gradually deviate from project conventions during extended sessions ("AI drift"). This manifests as wrong patterns (console.log instead of output()), forgotten naming conventions, scope creep, and lost project state. PAN Wizard already has the strongest drift prevention infrastructure in the market — state tracking, deviation rules, verification, cross-session resume — but lacks active enforcement and quantitative measurement. No competitor tool (Aider, Cursor, Cline, Windsurf, Copilot WS) offers built-in drift scoring. The industry is shifting from code generation speed to code quality in 2026, making this strategically timed.
+
+## Decision
+Add a `drift-check` command to pan-tools that:
+1. Loads convention rules from `.planning/codebase/CONVENTIONS.md` and `CLAUDE.md`
+2. Parses conventions into matchable rules (regex patterns, anti-patterns)
+3. Diffs changed files (via `git diff --name-only`) against those rules
+4. Produces a quantitative Drift Score (0.0-1.0) with per-file violations
+5. Outputs JSON with violations, scores, and human-readable summary
+
+Implementation is zero-dependency (regex-based matching), read-only (no code modification), and fast (<200ms). Built-in convention rules cover PAN Wizard's own patterns. Custom rules loaded from project-specific CONVENTIONS.md.
+
+### v0 (MVP): `drift-check` command + rule parser + scoring (20 points)
+### v1: Pre-commit hook + health --drift + verify integration (16 points)
+### v2: Cross-session trends + auto-discovery + custom rule DSL (30 points)
+
+## Consequences
+
+### Positive
+- PAN becomes the only tool with quantitative drift measurement
+- Convention enforcement moves from passive (advisory) to active (measurable)
+- Builds on existing infrastructure (verify.cjs, standards system, git integration)
+- Zero new dependencies
+- Enables cross-session drift trend analysis (v2)
+
+### Negative
+- Regex-based matching has false positive risk (mitigated by severity levels and thresholds)
+- Requires `.planning/codebase/CONVENTIONS.md` to exist for custom rules (built-in rules as fallback)
+- Convention parsing from markdown is heuristic, not semantic (mitigated by structured format)
+
+### Neutral
+- Adds one new pan-tools subcommand (`drift-check`)
+- Read-only — no state mutations in v0
+- Optional integration — doesn't change existing command behavior
+
+## Options Considered
+
+1. **External tool integration (CodeScene/SonarQube)** — Rejected: adds dependencies, SaaS lock-in, violates zero-dep principle
+2. **AST-based analysis** — Rejected: requires parser dependencies (acorn, etc.), too heavyweight for convention checking
+3. **Regex-based convention matching (chosen)** — Zero deps, fast, sufficient accuracy for convention-level checking
+4. **Human-in-the-loop only (Cline model)** — Rejected: too much friction, doesn't scale to autonomous execution
+5. **No action (status quo)** — Rejected: competitive gap, user-stated need, strategic timing
+
+## Links
+- Spec: `docs/specs/ai_drift_prevention_featureai.md`
+- Related: verify.cjs (validation infrastructure)
+- Related: config.cjs (standards system)
+- Related: ADR-0010 (standards integration)
+- Related: ADR-0014 (internal cleanup/code quality)

package/docs/decisions/ADR-0021-codebase-mapper-v2.md

@@ -0,0 +1,76 @@
+---
+require-code-mention: true
+---
+
+# ADR-0021: Codebase Mapper v2 — Advanced Codebase Import & Analysis
+
+## Status
+Accepted (shipped in v2.7.0 — 2026-03-08)
+
+## Context
+
+`/pan:map-codebase` is the gateway command for brownfield projects — the first experience users have when importing an existing codebase into PAN. The current implementation (v1, ADR-0008) spawns 4 parallel agents that produce 7 template-driven documents using bash grep patterns. This approach has three critical limitations:
+
+1. **No relationship awareness** — No module dependency graph, no circular dependency detection, no understanding of which modules depend on which. Users must manually trace imports across hundreds of files.
+
+2. **No best-practices assessment** — No detection of which patterns the codebase follows (error handling, testing, naming, security). Users discover convention violations during execution, not during planning.
+
+3. **Shallow analysis** — Hardcoded bash grep patterns (`grep -r "import.*stripe"`) are language-agnostic but fragile. They miss most real-world import patterns and provide no structural understanding.
+
+Competitors like Aider (tree-sitter AST repo-maps) and DeepWiki (auto-generated wikis) set user expectations for deep codebase analysis. PAN must match this depth while maintaining its zero-dependency constraint.
+
+Additionally, the user requests lowercase output filenames (stack.md not STACK.md) to align with PAN's existing `.planning/` lowercase convention.
+
+## Decision
+
+Redesign the codebase mapper with:
+
+1. **New `codebase.cjs` core module** — Language-aware import/export parsing using regex patterns (not AST) for JS/TS (v0), Python, Go, Rust, Java, C# (v1). Builds in-memory dependency graphs, detects circular dependencies, finds entry points and orphan modules.
+
+2. **6 focus areas** (was 4) — Add `relationships` (module dependency graph) and `practices` (best-practices detection) agents, producing `relationships.md` and `best-practices.md`.
+
+3. **9 output documents** (was 7) — All with lowercase filenames.
+
+4. **Pre-computed analysis** — Core module runs import analysis and language detection BEFORE agents spawn. Results passed to agents as structured data, avoiding expensive LLM re-scanning.
+
+5. **3 new CLI commands** — `codebase analyze-imports`, `codebase detect-languages`, `codebase best-practices` for standalone use and debugging.
+
+6. **Backward-compatible migration** — Consumers check lowercase first, fallback to UPPERCASE.
+
+## Consequences
+
+### Positive
+- Dependency graphs give users immediate architectural understanding of brownfield codebases
+- Best-practices assessment enables prioritized technical debt cleanup in roadmaps
+- Pre-computed analysis means agents start with facts, not discovery — higher quality output
+- Lowercase filenames align with PAN's existing convention
+- Zero runtime dependencies maintained (regex-only analysis)
+- Same command, richer output — zero learning curve
+
+### Negative
+- Regex-based parsing misses some complex patterns (re-exports, dynamic imports, computed requires)
+- 6 agents instead of 4 increases token cost per mapping run
+- Migration period where both UPPERCASE and lowercase filenames must be supported
+- New `codebase.cjs` module adds maintenance surface
+
+### Neutral
+- Template structure remains the same (enhanced, not replaced)
+- Agent architecture remains the same (parallel agents writing directly)
+- Workflow pattern remains the same (orchestrator spawns agents, collects confirmations)
+
+## Options Considered
+
+1. **tree-sitter AST parsing** (Aider approach) — Most accurate, supports 30+ languages. Rejected: adds ~5MB WASM runtime dependency, violates zero-dep constraint.
+
+2. **LLM-only analysis** (DeepWiki approach) — Let agents discover everything themselves. Rejected: expensive, slow, inconsistent results, agents re-scan the same files.
+
+3. **Regex-based analysis with pre-computation** (chosen) — Core module does fast regex parsing, passes structured data to agents. Best balance of accuracy, speed, and zero dependencies.
+
+4. **Embedding-based indexing** (Cursor/Continue.dev approach) — Semantic search with vector embeddings. Rejected: requires embedding model (runtime dep), accuracy issues documented in Continue.dev community.
+
+## Links
+- Supersedes: ADR-0008 (Mermaid/TOGAF enhancement — incorporated into v2)
+- Spec: `docs/specs/codebase_mapper_v2_featureai.md`
+- Related: `pan-wizard-core/bin/lib/codebase.cjs` (new module)
+- Related: `agents/pan-document_code.md` (rewritten agent)
+- Related: `pan-wizard-core/workflows/map-codebase.md` (updated workflow)

package/docs/decisions/ADR-0022-lifecycle-completeness.md

@@ -0,0 +1,63 @@
+# ADR-0022: Lifecycle Completeness — Test Generation, Code Review, Test Gate, Retrospective
+
+## Status
+Accepted (shipped in v2.8.0 — 2026-03-08)
+
+## Context
+PAN Wizard's lifecycle has structural gaps when compared against industry SDLC frameworks (V-Model, Agile, DevOps, SAFe). Specifically:
+
+1. **Test generation is orphaned:** `/pan:phase-tests` exists but no orchestrator calls it. Users must manually discover and invoke it.
+2. **No code review stage:** Between execution (pan-executor) and verification (pan-verifier), nobody checks code quality, convention compliance, or security patterns.
+3. **Verifier doesn't run tests:** `pan-verifier` checks goals against success criteria and artifacts, but never executes the project's test suite.
+4. **No retrospective:** `/pan:milestone-audit` checks WHAT was built against requirements, but there's no process-focused analysis of HOW work was done (estimation accuracy, common gap patterns).
+
+These gaps were discovered during a systematic comparison of PAN's lifecycle against 8 industry frameworks (Waterfall, V-Model, Agile/Scrum, SAFe, DevOps/CI-CD, Shift-Left, SRE, TOGAF ADM).
+
+## Decision
+Close the V-Model right-side gap by:
+
+1. **Wire `/pan:phase-tests` into `exec-phase.md`** — auto-invoke after execution completes (step 6.5)
+2. **Create `pan-reviewer` agent** — read-only code review with quality/convention/security checks
+3. **Add review step to `exec-phase.md`** — spawn pan-reviewer after test generation (step 6.7)
+4. **Add test suite gate to `verify-phase.md`** — verifier runs `npm test` and compares before/after counts
+5. **Create `/pan:retro` command** — milestone-level retrospective analyzing estimation accuracy and gap patterns
+
+The new lifecycle becomes:
+```
+plan → exec → tests (auto) → review (auto) → verify (with test gate) → next phase
+                                                                          ↓
+milestone-done → retro → next milestone
+```
+
+## Consequences
+
+### Positive
+- PAN becomes the only AI coding tool with complete V-Model coverage
+- Test generation is no longer orphaned — automatically invoked
+- Code quality issues caught before verification, not after
+- Test regressions caught by verifier (not just goal achievement)
+- Process learning through retrospectives improves estimation over time
+
+### Negative
+- exec-phase takes longer (~1-2 min for test gen + review)
+- pan-reviewer may produce false positive warnings (tuning needed)
+- Additional agent increases installer size slightly
+
+### Neutral
+- --skip-tests and --skip-review flags provide opt-out for rapid iteration
+- Retro is a separate command, not auto-invoked (user chooses when to reflect)
+- No changes to existing command JSON schemas — purely additive
+
+## Options Considered
+
+1. **Do nothing** — Leave gaps as-is. Rejected: user discovered the gap, evidence is clear.
+2. **Just wire phase-tests** — Minimal fix. Rejected: misses review + test gate opportunities.
+3. **Full lifecycle with mandatory gates** — All stages required. Rejected: too rigid for exploratory work.
+4. **Full lifecycle with skip flags (CHOSEN)** — All stages available, skippable via flags.
+
+## Links
+- Spec: `docs/specs/lifecycle_completeness_featureai.md`
+- Gap analysis: `link_system_temp.md`
+- Related: exec-phase.md, verify-phase.md, phase-tests.md workflows
+- Related: pan-verifier, pan-executor agents
+- Related: ADR-0019 (E2E UAT testing)

package/docs/decisions/ADR-0023-opus-4-7-adoption.md

@@ -0,0 +1,89 @@
+# ADR-0023: Opus 4.7 Adoption — 1M Context, Extended Thinking, Prompt Caching, Native Skills
+
+## Status
+Accepted (shipped in v2.10.0 — 2026-04-18)
+
+> **Amended 2026-10-04 (memory optimisation, O2 follow-up): E-1's priming step is withdrawn.**
+>
+> - **It never primed anything.** `pan-tools cache prime --summary` prints the cacheable set's paths, sizes and a sha into the orchestrator's own context. A command's output cannot set `cache_control` on another agent's prompt. The host caches each agent's prompt prefix by itself, primed or not. The "40-60%" saving below was never measured. What ADR-0044 later measured was the opposite problem: cache reads were 98% of token traffic, because every agent re-read the same large files.
+> - **It also loaded more.** `exec-phase` told the orchestrator to put the cacheable set's paths in every executor's context. That is the whole roadmap and requirements, which O2 replaced with a phase's `roadmap slice`.
+> - **What changed:** the `<cache_priming>` steps are gone from `plan-phase`, `exec-phase` and `verify-phase`, and so is the matching step in `focus-exec` and `army`. `cache prime` stays as a measurement, next to `context-budget` and hygiene's `cache-context` check (ADR-0044).
+
+## Context
+PAN Wizard's architecture (through v2.9.1) was designed around Claude 3.x assumptions: 200K context windows, no native extended thinking, no prompt caching, commands delivered as slash-command `.md` files rather than discoverable skills. Opus 4.7 (GA Q2 2026) materially changes the underlying primitives:
+
+- **1M context window** — medium codebases (up to ~700K tokens) can be ingested in a single agent call.
+- **Native extended thinking** — `thinking: enabled` frontmatter with per-agent `thinking_budget`. Reasoning is visible in-band and priced per-token.
+- **Prompt caching (cache_control: ephemeral)** — input blocks with stable content get a 5-minute cache TTL. Cache hits cost ~10% of cold tokens.
+- **Native skills discovery** — Claude Code 1.x loads skills from `.claude/skills/*.md` with frontmatter-based trigger metadata, enabling auto-invocation.
+
+PAN's workflow-first orchestration model made minimal use of these primitives. Competitors (Cursor 2, Windsurf, Aider) shipped multi-agent orchestration and session memory in late 2025. Without direct Opus 4.7 integration, PAN would be out-innovated on cost/latency and on workflow intelligence.
+
+We captured the investigation in [docs/specs/opus_47_existing_enhancements_featureai.md](../specs/opus_47_existing_enhancements_featureai.md) (Spec A — 12 enhancements to existing features) and [docs/specs/opus_47_extended_features_featureai.md](../specs/opus_47_extended_features_featureai.md) (Spec B — 14 new commands/agents, deferred to v3.x).
+
+## Decision
+Ship Spec A in full as v2.10.0. Defer Spec B to v3.x as stability data arrives.
+
+Concretely, adopt the following Opus 4.7 primitives across the existing surface:
+
+1. **Prompt caching layer** (E-1). Single canonical set of cacheable files: `CACHEABLE_CONTEXT_FILES` = [`project.md`, `requirements.md`, `roadmap.md`, `state.md`, `standards.md`]. `buildCachedContext(cwd)` returns ordered blocks with a stable SHA for cache-key hit predictability. Commands (`plan-phase`, `exec-phase`, `verify-phase`, `focus-exec`) prime the cache once per invocation via `pan-tools cache prime --summary`.
+2. **Whole-project ingest** (E-2). `/pan:map-codebase` branches on `estimateRepoTokenSize(cwd)`: single-shot mode (Opus 4.7 only) at ≤700K tokens, sharded mode (6-way parallel) above. Agent `pan-document_code` has an explicit `<mode>` block so it knows which mode it's executing in.
+3. **Extended thinking** (E-3). Five verification-heavy agents enable thinking with per-agent budgets: `pan-plan-checker` (8000), `pan-verifier` (6000), `pan-integration-checker` (6000), `pan-reviewer` (4000), `pan-debugger` (8000). Installer strips these fields for non-Claude runtimes and injects a prose "think step-by-step" preamble via `translateThinkingDirective`.
+4. **Agent memory layer** (E-4). New `memory.cjs` module with append-only per-agent logs at `.planning/memory/<agent>.md`. Agent-name validated against `^[a-zA-Z0-9_-]+$` to block path traversal. Compaction bounded by `DEFAULT_MAX_ENTRIES=500`. Retrospective command (`/pan:retro --write-memory`) extracts top-N gap patterns as planner lessons.
+5. **Native skills shims** (E-5). Installer generates `.claude/skills/pan-<cmd>.md` for every command so host skills discovery surfaces them with frontmatter-declared descriptions.
+6. **Parallel-tool execution** (E-6). `classifyStageDependencies` emits waves + a `parallelism_hint` that `focus-exec` Stage 3.0 uses to instruct parallel tool calls. `pan-executor` agent gained a `<parallel_tool_use>` block: batch reads, serialize writes.
+7. **Capability-aware model routing** (E-7). `resolveModel` accepts `{context_estimate, needs_thinking, cache_warm}` hints and adjusts the profile-selected tier upward (toward reasoning) when context is large or thinking is needed, downward (toward fast) when cache is warm and context is small.
+8. **Statusline & health indicators** (E-8). Statusline renders `🧠` when thinking is active and `⚡N%` when cache hit rate is known. `context-budget` reports cacheable block count, bytes, eligible percentage, and stable SHA.
+9. **Installer capability detection** (E-9). `detectModelCapabilities(modelName)` classifies default model from settings.json; installer emits a post-install warning if the default model lacks features Spec A relies on.
+10. **Focus-auto reflection gate** (E-10). Between cycles, `determineContinuation` emits a thinking-gated prompt that lets Opus 4.7 veto the next cycle earlier than the automatic stop rules would.
+11. **Debugger hypothesis trees** (E-11). `pan-debugger` generates ≥3 hypotheses with Bayesian priors and attacks the top 2 in parallel (parallel *investigation*, not parallel *fixes*).
+12. **Oldest-batch-first ordering** (E-12 — pre-existing bugfix folded into the release). `readLatestBatch` sorts ascending so an older unfinished batch executes before a newer one.
+
+Implementation verification strategy: per-item tests, plus end-to-end scenario tests for memory persistence, skills installation, and map-codebase mode selection. Target test delta +100 to +150; actual delta was +143 (1983 → 2126).
+
+## Consequences
+
+### Positive
+- **Cost reduction**: prompt caching saves 40-60% input tokens on multi-agent phases (measurements pending in production).
+- **Better planning**: planner/verifier with extended thinking catch logic gaps before execution wastes cycles.
+- **Coherent brownfield maps**: single-shot `map-codebase` eliminates stitching artifacts (contradictory version claims, missed cross-references) on repos ≤700K tokens.
+- **Cross-phase learning**: memory layer makes conventions stick across phases without human re-prompting.
+- **Discoverable commands**: native skills frontmatter enables host auto-invocation (e.g. "when user asks X, invoke `/pan:focus-scan`").
+
+### Negative
+- **Opus 4.7 only for best results**: single-shot `map-codebase` and extended thinking require Opus 4.7. Sonnet 4.6 / Haiku 4.5 work with degraded behavior; installer warns at install time via `detectModelCapabilities`.
+- **New file on disk**: `.planning/memory/<agent>.md` files grow over time. Compaction is manual (`pan-tools memory compact <agent> [max]`) or via `/pan:retro --write-memory` bounded emission.
+- **Claude-only features**: skills shims (E-5) and native thinking frontmatter (E-3) only apply to Claude Code. Non-Claude runtimes get a prose fallback for thinking; no skills shims for Codex/Gemini/OpenCode. Copilot retains its existing directory-per-skill format rather than re-using the Claude flat shim generator.
+- **Spec surface growth**: `+16 tests` in the spec-required path (scenario tests under `tests/scenarios/opus-47-*`), bringing the scenario suite to 28 files.
+
+### Neutral / Tradeoffs considered
+- **Why not also ship Spec B (extended features) in v2.10?** Spec B adds 14 new commands + 9 new agents + a message bus, a roughly 3200-LOC delta. Shipping alongside Spec A would couple two independently-verifiable risk surfaces. Spec B waits for Spec A adoption telemetry (cache hit rates, thinking cost observed in practice) before committing to Wave 1 (bus, cost dashboard, architect command).
+- **Why a dedicated memory module and not state.md?** state.md is per-phase and has strict schema. Memory is cross-phase, append-only, agent-scoped. Conflating them would force state.md into a role it wasn't designed for (learning log vs. execution checkpoint).
+- **Why skills shims for Claude only?** Claude Code is where native skills discovery is implemented. Copilot CLI has its own skills format (directory-per-skill with `SKILL.md`) that doesn't match the flat shim shape. Reworking both runtimes to share a generator is a refactor for v3.x; the current dual implementation works.
+
+## Implementation Notes
+
+### Commit history
+- `53c5bb5` — foundation (8 items: E-1 buildCachedContext, E-4 memory.cjs, E-9 detectModelCapabilities, E-7 resolveModel extension, E-1 cache helper, E-5 buildClaudeSkillShim, E-3 translateThinkingDirective, E-10 determineContinuation, E-6 classifyStageDependencies)
+- `0f4db12` — completion (6 items: E-2 estimateRepoTokenSize, E-3 agent frontmatter, E-5 installer integration, E-8 statusline, E-9 installer integration, E-11 debugger prose)
+- `21bceec` — v2.10.0 release (runtime-aware thinking strip, CLI wrappers, command integrations, version bump, CHANGELOG)
+- `5fb2745` — deep integration (retro→memory, cache metrics in health, scenario tests)
+- Follow-up — Spec A closeout (pan-document_code Mode, profile tier tree, 3 scenario tests, this ADR)
+
+### Rollback plan
+Spec A is additive. Rollback strategy if telemetry reveals a regression:
+- **Caching**: revert `<cache_priming>` blocks in command `.md` files; `buildCachedContext` can stay in core.cjs unused.
+- **Thinking**: remove `thinking:` fields from 5 agents; installer no-ops.
+- **Memory**: delete `.planning/memory/` to reset; module stays.
+- **Skills shims**: `rm -rf .claude/skills/pan-*.md` post-install; regenerated on next install.
+- **Mode branching**: `pan-document_code` falls back to `sharded` when `mode` frontmatter is absent.
+
+No `.planning/` schema changes; no breaking CLI contracts.
+
+## Related
+
+- Spec A: [opus_47_existing_enhancements_featureai.md](../specs/opus_47_existing_enhancements_featureai.md)
+- Spec B: [opus_47_extended_features_featureai.md](../specs/opus_47_extended_features_featureai.md) (deferred)
+- ADR-0014 (internal cleanup code quality) — baseline for the stability patterns this builds on
+- ADR-0015 (focus-auto runner) — reflection gate builds on auto-runner's safety harness
+- ADR-0022 (lifecycle completeness) — retro command extended here with memory write-back

package/docs/decisions/ADR-0024-spec-b-v2-completion.md

@@ -0,0 +1,137 @@
+# ADR-0024: Spec B v2 Completion — Consolidated Extended Features Across v3.0-v3.4
+
+## Status
+Accepted (shipped 2026-04-18 through 2026-04-19)
+
+## Context
+
+Spec A (Opus 4.7 existing enhancements, ADR-0023) shipped in v2.10.0 and consumed the five core Opus 4.7 primitives (prompt caching, extended thinking, 1M context, memory, capability routing) across PAN's existing surface. With Spec A stable and producing telemetry, the question was how to ship the *extended* feature set Spec B designed.
+
+Spec B v1 ([docs/specs/opus_47_extended_features_featureai.md](../specs/opus_47_extended_features_featureai.md)) proposed 14 new commands, 9 new agents, 14 new core modules across 5 waves — a ~3200 LOC, 15-week delta. On 2026-04-18 we accepted a consolidation pass (Spec B v2, [docs/specs/opus_47_extended_features_v2_featureai.md](../specs/opus_47_extended_features_v2_featureai.md)) that folded overlapping capabilities into 6 user-facing commands and shipped as v3.0 through v3.4 over roughly one calendar week.
+
+This ADR records the decisions made during that arc — what was consolidated, what was explicitly deferred, why the hierarchical orchestrator was gated behind a flag, and the safety posture for features that introduced new capabilities (agents-spawn-agents, worktree isolation, MCP discovery).
+
+## Decision
+
+Ship Spec B v2 across five additive waves with no breaking changes. Consolidate v1's 14 items into 6 user-facing commands plus one infrastructure layer. Keep the focus system (`/pan:focus-*`) untouched — Spec B v2 items interoperate via read boundaries and optional flags only, never modifying focus commands.
+
+### Wave breakdown
+
+| Wave | Release | Items | Scope |
+|------|---------|-------|-------|
+| 1 | v3.0.0 | Y-6 cost + Y-7 bus | Observability (cost dashboard) + foundation (file-backed message channels) |
+| 2 | v3.1.0 | Y-1 preview | Foresight — blast radius / dependency graph / milestone ETA in one multi-mode command |
+| 3 | v3.2.0 | Y-2 review-deep + Y-3 knowledge | Security + cross-check review (2 new agents) + grounded Q&A / discussion / playbook (1 new agent, 3 modes) |
+| 4 | v3.3.0 | Y-4 what-if + Y-5 mcp-bridge | Counterfactual phase replay in worktree + MCP discovery-only |
+| 5 | v3.4.0 | `--hierarchical` GA + `--deep-review` wiring + auto cost instrumentation | Wave 1 bus becomes observable via `pan-conductor` + cost hook |
+
+### Consolidation decisions (from v1)
+
+- **Foresight** (X-1 architect + X-5 simulate + X-11 predict-milestone) → single `/pan:preview` command with three modes
+- **Deep review** (X-4 self-review + X-12 harden) → single `/pan:review-deep` command with two sequential agent passes
+- **Knowledge** (X-3 converse + X-6 teach + X-10 explain) → single `/pan:knowledge` command with three modes
+- **Hierarchical exec** (X-2 orchestrate + X-13 bus) → infrastructure layer + opt-in flag on existing `exec-phase`, not a standalone command
+
+### Explicit deferrals (documented, not shipped)
+
+- **X-8 watch** (background monitoring) — no user-demand signal; external cron works today; revisit in v3.5+ if requested
+- **MCP auto-injection into planner context** — requires stable MCP schema contract; ship discovery-only (Y-5) first
+- **MCP auto-invocation from executor agent** — requires permission-gating + per-tool safety review
+- **Cross-runtime MCP discovery protocol** — no ecosystem signal; cache schema designed generically so future non-Claude runtimes can plug in
+- **`pan-conductor` nesting beyond 2 levels** — would need substantially more safety tooling; current 2-level cap is sufficient for the observed use cases
+
+### Safety posture decisions
+
+**Hierarchical orchestration is opt-in behind a flag, not the default.** Rationale:
+1. Flat exec is cheaper (~20-30% lower total cost for equivalent work).
+2. Flat exec is more predictable — each sub-agent's behavior is deterministic given plan input; hierarchical introduces a decomposition decision that varies with model reasoning.
+3. Flat exec is easier to debug — linear trace vs tree trace.
+4. Hierarchical is only useful when wall-clock reduction justifies the orchestration tax (phases with ≥4 autonomous plans).
+
+The safety harness is mandatory (not advisory) for `--hierarchical`:
+- Max 2 nesting levels (conductor → sub-agent; no sub-sub-agents)
+- Max 12 spawns per phase
+- Budget ceiling (reuses focus-auto's budget layer)
+- Emergency stop via `.planning/orchestration/abort` kill-switch
+- Audit trail in `.planning/orchestration/trace.json` + `.planning/bus/orchestrator.jsonl`
+
+**Counterfactual agent runs in isolated git worktree.** Rationale: counterfactual replay inherently involves speculative file modifications. Worktree isolation is the enforcement mechanism — the agent can edit freely in the worktree without affecting the main tree, and the worktree is auto-deleted after the report is written in the main tree. The agent's contract forbids commit/push/merge and paths outside the worktree.
+
+**MCP integration is discovery-only in v3.x.** Rationale: auto-invoking external tools (Linear, Slack, databases) without permission gating is a safety risk. Ship the read path (discovery + recommendation) first; revisit auto-invocation when MCP schemas stabilize and per-tool safety review is in place.
+
+**Cost instrumentation is non-blocking.** Rationale: observability must never break the primary agent loop. The SubagentStop hook swallows all errors silently. Records with zero tokens (when Claude Code's event payload lacks `usage` data) are logged anyway — presence matters even when cost doesn't resolve.
+
+## Consequences
+
+### Positive
+
+- **Shipped 6 user-facing commands in ~1 calendar week** instead of 13 over 15 weeks. Consolidation-first design reduced risk of abandoning mid-way.
+- **Zero breaking changes.** Every feature is additive; `.planning/` gains new subdirectories but no existing file changes shape.
+- **Each command has a clear single purpose.** `/pan:preview` is foresight, `/pan:cost` is observability, `/pan:review-deep` is security, `/pan:knowledge` is retrieval, `/pan:what-if` is counterfactual exploration, `/pan:mcp-bridge` is discovery. No overlap, no "which command do I use?" ambiguity.
+- **Focus system untouched.** Users of `/pan:focus-*` see identical behavior. Spec B v2 features integrate via flags (`--deep-review`) or via read boundaries (cost reads focus-auto telemetry, preview reads roadmap), not by modification.
+- **Safety posture is explicit.** Each new capability has documented boundaries (hierarchical caps, worktree isolation, discovery-only MCP).
+
+### Negative
+
+- **`--hierarchical` is Claude + Opus 4.7 only.** Other runtimes silently fall back to flat exec. This is documented but creates a capability gap — users on OpenAI/Gemini/etc. don't get hierarchical orchestration.
+- **MCP bridge is Claude-only.** Other runtimes return empty `source: "empty"` gracefully, but the recommendation feature is unavailable.
+- **Auto cost logging is best-effort.** Claude Code's SubagentStop payload doesn't always carry token counts. Records with zeros are honest but require the user to cross-reference provider billing for exact totals.
+- **Module count grew from 17 to 24.** Surface expansion. Mitigated by: each module has a clear single responsibility, and the module inventory in ARCHITECTURE.md documents each one explicitly.
+- **Spec B v1 artifacts remain in the repo.** `opus_47_extended_features_featureai.md` is marked `status: superseded` with a header banner pointing to v2. We chose preservation over deletion to maintain the design history trail.
+
+### Neutral / Tradeoffs considered
+
+- **Why not also ship X-8 watch?** Background monitoring is orthogonal to the Opus 4.7 capability set and doesn't reuse Spec A infrastructure. External cron + `/pan:health` cover 80% of the use case. Ship when a real user demand signal arrives.
+- **Why ship bus.cjs in Wave 1 before any consumer?** Y-7 infrastructure unblocks Y-2 (review-deep audit trail) and `pan-conductor` (orchestrator trace). Shipping the foundation first meant Wave 3 could implement review-deep without first implementing the bus. Separately-testable modules.
+- **Why flat namespace (`/pan:*`) instead of `/pan:adv:*` for v2 items?** Flat is discoverable; namespacing clutters tab-completion. 48 commands across 6 groups is manageable; further growth would warrant reconsidering.
+- **Why consolidate knowledge modes (ask/discuss/playbook) rather than ship three commands?** Single entry point means users don't have to remember which of `/pan:explain` / `/pan:converse` / `/pan:teach` to invoke. Each mode is independently invokable with a subcommand.
+
+## Implementation Notes
+
+### Commit history
+
+- `0c8df85` — v3.0.0 Wave 1 (Y-6 cost + Y-7 bus)
+- `1f98394` — v3.1.0 Wave 2 (Y-1 preview)
+- `f3a4451` — v3.2.0 Wave 3 (Y-2 review-deep + Y-3 knowledge)
+- `7faf9b2` — v3.3.0 Wave 4 (Y-4 what-if + Y-5 mcp-bridge)
+- `d391599` — v3.4.0 Wave 5 (`--hierarchical` GA + `--deep-review` wiring + cost hook)
+
+### Cumulative delta (v2.10.0 → v3.4.0)
+
+- Tests: 2143 → 2368 (+225)
+- Core modules: 17 → 24 (+7)
+- Agents: 12 → 18 (+6)
+- Commands: 42 → 48 (+6)
+- Hooks: 3 → 4 (+1)
+- Templates: ~22 → 26 (+4)
+- CLI subcommands: ~110 → ~130 (+20)
+
+### Rollback plan
+
+Spec B v2 is entirely additive. Rollback strategy if telemetry reveals a regression:
+- Remove the new commands from `commands/pan/` — host runtime sees them disappear on next session
+- Remove the new agents from `agents/` — no agent, no spawn path
+- `hooks/pan-cost-logger.js` — remove via installer's SubagentStop hook cleanup (`panHooks` array)
+- `pan-conductor` + `--hierarchical` flag — unwired if agent missing
+- `.planning/` subdirectories (`metrics/`, `bus/`, `bridge/`, `counterfactuals/`, `conversations/`, `orchestration/`, `reviews/`, `memory/`, `architecture/`) — data preserved; readers tolerate missing directories via `try/catch` in core library
+
+No schema changes to `.planning/state.md`, `.planning/roadmap.md`, `.planning/project.md`, or any other file that existed pre-v3.0. Rollback is a commit-level operation, not a data migration.
+
+### Future scope
+
+Post-v3.4 work is discretionary. Candidates:
+- X-8 watch (background monitoring)
+- MCP auto-injection into planner context (v3.5+ if schema stabilizes)
+- MCP auto-invocation from executor (v3.5+ with permission gating)
+- `pan-conductor` nesting beyond 2 levels (would require deeper safety tooling)
+- Cross-runtime MCP discovery protocol
+- Generic instrumentation for token capture across runtimes (Gemini, OpenCode, Codex, Copilot — currently zero token visibility)
+
+## Related
+
+- [ADR-0023: Opus 4.7 Adoption](ADR-0023-opus-4-7-adoption.md) — baseline Spec A integration this builds on
+- [Spec B v1](../specs/opus_47_extended_features_featureai.md) — original 14-item design (superseded)
+- [Spec B v2](../specs/opus_47_extended_features_v2_featureai.md) — consolidated design (accepted, shipped)
+- [MIGRATION-v2-to-v3.md](../MIGRATION-v2-to-v3.md) — user-facing upgrade guide
+- ADR-0015 (focus-auto runner) — budget ceiling layer reused by hierarchical safety harness
+- ADR-0022 (lifecycle completeness) — pan-reviewer baseline that pan-hardener + pan-meta-reviewer extend

package/docs/decisions/ADR-0025-behavioral-guardrails-layer.md

@@ -0,0 +1,129 @@
+# ADR-0025: Behavioral Guardrails Layer (v3.6.0)
+
+## Status
+Accepted (shipped 2026-04-27)
+
+## Context
+
+PAN Wizard's structural systems — phases, milestones, focus, plans — are mature, but anti-patterns (silent model swaps, skipping verification, manual scaffolding, scope creep) were addressed implicitly across many workflow files without a single consolidated rules surface. AI agents executing PAN workflows would routinely make context-pressured shortcuts that had to be re-corrected per session: silent model selection drift, skipping `/pan:verify-phase` because "tests passed locally," manually picking focus items instead of letting `focus.cjs` allocate by budget. Each correction was cheap individually; aggregated across sessions, it became the dominant source of rework.
+
+Review of Google's `agents-cli` (a CLI + skills package that injects ADK development workflows into Claude Code, Gemini CLI, Codex, and others — see `docs/specs/googlecli_adoption_featureai.md`) surfaced three patterns worth adopting:
+
+1. **A consolidated guardrails reference** — one short file naming the top anti-patterns, code preservation rules, and the stop-the-line regression rule
+2. **Phase-gated re-read directives** in long workflows — explicit "re-read section X before phase Y" markers that resist context compaction drift
+3. **A mandatory Phase 0 clarify gate** before scaffolding new work
+
+Three other patterns were considered and either deferred or skipped (see "Explicit deferrals" below).
+
+## Decision
+
+Ship the behavioral guardrails layer as v3.6.0 — additive only, zero breaking changes. The layer consists of:
+
+### 1. New reference doc: `pan-wizard-core/references/guardrails.md`
+
+A single ~58-line doc consolidating:
+
+- **Common Shortcuts to Resist** — 5-row table naming anti-patterns with rationale and correct action
+- **Code Preservation Principle** — surgical-edit doctrine; preserve config values, comments, formatting outside the user's explicit target
+- **Stop-the-Line Rule** — regressions halt feature work
+- **Systematic Debugging Sequence** — reproduce → localize → fix one variable → verify → guard
+- **Cross-References** — pointers to `tdd.md`, `verification-patterns.md`, `checkpoints.md`, and the workflows that consume guardrails
+
+The reference ships to all 5 runtimes via the existing `references/` install path. No installer logic changes.
+
+### 2. Re-Read Checkpoints in 4 long workflows
+
+Each long workflow (`exec-phase.md`, `plan-phase.md`, `verify-phase.md`, `execute-plan.md`) gains a `## Re-Read Checkpoints` section near the top with a 4-row table mapping "before this step" → "re-read this" → "why." Pattern resists context compaction drift across long autonomous sessions.
+
+### 3. Phase 0 Clarify Gate
+
+`new-project.md` gets a **MANDATORY** Phase 0 gate with 4 questions (problem / success / scope / constraints) the agent must get answered before scaffolding. `plan-phase.md` gets a lighter "recommended" Phase 0 with 3 phase-scoped questions.
+
+### 4. Workflow + agent cross-references to `guardrails.md`
+
+The 4 long workflows and 2 agents (`pan-reviewer`, `pan-planner`) now reference `guardrails.md` in their required-reading or role sections. Agents are instructed to flag Code Preservation violations at high severity.
+
+### Spec adjustment recorded here
+
+The original spec (`googlecli_adoption_featureai.md`) listed `focus-exec.md` as the 4th target workflow for Re-Read Checkpoints. `focus-exec.md` is a *command file* (`commands/pan/focus-exec.md`), not a workflow. The 4th workflow target is **`execute-plan.md`** (448 lines), the next-longest workflow after exec-phase, plan-phase, and verify-phase. `focus-exec` as a command will get re-read directives in a future patch if needed; not in v3.6.0.
+
+### Explicit deferrals (documented, not shipped)
+
+- **`pan-tools info` command** — overlap with `state json` and `validate health` is high. Deferred to v3.6.1 prototype-first; ship as new command only if prototype shows ≤80% overlap, otherwise fold into `state json --full`.
+- **Frontmatter `requires`/`related` schema** — defer until a concrete consumer (dispatcher precondition checks or doc generator) justifies the 50+ command backfill cost.
+- **LLM-as-judge eval framework** — different problem domain; PAN tests code workflows, not agent behavior. 100+ pt effort with no demand signal.
+- **Tool-level enforcement of Phase 0** — workflow text is the right enforcement layer; tool-level blocks add brittleness.
+- **`npx skills add` distribution model** — PAN's installer is feature-complete; switching is cosmetic.
+
+## Consequences
+
+### Positive
+
+- **One consolidated rules surface.** AI agents have a single grep-friendly file to consult instead of inferring rules from scattered workflow prose.
+- **Zero breaking changes.** All edits are additive; no existing command, workflow, or test changes behavior. Existing v3.5.x installs upgrading to v3.6.0 receive new files via standard `pan update`.
+- **Compounds across runtimes.** `references/` ships identically to all 5 runtime install paths (`.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.github/`). One file, five runtimes, zero installer changes.
+- **Compounds across sessions.** The cost of writing guardrails.md is one-time; the benefit of resisting silent model swaps and skipped verification accrues every future AI session.
+- **Test count grew.** 2567 → 2588 (+21 new tests: 16 unit across 4 new test files + 5 scenario across all 5 runtimes).
+- **Pattern is reusable.** The `references/<topic>.md` + workflow-cross-reference pattern can host future behavioral layers without growing the workflow surface.
+
+### Negative
+
+- **AI agents may treat guardrails as advisory.** Workflow text is the enforcement layer; an agent that decides to skip Phase 0 or ignore "Stop-the-Line" cannot be hard-blocked at the tool level. Mitigation: workflow text uses "MANDATORY, do not skip" and "Do NOT proceed" framings. Agents that have ingested guardrails.md and the workflow consistently follow it; agents that haven't won't.
+- **Re-read directives feel naggy if read literally.** The 4-row table at the top of each long workflow could be ignored by agents that skim. Net positive even when ignored — agents that *do* re-read avoid drift.
+- **Phase 0 gate adds friction for small projects.** `new-project.md`'s 4-question gate is overhead for trivial scaffolding. Mitigation: `--auto` mode short-circuits the gate when a PRD/idea document is provided. The gate is meant for the 80% case where users haven't yet articulated requirements.
+- **Spec/implementation mismatch on workflow target.** The original spec named `focus-exec.md` as a workflow target, but it's a command. Documented above; minor.
+- **Maintenance debt.** `guardrails.md` will drift out of sync with actual workflows over time. Mitigation: future `/pan:doc-audit` runs should include guardrails references in their checks.
+
+### Neutral / Tradeoffs considered
+
+- **Why not enforce guardrails at tool-level (e.g., `pan-tools` blocks commits with "skip-tests" flags)?** Workflow text is the right enforcement layer. Tool-level blocks become brittleness when an agent encounters a legitimate edge case the tool author didn't anticipate. AI judgment + textual rules > rigid tool-level gates.
+- **Why ≤80 lines for guardrails.md?** Context budget. The doc is referenced by ~6 workflow/agent files. If it bloats to 200 lines, it crowds out plan content in the agent's context window. 58 lines proved sufficient for the rule set; future additions should preserve this discipline.
+- **Why a single doc instead of per-rule files?** Discoverability. One filename, one URL, one path to remember. Splitting (`code-preservation.md`, `stop-the-line.md`, `shortcuts.md`) fragments and dilutes the surface.
+- **Why include `pan-reviewer` and `pan-planner` but not other agents?** These two are the highest-leverage entry points: planner generates the work, reviewer validates it. Other agents (`pan-executor`, `pan-tester`, etc.) inherit guardrails transitively via the workflows that spawn them. Adding the reference to all 20 agents would dilute the value.
+
+## Implementation Notes
+
+### Files added (8)
+- `pan-wizard-core/references/guardrails.md` — the anchor doc
+- `tests/guardrails.test.cjs` — 4 unit tests
+- `tests/workflows-checkpoints.test.cjs` — 4 unit tests
+- `tests/guardrails-references.test.cjs` — 6 unit tests
+- `tests/phase0-gate.test.cjs` — 2 unit tests
+- `tests/scenarios/guardrails-installed.test.cjs` — 5 scenario tests (one per runtime)
+- `docs/decisions/ADR-0025-behavioral-guardrails-layer.md` — this ADR
+- `docs/specs/googlecli_adoption_featureai.md` — the source spec (committed alongside)
+
+### Files modified (9)
+- `pan-wizard-core/workflows/exec-phase.md` — Re-Read Checkpoints + guardrails reference
+- `pan-wizard-core/workflows/plan-phase.md` — Re-Read Checkpoints + guardrails reference + Phase 0 (recommended)
+- `pan-wizard-core/workflows/verify-phase.md` — Re-Read Checkpoints + guardrails reference
+- `pan-wizard-core/workflows/execute-plan.md` — Re-Read Checkpoints + guardrails reference
+- `pan-wizard-core/workflows/new-project.md` — Phase 0 (MANDATORY) + guardrails reference
+- `agents/pan-reviewer.md` — guardrails reference + flag-Code-Preservation directive
+- `agents/pan-planner.md` — guardrails reference + must-enforce-in-deviation-rules directive
+- `package.json` — version 3.5.2 → 3.6.0
+- `CHANGELOG.md` — v3.6.0 entry
+
+### Test deltas
+- Unit: 2302 → 2318 (+16, 4 new test files)
+- Scenario: 265 → 270 (+5, one per runtime)
+- Total: **2567 → 2588** (+21)
+
+### Rollback plan
+The layer is entirely additive. Rollback strategy if telemetry reveals a regression:
+- Remove `references/guardrails.md` — workflows referencing it will resolve to "file not found" but won't fail the workflow logic
+- Remove the `## Re-Read Checkpoints` and `## Phase 0` sections from the 5 workflow files — they're plain markdown, no behavior depends on them
+- Remove the `**Read also:**` lines from the 2 agent files
+- Remove the 5 new test files
+- No schema or manifest changes; rollback is a commit-level revert
+
+### References
+- Source spec: `docs/specs/googlecli_adoption_featureai.md` (created 2026-04-27)
+- Ancestor pattern: `docs/specs/ai_drift_prevention_featureai.md` (Mar 2026)
+- External pattern source: Google `agents-cli` workflow SKILL.md (`d:\googlecli\agents-cli\skills\google-agents-cli-workflow\SKILL.md` lines 242-325)
+
+## Future scope
+
+- **v3.6.1 prototype**: `pan-tools info` self-discovery command — measure overlap with `state json`, ship or fold accordingly
+- **v3.7+**: Frontmatter `requires`/`related` schema — only if a concrete consumer (dispatcher precondition checks or auto-generated docs) emerges
+- **Doc-audit integration**: future `/pan:doc-audit` runs should verify guardrails references resolve and the 5 listed shortcuts are still the right top-5