prizmkit 1.1.111 → 1.1.113

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

@@ -5,7 +5,7 @@ description: "Launch and manage the refactor pipeline from within an AI CLI sess
 
 # Refactor Pipeline Launcher
 
-Launch the autonomous refactor 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 refactor pipeline from within an AI CLI conversation. Only Background daemon mode is fully detached and survives AI CLI session closure; Foreground runs in the current session, and Manual prints commands without launching.
 
 ### Execution Mode
 
@@ -70,7 +70,7 @@ Detect user intent from their message, then follow the corresponding workflow:
 
 #### Intent A: Start Pipeline
 
-> **Execution model**: The pipeline processes refactor tasks **sequentially** (one at a time, in priority order). The `dependencies` field in refactor-list.json is reserved for future parallel execution support and does NOT affect current execution order.
+> **Execution model**: The pipeline processes eligible refactor tasks one at a time. The `dependencies` field is active: dependencies must complete before dependents are selected. Among unrelated eligible refactors, stable list order determines selection.
 
 1. **Check prerequisites**:
    ```bash
@@ -115,13 +115,28 @@ Detect user intent from their message, then follow the corresponding workflow:
    ```bash
    # Check git working tree is clean
    git status --porcelain | head -5
-   # Run existing test suite to establish baseline
-   npm test 2>&1 | tail -20 || echo "Test command failed or not configured"
+
+   # Detect the likely baseline test command
+   python3 - <<'PY'
+   from pathlib import Path
+   if Path('package.json').exists():
+       print('Detected package.json; use the project test script if configured')
+   elif Path('pytest.ini').exists() or Path('pyproject.toml').exists():
+       print('Detected Python project; use pytest if configured')
+   elif Path('go.mod').exists():
+       print('Detected Go project; use go test ./...')
+   else:
+       print('No obvious test command detected; ask the user for the baseline command')
+   PY
    ```
 
+   Use the detected command, an existing project convention, or a user-provided command to establish the baseline before launch.
+
    If git working tree is dirty, warn the user:
    > "Working tree has uncommitted changes. It's recommended to commit or stash changes before starting refactoring so each refactor task has a clean baseline. Continue anyway?"
 
+   If no baseline command is detected, warn and ask the user for the correct command or explicit permission to continue without an automated baseline.
+
    If test baseline fails, warn the user:
    > "Test suite is not passing. Refactoring relies on tests to verify behavior preservation. Fix failing tests before starting the refactor pipeline, or continue at your own risk."
 
@@ -154,11 +169,11 @@ Detect user intent from their message, then follow the corresponding workflow:
    - No (default) — Use defaults for critic review and failure behavior
    - Yes — Configure critic review, stop-on-failure, and reasoning effort options
 
-   Note: Refactor filter defaults to all refactor items (by priority order). If the user selects "Other" on any option, handle their custom input.
+   Note: Refactor filter defaults to all refactor items. Runtime selects eligible refactors in stable list order after dependencies are completed; planners should order unrelated refactors by user priority before launch. If the user selects "Other" on any option, handle their custom input.
 
    **If user chose "Yes" to Advanced config**, run the advanced configuration round (a second `AskUserQuestion` round, plus a reasoning-effort follow-up). It applies to a minority of sessions, so the full question set lives in `${SKILL_DIR}/references/configuration.md` → **Advanced Configuration Round**. Default Critic to Off unless refactor items have `priority: "critical"` (in which case default to On).
 
-   **Environment variable mapping** and **advanced environment variables** tables — read `${SKILL_DIR}/references/configuration.md` for the full translation tables (10 config→env mappings + 8 advanced variables).
+   Read `${SKILL_DIR}/references/configuration.md` for the current environment-variable mapping and advanced environment-variable tables.
 
 
 7. **Show final command**: After user confirms configuration in step 6, assemble the complete command from execution mode + user-confirmed configuration, and present it to the user.
@@ -167,9 +182,9 @@ Detect user intent from their message, then follow the corresponding workflow:
    ```bash
    VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 python3 ./.prizmkit/dev-pipeline/cli.py refactor run .prizmkit/plans/refactor-list.json
    ```
-   With all options:
+   Selected-options example:
    ```bash
-   VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5 ENABLE_DEPLOY=1 PRIZMKIT_EFFORT=high \
+   VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 ENABLE_CRITIC=true MAX_RETRIES=5 STOP_ON_FAILURE=1 ENABLE_DEPLOY=1 PRIZMKIT_EFFORT=high \
      python3 ./.prizmkit/dev-pipeline/cli.py refactor run .prizmkit/plans/refactor-list.json
    ```
 
@@ -177,10 +192,10 @@ Detect user intent from their message, then follow the corresponding workflow:
    ```bash
    python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor start .prizmkit/plans/refactor-list.json --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1"
    ```
-   With all options:
+   Selected-options example:
    ```bash
    python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor start .prizmkit/plans/refactor-list.json \
-     --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5 ENABLE_DEPLOY=1"
+     --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 ENABLE_CRITIC=true MAX_RETRIES=5 STOP_ON_FAILURE=1 ENABLE_DEPLOY=1 PRIZMKIT_EFFORT=high"
    ```
 
    **Manual mode**: Print the assembled command(s) and **stop here**. Do not execute anything. Do not proceed to step 8.
@@ -197,7 +212,10 @@ Detect user intent from their message, then follow the corresponding workflow:
 
 8. **Confirm and launch** (Foreground and Background only — Manual mode ends at step 7):
 
-   Ask: "Ready to launch the refactor pipeline with the above command?"
+   Use a separate `AskUserQuestion` call: "Ready to launch the refactor pipeline with the above command?"
+   Options:
+   - Launch now (Recommended)
+   - Cancel
 
    After user confirms, execute the command from step 7.
 
@@ -207,6 +225,7 @@ Detect user intent from their message, then follow the corresponding workflow:
    - Summarize results: total refactors, succeeded, failed, skipped
    - If all succeeded: each refactor session has already run `prizmkit-retrospective` internally. Ask user what's next.
    - If some failed: show failed refactor IDs and suggest `python3 ./.prizmkit/dev-pipeline/cli.py reset refactor <R-XXX> --clean --run` for a fresh retry
+   - **Browser verification**: Refactor sessions with `browser_interaction` perform supplemental UI verification during execution. After completion, use `python3 ./.prizmkit/dev-pipeline/cli.py refactor status .prizmkit/plans/refactor-list.json` and per-refactor session logs as the source of truth before summarizing browser verification results.
 
    **If background daemon**:
    1. Verify launch:
@@ -310,8 +329,8 @@ Read the error-handling table in `${SKILL_DIR}/references/configuration.md` for
 ### Integration Notes
 
 - **After refactor-planner**: This is the natural next step. When user finishes refactor planning and has `.prizmkit/plans/refactor-list.json`, suggest launching the refactor pipeline.
-- **Session independence**: The pipeline runs completely detached. User can close the AI CLI session, open a new session later, and use this skill to check progress or stop the pipeline.
-- **Single instance**: Only one refactor pipeline can run at a time. The PID file prevents duplicates.
+- **Session independence**: Only Background daemon mode runs detached. Foreground runs in the current AI CLI session, and Manual mode prints commands without launching.
+- **Single instance per family**: Only one refactor pipeline can run at a time. Different pipeline families may coexist because they use separate daemon metadata and state directories.
 - **Pipeline coexistence**: Refactor pipeline uses `.prizmkit/state/refactor/` separate from `.prizmkit/state/features/` (features) and `.prizmkit/state/bugfix/` (bugs), so all three pipelines can run simultaneously without conflict.
 - **State preservation**: Stopping and restarting the pipeline resumes from where it left off -- completed refactors are not re-run.
 - **HANDOFF**: After pipeline completes all refactors, each session has already run `prizmkit-retrospective` internally. Ask user what's next.

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

@@ -1,6 +1,6 @@
 ---
 name: "refactor-planner"
-description: "Interactive refactoring planner. Understands refactoring intent through dialogue, analyzes current code structure, produces validated .prizmkit/plans/refactor-list.json for dev-pipeline execution. Use whenever users discuss refactoring planning, code restructuring scope, or preparing .prizmkit/plans/refactor-list.json."
+description: "Interactive refactoring planner. Understands refactoring intent through dialogue, analyzes current code structure, identifies refactoring targets, decomposes large refactors or code migrations, and produces validated .prizmkit/plans/refactor-list.json for dev-pipeline execution. Use whenever users discuss refactoring planning, code restructuring scope, code migration planning, or preparing .prizmkit/plans/refactor-list.json."
 ---
 
 # refactor planner
@@ -345,7 +345,7 @@ For simple refactoring with minimal scope (1-2 items, low/medium complexity, no
 
 ## Browser Verification
 
-Browser verification is a feature-pipeline capability only. Refactors use `behavior_preservation` strategy instead. Read `${SKILL_DIR}/references/planning-phases.md` for strategy details and UI refactoring examples.
+Browser verification is supported for UI-affecting refactors as a supplement to `behavior_preservation`. Refactors must still declare `behavior_preservation.strategy`; add `browser_interaction` only when UI behavior should be visually checked after refactoring. Read `${SKILL_DIR}/references/planning-phases.md` for strategy details and UI refactoring examples.
 
 ---
 

package/bundled/skills/refactor-planner/references/behavior-preservation.md

@@ -37,8 +37,10 @@ This guide covers strategies for ensuring that refactoring changes structure wit
 **Configuration in refactor-list.json**:
 ```json
 {
-  "behavior_preservation": "test-gate",
-  "test_command": "npm test"
+  "behavior_preservation": {
+    "strategy": "test-gate",
+    "existing_tests": true
+  }
 }
 ```
 
@@ -75,8 +77,13 @@ This guide covers strategies for ensuring that refactoring changes structure wit
 **Configuration in refactor-list.json**:
 ```json
 {
-  "behavior_preservation": "snapshot",
-  "snapshot_targets": ["API responses for /api/users/*", "CLI output for --help flag"]
+  "behavior_preservation": {
+    "strategy": "snapshot"
+  },
+  "acceptance_criteria": [
+    "API responses for /api/users/* match before/after snapshots",
+    "CLI output for --help remains unchanged"
+  ]
 }
 ```
 
@@ -112,8 +119,12 @@ This guide covers strategies for ensuring that refactoring changes structure wit
 **Configuration in refactor-list.json**:
 ```json
 {
-  "behavior_preservation": "manual",
-  "verification_notes": "Manually verify login flow works: email login, social login, password reset"
+  "behavior_preservation": {
+    "strategy": "manual"
+  },
+  "acceptance_criteria": [
+    "Manual verification confirms email login, social login, and password reset behavior remain unchanged"
+  ]
 }
 ```
 
@@ -123,16 +134,10 @@ This guide covers strategies for ensuring that refactoring changes structure wit
 
 Use this decision tree to select the appropriate strategy for each refactor item:
 
-```
-Does the target area have test coverage >60%?
-├── YES: Are the tests reliable (no flaky tests)?
-│   ├── YES → test-gate
-│   └── NO: Fix flaky tests first, then → test-gate
-│         (or if fixing is out of scope → snapshot)
-└── NO: Does the code produce deterministic, observable output?
-    ├── YES → snapshot
-    └── NO → manual (flag as high-risk)
-```
+1. If the target area has reliable test coverage above 60%, choose `test-gate`.
+2. If tests exist but are flaky, plan a prerequisite item to stabilize tests first; if stabilization is out of scope, choose `snapshot`.
+3. If test coverage is below 60% but behavior is deterministic and observable, choose `snapshot`.
+4. If neither reliable tests nor deterministic observable output exist, choose `manual` and flag the item as high risk.
 
 ### Strategy Selection Table
 
@@ -259,16 +264,16 @@ When coverage tools aren't available, assess manually:
 |---------------|-------------------|
 | >80% | Proceed with test-gate. High confidence in behavior preservation. |
 | 60-80% | Proceed with test-gate. Note gaps in refactor item descriptions for the pipeline to be cautious about. |
-| 30-60% | Consider writing additional tests before refactoring (as a prerequisite R-000 item). Or use snapshot strategy for low-coverage areas. |
+| 30-60% | Consider writing additional tests before refactoring as a normal `R-NNN` prerequisite item. Or use snapshot strategy for low-coverage areas. |
 | <30% | Strongly recommend writing tests first. If user declines, use snapshot or manual strategy and flag as high risk. |
 | 0% | WARN user explicitly. Recommend writing tests as a prerequisite. If user insists on proceeding, use manual strategy and document all known behaviors. |
 
 ### Adding Tests as a Prerequisite Item
 
-When test coverage is insufficient, add a prerequisite refactor item:
+When test coverage is insufficient, add a prerequisite refactor item using the normal `R-NNN` sequence. If the prerequisite is added before other generated items, it is usually `R-001`; downstream refactors depend on that ID.
 
 ```
-Refactor Item R-000:
+Refactor Item R-001:
   Title: Add test coverage for [target area] before refactoring
   Type: restructure
   Scope: [test files]

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

@@ -22,13 +22,11 @@ For simple refactoring with minimal scope.
          description: "Skip detailed analysis, draft refactor items directly and add to refactor-list.json"
        - label: "Full workflow"
          description: "Use the complete planning workflow with detailed code analysis"
-       - label: "Implement directly"
-         description: "Skip the task list entirely and implement the refactoring right now using /prizmkit-plan + /prizmkit-implement"
    ```
 
    - **Fast-path** → Continue with fast-path workflow below
    - **Full workflow** → Exit fast path, use full workflow from Phase 2
-   - **Implement directly** → Invoke `/prizmkit-plan` directly to create spec + plan, then `/prizmkit-implement` to execute. Do NOT add to `.prizmkit/plans/refactor-list.json`
+   - If the user wants direct implementation instead of planning, exit the planner flow after explicit confirmation and recommend `/prizmkit-plan`; do not invoke implementation from inside `refactor-planner`.
 
    **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
 3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
@@ -51,7 +49,7 @@ For simple refactoring with minimal scope.
 User: "Rename the auth middleware function from checkAuth to requireAuth everywhere."
 AI: [Detects simple rename, single module]
 AI: [Qualifies for fast path: 1 item, low complexity, no cross-module impact]
-AI: [Uses AskUserQuestion with options: "Fast-path", "Full workflow", "Implement directly"]
+AI: [Uses AskUserQuestion with options: "Fast-path", "Full workflow"]
 User: [Selects "Fast-path"]
 AI: "Drafting R-001..."
 AI: [Validates immediately]

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

@@ -130,13 +130,13 @@ Anti-pattern: do not generate an all-high refactor list unless every item indepe
 
 ## Browser Verification
 
-**Browser verification is a feature-pipeline capability only.** Refactors use `behavior_preservation` strategy instead to ensure no external behavior changes:
+Browser verification is supported for UI-affecting refactors, but it is supplemental. Every refactor still uses `behavior_preservation.strategy` as the primary behavior-preservation contract:
 
 - `strategy: test-gate` — Rely on existing test suite. Pipeline runs tests before and after refactoring.
 - `strategy: snapshot` — Compare behavior before/after refactoring using executable snapshots (outputs, API responses, side effects)
 - `strategy: manual` — Require human verification that behavior is preserved
 
-For refactors that modify UI code (e.g., component restructuring), the test-gate or snapshot strategy ensures visual appearance is preserved. You can optionally note browser verification needs in your description or acceptance criteria:
+For refactors that modify UI code, add `browser_interaction.verify_steps` when visual or browser-flow verification is useful. Also keep behavior-preservation acceptance criteria explicit:
 
 Example:
 ```