pan-wizard 2.8.1

package/commands/pan/discuss-phase.md

@@ -0,0 +1,84 @@
+---
+name: pan:discuss-phase
+group: Phase Lifecycle
+description: Gather phase context through adaptive questioning before planning
+argument-hint: "<phase> [--auto]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+---
+
+<objective>
+Extract implementation decisions that downstream agents need — researcher and planner will use context.md to know what to investigate and what choices are locked.
+
+**How it works:**
+1. Analyze the phase to identify gray areas (UI, UX, behavior, etc.)
+2. Present gray areas — user selects which to discuss
+3. Deep-dive each selected area until satisfied
+4. Create context.md with decisions that guide research and planning
+
+**Output:** `{phase_num}-context.md` — decisions clear enough that downstream agents can act without asking the user again
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/workflows/discuss-phase.md
+@~/.claude/pan-wizard-core/templates/context.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+Context files are resolved in-workflow using `init phase-op` and roadmap/state tool calls.
+</context>
+
+<process>
+1. Validate phase number (error if missing or not in roadmap)
+2. Check if context.md exists (offer update/view/skip if yes)
+3. **Analyze phase** — Identify domain and generate phase-specific gray areas
+4. **Present gray areas** — Multi-select: which to discuss? (NO skip option)
+5. **Deep-dive each area** — 4 questions per area, then offer more/next
+6. **Write context.md** — Sections match areas discussed
+7. Offer next steps (research or plan)
+
+**CRITICAL: Scope guardrail**
+- Phase boundary from roadmap.md is FIXED
+- Discussion clarifies HOW to implement, not WHETHER to add more
+- If user suggests new capabilities: "That's its own phase. I'll note it for later."
+- Capture deferred ideas — don't lose them, don't act on them
+
+**Domain-aware gray areas:**
+Gray areas depend on what's being built. Analyze the phase goal:
+- Something users SEE → layout, density, interactions, states
+- Something users CALL → responses, errors, auth, versioning
+- Something users RUN → output format, flags, modes, error handling
+- Something users READ → structure, tone, depth, flow
+- Something being ORGANIZED → criteria, grouping, naming, exceptions
+
+Generate 3-4 **phase-specific** gray areas, not generic categories.
+
+**Probing depth:**
+- Ask 4 questions per area before checking
+- "More questions about [area], or move to next?"
+- If more → ask 4 more, check again
+- After all areas → "Ready to create context?"
+
+**Do NOT ask about (Claude handles these):**
+- Technical implementation
+- Architecture choices
+- Performance concerns
+- Scope expansion
+</process>
+
+<success_criteria>
+- Gray areas identified through intelligent analysis
+- User chose which areas to discuss
+- Each selected area explored until satisfied
+- Scope creep redirected to deferred ideas
+- context.md captures decisions, not vague vision
+- User knows next steps
+</success_criteria>

package/commands/pan/exec-phase.md

@@ -0,0 +1,45 @@
+---
+name: pan:exec-phase
+group: Phase Lifecycle
+description: Execute all plans in a phase with wave-based parallelization
+argument-hint: "<phase-number> [--gaps-only] [--skip-tests] [--skip-review] [--fast]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - TodoWrite
+  - AskUserQuestion
+---
+<objective>
+Execute all plans in a phase using wave-based parallel execution.
+
+Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.
+
+Context budget: ~15% orchestrator, 100% fresh per subagent.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/workflows/exec-phase.md
+@~/.claude/pan-wizard-core/references/ui-brand.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS
+
+**Flags:**
+- `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
+- `--skip-tests` — Skip automatic test generation after execution completes.
+- `--skip-review` — Skip automatic code review after execution completes.
+- `--fast` — Skip both test generation and code review (implies `--skip-tests --skip-review`).
+
+Context files are resolved inside the workflow via `pan-tools init execute-phase` and per-subagent `<files_to_read>` blocks.
+</context>
+
+<process>
+Execute the execute-phase workflow from @~/.claude/pan-wizard-core/workflows/exec-phase.md end-to-end.
+Preserve all workflow gates (wave execution, checkpoint handling, verification, state updates, routing).
+</process>

package/commands/pan/focus-auto.md

@@ -0,0 +1,323 @@
+---
+name: focus-auto
+group: Focus
+description: Continuous scan-plan-exec loop with purpose-driven categories and 5-layer safety harness
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+---
+
+# /pan:focus-auto — Continuous Autonomous Improvement Campaigns
+
+Run purpose-driven improvement campaigns with a single command. The auto-runner orchestrates scan, plan, and exec cycles automatically with category-scoped scanning, intelligent defaults, and structured stopping.
+
+**ADR:** ADR-0015 | **Heritage:** execplan budget + PanMonty categories + focus-exec pipeline
+
+## CRITICAL: Project Scope Boundary
+
+This command runs improvement campaigns on the **host project's source code** — NOT on PAN Wizard's own infrastructure.
+
+**ALWAYS EXCLUDE these directories from scanning and execution:**
+- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within PAN runtime directories
+
+**These directories are PAN's own tooling installed into the project.** Do not scan PAN files for TODOs, do not report PAN files as lacking coverage, do not modify PAN agents/commands/core as part of a campaign. If a scan finding or batch item targets a PAN infrastructure file — DROP IT.
+
+---
+
+## FIRST ACTION — Category Selection (if no --category argument)
+
+If `$ARGUMENTS` does NOT contain `--category`, you MUST ask the user before doing anything else.
+
+**Display this text menu and STOP — wait for the user to reply:**
+
+```
+Which category should this auto campaign focus on?
+
+1. **cleanup** — Dead code, unused imports, duplicated logic, magic numbers (P3-P5)
+2. **stability** — Unguarded file ops, missing error handling, crash risks (P0-P2)
+3. **tests** — Missing test coverage, low assertion density (P2-P5)
+4. **features** — Roadmap items, new capabilities (P3-P5)
+5. **docs** — Stale documentation, missing command descriptions (P5-P6)
+6. **optimize** — Performance bottlenecks, redundant computation, robustness hardening (P1-P4)
+
+Reply with a number (1-6) or category name.
+```
+
+**After the user replies, map their response to a category name:**
+- "1" or "cleanup" → SELECTED_CATEGORY = cleanup
+- "2" or "stability" → SELECTED_CATEGORY = stability
+- "3" or "tests" → SELECTED_CATEGORY = tests
+- "4" or "features" → SELECTED_CATEGORY = features
+- "5" or "docs" → SELECTED_CATEGORY = docs
+- "6" or "optimize" → SELECTED_CATEGORY = optimize
+
+**Do NOT proceed past this point without a category. Do NOT guess. Do NOT pick a default. STOP and wait for the user's reply.**
+
+## AUTONOMY RULES (apply AFTER category is selected)
+
+- **DO NOT invoke the Skill tool.** All scan, plan, and exec work is done INLINE within this command.
+- **DO NOT stop between phases.** Execute Phase 0 through Phase 3 (or until a safety harness triggers) without pausing.
+- **DO NOT ask the user any more questions.** After category selection, run fully autonomously.
+- **DO NOT show intermediate results.** Only display: the cycle summary line after each cycle, and the campaign summary table at the end.
+
+## Arguments
+
+```
+/pan:focus-auto [--category CAT] [--mode MODE] [--budget N] [--max-cycles N]
+                [--total-budget N] [--continue] [--stop] [--status] [--dry-run]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--category` | null (all) | cleanup, tests, stability, features, docs |
+| `--mode` | category-dependent | bugfix, balanced, features, full |
+| `--budget` | category-dependent | Points per cycle (5-100) |
+| `--max-cycles` | 10 | Maximum iterations (1-50) |
+| `--total-budget` | 500 | Cumulative points cap (5-5000) |
+| `--continue` | — | Resume stopped/interrupted run |
+| `--stop` | — | Gracefully stop active run |
+| `--status` | — | Show current campaign progress |
+| `--dry-run` | — | Show plan without executing |
+
+## Category Defaults
+
+| Category | Priority Range | Default Mode | Default Budget |
+|----------|---------------|--------------|----------------|
+| cleanup | P3-P5 | balanced | 50 |
+| tests | P2-P5 | balanced | 50 |
+| stability | P0-P2 | bugfix | 40 |
+| features | P3-P5 | features | 50 |
+| docs | P5-P6 | balanced | 30 |
+| optimize | P1-P4 | balanced | 50 |
+
+## Pipeline
+
+### Phase 0: Initialization
+
+1. Parse arguments from `$ARGUMENTS`
+2. Handle quick operations first:
+   - If `--status`: run `pan-tools focus auto --status`, display result, STOP
+   - If `--stop`: run `pan-tools focus auto --stop`, display result, STOP
+3. If `--continue`:
+   - Run `pan-tools focus auto --continue` to resume
+   - Read the restored state to get category, mode, budget, etc.
+   - Skip to Phase 2 (Main Loop)
+4. If no `--category` was provided, you already displayed the menu in FIRST ACTION above. Use SELECTED_CATEGORY from the user's reply.
+5. Initialize new run using the category from step 4:
+   - Run `pan-tools focus auto --category <SELECTED_CATEGORY> [--mode MODE] [--budget N] [--max-cycles N] [--total-budget N] [--dry-run]`
+   - If `--dry-run`: display the plan, STOP
+   - Record the run state
+
+### Phase 1: Baseline Capture
+
+1. Run the project's test suite (discover the test command from `package.json` scripts, `Makefile`, or project docs)
+2. Record baseline test count from the summary line (e.g., "tests 1314")
+3. If tests fail: ERROR — "Cannot start: N tests failing. Fix tests before running auto campaign."
+4. Run `git status` to verify clean working tree (warn if dirty, don't block)
+5. Create safety tag: `git tag -f focus-auto-baseline`
+
+### Phase 2: Main Loop
+
+**For each cycle (1 to max_cycles), execute Steps 2.1 through 2.5 without stopping:**
+
+#### Step 2.1: Scan (INLINE — do NOT invoke /pan:focus-scan)
+
+Perform a deep codebase scan to find actionable work items with evidence.
+
+**2.1.1 Read Codebase State**
+- Read project source files via Glob + Read: modules, entry points, key directories
+- Read planning state: `.planning/config.json`, any state/roadmap files that exist
+- Read `package.json` (or equivalent project manifest) for version and entry points
+
+**2.1.2 Search for Issues**
+- Grep for `TODO`, `FIXME`, `HACK`, `STUB` in source and test directories
+- Grep for error-prone patterns relevant to the category:
+  - **stability:** unguarded `readdirSync`/`readFileSync` without try-catch, `existsSync` calls, `.forEach()` on unverified values, `parseInt` without NaN checks, `.match()` results accessed without null check
+  - **cleanup:** dead code, unused imports, duplicated logic, magic numbers
+  - **tests:** modules without corresponding test files, low assertion density
+  - **features:** roadmap items not yet implemented, README promises without backing code
+  - **docs:** stale documentation, missing command descriptions
+  - **optimize:** N+1 operations (file I/O / network calls inside loops), redundant re-computation (`JSON.parse`/`stringify` of same data), synchronous blocking in async modules (`readFileSync`/`execSync` alongside async exports), algorithmic complexity (nested `.find()`/`.filter()` in loops creating O(n²)+), unnecessary allocations in hot paths (spread in loops, string concat vs `join()`), regex construction inside loops (should be hoisted), unbounded collection growth (`.push()` without size limits), swallowed errors (`catch {}` / `catch { /* */ }`), suboptimal data structures (array `.includes()` where Set is better), dead assignments, unguarded property access on nullable values (`.length`/`.split()`/`.match()[0]` without null check)
+
+**Optimize category: convergent re-scan.** On cycles 2+, cross-reference scan findings against previous cycle completions (`cycles[].items` in auto-run state). Only pick genuinely new items — skip IDs already completed or failed. If the count of new findings drops AND cycle efficiency drops below 30% of the prior cycle's, this signals convergence and the `diminishing_returns` stop condition fires.
+- Use the Agent tool with Explore subagent for thorough analysis if needed
+- Cross-reference findings with any previously completed scan items
+
+**2.1.3 Classify Items**
+
+| Priority | Focus | Criteria |
+|----------|-------|----------|
+| P0 | CRASH/ERROR | Runtime throws, uncaught exceptions |
+| P1 | WRONG RESULTS | Silent corruption, incorrect output |
+| P2 | TEST GAPS | Missing coverage, low assertion density |
+| P3 | INCOMPLETE | Partially implemented features |
+| P4 | NEW FEATURES | From roadmap, not yet started |
+| P5 | TOOLING | DX improvements, CLI UX |
+| P6 | DOCUMENTATION | Docs sync, reference updates |
+
+For P3-P6 items, compute Reality Score: `RS = (UV + TC + RR) / JS`
+- UV = User Value (1-5), TC = Time Criticality (1-5), RR = Risk Reduction (1-5)
+- JS = Job Size: XS=1, S=2, M=3, L=5, XL=8
+- RS >= 3.0 = DO, RS 1.5-2.9 = DEFER, RS < 1.5 = BACKLOG
+
+**2.1.4 Filter by Category**
+Only keep items within the run's category priority range (see Category Defaults table). Drop items outside the range. If 0 items match: go to Phase 3 (Campaign End).
+
+**2.1.5 Write Scan**
+Write scan results to `.planning/focus/scan-<YYYY-MM-DD>-<category>.md` with:
+- Baseline snapshot table (version, tests, modules)
+- Items grouped by priority tier, each with: ID, title, symptom, root cause, fix guidance, file paths, effort size
+- Summary: item count by priority, total points
+
+#### Step 2.2: Plan (INLINE — do NOT invoke /pan:focus-plan)
+
+Create a capacity-budgeted batch from the scan items found in Step 2.1.
+
+**Capacity Points:** XS=1, S=2, M=4, L=10, XL=20
+
+**Allocation by Mode:**
+- `bugfix`: All budget on P0 mandatory, then P1, then P2-P4 smallest-first. No feature work.
+- `balanced`: 60% stability (P0-P2), 40% features (P3-P6)
+- `features`: P0 mandatory, then 80% on P3-P5, 20% on P1-P2 quick wins
+- `full`: All priorities equally weighted, largest-impact-first
+
+**Execution Tiers:** XS/S = MICRO, M = STANDARD, L/XL = FULL
+Select items fitting within the cycle's `budget_per_cycle`. Order: MICRO first, then STANDARD, then FULL.
+
+Write batch to `.planning/focus/batch-<YYYY-MM-DD>-<category>.json`:
+```json
+{ "date": "...", "mode": "...", "budget": N, "allocated": N,
+  "items": [{ "order": N, "id": "...", "title": "...", "priority": "P1",
+              "size": "XS", "points": N, "tier": "MICRO", "file": "...", "fix": "..." }],
+  "deferred": [{ "id": "...", "title": "...", "reason": "..." }] }
+```
+
+#### Step 2.3: Execute (INLINE — do NOT invoke /pan:focus-exec)
+
+Implement each item from the batch created in Step 2.2. Record `tests_before` by running the test suite first.
+
+**For each item in execution order:**
+
+**MICRO items (XS/S):**
+1. Read target file(s) — always read before editing
+2. Implement the fix
+3. Run the specific test file for the changed module
+4. Pass = DONE | Fail = one fix attempt, then revert changes, mark FAILED
+
+**STANDARD items (M):**
+1. State understanding: "Item X — Understanding: ..., Files: ..., Confidence: HIGH/MED"
+2. Read target files + test files
+3. Implement across necessary files
+4. Run the project's test suite
+5. Pass = DONE | Regression = revert all changes for this item, mark FAILED
+
+**FULL items (L/XL):**
+1. State detailed understanding
+2. Read widely: target, callers, tests, related code
+3. Design approach before coding
+4. Implement in logical chunks
+5. Run the project's build step if applicable
+6. Run the project's test suite
+7. Pass = DONE | Fail = investigate (15 min max), then revert, mark FAILED
+
+**After all items in the batch:**
+1. Run full test suite — ALL tests must pass
+2. Record `tests_after` from the summary line
+3. If `tests_after < tests_before`: REGRESSION — revert all changes for this cycle, mark all items FAILED
+4. Update the scan file: mark completed/failed items
+5. Stage specific changed files (not `git add -A`) and commit with accurate message listing only verified items
+6. Count: `items_completed`, `items_failed`, `points_used`
+
+#### Step 2.4: Record Cycle
+
+Run: `pan-tools focus auto --update --items-completed N --items-failed N --points-used N --tests-before N --tests-after N --batch-file <path>`
+
+Check the response for stop conditions:
+- `regression`: Tests decreased — STOP IMMEDIATELY
+- `budget_cap`: Cumulative budget exceeded — go to Phase 3
+- `max_cycles`: Maximum iterations reached — go to Phase 3
+- `zero_completed`: No items completed in this cycle — go to Phase 3
+- `diminishing_returns`: Optimize only — cycle efficiency < 30% of previous cycle — go to Phase 3
+- `null`: Continue to next cycle
+
+#### Step 2.5: Inter-Cycle Check
+
+Display one-line cycle summary: `Cycle N/M | X/Y pts | Z items done | Tests: A -> B`
+
+Then continue immediately to the next cycle (back to Step 2.1).
+
+### Phase 3: Campaign End
+
+1. Run `pan-tools focus auto --status` to get final state
+2. Display campaign summary:
+
+```
+## Campaign Complete
+
+| Metric | Value |
+|--------|-------|
+| Category | <category> |
+| Cycles | N completed |
+| Items completed | X |
+| Items failed | Y |
+| Points used | Z / total_budget |
+| Tests | baseline -> current (delta) |
+| Stop reason | <reason> |
+```
+
+3. Remove safety tag: `git tag -d focus-auto-baseline 2>/dev/null`
+
+## 5-Layer Safety Harness
+
+| Layer | Mechanism | Action |
+|-------|-----------|--------|
+| Per-cycle budget | `--budget N` per cycle | Limits single-cycle damage |
+| Cumulative budget | `--total-budget N` | Prevents runaway spending |
+| Iteration limit | `--max-cycles N` | Hard stop on loop count |
+| Regression circuit breaker | tests_after < tests_before | Immediate stop, status=stopped |
+| Zero-completed guard | 0 items done in a cycle | Stop — further cycles won't help |
+
+## 9 Behavioral Rules
+
+1. **Read Before Write** — Read every file before editing. Understand context, callers, invariants.
+2. **Root Cause** — Fix the actual defect, not symptoms. Trace the code path.
+3. **One Change, One Test** — Test after every code change. MICRO: specific test. STANDARD/FULL: full suite.
+4. **Follow the Plan** — Implement exactly what the batch says. No scope creep.
+5. **Cross-Platform** — Use platform-agnostic path APIs. Follow the project's module format conventions.
+6. **Revert Fast** — 5 min limit on debugging a single failure, then revert and mark FAILED.
+7. **Verify Understanding** — State understanding for M+ items before coding.
+8. **Preserve Tests** — Never change test expectations to match broken code.
+9. **Accurate Commits** — Only claim verified items in commit messages. Include actual test counts.
+
+## NEVER DO
+
+- Invoke the Skill tool (no `/pan:focus-scan`, `/pan:focus-plan`, `/pan:focus-exec`)
+- Stop or pause between phases (unless a safety harness triggers)
+- Ask the user questions after category selection (Phases 1-3 are fully autonomous)
+- Skip the baseline test capture (Phase 1)
+- Continue after a test regression (circuit breaker is mandatory)
+- Expand scope beyond what the scan found
+- Run more cycles than --max-cycles
+- Spend more points than --total-budget
+- Skip recording cycle results via --update
+- Change test expectations to match broken code
+- Use `git add -A` or `git add .` — stage specific files only
+
+## ALWAYS DO
+
+- Execute all phases autonomously from start to finish
+- Capture baseline before first cycle
+- Read every file before editing it
+- Test after every code change
+- Record every cycle via `pan-tools focus auto --update`
+- Stop on ANY safety harness trigger
+- Revert fast when stuck (5 min limit)
+- Display one-line cycle summary between cycles
+- Display campaign summary table at end
+- Commit once per cycle with accurate item list