prizmkit 1.1.99 → 1.1.101

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

@@ -1,398 +0,0 @@
----
-name: "refactor-planner"
-description: "Interactive refactoring planner. Understands refactoring intent through dialogue, analyzes current code structure, produces validated .prizmkit/plans/refactor-list.json for dev-pipeline execution. Use whenever users discuss refactoring planning, code restructuring scope, or preparing .prizmkit/plans/refactor-list.json."
----
-
-# refactor planner
-
-Plan executable refactoring items for dev-pipeline:
-- **Scope Assessment**: analyze current code structure and identify refactoring targets
-- **Item Decomposition**: break refactoring goals into well-ordered, behavior-preserving items
-
-Always produce a validated `.prizmkit/plans/refactor-list.json` that conforms to `dev-pipeline-refactor-list-v1`.
-
-## Invocation Commitment (Hard Rule)
-
-**When the user invokes `/refactor-planner`, you MUST execute the refactor-planner workflow.** You must NEVER:
-- Decide on the user's behalf that the task "doesn't need refactor-planner"
-- Skip refactor-planner to jump directly to refactor-workflow or any other skill
-- Bypass the interactive phases because you judge the task to be "simple" or "obvious"
-
-If you believe the task is better suited for a different workflow (e.g., single-file refactor via `/refactor-workflow`), you MUST:
-1. **Explain why** you think a different path is more appropriate
-2. **Ask the user explicitly** whether they want to switch or continue with refactor-planner
-3. **Only switch if the user confirms** — otherwise proceed with refactor-planner as invoked
-
-The user chose this skill intentionally. Respect that choice.
-
-## Scope Boundary (Hard Rule)
-
-**This skill is PLANNING ONLY.** You must NEVER:
-- Create, modify, or delete source code files (*.js, *.ts, *.py, *.go, *.html, *.css, etc.)
-- Execute refactoring operations (rename, move, extract, etc.)
-- Run build/install/test commands
-- Execute any implementation action beyond writing `.prizmkit/plans/refactor-list.json`
-
-**Your ONLY writable outputs are:**
-1. `.prizmkit/plans/refactor-list.json` (`.prizmkit/plans/`)
-2. Draft backups in `.prizmkit/plans/` (e.g., `refactor-list.draft.json`)
-
-**After planning is complete**, you MUST:
-1. Present the summary and recommended next step
-2. **Ask the user explicitly** whether they want to proceed to execution
-3. If the user agrees → recommend invoking `refactor-pipeline-launcher` (do NOT execute it yourself)
-4. If the user wants to adjust → continue refining `.prizmkit/plans/refactor-list.json`
-5. **NEVER auto-execute** the pipeline, launcher, or any implementation step
-
-## User-Provided Content Priority (Hard Rule)
-
-When the user provides detailed specifications, rules, or implementation requirements:
-
-1. **Verbatim preservation**: The user's exact wording MUST be preserved in `description` and `acceptance_criteria` fields. Do NOT paraphrase, summarize, abstract, or simplify.
-2. **No autonomous simplification**: A 200-word user specification must NOT become a 30-word description. Match the detail level of the user's input.
-3. **Clarify, don't assume**: If any user-provided rule is ambiguous or potentially conflicts with another, ASK the user to clarify. No limit on clarification rounds. Do NOT proceed with unresolved ambiguities.
-4. **Populate `user_context`**: ALL user-provided materials (supplementary content, rules, file path references) MUST be written into the `user_context` array of each refactor item in the generated `.prizmkit/plans/refactor-list.json`. Format:
-   - Supplementary content or rules → store as-is (verbatim text)
-   - File references → store as path string, e.g. `src/auth/login.ts:42-78` or `src/utils/validate.ts — focus on validateEmail function`
-
-## When to Use
-- "Plan refactoring", "Scope a restructuring"
-- "Prepare .prizmkit/plans/refactor-list.json", "Prepare dev-pipeline input for refactoring"
-- "Assess code for refactoring", "Identify refactoring targets"
-- "Plan a code migration", "Decompose a large refactor"
-
-Do NOT use this skill when the user wants to:
-- Execute a single refactor directly (use `refactor-workflow`)
-- Plan new features (use `feature-planner`)
-- Fix bugs (use `bug-planner`)
-
-## Resource Loading Rules (Mandatory)
-
-1. **Read decomposition guide**:
-   - Read `${SKILL_DIR}/assets/planning-guide.md` for decomposition patterns and description guidelines
-
-2. **Read scope assessment reference**:
-   - Read `${SKILL_DIR}/references/refactor-scoping-guide.md` for scope classification and risk assessment
-
-3. **Read behavior preservation reference**:
-   - Read `${SKILL_DIR}/references/behavior-preservation.md` for preservation strategy selection
-
-4. **Load on-demand references when triggered**:
-   - Validation errors or interrupted session -> see the "Error Recovery & Resume" section below
-
-5. **Define the PowerShell Python helper before running validation scripts**:
-   ```powershell
-   function Invoke-PrizmPython {
-     param([Parameter(ValueFromRemainingArguments = $true)][string[]]$Arguments)
-     $python = Get-Command python -ErrorAction SilentlyContinue
-     if ($python) {
-       & $python.Source -c 'import sys; raise SystemExit(0 if sys.version_info[0] == 3 else 1)' *> $null
-       if ($LASTEXITCODE -eq 0) {
-         & $python.Source @Arguments
-         return
-       }
-     }
-     $py = Get-Command py -ErrorAction SilentlyContinue
-     if ($py) {
-       & $py.Source -3 -c 'import sys; raise SystemExit(0 if sys.version_info[0] == 3 else 1)' *> $null
-       if ($LASTEXITCODE -eq 0) {
-         & $py.Source -3 @Arguments
-         return
-       }
-     }
-     throw "Python 3 is required. Install Python and ensure python or py is in PATH."
-   }
-   ```
-
-6. **Always validate output via script**:
-   - Run:
-     ```powershell
-     Invoke-PrizmPython ${SKILL_DIR}/scripts/validate-and-generate-refactor.py validate --input <output-path>
-     ```
-
-7. **Use script output as source of truth**:
-   - If validation fails, **MUST** fix and re-run until pass
-
-## Prerequisites
-
-Before questions, check optional context files (never block if absent):
-- `.prizmkit/prizm-docs/root.prizm` (architecture/project context)
-- `.prizmkit/config.json` (existing stack preferences and detected tech stack)
-- Existing test suite (critical for behavior preservation assessment)
-- Existing `.prizmkit/plans/refactor-list.json` (if appending additional items)
-- If `.prizmkit/prizm-docs/root.prizm` is absent and the project has existing source code, scan the directory structure:
-  ```powershell
-  Get-ChildItem -Path . -Directory -Recurse -Depth 2 -ErrorAction SilentlyContinue |
-    Where-Object { $_.FullName -notmatch '\\(node_modules|\.git|dist|build|__pycache__|vendor)(\\|$)' } |
-    Select-Object -ExpandProperty FullName
-  ```
-
-**Test suite detection:**
-- Scan for test runner config files (`jest.config.*`, `vitest.config.*`, `pytest.ini`, `.mocharc.*`, `karma.conf.*`)
-- If no test suite detected, WARN: "No test suite found. Behavior preservation will rely on manual verification. Consider writing tests before refactoring."
-- Record test suite status in planning context for downstream use
-
-## Operation Modes
-
-### Mode A: Interactive (default)
-Full Q&A -> code analysis -> item generation. Useful when starting from scratch or exploring refactoring scope.
-
-### Mode B: From Analysis
-When an existing analysis report (e.g., `refactor-analysis.md`) is available, skip the analysis phase and proceed directly to item decomposition.
-
-### Mode C: Validate
-Validate an existing `.prizmkit/plans/refactor-list.json` without regenerating it:
-```powershell
-Invoke-PrizmPython ${SKILL_DIR}/scripts/validate-and-generate-refactor.py validate --input .prizmkit/plans/refactor-list.json
-```
-
-### Mode D: Summary
-Display a human-readable summary of an existing `.prizmkit/plans/refactor-list.json`:
-- Item count, dependency graph, complexity distribution, behavior preservation strategies
-
-## Interactive Mode — Core Workflow
-
-Execute the planning workflow in conversation mode with mandatory checkpoints:
-
-### Phase 1: Project Context
-
-**Goal**: Understand the current codebase structure and tech stack.
-
-1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1 docs
-2. Read `.prizmkit/config.json` for tech stack info
-3. Identify existing test suite and coverage
-4. Summarize project context to the user: "Here's what I found about your project..."
-5. **Collect reference materials** — **Upfront Material Detection (Hard Rule)**: If the user has already provided materials (file paths, URLs, rules, specifications, code snippets) in the same message that invoked this skill: (a) Acknowledge what was received: "I received the following materials: [list]"; (b) Read/fetch all provided materials immediately; (c) You MUST still ask: "Are there any additional materials you'd like to provide?"; (d) NEVER skip this collection step just because the user already provided some materials.
-
-   If the user has NOT provided any materials upfront, explicitly ask whether they have any supplementary materials for you to review before planning the refactoring:
-   > "Do you have any reference materials I should review before planning the refactoring? This can include:
-   > - **Code paths** — specific files or directories that are refactoring targets or dependencies
-   > - **Documents** — design docs, architecture proposals, refactoring RFCs, or technical debt analyses
-   > - **Knowledge docs** — `.prizmkit/prizm-docs/` files, README files, or internal wiki pages for the affected area
-   > - **Images** — architecture diagrams, dependency graphs, or whiteboard photos
-   > - **Web links** — reference implementations, design pattern articles, or migration guides
-   >
-   > If none, we'll proceed with what's available in the codebase."
-
-   If the user provides materials, read/fetch them all before proceeding to Phase 2. For web links, use web fetch to retrieve and analyze the content. For images, read and analyze them visually. This context is critical for refactoring — understanding the target architecture and constraints prevents risky structural changes.
-
-**CHECKPOINT CP-RP-0**: Project context loaded, tech stack and test suite status known.
-
-### Phase 2: Refactor Goal Collection
-
-**Goal**: Through interactive dialogue, understand what the user wants to refactor and why.
-
-Support 4 input formats (users may mix formats):
-
-**Format A — Natural language**:
-> "This module is too large and hard to maintain"
-> "The auth logic is scattered across too many files"
-
-**Format B — Code smell pointer**:
-> "src/api/handler.js is 800 lines"
-> "There are 5 files that all implement similar validation logic"
-
-**Format C — Architecture migration**:
-> "Convert callbacks to async/await"
-> "Migrate from class components to hooks"
-> "Move from monolith to modular architecture"
-
-**Format D — Dependency decoupling**:
-> "There's a circular dependency between auth and user modules"
-> "The database layer is tightly coupled to the HTTP layer"
-
-For each input, ask clarifying questions:
-- What is the specific target (files, modules, patterns)?
-- What is the desired end state?
-- Are there constraints (must preserve API, must not touch certain files)?
-- What is the motivation (maintainability, performance, testability)?
-
-Continue collecting goals until the user says they're done. There is no limit on rounds.
-
-**CHECKPOINT CP-RP-1**: All refactoring goals collected and understood.
-
-### Phase 3: Code Analysis
-
-**Goal**: Analyze the target code to inform item decomposition.
-
-Dispatch **parallel Agent reads** of target files:
-- **Agent A (Structure)**: File inventory, dependency graph, module boundaries, public API surface
-- **Agent B (Quality)**: Code smells, complexity hotspots, duplication, coupling metrics
-- **Agent C (Tests)**: Test coverage of target areas, existing test patterns, behavior contracts
-
-Present consolidated findings:
-```
-## Code Analysis Results
-
-### Structure
-- [file inventory, dependency graph]
-
-### Quality Issues
-- [code smells, complexity hotspots, duplication]
-
-### Test Coverage
-- [test status for target areas]
-- [behavior contracts that must be preserved]
-
-### Recommended Decomposition
-- [suggested refactoring order based on findings]
-```
-
-Ask: "Based on this analysis, here's how I'd recommend decomposing the refactoring. Does this align with your expectations?"
-
-**CHECKPOINT CP-RP-2**: Code analysis complete, user agrees with recommended approach.
-
-### Phase 4: Item Decomposition
-
-**Goal**: Split refactoring goals into executable, well-ordered items.
-
-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.
-
-### Phase 5: Per-Item Confirmation
-
-**Goal**: Present each item to the user for confirmation, modification, or rejection.
-
-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.
-
-### Phase 6: Completeness Review
-
-**Goal**: Check the full item set for consistency, gaps, and headless execution readiness.
-
-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.
-
-### Phase 7: Generate & Validate
-
-**Goal**: Produce `.prizmkit/plans/refactor-list.json` and validate it.
-
-**IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
-1. Write a draft JSON to `.prizmkit/plans/refactor-list.draft.json` with all collected refactor data.
-2. Call the generate script to validate and produce the final file:
-   ```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
-   ```
-   The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes.
-3. If validation fails -> fix the draft and retry (max 3 attempts)
-4. If validation passes -> present final summary
-
-**CHECKPOINT CP-RP-6**: `.prizmkit/plans/refactor-list.json` generated and validated.
-
-## Checkpoints (Mandatory Gates)
-
-| Checkpoint | Artifact/State | Criteria | Phase |
-|-----------|----------------|----------|-------|
-| **CP-RP-0** | Project Context | Tech stack, test suite status, .prizmkit/prizm-docs loaded | 1 |
-| **CP-RP-1** | Goals Collected | All refactoring goals understood, no open ambiguities | 2 |
-| **CP-RP-2** | Code Analyzed | Analysis complete, user agrees with approach | 3 |
-| **CP-RP-3** | Items Decomposed | All items have deps, complexity, preservation strategy | 4 |
-| **CP-RP-4** | Items Confirmed | User confirmed/modified/skipped each item | 5 |
-| **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 |
-
-## Output Rules
-
-`.prizmkit/plans/refactor-list.json` must satisfy:
-- `$schema` = `dev-pipeline-refactor-list-v1`
-- Non-empty `refactors` array
-- Sequential IDs: `R-001`, `R-002`, ...
-- Valid dependency DAG (no cycles)
-- Each item has a declared `behavior_preservation` object with `strategy` field: `"test-gate"`, `"snapshot"`, or `"manual"`. Optional fields: `existing_tests` (boolean), `new_tests_needed` (string array). See `.prizmkit/dev-pipeline/templates/refactor-list-schema.json` for the full schema.
-- `priority` must be a string: `"critical"`, `"high"`, `"medium"`, or `"low"`
-- New items default `status: "pending"`
-- English titles for stable slug generation
-- `type` field must be one of: `extract`, `rename`, `restructure`, `simplify`, `decouple`, `migrate`
-- Descriptions minimum 15 words (error). Recommended: 30/50/80 words for low/medium/high complexity (warning).
-- `model` field is optional — omitting it means the pipeline uses $MODEL env or CLI default
-- `scope` object with nested structure: `files` array (target file paths) and `modules` array (module names)
-
-## Adversarial Critic Defaults
-
-Set default critic fields for each refactor item. The user can override per-item.
-
-| Priority | Complexity | `critic` | `critic_count` |
-|----------|-----------|----------|----------------|
-| critical | high | `true` | `3` |
-| critical | medium/low | `true` | `1` |
-| high | high | `true` | `1` |
-| other combinations | any | `false` | (omitted) |
-
----
-
-## Fast Path
-
-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. 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. 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. 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, 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)
-
-Recommend invoking `refactor-pipeline-launcher` to configure and launch the dev-pipeline. Do NOT recommend running shell scripts directly — that is the launcher's responsibility.
-
-## Error Recovery & Resume
-
-Key behaviors:
-- Warnings only -> proceed with user approval
-- Critical errors -> group by type, auto-fix where possible, max 3 total attempts
-- Interrupted session -> detect checkpoint from existing artifacts, offer resume or restart
-- `.prizmkit/plans/refactor-list.json` MUST be written to `.prizmkit/plans/` (project root level: `./{root}/.prizmkit/plans/refactor-list.json`)
-
-### Resume Detection
-
-If existing artifacts are found, offer to resume from the appropriate checkpoint/phase:
-
-| Artifact Found | Resume From |
-|---------------|------------|
-| Nothing | Phase 1: Project Context |
-| Draft in `.prizmkit/plans/` | Phase matching draft state |
-| Partial `.prizmkit/plans/refactor-list.json` | Phase 6: Completeness Review |
-| Valid `.prizmkit/plans/refactor-list.json` | Mode D: Summary |
-
-### Session Exit Gate
-
-Prevent accidental session exit without deliverable completion.
-
-**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:
-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
-   - **(b) Save draft & exit** — write current progress as draft, exit session
-   - **(c) Abandon** — exit without saving
-3. **If (b)**: Write draft and remind: "This is a draft, not validated. Run `/refactor-planner` again to resume."
-4. **If (c)**: Accept without further prompting.
-
-## Handoff Message Template
-
-After successful validation, report:
-1. Output file path
-2. Total refactor items
-3. Dependency ordering highlights (which items must run first)
-4. Behavior preservation strategy distribution (N items with test-gate, M with snapshot, etc.)
-5. Recommended next action: `refactor-pipeline-launcher`

package/bundled/skills-windows/refactor-planner/assets/planning-guide.md

@@ -1,292 +0,0 @@
-# Refactor Planning Reference Guide
-
-This guide provides structured patterns, decision matrices, and templates for decomposing refactoring goals into well-scoped, executable items. It is intended as a practical reference for the AI during interactive refactor planning sessions.
-
----
-
-## 1. Identifying Refactoring Boundaries
-
-Refactoring boundaries define where one refactor item ends and another begins. Good boundaries produce items that are independently executable and independently verifiable.
-
-### Boundary Heuristics
-
-| Signal | Boundary Type | Example |
-|--------|--------------|---------|
-| Different files/modules | Module boundary | "Extract auth logic" vs "Extract validation logic" |
-| Different refactoring operations | Operation boundary | "Rename function" vs "Extract class" |
-| Different risk levels | Risk boundary | "Safe rename" vs "Restructure module internals" |
-| Different test suites affected | Test boundary | "Changes unit tests only" vs "Changes integration tests" |
-| Sequential dependency | Dependency boundary | "Rename X" must complete before "Move X to new module" |
-
-### Rules for Setting Boundaries
-
-1. **One operation type per item.** Don't mix a rename with a structural extraction in the same item.
-2. **One module scope per item** (unless the refactoring specifically targets cross-module concerns like decoupling).
-3. **Each item should be independently testable.** After completing item R-001, all tests should pass before starting R-002.
-4. **If an item requires more than 3 files to change simultaneously**, consider splitting it.
-5. **If behavior preservation requires different strategies for different parts**, split into separate items with appropriate strategies.
-
----
-
-## 2. Description Writing Guide
-
-Refactor item descriptions are the primary input for autonomous pipeline sessions. A thin description forces the AI to guess about scope and safety constraints.
-
-### Minimum Word Counts
-
-| Complexity | Minimum Words | Warning Threshold |
-|------------|---------------|-------------------|
-| low        | 15            | 30                |
-| medium     | 15            | 50                |
-| high       | 15            | 80                |
-
-Below 15 words is a validation error. Below the threshold triggers a warning.
-
-### What to Include
-
-Every refactor description should cover:
-
-1. **What to change** — specific files, functions, classes, or patterns being refactored
-2. **How to change it** — the refactoring operation (extract, rename, move, inline, simplify)
-3. **Why** — the motivation (reduce complexity, improve testability, remove duplication)
-4. **Constraints** — what must NOT change (public API, behavior contracts, external interfaces)
-5. **Verification** — how to confirm the refactoring succeeded without breaking behavior
-
-### Good vs Bad Examples
-
-**Bad** (12 words — too thin):
-```
-"Extract the validation logic from the handler into a separate module."
-```
-
-**Good** (55 words — implementation-ready):
-```
-"Extract all input validation functions from src/api/handler.js (validateEmail, validatePassword, validateUsername) into a new src/utils/validators.js module. Update all imports in handler.js and any other files that import these functions directly. Preserve the exact function signatures and return types. The handler.js file should import from the new location. All existing tests must continue to pass without modification."
-```
-
-**Bad** (14 words):
-```
-"Convert the user service from callbacks to async/await pattern throughout."
-```
-
-**Good** (72 words — implementation-ready):
-```
-"Convert src/services/user-service.js from callback-based functions to async/await. Target functions: createUser, findUserById, updateUser, deleteUser (4 functions total). Each function currently accepts a callback as the last parameter and calls it with (err, result). Convert to return Promises and use async/await internally. Update all callers in src/routes/user-routes.js to use await instead of passing callbacks. Preserve all error handling behavior — errors that were passed to callbacks should now be thrown."
-```
-
----
-
-## 3. Common Refactoring Patterns
-
-Use these patterns as starting points when decomposing refactoring goals.
-
-### Pattern A: Extract Method/Function
-
-**When**: A function is too long, has multiple responsibilities, or contains duplicated logic.
-
-```
-R-001: Extract [specific logic] from [source function] into [new function name]
-  Type: extract
-  Scope: [source file]
-  Complexity: low
-  Preservation: test-gate
-```
-
-### Pattern B: Extract Class/Module
-
-**When**: A file/class is too large, a group of functions share a common concern, or a module has multiple responsibilities.
-
-```
-R-001: Create new module [name] with extracted [concern] logic
-  Type: extract
-  Scope: [source file, new file]
-  Complexity: medium
-  Preservation: test-gate
-
-R-002: Update imports to use new [name] module (deps: R-001)
-  Type: restructure
-  Scope: [all importing files]
-  Complexity: low
-  Preservation: test-gate
-```
-
-### Pattern C: Move Module/File
-
-**When**: A file is in the wrong directory, module organization needs restructuring.
-
-```
-R-001: Move [file] from [old path] to [new path]
-  Type: restructure
-  Scope: [file, all importers]
-  Complexity: low-medium (depends on import count)
-  Preservation: test-gate
-```
-
-### Pattern D: Inline (Reverse of Extract)
-
-**When**: An abstraction is unnecessary, a wrapper adds no value, or indirection hurts readability.
-
-```
-R-001: Inline [function/module] into [target]
-  Type: simplify
-  Scope: [source file, target file]
-  Complexity: low
-  Preservation: test-gate
-```
-
-### Pattern E: Rename (Variable, Function, Class, File)
-
-**When**: Names are misleading, inconsistent, or don't follow conventions.
-
-```
-R-001: Rename [old name] to [new name] across codebase
-  Type: rename
-  Scope: [all files containing the name]
-  Complexity: low
-  Preservation: test-gate
-```
-
-### Pattern F: Decouple Dependencies
-
-**When**: Circular dependencies, tight coupling between modules, or difficulty testing in isolation.
-
-```
-R-001: Define interface/contract for [dependency] (deps: none)
-  Type: decouple
-  Scope: [new interface file]
-  Complexity: medium
-  Preservation: test-gate
-
-R-002: Implement [dependency] behind new interface (deps: R-001)
-  Type: decouple
-  Scope: [implementation file]
-  Complexity: medium
-  Preservation: test-gate
-
-R-003: Update consumers to use interface instead of concrete (deps: R-002)
-  Type: decouple
-  Scope: [all consumer files]
-  Complexity: medium
-  Preservation: test-gate
-```
-
-### Pattern G: Architecture Migration
-
-**When**: Converting between paradigms (callbacks to promises, classes to functions, monolith to modules).
-
-```
-R-001: Add new [pattern] alongside old [pattern] (deps: none)
-  Type: migrate
-  Scope: [target files]
-  Complexity: medium-high
-  Preservation: test-gate or snapshot
-
-R-002: Migrate [specific area] to new pattern (deps: R-001)
-  Type: migrate
-  Scope: [area files]
-  Complexity: medium
-  Preservation: test-gate
-
-R-003: Remove old [pattern] code (deps: R-002)
-  Type: simplify
-  Scope: [cleaned files]
-  Complexity: low
-  Preservation: test-gate
-```
-
----
-
-## 4. Dependency Ordering Rules
-
-Correct ordering minimizes risk and ensures each step is independently verifiable.
-
-### Ordering Priority (execute in this order)
-
-1. **Safe renames** — Lowest risk. Pure name changes with no structural impact. Can be reverted trivially.
-2. **Extract/inline** — Moderate risk. Changes module boundaries but doesn't reorganize architecture.
-3. **Structural changes** — Higher risk. Reorganizes file layout, module hierarchy, or dependency graph.
-4. **Migrations** — Highest risk. Changes programming patterns or paradigms.
-
-### Dependency Rules
-
-1. **No circular dependencies.** Dependencies MUST form a directed acyclic graph (DAG).
-2. **Minimal dependency sets.** Each item should depend only on items it directly needs.
-3. **Rename before restructure.** If you're renaming something AND moving it, rename first (easier to track).
-4. **Create before consume.** If item A creates a new module and item B uses it, B depends on A.
-5. **Interface before implementation.** If decoupling, define the interface before implementing behind it.
-6. **Preserve before remove.** If migrating, ensure new code works before removing old code.
-
-### Validation Checklist
-
-- [ ] No item depends on itself
-- [ ] No circular dependency chains exist
-- [ ] Every item ID referenced in a dependency list is defined in the plan
-- [ ] The graph can be topologically sorted
-- [ ] Renames appear before structural changes that reference the renamed entities
-
----
-
-## 5. Acceptance Criteria for Refactoring
-
-Refactoring acceptance criteria focus on structural improvement AND behavior preservation. They differ from feature acceptance criteria.
-
-### Standard Criteria Templates
-
-**For extract operations:**
-- [ ] New module/function exists at [target path]
-- [ ] Original location imports from new location (no duplication)
-- [ ] All existing tests pass without modification
-- [ ] No new circular dependencies introduced
-
-**For rename operations:**
-- [ ] Old name does not appear anywhere in codebase (except git history)
-- [ ] All references updated to new name
-- [ ] All existing tests pass without modification
-
-**For restructure operations:**
-- [ ] Files are in their new locations
-- [ ] All import paths updated
-- [ ] Module boundary is clean (no reaching into internal paths)
-- [ ] All existing tests pass without modification
-
-**For decouple operations:**
-- [ ] Interface/contract defined and documented
-- [ ] Implementation satisfies interface
-- [ ] Consumers depend on interface, not implementation
-- [ ] No circular dependencies remain
-- [ ] All existing tests pass without modification
-
-**For migrate operations:**
-- [ ] New pattern is used in target area
-- [ ] Old pattern code is removed (no dead code)
-- [ ] All existing tests pass (may need test updates to use new pattern)
-- [ ] Behavior is identical (verified via test-gate or snapshot)
-
-### Writing Principles
-
-1. **Always include "all existing tests pass"** — this is the fundamental refactoring invariant.
-2. **Be specific about structural outcomes** — "files are organized by feature" is vague; "auth files are in src/features/auth/" is concrete.
-3. **Include negative criteria** — "no circular dependencies", "no dead code", "no duplicated logic".
-4. **Keep count manageable** — 3-5 criteria per item. More than 6 suggests the item should be split.
-
----
-
-## 6. Complexity Estimation for Refactoring
-
-| Factor | Low | Medium | High |
-|--------|-----|--------|------|
-| File count | 1-2 files | 3-5 files | 6+ files |
-| Cross-module scope | Same module | 2 modules | 3+ modules |
-| Test coverage | High (>80%) | Moderate (40-80%) | Low (<40%) |
-| Pattern familiarity | Well-known (rename, extract) | Common (restructure) | Novel (custom migration) |
-| Dependency changes | None | Minor (1-2 imports) | Significant (module graph changes) |
-
-**Rule**: Take the highest individual factor as the overall complexity. When in doubt, estimate higher.
-
-### Complexity Red Flags (Consider Splitting)
-
-- Item touches more than 5 files
-- Item requires changes to both test files and source files in non-trivial ways
-- Item involves both structural change AND pattern migration
-- Item has more than 6 acceptance criteria
-- Item's description exceeds 100 words (suggests multiple operations combined)