bmalph 2.9.0 → 2.11.0

package/ralph/ralph_loop.sh

@@ -76,6 +76,7 @@ _env_QUALITY_GATE_TIMEOUT="${QUALITY_GATE_TIMEOUT:-}"
 _env_QUALITY_GATE_ON_COMPLETION_ONLY="${QUALITY_GATE_ON_COMPLETION_ONLY:-}"
 _env_REVIEW_ENABLED="${REVIEW_ENABLED:-}"
 _env_REVIEW_INTERVAL="${REVIEW_INTERVAL:-}"
+_env_REVIEW_MODE="${REVIEW_MODE:-}"
 
 # Now set defaults (only if not already set by environment)
 MAX_CALLS_PER_HOUR="${MAX_CALLS_PER_HOUR:-100}"
@@ -116,6 +117,11 @@ REVIEW_FINDINGS_FILE="$RALPH_DIR/.review_findings.json"
 REVIEW_PROMPT_FILE="$RALPH_DIR/REVIEW_PROMPT.md"
 REVIEW_LAST_SHA_FILE="$RALPH_DIR/.review_last_sha"
 
+# REVIEW_MODE is derived in initialize_runtime_context() after .ralphrc is loaded.
+# This ensures backwards compat: old .ralphrc files with only REVIEW_ENABLED=true
+# still map to enhanced mode. Env vars always win via the snapshot/restore mechanism.
+REVIEW_MODE="${REVIEW_MODE:-off}"
+
 # Valid tool patterns for --allowed-tools validation
 # Default: Claude Code tools. Platform driver overwrites via driver_valid_tools() in main().
 # Validation runs in main() after load_platform_driver so the correct patterns are in effect.
@@ -267,6 +273,7 @@ load_ralphrc() {
     [[ -n "$_env_QUALITY_GATE_ON_COMPLETION_ONLY" ]] && QUALITY_GATE_ON_COMPLETION_ONLY="$_env_QUALITY_GATE_ON_COMPLETION_ONLY"
     [[ -n "$_env_REVIEW_ENABLED" ]] && REVIEW_ENABLED="$_env_REVIEW_ENABLED"
     [[ -n "$_env_REVIEW_INTERVAL" ]] && REVIEW_INTERVAL="$_env_REVIEW_INTERVAL"
+    [[ -n "$_env_REVIEW_MODE" ]] && REVIEW_MODE="$_env_REVIEW_MODE"
 
     normalize_claude_permission_mode
     RALPHRC_FILE="$config_file"
@@ -317,6 +324,14 @@ initialize_runtime_context() {
         fi
     fi
 
+    # Derive REVIEW_MODE after .ralphrc load so backwards-compat works:
+    # old .ralphrc files with only REVIEW_ENABLED=true map to enhanced mode.
+    if [[ "$REVIEW_MODE" == "off" && "$REVIEW_ENABLED" == "true" ]]; then
+        REVIEW_MODE="enhanced"
+    fi
+    # Keep REVIEW_ENABLED in sync for any code that checks it
+    [[ "$REVIEW_MODE" != "off" ]] && REVIEW_ENABLED="true" || REVIEW_ENABLED="false"
+
     # Load platform driver after config so PLATFORM_DRIVER can be overridden.
     load_platform_driver
     RUNTIME_CONTEXT_LOADED=true
@@ -357,7 +372,7 @@ get_tmux_base_index() {
 # Setup tmux session with monitor
 setup_tmux_session() {
     local session_name="ralph-$(date +%s)"
-    local ralph_home="${RALPH_HOME:-$HOME/.ralph}"
+    local ralph_home="${RALPH_HOME:-$SCRIPT_DIR}"
     local project_dir="$(pwd)"
 
     initialize_runtime_context
@@ -516,6 +531,20 @@ log_status() {
     echo "[$timestamp] [$level] $message" >> "$LOG_DIR/ralph.log"
 }
 
+# Human-readable label for a process exit code
+describe_exit_code() {
+    local code=$1
+    case "$code" in
+        0)   echo "completed" ;;
+        1)   echo "error" ;;
+        124) echo "timed out" ;;
+        130) echo "interrupted (SIGINT)" ;;
+        137) echo "killed (OOM or SIGKILL)" ;;
+        143) echo "terminated (SIGTERM)" ;;
+        *)   echo "error (exit $code)" ;;
+    esac
+}
+
 # Update status JSON for external monitoring
 update_status() {
     local loop_count=$1
@@ -523,6 +552,7 @@ update_status() {
     local last_action=$3
     local status=$4
     local exit_reason=${5:-""}
+    local driver_exit_code=${6:-""}
 
     jq -n \
         --arg timestamp "$(get_iso_timestamp)" \
@@ -533,6 +563,7 @@ update_status() {
         --arg status "$status" \
         --arg exit_reason "$exit_reason" \
         --arg next_reset "$(get_next_hour_time)" \
+        --arg driver_exit_code "$driver_exit_code" \
         '{
             timestamp: $timestamp,
             loop_count: $loop_count,
@@ -541,7 +572,8 @@ update_status() {
             last_action: $last_action,
             status: $status,
             exit_reason: $exit_reason,
-            next_reset: $next_reset
+            next_reset: $next_reset,
+            driver_exit_code: (if $driver_exit_code != "" then ($driver_exit_code | tonumber) else null end)
         }' > "$STATUS_FILE"
 
     # Merge quality gate status if results exist
@@ -617,6 +649,44 @@ validate_claude_permission_mode() {
     esac
 }
 
+validate_git_repo() {
+    if ! command -v git &>/dev/null; then
+        log_status "ERROR" "git is not installed or not on PATH."
+        echo ""
+        echo "Ralph requires git for progress detection."
+        echo ""
+        echo "Install git:"
+        echo "  macOS:   brew install git  (or: xcode-select --install)"
+        echo "  Ubuntu:  sudo apt-get install git"
+        echo "  Windows: https://git-scm.com/downloads"
+        echo ""
+        echo "After installing, run this command again."
+        return 1
+    fi
+
+    if ! git rev-parse --git-dir &>/dev/null 2>&1; then
+        log_status "ERROR" "No git repository found in $(pwd)."
+        echo ""
+        echo "Ralph requires a git repository for progress detection."
+        echo ""
+        echo "To fix this, run:"
+        echo "  git init && git add -A && git commit -m 'initial commit'"
+        return 1
+    fi
+
+    if ! git rev-parse HEAD &>/dev/null 2>&1; then
+        log_status "ERROR" "Git repository has no commits."
+        echo ""
+        echo "Ralph requires at least one commit for progress detection."
+        echo ""
+        echo "To fix this, run:"
+        echo "  git add -A && git commit -m 'initial commit'"
+        return 1
+    fi
+
+    return 0
+}
+
 warn_if_allowed_tools_ignored() {
     if driver_supports_tool_allowlist; then
         return 0
@@ -811,6 +881,51 @@ count_fix_plan_checkboxes() {
     printf '%s %s %s\n' "$completed_items" "$uncompleted_items" "$total_items"
 }
 
+# Extract the first unchecked task line from @fix_plan.md.
+# Returns the raw checkbox line trimmed of leading whitespace, capped at 100 chars.
+# Outputs empty string if no unchecked tasks exist or file is missing.
+# Args: $1 = path to @fix_plan.md (optional, defaults to $RALPH_DIR/@fix_plan.md)
+extract_next_fix_plan_task() {
+    local fix_plan_file="${1:-$RALPH_DIR/@fix_plan.md}"
+    [[ -f "$fix_plan_file" ]] || return 0
+    local line
+    line=$(grep -m 1 -E "^[[:space:]]*- \[ \]" "$fix_plan_file" 2>/dev/null || true)
+    # Trim leading whitespace
+    line="${line#"${line%%[![:space:]]*}"}"
+    # Trim trailing whitespace
+    line="${line%"${line##*[![:space:]]}"}"
+    printf '%s' "${line:0:100}"
+}
+
+# Collapse completed story detail lines in @fix_plan.md.
+# For each [x]/[X] story line, strips subsequent indented blockquote lines (  > ...).
+# Incomplete stories keep their detail lines intact.
+# Args: $1 = path to @fix_plan.md (modifies in place via atomic write)
+collapse_completed_stories() {
+    local fix_plan_file="${1:-$RALPH_DIR/@fix_plan.md}"
+    [[ -f "$fix_plan_file" ]] || return 0
+
+    local tmp_file="${fix_plan_file}.collapse_tmp"
+    local skipping=false
+
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        if [[ "$line" =~ ^[[:space:]]*-[[:space:]]*\[[xX]\][[:space:]]*Story[[:space:]]+[0-9] ]]; then
+            skipping=true
+            printf '%s\n' "$line"
+            continue
+        fi
+
+        if $skipping && [[ "$line" =~ ^[[:space:]]+\> ]]; then
+            continue
+        fi
+
+        skipping=false
+        printf '%s\n' "$line"
+    done < "$fix_plan_file" > "$tmp_file"
+
+    mv "$tmp_file" "$fix_plan_file"
+}
+
 enforce_fix_plan_progress_tracking() {
     local analysis_file=$1
     local completed_before=$2
@@ -1226,11 +1341,17 @@ validate_allowed_tools() {
 # Provides loop-specific context via --append-system-prompt
 build_loop_context() {
     local loop_count=$1
+    local session_id="${2:-}"
     local context=""
 
     # Add loop number
     context="Loop #${loop_count}. "
 
+    # Signal session continuity when resuming a valid session
+    if [[ -n "$session_id" ]]; then
+        context+="Session continued — do NOT re-read spec files. Resume implementation. "
+    fi
+
     # Extract incomplete tasks from @fix_plan.md
     # Bug #3 Fix: Support indented markdown checkboxes with [[:space:]]* pattern
     if [[ -f "$RALPH_DIR/@fix_plan.md" ]]; then
@@ -1239,6 +1360,13 @@ build_loop_context() {
         local total_tasks=0
         read -r completed_tasks incomplete_tasks total_tasks < <(count_fix_plan_checkboxes "$RALPH_DIR/@fix_plan.md")
         context+="Remaining tasks: ${incomplete_tasks}. "
+
+        # Inject the next unchecked task to give the AI a clear directive
+        local next_task
+        next_task=$(extract_next_fix_plan_task "$RALPH_DIR/@fix_plan.md")
+        if [[ -n "$next_task" ]]; then
+            context+="Next: ${next_task}. "
+        fi
     fi
 
     # Add circuit breaker state
@@ -1278,31 +1406,119 @@ build_loop_context() {
         fi
     fi
 
+    # Add git diff summary from previous loop (last segment — truncated first if over budget)
+    if [[ -f "$RALPH_DIR/.loop_diff_summary" ]]; then
+        local diff_summary
+        diff_summary=$(head -c 150 "$RALPH_DIR/.loop_diff_summary" 2>/dev/null)
+        if [[ -n "$diff_summary" ]]; then
+            context+="${diff_summary}. "
+        fi
+    fi
+
     # Limit total length to ~500 chars
     echo "${context:0:500}"
 }
 
-# Check if a periodic code review should run this iteration
+# Capture a compact git diff summary after each loop iteration.
+# Writes to $RALPH_DIR/.loop_diff_summary for the next loop's build_loop_context().
+# Args: $1 = loop_start_sha (git HEAD at loop start)
+capture_loop_diff_summary() {
+    local loop_start_sha="${1:-}"
+    local summary_file="$RALPH_DIR/.loop_diff_summary"
+
+    # Clear previous summary
+    rm -f "$summary_file"
+
+    # Require git and a valid repo
+    if ! command -v git &>/dev/null || ! git rev-parse --git-dir &>/dev/null 2>&1; then
+        return 0
+    fi
+
+    local current_sha
+    current_sha=$(git rev-parse HEAD 2>/dev/null || echo "")
+    local numstat_output=""
+
+    if [[ -n "$loop_start_sha" && -n "$current_sha" && "$loop_start_sha" != "$current_sha" ]]; then
+        # Commits exist: union of committed + working tree changes, deduplicated by filename
+        numstat_output=$(
+            {
+                git diff --numstat "$loop_start_sha" HEAD 2>/dev/null
+                git diff --numstat HEAD 2>/dev/null
+                git diff --numstat --cached 2>/dev/null
+            } | awk -F'\t' '!seen[$3]++'
+        )
+    else
+        # No commits: staged + unstaged only
+        numstat_output=$(
+            {
+                git diff --numstat 2>/dev/null
+                git diff --numstat --cached 2>/dev/null
+            } | awk -F'\t' '!seen[$3]++'
+        )
+    fi
+
+    [[ -z "$numstat_output" ]] && return 0
+
+    # Format: Changed: file (+add/-del), file2 (+add/-del)
+    # Skip binary files (numstat shows - - for binary)
+    # Use tab separator — numstat output is tab-delimited (handles filenames with spaces)
+    local formatted
+    formatted=$(echo "$numstat_output" | awk -F'\t' '
+        $1 != "-" {
+            if (n++) printf ", "
+            printf "%s (+%s/-%s)", $3, $1, $2
+        }
+    ')
+
+    [[ -z "$formatted" ]] && return 0
+
+    local result="Changed: ${formatted}"
+    # Self-truncate to ~150 chars (144 content + "...")
+    if [[ ${#result} -gt 147 ]]; then
+        result="${result:0:144}..."
+    fi
+
+    echo "$result" > "$summary_file"
+}
+
+# Check if a code review should run this iteration
 # Returns 0 (true) when review is due, 1 (false) otherwise
+# Args: $1 = loop_count, $2 = fix_plan_completed_delta (optional, for ultimate mode)
 should_run_review() {
-    [[ "$REVIEW_ENABLED" != "true" ]] && return 1
+    [[ "$REVIEW_MODE" == "off" ]] && return 1
     local loop_count=$1
+    local fix_plan_delta=${2:-0}
+
     # Never review on first loop (no implementation yet)
     (( loop_count < 1 )) && return 1
-    (( loop_count % REVIEW_INTERVAL != 0 )) && return 1
+
     # Skip if circuit breaker is not CLOSED
     if [[ -f "$RALPH_DIR/.circuit_breaker_state" ]]; then
         local cb_state
         cb_state=$(jq -r '.state // "CLOSED"' "$RALPH_DIR/.circuit_breaker_state" 2>/dev/null)
         [[ "$cb_state" != "CLOSED" ]] && return 1
     fi
+
+    # Mode-specific trigger
+    case "$REVIEW_MODE" in
+        enhanced)
+            (( loop_count % REVIEW_INTERVAL != 0 )) && return 1
+            ;;
+        ultimate)
+            (( fix_plan_delta < 1 )) && return 1
+            ;;
+        *)
+            # Unknown mode — treat as off
+            return 1
+            ;;
+    esac
+
     # Skip if no changes since last review (committed or uncommitted)
     if command -v git &>/dev/null && git rev-parse --git-dir &>/dev/null 2>&1; then
         local current_sha last_sha
         current_sha=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
         last_sha=""
         [[ -f "$REVIEW_LAST_SHA_FILE" ]] && last_sha=$(cat "$REVIEW_LAST_SHA_FILE" 2>/dev/null)
-        # Check for new commits OR uncommitted workspace changes
         local has_uncommitted
         has_uncommitted=$(git status --porcelain 2>/dev/null | head -1)
         if [[ "$current_sha" == "$last_sha" && -z "$has_uncommitted" ]]; then
@@ -1313,7 +1529,8 @@ should_run_review() {
 }
 
 # Build review findings context for injection into the next implementation loop
-# Returns a compact string (max 500 chars) with unresolved findings
+# Returns a compact string (max 500-700 chars) with unresolved findings
+# HIGH/CRITICAL findings get a PRIORITY prefix and a higher char cap (700)
 build_review_context() {
     if [[ ! -f "$REVIEW_FINDINGS_FILE" ]]; then
         echo ""
@@ -1330,7 +1547,15 @@ build_review_context() {
         return
     fi
 
-    local context="REVIEW FINDINGS ($severity, $issues_found issues): $summary"
+    # HIGH/CRITICAL findings: instruct the AI to fix them before picking a new story
+    local context=""
+    local max_len=500
+    if [[ "$severity" == "HIGH" || "$severity" == "CRITICAL" ]]; then
+        context="PRIORITY: Fix these code review findings BEFORE picking a new story. "
+        max_len=700
+    fi
+    context+="REVIEW FINDINGS ($severity, $issues_found issues): $summary"
+
     # Include top details if space allows
     local top_details
     top_details=$(jq -r '(.details[:2] // []) | map("- [\(.severity)] \(.file): \(.issue)") | join("; ")' "$REVIEW_FINDINGS_FILE" 2>/dev/null | head -c 150)
@@ -1338,7 +1563,7 @@ build_review_context() {
         context+=" Details: $top_details"
     fi
 
-    echo "${context:0:500}"
+    echo "${context:0:$max_len}"
 }
 
 # Execute a periodic code review loop (read-only, no file modifications)
@@ -1916,12 +2141,16 @@ get_live_stream_filter() {
 execute_claude_code() {
     local timestamp=$(date '+%Y-%m-%d_%H-%M-%S')
     local output_file="$LOG_DIR/claude_output_${timestamp}.log"
+    local stderr_file="$LOG_DIR/claude_stderr_${timestamp}.log"
     local loop_count=$1
     local calls_made=$(cat "$CALL_COUNT_FILE" 2>/dev/null || echo "0")
     calls_made=$((calls_made + 1))
     local fix_plan_completed_before=0
     read -r fix_plan_completed_before _ _ < <(count_fix_plan_checkboxes "$RALPH_DIR/@fix_plan.md")
 
+    # Clear previous diff summary to prevent stale context on early exit (#117)
+    rm -f "$RALPH_DIR/.loop_diff_summary"
+
     # Fix #141: Capture git HEAD SHA at loop start to detect commits as progress
     # Store in file for access by progress detection after Claude execution
     local loop_start_sha=""
@@ -1934,21 +2163,22 @@ execute_claude_code() {
     local timeout_seconds=$((CLAUDE_TIMEOUT_MINUTES * 60))
     log_status "INFO" "⏳ Starting $DRIVER_DISPLAY_NAME execution... (timeout: ${CLAUDE_TIMEOUT_MINUTES}m)"
 
+    # Initialize or resume session (must happen before build_loop_context
+    # so the session_id can gate the "session continued" signal)
+    local session_id=""
+    if [[ "$CLAUDE_USE_CONTINUE" == "true" ]] && supports_driver_sessions; then
+        session_id=$(init_claude_session)
+    fi
+
     # Build loop context for session continuity
     local loop_context=""
     if [[ "$CLAUDE_USE_CONTINUE" == "true" ]]; then
-        loop_context=$(build_loop_context "$loop_count")
+        loop_context=$(build_loop_context "$loop_count" "$session_id")
         if [[ -n "$loop_context" && "$VERBOSE_PROGRESS" == "true" ]]; then
             log_status "INFO" "Loop context: $loop_context"
         fi
     fi
 
-    # Initialize or resume session
-    local session_id=""
-    if [[ "$CLAUDE_USE_CONTINUE" == "true" ]] && supports_driver_sessions; then
-        session_id=$(init_claude_session)
-    fi
-
     # Live mode requires JSON output (stream-json) — override text format
     if [[ "$LIVE_OUTPUT" == "true" && "$CLAUDE_OUTPUT_FORMAT" == "text" ]]; then
         log_status "WARN" "Live mode requires JSON output format. Overriding text → json for this session."
@@ -2037,7 +2267,7 @@ execute_claude_code() {
         # read from stdin even in -p (print) mode, causing the process to hang
         set -o pipefail
         portable_timeout ${timeout_seconds}s stdbuf -oL "${LIVE_CMD_ARGS[@]}" \
-            < /dev/null 2>&1 | stdbuf -oL tee "$output_file" | stdbuf -oL jq --unbuffered -j "$jq_filter" 2>/dev/null | tee "$LIVE_LOG_FILE"
+            < /dev/null 2>"$stderr_file" | stdbuf -oL tee "$output_file" | stdbuf -oL jq --unbuffered -j "$jq_filter" 2>/dev/null | tee "$LIVE_LOG_FILE"
 
         # Capture exit codes from pipeline
         local -a pipe_status=("${PIPESTATUS[@]}")
@@ -2089,7 +2319,7 @@ execute_claude_code() {
             # stdin must be redirected from /dev/null because newer Claude CLI versions
             # read from stdin even in -p (print) mode, causing SIGTTIN suspension
             # when the process is backgrounded
-            if portable_timeout ${timeout_seconds}s "${CLAUDE_CMD_ARGS[@]}" < /dev/null > "$output_file" 2>&1 &
+            if portable_timeout ${timeout_seconds}s "${CLAUDE_CMD_ARGS[@]}" < /dev/null > "$output_file" 2>"$stderr_file" &
             then
                 :  # Continue to wait loop
             else
@@ -2104,7 +2334,7 @@ execute_claude_code() {
         # Note: Legacy mode doesn't use --allowedTools, so tool permissions
         # will be handled by Claude Code's default permission system
         if [[ "$use_modern_cli" == "false" ]]; then
-            if portable_timeout ${timeout_seconds}s $CLAUDE_CODE_CMD < "$PROMPT_FILE" > "$output_file" 2>&1 &
+            if portable_timeout ${timeout_seconds}s $CLAUDE_CODE_CMD < "$PROMPT_FILE" > "$output_file" 2>"$stderr_file" &
             then
                 :  # Continue to wait loop
             else
@@ -2163,6 +2393,9 @@ EOF
         exit_code=$?
     fi
 
+    # Expose the raw driver exit code to the main loop for status reporting
+    LAST_DRIVER_EXIT_CODE=$exit_code
+
     if [ $exit_code -eq 0 ]; then
         # Only increment counter on successful execution
         echo "$calls_made" > "$CALL_COUNT_FILE"
@@ -2186,6 +2419,11 @@ EOF
         read -r fix_plan_completed_after _ _ < <(count_fix_plan_checkboxes "$RALPH_DIR/@fix_plan.md")
         enforce_fix_plan_progress_tracking "$RESPONSE_ANALYSIS_FILE" "$fix_plan_completed_before" "$fix_plan_completed_after"
 
+        # Collapse completed story details so the agent doesn't re-read them
+        if [[ $fix_plan_completed_after -gt $fix_plan_completed_before ]]; then
+            collapse_completed_stories "$RALPH_DIR/@fix_plan.md"
+        fi
+
         # Run quality gates
         local exit_signal_for_gates
         exit_signal_for_gates=$(jq -r '.analysis.exit_signal // false' "$RESPONSE_ANALYSIS_FILE" 2>/dev/null || echo "false")
@@ -2248,6 +2486,9 @@ EOF
             fi
         fi
 
+        # Capture diff summary for next loop's context (#117)
+        capture_loop_diff_summary "$loop_start_sha"
+
         local has_errors="false"
 
         # Two-stage error detection to avoid JSON field false positives
@@ -2298,24 +2539,50 @@ EOF
             log_status "ERROR" "🚫 Claude API 5-hour usage limit reached"
             return 2  # Special return code for API limit
         else
-            log_status "ERROR" "❌ $DRIVER_DISPLAY_NAME execution failed, check: $output_file"
+            local exit_desc
+            exit_desc=$(describe_exit_code "$exit_code")
+            log_status "ERROR" "❌ $DRIVER_DISPLAY_NAME exited: $exit_desc (code $exit_code)"
+            if [[ -f "$stderr_file" && -s "$stderr_file" ]]; then
+                log_status "ERROR" "  stderr (last 3 lines): $(tail -3 "$stderr_file")"
+                log_status "ERROR" "  full stderr log: $stderr_file"
+            fi
             return 1
         fi
     fi
 }
 
-# Cleanup function
-cleanup() {
-    log_status "INFO" "Ralph loop interrupted. Cleaning up..."
+# Guard against double cleanup (EXIT fires after signal handler exits)
+_CLEANUP_DONE=false
+
+# EXIT trap — catches set -e failures and other unexpected exits
+_on_exit() {
+    local code=$?
+    [[ "$_CLEANUP_DONE" == "true" ]] && return
+    _CLEANUP_DONE=true
+    if [[ "$code" -ne 0 ]]; then
+        local desc
+        desc=$(describe_exit_code "$code")
+        log_status "ERROR" "Ralph loop exiting unexpectedly: $desc (code $code)"
+        update_status "$loop_count" "$(cat "$CALL_COUNT_FILE" 2>/dev/null || echo "0")" "unexpected_exit" "stopped" "$desc" "$code"
+    fi
+}
+
+# Signal handler — preserves signal identity in exit code
+_on_signal() {
+    local sig=$1
+    log_status "INFO" "Ralph loop interrupted by $sig. Cleaning up..."
     reset_session "manual_interrupt"
-    update_status "$loop_count" "$(cat "$CALL_COUNT_FILE" 2>/dev/null || echo "0")" "interrupted" "stopped"
-    exit 0
+    update_status "$loop_count" "$(cat "$CALL_COUNT_FILE" 2>/dev/null || echo "0")" "interrupted" "stopped" "$sig"
+    _CLEANUP_DONE=true
+    [[ "$sig" == "SIGINT" ]] && exit 130
+    exit 143
 }
 
-# Set up signal handlers
-trap cleanup SIGINT SIGTERM
+trap _on_exit EXIT
+trap '_on_signal SIGINT' SIGINT
+trap '_on_signal SIGTERM' SIGTERM
 
-# Global variable for loop count (needed by cleanup function)
+# Global variable for loop count (needed by trap handlers)
 loop_count=0
 
 # Main loop
@@ -2417,6 +2684,11 @@ main() {
         exit 1
     fi
 
+    # Check for git repository (required for progress detection)
+    if ! validate_git_repo; then
+        exit 1
+    fi
+
     # Initialize session tracking before entering the loop
     init_session_tracking
 
@@ -2499,8 +2771,18 @@ main() {
 
             update_status "$loop_count" "$(cat "$CALL_COUNT_FILE")" "completed" "success"
 
-            # Periodic code review check
-            if should_run_review "$loop_count"; then
+            # Consume review findings after successful execution — the AI has received
+            # the context via --append-system-prompt. Deleting here (not in
+            # build_review_context) ensures findings survive transient loop failures.
+            rm -f "$REVIEW_FINDINGS_FILE"
+
+            # Code review check
+            local fix_plan_delta=0
+            if [[ -f "$RESPONSE_ANALYSIS_FILE" ]]; then
+                fix_plan_delta=$(jq -r '.analysis.fix_plan_completed_delta // 0' "$RESPONSE_ANALYSIS_FILE" 2>/dev/null || echo "0")
+                [[ ! "$fix_plan_delta" =~ ^-?[0-9]+$ ]] && fix_plan_delta=0
+            fi
+            if should_run_review "$loop_count" "$fix_plan_delta"; then
                 run_review_loop "$loop_count"
             fi
 
@@ -2551,7 +2833,12 @@ main() {
                 printf "\n"
             fi
         else
-            update_status "$loop_count" "$(cat "$CALL_COUNT_FILE")" "failed" "error"
+            # Infrastructure failures (timeout, crash, OOM) intentionally bypass
+            # record_loop_result to avoid counting as agent stagnation. The circuit
+            # breaker only tracks progress during successful executions. (Issue #145)
+            local exit_desc
+            exit_desc=$(describe_exit_code "${LAST_DRIVER_EXIT_CODE:-1}")
+            update_status "$loop_count" "$(cat "$CALL_COUNT_FILE")" "failed" "error" "$exit_desc" "${LAST_DRIVER_EXIT_CODE:-}"
             log_status "WARN" "Execution failed, waiting 30 seconds before retry..."
             sleep 30
         fi

package/ralph/templates/PROMPT.md

@@ -4,21 +4,28 @@
 You are Ralph, an autonomous AI development agent working on a [YOUR PROJECT NAME] project.
 
 ## Current Objectives
-1. Study .ralph/specs/* to learn about the project specifications
-2. Review .ralph/@fix_plan.md for current priorities
-3. Implement the highest priority item using best practices
+1. Review .ralph/@fix_plan.md for current priorities
+2. Search the codebase for related code — especially which existing files need changes to integrate your work
+3. Implement the task from the loop context (or the first unchecked item in @fix_plan.md on the first loop)
 4. Use parallel subagents for complex tasks (max 100 concurrent)
 5. Run tests after each implementation
-6. Update documentation and the completed story checkbox in @fix_plan.md
+6. Update the completed story checkbox in @fix_plan.md and commit
+7. Read .ralph/specs/* ONLY if the task requires specific context you don't already have
 
 ## Key Principles
-- ONE task per loop - focus on the most important thing
+- Write code within the first few minutes of each loop
+- ONE task per loop — implement the task specified in the loop context
 - Search the codebase before assuming something isn't implemented
+- Creating new files is often only half the task — wire them into the existing application
 - Use subagents for expensive operations (file searching, analysis)
-- Write comprehensive tests with clear documentation
 - Toggle completed story checkboxes in .ralph/@fix_plan.md without rewriting story lines
 - Commit working changes with descriptive messages
 
+## Session Continuity
+- If you have context from a previous loop, do NOT re-read spec files
+- Resume implementation where you left off
+- Only consult specs when you encounter ambiguity in the current task
+
 ## Progress Tracking (CRITICAL)
 - Ralph tracks progress by counting story checkboxes in .ralph/@fix_plan.md
 - When you complete a story, change `- [ ]` to `- [x]` on that exact story line
@@ -306,7 +313,7 @@ RECOMMENDATION: Blocked on [specific dependency] - need [what's needed]
 - examples/: Example usage and test cases
 
 ## Current Task
-Follow .ralph/@fix_plan.md and choose the most important item to implement next.
-Use your judgment to prioritize what will have the biggest impact on project progress.
+Implement the task specified in the loop context.
+If no task is specified (first loop), pick the first unchecked item from .ralph/@fix_plan.md.
 
 Remember: Quality over speed. Build it right the first time. Know when you're done.

package/ralph/templates/ralphrc.template

@@ -129,13 +129,18 @@ QUALITY_GATE_ON_COMPLETION_ONLY="${QUALITY_GATE_ON_COMPLETION_ONLY:-false}"
 # PERIODIC CODE REVIEW
 # =============================================================================
 
-# Enable periodic code review loops (set via 'bmalph run --review' or manually)
-# When enabled, Ralph runs a read-only review session every REVIEW_INTERVAL loops.
+# Review mode: off, enhanced, or ultimate (set via 'bmalph run --review [mode]')
+# - off:      no code review (default)
+# - enhanced: periodic review every REVIEW_INTERVAL loops (~10-14% more tokens)
+# - ultimate: review after every completed story (~20-30% more tokens)
 # The review agent analyzes git diffs and outputs findings for the next implementation loop.
 # Currently supported on Claude Code only.
+REVIEW_MODE="${REVIEW_MODE:-off}"
+
+# (Legacy) Enables review — prefer REVIEW_MODE instead
 REVIEW_ENABLED="${REVIEW_ENABLED:-false}"
 
-# Number of implementation loops between review sessions (default: 5)
+# Number of implementation loops between review sessions (enhanced mode only)
 REVIEW_INTERVAL="${REVIEW_INTERVAL:-5}"
 
 # =============================================================================