prizmkit 1.1.19 → 1.1.21

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

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

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

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

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

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