pan-wizard 3.33.0 → 3.34.0

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
 ```

package/commands/pan/focus-plan.md

@@ -2,6 +2,7 @@
 name: focus-plan
 group: Focus
 description: Create capacity-budgeted work batch with spec coverage verification and 4 execution modes
+argument-hint: "[--budget N] [--mode bugfix|balanced|features|full] [--priority P0-P6] [--lean] [--no-spec-check]"
 allowed-tools:
   - Read
   - Write
@@ -24,7 +25,7 @@ Create a capacity-budgeted work batch from focus-scan results **with mandatory v
 This command plans work batches for the **host project** — NOT for PAN Wizard's own infrastructure.
 
 **NEVER include items targeting 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
 
 If a scan item points to a PAN infrastructure file, DROP it from the batch. PAN's files are not the project's responsibility.
@@ -38,11 +39,11 @@ If no recent scan exists, run `/pan:focus-scan` automatically before proceeding.
 **Flags:**
 - `--budget N` — Override capacity budget in points (default: 50, min: 5, max: 100)
 - `--mode MODE` — Execution mode. Default: `balanced`
-  - `bugfix` — P0->P1->smallest-first, no feature work (40 pts)
+  - `bugfix` — one pass over P0-P4 in priority order, smallest-first within each; P5-P6 left out (40 pts)
   - `balanced` — **Default.** Mix of stability fixes + feature development, 60/40 split (50 pts)
-  - `features` — Feature-focused: 80% budget on P3-P5, P0 crashes still mandatory (50 pts)
-  - `full` — Full-spectrum: enhanced budget, all priorities equally weighted (60 pts)
-- `--priority P0-P6` — Only pick items from these priority tiers
+  - `features` — Feature-focused: P0 crashes mandatory, then 80% of what that leaves on P3-P5 (50 pts)
+  - `full` — Full-spectrum: one pass over every priority, P0 first and smallest-first within each; budget raised to at least 60 (60 pts)
+- `--priority PN` — Only pick items at priority PN or higher (P0 through PN), e.g. `--priority P2`
 - `--lean` — Apply RS filtering: exclude items with RS < 1.5
 - `--no-spec-check` — Skip spec coverage verification (NOT recommended — use only for pure bugfix batches)
 
@@ -133,13 +134,13 @@ This becomes the **spec gap backlog** — items that specs/ADRs promised but the
 ### `features` — Feature-Focused Sprint
 - **Budget:** 50 pts
 - **Mandatory pass:** All P0 items
-- **Feature pass (80%):** 40 pts for P3-P5
-- **Stability pass (20%):** 10 pts for P1-P2 quick wins
+- **Feature pass (80%):** 80% of what the P0 pass left, for P3-P5 (40 pts when there are no P0 items)
+- **Stability pass (20%):** the rest of it, for P1-P2 quick wins (10 pts when there are no P0 items)
 - **Spec coverage:** Feature items MUST map to spec requirements — reject unspecified feature work
 
 ### `full` — Full-Spectrum Marathon
 - **Budget:** 60 pts
-- **All priorities weighted equally, largest-impact-first**
+- **One pass over every priority in priority order, smallest-first within each**
 - **Spec coverage:** Full traceability — every item maps to a spec/ADR requirement or is flagged as unspecified
 
 ### Batch Selection Algorithm
@@ -220,7 +221,7 @@ This becomes the post-execution checklist for `/pan:focus-exec`.
 
 ## Phase 5: Output
 
-Produce a batch file at `.planning/focus/batch-<YYYY-MM-DD>.json` via `pan-tools focus plan`:
+Write the batch to `.planning/focus/batch-<YYYY-MM-DD>.json` yourself — `{date, mode, budget, allocated, items: [...]}`, each item `{id, title, priority, effort, points, tier, files}` with `tier` one of `MICRO`, `STANDARD`, `FULL` (`focus exec` and `focus classify-stages` group items by it, and an item without it lands in no wave); `focus exec`, `focus classify-stages` and `/pan:focus-exec` read an `items` or `batch` array. Do not hand this step to `pan-tools focus plan`: it ignores the scan and the spec mapping, batches only incomplete roadmap phases, pending todos and `.planning/patterns.md` entries, and overwrites the day's batch file:
 
 ```markdown
 ## Focus Batch — <date>
@@ -252,11 +253,11 @@ Produce a batch file at `.planning/focus/batch-<YYYY-MM-DD>.json` via `pan-tools
 | NCA affordability | ADR-0018 SC-4 | Blocked by SC-1, SC-2 | After this batch |
 
 ### Dependency Order
-```
+~~~
 #1 (P0 crash fix) → independent
 #3 (categories) → #4 (keywords) → #5 (match types)
 #2 (tests) → independent
-```
+~~~
 
 ### Post-Execution Verification Checklist
 - [ ] SC-1: Category count >= 65 → `SELECT COUNT(*) FROM stx_category`

package/commands/pan/focus-scan.md

@@ -2,8 +2,10 @@
 name: focus-scan
 group: Focus
 description: Deep-dive strategic work scan with prioritized items and Reality Score filtering
+argument-hint: "[--focus <area>] [--quick] [--refresh] [--lean]"
 allowed-tools:
   - Read
+  - Write
   - Bash
   - Grep
   - Glob
@@ -22,13 +24,13 @@ Survey the project for prioritized work items with evidence-based scoring. $ARGU
 This command scans the **host project's source code** for work items — not PAN Wizard's own infrastructure.
 
 **Exclude these directories from scanning:**
-- `.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 never report PAN planning files as "issues")
 - 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 report TODO/FIXME items found in PAN files. Do not flag PAN files as lacking test coverage. Do not suggest improvements to PAN's agents, commands, or core modules.
 
-If a scan finding points to a file inside `.claude/`, `.github/`, `.opencode/`, `.gemini/`, or `.codex/` — DROP IT. It is not the project's responsibility.
+If a scan finding points to a file in one of the PAN paths listed above — DROP IT. It is not the project's responsibility.
 
 ---
 
@@ -235,7 +237,7 @@ Gather items from:
 ## Phase 5: Scan Assembly
 
 ### 5.1 Output
-Return JSON via `pan-tools focus scan` with all items, or write to `.planning/focus/` for persistence.
+Write the scan to `.planning/focus/scan-<YYYY-MM-DD>.md`, where `/pan:focus-plan` builds from it and `/pan:focus-exec` updates it (Stage 5.2). `pan-tools focus scan` does not take these items: it lists only incomplete roadmap phases that have a directory, pending todos and `.planning/patterns.md` entries.
 
 ### 5.2 Document Structure
 

package/commands/pan/focus-sync.md

@@ -2,6 +2,7 @@
 name: focus-sync
 group: Focus
 description: Synchronize documentation after changes — check staleness and update counts
+argument-hint: "[--readme | --docs | --arch | --all]"
 allowed-tools:
   - Read
   - Bash
@@ -24,7 +25,7 @@ Synchronize project documentation across all files. $ARGUMENTS
 This command synchronizes the **host project's documentation** — NOT PAN Wizard's own infrastructure files.
 
 **NEVER sync, modify, or report staleness 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.** Documentation sync applies to the project's README, docs, guides, and code comments — not to PAN's installed agents or command definitions.
@@ -91,7 +92,7 @@ CHANGELOG.md              <- Version history
 
 ## Report
 
-Output via `pan-tools focus sync`:
+Report in this shape (`pan-tools focus sync` itself returns only JSON — `actuals` (counts of commands, agents and modules), `stale` / `current` entries for those counts, any `--tests` / `--suites` counts, renamed `/pan:` commands and the package.json-vs-CHANGELOG version, plus `stale_count` and `needs_sync`):
 
 ```
 | Area | Status | Finding |

package/commands/pan/git.md

@@ -15,7 +15,7 @@ allowed-tools:
 <objective>
 Phase-aware git workflow with safety guardrails built in. Every subcommand that modifies history runs safety checks. Rollback uses PAN snapshot tags (`pan-rollback-*`), which `pan-tools rollback-snapshot <phase>` creates; no workflow creates them for you.
 
-Works with any git repository — PAN installation not required.
+Works with any git repository — no PAN project (`.planning/`) needed, only the installed `pan-tools.cjs`.
 </objective>
 
 <subcommands>
@@ -59,19 +59,19 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git commit \
 ```
 
 **Options:**
-- `--type` — `feat | fix | docs | test | refactor | chore`
+- `--type` — `feat | fix | docs | test | refactor | perf | chore`
 - `--message` — Commit message body
 - `--all` — Stage all changes before committing
 - `--files f1 f2` — Stage specific files
 - `--amend` — Amend last commit (no message needed)
-- `--force` — Bypass deleted-file and sensitive-file blocks
+- `--force` — Bypass the deleted-file block (not the sensitive-file block)
 
 **Safety checks run automatically:**
 
 | Check | Blocks on | Override |
 |-------|-----------|---------|
-| Deleted files | Staged deletions found | `--force` |
-| Sensitive files | `.env`, `.pem`, `.key`, `secret`, `password`, `token` | `--force` |
+| Deleted files | A deletion anywhere in the repository (`git status --porcelain`, staged or not) | `--force` |
+| Sensitive files | A staged path ending `.env`, `.pem` or `.key`, or containing `credentials`, `secret`, `password` or `token` (PAN's own `.planning/metrics/tokens.jsonl` is exempt) | None: narrow `commit.sensitive_patterns` in `.planning/config.json`, or commit the file yourself |
 
 **Output:** `{committed, hash, type, safety_checks}`
 
@@ -174,14 +174,14 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git diff --staged --file src/ap
 ### rollback — Revert to PAN Snapshot
 
 ```bash
-# Rollback to latest PAN snapshot tag (requires clean working tree)
+# Rollback to the last pan-rollback-* tag in name order — the newest only among one phase's snapshots (requires clean working tree)
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git rollback
 
 # Preview — does NOT reset, shows what would happen
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git rollback --dry-run
 
 # Rollback to specific tag
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git rollback --tag pan-rollback-03-1714000000
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git rollback --tag pan-rollback-3-20260415T101500
 ```
 
 **Rollback workflow:**
@@ -219,5 +219,5 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs git sync --remote upstream --br
 </workflow>
 
 <runtime_note>
-All subcommands work with any git repository regardless of whether PAN is installed or `.planning/` exists. The only requirement is a valid git repo (`git init` or cloned).
+All subcommands work with any git repository, whether or not it holds a PAN project (`.planning/`); they run the installed `pan-tools.cjs`. The only requirement is a valid git repo (`git init` or cloned).
 </runtime_note>

package/commands/pan/health.md

@@ -2,7 +2,7 @@
 name: pan:health
 group: System
 description: Diagnose planning directory health and optionally repair issues
-argument-hint: "[--repair]"
+argument-hint: "[--repair] [--standards] [--full] [--drift] [--links]"
 allowed-tools:
   - Read
   - Bash
@@ -19,5 +19,5 @@ Validate `.planning/` directory integrity and report actionable issues. Checks f
 
 <process>
 Execute the health workflow from @~/.claude/pan-wizard-core/workflows/health.md end-to-end.
-Parse --repair flag from arguments and pass to workflow.
+Pass the arguments to the workflow, which forwards `--repair`, `--standards`, `--full`, `--drift` and `--links` to `validate health`.
 </process>