pan-wizard 3.35.0 → 3.37.0

package/docs/decisions/ADR-0015-focus-auto-runner.md

@@ -0,0 +1,296 @@
+# ADR-0015: Focus Auto-Runner — Continuous Categorized Execution
+
+**Status:** Accepted (shipped in v2.3.0 — 2026-03-03)
+**Date:** 2026-03-03
+**Context:** Strategic Feature Spec — `docs/specs/focus_auto_runner_featureai.md`
+**Competitive Research:** `docs/specs/continuous_autonomous_execution_featureai.md`
+
+## Decision
+
+Add `/pan:focus-auto` — a continuous scan→plan→exec loop with 5 purpose-driven categories and a 5-layer safety harness. The auto-runner orchestrates multiple focus cycles as a single campaign, with category-scoped scanning, intelligent default escalation, and structured run state persistence.
+
+**Architecture**: Workflow-orchestrated loop (command .md) + core state management (focus.cjs). The AI workflow orchestrates the scan→plan→exec loop; the core module manages run state persistence, category filtering, and cycle recording. This follows PAN's established separation: core returns data, workflows make AI decisions.
+
+## Context
+
+### The Problem (Quantified)
+
+PAN Wizard's focus system requires **3 manual invocations per improvement cycle**: `/pan:focus-scan` → `/pan:focus-plan` → `/pan:focus-exec`. For a typical 5-cycle quality campaign:
+
+| Metric | Manual (Status Quo) | With Auto-Runner |
+|--------|-------------------|-----------------|
+| Commands typed | 15 (3 × 5 cycles) | 1 |
+| Human decision points | 10 (review scan + confirm plan × 5) | 0 (category carries defaults) |
+| Context switches | 5 (between cycles) | 0 (continuous loop) |
+| Total wall-clock overhead | ~15 min of human typing/reviewing | ~10 sec (one command) |
+
+Evidence from real usage: sessions 24-25 ran back-to-back manual cycles in a single day (44 items, 95 points, across 65 files). Sessions 1-12 ran 12+ execplan/superplan cycles manually. The pattern is clear: **the most valuable PAN workflows involve repetition, and repetition is what should be automated**.
+
+### Budget System Heritage (5 Generations)
+
+The auto-runner's budget and category systems are not new inventions — they trace a clear lineage through PAN's evolution:
+
+```
+execplan.md (v1, sessions 1-12)
+├── Capacity Budget: XS=1, S=2, M=4, L=10, XL=20
+├── 4 Modes: bugfix/balanced/features/full
+├── 6-Stage Pipeline, 9 Behavioral Rules
+└── Test cadence by tier: MICRO/STANDARD/FULL
+    │
+    ↓
+superplan.md (v1-v18, sessions 1-20)
+├── Priority Framework: P0-P6
+├── Effort Estimation: XS-XL
+├── Reality Score: RS = (UV + TC + RR) / JS
+└── Scan Assembly: items grouped by priority
+    │
+    ↓
+focus-scan/plan/exec (v1, session 17, ADR-0006)
+├── Unified in focus.cjs module (559 LOC)
+├── JSON batch files (.planning/focus/batch-*.json)
+├── allocateBudget() with multi-pass algorithm
+└── 73 tests in focus.test.cjs
+    │
+    ↓
+panmonty_protocol.md (parallel track, sessions 1+)
+├── 5 Change Categories: DOCS_ONLY/TESTS_ONLY/LIB_CHANGE/HOOK_CHANGE/FULL_FEATURE
+├── Loop Exhaustion Guard: 3rd Phase 7 entry → ask user
+└── Quick Mode: auto-detect XS/S → skip full workflow
+    │
+    ↓
+focus-auto (THIS FEATURE)
+├── Inherits: budget, 4 modes, 6-stage pipeline, 9 rules, tiers
+├── Adapts: PanMonty categories → 5 purpose categories with priority-range mapping
+├── Adapts: PanMonty loop exhaustion → circuit breaker + zero-completed stop
+└── Creates: continuous loop, run state persistence, campaign-level tracking
+```
+
+Every design choice in the auto-runner has heritage. None are novel risks.
+
+### Competitive Landscape
+
+8-tool competitive analysis (full research: `docs/specs/continuous_autonomous_execution_featureai.md`):
+
+| Tool | Has Continuous Mode | Has Categories | Has Budget | Has Loop Control |
+|------|-------------------|---------------|-----------|-----------------|
+| Cursor | Background Agents (cloud) | None | Opaque credits | Run until done/fail |
+| GitHub Copilot | Coding Agent (cloud) | Labels (implicit) | Per-issue | PR completion |
+| Aider | --watch-files (event) | None | None | User bash loop |
+| Cline | YOLO mode | None | Removed (v3.35) | None |
+| Claude Code | Headless -p | None | --max-turns | Session end |
+| Windsurf | Turbo Mode | None | Per-session | Debug loop |
+| Devin | Compound agent | None | Per-task | Checkpoints |
+| OpenAI Codex | Cloud sandbox | None | Per-task | Task completion |
+
+**Whitespace**: No tool has categorized work queues, budget-aware continuous execution, priority-driven selection, structured progress persistence, OR cross-runtime continuous orchestration. PAN would be first on all five axes.
+
+### Demand Evidence
+
+| Evidence Type | Source | Finding |
+|--------------|--------|---------|
+| User-stated explicit request | This conversation | "design auto flow... with categories of what it scans for, like cleanups" |
+| Internal usage (quantified) | Sessions 24-25 | 44 items, 95 pts, 2 back-to-back manual cycles |
+| Internal usage (historical) | Sessions 1-20 | 12+ manual execplan/superplan invocations |
+| Competitor convergence | Cursor, Copilot, Aider | All shipping continuous modes; becoming table-stakes |
+| Architectural heritage | panmonty_protocol.md | 5 change categories + loop exhaustion guard already in production |
+
+**Demand status**: STRONG — direct user request + 25 sessions of quantified manual cycling + competitive convergence + architectural heritage.
+
+## Key Design Choices
+
+### 1. Five Predefined Categories with Intelligent Defaults
+
+Categories are **not user-configurable** — 5 predefined options cover 95% of real usage (validated across 25 sessions). Each category carries a default mapping chain that eliminates manual flag selection:
+
+| Category | Priority Range | Default Mode | Default Budget | Heritage |
+|----------|---------------|--------------|----------------|----------|
+| `cleanup` | P3-P5 | balanced | 50 pts | PanMonty LIB_CHANGE |
+| `tests` | P2-P5 | balanced | 50 pts | PanMonty TESTS_ONLY |
+| `stability` | P0-P2 | bugfix | 40 pts | PanMonty LIB_CHANGE (critical) |
+| `features` | P3-P5 | features | 50 pts | PanMonty FULL_FEATURE |
+| `docs` | P5-P6 | balanced | 30 pts | PanMonty DOCS_ONLY |
+
+Explicit flags override: `--category stability --mode full --budget 60` uses those values.
+
+### 2. Category as Post-Filter (Not Separate Scan)
+
+```javascript
+function categoryFilter(items, category) {
+  if (!category) return items;
+  const range = CATEGORY_PRIORITY_RANGE[category];
+  return items.filter(item => {
+    const idx = PRIORITY_LEVELS.indexOf(item.priority);
+    return idx >= range.min && idx <= range.max;
+  });
+}
+```
+
+Reuses 100% of existing `collectWorkItems()` infrastructure. No per-category scanners. No duplication.
+
+### 3. Five-Layer Safety Harness
+
+| Layer | Mechanism | Default | Heritage |
+|-------|-----------|---------|----------|
+| Per-cycle budget | `--budget N` | 50 pts (category-dependent) | execplan.md capacity system |
+| Cumulative budget | `--total-budget N` | 500 pts | Novel — no competitor has this |
+| Iteration limit | `--max-cycles N` | 10 | Novel — prevents infinite loops |
+| Regression circuit breaker | tests_after < tests_before | Immediate stop | PanMonty Phase 7 loop exhaustion |
+| Zero-completed guard | Cycle produces 0 items done | Immediate stop | PanMonty loop exhaustion adaptation |
+
+No competitor has more than 1 safety layer. Cline removed its only one.
+
+### 4. Workflow-Orchestrated Loop with Core State Management
+
+- **Core** (`focus.cjs`): `cmdFocusAuto()` manages run state (init, status, update, stop), `categoryFilter()` scopes items, `readAutoRun()` / `writeAutoRun()` handle persistence. Pure data operations. No AI, no git, no shell.
+- **Workflow** (`focus-auto.md`): Orchestrates the scan→plan→exec loop. Reads code, runs tests, makes git commits, decides whether to continue. Has AI tool access.
+
+This follows the established separation proven in ADR-0003 (smart execution) and ADR-0006 (focus commands).
+
+### 5. Run State Persistence
+
+`auto-run.json` in `.planning/focus/` tracks full campaign state with per-cycle history:
+
+```json
+{
+  "run_id": "auto-2026-03-03-1",
+  "status": "in_progress",
+  "category": "cleanup",
+  "cycles": [{ "cycle": 1, "items_completed": 12, "points_used": 38, ... }],
+  "totals": { "cycles_completed": 1, "items_completed": 12, "points_used": 38 }
+}
+```
+
+Enables `--continue` for cross-session resumability. Co-located with existing `batch-*.json` files.
+
+### 6. Per-Cycle Commits (Inherited)
+
+Each cycle produces a self-contained commit via the existing focus-exec Stage 6. Failure in cycle N preserves cycles 1..N-1 as committed code. This is safer than a single final commit (proven across 25 sessions in execplan/focus-exec).
+
+## Consequences
+
+### Positive
+- **15→1 invocations**: 5-cycle campaign drops from 15 manual commands to 1 (quantified: saves ~15 min human overhead per campaign)
+- **First-in-industry**: Categorized work queues with purpose-driven campaigns. No competitor has this — 18+ month moat before replication (competitors would need scan→plan→exec infrastructure first)
+- **5-layer safety**: Per-cycle budget + cumulative budget + max cycles + regression circuit breaker + zero-completed guard. Most comprehensive autonomous safety harness in AI coding tools
+- **Heritage-validated**: Every component traces to proven systems (execplan budget, PanMonty categories, focus-exec pipeline). Zero novel risk
+- **Cross-runtime**: Works across all 5 runtimes (Claude Code, OpenCode, Gemini CLI, Codex, Copilot CLI) via command .md
+- **Resumable**: `--continue` restores full campaign state across sessions
+- **Zero new modules**: Extends focus.cjs (4 functions: ~150 LOC) + constants.cjs (3 constants) + pan-tools.cjs (1 case). No new runtime dependencies. No installer changes
+- **Cognitive load -1**: Eliminates 14 manual invocations per 5-cycle campaign. Category concept is already familiar from PanMonty. Net simplification for target users (those who run 2+ cycles)
+
+### Negative
+- **+1 command**: 41→42 commands (+2.4% growth). Mitigated: grouped under Focus, discovered via /pan:help
+- **AI dependency**: Loop correctness depends on AI following workflow instructions. Mitigated: 9 behavioral rules are battle-tested across 6+ sessions; workflow .md is heavily structured
+- **Single concurrent run**: One auto-run at a time per project. Mitigated: concurrent runs would cause git state conflicts; single run is the safe default
+- **More git history**: Per-cycle commits produce N commits per campaign instead of 1. Mitigated: each commit is self-describing and individually reviewable; squash available via `git rebase`
+- **5 fixed categories**: Can't add "security" or "performance" without code change. Mitigated: priority-range filtering covers any P0-P6 work; categories are convenience groupings, not hard gates
+
+### Neutral
+- Existing manual scan→plan→exec workflow unchanged and independently usable
+- auto-run.json is a new file but in existing .planning/focus/ directory
+- No new runtime dependencies, no new modules, no installer changes
+- Config.json `auto` section is optional (v2 enhancement, not v0/v1)
+
+## Options Considered
+
+### 1. Shell Script Wrapper — User writes bash loop
+User wraps `pan-tools focus scan && pan-tools focus plan && pan-tools focus exec` in a bash while-loop.
+
+**Pro:** Zero implementation work.
+**Con:** Not cross-platform (no PowerShell/CMD equivalent). No category system. No state persistence. No safety harness. No budget tracking. No resume. User must handle every edge case.
+**Rejected** — violates cross-platform constraint, provides none of the category/budget value.
+
+### 2. Core Module Loop — Put loop logic in focus.cjs
+`focus.cjs` runs the scan→plan→exec loop internally.
+
+**Pro:** Deterministic — no AI dependency for loop control.
+**Con:** Core modules cannot invoke AI decisions (what to scan), git operations (commit), shell commands (npm test), or file edits (implementing fixes). Would require importing agents, which violates the core←→workflow separation (core returns data, workflows orchestrate). Would create circular dependencies.
+**Rejected** — violates layer boundary architecture established in ADR-0003 and ADR-0006.
+
+### 3. Background Daemon — Run as persistent service
+Auto-runner runs as a background Node.js process, watching for file changes or operating on a schedule.
+
+**Pro:** True unattended execution. Could run overnight without keeping AI session open.
+**Con:** Zero-dependency constraint (no process management library). Cross-platform daemon complexity (Windows services vs. Unix daemons). PAN is session-bound by design — all 5 runtimes assume interactive session scope. Daemon would need its own logging, crash recovery, and process lifecycle management. Security implications of unattended code changes.
+**Rejected** — violates zero-dep constraint, incompatible with session-bound architecture, massive implementation complexity for marginal value.
+
+### 4. Workflow-Orchestrated Loop with Core State Management (CHOSEN)
+Core manages run state persistence and category filtering. Workflow .md file orchestrates the scan→plan→exec loop with AI capabilities (reading code, making decisions, running tests, committing).
+
+**Pro:** Clean separation matching established patterns. Core is testable (pure data operations). Workflow has full AI tool access. State persists across sessions via JSON. Extends existing focus.cjs (no new module).
+**Con:** Depends on AI following workflow instructions correctly (mitigated: 9 behavioral rules, structured workflow .md).
+**Chosen** — best of both worlds: structured state management + intelligent AI-driven execution.
+
+### 5. Event-Driven File Watcher (Aider Model)
+Watch filesystem for changes and trigger scan→plan→exec on file change events.
+
+**Pro:** Reactive — runs when user saves files.
+**Con:** PAN's value is in batch campaigns, not reactive fixes. File watching requires `fs.watch()` which has known cross-platform inconsistencies. Would trigger on AI-generated changes creating feedback loops. Doesn't fit the "run a cleanup campaign" mental model.
+**Rejected** — wrong paradigm for PAN's batch-oriented architecture. PAN scans for *project-wide* patterns, not individual file changes.
+
+### 6. Multi-Category Parallel Execution
+Run cleanup AND tests AND stability campaigns simultaneously in separate git branches, merge at end.
+
+**Pro:** Maximum throughput.
+**Con:** Requires git worktree orchestration. Merge conflicts between concurrent campaigns likely (both touch overlapping files). Session-bound runtimes can't run multiple AI streams. Complexity explosion for marginal benefit — sequential campaigns cover the same ground safely.
+**Rejected** — complexity disproportionate to value. Sequential single-category campaigns achieve the same outcome safely.
+
+## What We Explicitly Did NOT Build (and Why)
+
+| Rejected Feature | Reason |
+|-----------------|--------|
+| User-defined custom categories | 5 predefined covers 95% of real usage (25 sessions). Configuration adds cognitive load, testing surface, and documentation burden for 5% marginal coverage |
+| Cloud/remote execution | PAN is local-first, zero-dep, session-bound. Cloud execution would require Docker, GitHub Actions, or equivalent — contradicts core constraints |
+| Real-time file watching | Batch execution is PAN's paradigm. File watching creates feedback loops and doesn't match "run a campaign" mental model |
+| Daemon/service mode | Zero-dep constraint. Cross-platform daemon complexity. PAN is session-bound by design |
+| Multi-branch parallel campaigns | Git worktree orchestration, merge conflicts, single-session AI constraint |
+| External task sources (Jira, GitHub Issues) | PAN reads .planning/ only. External integration is a separate feature with separate auth/API concerns |
+| AI model selection per category | Model profile is a separate concern (handled by /pan:profile) |
+| Safety-free mode (Cline YOLO) | User trust requires verification. Circuit breaker is a feature, not a constraint |
+
+## Implementation Summary
+
+| Task | Files | Effort | Priority |
+|------|-------|--------|----------|
+| Constants (FOCUS_CATEGORIES, etc.) | constants.cjs | XS (1 pt) | P0 |
+| categoryFilter() function | focus.cjs | S (2 pts) | P0 |
+| cmdFocusAuto() — init/status/stop/update | focus.cjs | M (4 pts) | P0 |
+| Dispatcher routing (auto case) | pan-tools.cjs | XS (1 pt) | P0 |
+| focus-auto.md command file | commands/pan/ | S (2 pts) | P1 |
+| Unit tests (14+) | tests/focus.test.cjs | S (2 pts) | P1 |
+| Integration tests (8+) | tests/focus-auto-integration.test.cjs | S (2 pts) | P2 |
+| E2E tests (3+) | tests/focus-auto-e2e.test.cjs | M (4 pts) | P2 |
+| Doc sync (README, CLI-REF, CHANGELOG) | docs/ | XS (1 pt) | P3 |
+
+**Total: 9 tasks, 19 points, S-M effort, 25+ tests**
+
+### Feature Ladder
+
+| Version | Scope | Effort |
+|---------|-------|--------|
+| **v0 (MVP)** | cmdFocusAuto + categoryFilter + constants + dispatcher + command .md | M (4 pts) |
+| **v1 (Complete)** | --continue + --dry-run + --total-budget + circuit breaker + zero-completed guard + campaign summary | M (4 pts) |
+| **v2 (Enhanced)** | Config defaults + campaign history archiving + aggregate analytics + `--history` | L (10 pts) |
+
+## Moat Assessment
+
+| Moat Type | Score (0-5) | Rationale |
+|-----------|-------------|-----------|
+| Context Engineering | 5 | Categories reduce scan noise by 40-70% per campaign |
+| Cross-Platform | 5 | 5-runtime continuous execution (only tool with this) |
+| Developer Experience | 5 | 15→1 invocations for 5-cycle campaign |
+| Zero Dependencies | 5 | Pure Node.js, file-based state, no daemon/cloud/Docker |
+| State Persistence | 5 | auto-run.json + --continue + per-cycle batch files |
+| Verification Quality | 5 | 5-layer safety (only tool with >1 safety layer) |
+| Budget Heritage | 5 | 25 sessions of proven XS-XL point system |
+| **Total** | **35/35** | **Strongest moat score in ADR history** |
+
+## Links
+
+- **Spec:** `docs/specs/focus_auto_runner_featureai.md`
+- **Competitive research:** `docs/specs/continuous_autonomous_execution_featureai.md`
+- **Extends:** ADR-0006 (Focus Commands — adds auto to the 5-command focus group)
+- **Extends:** ADR-0003 (Smart Execution — inherits budget, tiers, behavioral rules)
+- **Heritage:** execplan.md (capacity budget), superplan.md (scan/priority), panmonty_protocol.md (categories, loop exhaustion)
+- **Modules:** focus.cjs, constants.cjs, pan-tools.cjs, core.cjs, utils.cjs
+- **Competitive field:** Cursor Background Agents, GitHub Copilot Coding Agent, Aider --watch-files, Claude Code headless -p, Cline YOLO mode

package/docs/decisions/ADR-0016-enhanced-doc-sync.md

@@ -0,0 +1,54 @@
+# ADR-0016: Enhanced Documentation Sync (focus-sync v2)
+
+## Status
+Accepted (shipped in v2.5.0 — 2026-03-07)
+
+## Context
+The current `focus sync` command checks only README.md for 3 count patterns (commands, agents, modules). An end-to-end documentation audit on 2026-03-04 revealed 20+ staleness issues across 8 files:
+
+- Stale counts in DEVELOPMENT.md (test count 1277 vs actual 1314)
+- Old command names from v1.0.0 rename in EXAMPLES.md (`resume-work`, `pause-work`, `complete-milestone`, `new-milestone`)
+- Wrong Copilot CLI prefix in FAQ.md (`/pan:*` should be `/pan-*`)
+- Missing `focus-auto` command in USER-GUIDE.md tables
+- Placeholder URL in TROUBLESHOOTING.md
+
+Every feature addition (e.g., focus-auto in v2.3.0) requires manual audit of 14+ files. This was demonstrably missed and is unsustainable.
+
+## Decision
+Enhance `checkDocStaleness()` in `focus.cjs` to:
+
+1. **Scan all doc files** (README, ARCHITECTURE, DEVELOPMENT, CONTRIBUTING, USER-GUIDE, CLI-REFERENCE) for count patterns — not just README
+2. **Detect old command names** using a `COMMAND_RENAME_MAP` constant in `constants.cjs` (17 entries from v1.0.0 rename)
+3. **Check command table completeness** — parse markdown tables containing `/pan:` entries and verify all `.md` files in `commands/pan/` have entries
+4. **Cross-reference version** — compare `package.json` version against CHANGELOG top entry
+5. Return enriched output with new fields (`old_names`, `missing_commands`, `version_match`) alongside existing fields
+
+Output contract is **additive** — existing `stale`, `current`, `actuals` fields preserved. No breaking changes.
+
+## Consequences
+
+### Positive
+- Catches 90%+ of documentation staleness automatically
+- Reduces manual audit from ~30 minutes to <1 minute
+- Prevents stale docs from shipping when used in focus-auto loop
+- Old command names detectable programmatically (was purely visual before)
+
+### Negative
+- More file reads per sync invocation (~12 files vs 1) — acceptable at <100ms total
+- COMMAND_RENAME_MAP requires maintenance if future renames happen (unlikely after v1.0.0 stabilization)
+
+### Neutral
+- No changes to the focus-sync.md command file structure (it reads JSON output)
+- No new modules or exports beyond the COMMAND_RENAME_MAP constant
+- Test count checking uses stored count rather than live `npm test` execution
+
+## Options Considered
+
+1. **Status quo** — Keep checking only README. Rejected: misses 90% of staleness.
+2. **Full AST-based doc parser** — Parse markdown AST for tables, headings. Rejected: over-engineering for regex-solvable patterns.
+3. **Enhanced regex scanning (chosen)** — Extend existing pattern to more files and add targeted checks. Right balance of coverage and simplicity.
+
+## Links
+- Feature spec: `docs/specs/focus_sync_v2_featureai.md`
+- Related: ADR-0006 (focus commands), ADR-0014 (internal cleanup)
+- Audit findings: 20+ issues across Categories A-D in spec

package/docs/decisions/ADR-0017-enhanced-focus-design.md

@@ -0,0 +1,69 @@
+# ADR-0017: Enhanced focus-design with Autonomous Investigation
+
+## Status
+Accepted (shipped in v2.3.0 — 2026-03-03)
+
+## Context
+PAN's `/pan:focus-design` is the most comprehensive AI feature specification workflow in the ecosystem (10 phases, 4 modes, strategic analysis, security modeling, ADR generation). However, competitive analysis reveals three critical gaps:
+
+1. **No autonomous codebase investigation** before spec creation — Cline's `/deep-planning` leads here with silent grep/read before asking any questions, consistently called "game changer" by users
+2. **No impact analysis** showing what existing modules are affected — no competitor does this either, representing an opportunity to lead
+3. **Clarification questions are generic templates**, not grounded in discovered code patterns — Cline's informed questions (referencing actual found patterns) are the industry benchmark
+
+Additionally, the older `/featureAI` command (730 lines in `.claude/commands/`) contains stale hardcoded counts (31 commands, 604 tests, 14 modules) and should be deprecated in favor of focus-design.
+
+The competitive landscape in March 2026 includes:
+- **Cline `/deep-planning`**: Best autonomous investigation, clean context separation
+- **Windsurf megaplan**: Structured clarification questionnaire, persistent plan.md
+- **Amazon Kiro**: Requirements → Design → Tasks three-phase spec with hooks
+- **GitHub Spec-Kit**: Constitution + spec + plan + tasks (4x slower than iterative prompting per Scott Logic)
+- **Cursor Rules**: Context injection, no spec workflow
+- **Aider Architect**: Two-model separation, no persistent artifact
+
+## Decision
+Enhance the existing `commands/pan/focus-design.md` command file with 10 additive changes:
+
+1. **Phase 0.8: Autonomous Codebase Investigation** — silent discovery + impact analysis before any design work
+2. **Phase 0.2.5: Before/After State Specification** — explicit current→desired behavior mapping (from Copilot Workspace)
+3. **Structured Acceptance Criteria** — table format with verification methods and pass conditions
+4. **Remove all hardcoded counts** — use dynamic language throughout
+5. **Scope Calibration Guidance** — auto-mode selection table for agents
+6. **Dynamic Competitor Selection** — domain-aware research, not hardcoded 6 tools
+7. **Phase 1.5: Informed Clarification** — questions MUST reference discovered code patterns
+8. **MCP/context7 Tools** — add to allowed-tools frontmatter
+9. **Updated Convention Checklist** — PAN-specific function names (readStateSafe, output, toPosix, etc.)
+10. **Enhanced Report Summary** — investigation depth, competitive position, informed questions
+
+This is a command .md file enhancement only — zero code changes needed.
+
+## Consequences
+
+### Positive
+- Specs grounded in actual code patterns instead of generic templates
+- Impact analysis prevents implementation surprises (blast radius known before design)
+- Best-in-industry depth: investigation + strategic analysis + security + testing — no competitor combines all four
+- Zero code changes needed — immediate deployment across all 5 runtimes
+- Informed questions save user time (no generic "do you want tests?" — always want tests)
+- Scope calibration prevents overkill for small features (Scott Logic's SDD critique addressed)
+
+### Negative
+- Command file grows from ~664 to ~800 lines (more complex for maintainers)
+- Investigation phase adds ~20% more time to full-mode runs
+- /featureAI users must update their muscle memory to focus-design
+
+### Neutral
+- Spec format remains markdown (no structural change to output artifacts)
+- Existing specs produced by focus-design v1 remain valid
+- All 4 modes (full/internal/outward/spike) remain — new phases follow mode skip rules
+
+## Options Considered
+1. **Keep focus-design as-is** — Rejected: competitive gap is real and widening (Cline, Kiro, Windsurf all advancing)
+2. **Create a new command (/pan:focus-design-v2)** — Rejected: unnecessary command proliferation, cognitive load +1
+3. **Enhance focus-design.md (chosen)** — Best: additive changes, zero breaking changes, immediate impact
+4. **Build investigation into a separate agent** — Rejected: investigation must be inline to ground subsequent phases; separate agent loses context
+
+## Links
+- Spec: `docs/specs/focus_design_v2_featureai.md`
+- Related commands: focus-design.md, featureAI.md (deprecated)
+- Predecessor: ADR-0006 (Focus Commands), ADR-0015 (Focus Auto-Runner)
+- Competitive analysis sources: Cline docs, Windsurf Wave 10, Kiro docs, Spec-Kit, Martin Fowler SDD analysis

package/docs/decisions/ADR-0018-user-reality-testing.md

@@ -0,0 +1,84 @@
+# ADR-0018: User Reality Testing System
+
+## Status
+Accepted (shipped in v2.3.0 — 2026-03-03)
+
+## Context
+PAN Wizard supports 5 AI coding tool runtimes (Claude Code, OpenCode, Gemini CLI, Codex, Copilot CLI) across 3 platforms (Windows, Mac, Linux). The existing test suite (1,314 tests, 42 files) validates individual core modules and CLI commands in isolation using `node:test` and temp directories.
+
+However, real users experience PAN through multi-step workflows: install, init project, create phases, plan, execute, verify. The current tests don't replicate this. Specific gaps:
+
+1. **Runtime install tests verify file structure but don't run commands** — 4 of 5 runtimes are structure-only
+2. **No CI pipeline** — tests run only on developer's Windows machine; Mac/Linux coverage = 0
+3. **Installer is script-only** — 2,636 LOC with no exported functions; internal logic untestable
+4. **No multi-step workflow tests** — no test validates a sequence like install → init → plan → verify
+5. **No structured diagnostics** — test failures require reading raw output to identify the broken runtime/platform
+
+The user explicitly reported: "the testing done is not replicating user testing."
+
+## Decision
+
+Build a 4-component "User Reality Testing" system:
+
+### Component 1: Scenario Runner
+Extend `tests/helpers.cjs` with `createScenarioRunner(runtime)` that:
+- Creates temp dir, installs PAN for specified runtime
+- Provides `execute(steps)` function for multi-step workflow testing
+- Returns structured diagnostics on failure (runtime, platform, step, error, fix hint)
+
+### Component 2: Installer Function Extraction
+Extract pure/testable functions from `bin/install.js` into `bin/install-lib.cjs`:
+- `getDirName()`, `expandTilde()`, content converters, attribution processing, `parseJsonc()`
+- `install.js` requires `install-lib.cjs` — behavior unchanged, functions now independently testable
+
+### Component 3: Scenario Test Files
+New `tests/scenarios/` directory with 7 test files:
+- `runtime-matrix.test.cjs` — all 5 runtimes: install + basic commands
+- `workflow-init.test.cjs`, `workflow-phases.test.cjs`, `workflow-focus.test.cjs` — multi-step flows
+- `installer-functions.test.cjs` — direct tests of extracted functions
+- `state-integrity.test.cjs`, `cross-platform-paths.test.cjs` — edge cases
+
+### Component 4: CI Pipeline
+`.github/workflows/ci.yml` with matrix: 3 OS x Node 18/20/22
+
+### Separation of Test Tiers
+- `npm test` — fast unit/integration tests only (existing 1,314 tests, <30s)
+- `npm run test:scenarios` — slow scenario tests only (<60s)
+- `npm run test:all` — everything (<90s)
+
+## Consequences
+
+### Positive
+- All 5 runtimes tested on 3 platforms via CI — 15-cell coverage matrix
+- Multi-step workflow bugs caught before users hit them
+- Installer functions independently testable for the first time
+- Structured diagnostics reduce bug investigation time
+- Foundation for future: scenario recording, regression dashboards
+
+### Negative
+- Installer extraction has medium risk of introducing bugs (mitigated by running full E2E tests after)
+- Scenario tests are slower than unit tests (~15s) — separated into own script
+- CI matrix (9 cells) consumes GitHub Actions minutes
+
+### Neutral
+- Zero new runtime dependencies (uses only `node:test`, `node:assert`, `node:fs`, `node:child_process`)
+- No changes to user-facing commands or output schemas
+- Existing 1,314 tests completely unchanged
+
+## Options Considered
+
+1. **Do nothing** — Continue with unit tests only. Rejected: user explicitly reports the gap; cross-platform bugs will continue reaching users.
+
+2. **Docker-based testing** — Run tests in containers per platform. Rejected: adds infrastructure dependency; GitHub Actions matrix covers platforms more simply.
+
+3. **Mock-heavy approach** — Mock filesystem, shell, etc. Rejected: defeats the purpose of "reality testing"; mocks hide the bugs we're trying to find.
+
+4. **Full installer rewrite as module (chosen: partial extraction)** — Rewrite all 2,636 LOC as a proper module with exports. Rejected: too risky for one change; partial extraction (just pure functions) gives 80% of the testing benefit with 20% of the risk.
+
+5. **Scenario runner with structured diagnostics (CHOSEN)** — Extend existing patterns, extract testable installer functions, add CI pipeline.
+
+## Links
+- Spec: `docs/specs/user_reality_testing_system_featureai.md`
+- Related: ADR-0015 (focus-auto-runner), ADR-0009 (production deployment checklist)
+- Existing E2E: `tests/e2e-install.test.cjs`
+- Installer: `bin/install.js`

package/docs/decisions/ADR-0019-end-to-end-user-acceptance-testing.md

@@ -0,0 +1,113 @@
+# ADR-0019: End-to-End User Acceptance Testing
+
+## Status
+Accepted (shipped in v2.3.0 — 2026-03-03)
+
+## Context
+ADR-0018 introduced the "User Reality Testing" system: a scenario runner (`createScenarioRunner`), installer function extraction (`install-lib.cjs`), 47 scenario tests, and a CI pipeline. These tests validate that `pan-tools.cjs` commands work when run from an installed location across all 5 runtimes.
+
+However, a critical gap remains: **no test validates the host tool integration surface**. When a user installs PAN into a project folder and opens it in VS Code with Claude Code or Copilot CLI, the host tool consumes:
+
+1. **`settings.json` / `config.json`** — Hook registration with runtime-specific key casing (PascalCase for Claude, camelCase for Copilot) and structure (nested vs flat)
+2. **Command `.md` files** — Placed in runtime-specific directories (`.claude/commands/pan/`, `.github/skills/pan-*/SKILL.md`, etc.)
+3. **Hook `.js` files** — Referenced by path in settings/config, must actually exist on disk
+4. **Agent `.md` files** — Must have valid frontmatter (`name`, `description`) and XML structure tags (`<objective>`)
+
+If any of these contracts break — a hook key gets the wrong casing, a command file is misplaced, a hook references a nonexistent file — the user experience silently fails. The host tool doesn't throw an error; it just doesn't discover the commands or fire the hooks.
+
+The user explicitly identified this gap: "it works well from a system test but contain no end state user test, where the panwizard is installed into a folder opened up with VSCODE and is called via claude or copilot."
+
+## Decision
+
+Add 5 new scenario test files that validate the **host tool integration contract** — the file structures and schemas that Claude Code and Copilot CLI consume:
+
+### Test File 1: `settings-schema.test.cjs`
+Validates `settings.json` (Claude) and `config.json` (Copilot) after installation:
+- JSON is parseable
+- Hook event keys use correct casing per runtime
+- Hook entries are arrays with correct internal structure
+- `statusLine` key exists with `command` field
+- No cross-contamination (no camelCase in Claude, no PascalCase in Copilot)
+
+### Test File 2: `command-discovery.test.cjs`
+Validates command files are placed where each runtime expects them:
+- Claude: `.claude/commands/pan/*.md` with >= 30 files
+- Copilot: `.github/skills/pan-*/SKILL.md` with >= 30 directories
+- Codex: `.codex/skills/pan-*/SKILL.md` with >= 30 directories
+- Critical commands exist by name (plan-phase, exec-phase, verify-phase, new-project, quick)
+- No empty command files (size > 100 bytes)
+
+### Test File 3: `hook-registration.test.cjs`
+Validates hook entries reference real files:
+- Each hook command path resolves to an existing `.js` file on disk
+- 3 expected hooks present: `pan-check-update.js`, `pan-context-monitor.js`, `pan-statusline.js`
+- Hook files are non-empty (> 100 bytes, not stub files)
+- No duplicate hook entries (installer deduplication worked)
+
+### Test File 4: `agent-structure.test.cjs`
+Validates agent `.md` files have valid structure:
+- Agent count >= 10
+- Each agent has `name` in frontmatter
+- Each agent body contains `<objective>` XML tag
+- No empty agent files
+
+### Test File 5: `user-workflow-e2e.test.cjs`
+Validates a realistic 10-step user workflow produces coherent state:
+1. Install (via createScenarioRunner)
+2. Setup .planning/ structure
+3. config-ensure-section
+4. phase add (first)
+5. phase add (second)
+6. phases list (shows both)
+7. state add-decision
+8. state-snapshot (reflects all changes)
+9. validate health (passes)
+10. generate-slug (utility works in context)
+
+### What This Does NOT Test
+- LLM responses (non-deterministic)
+- VS Code extension behavior (third-party code)
+- Actual hook execution (requires real event triggers from host tool)
+- Interactive readline prompts (requires stdin mocking)
+- Full `/pan:new-project` interactive flow (requires LLM)
+
+## Consequences
+
+### Positive
+- Host tool integration surface validated for Claude and Copilot — catches silent failures before release
+- Command discoverability tested for 3 runtimes — prevents "command not found" bugs
+- Hook registration integrity verified — catches reference-to-nonexistent-file bugs
+- Agent structure validated — catches broken agent files early
+- Full user workflow coherence tested — catches state corruption across operations
+- ~50 new tests, additive only — no existing tests modified
+- Zero runtime dependencies — uses only `node:test`, `node:assert`, `node:fs`, `node:path`
+
+### Negative
+- Tests document assumed host tool schemas (settings.json, config.json) which may change in future host tool releases
+- Agent validation is structural only (frontmatter + XML tags) — doesn't validate prompt quality
+- Workflow e2e is a subset of the full user journey (no LLM interaction, no interactive Q&A)
+
+### Neutral
+- No changes to installer, core modules, or user-facing commands
+- Existing 1,466 tests completely unchanged
+- `npm run test:scenarios` glob automatically picks up new files
+- CI pipeline (from ADR-0018) automatically runs new tests
+
+## Options Considered
+
+1. **Start actual Claude Code / Copilot process and invoke commands** — Rejected: requires full IDE installation, non-deterministic, not automatable in CI, massively complex setup.
+
+2. **Mock the host tool's config loading** — Rejected: we'd be testing our mock, not the real integration. The point is to validate real files.
+
+3. **JSON Schema validation with a library** — Rejected: adds runtime dependency. Manual key checking is sufficient and self-documenting.
+
+4. **Validate file contracts by reading installed directory structure (CHOSEN)** — Validate the files that host tools consume: settings/config JSON, command placement, hook references, agent structure. This is deterministic, automatable, zero-dep, and catches the exact class of bugs users report.
+
+5. **Golden file comparison** — Partially deferred to v2: compare installed files against known-good snapshots. Good for detecting unexpected changes but brittle across versions.
+
+## Links
+- Spec: `docs/specs/end_to_end_user_acceptance_testing_featureai.md`
+- Predecessor: ADR-0018 (User Reality Testing — scenario runner, installer extraction, CI)
+- Related: ADR-0009 (production deployment checklist)
+- Installer: `bin/install.js` (settings.json/config.json generation at lines 1520-1669)
+- Scenario runner: `tests/helpers.cjs` (createScenarioRunner at lines 59-108)