bmalph 2.8.0 → 2.10.0

package/ralph/drivers/codex.sh

@@ -46,7 +46,7 @@ driver_permission_denial_help() {
 }
 
 # Build Codex CLI command
-# Codex uses: codex exec [--resume <id>] --json "prompt"
+# Codex uses: codex exec [resume <id>] --json "prompt"
 driver_build_command() {
     local prompt_file=$1
     local loop_context=$2
@@ -67,7 +67,7 @@ driver_build_command() {
 
     # Session resume — gated on CLAUDE_USE_CONTINUE to respect --no-continue flag
     if [[ "$CLAUDE_USE_CONTINUE" == "true" && -n "$session_id" ]]; then
-        CLAUDE_CMD_ARGS+=("--resume" "$session_id")
+        CLAUDE_CMD_ARGS+=("resume" "$session_id")
     fi
 
     # Build prompt with context

package/ralph/lib/response_analyzer.sh

@@ -762,14 +762,14 @@ parse_json_response() {
     local summary_has_no_work_pattern="false"
     if [[ "$response_shape" == "codex_jsonl" || "$response_shape" == "opencode_jsonl" || "$response_shape" == "cursor_stream_jsonl" ]] && [[ "$explicit_exit_signal_found" != "true" && -n "$summary" ]]; then
         for keyword in "${COMPLETION_KEYWORDS[@]}"; do
-            if echo "$summary" | grep -qi "$keyword"; then
+            if echo "$summary" | grep -qiw "$keyword"; then
                 summary_has_completion_keyword="true"
                 break
             fi
         done
 
         for pattern in "${NO_WORK_PATTERNS[@]}"; do
-            if echo "$summary" | grep -qi "$pattern"; then
+            if echo "$summary" | grep -qiw "$pattern"; then
                 summary_has_no_work_pattern="true"
                 break
             fi
@@ -1035,13 +1035,15 @@ analyze_response() {
 
     # Text parsing fallback (original logic)
 
-    # Track whether an explicit EXIT_SIGNAL was found in RALPH_STATUS block
-    # If explicit signal found, heuristics should NOT override Claude's intent
-    local explicit_exit_signal_found=false
-
-    # 1. Check for explicit structured output (if Claude follows schema)
+    # 1. Check for explicit structured output (RALPH_STATUS block)
+    # When a status block is present, it is authoritative — skip all heuristics.
+    # A structurally valid but field-empty block results in exit_signal=false,
+    # confidence=0 by design (AI produced a block but provided no signal).
+    local ralph_status_block_found=false
     local ralph_status_json=""
     if ralph_status_json=$(extract_ralph_status_block_json "$output_content" 2>/dev/null); then
+        ralph_status_block_found=true
+
         local status
         status=$(printf '%s' "$ralph_status_json" | jq -r -j '.status' 2>/dev/null)
         local exit_sig_found
@@ -1062,14 +1064,14 @@ analyze_response() {
 
         # If EXIT_SIGNAL is explicitly provided, respect it
         if [[ "$exit_sig_found" == "true" ]]; then
-            explicit_exit_signal_found=true
             if [[ "$exit_sig" == "true" ]]; then
                 has_completion_signal=true
                 exit_signal=true
                 confidence_score=100
             else
-                # Explicit EXIT_SIGNAL: false - Claude says to continue
+                # Explicit EXIT_SIGNAL: false — Claude says to continue
                 exit_signal=false
+                confidence_score=80
             fi
         elif [[ "$status" == "COMPLETE" ]]; then
             # No explicit EXIT_SIGNAL but STATUS is COMPLETE
@@ -1077,68 +1079,93 @@ analyze_response() {
             exit_signal=true
             confidence_score=100
         fi
+        # is_test_only and is_stuck stay false (defaults) — status block is authoritative
     fi
 
-    # 2. Detect completion keywords in natural language output
-    for keyword in "${COMPLETION_KEYWORDS[@]}"; do
-        if grep -qi "$keyword" "$output_file"; then
-            has_completion_signal=true
-            ((confidence_score+=10))
-            break
-        fi
-    done
+    if [[ "$ralph_status_block_found" != "true" ]]; then
+        # No status block found — fall back to heuristic analysis
 
-    # 3. Detect test-only loops
-    local test_command_count=0
-    local implementation_count=0
-    local error_count=0
+        # 2. Detect completion keywords in natural language output
+        for keyword in "${COMPLETION_KEYWORDS[@]}"; do
+            if grep -qiw "$keyword" "$output_file"; then
+                has_completion_signal=true
+                ((confidence_score+=10))
+                break
+            fi
+        done
 
-    test_command_count=$(grep -c -i "running tests\|npm test\|bats\|pytest\|jest" "$output_file" 2>/dev/null | head -1 || echo "0")
-    implementation_count=$(grep -c -i "implementing\|creating\|writing\|adding\|function\|class" "$output_file" 2>/dev/null | head -1 || echo "0")
+        # 3. Detect test-only loops
+        local test_command_count=0
+        local implementation_count=0
+        local error_count=0
 
-    # Strip whitespace and ensure it's a number
-    test_command_count=$(echo "$test_command_count" | tr -d '[:space:]')
-    implementation_count=$(echo "$implementation_count" | tr -d '[:space:]')
+        test_command_count=$(grep -c -i "running tests\|npm test\|bats\|pytest\|jest" "$output_file" 2>/dev/null | head -1 || echo "0")
+        implementation_count=$(grep -c -i "implementing\|creating\|writing\|adding\|function\|class" "$output_file" 2>/dev/null | head -1 || echo "0")
 
-    # Convert to integers with default fallback
-    test_command_count=${test_command_count:-0}
-    implementation_count=${implementation_count:-0}
-    test_command_count=$((test_command_count + 0))
-    implementation_count=$((implementation_count + 0))
+        # Strip whitespace and ensure it's a number
+        test_command_count=$(echo "$test_command_count" | tr -d '[:space:]')
+        implementation_count=$(echo "$implementation_count" | tr -d '[:space:]')
 
-    if [[ $test_command_count -gt 0 ]] && [[ $implementation_count -eq 0 ]]; then
-        is_test_only=true
-        work_summary="Test execution only, no implementation"
-    fi
+        # Convert to integers with default fallback
+        test_command_count=${test_command_count:-0}
+        implementation_count=${implementation_count:-0}
+        test_command_count=$((test_command_count + 0))
+        implementation_count=$((implementation_count + 0))
 
-    # 4. Detect stuck/error loops
-    # Use two-stage filtering to avoid counting JSON field names as errors
-    # Stage 1: Filter out JSON field patterns like "is_error": false
-    # Stage 2: Count actual error messages in specific contexts
-    # Pattern aligned with ralph_loop.sh to ensure consistent behavior
-    error_count=$(grep -v '"[^"]*error[^"]*":' "$output_file" 2>/dev/null | \
-                  grep -cE '(^Error:|^ERROR:|^error:|\]: error|Link: error|Error occurred|failed with error|[Ee]xception|Fatal|FATAL)' \
-                  2>/dev/null || echo "0")
-    error_count=$(echo "$error_count" | tr -d '[:space:]')
-    error_count=${error_count:-0}
-    error_count=$((error_count + 0))
+        if [[ $test_command_count -gt 0 ]] && [[ $implementation_count -eq 0 ]]; then
+            is_test_only=true
+            work_summary="Test execution only, no implementation"
+        fi
 
-    if [[ $error_count -gt 5 ]]; then
-        is_stuck=true
-    fi
+        # 4. Detect stuck/error loops
+        # Use two-stage filtering to avoid counting JSON field names as errors
+        # Stage 1: Filter out JSON field patterns like "is_error": false
+        # Stage 2: Count actual error messages in specific contexts
+        # Pattern aligned with ralph_loop.sh to ensure consistent behavior
+        error_count=$(grep -v '"[^"]*error[^"]*":' "$output_file" 2>/dev/null | \
+                      grep -cE '(^Error:|^ERROR:|^error:|\]: error|Link: error|Error occurred|failed with error|[Ee]xception|Fatal|FATAL)' \
+                      2>/dev/null || echo "0")
+        error_count=$(echo "$error_count" | tr -d '[:space:]')
+        error_count=${error_count:-0}
+        error_count=$((error_count + 0))
+
+        if [[ $error_count -gt 5 ]]; then
+            is_stuck=true
+        fi
 
-    # 5. Detect "nothing to do" patterns
-    for pattern in "${NO_WORK_PATTERNS[@]}"; do
-        if grep -qi "$pattern" "$output_file"; then
-            has_completion_signal=true
-            ((confidence_score+=15))
-            work_summary="No work remaining"
-            break
+        # 5. Detect "nothing to do" patterns
+        for pattern in "${NO_WORK_PATTERNS[@]}"; do
+            if grep -qiw "$pattern" "$output_file"; then
+                has_completion_signal=true
+                ((confidence_score+=15))
+                work_summary="No work remaining"
+                break
+            fi
+        done
+
+        # 7. Analyze output length trends (detect declining engagement)
+        if [[ -f "$RALPH_DIR/.last_output_length" ]]; then
+            local last_length
+            last_length=$(cat "$RALPH_DIR/.last_output_length")
+            if [[ "$last_length" -gt 0 ]]; then
+                local length_ratio=$((output_length * 100 / last_length))
+                if [[ $length_ratio -lt 50 ]]; then
+                    # Output is less than 50% of previous - possible completion
+                    ((confidence_score+=10))
+                fi
+            fi
         fi
-    done
 
-    # 6. Check for file changes (git integration)
-    # Fix #141: Detect both uncommitted changes AND committed changes
+        # 9. Determine exit signal based on confidence (heuristic)
+        if [[ $confidence_score -ge 40 || "$has_completion_signal" == "true" ]]; then
+            exit_signal=true
+        fi
+    fi
+
+    # Always persist output length for next iteration (both paths)
+    echo "$output_length" > "$RALPH_DIR/.last_output_length"
+
+    # 6. Check for file changes (git integration) — always runs
     if command -v git &>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
         local loop_start_sha=""
         local current_sha=""
@@ -1174,19 +1201,7 @@ analyze_response() {
         fi
     fi
 
-    # 7. Analyze output length trends (detect declining engagement)
-    if [[ -f "$RALPH_DIR/.last_output_length" ]]; then
-        local last_length=$(cat "$RALPH_DIR/.last_output_length")
-        local length_ratio=$((output_length * 100 / last_length))
-
-        if [[ $length_ratio -lt 50 ]]; then
-            # Output is less than 50% of previous - possible completion
-            ((confidence_score+=10))
-        fi
-    fi
-    echo "$output_length" > "$RALPH_DIR/.last_output_length"
-
-    # 8. Extract work summary from output
+    # 8. Extract work summary from output — always runs
     if [[ -z "$work_summary" ]]; then
         # Try to find summary in output
         work_summary=$(grep -i "summary\|completed\|implemented" "$output_file" | head -1 | cut -c 1-100)
@@ -1195,21 +1210,6 @@ analyze_response() {
         fi
     fi
 
-    # Explicit EXIT_SIGNAL=false means "continue working", so completion
-    # heuristics must not register a done signal.
-    if [[ "$explicit_exit_signal_found" == "true" && "$exit_signal" == "false" ]]; then
-        has_completion_signal=false
-    fi
-
-    # 9. Determine exit signal based on confidence (heuristic)
-    # IMPORTANT: Only apply heuristics if no explicit EXIT_SIGNAL was found in RALPH_STATUS
-    # Claude's explicit intent takes precedence over natural language pattern matching
-    if [[ "$explicit_exit_signal_found" != "true" ]]; then
-        if [[ $confidence_score -ge 40 || "$has_completion_signal" == "true" ]]; then
-            exit_signal=true
-        fi
-    fi
-
     local has_permission_denials=false
     local permission_denial_count=0
     local denied_commands_json='[]'

package/ralph/ralph_loop.sh

@@ -74,6 +74,9 @@ _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:-}"
+_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}"
@@ -107,6 +110,18 @@ 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"
 
+# Periodic code review configuration
+REVIEW_ENABLED="${REVIEW_ENABLED:-false}"
+REVIEW_INTERVAL="${REVIEW_INTERVAL:-5}"
+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.
@@ -256,6 +271,9 @@ load_ralphrc() {
     [[ -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"
+    [[ -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"
@@ -306,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
@@ -346,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
@@ -1271,6 +1297,177 @@ build_loop_context() {
     echo "${context:0:500}"
 }
 
+# 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_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
+
+    # 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)
+        local has_uncommitted
+        has_uncommitted=$(git status --porcelain 2>/dev/null | head -1)
+        if [[ "$current_sha" == "$last_sha" && -z "$has_uncommitted" ]]; then
+            return 1
+        fi
+    fi
+    return 0
+}
+
+# Build review findings context for injection into the next implementation loop
+# 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 ""
+        return
+    fi
+
+    local severity issues_found summary
+    severity=$(jq -r '.severity // ""' "$REVIEW_FINDINGS_FILE" 2>/dev/null)
+    issues_found=$(jq -r '.issues_found // 0' "$REVIEW_FINDINGS_FILE" 2>/dev/null)
+    summary=$(jq -r '.summary // ""' "$REVIEW_FINDINGS_FILE" 2>/dev/null | head -c 300)
+
+    if [[ "$issues_found" == "0" || -z "$severity" || "$severity" == "null" ]]; then
+        echo ""
+        return
+    fi
+
+    # 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)
+    if [[ -n "$top_details" && "$top_details" != "null" ]]; then
+        context+=" Details: $top_details"
+    fi
+
+    echo "${context:0:$max_len}"
+}
+
+# Execute a periodic code review loop (read-only, no file modifications)
+# Uses a fresh ephemeral session with restricted tool permissions
+run_review_loop() {
+    local loop_count=$1
+
+    log_status "INFO" "Starting periodic code review (loop #$loop_count)"
+
+    # Get diff context (committed + uncommitted changes)
+    local last_sha=""
+    [[ -f "$REVIEW_LAST_SHA_FILE" ]] && last_sha=$(cat "$REVIEW_LAST_SHA_FILE" 2>/dev/null)
+    local diff_context=""
+    if command -v git &>/dev/null && git rev-parse --git-dir &>/dev/null 2>&1; then
+        local committed_diff="" uncommitted_diff=""
+        if [[ -n "$last_sha" ]]; then
+            committed_diff=$(git diff "$last_sha"..HEAD --stat 2>/dev/null | head -20 || true)
+        else
+            committed_diff=$(git diff HEAD~5..HEAD --stat 2>/dev/null | head -20 || true)
+        fi
+        uncommitted_diff=$(git diff --stat 2>/dev/null | head -10 || true)
+        diff_context="${committed_diff}"
+        if [[ -n "$uncommitted_diff" ]]; then
+            diff_context+=$'\nUncommitted:\n'"${uncommitted_diff}"
+        fi
+        [[ -z "$diff_context" ]] && diff_context="No recent changes"
+    fi
+
+    # Check review prompt exists
+    if [[ ! -f "$REVIEW_PROMPT_FILE" ]]; then
+        log_status "WARN" "Review prompt file not found: $REVIEW_PROMPT_FILE — skipping review"
+        return 0
+    fi
+
+    # Build review-specific context
+    local review_context="CODE REVIEW LOOP (read-only). Analyze changes since last review. Recent changes: $diff_context"
+
+    # Save and override CLAUDE_ALLOWED_TOOLS for read-only mode
+    local saved_tools="$CLAUDE_ALLOWED_TOOLS"
+    CLAUDE_ALLOWED_TOOLS="Read,Glob,Grep"
+
+    local timeout_seconds=$((CLAUDE_TIMEOUT_MINUTES * 60))
+    local review_output_file="$LOG_DIR/review_loop_${loop_count}.log"
+
+    # Build command with review prompt and NO session resume (ephemeral)
+    if driver_build_command "$REVIEW_PROMPT_FILE" "$review_context" ""; then
+        # Execute review (capture output)
+        portable_timeout "${timeout_seconds}s" "${CLAUDE_CMD_ARGS[@]}" \
+            < /dev/null > "$review_output_file" 2>&1 || true
+    fi
+
+    # Restore CLAUDE_ALLOWED_TOOLS
+    CLAUDE_ALLOWED_TOOLS="$saved_tools"
+
+    # Parse review findings from output
+    if [[ -f "$review_output_file" ]]; then
+        # Review ran successfully — save SHA so we don't re-review the same state
+        git rev-parse HEAD > "$REVIEW_LAST_SHA_FILE" 2>/dev/null || true
+
+        local findings_json=""
+        # Extract JSON between ---REVIEW_FINDINGS--- and ---END_REVIEW_FINDINGS--- markers
+        findings_json=$(sed -n '/---REVIEW_FINDINGS---/,/---END_REVIEW_FINDINGS---/{//!p;}' "$review_output_file" 2>/dev/null | tr -d '\n' | head -c 5000)
+
+        # If output is JSON format, try extracting from result field first
+        if [[ -z "$findings_json" ]]; then
+            local raw_text
+            raw_text=$(jq -r '.result // .content // ""' "$review_output_file" 2>/dev/null || cat "$review_output_file" 2>/dev/null)
+            findings_json=$(echo "$raw_text" | sed -n '/---REVIEW_FINDINGS---/,/---END_REVIEW_FINDINGS---/{//!p;}' 2>/dev/null | tr -d '\n' | head -c 5000)
+        fi
+
+        if [[ -n "$findings_json" ]]; then
+            # Validate it's valid JSON before writing
+            if echo "$findings_json" | jq . > /dev/null 2>&1; then
+                local tmp_findings="$REVIEW_FINDINGS_FILE.tmp"
+                echo "$findings_json" > "$tmp_findings"
+                mv "$tmp_findings" "$REVIEW_FINDINGS_FILE"
+                local issue_count
+                issue_count=$(echo "$findings_json" | jq -r '.issues_found // 0' 2>/dev/null)
+                log_status "INFO" "Code review complete. $issue_count issue(s) found."
+            else
+                log_status "WARN" "Review findings JSON is malformed — skipping"
+            fi
+        else
+            log_status "INFO" "Code review complete. No structured findings extracted."
+        fi
+    fi
+}
+
 # Get session file age in seconds (cross-platform)
 # Returns: age in seconds on stdout, or -1 if stat fails
 get_session_file_age_seconds() {
@@ -1805,6 +2002,13 @@ execute_claude_code() {
     if build_claude_command "$PROMPT_FILE" "$loop_context" "$session_id"; then
         use_modern_cli=true
         log_status "INFO" "Using modern CLI mode (${CLAUDE_OUTPUT_FORMAT} output)"
+
+        # Build review findings context (separate from loop context)
+        local review_context=""
+        review_context=$(build_review_context)
+        if [[ -n "$review_context" ]]; then
+            CLAUDE_CMD_ARGS+=("--append-system-prompt" "$review_context")
+        fi
     else
         log_status "WARN" "Failed to build modern CLI command, falling back to legacy mode"
         if [[ "$LIVE_OUTPUT" == "true" ]]; then
@@ -2336,6 +2540,21 @@ main() {
 
             update_status "$loop_count" "$(cat "$CALL_COUNT_FILE")" "completed" "success"
 
+            # 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
+
             # Brief pause between successful executions
             sleep 5
         elif [ $exec_result -eq 3 ]; then

package/ralph/templates/PROMPT.md

@@ -50,6 +50,18 @@ You are Ralph, an autonomous AI development agent working on a [YOUR PROJECT NAM
 - prefer small, reversible changes when requirements are ambiguous
 - surface blockers in the Ralph status block instead of starting a conversation
 
+## Self-Review Checklist (Before Reporting Status)
+
+Before writing your RALPH_STATUS block, review your own work:
+
+1. Re-read the diff of files you modified this loop — check for obvious bugs, typos, missing error handling
+2. Verify you did not introduce regressions in existing functionality
+3. Confirm your changes match the spec in .ralph/specs/ for the story you worked on
+4. Check that new functions have proper error handling and edge case coverage
+5. Ensure you did not leave TODO/FIXME/HACK comments without justification
+
+If you find issues, fix them before reporting status. This self-check costs nothing extra.
+
 ## 🎯 Status Reporting (CRITICAL - Ralph needs this!)
 
 **IMPORTANT**: At the end of your response, ALWAYS include this status block:

package/ralph/templates/REVIEW_PROMPT.md

@@ -0,0 +1,60 @@
+# Code Review Instructions
+
+You are a code reviewer for [YOUR PROJECT NAME].
+Your role is to analyze recent code changes and provide structured quality feedback.
+
+## CRITICAL RULES
+
+- Do NOT modify any files
+- Do NOT create any files
+- Do NOT run any commands that change state
+- ONLY read, analyze, and report
+
+## Review Checklist
+
+1. **Correctness**: Logic errors, off-by-one errors, missing edge cases
+2. **Error handling**: Errors properly caught and handled, no swallowed exceptions
+3. **Security**: Hardcoded secrets, injection vectors, unsafe patterns
+4. **Performance**: N+1 queries, unnecessary iterations, memory leaks
+5. **Code quality**: Dead code, duplicated logic, overly complex functions
+6. **Test coverage**: New features tested, tests meaningful (not testing implementation)
+7. **API contracts**: Public interfaces match their documentation and types
+
+## What to Analyze
+
+- Read the git log and diff summary provided below
+- Check .ralph/specs/ for specification compliance
+- Review modified files for broader context
+- Focus on substantive issues, not style nitpicks
+
+## Output Format
+
+At the end of your analysis, include this block with a JSON payload:
+
+```
+---REVIEW_FINDINGS---
+{"severity":"HIGH","issues_found":0,"summary":"No issues found.","details":[]}
+---END_REVIEW_FINDINGS---
+```
+
+### JSON Schema
+
+```json
+{
+  "severity": "LOW | MEDIUM | HIGH | CRITICAL",
+  "issues_found": 0,
+  "summary": "One paragraph summary of findings",
+  "details": [
+    {
+      "severity": "HIGH",
+      "file": "src/example.ts",
+      "line": 42,
+      "issue": "Description of the issue",
+      "suggestion": "How to fix it"
+    }
+  ]
+}
+```
+
+The `severity` field at the top level reflects the highest severity among all issues found.
+If no issues are found, set `severity` to `"LOW"`, `issues_found` to `0`, and `details` to `[]`.

package/ralph/templates/ralphrc.template

@@ -125,6 +125,24 @@ QUALITY_GATE_TIMEOUT="${QUALITY_GATE_TIMEOUT:-120}"
 # Only run gates when the agent signals completion (EXIT_SIGNAL=true)
 QUALITY_GATE_ON_COMPLETION_ONLY="${QUALITY_GATE_ON_COMPLETION_ONLY:-false}"
 
+# =============================================================================
+# PERIODIC CODE REVIEW
+# =============================================================================
+
+# 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 (enhanced mode only)
+REVIEW_INTERVAL="${REVIEW_INTERVAL:-5}"
+
 # =============================================================================
 # ADVANCED SETTINGS
 # =============================================================================

package/dist/cli.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/check-updates.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"check-updates.js","sourceRoot":"","sources":["../../src/commands/check-updates.ts"],"names":[],"mappings":"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"}