prizmkit 1.1.79 → 1.1.81

package/bundled/skills-windows/refactor-pipeline-launcher/SKILL.md

@@ -156,28 +156,13 @@ Detect user intent from their message, then follow the corresponding workflow:
 
    Wait for user confirmation before proceeding.
 
-5. **Ask execution mode** (first user decision — SEPARATE `AskUserQuestion` call):
+5. **Ask execution mode** (first user decision):
 
-   ⛔ **This MUST be its own standalone `AskUserQuestion` call.** Do NOT combine execution mode with step 6 config questions. The execution mode question is asked ALONE, user responds, THEN you proceed to step 6.
+   Present the three execution modes from the **Execution Mode** section above as a single standalone `AskUserQuestion` call (exactly 1 question, multiSelect: false). Wait for the user's response before continuing to step 6.
 
-   Use `AskUserQuestion` with exactly 1 question:
+   Each `AskUserQuestion` round is a genuine gate: callers tend to merge interactive rounds and pre-fill answers, which skips real user decisions and produces wrong configs. Therefore: ask execution mode (step 5) and configuration (step 6) as SEPARATE `AskUserQuestion` calls, in order, and do not assemble or show the final command (step 7) until the user has answered both. If you find yourself writing the final command before the user has answered, STOP — you are violating this rule.
 
-   **Question 1 — Execution mode** (multiSelect: false):
-   - Foreground (Recommended) — pipeline runs in the current session via `run-refactor.ps1 run`. Visible output and direct error feedback.
-   - Background daemon — pipeline runs fully detached via `launch-refactor-daemon.ps1`. Survives AI CLI session closure.
-   - Manual — display the final assembled commands only. Do not execute anything. User runs them on their own.
-
-   ⚠️ STOP HERE and wait for user response before continuing to step 6.
-
-6. **Ask configuration options** ⚠️ MANDATORY INTERACTIVE STEP — applies to ALL execution modes (Foreground, Background, AND Manual). This is a SEPARATE `AskUserQuestion` call from step 5. You MUST ask the user to configure options and WAIT for their response BEFORE proceeding to step 7.
-
-   ⛔ **HARD STOP**: You MUST call `AskUserQuestion` with the 3 questions below and WAIT for the user's response. You MUST NOT:
-   - Combine step 5 and step 6 into one `AskUserQuestion` call (this is the most common violation — execution mode MUST be asked separately in step 5)
-   - Skip this step and jump to step 7
-   - Merge step 6 and step 7 into one response
-   - Assume default values and show the command without asking
-   - Show the command as text and ask "ready?" without presenting the options
-   If you find yourself writing the final command before the user has answered these 3 questions, STOP — you are violating this rule.
+6. **Ask configuration options** — a SEPARATE `AskUserQuestion` call from step 5, applies to ALL execution modes (Foreground, Background, AND Manual).
 
    Use `AskUserQuestion` to present ALL 3 configuration choices (the full 3-question budget goes to config, NOT shared with execution mode):
 
@@ -196,51 +181,11 @@ Detect user intent from their message, then follow the corresponding workflow:
 
    Note: Refactor filter defaults to all refactor items (by priority order). If the user selects "Other" on any option, handle their custom input.
 
-   **If user chose "Yes" to Advanced config**, ask a second round of `AskUserQuestion`:
-
-   **Question 1 — Session timeout** (multiSelect: false):
-   - None (default) — No timeout
-   - 30 min — `SESSION_TIMEOUT=1800`
-   - 1 hour — `SESSION_TIMEOUT=3600`
-   - 2 hours — `SESSION_TIMEOUT=7200`
-
-   **Question 2 — Stop on failure** (multiSelect: false):
-   - Off (default) — Pipeline continues to next task after failure
-   - On — Pipeline halts immediately when a task exhausts all retries (`STOP_ON_FAILURE=1`)
-
-   **Question 3 — Critic review** (multiSelect: false):
-   - Off (default) — Skip adversarial review
-   - On — Enable adversarial critic review: an independent AI agent reviews the refactor plan for completeness and the implementation for regressions, missing edge cases, and behavior violations. Adds ~5-10 min per refactor task.
-
-   **Question 4 — Reasoning effort** (multiSelect: false):
-   - Default (none) — Use CLI default
-   - low — Minimize reasoning, fastest output (`PRIZMKIT_EFFORT=low`)
-   - medium — Moderate reasoning (`PRIZMKIT_EFFORT=medium`)
-   - high — Thorough reasoning for complex tasks (`PRIZMKIT_EFFORT=high`)
-   - xhigh — Extensive reasoning (`PRIZMKIT_EFFORT=xhigh`)
-   - max — Maximum reasoning, Claude Code only (`PRIZMKIT_EFFORT=max`)
-
-   Default Critic to Off unless refactor items have `priority: "critical"` (in which case default to On).
-
-   **Environment variable mapping** (for translating user responses → env vars):
-
-   | Config choice | Environment variable |
-   |-----------|---------------------|
-   | Verbose: On | `VERBOSE=1` |
-   | Verbose: Off | `VERBOSE=0` |
-   | Max retries: N | `MAX_RETRIES=N` |
-   | Critic: On | `ENABLE_CRITIC=true` |
-   | Timeout: value | `SESSION_TIMEOUT=<seconds>` |
-   | Stop on failure: On | `STOP_ON_FAILURE=1` |
-   | Effort: value | `PRIZMKIT_EFFORT=<value>` |
-
-   **Advanced environment variables** (not exposed in interactive menu, pass via `--env`):
+   **If user chose "Yes" to Advanced config**, run the advanced configuration round (a second `AskUserQuestion` round). It applies to a minority of sessions, so the full question set lives in `${SKILL_DIR}/references/configuration.md` → **Advanced Configuration Round**. Default Critic to Off unless refactor items have `priority: "critical"` (in which case default to On).
 
-   | Variable | Default | Purpose |
-   |----------|---------|---------|
-   | `MODEL` | (none) | AI model override (e.g. `claude-opus-4.6`) |
+   **Environment variable mapping** and **advanced environment variables** tables — read `${SKILL_DIR}/references/configuration.md` for the full translation tables (10 config→env mappings + 8 advanced variables).
 
-   ⚠️ STOP HERE and wait for user response before continuing to step 7.
+   STOP HERE and wait for user response before continuing to step 7.
 
 7. **Show final command**: After user confirms configuration in step 6, assemble the complete command from execution mode + user-confirmed configuration, and present it to the user.
 
@@ -389,21 +334,7 @@ Notes:
 
 ### Error Handling
 
-| Error | Action |
-|-------|--------|
-| `.prizmkit/plans/refactor-list.json` not found | Tell user to run `refactor-planner` skill first |
-| Circular dependencies in refactor list | Fix dependency graph in `.prizmkit/plans/refactor-list.json` before launching |
-| Test baseline failing | Fix failing tests before starting refactoring -- behavior preservation requires a green baseline |
-| JSON parsing failed | Use the bundled Python validation/status scripts instead of external JSON tools |
-| AI CLI not in PATH | Check Codex (`codex`), Claude (`claude`), or CodeBuddy (`cbc`) installation |
-| Refactor pipeline already running | Show status, ask if user wants to stop and restart |
-| PID file stale (process dead) | `launch-refactor-daemon.ps1` auto-cleans, retry start |
-| Launch failed (process died immediately) | Show last 20 lines of log: `Get-Content -Tail 20 .prizmkit/state/daemon/refactor-daemon.log` |
-| Refactor stuck/blocked | Use `reset-refactor.ps1 <R-XXX> --clean --run` for a fresh retry |
-| All refactors blocked/failed | Show status, suggest recovery: `.\.prizmkit\dev-pipeline\reset-refactor.ps1 <R-XXX> --clean --run .prizmkit/plans/refactor-list.json` |
-| `playwright-cli` not installed | Browser verification skipped for playwright refactors (non-blocking). Suggest: `npm install -g @playwright/cli@latest; playwright-cli install --skills` |
-| `opencli` not installed | Browser verification skipped for opencli refactors (non-blocking). Install opencli for Chrome session-based browser verification |
-| PowerShell execution policy blocks script | Run `Set-ExecutionPolicy -Scope Process Bypass` for the current terminal |
+Read the error-handling table in `${SKILL_DIR}/references/configuration.md` for the full list of errors and recovery actions.
 
 ### Integration Notes
 

package/bundled/skills-windows/refactor-pipeline-launcher/references/configuration.md

@@ -0,0 +1,82 @@
+# Configuration Reference — Refactor Pipeline Launcher (Windows)
+
+Environment variable mappings for the refactor launcher.
+
+## Environment Variable Mapping
+
+Translating user responses to env vars:
+
+| Config choice | Environment variable |
+|-----------|---------------------|
+| Verbose: On | `VERBOSE=1` |
+| Verbose: Off | `VERBOSE=0` |
+| Max retries: N | `MAX_RETRIES=N` |
+| Strict behavior: On | `STRICT_BEHAVIOR_CHECK=1` |
+| Strict behavior: Off | `STRICT_BEHAVIOR_CHECK=0` |
+| Critic: On | `ENABLE_CRITIC=true` |
+| Timeout: value | `SESSION_TIMEOUT=<seconds>` |
+| Stop on failure: On | `STOP_ON_FAILURE=1` |
+| Deploy: Yes | `ENABLE_DEPLOY=1` |
+| Effort: value | `PRIZMKIT_EFFORT=<value>` |
+
+## Advanced Environment Variables
+
+Not exposed in interactive menu, pass via `--env`:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MODEL` | (none) | AI model override (e.g. `claude-opus-4.6`) |
+| `AUTO_PUSH` | `0` | Auto-push to remote after successful refactor (`1` to enable) |
+| `DEV_BRANCH` | auto-generated | Custom dev branch name (default: `refactor/pipeline-{run_id}`) |
+| `HEARTBEAT_INTERVAL` | `30` | Heartbeat log interval in seconds |
+| `HEARTBEAT_STALE_THRESHOLD` | `600` | Max seconds without heartbeat before marking stale |
+| `LOG_CLEANUP_ENABLED` | `1` | Run periodic log cleanup (`0` to disable) |
+| `LOG_RETENTION_DAYS` | `14` | Delete logs older than N days |
+| `LOG_MAX_TOTAL_MB` | `1024` | Keep total logs under N MB via oldest-first cleanup |
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| `.prizmkit/plans/refactor-list.json` not found | Tell user to run `refactor-planner` skill first |
+| Circular dependencies in refactor list | Fix dependency graph in `.prizmkit/plans/refactor-list.json` before launching |
+| Test baseline failing | Fix failing tests before starting refactoring -- behavior preservation requires a green baseline |
+| JSON parsing failed | Use the bundled Python validation/status scripts instead of external JSON tools |
+| AI CLI not in PATH | Check Codex (`codex`), Claude (`claude`), or CodeBuddy (`cbc`) installation |
+| Refactor pipeline already running | Show status, ask if user wants to stop and restart |
+| PID file stale (process dead) | `launch-refactor-daemon.ps1` auto-cleans, retry start |
+| Launch failed (process died immediately) | Show last 20 lines of log: `Get-Content -Tail 20 .prizmkit/state/daemon/refactor-daemon.log` |
+| Refactor stuck/blocked | Use `reset-refactor.ps1 <R-XXX> --clean --run` for a fresh retry |
+| All refactors blocked/failed | Show status, suggest recovery: `.\.prizmkit\dev-pipeline\reset-refactor.ps1 <R-XXX> --clean --run .prizmkit/plans/refactor-list.json` |
+| `playwright-cli` not installed | Browser verification skipped for playwright refactors (non-blocking). Suggest: `npm install -g @playwright/cli@latest; playwright-cli install --skills` |
+| `opencli` not installed | Browser verification skipped for opencli refactors (non-blocking). Install opencli for Chrome session-based browser verification |
+| Deploy session failed | Pipeline completed but deploy session exited non-zero. Check `.prizmkit/state/refactor/deploy/<session_id>/logs/session.log`. Retry manually: `/prizmkit-deploy`. |
+| PowerShell execution policy blocks script | Run `Set-ExecutionPolicy -Scope Process Bypass` for the current terminal |
+
+## Advanced Configuration Round
+
+Only run this when the user answered "Yes" to the **Advanced config?** question in step 6. It applies to a minority of sessions.
+
+Ask a second round of `AskUserQuestion` with these 4 questions:
+
+**Question 1 — Session timeout** (multiSelect: false):
+- None (default) — No timeout
+- 30 min — `SESSION_TIMEOUT=1800`
+- 1 hour — `SESSION_TIMEOUT=3600`
+- 2 hours — `SESSION_TIMEOUT=7200`
+
+**Question 2 — Stop on failure** (multiSelect: false):
+- Off (default) — Pipeline continues to next task after failure
+- On — Pipeline halts immediately when a task exhausts all retries (`STOP_ON_FAILURE=1`)
+
+**Question 3 — Critic review** (multiSelect: false):
+- Off (default) — Skip adversarial review
+- On — Enable adversarial critic review: an independent AI agent reviews the refactor plan for completeness and the implementation for regressions, missing edge cases, and behavior violations. Adds ~5-10 min per refactor task.
+
+**Question 4 — Reasoning effort** (multiSelect: false):
+- Default (none) — Use CLI default
+- low — Minimize reasoning, fastest output (`PRIZMKIT_EFFORT=low`)
+- medium — Moderate reasoning (`PRIZMKIT_EFFORT=medium`)
+- high — Thorough reasoning for complex tasks (`PRIZMKIT_EFFORT=high`)
+- xhigh — Extensive reasoning (`PRIZMKIT_EFFORT=xhigh`)
+- max — Maximum reasoning, Claude Code only (`PRIZMKIT_EFFORT=max`)

package/bundled/skills-windows/refactor-planner/SKILL.md

@@ -78,7 +78,7 @@ Do NOT use this skill when the user wants to:
    - Read `${SKILL_DIR}/references/behavior-preservation.md` for preservation strategy selection
 
 4. **Load on-demand references when triggered**:
-   - Validation errors or interrupted session -> read error recovery patterns (similar to feature-planner)
+   - Validation errors or interrupted session -> see the "Error Recovery & Resume" section below
 
 5. **Define the PowerShell Python helper before running validation scripts**:
    ```powershell
@@ -246,13 +246,7 @@ Ask: "Based on this analysis, here's how I'd recommend decomposing the refactori
 
 **Goal**: Split refactoring goals into executable, well-ordered items.
 
-Read `${SKILL_DIR}/assets/planning-guide.md` for decomposition patterns and dependency ordering rules.
-
-For each refactoring goal:
-1. Identify atomic refactoring operations
-2. Determine inter-item dependencies (safe renames first, structural changes later)
-3. Assess complexity per item (file count, cross-module scope, test coverage)
-4. Assign behavior preservation strategy per item (read `${SKILL_DIR}/references/behavior-preservation.md`)
+Read `${SKILL_DIR}/references/planning-phases.md` for the full Phase 4-6 procedures — item decomposition patterns, per-item confirmation loop, and completeness review checklist.
 
 **CHECKPOINT CP-RP-3**: All items decomposed with dependencies and preservation strategies.
 
@@ -260,29 +254,7 @@ For each refactoring goal:
 
 **Goal**: Present each item to the user for confirmation, modification, or rejection.
 
-For each item, display:
-
-```
-Refactor Item R-001:
-  Title: [title]
-  Type: [extract/rename/restructure/simplify/decouple/migrate]
-  Scope: [files list]
-  Priority: [critical/high/medium/low]
-  Complexity: [low/medium/high]
-  Behavior Preservation: [test-gate/snapshot/manual]
-  Acceptance Criteria:
-    - [criterion 1]
-    - [criterion 2]
-  Dependencies: [none / R-002, R-003]
-  
-  Confirm? (Y/modify/skip)
-```
-
-- **Y**: Accept item as-is
-- **modify**: User provides changes, update item, re-display for confirmation
-- **skip**: Remove item from the list
-
-Continue until all items are confirmed or skipped.
+See `${SKILL_DIR}/references/planning-phases.md` for the display template and confirm/modify/skip loop procedure.
 
 **CHECKPOINT CP-RP-4**: All items confirmed by user.
 
@@ -290,28 +262,7 @@ Continue until all items are confirmed or skipped.
 
 **Goal**: Check the full item set for consistency, gaps, and headless execution readiness.
 
-1. **Dependency ordering check**: Verify items form a valid DAG (no cycles). Items should be ordered: safe renames -> extract/inline -> structural changes -> migrations
-2. **Behavior preservation check**: Every item must have a declared preservation strategy. Flag any item with `manual` strategy and no test coverage.
-3. **Gap detection**: Are there intermediate steps needed between items? Does item A's output match item B's input assumption?
-4. **Cross-module impact**: Do any items affect modules outside the declared scope?
-5. **Headless Execution Readiness**: The refactor pipeline runs each item through an autonomous AI session with NO human interaction. For each item, verify:
-   - **Scope clarity**: Are all affected files explicitly listed? The AI must know exactly where to look.
-   - **Refactoring instructions**: Is the description specific enough to execute without ambiguity?
-     - ❌ "Clean up the utils module" — what exactly should change?
-     - ✅ "Extract validation functions (validateEmail, validatePhone, validateUrl) from src/utils/helpers.ts into src/utils/validation.ts. Update all 12 import sites. Preserve existing function signatures."
-   - **Behavior preservation**: Is it clear what tests to run and what behavior must be preserved?
-   - **Dependency context**: If item depends on earlier refactors, does the description reference what changed?
-
-Present review summary:
-```
-Item       | Deps Valid | Preservation | Gaps           | Status
-R-001      | OK         | test-gate    | -              | Ready
-R-002      | OK         | test-gate    | -              | Ready
-R-003      | OK         | manual       | No test coverage| Needs attention
-R-004      | OK         | snapshot     | -              | Ready
-```
-
-If issues found, discuss with user and resolve before proceeding.
+See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review checklist and review summary table format.
 
 **CHECKPOINT CP-RP-5**: Completeness review passed, all issues resolved.
 
@@ -343,8 +294,6 @@ If issues found, discuss with user and resolve before proceeding.
 | **CP-RP-5** | Completeness OK | DAG valid, preservation strategies declared, no gaps | 6 |
 | **CP-RP-6** | Output Valid | `.prizmkit/plans/refactor-list.json` passes validation script | 7 |
 
-**Resume Detection**: If existing artifacts found (partial `.prizmkit/plans/refactor-list.json`, draft `refactor-list.draft.json` in `.prizmkit/plans/`), offer to resume from the appropriate checkpoint.
-
 ## Output Rules
 
 `.prizmkit/plans/refactor-list.json` must satisfy:
@@ -376,118 +325,27 @@ Set default critic fields for each refactor item. The user can override per-item
 
 ## Fast Path
 
-For simple refactoring with minimal scope:
-
-### Eligibility Criteria (ALL must apply)
-- 1-2 refactor items only
-- Complexity: `low` or `medium` for all items
-- No cross-module impact (all items within same module)
-- Well-known refactoring pattern (rename, extract method/class, inline)
-- Existing test coverage for target area
-
-### Fast Path Workflow
-1. Confirm refactoring scope with user
-2. **User confirmation (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
-
-   ```
-   AskUserQuestion:
-     question: "This qualifies for fast-path (simple refactoring). How would you like to proceed?"
-     header: "Approach"
-     options:
-       - label: "Fast-path"
-         description: "Skip detailed analysis, draft refactor items directly and add to refactor-list.json"
-       - label: "Full workflow"
-         description: "Use the complete planning workflow with detailed code analysis"
-       - label: "Implement directly"
-         description: "Skip the task list entirely and implement the refactoring right now using /prizmkit-plan + /prizmkit-implement"
-   ```
-
-   - **Fast-path** → Continue with fast-path workflow below
-   - **Full workflow** → Exit fast path, use full workflow from Phase 2
-   - **Implement directly** → Invoke `/prizmkit-plan` directly to create spec + plan, then `/prizmkit-implement` to execute. Do NOT add to `.prizmkit/plans/refactor-list.json`
-   
-   **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
-3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
-4. Write draft to `.prizmkit/plans/refactor-list.draft.json`, then call the generate script:
-   ```powershell
-   Invoke-PrizmPython ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
-   ```
-5. If valid -> summarize and recommend next step
-6. If invalid -> apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
-
-### When NOT to Use Fast Path
-- More than 2 refactor items
-- Any item with `high` complexity
-- Cross-module impact
-- Architecture migration patterns (Format C goals)
-- No existing test coverage for target area
-
-### Example Fast Path Session
-```
-User: "Rename the auth middleware function from checkAuth to requireAuth everywhere."
-AI: [Detects simple rename, single module]
-AI: [Qualifies for fast path: 1 item, low complexity, no cross-module impact]
-AI: [Uses AskUserQuestion with options: "Fast-path", "Full workflow", "Implement directly"]
-User: [Selects "Fast-path"]
-AI: "Drafting R-001..."
-AI: [Validates immediately]
-AI: "Ready to proceed to dev-pipeline."
-```
+For simple refactoring with minimal scope (1-2 items, low/medium complexity, no cross-module impact, existing test coverage). Read `${SKILL_DIR}/references/fast-path.md` for eligibility criteria, full workflow (including AskUserQuestion format), conditions NOT to use, and an example session.
 
 ## Browser Verification
 
-**Browser verification is a feature-pipeline capability only.** Refactors use `behavior_preservation` strategy instead to ensure no external behavior changes:
-
-- `strategy: test-gate` — Rely on existing test suite. Pipeline runs tests before and after refactoring.
-- `strategy: snapshot` — Compare behavior before/after refactoring using executable snapshots (outputs, API responses, side effects)
-- `strategy: manual` — Require human verification that behavior is preserved
-
-For refactors that modify UI code (e.g., component restructuring), the test-gate or snapshot strategy ensures visual appearance is preserved. You can optionally note browser verification needs in your description or acceptance criteria:
-
-Example:
-```
-Refactor Title: Extract UserProfile component from AccountSettings
-Type: extract
-Strategy: snapshot
-Acceptance Criteria:
-  1. UserProfile component renders identically to inline version (compare snapshots)
-  2. All props are correctly forwarded (unit tests pass)
-  3. No visual regression (screenshot comparison)
-  4. Component is reusable in other views
-```
-
-The refactor pipeline AI will use the snapshot strategy to verify external behavior is preserved during refactoring.
+Browser verification is a feature-pipeline capability only. Refactors use `behavior_preservation` strategy instead. Read `${SKILL_DIR}/references/planning-phases.md` for strategy details and UI refactoring examples.
 
 ---
 
 ## Refactoring-Specific Features
 
 ### Behavior Preservation Check
-Every item MUST declare a behavior preservation strategy. Read `${SKILL_DIR}/references/behavior-preservation.md` for strategy details.
-
-| Strategy | When to Use |
-|----------|-------------|
-| `test-gate` | Target area has good test coverage. Run full test suite after each change. |
-| `snapshot` | Compare output/state before and after. Useful when tests are insufficient but behavior is observable. |
-| `manual` | Human verification required. Last resort when neither tests nor snapshots are feasible. |
 
-Flag items using `manual` strategy prominently — they carry the highest risk of behavior regression.
+Every item MUST declare a behavior preservation strategy. Read `${SKILL_DIR}/references/behavior-preservation.md` for strategy details. See `${SKILL_DIR}/references/planning-phases.md` for the strategy selection table and manual-strategy flagging rules.
 
 ### Dependency Ordering
-Auto-detect inter-item dependencies and enforce safe ordering:
-1. **Safe renames** first (lowest risk, no structural change)
-2. **Extract/inline** operations (moderate risk, changes module boundaries)
-3. **Structural changes** (higher risk, reorganizes architecture)
-4. **Migrations** last (highest risk, changes patterns/paradigms)
+
+Auto-detect inter-item dependencies and enforce safe ordering. Read `${SKILL_DIR}/references/planning-phases.md` for the full dependency ordering rules (safe renames -> extract/inline -> structural -> migrations).
 
 ### Complexity Assessment
-Assess each item's complexity based on:
-- **File count**: 1-2 files = low, 3-5 files = medium, 6+ files = high
-- **Cross-module scope**: same module = low, 2 modules = medium, 3+ modules = high
-- **Test coverage**: high coverage = reduces complexity, low coverage = increases complexity
-- **Pattern familiarity**: well-known pattern = low, novel restructuring = high
 
-Take the highest of these individual assessments as the item's complexity.
+Assess each item's complexity based on file count, cross-module scope, test coverage, and pattern familiarity. Read `${SKILL_DIR}/references/planning-phases.md` for the full complexity assessment criteria and scoring rules.
 
 ## Next-Step Execution Policy (after planning)
 
@@ -503,6 +361,8 @@ Key behaviors:
 
 ### Resume Detection
 
+If existing artifacts are found, offer to resume from the appropriate checkpoint/phase:
+
 | Artifact Found | Resume From |
 |---------------|------------|
 | Nothing | Phase 1: Project Context |
@@ -510,18 +370,16 @@ Key behaviors:
 | Partial `.prizmkit/plans/refactor-list.json` | Phase 6: Completeness Review |
 | Valid `.prizmkit/plans/refactor-list.json` | Mode D: Summary |
 
-## Session Exit Gate
+### Session Exit Gate
 
 Prevent accidental session exit without deliverable completion.
 
-### Trigger Conditions
-Activate exit gate when ALL are true:
+**Trigger conditions** — activate the exit gate when ALL are true:
 - User invoked `/refactor-planner` (not just mentioned refactoring)
 - Current phase < Phase 7 (validation not yet passed)
 - No valid `.prizmkit/plans/refactor-list.json` has been written in this session
 
-### Gate Behavior
-When the session appears to be ending:
+**Gate behavior** — when the session appears to be ending:
 1. **Remind**: "You set out to produce `.prizmkit/plans/refactor-list.json` but we haven't completed it yet."
 2. **Offer 3 options**:
    - **(a) Continue to completion** — resume from current phase

package/bundled/skills-windows/refactor-planner/references/fast-path.md

@@ -0,0 +1,59 @@
+# Fast Path — Refactor Planner
+
+For simple refactoring with minimal scope.
+
+## Eligibility Criteria (ALL must apply)
+- 1-2 refactor items only
+- Complexity: `low` or `medium` for all items
+- No cross-module impact (all items within same module)
+- Well-known refactoring pattern (rename, extract method/class, inline)
+- Existing test coverage for target area
+
+## Fast Path Workflow
+1. Confirm refactoring scope with user
+2. **User confirmation (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
+
+   ```
+   AskUserQuestion:
+     question: "This qualifies for fast-path (simple refactoring). How would you like to proceed?"
+     header: "Approach"
+     options:
+       - label: "Fast-path"
+         description: "Skip detailed analysis, draft refactor items directly and add to refactor-list.json"
+       - label: "Full workflow"
+         description: "Use the complete planning workflow with detailed code analysis"
+       - label: "Implement directly"
+         description: "Skip the task list entirely and implement the refactoring right now using /prizmkit-plan + /prizmkit-implement"
+   ```
+
+   - **Fast-path** → Continue with fast-path workflow below
+   - **Full workflow** → Exit fast path, use full workflow from Phase 2
+   - **Implement directly** → Invoke `/prizmkit-plan` directly to create spec + plan, then `/prizmkit-implement` to execute. Do NOT add to `.prizmkit/plans/refactor-list.json`
+
+   **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
+3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
+4. Write draft to `.prizmkit/plans/refactor-list.draft.json`, then call the generate script:
+   ```powershell
+   Invoke-PrizmPython ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
+   ```
+5. If valid -> summarize and recommend next step
+6. If invalid -> apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
+
+## When NOT to Use Fast Path
+- More than 2 refactor items
+- Any item with `high` complexity
+- Cross-module impact
+- Architecture migration patterns (Format C goals)
+- No existing test coverage for target area
+
+## Example Fast Path Session
+```
+User: "Rename the auth middleware function from checkAuth to requireAuth everywhere."
+AI: [Detects simple rename, single module]
+AI: [Qualifies for fast path: 1 item, low complexity, no cross-module impact]
+AI: [Uses AskUserQuestion with options: "Fast-path", "Full workflow", "Implement directly"]
+User: [Selects "Fast-path"]
+AI: "Drafting R-001..."
+AI: [Validates immediately]
+AI: "Ready to proceed to dev-pipeline."
+```

package/bundled/skills-windows/refactor-planner/references/planning-phases.md

@@ -0,0 +1,135 @@
+# Planning Phases — Refactor Planner
+
+Detailed procedures for Phases 4-6 of the refactor-planner interactive workflow, plus refactoring-specific assessment rules and browser verification guidance.
+
+---
+
+## Phase 4: Item Decomposition Procedure
+
+Read `${SKILL_DIR}/assets/planning-guide.md` for decomposition patterns and dependency ordering rules.
+
+For each refactoring goal:
+1. Identify atomic refactoring operations
+2. Determine inter-item dependencies (safe renames first, structural changes later)
+3. Assess complexity per item (file count, cross-module scope, test coverage)
+4. Assign behavior preservation strategy per item (read `${SKILL_DIR}/references/behavior-preservation.md`)
+
+---
+
+## Phase 5: Per-Item Confirmation Loop
+
+For each item, display:
+
+```
+Refactor Item R-001:
+  Title: [title]
+  Type: [extract/rename/restructure/simplify/decouple/migrate]
+  Scope: [files list]
+  Priority: [critical/high/medium/low]
+  Complexity: [low/medium/high]
+  Behavior Preservation: [test-gate/snapshot/manual]
+  Acceptance Criteria:
+    - [criterion 1]
+    - [criterion 2]
+  Dependencies: [none / R-002, R-003]
+  
+  Confirm? (Y/modify/skip)
+```
+
+- **Y**: Accept item as-is
+- **modify**: User provides changes, update item, re-display for confirmation
+- **skip**: Remove item from the list
+
+Continue until all items are confirmed or skipped.
+
+---
+
+## Phase 6: Completeness Review Checklist
+
+1. **Dependency ordering check**: Verify items form a valid DAG (no cycles). Items should be ordered: safe renames -> extract/inline -> structural changes -> migrations
+2. **Behavior preservation check**: Every item must have a declared preservation strategy. Flag any item with `manual` strategy and no test coverage.
+3. **Gap detection**: Are there intermediate steps needed between items? Does item A's output match item B's input assumption?
+4. **Cross-module impact**: Do any items affect modules outside the declared scope?
+5. **Headless Execution Readiness**: The refactor pipeline runs each item through an autonomous AI session with NO human interaction. For each item, verify:
+   - **Scope clarity**: Are all affected files explicitly listed? The AI must know exactly where to look.
+   - **Refactoring instructions**: Is the description specific enough to execute without ambiguity?
+     - ❌ "Clean up the utils module" — what exactly should change?
+     - ✅ "Extract validation functions (validateEmail, validatePhone, validateUrl) from src/utils/helpers.ts into src/utils/validation.ts. Update all 12 import sites. Preserve existing function signatures."
+   - **Behavior preservation**: Is it clear what tests to run and what behavior must be preserved?
+   - **Dependency context**: If item depends on earlier refactors, does the description reference what changed?
+
+### Review Summary Table Format
+
+Present review summary:
+
+```
+Item       | Deps Valid | Preservation | Gaps           | Status
+R-001      | OK         | test-gate    | -              | Ready
+R-002      | OK         | test-gate    | -              | Ready
+R-003      | OK         | manual       | No test coverage| Needs attention
+R-004      | OK         | snapshot     | -              | Ready
+```
+
+If issues found, discuss with user and resolve before proceeding.
+
+---
+
+## Behavior Preservation Check
+
+Every item MUST declare a behavior preservation strategy. Read `${SKILL_DIR}/references/behavior-preservation.md` for strategy details.
+
+| Strategy | When to Use |
+|----------|-------------|
+| `test-gate` | Target area has good test coverage. Run full test suite after each change. |
+| `snapshot` | Compare output/state before and after. Used when tests are insufficient but behavior is observable. |
+| `manual` | Human verification required. Last resort when neither tests nor snapshots are feasible. |
+
+Flag items using `manual` strategy prominently — they carry the highest risk of behavior regression.
+
+---
+
+## Dependency Ordering
+
+Auto-detect inter-item dependencies and enforce safe ordering:
+1. **Safe renames** first (lowest risk, no structural change)
+2. **Extract/inline** operations (moderate risk, changes module boundaries)
+3. **Structural changes** (higher risk, reorganizes architecture)
+4. **Migrations** last (highest risk, changes patterns/paradigms)
+
+---
+
+## Complexity Assessment
+
+Assess each item's complexity based on:
+- **File count**: 1-2 files = low, 3-5 files = medium, 6+ files = high
+- **Cross-module scope**: same module = low, 2 modules = medium, 3+ modules = high
+- **Test coverage**: high coverage = reduces complexity, low coverage = increases complexity
+- **Pattern familiarity**: well-known pattern = low, novel restructuring = high
+
+Take the highest of these individual assessments as the item's complexity.
+
+---
+
+## Browser Verification
+
+**Browser verification is a feature-pipeline capability only.** Refactors use `behavior_preservation` strategy instead to ensure no external behavior changes:
+
+- `strategy: test-gate` — Rely on existing test suite. Pipeline runs tests before and after refactoring.
+- `strategy: snapshot` — Compare behavior before/after refactoring using executable snapshots (outputs, API responses, side effects)
+- `strategy: manual` — Require human verification that behavior is preserved
+
+For refactors that modify UI code (e.g., component restructuring), the test-gate or snapshot strategy ensures visual appearance is preserved. You can optionally note browser verification needs in your description or acceptance criteria:
+
+Example:
+```
+Refactor Title: Extract UserProfile component from AccountSettings
+Type: extract
+Strategy: snapshot
+Acceptance Criteria:
+  1. UserProfile component renders identically to inline version (compare snapshots)
+  2. All props are correctly forwarded (unit tests pass)
+  3. No visual regression (screenshot comparison)
+  4. Component is reusable in other views
+```
+
+The refactor pipeline AI will use the snapshot strategy to verify external behavior is preserved during refactoring.