prizmkit 1.1.20 → 1.1.23

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.20",
-  "bundledAt": "2026-04-11T05:49:50.851Z",
-  "bundledFrom": "13e5e58"
+  "frameworkVersion": "1.1.23",
+  "bundledAt": "2026-04-11T14:45:05.180Z",
+  "bundledFrom": "fbba566"
 }

package/bundled/dev-pipeline/lib/branch.sh

@@ -2,18 +2,21 @@
 # ============================================================
 # dev-pipeline/lib/branch.sh - Git Branch Lifecycle Library
 #
-# Shared by run-feature.sh and run-bugfix.sh for branch-based serial
-# development. Each pipeline run creates a dev branch and all
-# features/bugs commit directly on it in sequence.
+# Shared by run-feature.sh, run-bugfix.sh, and run-refactor.sh
+# for branch-based serial development. Each pipeline run creates
+# a dev branch and all features/bugs/refactors commit on it.
 #
 # Functions:
-#   branch_create  — Create and checkout a new branch
-#   branch_return  — Checkout back to original branch
-#   branch_merge   — Merge dev branch into original and optionally push
+#   branch_create                   — Create and checkout a new branch
+#   branch_return                   — Checkout back to original branch
+#   branch_merge                    — Merge dev branch into original and optionally push
+#   branch_ensure_return            — Guaranteed return to original branch (try/finally)
 #
 # Environment:
-#   DEV_BRANCH    — Optional custom branch name override
-#   AUTO_PUSH     — Set to 1 to auto-push after successful feature
+#   _ORIGINAL_BRANCH                Set by caller before branch_create
+#   _DEV_BRANCH_NAME                Set by caller after branch_create
+#   DEV_BRANCH                      Optional custom branch name override
+#   AUTO_PUSH                       Set to 1 to auto-push after successful feature
 # ============================================================
 
 # branch_create <project_root> <branch_name> <source_branch>
@@ -80,11 +83,15 @@ branch_return() {
 #
 # Merges dev_branch into original_branch, then optionally pushes.
 # Steps:
-#   1. Checkout original_branch
+#   1. Stash tracked dirty files (NOT untracked — .prizmkit/state/ is gitignored)
 #   2. Rebase dev_branch onto original_branch (handles diverged main)
 #   3. Fast-forward merge original_branch to rebased dev tip
 #   4. Push to remote if auto_push == "1"
 #   5. Delete dev_branch (local only, it's been merged)
+#   6. Restore stashed files
+#
+# IMPORTANT: On failure, caller MUST still call branch_ensure_return()
+# to guarantee return to the original branch.
 #
 # Returns 0 on success, 1 on failure.
 branch_merge() {
@@ -93,16 +100,21 @@ branch_merge() {
     local original_branch="$3"
     local auto_push="${4:-0}"
 
-    # Step 1: Checkout original branch
-    # Stash any uncommitted changes (e.g. untracked state/ files) so checkout is not blocked
+    # Step 1: Stash any tracked uncommitted changes so checkout is not blocked.
+    # Only stash tracked changes (not untracked). Untracked files like
+    # .prizmkit/state/ are gitignored and survive checkout without issue.
+    # Using --include-untracked causes stash pop conflicts and can lose
+    # state/ files that are needed for pipeline status tracking.
     local had_stash=false
-    local remaining_dirty
-    remaining_dirty=$(git -C "$project_root" status --porcelain 2>/dev/null || true)
-    if [[ -n "$remaining_dirty" ]]; then
-        if git -C "$project_root" stash push --include-untracked -m "pipeline-merge-stash" 2>/dev/null; then
+    local tracked_dirty
+    tracked_dirty=$(git -C "$project_root" diff --name-only 2>/dev/null || true)
+    local staged_dirty
+    staged_dirty=$(git -C "$project_root" diff --cached --name-only 2>/dev/null || true)
+    if [[ -n "$tracked_dirty" || -n "$staged_dirty" ]]; then
+        if git -C "$project_root" stash push -m "pipeline-merge-stash" 2>/dev/null; then
             had_stash=true
         else
-            log_warn "git stash failed — uncommitted changes may not be preserved during merge"
+            log_warn "git stash failed — uncommitted tracked changes may not be preserved during merge"
             had_stash=false
         fi
     fi
@@ -116,14 +128,21 @@ branch_merge() {
         log_error "Rebase of $dev_branch onto $original_branch failed — resolve manually:"
         log_error "  git rebase --abort  # then resolve conflicts and retry"
         git -C "$project_root" rebase --abort 2>/dev/null || true
-        git -C "$project_root" checkout "$dev_branch" 2>/dev/null || true
-        [[ "$had_stash" == true ]] && git -C "$project_root" stash pop 2>/dev/null || true
+        if [[ "$had_stash" == true ]]; then
+            if ! git -C "$project_root" stash pop 2>/dev/null; then
+                log_warn "git stash pop failed after rebase abort — run 'git stash list' to check"
+            fi
+        fi
         return 1
     fi
     # After the rebase we are on dev_branch — checkout original for the fast-forward
     if ! git -C "$project_root" checkout "$original_branch" 2>/dev/null; then
         log_error "Failed to checkout $original_branch for merge"
-        [[ "$had_stash" == true ]] && git -C "$project_root" stash pop 2>/dev/null || true
+        if [[ "$had_stash" == true ]]; then
+            if ! git -C "$project_root" stash pop 2>/dev/null; then
+                log_warn "git stash pop failed after checkout failure — run 'git stash list' to check"
+            fi
+        fi
         return 1
     fi
 
@@ -131,8 +150,11 @@ branch_merge() {
     if ! git -C "$project_root" merge --ff-only "$dev_branch" 2>&1; then
         log_error "Merge failed after rebase — this should not happen, resolve manually:"
         log_error "  git checkout $original_branch && git rebase $dev_branch"
-        git -C "$project_root" checkout "$dev_branch" 2>/dev/null || true
-        [[ "$had_stash" == true ]] && git -C "$project_root" stash pop 2>/dev/null || true
+        if [[ "$had_stash" == true ]]; then
+            if ! git -C "$project_root" stash pop 2>/dev/null; then
+                log_warn "git stash pop failed after merge failure — run 'git stash list' to check"
+            fi
+        fi
         return 1
     fi
 
@@ -152,8 +174,150 @@ branch_merge() {
     git -C "$project_root" branch -d "$dev_branch" 2>/dev/null && \
         log_info "Deleted merged branch: $dev_branch" || true
 
-    # Step 6: Restore stashed state/ files
-    [[ "$had_stash" == true ]] && git -C "$project_root" stash pop 2>/dev/null || true
+    # Step 6: Restore stashed files
+    if [[ "$had_stash" == true ]]; then
+        if ! git -C "$project_root" stash pop 2>/dev/null; then
+            log_warn "git stash pop failed after merge — stashed changes may be lost. Run 'git stash list' to check."
+        fi
+    fi
+
+    return 0
+}
+
+# branch_save_wip <project_root> <dev_branch>
+#
+# Saves any uncommitted work-in-progress on the dev branch before returning
+# to the original branch. Called during interrupt/crash cleanup to preserve
+# partially completed AI work that hasn't been committed yet.
+#
+# Commits ALL changes (tracked + untracked, excluding gitignored) with a
+# "wip:" prefix message so it's easy to identify and squash later.
+#
+# Safe to call when the working tree is clean — it simply does nothing.
+# Never fails — errors are logged but the function always returns 0.
+branch_save_wip() {
+    local project_root="$1"
+    local dev_branch="$2"
+
+    # Nothing to save if dev_branch is empty
+    if [[ -z "$dev_branch" ]]; then
+        return 0
+    fi
+
+    # Verify we're actually on the dev branch
+    local current_branch
+    current_branch=$(git -C "$project_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+    if [[ "$current_branch" != "$dev_branch" ]]; then
+        return 0
+    fi
+
+    # Check if there are any uncommitted changes (tracked or untracked, excluding gitignored)
+    local has_changes
+    has_changes=$(git -C "$project_root" status --porcelain 2>/dev/null || true)
+    if [[ -z "$has_changes" ]]; then
+        return 0
+    fi
+
+    log_warn "Saving uncommitted work-in-progress on branch: $dev_branch"
+
+    # Stage all changes (tracked + untracked, respects .gitignore)
+    if ! git -C "$project_root" add -A 2>/dev/null; then
+        log_warn "git add -A failed — uncommitted work may be lost on branch switch"
+        return 0
+    fi
+
+    # Commit with WIP marker
+    if git -C "$project_root" commit --no-verify \
+        -m "wip($dev_branch): interrupted — uncommitted work saved" \
+        -m "Pipeline was interrupted by signal. This commit preserves work-in-progress." \
+        -m "To resume: git checkout $dev_branch" 2>/dev/null; then
+        log_info "Saved uncommitted work on branch $dev_branch"
+    else
+        log_warn "git commit failed — uncommitted work may be lost on branch switch"
+    fi
+
+    return 0
+}
+
+# branch_ensure_return <project_root> <original_branch> [dev_branch]
+#
+# GUARANTEED return to the original branch. Like a try/finally block.
+# Must be called in EVERY exit path: success, failure, interrupt, crash.
+# This is the single point of truth for "always go back to original branch".
+#
+# If dev_branch is provided and we're currently on it, any uncommitted
+# work is saved as a WIP commit before switching (via branch_save_wip).
+#
+# Handles:
+#   - Saving uncommitted WIP on dev branch (if dev_branch provided)
+#   - Aborting any in-progress rebase (leftover from branch_merge failure)
+#   - Stashing any tracked dirty files that block checkout
+#   - Checking out original_branch
+#   - Restoring stashed files
+#   - Logging for diagnostics
+#
+# Never fails — errors are logged but the function always returns 0
+# so it can be used in cleanup traps without breaking error handling.
+branch_ensure_return() {
+    local project_root="$1"
+    local original_branch="$2"
+    local dev_branch="${3:-}"
+
+    # If original_branch is empty or unset, nothing to return to
+    if [[ -z "$original_branch" ]]; then
+        return 0
+    fi
+
+    # Abort any in-progress rebase (can happen if branch_merge failed mid-way)
+    if git -C "$project_root" rebase --show-current-patch >/dev/null 2>&1; then
+        log_warn "Aborting in-progress rebase..."
+        git -C "$project_root" rebase --abort 2>/dev/null || true
+    fi
+
+    # Check current branch
+    local current_branch
+    current_branch=$(git -C "$project_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+
+    if [[ "$current_branch" == "$original_branch" ]]; then
+        return 0
+    fi
+
+    # Save any uncommitted WIP on dev branch before switching away
+    # Use dev_branch if provided; otherwise infer from current_branch
+    local _wip_branch="${dev_branch:-$current_branch}"
+    if [[ -n "$_wip_branch" && "$_wip_branch" != "$original_branch" ]]; then
+        branch_save_wip "$project_root" "$_wip_branch"
+    fi
+
+    log_info "Ensuring return to original branch: $original_branch (currently on: ${current_branch:-unknown})"
+
+    # Stash any tracked dirty files that would block checkout
+    # (branch_save_wip should have committed everything, but this is a safety net
+    #  in case the commit failed or new files appeared)
+    local had_stash=false
+    local tracked_dirty
+    tracked_dirty=$(git -C "$project_root" diff --name-only 2>/dev/null || true)
+    local staged_dirty
+    staged_dirty=$(git -C "$project_root" diff --cached --name-only 2>/dev/null || true)
+    if [[ -n "$tracked_dirty" || -n "$staged_dirty" ]]; then
+        if git -C "$project_root" stash push -m "pipeline-ensure-return-stash" 2>/dev/null; then
+            had_stash=true
+        fi
+    fi
+
+    # Checkout original branch
+    if git -C "$project_root" checkout "$original_branch" 2>/dev/null; then
+        log_info "Returned to branch: $original_branch"
+    else
+        log_error "Failed to checkout $original_branch — manual recovery needed"
+    fi
+
+    # Restore stashed files
+    if [[ "$had_stash" == true ]]; then
+        if ! git -C "$project_root" stash pop 2>/dev/null; then
+            log_warn "git stash pop failed during branch return — stashed changes may be lost. Run 'git stash list' to check."
+        fi
+    fi
 
     return 0
 }

package/bundled/dev-pipeline/reset-bug.sh

@@ -139,22 +139,20 @@ fi
 BUG_IDS=()
 
 if [[ -n "$FILTER_MODE" ]]; then
-    # Filter by status from .prizmkit/state/bugfix/bugs/*/status.json
+    # Filter by status from bug-fix-list.json (single source of truth)
     while IFS= read -r bid; do
         [[ -n "$bid" ]] && BUG_IDS+=("$bid")
     done < <(python3 -c "
-import json, os, sys
-state_dir = '$STATE_DIR'
+import json, sys
 filter_mode = '$FILTER_MODE'
-bugs_dir = os.path.join(state_dir, 'bugs')
-if not os.path.isdir(bugs_dir):
-    sys.exit(0)
-for bid in sorted(os.listdir(bugs_dir)):
-    status_file = os.path.join(bugs_dir, bid, 'status.json')
-    if not os.path.isfile(status_file):
+bug_list = '$BUG_LIST'
+with open(bug_list) as f:
+    data = json.load(f)
+for bug in data.get('bugs', []):
+    if not isinstance(bug, dict):
         continue
-    with open(status_file) as f:
-        status = json.load(f).get('status', '')
+    bid = bug.get('id', '')
+    status = bug.get('status', '')
     if filter_mode == 'auto_skipped' and status == 'auto_skipped':
         print(bid)
     elif filter_mode == 'failed' and status == 'failed':
@@ -244,13 +242,23 @@ sys.exit(1)
     echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
 
     STATUS_FILE="$STATE_DIR/bugs/$CUR_BUG_ID/status.json"
+    # Read status from bug-fix-list.json (single source of truth)
+    CURRENT_STATUS=$(python3 -c "
+import json, sys
+with open('$BUG_LIST') as f:
+    data = json.load(f)
+for bug in data.get('bugs', []):
+    if isinstance(bug, dict) and bug.get('id') == '$CUR_BUG_ID':
+        print(bug.get('status', '?'))
+        sys.exit(0)
+print('?')
+" 2>/dev/null || echo "?")
     if [[ -f "$STATUS_FILE" ]]; then
-        CURRENT_STATUS=$(python3 -c "import json; d=json.load(open('$STATUS_FILE')); print(d.get('status','?'))")
         CURRENT_RETRY=$(python3 -c "import json; d=json.load(open('$STATUS_FILE')); print(d.get('retry_count',0))")
         SESSION_COUNT=$(python3 -c "import json; d=json.load(open('$STATUS_FILE')); print(len(d.get('sessions',[])))")
         log_info "Current status: $CURRENT_STATUS (retry $CURRENT_RETRY, $SESSION_COUNT sessions)"
     else
-        log_info "No status file found (never executed)"
+        log_info "Current status: $CURRENT_STATUS (no runtime state file)"
     fi
 
     BUGFIX_DIR="$PROJECT_ROOT/.prizmkit/bugfix/$CUR_BUG_ID"

package/bundled/dev-pipeline/reset-feature.sh

@@ -139,22 +139,20 @@ fi
 FEATURE_IDS=()
 
 if [[ -n "$FILTER_MODE" ]]; then
-    # Filter by status from state/features/*/status.json
+    # Filter by status from feature-list.json (single source of truth)
     while IFS= read -r fid; do
         [[ -n "$fid" ]] && FEATURE_IDS+=("$fid")
     done < <(python3 -c "
-import json, os, sys
-state_dir = '$STATE_DIR'
+import json, sys
 filter_mode = '$FILTER_MODE'
-features_dir = os.path.join(state_dir, 'features')
-if not os.path.isdir(features_dir):
-    sys.exit(0)
-for fid in sorted(os.listdir(features_dir)):
-    status_file = os.path.join(features_dir, fid, 'status.json')
-    if not os.path.isfile(status_file):
+feature_list = '$FEATURE_LIST'
+with open(feature_list) as f:
+    data = json.load(f)
+for feat in data.get('features', []):
+    if not isinstance(feat, dict):
         continue
-    with open(status_file) as f:
-        status = json.load(f).get('status', '')
+    fid = feat.get('id', '')
+    status = feat.get('status', '')
     if filter_mode == 'auto_skipped' and status == 'auto_skipped':
         print(fid)
     elif filter_mode == 'failed' and status == 'failed':
@@ -253,13 +251,23 @@ sys.exit(1)
     echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
 
     STATUS_FILE="$STATE_DIR/features/$CUR_FEATURE_ID/status.json"
+    # Read status from feature-list.json (single source of truth)
+    CURRENT_STATUS=$(python3 -c "
+import json, sys
+with open('$FEATURE_LIST') as f:
+    data = json.load(f)
+for feat in data.get('features', []):
+    if isinstance(feat, dict) and feat.get('id') == '$CUR_FEATURE_ID':
+        print(feat.get('status', '?'))
+        sys.exit(0)
+print('?')
+" 2>/dev/null || echo "?")
     if [[ -f "$STATUS_FILE" ]]; then
-        CURRENT_STATUS=$(python3 -c "import json; d=json.load(open('$STATUS_FILE')); print(d.get('status','?'))")
         CURRENT_RETRY=$(python3 -c "import json; d=json.load(open('$STATUS_FILE')); print(d.get('retry_count',0))")
         SESSION_COUNT=$(python3 -c "import json; d=json.load(open('$STATUS_FILE')); print(len(d.get('sessions',[])))")
         log_info "Current status: $CURRENT_STATUS (retry $CURRENT_RETRY, $SESSION_COUNT sessions)"
     else
-        log_info "No status file found (never executed)"
+        log_info "Current status: $CURRENT_STATUS (no runtime state file)"
     fi
 
     SPECS_DIR="$PROJECT_ROOT/.prizmkit/specs/$FEATURE_SLUG"

package/bundled/dev-pipeline/reset-refactor.sh

@@ -129,22 +129,20 @@ fi
 REFACTOR_IDS=()
 
 if [[ -n "$FILTER_MODE" ]]; then
-    # Filter by status from .prizmkit/state/refactor/refactors/*/status.json
+    # Filter by status from refactor-list.json (single source of truth)
     while IFS= read -r rid; do
         [[ -n "$rid" ]] && REFACTOR_IDS+=("$rid")
     done < <(python3 -c "
-import json, os, sys
-state_dir = '$STATE_DIR'
+import json, sys
 filter_mode = '$FILTER_MODE'
-refactors_dir = os.path.join(state_dir, 'refactors')
-if not os.path.isdir(refactors_dir):
-    sys.exit(0)
-for rid in sorted(os.listdir(refactors_dir)):
-    status_file = os.path.join(refactors_dir, rid, 'status.json')
-    if not os.path.isfile(status_file):
+refactor_list = '$REFACTOR_LIST'
+with open(refactor_list) as f:
+    data = json.load(f)
+for r in data.get('refactors', []):
+    if not isinstance(r, dict):
         continue
-    with open(status_file) as f:
-        status = json.load(f).get('status', '')
+    rid = r.get('id', '')
+    status = r.get('status', '')
     if filter_mode == 'auto_skipped' and status == 'auto_skipped':
         print(rid)
     elif filter_mode == 'failed' and status == 'failed':
@@ -242,13 +240,23 @@ sys.exit(1)
     echo -e "${BOLD}════════════════════════════════════════════════════${NC}"
 
     STATUS_FILE="$STATE_DIR/refactors/$CUR_REFACTOR_ID/status.json"
+    # Read status from refactor-list.json (single source of truth)
+    CURRENT_STATUS=$(python3 -c "
+import json, sys
+with open('$REFACTOR_LIST') as f:
+    data = json.load(f)
+for r in data.get('refactors', []):
+    if isinstance(r, dict) and r.get('id') == '$CUR_REFACTOR_ID':
+        print(r.get('status', '?'))
+        sys.exit(0)
+print('?')
+" 2>/dev/null || echo "?")
     if [[ -f "$STATUS_FILE" ]]; then
-        CURRENT_STATUS=$(python3 -c "import json; d=json.load(open('$STATUS_FILE')); print(d.get('status','?'))")
         CURRENT_RETRY=$(python3 -c "import json; d=json.load(open('$STATUS_FILE')); print(d.get('retry_count',0))")
         SESSION_COUNT=$(python3 -c "import json; d=json.load(open('$STATUS_FILE')); print(len(d.get('sessions',[])))")
         log_info "Current status: $CURRENT_STATUS (retry $CURRENT_RETRY, $SESSION_COUNT sessions)"
     else
-        log_info "No status file found (never executed)"
+        log_info "Current status: $CURRENT_STATUS (no runtime state file)"
     fi
 
     SPECS_DIR="$PROJECT_ROOT/.prizmkit/specs/$REFACTOR_SLUG"