prizmkit 1.1.153 → 1.1.154

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.153",
-  "bundledAt": "2026-07-26T05:44:00.463Z",
-  "bundledFrom": "54bad91"
+  "frameworkVersion": "1.1.154",
+  "bundledAt": "2026-07-26T11:39:59.047Z",
+  "bundledFrom": "1d81b9b"
 }

package/bundled/dev-pipeline/README.md

@@ -14,21 +14,20 @@ Autonomous development pipeline that drives iterative AI CLI sessions through Pr
 
 ### Unified Python CLI prerequisites
 
-- Python 3.10+ for the unified Python CLI skeleton under `dev-pipeline/cli.py`
-- No third-party Python runtime packages are required by the CLI skeleton
-- The existing Python runtime is canonical for behavior while parity-based Python porting proceeds
+- Python 3.10+ for the canonical Python CLI under `dev-pipeline/cli.py`
+- No third-party Python runtime packages are required
+- The Python runtime is the sole behavior source; retired shell and PowerShell wrappers are not compatibility entrypoints
 
-Inspect the transition command surface without invoking legacy shell wrappers:
+Inspect the operation-first command surface without dispatching runtime behavior:
 
 ```bash
 python3 dev-pipeline/cli.py --help
-python3 dev-pipeline/cli.py diagnostics paths
-python3 dev-pipeline/cli.py diagnostics entrypoints
-python3 dev-pipeline/cli.py feature describe
-python3 dev-pipeline/cli.py daemon feature describe
+python3 dev-pipeline/cli.py run --help
+python3 dev-pipeline/cli.py status --help
+python3 dev-pipeline/cli.py diagnostics ai-cli
 ```
 
-The unified CLI currently describes command contracts for feature, bugfix, refactor, recovery, reset, daemon, status, and diagnostics flows. It is an architecture skeleton and transition layer; it does not yet replace the shell implementation for runtime behavior.
+The public namespaces are `run`, `status`, `reset`, `daemon`, `diagnostics`, and `helper`. Standard `--help` is the only command-description interface; family names are targets, not top-level namespaces.
 
 ## Quick Start
 
@@ -42,10 +41,10 @@ python3 .prizmkit/dev-pipeline/scripts/init-pipeline.py \
   --state-dir .prizmkit/state/features
 
 # 3. Run the pipeline (foreground, Ctrl+C to pause, re-run to resume)
-python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py run feature .prizmkit/plans/feature-list.json
 
 # 4. Check progress at any time (from another terminal)
-python3 ./.prizmkit/dev-pipeline/cli.py feature status .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py status feature .prizmkit/plans/feature-list.json
 
 # 5. Or run as a background daemon
 python3 ./.prizmkit/dev-pipeline/cli.py daemon feature start .prizmkit/plans/feature-list.json
@@ -55,17 +54,17 @@ python3 ./.prizmkit/dev-pipeline/cli.py daemon feature start .prizmkit/plans/fea
 
 ## Python Runtime CLI Reference
 
-### `cli.py feature` — Feature Pipeline Runner
+### `cli.py run feature` — Feature Pipeline Runner
 
-Main entry point. Drives the full feature development pipeline.
+Main foreground entry point for the feature pipeline.
 
 ```bash
-python3 ./cli.py feature run [.prizmkit/plans/feature-list.json]                # Run all features
-python3 ./cli.py feature run <feature-id> [options]             # Run a single feature (F-NNN)
-python3 ./cli.py feature status [.prizmkit/plans/feature-list.json]             # Show pipeline status
-python3 ./cli.py reset feature                                  # Clear all state in state/
-python3 ./cli.py feature test-cli                               # Test AI CLI detection
-python3 ./cli.py feature help                                   # Show usage help
+python3 ./cli.py run feature [.prizmkit/plans/feature-list.json]                # Run all features
+python3 ./cli.py run feature <feature-id> [options]             # Run a single feature (F-NNN)
+python3 ./cli.py status feature [.prizmkit/plans/feature-list.json]             # Show feature status
+python3 ./cli.py reset feature <feature-id> --state-only        # Recover causal state without Git/artifact cleanup
+python3 ./cli.py diagnostics ai-cli                             # Inspect AI CLI resolution
+python3 ./cli.py run feature --help                             # Show parser-owned usage help
 ```
 
 **Single-feature options:**
@@ -80,59 +79,74 @@ python3 ./cli.py feature help                                   # Show usage hel
 
 ```bash
 # Run all features
-python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py run feature .prizmkit/plans/feature-list.json
 
 # Run a single feature
-python3 ./.prizmkit/dev-pipeline/cli.py feature run F-007
+python3 ./.prizmkit/dev-pipeline/cli.py run feature F-007
 
 # Dry run — inspect the generated prompt without spawning a session
-python3 ./.prizmkit/dev-pipeline/cli.py feature run F-007 --dry-run
+python3 ./.prizmkit/dev-pipeline/cli.py run feature F-007 --dry-run
 
 # Resume from Phase 6 (implementation)
-python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json --resume-phase 6
+python3 ./.prizmkit/dev-pipeline/cli.py run feature .prizmkit/plans/feature-list.json --resume-phase 6
 ```
 
 If `.prizmkit/plans/feature-list.json` path is omitted, defaults to `.prizmkit/plans/feature-list.json` in the project root.
 
 ---
 
-### `cli.py reset feature` — Reset Feature Recovery State
+### `cli.py reset <family>` — Explicit Recovery and Cleanup Modes
 
-Reset is state-only and never starts execution. `--run` is unsupported; invoke `feature run` separately after a successful reset.
+Reset never starts execution and rejects `--run`; invoke the matching `run <family>` command separately. Every invocation must select exactly one mode before the runtime will inspect mutable pipeline state or Git resources.
 
 ```bash
-python3 ./cli.py reset feature <feature-id> [--clean] [.prizmkit/plans/feature-list.json]
-python3 ./cli.py reset feature --failed --preserve-runtime [.prizmkit/plans/feature-list.json]
+python3 ./cli.py reset <family> <item-id> --state-only [list-path]
+python3 ./cli.py reset <family> --state-only --all [list-path]
+python3 ./cli.py reset <family> <item-id-or-range> --fresh-checkout [list-path]
+python3 ./cli.py reset <family> <--auto-skipped|--failed|--stalled> --fresh-checkout [list-path]
+python3 ./cli.py reset <family> <item-id-or-range> --clean [list-path]
+python3 ./cli.py reset <family> <--auto-skipped|--failed|--stalled> --clean [list-path]
+python3 ./cli.py reset <family> --failed --preserve-runtime [list-path]
 ```
 
-| Flag | Description |
-|------|-------------|
-| `--clean` | Delete the task branch, session history, and `.prizmkit/specs/{slug}/` artifacts |
-| `--failed --preserve-runtime` | Restore every failed chain in the list while retaining checkout identity, branches/worktrees, sessions, checkpoints, artifacts, and WIP |
+| Mode | Selector and effect |
+|------|---------------------|
+| `--state-only` | Requires one ID or explicit `--all`. Resets supported blocking roots and only causal `auto_skipped` descendants whose full blocker set is recovered; preserves checkout identity, branches/worktrees, source changes, checkpoints, and artifact/session files. Feature/Refactor roots are `failed` or `skipped`; Bugfix additionally supports `needs_info`. |
+| `--fresh-checkout` | Requires one ID, range, or supported status filter. Performs the former standard reset, may discard active-checkout WIP, and publishes a new checkout boundary without deleting the task branch. |
+| `--clean` | Accepts the fresh-checkout selectors and additionally deletes task branches, session history, continuation summaries, and task artifacts. |
+| `--failed --preserve-runtime` | Whole-list failed-only recovery. Retains runtime history, valid checkout identity, branches/worktrees, checkpoints, artifacts, and WIP; a missing recorded branch is replaced from its local base and implementation-and-later checkpoints are rewound. |
 
-`--preserve-runtime` requires `--failed` and cannot be combined with `--clean`, an item ID/range, or another reset filter. It restores every `failed` root plus causal `auto_skipped` descendants, clears code/infrastructure retry counters, and marks continuation pending without clearing existing history or failure metadata. Valid checkout/branch/worktree/checkpoint identity is reused unchanged; when the recorded branch is missing, reset creates a replacement from the recorded base, retains old artifacts for reference, and rewinds implementation-and-later checkpoint stages to `pending`.
+State-only rejects ranges and status filters. Preserve-runtime rejects IDs, ranges, `--all`, clean, other modes, and other filters. Missing modes, conflicting modes, unsupported selectors, and malformed causal dependency state fail before mutation.
 
 **Examples:**
 
 ```bash
-# Preserve all failed runtime chains, then execute separately
-python3 ./.prizmkit/dev-pipeline/cli.py reset feature --failed --preserve-runtime
-python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json
+# Recover one causal state chain without changing Git/checkpoints/artifact files
+python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-007 --state-only
+python3 ./.prizmkit/dev-pipeline/cli.py run feature F-007
 
-# Fresh single-feature reset, then execute separately
-python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-007
-python3 ./.prizmkit/dev-pipeline/cli.py feature run F-007
+# Recover all causal state chains
+python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix --state-only --all
+python3 ./.prizmkit/dev-pipeline/cli.py run bugfix .prizmkit/plans/bug-fix-list.json
 
-# Destructive clean reset, then execute separately
+# Preserve all failed runtime chains
+python3 ./.prizmkit/dev-pipeline/cli.py reset refactor --failed --preserve-runtime
+python3 ./.prizmkit/dev-pipeline/cli.py run refactor .prizmkit/plans/refactor-list.json
+
+# Publish a fresh checkout boundary
+python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-007 --fresh-checkout
+python3 ./.prizmkit/dev-pipeline/cli.py run feature F-007
+
+# Destructive clean reset
 python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-007 --clean my-features.json
-python3 ./.prizmkit/dev-pipeline/cli.py feature run F-007 my-features.json
+python3 ./.prizmkit/dev-pipeline/cli.py run feature F-007 my-features.json
 ```
 
 ---
 
 ### `cli.py daemon feature` — Feature Pipeline Daemon
 
-Manages `cli.py feature` as a background daemon process with PID tracking and log consolidation. Designed for invocation from AI skill sessions.
+Manages `cli.py run feature` as a background daemon process with PID tracking and log consolidation. Designed for invocation from AI skill sessions.
 
 ```bash
 python3 ./cli.py daemon feature start [.prizmkit/plans/feature-list.json] [--mode <mode>] [--env "KEY=VAL ..."]
@@ -140,7 +154,7 @@ python3 ./cli.py daemon feature stop
 python3 ./cli.py daemon feature status
 python3 ./cli.py daemon feature logs [--lines N] [--follow]
 python3 ./cli.py daemon feature restart [.prizmkit/plans/feature-list.json] [--mode <mode>] [--env "KEY=VAL ..."]
-python3 ./cli.py daemon feature help
+python3 ./cli.py daemon feature --help
 ```
 
 | Subcommand | Description |
@@ -183,19 +197,19 @@ python3 ./.prizmkit/dev-pipeline/cli.py daemon feature start .prizmkit/plans/fea
 
 ---
 
-### `cli.py bugfix` — Bug-Fix Pipeline Runner
+### `cli.py run bugfix` — Bug-Fix Pipeline Runner
 
-Equivalent to `cli.py feature` but for the bug-fix pipeline.
+Uses the same operation-first foreground contract as `cli.py run feature`.
 
 ```bash
-python3 ./cli.py bugfix run [.prizmkit/plans/bug-fix-list.json]         # Run all bugs
-python3 ./cli.py bugfix run <bug-id> [options]           # Run single bug (B-NNN)
-python3 ./cli.py bugfix status [.prizmkit/plans/bug-fix-list.json]       # Show status
-python3 ./cli.py reset bugfix                            # Clear all bugfix state
-python3 ./cli.py bugfix help
+python3 ./cli.py run bugfix [.prizmkit/plans/bug-fix-list.json]         # Run all bugs
+python3 ./cli.py run bugfix <bug-id> [options]           # Run single bug (B-NNN)
+python3 ./cli.py status bugfix [.prizmkit/plans/bug-fix-list.json]       # Show status
+python3 ./cli.py reset bugfix <bug-id> --state-only      # Recover causal Bugfix state
+python3 ./cli.py run bugfix --help
 ```
 
-**Single-bug options:** `--dry-run` (same as `cli.py feature`)
+**Single-bug options:** `--dry-run` (same as `cli.py run feature`)
 
 Processes bugs by: **severity** (critical > high > medium > low) then **priority** (high > medium > low).
 
@@ -203,7 +217,7 @@ Processes bugs by: **severity** (critical > high > medium > low) then **priority
 
 ### `cli.py daemon bugfix` — Bug-Fix Pipeline Daemon
 
-Identical interface to `cli.py daemon feature` but manages `cli.py bugfix` in background.
+Identical interface to `cli.py daemon feature` but manages `cli.py run bugfix` in background.
 
 ```bash
 python3 ./cli.py daemon bugfix start [.prizmkit/plans/bug-fix-list.json] [--env "KEY=VAL ..."]
@@ -309,7 +323,7 @@ python3 scripts/generate-bootstrap-prompt.py \
 { "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 .prizmkit/plans/feature-list.json (empty string if not specified). Used by `cli.py feature` to set `--model` on the AI CLI.
+The `model` field is extracted from the feature's `"model"` field in .prizmkit/plans/feature-list.json (empty string if not specified). Used by `cli.py run feature` to set `--model` on the AI CLI.
 
 **Conditional blocks resolved for explicit legacy templates:**
 - `{{IF_RESUME}}` / `{{IF_FRESH_START}}` — Resume vs fresh start
@@ -531,10 +545,10 @@ Also exports: `log_info`, `log_warn`, `log_error`, `log_success` (with timestamp
 
 | Variable | Default | Used By | Description |
 |----------|---------|---------|-------------|
-| `MAX_RETRIES` | `3` | cli.py feature | Max retry attempts per feature before marking as failed |
-| `PIPELINE_MODE` | (auto) | cli.py feature, cli.py daemon feature | Override mode for all features: `lite\|standard\|full` |
-| `DEV_BRANCH` | auto-generated | cli.py feature | Custom git branch name (default: `dev/{feature-id}-{timestamp}`) |
-| `AUTO_PUSH` | `0` | cli.py feature | Set to `1` to auto-push branch to remote after successful session |
+| `MAX_RETRIES` | `3` | cli.py run feature | Max retry attempts per feature before marking as failed |
+| `PIPELINE_MODE` | (auto) | cli.py run feature, cli.py daemon feature | Override mode for all features: `lite\|standard\|full` |
+| `DEV_BRANCH` | auto-generated | cli.py run feature | Custom git branch name (default: `dev/{feature-id}-{timestamp}`) |
+| `AUTO_PUSH` | `0` | cli.py run feature | Set to `1` to auto-push branch to remote after successful session |
 
 ### AI CLI Configuration
 
@@ -542,23 +556,23 @@ Also exports: `log_info`, `log_warn`, `log_error`, `log_success` (with timestamp
 |----------|---------|---------|-------------|
 | `AI_CLI` | auto-detect | Python runtime | AI CLI command name. Auto-detects `cbc`, `claude`, or `codex` |
 | `PRIZMKIT_PLATFORM` | auto-detect | Python runtime | Platform hint for custom/wrapped AI CLI commands: `codebuddy`, `claude`, or `codex` |
-| `MODEL` | (none) | cli.py feature, cli.py bugfix | AI model fallback. Overridden by per-feature `model` field. See [Model Selection](#model-selection) |
+| `MODEL` | (none) | cli.py run feature, cli.py run bugfix | AI model fallback. Overridden by per-feature `model` field. See [Model Selection](#model-selection) |
 | `CODEBUDDY_CLI` | (deprecated) | Python runtime | Legacy alias for `AI_CLI`. Prefer `AI_CLI` |
-| `VERBOSE` | `0` | cli.py feature | Set to `1` to enable `--verbose` on AI CLI |
+| `VERBOSE` | `0` | cli.py run feature | Set to `1` to enable `--verbose` on AI CLI |
 
 ### Monitoring & Logging
 
 | Variable | Default | Used By | Description |
 |----------|---------|---------|-------------|
-| `HEARTBEAT_INTERVAL` | `30` | cli.py feature | Seconds between heartbeat log output |
-| `HEARTBEAT_STALE_THRESHOLD` | `600` | cli.py feature | Seconds before a session is considered stale/stuck |
+| `HEARTBEAT_INTERVAL` | `30` | cli.py run feature | Seconds between heartbeat log output |
+| `HEARTBEAT_STALE_THRESHOLD` | `600` | cli.py run feature | Seconds before a session is considered stale/stuck |
 
 **Examples:**
 
 ```bash
 # All env vars in one invocation
 MAX_RETRIES=5 MODEL=claude-sonnet-4.6 VERBOSE=1 \
-  python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json
+  python3 ./.prizmkit/dev-pipeline/cli.py run feature .prizmkit/plans/feature-list.json
 
 # Via daemon with --env
 python3 ./.prizmkit/dev-pipeline/cli.py daemon feature start .prizmkit/plans/feature-list.json \
@@ -598,14 +612,14 @@ Specify a model for individual features in `.prizmkit/plans/feature-list.json`:
 
 ```bash
 # All features without a per-feature model use Sonnet
-MODEL=claude-sonnet-4.6 python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json
+MODEL=claude-sonnet-4.6 python3 ./.prizmkit/dev-pipeline/cli.py run feature .prizmkit/plans/feature-list.json
 
 # Destructively reset, then retry with Opus as a separate run
 python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-007 --clean
-MODEL=claude-opus-4.6 python3 ./.prizmkit/dev-pipeline/cli.py feature run F-007
+MODEL=claude-opus-4.6 python3 ./.prizmkit/dev-pipeline/cli.py run feature F-007
 
-# Test which model the CLI is using
-MODEL=claude-sonnet-4.6 python3 ./.prizmkit/dev-pipeline/cli.py feature test-cli
+# Inspect the resolved global AI CLI and model
+MODEL=claude-sonnet-4.6 python3 ./.prizmkit/dev-pipeline/cli.py diagnostics ai-cli
 ```
 
 ### Dry-Run Model Verification
@@ -613,7 +627,7 @@ MODEL=claude-sonnet-4.6 python3 ./.prizmkit/dev-pipeline/cli.py feature test-cli
 Use `--dry-run` to verify which model will be used without spawning a session:
 
 ```bash
-python3 ./.prizmkit/dev-pipeline/cli.py feature run F-017 --dry-run
+python3 ./.prizmkit/dev-pipeline/cli.py run feature F-017 --dry-run
 # Output includes: "Feature Model: claude-opus-4.6"
 ```
 
@@ -652,15 +666,15 @@ To permanently configure, create `.prizmkit/config.json`:
 Or override per-invocation:
 
 ```bash
-AI_CLI=claude python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json
+AI_CLI=claude python3 ./.prizmkit/dev-pipeline/cli.py run feature .prizmkit/plans/feature-list.json
 ```
 
-### Testing AI CLI (`test-cli`)
+### AI CLI Diagnostics
 
 ```bash
-python3 ./.prizmkit/dev-pipeline/cli.py feature test-cli
-MODEL=claude-sonnet-4.6 python3 ./.prizmkit/dev-pipeline/cli.py feature test-cli
-AI_CLI=cbc python3 ./.prizmkit/dev-pipeline/cli.py feature test-cli
+python3 ./.prizmkit/dev-pipeline/cli.py diagnostics ai-cli
+MODEL=claude-sonnet-4.6 python3 ./.prizmkit/dev-pipeline/cli.py diagnostics ai-cli
+AI_CLI=cbc python3 ./.prizmkit/dev-pipeline/cli.py diagnostics ai-cli
 ```
 
 ---
@@ -670,7 +684,7 @@ AI_CLI=cbc python3 ./.prizmkit/dev-pipeline/cli.py feature test-cli
 ### Feature Pipeline Execution Flow
 
 ```
-cli.py feature run command
+cli.py run feature command
   |
   +- detect-stuck.py              # Check for stale/stuck sessions
   +- update-feature-status.py     # get_next: find next runnable feature
@@ -749,14 +763,14 @@ cat .prizmkit/state/features/F-003/sessions/F-003-*/logs/session.log | less
 ### Pause & Resume
 
 - **Ctrl+C** triggers graceful shutdown — current state is saved
-- **Re-running** `python3 ./cli.py feature run` resumes from where it left off (completed features skipped)
-- Force resume from a phase: `python3 ./cli.py feature run .prizmkit/plans/feature-list.json --resume-phase 6`
+- **Re-running** `python3 ./cli.py run feature` resumes from where it left off (completed features skipped)
+- Force resume from a phase: `python3 ./cli.py run feature .prizmkit/plans/feature-list.json --resume-phase 6`
 
 ### Manual Intervention
 
 ```bash
 # Check what failed
-python3 ./.prizmkit/dev-pipeline/cli.py feature status .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py status feature .prizmkit/plans/feature-list.json
 
 # Review session logs
 cat .prizmkit/state/features/F-XXX/sessions/*/logs/session.log
@@ -774,7 +788,7 @@ python3 .prizmkit/dev-pipeline/scripts/update-feature-status.py \
   --feature-id F-XXX --action reset
 
 # Resume
-python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py run feature .prizmkit/plans/feature-list.json
 ```
 
 ---
@@ -788,17 +802,17 @@ The bug fix pipeline provides the same autonomous outer-loop as the feature pipe
 ```bash
 # 1. Generate bug fix list (via bug-planner skill)
 # 2. Run foreground
-python3 ./.prizmkit/dev-pipeline/cli.py bugfix run .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py run bugfix .prizmkit/plans/bug-fix-list.json
 # 3. Or as daemon
 python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix start .prizmkit/plans/bug-fix-list.json
 # 4. Check progress
-python3 ./.prizmkit/dev-pipeline/cli.py bugfix status .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py status bugfix .prizmkit/plans/bug-fix-list.json
 ```
 
 ### Bug Fix Execution Flow
 
 ```
-cli.py bugfix run command
+cli.py run bugfix command
   |
   +- update-bug-status.py          # get_next (severity -> priority order)
   +- generate-bugfix-prompt.py     # Build prompt from template
@@ -851,13 +865,12 @@ cli.py bugfix run command
 
 ```
 .prizmkit/dev-pipeline/
-+-- cli.py feature                           # Main pipeline runner (features)
-+-- cli.py reset feature                 # Reset & retry failed feature
-+-- cli.py reset feature                 # Reset/clean feature for re-execution
-+-- cli.py daemon feature                 # Background daemon for feature pipeline
-+-- cli.py bugfix                    # Bug-fix pipeline runner
-+-- cli.py reset bugfix                     # Reset & retry failed bug
-+-- cli.py daemon bugfix          # Background daemon for bugfix pipeline
++-- cli.py run <family>               # Foreground feature/bugfix/refactor runners
++-- cli.py status <family|all>          # Read-only family or aggregate status
++-- cli.py reset <family>               # Explicit state-only/fresh/clean/preserve reset modes
++-- cli.py daemon <family>              # Background daemon lifecycle
++-- cli.py diagnostics <action>         # Paths, entrypoints, version, and AI CLI resolution
++-- cli.py helper                       # Low-level cross-platform helper commands
 +-- README.md                        # This file
 +-- .gitignore                       # Ignores .prizmkit/state/, __pycache__/
 |
@@ -945,7 +958,7 @@ Check `set -e` interactions. All python invocations in the main loop should have
 Verify CLI is functional: `claude -p "test" --dangerously-skip-permissions`, `echo "test" | cbc --print -y`, or `echo "test" | codex --ask-for-approval never --sandbox danger-full-access exec --skip-git-repo-check -`
 
 ### "PIPELINE_BLOCKED" loops
-All remaining features have unmet dependencies. Use `python3 ./cli.py feature status` to find the blocking feature, then reset or manually complete it.
+All remaining features have unmet dependencies. Use `python3 ./cli.py status feature` to find the blocking feature, then reset or manually complete it.
 
 ### Feature marked as "crashed"
 Session exited without `session-status.json`. Pipeline retries up to `MAX_RETRIES` times automatically.

package/bundled/dev-pipeline/assets/skill-subagent-integration.md

@@ -15,7 +15,7 @@ Skill behavior is owned by canonical skills:
 ```text
 dev-pipeline (outer loop)
     |
-    +-- cli.py feature/bugfix/refactor       Python runtime CLI — picks next item, starts CLI
+    +-- cli.py run <family>                 Python runtime CLI — picks next item, starts CLI
     +-- scripts/                             Python state and prompt management scripts
     +-- templates/                           Session prompt templates and sections
     |

package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py

@@ -634,6 +634,20 @@ def _derive_semantic_state(
         return _semantic_error(workflow_type, current_step, "invalid_blocked_reason", "blocked_reason must be a non-empty string")
     if terminal_status == "WORKFLOW_BLOCKED" and not blocked_reason:
         return _semantic_error(workflow_type, current_step, "missing_blocked_reason", "WORKFLOW_BLOCKED requires blocked_reason")
+    if blocked_reason and terminal_status == "WORKFLOW_COMPLETED":
+        return _semantic_error(
+            workflow_type,
+            current_step,
+            "completed_workflow_has_blocked_reason",
+            "WORKFLOW_COMPLETED cannot retain blocked_reason",
+        )
+    if blocked_reason and terminal_status != "WORKFLOW_BLOCKED":
+        return _semantic_error(
+            workflow_type,
+            current_step,
+            "blocked_reason_without_blocked_terminal",
+            "blocked_reason requires terminal_status=WORKFLOW_BLOCKED",
+        )
 
     review_step = _single_step(steps, "prizmkit-code-review")
     test_step = _single_step(steps, "prizmkit-test")