prizmkit 1.1.130 → 1.1.131

package/bundled/skills/refactor-pipeline-launcher/references/configuration.md

@@ -1,30 +1,28 @@
-# Configuration Reference — Refactor Pipeline Launcher
+# Configuration Reference — Refactor Pipeline Command Builder
 
-Environment variable mappings for the refactor launcher.
+Use this reference only to translate confirmed user choices into command fragments. The skill returns commands; it does not execute them.
 
-## Configured AI CLI Prerequisite Check
+## Configured AI CLI Prerequisite Command
 
-Read this section during launcher prerequisite validation before reporting AI CLI availability.
+Runtime AI CLI selection is config-driven. Resolve the executable in this order:
 
-Runtime AI CLI selection is config-driven. Resolve the executable name in this order:
-1. `AI_CLI` environment variable when set.
-2. `.prizmkit/config.json` `ai_cli` when present.
-3. `claude` fallback only when neither is configured.
+1. `AI_CLI` environment variable.
+2. `.prizmkit/config.json` `ai_cli`.
+3. `claude` only when neither is configured.
+
+Return this check command as part of start-command preparation:
 
-Run this quick check from the project root:
 ```bash
-command -v python3 >/dev/null && command -v git >/dev/null || { echo "python3 or git missing"; exit 1; }
 AI_CLI="$(
   python3 - <<'PY'
 import json, os, shlex
 from pathlib import Path
 cli = os.environ.get("AI_CLI", "").strip()
 if not cli:
-    config_path = Path(".prizmkit/config.json")
-    if config_path.is_file():
+    path = Path(".prizmkit/config.json")
+    if path.is_file():
         try:
-            data = json.loads(config_path.read_text(encoding="utf-8"))
-            cli = str(data.get("ai_cli") or "").strip()
+            cli = str(json.loads(path.read_text(encoding="utf-8")).get("ai_cli") or "").strip()
         except (OSError, json.JSONDecodeError):
             cli = ""
 cli = cli or "claude"
@@ -35,79 +33,46 @@ except ValueError:
 PY
 )"
 printf 'Configured AI CLI: %s\n' "$AI_CLI"
-command -v "$AI_CLI" >/dev/null && printf 'AI CLI OK: %s\n' "$(command -v "$AI_CLI")" || { printf 'AI CLI not found: %s\n' "$AI_CLI"; exit 1; }
-echo "All dependencies OK"
+command -v "$AI_CLI" >/dev/null
 ```
 
-Report the configured executable, for example `Configured AI CLI: claude`. Do not report the first arbitrary PATH match such as `cbc` when project config selects a different AI CLI.
-
-## Environment Variable Mapping
-
-Translating user responses to env vars:
-
-| Config choice | Environment variable |
-|-----------|---------------------|
-| Verbose: On | `VERBOSE=1` |
-| Verbose: Off | `VERBOSE=0` |
-| Max retries: N | `MAX_RETRIES=N` |
-| Strict behavior: On | `STRICT_BEHAVIOR_CHECK=1` |
-| Strict behavior: Off | `STRICT_BEHAVIOR_CHECK=0` |
-| Stop on failure: On | `STOP_ON_FAILURE=1` |
-| Deploy: Yes | `ENABLE_DEPLOY=1` |
-| Effort: value | `PRIZMKIT_EFFORT=<value>` |
-
-## Advanced Environment Variables
-
-Not exposed in interactive menu, pass via `--env`:
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `MODEL` | (none) | AI model override (e.g. `claude-opus-4.6`) |
-| `AUTO_PUSH` | `0` | Auto-push to remote after successful refactor (`1` to enable) |
-| `DEV_BRANCH` | auto-generated | Custom dev branch name (default: `refactor/pipeline-{run_id}`) |
-| `HEARTBEAT_INTERVAL` | `30` | Heartbeat log interval in seconds |
-| `HEARTBEAT_STALE_THRESHOLD` | `600` | Max seconds without heartbeat before marking stale |
-
-## Error Handling
-
-| Error | Action |
-|-------|--------|
-| `.prizmkit/plans/refactor-list.json` not found | Tell user to run `refactor-planner` skill first |
-| Circular dependencies in refactor list | Fix dependency graph in `.prizmkit/plans/refactor-list.json` before launching |
-| Test baseline failing | Fix failing tests before starting refactoring — behavior preservation requires a green baseline |
-| `python3` not installed | Install Python 3.10+ and rerun the Python runtime command |
-| `git` not installed | Install git; the Python runtime uses git for branch/worktree/status operations |
-| Configured AI CLI not in PATH | Install the executable selected by `AI_CLI` or `.prizmkit/config.json` `ai_cli`, or update the config to a CLI available in PATH. |
-| Refactor pipeline already running | Show status, ask if user wants to stop and restart |
-| PID file stale (process dead) | `python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor start .prizmkit/plans/refactor-list.json` auto-cleans, retry start |
-| Launch failed (process died immediately) | Show last 20 lines of log: `python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor logs --lines 20` |
-| Refactor stuck/blocked | Use `python3 ./.prizmkit/dev-pipeline/cli.py reset refactor <R-XXX> --clean --run` for a fresh retry |
-| All refactors blocked/failed | Show status, suggest recovery: `python3 ./.prizmkit/dev-pipeline/cli.py reset refactor <R-XXX> --clean --run .prizmkit/plans/refactor-list.json` |
-| `playwright-cli` not installed | Browser verification skipped for playwright refactors (non-blocking). Suggest: `npm install -g @playwright/cli@latest && playwright-cli install --skills` |
-| `opencli` not installed | Browser verification skipped for opencli refactors (non-blocking). Install opencli for Chrome session-based browser verification |
-| Deploy session failed | Pipeline completed but deploy session exited non-zero. Check `.prizmkit/state/refactor/deploy/<session_id>/logs/session.log`. Retry manually: `/prizmkit-deploy`. |
-| Permission denied running Python CLI | Ensure Python is installed and the command uses `python3 ./.prizmkit/dev-pipeline/cli.py ...` |
-
-## Advanced Configuration Round
-
-Only run this when the user answered "Yes" to the **Advanced config?** question in step 6. It applies to a minority of sessions.
-
-Ask a second round of `AskUserQuestion` with these 2 questions:
-
-**Question 1 — Stop on failure** (multiSelect: false):
-- Off (default) — Pipeline continues to next task after failure
-- On — Pipeline halts immediately when a task exhausts all retries (`STOP_ON_FAILURE=1`)
-
-**Question 2 — Deploy after completion?** (multiSelect: false):
-- No (default) — Skip deployment after pipeline completes
-- Yes — Run /prizmkit-deploy automatically after all refactors complete successfully (`ENABLE_DEPLOY=1`). Deployment is blocked if any refactor did not complete successfully (status not 'completed' or manually 'skipped').
-
-Then ask about reasoning effort in a follow-up `AskUserQuestion` call:
-
-**Question — Reasoning effort** (multiSelect: false):
-- Default (none) — Use CLI default
-- low — Minimize reasoning, fastest output (`PRIZMKIT_EFFORT=low`)
-- medium — Moderate reasoning (`PRIZMKIT_EFFORT=medium`)
-- high — Thorough reasoning for complex tasks (`PRIZMKIT_EFFORT=high`)
-- xhigh — Extensive reasoning (`PRIZMKIT_EFFORT=xhigh`)
-- max — Maximum reasoning, Claude Code only (`PRIZMKIT_EFFORT=max`)
+Do not claim the configured executable exists until the user supplies successful command output.
+
+## Base Configuration Mapping
+
+| Choice | Command fragment |
+|---|---|
+| Verbose Off | `VERBOSE=0` |
+| Verbose On | `VERBOSE=1` |
+| Max retries N | `MAX_RETRIES=N` |
+| Strict behavior On | `STRICT_BEHAVIOR_CHECK=1` |
+| Strict behavior Off | `STRICT_BEHAVIOR_CHECK=0` |
+
+## Advanced Configuration Questions
+
+Ask only when the user selected Advanced config.
+
+1. **Stop on failure**
+   - Off (default) — continue to other eligible tasks after a task exhausts retries.
+   - On — add `STOP_ON_FAILURE=1`.
+2. **Reasoning effort**
+   - Default — omit `PRIZMKIT_EFFORT`.
+   - `low`, `medium`, `high`, `xhigh`, or `max` — add `PRIZMKIT_EFFORT=<value>` after confirming the configured AI CLI supports it.
+
+These are the complete advanced choices for this command builder.
+
+## Baseline Command Guidance
+
+- Return `git status --short` as a suggested baseline cleanliness check.
+- When the project already declares a test command, return that exact command as an optional baseline command.
+- Do not infer a test command from framework names alone.
+- Do not claim the baseline is green until the user supplies successful output.
+
+## Command Construction Rules
+
+- Foreground: place environment assignments before `python3`.
+- Background daemon: place assignments inside one `--env "..."` value.
+- Include only confirmed options.
+- Preserve the user-provided list path.
+- Shell-quote custom paths and values.
+- Return one start command for the selected mode, never both.

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

@@ -5,7 +5,7 @@ description: "Interactive refactoring planner. Understands refactoring intent th
 
 # refactor planner
 
-Plan executable refactoring items for dev-pipeline:
+Plan executable refactoring items for later autonomous dev-pipeline execution. This skill creates or updates planning artifacts only:
 - **Scope Assessment**: analyze current code structure and identify refactoring targets
 - **Item Decomposition**: break refactoring goals into well-ordered, behavior-preserving items
 
@@ -27,7 +27,7 @@ The user chose this skill intentionally. Respect that choice.
 
 ## Scope Boundary (Hard Rule)
 
-**This skill is PLANNING ONLY.** You must NEVER:
+**This skill is PLANNING ONLY.** It may analyze code for planning evidence and create, append, validate, and review refactor planning artifacts, but it must never perform the refactor or start execution. You must NEVER:
 - Create, modify, or delete source code files (*.js, *.ts, *.py, *.go, *.html, *.css, etc.)
 - Execute refactoring operations (rename, move, extract, etc.)
 - Run build/install/test commands
@@ -42,7 +42,8 @@ The user chose this skill intentionally. Respect that choice.
 2. **Ask the user explicitly** whether they want to proceed to execution
 3. If the user agrees → recommend invoking `refactor-pipeline-launcher` (do NOT execute it yourself)
 4. If the user wants to adjust → continue refining `.prizmkit/plans/refactor-list.json`
-5. **NEVER auto-execute** the pipeline, launcher, or any implementation step
+5. **NEVER auto-execute** the pipeline, launcher, composite workflow, or any implementation step
+6. Return the validated refactor list to the caller; only `refactor-pipeline-launcher` prepares the runtime command
 
 ## User-Provided Content Priority (Hard Rule)
 
@@ -145,7 +146,7 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
 
 **Goal**: Understand the current codebase structure and tech stack.
 
-1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1 docs
+1. Read `.prizmkit/prizm-docs/root.prizm` and the relevant module documents it points to
 2. Read `.prizmkit/config.json` for tech stack info
 3. Identify existing test suite and coverage
 4. Summarize project context to the user: "Here's what I found about your project..."
@@ -202,10 +203,10 @@ Continue collecting goals until the user says they're done. There is no limit on
 
 **Goal**: Analyze the target code to inform item decomposition.
 
-Dispatch **parallel Agent reads** of target files:
-- **Agent A (Structure)**: File inventory, dependency graph, module boundaries, public API surface
-- **Agent B (Quality)**: Code smells, complexity hotspots, duplication, coupling metrics
-- **Agent C (Tests)**: Test coverage of target areas, existing test patterns, behavior contracts
+Run three parallel read-only analysis perspectives over the target files:
+- **Structure perspective**: File inventory, dependency graph, module boundaries, public API surface
+- **Quality perspective**: Code smells, complexity hotspots, duplication, coupling metrics
+- **Test perspective**: Test coverage of target areas, existing test patterns, behavior contracts
 
 Present consolidated findings:
 ```
@@ -287,22 +288,9 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
 
 ## Local Generated-Plan Review Gate
 
-User requirement preserved verbatim: `there is a litter bug for prizm-code-review will to check git diff in working space and staged space , however the .prizmkit will be gitignored in most situation.  so do you think the content should be change to inline a new reference file instead of use prizmkit-code-review`
+Run this gate after `.prizmkit/plans/refactor-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final refactor entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
 
-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 when the current session generated, appended, or rewrote final refactor planning content. For validate-only, summary-only, or draft-save flows with no new final planning content, report: `Local generated-plan review: not applicable — no new final planning content written.`
-
-1. **Load the local reference**: read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the source of truth for this planner-output review loop.
-2. **Read actual planning artifacts directly**: inspect `.prizmkit/plans/refactor-list.json`, `.prizmkit/plans/refactor-list.draft.json` when present, and any pre-session or in-memory draft snapshot. Do not rely on `git status`, `git diff`, or `git diff --cached`, because `.prizmkit` planning artifacts are often gitignored or untracked.
-3. **Identify review scope**: compare by stable refactor IDs and item fields against the pre-session list when one existed. Ignore root generator metadata such as `$schema`, `created_at`, and `created_by`. Review only newly added or changed refactor entries; preserve unchanged historical entries except when needed to verify dependency references or behavior-preservation interactions.
-4. **Run the local checklist** from the reference: schema compatibility, dependency/DAG soundness, safe behavior-preserving order, description completeness, headless execution readiness, acceptance criteria measurability, `behavior_preservation` strategy quality, user-provided wording preservation, task-scoped `user_context` isolation, and priority/complexity calibration.
-5. **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.
-6. **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.
-7. **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.
-8. **Report the gate outcome** in the final summary: include local generated-plan review verdict, reviewed refactor IDs, accepted fixes (or "none"), and final validation result.
+Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual draft and final artifacts directly because `.prizmkit` files may be gitignored. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, and require validation to pass again before reporting the review result.
 
 ## Output Rules
 
@@ -403,40 +391,7 @@ Recommend invoking `refactor-pipeline-launcher` to configure and launch the dev-
 
 ## Error Recovery & Resume
 
-Key behaviors:
-- Warnings only -> proceed with user approval
-- Critical errors -> group by type, auto-fix where possible, max 3 total attempts
-- Interrupted session -> detect checkpoint from existing artifacts, offer resume or restart
-- `.prizmkit/plans/refactor-list.json` MUST be written to `.prizmkit/plans/` (project root level: `./{root}/.prizmkit/plans/refactor-list.json`)
-
-### Resume Detection
-
-If existing artifacts are found, offer to resume from the appropriate checkpoint/phase:
-
-| Artifact Found | Resume From |
-|---------------|------------|
-| Nothing | Phase 1: Project Context |
-| Draft in `.prizmkit/plans/` | Phase matching draft state |
-| Partial `.prizmkit/plans/refactor-list.json` | Phase 6: Completeness Review |
-| Valid `.prizmkit/plans/refactor-list.json` | Mode D: Summary |
-
-### Session Exit Gate
-
-Prevent accidental session exit without deliverable completion.
-
-**Trigger conditions** — activate the exit gate when ALL are true:
-- User invoked `/refactor-planner` (not just mentioned refactoring)
-- Current phase < Phase 7 (validation not yet passed)
-- No valid `.prizmkit/plans/refactor-list.json` has been written in this session
-
-**Gate behavior** — when the session appears to be ending:
-1. **Remind**: "You set out to produce `.prizmkit/plans/refactor-list.json` but we haven't completed it yet."
-2. **Offer 3 options**:
-   - **(a) Continue to completion** — resume from current phase
-   - **(b) Save draft & exit** — write current progress as draft, exit session
-   - **(c) Abandon** — exit without saving
-3. **If (b)**: Write draft and remind: "This is a draft, not validated. Run `/refactor-planner` again to resume."
-4. **If (c)**: Accept without further prompting.
+When validation fails, existing planning artifacts are detected, the session is interrupted, or the user exits before producing a valid final plan, read `${SKILL_DIR}/references/error-recovery.md`. Keep recovery planning-only and resume from the artifact's actual completeness rather than restarting or guessing.
 
 ## Handoff Message Template