prizmkit 1.1.130 → 1.1.131

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

@@ -1,275 +1,186 @@
 ---
 name: "bugfix-pipeline-launcher"
-description: "Launch and manage the bugfix pipeline from within an AI CLI session. Start pipeline in background, monitor logs, check status, stop pipeline. Use this skill whenever the user wants to start fixing bugs, run the bugfix pipeline, check bugfix progress, or stop the bugfix pipeline. Trigger on: 'start fixing bugs', 'run bugfix pipeline', 'bugfix status', 'stop bug fix', 'launch bug fix', 'fix progress', 'stop fixing'. (project)"
+description: "Build bugfix-pipeline commands from a validated .prizmkit/plans/bug-fix-list.json without executing them. Produces foreground or background-daemon start commands plus status, logs, stop, and safe retry commands. Use whenever the user wants to start fixing a prepared bug list, construct a bugfix command, check bugfix status, view logs, stop a run, retry a bug, or clean retry B-001. Trigger on: 'start fixing bugs', 'run bugfix pipeline', 'bugfix status', 'bugfix logs', 'stop bug fix', 'retry bug', 'retry B-001'."
 ---
 
-# Bugfix-Pipeline Launcher
+# Bugfix Pipeline Command Builder
 
-Launch the autonomous bug fix 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.
+Build commands for the autonomous bugfix pipeline from within an AI CLI conversation. This skill reads configuration and planning inputs, asks only the choices needed to construct an accurate command, displays the command and its effects, then stops.
 
-### Execution Mode
+## Command-Only Boundary
 
-Three execution modes are available. The user chooses one before configuring other options:
+This skill:
 
-1. **Foreground** (recommended) — `python3 ./.prizmkit/dev-pipeline/cli.py bugfix run`. Visible output, direct error feedback, no orphaned processes.
-2. **Background daemon** — `python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix start .prizmkit/plans/bug-fix-list.json`. Runs fully detached, survives AI CLI session closure.
-3. **Manual** — Display the assembled command(s) only. Do not execute anything. User runs them on their own.
+- reads a validated bug list and relevant configuration;
+- builds prerequisite-check, start, status, logs, stop, and retry commands;
+- explains command effects and destructive options before returning them;
+- never executes shell commands, starts processes, follows logs, changes pipeline state, fixes source code, or runs verification.
 
-**Background mode traceability**: Daemon mode metadata and logs are written by the Python runtime (`daemon bugfix start/status/logs`). Do not create any extra launcher-managed audit file.
+Do not invoke another workflow or implementation skill from this command builder. The user decides where and when to run the returned command.
 
-### When to Use
+## When to Use
 
-**Start bugfix pipeline** -- User says:
-- "start fixing bugs", "run bugfix pipeline", "launch bug fixes", "fix all bugs"
-- "start bug fix", "execute bug list", "begin fixing", "batch fix"
-- After bug-planner completes: "fix them", "start fixing"
+Use this skill for:
 
-**Check status** -- User says:
-- "bugfix status", "check bug fixes", "how's the fixing going", "bug fix progress"
-- "fix progress", "bug fix status", "check fix progress", "how far along are the fixes"
+- constructing a foreground or background-daemon bugfix pipeline command;
+- constructing status, logs, stop, or retry commands;
+- translating user-selected runtime options into environment variables.
 
-**Stop bugfix pipeline** -- User says:
-- "stop bug fix", "stop fixing", "halt bugfix", "pause bug fix", "stop fix pipeline"
+Do not use it to:
 
-**Show logs** -- User says:
-- "bugfix logs", "show fix logs", "what's being fixed"
-- "view fix logs", "fix logs"
+- create or modify `.prizmkit/plans/bug-fix-list.json` — use `bug-planner`;
+- fix a bug in the current conversation;
+- execute, monitor, or verify a pipeline run.
 
-**Do NOT use this skill when:**
-- User wants to plan/collect bugs (use `bug-planner` instead)
-- User wants to fix a single bug interactively in current session (use `bug-fix-workflow`)
-- User wants to launch the feature pipeline (use `feature-pipeline-launcher`)
+## Inputs
 
-### Prerequisites
+Default paths:
 
-Before any action, validate:
+- Runtime CLI: `.prizmkit/dev-pipeline/cli.py`
+- Bug plan: `.prizmkit/plans/bug-fix-list.json`
 
-1. **bugfix pipeline exists**: Confirm `.prizmkit/dev-pipeline/cli.py` is present
-2. **For start**: `.prizmkit/plans/bug-fix-list.json` must exist in `.prizmkit/plans/` (or user-specified path)
-3. **Dependencies**: `python3`, `git`, and the configured AI CLI must be in PATH. Resolve and report the AI CLI from `AI_CLI` env, then `.prizmkit/config.json` `ai_cli`, then fallback to `claude` only when neither is configured. Read `${SKILL_DIR}/references/configuration.md` §Configured AI CLI Prerequisite Check before running the AI CLI check.
-4. **Python version**: Requires Python 3.10+ for the unified dev-pipeline runtime
-5. **Browser tools** (optional): If any bug has `browser_interaction` field, check the corresponding tool is available. Bugs may specify `tool: "playwright-cli"`, `tool: "opencli"`, or `tool: "auto"` (AI chooses at runtime).
+Accept a user-specified bug-list path when provided. Read the plan directly to summarize IDs, severity, dependencies, and current statuses. If the plan is missing or malformed, report that a valid bug plan is required and stop without constructing a start command.
+
+Read `${SKILL_DIR}/references/configuration.md` before constructing prerequisite or runtime option fragments.
+
+## Intent Routing
+
+| Intent | Output |
+|---|---|
+| Start prepared bugs | Prerequisite-check command plus one start command |
+| Check status | Daemon status and item-level status commands |
+| Show logs | Recent or follow-log command |
+| Stop | Daemon stop command plus optional status command |
+| Retry one bug | Standard or clean reset-and-run command with safety disclosure |
+
+Only the start intent uses the execution-mode and configuration rounds.
+
+## Start Command Workflow
+
+### Step 1: Resolve inputs
+
+1. Resolve the bug-list path.
+2. Read the list and summarize total, eligible, blocked, and selected bug IDs.
+3. If an existing run is suspected from user context, include a status command in the output; do not run it.
+
+### Step 2: Ask execution mode
+
+Use one `AskUserQuestion` call with exactly one question:
+
+- **Foreground (Recommended)** — build `bugfix run`; output remains attached to the user's terminal.
+- **Background daemon** — build `daemon bugfix start`; the runtime manages detached execution and logs.
+
+Wait for the response before asking configuration.
+
+### Step 3: Ask base configuration
+
+Use a separate `AskUserQuestion` call with exactly three questions:
+
+1. **Verbose logging** — On or Off.
+2. **Max retries** — 3, 1, 5, or a user-provided non-negative integer.
+3. **Advanced config** — No or Yes.
+
+If Advanced config is Yes, load the advanced question set from `${SKILL_DIR}/references/configuration.md`. Advanced configuration contains only stop-on-failure and reasoning effort.
+
+### Step 4: Build command fragments
+
+Map confirmed choices to environment variables using `${SKILL_DIR}/references/configuration.md`.
+
+Return this prerequisite-check command separately from the pipeline command:
 
-Quick check:
 ```bash
-command -v python3 >/dev/null && command -v git >/dev/null && echo "Core dependencies OK"
-# AI CLI check: read `${SKILL_DIR}/references/configuration.md` §Configured AI CLI Prerequisite Check.
-# It must print `Configured AI CLI: <name>` and verify that exact executable.
-# Optional: browser interaction support (check both tools — bugs may use either)
-command -v playwright-cli && echo "playwright-cli OK" || echo "playwright-cli not found (playwright browser verification will be skipped)"
-command -v opencli && echo "opencli OK" || echo "opencli not found (opencli browser verification will be skipped)"
+command -v python3 >/dev/null && command -v git >/dev/null && test -f .prizmkit/dev-pipeline/cli.py && python3 -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)'
 ```
 
-If `.prizmkit/plans/bug-fix-list.json` is missing, inform user:
-> "No .prizmkit/plans/bug-fix-list.json found. Run the `bug-planner` skill first to generate one, or provide a path to your bug fix list."
+Also include the configured AI CLI check fragment from the reference. These are returned commands, not checks performed by this skill.
 
-### Workflow
+### Step 5: Return the start command
 
-Detect user intent from their message, then follow the corresponding workflow:
+Foreground template:
 
----
+```bash
+VERBOSE=1 MAX_RETRIES=3 \
+  python3 ./.prizmkit/dev-pipeline/cli.py bugfix run .prizmkit/plans/bug-fix-list.json
+```
 
-#### Intent A: Start Bugfix Pipeline
-
-> **Execution model**: The pipeline processes eligible bugs one at a time. The `dependencies` field is active: dependencies must complete before dependents are selected. Among unrelated eligible bugs, stable list order determines selection.
-
-1. **Check prerequisites**:
-   ```bash
-   ls .prizmkit/plans/bug-fix-list.json 2>/dev/null && echo "Found" || echo "Missing"
-   ```
-
-2. **Check not already running**:
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix status 2>/dev/null
-   ```
-   If running, inform user and ask: "Bugfix pipeline is already running. Want to restart it, check status, or view logs?"
-
-3. **Show bug summary** (so user knows what will be fixed):
-   ```bash
-   python3 -c "
-   import json
-   with open('.prizmkit/plans/bug-fix-list.json') as f:
-       data = json.load(f)
-   bugs = data.get('bugs', [])
-   severity_order = {'critical': 0, 'high': 1, 'medium': 2, 'low': 3}
-   print(f'Total bugs: {len(bugs)}')
-   sev_counts = {}
-   for b in bugs:
-       s = b.get('severity', 'medium')
-       sev_counts[s] = sev_counts.get(s, 0) + 1
-   print(f'By severity: {dict(sorted(sev_counts.items(), key=lambda x: severity_order.get(x[0], 2)))}')
-   print()
-   for b in bugs:
-       print(f\"  {b['id']}: [{b.get('severity','?').upper()}] {b.get('title', 'untitled')}\")
-   "
-   ```
-   If pipeline state already exists, use the status command instead:
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py bugfix status .prizmkit/plans/bug-fix-list.json
-   ```
-
-4. **Ask execution mode** (first user decision — SEPARATE `AskUserQuestion` call with exactly 1 question):
-
-   Present the three execution modes from the **Execution Mode** section above (Foreground / Background daemon / Manual), multiSelect: false. Then STOP and wait for the user's response before continuing to step 5.
-
-5. **Ask configuration options** — applies to ALL execution modes (Foreground, Background, AND Manual). This is a SEPARATE `AskUserQuestion` call from step 4.
-
-   RULE: Execution mode (step 4) and configuration (step 5) are two distinct `AskUserQuestion` calls, asked in order, each followed by waiting for the user's answer. Merging them, assuming defaults, or showing the final command before the user has answered both rounds produces a misconfigured pipeline that runs autonomously for a long time — so it MUST NOT happen. If you find yourself writing the final command before the user has answered, STOP.
-
-   The step-5 questions (4 round-1 questions, plus a round 2 if the user picks "Yes" to Advanced config) and their env-var mappings are enumerated in `${SKILL_DIR}/references/configuration.md` under "Interactive Configuration Options". Present round 1 as one `AskUserQuestion` call; run round 2 only if Advanced config = Yes. Then STOP and wait for the user's response before continuing to step 6.
-6. **Show final command**: Assemble the complete command from execution mode + confirmed configuration, and present it to the user.
-
-   **Foreground command:**
-   ```bash
-   VERBOSE=1 python3 ./.prizmkit/dev-pipeline/cli.py bugfix run .prizmkit/plans/bug-fix-list.json
-   ```
-   Selected-options example:
-   ```bash
-   VERBOSE=1 MAX_RETRIES=5 STOP_ON_FAILURE=1 ENABLE_DEPLOY=1 PRIZMKIT_EFFORT=high \
-     python3 ./.prizmkit/dev-pipeline/cli.py bugfix run .prizmkit/plans/bug-fix-list.json
-   ```
-
-   **Background daemon command:**
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix start .prizmkit/plans/bug-fix-list.json --env "VERBOSE=1"
-   ```
-   Selected-options example:
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix start .prizmkit/plans/bug-fix-list.json \
-     --env "VERBOSE=1 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 7.
-   ```
-   # To run in foreground:
-   VERBOSE=1 python3 ./.prizmkit/dev-pipeline/cli.py bugfix run .prizmkit/plans/bug-fix-list.json
-
-   # To run in background (detached):
-   python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix start .prizmkit/plans/bug-fix-list.json --env "VERBOSE=1"
-
-   # To check status:
-   python3 ./.prizmkit/dev-pipeline/cli.py bugfix status .prizmkit/plans/bug-fix-list.json
-   ```
-
-7. **Confirm and launch** (Foreground and Background only — Manual mode ends at step 6):
-
-   Use a separate `AskUserQuestion` call: "Ready to launch the bugfix pipeline with the above command?"
-   Options:
-   - Launch now (Recommended)
-   - Cancel
-
-   After user confirms, execute the command from step 6.
-
-8. **Post-launch** (depends on execution mode):
-
-   **If foreground**: Pipeline runs to completion in the terminal. After it finishes:
-   - Summarize results: total bugs, fixed, failed, skipped
-   - If all fixed: each bug session has already run `prizmkit-retrospective` internally (structural sync by default; full retrospective when the fix changed interfaces, dependencies, or observable behavior). Ask user what's next.
-   - If some failed: show failed bug IDs and suggest `python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix <B-XXX> --clean --run` for a fresh retry
-   - **Browser verification**: Bug sessions with `browser_interaction` perform their own verification attempts during execution. After completion, use `python3 ./.prizmkit/dev-pipeline/cli.py bugfix status .prizmkit/plans/bug-fix-list.json` and per-bug session logs as the source of truth before summarizing browser verification results.
-
-   **If background daemon**:
-   1. Verify launch:
-      ```bash
-      python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix status
-      ```
-   2. Start log monitoring — Use the Bash tool with `run_in_background: true`:
-      ```bash
-      python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix logs --follow
-      ```
-   3. Report to user:
-      - Pipeline PID
-      - Log file location
-      - "You can ask me 'bugfix status' or 'show fix logs' at any time"
-      - "Closing this session will NOT stop the pipeline"
+Background template:
 
----
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix start .prizmkit/plans/bug-fix-list.json \
+  --env "VERBOSE=1 MAX_RETRIES=3"
+```
+
+Return only the template matching the confirmed mode and options. Explain that the command has not been executed, then stop.
 
-#### Intent B: Check Status
+## Status Command
 
-1. **Check daemon status**:
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix status
-   ```
+Return:
 
-2. **Show bug-level progress**:
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py bugfix status .prizmkit/plans/bug-fix-list.json
-   ```
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix status
+python3 ./.prizmkit/dev-pipeline/cli.py bugfix status .prizmkit/plans/bug-fix-list.json
+```
 
-3. **Show recent log activity** (last 20 lines):
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix logs --lines 20
-   ```
+Do not infer completion from the plan file alone when runtime state may exist.
 
-4. **Summarize** to user: total bugs, completed, in_progress, failed, pending, needs_info.
+## Logs Command
 
----
+Recent logs:
+
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix logs --lines 50
+```
 
-#### Intent C: Stop Bugfix Pipeline
+Follow logs:
 
-1. **Stop the daemon**:
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix stop
-   ```
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix logs --follow
+```
 
-2. **Verify stopped**:
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix status 2>/dev/null || true
-   ```
+When the user names a specific bug, explain that its session path can be identified from `.prizmkit/state/bugfix/<BUG_ID>/status.json`; do not read or tail it from this skill.
 
-3. **Inform user**: "Bugfix pipeline stopped. State is preserved -- you can resume later with 'start bug fix' and it will pick up where it left off."
+## Stop Command
 
----
+Return:
+
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix stop
+```
 
-#### Intent D: Show Logs
+Optionally include the daemon status command for the user to run afterward. Do not claim the pipeline stopped until runtime output confirms it.
 
-1. **Check if running**:
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix status 2>/dev/null
-   ```
+## Retry Command
 
-2. **If running** -- Start live tail with Bash tool `run_in_background: true`:
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix logs --follow
-   ```
+A reset can discard uncommitted changes when the target task branch is currently checked out. Clean reset additionally deletes the task branch and clears its task history/artifacts. Never hide these effects behind the word “retry.”
 
-3. **If not running** -- Show last 50 lines:
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix logs --lines 50
-   ```
+Use `AskUserQuestion` before constructing a retry command:
 
-4. **For per-bug session logs** (when user asks about a specific bug):
-   ```bash
-   # Check bug status for last session ID
-   cat .prizmkit/state/bugfix/<BUG_ID>/status.json 2>/dev/null
-   # Then tail that bug's session log
-   tail -100 .prizmkit/state/bugfix/<BUG_ID>/sessions/<SESSION_ID>/logs/session.log
-   ```
+- **Standard retry (Recommended)** — reset task status and rerun while preserving a non-current task branch; warn that an active task branch may still have uncommitted changes discarded by reset.
+- **Clean retry** — perform the standard reset and also delete the task branch and clear task history/artifacts.
+- **Cancel** — return no reset command.
 
----
+Standard template:
 
-#### Intent E: Retry Single Bug
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix B-001 --run .prizmkit/plans/bug-fix-list.json
+```
 
-When user says "retry B-001":
+Clean template:
 
 ```bash
 python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix B-001 --clean --run .prizmkit/plans/bug-fix-list.json
 ```
 
-**Note:** `python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix <B-XXX> --clean --run .prizmkit/plans/bug-fix-list.json` performs a full clean (deletes session history and artifacts) before retrying the selected bug — this gives a fresh start.
+For clean retry, require explicit acknowledgement of branch deletion and possible uncommitted-change loss before displaying the command.
 
-### Error Handling
+## Output Contract
 
-Read `${SKILL_DIR}/references/configuration.md` for the full error handling table.
+For every request, return:
 
-### Integration Notes
+1. Intent and resolved target.
+2. Input plan path and selected IDs, when applicable.
+3. Assumptions and safety warnings.
+4. Exact command block.
+5. `Command execution: not performed by this skill.`
 
-- **After bug-planner**: This is the natural next step. When user finishes bug planning and has `.prizmkit/plans/bug-fix-list.json`, suggest launching the bugfix pipeline.
-- **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 bugfix pipeline can run at a time. Different pipeline families may coexist because they use separate daemon metadata and state directories.
-- **Pipeline coexistence**: Bugfix, feature, and refactor pipelines use separate state directories (`.prizmkit/state/bugfix/`, `.prizmkit/state/features/`, `.prizmkit/state/refactor/`), so all three 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**: Dependencies are active. Runtime selects eligible bugs in stable list order after dependencies are completed; planners should order unrelated bugs by severity/priority before launch.
-- **Background mode traceability**: Daemon mode metadata/logging is runtime-owned; use `daemon bugfix status` and `daemon bugfix logs`.
-- **HANDOFF**: After pipeline completes all bugs, summarize results and ask what the user wants next. Individual sessions already run retrospective according to the bug-fix documentation policy.
+Never report command success, process IDs, log locations, bug completion, verification results, or state changes unless the user later supplies authoritative runtime output for explanation.

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

@@ -1,30 +1,28 @@
-# Configuration Reference — Bugfix Pipeline Launcher
+# Configuration Reference — Bugfix Pipeline Command Builder
 
-Environment variable mappings for the bugfix 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,89 +33,37 @@ 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: Off | `VERBOSE=0` |
-| Verbose: On | `VERBOSE=1` |
-| Max retries: N | `MAX_RETRIES=N` |
-| 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 bug fix (`1` to enable) |
-| `DEV_BRANCH` | auto-generated | Custom dev branch name (default: `bugfix/pipeline-{run_id}`) |
-| `HEARTBEAT_INTERVAL` | `30` | Heartbeat log interval in seconds |
-| `HEARTBEAT_STALE_THRESHOLD` | `600` | Max seconds without heartbeat before marking stale |
-
-## Interactive Configuration Options
-
-Present these via `AskUserQuestion` in step 5. Round 1 is one `AskUserQuestion` call with all 4 questions; round 2 only runs if the user picks "Yes" to Advanced config.
-
-### Round 1 (always asked)
-
-**Question 1 — Verbose logging** (multiSelect: false):
-- On (default) — Detailed AI session logs including tool calls and subagent activity
-- Off — Minimal logging
-
-**Question 2 — Max retries** (multiSelect: false):
-- 3 (default)
-- 1
-- 5
+Do not claim the configured executable exists until the user supplies successful command output.
 
-**Question 4 — Advanced config?** (multiSelect: false):
-- No (default) — Use defaults for failure behavior
-- Yes — Configure stop-on-failure, deploy, and reasoning effort options
+## Base Configuration Mapping
 
-Note: Bug filter defaults to all bugs. Runtime selects eligible bugs in stable list order after dependencies are completed; planners should order unrelated bugs by severity/priority before launch. If the user selects "Other" on any option, handle their custom input.
+| Choice | Command fragment |
+|---|---|
+| Verbose Off | `VERBOSE=0` |
+| Verbose On | `VERBOSE=1` |
+| Max retries N | `MAX_RETRIES=N` |
 
-### Round 2 (only if Advanced config = Yes)
+## Advanced Configuration 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`)
+Ask only when the user selected Advanced config.
 
-**Question 2 — Deploy after completion?** (multiSelect: false):
-- No (default) — Skip deployment after pipeline completes
-- Yes — Run /prizmkit-deploy automatically after all bugs fixed successfully (`ENABLE_DEPLOY=1`). Deployment is blocked if any bug was not fixed (status not 'completed', 'skipped', or 'needs_info').
+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.
 
-**Question 3 — 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`)
+These are the complete advanced choices for this command builder.
 
-## Error Handling
+## Command Construction Rules
 
-| Error | Action |
-|-------|--------|
-| `.prizmkit/plans/bug-fix-list.json` not found | Tell user to run `bug-planner` skill first |
-| `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. |
-| Bugfix 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 bugfix start .prizmkit/plans/bug-fix-list.json` auto-cleans, retry start |
-| Launch failed (process died immediately) | Show last 20 lines of log: `python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix logs --lines 20` |
-| All bugs blocked/failed/needs_info | Show status, suggest retrying with `python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix <B-XXX> --clean --run .prizmkit/plans/bug-fix-list.json` or providing more info |
-| `playwright-cli` not installed | Browser verification skipped for playwright bugs (non-blocking). Suggest: `npm install -g @playwright/cli@latest && playwright-cli install --skills` |
-| `opencli` not installed | Browser verification skipped for opencli bugs (non-blocking). Install opencli for Chrome session-based browser verification |
-| Deploy session failed | Pipeline completed but deploy session exited non-zero. Check `.prizmkit/state/bugfix/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 ...` |
+- 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.