prizmkit 1.1.106 → 1.1.108

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

@@ -51,9 +51,22 @@ When the user provides detailed specifications, rules, or implementation require
 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`
+4. **Task-scoped `user_context`**: In single-refactor planning, write the relevant user-provided materials into that refactor item's `user_context`. In multi-refactor planning, multi-refactor `user_context` must contain only the user text, file references, goals, and constraints relevant to that specific refactor item.
+   - Preserve the matching user wording verbatim, but scope it to the item it belongs to.
+   - Do NOT copy the full multi-refactor request into every item.
+   - Ensure there are no unrelated sibling refactor goals, target files, constraints, desired end states, or supplementary materials in a refactor item's `user_context`.
+   - Shared global context may be copied to every item only when it is explicitly applicable to all generated items.
+   - If a goal, constraint, target file, or architecture note applies to only one refactor item, attach it only to that matching item.
+   - If applicability is unclear, ask the user to map the material to the correct refactor item before generating the final list.
+5. **`user_context` format**:
+   - Refactor-specific supplementary content, goals, or constraints → store as-is (verbatim text) on the matching refactor item only
+   - Refactor-specific file references → store as path string, e.g. `src/auth/login.ts:42-78` or `src/utils/validate.ts — focus on validateEmail function`
+   - Truly shared global constraints → repeat only when they apply to every generated refactor item
+
+**Multi-refactor isolation example:**
+- User request includes: `Refactor A: extract auth validation into middleware`, `Refactor B: split dashboard chart utilities`, and `Shared: preserve all public APIs`.
+- The auth middleware refactor `user_context` includes `Refactor A: extract auth validation into middleware` and the shared API constraint; it MUST NOT include `Refactor B: split dashboard chart utilities`.
+- The chart utilities refactor `user_context` includes `Refactor B: split dashboard chart utilities` and the shared API constraint; it MUST NOT include `Refactor A: extract auth validation into middleware`.
 
 ## When to Use
 - "Plan refactoring", "Scope a restructuring"
@@ -252,10 +265,13 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
    ```
    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
+4. If validation passes -> run the mandatory Post-Generation Plan Review Gate (see §Post-Generation Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass
+5. If review and validation pass -> present final summary
 
 **CHECKPOINT CP-RP-6**: `.prizmkit/plans/refactor-list.json` generated and validated.
 
+**CHECKPOINT CP-RP-7**: `/prizmkit-code-review` reviewed only newly added/changed refactor entries; accepted fixes were regenerated and revalidated.
+
 ## Checkpoints (Mandatory Gates)
 
 | Checkpoint | Artifact/State | Criteria | Phase |
@@ -267,6 +283,32 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
 | **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 |
+| **CP-RP-7** | Plan Review Passed | `/prizmkit-code-review` reviewed only newly added/changed refactor entries; accepted fixes were regenerated and revalidated | 7 |
+
+## Post-Generation Plan Review Gate
+
+User requirement preserved verbatim: `每次完成任务规划的时候，应该调用/prizmkit-code-review 对新增的计划内容进行review，确保生成新增的计划的正确行和完整性。`
+
+Run this gate **after** `.prizmkit/plans/refactor-list.json` passes the validation/generate script and **before** the final handoff summary recommends `refactor-pipeline-launcher`. This gate applies to full workflow, Mode B from analysis, and fast-path refactor planning.
+
+1. **Identify review scope**: compare the final validated refactor list against the pre-session list when one existed. Review only newly added or changed refactor entries. Do not re-review unchanged historical entries except when needed to verify dependency references or behavior-preservation interactions.
+2. **Invoke `/prizmkit-code-review` as a planning-quality gate** with an explicit prompt that this is a refactor-plan-entry review, not an implementation review. The review must check:
+   - schema correctness and compatibility with `dev-pipeline-refactor-list-v1`
+   - dependency/DAG soundness, including safe behavior-preserving order
+   - description completeness and headless execution readiness
+   - acceptance criteria specificity and measurable behavior-preservation verification
+   - `behavior_preservation` strategy quality and target scope consistency
+   - preservation of user-provided wording in `description`, `acceptance_criteria`, and `user_context`
+   - task-scoped `user_context` isolation: no unrelated sibling refactor goals, target files, constraints, or supplementary materials, and shared context appears on multiple items only when explicitly global
+   - priority/complexity calibration: every reviewed refactor has a short priority rationale and complexity rationale, medium/low assignments are allowed when criteria fit, and high/high is not used merely because the work is cleanup, framework-related, multi-file, or user-requested
+3. **Keep the review planning-only**: do NOT start `refactor-pipeline-launcher`, do NOT run the refactor pipeline, do NOT run tests/builds/installs, and do NOT implement source-code refactors.
+4. **Apply accepted review fixes through the draft/source plan**: when a finding is accepted, update `.prizmkit/plans/refactor-list.draft.json` or the in-memory draft representation first, then regenerate the final file with:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
+   ```
+   Do not hand-patch the final JSON as the source of truth; map final-output findings back to draft entries before regeneration.
+5. **Revalidate after every accepted fix batch**: the generate script must pass again before the planner can proceed. If validation fails, fix the draft and rerun until pass.
+6. **Report the gate outcome** in the final summary: include `/prizmkit-code-review` verdict, reviewed refactor IDs, accepted fixes (or "none"), and final validation result.
 
 ## Output Rules
 
@@ -307,6 +349,44 @@ Browser verification is a feature-pipeline capability only. Refactors use `behav
 
 ---
 
+## Priority and Complexity Calibration (Mandatory)
+
+Refactor planning must not collapse into uniform `Priority: high` and `Complexity: high`. Refactoring work can be low or medium priority even when it touches several files. Do not use high/high merely because code needs cleanup, the user cares about maintainability, the target is framework code, or multiple files are involved.
+
+### Priority Rubric
+
+| Priority | Use When | Do NOT Use Merely Because |
+|----------|----------|---------------------------|
+| `critical` | Behavior-preserving restructure is required to unblock an imminent release, security/compliance fix, or safe migration with no acceptable workaround. | The refactor is large or architectural in wording. |
+| `high` | Current structure blocks core feature delivery, creates ongoing correctness/security/data-risk, prevents supported runtime upgrades, or many downstream tasks cannot proceed. | The code is messy, multi-file, or important to the user. |
+| `medium` | Refactor improves maintainability, testability, or dependency boundaries for planned work but does not block current operation. | Medium is the normal default for useful refactors. |
+| `low` | Local cleanup, rename, simplification, documentation-oriented organization, or isolated code-health improvement with low behavior risk. | Small scope alone does not make it low if it blocks a high-impact outcome. |
+
+### Complexity Rationale Rules
+
+Assign complexity from concrete refactor scope indicators and include a short rationale:
+- file count and expected import/update sites
+- cross-module scope and dependency depth
+- public API/interface or import-path change
+- existing test coverage and behavior-preservation strategy
+- behavior-preservation risk and snapshot/manual verification needs
+- migration impact, rollout phases, or compatibility shims
+
+Use `low` for 1-3 files in one module with good tests and no public API/import-path change. Use `medium` for 4-8 files or two modules with bounded public impact and clear behavior-preservation tests. Use `high` only for 9+ files, 3+ modules, public API/import-path migration, weak test coverage, manual preservation risk, or cross-module migration impact.
+
+### Required Planning Review Summary
+
+Before writing `.prizmkit/plans/refactor-list.json`, show a calibration table with rationale columns:
+
+```
+ID    | Title                       | Priority | Priority Rationale              | Complexity | Complexity Rationale
+R-001 | Break auth/user cycle        | high     | Blocks feature work; core risk  | high       | 3 modules + public imports + weak tests
+R-002 | Extract chart format helpers | medium   | Maintainability for planned UI  | medium     | 5 files; bounded helper API; tests exist
+R-003 | Rename local temp variable   | low      | Local readability only          | low        | One file; no interface or behavior change
+```
+
+Anti-pattern rule: do not assign every generated item `Priority: high` and `Complexity: high` unless each item independently satisfies the documented high-priority and high-complexity criteria and the rationale names those criteria.
+
 ## Refactoring-Specific Features
 
 ### Behavior Preservation Check
@@ -319,7 +399,7 @@ Auto-detect inter-item dependencies and enforce safe ordering. Read `${SKILL_DIR
 
 ### 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.
+Assess each item's complexity from concrete indicators: file count, cross-module scope, public API/import-path changes, dependency depth, test coverage, behavior-preservation risk, and migration impact. Read `${SKILL_DIR}/references/planning-phases.md` for the full complexity assessment criteria and scoring rules. Every confirmation/review summary must include a short complexity rationale.
 
 ## Next-Step Execution Policy (after planning)
 
@@ -364,9 +444,10 @@ Prevent accidental session exit without deliverable completion.
 
 ## Handoff Message Template
 
-After successful validation, report:
+After successful validation and the Post-Generation Plan Review Gate, 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`
+5. Review result: `/prizmkit-code-review` verdict, reviewed refactor IDs, accepted fixes (or "none"), and final validation result
+6. Recommended next action: `refactor-pipeline-launcher`

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

@@ -36,7 +36,7 @@ For simple refactoring with minimal scope.
    ```bash
    python3 ${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
+5. If valid -> run the mandatory Post-Generation Plan Review Gate from the main `refactor-planner` skill before summarizing or recommending `refactor-pipeline-launcher`.
 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
@@ -55,5 +55,6 @@ AI: [Uses AskUserQuestion with options: "Fast-path", "Full workflow", "Implement
 User: [Selects "Fast-path"]
 AI: "Drafting R-001..."
 AI: [Validates immediately]
+AI: [Runs the Post-Generation Plan Review Gate on R-001 only]
 AI: "Ready to proceed to dev-pipeline."
 ```

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

@@ -11,8 +11,9 @@ Read `${SKILL_DIR}/assets/planning-guide.md` for decomposition patterns and depe
 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`)
+3. Assess complexity per item from concrete indicators (file count, cross-module scope, public API/import-path impact, dependency depth, test coverage, behavior-preservation risk, migration impact)
+4. Assign priority from concrete impact (blocked delivery, correctness/security/data risk, maintainability value, or local cleanup), not from size or user urgency alone
+5. Assign behavior preservation strategy per item (read `${SKILL_DIR}/references/behavior-preservation.md`)
 
 ---
 
@@ -26,7 +27,9 @@ Refactor Item R-001:
   Type: [extract/rename/restructure/simplify/decouple/migrate]
   Scope: [files list]
   Priority: [critical/high/medium/low]
+  Priority Rationale: [short concrete impact reason]
   Complexity: [low/medium/high]
+  Complexity Rationale: [short scope/risk reason]
   Behavior Preservation: [test-gate/snapshot/manual]
   Acceptance Criteria:
     - [criterion 1]
@@ -63,11 +66,11 @@ Continue until all items are confirmed or skipped.
 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
+Item       | Priority | Priority Rationale       | Complexity | Complexity Rationale        | Deps Valid | Preservation | Gaps           | Status
+R-001      | high     | Blocks core feature work  | high       | 3 modules + public imports  | OK         | test-gate    | -              | Ready
+R-002      | medium   | Planned maintainability   | medium     | 5 files + tests exist       | OK         | test-gate    | -              | Ready
+R-003      | low      | Local readability only    | low        | One file, no API change     | OK         | manual       | No test coverage| Needs attention
+R-004      | medium   | Reduces bounded coupling  | medium     | 2 modules + snapshot check  | OK         | snapshot     | -              | Ready
 ```
 
 If issues found, discuss with user and resolve before proceeding.
@@ -100,13 +103,28 @@ Auto-detect inter-item dependencies and enforce safe ordering:
 
 ## Complexity Assessment
 
+Complexity is a behavior-preserving execution risk estimate, not a measure of how much the user wants the refactor. Do not default to high because a refactor spans multiple files, targets framework code, or improves maintainability.
+
 Assess each item's complexity based on:
-- **File count**: 1-2 files = low, 3-5 files = medium, 6+ files = high
+- **File count**: 1-3 files = low, 4-8 files = medium, 9+ 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
+- **Public API/import-path impact**: no public change = low, bounded internal interface = medium, public API/import migration = high
+- **Dependency depth**: 0-2 import/update sites = low, 3-5 = medium, 6+ = high
+- **Test coverage**: strong existing tests can keep complexity lower; weak/missing tests increase complexity
+- **Behavior-preservation risk**: test-gate with clear assertions = lower, snapshot/manual verification = higher
+- **Migration impact**: no rollout = low, compatibility shim = medium, cross-module migration or phased rollout = high
+
+Take the highest well-supported individual assessment as the item's complexity, then record the rationale in the confirmation table.
+
+### Mixed Calibration Examples
+
+| Refactor | Priority | Complexity | Rationale |
+|----------|----------|------------|-----------|
+| Break circular dependency blocking auth feature work | high | high | Blocks core delivery; 3 modules, public imports, and weak tests. |
+| Extract chart formatting helpers from dashboard files | medium | medium | Improves planned maintainability; 5 files with bounded helper API and existing tests. |
+| Rename local variable in parser for readability | low | low | Local cleanup only; one file, no interface or behavior change. |
 
-Take the highest of these individual assessments as the item's complexity.
+Anti-pattern: do not generate an all-high refactor list unless every item independently satisfies documented high-priority and high-complexity criteria.
 
 ---
 

package/bundled/skills/refactor-workflow/SKILL.md

@@ -1,61 +1,90 @@
 ---
 name: "refactor-workflow"
-description: "One-stop entry point for code refactoring. Brainstorms refactoring goals with the user until fully clarified, then orchestrates refactor-planner → refactor-pipeline-launcher → execution. Handles multi-refactor batch development from a single request. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring', 'batch refactor'."
+description: "Triage-based refactor workflow. Clarifies behavior-preserving refactoring goals, then lets the user choose Fast Path for simple current-session/current-workspace refactors or Pipeline Path for complex/batch refactors via refactor-planner → refactor-pipeline-launcher. Use when the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring', 'batch refactor'."
 ---
 
 # Refactor Workflow
 
-One-stop entry point for code refactoring. Covers the complete journey from a rough refactoring idea to verified, behavior-preserving code changes: deep goal clarification → structured planning → autonomous pipeline execution.
+Triage-based entry point for code refactoring. The workflow clarifies behavior-preserving goals, assesses risk and scope, asks the user to choose an approach, then follows one of two paths:
+
+- **Fast Path** — a simple behavior-preserving refactor is implemented directly in the **current session** and **current workspace** with the normal PrizmKit lifecycle commands.
+- **Pipeline Path** — complex or batch refactors are planned with `refactor-planner`, launched with `refactor-pipeline-launcher`, then monitored.
+
+This skill keeps Fast Path and Pipeline Path separate. Pipeline monitoring only happens after the user selects Pipeline Path and the launcher starts execution.
 
 ## When to Use
 
 User says:
 - "Refactor the auth module", "Clean up this code", "Restructure the payment service"
 - "Extract shared logic into a separate module", "Optimize code structure"
+- "Do this small behavior-preserving cleanup now"
 - "Batch refactor these modules", "Code refactoring across multiple files"
 - Code has accumulated tech debt that needs structural improvement
 - Module needs to be split, merged, or reorganized
 
 **Do NOT use this skill when:**
-- User only wants to plan refactoring (use `refactor-planner` directly)
-- User only wants to launch pipeline for existing .prizmkit/plans/refactor-list.json (use `refactor-pipeline-launcher`)
-- User wants to add features (use `feature-workflow`)
-- User wants to fix bugs (use `bug-planner` + `bugfix-pipeline-launcher`)
+- User only wants to plan refactoring without execution → use `refactor-planner` directly
+- User only wants to launch an existing `.prizmkit/plans/refactor-list.json` → use `refactor-pipeline-launcher`
+- User wants to add features → use `feature-workflow`
+- User wants to fix bugs → use `bug-fix-workflow` or `bug-planner` + `bugfix-pipeline-launcher`
 
 ---
 
 ## Overview
 
-Four phases take a rough refactoring idea to verified, behavior-preserving code so the user doesn't have to manually chain planner → launcher → monitoring:
+The shared contract is:
+
+1. **Brainstorm** — clarify refactoring type, collect reference materials, read relevant code/docs/tests, and confirm behavior-preservation requirements.
+2. **Assess difficulty and behavior risk** — decide whether the request is a simple behavior-preserving Fast Path candidate or a complex/batch Pipeline Path candidate.
+3. **AskUserQuestion approach selection** — present selectable options; never silently choose the path.
+4. **Execute selected path**:
+   - **Fast Path**: `/prizmkit-plan` → `/prizmkit-implement` with behavior-preservation tests/checks → `/prizmkit-code-review` → `/prizmkit-retrospective` → `/prizmkit-committer` in the current workspace.
+   - **Pipeline Path**: `refactor-planner` → `refactor-pipeline-launcher` → monitoring.
+
+### Terminology
 
-1. **Brainstorm** — clarify type, collect reference materials, parallel deep read code & docs, discuss plan grounded in real code → fully clarified refactoring goals
-2. **Plan** — call `refactor-planner` → `.prizmkit/plans/refactor-list.json` with N refactor items
-3. **Launch** — call `refactor-pipeline-launcher` → pipeline started (execution mode chosen by user via launcher)
-4. **Monitor** — track progress → status updates, completion report
+| Term | Meaning |
+|------|---------|
+| **Fast Path** | Current-session/current-workspace implementation for simple, behavior-preserving refactors. It does not create or consume `.prizmkit/plans/refactor-list.json` and does not start the refactor pipeline. |
+| **Pipeline Path** | Complex or batch refactor execution. Planner handoff goes to `refactor-planner`; launcher handoff goes to `refactor-pipeline-launcher`; monitoring follows only after launch. |
+| **Current session** | The interactive AI CLI session that is already discussing the refactor with the user. |
+| **Current workspace** | The current git checkout and working tree, not a background pipeline worktree/session. |
+| **Behavior preservation** | External behavior, public contracts, tests, and user-visible outcomes remain unchanged unless the user explicitly approves a behavior change as a feature. |
+| **Monitoring** | Status/log follow-up for a launched refactor pipeline; it is not part of the Fast Path. |
 
-### Branch Management
+### Workspace and Branch Model
 
-The dev-pipeline handles branch management per-refactor automatically:
-- Each refactor item is implemented on its own branch by the pipeline
-- Branches are created, committed, and managed by the pipeline session
-- This workflow does NOT create a top-level branch — the pipeline manages granular per-refactor branches
+- **Fast Path**: work happens in the current workspace and current interactive session. Use the current branch unless the project policy or user explicitly asks to create a branch.
+- **Pipeline Path**: `refactor-pipeline-launcher` and the dev-pipeline manage per-refactor branches/worktrees. This workflow does not create a top-level branch before handing off to the launcher.
 
 ---
 
 ## Input Modes
 
-**Mode A: From natural language description** (default)
+**Mode A: Natural language refactoring goal** (default)
 
 Natural language description of the refactoring goals. Can be:
+- A simple behavior-preserving refactor: "Extract this helper function and keep behavior unchanged"
 - A module target: "Refactor the auth module — extract shared middleware, simplify the token flow"
 - A batch of refactors: "Clean up the payment service, decouple the notification module, and extract common utilities"
 - An incremental request: "Also refactor the logging layer to use structured logging"
 
-Flow: brainstorm → refactor-planner → refactor-pipeline-launcher → monitor
+Flow: brainstorm → complexity/behavior-risk assessment → AskUserQuestion → Fast Path or Pipeline Path.
 
-**Mode B: From existing `.prizmkit/plans/refactor-list.json`** — user says "run pipeline from existing file", or the file already exists. Skip ahead per the [Resume table](#resume--interruption-recovery).
+**Mode B: Existing `.prizmkit/plans/refactor-list.json`**
 
-**Mode C: Incremental (add to existing refactor plan)** — user says "add more refactors". Brainstorm new goals, then invoke `refactor-planner` in incremental mode (appends to existing list) → launch → monitor.
+When the user says "run pipeline from existing file" or `.prizmkit/plans/refactor-list.json` already exists and should be executed:
+- Skip brainstorm and `refactor-planner`
+- Invoke `refactor-pipeline-launcher` directly
+- Monitor and report progress
+
+**Mode C: Incremental refactor request**
+
+When user says "add more refactors":
+- Brainstorm only the new refactoring goals
+- Assess whether the new scope is simple and behavior-preserving enough for Fast Path
+- For simple work: use Fast Path in the current workspace
+- For complex or batch work: invoke `refactor-planner` in incremental mode, then `refactor-pipeline-launcher`
 
 ---
 
@@ -79,6 +108,7 @@ Then ask:
 - **What** code needs restructuring (modules, files, patterns)
 - **Why** it needs refactoring (tech debt, coupling, complexity, readability, performance structure)
 - **What outcome** they want (target architecture, desired structure, quality goals)
+- **What behavior must remain unchanged** (public APIs, outputs, workflows, tests, performance-sensitive paths)
 
 ### Step 1.2: Collect Reference Materials
 
@@ -95,6 +125,7 @@ Ask:
 2. **Design documents** — "Do you have any design docs, architecture diagrams, or refactoring proposals I should read?"
 3. **Knowledge docs** — "Are there related `.prizmkit/prizm-docs/`, README files, or internal wiki pages for the target area?"
 4. **Related issues/PRs** — "Any related issues, PRs, or previous refactoring attempts I should be aware of?"
+5. **Behavior checks** — "Which tests, commands, or manual scenarios prove behavior must stay the same?"
 
 Record everything the user provides — these become inputs for Step 1.3.
 
@@ -121,23 +152,26 @@ Read `${SKILL_DIR}/references/brainstorm-guide.md` §Completion Signs for the fu
 
 Once brainstorming is complete, produce a structured goals summary. Read `${SKILL_DIR}/references/brainstorm-guide.md` §Refactoring Goals Summary Template for the structured output format. Present the summary to the user and get explicit confirmation before proceeding.
 
+The summary must include behavior-preservation expectations: tests to run, public contracts to keep stable, and any explicitly approved behavior changes. If behavior changes are required, route them as feature work rather than refactoring unless the user explicitly scopes them here.
+
 **CHECKPOINT CP-RW-0**: Refactoring goals fully clarified and confirmed by user.
 
 ---
 
 ### Step 1.7: Complexity Assessment & Approach Selection
 
-After confirming refactoring goals, assess whether this refactor needs the full pipeline or can be done directly in the current session.
+After confirming refactoring goals, assess whether this refactor needs the Pipeline Path or can be done directly in the current session/current workspace.
 
-**Simple refactor → Fast Path candidate** (ALL must be true):
+**Simple behavior-preserving refactor → Fast Path candidate** (ALL must be true):
 - Single module, no cross-module impact
 - ≤3 files affected
 - No public API or interface changes
 - Straightforward transformation (extract method, rename, move file, simplify logic)
-- Existing tests fully cover the affected code paths
-- No risk of behavior change
+- Existing tests or focused checks cover the affected behavior
+- No behavior change risk beyond what tests/checks can verify
 
-**Complex refactor → Planning Path** (ANY is true):
+**Complex or batch refactors → Pipeline Path candidate** (ANY is true):
+- Multiple refactor items or batch refactoring request
 - Cross-module impact (>2 modules affected)
 - Public API or interface changes required
 - Multiple interrelated refactoring steps with dependency ordering
@@ -145,48 +179,56 @@ After confirming refactoring goals, assess whether this refactor needs the full
 - Insufficient test coverage in target area (risk of hidden behavior changes)
 - Requires coordination with other ongoing work
 
-**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options. Tailor the question text to the assessment ("This refactoring appears straightforward…" for simple, "This refactoring is complex and will benefit from structured planning…" for complex), but the two options are always the same:
+**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options. Tailor the question text to the assessment: for a simple refactor, "This refactor appears straightforward and behavior-preserving enough for the current-session Fast Path." For a complex or batch refactor, "This refactor is complex or batch-oriented and should use the Pipeline Path."
 
 ```
 AskUserQuestion:
-  question: <tailored to simple vs complex assessment>
+  question: "How would you like to proceed?"
   header: "Approach"
   options:
-    - label: "Refactor now (fast path)"
-      description: "Plan and refactor directly in this session using /prizmkit-plan + /prizmkit-implement"
-    - label: "Add to refactor list (pipeline)"
-      description: "Generate .prizmkit/plans/refactor-list.json via refactor-planner, then launch pipeline for autonomous execution"
+    - label: "Refactor now (Fast Path — current session/current workspace)"
+      description: "Run /prizmkit-plan → /prizmkit-implement → /prizmkit-code-review → /prizmkit-retrospective → /prizmkit-committer directly in this workspace with behavior-preservation checks"
+    - label: "Use Pipeline Path (refactor-planner → refactor-pipeline-launcher)"
+      description: "Generate .prizmkit/plans/refactor-list.json with refactor-planner, then launch autonomous execution with refactor-pipeline-launcher"
 ```
 
-- **Refactor now** → Fast Path: `/prizmkit-plan` (goals → `spec.md` + `plan.md`) → `/prizmkit-implement` (behavior preservation verified by tests) → `/prizmkit-code-review` → `/prizmkit-committer` (`refactor(<scope>):` prefix) → `/prizmkit-retrospective` (sync `.prizmkit/prizm-docs/`). **End workflow** — skip Phase 2/3/4.
-- **Add to refactor list** → Continue to Phase 2 (Plan via pipeline).
+- **Refactor now (Fast Path)**:
+  1. Invoke `/prizmkit-plan` with the goals summary → generates `spec.md` + `plan.md` including behavior-preservation strategy
+  2. Invoke `/prizmkit-implement` to execute the plan in the current workspace and verify behavior stays unchanged
+  3. Run `/prizmkit-code-review` for quality and behavior-preservation review
+  4. Run `/prizmkit-retrospective` to sync `.prizmkit/prizm-docs/`
+  5. Commit via `/prizmkit-committer` with `refactor(<scope>):` prefix
+  6. End workflow — do not call `refactor-planner`, do not call `refactor-pipeline-launcher`, and do not enter monitoring
+- **Use Pipeline Path** → Continue to Phase 2 (Planner handoff)
 
 **NEVER proceed without explicit user confirmation via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
 
-**CHECKPOINT CP-RW-0.5**: Approach selected by user (fast path or pipeline).
+**CHECKPOINT CP-RW-0.5**: Approach selected by user (Fast Path or Pipeline Path).
 
 ---
 
-## Phase 2: Plan
+## Phase 2: Plan — Pipeline Path Only
 
-**Goal**: Generate structured .prizmkit/plans/refactor-list.json from the clarified refactoring goals.
+**Goal**: Generate structured `.prizmkit/plans/refactor-list.json` from the clarified refactoring goals.
+
+Run this phase only when the user selected Pipeline Path or provided a batch/complex refactor request that they chose to send through the pipeline.
 
 **STEPS**:
 
-1. **Invoke `refactor-planner` skill** with the full goals summary from Phase 1:
+1. **Planner handoff — invoke `refactor-planner`** with the full goals summary from Phase 1:
    - Pass the structured goals summary as input — NOT the raw user conversation
    - For new refactoring: standard planning mode
    - For existing projects with `--incremental`: incremental planning mode
    - **Input**: Markdown goals summary (refactor targets, scope, behavior preservation strategy)
    - **Output**: `.prizmkit/plans/refactor-list.json` (schema: `dev-pipeline-refactor-list-v1`) containing `project_name`, `refactors[]` with id (R-NNN), title, description, scope, type, priority, complexity, behavior_preservation, acceptance_criteria, dependencies, status
 
-2. **Interactive planning** (if refactor-planner requires clarification):
-   - Because Phase 1 was thorough, refactor-planner should need minimal clarification
+2. **Interactive planning** (if `refactor-planner` requires clarification):
+   - Because Phase 1 was thorough, `refactor-planner` should need minimal clarification
    - If questions arise, answer from the Phase 1 context or pass through to user
 
 3. **Validate output**:
    - Confirm `.prizmkit/plans/refactor-list.json` exists
-   - Show summary: total refactor items, complexity distribution, dependencies
+   - Show summary: total refactor items, complexity distribution, dependencies, behavior-preservation coverage
 
 **CHECKPOINT CP-RW-1**: `.prizmkit/plans/refactor-list.json` generated and validated.
 
@@ -194,15 +236,15 @@ AskUserQuestion:
 
 ---
 
-## Phase 3: Launch
+## Phase 3: Launch — Pipeline Path Only
 
-**Goal**: Start the refactoring pipeline.
+**Goal**: Start the refactoring pipeline after planner handoff has produced a validated refactor list.
 
 **STEPS**:
 
 1. **Show refactor summary** before launching:
    ```
-   Ready to launch pipeline with N refactor items:
+   Ready to launch Pipeline Path with N refactor items:
      R-001: Extract auth middleware (medium complexity)
      R-002: Decouple notification service (high complexity)
      R-003: Simplify token flow (low complexity)
@@ -210,10 +252,11 @@ AskUserQuestion:
    Proceed? (Y/n)
    ```
 
-2. **Invoke `refactor-pipeline-launcher` skill**:
+2. **Launcher handoff — invoke `refactor-pipeline-launcher`**:
    - **Input**: Path to validated `.prizmkit/plans/refactor-list.json`
    - The launcher handles all prerequisites checks
    - The launcher presents execution mode choices to the user (foreground/background/manual)
+   - The launcher preserves strict behavior-check defaults
    - Do NOT duplicate execution mode selection here — let the launcher handle it
    - **Output**: PID/status, log file path, execution mode selected
    - Returns PID/status and log file location
@@ -226,9 +269,9 @@ AskUserQuestion:
 
 ---
 
-## Phase 4: Monitor
+## Phase 4: Monitor — Pipeline Path Only
 
-**Goal**: Track pipeline progress and report to user.
+**Goal**: Track pipeline progress and report to user. Monitoring applies only after `refactor-pipeline-launcher` has started a pipeline.
 
 **STEPS**:
 
@@ -271,13 +314,14 @@ AskUserQuestion:
 The workflow supports resuming by detecting existing state:
 
 | State Found | Resume From |
-|-------------|------------|
-| No `.prizmkit/plans/refactor-list.json` | Phase 1: Brainstorm |
+|-------------|-------------|
+| Fast Path `spec.md` + `plan.md` exist, code not committed | Resume `/prizmkit-implement` / review / retrospective / commit based on current state |
+| No `.prizmkit/plans/refactor-list.json` and no Fast Path artifacts | Phase 1: Brainstorm |
 | `.prizmkit/plans/refactor-list.json` exists, no pipeline state | Phase 3: Launch |
 | `.prizmkit/plans/refactor-list.json` + pipeline state exists | Phase 4: Monitor (check status) |
 | All refactors completed | Report completion, suggest next steps |
 
-**Resume**: If `.prizmkit/plans/refactor-list.json` exists, ask user: "Existing refactor plan found with N items. Resume pipeline or re-plan?"
+**Resume**: If `.prizmkit/plans/refactor-list.json` exists, ask user: "Existing refactor plan found with N items. Resume Pipeline Path or re-plan?" If Fast Path artifacts exist, ask whether to continue the current-workspace refactor or discard/re-plan.
 
 ---
 
@@ -300,21 +344,36 @@ While the pipeline runs, the user can continue the conversation:
 |-------|--------|
 | User's refactoring goal is too vague | Ask for more context: "Can you describe what's wrong with the current code structure?" |
 | Brainstorming stalls | Offer concrete options: "Would you prefer incremental or comprehensive refactoring?" |
-| No tests exist for target module | WARN user, recommend writing tests first before refactoring |
+| No tests exist for target module | WARN user, recommend writing tests/checks before Fast Path; consider Pipeline Path for risky refactors |
+| Fast Path starts risking behavior change | Pause and ask whether to switch to Pipeline Path (`refactor-planner` → `refactor-pipeline-launcher`) |
 | `refactor-planner` cannot parse goals | Refine the goals summary and retry |
 | `.prizmkit/plans/refactor-list.json` generation failed | Show error, retry with refined input |
 | Pipeline launch failed | Show daemon log, suggest manual start with `python3 ./.prizmkit/dev-pipeline/cli.py refactor run .prizmkit/plans/refactor-list.json` or `python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor start .prizmkit/plans/refactor-list.json` |
 | All refactor items blocked/failed | Show status, suggest retrying specific items |
 | User wants to cancel mid-brainstorming | Save conversation context, offer to resume later |
-| Behavior regression detected during pipeline | Pipeline handles per-item — failed items are retried or reported |
+| Behavior regression detected during Fast Path | Revert or fix immediately before commit; refactoring cannot ship with behavior regression |
+| Behavior regression detected during pipeline | Pipeline handles per-item retries/failures; report failed items and behavior checks |
+
+---
 
+## HANDOFF
 
+| From | To | Condition |
+|------|----|-----------|
+| **this skill** | `/prizmkit-plan` | User selects Fast Path for simple behavior-preserving refactor work in the current workspace |
+| **this skill** | `/prizmkit-implement` | Fast Path plan is ready for current-session implementation with behavior checks |
+| **this skill** | `/prizmkit-code-review` | Fast Path refactor is complete and needs quality/behavior-preservation review |
+| **this skill** | `/prizmkit-retrospective` | Fast Path refactor changes need `.prizmkit/prizm-docs/` sync before commit |
+| **this skill** | `/prizmkit-committer` | Fast Path refactor is reviewed, docs are synced, and behavior preservation is verified |
+| **this skill** | `refactor-planner` | User selects Pipeline Path for complex or batch refactors |
+| `refactor-planner` | `refactor-pipeline-launcher` | Planner handoff produced validated `.prizmkit/plans/refactor-list.json` |
+| `refactor-pipeline-launcher` | **this skill** | Launcher handoff completed and monitoring/status follow-up is needed |
+
+---
 
 ## Output
 
-- Structured refactoring goals summary (Phase 1 artifact)
-- `.prizmkit/plans/refactor-list.json` (Phase 2 artifact)
-- Pipeline execution (Phase 3)
-- Progress updates (Phase 4)
-- Multiple git commits with `refactor(<scope>):` prefix
-- Updated `.prizmkit/prizm-docs/` (via prizmkit-retrospective per refactor item)
+Output depends on the selected path:
+
+- **Fast Path**: `spec.md` + `plan.md`, behavior-preserving current-workspace code changes, behavior test/check evidence, `/prizmkit-code-review` result, updated `.prizmkit/prizm-docs/`, and one `refactor(<scope>):` commit from `/prizmkit-committer`.
+- **Pipeline Path**: structured refactoring goals summary, `.prizmkit/plans/refactor-list.json`, pipeline execution via `refactor-pipeline-launcher`, monitoring updates, and per-refactor commits managed by the dev-pipeline.

package/bundled/templates/project-memory-template.md

@@ -30,7 +30,7 @@ This project uses PrizmKit with the Prizm documentation system for AI-optimized
   3. Add a pointer in the parent L1 doc's SUBDIRS section
 
 ### Available Commands
-Run `/prizm-kit` to see all available PrizmKit commands.
+Run `/prizmkit` to see all available PrizmKit commands.
 
 ### Fast Path for Simple Changes
 Not every change needs the full spec -> plan workflow. Use fast path for:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.106",
+  "version": "1.1.108",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {