prizmkit 1.0.108 → 1.0.109

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.108",
-  "bundledAt": "2026-03-26T01:27:22.624Z",
-  "bundledFrom": "90a9f59"
+  "frameworkVersion": "1.0.109",
+  "bundledAt": "2026-03-26T02:14:25.170Z",
+  "bundledFrom": "d4369e9"
 }

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.108",
+  "version": "1.0.109",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/bundled/skills/bug-fix-workflow/SKILL.md

@@ -29,8 +29,51 @@ The bug can come from:
 - **A description**: "the login page crashes when I click submit"
 - **A failed test**: "this test is failing: src/auth/__tests__/login.test.ts"
 
+## Fast Path
+
+For trivial bugs with clear root cause and minimal scope:
+
+### Eligibility Criteria (ALL must be true)
+- Root cause is immediately obvious (typo, missing null check, wrong variable name, off-by-one)
+- Fix is ≤10 lines of code in a single file
+- No cross-module impact
+- Existing tests cover the affected path (or bug is in untested utility)
+- No data model or API changes
+
+### Fast Path Workflow
+1. Branch Setup → `fix/<BUG_ID>-<short-desc>`
+2. Write reproduction test → confirm failing
+3. Apply fix → confirm test passes + full suite green
+4. Ask user: "Quick fix applied. Verify before commit? (Y/skip)"
+5. Commit with `fix(<scope>):` prefix
+6. Ask merge preference
+
+**Fast Path still requires**: fix branch, reproduction test, full test suite pass, user merge decision.
+
+---
+
 ## Execution
 
+### Phase 0: Branch Setup
+
+**Goal**: Create an isolated working branch to keep main clean.
+
+1. **Check current branch**:
+   ```bash
+   git branch --show-current
+   ```
+2. **If on `main` or a shared branch**: Create and switch to fix branch:
+   ```bash
+   git checkout -b fix/<BUG_ID>-<short-description>
+   ```
+   Example: `git checkout -b fix/B-001-login-null-crash`
+3. **If already on a fix branch**: Confirm with user: "Continue on current branch `<branch-name>`, or create a new one?"
+4. **Record the original branch name** for later merge.
+
+**CHECKPOINT CP-BFW-0**: On a dedicated fix branch, not main/shared branch.
+
+---
+
 ### Phase 1: Triage
 
 **Goal**: Understand the bug, locate affected code, classify severity.
@@ -108,23 +151,75 @@ If the fix causes test regressions:
    Ready to commit.
    ```
 
-### Phase 5: Commit
+### Phase 5: User Verification
+
+**Goal**: Let the user verify the fix works as expected before committing.
 
-**Goal**: Commit the fix with proper conventions.
+1. **Ask user**: "Fix passes all tests. Would you like to verify before committing?"
+   - **(a) Run the app** — Start the dev server so you can manually test the fix scenario
+   - **(b) Run a specific command** — Specify a test or script to run
+   - **(c) Skip verification** — Proceed directly to commit (automated tests already pass)
+2. **If (a)**: Detect and suggest dev server command (e.g. `npm run dev`, `python manage.py runserver`), start it, wait for user confirmation: "Fix verified? (yes/no)"
+3. **If (b)**: Run the specified command, show results, ask confirmation
+4. **If (c)**: Proceed to Phase 6
+
+If user reports the fix is NOT working:
+- Return to Phase 3 (max 2 more attempts)
+- If still failing: escalate with analysis
+
+---
+
+### Phase 6: Commit & Merge
+
+**Goal**: Commit the fix and offer to merge back to the original branch.
 
 1. **Run `/prizmkit-committer`**:
    - Commit message: `fix(<scope>): <description>`
    - Include both fix code and reproduction test
    - Do NOT push (user decides when to push)
-   - Do NOT run `/prizmkit-retrospective` — bug fixes do not update `.prizm-docs/` (per project rules: "bugs are incomplete features, recording bug details causes doc bloat with no AI value")
+   - Do NOT run `/prizmkit-retrospective` — bug fixes do not update `.prizm-docs/`
    - `/prizmkit-committer` is a pure commit tool — it does NOT modify `.prizm-docs/` or any project files
-2. **If bug came from bug-fix-list.json**: inform user to update bug status
+2. **Ask merge preference**:
+   ```
+   Fix committed on branch `fix/<BUG_ID>-<short-desc>`.
+   What would you like to do?
+   (a) Merge to <original-branch> and delete fix branch
+   (b) Keep fix branch (for PR review workflow)
+   (c) Decide later
+   ```
+3. **If (a)**:
+   ```bash
+   git checkout <original-branch>
+   git merge fix/<BUG_ID>-<short-description>
+   git branch -d fix/<BUG_ID>-<short-description>
+   ```
+4. **If (b)**: Inform user: "Branch `fix/<BUG_ID>-<short-desc>` retained. Create a PR when ready."
+5. **If bug came from bug-fix-list.json**: inform user to update bug status
    ```
    Bug B-001 fixed and committed.
    To update the bug list: manually set B-001 status to "fixed" in bug-fix-list.json
    Or retry the pipeline to pick up remaining bugs.
    ```
 
+## Resume — Interruption Recovery
+
+The workflow supports resuming from the last completed phase by detecting existing artifacts.
+
+**Detection logic**: Check `.prizmkit/bugfix/<BUG_ID>/` and git branch state:
+
+| Artifact Found | Resume From |
+|---------------|------------|
+| (nothing) | Phase 0: Branch Setup |
+| On `fix/<BUG_ID>-*` branch, no artifacts | Phase 1: Triage |
+| `fix-plan.md` only | Phase 3: Fix |
+| `fix-plan.md` + code changes exist | Phase 4: Review |
+| All docs + review passed | Phase 5: User Verification |
+| All docs + committed | Phase 6: Merge decision |
+
+**Resume**: If `<BUG_ID>` matches an existing `.prizmkit/bugfix/<BUG_ID>/` directory, resume instead of starting fresh.
+
+---
+
 ## Artifacts
 
 Bug fix artifacts are stored at `.prizmkit/bugfix/<BUG_ID>/`:
@@ -138,8 +233,10 @@ Only 2 artifact files per bug, consistent with the pipeline convention.
 | Dimension | bug-fix-workflow (this skill) | bugfix-pipeline-launcher |
 |-----------|-------------------------------|--------------------------|
 | Scope | One bug at a time | All bugs in batch |
-| Execution | Interactive, in-session | Background daemon |
+| Execution | Interactive, in-session | Foreground or background daemon |
+| Branch | Creates `fix/<BUG_ID>-*` branch | Pipeline manages branches |
 | Visibility | Full user interaction at each phase | Async, check status periodically |
+| User verification | Yes (Phase 5) | No (automated) |
 | Best for | Complex bugs needing user input | Batch of well-defined bugs |
 | Artifacts | Same (fix-plan.md + fix-report.md) | Same |
 | Commit prefix | `fix(<scope>):` | `fix(<scope>):` |
@@ -153,6 +250,7 @@ Only 2 artifact files per bug, consistent with the pipeline convention.
 | Fix causes regressions | Revert, analyze, retry (max 3 rounds) |
 | Root cause unclear after investigation | Present findings, ask user for guidance |
 | Affected files are in unfamiliar module | Read `.prizm-docs/` L1/L2 for that module first |
+| Branch conflict during merge | Show conflict, ask user to resolve or keep branch |
 
 ## HANDOFF
 
@@ -161,11 +259,11 @@ Only 2 artifact files per bug, consistent with the pipeline convention.
 | `bug-planner` | **this skill** | User picks one bug to fix interactively |
 | `bugfix-pipeline-launcher` | **this skill** | User wants to fix a stuck/complex bug manually |
 | **this skill** | `bugfix-pipeline-launcher` | After fixing, user wants to continue with remaining bugs |
-| **this skill** | `prizmkit-committer` | Built into Phase 5 (pure commit, no doc sync) |
+| **this skill** | `prizmkit-committer` | Built into Phase 6 (pure commit, no doc sync) |
 
 ## Output
 
 - Fixed code with reproduction test
 - `.prizmkit/bugfix/<BUG_ID>/fix-plan.md`
 - `.prizmkit/bugfix/<BUG_ID>/fix-report.md`
-- Git commit with `fix(<scope>):` prefix
+- Git commit with `fix(<scope>):` prefix on dedicated fix branch

package/bundled/skills/bugfix-pipeline-launcher/SKILL.md

@@ -5,11 +5,25 @@ description: "Launch and manage the bugfix pipeline from within an AI CLI sessio
 
 # Bugfix-Pipeline Launcher
 
-Launch the autonomous bug fix pipeline from within an AI CLI conversation. The pipeline runs as a fully detached background process -- closing the AI CLI session does NOT stop the pipeline.
+Launch the autonomous bug fix pipeline from within an AI CLI conversation. Supports foreground and background execution modes.
 
 ### Execution Mode
 
-Always use daemon mode via `dev-pipeline/launch-bugfix-daemon.sh` for start/stop/status/log actions. Foreground `run-bugfix.sh` can be terminated by AI CLI command timeout, while daemon mode survives session timeout — this prevents half-finished bug fixes that leave the codebase in an inconsistent state.
+**Default: Foreground mode** via `dev-pipeline/run-bugfix.sh run` — this provides visible output and direct error feedback. Use `launch-bugfix-daemon.sh` only when the user explicitly requests background execution.
+
+Foreground `run-bugfix.sh` is preferred because:
+- Immediate visibility of errors and progress
+- No orphaned processes if something goes wrong
+- Session summary artifacts are written reliably
+
+Use daemon mode (`launch-bugfix-daemon.sh`) only when:
+- User explicitly requests background/detached execution
+- Pipeline must survive AI CLI session closure
+
+**Background mode documentation**: When the user chooses background/daemon mode, record the choice and PID in `.prizmkit/bugfix-pipeline-run.log` (append-only) with timestamp, so the decision is traceable:
+```
+[2026-03-26T10:30:00] MODE=daemon PID=12345 BUG_LIST=bug-fix-list.json BUGS=3
+```
 
 ### When to Use
 
@@ -41,7 +55,7 @@ Always use daemon mode via `dev-pipeline/launch-bugfix-daemon.sh` for start/stop
 
 Before any action, validate:
 
-1. **bugfix pipeline exists**: Confirm `dev-pipeline/launch-bugfix-daemon.sh` is present and executable
+1. **bugfix pipeline exists**: Confirm `dev-pipeline/launch-bugfix-daemon.sh` and `dev-pipeline/run-bugfix.sh` are present and executable
 2. **For start**: `bug-fix-list.json` must exist in project root (or user-specified path)
 3. **Dependencies**: `jq`, `python3`, AI CLI (`cbc` or `claude`) must be in PATH
 
@@ -100,33 +114,61 @@ Detect user intent from their message, then follow the corresponding workflow:
      --action status 2>/dev/null
    ```
 
-4. **Ask user to confirm**: "Ready to launch the bugfix pipeline? It will process N bugs (by severity order) in the background."
+4. **Ask execution mode**: Present the user with a choice before launching:
+   - **(1) Foreground in session (recommended)**: Pipeline runs in the current session via `run-bugfix.sh run`. Visible output and direct error feedback.
+   - **(2) Background daemon**: Pipeline runs fully detached via `launch-bugfix-daemon.sh`. Survives session closure. Use only when user explicitly requests background execution.
+   - **(3) Manual — show commands**: Display the exact commands the user can run themselves. No execution.
+
+   Default to option 1 if user says "just run it" or doesn't specify. Default to option 2 only if user explicitly says "background", "detached", or "run in background".
+
+   **If option 1 (foreground)**:
+   ```bash
+   dev-pipeline/run-bugfix.sh run bug-fix-list.json
+   ```
 
-5. **Launch**:
+   **If option 2 (background)**:
    ```bash
    dev-pipeline/launch-bugfix-daemon.sh start bug-fix-list.json
    ```
-   If user specified environment overrides (e.g. timeout, retries, verbose):
+   After launch, **record the decision** for traceability:
    ```bash
-   dev-pipeline/launch-bugfix-daemon.sh start bug-fix-list.json --env "SESSION_TIMEOUT=7200 MAX_RETRIES=5"
+   echo "[$(date -u +%Y-%m-%dT%H:%M:%S)] MODE=daemon PID=$(cat dev-pipeline/bugfix-state/daemon.pid 2>/dev/null) BUG_LIST=bug-fix-list.json BUGS=$(python3 -c "import json; print(len(json.load(open('bug-fix-list.json')).get('bugs',[])))")" >> .prizmkit/bugfix-pipeline-run.log
    ```
+   Note: Pipeline runs fully detached. Survives session closure.
+
+   **If option 3 (manual)**: Print commands and stop. Do not execute anything.
+   ```
+   # To run in foreground (recommended):
+   dev-pipeline/run-bugfix.sh run bug-fix-list.json
+
+   # To run in background (detached):
+   dev-pipeline/launch-bugfix-daemon.sh start bug-fix-list.json
+
+   # To check status:
+   dev-pipeline/run-bugfix.sh status bug-fix-list.json
+   ```
+
+5. **Ask user to confirm**: "Ready to launch the bugfix pipeline? It will process N bugs (by severity order)."
+
+6. **Launch** (based on chosen mode — see step 4).
 
-6. **Verify launch**:
+7. **Verify launch**:
    ```bash
    dev-pipeline/launch-bugfix-daemon.sh status
    ```
 
-7. **Start log monitoring** -- Use the Bash tool with `run_in_background: true`:
+8. **Start log monitoring** (daemon mode only) -- Use the Bash tool with `run_in_background: true`:
    ```bash
    tail -f dev-pipeline/bugfix-state/pipeline-daemon.log
    ```
    This runs in background so you can continue interacting with the user.
 
-8. **Report to user**:
-   - Pipeline PID
+9. **Report to user**:
+   - Execution mode chosen
+   - Pipeline PID (daemon mode) or session status (foreground)
    - Log file location
    - "You can ask me 'bugfix status' or 'show fix logs' at any time"
-   - "Closing this session will NOT stop the pipeline"
+   - (daemon mode only) "Closing this session will NOT stop the pipeline"
 
 ---
 
@@ -246,9 +288,10 @@ SESSION_TIMEOUT=3600 dev-pipeline/retry-bug.sh B-001 bug-fix-list.json
 ### Integration Notes
 
 - **After bug-planner**: This is the natural next step. When user finishes bug planning and has `bug-fix-list.json`, suggest launching the bugfix pipeline.
-- **Session independence**: The bugfix pipeline runs completely detached. User can close the AI CLI, open a new session later, and use this skill to check progress or stop the pipeline.
+- **Session independence**: In daemon mode, the bugfix pipeline runs completely detached. User can close the AI CLI, open a new session later, and use this skill to check progress or stop the pipeline.
 - **Single instance**: Only one bugfix pipeline can run at a time. The PID file prevents duplicates.
 - **Feature pipeline coexistence**: Bugfix and feature pipelines use separate state directories (`bugfix-state/` vs `state/`), so they can run simultaneously without conflict.
 - **State preservation**: Stopping and restarting the bugfix pipeline resumes from where it left off -- completed bugs are not re-fixed.
 - **Bug ordering**: Bugs are processed by severity (critical → high → medium → low), then by priority number within the same severity.
+- **Background mode traceability**: When daemon mode is chosen, the decision is logged to `.prizmkit/bugfix-pipeline-run.log` with timestamp, PID, and bug count for auditability.
 - **HANDOFF**: After pipeline completes all bugs, suggest running `prizmkit-retrospective` to capture lessons learned, or checking the fix reports in `.prizmkit/bugfix/`.

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

@@ -32,7 +32,7 @@ feature-workflow <requirements description>
    │
    ├── Phase 1: Plan → app-planner → feature-list.json
    │
-   ├── Phase 2: Launch → dev-pipeline-launcher → background pipeline
+   ├── Phase 2: Launch → dev-pipeline-launcher → pipeline execution
    │
    └── Phase 3: Monitor → track progress → report results
 ```
@@ -42,7 +42,7 @@ feature-workflow <requirements description>
 | Phase | Action | Result |
 |-------|--------|--------|
 | 1 | Call `app-planner` | `feature-list.json` with N features |
-| 2 | Call `dev-pipeline-launcher` | Background pipeline started |
+| 2 | Call `dev-pipeline-launcher` | Pipeline started (execution mode chosen by user via launcher) |
 | 3 | Monitor progress | Status updates, completion report |
 
 ### Why This Skill Exists
@@ -56,6 +56,13 @@ With this skill, users can:
 1. Say "Build a task management App" and walk away
 2. All planning + execution happens automatically
 
+### Branch Management
+
+The dev-pipeline handles branch management per-feature automatically:
+- Each feature 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-feature branches
+
 ---
 
 ## Input Modes
@@ -112,7 +119,7 @@ When user says "add features to existing project" or the project already has fea
 
 ## Phase 2: Launch
 
-**Goal**: Start the background development pipeline.
+**Goal**: Start the development pipeline.
 
 **STEPS**:
 
@@ -123,27 +130,20 @@ When user says "add features to existing project" or the project already has fea
      F-002: Task CRUD (medium complexity)
      F-003: Task categories (low complexity)
 
-   Pipeline will run in background. Close this session will NOT stop it.
    Proceed? (Y/n)
    ```
 
-2. **Ask execution mode**: Before invoking the launcher, present the choice:
-   - **(1) Background daemon (recommended)**: Runs detached, survives session closure.
-   - **(2) Foreground in session**: Runs in current session with visible output. Stops if session times out.
-   - **(3) Manual — show commands**: Display commands only, no execution.
-
-   Pass the chosen mode to `dev-pipeline-launcher`.
-
-3. **Invoke `dev-pipeline-launcher` skill**:
+2. **Invoke `dev-pipeline-launcher` skill**:
    - The launcher handles all prerequisites checks
-   - Starts `launch-daemon.sh` in background
-   - Returns PID and log file location
+   - The launcher presents execution mode choices to the user (foreground/background/manual)
+   - Do NOT duplicate execution mode selection here — let the launcher handle it
+   - Returns PID/status and log file location
 
-4. **Verify launch success**:
+3. **Verify launch success**:
    - Confirm pipeline is running
    - Record PID and log path for Phase 3
 
-**CHECKPOINT CP-FW-2**: Pipeline launched successfully in background.
+**CHECKPOINT CP-FW-2**: Pipeline launched successfully.
 
 ---
 
@@ -173,7 +173,7 @@ When user says "add features to existing project" or the project already has fea
 
 4. **Completion report** (when pipeline finishes all features):
    ```
-   ✅ Pipeline completed: 3/3 features
+   Pipeline completed: 3/3 features
 
    Summary:
    - F-001: User authentication → COMMITTED (feat: user auth)
@@ -190,9 +190,24 @@ When user says "add features to existing project" or the project already has fea
 
 ---
 
+## Resume — Interruption Recovery
+
+The workflow supports resuming by detecting existing state:
+
+| State Found | Resume From |
+|-------------|------------|
+| No `feature-list.json` | Phase 1: Plan |
+| `feature-list.json` exists, no pipeline state | Phase 2: Launch |
+| `feature-list.json` + pipeline state exists | Phase 3: Monitor (check status) |
+| All features completed | Report completion, suggest next steps |
+
+**Resume**: If `feature-list.json` exists, ask user: "Existing feature plan found with N features. Resume pipeline or re-plan?"
+
+---
+
 ## Interaction During Pipeline
 
-While the pipeline runs in background, the user can continue the conversation:
+While the pipeline runs, the user can continue the conversation:
 
 | User says | Action |
 |-----------|--------|
@@ -220,7 +235,7 @@ While the pipeline runs in background, the user can continue the conversation:
 | Skill | Relationship |
 |-------|-------------|
 | `app-planner` | **Called by Phase 1** — generates feature-list.json |
-| `dev-pipeline-launcher` | **Called by Phase 2** — starts background pipeline |
+| `dev-pipeline-launcher` | **Called by Phase 2** — starts pipeline (handles execution mode selection) |
 | `bug-planner` | **Alternative** — for bug fix workflows |
 | `bugfix-pipeline-launcher` | **Alternative** — for bug fix pipelines |
 | `refactor-workflow` | **Alternative** — for code restructuring |
@@ -233,9 +248,11 @@ While the pipeline runs in background, the user can continue the conversation:
 |-----------|-----------------|------------------|-------------------|
 | **Purpose** | New features (batch) | Single bug fix (interactive) | Code restructuring |
 | **Planning Skill** | `app-planner` | None (triage built-in) | None (analysis built-in) |
-| **Execution** | Background daemon | In-session, interactive | In-session |
+| **Branch** | Pipeline manages per-feature | `fix/<BUG_ID>-*` | `refactor/<slug>` |
+| **Execution** | Foreground or background daemon | In-session, interactive | In-session |
 | **Input** | Requirements description | Bug report / stack trace | Module / code target |
 | **Output** | Multiple `feat()` commits | Single `fix()` commit | Single `refactor()` commit |
+| **User verification** | No (pipeline automated) | Yes (Phase 5) | Yes (Phase 5) |
 | **Batch alternative** | (this is the batch flow) | `bug-planner` + `bugfix-pipeline-launcher` | N/A |
 
 ---
@@ -247,7 +264,7 @@ All internal asset paths use `${SKILL_DIR}` placeholder for cross-IDE compatibil
 ## Output
 
 - `feature-list.json` (Phase 1 artifact)
-- Background pipeline running (Phase 2)
+- Pipeline execution (Phase 2)
 - Progress updates (Phase 3)
 - Multiple git commits with `feat(<scope>):` prefix
 - Updated `.prizm-docs/` (via prizmkit-retrospective per feature)

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

@@ -1,12 +1,12 @@
 ---
 name: "refactor-workflow"
 tier: 1
-description: "End-to-end refactor workflow: analyze → plan → implement → review → commit. 5-phase behavior-preserving pipeline with mandatory test gates. 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'. (project)"
+description: "End-to-end refactor workflow: analyze → plan → implement → review → commit. 6-phase behavior-preserving pipeline with mandatory test gates. 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'. (project)"
 ---
 
 # PrizmKit Refactor Workflow
 
-End-to-end orchestration skill for code refactoring and optimization. Chains existing PrizmKit skills into a 5-phase behavior-preserving pipeline with mandatory test gates after each task.
+End-to-end orchestration skill for code refactoring and optimization. Chains existing PrizmKit skills into a 6-phase behavior-preserving pipeline with mandatory test gates after each task.
 
 ### When to Use
 - User says "refactor", "clean up code", "restructure", "extract module", "code refactoring", "optimize code structure"
@@ -23,22 +23,24 @@ End-to-end orchestration skill for code refactoring and optimization. Chains exi
 
 ```
 refactor-workflow
+  → Phase 0: Branch    → refactor/<slug> branch
   → Phase 1: Analyze   → refactor-analysis.md
   → Phase 2: Plan      → plan.md (including Tasks section)
   → Phase 3: Implement → (code)
   → Phase 4: Review    → (review report)
-  → Phase 5: Commit    → git commit
+  → Phase 5: Verify & Commit → git commit + merge decision
 ```
 
 ### Pipeline Phases
 
 | Phase | Name | Skill Used | Artifact |
 |-------|------|-----------|----------|
+| 0 | Branch Setup | git | → `refactor/<slug>` branch |
 | 1 | Analyze (Code Analysis) | Built-in code analysis + code reading | → `refactor-analysis.md` |
 | 2 | Plan (Refactor Plan & Tasks) | `/prizmkit-plan` | → `plan.md` (with Tasks section) |
 | 3 | Implement | `/prizmkit-implement` | (code changes) |
 | 4 | Code Review | `/prizmkit-code-review` | (review report) |
-| 5 | Commit | `/prizmkit-committer` | git commit |
+| 5 | Verify & Commit | `/prizmkit-committer` | git commit + merge |
 
 ### Key Principles
 
@@ -61,6 +63,26 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 ---
 
+## Phase 0: Branch Setup
+
+**Goal**: Create an isolated working branch to keep main clean.
+
+1. **Check current branch**:
+   ```bash
+   git branch --show-current
+   ```
+2. **If on `main` or a shared branch**: Create and switch to refactor branch:
+   ```bash
+   git checkout -b refactor/<refactor-slug>
+   ```
+   Example: `git checkout -b refactor/extract-auth-middleware`
+3. **If already on a refactor branch**: Confirm with user: "Continue on current branch `<branch-name>`, or create a new one?"
+4. **Record the original branch name** for later merge.
+
+**CHECKPOINT CP-RW-0**: On a dedicated refactor branch, not main/shared branch.
+
+---
+
 ## Phase 1: Analyze — Code Analysis
 
 **Goal**: Assess current code state, identify refactoring targets, establish baseline.
@@ -163,23 +185,44 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 ---
 
-## Phase 5: Commit
+## Phase 5: Verify, Commit & Merge
 
-**Goal**: Commit with refactor convention.
+**Goal**: Let user verify, commit with refactor convention, and merge back.
 
 **STEPS:**
 
-1. **Invoke `/prizmkit-retrospective`** (Job 1: structural sync only):
+1. **User verification** (optional):
+   - Ask user: "Refactoring complete and all tests pass. Would you like to verify before committing?"
+     - **(a) Run the app** — Start dev server for manual verification
+     - **(b) Run a specific command** — Specify a test or script
+     - **(c) Skip** — Proceed to commit (tests already pass)
+   - If user reports issues: return to Phase 3
+2. **Invoke `/prizmkit-retrospective`** (Job 1: structural sync only):
    - Update KEY_FILES/INTERFACES/DEPENDENCIES in affected `.prizm-docs/` files
    - Skip knowledge injection unless refactoring revealed a genuinely new pitfall (e.g. a non-obvious coupling)
    - If structural changes are significant (module split/merge), update L1 doc
    - Stage doc changes: `git add .prizm-docs/`
-2. **Invoke `/prizmkit-committer`**:
+3. **Invoke `/prizmkit-committer`**:
    - Commit message: `refactor(<scope>): <description>`
    - Include all refactored code + any test updates
    - Do NOT push
-
-**CHECKPOINT CP-RW-5**: Commit recorded with `refactor()` prefix.
+4. **Ask merge preference**:
+   ```
+   Refactoring committed on branch `refactor/<slug>`.
+   What would you like to do?
+   (a) Merge to <original-branch> and delete refactor branch
+   (b) Keep refactor branch (for PR review workflow)
+   (c) Decide later
+   ```
+5. **If (a)**:
+   ```bash
+   git checkout <original-branch>
+   git merge refactor/<slug>
+   git branch -d refactor/<slug>
+   ```
+6. **If (b)**: Inform user: "Branch `refactor/<slug>` retained. Create a PR when ready."
+
+**CHECKPOINT CP-RW-5**: Commit recorded with `refactor()` prefix. Merge decision made.
 
 ---
 
@@ -188,7 +231,7 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 For single-file refactoring (rename, extract method, <30 lines changed):
 
 ```
-Phase 1 (Analyze) → Phase 2 (Simplified Plan) → Phase 3 (Implement) → Phase 4 (Review) → Phase 5 (Commit)
+Phase 0 (Branch) → Phase 1 (Analyze) → Phase 2 (Simplified Plan) → Phase 3 (Implement) → Phase 4 (Review) → Phase 5 (Commit & Merge)
 ```
 
 Skip Phase 2's detailed planning process, but still generate a lightweight `plan.md` with a simplified Tasks section (typically 1-2 tasks).
@@ -206,11 +249,13 @@ Skip Phase 2's detailed planning process, but still generate a lightweight `plan
 - Single-task refactors typically have just one task in plan.md
 
 **Fast Path still requires:**
+- Refactor branch (Phase 0)
 - refactor-analysis.md (lightweight version with baseline)
 - plan.md (simplified, 1-2 tasks)
 - Full test suite run after implementation
 - Code review
 - `refactor(<scope>):` commit convention
+- Merge decision
 
 ---
 
@@ -218,15 +263,16 @@ Skip Phase 2's detailed planning process, but still generate a lightweight `plan
 
 The pipeline supports resuming from the last completed phase by detecting existing artifacts.
 
-**Detection logic**: Check `.prizmkit/refactor/<slug>/` for:
+**Detection logic**: Check `.prizmkit/refactor/<slug>/` and git branch state:
 
 | Artifact Found | Resume From |
 |---------------|------------|
-| (nothing) | Phase 1: Analyze |
+| (nothing) | Phase 0: Branch Setup |
+| On `refactor/<slug>` branch, no artifacts | Phase 1: Analyze |
 | `refactor-analysis.md` only | Phase 2: Plan |
 | `refactor-analysis.md` + `plan.md` | Phase 3: Implement |
 | All docs + code changes exist | Phase 4: Review |
-| All docs + review passed | Phase 5: Commit |
+| All docs + review passed | Phase 5: Verify & Commit |
 
 **Resume**: If `<slug>` matches an existing `.prizmkit/refactor/<slug>/` directory, resume instead of starting fresh.
 
@@ -244,6 +290,7 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | Review fails after 2 rounds | Escalate with review findings |
 | Refactoring creates circular dependency | STOP, revise plan |
 | Performance regression detected | STOP, investigate, revise approach |
+| Branch conflict during merge | Show conflict, ask user to resolve or keep branch |
 
 ---
 
@@ -259,23 +306,24 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | `/prizmkit-retrospective` | Phase 5: structural sync before commit (Job 1 only, skip knowledge injection unless new pitfall) |
 | `feature-workflow` | Handoff target when new behavior is needed |
 | `/prizmkit-specify` | NOT used (no user stories for refactoring) |
-| `/prizmkit-analyze` | NOT used (no spec ↔ plan consistency needed) |
+| `/prizmkit-analyze` | NOT used (no spec <-> plan consistency needed) |
 
 ---
 
 ## Comparison with Feature and Bug Fix Pipelines
 
-| Dimension | Feature Workflow | Refactor Workflow | Bug Fix Pipeline |
+| Dimension | Feature Workflow | Refactor Workflow | Bug Fix Workflow |
 |-----------|-----------------|-------------------|------------------|
 | Input | Natural language requirement | Module/code target | Bug description |
-| Pipeline Phases | 6 (Fast: 4) | 5 (Fast: 3) | 5 (Fast: 3) |
-| Phase 1 | Specify (spec.md) | Analyze (refactor-analysis.md) | Triage (fix-plan.md) |
+| Branch | Pipeline manages per-feature | `refactor/<slug>` | `fix/<BUG_ID>-*` |
+| Pipeline Phases | 3 (plan → launch → monitor) | 6 (branch → analyze → plan → implement → review → commit) | 7 (branch → triage → reproduce → fix → review → verify → commit) |
+| Phase 1 | Plan (app-planner) | Analyze (refactor-analysis.md) | Triage (fix-plan.md) |
 | Artifact Path | `.prizmkit/specs/<slug>/` | `.prizmkit/refactor/<slug>/` | `.prizmkit/bugfix/<id>/` |
 | Commit Prefix | `feat(<scope>):` | `refactor(<scope>):` | `fix(<scope>):` |
-| REGISTRY Update | ✅ | ❌ | ❌ |
 | Test Strategy | TDD per task | Full suite after EVERY task | Reproduction test |
-| Scope Guard | N/A | ✅ (enforced) | N/A |
-| Behavior Change | ✅ Expected | ❌ Forbidden | ✅ Fix behavior |
+| Scope Guard | N/A | Enforced | N/A |
+| Behavior Change | Expected | Forbidden | Fix behavior |
+| User Verification | No (pipeline) | Yes (Phase 5) | Yes (Phase 5) |
 
 ## Output
 
@@ -283,5 +331,5 @@ The pipeline supports resuming from the last completed phase by detecting existi
 - `plan.md` with Tasks section (Phase 2 artifact)
 - Refactored implementation code (Phase 3)
 - Code review report (Phase 4, conversation only)
-- Git commit with `refactor(<scope>):` prefix (Phase 5)
+- Git commit with `refactor(<scope>):` prefix on dedicated refactor branch (Phase 5)
 - Updated `.prizm-docs/` (if applicable)

package/package.json

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