pan-wizard 3.32.0 → 3.34.0

package/commands/pan/exec-phase.md

@@ -2,7 +2,7 @@
 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]"
+argument-hint: "<phase-number> [--gaps-only] [--skip-tests] [--skip-review] [--fast] [--deep-review] [--hierarchical] [--auto]"
 allowed-tools:
   - Read
   - Write
@@ -31,38 +31,36 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
 Execution is complete when ALL conditions are met:
 1. Every plan in the phase has been dispatched to a subagent
 2. All subagents have returned (success or failure)
-3. Full test suite passes with count >= pre-execution baseline
+3. The verifier's test gate ran the suite (or verification was skipped because `workflow.verifier` is off)
 4. All verified tasks committed with accurate commit messages
 5. state.md updated with phase progress
 6. Failed tasks (if any) logged with error classification and root cause
 
-Execution FAILS if: test count drops below baseline after all retries, or state corruption is detected.
+Execution FAILS if: a plan fails and the user stops the run, or state corruption is detected.
 </completion_contract>
 
 <wave_dependencies>
-Discovery → Baseline: Test baseline MUST be captured before any wave executes (regression detection requires it)
-Baseline → Wave N: Each wave MUST wait for the previous wave to complete and pass verification
-Wave N → Commit N: Wave changes MUST pass tests before committing (don't commit broken code)
-All Waves → Final Verify: Full test suite MUST pass after all waves complete
-Final Verify → State Update: state.md MUST only be updated after verification passes
+Discovery → Waves: executors commit each task themselves; the workflow's generate_tests step and the verifier's test gate run the suite (the orchestrator does not commit waves)
+Wave N → Wave N+1: Each wave waits for the previous wave's executors to return; their summaries are spot-checked (summary.md, commits, no `## Self-Check: FAILED`) before the next wave starts
+All Waves → Verify: the verifier's test gate judges the suite; a failed gate is a gap for `/pan:plan-phase <N> --gaps`, not a revert
+Verify → Phase complete: `phase complete` runs only after verification passes (or a `human_needed` verdict is approved), or after the "verification skipped" report when `workflow.verifier` is off
 
 HARD STOP conditions (do not proceed to next wave):
-- Baseline capture fails (test suite broken before we start) → STOP, report to user
-- Wave N test count drops below baseline after 3 retries → revert wave, mark all wave tasks FAILED, continue to next wave
 - State corruption detected (malformed state.md or plan files) → STOP execution entirely, report to user
-- All waves complete but final test count < baseline → revert last wave, re-verify
+- A plan failed and the user chose "Stop?" → partial completion report; if they continue, never run a plan that depends on a failed one (`phase-plan-index --failed`)
 </wave_dependencies>
 
 <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.
+- `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after `/pan:plan-phase <N> --gaps` 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`).
 - `--deep-review` — After the normal code review, run the deep review inline: the `/pan:review-deep` process, a security audit by pan-hardener plus a cross-check by pan-meta-reviewer, merged into `.planning/reviews/<N>/deep-review.md`. It builds on the normal review, so it is skipped with `--skip-review` or `--fast`. Recommended for phases touching auth, payment, PII, migrations, or public APIs. Costs roughly 3× a normal review.
-- `--hierarchical` (v3.4+, Claude Code only — needs native sub-agent spawning) — Spawn `pan-conductor` as a top-level orchestrator that decomposes the phase and spawns executor/reviewer/verifier sub-agents in sequence. `pan-conductor` runs on the reasoning tier under the default profile, which inherits the model you launched with (the `budget` profile drops it to mid). Bounded by safety harness: max 2 nesting levels, 12 spawns per phase, budget ceiling, `.planning/orchestration/abort` kill-switch. On runtimes that cannot spawn nested agents, this flag is a no-op with a warning and falls back to flat exec. Use only for large phases (≥4 autonomous plans) where wall-clock reduction justifies the ~20-30% orchestration tax.
+- `--hierarchical` (v3.4+, Claude Code only — needs native sub-agent spawning) — Spawn `pan-conductor` as a top-level orchestrator that decomposes the phase and spawns executor/reviewer/verifier sub-agents in sequence. `pan-conductor` carries no `model:` and is spawned without one, so it runs on the model you launched the session with under every profile. Bounded by safety harness: max 2 nesting levels, 12 spawns per phase, budget ceiling, `.planning/orchestration/abort` kill-switch. On runtimes that cannot spawn nested agents, this flag is a no-op with a warning and falls back to flat exec. Use only for large phases (≥4 autonomous plans) where wall-clock reduction justifies the ~20-30% orchestration tax.
+- `--auto` — Autonomous chain: sets `workflow.auto_advance`, and once verification passes with no gaps runs the transition to the next phase instead of stopping at a menu. `/pan:plan-phase --auto` passes `--auto --no-transition`, which stops after verification and the roadmap update and returns `PHASE COMPLETE`, or returns `GAPS FOUND` (no roadmap update) when verification finds gaps.
 
 Context files are resolved inside the workflow via `pan-tools init execute-phase` and per-subagent `<files_to_read>` blocks.
 </context>
@@ -73,34 +71,20 @@ Each execution stage has a restricted set of appropriate actions. Using the wron
 | Stage | Read | Grep/Glob | Edit/Write | Bash (tests) | Bash (git) | Agent |
 |-------|------|-----------|------------|--------------|------------|-------|
 | Discovery (find plans) | YES | YES | NO | NO | NO | NO |
-| Baseline capture | YES | NO | NO | YES | YES | NO |
 | Wave execution | YES | YES | YES | YES | NO | YES |
 | Wave verification | YES | YES | NO | YES | NO | NO |
-| Wave commit | NO | NO | NO | NO | YES | NO |
 | Final verification | YES | YES | NO | YES | NO | NO |
 | State update | YES | NO | YES | NO | YES | NO |
 
 **Key constraints:**
 - Discovery: read-only — do not modify files while figuring out what to execute
-- Baseline: run tests + git status only — no code changes before baseline is captured
 - Wave verification: NO Edit/Write — you are checking work, not doing more work
-- Wave commit: git operations only — all code changes must be done before committing
+- Commits: each executor commits its own tasks; the orchestrator makes no wave commits, and commits the phase's tracking files after `phase complete`
 </action_gating>
 
-<cache_priming>
-**Before Discovery, prime the prompt cache once per invocation.** All subagents spawned within the next 5 minutes will hit the cache instead of re-sending the full context.
-
-Run once:
-```
-pan-tools cache prime --summary
-```
-
-This returns `{blocks: [{path, bytes, cache}], total_bytes, sha}` for the cacheable set (project.md, requirements.md, roadmap.md, state.md, standards.md). The `sha` is stable across identical inputs, so repeated calls within the phase hit cached reads.
-
-When spawning subagents for wave execution, include the cacheable block paths in each agent's system-context so a host runtime that supports prompt caching (Claude Code does) can mark them `cache_control: ephemeral`. Where prompt caching is unavailable, this step is a no-op — nothing breaks, just no savings.
-</cache_priming>
-
 <process>
+**With `--hierarchical` on Claude Code:** run the workflow below, but in place of its wave execution, code review and `verify_phase_goal` spawn, spawn `pan-conductor` (`subagent_type="pan-conductor"`) with the phase number and the other flags: it runs the executors, the reviewer and the verifier itself, under its safety harness. When it returns, route on the verification its verifier wrote, as `verify_phase_goal` does, and carry on with the steps after it. On any other runtime, print `--hierarchical is not supported on <runtime>. Falling back to flat exec.` and run the workflow unchanged.
+
 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).
 
@@ -111,25 +95,25 @@ Preserve all workflow gates (wave execution, checkpoint handling, verification,
 
 **Attention Anchor — emit after each wave completes:**
 ```
-Wave {N}/{total} complete | Tasks: {done}/{total} | Tests: {baseline} → {current}
+Wave {N}/{total} complete | Plans: {done}/{total} | Failed: {plan IDs, or none}
 Remaining waves: {list of wave numbers with task counts}
 Next: Wave {N+1} — {task count} tasks [{task IDs}]
 ```
-This prevents drift in multi-wave phases where the agent loses track of which waves remain and what the test baseline was.
+This prevents drift in multi-wave phases where the agent loses track of which waves remain and which plans failed.
 
 **Task tracking:** where your runtime offers a todo or task-tracking tool, you may keep the wave list in it. Do not depend on one: some runtimes offer none on their newest models (Claude Code gates its task tools behind `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` there). The attention anchor above, the wave summaries and state.md are the record either way.
 
 **State Intent Before Implementing (M+ tasks):**
 For each STANDARD or FULL task, state before coding: "I will modify [files], adding [what], to achieve [goal]. Risk: [what could break]."
 
-**Pre-Commit Verification Checklist — apply before each wave commit:**
+**Pre-Commit Verification Checklist — the executors commit each task themselves (there is no wave commit); check their work against it when a wave returns:**
 1. Every modified file was read before editing
-2. `git diff --stat` contains only files related to the current wave's tasks
-3. Test suite passes and count meets or exceeds pre-wave baseline
+2. The wave's commits touch only files related to its tasks
+3. No summary carries `## Self-Check: FAILED` (the suite as a whole is judged by the verifier's test gate)
 4. Commit message lists only tasks that are verified (tests ran, tests passed)
-5. No secrets or credentials staged
+5. No secrets or credentials in the wave's commits
 
-If any check fails: fix and re-verify before committing.
+If any check fails: treat that plan as failed and route it as the workflow's spot-check does ("Retry plan?" or "Continue with remaining waves?").
 
 **Error Recovery Classification — apply when any task fails:**
 - RECOVERABLE (retry up to 3 times): test failure after code change, build syntax error, file not found (search for moved path)

package/commands/pan/experiment.md

@@ -2,6 +2,7 @@
 name: experiment
 group: Self-Improvement
 description: Manage external experiments — scaffold, run, harvest, promote findings back to PAN
+argument-hint: "new <slug> --idea <path> [--runtime r] [--root path] [--budget n] | list [--root path] | manifest <slug> | run <slug> [--timeout sec] [--prompt text] | status <slug> | stop <slug> | harvest <slug> [--source-root path] [--force] | prune <slug> [--hard]"
 allowed-tools:
   - Read
   - Write
@@ -32,7 +33,7 @@ allowed-tools:
 
 - Building production user features. Use `/pan:new-project` and `/pan:exec-phase` directly.
 - Validating a single-file change. The experiment loop is heavy — use `npm test` and `/pan:quick`.
-- Inside the PAN source repo. The command **refuses** to scaffold experiments inside `d:\PanWizard\` (or wherever the source is cloned). The experiment root defaults to `~/pan-experiments/`.
+- Inside the PAN source repo. The command **refuses** to scaffold experiments inside PAN's source repository, wherever it is cloned. The experiment root defaults to `~/pan-experiments/`.
 
 ---
 
@@ -47,7 +48,7 @@ Scaffold a new experiment folder. Creates:
 ├── .planning/
 │   ├── idea.md              ← copied from --idea path
 │   └── experiment.json      ← manifest (slug, runtime, created_at, etc.)
-└── .claude/ (or .codex/, .gemini/, .opencode/, .github/)   ← PAN install for chosen runtime
+└── .claude/ (or .codex/, .gemini/, .opencode/, .github/)   ← PAN install for chosen runtime — only when pan-tools runs from a source checkout (beside `bin/install.js`); the installed copy skips it and records `installer_skipped` in experiment.json
 ```
 
 **Flags:**
@@ -57,7 +58,7 @@ Scaffold a new experiment folder. Creates:
 | `--idea <path>` | required | Path to the idea.md doc; copied into the experiment |
 | `--runtime <r>` | `claude` | Which AI coding runtime to install: claude / codex / gemini / opencode / copilot |
 | `--root <path>` | `~/pan-experiments/` | Override the experiment root directory |
-| `--budget <pts>` | `80` | Optional budget cap (saved to manifest, enforced by W2 runner) |
+| `--budget <pts>` | none | Optional budget cap, saved to the manifest (the runner does not enforce it) |
 | `--skip-installer` | `false` | Don't run the PAN installer (dev-only) |
 
 **Slug rules:** lowercase letters, digits, hyphens. Max 40 chars. No leading/trailing hyphen.
@@ -73,7 +74,7 @@ Enumerate all experiments under the root. Returns `{ experiments: [...], count }
 | Flag | Default | Purpose |
 |------|---------|---------|
 | `--root <path>` | `~/pan-experiments/` | Override the root |
-| `--raw` | `false` | Human-readable output instead of JSON |
+| `--raw` | `false` | No effect: `list` always prints JSON |
 
 ### `/pan:experiment manifest <slug>`
 
@@ -98,12 +99,12 @@ Spawn the external AI runtime against the experiment folder. **Synchronous** —
 | Flag | Default | Purpose |
 |------|---------|---------|
 | `--timeout <sec>` | `3600` (60 min) | Hard timeout in seconds; runner sends SIGTERM at deadline |
-| `--prompt <text>` | `/pan:new-project --auto @.planning/idea.md` | Prompt passed to the external runtime |
+| `--prompt <text>` | `/pan:new-project --auto @.planning/idea.md` — the Claude Code / Gemini form; pass the runtime's own for Codex (`$pan-new-project …`) or OpenCode (`/pan-new-project …`) | Prompt passed to the external runtime |
 | `--root <path>` | `~/pan-experiments/` | Override the experiment root |
 
-**Returns:** `{ status: "done"\|"failed", stop_reason: "success"\|"error"\|"timeout"\|"manual", exit_code, elapsed_ms, started_at, ended_at }`. Run-state is also persisted to `<experiment>/.planning/run-state.json`.
+**Returns:** `{ experiment_id, status: "done"\|"incomplete"\|"failed", stop_reason: "success"\|"incomplete"\|"error"\|"timeout", exit_code, elapsed_ms, started_at, ended_at }` — `incomplete` is an exit 0 whose state.md does not show the milestone completed. Run-state is also persisted to `<experiment>/.planning/run-state.json`.
 
-**Runtime support:** claude / codex / gemini / opencode (via `RUNTIME_RUNNERS` adapter map in `runner.cjs`). GitHub Copilot CLI is **unsupported** for the `run` subcommand — no documented headless prompt mode. Copilot users can still scaffold and harvest manually.
+**Runtime support:** claude / codex / gemini / opencode (via `RUNTIME_RUNNERS` adapter map in `runner.cjs`). GitHub Copilot CLI is **unsupported** for the `run` subcommand — the runner has no Copilot adapter yet (`copilot -p` does run a prompt headless). Copilot users can still scaffold and harvest manually.
 
 **Billing note (Claude runtime):** headless `claude -p` runs bill against the **Claude Agent SDK credit pool** — a monthly allotment separate from your interactive subscription limits (Anthropic split the two effective June 15, 2026). Experiment runs do not consume interactive-session quota, but heavy experimentation can exhaust the SDK pool independently. Note: the CLI `experiment run` does not capture a metrics envelope — the `billing_pool: "agent_sdk"` tagging is produced only via the runner module's capture-metrics API, not from the command line, so CLI run-state has no `metrics` key to reconcile against.
 
@@ -140,7 +141,7 @@ A `harvest.json` manifest is written at the destination capturing source path, t
 | Flag | Default | Purpose |
 |------|---------|---------|
 | `--root <path>` | `~/pan-experiments/` | Override the experiment root |
-| `--source-root <path>` | PAN source repo | Override harvest destination |
+| `--source-root <path>` | the root of the PAN copy running pan-tools: a source checkout, or the runtime's config dir (e.g. `.claude/`) for an installed copy | Override harvest destination |
 | `--force` | `false` | Overwrite an existing harvest at the destination |
 
 **Returns:** `{ experiment_id, harvest_path, harvested_paths: [...], total_bytes, harvested_at, pan_version }`. On conflict without `--force`, returns `{ error }`.
@@ -208,7 +209,7 @@ pan-tools experiment manifest md-lint
 
 ## Safety guards
 
-- **Never inside source repo.** `newExperiment` refuses to write to `d:\PanWizard\` (or wherever the PAN source is). Mirrors `bin/install.js` `PAN_SOURCE_ROOT` guard.
+- **Never inside source repo.** `newExperiment` refuses to write inside PAN's source repository, wherever it is cloned. Mirrors `bin/install.js` `PAN_SOURCE_ROOT` guard.
 - **No clobber.** Refuses to scaffold over an existing experiment folder of the same slug.
 - **Slug validation.** Lowercase + digits + hyphens, max 40 chars. Rejects uppercase, spaces, special characters.
 - **Idea path validation.** Errors if the `--idea` file doesn't exist.
@@ -222,4 +223,4 @@ pan-tools experiment manifest md-lint
 
 ## Runtime support
 
-Works in all 5 runtimes (Claude / Codex / Gemini / OpenCode / Copilot). The W2 external runner (subprocess invocation of the external session) supports Claude / Codex / Gemini / OpenCode; GitHub Copilot CLI lacks a headless prompt mode and is opt-out for the `run` subcommand.
+Works in all 5 runtimes (Claude / Codex / Gemini / OpenCode / Copilot). The W2 external runner (subprocess invocation of the external session) supports Claude / Codex / Gemini / OpenCode; GitHub Copilot CLI has no runner adapter yet and is opt-out for the `run` subcommand.

package/commands/pan/focus-auto.md

@@ -2,6 +2,7 @@
 name: focus-auto
 group: Focus
 description: Continuous scan-plan-exec loop with purpose-driven categories and a layered safety harness
+argument-hint: "[--source scan|backlog] [--category CAT] [--mode MODE] [--budget N] [--max-cycles N] [--total-budget N] [--enforce-budget] [--verify-reserve F] [--continue] [--stop] [--status] [--dry-run] [--deep-review] [--parallel-research] [--parallel-verify] [--clean-seal]"
 allowed-tools:
   - Read
   - Write
@@ -23,7 +24,7 @@ Run purpose-driven improvement campaigns with a single command. The auto-runner
 This command runs improvement campaigns on the **host project's source code** — not on PAN Wizard's own infrastructure.
 
 **Exclude these directories from scanning and execution:**
-- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- `.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.agents/`, and the Copilot runtime paths PAN installs into under `.github/` (`agents/`, `skills/`, `hooks/`, `copilot/`, `pan-wizard-core/`, `pan-local-patches/`, `mcp.json`, `package.json`, `pan-file-manifest.json`) — 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.
@@ -35,9 +36,10 @@ A campaign is complete when ANY stop condition is met:
 1. Max cycles reached (--max-cycles, default 10)
 2. Total budget exhausted (--total-budget) — **advisory by default**: tracked and surfaced but does NOT stop the run unless `--enforce-budget` (or config `budget.enforce: true`) is set
 3. Scan returns zero items for the selected category
-4. Context window drops below 25% (CRITICAL threshold)
-5. User sends /pan:focus-auto --stop
-6. Category-specific completion (e.g., prompts_remaining === 0)
+4. User sends /pan:focus-auto --stop
+5. Category-specific completion (e.g., prompts_remaining === 0)
+
+The context monitor's notes are not a stop condition: they give no figure and ask for a checkpoint. On the critical note, bring the scan file up to date (items completed and failed) before the next step, then carry on with the cycle. Record it with `focus auto --update` only at its end (Step 2.4): `--update` closes a cycle and runs the stop checks, so a mid-cycle call with nothing done ends the run as `zero_completed`. After the host compacts, re-read the campaign with `focus auto --status`: PAN's state re-injection carries state.md's position, not the campaign's. If the session ends instead, `focus auto --continue` resumes only a stopped run or one with no cycle recorded yet: run `/pan:focus-auto --stop`, then `--continue`.
 
 Each cycle is complete when: scan → plan → exec → commit succeeds, OR a safety harness triggers and the cycle is cleanly aborted with state preserved.
 </completion_contract>
@@ -88,7 +90,8 @@ Wait for the user's reply before proceeding. Do not guess or pick a default cate
 
 ```
 /pan:focus-auto [--source scan|backlog] [--category CAT] [--mode MODE] [--budget N]
-                [--max-cycles N] [--total-budget N] [--continue] [--stop] [--status]
+                [--max-cycles N] [--total-budget N] [--enforce-budget] [--verify-reserve F]
+                [--continue] [--stop] [--status]
                 [--dry-run] [--deep-review]
                 [--parallel-research] [--parallel-verify] [--clean-seal]
 ```
@@ -124,6 +127,7 @@ Wait for the user's reply before proceeding. Do not guess or pick a default cate
 | optimize | P1-P4 | balanced | 50 |
 | prompts | P0-P6 | balanced | 100 |
 | security | P0-P2 | bugfix | 40 |
+| distill | P1-P5 | balanced | 50 |
 
 ## Backlog source (`--source backlog`, ADR-0031)
 
@@ -131,7 +135,7 @@ When `--source backlog` is set, work is selected from the **curated planning sur
 
 1. **Read the backlog once** at Phase 0: actionable items are unchecked rows in `roadmap.md` (phase/plan checkboxes) and unmet `requirements.md` REQ rows. Skip anything struck, completed, or marked blocked.
 2. **Score from the CURRENT document — never a hardcoded ID list.** For each item, derive `RS = (UserValue + TimeCriticality + RiskReduction) / Effort` (1–5 each; Effort from the row's size tag). Sort by wave/priority ascending → RS descending → effort ascending. This re-derives the order from whatever the roadmap says today, so it never goes stale.
-3. **Pop the top survivor each cycle**; re-rank only if a landing changed a dependency. The same budget/cycle/context stops and safety harness apply unchanged.
+3. **Pop the top survivor each cycle**; re-rank only if a landing changed a dependency. The same budget/cycle stops and safety harness apply unchanged.
 4. The backlog ranker reads only PAN's planning files — it embeds **no** project-specific item IDs, test counts, or build commands. A project with no actionable backlog items is a clean stop (`scan returns zero items` equivalent).
 
 ## Concurrency model (when `--parallel-research` / `--parallel-verify`, ADR-0031)
@@ -162,7 +166,8 @@ The proven shape is **parallel read-only research → exactly ONE serial impleme
    - 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]`
+   - Run `pan-tools focus auto --category <SELECTED_CATEGORY> [--source scan|backlog] [--mode MODE] [--budget N] [--max-cycles N] [--total-budget N] [--enforce-budget] [--verify-reserve F] [--deep-review] [--parallel-research] [--parallel-verify] [--clean-seal] [--dry-run]`,
+     passing on every one of these flags the user gave: the tooling reads each of them, and a flag left off here never takes effect
    - If `--dry-run`: display the plan, STOP
    - Record the run state
 
@@ -185,7 +190,7 @@ Phase 2 (each cycle): Scan → Plan → Exec → Commit is strictly sequential w
 HARD STOP conditions:
 - Phase 1 fails (tests broken): Do not enter main loop — report and exit
 - Any cycle: test count drops below baseline after revert → stop campaign, preserve state
-- Context drops below 25%: stop campaign cleanly (safety harness)
+- The context monitor's critical note is not a stop: bring the scan file up to date before the next step, then carry on; record the cycle (`focus auto --update`) only at its end, since `--update` closes the cycle and runs the stop checks
 </phase_dependencies>
 
 ### Phase 2: Main Loop
@@ -241,7 +246,7 @@ For P3-P6 items, compute Reality Score: `RS = (UV + TC + RR) / JS`
 - 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).
+Only keep items within the run's category priority range (see Category Defaults table). Drop items outside the range. If 0 items match: record the empty cycle with Step 2.4's update, `focus auto --update --items-completed 0 --items-failed 0 --points-used 0 --tests-before <N> --tests-after <N>` (`<N>` is the current test count: the last recorded cycle's `tests_after`, or the Phase 1 baseline before the first cycle), so the run ends with its stop reason — `zero_completed`, or `security_complete` / `distill_complete` for those categories (`max_cycles` if this was the run's last cycle) — then go to Phase 3 (Campaign End).
 
 **2.1.5 Write Scan**
 Write scan results to `.planning/focus/scan-<YYYY-MM-DD>-<category>.md` with:
@@ -256,10 +261,10 @@ 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.
+- `bugfix`: All budget on P0 mandatory, then P1, then P2-P4 smallest-first; no separate feature pass (P3-P4 are taken in priority order, P5-P6 left out).
 - `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
+- `full`: One pass over every priority in priority order (P0 first), smallest-first within each
 
 **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.
@@ -351,8 +356,9 @@ Check the response for stop conditions:
 - `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
 - `prompts_complete`: Prompts only — all prompts in document executed — go to Phase 3
-- `security_complete`: Security only — scan found no HIGH/CRITICAL items remaining — go to Phase 3
-- `deep_review_block`: `--deep-review` only — critical pattern detected in changed files — go to Phase 3 with warning
+- `security_complete`: Security only — the cycle recorded zero completed items (how an empty scan ends the run; for this category it replaces `zero_completed`) — go to Phase 3
+- `distill_complete`: Distill only — the cycle recorded zero completed items (how an empty scan ends the run; for this category it replaces `zero_completed`) — go to Phase 3
+- `weekly_limit`: Claude Code's 7-day usage window reached `cost.weekly_limit_stop_pct` (default 90%; read by `pan-tools cost limits`) — the run is stopped, not completed: go to Phase 3, and resume with `--continue` once the window has room
 - `null`: Continue to next cycle
 
 #### Step 2.5: Inter-Cycle Context Management
@@ -418,7 +424,7 @@ Then continue immediately to the next cycle (back to Step 2.1).
 | Layer | Mechanism | Action |
 |-------|-----------|--------|
 | Per-cycle budget | `--budget N` per cycle | Limits single-cycle damage |
-| Cumulative budget | `--total-budget N` | Prevents runaway spending |
+| Cumulative budget | `--total-budget N` | Advisory by default (tracked and surfaced); stops the run only when enforced (`--enforce-budget` / config `budget.enforce`) |
 | Verify reserve | `--verify-reserve F` | Holds back a budget fraction so the final re-verification isn't starved — stops new work early under enforcement (`budget_reserve_reached`) and spends the reserve on the clean re-verify in Phase 3 |
 | Iteration limit | `--max-cycles N` | Hard stop on loop count |
 | Regression circuit breaker | tests_after < tests_before | Immediate stop, status=stopped |
@@ -487,7 +493,7 @@ Alternative format — checklist style:
 5. If tests pass: mark the prompt as complete (`- [x]`), commit, move to next prompt
 6. If tests fail: one fix attempt, then revert and mark prompt as FAILED, move to next prompt
 7. Each prompt = one batch item. Budget: 1 prompt per cycle unless prompt is trivial (XS)
-8. Record `prompts_remaining` count in cycle update — when 0, `prompts_complete` stop fires
+8. Record the count with `--prompts-remaining N` on the cycle's `focus auto --update` — at 0, `prompts_complete` fires; without the flag the count is null and it never fires
 
 **Key rules:**
 - Execute prompts in document order — NEVER skip ahead or reorder
@@ -524,7 +530,7 @@ When a specification document is found that doesn't have a matching micro-prompt
 
 ## Security Category — Execution Details
 
-The security category scans for OWASP Top 10 (2025) violations and STRIDE threats, then fixes them cycle by cycle until the scan returns zero HIGH/CRITICAL findings.
+The security category scans for OWASP Top 10 (2025) violations and STRIDE threats, then fixes them cycle by cycle until the scan finds no P0-P2 (critical, high or medium) items or a cycle completes nothing.
 
 ### Scan approach (Step 2.1)
 
@@ -534,12 +540,12 @@ Three passes per cycle:
 
 | OWASP | Grep pattern | Priority |
 |-------|-------------|---------|
-| A03 Injection | `eval(`, `execSync(`, `` `SELECT.*\${ ``, `child_process.exec(` | P0 |
-| A02 Crypto | `createHash\(['"]md5\|sha1`, `Math\.random\(\)` near auth/token | P0 |
+| A05 Injection | `eval(`, `execSync(`, `` `SELECT.*\${ ``, `child_process.exec(` | P0 |
+| A04 Crypto | `createHash\(['"]md5\|sha1`, `Math\.random\(\)` near auth/token | P0 |
 | A01 Access | Route without auth middleware, IDOR (raw `req.params.id` to DB) | P1 |
-| A05 Misconfig | `origin:\s*['"]?\*`, `Access-Control-Allow-Origin: \*`, stack in response | P1 |
+| A02 Misconfig | `origin:\s*['"]?\*`, `Access-Control-Allow-Origin: \*`, stack in response | P1 |
 | A07 Auth | No session expiry, credentials in URL params | P1 |
-| A04 Design | Missing rate-limit on auth/payment endpoints | P2 |
+| A06 Design | Missing rate-limit on auth/payment endpoints | P2 |
 | A09 Logging | Security events (`login`, `payment`, `admin`) with no log call nearby | P2 |
 
 **Pass 2 — Structural check (always runs):**
@@ -548,7 +554,7 @@ Three passes per cycle:
 - Check for prototype pollution risk: `Object.assign(req.body)` or spread from untrusted input into a stored object
 
 **Pass 3 — Semantic depth (Agent tool, for M/L items only):**
-When a pattern match needs code-path confirmation, spawn an Explore subagent:
+When a pattern match needs code-path confirmation, spawn the `pan-hardener` subagent:
 > "Read [file]. Confirm whether [line N] is reachable from an unauthenticated request path and whether the input is sanitized before use."
 
 Use the confirmation to decide whether to include the item at P0/P1 or drop it as a false positive.
@@ -578,9 +584,9 @@ Treat each security item as a STANDARD or FULL item regardless of effort estimat
 
 ### Stop condition
 
-`security_complete` fires when the scan finds zero P0/P1 items. P2 items (medium) may remain — they won't stop the campaign unless `zero_completed` fires (no items at all).
+`security_complete` fires when a security cycle records zero completed items — `--update` cannot see the scan, so this is how an empty scan ends the run. A cycle whose items all failed reports it too: for this category it replaces `zero_completed`. P2 items (medium) the scan still finds are worked like any other, so they keep the campaign running.
 
-A security campaign that ends with `security_complete` means: no critical or high OWASP violations found in the scanned files. Medium/low items can be addressed in subsequent targeted passes or documented as accepted risk.
+A security campaign that ends with `security_complete` had a cycle that completed nothing: if its scan was empty, no critical or high OWASP violations were found in the scanned files; if its items failed, they are still open. Medium/low items can be addressed in subsequent targeted passes or documented as accepted risk.
 
 ---
 
@@ -596,7 +602,7 @@ The `distill` category targets **AI-generated code bloat** with a 5-pass pipelin
 | 2 | **AST-style analysis** — single-instance factories, deep nesting | Free | review |
 | 3 | **Cross-file graph** — repeated 5+ line blocks, unreferenced exports | Free | review |
 | 4 | **LLM judgment** — pan-distiller agent receives ONLY flagged spans (max 50 lines context per finding); validates pattern, refines tier, proposes minimal rewrite | LLM tokens | safe / review / risky |
-| 5 | **Cross-session memory** — compares findings to `.planning/memory/distill-patterns.md`; flags **regressed** patterns ("we already fixed this") | Free | metadata |
+| 5 | **Cross-session memory** — compares findings to `.planning/memory/distill-patterns.md`; flags **recurring** patterns (detected in an earlier session — the file records detections, not fixes) | Free | metadata |
 
 ### Safety Tiers
 
@@ -620,7 +626,7 @@ Default threshold: **2.0x**. If a cycle's ratio exceeds threshold, the bloat bud
 
 ### Stop condition
 
-`distill_complete` fires when the scan finds zero bloat findings. The codebase is fully distilled for the patterns the deterministic + AST + graph passes detect.
+`distill_complete` fires when a distill cycle records zero completed items — how an empty scan ends the run, and also what a cycle whose items all failed reports, since for this category it replaces `zero_completed`. After an empty scan the codebase is fully distilled for the patterns the deterministic + AST + graph passes detect; after a cycle whose items all failed, those findings are still open.
 
 ### CLI
 
@@ -630,7 +636,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs distill analyze [--touched-loc
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs distill report
 ```
 
-`scan` returns findings. `analyze` adds bloat budget + regressed pattern detection. `report` writes findings to `.planning/memory/distill-patterns.md` for the next session.
+`scan` returns findings. `analyze` adds bloat budget + recurring-pattern detection (its `regressed` list: findings already recorded in an earlier session). `report` writes findings to `.planning/memory/distill-patterns.md` for the next session.
 
 <failure_pattern_capture>
 When the same failure pattern appears in 2+ items within a campaign, capture it for future runs.
@@ -669,7 +675,7 @@ This prevents the campaign from burning budget on items that will predictably fa
 - Continue after a test regression — a test count decrease means code was broken; continuing compounds the damage
 - Expand scope beyond what the scan found — scope creep in an autonomous loop compounds unpredictably across cycles
 - Run more cycles than --max-cycles — the limit exists to cap total cost and prevent runaway loops
-- Spend more points than --total-budget — the budget cap is the user's cost control mechanism
+- Spend more points than --total-budget when the budget is enforced (`--enforce-budget` or config `budget.enforce: true`) — the enforced cap is the user's cost control mechanism
 - Skip recording cycle results via --update — unrecorded cycles break resume, status, and stop-condition checks
 - Change test expectations to match broken code — this hides bugs instead of fixing them
 - Use `git add -A` or `git add .` — bulk staging can accidentally commit secrets, build artifacts, or unrelated changes

package/commands/pan/focus-design.md

@@ -2,6 +2,7 @@
 name: focus-design
 group: Focus
 description: Strategic 10-phase feature investigation, design, and specification pipeline
+argument-hint: "<feature description> [--full | --internal | --outward | --spike] [--gate] [--audit] [--mvp]"
 allowed-tools:
   - Read
   - Write
@@ -31,7 +32,7 @@ Research, design, and specify a new feature with strategic analysis. $ARGUMENTS
 This command investigates and designs features for the **host project** — NOT for PAN Wizard itself.
 
 **NEVER investigate, design for, or reference these PAN infrastructure directories as part of the project:**
-- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- `.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.agents/`, and the Copilot runtime paths PAN installs into under `.github/` (`agents/`, `skills/`, `hooks/`, `copilot/`, `pan-wizard-core/`, `pan-local-patches/`, `mcp.json`, `package.json`, `pan-file-manifest.json`) — PAN runtime directories
 - `.planning/` — PAN planning state (read for context, but don't treat as project source code)
 - Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within those directories
 
@@ -148,7 +149,7 @@ Use case: Quick prototyping, time-boxed exploration, "should we even try this?"
 
 **Modifiers (layer on top of any mode):**
 - `--gate` — Pause after Phase 3 (Strategy) for user review before proceeding to design
-- `--audit` — Add Phase 2.5 reality check of existing implementation (not available with `--spike`)
+- `--audit` — Add Phase 2.5 reality check of existing implementation (not available with `--internal` or `--spike`, which skip Phase 2.5)
 - `--mvp` — Stop after generating the v0 (MVP) task list — skip v1/v2 layers
 
 ### Scope Calibration (Auto-Detection)
@@ -195,7 +196,7 @@ Present the suggested mode and rationale. If the user hasn't specified, use the
 ### 0.1 Problem Statement
 Write a crisp, one-paragraph problem statement answering:
 - What user pain or limitation does this address?
-- Why does it matter NOW for the target users (developers using AI coding assistants)?
+- Why does it matter NOW for the project's target users (as the project's own docs describe them)?
 - What is the cost of NOT doing this?
 
 ### 0.2 Demand Evidence (MANDATORY)
@@ -400,7 +401,7 @@ Based on Phase 0.8 investigation and Phase 1 reconnaissance findings, ask 2-4 IN
 
 ## Phase 2: Competitive Intelligence
 
-**Research how the best AI workflow tools solve this problem.**
+**Research how the best tools in the feature's domain solve this problem.**
 
 ### 2.1 Deep-Dive Research (6+ Tools)
 Select competitor tools relevant to the FEATURE DOMAIN, not a fixed list. Use web search for each.
@@ -707,9 +708,9 @@ or architectural constraints from Phase 3.5]
 [How does this fit into the existing system? Include the dependency map from Phase 1.4
 and the layer violation check from Phase 3.5.2. Show which modules are touched.]
 
-```
+~~~
 [Dependency diagram or integration flow from Phase 1.4 / 3.5.6]
-```
+~~~
 
 ### Interface Contract
 [The output schema or API contract from Phase 3.5.3 — exact format, not just description.
@@ -1073,6 +1074,8 @@ Output a complete summary with:
 
 ## NEVER DO
 
+These rules and ALWAYS DO below apply to the phases your mode actually runs. Anything the Mode + Phase Matrix or a modifier skips (a whole phase, or the parts a lite phase leaves out) is not a violation.
+
 - Design without proving the problem exists (Phase 0 demand evidence is mandatory)
 - Skip competitive research — must be best-of-breed
 - Copy a tool's design without understanding WHY they made that choice

package/commands/pan/focus-doc-audit.md

@@ -2,6 +2,7 @@
 name: focus-doc-audit
 group: Focus
 description: Multi-dimensional document audit — accuracy, freshness, links, cross-consistency, and structural quality
+argument-hint: "[file|directory] [--deep] [--links] [--fix] [--all] [--score-only] [--min-score N] [--format markdown|json|checklist]"
 allowed-tools:
   - Read
   - Write
@@ -28,7 +29,7 @@ Audit project documentation for accuracy, freshness, broken links, structural qu
 This command audits the **host project's documentation** — NOT PAN Wizard's own infrastructure files.
 
 **NEVER audit, modify, or report issues in these PAN directories:**
-- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- `.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.agents/`, and the Copilot runtime paths PAN installs into under `.github/` (`agents/`, `skills/`, `hooks/`, `copilot/`, `pan-wizard-core/`, `pan-local-patches/`, `mcp.json`, `package.json`, `pan-file-manifest.json`) — PAN runtime directories
 - `.planning/` — PAN planning state (read for context, never audit as project docs)
 - Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within PAN runtime directories
 
@@ -316,7 +317,7 @@ For all audited documents, extract overlapping claims and check for contradictio
 When documents disagree, determine which is correct:
 
 ```
-Config files > README > CLAUDE.md > docs/ > CHANGELOG > inline comments
+Config files > README > CLAUDE.md > inline comments > docs/ > CHANGELOG
 ```
 
 The document closer to code is more likely correct.
@@ -499,7 +500,7 @@ Score = (Accuracy × 0.25) + (Freshness × 0.15) + (Completeness × 0.15) +
 | Actionability | 82% | INSTALL.md (70%) | CONTRIBUTING.md (95%) |
 | Readability | 88% | — | — |
 
-**Recommended priority:** Fix docs/API.md (Grade F) → Fix CONTRIBUTING.md (Grade C) → Update INSTALL.md freshness
+**Recommended priority:** Fix docs/API.md (Grade D) → Fix CONTRIBUTING.md (Grade C) → Update INSTALL.md freshness
 ```
 
 ---

package/commands/pan/focus-drift-walking.md

@@ -2,6 +2,7 @@
 name: focus-drift-walking
 group: Focus
 description: Deep documentation-code drift detection, CLAUDE.md alignment, and auto-repair across all project directories
+argument-hint: "[--create] [--audit] [--repair] [--report] [--dir <path>] [--depth N] [--severity critical|high|medium|low|info] [--format markdown|json|checklist] [--quick]"
 allowed-tools:
   - Read
   - Write
@@ -27,7 +28,7 @@ Walk every directory in the project, detect drift between documentation and code
 This command walks the **host project's directories and documentation** — NOT PAN Wizard's own infrastructure.
 
 **ALWAYS EXCLUDE these directories from walking:**
-- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- `.claude/`, `.codex/`, `.gemini/`, `.opencode/`, `.agents/`, and the Copilot runtime paths PAN installs into under `.github/` (`agents/`, `skills/`, `hooks/`, `copilot/`, `pan-wizard-core/`, `pan-local-patches/`, `mcp.json`, `package.json`, `pan-file-manifest.json`) — PAN runtime directories
 - `.planning/` — PAN planning state (read for context, never report as drift)
 - Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within PAN runtime directories
 - Build output directories: `build/`, `dist/`, `out/`, `target/`, `bin/`, `obj/`, `node_modules/`, `.git/`, `__pycache__/`, `.next/`, `.nuxt/`
@@ -49,7 +50,7 @@ When `/pan:focus-drift-walking` is invoked, execute ALL phases for the selected
 - `--report` — Dry run: detect and report drift without modifying anything
 - `--dir <path>` — Target a specific directory subtree only
 - `--depth <n>` — Limit walk depth (default: unlimited)
-- `--severity <level>` — Filter report: `critical`, `warning`, `info` (default: all)
+- `--severity <level>` — Filter report: `critical`, `high`, `medium`, `low`, `info` (default: all)
 - `--format <type>` — Output format: `markdown` (default), `json`, `checklist`
 - `--quick` — Skip Phase 4 (deep semantic analysis) and Phase 7 (cross-project sync)
 
@@ -503,7 +504,7 @@ When root docs and sub-docs disagree:
 
 - Walk build output directories (`build/`, `dist/`, `node_modules/`, `target/`, `obj/`, `__pycache__/`, `.git/`)
 - Report PAN infrastructure files as project drift
-- Auto-fix purpose statements, architecture descriptions, or conventions without `--repair`
+- Auto-fix purpose statements, architecture descriptions, conventions, dependency directions or build commands — even `--repair` only flags these (Phase 6.2)
 - Create documentation for trivial directories (< 3 source files)
 - Include secrets, credentials, or API keys in any generated documentation
 - Guess at file contents — always read and verify