pan-wizard 3.33.0 → 3.35.0

package/commands/pan/design-phase.md

@@ -2,7 +2,7 @@
 name: pan:design-phase
 group: Phase Lifecycle
 description: Design a roadmap phase before planning — architecture, ADR, threat-lite, machine-checkable criteria — verified by an independent checker
-argument-hint: "[phase] [--spike] [--skip-design] [--redesign]"
+argument-hint: "<phase> [--spike] [--skip-design] [--redesign]"
 agent: pan-designer
 allowed-tools:
   - Read
@@ -53,16 +53,16 @@ ELSE (default):
 1. **Validate phase** — error if the phase number is missing or not in `roadmap.md`.
 2. **Prime context** — resolve the phase directory; gather `{phase}-context.md`, `{phase}-research.md`, and the phase boundary from `roadmap.md`.
 3. **Design** — spawn `pan-designer` with a `<files_to_read>` block (context, research, roadmap boundary, `CLAUDE.md`). It fills in `templates/design.md` at the `phase` tier (`spike` if `--spike`).
-4. **Verify (reflexion loop)** — spawn `pan-design-checker` with the drafted design + the boundary source:
+4. **Verify (reflexion loop)** — spawn `pan-design-checker` with the drafted design + the boundary source, plus an `<open_findings>` block holding `pan-tools findings list --phase {phase} --agent pan-design-checker --status open` (empty on the first check):
    - If it PASSES → done.
    - If it finds gaps (iteration 1) → `pan-designer` revises (address genuine gaps only), re-check.
    - If it finds gaps (iteration 2) → final revision, record remaining gaps as caveats.
-   - **Max 2 revision iterations** (design → check → revise → check → final) — the same guardrail `plan-phase` uses with `pan-plan-checker`.
+   - **Max 2 revision iterations** (design → check → revise → check → final revision, not re-checked). `plan-phase` also caps its loop at 2 revisions, but checks a third time after the second.
    - **Record each check.** Save the checker's returned text verbatim to `{phase_dir}/{padded_phase}-design-check.md` with the Write tool. Record it and branch on the verdict it prints (`PASS` or `GAPS`):
      ```bash
      node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "{phase}" --agent pan-design-checker --file "{phase_dir}/{padded_phase}-design-check.md" --raw
      ```
-     A re-check is the next attempt and closes the gaps it no longer reports. When the final iteration still has gaps, record them as the caveats they are before writing the design:
+     A re-check is the next attempt. It answers each earlier gap in `resolutions`, and the record closes the ones answered `resolved` with evidence; a gap it neither reports nor answers stays open. When the final iteration still has gaps, record them as the caveats they are before writing the design:
      ```bash
      node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "{phase}" --agent pan-design-checker --open --as deferred --reason "design caveat after 2 revision iterations"
      ```
@@ -81,5 +81,5 @@ Design FAILS if: phase not found in roadmap, or the designer returns empty/malfo
 </completion_contract>
 
 <handoff>
-`{phase}-design.md` is an **optional upstream input** to `/pan:plan-phase`, consumed by `pan-planner` exactly as `{phase}-context.md` is. `pan-plan-checker` verifies the plan conforms to it (Design Conformance dimension). A phase without a design.md still plans — the design step strengthens planning, it does not gate it.
+`{phase}-design.md` is an **optional upstream input** to `/pan:plan-phase`, consumed by `pan-planner` like `{phase}-context.md` — except that the plan-phase workflow does not list it in the planner's or checker's `<files_to_read>`, so both use it only when they find it in the phase directory. `pan-plan-checker` verifies the plan conforms to it (Design Conformance dimension). A phase without a design.md still plans — the design step strengthens planning, it does not gate it.
 </handoff>

package/commands/pan/discuss-phase.md

@@ -33,6 +33,8 @@ Extract implementation decisions that downstream agents need — researcher and
 <context>
 Phase number: $ARGUMENTS (required)
 
+**`--auto`** (or `workflow.auto_advance: true`): no questions — the workflow writes a minimal context.md from the roadmap goal, idea.md, project.md and requirements.md, then spawns plan-phase with `--auto`; the interactive steps below are skipped.
+
 Context files are resolved in-workflow using `init phase-op` and roadmap/state tool calls.
 </context>
 

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
@@ -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 }`.
@@ -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>
@@ -133,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)
@@ -188,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
@@ -244,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:
@@ -259,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.
@@ -354,9 +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
-- `distill_complete`: Distill only — scan found no bloat findings 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
@@ -491,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
@@ -528,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)
 
@@ -552,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.
@@ -582,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.
 
 ---
 
@@ -600,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
 
@@ -624,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
 
@@ -634,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.

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.

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

package/commands/pan/focus-exec.md

@@ -2,6 +2,7 @@
 name: focus-exec
 group: Focus
 description: Automated batch execution pipeline with 6 stages, behavioral rules, 3 execution tiers
+argument-hint: "[--budget N] [--mode bugfix|balanced|features|full] [--priority P0-P6] [--dry-run] [--no-commit] [--continue] [--deep-review]"
 allowed-tools:
   - Read
   - Write
@@ -85,7 +86,7 @@ Each stage has a restricted set of appropriate actions. Using the wrong tool at
 This command executes work on the **host project's source code** — not on PAN Wizard's own infrastructure.
 
 **Do not read, modify, or fix files 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
 - 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.** If a batch item targets a PAN infrastructure file, SKIP it with reason "PAN infrastructure — out of scope." Never modify PAN's agents, commands, core modules, or dispatcher as part of project work.
@@ -116,7 +117,7 @@ HARD STOP conditions (do not proceed to next stage):
 - `--dry-run` — Run Stages 1-2 only (show what WOULD be executed)
 - `--no-commit` — Skip the commit step in Stage 6
 - `--continue` — Resume a previously interrupted execution
-- `--deep-review` (v3.4+) — After each high-stakes item's execution, run `/pan:review-deep` for that item (pan-hardener + pan-meta-reviewer security + cross-check). Slows the campaign by roughly 3× per item that triggers the deep pass; use for batches touching auth/payment/migrations.
+- `--deep-review` (v3.4+) — After each high-stakes item's execution, run the deep pass on that item's changed files: spawn pan-hardener (`<output_path>` `.planning/reviews/<item-id>/hardener.md`), then pan-meta-reviewer on its report (`.planning/reviews/<item-id>/meta.md`), and merge with `pan-tools review-deep merge <item-id> --hardener-file … --meta-file …` (no first-pass review, so no `--reviewer-file`; `/pan:review-deep` itself needs a phase). Slows the campaign by roughly 3× per item that triggers the deep pass; use for batches touching auth/payment/migrations.
 
 ---
 
@@ -161,7 +162,7 @@ Every code change must be tested before moving to the next item.
 Test cadence by tier:
 - **MICRO (XS/S):** Run specific test after implementing. Batch up to 3 independent items before smoke.
 - **STANDARD (M):** Full test suite after each item.
-- **FULL (L/XL):** Build hooks + full test suite after each item.
+- **FULL (L/XL):** The project's build step (if it has one) + full test suite after each item.
 
 ### Rule 4: Don't Invent — Follow the Plan
 Implement exactly what the batch says. Do not:
@@ -210,8 +211,7 @@ This catches emergent interactions: 5 "add try-catch" fixes might reveal the mod
 1. **Check Project Status** — git status, recent commits
 2. **Test Baseline** — run test suite, record current counts
 3. **Create rollback snapshot** — git tag for safety
-4. **Prime prompt cache** — `pan-tools cache prime --summary` (once; all sub-agents in the next 5 min hit cached context)
-5. **Report** — Output session start summary
+4. **Report** — Output session start summary
 
 **Circular optimization — init trace:**
 ```bash
@@ -286,7 +286,7 @@ Display the execution batch to user, then continue automatically.
 3. DESIGN — outline approach before coding
 4. STATE INTENT — "I will modify [files]. Risk: [what could break]"
 5. IMPLEMENT in logical chunks
-6. BUILD — build hooks if hooks changed
+6. BUILD — run the project's build step if the item changed what it builds
 7. TEST — full test suite
 8. CONFIRM — all pass -> DONE | fail -> investigate (15 min max) -> REVERT -> FAILED
 ```