pan-wizard 3.36.0 → 3.37.0

package/pan-wizard-core/workflows/exec-lean.md

@@ -0,0 +1,69 @@
+<purpose>
+Execute a lean phase in this one session: you do the work the executor agent would do, then one reviewer pass and a verifier check it. Autodev runs this for a phase the engine sized lean (its requirements say precisely what to build, and the engine wrote and checked its plan), so the full exec-phase orchestration (an orchestrating session, a separate executor, test generation) is not needed. The reviewer stays: on the brief test (2026-10-25) a lean build and a bare host's build each carried one high-severity defect the hidden checks could not see, and the reviewer found both. The phase gate still decides when autodev runs `phase complete`.
+</purpose>
+
+<rules>
+- **The plan is the specification.** Do what each task's `<action>` says, nothing more. Do not widen scope; log anything else to `{phase_dir}/deferred-items.md`.
+- **Tests are the spec.** Test files the plan does not list in `files_modified` are read-only. Never delete, rename or skip a test, remove an assertion, or add one that cannot fail. A plan's `supersedes_tests` are the exception it declares: update their expectations to what the named requirements now require, and record each change as a deviation. A test you cannot satisfy without weakening it means stop and reply `## BLOCKED_SPEC_CONFLICT` with the test, the requirement and why both cannot hold.
+- **Commit each task** when its verify command passes: `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "feat({padded}-{plan}): <what the task did>" --files <the files it changed>`.
+- **Unattended:** do not ask questions; take the recommended default and record what you assumed in the summary. Do not start another phase or command.
+</rules>
+
+<process>
+1. **Load the phase:**
+   ```bash
+   INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init execute-phase "{phase}")
+   ```
+   Read `phase_dir`, `phase_number`, `incomplete_plans`, `plan_check` and `verifier_enabled`. When `plan_check.status` is not `ok` or `disabled`, stop and reply `EXECUTION HALTED: plan check {status}`.
+
+2. **Record the test baseline** (what the suite does before this phase):
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs test run --phase "{phase_number}" --baseline > /dev/null
+   ```
+
+3. **Execute each incomplete plan, in order.** Read the plan. For each task: make the change, write or update the tests its action names, run its `<verify>` command until it passes (at most three fix attempts, then record the task as an issue and continue), and commit it. Then write `{phase_dir}/{padded}-{plan}-summary.md` from `~/.claude/pan-wizard-core/templates/summary.md`: what was built, the files, every deviation (including each superseded test expectation: file, what it asserted, what it asserts now, which requirement) and every assumption. Then record progress and commit the summary:
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state advance-plan
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state update-progress
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap update-plan-progress "{phase_number}"
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs requirements mark-complete {the plan's requirements}
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs({padded}-{plan}): complete plan" --files {phase_dir}/{padded}-{plan}-summary.md .planning/state.md .planning/roadmap.md .planning/requirements.md
+   ```
+
+4. **Review.** One pass of the code reviewer over what the phase changed; it looks for what the tests and the verifier do not (a save that is not crash-safe, unchecked arithmetic, state left wrong after an error). Collect the scope, then spawn it:
+   ```bash
+   REVIEW_SCOPE=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs review scope "{phase_number}")
+   CHANGED_FILES_LIST=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs review scope "{phase_number}" --raw)
+   ```
+   ```
+   Task(
+     subagent_type="pan-reviewer",
+     model="{reviewer_model from: node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-reviewer --raw}",
+     prompt="<objective>Review the code changed in phase {phase_number} for defects: behaviour that contradicts the requirements, data loss or corruption (including a crash mid-write), inputs that must throw and do not, state left wrong after an error, security problems. Real defects only, each with a concrete input that shows it.</objective> <files_to_read>./CLAUDE.md (if it exists); changed files: ${CHANGED_FILES_LIST}</files_to_read> <intent>${REVIEW_SCOPE}</intent> <executor_concerns>{what you finished but were not sure of, with why; empty when none}</executor_concerns>"
+   )
+   ```
+   Write its returned text, verbatim and in full with its `pan-verdict` block, to `{phase_dir}/{phase_number}-review.md` (the reviewer is read-only), then record it:
+   ```bash
+   REVIEW_VERDICT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "{phase_number}" --agent pan-reviewer --file "{phase_dir}/{phase_number}-review.md" --raw)
+   ```
+   `PASS`: go on. `PASS_WITH_WARNINGS`: go on, recording that the phase continues past them:
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "{phase_number}" --agent pan-reviewer --open --as deferred --reason "accepted at review: PASS_WITH_WARNINGS"
+   ```
+   `NEEDS_FIXES`: fix each ERROR finding (the tests stay the spec: a fix adds a test for the defect, never weakens one), commit the fixes as `fix({padded}): review findings`, and run the review once more. A second `NEEDS_FIXES` does not loop: record what stays open with `findings dispose ... --as deferred --reason "open after one fix round (unattended)"`, go on to verification, and name those findings in the reply. Never continue past findings silently: an open finding without a recorded reason is what the milestone audit cannot see.
+
+5. **Verify** (skip only when `verifier_enabled` is false, and say so). Spawn the verifier; it is a second pair of eyes, so give it paths, not your conclusions:
+   ```
+   Task(
+     subagent_type="pan-verifier",
+     model="{verifier_model from: node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-verifier --raw}",
+     prompt="Verify phase {phase_number} goal achievement. Phase directory: {phase_dir}. Check the plans' must_haves and requirement IDs against the code. Run the project's test suite as the test gate and record test_gate in the frontmatter. Create verification.md."
+   )
+   ```
+   Then record its verdict:
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "{phase_number}" --file "$(ls {phase_dir}/*-verification.md | head -1)" --raw
+   ```
+
+6. **Reply** in a few lines: the plans executed, the commits, the review verdict and any finding left open, the verification status, and any deviation, assumption or issue. Do not run `phase complete`: autodev runs it next and the phase gate decides.
+</process>

package/pan-wizard-core/workflows/exec-phase.md

@@ -52,6 +52,14 @@ Parse JSON for: `executor_model`, `verifier_model`, `reviewer_model`, `commit_do
 
 **Drift.** For each `plan_drift` entry, tell the executor of that plan, in its prompt, which of its `files_modified` changed since it was planned (`files`), so it re-reads them before editing. An entry with `error` means its `planned_commit` is unknown: say so and continue.
 
+**Size the ceremony** (pass `--quality` or `--full` through when `$ARGUMENTS` has them):
+
+```bash
+SIZING=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs size phase "${PHASE_ARG}" [--quality] [--full])
+```
+
+Show `Ceremony: {path} ({reasons joined by "; "})`. When `SIZING.path` is `lean`, the phase runs without the test-generation agent (`generate_tests`); the executor's own tests, the engine's test gate, one code review pass (`code_review`) and the verifier (`verify_phase_goal`) still run, and the phase gate still decides.
+
 When `parallelization` is false, plans within a wave execute sequentially.
 
 **Circular optimization — start trace session for this exec:**
@@ -96,6 +104,8 @@ PLAN_INDEX=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase-plan-index "
 
 Parse JSON for: `phase`, `plans[]` (each with `id`, `wave`, `autonomous`, `objective`, `files_modified`, `task_count`, `has_summary`), `waves` (map of wave number → plan IDs), `incomplete`, `has_checkpoints`.
 
+**One plan (`--plan <id>`).** Execute only that plan: skip every other plan, then stop after its summary and commits, with no code review, verification or phase routing. `pan-tools autodev run --worktrees` runs each plan this way in its own git worktree and merges the plans back behind a shadow-merge preflight; the phase-level steps run later on the merged result. If the plan already has a summary, say so and stop.
+
 **Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip plans whose frontmatter lacks `gap_closure: true` (`phase-plan-index` does not report it; `frontmatter get <plan> --field gap_closure` exits 1 when it is absent). If all filtered: "No matching incomplete plans" → exit.
 
 **If `--gaps-only`:** this run is the fix round after a verification found gaps — a second attempt at work that failed once. Resolve the executor for that attempt and use it in place of `executor_model` for every spawn in this run:
@@ -186,6 +196,11 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
        - .agents/skills/ (Project skills, if exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
        </files_to_read>
 
+       {Only when the plan's frontmatter has `supersedes_tests`, include:}
+       <superseded_tests>
+       This plan changes behaviour earlier phases built ({supersedes_requirements}). These test files assert the old behaviour and the plan declares them: {supersedes_tests}. Updating their expectations to what those requirements now require is part of the task, not a spec conflict. Record each changed expectation as a deviation in the summary (file, what it asserted, what it asserts now, which requirement). Deleting, skipping or weakening a test is still forbidden, and `verify test-integrity` still checks it.
+       </superseded_tests>
+
        If the plan's `<context>` names `@.planning/roadmap.md`, read `{slice_path}` in its place: it carries this phase's section, its dependencies' goals and its requirements, and the whole roadmap is the largest file in `.planning/` on a long project. Open the whole file only for something the slice leaves out.
 
        <success_criteria>
@@ -353,7 +368,7 @@ Concerns go into the review too: the code_review step passes them to the reviewe
 <step name="generate_tests">
 **Auto-invoke test generation after execution completes.**
 
-**Skip if** `--skip-tests` or `--fast` flag is present in $ARGUMENTS.
+**Skip if** `--skip-tests` or `--fast` flag is present in $ARGUMENTS, or `SIZING.path` is `lean`.
 
 1. Record baseline test count:
 ```bash
@@ -363,12 +378,9 @@ TEST_BASELINE=$(npm test 2>&1 | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
 2. Invoke phase-tests workflow for the completed phase:
 ```
 Task(
-  prompt="Generate tests for phase ${PHASE_NUMBER}.
+  prompt="Follow the phase-tests workflow (~/.claude/pan-wizard-core/workflows/phase-tests.md) for phase ${PHASE_NUMBER}.
 Phase directory: ${phase_dir}
-Read each summary.md to understand what was built.
-Generate unit and integration tests for the new code.
-Discover the project's existing test patterns, directories, frameworks, and helpers before writing tests.
-Follow whatever conventions the project already uses.",
+It classifies each changed file, discovers the project's test patterns, writes the tests the plan approves, and commits them.",
   subagent_type="general-purpose",
   model="{executor_model}",
 )
@@ -379,7 +391,13 @@ Alternatively, if the user's AI tool supports it, invoke the command directly:
 /pan:phase-tests ${PHASE_NUMBER}
 ```
 
-3. Record new test count:
+3. Prove the new tests catch something (V4). A test that passes without the phase's code is tautological:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify red "${PHASE_NUMBER}"
+```
+Rewrite or drop each test it reports as `not_red`; `not_checked` names a runner that cannot run one file and is reported, not failed.
+
+4. Record new test count:
 ```bash
 TEST_AFTER=$(npm test 2>&1 | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
 ```
@@ -400,7 +418,7 @@ TEST_AFTER=$(npm test 2>&1 | grep -E "^(ℹ|#) tests" | awk '{print $NF}')
 <step name="code_review">
 **Spawn pan-reviewer agent to review changed files.**
 
-**Skip if** `--skip-review` or `--fast` flag is present in $ARGUMENTS.
+**Skip if** `--skip-review` or `--fast` flag is present in $ARGUMENTS. A lean phase (`SIZING.path`) keeps this step: the review finds what the tests and the verifier do not.
 
 1. Collect the review scope: the files the phase's commits changed plus any uncommitted or untracked work, whether or not a summary lists them, and the intent to judge them against:
 ```bash
@@ -457,6 +475,16 @@ Task(
 
 3. **Save the report.** Use the Write tool to write the reviewer's returned text, verbatim and in full (including its closing `pan-verdict` block), to `{phase_dir}/{phase_number}-review.md`. The reviewer is read-only by design, so the orchestrator saves the report. `/pan:review-deep` and the findings ledger read this file.
 
+   **Lenses (opt-in).** Check the review mode first:
+   ```bash
+   REVIEW_MODE=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.review_mode 2>/dev/null || echo single)
+   ```
+   When it is `lenses`, run step 2 three times instead of once. Each spawn's prompt carries one `<lens>` (`correctness`, `security`, `maintainability`), and each report is saved to `{phase_dir}/{phase_number}-review-{lens}.md`. Then merge them in code. A finding survives only when at least two of the three passes reported it, and the verdict is recomputed from what survives:
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs review vote --phase "${PHASE_NUMBER}" --out "{phase_dir}/{phase_number}-review.md" "{phase_dir}/{phase_number}-review-correctness.md" "{phase_dir}/{phase_number}-review-security.md" "{phase_dir}/{phase_number}-review-maintainability.md"
+   ```
+   Step 4 records the merged `{phase_number}-review.md` as usual. `single`, the default, is the one pass above.
+
 4. **Record the verdict, then act on it.** The record is what this step branches on. It also adds the findings to the ledger (`.planning/findings.jsonl`) and logs the verdict to the trace, so no separate trace call is needed:
 ```bash
 REVIEW_FILE="{phase_dir}/{phase_number}-review.md"

package/{commands/pan → pan-wizard-core/workflows}/focus-doc-audit.md

@@ -1,20 +1,4 @@
----
-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
-  - Edit
-  - Bash
-  - Grep
-  - Glob
-  - Agent
-  - WebFetch
----
-
-# /pan:focus-doc-audit — Deep Document Audit & Quality Assessment
+# /pan:focus-docs — Deep Document Audit & Quality Assessment
 
 Audit project documentation for accuracy, freshness, broken links, structural quality, cross-document consistency, and code alignment. $ARGUMENTS
 
@@ -24,7 +8,7 @@ Audit project documentation for accuracy, freshness, broken links, structural qu
 
 ---
 
-## CRITICAL: Project Scope Boundary
+## Project Scope Boundary
 
 This command audits the **host project's documentation** — NOT PAN Wizard's own infrastructure files.
 
@@ -41,20 +25,20 @@ If you find yourself auditing a PAN command file — STOP. Refocus on the projec
 
 ## MANDATORY: Execute ALL Phases Automatically
 
-When `/pan:focus-doc-audit` is invoked, execute ALL phases for the selected mode without stopping. Do NOT ask questions between phases. Do NOT skip phases beyond what the mode specifies. Produce a complete audit report at the end.
+When `/pan:focus-docs` is invoked, execute ALL phases for the selected mode without stopping. Do NOT ask questions between phases. Do NOT skip phases beyond what the mode specifies. Produce a complete audit report at the end.
 
 **Usage:**
 ```
-/pan:focus-doc-audit                     # Audit core docs (README, main docs)
-/pan:focus-doc-audit <file>              # Audit a specific file
-/pan:focus-doc-audit <directory>         # Audit all markdown files in directory
-/pan:focus-doc-audit --deep              # Deep audit: verify every claim against code
-/pan:focus-doc-audit --links             # Link validation pass only
-/pan:focus-doc-audit --fix               # Auto-fix simple issues (counts, versions, dates, links)
-/pan:focus-doc-audit --all               # Audit ALL documentation files project-wide
-/pan:focus-doc-audit --score-only        # Skip fix suggestions, just output scores
-/pan:focus-doc-audit --min-score <N>     # Only report files scoring below N% (default: 100 = report all)
-/pan:focus-doc-audit --format <type>     # Output: markdown (default), json, checklist
+/pan:focus-docs                     # Audit core docs (README, main docs)
+/pan:focus-docs <file>              # Audit a specific file
+/pan:focus-docs <directory>         # Audit all markdown files in directory
+/pan:focus-docs --deep              # Deep audit: verify every claim against code
+/pan:focus-docs --links             # Link validation pass only
+/pan:focus-docs --fix               # Auto-fix simple issues (counts, versions, dates, links)
+/pan:focus-docs --all               # Audit ALL documentation files project-wide
+/pan:focus-docs --score-only        # Skip fix suggestions, just output scores
+/pan:focus-docs --min-score <N>     # Only report files scoring below N% (default: 100 = report all)
+/pan:focus-docs --format <type>     # Output: markdown (default), json, checklist
 ```
 
 ---

package/{commands/pan → pan-wizard-core/workflows}/focus-drift-walking.md

@@ -1,19 +1,4 @@
----
-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
-  - Edit
-  - Bash
-  - Grep
-  - Glob
-  - Agent
----
-
-# /pan:focus-drift-walking — Documentation-Code Drift Detection & Alignment
+# /pan:focus-auto --step drift — Documentation-Code Drift Detection & Alignment
 
 Walk every directory in the project, detect drift between documentation and code reality, create missing documentation, repair drifted files, and synchronize the truth hierarchy. $ARGUMENTS
 
@@ -23,7 +8,7 @@ Walk every directory in the project, detect drift between documentation and code
 
 ---
 
-## CRITICAL: Project Scope Boundary
+## Project Scope Boundary
 
 This command walks the **host project's directories and documentation** — NOT PAN Wizard's own infrastructure.
 
@@ -41,7 +26,7 @@ If a drift finding points to a file inside a PAN or build directory — DROP IT.
 
 ## MANDATORY: Execute ALL Phases Automatically
 
-When `/pan:focus-drift-walking` is invoked, execute ALL phases for the selected mode without stopping. Do NOT ask questions between phases. Do NOT skip phases beyond what the mode specifies. Produce a complete drift report at the end.
+When `/pan:focus-auto --step drift` is invoked, execute ALL phases for the selected mode without stopping. Do NOT ask questions between phases. Do NOT skip phases beyond what the mode specifies. Produce a complete drift report at the end.
 
 **Flags:**
 - `--create` — Create missing documentation files in directories that lack them

package/{commands/pan → pan-wizard-core/workflows}/focus-exec.md

@@ -1,19 +1,4 @@
----
-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
-  - Edit
-  - Bash
-  - Grep
-  - Glob
-  - Agent
----
-
-# /pan:focus-exec — Automated Batch Execution Pipeline
+# /pan:focus-auto --step exec — Automated Batch Execution Pipeline
 
 Execute items from the current focus batch with capacity-based sizing, full session lifecycle, and verification. $ARGUMENTS
 
@@ -36,7 +21,7 @@ Execution FAILS if: test baseline cannot be established (Stage 1), or test count
 ## Pipeline Overview
 
 ```
-/pan:focus-exec
+/pan:focus-auto --step exec
 
   Stage 1: SESSION START
     - Check project status, record baseline
@@ -95,7 +80,7 @@ This command executes work on the **host project's source code** — not on PAN
 
 ## Execute All Stages Sequentially
 
-When `/pan:focus-exec` is invoked, run all 6 stages in order. Do not skip stages or stop between them unless tests regress.
+When `/pan:focus-auto --step exec` is invoked, run all 6 stages in order. Do not skip stages or stop between them unless tests regress.
 
 <stage_dependencies>
 Stage 1 → Stage 2: Baseline MUST exist before batch loads (regression detection requires it)
@@ -106,7 +91,7 @@ Stage 5 → Stage 6: Docs MUST be updated before commit (commit captures the com
 
 HARD STOP conditions (do not proceed to next stage):
 - Stage 1: Test suite fails → fix tests before proceeding
-- Stage 2: No batch file found → tell user to run /pan:focus-plan
+- Stage 2: No batch file found → tell user to run /pan:focus-auto --step plan
 - Stage 4: Test count below baseline → revert last changes, re-verify
 </stage_dependencies>
 
@@ -235,7 +220,7 @@ baseline_commit: <current HEAD>
 
 ### 2.1 Find Active Batch
 Search for: `.planning/focus/batch-*.json`
-Pick the newest. If none exists, tell user to run `/pan:focus-plan` first.
+Pick the newest. If none exists, tell user to run `/pan:focus-auto --step plan` first.
 
 ### 2.2 Read and Validate the Batch
 Extract all items: ID, Title, Priority, Effort, Points, Tier, Files.
@@ -409,7 +394,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace end 2>/dev/null
 ### 6.4 Final Report
 
 ```markdown
-## /pan:focus-exec Complete
+## /pan:focus-auto --step exec Complete
 
 | Stage | Status |
 |-------|--------|
@@ -427,8 +412,8 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace end 2>/dev/null
 - **Tests:** Before N -> After M (+K new)
 
 ### Resume
-Run `/pan:focus-exec --continue` for remaining items.
-Run `/pan:focus-scan` to regenerate the scan.
+Run `/pan:focus-auto --step exec --continue` for remaining items.
+Run `/pan:focus-auto --step scan` to regenerate the scan.
 ```
 
 ---

package/{commands/pan → pan-wizard-core/workflows}/focus-plan.md

@@ -1,18 +1,4 @@
----
-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
-  - Edit
-  - Bash
-  - Grep
-  - Glob
----
-
-# /pan:focus-plan — Capacity-Budgeted Work Batch Planner with Spec Coverage Verification
+# /pan:focus-auto --step plan — Capacity-Budgeted Work Batch Planner with Spec Coverage Verification
 
 Create a capacity-budgeted work batch from focus-scan results **with mandatory verification that planned work covers all relevant spec and ADR requirements.** $ARGUMENTS
 
@@ -20,7 +6,7 @@ Create a capacity-budgeted work batch from focus-scan results **with mandatory v
 
 ---
 
-## CRITICAL: Project Scope Boundary
+## Project Scope Boundary
 
 This command plans work batches for the **host project** — NOT for PAN Wizard's own infrastructure.
 
@@ -34,7 +20,7 @@ If a scan item points to a PAN infrastructure file, DROP it from the batch. PAN'
 
 ## MANDATORY: Run focus-scan first
 
-If no recent scan exists, run `/pan:focus-scan` automatically before proceeding.
+If no recent scan exists, run `/pan:focus-auto --step scan` automatically before proceeding.
 
 **Flags:**
 - `--budget N` — Override capacity budget in points (default: 50, min: 5, max: 100)
@@ -215,13 +201,13 @@ For each success criterion in the batch, specify HOW it will be verified after e
 | SC-2 | Keywords >= 500 | `SELECT COUNT(*) FROM stx_keyword` | >= 500 |
 | SC-5 | No regression | `dotnet test` | All pass, count >= N |
 
-This becomes the post-execution checklist for `/pan:focus-exec`.
+This becomes the post-execution checklist for `/pan:focus-auto --step exec`.
 
 ---
 
 ## Phase 5: Output
 
-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:
+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-auto --step 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>
@@ -267,7 +253,7 @@ Write the batch to `.planning/focus/batch-<YYYY-MM-DD>.json` yourself — `{date
 Execution Order: MICRO first, then STANDARD, then FULL
 ```
 
-Ready for `/pan:focus-exec`.
+Ready for `/pan:focus-auto --step exec`.
 
 ---
 

package/{commands/pan → pan-wizard-core/workflows}/focus-scan.md

@@ -1,17 +1,4 @@
----
-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
----
-
-# /pan:focus-scan — Deep-Dive Strategic Work Scan
+# /pan:focus-auto --step scan — Deep-Dive Strategic Work Scan
 
 Survey the project for prioritized work items with evidence-based scoring. $ARGUMENTS
 
@@ -48,7 +35,7 @@ Do not read entire files when Grep can find the relevant lines. Do not use Bash
 
 ## Execute All Phases Automatically
 
-When `/pan:focus-scan` is invoked, execute all phases without stopping. Do not ask questions between phases or skip phases. The output is a prioritized work list with Reality Score filtering.
+When `/pan:focus-auto --step scan` is invoked, execute all phases without stopping. Do not ask questions between phases or skip phases. The output is a prioritized work list with Reality Score filtering.
 
 **Flags:**
 - `--focus <area>` — Weight items toward a specific area (e.g., `--focus commands`, `--focus hooks`, `--focus tests`)
@@ -237,7 +224,7 @@ Gather items from:
 ## Phase 5: Scan Assembly
 
 ### 5.1 Output
-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.
+Write the scan to `.planning/focus/scan-<YYYY-MM-DD>.md`, where `/pan:focus-auto --step plan` builds from it and `/pan:focus-auto --step 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 → pan-wizard-core/workflows}/focus-sync.md

@@ -1,18 +1,4 @@
----
-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
-  - Grep
-  - Glob
-  - Edit
-  - Write
----
-
-# /pan:focus-sync — Documentation Synchronization
+# /pan:focus-docs --sync — Documentation Synchronization
 
 Synchronize project documentation across all files. $ARGUMENTS
 
@@ -20,7 +6,7 @@ Synchronize project documentation across all files. $ARGUMENTS
 
 ---
 
-## CRITICAL: Project Scope Boundary
+## Project Scope Boundary
 
 This command synchronizes the **host project's documentation** — NOT PAN Wizard's own infrastructure files.
 
@@ -35,11 +21,11 @@ This command synchronizes the **host project's documentation** — NOT PAN Wizar
 ## Usage
 
 ```
-/pan:focus-sync                  # Full sync check: report staleness
-/pan:focus-sync --readme         # Check README.md only
-/pan:focus-sync --docs           # Verify documentation matches implementations
-/pan:focus-sync --arch           # Verify architecture docs match actual structure
-/pan:focus-sync --all            # Full sync of everything + auto-fix
+/pan:focus-docs --sync                  # Full sync check: report staleness
+/pan:focus-docs --sync --readme         # Check README.md only
+/pan:focus-docs --sync --docs           # Verify documentation matches implementations
+/pan:focus-docs --sync --arch           # Verify architecture docs match actual structure
+/pan:focus-docs --sync --all            # Full sync of everything + auto-fix
 ```
 
 ---

package/pan-wizard-core/workflows/health.md

@@ -72,6 +72,12 @@ Status: HEALTHY | DEGRADED | BROKEN
 Errors: N | Warnings: N | Info: N
 ```
 
+**Ask per repair class before repairing.** With `--repair`, run `validate health` without it first and read `repairs_available` (for example `resetConfig`, `regenerateState`, `syncRequirements`, `syncRoadmap`). Ask about each class on its own, saying what it rewrites (state.md is backed up before regeneration; config.json is reset to defaults). Then repair only the classes the user accepted:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs validate health --repair --only <class>,<class>
+```
+A class the user declines is not touched.
+
 **If repairs were performed:**
 ```
 ## Repairs Performed