npm - prizmkit - Versions diffs - 1.1.20 → 1.1.21 - Mend

prizmkit 1.1.20 → 1.1.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/bundled/VERSION.json +3 -3
package/bundled/dev-pipeline/lib/branch.sh +187 -23
package/bundled/dev-pipeline/run-bugfix.sh +113 -26
package/bundled/dev-pipeline/run-feature.sh +113 -27
package/bundled/dev-pipeline/run-refactor.sh +113 -26
package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +32 -0
package/bundled/dev-pipeline/templates/bootstrap-tier1.md +22 -7
package/bundled/dev-pipeline/templates/bootstrap-tier2.md +22 -7
package/bundled/dev-pipeline/templates/bootstrap-tier3.md +22 -7
package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md +22 -7
package/bundled/skills/_metadata.json +1 -1
package/package.json +1 -1

package/bundled/VERSION.json CHANGED Viewed

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.20",
-  "bundledAt": "2026-04-11T05:49:50.851Z",
-  "bundledFrom": "13e5e58"
+  "frameworkVersion": "1.1.21",
+  "bundledAt": "2026-04-11T11:23:13.654Z",
+  "bundledFrom": "5137496"
 }

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

@@ -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 CHANGED Viewed

@@ -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))

package/bundled/dev-pipeline/run-feature.sh CHANGED Viewed

@@ -308,8 +308,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
@@ -352,7 +359,7 @@ sys.exit(0)
         fi
     fi
-    # Update feature status
+    # Update feature status (do NOT commit on dev branch — commit happens after merge)
     local update_output
     update_output=$(python3 "$SCRIPTS_DIR/update-feature-status.py" \
         --feature-list "$feature_list" \
@@ -366,12 +373,6 @@ sys.exit(0)
         log_error ".prizmkit/plans/feature-list.json may be out of sync. Manual intervention needed."
     }
-    # Commit feature status update (pipeline management commit)
-    if ! git -C "$project_root" diff --quiet "$feature_list" 2>/dev/null; then
-        git -C "$project_root" add "$feature_list"
-        git -C "$project_root" commit --no-verify -m "chore($feature_id): update feature status" 2>/dev/null || true
-    fi
     # Return status via global variable (avoids $() swallowing stdout)
     _SPAWN_RESULT="$session_status"
 }
@@ -393,13 +394,40 @@ cleanup() {
         log_info "Original branch was: $_ORIGINAL_BRANCH"
     fi
+    # Update status of currently in-progress feature to interrupted
     if [[ -n "$FEATURE_LIST" && -f "$FEATURE_LIST" ]]; then
+        # Find any in-progress feature and mark it as interrupted
+        local _interrupted_id
+        _interrupted_id=$(python3 -c "
+import json, sys
+with open(sys.argv[1]) as f:
+    data = json.load(f)
+for feat in data.get('features', []):
+    if feat.get('status') == 'in_progress':
+        print(feat['id'])
+        break
+" "$FEATURE_LIST" 2>/dev/null || echo "")
+        if [[ -n "$_interrupted_id" ]]; then
+            python3 "$SCRIPTS_DIR/update-feature-status.py" \
+                --feature-list "$FEATURE_LIST" \
+                --state-dir "$STATE_DIR" \
+                --feature-id "$_interrupted_id" \
+                --session-status "failed" \
+                --action update 2>/dev/null || true
+            log_info "Feature $_interrupted_id marked as failed due to interrupt"
+        fi
+        # Pause the pipeline (mark remaining pending items)
         python3 "$SCRIPTS_DIR/update-feature-status.py" \
             --feature-list "$FEATURE_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 "Pipeline paused. Run './run-feature.sh run' to resume."
     exit 130
 }
@@ -814,6 +842,20 @@ else:
             log_info "Development was on branch: $_DEV_BRANCH_NAME"
         fi
         log_info "Session log: $session_dir/logs/session.log"
+        # Update feature status to failed on interrupt
+        if [[ -n "$feature_list" && -f "$feature_list" ]]; then
+            python3 "$SCRIPTS_DIR/update-feature-status.py" \
+                --feature-list "$feature_list" \
+                --state-dir "$STATE_DIR" \
+                --feature-id "$feature_id" \
+                --session-status "failed" \
+                --action update 2>/dev/null || true
+            log_info "Feature $feature_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_feature SIGINT SIGTERM
@@ -827,6 +869,20 @@ else:
     _source_branch=$(git -C "$_proj_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
     _ORIGINAL_BRANCH="$_source_branch"
+    # Mark feature 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-feature-status.py" \
+        --feature-list "$feature_list" \
+        --state-dir "$STATE_DIR" \
+        --feature-id "$feature_id" \
+        --action start >/dev/null 2>&1 || true
+    # Commit the in_progress status on the original branch
+    if ! git -C "$_proj_root" diff --quiet "$feature_list" 2>/dev/null; then
+        git -C "$_proj_root" add "$feature_list" 2>/dev/null || true
+        git -C "$_proj_root" commit --no-verify -m "chore($feature_id): mark in_progress" 2>/dev/null || true
+    fi
     local _branch_name="${DEV_BRANCH:-dev/${feature_id}-$(date +%Y%m%d%H%M)}"
     if branch_create "$_proj_root" "$_branch_name" "$_source_branch"; then
         _DEV_BRANCH_NAME="$_branch_name"
@@ -846,18 +902,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 feature status update on the original branch (after guaranteed return)
+    if ! git -C "$_proj_root" diff --quiet "$feature_list" 2>/dev/null; then
+        git -C "$_proj_root" add "$feature_list"
+        git -C "$_proj_root" commit --no-verify -m "chore($feature_id): update feature status" 2>/dev/null || true
+    fi
     echo ""
     if [[ "$session_status" == "success" ]]; then
         log_success "════════════════════════════════════════════════════"
@@ -980,6 +1041,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
         # Check for stuck features
         local stuck_result
         stuck_result=$(python3 "$SCRIPTS_DIR/detect-stuck.py" \
@@ -1081,7 +1154,21 @@ print(count)
             git -C "$_proj_root" commit --no-verify -m "ready for run $feature_id" 2>/dev/null || true
         fi
-        # Create per-feature dev branch
+        # Mark feature 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-feature-status.py" \
+            --feature-list "$feature_list" \
+            --state-dir "$STATE_DIR" \
+            --feature-id "$feature_id" \
+            --action start >/dev/null 2>&1 || true
+        # Commit the in_progress status on the original branch
+        if ! git -C "$_proj_root" diff --quiet "$feature_list" 2>/dev/null; then
+            git -C "$_proj_root" add "$feature_list" 2>/dev/null || true
+            git -C "$_proj_root" commit --no-verify -m "chore($feature_id): mark in_progress" 2>/dev/null || true
+        fi
+        # Create per-feature dev branch (from the now-updated original branch)
         local _feature_branch="${DEV_BRANCH:-dev/${feature_id}-$(date +%Y%m%d%H%M)}"
         if branch_create "$_proj_root" "$_feature_branch" "$_ORIGINAL_BRANCH"; then
             _DEV_BRANCH_NAME="$_feature_branch"
@@ -1127,6 +1214,8 @@ print(count)
         local gen_output
         gen_output=$(python3 "$SCRIPTS_DIR/generate-bootstrap-prompt.py" "${main_prompt_args[@]}" 2>/dev/null) || {
             log_error "Failed to generate bootstrap prompt for $feature_id"
+            branch_ensure_return "$_proj_root" "$_ORIGINAL_BRANCH"
+            _DEV_BRANCH_NAME=""
             continue
         }
         local feature_model pipeline_mode agent_count critic_enabled
@@ -1146,13 +1235,6 @@ print(count)
         log_info "Pipeline mode: ${BOLD}$pipeline_mode${NC} ($_mode_desc)"
         log_info "Agents: $agent_count (critic: $([ "$critic_enabled" = "true" ] && echo "enabled" || echo "disabled"))"
-        # Mark feature as in-progress before spawning session
-        python3 "$SCRIPTS_DIR/update-feature-status.py" \
-            --feature-list "$feature_list" \
-            --state-dir "$STATE_DIR" \
-            --feature-id "$feature_id" \
-            --action start >/dev/null 2>&1 || true
         # Spawn session and wait
         prizm_log_bootstrap_prompt "$bootstrap_prompt" "$feature_id"
         log_info "Spawning AI CLI session: $session_id"
@@ -1173,19 +1255,23 @@ print(count)
             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"
-                # Return to original branch; state/ files are untracked and persist across checkout
-                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 feature status update on the original branch (after guaranteed return)
+        if ! git -C "$_proj_root" diff --quiet "$feature_list" 2>/dev/null; then
+            git -C "$_proj_root" add "$feature_list"
+            git -C "$_proj_root" commit --no-verify -m "chore($feature_id): update feature status" 2>/dev/null || true
+        fi
         session_count=$((session_count + 1))
         total_subagent_calls=$((total_subagent_calls + _SUBAGENT_COUNT))

package/bundled/dev-pipeline/run-refactor.sh CHANGED Viewed

@@ -262,8 +262,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
@@ -297,7 +304,7 @@ sys.exit(0)
         fi
     fi
-    # Update refactor status
+    # Update refactor status (do NOT commit on dev branch — commit happens after merge)
     python3 "$SCRIPTS_DIR/update-refactor-status.py" \
         --refactor-list "$refactor_list" \
         --state-dir "$STATE_DIR" \
@@ -307,12 +314,6 @@ sys.exit(0)
         --max-retries "$max_retries" \
         --action update >/dev/null 2>&1 || true
-    # Commit .prizmkit/plans/refactor-list.json status update (pipeline management commit)
-    if ! git -C "$project_root" diff --quiet "$refactor_list" 2>/dev/null; then
-        git -C "$project_root" add "$refactor_list"
-        git -C "$project_root" commit --no-verify -m "chore($refactor_id): update refactor status" 2>/dev/null || true
-    fi
     _SPAWN_RESULT="$session_status"
 }
@@ -333,13 +334,40 @@ cleanup() {
         log_info "Original branch was: $_ORIGINAL_BRANCH"
     fi
+    # Update status of currently in-progress refactor to interrupted
     if [[ -n "$REFACTOR_LIST" && -f "$REFACTOR_LIST" ]]; then
+        # Find any in-progress refactor 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 item in data.get('refactors', []):
+    if item.get('status') == 'in_progress':
+        print(item['id'])
+        break
+" "$REFACTOR_LIST" 2>/dev/null || echo "")
+        if [[ -n "$_interrupted_id" ]]; then
+            python3 "$SCRIPTS_DIR/update-refactor-status.py" \
+                --refactor-list "$REFACTOR_LIST" \
+                --state-dir "$STATE_DIR" \
+                --refactor-id "$_interrupted_id" \
+                --session-status "failed" \
+                --action update 2>/dev/null || true
+            log_info "Refactor $_interrupted_id marked as failed due to interrupt"
+        fi
+        # Pause the pipeline
         python3 "$SCRIPTS_DIR/update-refactor-status.py" \
             --refactor-list "$REFACTOR_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 "Refactor pipeline paused. Run './run-refactor.sh run' to resume."
     exit 130
 }
@@ -669,6 +697,20 @@ else:
             log_info "Development was on branch: $_DEV_BRANCH_NAME"
         fi
         log_info "Session log: $session_dir/logs/session.log"
+        # Update refactor status to failed on interrupt
+        if [[ -n "$refactor_list" && -f "$refactor_list" ]]; then
+            python3 "$SCRIPTS_DIR/update-refactor-status.py" \
+                --refactor-list "$refactor_list" \
+                --state-dir "$STATE_DIR" \
+                --refactor-id "$refactor_id" \
+                --session-status "failed" \
+                --action update 2>/dev/null || true
+            log_info "Refactor $refactor_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_refactor SIGINT SIGTERM
@@ -682,6 +724,20 @@ else:
     _source_branch=$(git -C "$_proj_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
     _ORIGINAL_BRANCH="$_source_branch"
+    # Mark refactor 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-refactor-status.py" \
+        --refactor-list "$refactor_list" \
+        --state-dir "$STATE_DIR" \
+        --refactor-id "$refactor_id" \
+        --action start >/dev/null 2>&1 || true
+    # Commit the in_progress status on the original branch
+    if ! git -C "$_proj_root" diff --quiet "$refactor_list" 2>/dev/null; then
+        git -C "$_proj_root" add "$refactor_list" 2>/dev/null || true
+        git -C "$_proj_root" commit --no-verify -m "chore($refactor_id): mark in_progress" 2>/dev/null || true
+    fi
     local _branch_name="${DEV_BRANCH:-refactor/${refactor_id}-$(date +%s)}"
     if branch_create "$_proj_root" "$_branch_name" "$_source_branch"; then
         _DEV_BRANCH_NAME="$_branch_name"
@@ -701,18 +757,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 refactor status update on the original branch (after guaranteed return)
+    if ! git -C "$_proj_root" diff --quiet "$refactor_list" 2>/dev/null; then
+        git -C "$_proj_root" add "$refactor_list"
+        git -C "$_proj_root" commit --no-verify -m "chore($refactor_id): update refactor status" 2>/dev/null || true
+    fi
     echo ""
     if [[ "$session_status" == "success" ]]; then
         log_success "════════════════════════════════════════════════════"
@@ -820,6 +881,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 refactor to process (dependency-topological order)
         local next_refactor
         if ! next_refactor=$(python3 "$SCRIPTS_DIR/update-refactor-status.py" \
@@ -874,7 +947,21 @@ main() {
             git -C "$_proj_root" commit --no-verify -m "chore: capture artifacts before $refactor_id session" 2>/dev/null || true
         fi
-        # Create per-refactor dev branch
+        # Mark refactor 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-refactor-status.py" \
+            --refactor-list "$refactor_list" \
+            --state-dir "$STATE_DIR" \
+            --refactor-id "$refactor_id" \
+            --action start >/dev/null 2>&1 || true
+        # Commit the in_progress status on the original branch
+        if ! git -C "$_proj_root" diff --quiet "$refactor_list" 2>/dev/null; then
+            git -C "$_proj_root" add "$refactor_list" 2>/dev/null || true
+            git -C "$_proj_root" commit --no-verify -m "chore($refactor_id): mark in_progress" 2>/dev/null || true
+        fi
+        # Create per-refactor dev branch (from the now-updated original branch)
         local _refactor_branch="${DEV_BRANCH:-refactor/${refactor_id}-$(date +%Y%m%d%H%M)}"
         if branch_create "$_proj_root" "$_refactor_branch" "$_ORIGINAL_BRANCH"; then
             _DEV_BRANCH_NAME="$_refactor_branch"
@@ -920,6 +1007,8 @@ main() {
         local gen_output
         gen_output=$(python3 "$SCRIPTS_DIR/generate-refactor-prompt.py" "${main_prompt_args[@]}" 2>/dev/null) || {
             log_error "Failed to generate bootstrap prompt for $refactor_id"
+            branch_ensure_return "$_proj_root" "$_ORIGINAL_BRANCH"
+            _DEV_BRANCH_NAME=""
             continue
         }
         local refactor_model pipeline_mode agent_count critic_enabled
@@ -943,13 +1032,6 @@ main() {
             log_info "Refactor model: $refactor_model"
         fi
-        # Mark refactor as in-progress before spawning session
-        python3 "$SCRIPTS_DIR/update-refactor-status.py" \
-            --refactor-list "$refactor_list" \
-            --state-dir "$STATE_DIR" \
-            --refactor-id "$refactor_id" \
-            --action start >/dev/null 2>&1 || true
         # Spawn session
         log_info "Spawning AI CLI session: $session_id"
         _SPAWN_RESULT=""
@@ -979,18 +1061,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 refactor status update on the original branch (after guaranteed return)
+        if ! git -C "$_proj_root" diff --quiet "$refactor_list" 2>/dev/null; then
+            git -C "$_proj_root" add "$refactor_list"
+            git -C "$_proj_root" commit --no-verify -m "chore($refactor_id): update refactor status" 2>/dev/null || true
+        fi
         # Stuck detection
         if python3 "$SCRIPTS_DIR/detect-stuck.py" \
             --state-dir "$STATE_DIR" \

package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py CHANGED Viewed

@@ -1314,6 +1314,36 @@ def build_replacements(args, feature, features, global_context, script_dir):
     if isinstance(testing_config, dict):
         coverage_target = str(testing_config.get("coverage_target", 80))
+    # Detect dev server port from package.json
+    dev_port = "3000"  # Default fallback
+    try:
+        pkg_path = os.path.join(project_root, "package.json")
+        if os.path.isfile(pkg_path):
+            with open(pkg_path, "r", encoding="utf-8") as f:
+                pkg = json.load(f)
+            dev_script = pkg.get("scripts", {}).get("dev", "")
+            # Extract -p <port> from dev script
+            port_match = re.search(r"-p\s+(\d+)", dev_script)
+            if port_match:
+                dev_port = port_match.group(1)
+            else:
+                # Fallback: try NEXT_PUBLIC_SITE_URL from .env files
+                for env_file in [".env.local", ".env"]:
+                    env_path = os.path.join(project_root, env_file)
+                    if os.path.isfile(env_path):
+                        with open(env_path, "r", encoding="utf-8") as ef:
+                            for line in ef:
+                                m = re.match(
+                                    r"NEXT_PUBLIC_SITE_URL\s*=\s*.*?:([0-9]+)", line.strip()
+                                )
+                                if m:
+                                    dev_port = m.group(1)
+                                    break
+                        if dev_port != "3000":
+                            break
+    except Exception:
+        pass  # Keep default 3000 on any error
+    dev_url = f"http://localhost:{dev_port}"
     replacements = {
         "{{RUN_ID}}": args.run_id,
@@ -1356,6 +1386,8 @@ def build_replacements(args, feature, features, global_context, script_dir):
         "{{TEST_CMD}}": test_cmd,
         "{{BASELINE_FAILURES}}": baseline_failures,
         "{{COVERAGE_TARGET}}": coverage_target,
+        "{{DEV_PORT}}": dev_port,
+        "{{DEV_URL}}": dev_url,
     }
     return replacements, effective_resume, browser_enabled

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

@@ -194,17 +194,32 @@ You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without
 You know this project's tech stack. Detect and start the dev server yourself:
 1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
-2. Choose an available port — check what the project defaults to, or pick one that is free:
+2. **Detect the dev server port** — use the pre-detected port from pipeline if available, otherwise extract from project config. Do NOT hardcode or guess the port:
    ```bash
-   lsof -ti:<port> 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   # Use pipeline-injected port if available, otherwise extract from package.json
+   DEV_PORT={{DEV_PORT}}
+   # If DEV_PORT is still a placeholder, detect at runtime:
+   if [ "$DEV_PORT" = "{{DEV_PORT}}" ]; then
+     DEV_PORT=$(node -e "const s=require('./package.json').scripts.dev; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')")
+     if [ -z "$DEV_PORT" ]; then
+       DEV_PORT=$(echo "$NEXT_PUBLIC_SITE_URL" | sed -nE 's|.*:([0-9]+).*|\1|p')
+     fi
+     DEV_PORT=${DEV_PORT:-3000}
+   fi
+   echo "Detected DEV_PORT=$DEV_PORT"
    ```
-3. Start the dev server in background, capture PID:
+3. Verify the port is available:
+   ```bash
+   lsof -ti:$DEV_PORT 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   ```
+4. Start the dev server in background, capture PID:
    ```bash
    <start-command> &
    DEV_SERVER_PID=$!
    ```
-4. Wait for server to be ready: poll the target URL with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
-5. If the page requires authentication, use playwright-cli to register a test user and log in first
+5. Wait for server to be ready: poll `http://localhost:$DEV_PORT` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
+7. If the page requires authentication, use playwright-cli to register a test user and log in first
 **Step 2 — Verification**:
@@ -217,14 +232,14 @@ Take a final screenshot for evidence.
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-2. Verify port is released: `lsof -ti:<port> | xargs kill -9 2>/dev/null || true`
+2. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
 **Step 4 — Reporting**:
 Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
-   URL: <actual URL used>
+   URL: http://localhost:$DEV_PORT
    Dev Server Command: <actual command used>
    Steps executed: [list]
    Screenshot: [path]

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

@@ -292,17 +292,32 @@ You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without
 You know this project's tech stack. Detect and start the dev server yourself:
 1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
-2. Choose an available port — check what the project defaults to, or pick one that is free:
+2. **Detect the dev server port** — use the pre-detected port from pipeline if available, otherwise extract from project config. Do NOT hardcode or guess the port:
    ```bash
-   lsof -ti:<port> 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   # Use pipeline-injected port if available, otherwise extract from package.json
+   DEV_PORT={{DEV_PORT}}
+   # If DEV_PORT is still a placeholder, detect at runtime:
+   if [ "$DEV_PORT" = "{{DEV_PORT}}" ]; then
+     DEV_PORT=$(node -e "const s=require('./package.json').scripts.dev; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')")
+     if [ -z "$DEV_PORT" ]; then
+       DEV_PORT=$(echo "$NEXT_PUBLIC_SITE_URL" | sed -nE 's|.*:([0-9]+).*|\1|p')
+     fi
+     DEV_PORT=${DEV_PORT:-3000}
+   fi
+   echo "Detected DEV_PORT=$DEV_PORT"
    ```
-3. Start the dev server in background, capture PID:
+3. Verify the port is available:
+   ```bash
+   lsof -ti:$DEV_PORT 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   ```
+4. Start the dev server in background, capture PID:
    ```bash
    <start-command> &
    DEV_SERVER_PID=$!
    ```
-4. Wait for server to be ready: poll the target URL with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
-5. If the page requires authentication, use playwright-cli to register a test user and log in first
+5. Wait for server to be ready: poll `http://localhost:$DEV_PORT` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
+7. If the page requires authentication, use playwright-cli to register a test user and log in first
 **Step 2 — Verification**:
@@ -315,14 +330,14 @@ Take a final screenshot for evidence.
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-2. Verify port is released: `lsof -ti:<port> | xargs kill -9 2>/dev/null || true`
+2. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
 **Step 4 — Reporting**:
 Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
-   URL: <actual URL used>
+   URL: http://localhost:$DEV_PORT
    Dev Server Command: <actual command used>
    Steps executed: [list]
    Screenshot: [path]

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

@@ -364,17 +364,32 @@ You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without
 You know this project's tech stack. Detect and start the dev server yourself:
 1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
-2. Choose an available port — check what the project defaults to, or pick one that is free:
+2. **Detect the dev server port** — use the pre-detected port from pipeline if available, otherwise extract from project config. Do NOT hardcode or guess the port:
    ```bash
-   lsof -ti:<port> 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   # Use pipeline-injected port if available, otherwise extract from package.json
+   DEV_PORT={{DEV_PORT}}
+   # If DEV_PORT is still a placeholder, detect at runtime:
+   if [ "$DEV_PORT" = "{{DEV_PORT}}" ]; then
+     DEV_PORT=$(node -e "const s=require('./package.json').scripts.dev; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')")
+     if [ -z "$DEV_PORT" ]; then
+       DEV_PORT=$(echo "$NEXT_PUBLIC_SITE_URL" | sed -nE 's|.*:([0-9]+).*|\1|p')
+     fi
+     DEV_PORT=${DEV_PORT:-3000}
+   fi
+   echo "Detected DEV_PORT=$DEV_PORT"
    ```
-3. Start the dev server in background, capture PID:
+3. Verify the port is available:
+   ```bash
+   lsof -ti:$DEV_PORT 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   ```
+4. Start the dev server in background, capture PID:
    ```bash
    <start-command> &
    DEV_SERVER_PID=$!
    ```
-4. Wait for server to be ready: poll the target URL with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
-5. If the page requires authentication, use playwright-cli to register a test user and log in first
+5. Wait for server to be ready: poll `http://localhost:$DEV_PORT` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
+7. If the page requires authentication, use playwright-cli to register a test user and log in first
 **Step 2 — Verification**:
@@ -387,14 +402,14 @@ Take a final screenshot for evidence.
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-2. Verify port is released: `lsof -ti:<port> | xargs kill -9 2>/dev/null || true`
+2. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
 **Step 4 — Reporting**:
 Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
-   URL: <actual URL used>
+   URL: http://localhost:$DEV_PORT
    Dev Server Command: <actual command used>
    Steps executed: [list]
    Screenshot: [path]

package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md CHANGED Viewed

@@ -7,17 +7,32 @@ You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without
 You know this project's tech stack. Detect and start the dev server yourself:
 1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
-2. Choose an available port — check what the project defaults to, or pick one that is free:
+2. **Detect the dev server port** — use the pre-detected port from pipeline if available, otherwise extract from project config. Do NOT hardcode or guess the port:
    ```bash
-   lsof -ti:<port> 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   # Use pipeline-injected port if available, otherwise extract from package.json
+   DEV_PORT={{DEV_PORT}}
+   # If DEV_PORT is still a placeholder, detect at runtime:
+   if [ "$DEV_PORT" = "{{DEV_PORT}}" ]; then
+     DEV_PORT=$(node -e "const s=require('./package.json').scripts.dev; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')")
+     if [ -z "$DEV_PORT" ]; then
+       DEV_PORT=$(echo "$NEXT_PUBLIC_SITE_URL" | sed -nE 's|.*:([0-9]+).*|\1|p')
+     fi
+     DEV_PORT=${DEV_PORT:-3000}
+   fi
+   echo "Detected DEV_PORT=$DEV_PORT"
    ```
-3. Start the dev server in background, capture PID:
+3. Verify the port is available:
+   ```bash
+   lsof -ti:$DEV_PORT 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   ```
+4. Start the dev server in background, capture PID:
    ```bash
    <start-command> &
    DEV_SERVER_PID=$!
    ```
-4. Wait for server to be ready: poll the target URL with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
-5. If the page requires authentication, use playwright-cli to register a test user and log in first
+5. Wait for server to be ready: poll `http://localhost:$DEV_PORT` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
+7. If the page requires authentication, use playwright-cli to register a test user and log in first
 **Step 2 — Verification**:
@@ -31,14 +46,14 @@ Take a final screenshot for evidence.
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-2. Verify port is released: `lsof -ti:<port> | xargs kill -9 2>/dev/null || true`
+2. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
 **Step 4 — Reporting**:
 Append results to `context-snapshot.md`:
 ```
 ## Browser Verification
-URL: <actual URL used>
+URL: http://localhost:$DEV_PORT
 Dev Server Command: <actual command used>
 Steps executed: [list]
 Screenshot: [path]

package/bundled/skills/_metadata.json CHANGED Viewed

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.20",
+  "version": "1.1.21",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/package.json CHANGED Viewed

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