bmalph 2.7.6 → 2.8.0

package/ralph/ralph_import.sh

@@ -353,9 +353,17 @@ You are Ralph, an autonomous AI development agent working on a [PROJECT NAME] pr
 - Search the codebase before assuming something isn't implemented
 - Use subagents for expensive operations (file searching, analysis)
 - Write comprehensive tests with clear documentation
-- Update @fix_plan.md with your learnings
+- Toggle completed story checkboxes in @fix_plan.md without rewriting story lines
 - Commit working changes with descriptive messages
 
+## Progress Tracking (CRITICAL)
+- Ralph tracks progress by counting story checkboxes in @fix_plan.md
+- When you complete a story, change `- [ ]` to `- [x]` on that exact story line
+- Do NOT remove, rewrite, or reorder story lines in @fix_plan.md
+- Update the checkbox before committing so the monitor updates immediately
+- Set `TASKS_COMPLETED_THIS_LOOP` to the exact number of story checkboxes toggled this loop
+- Only valid values: 0 or 1
+
 ## 🧪 Testing Guidelines (CRITICAL)
 - LIMIT testing to ~20% of your total effort per loop
 - PRIORITIZE: Implementation > Documentation > Tests

package/ralph/ralph_loop.sh

@@ -33,6 +33,7 @@ LIVE_LOG_FILE="$RALPH_DIR/live.log"  # Fixed file for live output monitoring
 CALL_COUNT_FILE="$RALPH_DIR/.call_count"
 TIMESTAMP_FILE="$RALPH_DIR/.last_reset"
 USE_TMUX=false
+PENDING_EXIT_REASON=""
 
 # Save environment variable state BEFORE setting defaults
 # These are used by load_ralphrc() to determine which values came from environment
@@ -68,18 +69,23 @@ _cli_CLAUDE_SESSION_EXPIRY_HOURS="${CLAUDE_SESSION_EXPIRY_HOURS:-}"
 _cli_VERBOSE_PROGRESS="${VERBOSE_PROGRESS:-}"
 _env_CB_COOLDOWN_MINUTES="${CB_COOLDOWN_MINUTES:-}"
 _env_CB_AUTO_RESET="${CB_AUTO_RESET:-}"
+_env_TEST_COMMAND="${TEST_COMMAND:-}"
+_env_QUALITY_GATES="${QUALITY_GATES:-}"
+_env_QUALITY_GATE_MODE="${QUALITY_GATE_MODE:-}"
+_env_QUALITY_GATE_TIMEOUT="${QUALITY_GATE_TIMEOUT:-}"
+_env_QUALITY_GATE_ON_COMPLETION_ONLY="${QUALITY_GATE_ON_COMPLETION_ONLY:-}"
 
 # Now set defaults (only if not already set by environment)
 MAX_CALLS_PER_HOUR="${MAX_CALLS_PER_HOUR:-100}"
 VERBOSE_PROGRESS="${VERBOSE_PROGRESS:-false}"
 CLAUDE_TIMEOUT_MINUTES="${CLAUDE_TIMEOUT_MINUTES:-15}"
-DEFAULT_CLAUDE_ALLOWED_TOOLS="Write,Read,Edit,MultiEdit,Glob,Grep,Task,TodoWrite,WebFetch,WebSearch,NotebookEdit,Bash"
+DEFAULT_CLAUDE_ALLOWED_TOOLS="Write,Read,Edit,MultiEdit,Glob,Grep,Task,TodoWrite,WebFetch,WebSearch,EnterPlanMode,ExitPlanMode,NotebookEdit,Bash"
 DEFAULT_PERMISSION_DENIAL_MODE="continue"
 
 # Modern Claude CLI configuration (Phase 1.1)
 CLAUDE_OUTPUT_FORMAT="${CLAUDE_OUTPUT_FORMAT:-json}"
 CLAUDE_ALLOWED_TOOLS="${CLAUDE_ALLOWED_TOOLS:-$DEFAULT_CLAUDE_ALLOWED_TOOLS}"
-CLAUDE_PERMISSION_MODE="${CLAUDE_PERMISSION_MODE:-auto}"
+CLAUDE_PERMISSION_MODE="${CLAUDE_PERMISSION_MODE:-bypassPermissions}"
 CLAUDE_USE_CONTINUE="${CLAUDE_USE_CONTINUE:-true}"
 PERMISSION_DENIAL_MODE="${PERMISSION_DENIAL_MODE:-$DEFAULT_PERMISSION_DENIAL_MODE}"
 CLAUDE_SESSION_FILE="$RALPH_DIR/.claude_session_id" # Session ID persistence file
@@ -93,6 +99,14 @@ RALPH_SESSION_HISTORY_FILE="$RALPH_DIR/.ralph_session_history"  # Session transi
 # Too short = frequent context loss; Too long = stale context causes unpredictable behavior
 CLAUDE_SESSION_EXPIRY_HOURS=${CLAUDE_SESSION_EXPIRY_HOURS:-24}
 
+# Quality gates configuration
+TEST_COMMAND="${TEST_COMMAND:-}"
+QUALITY_GATES="${QUALITY_GATES:-}"
+QUALITY_GATE_MODE="${QUALITY_GATE_MODE:-warn}"
+QUALITY_GATE_TIMEOUT="${QUALITY_GATE_TIMEOUT:-120}"
+QUALITY_GATE_ON_COMPLETION_ONLY="${QUALITY_GATE_ON_COMPLETION_ONLY:-false}"
+QUALITY_GATE_RESULTS_FILE="$RALPH_DIR/.quality_gate_results"
+
 # 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.
@@ -108,6 +122,8 @@ VALID_TOOL_PATTERNS=(
     "WebFetch"
     "WebSearch"
     "AskUserQuestion"
+    "EnterPlanMode"
+    "ExitPlanMode"
     "Bash"
     "Bash(git *)"
     "Bash(npm *)"
@@ -235,6 +251,11 @@ load_ralphrc() {
     [[ "$_CLI_VERBOSE_PROGRESS" == "true" ]] && VERBOSE_PROGRESS="$_cli_VERBOSE_PROGRESS"
     [[ -n "$_env_CB_COOLDOWN_MINUTES" ]] && CB_COOLDOWN_MINUTES="$_env_CB_COOLDOWN_MINUTES"
     [[ -n "$_env_CB_AUTO_RESET" ]] && CB_AUTO_RESET="$_env_CB_AUTO_RESET"
+    [[ -n "$_env_TEST_COMMAND" ]] && TEST_COMMAND="$_env_TEST_COMMAND"
+    [[ -n "$_env_QUALITY_GATES" ]] && QUALITY_GATES="$_env_QUALITY_GATES"
+    [[ -n "$_env_QUALITY_GATE_MODE" ]] && QUALITY_GATE_MODE="$_env_QUALITY_GATE_MODE"
+    [[ -n "$_env_QUALITY_GATE_TIMEOUT" ]] && QUALITY_GATE_TIMEOUT="$_env_QUALITY_GATE_TIMEOUT"
+    [[ -n "$_env_QUALITY_GATE_ON_COMPLETION_ONLY" ]] && QUALITY_GATE_ON_COMPLETION_ONLY="$_env_QUALITY_GATE_ON_COMPLETION_ONLY"
 
     normalize_claude_permission_mode
     RALPHRC_FILE="$config_file"
@@ -249,7 +270,7 @@ driver_supports_tool_allowlist() {
 driver_permission_denial_help() {
     echo "  - Review the active driver's permission or approval settings."
     echo "  - ALLOWED_TOOLS in $RALPHRC_FILE only applies to the Claude Code driver."
-    echo "  - Keep CLAUDE_PERMISSION_MODE=auto for unattended Claude Code loops."
+    echo "  - Keep CLAUDE_PERMISSION_MODE=bypassPermissions for unattended Claude Code loops."
     echo "  - After updating permissions, reset the session and restart the loop."
 }
 
@@ -511,6 +532,17 @@ update_status() {
             exit_reason: $exit_reason,
             next_reset: $next_reset
         }' > "$STATUS_FILE"
+
+    # Merge quality gate status if results exist
+    if [[ -f "$QUALITY_GATE_RESULTS_FILE" ]]; then
+        local qg_tmp="$STATUS_FILE.qg_tmp"
+        if jq -s '.[0] * {quality_gates: {overall_status: .[1].overall_status, mode: .[1].mode}}' \
+            "$STATUS_FILE" "$QUALITY_GATE_RESULTS_FILE" > "$qg_tmp" 2>/dev/null; then
+            mv "$qg_tmp" "$STATUS_FILE"
+        else
+            rm -f "$qg_tmp" 2>/dev/null
+        fi
+    fi
 }
 
 validate_permission_denial_mode() {
@@ -528,9 +560,34 @@ validate_permission_denial_mode() {
     esac
 }
 
+validate_quality_gate_mode() {
+    local mode=$1
+
+    case "$mode" in
+        warn|block|circuit-breaker)
+            return 0
+            ;;
+        *)
+            echo "Error: Invalid QUALITY_GATE_MODE: '$mode'"
+            echo "Valid modes: warn block circuit-breaker"
+            return 1
+            ;;
+    esac
+}
+
+validate_quality_gate_timeout() {
+    local timeout=$1
+
+    if [[ ! "$timeout" =~ ^[0-9]+$ ]] || [[ "$timeout" -eq 0 ]]; then
+        echo "Error: QUALITY_GATE_TIMEOUT must be a positive integer, got: '$timeout'"
+        return 1
+    fi
+    return 0
+}
+
 normalize_claude_permission_mode() {
     if [[ -z "${CLAUDE_PERMISSION_MODE:-}" ]]; then
-        CLAUDE_PERMISSION_MODE="auto"
+        CLAUDE_PERMISSION_MODE="bypassPermissions"
     fi
 }
 
@@ -726,9 +783,275 @@ wait_for_reset() {
     log_status "SUCCESS" "Rate limit reset! Ready for new calls."
 }
 
+count_fix_plan_checkboxes() {
+    local fix_plan_file="${1:-$RALPH_DIR/@fix_plan.md}"
+    local completed_items=0
+    local uncompleted_items=0
+    local total_items=0
+
+    if [[ -f "$fix_plan_file" ]]; then
+        uncompleted_items=$(grep -cE "^[[:space:]]*- \[ \]" "$fix_plan_file" 2>/dev/null || true)
+        [[ -z "$uncompleted_items" ]] && uncompleted_items=0
+        completed_items=$(grep -cE "^[[:space:]]*- \[[xX]\]" "$fix_plan_file" 2>/dev/null || true)
+        [[ -z "$completed_items" ]] && completed_items=0
+    fi
+
+    total_items=$((completed_items + uncompleted_items))
+    printf '%s %s %s\n' "$completed_items" "$uncompleted_items" "$total_items"
+}
+
+enforce_fix_plan_progress_tracking() {
+    local analysis_file=$1
+    local completed_before=$2
+    local completed_after=$3
+
+    if [[ ! -f "$analysis_file" ]]; then
+        return 0
+    fi
+
+    local claimed_tasks
+    claimed_tasks=$(jq -r '.analysis.tasks_completed_this_loop // 0' "$analysis_file" 2>/dev/null || echo "0")
+    if [[ ! "$claimed_tasks" =~ ^-?[0-9]+$ ]]; then
+        claimed_tasks=0
+    fi
+
+    local fix_plan_completed_delta=$((completed_after - completed_before))
+    local has_progress_tracking_mismatch=false
+    if [[ $claimed_tasks -ne $fix_plan_completed_delta || $claimed_tasks -gt 1 || $fix_plan_completed_delta -gt 1 || $fix_plan_completed_delta -lt 0 ]]; then
+        has_progress_tracking_mismatch=true
+    fi
+
+    local tmp_file="$analysis_file.tmp"
+    if jq \
+        --argjson claimed_tasks "$claimed_tasks" \
+        --argjson fix_plan_completed_delta "$fix_plan_completed_delta" \
+        --argjson has_progress_tracking_mismatch "$has_progress_tracking_mismatch" \
+        '
+            (.analysis //= {}) |
+            .analysis.tasks_completed_this_loop = $claimed_tasks |
+            .analysis.fix_plan_completed_delta = $fix_plan_completed_delta |
+            .analysis.has_progress_tracking_mismatch = $has_progress_tracking_mismatch |
+            if $has_progress_tracking_mismatch then
+                .analysis.has_completion_signal = false |
+                .analysis.exit_signal = false
+            else
+                .
+            end
+        ' "$analysis_file" > "$tmp_file" 2>/dev/null; then
+        mv "$tmp_file" "$analysis_file"
+    else
+        rm -f "$tmp_file" 2>/dev/null
+        return 0
+    fi
+
+    if [[ "$has_progress_tracking_mismatch" == "true" ]]; then
+        log_status "WARN" "Progress tracking mismatch: claimed $claimed_tasks completed task(s) but checkbox delta was $fix_plan_completed_delta. Completion signals suppressed for this loop."
+    fi
+
+    return 0
+}
+
+# Run the built-in test gate
+# Reads tests_status from .response_analysis. If FAILING and TEST_COMMAND is set,
+# runs the command to verify. Returns JSON with status/verified/output on stdout.
+run_test_gate() {
+    local analysis_file=$1
+
+    if [[ ! -f "$analysis_file" ]]; then
+        echo '{"status":"skip","tests_status_reported":"","verified":false,"output":""}'
+        return 0
+    fi
+
+    local tests_status
+    tests_status=$(jq -r '.analysis.tests_status // "UNKNOWN"' "$analysis_file" 2>/dev/null || echo "UNKNOWN")
+
+    if [[ "$tests_status" == "UNKNOWN" && -z "$TEST_COMMAND" ]]; then
+        echo '{"status":"skip","tests_status_reported":"UNKNOWN","verified":false,"output":""}'
+        return 0
+    fi
+
+    if [[ "$tests_status" == "PASSING" && -z "$TEST_COMMAND" ]]; then
+        jq -n --arg ts "$tests_status" '{"status":"pass","tests_status_reported":$ts,"verified":false,"output":""}'
+        return 0
+    fi
+
+    if [[ -n "$TEST_COMMAND" ]]; then
+        local cmd_output=""
+        local cmd_exit=0
+        cmd_output=$(portable_timeout "${QUALITY_GATE_TIMEOUT}s" bash -c "$TEST_COMMAND" 2>&1) || cmd_exit=$?
+        cmd_output="${cmd_output:0:500}"
+
+        local verified_status="pass"
+        if [[ $cmd_exit -ne 0 ]]; then
+            verified_status="fail"
+        fi
+
+        jq -n \
+            --arg status "$verified_status" \
+            --arg ts "$tests_status" \
+            --arg out "$cmd_output" \
+            '{"status":$status,"tests_status_reported":$ts,"verified":true,"output":$out}'
+        return 0
+    fi
+
+    # No TEST_COMMAND, trust the reported status
+    local gate_status="pass"
+    if [[ "$tests_status" == "FAILING" ]]; then
+        gate_status="fail"
+    fi
+
+    jq -n \
+        --arg status "$gate_status" \
+        --arg ts "$tests_status" \
+        '{"status":$status,"tests_status_reported":$ts,"verified":false,"output":""}'
+}
+
+# Run user-defined quality gate commands
+# Splits QUALITY_GATES on semicolons, runs each with portable_timeout.
+# Returns JSON array of results on stdout.
+run_custom_gates() {
+    if [[ -z "$QUALITY_GATES" ]]; then
+        echo "[]"
+        return 0
+    fi
+
+    local results="[]"
+    local gates
+    IFS=";" read -ra gates <<< "$QUALITY_GATES"
+
+    for gate_cmd in "${gates[@]}"; do
+        gate_cmd=$(echo "$gate_cmd" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+        [[ -z "$gate_cmd" ]] && continue
+
+        local cmd_output=""
+        local cmd_exit=0
+        local start_time
+        start_time=$(date +%s)
+        local timed_out="false"
+
+        cmd_output=$(portable_timeout "${QUALITY_GATE_TIMEOUT}s" bash -c "$gate_cmd" 2>&1) || cmd_exit=$?
+
+        local end_time
+        end_time=$(date +%s)
+        local duration=$((end_time - start_time))
+
+        # portable_timeout returns 124 on timeout
+        if [[ $cmd_exit -eq 124 ]]; then
+            timed_out="true"
+        fi
+
+        cmd_output="${cmd_output:0:500}"
+
+        local gate_status="pass"
+        if [[ $cmd_exit -ne 0 ]]; then
+            gate_status="fail"
+        fi
+
+        results=$(echo "$results" | jq \
+            --arg cmd "$gate_cmd" \
+            --arg status "$gate_status" \
+            --argjson exit_code "$cmd_exit" \
+            --arg out "$cmd_output" \
+            --argjson dur "$duration" \
+            --argjson timed_out "$timed_out" \
+            '. += [{"command":$cmd,"status":$status,"exit_code":$exit_code,"output":$out,"duration_seconds":$dur,"timed_out":$timed_out}]'
+        )
+    done
+
+    echo "$results"
+}
+
+# Orchestrator: run all quality gates and write results file
+# Args: loop_number exit_signal_active
+# Returns (on stdout): 0=pass/warn, 1=block failure, 2=circuit-breaker failure
+run_quality_gates() {
+    local loop_number=$1
+    local exit_signal_active=${2:-"false"}
+
+    # Skip if no gates configured
+    if [[ -z "$TEST_COMMAND" && -z "$QUALITY_GATES" ]]; then
+        echo "0"
+        return 0
+    fi
+
+    # Skip if completion-only mode and not completing
+    if [[ "$QUALITY_GATE_ON_COMPLETION_ONLY" == "true" && "$exit_signal_active" != "true" ]]; then
+        echo "0"
+        return 0
+    fi
+
+    local test_gate_json
+    test_gate_json=$(run_test_gate "$RESPONSE_ANALYSIS_FILE")
+
+    local custom_gates_json
+    custom_gates_json=$(run_custom_gates)
+
+    # Determine overall status
+    local overall_status="pass"
+    local test_gate_status
+    test_gate_status=$(echo "$test_gate_json" | jq -r '.status' 2>/dev/null || echo "skip")
+    if [[ "$test_gate_status" == "fail" ]]; then
+        overall_status="fail"
+    fi
+
+    local custom_fail_count
+    custom_fail_count=$(echo "$custom_gates_json" | jq '[.[] | select(.status == "fail")] | length' 2>/dev/null || echo "0")
+    if [[ $custom_fail_count -gt 0 ]]; then
+        overall_status="fail"
+    fi
+
+    # Write results file atomically (tmp+mv to avoid truncation on jq failure)
+    local qg_tmp="$QUALITY_GATE_RESULTS_FILE.tmp"
+    if jq -n \
+        --arg timestamp "$(get_iso_timestamp)" \
+        --argjson loop_number "$loop_number" \
+        --argjson test_gate "$test_gate_json" \
+        --argjson custom_gates "$custom_gates_json" \
+        --arg overall_status "$overall_status" \
+        --arg mode "$QUALITY_GATE_MODE" \
+        '{
+            timestamp: $timestamp,
+            loop_number: $loop_number,
+            test_gate: $test_gate,
+            custom_gates: $custom_gates,
+            overall_status: $overall_status,
+            mode: $mode
+        }' > "$qg_tmp" 2>/dev/null; then
+        mv "$qg_tmp" "$QUALITY_GATE_RESULTS_FILE"
+    else
+        rm -f "$qg_tmp" 2>/dev/null
+    fi
+
+    if [[ "$overall_status" == "fail" ]]; then
+        log_status "WARN" "Quality gate failure (mode=$QUALITY_GATE_MODE): test_gate=$test_gate_status, custom_failures=$custom_fail_count"
+    fi
+
+    # Return code based on mode
+    if [[ "$overall_status" == "pass" ]]; then
+        echo "0"
+        return 0
+    fi
+
+    case "$QUALITY_GATE_MODE" in
+        block)
+            echo "1"
+            return 0
+            ;;
+        circuit-breaker)
+            echo "2"
+            return 0
+            ;;
+        *)
+            # warn mode: return 0 even on failure
+            echo "0"
+            return 0
+            ;;
+    esac
+}
+
 # Check if we should gracefully exit
 should_exit_gracefully() {
-    
+
     if [[ ! -f "$EXIT_SIGNALS_FILE" ]]; then
         return 1  # Don't exit, file doesn't exist
     fi
@@ -792,11 +1115,10 @@ should_exit_gracefully() {
     # Fix #144: Only match valid markdown checkboxes, not date entries like [2026-01-29]
     # Valid patterns: "- [ ]" (uncompleted) and "- [x]" or "- [X]" (completed)
     if [[ -f "$RALPH_DIR/@fix_plan.md" ]]; then
-        local uncompleted_items=$(grep -cE "^[[:space:]]*- \[ \]" "$RALPH_DIR/@fix_plan.md" 2>/dev/null || true)
-        [[ -z "$uncompleted_items" ]] && uncompleted_items=0
-        local completed_items=$(grep -cE "^[[:space:]]*- \[[xX]\]" "$RALPH_DIR/@fix_plan.md" 2>/dev/null || true)
-        [[ -z "$completed_items" ]] && completed_items=0
-        local total_items=$((uncompleted_items + completed_items))
+        local completed_items=0
+        local uncompleted_items=0
+        local total_items=0
+        read -r completed_items uncompleted_items total_items < <(count_fix_plan_checkboxes "$RALPH_DIR/@fix_plan.md")
 
         if [[ $total_items -gt 0 ]] && [[ $completed_items -eq $total_items ]]; then
             log_status "WARN" "Exit condition: All @fix_plan.md items completed ($completed_items/$total_items)" >&2
@@ -901,8 +1223,10 @@ build_loop_context() {
     # 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
-        local incomplete_tasks=$(grep -cE "^[[:space:]]*- \[ \]" "$RALPH_DIR/@fix_plan.md" 2>/dev/null || true)
-        [[ -z "$incomplete_tasks" ]] && incomplete_tasks=0
+        local completed_tasks=0
+        local incomplete_tasks=0
+        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}. "
     fi
 
@@ -918,7 +1242,28 @@ build_loop_context() {
     if [[ -f "$RESPONSE_ANALYSIS_FILE" ]]; then
         local prev_summary=$(jq -r '.analysis.work_summary // ""' "$RESPONSE_ANALYSIS_FILE" 2>/dev/null | head -c 200)
         if [[ -n "$prev_summary" && "$prev_summary" != "null" ]]; then
-            context+="Previous: ${prev_summary}"
+            context+="Previous: ${prev_summary}. "
+        fi
+    fi
+
+    # Add quality gate failure feedback (block and circuit-breaker modes only)
+    if [[ -f "$QUALITY_GATE_RESULTS_FILE" ]]; then
+        local qg_status qg_mode
+        qg_status=$(jq -r '.overall_status // "pass"' "$QUALITY_GATE_RESULTS_FILE" 2>/dev/null)
+        qg_mode=$(jq -r '.mode // "warn"' "$QUALITY_GATE_RESULTS_FILE" 2>/dev/null)
+
+        if [[ "$qg_status" == "fail" && "$qg_mode" != "warn" ]]; then
+            local test_gate_status
+            test_gate_status=$(jq -r '.test_gate.status // "skip"' "$QUALITY_GATE_RESULTS_FILE" 2>/dev/null)
+            if [[ "$test_gate_status" == "fail" ]]; then
+                context+="TESTS FAILING. "
+            fi
+
+            local failed_gates
+            failed_gates=$(jq -r '[.custom_gates[] | select(.status == "fail") | .command | split(" ")[0:2] | join(" ")] | join(", ")' "$QUALITY_GATE_RESULTS_FILE" 2>/dev/null)
+            if [[ -n "$failed_gates" ]]; then
+                context+="QG fail: ${failed_gates}. "
+            fi
         fi
     fi
 
@@ -1031,7 +1376,15 @@ save_claude_session() {
     # Try to extract session ID from structured output
     if [[ -f "$output_file" ]]; then
         local session_id
-        session_id=$(extract_session_id_from_output "$output_file" 2>/dev/null || echo "")
+        if declare -F driver_extract_session_id_from_output >/dev/null; then
+            session_id=$(driver_extract_session_id_from_output "$output_file" 2>/dev/null || echo "")
+        fi
+        if [[ -z "$session_id" || "$session_id" == "null" ]]; then
+            session_id=$(extract_session_id_from_output "$output_file" 2>/dev/null || echo "")
+        fi
+        if [[ -z "$session_id" || "$session_id" == "null" ]] && declare -F driver_fallback_session_id >/dev/null; then
+            session_id=$(driver_fallback_session_id "$output_file" 2>/dev/null || echo "")
+        fi
         if [[ -n "$session_id" && "$session_id" != "null" ]]; then
             echo "$session_id" > "$CLAUDE_SESSION_FILE"
             sync_ralph_session_with_driver "$session_id"
@@ -1410,6 +1763,8 @@ execute_claude_code() {
     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")
 
     # 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
@@ -1664,12 +2019,36 @@ EOF
         analyze_response "$output_file" "$loop_count"
         local analysis_exit_code=$?
 
+        local fix_plan_completed_after=0
+        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"
+
+        # 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")
+        local qg_result
+        qg_result=$(run_quality_gates "$loop_count" "$exit_signal_for_gates")
+
+        # Block mode: suppress exit signals so the loop keeps running
+        if [[ "$qg_result" == "1" ]]; then
+            log_status "WARN" "Quality gate block: suppressing completion signals"
+            local qg_tmp="$RESPONSE_ANALYSIS_FILE.qg_tmp"
+            if jq '.analysis.has_completion_signal = false | .analysis.exit_signal = false' \
+                "$RESPONSE_ANALYSIS_FILE" > "$qg_tmp" 2>/dev/null; then
+                mv "$qg_tmp" "$RESPONSE_ANALYSIS_FILE"
+            else
+                rm -f "$qg_tmp" 2>/dev/null
+            fi
+        fi
+
         # Update exit signals based on analysis
         update_exit_signals
 
         # Log analysis summary
         log_analysis_summary
 
+        PENDING_EXIT_REASON=$(should_exit_gracefully)
+
         # Get file change count for circuit breaker
         # Fix #141: Detect both uncommitted changes AND committed changes
         local files_changed=0
@@ -1730,6 +2109,13 @@ EOF
         fi
         local output_length=$(wc -c < "$output_file" 2>/dev/null || echo 0)
 
+        # Circuit-breaker mode: override progress signals so circuit breaker sees no-progress
+        if [[ "$qg_result" == "2" ]]; then
+            log_status "WARN" "Quality gate circuit-breaker: overriding progress signals"
+            files_changed=0
+            has_errors="true"
+        fi
+
         # Record result in circuit breaker
         record_loop_result "$loop_count" "$files_changed" "$has_errors" "$output_length"
         local circuit_result=$?
@@ -1777,6 +2163,18 @@ main() {
         exit 1
     fi
 
+    if [[ -n "$QUALITY_GATES" || -n "$TEST_COMMAND" ]]; then
+        if ! validate_quality_gate_mode "$QUALITY_GATE_MODE"; then
+            exit 1
+        fi
+        if ! validate_quality_gate_timeout "$QUALITY_GATE_TIMEOUT"; then
+            exit 1
+        fi
+        if ! has_timeout_command; then
+            log_status "WARN" "No timeout command available. Quality gate and test commands will fail. Install coreutils to enable timeout support."
+        fi
+    fi
+
     if [[ "$(driver_name)" == "claude-code" ]]; then
         normalize_claude_permission_mode
 
@@ -1921,6 +2319,21 @@ main() {
                 continue
             fi
 
+            if [[ -n "$PENDING_EXIT_REASON" ]]; then
+                local exit_reason="$PENDING_EXIT_REASON"
+                PENDING_EXIT_REASON=""
+
+                log_status "SUCCESS" "🏁 Graceful exit triggered: $exit_reason"
+                reset_session "project_complete"
+                update_status "$loop_count" "$(cat "$CALL_COUNT_FILE")" "graceful_exit" "completed" "$exit_reason"
+
+                log_status "SUCCESS" "🎉 Ralph has completed the project! Final stats:"
+                log_status "INFO" "  - Total loops: $loop_count"
+                log_status "INFO" "  - API calls used: $(cat "$CALL_COUNT_FILE")"
+                log_status "INFO" "  - Exit reason: $exit_reason"
+                break
+            fi
+
             update_status "$loop_count" "$(cat "$CALL_COUNT_FILE")" "completed" "success"
 
             # Brief pause between successful executions
@@ -2006,7 +2419,7 @@ Options:
 Modern CLI Options (Phase 1.1):
     --output-format FORMAT  Set driver output format: json or text (default: $CLAUDE_OUTPUT_FORMAT)
                             Note: --live mode requires JSON and will auto-switch
-    --allowed-tools TOOLS   Claude Code only. Ignored by codex, cursor, and copilot
+    --allowed-tools TOOLS   Claude Code only. Ignored by codex, opencode, cursor, and copilot
     --no-continue           Disable session continuity across loops
     --session-expiry HOURS  Set session expiration time in hours (default: $CLAUDE_SESSION_EXPIRY_HOURS)
 

package/ralph/templates/PROMPT.md

@@ -9,16 +9,24 @@ You are Ralph, an autonomous AI development agent working on a [YOUR PROJECT NAM
 3. Implement the highest priority item using best practices
 4. Use parallel subagents for complex tasks (max 100 concurrent)
 5. Run tests after each implementation
-6. Update documentation and @fix_plan.md
+6. Update documentation and the completed story checkbox in @fix_plan.md
 
 ## Key Principles
 - ONE task per loop - focus on the most important thing
 - Search the codebase before assuming something isn't implemented
 - Use subagents for expensive operations (file searching, analysis)
 - Write comprehensive tests with clear documentation
-- Update .ralph/@fix_plan.md with your learnings
+- Toggle completed story checkboxes in .ralph/@fix_plan.md without rewriting story lines
 - Commit working changes with descriptive messages
 
+## 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
+- Do NOT remove, rewrite, or reorder story lines in .ralph/@fix_plan.md
+- Update the checkbox before committing so the monitor updates immediately
+- Set `TASKS_COMPLETED_THIS_LOOP` to the exact number of story checkboxes toggled this loop
+- Only valid values: 0 or 1
+
 ## 🧪 Testing Guidelines (CRITICAL)
 - LIMIT testing to ~20% of your total effort per loop
 - PRIORITIZE: Implementation > Documentation > Tests
@@ -34,6 +42,8 @@ You are Ralph, an autonomous AI development agent working on a [YOUR PROJECT NAM
 - Keep .ralph/@AGENT.md updated with build/run instructions
 - Document the WHY behind tests and implementations
 - No placeholder implementations - build it properly
+
+## Autonomous Mode (CRITICAL)
 - do not ask the user questions during loop execution
 - do not use AskUserQuestion, EnterPlanMode, or ExitPlanMode during loop execution
 - make the safest reasonable assumption and continue
@@ -47,7 +57,7 @@ You are Ralph, an autonomous AI development agent working on a [YOUR PROJECT NAM
 ```
 ---RALPH_STATUS---
 STATUS: IN_PROGRESS | COMPLETE | BLOCKED
-TASKS_COMPLETED_THIS_LOOP: <number>
+TASKS_COMPLETED_THIS_LOOP: 0 | 1
 FILES_MODIFIED: <number>
 TESTS_STATUS: PASSING | FAILING | NOT_RUN
 WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
@@ -71,7 +81,7 @@ Set EXIT_SIGNAL to **true** when ALL of these conditions are met:
 ```
 ---RALPH_STATUS---
 STATUS: IN_PROGRESS
-TASKS_COMPLETED_THIS_LOOP: 2
+TASKS_COMPLETED_THIS_LOOP: 1
 FILES_MODIFIED: 5
 TESTS_STATUS: PASSING
 WORK_TYPE: IMPLEMENTATION
@@ -234,7 +244,7 @@ RECOMMENDATION: No remaining work, all .ralph/specs implemented
 ```
 ---RALPH_STATUS---
 STATUS: IN_PROGRESS
-TASKS_COMPLETED_THIS_LOOP: 3
+TASKS_COMPLETED_THIS_LOOP: 1
 FILES_MODIFIED: 7
 TESTS_STATUS: PASSING
 WORK_TYPE: IMPLEMENTATION