prizmkit 1.1.19 → 1.1.21

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.19",
-  "bundledAt": "2026-04-11T01:16:59.208Z",
-  "bundledFrom": "fff3866"
+  "frameworkVersion": "1.1.21",
+  "bundledAt": "2026-04-11T11:23:13.654Z",
+  "bundledFrom": "5137496"
 }

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/run-bugfix.sh

@@ -254,8 +254,15 @@ if incomplete:
     sys.exit(1)
 print('ALL_COMPLETE')
 sys.exit(0)
-" "$checkpoint_file" 2>&1)
+" "$checkpoint_file" 2>&1) || checkpoint_result="CHECK_FAILED"
             local check_exit=$?
+            if [[ "$checkpoint_result" == "CHECK_FAILED" ]]; then
+                check_exit=2
+            elif [[ "$checkpoint_result" == *"INCOMPLETE"* ]]; then
+                check_exit=1
+            else
+                check_exit=0
+            fi
             if [[ $check_exit -eq 2 ]]; then
                 log_warn "CHECKPOINT_CORRUPTED: workflow-checkpoint.json is not valid JSON"
             elif [[ $check_exit -eq 1 ]]; then
@@ -270,7 +277,7 @@ sys.exit(0)
     # Subagent detection
     prizm_detect_subagents "$session_log"
 
-    # Update bug status
+    # Update bug status (do NOT commit on dev branch — commit happens after merge)
     python3 "$SCRIPTS_DIR/update-bug-status.py" \
         --bug-list "$bug_list" \
         --state-dir "$STATE_DIR" \
@@ -280,12 +287,6 @@ sys.exit(0)
         --max-retries "$max_retries" \
         --action update >/dev/null 2>&1 || true
 
-    # Commit .prizmkit/plans/bug-fix-list.json status update (pipeline management commit)
-    if ! git -C "$project_root" diff --quiet "$bug_list" 2>/dev/null; then
-        git -C "$project_root" add "$bug_list"
-        git -C "$project_root" commit --no-verify -m "chore($bug_id): update bug status" 2>/dev/null || true
-    fi
-
     _SPAWN_RESULT="$session_status"
 }
 
@@ -306,13 +307,40 @@ cleanup() {
         log_info "Original branch was: $_ORIGINAL_BRANCH"
     fi
 
+    # Update status of currently in-progress bug to interrupted
     if [[ -n "$BUG_LIST" && -f "$BUG_LIST" ]]; then
+        # Find any in-progress bug and mark it as failed
+        local _interrupted_id
+        _interrupted_id=$(python3 -c "
+import json, sys
+with open(sys.argv[1]) as f:
+    data = json.load(f)
+for bug in data.get('bugs', []):
+    if bug.get('status') == 'in_progress':
+        print(bug['id'])
+        break
+" "$BUG_LIST" 2>/dev/null || echo "")
+
+        if [[ -n "$_interrupted_id" ]]; then
+            python3 "$SCRIPTS_DIR/update-bug-status.py" \
+                --bug-list "$BUG_LIST" \
+                --state-dir "$STATE_DIR" \
+                --bug-id "$_interrupted_id" \
+                --session-status "failed" \
+                --action update 2>/dev/null || true
+            log_info "Bug $_interrupted_id marked as failed due to interrupt"
+        fi
+
+        # Pause the pipeline
         python3 "$SCRIPTS_DIR/update-bug-status.py" \
             --bug-list "$BUG_LIST" \
             --state-dir "$STATE_DIR" \
             --action pause 2>/dev/null || true
     fi
 
+    # GUARANTEED: always return to original branch (save WIP on dev branch first)
+    branch_ensure_return "$(cd "$SCRIPT_DIR/.." && pwd)" "$_ORIGINAL_BRANCH" "$_DEV_BRANCH_NAME"
+
     log_info "Bug fix pipeline paused. Run './run-bugfix.sh run' to resume."
     exit 130
 }
@@ -639,6 +667,20 @@ else:
             log_info "Development was on branch: $_DEV_BRANCH_NAME"
         fi
         log_info "Session log: $session_dir/logs/session.log"
+
+        # Update bug status to failed on interrupt
+        if [[ -n "$bug_list" && -f "$bug_list" ]]; then
+            python3 "$SCRIPTS_DIR/update-bug-status.py" \
+                --bug-list "$bug_list" \
+                --state-dir "$STATE_DIR" \
+                --bug-id "$bug_id" \
+                --session-status "failed" \
+                --action update 2>/dev/null || true
+            log_info "Bug $bug_id marked as failed due to interrupt"
+        fi
+
+        # GUARANTEED: always return to original branch (save WIP on dev branch first)
+        branch_ensure_return "$(cd "$SCRIPT_DIR/.." && pwd)" "$_ORIGINAL_BRANCH" "$_DEV_BRANCH_NAME"
         exit 130
     }
     trap cleanup_single_bug SIGINT SIGTERM
@@ -652,6 +694,20 @@ else:
     _source_branch=$(git -C "$_proj_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
     _ORIGINAL_BRANCH="$_source_branch"
 
+    # Mark bug as in-progress BEFORE creating dev branch
+    # This ensures the in_progress status commit lands on the original branch,
+    # not the dev branch — preventing rebase conflicts in branch_merge later.
+    python3 "$SCRIPTS_DIR/update-bug-status.py" \
+        --bug-list "$bug_list" \
+        --state-dir "$STATE_DIR" \
+        --bug-id "$bug_id" \
+        --action start >/dev/null 2>&1 || true
+    # Commit the in_progress status on the original branch
+    if ! git -C "$_proj_root" diff --quiet "$bug_list" 2>/dev/null; then
+        git -C "$_proj_root" add "$bug_list" 2>/dev/null || true
+        git -C "$_proj_root" commit --no-verify -m "chore($bug_id): mark in_progress" 2>/dev/null || true
+    fi
+
     local _branch_name="${DEV_BRANCH:-bugfix/${bug_id}-$(date +%s)}"
     if branch_create "$_proj_root" "$_branch_name" "$_source_branch"; then
         _DEV_BRANCH_NAME="$_branch_name"
@@ -671,18 +727,23 @@ else:
         else
             log_warn "Auto-merge failed — dev branch preserved: $_DEV_BRANCH_NAME"
             log_warn "Merge manually: git checkout $_ORIGINAL_BRANCH && git rebase $_DEV_BRANCH_NAME"
-            git -C "$_proj_root" checkout "$_ORIGINAL_BRANCH" 2>/dev/null || true
             _DEV_BRANCH_NAME=""
         fi
     elif [[ -n "$_DEV_BRANCH_NAME" ]]; then
-        # Session failed — return to original branch, preserve dev branch for inspection
-        if ! git -C "$_proj_root" checkout "$_ORIGINAL_BRANCH" 2>/dev/null; then
-            log_warn "Failed to checkout $_ORIGINAL_BRANCH after session failure — staying on dev branch"
-        fi
+        # Session failed — preserve dev branch for inspection
         log_warn "Session failed — dev branch preserved for inspection: $_DEV_BRANCH_NAME"
         _DEV_BRANCH_NAME=""
     fi
 
+    # GUARANTEED: always return to original branch regardless of success/failure/merge outcome
+    branch_ensure_return "$_proj_root" "$_ORIGINAL_BRANCH"
+
+    # Commit bug status update on the original branch (after guaranteed return)
+    if ! git -C "$_proj_root" diff --quiet "$bug_list" 2>/dev/null; then
+        git -C "$_proj_root" add "$bug_list"
+        git -C "$_proj_root" commit --no-verify -m "chore($bug_id): update bug status" 2>/dev/null || true
+    fi
+
     echo ""
     if [[ "$session_status" == "success" ]]; then
         log_success "════════════════════════════════════════════════════"
@@ -785,6 +846,18 @@ main() {
     local total_subagent_calls=0
 
     while true; do
+        # Safety net: ensure we're on the original branch at the start of each iteration.
+        # If a previous iteration's `continue` skipped branch_ensure_return, we could
+        # still be on a dev branch. This prevents cascading branch confusion.
+        if [[ -n "$_ORIGINAL_BRANCH" ]]; then
+            local _cur_branch
+            _cur_branch=$(git -C "$_proj_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)
+            if [[ -n "$_cur_branch" && "$_cur_branch" != "$_ORIGINAL_BRANCH" ]]; then
+                log_warn "Still on branch $_cur_branch at loop start — returning to $_ORIGINAL_BRANCH"
+                branch_ensure_return "$_proj_root" "$_ORIGINAL_BRANCH"
+            fi
+        fi
+
         # Find next bug to process
         local next_bug
         if ! next_bug=$(python3 "$SCRIPTS_DIR/update-bug-status.py" \
@@ -839,7 +912,21 @@ main() {
             git -C "$_proj_root" commit --no-verify -m "chore: capture artifacts before $bug_id session" 2>/dev/null || true
         fi
 
-        # Create per-bug dev branch
+        # Mark bug as in-progress BEFORE creating dev branch
+        # This ensures the in_progress status commit lands on the original branch,
+        # not the dev branch — preventing rebase conflicts in branch_merge later.
+        python3 "$SCRIPTS_DIR/update-bug-status.py" \
+            --bug-list "$bug_list" \
+            --state-dir "$STATE_DIR" \
+            --bug-id "$bug_id" \
+            --action start >/dev/null 2>&1 || true
+        # Commit the in_progress status on the original branch
+        if ! git -C "$_proj_root" diff --quiet "$bug_list" 2>/dev/null; then
+            git -C "$_proj_root" add "$bug_list" 2>/dev/null || true
+            git -C "$_proj_root" commit --no-verify -m "chore($bug_id): mark in_progress" 2>/dev/null || true
+        fi
+
+        # Create per-bug dev branch (from the now-updated original branch)
         local _bug_branch="${DEV_BRANCH:-bugfix/${bug_id}-$(date +%Y%m%d%H%M)}"
         if branch_create "$_proj_root" "$_bug_branch" "$_ORIGINAL_BRANCH"; then
             _DEV_BRANCH_NAME="$_bug_branch"
@@ -885,6 +972,8 @@ main() {
         local gen_output
         gen_output=$(python3 "$SCRIPTS_DIR/generate-bugfix-prompt.py" "${main_prompt_args[@]}" 2>/dev/null) || {
             log_error "Failed to generate bootstrap prompt for $bug_id"
+            branch_ensure_return "$_proj_root" "$_ORIGINAL_BRANCH"
+            _DEV_BRANCH_NAME=""
             continue
         }
         local bug_model pipeline_mode agent_count critic_enabled
@@ -907,13 +996,6 @@ main() {
             log_info "Bug model: $bug_model"
         fi
 
-        # Mark bug as in-progress before spawning session
-        python3 "$SCRIPTS_DIR/update-bug-status.py" \
-            --bug-list "$bug_list" \
-            --state-dir "$STATE_DIR" \
-            --bug-id "$bug_id" \
-            --action start >/dev/null 2>&1 || true
-
         # Spawn session
         log_info "Spawning AI CLI session: $session_id"
         _SPAWN_RESULT=""
@@ -931,18 +1013,23 @@ main() {
             else
                 log_warn "Auto-merge failed — dev branch preserved: $_DEV_BRANCH_NAME"
                 log_warn "Merge manually: git checkout $_ORIGINAL_BRANCH && git rebase $_DEV_BRANCH_NAME"
-                git -C "$_proj_root" checkout "$_ORIGINAL_BRANCH" 2>/dev/null || true
                 _DEV_BRANCH_NAME=""
             fi
         elif [[ -n "$_DEV_BRANCH_NAME" ]]; then
-            # Session failed — return to original branch, preserve dev branch for inspection
-            if ! git -C "$_proj_root" checkout "$_ORIGINAL_BRANCH" 2>/dev/null; then
-                log_warn "Failed to checkout $_ORIGINAL_BRANCH after session failure — staying on dev branch"
-            fi
+            # Session failed — preserve dev branch for inspection
             log_warn "Session failed — dev branch preserved for inspection: $_DEV_BRANCH_NAME"
             _DEV_BRANCH_NAME=""
         fi
 
+        # GUARANTEED: always return to original branch regardless of success/failure/merge outcome
+        branch_ensure_return "$_proj_root" "$_ORIGINAL_BRANCH"
+
+        # Commit bug status update on the original branch (after guaranteed return)
+        if ! git -C "$_proj_root" diff --quiet "$bug_list" 2>/dev/null; then
+            git -C "$_proj_root" add "$bug_list"
+            git -C "$_proj_root" commit --no-verify -m "chore($bug_id): update bug status" 2>/dev/null || true
+        fi
+
         session_count=$((session_count + 1))
         total_subagent_calls=$((total_subagent_calls + _SUBAGENT_COUNT))