anvil-dev-framework 0.1.6

package/global/hooks/ralph_stop.sh

@@ -0,0 +1,502 @@
+#!/bin/bash
+# =============================================================================
+# ralph_stop.sh - Ralph Wiggum Stop Hook with Circuit Breaker (ANV-160)
+# =============================================================================
+#
+# Stop hook for Ralph Wiggum autonomous execution mode.
+# Blocks exit until completion promise is detected or safety limits reached.
+#
+# Usage: Called automatically by Claude Code on Stop events during Ralph mode
+#
+# Environment Variables:
+#   RALPH_MAX_ITERATIONS     - Max iterations (default: 50)
+#   RALPH_COMPLETION_PROMISE - Completion text to detect (default: COMPLETE)
+#   RALPH_STATE_FILE         - State file path (default: .claude/ralph-state.json)
+#   RALPH_ENABLE_LOGGING     - Set to "true" to enable logging
+#
+# Exit Codes:
+#   0 - Allow exit (complete, fatal error, or safety limit)
+#   1 - Block exit and restart (continue iteration)
+#
+# DEPENDENCY: jq (apt install jq / brew install jq)
+# WARNING: Windows/Git Bash users must install jq separately or use WSL
+#
+
+set -euo pipefail
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+MAX_ITERATIONS="${RALPH_MAX_ITERATIONS:-50}"
+COMPLETION_PROMISE="${RALPH_COMPLETION_PROMISE:-COMPLETE}"
+STATE_FILE="${RALPH_STATE_FILE:-.claude/ralph-state.json}"
+ENABLE_LOGGING="${RALPH_ENABLE_LOGGING:-false}"
+LOG_FILE=".claude/logs/ralph.log"
+PROGRESS_FILE="progress.txt"
+
+# Circuit breaker thresholds
+NO_CHANGE_THRESHOLD=3
+REPEATED_ERROR_THRESHOLD=5
+
+# =============================================================================
+# Logging
+# =============================================================================
+
+log_event() {
+    local level="$1"
+    local message="$2"
+
+    if [[ "$ENABLE_LOGGING" == "true" ]]; then
+        local timestamp
+        timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+        mkdir -p "$(dirname "$LOG_FILE")"
+        echo "[$timestamp] [$level] $message" >> "$LOG_FILE"
+    fi
+
+    # Also output to stderr for visibility
+    case "$level" in
+        ERROR) echo "❌ Ralph: $message" >&2 ;;
+        WARN)  echo "⚠️  Ralph: $message" >&2 ;;
+        INFO)  echo "🔄 Ralph: $message" >&2 ;;
+        OK)    echo "✅ Ralph: $message" >&2 ;;
+    esac
+}
+
+# =============================================================================
+# State Management
+# =============================================================================
+
+init_state() {
+    if [[ ! -f "$STATE_FILE" ]]; then
+        mkdir -p "$(dirname "$STATE_FILE")"
+        cat > "$STATE_FILE" << 'INIT_STATE'
+{
+  "iteration": 0,
+  "started_at": "",
+  "no_change_count": 0,
+  "last_diff_hash": "",
+  "error_hashes": [],
+  "status": "running"
+}
+INIT_STATE
+        # Set started_at timestamp
+        local timestamp
+        timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+        jq --arg ts "$timestamp" '.started_at = $ts' "$STATE_FILE" > tmp.$$ && mv tmp.$$ "$STATE_FILE"
+    fi
+}
+
+read_state() {
+    local key="$1"
+    local default="${2:-}"
+    jq -r ".$key // \"$default\"" "$STATE_FILE" 2>/dev/null || echo "$default"
+}
+
+update_state() {
+    local key="$1"
+    local value="$2"
+
+    if [[ "$value" =~ ^[0-9]+$ ]]; then
+        # Numeric value
+        jq --argjson v "$value" ".$key = \$v" "$STATE_FILE" > tmp.$$ && mv tmp.$$ "$STATE_FILE"
+    else
+        # String value
+        jq --arg v "$value" ".$key = \$v" "$STATE_FILE" > tmp.$$ && mv tmp.$$ "$STATE_FILE"
+    fi
+}
+
+cleanup_state() {
+    if [[ -f "$STATE_FILE" ]]; then
+        rm -f "$STATE_FILE"
+    fi
+}
+
+# =============================================================================
+# Circuit Breaker Detection
+# =============================================================================
+
+get_current_diff_hash() {
+    # Hash of current git diff to detect if changes were made
+    git diff --stat 2>/dev/null | md5sum 2>/dev/null | cut -d' ' -f1 || echo "no-git"
+}
+
+check_no_change_circuit() {
+    local current_hash
+    current_hash=$(get_current_diff_hash)
+    local last_hash
+    last_hash=$(read_state "last_diff_hash" "")
+
+    if [[ "$current_hash" == "$last_hash" && -n "$last_hash" ]]; then
+        local no_change_count
+        no_change_count=$(read_state "no_change_count" "0")
+        no_change_count=$((no_change_count + 1))
+        update_state "no_change_count" "$no_change_count"
+
+        if [[ $no_change_count -ge $NO_CHANGE_THRESHOLD ]]; then
+            log_event "ERROR" "Circuit breaker: $NO_CHANGE_THRESHOLD iterations with no file changes"
+            return 1
+        else
+            log_event "WARN" "No file changes detected (${no_change_count}/${NO_CHANGE_THRESHOLD})"
+        fi
+    else
+        update_state "no_change_count" "0"
+        update_state "last_diff_hash" "$current_hash"
+    fi
+
+    return 0
+}
+
+# =============================================================================
+# Linear Integration (ANV-213)
+# =============================================================================
+
+report_linear_progress() {
+    # Report Linear sync progress to progress.txt at iteration boundaries.
+    #
+    # NOTE: The actual Linear API sync happens in ralph_state.py when
+    # mark_subtask_complete() is called - it internally calls sync_to_linear().
+    # This function reads the sync status from state and reports it to progress.txt.
+
+    if [[ ! -f "$STATE_FILE" ]]; then
+        return 0
+    fi
+
+    # Check if Linear integration is enabled
+    local linear_enabled
+    linear_enabled=$(jq -r '.linear_integration.enabled // false' "$STATE_FILE" 2>/dev/null || echo "false")
+
+    if [[ "$linear_enabled" != "true" ]]; then
+        return 0  # Not a Linear session
+    fi
+
+    local no_sync
+    no_sync=$(jq -r '.linear_integration.no_sync // false' "$STATE_FILE" 2>/dev/null || echo "false")
+
+    if [[ "$no_sync" == "true" ]]; then
+        log_event "INFO" "Linear sync disabled for this session"
+        return 0
+    fi
+
+    # Get sync info from state (set by ralph_state.py sync_to_linear)
+    local last_sync
+    last_sync=$(jq -r '.linear_integration.last_sync // ""' "$STATE_FILE" 2>/dev/null || echo "")
+
+    if [[ -n "$last_sync" ]]; then
+        # Append sync info to progress.txt
+        if [[ -f "$PROGRESS_FILE" ]]; then
+            local completed
+            completed=$(jq -r '[.linear_integration.subtasks[] | select(.status == "completed")] | length' "$STATE_FILE" 2>/dev/null || echo "0")
+            local total
+            total=$(jq -r '.linear_integration.subtasks | length' "$STATE_FILE" 2>/dev/null || echo "0")
+
+            # Get the most recently completed subtask
+            local last_completed
+            last_completed=$(jq -r '[.linear_integration.subtasks[] | select(.status == "completed")] | sort_by(.completed_at) | last | .identifier // ""' "$STATE_FILE" 2>/dev/null || echo "")
+
+            if [[ -n "$last_completed" ]]; then
+                echo "" >> "$PROGRESS_FILE"
+                echo "[Linear] Synced $last_completed to Done ($completed/$total completed)" >> "$PROGRESS_FILE"
+                log_event "INFO" "Synced $last_completed to Done in Linear"
+            fi
+        fi
+    fi
+
+    return 0
+}
+
+# =============================================================================
+# Git Checkpointing
+# =============================================================================
+
+git_checkpoint() {
+    local iteration="$1"
+
+    # Only checkpoint if there are changes
+    if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
+        git add -A 2>/dev/null || true
+        git commit -m "ralph: checkpoint iteration $iteration" --no-verify 2>/dev/null || true
+        log_event "INFO" "Git checkpoint created for iteration $iteration"
+    fi
+}
+
+# =============================================================================
+# CCS Checkpoint Handling (ANV-200)
+# =============================================================================
+
+check_ccs_checkpoint() {
+    # Check if CCS context checkpoint was triggered
+    local checkpoint_active
+    checkpoint_active=$(jq -r '.context_checkpoint.active // false' "$STATE_FILE" 2>/dev/null)
+    if [[ "$checkpoint_active" == "true" ]]; then
+        return 0
+    fi
+    return 1
+}
+
+handle_ccs_checkpoint() {
+    log_event "INFO" "CCS checkpoint detected - preparing resume context"
+    local level percent handoff_file current_item
+    level=$(jq -r '.context_checkpoint.level // "L2"' "$STATE_FILE")
+    percent=$(jq -r '.context_checkpoint.percent_at_checkpoint // 0' "$STATE_FILE")
+    handoff_file=$(jq -r '.context_checkpoint.handoff_file // ""' "$STATE_FILE")
+    current_item=$(jq -r '.context_checkpoint.current_todo_item // ""' "$STATE_FILE")
+    regenerate_prompt_with_checkpoint "$handoff_file" "$current_item" "$level" "$percent"
+    jq '.context_checkpoint.active = false' "$STATE_FILE" > tmp.$$ && mv tmp.$$ "$STATE_FILE"
+    log_event "OK" "Resume context prepared (L${level} at ${percent}%)"
+}
+
+regenerate_prompt_with_checkpoint() {
+    local handoff_file="$1"
+    local current_item="$2"
+    local level="$3"
+    local percent="$4"
+    local prompt_file="PROMPT.md"
+
+    # Use the Python prompt generator (ANV-201) for enhanced resume templates
+    local script_dir
+    script_dir="$(dirname "$0")/../lib"
+
+    if [[ -f "$script_dir/ralph_prompt_generator.py" ]]; then
+        # Use Python generator with full state context
+        python3 "$script_dir/ralph_prompt_generator.py" \
+            --mode ralph \
+            --state "$STATE_FILE" \
+            --output "$prompt_file" 2>/dev/null
+
+        if [[ $? -eq 0 ]]; then
+            log_event "INFO" "Generated resume prompt via Python generator: $prompt_file"
+            return 0
+        fi
+        # Fall back to inline template if Python fails
+        log_event "WARN" "Python generator failed, using fallback template"
+    fi
+
+    # Fallback: Inline template (original ANV-200 implementation)
+    local timestamp
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    local todo_items
+    todo_items=$(jq -r '.todo_items // [] | .[]' "$STATE_FILE" 2>/dev/null | head -10)
+    local iteration
+    iteration=$(jq -r '.iteration // 0' "$STATE_FILE")
+    local task_name
+    task_name=$(jq -r '.task_name // "Unknown Task"' "$STATE_FILE")
+
+    cat > "$prompt_file" << RESUME_PROMPT
+# Ralph Autonomous Session Resume
+
+> **Context Checkpoint Recovery**
+> Generated at $timestamp
+> Previous session hit L${level} threshold (${percent}% context)
+
+---
+
+## Previous Session Summary
+
+**Task**: $task_name
+**Iteration**: $iteration
+**Checkpoint Level**: L${level}
+**Context at Checkpoint**: ${percent}%
+
+---
+
+## Handoff Document
+
+The previous session created a detailed handoff document with full context:
+
+\`\`\`
+$handoff_file
+\`\`\`
+
+**IMPORTANT**: Read this file first to understand the full context of where work left off.
+
+---
+
+## Current Task Context
+
+### Current Item (In Progress)
+
+**Task**: $current_item
+
+### Remaining Work
+
+\`\`\`
+$todo_items
+\`\`\`
+
+---
+
+## Resume Instructions
+
+**CRITICAL**: This is a continuation session. Follow these rules:
+
+1. **DO NOT restart from the beginning** - Work has already been done
+2. **Read the handoff document first** - Contains full context
+3. **Continue from the current item** - Pick up exactly where left off
+4. **Complete current task before moving on** - Don't skip items
+5. **Signal completion with \`<promise>COMPLETE</promise>\`** when done
+
+---
+
+*This prompt was auto-generated by ralph_stop.sh checkpoint handling (ANV-200/ANV-201)*
+RESUME_PROMPT
+    log_event "INFO" "Generated resume prompt (fallback): $prompt_file"
+}
+
+# =============================================================================
+# Transcript Analysis
+# =============================================================================
+
+check_completion_promise() {
+    # Check if the Claude transcript contains the completion promise
+    # CLAUDE_TRANSCRIPT is set by Claude Code with the session output
+
+    local transcript="${CLAUDE_TRANSCRIPT:-}"
+
+    if [[ -z "$transcript" ]]; then
+        # No transcript available, check if we can read from stdin or a file
+        return 1
+    fi
+
+    if echo "$transcript" | grep -q "<promise>$COMPLETION_PROMISE</promise>"; then
+        return 0
+    fi
+
+    return 1
+}
+
+check_fatal_error() {
+    local transcript="${CLAUDE_TRANSCRIPT:-}"
+
+    if [[ -z "$transcript" ]]; then
+        return 1
+    fi
+
+    if echo "$transcript" | grep -q "<fatal>"; then
+        return 0
+    fi
+
+    return 1
+}
+
+check_stuck_signals() {
+    local transcript="${CLAUDE_TRANSCRIPT:-}"
+
+    if [[ -z "$transcript" ]]; then
+        return 1
+    fi
+
+    # Check for stuck/blocked language
+    if echo "$transcript" | grep -qiE "(I'm stuck|cannot proceed|blocked by|unresolvable)"; then
+        return 0
+    fi
+
+    return 1
+}
+
+# =============================================================================
+# Main Logic
+# =============================================================================
+
+main() {
+    # Check if Ralph mode is active
+    if [[ ! -f "$STATE_FILE" ]]; then
+        # Not in Ralph mode, don't interfere
+        exit 0
+    fi
+
+    init_state
+
+    # Read and increment iteration
+    local iteration
+    iteration=$(read_state "iteration" "0")
+    iteration=$((iteration + 1))
+    update_state "iteration" "$iteration"
+
+    log_event "INFO" "Iteration $iteration starting"
+
+    # ==========================================================================
+    # CCS Check: Context checkpoint triggered (ANV-200)
+    # ==========================================================================
+    if check_ccs_checkpoint; then
+        handle_ccs_checkpoint
+        git_checkpoint "$iteration"
+        exit 1  # Restart loop with checkpoint context
+    fi
+
+    # ==========================================================================
+    # Safety Check 1: Max iterations
+    # ==========================================================================
+    if [[ $iteration -ge $MAX_ITERATIONS ]]; then
+        log_event "WARN" "Maximum iterations ($MAX_ITERATIONS) reached"
+        update_state "status" "max_iterations"
+        cleanup_state
+        exit 0  # Allow exit
+    fi
+
+    # ==========================================================================
+    # Check 2: Completion promise detected
+    # ==========================================================================
+    if check_completion_promise; then
+        log_event "OK" "Task complete after $iteration iterations! Promise detected."
+        update_state "status" "completed"
+        cleanup_state
+        exit 0  # Allow exit
+    fi
+
+    # ==========================================================================
+    # Check 3: Fatal error detected
+    # ==========================================================================
+    if check_fatal_error; then
+        log_event "ERROR" "Fatal error detected - stopping loop"
+        update_state "status" "fatal_error"
+        cleanup_state
+        exit 0  # Allow exit
+    fi
+
+    # ==========================================================================
+    # Check 4: Stuck signals detected
+    # ==========================================================================
+    if check_stuck_signals; then
+        log_event "WARN" "Stuck signals detected - may need manual intervention"
+        # Don't exit yet, but log warning
+    fi
+
+    # ==========================================================================
+    # Check 5: Circuit breaker - no changes
+    # ==========================================================================
+    if ! check_no_change_circuit; then
+        update_state "status" "circuit_breaker"
+        cleanup_state
+        exit 0  # Allow exit
+    fi
+
+    # ==========================================================================
+    # Report Linear progress at iteration boundary (ANV-213)
+    # ==========================================================================
+    report_linear_progress
+
+    # ==========================================================================
+    # Git checkpoint before restart
+    # ==========================================================================
+    git_checkpoint "$iteration"
+
+    # ==========================================================================
+    # Continue loop
+    # ==========================================================================
+    log_event "INFO" "Iteration $iteration incomplete - restarting..."
+    exit 1  # Block exit, trigger restart
+}
+
+# =============================================================================
+# Entry Point
+# =============================================================================
+
+# Check for jq dependency
+if ! command -v jq &> /dev/null; then
+    echo "❌ Ralph requires jq for JSON processing" >&2
+    echo "   Install: apt install jq (Linux) or brew install jq (macOS)" >&2
+    exit 0  # Allow exit rather than blocking
+fi
+
+main "$@"