prizmkit 1.0.144 → 1.0.147

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.144",
-  "bundledAt": "2026-03-29T13:53:32.397Z",
-  "bundledFrom": "f48ed27"
+  "frameworkVersion": "1.0.147",
+  "bundledAt": "2026-03-30T17:09:52.213Z",
+  "bundledFrom": "4cdb143"
 }

package/bundled/dev-pipeline/templates/bootstrap-tier1.md

@@ -158,25 +158,37 @@ $TEST_CMD 2>&1 | tee /tmp/test-baseline.txt | tail -20
 **CP-2**: All acceptance criteria met, all tests pass.
 
 {{IF_BROWSER_INTERACTION}}
-### Phase 3.5: Browser Verification (playwright-cli)
+### Phase 3.5: Browser Verification (playwright-cli) — MANDATORY
 
-Verify UI behavior using `playwright-cli` before committing. This phase is best-effort — failures are logged but do NOT block the commit.
+You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without actually running playwright-cli.
 
-1. Start dev server if needed: `{{BROWSER_SETUP_COMMAND}}`
-2. Use `playwright-cli` to open `{{BROWSER_URL}}`, then verify:
+**Startup**:
+1. Check if port is already in use: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
+2. Start dev server: `{{BROWSER_SETUP_COMMAND}}`
+3. Wait for server to be ready: poll `{{BROWSER_URL}}` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+4. If the page requires authentication, use playwright-cli to register a test user and log in first
+
+**Verification**:
+5. Use `playwright-cli` to open `{{BROWSER_URL}}`, then verify:
    {{BROWSER_VERIFY_STEPS}}
-3. Take a final screenshot for evidence.
-4. Close browser and stop dev server.
-5. Append results to `context-snapshot.md`:
+6. Take a final screenshot for evidence
+
+**Cleanup (REQUIRED — you started it, you stop it)**:
+7. Stop the dev server process you started in step 2 (kill the process)
+8. Verify port is released: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
+
+**Reporting**:
+9. Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
    URL: {{BROWSER_URL}}
    Steps executed: [list]
    Screenshot: [path]
    Result: PASS / FAIL (reason)
+   Server cleanup: confirmed
    ```
 
-If any step fails, log the failure and continue. Do NOT retry browser verification.
+If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.
 {{END_IF_BROWSER_INTERACTION}}
 
 ### Phase 4: Architecture Sync & Commit (SINGLE COMMIT)

package/bundled/dev-pipeline/templates/bootstrap-tier2.md

@@ -269,25 +269,37 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '#
 **CP-3**: Tests pass, verdict is not NEEDS_FIXES.
 
 {{IF_BROWSER_INTERACTION}}
-### Phase 5.5: Browser Verification (playwright-cli)
+### Phase 5.5: Browser Verification (playwright-cli) — MANDATORY
 
-Verify UI behavior using `playwright-cli` before committing. This phase is best-effort — failures are logged but do NOT block the commit.
+You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without actually running playwright-cli.
 
-1. Start dev server if needed: `{{BROWSER_SETUP_COMMAND}}`
-2. Use `playwright-cli` to open `{{BROWSER_URL}}`, then verify:
+**Startup**:
+1. Check if port is already in use: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
+2. Start dev server: `{{BROWSER_SETUP_COMMAND}}`
+3. Wait for server to be ready: poll `{{BROWSER_URL}}` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+4. If the page requires authentication, use playwright-cli to register a test user and log in first
+
+**Verification**:
+5. Use `playwright-cli` to open `{{BROWSER_URL}}`, then verify:
    {{BROWSER_VERIFY_STEPS}}
-3. Take a final screenshot for evidence.
-4. Close browser and stop dev server.
-5. Append results to `context-snapshot.md`:
+6. Take a final screenshot for evidence
+
+**Cleanup (REQUIRED — you started it, you stop it)**:
+7. Stop the dev server process you started in step 2 (kill the process)
+8. Verify port is released: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
+
+**Reporting**:
+9. Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
    URL: {{BROWSER_URL}}
    Steps executed: [list]
    Screenshot: [path]
    Result: PASS / FAIL (reason)
+   Server cleanup: confirmed
    ```
 
-If any step fails, log the failure and continue. Do NOT retry browser verification.
+If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.
 {{END_IF_BROWSER_INTERACTION}}
 
 ### Phase 6: Architecture Sync & Commit (SINGLE COMMIT)

package/bundled/dev-pipeline/templates/bootstrap-tier3.md

@@ -367,25 +367,37 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '#
 **CP-3**: Integration tests pass, verdict is not NEEDS_FIXES.
 
 {{IF_BROWSER_INTERACTION}}
-### Phase 5.5: Browser Verification (playwright-cli)
+### Phase 5.5: Browser Verification (playwright-cli) — MANDATORY
 
-Verify UI behavior using `playwright-cli` before committing. This phase is best-effort — failures are logged but do NOT block the commit.
+You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without actually running playwright-cli.
 
-1. Start dev server if needed: `{{BROWSER_SETUP_COMMAND}}`
-2. Use `playwright-cli` to open `{{BROWSER_URL}}`, then verify:
+**Startup**:
+1. Check if port is already in use: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
+2. Start dev server: `{{BROWSER_SETUP_COMMAND}}`
+3. Wait for server to be ready: poll `{{BROWSER_URL}}` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+4. If the page requires authentication, use playwright-cli to register a test user and log in first
+
+**Verification**:
+5. Use `playwright-cli` to open `{{BROWSER_URL}}`, then verify:
    {{BROWSER_VERIFY_STEPS}}
-3. Take a final screenshot for evidence.
-4. Close browser and stop dev server.
-5. Append results to `context-snapshot.md`:
+6. Take a final screenshot for evidence
+
+**Cleanup (REQUIRED — you started it, you stop it)**:
+7. Stop the dev server process you started in step 2 (kill the process)
+8. Verify port is released: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
+
+**Reporting**:
+9. Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
    URL: {{BROWSER_URL}}
    Steps executed: [list]
    Screenshot: [path]
    Result: PASS / FAIL (reason)
+   Server cleanup: confirmed
    ```
 
-If any step fails, log the failure and continue. Do NOT retry browser verification.
+If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.
 {{END_IF_BROWSER_INTERACTION}}
 
 

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.144",
+  "version": "1.0.147",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",
@@ -224,6 +224,13 @@
       "category": "Custom-skill",
       "hasAssets": false,
       "hasScripts": false
+    },
+    "recovery-workflow": {
+      "description": "Recover and resume interrupted feature pipeline sessions. Detects partial work from failed or interrupted sessions and resumes from the correct phase.",
+      "tier": "companion",
+      "category": "Custom-skill",
+      "hasAssets": false,
+      "hasScripts": false
     }
   },
   "suites": {

package/bundled/skills/recovery-workflow/SKILL.md

@@ -0,0 +1,428 @@
+---
+name: "recovery-workflow"
+description: "Recover and resume interrupted feature pipeline sessions. Detects partial work (code changes, spec/plan artifacts, branch state, test results) from failed or interrupted sessions and intelligently resumes from the correct phase — instead of discarding everything and restarting from scratch. Use this skill whenever a pipeline session fails mid-execution, times out, gets interrupted, or when the user wants to salvage partial work from a failed feature. Trigger on: 'recover feature', 'resume session', 'continue from where it stopped', 'salvage partial work', 'fix failed feature', 'session interrupted', 'recover F-XXX', 'resume F-XXX', 'continue F-XXX', 'feature stuck', 'pick up where it left off', 'session timed out', 'don't want to restart from scratch', 'token limit exceeded'. (project)"
+---
+
+# Recovery Workflow
+
+Intelligently recover and resume interrupted feature pipeline sessions. Instead of discarding partial work and restarting from scratch (which wastes tokens and time), this skill inspects the actual filesystem state — code changes, artifacts, git branches, test results — and continues from the right point.
+
+## When to Use
+
+User says:
+- "Recover F-007", "Resume F-007", "Continue F-007 from where it stopped"
+- "Feature session failed/timed out, salvage the work"
+- "Pipeline interrupted, don't want to restart from scratch"
+- "F-003 is stuck, pick up where it left off"
+- "Session timed out but there's code already written"
+
+**Do NOT use when:**
+- User wants a clean retry from scratch → `retry-feature.sh` or `reset-feature.sh --clean --run`
+- Pipeline is still running normally → `dev-pipeline-launcher` (Intent B: Check Status)
+- User wants to fix a specific bug → `bug-fix-workflow`
+- Feature never started (no state at all) → `dev-pipeline-launcher` (Intent E: Retry)
+
+## Why This Skill Exists
+
+Current retry tools have a fundamental limitation:
+
+| Tool | What it does | What's lost |
+|------|-------------|-------------|
+| `retry-feature.sh` | Cleans all artifacts, resets status, spawns fresh session | All code changes, spec, plan — everything |
+| `reset-feature.sh --clean --run` | Even more thorough clean + retry | Same, plus session history |
+| `run.sh --resume-phase N` | Tells new session "start from phase N" via prompt | Better, but doesn't inspect actual worktree state — the new AI session has no memory of what was done |
+
+The gap: when a session is interrupted mid-implementation, the **worktree already has real code changes** — possibly a spec, plan, partial or complete implementation, even passing tests. Discarding all of this wastes significant tokens and time. This skill bridges that gap by inspecting the actual filesystem state and resuming intelligently within the current interactive session.
+
+---
+
+## Overview
+
+```
+recovery-workflow <feature-id>
+   │
+   ├── Phase 0: Identify feature and gather context
+   │
+   ├── Phase 1: Detect state (artifacts, code, tests, branch)
+   │
+   ├── Phase 2: Diagnose and present recovery options
+   │
+   └── Phase 3: Execute recovery (chain remaining prizmkit skills)
+```
+
+## Input
+
+| Input | Required | Example |
+|-------|----------|---------|
+| Feature ID | Yes | `F-007` |
+| Feature list path | No (default: `feature-list.json`) | `my-features.json` |
+
+---
+
+## Phase 0: Feature Identification
+
+**Goal**: Locate the feature and its context.
+
+1. **Parse feature ID** from user input (e.g., "recover F-007", "resume F-007")
+2. **Read feature-list.json** to get feature metadata:
+   ```bash
+   python3 -c "
+   import json, re
+   with open('feature-list.json') as f:
+       data = json.load(f)
+   for feat in data.get('features', []):
+       if feat.get('id') == 'F-007':
+           print(json.dumps(feat, indent=2))
+   "
+   ```
+3. **Compute feature slug** (same algorithm the pipeline uses):
+   ```python
+   # F-007 + "User Authentication" → "007-user-authentication"
+   numeric = feature_id.replace('F-', '').zfill(3)
+   slug = re.sub(r'[^a-z0-9\s-]', '', title.lower())
+   slug = re.sub(r'[\s]+', '-', slug.strip()).strip('-')
+   slug = f"{numeric}-{slug}"
+   ```
+
+If the feature is not found, ask the user for the correct ID or file path.
+
+---
+
+## Phase 1: State Detection
+
+**Goal**: Build a complete picture of what exists from the interrupted session.
+
+Run the detection script:
+
+```bash
+python3 ${SKILL_DIR}/scripts/detect-recovery-state.py \
+  --feature-id <FEATURE_ID> \
+  --feature-list feature-list.json
+```
+
+The script scans four categories of state and outputs structured JSON:
+
+### 1.1 Pipeline State
+- `dev-pipeline/state/features/{FEATURE_ID}/status.json` — pipeline tracking status, retry count, session history
+- Last session directory — path for log inspection
+
+### 1.2 PrizmKit Artifacts
+- `.prizmkit/specs/{slug}/spec.md` — specification generated?
+- `.prizmkit/specs/{slug}/plan.md` — plan generated?
+- If plan.md exists: count completed vs total tasks (look for `[x]` vs `[ ]` checkboxes)
+
+### 1.3 Git State
+- **Feature branch**: does `feat/{slug}` exist?
+- **Current branch**: are we already on the feature branch?
+- **Uncommitted changes**: `git diff --stat` (working tree changes)
+- **Staged changes**: `git diff --cached --stat`
+- **Commits ahead of main**: `git log main..HEAD --oneline`
+
+### 1.4 Code Changes
+- Number of modified/added/deleted files
+- Which directories were touched
+- Whether test files were created/modified
+
+### Detection Output
+
+The script produces a structured JSON report:
+
+```json
+{
+  "feature_id": "F-007",
+  "feature_title": "User Authentication",
+  "feature_slug": "007-user-authentication",
+  "pipeline": {
+    "status": "failed",
+    "retry_count": 1,
+    "last_session_id": "F-007-20260329101500",
+    "last_session_dir": "dev-pipeline/state/features/F-007/sessions/F-007-20260329101500"
+  },
+  "artifacts": {
+    "spec_exists": true,
+    "plan_exists": true,
+    "spec_path": ".prizmkit/specs/007-user-authentication/spec.md",
+    "plan_path": ".prizmkit/specs/007-user-authentication/plan.md",
+    "plan_tasks_total": 5,
+    "plan_tasks_completed": 3
+  },
+  "git": {
+    "feature_branch": "feat/007-user-authentication",
+    "branch_exists": true,
+    "on_feature_branch": true,
+    "uncommitted_files": 8,
+    "staged_files": 0,
+    "commits_ahead_of_main": 0
+  },
+  "code": {
+    "files_modified": 6,
+    "files_added": 4,
+    "test_files_touched": 2,
+    "directories_touched": ["src/auth/", "src/middleware/", "tests/"]
+  },
+  "recovery": {
+    "recommended_action": "continue_implementation",
+    "recommended_phase": "implement",
+    "reason": "spec and plan exist, 3/5 plan tasks completed, code changes present",
+    "remaining_work": "2 tasks + review + commit"
+  }
+}
+```
+
+**CHECKPOINT CP-RW-0**: State detection complete, structured report available.
+
+---
+
+## Phase 2: Diagnosis & Recovery Options
+
+**Goal**: Present findings to user and agree on a recovery strategy.
+
+### 2.1 Present Discovery Summary
+
+Read the detection script output and show the user a clear summary:
+
+```
+═══════════════════════════════════════════════════
+  Recovery Report: F-007 — User Authentication
+═══════════════════════════════════════════════════
+
+  Pipeline Status:  FAILED (retry 1)
+  Feature Branch:   feat/007-user-authentication
+
+  Artifacts Found:
+    ✓ spec.md (specification)
+    ✓ plan.md (5 tasks, 3 completed)
+    ✓ Code changes (10 files — 6 modified, 4 new)
+    ✓ Test files (2 found)
+
+  Recommended: Continue implementation
+  Remaining:   2 tasks + review + commit
+═══════════════════════════════════════════════════
+```
+
+### 2.2 Run Tests (if code changes exist)
+
+Before presenting options, run the project's test suite to understand the health of existing code:
+
+```bash
+# detect test command from .prizmkit/config.json or package.json
+npm test   # or the appropriate test command
+```
+
+Include test results in the summary:
+- How many tests pass/fail
+- If there are failures — which tests and why
+
+### 2.3 Present Recovery Options
+
+Based on the detected state, offer the appropriate options. The most common scenarios:
+
+**Scenario A: Implementation in progress** (spec + plan + code changes)
+Most common case — session died mid-implementation.
+
+| Option | Description |
+|--------|-------------|
+| **(a) Smart Resume** (recommended) | Fix test failures if any, complete remaining plan tasks, then review → commit |
+| **(b) Review & Commit Only** | If implementation looks complete (all tasks done, tests passing), skip to code review |
+| **(c) Re-implement from Plan** | Keep spec and plan, discard code changes, re-implement. Useful if partial code is low quality |
+| **(d) Clean Restart** | Discard everything, start from scratch (equivalent to `reset-feature.sh --clean --run`) |
+
+**Scenario B: Only planning artifacts** (spec/plan exist, no code changes)
+Session died during or after planning, before implementation started.
+
+| Option | Description |
+|--------|-------------|
+| **(a) Start Implementation** (recommended) | Plan is ready, begin implementing |
+| **(b) Re-plan** | Keep spec, regenerate plan (useful if plan was incomplete or poor) |
+| **(c) Clean Restart** | Discard everything and start over |
+
+**Scenario C: Code changes but no artifacts** (git changes, no .prizmkit artifacts)
+Unusual — might be manual work or artifacts were cleaned.
+
+| Option | Description |
+|--------|-------------|
+| **(a) Adopt & Continue** | Read existing code, proceed to review + commit |
+| **(b) Clean Restart** | Discard and restart |
+
+**Scenario D: Already committed** (feature branch has commits ahead of main)
+Session completed implementation but didn't finish post-commit steps.
+
+| Option | Description |
+|--------|-------------|
+| **(a) Complete Post-commit** (recommended) | Run code review, retrospective, handle merge |
+| **(b) Clean Restart** | Discard and restart |
+
+**Scenario E: No state found** (no branch, no artifacts, no code)
+Feature was never executed or was fully cleaned.
+
+| Option | Description |
+|--------|-------------|
+| **(a) Run from Scratch** | Suggest using `dev-pipeline-launcher` (Intent E) or `retry-feature.sh` instead |
+
+Ask the user to choose. Default to the recommended option.
+
+**CHECKPOINT CP-RW-1**: User confirmed recovery strategy.
+
+---
+
+## Phase 3: Execute Recovery
+
+**Goal**: Execute the remaining phases based on the user's chosen strategy.
+
+### 3.0 Branch Setup
+
+Ensure we're on the right branch:
+
+```bash
+# If feature branch exists but we're not on it:
+git checkout feat/{slug}
+
+# If no feature branch but code changes are on current branch:
+git checkout -b feat/{slug}
+```
+
+### 3.1 Read Existing Artifacts
+
+Load the artifacts that were preserved, so we have full context:
+
+1. **Read spec.md** (if exists) — understand what this feature should do
+2. **Read plan.md** (if exists) — understand the implementation plan and task breakdown
+3. **Scan code changes** — `git diff main --stat` to understand what was already done
+4. **Read relevant `.prizm-docs/`** — load project context (L0 root, relevant L1)
+
+This step replaces the Phase 0-2 that the pipeline would have done (project bootstrap, context building, planning). The artifacts serve as memory of the interrupted session.
+
+### 3.2 Fix Existing Test Failures (if any)
+
+If tests are failing from the interrupted session, fix them first. Continuing implementation on top of a broken state compounds errors.
+
+1. Read the test failure output
+2. Read the relevant source files
+3. Apply minimal fixes to make tests pass
+4. Verify: run test suite → all green
+
+If failures cannot be fixed after 3 attempts, ask the user whether to:
+- Continue anyway (if failures are unrelated to this feature)
+- Switch to "Re-implement from Plan" strategy
+- Clean restart
+
+### 3.3 Continue Implementation
+
+If plan.md exists with incomplete tasks:
+
+1. **Read plan.md** and identify remaining tasks — look for unchecked `[ ]` items in the Tasks section
+2. **For each remaining task**:
+   - Read the task description from plan.md
+   - Implement the change following the same approach as `/prizmkit-implement`
+   - Run full test suite after each task
+   - Mark task as complete `[x]` in plan.md
+3. After all tasks complete → full test suite must pass
+
+If no plan.md exists but code changes are present (Scenario C), skip this step — go straight to review.
+
+### 3.4 Code Review
+
+Invoke `/prizmkit-code-review` on all changes:
+- Review scope: all files modified/added relative to main branch (`git diff main --stat`)
+- If review returns NEEDS_FIXES → apply fixes, re-review (max 2 rounds)
+- If review returns PASS or PASS_WITH_WARNINGS → proceed
+
+### 3.5 User Verification
+
+Ask user: "Implementation recovered and reviewed. Verify before committing?"
+- **(a) Run the app** → suggest and start the dev server
+- **(b) Run a specific command** → execute what the user specifies
+- **(c) Skip** → proceed directly to commit
+
+If user reports issues: return to 3.3 (max 2 additional rounds).
+
+### 3.6 Retrospective & Commit
+
+1. **Invoke `/prizmkit-retrospective`** — update `.prizm-docs/` for structural changes caused by this feature
+2. **Invoke `/prizmkit-committer`** — commit with `feat(<scope>): <description>` prefix
+3. **Update pipeline state** — mark feature as completed:
+   ```bash
+   python3 dev-pipeline/scripts/update-feature-status.py \
+     --feature-list feature-list.json \
+     --state-dir dev-pipeline/state \
+     --feature-id <FEATURE_ID> \
+     --action complete
+   ```
+
+### 3.7 Post-Recovery
+
+1. **Ask merge preference**:
+   - (a) Merge to main and delete feature branch
+   - (b) Keep feature branch for PR review
+   - (c) Decide later
+
+2. **Report completion**:
+   ```
+   Recovery complete: F-007 — User Authentication
+
+   Recovered from: implementation phase (3/5 tasks done)
+   Completed: 2 remaining tasks + test fixes + review + commit
+   Work preserved: spec.md, plan.md, 3 completed tasks
+
+   Next: Check pipeline status for remaining features,
+         or invoke /recovery-workflow for another failed feature.
+   ```
+
+3. **Suggest next steps**:
+   - If other features are pending/failed → offer to check pipeline status or recover another
+   - If this was the last feature → suggest integration verification
+
+**CHECKPOINT CP-RW-2**: Feature recovered, committed, and pipeline state updated.
+
+---
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Feature ID not found in feature-list.json | Ask user for correct ID or file path |
+| No state to recover (never executed) | Inform user, suggest `dev-pipeline-launcher` instead |
+| Feature branch was deleted | Check if changes exist elsewhere; if not, offer clean start |
+| Merge conflicts on feature branch | Show conflicts, help resolve before continuing |
+| Test failures unfixable after 3 attempts | Escalate to user, offer alternative strategies |
+| Code quality too low to salvage | Recommend re-implement from plan |
+| Pipeline state file inconsistent with git | Trust git and filesystem over status.json — git is the ground truth |
+| detection script fails | Fall back to manual detection (Phase 1 checks can be done individually via bash) |
+
+---
+
+## Relationship to Other Skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `dev-pipeline-launcher` | **Upstream** — launcher can suggest this skill when features fail; this skill updates pipeline state after recovery |
+| `retry-feature.sh` | **Alternative** — full clean retry; this skill is the smart alternative |
+| `reset-feature.sh` | **Used by option (d)** — clean restart delegates to reset-feature |
+| `/prizmkit-implement` | **Approach shared in Phase 3.3** — same implementation methodology |
+| `/prizmkit-code-review` | **Called in Phase 3.4** — reviews recovered code |
+| `/prizmkit-committer` | **Called in Phase 3.6** — commits the result |
+| `/prizmkit-retrospective` | **Called in Phase 3.6** — updates .prizm-docs/ |
+| `feature-workflow` | **Sibling** — feature-workflow builds new features; this skill salvages interrupted ones |
+
+---
+
+## Comparison with Existing Recovery Tools
+
+| Dimension | recovery-workflow | retry-feature.sh | reset + run | run.sh --resume-phase |
+|-----------|------------------|-------------------|-------------|----------------------|
+| State inspection | Deep (git + artifacts + tests) | None | None | None |
+| Preserves code | Yes | No (cleans) | No (cleans) | Prompt-level only |
+| Preserves artifacts | Yes (selective) | No | No | Prompt-level |
+| Runs tests first | Yes | No | No | No |
+| User choice | Multiple strategies | Always clean | Always clean | Fixed phase number |
+| Execution mode | Interactive (in-session) | Spawns new session | Spawns new session | Spawns new session |
+| Token efficiency | High (skips done work) | Low (redo all) | Low (redo all) | Medium |
+| Context continuity | Full (reads existing artifacts) | None (fresh AI session) | None | Partial |
+
+## Output
+
+- Recovered and completed feature implementation
+- Updated pipeline state (feature marked complete)
+- Git commit with `feat(<scope>):` prefix
+- Updated `.prizm-docs/` (via retrospective)
+- Recovery summary showing what was salvaged vs what was re-done

package/bundled/skills/recovery-workflow/scripts/detect-recovery-state.py

@@ -0,0 +1,483 @@
+#!/usr/bin/env python3
+"""
+detect-recovery-state.py — Scan filesystem for partial work from an interrupted
+feature pipeline session and output a structured recovery report.
+
+Checks four state categories:
+  1. Pipeline state (dev-pipeline/state/)
+  2. PrizmKit artifacts (.prizmkit/specs/{slug}/)
+  3. Git state (branches, uncommitted changes, commits ahead)
+  4. Code changes (file counts, directories touched)
+
+Does NOT run tests — that's left to the skill so the user sees output in real time.
+
+Usage:
+  python3 detect-recovery-state.py --feature-id F-007 --feature-list feature-list.json
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+
+
+def run_git(args, cwd=None):
+    """Run a git command and return stdout, or empty string on failure."""
+    try:
+        result = subprocess.run(
+            ["git"] + args,
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+            timeout=10,
+        )
+        return result.stdout.strip()
+    except (subprocess.SubprocessError, FileNotFoundError):
+        return ""
+
+
+def compute_slug(feature_id, title):
+    """Compute feature slug using the same algorithm as the pipeline."""
+    numeric = feature_id.replace("F-", "").replace("f-", "").zfill(3)
+    slug = title.lower()
+    slug = re.sub(r"[^a-z0-9\s-]", "", slug)
+    slug = re.sub(r"[\s]+", "-", slug.strip())
+    slug = re.sub(r"-+", "-", slug).strip("-") or "feature"
+    return f"{numeric}-{slug}"
+
+
+def find_feature(feature_list_path, feature_id):
+    """Find feature in feature-list.json."""
+    with open(feature_list_path) as f:
+        data = json.load(f)
+    for feat in data.get("features", []):
+        if feat.get("id") == feature_id:
+            return feat
+    return None
+
+
+def detect_pipeline_state(state_dir, feature_id):
+    """Check dev-pipeline/state/ for feature status."""
+    result = {
+        "status": "unknown",
+        "retry_count": 0,
+        "last_session_id": None,
+        "last_session_dir": None,
+        "has_state": False,
+    }
+
+    status_file = os.path.join(state_dir, "features", feature_id, "status.json")
+    if not os.path.isfile(status_file):
+        return result
+
+    try:
+        with open(status_file) as f:
+            status_data = json.load(f)
+        result["has_state"] = True
+        result["status"] = status_data.get("status", "unknown")
+        result["retry_count"] = status_data.get("retry_count", 0)
+
+        sessions = status_data.get("sessions", [])
+        if sessions:
+            last = sessions[-1]
+            sid = last.get("session_id", "")
+            result["last_session_id"] = sid
+            result["last_session_dir"] = os.path.join(
+                state_dir, "features", feature_id, "sessions", sid
+            )
+    except (json.JSONDecodeError, IOError):
+        pass
+
+    return result
+
+
+def detect_artifacts(project_root, feature_slug):
+    """Check .prizmkit/specs/{slug}/ for planning artifacts."""
+    specs_dir = os.path.join(project_root, ".prizmkit", "specs", feature_slug)
+    result = {
+        "spec_exists": False,
+        "plan_exists": False,
+        "spec_path": None,
+        "plan_path": None,
+        "plan_tasks_total": 0,
+        "plan_tasks_completed": 0,
+        "other_artifacts": [],
+    }
+
+    if not os.path.isdir(specs_dir):
+        return result
+
+    spec_path = os.path.join(specs_dir, "spec.md")
+    plan_path = os.path.join(specs_dir, "plan.md")
+
+    if os.path.isfile(spec_path):
+        result["spec_exists"] = True
+        result["spec_path"] = os.path.relpath(spec_path, project_root)
+
+    if os.path.isfile(plan_path):
+        result["plan_exists"] = True
+        result["plan_path"] = os.path.relpath(plan_path, project_root)
+
+        # Count tasks in plan.md (look for checkbox pattern)
+        try:
+            with open(plan_path) as f:
+                content = f.read()
+            # Match both [x] and [ ] patterns (task checkboxes)
+            completed = len(re.findall(r"^\s*-\s*\[x\]", content, re.MULTILINE | re.IGNORECASE))
+            pending = len(re.findall(r"^\s*-\s*\[ \]", content, re.MULTILINE))
+            result["plan_tasks_total"] = completed + pending
+            result["plan_tasks_completed"] = completed
+        except IOError:
+            pass
+
+    # Check for other artifacts
+    try:
+        for name in os.listdir(specs_dir):
+            if name not in ("spec.md", "plan.md") and os.path.isfile(
+                os.path.join(specs_dir, name)
+            ):
+                result["other_artifacts"].append(name)
+    except IOError:
+        pass
+
+    return result
+
+
+def detect_git_state(project_root, feature_slug):
+    """Check git for branch existence, uncommitted changes, commits ahead."""
+    result = {
+        "feature_branch": f"feat/{feature_slug}",
+        "branch_exists": False,
+        "on_feature_branch": False,
+        "uncommitted_files": 0,
+        "staged_files": 0,
+        "commits_ahead_of_main": 0,
+        "current_branch": "",
+    }
+
+    # Current branch
+    current = run_git(["branch", "--show-current"], cwd=project_root)
+    result["current_branch"] = current
+
+    # Check if feature branch exists
+    branch_name = f"feat/{feature_slug}"
+    branches_output = run_git(["branch", "--list", branch_name], cwd=project_root)
+    if branches_output.strip():
+        result["branch_exists"] = True
+
+    # Also check without feat/ prefix (some pipelines use different naming)
+    if not result["branch_exists"]:
+        alt_branch = f"feature/{feature_slug}"
+        alt_output = run_git(["branch", "--list", alt_branch], cwd=project_root)
+        if alt_output.strip():
+            result["branch_exists"] = True
+            result["feature_branch"] = alt_branch
+
+    result["on_feature_branch"] = current == result["feature_branch"]
+
+    # Uncommitted changes (working tree)
+    diff_stat = run_git(["diff", "--stat"], cwd=project_root)
+    if diff_stat:
+        # Count "N files changed" from the summary line
+        lines = diff_stat.strip().split("\n")
+        result["uncommitted_files"] = max(0, len(lines) - 1)  # exclude summary line
+
+    # Staged changes
+    staged_stat = run_git(["diff", "--cached", "--stat"], cwd=project_root)
+    if staged_stat:
+        lines = staged_stat.strip().split("\n")
+        result["staged_files"] = max(0, len(lines) - 1)
+
+    # Commits ahead of main
+    main_branch = "main"
+    # Try to detect default branch
+    for candidate in ["main", "master"]:
+        check = run_git(["rev-parse", "--verify", candidate], cwd=project_root)
+        if check:
+            main_branch = candidate
+            break
+
+    log_output = run_git(
+        ["log", f"{main_branch}..HEAD", "--oneline"], cwd=project_root
+    )
+    if log_output:
+        result["commits_ahead_of_main"] = len(log_output.strip().split("\n"))
+
+    return result
+
+
+def detect_code_changes(project_root, main_branch="main"):
+    """Analyze code changes relative to main branch.
+
+    Filters out pipeline/config files that aren't source code — only counts
+    files that represent actual implementation work.
+    """
+    # Files/patterns that are pipeline artifacts, not implementation code
+    IGNORED_FILES = {
+        "feature-list.json",
+        "bug-fix-list.json",
+        "package-lock.json",
+        "yarn.lock",
+        "pnpm-lock.yaml",
+    }
+    IGNORED_PREFIXES = (
+        ".prizmkit/",
+        "dev-pipeline/state/",
+        ".prizm-docs/",
+        ".claude/",
+        ".codebuddy/",
+    )
+
+    def is_source_file(filepath):
+        """Return True if this file represents implementation code."""
+        basename = os.path.basename(filepath)
+        if basename in IGNORED_FILES:
+            return False
+        for prefix in IGNORED_PREFIXES:
+            if filepath.startswith(prefix):
+                return False
+        return True
+
+    result = {
+        "files_modified": 0,
+        "files_added": 0,
+        "files_deleted": 0,
+        "test_files_touched": 0,
+        "directories_touched": [],
+        "has_changes": False,
+    }
+
+    # Get diff stat relative to main
+    diff_output = run_git(
+        ["diff", main_branch, "--name-status"], cwd=project_root
+    )
+
+    # Also include uncommitted changes
+    uncommitted = run_git(["diff", "--name-status"], cwd=project_root)
+    untracked = run_git(
+        ["ls-files", "--others", "--exclude-standard"], cwd=project_root
+    )
+
+    all_files = set()
+    dirs = set()
+
+    if diff_output:
+        for line in diff_output.strip().split("\n"):
+            if not line.strip():
+                continue
+            parts = line.split("\t", 1)
+            if len(parts) < 2:
+                continue
+            status, filepath = parts[0], parts[1]
+            if not is_source_file(filepath):
+                continue
+            all_files.add(filepath)
+            if status.startswith("M"):
+                result["files_modified"] += 1
+            elif status.startswith("A"):
+                result["files_added"] += 1
+            elif status.startswith("D"):
+                result["files_deleted"] += 1
+
+    if uncommitted:
+        for line in uncommitted.strip().split("\n"):
+            if not line.strip():
+                continue
+            parts = line.split("\t", 1)
+            if len(parts) >= 2:
+                filepath = parts[1]
+                if not is_source_file(filepath):
+                    continue
+                all_files.add(filepath)
+                result["files_modified"] += 1
+
+    if untracked:
+        for filepath in untracked.strip().split("\n"):
+            if filepath.strip() and is_source_file(filepath.strip()):
+                all_files.add(filepath.strip())
+                result["files_added"] += 1
+
+    # Analyze file set
+    test_patterns = re.compile(
+        r"(test|spec|__tests__|\.test\.|\.spec\.)", re.IGNORECASE
+    )
+    for filepath in all_files:
+        if test_patterns.search(filepath):
+            result["test_files_touched"] += 1
+        parent = os.path.dirname(filepath)
+        if parent:
+            # Keep first two levels for readability
+            parts = parent.split(os.sep)
+            dirs.add(os.sep.join(parts[:2]) + "/")
+
+    result["directories_touched"] = sorted(dirs)
+    result["has_changes"] = len(all_files) > 0
+
+    return result
+
+
+def determine_recovery(artifacts, git_state, code_changes, pipeline):
+    """Recommend a recovery action based on detected state."""
+    has_spec = artifacts["spec_exists"]
+    has_plan = artifacts["plan_exists"]
+    has_code = code_changes["has_changes"]
+    has_commits = git_state["commits_ahead_of_main"] > 0
+    tasks_total = artifacts["plan_tasks_total"]
+    tasks_done = artifacts["plan_tasks_completed"]
+
+    # Scenario D: Already committed
+    if has_commits:
+        return {
+            "recommended_action": "complete_post_commit",
+            "recommended_phase": "review",
+            "scenario": "D",
+            "reason": f"{git_state['commits_ahead_of_main']} commit(s) ahead of main — implementation may be complete",
+            "remaining_work": "code review + retrospective + merge",
+        }
+
+    # Scenario A: Implementation in progress
+    if has_plan and has_code:
+        if tasks_total > 0 and tasks_done == tasks_total:
+            return {
+                "recommended_action": "review_and_commit",
+                "recommended_phase": "review",
+                "scenario": "A",
+                "reason": f"all {tasks_total} plan tasks completed, code changes present",
+                "remaining_work": "code review + commit",
+            }
+        else:
+            tasks_remaining = tasks_total - tasks_done if tasks_total > 0 else "unknown"
+            return {
+                "recommended_action": "continue_implementation",
+                "recommended_phase": "implement",
+                "scenario": "A",
+                "reason": f"spec and plan exist, {tasks_done}/{tasks_total} tasks completed, code changes present",
+                "remaining_work": f"{tasks_remaining} tasks + review + commit",
+            }
+
+    # Scenario B: Only planning artifacts
+    if has_spec or has_plan:
+        if has_plan:
+            return {
+                "recommended_action": "start_implementation",
+                "recommended_phase": "implement",
+                "scenario": "B",
+                "reason": "spec and plan exist, no code changes yet",
+                "remaining_work": f"{tasks_total} tasks + review + commit",
+            }
+        else:
+            return {
+                "recommended_action": "generate_plan",
+                "recommended_phase": "plan",
+                "scenario": "B",
+                "reason": "spec exists but no plan — session interrupted during planning",
+                "remaining_work": "plan + implement + review + commit",
+            }
+
+    # Scenario C: Code changes but no artifacts
+    if has_code:
+        return {
+            "recommended_action": "adopt_and_continue",
+            "recommended_phase": "review",
+            "scenario": "C",
+            "reason": "code changes found but no prizmkit artifacts — possible manual work or artifacts cleaned",
+            "remaining_work": "review + commit",
+        }
+
+    # Scenario E: Nothing found
+    return {
+        "recommended_action": "start_fresh",
+        "recommended_phase": "none",
+        "scenario": "E",
+        "reason": "no artifacts, no code changes, no commits — feature was never executed or fully cleaned",
+        "remaining_work": "full pipeline run",
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Detect recovery state for an interrupted feature session"
+    )
+    parser.add_argument("--feature-id", required=True, help="Feature ID (e.g., F-007)")
+    parser.add_argument(
+        "--feature-list",
+        default="feature-list.json",
+        help="Path to feature-list.json (default: feature-list.json)",
+    )
+    parser.add_argument(
+        "--state-dir",
+        default=None,
+        help="Pipeline state directory (default: dev-pipeline/state)",
+    )
+    parser.add_argument(
+        "--project-root",
+        default=None,
+        help="Project root directory (default: auto-detect from git)",
+    )
+
+    args = parser.parse_args()
+
+    # Resolve project root
+    if args.project_root:
+        project_root = os.path.abspath(args.project_root)
+    else:
+        git_root = run_git(["rev-parse", "--show-toplevel"])
+        project_root = git_root if git_root else os.getcwd()
+
+    # Resolve state dir
+    state_dir = args.state_dir or os.path.join(project_root, "dev-pipeline", "state")
+
+    # Resolve feature list path
+    feature_list_path = args.feature_list
+    if not os.path.isabs(feature_list_path):
+        feature_list_path = os.path.join(project_root, feature_list_path)
+
+    # Find feature
+    if not os.path.isfile(feature_list_path):
+        print(
+            json.dumps({"error": f"Feature list not found: {feature_list_path}"}),
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    feature = find_feature(feature_list_path, args.feature_id)
+    if not feature:
+        print(
+            json.dumps(
+                {
+                    "error": f"Feature {args.feature_id} not found in {feature_list_path}"
+                }
+            ),
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    title = feature.get("title", "untitled")
+    slug = compute_slug(args.feature_id, title)
+
+    # Run all detection phases
+    pipeline = detect_pipeline_state(state_dir, args.feature_id)
+    artifacts = detect_artifacts(project_root, slug)
+    git_state = detect_git_state(project_root, slug)
+    code_changes = detect_code_changes(project_root)
+    recovery = determine_recovery(artifacts, git_state, code_changes, pipeline)
+
+    # Build report
+    report = {
+        "feature_id": args.feature_id,
+        "feature_title": title,
+        "feature_slug": slug,
+        "pipeline": pipeline,
+        "artifacts": artifacts,
+        "git": git_state,
+        "code": code_changes,
+        "recovery": recovery,
+    }
+
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.0.144",
+  "version": "1.0.147",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {