prizmkit 1.1.110 → 1.1.112

package/bundled/dev-pipeline/templates/bootstrap-tier3.md

@@ -12,7 +12,7 @@ You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATU
 
 **CRITICAL**: You MUST NOT exit until ALL work is complete and committed. When you spawn Critic or Reviewer agents, wait for each to finish (run_in_background=false). Do NOT spawn agents in background and exit — that kills the session.
 
-**Tier 3 — Orchestrator + Critic/Reviewer**: For complex features, the main orchestrator handles context, planning, and implementation directly. Critic challenges the plan and Reviewer reviews. Do not spawn a top-level Dev implementation agent.
+**Tier 3 — Orchestrator + Critic**: For complex features, the main orchestrator handles context, planning, and implementation directly. Critic challenges the plan. Do not spawn top-level Dev or Reviewer subagents; code review runs later through `/prizmkit-code-review`.
 
 **Agent spawn failure policy (all Agent tool calls)**:
 - If spawning Reviewer or Critic fails with team/config/lock errors, retry at most once.
@@ -180,23 +180,16 @@ Before proceeding past CP-1, verify:
 
 **CP-1**: Both spec.md and plan.md exist.
 
-### Phase 3: Analyze — Reviewer Agent
+### Phase 3: Plan Self-Check — Orchestrator Direct
 
-Spawn Reviewer agent (Agent tool, subagent_type="prizm-dev-team-reviewer", mode="plan", run_in_background=false, isolation=default/no worktree). Do not request worktree isolation; this prevents AI tool-created `.claude/worktrees/...` subagent worktrees. PrizmKit pipeline-managed linked git worktrees under `.prizmkit/state/worktrees/...` are separate and controlled by `USE_WORKTREE`.
+Do not spawn a top-level Reviewer subagent for planning analysis. Perform a bounded self-check before implementation:
 
-Spawn failure cap: for team/config/lock errors, retry at most once for this Reviewer spawn. If the second attempt fails, do not poll for report artifacts; fix/check the plan inline or write `failure-log.md` before stopping for recovery.
+1. Re-read only `context-snapshot.md`, `spec.md`, and `plan.md`.
+2. Cross-check spec.md and plan.md Tasks against the feature description and acceptance criteria.
+3. Verify the plan references the File Manifest and avoids unrelated work.
+4. If you find CRITICAL issues, fix ONLY those issues in spec.md/plan.md before continuing.
 
-Prompt:
-> "Read {{REVIEWER_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
-> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has TRAPS/RULES, Section 4 has file manifest.
-> 2. Cross-check `spec.md` and `plan.md` (including Tasks section) for consistency.
-> 3. Before flagging CRITICAL or HIGH issues, read the relevant source files listed in the File Manifest to verify.
-> Report: CRITICAL, HIGH, MEDIUM issues found (or 'No issues found')."
-
-Wait for Reviewer to return.
-- If CRITICAL issues found: fix them yourself — read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full project context. Fix ONLY the listed CRITICAL issues in spec.md/plan.md. Then re-run analyze (max 1 round).
-
-**CP-2**: No CRITICAL issues.
+**CP-2**: Plan self-check complete; no CRITICAL plan issues remain.
 
 {{IF_CRITIC_ENABLED}}
 ### Phase 3.5: Plan Challenge — Critic Agent(s)
@@ -495,12 +488,10 @@ If verification fails, log the failure details but continue to commit. Failures
 
 ### Phase 6: Retrospective & Commit (SINGLE COMMIT) — DO NOT SKIP
 
-**Bug Fix Documentation Policy**:
-- DEFAULT: Run `/prizmkit-retrospective` with structural sync only (update file counts, interfaces, dependencies). Skip knowledge injection.
-- UPDATE DOCS (run full retrospective — Job 1 + Job 2) when bug fix causes: interface signature changes, dependency additions/removals, observable behavior changes to existing features, or newly discovered TRAPs.
-- Simple bugs: No new spec.md/plan.md needed. Use fast path.
-- Complex bugs (multi-module, cascading): Use `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/<BUG_ID>/`.
-- Commit prefix: `fix(<scope>):` (not `feat:`).
+**Feature Documentation Policy**:
+- Run `/prizmkit-retrospective` before commit to update `.prizmkit/prizm-docs/` with durable structural knowledge from this feature.
+- Capture architecture knowledge when the feature adds interfaces, dependencies, observable behavior, modules, or durable TRAPS/RULES/DECISIONS.
+- Commit prefix: `feat({{FEATURE_ID}}):`.
 
 **6a.** Check if feature already committed by inspecting recent git history for `{{FEATURE_ID}}`:
 ```bash
@@ -515,7 +506,6 @@ git log --oneline
 - **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
 - Stage doc changes: `git add .prizmkit/prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
-- **For bug-fix sessions**: structural sync (Job 1) by default. Run knowledge injection (Job 2) when the fix causes interface signature changes, dependency additions/removals, observable behavior changes, or reveals new TRAPs
 
 **6c.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):
 ```bash
@@ -566,7 +556,6 @@ Rules for writing completion notes:
 | Feature Artifacts Dir | `.prizmkit/specs/{{FEATURE_SLUG}}/` |
 | Context Snapshot | `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` |
 | Team Config | `{{TEAM_CONFIG_PATH}}` |
-| Reviewer Agent Def | {{REVIEWER_SUBAGENT_PATH}} |
 {{IF_CRITIC_ENABLED}}
 | Critic Agent Def | {{CRITIC_SUBAGENT_PATH}} |
 {{END_IF_CRITIC_ENABLED}}
@@ -592,10 +581,10 @@ If you encounter an unrecoverable error, context overflow, or are about to exit
 
 ## Reminders
 
-- Tier 3: orchestrator implements directly; Critic challenges plan; Reviewer reviews
+- Tier 3: orchestrator implements directly; Critic challenges plan; `/prizmkit-code-review` handles review later
 - context-snapshot.md is append-only: orchestrator writes Sections 1-4 + Implementation Log, Reviewer appends Review Notes
 - Gate checks enforce Implementation Log and Review Notes are written before proceeding
-- Do NOT use `run_in_background=true` when spawning Critic or Reviewer agents
+- Do NOT use `run_in_background=true` when spawning Critic agents
 - Commit phase must use `/prizmkit-committer`; do NOT replace with manual git commit commands
 - **NEVER delete, modify, or touch any file under `.prizmkit/state/`** — those are pipeline runtime files managed by the runner
 - NEVER run `rm -rf`, `git clean`, or any destructive filesystem operations

package/bundled/dev-pipeline/templates/bug-fix-list-schema.json

@@ -75,7 +75,15 @@
               "medium",
               "low"
             ],
-            "description": "Fix priority. Pipeline processes high before medium before low; within same level, array order determines sequence. Both critical and high severity map to high priority."
+            "description": "Fix priority. Planner should order bugs by severity/priority before runtime execution. Runtime preserves stable list order subject to dependency constraints. Both critical and high severity map to high priority."
+          },
+          "dependencies": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^B-\\d{3}$"
+            },
+            "description": "IDs of bugs that must be completed before this one"
           },
           "error_source": {
             "type": "object",

package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md

@@ -11,7 +11,7 @@
 
 You are the **bug fix session agent**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}".
 
-**CRITICAL**: You MUST NOT exit until ALL work is complete and committed.
+**CRITICAL**: You MUST NOT exit until ALL automated work is complete and committed, unless a fresh manual/hybrid verification gate requires stopping as `partial` before commit.
 
 **SUBAGENT LIFECYCLE**: Any normal work subagent must be awaited with `run_in_background=false`. Do not spawn persistent background subagents for headless recovery.
 
@@ -177,7 +177,7 @@ After implement completes, verify:
 
 ### Phase 3: Review
 
-If `FAST_PATH=true` (≤ 2 tasks, obvious root cause), skip this phase entirely.
+If `FAST_PATH=true` (≤ 2 tasks, obvious root cause), skip this phase entirely and mark checkpoint step `prizmkit-code-review` as `skipped` before continuing.
 
 Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/`:
 - The skill runs an internal review-fix loop (Reviewer → filter → orchestrator fix, max 3 rounds) and writes `review-report.md`
@@ -209,8 +209,10 @@ Read `review-report.md` and check the Verdict:
 
 {{IF_VERIFICATION_MANUAL_OR_HYBRID}}
 **MANUAL VERIFICATION GATE**:
-- After automated review passes, write session-status.json with status="partial", resume_from_phase=4
-- Set bug status to `verifying` and STOP — manual UAT required before commit
+- Fresh manual/hybrid bugfix sessions stop after automated review and before commit.
+- Write session-status.json with status="partial", resume_from_phase=4, and STOP — manual UAT is required before commit.
+- Recovery/retry/continuation sessions may substitute automated verification for manual/hybrid UAT only when evidence is documented in fix-report.md and session-status.json.
+- Do not write `verifying` to the external bug-list status field; fine-grained verification is session/checkpoint metadata, while the external list status remains one of `pending`, `in_progress`, `completed`, `failed`, `skipped`, or `needs_info`.
 {{END_IF_VERIFICATION_MANUAL_OR_HYBRID}}
 
 ---
@@ -223,10 +225,11 @@ Read `review-report.md` and check the Verdict:
 
 **a.** If a new pitfall was discovered (not previously in TRAPS):
    - Update the affected module's TRAPS section in `.prizmkit/prizm-docs/`
-   - Format: `- TRAP: <description> | FIX: <solution> | DATE: YYYY-MM-DD`
+   - Format: `- [LOW|HIGH|CRITICAL] <description> | FIX: <approach>`
+   - Do not add dates.
 
 **b.** Run `/prizmkit-retrospective` following the policy above.
-   Stage doc changes: `git add .prizmkit/prizm-docs/`
+   Stage doc changes explicitly when `.prizmkit/prizm-docs/` changed.
 
 **c.** Stage all changed files explicitly (NEVER use `git add -A` or `git add .`):
 ```bash
@@ -234,7 +237,7 @@ git add <specific-files-modified>
 git add .prizmkit/prizm-docs/
 ```
 
-**d.** Run `/prizmkit-committer --headless`:
+**d.** Run `/prizmkit-committer`:
    - Commit message prefix: `fix({{FIX_SCOPE}}): {{BUG_TITLE}}`
    - Include both fix code and reproduction test
    - Do NOT push
@@ -259,7 +262,7 @@ The fix-report.md MUST contain:
 - **Knowledge Captured**: TRAPS updated (if any), prevention recommendation
 - **Acceptance Criteria Verification**: checklist with pass/fail for each criterion
 
-**Checkpoint update**: Set steps `prizmkit-committer` and `bug-report` to `"completed"`.
+- **Checkpoint update**: Set `prizmkit-retrospective`, `prizmkit-committer`, and `bug-report` to `completed` as each finishes.
 
 ---
 

package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md

@@ -7,25 +7,22 @@
 - **Refactor Type**: {{REFACTOR_TYPE}}
 - **Priority**: {{PRIORITY}}
 - **Complexity**: {{COMPLEXITY}}
+- **Pipeline Mode**: {{PIPELINE_MODE}}
 
 ## Your Mission
 
 You are the **refactor session orchestrator**. Execute Refactor {{REFACTOR_ID}}: "{{REFACTOR_TITLE}}".
 
-**CRITICAL SESSION LIFECYCLE RULE**: You MUST NOT exit until ALL work is complete and session-status.json is written. When you spawn normal work subagents, you MUST **wait for each to finish** (run_in_background=false) before proceeding. Do NOT spawn a work agent in the background and exit — that kills the session.
+**CRITICAL SESSION LIFECYCLE RULE**: You MUST NOT exit until all refactor work is complete, checkpoint state is updated, and session-status.json is written.
 
-**NON-INTERACTIVE MODE**: You are running in headless non-interactive mode. There is NO human on the other end. NEVER ask for user confirmation, NEVER wait for user input, NEVER use interactive prompts (e.g. "Would you like me to…"). If a skill has an interactive step (e.g. offer remediation, ask for approval), skip it and proceed autonomously. Make decisions based on the data available and move forward.
+**NON-INTERACTIVE MODE**: You are running in headless non-interactive mode. There is NO human on the other end. NEVER ask for user confirmation, NEVER wait for user input, and NEVER use interactive prompts. Resolve uncertainty from existing code, project docs, and conservative behavior-preserving defaults.
 
-**NORMAL-PATH TEAM REQUIREMENT**: Use the `prizm-dev-team` agents (Dev + Reviewer) for implementation and review. You are the orchestrator — handle coordination, planning, and commit phases directly. If a required agent cannot be spawned after the bounded retry policy below, follow the documented recovery exception instead of looping forever.
+**ORCHESTRATOR-DIRECT RULE**: Do not spawn top-level Dev or Reviewer subagents. The main orchestrator plans, implements via `/prizmkit-implement`, and runs `/prizmkit-code-review` directly.
 
 **REFACTOR DOCUMENTATION POLICY**:
-- **DEFAULT**: Run `/prizmkit-retrospective` with full sync (Job 1 + Job 2), because refactoring changes code structure and interfaces.
-- **SKIP Job 2** only if the refactor is a pure rename with no interface changes.
-- Commit with `refactor(<scope>):` prefix, NOT `feat:` or `fix:`
-
-### Team Definition Reference
-
-- **Team config**: `{{TEAM_CONFIG_PATH}}`
+- Default: run `/prizmkit-retrospective` with full sync because refactoring changes structure and interfaces.
+- Skip architecture knowledge injection only for a pure rename with no interface or dependency changes.
+- Commit with `refactor(<scope>):`, not `feat:` or `fix:`.
 
 ### Refactor Description
 
@@ -43,11 +40,7 @@ You are the **refactor session orchestrator**. Execute Refactor {{REFACTOR_ID}}:
 
 ### Behavior Preservation
 
-- **Strategy**: {{BEHAVIOR_STRATEGY}}
-- **Existing Tests**:
-{{EXISTING_TESTS}}
-- **New Tests Needed**:
-{{NEW_TESTS_NEEDED}}
+{{BEHAVIOR_PRESERVATION}}
 
 ### Acceptance Criteria
 
@@ -61,268 +54,215 @@ You are the **refactor session orchestrator**. Execute Refactor {{REFACTOR_ID}}:
 
 {{GLOBAL_CONTEXT}}
 
-
 ## Refactor Artifacts Directory
 
-**ALWAYS** use per-refactor subdirectory `.prizmkit/refactor/{{REFACTOR_ID}}/`:
+Always use per-refactor subdirectory `.prizmkit/refactor/{{REFACTOR_ID}}/`:
 
 ```
 .prizmkit/refactor/{{REFACTOR_ID}}/
-├── spec.md              ← /prizmkit-plan output (goals, scope, behavior preservation)
-├── plan.md              ← /prizmkit-plan output (change approach, tasks)
-└── refactor-report.md   ← Phase 5 output (generated after commit)
+├── spec.md
+├── plan.md
+├── review-report.md
+├── refactor-report.md
+└── completion-summary.json
 ```
 
-## Execution Instructions
-
-**YOU are the orchestrator. Execute each phase by spawning the appropriate team agent with run_in_background=false.**
-
-**Agent spawn failure policy (all Agent tool calls)**:
-- If spawning Dev or Reviewer fails with team/config/lock errors, retry at most once.
-- If the second attempt fails, do not keep spawning variants and do not enter artifact polling for Implementation Log, review-report, or refactor-report markers.
-- Recovery exception: complete remaining refactor work directly in the orchestrator only when the action is safe and bounded; otherwise write `failure-log.md` with the spawn error and last observable state before stopping for recovery.
-- Any recovery exception must be recorded in the required report or session status so downstream runs know the normal team path was unavailable.
-- Apply the same cap to any re-spawn for report repair or resume prompts; do not burn multiple minutes on identical team/config/lock failures.
-
 {{CHECKPOINT_SYSTEM}}
 
-### Step 1: Initialize
-
-#### Agent Setup
+## Execution
 
-Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
-- Dev: `{{DEV_SUBAGENT_PATH}}`
-- Reviewer: `{{REVIEWER_SUBAGENT_PATH}}`
+### Phase 0: Initialize
 
 Create refactor artifacts directory:
+
 ```bash
 {{RUNTIME_HELPER_CMD}} artifact ensure-dir .prizmkit/refactor/{{REFACTOR_ID}}
 ```
 
-### Step 2: Pipeline Phases
+**Checkpoint update**: set step `prizmkit-init` to `completed` in `{{CHECKPOINT_PATH}}`.
 
-#### Phase 1: Plan — Specification & Plan Generation
+---
 
-**Goal**: Generate spec.md and plan.md with behavior-preserving task breakdown.
+### Phase 1: Plan — Specification & Plan Generation
 
-Run `/prizmkit-plan` with `artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/`:
-- Description: "{{REFACTOR_TITLE}} — {{REFACTOR_DESCRIPTION}}"
-- The spec.md MUST include:
-  - Goals with acceptance criteria (from the acceptance criteria above)
-  - Scope (files and modules from above)
-  - Behavior Preservation section (strategy: {{BEHAVIOR_STRATEGY}}, existing tests, what must not change)
-- The plan.md MUST include:
-  - Change approach with behavior preservation strategy
-  - Tasks ordered by safety: safe renames first → extractions → structural changes
-  - Every task ends with "run test suite to verify behavior preserved"
-  - Rollback strategy
+Run `/prizmkit-plan` with `artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/`.
 
-Resolve uncertain refactor details from the refactor description, existing code, and conservative existing-project patterns.
+The generated `spec.md` MUST include:
+- goals with acceptance criteria;
+- scope files/modules;
+- behavior preservation strategy;
+- interfaces or observable behavior that must not change.
 
-{{IF_BROWSER_INTERACTION}}
+The generated `plan.md` MUST include:
+- behavior-preserving task order;
+- test strategy before, during, and after refactor;
+- rollback strategy;
+- explicit risks and mitigations.
 
-#### Browser Behavior Preservation Protocol
-
-The refactor may affect UI behavior. Use this single browser protocol for planning, implementation, review, and final reporting:
+Resolve uncertain refactor details from existing code and conservative existing-project patterns.
 
-{{IF_BROWSER_TOOL_AUTO}}
-- **Browser Tool**: Auto-select at runtime based on dev server and feature complexity.
-{{END_IF_BROWSER_TOOL_AUTO}}
+{{IF_BROWSER_INTERACTION}}
 
-{{IF_BROWSER_TOOL_PLAYWRIGHT}}
-- **Browser Tool**: playwright-cli — local isolated browser instance for dev server verification.
-{{END_IF_BROWSER_TOOL_PLAYWRIGHT}}
+#### Browser Behavior Preservation Protocol
 
-{{IF_BROWSER_TOOL_OPENCLI}}
-- **Browser Tool**: opencli — Chrome session with existing login for OAuth/third-party integrations.
-{{END_IF_BROWSER_TOOL_OPENCLI}}
+The refactor may affect UI behavior. Browser verification is a mandatory attempt by default, but it blocks only when the task explicitly marks browser verification as blocking.
 
-**Verification Goals**:
+**Browser Verification Goals**:
 {{BROWSER_VERIFY_STEPS}}
 
-Evidence must cover affected UI render, primary user interactions, behavior-sensitive workflows, tool used, and whether verification belongs in implementation, review, or both.
+If `DEV_PORT` is unknown, discover it from project config; do not guess port 3000.
 
 {{END_IF_BROWSER_INTERACTION}}
 
-- **CP-RF-1**: Both `spec.md` and `plan.md` exist in `.prizmkit/refactor/{{REFACTOR_ID}}/`
-- **Checkpoint update**: set step `prizmkit-plan` to `"completed"` in `{{CHECKPOINT_PATH}}`
+**Checkpoint update**: set step `prizmkit-plan` to `completed` in `{{CHECKPOINT_PATH}}`.
 
 ---
 
-#### Phase 2: Implement — Behavior-Preserving Refactoring
+{{IF_CRITIC_ENABLED}}
+### Phase 2: Critic — Behavior Preservation Review
 
-**Goal**: Execute all tasks from plan.md while preserving existing behavior.
+Challenge the plan before implementation. Focus on:
+- behavior preservation gaps;
+- unsafe task ordering;
+- missing rollback strategy;
+- insufficient test evidence.
 
-- Spawn Dev agent (Agent tool, subagent_type="prizm-dev-team-dev", run_in_background=false)
-  Apply the all-agent spawn failure policy above for this Dev spawn: for team/config/lock errors, retry at most once; if the second attempt fails, do not poll for `## Implementation Log`; use the bounded recovery exception.
-  Prompt: "Read {{DEV_SUBAGENT_PATH}}. For refactor {{REFACTOR_ID}} ('{{REFACTOR_TITLE}}'):
-  1. Read `.prizmkit/refactor/{{REFACTOR_ID}}/spec.md` and `.prizmkit/refactor/{{REFACTOR_ID}}/plan.md`
-  2. Read `.prizmkit/prizm-docs/` for affected modules (TRAPS, RULES, PATTERNS)
-  3. Before making any changes, run the existing test suite to establish a green baseline
-  4. Run `/prizmkit-implement` with `artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/` — this handles the full implementation cycle:
-     - Reads plan.md Tasks section
-     - Implements task-by-task, marking each `[x]` immediately
-     - Runs tests after EVERY task — all tests MUST pass (behavior preservation)
-     - If tests fail: revert the task, analyze why, try alternative approach
-     - Writes '## Implementation Log' to context-snapshot.md (or equivalent)
-  5. Do NOT change behavior — only improve structure
+Write the critic result into `.prizmkit/refactor/{{REFACTOR_ID}}/context-snapshot.md` or the plan notes, then update any unsafe plan details before implementation.
 
-{{IF_BROWSER_INTERACTION}}
+**Checkpoint update**: set step `critic-plan-review` to `completed` in `{{CHECKPOINT_PATH}}`.
 
-  6. Apply the Browser Behavior Preservation Protocol above after major refactor tasks and document evidence in implementation notes.
+---
 
-{{END_IF_BROWSER_INTERACTION}}
+{{END_IF_CRITIC_ENABLED}}
+### Phase 3: Implement — Behavior-Preserving Refactoring
 
-  7. If the refactor involves multiple files: update durable checkpoints/artifacts at the midpoint, minimize output, and rely on runner continuation if context overflow occurs.
-  8. After all tasks complete, run the full test suite one final time
-  "
-- **Wait for Dev to return**
-- If Dev reports test failures that cannot be resolved after 3 attempts: escalate, write status="failed"
-- **CP-RF-2**: All tasks completed, all tests green
-- **Checkpoint update**: set step `prizmkit-implement` to `"completed"` in `{{CHECKPOINT_PATH}}`
+Run `/prizmkit-implement` with `artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/`.
 
----
+Implementation requirements:
+1. Establish a green baseline before changes when tests exist.
+2. Execute plan tasks in order.
+3. Preserve existing behavior; do not mix unrelated feature work or bug fixes into the refactor.
+4. Run focused tests after each risky task and full relevant tests before review.
+5. Mark each completed task `[x]` in plan.md.
 
-#### Phase 3: Review — Code Review & Behavior Verification
+{{IF_BROWSER_INTERACTION}}
+Apply the browser behavior preservation protocol where UI behavior can be affected. Document evidence in implementation notes.
+{{END_IF_BROWSER_INTERACTION}}
 
-**Goal**: Verify refactoring quality and behavior preservation.
+**Checkpoint update**: set step `prizmkit-implement` to `completed` in `{{CHECKPOINT_PATH}}`.
 
-- Spawn Reviewer agent (Agent tool, subagent_type="prizm-dev-team-reviewer", run_in_background=false)
-  Apply the all-agent spawn failure policy above for this Reviewer spawn.
-  Prompt: "Read {{REVIEWER_SUBAGENT_PATH}}. For refactor {{REFACTOR_ID}}:
-  1. Read `.prizmkit/refactor/{{REFACTOR_ID}}/spec.md` for goals and behavior preservation contracts
-  2. Read `.prizmkit/refactor/{{REFACTOR_ID}}/plan.md` for architecture decisions and completed tasks
-  3. Run `/prizmkit-code-review` with artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/. The skill runs an internal review-fix loop (Reviewer → filter → orchestrator fix, max 3 rounds) and writes review-report.md.
-  4. Run full test suite and verify ALL tests pass
+---
 
-{{IF_BROWSER_INTERACTION}}
+### Phase 4: Review — Code Review & Behavior Verification
 
-  5. Verify the Browser Behavior Preservation Protocol evidence and document findings in `review-report.md`.
+Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/` directly from the main orchestrator.
 
-{{END_IF_BROWSER_INTERACTION}}
+Review requirements:
+- verify refactor quality against spec.md and plan.md;
+- verify behavior preservation evidence;
+- run or confirm relevant tests;
+- write `.prizmkit/refactor/{{REFACTOR_ID}}/review-report.md` with `## Verdict`.
+
+If the report is missing after one bounded status check, write `failure-log.md` and either perform a safe inline fallback review or stop with a clear recovery failure.
 
-  6. review-report.md will be written to .prizmkit/refactor/{{REFACTOR_ID}}/ by prizmkit-code-review
-  7. Report: verdict (PASS/NEEDS_FIXES), number of rounds, findings fixed/rejected
-  "
-- **Wait for Reviewer to return**
-- **Gate Check — Review Report**:
-  After Reviewer returns, verify the review report contains a verdict:
-  ```bash
-  {{RUNTIME_HELPER_CMD}} text contains .prizmkit/refactor/{{REFACTOR_ID}}/review-report.md --pattern "## Verdict"
-  ```
-  If GATE:MISSING:
-  - Do not enter an unbounded report-repair loop and do not repeatedly re-spawn Reviewer.
-  - Perform one bounded status check; retry at most once: inspect the Reviewer output, `review-report.md` path, and any internal Reviewer agent spawn messages from `/prizmkit-code-review`.
-  - If the missing report is caused by team/config/lock errors from the Reviewer or internal Reviewer agent spawn, retry the Reviewer agent at most once only if it appears transient.
-  - If the report is still missing after that single check/retry, write `.prizmkit/refactor/{{REFACTOR_ID}}/failure-log.md` with the spawn/skill error and last observable state, then either perform a safe inline fallback review (spec/plan/diff/tests → write `review-report.md` with `## Verdict`) or stop with a clear recovery failure.
-
-Read `review-report.md` and check the Verdict:
-- `PASS` → proceed to next phase
-- `NEEDS_FIXES` → log remaining findings and proceed (do not retry externally)
-- **CP-RF-3**: Code review complete, tests pass, behavior preserved
-- **Checkpoint update**: set step `prizmkit-code-review` to `"completed"` in `{{CHECKPOINT_PATH}}`
+**Checkpoint update**: set step `prizmkit-code-review` to `completed` in `{{CHECKPOINT_PATH}}`.
 
 ---
 
-#### Phase 4: Commit & Report
+{{IF_BROWSER_INTERACTION}}
+### Phase 5: Browser Verification
 
-**Goal**: Commit the refactor, update docs, generate report.
+Attempt browser verification for affected UI behavior. If no usable browser tool/server/port can be found and browser verification is non-blocking, mark browser verification `skipped` and continue. If explicit policy marks browser verification as blocking, mark it `failed` and write `failure-log.md`.
 
-**This phase is executed by YOU (the orchestrator), NOT a subagent.**
+Record tool choice, URL, steps, screenshot path if available, result, and cleanup status in `.prizmkit/refactor/{{REFACTOR_ID}}/context-snapshot.md`.
 
-1. Run `/prizmkit-retrospective` (full sync — Job 1 + Job 2) to update `.prizmkit/prizm-docs/` with structural changes
+**Checkpoint update**: set step `browser-verification` to `completed`, `skipped`, or `failed` according to the evidence.
 
-2. Run `/prizmkit-committer --headless` with:
-   - Commit message: `refactor({{REFACTOR_ID}}): {{REFACTOR_TITLE}}`
-   - Include all refactored files and any new/updated tests
-   - Do NOT push (user will push manually)
+---
 
-3. Write the refactor report to `.prizmkit/refactor/{{REFACTOR_ID}}/refactor-report.md`
+{{END_IF_BROWSER_INTERACTION}}
+### Phase 6: Commit, Report & Completion Summary
 
-   The refactor-report.md MUST contain these sections:
-   - Refactor Summary (ID, title, type, status, phases completed)
-   - What Changed (files modified, structural changes made, diff summary)
-   - Behavior Verification (test suite results before/after, specific tests exercised)
+Run `/prizmkit-retrospective` using the current working tree and staged changes as input context. Do not rely only on `git diff --cached`.
 
-{{IF_BROWSER_INTERACTION}}
+Stage changed files explicitly; never use `git add -A` or `git add .`.
 
-   - Browser Verification (UI flows tested, tools used, any manual verification performed)
+Run `/prizmkit-committer` with commit prefix:
 
-{{END_IF_BROWSER_INTERACTION}}
+```text
+refactor({{REFACTOR_ID}}): {{REFACTOR_TITLE}}
+```
 
-   - Code Quality Metrics (if measurable: files consolidated, duplication reduced, etc.)
-   - Acceptance Criteria Verification (checklist with pass/fail for each criterion)
+Do not push.
 
-4. Write completion summary for downstream dependency context:
+Write `.prizmkit/refactor/{{REFACTOR_ID}}/refactor-report.md` with:
+- refactor summary;
+- files/modules changed;
+- behavior-preservation evidence before/after;
+- review findings;
+- browser evidence when applicable;
+- acceptance criteria checklist.
 
-   Write `.prizmkit/refactor/{{REFACTOR_ID}}/completion-summary.json` — this is NOT committed to git. The pipeline runner reads it to propagate context to dependent refactors.
-   ```json
-   {
-     "completion_notes": [
-       "<each item: one key structural change that downstream refactors may need to know>",
-       "Example: Extracted shared validation logic into src/utils/validation.ts",
-       "Example: Renamed UserService → AuthService, moved from src/services/ to src/auth/",
-       "Example: Decoupled payment module from user module via PaymentGateway interface"
-     ]
-   }
-   ```
-   Rules: focus on structural changes, new module boundaries, renamed/moved files, changed interfaces. 3-8 notes, each under 120 chars.
+Write `.prizmkit/refactor/{{REFACTOR_ID}}/completion-summary.json` for downstream refactor context:
 
-- **CP-RF-4**: Commit recorded, refactor-report.md written, .prizmkit/prizm-docs/ updated
-- **Checkpoint update**: set steps `prizmkit-committer` and `refactor-report` to `"completed"` in `{{CHECKPOINT_PATH}}`
+```json
+{
+  "completion_notes": [
+    "<key structural change, moved/renamed interface, or new module boundary>"
+  ]
+}
+```
+
+**Checkpoint update**: set `prizmkit-retrospective`, `prizmkit-committer`, `refactor-report`, and `completion-summary` to `completed` as each finishes.
 
-### Step 3: Report Session Status
+---
 
-**CRITICAL**: Before this session ends, you MUST write the session status file.
+### Final: Report Session Status
 
-Write to: `{{SESSION_STATUS_PATH}}`
+Before exiting, write `{{SESSION_STATUS_PATH}}`:
 
 ```json
 {
   "session_id": "{{SESSION_ID}}",
   "refactor_id": "{{REFACTOR_ID}}",
   "status": "<success|partial|failed>",
-  "completed_phases": [1, 2, 3, 4],
-  "current_phase": 4,
-  "checkpoint_reached": "CP-RF-4",
+  "completed_phases": [1, 2, 3, 4, 5, 6],
+  "current_phase": 6,
+  "checkpoint_reached": "completion-summary",
   "errors": [],
   "can_resume": false,
   "resume_from_phase": null,
   "artifacts": {
     "spec_path": ".prizmkit/refactor/{{REFACTOR_ID}}/spec.md",
     "plan_path": ".prizmkit/refactor/{{REFACTOR_ID}}/plan.md",
-    "report_path": ".prizmkit/refactor/{{REFACTOR_ID}}/refactor-report.md"
+    "review_report_path": ".prizmkit/refactor/{{REFACTOR_ID}}/review-report.md",
+    "report_path": ".prizmkit/refactor/{{REFACTOR_ID}}/refactor-report.md",
+    "completion_summary_path": ".prizmkit/refactor/{{REFACTOR_ID}}/completion-summary.json"
   },
   "git_commit": "<commit hash>",
-  "behavior_preserved": true,
-  "timestamp": "{{TIMESTAMP}}"
+  "behavior_preserved": true
 }
 ```
 
-**Status values**: `success` (all phases done) | `partial` (can resume) | `failed` (unrecoverable)
-
 ## Critical Paths
 
 | Resource | Path |
 |----------|------|
-| Team Definition (source of truth) | `{{TEAM_CONFIG_PATH}}` |
 | Refactor Artifacts Dir | `.prizmkit/refactor/{{REFACTOR_ID}}/` |
 | Spec | `.prizmkit/refactor/{{REFACTOR_ID}}/spec.md` |
 | Plan | `.prizmkit/refactor/{{REFACTOR_ID}}/plan.md` |
+| Review Report | `.prizmkit/refactor/{{REFACTOR_ID}}/review-report.md` |
 | Refactor Report | `.prizmkit/refactor/{{REFACTOR_ID}}/refactor-report.md` |
-| Dev Agent Def | {{DEV_SUBAGENT_PATH}} |
-| Reviewer Agent Def | {{REVIEWER_SUBAGENT_PATH}} |
+| Completion Summary | `.prizmkit/refactor/{{REFACTOR_ID}}/completion-summary.json` |
 | Session Status Output | {{SESSION_STATUS_PATH}} |
 | Workflow Checkpoint | {{CHECKPOINT_PATH}} |
 | Project Root | {{PROJECT_ROOT}} |
 
 ## Reminders
 
-- **MANDATORY**: Use `prizm-dev-team` agents — single-agent execution is FORBIDDEN
-- **Behavior preservation is the #1 priority**: If tests break, stop and fix before proceeding
-- **Run tests after EVERY task** — not just at the end
-- Use `/prizmkit-plan` with `artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/` for spec + plan generation
-- **Commit with** `refactor(<scope>):` prefix, NOT `feat:` or `fix:`
-- **Run full retrospective** (Job 1 + Job 2) — refactoring changes code structure
-- ALWAYS write session-status.json before exiting
-- Do NOT use `run_in_background=true` when spawning normal work agents
+- Use L1 skills: `/prizmkit-plan`, `/prizmkit-implement`, `/prizmkit-code-review`, `/prizmkit-retrospective`, `/prizmkit-committer`.
+- Do not spawn top-level Dev or Reviewer subagents.
+- Behavior preservation is the first priority.
+- Browser verification is a mandatory attempt by default; it blocks only when explicitly required.
+- If `DEV_PORT` is unknown, discover it from project config; do not guess port 3000.
+- Always write session-status.json before exiting.

package/bundled/dev-pipeline/templates/sections/bugfix-artifacts.md

@@ -0,0 +1,16 @@
+## Bug Fix Artifacts Directory
+
+Use only this durable artifact directory for this bug fix:
+
+```text
+.prizmkit/bugfix/{{BUG_ID}}/
+├── spec.md
+├── plan.md
+├── context-snapshot.md
+├── review-report.md
+├── fix-report.md
+├── failure-log.md
+└── workflow-checkpoint.json
+```
+
+Do not write bugfix artifacts under feature or refactor artifact directories.

package/bundled/dev-pipeline/templates/sections/bugfix-critical-paths.md

@@ -0,0 +1,12 @@
+## Critical Paths
+
+| Resource | Path |
+|----------|------|
+| Bug Fix Artifacts Dir | `.prizmkit/bugfix/{{BUG_ID}}/` |
+| Spec | `.prizmkit/bugfix/{{BUG_ID}}/spec.md` |
+| Plan | `.prizmkit/bugfix/{{BUG_ID}}/plan.md` |
+| Review Report | `.prizmkit/bugfix/{{BUG_ID}}/review-report.md` |
+| Fix Report | `.prizmkit/bugfix/{{BUG_ID}}/fix-report.md` |
+| Workflow Checkpoint | `{{CHECKPOINT_PATH}}` |
+| Session Status Output | `{{SESSION_STATUS_PATH}}` |
+| Project Root | `{{PROJECT_ROOT}}` |