prizmkit 1.0.76 → 1.0.78

package/bundled/dev-pipeline/README.md

@@ -1,13 +1,14 @@
 # dev-pipeline
 
-Autonomous development pipeline that drives the `prizm-dev-team` multi-agent team through iterative CodeBuddy CLI sessions, implementing a complete app feature-by-feature from a `feature-list.json` specification.
+Autonomous development pipeline that drives the `prizm-dev-team` multi-agent team through iterative AI CLI sessions, implementing a complete app feature-by-feature from a `feature-list.json` specification. Includes a parallel bug-fix pipeline for `bug-fix-list.json`.
 
 ## Prerequisites
 
 - Python 3.8+
 - [jq](https://jqlang.github.io/jq/) (`brew install jq`)
 - AI CLI in PATH: CodeBuddy (`cbc`) or Claude Code (`claude`)
-- `feature-list.json` generated by the `app-planner` skill
+- `feature-list.json` generated by the `app-planner` skill (for feature pipeline)
+- `bug-fix-list.json` generated by the `bug-planner` skill (for bug pipeline)
 
 ## Quick Start
 
@@ -25,143 +26,638 @@ python3 dev-pipeline/scripts/init-pipeline.py \
 
 # 4. Check progress at any time (from another terminal)
 ./dev-pipeline/run.sh status feature-list.json
+
+# 5. Or run as a background daemon
+./dev-pipeline/launch-daemon.sh start feature-list.json
 ```
 
-## Commands
+---
+
+## Shell Scripts Reference
 
-| Command | Description |
-|---------|-------------|
-| `./run.sh run [feature-list.json] [options]` | Start or resume the pipeline. Processes features sequentially by dependency order. |
-| `./run.sh status [feature-list.json]` | Display current pipeline status: completed, pending, blocked, failed features. |
-| `./run.sh test-cli` | Test AI CLI detection: show detected CLI, version, platform, and query the AI model identity. |
-| `./run.sh reset` | Clear all runtime state in `state/`. Pipeline starts fresh on next `run`. |
-| `./run.sh help` | Show usage help. |
-| `./retry-feature.sh <feature-id> [feature-list.json]` | Retry a single failed feature. Runs one session then exits. |
-| `./reset-feature.sh <feature-id> [--clean] [--run]` | Reset a feature to pending. `--clean` deletes artifacts, `--run` auto-retries. |
+### `run.sh` — Feature Pipeline Runner
 
-`run.sh` 常用 options：`--resume-phase N`、`--max-retries N`、`--timeout SEC`、`--ai-cli CMD`、`--dry-run`、`--no-reset`。
+Main entry point. Drives the full feature development pipeline.
+
+```bash
+./run.sh run [feature-list.json]                # Run all features
+./run.sh run <feature-id> [options]             # Run a single feature (F-NNN)
+./run.sh status [feature-list.json]             # Show pipeline status
+./run.sh reset                                  # Clear all state in state/
+./run.sh test-cli                               # Test AI CLI detection
+./run.sh help                                   # Show usage help
+```
 
-If `feature-list.json` path is omitted, defaults to `.dev-pipeline/feature-list.json` (run.sh) or `feature-list.json` (retry-feature.sh).
+**Single-feature options:**
 
-### Retrying a Failed Feature
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Generate bootstrap prompt only, don't spawn AI session |
+| `--timeout N` | Override `SESSION_TIMEOUT` for this run (seconds) |
+| `--resume-phase N` | Resume from specific phase number |
+| `--no-reset` | Don't reset feature artifacts before running |
 
-When a feature fails after max retries, use `retry-feature.sh` to run a single retry session:
+**Examples:**
 
 ```bash
-# Retry F-007
-./dev-pipeline/retry-feature.sh F-007
+# Run all features
+./dev-pipeline/run.sh run feature-list.json
 
-# With custom feature list
-./dev-pipeline/retry-feature.sh F-007 feature-list.json
+# Run a single feature
+./dev-pipeline/run.sh run F-007
 
-# With timeout (default: no limit)
-SESSION_TIMEOUT=7200 ./dev-pipeline/retry-feature.sh F-007
+# Dry run — inspect the generated prompt without spawning a session
+./dev-pipeline/run.sh run F-007 --dry-run
+
+# Resume from Phase 6 (implementation)
+./dev-pipeline/run.sh run feature-list.json --resume-phase 6
+
+# With timeout per session
+SESSION_TIMEOUT=7200 ./dev-pipeline/run.sh run feature-list.json
 ```
 
-The script will:
-1. Reset the feature status to allow retry
-2. Generate a fresh bootstrap prompt
-3. Run exactly one AI CLI session with heartbeat monitoring
-4. Update feature status based on the result
-5. Exit (does not continue to other features)
+If `feature-list.json` path is omitted, defaults to `feature-list.json` in the project root.
+
+---
 
-### Resetting a Failed Feature
+### `retry-feature.sh` — Retry Single Failed Feature
 
-When a feature is stuck (e.g. retry count exceeded, bad artifacts), use `reset-feature.sh` to wipe its state:
+Runs exactly ONE AI CLI session for a specified feature, then exits.
 
 ```bash
-# Reset status only (retry_count → 0, status → pending)
-./dev-pipeline/reset-feature.sh F-007
+./retry-feature.sh <feature-id> [feature-list.json]
+```
 
-# Reset + delete all session history and .prizmkit artifacts
-./dev-pipeline/reset-feature.sh F-007 --clean
+**What it does:**
+1. Cleans feature artifacts for a fresh restart
+2. Generates a fresh bootstrap prompt
+3. Runs exactly one AI CLI session with heartbeat monitoring
+4. Updates feature status based on the result
+5. Exits (does not continue to other features)
 
-# Reset + clean + immediately retry
-./dev-pipeline/reset-feature.sh F-007 --clean --run
+**Examples:**
 
-# With custom feature list
-./dev-pipeline/reset-feature.sh F-007 --clean my-features.json
+```bash
+./dev-pipeline/retry-feature.sh F-007
+./dev-pipeline/retry-feature.sh F-007 feature-list.json
+SESSION_TIMEOUT=7200 ./dev-pipeline/retry-feature.sh F-007
+MODEL=claude-opus-4.6 ./dev-pipeline/retry-feature.sh F-007
 ```
 
-What gets cleaned with `--clean`:
+---
+
+### `reset-feature.sh` — Reset Failed/Stuck Feature
+
+Resets a feature's state so it can be re-executed from scratch.
+
+```bash
+./reset-feature.sh <feature-id> [--clean] [--run] [feature-list.json]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--clean` | Delete session history + `.prizmkit/specs/{slug}/` artifacts |
+| `--run` | Immediately retry after reset (calls `retry-feature.sh`) |
+
+**What gets cleaned with `--clean`:**
 - `state/features/F-XXX/sessions/` — all session logs and prompts
-- `.prizmkit/specs/{feature-slug}/` — spec.md, plan.md (with Tasks section), contracts/
+- `.prizmkit/specs/{feature-slug}/` — spec.md, plan.md, context-snapshot.md
 
-What is always reset (with or without `--clean`):
+**What is always reset (with or without `--clean`):**
 - `status.json` — status → pending, retry_count → 0
 - `feature-list.json` — feature status → pending
 
-## Environment Variables
+**Examples:**
+
+```bash
+./dev-pipeline/reset-feature.sh F-007                    # Reset status only
+./dev-pipeline/reset-feature.sh F-007 --clean            # Reset + delete artifacts
+./dev-pipeline/reset-feature.sh F-007 --clean --run      # Reset + clean + retry
+./dev-pipeline/reset-feature.sh F-007 --clean my-features.json
+```
+
+---
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `MAX_RETRIES` | `3` | Maximum retry attempts per feature before marking as failed. |
-| `SESSION_TIMEOUT` | `0` (no limit) | Timeout in seconds per AI CLI session. 0 = no timeout. |
-| `AI_CLI` | auto-detect | AI CLI command name. Auto-detects `cbc` or `claude`. Set to override. |
-| `MODEL` | (none) | AI model ID for the session. Passed as `--model` to the CLI. See [Model Selection](#model-selection). |
-| `CODEBUDDY_CLI` | (deprecated) | Legacy alias for `AI_CLI`. Prefer `AI_CLI`. |
-| `VERBOSE` | `0` | Set to `1` to enable `--verbose` on AI CLI (shows subagent output). |
-| `HEARTBEAT_INTERVAL` | `30` | Seconds between heartbeat log output while a session is running. |
-| `HEARTBEAT_STALE_THRESHOLD` | `600` | Seconds before a session is considered stale/stuck. |
-| `LOG_CLEANUP_ENABLED` | `1` | Run log cleanup before pipeline execution (`1`=enabled, `0`=disabled). |
-| `LOG_RETENTION_DAYS` | `14` | Delete logs older than N days. |
-| `LOG_MAX_TOTAL_MB` | `1024` | Keep total log size under N MB by deleting oldest logs first. |
+### `launch-daemon.sh` — Feature Pipeline Daemon
 
-Example with custom config:
+Manages `run.sh` as a background daemon process with PID tracking and log consolidation. Designed for invocation from AI skill sessions.
 
 ```bash
-MAX_RETRIES=5 ./dev-pipeline/run.sh run feature-list.json
+./launch-daemon.sh start [feature-list.json] [--mode <mode>] [--env "KEY=VAL ..."]
+./launch-daemon.sh stop
+./launch-daemon.sh status
+./launch-daemon.sh logs [--lines N] [--follow]
+./launch-daemon.sh restart [feature-list.json] [--mode <mode>] [--env "KEY=VAL ..."]
+./launch-daemon.sh help
+```
 
-# With 2-hour timeout per session
-SESSION_TIMEOUT=7200 ./dev-pipeline/run.sh run feature-list.json
+| Subcommand | Description |
+|------------|-------------|
+| `start` | Launch pipeline in background. Stores PID in `state/.pipeline.pid` |
+| `stop` | Gracefully stop (SIGTERM, waits 30s, then SIGKILL) |
+| `status` | Check if running; outputs JSON + formatted progress to stderr |
+| `logs` | View pipeline logs. `--follow` for live tail, `--lines N` for last N lines |
+| `restart` | Stop + start |
+
+**`--mode` options:** `lite`, `standard`, `full`, `self-evolve`
 
-# Keep only recent logs and cap total log size
-LOG_RETENTION_DAYS=7 LOG_MAX_TOTAL_MB=512 ./dev-pipeline/run.sh run feature-list.json
+**`--env` format:** Pass environment variables as a quoted string:
+
+```bash
+./dev-pipeline/launch-daemon.sh start feature-list.json \
+  --mode standard \
+  --env "MAX_RETRIES=5 SESSION_TIMEOUT=3600 MODEL=claude-sonnet-4.6"
 ```
 
-### AI CLI Configuration
+**Output (JSON on stdout for programmatic consumption):**
 
-The pipeline auto-detects which AI CLI to use. Detection priority:
+```json
+{
+  "success": true,
+  "pid": 12345,
+  "log_file": "state/pipeline-daemon.log",
+  "started_at": "2026-03-21T12:00:00Z",
+  "progress": {
+    "total": 10, "completed": 3, "in_progress": 1,
+    "failed": 0, "pending": 6, "percent": 30.0
+  }
+}
+```
 
-1. `AI_CLI` environment variable (highest)
-2. `.prizmkit/config.json` → `ai_cli` field
-3. `CODEBUDDY_CLI` environment variable (legacy)
-4. Auto-detect: `cbc` in PATH → `claude` in PATH (lowest)
+**Key behaviors:**
+- Log stored at `state/pipeline-daemon.log` (50MB rotation)
+- Metadata at `state/.pipeline-meta.json`
+- Unsets `CLAUDECODE` env to prevent nested session errors
+
+---
 
-To permanently configure a project to use a specific CLI, create `.prizmkit/config.json`:
+### `run-bugfix.sh` — Bug-Fix Pipeline Runner
+
+Equivalent to `run.sh` but for the bug-fix pipeline.
+
+```bash
+./run-bugfix.sh run [bug-fix-list.json]         # Run all bugs
+./run-bugfix.sh run <bug-id> [options]           # Run single bug (B-NNN)
+./run-bugfix.sh status [bug-fix-list.json]       # Show status
+./run-bugfix.sh reset                            # Clear all bugfix state
+./run-bugfix.sh help
+```
+
+**Single-bug options:** `--dry-run`, `--timeout N` (same as `run.sh`)
+
+Processes bugs by: **severity** (critical > high > medium > low) then **priority** number.
+
+---
+
+### `retry-bug.sh` — Retry Single Failed Bug
+
+```bash
+./retry-bug.sh <bug-id> [bug-fix-list.json]
+```
+
+Same behavior as `retry-feature.sh` but for bugs. Cleans bug artifacts, generates bugfix prompt, runs one session, updates status.
+
+---
+
+### `launch-bugfix-daemon.sh` — Bug-Fix Pipeline Daemon
+
+Identical interface to `launch-daemon.sh` but manages `run-bugfix.sh` in background.
+
+```bash
+./launch-bugfix-daemon.sh start [bug-fix-list.json] [--env "KEY=VAL ..."]
+./launch-bugfix-daemon.sh stop
+./launch-bugfix-daemon.sh status
+./launch-bugfix-daemon.sh logs [--lines N] [--follow]
+./launch-bugfix-daemon.sh restart [bug-fix-list.json] [--env "KEY=VAL ..."]
+```
+
+Uses `bugfix-state/` instead of `state/`.
+
+---
+
+## Python Scripts Reference
+
+### `scripts/init-pipeline.py` — Initialize Feature Pipeline State
+
+Validates `feature-list.json` schema and creates the `state/` directory structure.
+
+```bash
+python3 scripts/init-pipeline.py \
+  --feature-list <path> \
+  --state-dir <path>
+```
+
+**Validation checks:**
+- Schema: `$schema == "dev-pipeline-feature-list-v1"`
+- Required fields: `app_name` (string), `features` (non-empty array)
+- Per-feature: `id` (F-NNN), `title`, `description`, `priority` (int), `dependencies` (array of F-NNN), `acceptance_criteria` (array), `status`
+- Dependency DAG cycle detection (Kahn's algorithm)
+
+**Output (JSON to stdout):**
+
+```json
+{ "valid": true, "features_count": 10, "state_dir": "/absolute/path/state" }
+```
+
+**Created files:**
+- `state/pipeline.json` — Pipeline metadata (run_id, created_at, total_features)
+- `state/features/{F-NNN}/status.json` — Per-feature status
+- `state/features/{F-NNN}/sessions/` — Session history directory
+
+---
+
+### `scripts/init-bugfix-pipeline.py` — Initialize Bug-Fix Pipeline State
+
+```bash
+python3 scripts/init-bugfix-pipeline.py \
+  --bug-list <path> \
+  --state-dir <path>
+```
+
+**Validation:** Schema `dev-pipeline-bug-fix-list-v1`, required fields per bug: `id` (B-NNN), `title`, `description`, `severity` (critical|high|medium|low), `error_source`, `verification_type`, `acceptance_criteria`, `status`.
+
+---
+
+### `scripts/init-dev-team.py` — Initialize PrizmKit Directories
+
+Creates per-feature directory structure for PrizmKit agent artifacts.
+
+```bash
+python3 scripts/init-dev-team.py \
+  --project-root <path> \
+  [--feature-id <id>] \
+  [--feature-slug <slug>]
+```
+
+**Creates:** `.prizmkit/specs/{feature-slug}/` directory.
+
+---
+
+### `scripts/generate-bootstrap-prompt.py` — Generate Feature Session Prompt
+
+Renders a session-specific bootstrap prompt from a tier template and feature-list.json.
+
+```bash
+python3 scripts/generate-bootstrap-prompt.py \
+  --feature-list <path> \
+  --feature-id <id> \
+  --session-id <id> \
+  --run-id <id> \
+  --retry-count <n> \
+  --resume-phase <n|null> \
+  --output <path> \
+  [--state-dir <path>] \
+  [--template <path>] \
+  [--mode lite|standard|full|self-evolve]
+```
+
+**Template auto-selection by complexity:**
+
+| `estimated_complexity` | Pipeline Mode | Template |
+|------------------------|--------------|----------|
+| `low` | lite | `bootstrap-tier1.md` (single agent) |
+| `medium` | standard | `bootstrap-tier2.md` (dual agent) |
+| `high` / `critical` | full | `bootstrap-tier3.md` (full team) |
+| (override) | self-evolve | `bootstrap-tier3.md` + framework guardrails |
+
+**Output (JSON to stdout):**
+
+```json
+{ "success": true, "output_path": "/absolute/path/prompt.md", "model": "claude-sonnet-4.6" }
+```
+
+The `model` field is extracted from the feature's `"model"` field in feature-list.json (empty string if not specified). Used by `run.sh` and `retry-feature.sh` to set `--model` on the AI CLI.
+
+**Conditional blocks resolved:**
+- `{{IF_RESUME}}` / `{{IF_FRESH_START}}` — Resume vs fresh start
+- `{{IF_INIT_NEEDED}}` / `{{IF_INIT_DONE}}` — PrizmKit init status
+- `{{IF_MODE_LITE}}` / `{{IF_MODE_STANDARD}}` / `{{IF_MODE_FULL}}` / `{{IF_MODE_SELF_EVOLVE}}` — Pipeline mode blocks
+
+---
+
+### `scripts/generate-bugfix-prompt.py` — Generate Bug-Fix Session Prompt
+
+```bash
+python3 scripts/generate-bugfix-prompt.py \
+  --bug-list <path> \
+  --bug-id <id> \
+  --session-id <id> \
+  --run-id <id> \
+  --retry-count <n> \
+  --resume-phase <n|null> \
+  --state-dir <path> \
+  --output <path> \
+  [--template <path>]
+```
+
+Resolves `{{BUG_ID}}`, `{{BUG_TITLE}}`, `{{SEVERITY}}`, `{{VERIFICATION_TYPE}}`, `{{ERROR_SOURCE}}`, etc.
+
+---
+
+### `scripts/update-feature-status.py` — Feature State Machine
+
+Core state management for features. Supports 8 actions.
+
+```bash
+python3 scripts/update-feature-status.py \
+  --feature-list <path> \
+  --state-dir <path> \
+  --action <action> \
+  [options]
+```
+
+| Action | Required Args | Description |
+|--------|--------------|-------------|
+| `get_next` | — | Find next runnable feature (pending + deps met). Returns `PIPELINE_COMPLETE` or `PIPELINE_BLOCKED` if none. |
+| `start` | `--feature-id` | Mark feature as in_progress |
+| `update` | `--feature-id --session-status <status> [--session-id] [--max-retries N]` | Update after session completes |
+| `status` | — | Pretty-print pipeline status (progress bar, ETA, per-feature breakdown) |
+| `reset` | `--feature-id` | Reset to pending, retry_count → 0 |
+| `clean` | `--feature-id --feature-slug --project-root` | Reset + delete all session history and .prizmkit artifacts |
+| `pause` | — | Save state for graceful shutdown |
+| `complete` | `--feature-id` | Shortcut for manually marking completed |
+
+**Session status values (for `--session-status`):**
+`success`, `partial_resumable`, `partial_not_resumable`, `failed`, `crashed`, `timed_out`, `commit_missing`, `docs_missing`, `merge_conflict`
+
+**Output (JSON to stdout):**
 
 ```json
 {
-  "ai_cli": "claude-internal",
-  "platform": "claude"
+  "action": "update", "feature_id": "F-007",
+  "session_status": "success", "new_status": "completed",
+  "retry_count": 0, "updated_at": "2026-03-21T12:34:56Z"
 }
 ```
 
-Or override per-invocation:
+---
+
+### `scripts/update-bug-status.py` — Bug State Machine
+
+Same interface as `update-feature-status.py` but for bugs.
 
 ```bash
-AI_CLI=claude-internal ./dev-pipeline/run.sh run feature-list.json
+python3 scripts/update-bug-status.py \
+  --bug-list <path> \
+  --state-dir <path> \
+  --action <action> \
+  [options]
 ```
 
-### Model Selection
+**Actions:** `get_next`, `update`, `status`, `pause`, `reset`, `clean`
 
-Use the `MODEL` environment variable to specify which AI model to use. The value is passed as `--model <id>` to the CLI.
+**Priority order:** severity (critical > high > medium > low), then priority number.
+
+---
+
+### `scripts/check-session-status.py` — Parse Session Outcome
+
+Reads the `session-status.json` written by the AI agent and determines outcome.
 
 ```bash
-# Run pipeline with Sonnet (faster, cheaper)
-MODEL=claude-sonnet-4.6 ./dev-pipeline/run.sh run feature-list.json
+python3 scripts/check-session-status.py --status-file <path>
+```
+
+**Output (single line to stdout):**
+`success` | `partial_resumable` | `partial_not_resumable` | `failed` | `crashed` | `commit_missing` | `docs_missing` | `merge_conflict`
+
+**Detail report (JSON to stderr):**
+
+```json
+{
+  "status": "success", "feature_id": "F-007",
+  "completed_phases": [...], "error_count": 0, "can_resume": false
+}
+```
+
+---
+
+### `scripts/detect-stuck.py` — Detect Stuck/Stale Features
+
+Identifies features that are blocked or stuck in the pipeline.
+
+```bash
+python3 scripts/detect-stuck.py \
+  --state-dir <path> \
+  [--feature-id <id>] \
+  [--max-retries <n>] \
+  [--stale-threshold <seconds>]
+```
+
+**Checks performed:**
+1. Max retries exceeded
+2. Stuck at same checkpoint for 3 consecutive sessions
+3. Stale heartbeat (in_progress with no recent activity)
+4. Dependency deadlock (depends on a failed feature)
+
+**Output (JSON):**
+
+```json
+{
+  "stuck_features": [
+    { "feature_id": "F-007", "reason": "max_retries_exceeded", "suggestion": "..." }
+  ],
+  "total_checked": 10, "stuck_count": 1
+}
+```
+
+**Exit code:** 0 if none stuck, 1 if any stuck.
+
+---
+
+### `scripts/cleanup-logs.py` — Log File Cleanup
+
+Manages log file size by age and total size thresholds.
+
+```bash
+python3 scripts/cleanup-logs.py \
+  --state-dir <path> \
+  [--retention-days <n>] \
+  [--max-total-mb <n>] \
+  [--dry-run]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--retention-days` | 14 | Delete files older than N days |
+| `--max-total-mb` | 1024 | If total > N MB, remove oldest first |
+| `--dry-run` | false | Show what would be deleted without deleting |
+
+---
 
-# Run pipeline with Opus (most capable)
-MODEL=claude-opus-4.6 ./dev-pipeline/run.sh run feature-list.json
+### `scripts/parse-stream-progress.py` — Real-Time Progress Parser
 
-# Retry a feature with a specific model
+Reads AI CLI `stream-json` output and extracts progress metrics.
+
+```bash
+python3 scripts/parse-stream-progress.py \
+  --session-log <path> \
+  --progress-file <path>
+```
+
+**Runs as a background process** (spawned by `lib/heartbeat.sh`). Reads JSONL from session log, writes progress to `progress.json` (atomic writes).
+
+**Phase detection (monotonic):** specify → plan → analyze → implement → code-review → retrospective → commit
+
+**Output (progress.json):**
+
+```json
+{
+  "updated_at": "2026-03-21T12:34:56Z",
+  "message_count": 42,
+  "current_tool": "bash",
+  "current_tool_input_summary": "npm test | head -20",
+  "current_phase": "implement",
+  "detected_phases": ["specify", "plan", "implement"],
+  "total_tool_calls": 23,
+  "is_active": true
+}
+```
+
+---
+
+### `scripts/utils.py` — Shared Python Utilities
+
+Imported by all Python scripts. Provides:
+
+| Function | Description |
+|----------|-------------|
+| `load_json_file(path)` | Returns `(data, error_string)` |
+| `write_json_file(path, data)` | Returns `error_string` or `None` |
+| `setup_logging(name, level)` | Configure logger with stderr output |
+| `error_out(message, code)` | Print error JSON + exit |
+| `pad_right(text, width)` | Pad accounting for ANSI escape codes |
+
+---
+
+## Shell Libraries
+
+### `lib/common.sh` — CLI Detection & Shared Helpers
+
+Sourced by daemon and runner scripts. Provides:
+
+| Function | Description |
+|----------|-------------|
+| `prizm_detect_cli_and_platform()` | Sets `CLI_CMD` and `PLATFORM`. Priority: `AI_CLI` env > `config.json` > `CODEBUDDY_CLI` > auto-detect |
+| `prizm_check_common_dependencies(cli_cmd)` | Verifies jq, python3, and CLI are installed |
+
+Also exports: `log_info`, `log_warn`, `log_error`, `log_success` (with timestamps), and color constants.
+
+### `lib/branch.sh` — Git Branch Lifecycle
+
+| Function | Description |
+|----------|-------------|
+| `branch_create(project_root, branch_name, source_branch)` | Create & checkout feature branch. Reuses if exists. Returns 0/1. |
+| `branch_return(project_root, original_branch)` | Checkout back to original branch |
+
+### `lib/heartbeat.sh` — Heartbeat & Progress Monitoring
+
+| Function | Description |
+|----------|-------------|
+| `start_heartbeat(cli_pid, session_log, progress_json, interval)` | Start background heartbeat monitor. Sets `_HEARTBEAT_PID`. |
+| `stop_heartbeat(heartbeat_pid)` | Kill heartbeat process |
+| `start_progress_parser(session_log, progress_json, scripts_dir)` | Spawn `parse-stream-progress.py` if stream-json supported. Sets `_PARSER_PID`. |
+| `stop_progress_parser(parser_pid)` | Kill parser process |
+| `detect_stream_json_support(cli_cmd)` | Sets `USE_STREAM_JSON=true\|false` |
+
+---
+
+## Environment Variables
+
+### Pipeline Control
+
+| Variable | Default | Used By | Description |
+|----------|---------|---------|-------------|
+| `MAX_RETRIES` | `3` | run.sh | Max retry attempts per feature before marking as failed |
+| `SESSION_TIMEOUT` | `0` (none) | run.sh, retry-feature.sh, run-bugfix.sh, retry-bug.sh | Timeout in seconds per AI CLI session. 0 = no timeout |
+| `PIPELINE_MODE` | (auto) | run.sh, launch-daemon.sh | Override mode for all features: `lite\|standard\|full\|self-evolve` |
+| `DEV_BRANCH` | auto-generated | run.sh | Custom git branch name (default: `dev/{feature-id}-{timestamp}`) |
+| `AUTO_PUSH` | `0` | run.sh | Set to `1` to auto-push branch to remote after successful session |
+
+### AI CLI Configuration
+
+| Variable | Default | Used By | Description |
+|----------|---------|---------|-------------|
+| `AI_CLI` | auto-detect | all shell scripts | AI CLI command name. Auto-detects `cbc` or `claude` |
+| `PRIZMKIT_PLATFORM` | auto-detect | all shell scripts | Force platform: `codebuddy` or `claude` |
+| `MODEL` | (none) | run.sh, retry-feature.sh, run-bugfix.sh, retry-bug.sh | AI model fallback. Overridden by per-feature `model` field. See [Model Selection](#model-selection) |
+| `CODEBUDDY_CLI` | (deprecated) | all shell scripts | Legacy alias for `AI_CLI`. Prefer `AI_CLI` |
+| `VERBOSE` | `0` | run.sh, retry-feature.sh | Set to `1` to enable `--verbose` on AI CLI |
+
+### Monitoring & Logging
+
+| Variable | Default | Used By | Description |
+|----------|---------|---------|-------------|
+| `HEARTBEAT_INTERVAL` | `30` | run.sh, retry-feature.sh | Seconds between heartbeat log output |
+| `HEARTBEAT_STALE_THRESHOLD` | `600` | run.sh | Seconds before a session is considered stale/stuck |
+| `LOG_CLEANUP_ENABLED` | `1` | run.sh | Run log cleanup before pipeline execution |
+| `LOG_RETENTION_DAYS` | `14` | run.sh | Delete logs older than N days |
+| `LOG_MAX_TOTAL_MB` | `1024` | run.sh | Keep total log size under N MB |
+
+**Examples:**
+
+```bash
+# All env vars in one invocation
+MAX_RETRIES=5 SESSION_TIMEOUT=7200 MODEL=claude-sonnet-4.6 VERBOSE=1 \
+  ./dev-pipeline/run.sh run feature-list.json
+
+# Via daemon with --env
+./dev-pipeline/launch-daemon.sh start feature-list.json \
+  --mode standard \
+  --env "MAX_RETRIES=5 SESSION_TIMEOUT=3600 AUTO_PUSH=1"
+```
+
+---
+
+## Model Selection
+
+Model is resolved with this priority chain (highest first):
+
+1. **Per-feature `model` field** in `feature-list.json`
+2. **`MODEL` environment variable**
+3. **No `--model` flag** (CLI uses its default)
+
+### Per-Feature Model
+
+Specify a model for individual features in `feature-list.json`:
+
+```json
+{
+  "features": [
+    { "id": "F-017", "title": "Complex Feature", "model": "claude-opus-4.6" },
+    { "id": "F-018", "title": "Simple Feature", "model": "claude-sonnet-4.6" },
+    { "id": "F-019", "title": "Use Default", "...": "..." }
+  ]
+}
+```
+
+- `F-017` will use `claude-opus-4.6` regardless of `$MODEL` env
+- `F-018` will use `claude-sonnet-4.6` regardless of `$MODEL` env
+- `F-019` will fall back to `$MODEL` env, or CLI default if `MODEL` is unset
+
+### Global Model via Environment
+
+```bash
+# All features without a per-feature model use Sonnet
+MODEL=claude-sonnet-4.6 ./dev-pipeline/run.sh run feature-list.json
+
+# Retry with Opus
 MODEL=claude-opus-4.6 ./dev-pipeline/retry-feature.sh F-007
 
 # Test which model the CLI is using
 MODEL=claude-sonnet-4.6 ./dev-pipeline/run.sh test-cli
 ```
 
-Common model IDs (for `cbc`):
+### Dry-Run Model Verification
+
+Use `--dry-run` to verify which model will be used without spawning a session:
+
+```bash
+./dev-pipeline/run.sh run F-017 --dry-run
+# Output includes: "Feature Model: claude-opus-4.6"
+```
+
+### Common Model IDs
 
 | Model ID | Description |
 |----------|-------------|
@@ -169,153 +665,163 @@ Common model IDs (for `cbc`):
 | `claude-sonnet-4.6` | Balanced speed/capability (recommended for pipeline) |
 | `claude-haiku-4.5` | Fastest, cheapest, less capable |
 
-> **Note**: `--model` support depends on the CLI. `cbc` fully supports it. `claude-internal` does not support `--model` in headless mode (only interactive `/model` command). If `MODEL` is set but the CLI doesn't support it, the flag is silently ignored.
+> **Note**: `--model` support depends on the CLI. `claude` and `cbc` fully support it. If the CLI doesn't support it, the flag is silently ignored.
 
-### Testing AI CLI (`test-cli`)
+### Auto-Detection of Available Models
 
-Use `test-cli` to verify which CLI, version, and model the pipeline will use:
+The pipeline automatically detects which AI models are available for your CLI:
 
 ```bash
-# Basic test — uses auto-detected CLI and default model
-./dev-pipeline/run.sh test-cli
+# Manual detection
+./dev-pipeline/scripts/detect-models.sh
 
-# Test with a specific model
-MODEL=claude-sonnet-4.6 ./dev-pipeline/run.sh test-cli
-
-# Test with a specific CLI
-AI_CLI=cbc ./dev-pipeline/run.sh test-cli
+# Results saved to
+cat .prizmkit/available-models.json
 ```
 
-Example output:
+Detection methods vary by platform:
+
+- **CodeBuddy (cbc)**: Probes the CLI backend for the full list of supported models
+- **Claude Code**: Self-reports the default model (model switching not available)
+
+The pipeline runs detection automatically on:
+
+- `./run.sh run` — before processing features
+- `./retry-feature.sh` — before retrying
+- `git pull` — via post-merge hook (background, non-blocking)
+
+### Model Validation
+
+When `available-models.json` exists, the pipeline validates feature model fields:
+
+- Warns if a specified model is not in the available list
+- Warns if the CLI doesn't support `--model` switching
+- **Never blocks** — validation is advisory only
+
+---
+
+## AI CLI Configuration
+
+The pipeline auto-detects which AI CLI to use. Detection priority:
+
+1. `AI_CLI` environment variable (highest)
+2. `.prizmkit/config.json` → `ai_cli` field
+3. `CODEBUDDY_CLI` environment variable (legacy)
+4. Auto-detect: `cbc` in PATH → `claude` in PATH (lowest)
 
+To permanently configure, create `.prizmkit/config.json`:
+
+```json
+{
+  "ai_cli": "claude",
+  "platform": "claude"
+}
 ```
-============================================
-  Dev-Pipeline AI CLI Test
-============================================
 
-  Detected CLI:    cbc
-  Platform:        codebuddy
-  CLI Version:     2.62.1
+Or override per-invocation:
 
-  Querying AI model (headless mode)...
+```bash
+AI_CLI=claude ./dev-pipeline/run.sh run feature-list.json
+```
 
-  AI Response:     I'm CodeBuddy, running Claude Opus 4.6
+### Testing AI CLI (`test-cli`)
 
-============================================
+```bash
+./dev-pipeline/run.sh test-cli
+MODEL=claude-sonnet-4.6 ./dev-pipeline/run.sh test-cli
+AI_CLI=cbc ./dev-pipeline/run.sh test-cli
 ```
 
-The test sends a one-line prompt asking the AI to identify itself, with a 30-second timeout. If the CLI requires authentication or is unavailable, it shows a fallback message.
+---
 
 ## How It Works
 
-### Execution Flow
+### Feature Pipeline Execution Flow
 
 ```
 run.sh main loop
-  │
-  ├─ detect-stuck.py          # Check for stale/stuck sessions
-  ├─ update-feature-status.py # get_next: find next runnable feature (pending + deps met)
-  │
-  ├─ generate-bootstrap-prompt.py  # Build prompt with feature details + context
-  │
-  ├─ AI CLI session            # cbc --print -y < prompt (CodeBuddy)
-  │   │                        # claude --print -p "$(cat prompt)" --yes (Claude Code)
-  │   └─ prizm-dev-team       # Multi-agent team implements the feature
-  │       ├─ Orchestrator    # Main agent: init, plan, schedule, retrospective, commit
-  │       ├─ Dev x N          # Implementation with TDD
-  │       └─ Reviewer        # Analyze + code review
-  │
-  ├─ check-session-status.py  # Parse session outcome
-  ├─ update-feature-status.py # Update feature state (completed/failed/retry)
-  │
-  └─ loop → next feature
-```
-
-### 10-Phase Pipeline (per feature session)
-
-Each AI CLI session drives the prizm-dev-team through these phases. **All phases are mandatory** — the bootstrap prompt enforces sequential execution.
-
-> **Note**: The bootstrap prompt adapts these phases based on complexity mode (lite/standard/full). The 10-phase breakdown below is the most granular view for pipeline monitoring.
-
-| Phase | Name | Agent | PrizmKit Skills | Artifacts |
-|-------|------|-------|----------------|-----------|
-| 0 | Init | Orchestrator | `prizmkit-init` | `.prizm-docs/root.prizm`, `.prizmkit/config.json` |
-| 1 | Specify | Orchestrator | `prizmkit-specify`, `prizmkit-clarify` | `.prizmkit/specs/spec.md` |
-| 2 | Plan + Tasks | Orchestrator | `prizmkit-plan` | `.prizmkit/specs/plan.md` (含 Tasks section) |
-| 3 | Analyze | Reviewer | `prizmkit-analyze` | Analysis report (no CRITICAL issues) |
-| 4 | Schedule | Orchestrator | — | TaskList entries assigned |
-| 5 | Implement | Dev x N | `prizmkit-implement` | Code + tests, plan.md Tasks marked `[x]` |
-| 6 | Review | Reviewer | `prizmkit-code-review` | Integration tests, review report |
-| 7 | Fix Loop | Dev | — | Max 3 rounds of fixes |
-| 8 | Retrospective & Commit | Orchestrator | `prizmkit-retrospective`, `prizmkit-committer` | .prizm-docs/ synced + enriched, git commit |
+  |
+  +- detect-stuck.py              # Check for stale/stuck sessions
+  +- update-feature-status.py     # get_next: find next runnable feature
+  |
+  +- generate-bootstrap-prompt.py # Build prompt from template + feature
+  |                               # Returns JSON with model field
+  |
+  +- AI CLI session               # claude -p "$(cat prompt)" --dangerously-skip-permissions
+  |   |                           # cbc --print -y < prompt
+  |   +- prizm-dev-team           # Multi-agent team implements the feature
+  |       +- Orchestrator         # Main: init, context, plan, retrospective, commit
+  |       +- Dev x N              # Implementation with TDD
+  |       +- Reviewer             # Analyze + code review
+  |
+  +- check-session-status.py      # Parse session outcome
+  +- update-feature-status.py     # Update feature state (completed/failed/retry)
+  |
+  +- loop -> next feature
+```
+
+### Tiered Execution (per feature session)
+
+The bootstrap prompt adapts based on feature complexity:
+
+| Tier | Template | Agents | Use Case |
+|------|----------|--------|----------|
+| Tier 1 (lite) | `bootstrap-tier1.md` | Single agent handles everything | Low complexity features |
+| Tier 2 (standard) | `bootstrap-tier2.md` | Orchestrator + Dev + Reviewer subagents | Medium complexity |
+| Tier 3 (full) | `bootstrap-tier3.md` | Full team with spec/plan/analyze/implement/review phases | High/critical complexity |
+
+**Self-evolve mode:** Uses Tier 3 template with additional framework guardrails for developing the PrizmKit framework itself.
 
 ### Feature Dependency Resolution
 
-Features are executed in dependency order. The pipeline uses a DAG (Directed Acyclic Graph) to determine which features are runnable:
+Features are executed in dependency order via DAG:
 
-- A feature is **runnable** if status is `pending` and all dependencies are `completed`.
-- A feature is **blocked** if any dependency is not yet `completed`.
-- Features with no remaining runnable features and incomplete blocked features enter a 60s retry wait.
+- **Runnable**: status is `pending` and all dependencies are `completed`
+- **Blocked**: any dependency is not yet `completed`
+- **Pipeline blocked**: no runnable features remain → 60s retry wait
 
 ### Session Lifecycle
 
-1. **Bootstrap prompt** is generated from the feature spec, tech stack context, and acceptance criteria.
-2. The AI CLI is spawned as a background process:
-   - **CodeBuddy**: `cbc --print -y < prompt` (prompt via stdin)
-   - **Claude Code**: `claude --print -p "$(cat prompt)" --yes` (prompt via `-p` argument)
-3. A **timeout watchdog** runs in parallel if `SESSION_TIMEOUT > 0`; kills the session if it exceeds the limit.
-4. A **heartbeat monitor** prints progress every `HEARTBEAT_INTERVAL` seconds (default 30s).
-5. On completion, the script checks for `session-status.json` to determine success/failure.
-6. Feature status is updated. On failure, retry count increments. After `MAX_RETRIES`, the feature is marked failed.
+1. **Bootstrap prompt** generated from feature spec, context, and acceptance criteria
+2. AI CLI spawned as background process with optional `--model` flag
+3. **Timeout watchdog** runs in parallel if `SESSION_TIMEOUT > 0`
+4. **Heartbeat monitor** prints progress every `HEARTBEAT_INTERVAL` seconds
+5. **Progress parser** (if stream-json supported) extracts phase/tool metrics
+6. On completion, `session-status.json` determines success/failure
+7. Feature status updated; on failure, retry count increments
 
 ### Heartbeat Output
 
-While an AI CLI session is running, the pipeline outputs periodic heartbeat lines:
-
 ```
-  ▶ [HEARTBEAT] 1m30s elapsed | log: 245KB (+12480B) | Creating team prizm-dev-team-F-001...
-  ▶ [HEARTBEAT] 2m0s elapsed | log: 389KB (+147456B) | Generating spec.md for feature...
-  ⏸ [HEARTBEAT] 2m30s elapsed | log: 389KB (+0B) | (waiting for AI response)
+  > [HEARTBEAT] 1m30s elapsed | log: 245KB (+12480B) | Creating team prizm-dev-team-F-001...
+  > [HEARTBEAT] 2m0s elapsed | log: 389KB (+147456B) | Generating spec.md for feature...
+  @ [HEARTBEAT] 2m30s elapsed | log: 389KB (+0B) | (waiting for AI response)
 ```
 
-- `▶` (green): log is growing — session is actively producing output
-- `⏸` (yellow): log unchanged since last check — session may be waiting or stuck
-- Shows elapsed time, log file size, growth since last heartbeat, and last log line
+- `>` (green): log is growing — session is actively producing output
+- `@` (yellow): log unchanged — session may be waiting or stuck
 
 ### Monitoring Session Logs
 
-Each AI CLI session 的完整输出（tool 调用、文件读写、代码生成、AI 思考过程）都记录在 session log 中。开一个新终端实时查看：
-
 ```bash
-# 实时跟踪当前正在执行的 session 日志
+# Live tail current session
 tail -f dev-pipeline/state/features/F-*/sessions/*/logs/session.log
 
-# 如果知道具体 feature ID，可以更精确
+# Specific feature
 tail -f dev-pipeline/state/features/F-003/sessions/*/logs/session.log
-```
-
-通过日志可以判断：
-- session 当前在执行哪个 phase
-- 是否在读正确的文件
-- 是否出现幻觉或方向错误
-- 具体卡在什么步骤
 
-session 结束后查看完整日志：
-
-```bash
+# Review completed session
 cat dev-pipeline/state/features/F-003/sessions/F-003-*/logs/session.log | less
 ```
 
 ### Pause & Resume
 
-- **Ctrl+C** during execution triggers graceful shutdown — current state is saved.
-- **Re-running** `./run.sh run feature-list.json` resumes from where it left off. Completed features are skipped.
-- 如需强制从某一阶段继续，可使用：`./run.sh run feature-list.json --resume-phase 6`（例如直接进入实现阶段）。
+- **Ctrl+C** triggers graceful shutdown — current state is saved
+- **Re-running** `./run.sh run` resumes from where it left off (completed features skipped)
+- Force resume from a phase: `./run.sh run feature-list.json --resume-phase 6`
 
 ### Manual Intervention
 
-If a feature fails after max retries, the pipeline blocks. To resolve:
-
 ```bash
 # Check what failed
 ./dev-pipeline/run.sh status feature-list.json
@@ -323,256 +829,202 @@ If a feature fails after max retries, the pipeline blocks. To resolve:
 # Review session logs
 cat dev-pipeline/state/features/F-XXX/sessions/*/logs/session.log
 
-# Option A: Fix manually and mark as complete
+# Option A: Fix manually and mark complete
 python3 dev-pipeline/scripts/update-feature-status.py \
   --feature-list feature-list.json \
   --state-dir dev-pipeline/state \
   --feature-id F-XXX --action complete
 
-# Option B: Reset the feature for retry
+# Option B: Reset for retry
 python3 dev-pipeline/scripts/update-feature-status.py \
   --feature-list feature-list.json \
   --state-dir dev-pipeline/state \
   --feature-id F-XXX --action reset
 
-# Resume pipeline
+# Resume
 ./dev-pipeline/run.sh run feature-list.json
 ```
 
-## Directory Structure
-
-```
-dev-pipeline/
-├── run.sh                        # Main entry point — full pipeline loop
-├── retry-feature.sh              # Retry a single failed feature
-├── reset-feature.sh              # Reset/clean a feature for fresh re-execution
-├── README.md                     # This file
-├── .gitignore                    # Ignores state/ and __pycache__/
-├── scripts/
-│   ├── init-pipeline.py          # Initialize state/ from feature-list.json
-│   ├── init-dev-team.py          # Initialize .dev-team/ and .prizmkit/ directories
-│   ├── generate-bootstrap-prompt.py  # Build per-feature prompt for AI CLI session
-│   ├── check-session-status.py   # Parse session-status.json for outcome
-│   ├── update-feature-status.py  # Update feature state + get_next + status display
-│   └── detect-stuck.py           # Detect stuck/stale sessions by heartbeat
-├── templates/
-│   ├── bootstrap-prompt.md       # Prompt template for AI CLI sessions
-│   ├── feature-list-schema.json  # JSON schema for feature-list.json
-│   └── session-status-schema.json  # JSON schema for session output
-├── assets/
-│   ├── feature-list-example.json # Example feature list (TaskFlow app)
-│   └── prizm-dev-team-integration.md  # How pipeline integrates with prizm-dev-team
-└── state/                        # Runtime state (gitignored, auto-generated)
-    ├── pipeline.json             # Pipeline run metadata
-    ├── current-session.json      # Currently executing session
-    └── features/
-        └── F-XXX/
-            ├── status.json       # Feature status, retry count, session history
-            └── sessions/
-                └── F-XXX-YYYYMMDDHHMMSS/
-                    ├── bootstrap-prompt.md  # Generated prompt for this session
-                    └── logs/
-│                    └── session.log      # Full AI CLI session output
-```
-
-### PrizmKit Artifact Structure (per-feature)
-
-Each feature generates artifacts in a dedicated subdirectory under `.prizmkit/specs/`:
-
-```
-.prizmkit/
-├── config.json                          # PrizmKit configuration
-└── specs/
-    ├── 001-project-infrastructure-setup/
-    │   ├── spec.md                      # Phase 1: Feature specification
-    │   ├── checklists/
-    │   │   └── requirements.md          # Phase 1: Spec quality checklist
-    │   ├── plan.md                      # Phase 2: Implementation plan
-    │   ├── data-model.md               # Phase 2: Data model (if applicable)
-    │   └── contracts/                   # Phase 2: API contracts (if applicable)
-    ├── 002-core-encryption-vault/
-    │   └── ...
-    └── ...
-```
-
-## macOS Compatibility Notes
-
-The original `run.sh` used GNU `timeout` which is not available on macOS by default. The current implementation uses a background process + watchdog pattern instead, which works on both macOS and Linux without additional dependencies.
-
-Key adaptations:
-- The AI CLI is run as a background process with `&`
-- A separate watchdog subshell handles timeout via `sleep + kill`
-- A heartbeat monitor subshell prints periodic progress to the terminal
-- SIGTERM (exit code 143) is mapped to exit code 124 (GNU timeout convention)
-- All cleanup commands use `|| true` to prevent `set -e` from causing silent exits
-
-## Troubleshooting
-
-### Pipeline stops after completing one feature
-
-Check if `set -e` is causing a silent exit. All python script invocations in the main loop should have `|| true` guards. Review `run.sh` for any unguarded commands that might return non-zero.
-
-### Session log is empty
+---
 
-The AI CLI session didn't produce any output. Verify:
-- Your CLI is in PATH and functional:
-  - CodeBuddy: `echo "test" | cbc --print -y`
-  - Claude Code: `claude --print -p "test" --yes`
-- The bootstrap prompt file was generated: check `state/features/F-XXX/sessions/*/bootstrap-prompt.md`
+## Bug Fix Pipeline
 
-### "PIPELINE_BLOCKED" message loops
+The bug fix pipeline provides the same autonomous outer-loop as the feature pipeline, tailored for `bug-fix-list.json`.
 
-All remaining features have unmet dependencies. Check `status` to find which features failed:
+### Quick Start
 
 ```bash
-./dev-pipeline/run.sh status feature-list.json
+# 1. Generate bug fix list (via bug-planner skill)
+# 2. Run foreground
+./dev-pipeline/run-bugfix.sh run bug-fix-list.json
+# 3. Or as daemon
+./dev-pipeline/launch-bugfix-daemon.sh start bug-fix-list.json
+# 4. Check progress
+./dev-pipeline/run-bugfix.sh status bug-fix-list.json
 ```
 
-Then manually complete or reset the blocking feature.
-
-### Feature marked as "crashed"
-
-The AI CLI session exited without producing a `session-status.json`. This typically means the session crashed or the agent didn't write a completion status. The pipeline will retry up to `MAX_RETRIES` times.
-
-### .prizmkit/specs/ is empty after feature completion
-
-The session skipped the PrizmKit artifact generation phases (spec.md, plan.md). This can happen if:
-
-1. **Agent definitions not found**: Check that agent definition files exist
-   - CodeBuddy: `.codebuddy/agents/prizm-dev-team-*.md`
-   - Claude Code: `.claude/agents/prizm-dev-team-*.md`
-2. **Team config missing**: Check that team configuration exists
-   - CodeBuddy: `~/.codebuddy/teams/prizm-dev-team/config.json`
-   - Claude Code: `.claude/team-info.json`
-3. **Session took shortcuts**: The AI CLI session implemented the feature directly without following the 10-phase pipeline
-
-To fix, ensure the agent definitions and team configs are properly installed per the Prizm-Kit-Construct-Guide.md.
+### Bug Fix Execution Flow
 
-## Agent and Team Configuration
+```
+run-bugfix.sh main loop
+  |
+  +- update-bug-status.py          # get_next (severity -> priority order)
+  +- generate-bugfix-prompt.py     # Build prompt from template
+  +- AI CLI session
+  |   +- Phase 1: Triage           (classify, assess, write fix-plan.md)
+  |   +- Phase 2: Reproduce        (create failing reproduction test)
+  |   +- Phase 3: Fix              (TDD — make reproduction test pass)
+  |   +- Phase 4: Verify           (code review + regression tests)
+  |   +- Phase 5: Commit           (commit, TRAPS update, fix-report.md)
+  +- check-session-status.py
+  +- update-bug-status.py
+  +- loop -> next bug
+```
 
-The pipeline expects:
+### Bug Fix Artifacts
 
-**CodeBuddy (CBC):**
+```
+.prizmkit/bugfix/B-001/
++-- fix-plan.md       <- Phase 1 output
++-- fix-report.md     <- Phase 5 output
+```
 
-| Resource | Location | Description |
-|----------|----------|-------------|
-| Agent Definitions | `.codebuddy/agents/prizm-dev-team-*.md` | 2 agent types: dev, reviewer |
-| Team Config | `~/.codebuddy/teams/prizm-dev-team/config.json` | Team runtime configuration |
-| Team Inboxes | `~/.codebuddy/teams/prizm-dev-team/inboxes/` | Agent message inboxes |
+### Bug Fix State Directory
 
-**Claude Code (CC):**
+```
+dev-pipeline/bugfix-state/          # Runtime state (gitignored)
++-- pipeline.json
++-- current-session.json
++-- bugs/B-XXX/
+    +-- status.json
+    +-- sessions/B-XXX-YYYYMMDDHHMMSS/
+        +-- bootstrap-prompt.md
+        +-- logs/session.log
+```
 
-| Resource | Location | Description |
-|----------|----------|-------------|
-| Agent Definitions | `.claude/agents/prizm-dev-team-*.md` | 2 agent types: dev, reviewer |
-| Team Config | `.claude/team-info.json` | Team runtime configuration (project-level) |
+### Pipeline Comparison
 
-The `generate-bootstrap-prompt.py` script resolves these paths automatically. If paths are incorrect, check the `build_replacements()` function in that script.
+| Aspect | Feature Pipeline | Bug Fix Pipeline |
+|--------|-----------------|------------------|
+| Input file | `feature-list.json` | `bug-fix-list.json` |
+| ID format | `F-NNN` | `B-NNN` |
+| State dir | `state/` | `bugfix-state/` |
+| Ordering | Dependencies DAG + priority | Severity + priority (no deps) |
+| Phases | Tiered (3-10 phases) | 5-phase (triage-reproduce-fix-verify-commit) |
+| Commit prefix | `feat(<scope>):` | `fix(<scope>):` |
+| Test strategy | TDD per task | Reproduction test |
 
 ---
 
-## Bug Fix Pipeline (Outer Automation)
+## Directory Structure
 
-The bug fix pipeline provides the same autonomous outer-loop automation as the feature pipeline, but tailored for bug fixes from a `bug-fix-list.json`.
+```
+dev-pipeline/
++-- run.sh                           # Main pipeline runner (features)
++-- retry-feature.sh                 # Retry single failed feature
++-- reset-feature.sh                 # Reset/clean feature for re-execution
++-- launch-daemon.sh                 # Background daemon for feature pipeline
++-- run-bugfix.sh                    # Bug-fix pipeline runner
++-- retry-bug.sh                     # Retry single failed bug
++-- launch-bugfix-daemon.sh          # Background daemon for bugfix pipeline
++-- README.md                        # This file
++-- .gitignore                       # Ignores state/, bugfix-state/, __pycache__/
+|
++-- lib/
+|   +-- common.sh                    # CLI detection, deps check, logging helpers
+|   +-- branch.sh                    # Git branch create/return lifecycle
+|   +-- heartbeat.sh                 # Heartbeat monitor + progress parser management
+|
++-- scripts/
+|   +-- utils.py                     # Shared Python utilities (JSON I/O, logging)
+|   +-- init-pipeline.py             # Validate feature-list.json + create state/
+|   +-- init-bugfix-pipeline.py      # Validate bug-fix-list.json + create bugfix-state/
+|   +-- init-dev-team.py             # Create .prizmkit/specs/{slug}/ directories
+|   +-- generate-bootstrap-prompt.py # Render feature session prompt from template
+|   +-- generate-bugfix-prompt.py    # Render bugfix session prompt from template
+|   +-- check-session-status.py      # Parse session-status.json outcome
+|   +-- update-feature-status.py     # Feature state machine (8 actions)
+|   +-- update-bug-status.py         # Bug state machine (6 actions)
+|   +-- detect-stuck.py              # Detect stuck/stale features
+|   +-- cleanup-logs.py              # Age/size-based log cleanup
+|   +-- parse-stream-progress.py     # Real-time stream-json progress parser
+|
++-- templates/
+|   +-- bootstrap-tier1.md           # Tier 1 prompt template (single agent, lite)
+|   +-- bootstrap-tier2.md           # Tier 2 prompt template (dual agent, standard)
+|   +-- bootstrap-tier3.md           # Tier 3 prompt template (full team, full/self-evolve)
+|   +-- bootstrap-prompt.md          # Legacy monolithic template (fallback)
+|   +-- bugfix-bootstrap-prompt.md   # Bug-fix session prompt template
+|   +-- agent-knowledge-template.md  # Template for agent knowledge docs
+|   +-- feature-list-schema.json     # JSON schema for feature-list.json
+|   +-- bug-fix-list-schema.json     # JSON schema for bug-fix-list.json
+|   +-- session-status-schema.json   # JSON schema for session-status.json
+|
++-- assets/
+|   +-- feature-list-example.json    # Example feature list
+|   +-- prizm-dev-team-integration.md # Pipeline + prizm-dev-team integration docs
+|
++-- tests/
+|   +-- conftest.py                  # Pytest configuration
+|   +-- test_generate_bootstrap_prompt.py  # Tests for prompt generation
+|   +-- test_generate_bugfix_prompt.py     # Tests for bugfix prompt generation
+|   +-- test_utils.py                # Tests for shared utilities
+|
++-- state/                           # Feature pipeline runtime state (gitignored)
+|   +-- pipeline.json
+|   +-- current-session.json
+|   +-- .pipeline.pid                # Daemon PID file
+|   +-- .pipeline-meta.json          # Daemon metadata
+|   +-- pipeline-daemon.log          # Daemon log (50MB rotation)
+|   +-- features/F-XXX/
+|       +-- status.json
+|       +-- sessions/F-XXX-YYYYMMDDHHMMSS/
+|           +-- bootstrap-prompt.md
+|           +-- logs/session.log
+|
++-- bugfix-state/                    # Bug pipeline runtime state (gitignored)
+    +-- (same structure as state/ but with bugs/B-XXX/)
+```
 
-### Quick Start
+---
 
-```bash
-# 1. Generate bug fix list (via bug-planner skill in an AI CLI session)
-#    Output: bug-fix-list.json in project root
+## Agent and Team Configuration
 
-# 2. Run the bugfix pipeline (foreground)
-./dev-pipeline/run-bugfix.sh run bug-fix-list.json
+| Platform | Agent Definitions | Team Config |
+|----------|------------------|-------------|
+| Claude Code | `.claude/agents/prizm-dev-team-*.md` | `.claude/team-info.json` |
+| CodeBuddy | `.codebuddy/agents/prizm-dev-team-*.md` | `~/.codebuddy/teams/prizm-dev-team/config.json` |
 
-# 3. Or run as a background daemon
-./dev-pipeline/launch-bugfix-daemon.sh start bug-fix-list.json
+Agent files are 2 types: `prizm-dev-team-dev.md` (implementation) and `prizm-dev-team-reviewer.md` (review). Paths are auto-resolved by `generate-bootstrap-prompt.py`.
 
-# 4. Check progress
-./dev-pipeline/run-bugfix.sh status bug-fix-list.json
-```
+---
 
-### Bug Fix Commands
+## macOS Compatibility
 
-| Command | Description |
-|---------|-------------|
-| `./run-bugfix.sh run [bug-fix-list.json]` | Run all bugs by severity/priority order |
-| `./run-bugfix.sh run <bug-id> [options]` | Run a single bug fix |
-| `./run-bugfix.sh status [bug-fix-list.json]` | Display bug fix pipeline status |
-| `./run-bugfix.sh reset` | Clear all bugfix runtime state |
-| `./retry-bug.sh <bug-id> [bug-fix-list.json]` | Retry a single failed bug fix |
-| `./launch-bugfix-daemon.sh start [bug-fix-list.json]` | Start bugfix pipeline in background |
-| `./launch-bugfix-daemon.sh stop` | Gracefully stop the bugfix daemon |
-| `./launch-bugfix-daemon.sh status` | Check daemon status with progress JSON |
-| `./launch-bugfix-daemon.sh logs --follow` | Live tail daemon logs |
+Uses a background process + watchdog pattern instead of GNU `timeout`:
+- AI CLI runs as `&` background process
+- Watchdog subshell handles timeout via `sleep + kill`
+- SIGTERM (exit 143) mapped to exit 124 (GNU timeout convention)
+- All cleanup uses `|| true` to prevent `set -e` issues
 
-### Bug Fix Execution Flow
+---
 
-```
-run-bugfix.sh main loop
-  │
-  ├─ update-bug-status.py        # get_next: find next bug (by severity → priority)
-  │
-  ├─ generate-bugfix-prompt.py   # Build prompt from bugfix-bootstrap-prompt.md template
-  │
-  ├─ AI CLI session               # cbc --print -y < prompt (CBC)
-  │   │                            # claude --print -p "$(cat prompt)" --yes (CC)
-  │   └─ bugfix 5-phase workflow
-  │       ├─ Phase 1: Triage      (Dev agent: classify, assess impact, write fix-plan.md)
-  │       ├─ Phase 2: Reproduce   (Dev agent: create failing reproduction test)
-  │       ├─ Phase 3: Fix         (Dev agent: TDD — make reproduction test pass)
-  │       ├─ Phase 4: Verify      (Reviewer agent: code review + regression tests)
-  │       └─ Phase 5: Commit      (Dev agent: commit, update TRAPS, write fix-report.md)
-  │
-  ├─ check-session-status.py     # Parse session outcome
-  ├─ update-bug-status.py        # Update bug state (completed/failed/retry)
-  │
-  └─ loop → next bug
-```
-
-### Bug Priority Resolution
-
-Bugs are processed in this order:
-1. **Severity** first: `critical` > `high` > `medium` > `low`
-2. **Priority field** second: lower number = higher priority
-3. **In-progress** bugs (interrupted sessions) are resumed before pending bugs
+## Troubleshooting
 
-### Bug Fix Artifacts
+### Pipeline stops after one feature
+Check `set -e` interactions. All python invocations in the main loop should have `|| true` guards.
 
-Each bug fix produces exactly 2 artifacts:
+### Session log is empty
+Verify CLI is functional: `claude -p "test" --dangerously-skip-permissions` or `echo "test" | cbc --print -y`
 
-```
-.prizmkit/bugfix/B-001/
-├── fix-plan.md       ← Phase 1 output
-└── fix-report.md     ← Phase 5 output
-```
+### "PIPELINE_BLOCKED" loops
+All remaining features have unmet dependencies. Use `./run.sh status` to find the blocking feature, then reset or manually complete it.
 
-### Bug Fix State Directory
+### Feature marked as "crashed"
+Session exited without `session-status.json`. Pipeline retries up to `MAX_RETRIES` times automatically.
 
-```
-dev-pipeline/bugfix-state/        # Runtime state (gitignored)
-├── pipeline.json                 # Pipeline run metadata
-├── current-session.json          # Currently executing session
-└── bugs/
-    └── B-XXX/
-        ├── status.json           # Bug status, retry count, session history
-        └── sessions/
-            └── B-XXX-YYYYMMDDHHMMSS/
-                ├── bootstrap-prompt.md  # Generated prompt for this session
-                └── logs/
-                    └── session.log      # Full session output
-```
-
-### Differences Between Pipelines
-
-| Aspect | Feature Pipeline | Refactor Workflow | Bug Fix Pipeline |
-|--------|-----------------|-------------------|------------------|
-| Input file | `feature-list.json` | N/A (conversation trigger) | `bug-fix-list.json` |
-| ID format | `F-NNN` | `<refactor-slug>` | `B-NNN` |
-| State dir | `state/` | N/A (in-session) | `bugfix-state/` |
-| Ordering | Dependencies DAG → priority | N/A (single refactor per session) | Severity → priority (no dependencies) |
-| Phases | 10-phase (specify → plan → tasks → implement → review) | 6-phase (analyze → plan → tasks → implement → review → commit) | 5-phase (triage → reproduce → fix → verify → commit) |
-| Agents | Orchestrator + Dev + Reviewer | Dev + Reviewer only | Dev + Reviewer only |
-| Artifacts | spec.md, plan.md (with Tasks section) | refactor-analysis.md, plan.md (with Tasks section) | fix-plan.md, fix-report.md only |
-| Commit prefix | `feat(<scope>):` | `refactor(<scope>):` | `fix(<scope>):` |
-| Scope Guard | N/A | ✅ (behavior change → STOP) | N/A |
-| Test Strategy | TDD per task | Full suite after EVERY task | Reproduction test |
+### Context window exhaustion (session crash mid-implementation)
+The bootstrap templates include Context Budget Rules to minimize context consumption. If crashes persist:
+1. Set a per-feature model with larger context: `"model": "claude-opus-4.6"`
+2. Reduce feature scope / split into smaller features
+3. Check session log for unnecessary file reads or large tool outputs