@the-bearded-bear/claude-craft 3.0.2 → 3.1.0

package/Tools/Ralph/lib/circuit-breaker.sh

@@ -0,0 +1,172 @@
+#!/bin/bash
+# =============================================================================
+# Ralph Wiggum - Circuit Breaker Module
+# Safety mechanism to prevent infinite loops and detect stalls
+# =============================================================================
+
+# Circuit breaker thresholds (defaults)
+CB_NO_CHANGES_THRESHOLD="${CB_NO_CHANGES_THRESHOLD:-3}"
+CB_REPEATED_ERROR_THRESHOLD="${CB_REPEATED_ERROR_THRESHOLD:-5}"
+CB_OUTPUT_DECLINE_THRESHOLD="${CB_OUTPUT_DECLINE_THRESHOLD:-70}"
+
+# Circuit breaker state
+CB_ITERATIONS_WITHOUT_CHANGES=0
+CB_CONSECUTIVE_ERRORS=0
+CB_PEAK_OUTPUT_LENGTH=0
+CB_LAST_OUTPUT_LENGTH=0
+CB_TRIGGERED=false
+CB_TRIGGER_REASON=""
+
+# =============================================================================
+# Initialization
+# =============================================================================
+
+init_circuit_breaker() {
+    CB_ITERATIONS_WITHOUT_CHANGES=0
+    CB_CONSECUTIVE_ERRORS=0
+    CB_PEAK_OUTPUT_LENGTH=0
+    CB_LAST_OUTPUT_LENGTH=0
+    CB_TRIGGERED=false
+    CB_TRIGGER_REASON=""
+
+    # Load thresholds from config if available
+    if [[ -n "$CONFIG_FILE" && -f "$CONFIG_FILE" ]] && command -v yq &> /dev/null; then
+        local no_changes=$(yq e '.circuit_breaker.no_file_changes_threshold // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ -n "$no_changes" ]] && CB_NO_CHANGES_THRESHOLD=$no_changes
+
+        local errors=$(yq e '.circuit_breaker.repeated_error_threshold // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ -n "$errors" ]] && CB_REPEATED_ERROR_THRESHOLD=$errors
+
+        local decline=$(yq e '.circuit_breaker.output_decline_threshold // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ -n "$decline" ]] && CB_OUTPUT_DECLINE_THRESHOLD=$decline
+    fi
+
+    print_verbose "Circuit breaker initialized:"
+    print_verbose "  - No changes threshold: $CB_NO_CHANGES_THRESHOLD"
+    print_verbose "  - Error threshold: $CB_REPEATED_ERROR_THRESHOLD"
+    print_verbose "  - Output decline threshold: ${CB_OUTPUT_DECLINE_THRESHOLD}%"
+}
+
+# =============================================================================
+# Circuit Breaker Check
+# =============================================================================
+
+check_circuit_breaker() {
+    # Return 0 (true) if triggered, 1 (false) if OK to continue
+
+    # Check no progress (no file changes)
+    if [[ $CB_ITERATIONS_WITHOUT_CHANGES -ge $CB_NO_CHANGES_THRESHOLD ]]; then
+        CB_TRIGGERED=true
+        CB_TRIGGER_REASON="no_progress"
+        print_warning "${MSG_CB_TRIGGERED}: ${MSG_CB_NO_CHANGES} $CB_ITERATIONS_WITHOUT_CHANGES ${MSG_CB_ITERATIONS}"
+        return 0
+    fi
+
+    # Check repeated errors
+    if [[ $CB_CONSECUTIVE_ERRORS -ge $CB_REPEATED_ERROR_THRESHOLD ]]; then
+        CB_TRIGGERED=true
+        CB_TRIGGER_REASON="repeated_errors"
+        print_warning "${MSG_CB_TRIGGERED}: ${MSG_CB_REPEATED_ERRORS}"
+        return 0
+    fi
+
+    # Check output decline
+    if [[ $CB_PEAK_OUTPUT_LENGTH -gt 0 && $CB_LAST_OUTPUT_LENGTH -gt 0 ]]; then
+        local decline_percent=$(( (CB_PEAK_OUTPUT_LENGTH - CB_LAST_OUTPUT_LENGTH) * 100 / CB_PEAK_OUTPUT_LENGTH ))
+        if [[ $decline_percent -ge $CB_OUTPUT_DECLINE_THRESHOLD ]]; then
+            CB_TRIGGERED=true
+            CB_TRIGGER_REASON="output_decline"
+            print_warning "${MSG_CB_TRIGGERED}: ${MSG_CB_OUTPUT_DECLINE} ${decline_percent}${MSG_CB_PERCENT}"
+            return 0
+        fi
+    fi
+
+    return 1
+}
+
+# =============================================================================
+# Update Circuit Breaker State
+# =============================================================================
+
+update_circuit_breaker() {
+    local event_type="$1"
+    local output="$2"
+
+    case "$event_type" in
+        progress)
+            # Reset counters on progress
+            CB_ITERATIONS_WITHOUT_CHANGES=0
+            CB_CONSECUTIVE_ERRORS=0
+
+            # Update output tracking
+            local output_length=${#output}
+            CB_LAST_OUTPUT_LENGTH=$output_length
+            if [[ $output_length -gt $CB_PEAK_OUTPUT_LENGTH ]]; then
+                CB_PEAK_OUTPUT_LENGTH=$output_length
+            fi
+            ;;
+
+        no_progress)
+            CB_ITERATIONS_WITHOUT_CHANGES=$((CB_ITERATIONS_WITHOUT_CHANGES + 1))
+            print_verbose "No progress: $CB_ITERATIONS_WITHOUT_CHANGES / $CB_NO_CHANGES_THRESHOLD"
+            ;;
+
+        error)
+            CB_CONSECUTIVE_ERRORS=$((CB_CONSECUTIVE_ERRORS + 1))
+            print_verbose "Error count: $CB_CONSECUTIVE_ERRORS / $CB_REPEATED_ERROR_THRESHOLD"
+            ;;
+
+        reset)
+            CB_ITERATIONS_WITHOUT_CHANGES=0
+            CB_CONSECUTIVE_ERRORS=0
+            CB_TRIGGERED=false
+            CB_TRIGGER_REASON=""
+            print_verbose "${MSG_CB_RESET}"
+            ;;
+    esac
+
+    # Update session state if available
+    if [[ -n "$SESSION_ID" ]]; then
+        update_session_state "$SESSION_ID" "circuit_breaker" "{
+            \"iterations_without_changes\": $CB_ITERATIONS_WITHOUT_CHANGES,
+            \"consecutive_errors\": $CB_CONSECUTIVE_ERRORS,
+            \"peak_output_length\": $CB_PEAK_OUTPUT_LENGTH,
+            \"last_output_length\": $CB_LAST_OUTPUT_LENGTH,
+            \"triggered\": $CB_TRIGGERED,
+            \"trigger_reason\": \"$CB_TRIGGER_REASON\"
+        }"
+    fi
+}
+
+# =============================================================================
+# Circuit Breaker Status
+# =============================================================================
+
+get_circuit_breaker_status() {
+    cat <<EOF
+{
+    "iterations_without_changes": $CB_ITERATIONS_WITHOUT_CHANGES,
+    "consecutive_errors": $CB_CONSECUTIVE_ERRORS,
+    "peak_output_length": $CB_PEAK_OUTPUT_LENGTH,
+    "last_output_length": $CB_LAST_OUTPUT_LENGTH,
+    "triggered": $CB_TRIGGERED,
+    "trigger_reason": "$CB_TRIGGER_REASON",
+    "thresholds": {
+        "no_changes": $CB_NO_CHANGES_THRESHOLD,
+        "errors": $CB_REPEATED_ERROR_THRESHOLD,
+        "output_decline": $CB_OUTPUT_DECLINE_THRESHOLD
+    }
+}
+EOF
+}
+
+# =============================================================================
+# Force Trip
+# =============================================================================
+
+trip_circuit_breaker() {
+    local reason="$1"
+    CB_TRIGGERED=true
+    CB_TRIGGER_REASON="${reason:-manual}"
+    print_warning "${MSG_CB_TRIGGERED}: $CB_TRIGGER_REASON"
+}

package/Tools/Ralph/lib/dod-validator.sh

@@ -0,0 +1,306 @@
+#!/bin/bash
+# =============================================================================
+# Ralph Wiggum - Definition of Done Validator Module
+# Validates completion criteria using configurable checklist
+# =============================================================================
+
+# Default completion marker
+DOD_COMPLETION_MARKER="${DOD_COMPLETION_MARKER:-<promise>COMPLETE</promise>}"
+
+# DoD validator types
+declare -A DOD_VALIDATORS=(
+    ["command"]="validate_command"
+    ["output_contains"]="validate_output_contains"
+    ["file_changed"]="validate_file_changed"
+    ["hook"]="validate_hook"
+    ["human"]="validate_human"
+)
+
+# =============================================================================
+# Main DoD Validation
+# =============================================================================
+
+validate_dod() {
+    local output="$1"
+    local config_file="$2"
+
+    # If no config, use simple completion marker check
+    if [[ -z "$config_file" || ! -f "$config_file" ]]; then
+        return $(validate_simple_completion "$output")
+    fi
+
+    # Check if yq is available for YAML parsing
+    if ! command -v yq &> /dev/null; then
+        return $(validate_simple_completion "$output")
+    fi
+
+    # Get DoD checklist from config
+    local checklist=$(yq e '.definition_of_done.checklist // []' "$config_file" 2>/dev/null)
+
+    # If no checklist, use simple completion marker
+    if [[ "$checklist" == "[]" || -z "$checklist" ]]; then
+        local marker=$(yq e '.definition_of_done.completion_marker // ""' "$config_file" 2>/dev/null)
+        if [[ -n "$marker" ]]; then
+            DOD_COMPLETION_MARKER="$marker"
+        fi
+        return $(validate_simple_completion "$output")
+    fi
+
+    # Process checklist items
+    local all_required_passed=true
+    local results=()
+
+    # Get count of checklist items
+    local count=$(echo "$checklist" | yq e 'length' -)
+
+    for ((i=0; i<count; i++)); do
+        local item=$(yq e ".definition_of_done.checklist[$i]" "$config_file")
+        local id=$(echo "$item" | yq e '.id' -)
+        local name=$(echo "$item" | yq e '.name' -)
+        local type=$(echo "$item" | yq e '.type' -)
+        local required=$(echo "$item" | yq e '.required // true' -)
+
+        # Validate based on type
+        local passed=false
+        local message=""
+
+        case "$type" in
+            command)
+                local cmd=$(echo "$item" | yq e '.command' -)
+                if validate_command "$cmd"; then
+                    passed=true
+                    message="Command passed"
+                else
+                    message="Command failed"
+                fi
+                ;;
+            output_contains)
+                local pattern=$(echo "$item" | yq e '.pattern' -)
+                if validate_output_contains "$output" "$pattern"; then
+                    passed=true
+                    message="Pattern found"
+                else
+                    message="Pattern not found"
+                fi
+                ;;
+            file_changed)
+                local pattern=$(echo "$item" | yq e '.pattern' -)
+                if validate_file_changed "$pattern"; then
+                    passed=true
+                    message="Files changed"
+                else
+                    message="No files changed"
+                fi
+                ;;
+            hook)
+                local script=$(echo "$item" | yq e '.script' -)
+                if validate_hook "$script" "$output"; then
+                    passed=true
+                    message="Hook passed"
+                else
+                    message="Hook failed"
+                fi
+                ;;
+            human)
+                local prompt=$(echo "$item" | yq e '.prompt // ""' -)
+                if validate_human "$name" "$prompt"; then
+                    passed=true
+                    message="Human approved"
+                else
+                    message="Human rejected"
+                fi
+                ;;
+            *)
+                message="Unknown validator type: $type"
+                ;;
+        esac
+
+        # Print result
+        if [[ "$passed" == "true" ]]; then
+            echo -e "  ${C_GREEN}✓${C_RESET} [$id] $name - ${C_GREEN}${MSG_DOD_ITEM_PASSED}${C_RESET}"
+        else
+            if [[ "$required" == "true" ]]; then
+                echo -e "  ${C_RED}✗${C_RESET} [$id] $name - ${C_RED}${MSG_DOD_ITEM_FAILED}${C_RESET} (${MSG_DOD_REQUIRED})"
+                all_required_passed=false
+            else
+                echo -e "  ${C_YELLOW}○${C_RESET} [$id] $name - ${C_YELLOW}${MSG_DOD_ITEM_SKIPPED}${C_RESET} (${MSG_DOD_OPTIONAL})"
+            fi
+        fi
+
+        # Store result
+        results+=("{\"id\":\"$id\",\"passed\":$passed,\"required\":$required,\"message\":\"$message\"}")
+    done
+
+    # Return overall result
+    if [[ "$all_required_passed" == "true" ]]; then
+        echo -e "\n  ${C_GREEN}${MSG_DOD_ALL_REQUIRED_PASSED}${C_RESET}"
+        return 0
+    else
+        echo -e "\n  ${C_RED}${MSG_DOD_MISSING_REQUIRED}${C_RESET}"
+        return 1
+    fi
+}
+
+# =============================================================================
+# Simple Completion Check
+# =============================================================================
+
+validate_simple_completion() {
+    local output="$1"
+
+    if echo "$output" | grep -qF "$DOD_COMPLETION_MARKER"; then
+        echo -e "  ${C_GREEN}✓${C_RESET} Completion marker found"
+        return 0
+    else
+        echo -e "  ${C_YELLOW}○${C_RESET} Completion marker not found"
+        return 1
+    fi
+}
+
+# =============================================================================
+# Validator: Command
+# =============================================================================
+
+validate_command() {
+    local cmd="$1"
+
+    echo -e "  ${C_DIM}${MSG_VALIDATOR_COMMAND}: $cmd${C_RESET}"
+
+    # Execute the command
+    if eval "$cmd" > /dev/null 2>&1; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+# =============================================================================
+# Validator: Output Contains Pattern
+# =============================================================================
+
+validate_output_contains() {
+    local output="$1"
+    local pattern="$2"
+
+    echo -e "  ${C_DIM}${MSG_VALIDATOR_OUTPUT}: $pattern${C_RESET}"
+
+    if echo "$output" | grep -qE "$pattern"; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+# =============================================================================
+# Validator: File Changed
+# =============================================================================
+
+validate_file_changed() {
+    local pattern="$1"
+
+    echo -e "  ${C_DIM}${MSG_VALIDATOR_FILE}: $pattern${C_RESET}"
+
+    # Use git to check for changes matching pattern
+    if command -v git &> /dev/null && git rev-parse --git-dir &> /dev/null; then
+        local changes=$(git status --porcelain 2>/dev/null | grep -E "$pattern" | wc -l)
+        if [[ $changes -gt 0 ]]; then
+            return 0
+        fi
+    else
+        # Fallback: check for recently modified files
+        local changes=$(find . -name "$pattern" -mmin -5 2>/dev/null | wc -l)
+        if [[ $changes -gt 0 ]]; then
+            return 0
+        fi
+    fi
+
+    return 1
+}
+
+# =============================================================================
+# Validator: Hook
+# =============================================================================
+
+validate_hook() {
+    local script="$1"
+    local output="$2"
+
+    echo -e "  ${C_DIM}${MSG_VALIDATOR_HOOK}: $script${C_RESET}"
+
+    # Check if script exists
+    if [[ ! -f "$script" ]]; then
+        echo -e "  ${C_RED}Hook script not found: $script${C_RESET}"
+        return 1
+    fi
+
+    # Prepare input JSON (same format as Claude hooks)
+    local input_json=$(jq -n \
+        --arg cwd "$PWD" \
+        --arg output "$output" \
+        '{cwd: $cwd, output: $output}')
+
+    # Execute hook with JSON input
+    local result
+    result=$(echo "$input_json" | bash "$script" 2>&1)
+    local exit_code=$?
+
+    # Check exit code (0 = continue/pass, 2 = block/fail)
+    if [[ $exit_code -eq 0 ]]; then
+        return 0
+    elif [[ $exit_code -eq 2 ]]; then
+        return 1
+    else
+        # Other exit codes treated as errors
+        echo -e "  ${C_YELLOW}Hook exited with code $exit_code${C_RESET}"
+        return 1
+    fi
+}
+
+# =============================================================================
+# Validator: Human
+# =============================================================================
+
+validate_human() {
+    local name="$1"
+    local prompt="$2"
+
+    echo -e "\n  ${C_MAGENTA}${MSG_DOD_HUMAN_GATE}: $name${C_RESET}"
+
+    # Default prompt if not provided
+    if [[ -z "$prompt" ]]; then
+        prompt="${MSG_DOD_HUMAN_PROMPT}"
+    fi
+
+    # Ask for human input
+    echo -ne "  ${C_BOLD}$prompt ${C_RESET}"
+    read -r response
+
+    # Check response
+    case "${response,,}" in
+        y|yes|o|oui|s|si|j|ja|sim)
+            return 0
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+}
+
+# =============================================================================
+# DoD Result Storage
+# =============================================================================
+
+store_dod_results() {
+    local session_id="$1"
+    local results="$2"
+
+    local session_dir="$RALPH_SESSION_BASE/sessions/$session_id"
+    local state_file="$session_dir/state.json"
+
+    if [[ -f "$state_file" ]]; then
+        local tmp_file=$(mktemp)
+        echo "$results" | jq -s '.' > "$session_dir/dod_results.json"
+        jq --slurpfile results "$session_dir/dod_results.json" '.dod_results = $results[0]' "$state_file" > "$tmp_file"
+        mv "$tmp_file" "$state_file"
+    fi
+}

package/Tools/Ralph/lib/loop.sh

@@ -0,0 +1,232 @@
+#!/bin/bash
+# =============================================================================
+# Ralph Wiggum - Main Loop Module
+# Core iteration loop logic and Claude invocation
+# =============================================================================
+
+# Claude command configuration
+CLAUDE_COMMAND="${CLAUDE_COMMAND:-claude}"
+CLAUDE_ARGS="${CLAUDE_ARGS:---dangerously-skip-permissions}"
+
+# =============================================================================
+# Claude Invocation
+# =============================================================================
+
+invoke_claude() {
+    local session_id="$1"
+    local prompt="$2"
+    local timeout="$3"
+
+    # Build the command
+    local cmd="$CLAUDE_COMMAND"
+
+    # Add continue flag if we have a session
+    if [[ -n "$session_id" ]]; then
+        cmd="$cmd --continue"
+    fi
+
+    # Add prompt
+    cmd="$cmd -p"
+
+    # Log the invocation
+    log_session "$session_id" "INFO" "Invoking Claude: $cmd \"${prompt:0:100}...\""
+
+    # Execute with timeout
+    local timeout_sec=$((timeout / 1000))
+    local output
+    local exit_code
+
+    # Use timeout command if available
+    if command -v timeout &> /dev/null; then
+        output=$(timeout "${timeout_sec}s" $cmd "$prompt" 2>&1)
+        exit_code=$?
+
+        # Check for timeout (exit code 124)
+        if [[ $exit_code -eq 124 ]]; then
+            log_session "$session_id" "ERROR" "Claude invocation timed out after ${timeout_sec}s"
+            return 124
+        fi
+    else
+        # Fallback without timeout
+        output=$($cmd "$prompt" 2>&1)
+        exit_code=$?
+    fi
+
+    # Log result
+    if [[ $exit_code -eq 0 ]]; then
+        log_session "$session_id" "INFO" "Claude responded (${#output} chars)"
+    else
+        log_session "$session_id" "ERROR" "Claude failed with exit code $exit_code"
+    fi
+
+    # Output the response
+    echo "$output"
+    return $exit_code
+}
+
+# =============================================================================
+# Output Processing
+# =============================================================================
+
+process_output() {
+    local output="$1"
+    local session_id="$2"
+
+    # Store the raw output
+    local session_dir="$RALPH_SESSION_BASE/sessions/$session_id"
+    local output_file="$session_dir/last_output.txt"
+
+    echo "$output" > "$output_file"
+
+    # Extract any structured data if present
+    # Look for JSON blocks, completion markers, etc.
+
+    # Check for completion marker
+    if echo "$output" | grep -q "$DEFAULT_COMPLETION_MARKER"; then
+        log_session "$session_id" "INFO" "Completion marker found in output"
+        return 0
+    fi
+
+    return 1
+}
+
+# =============================================================================
+# File Change Detection
+# =============================================================================
+
+detect_file_changes() {
+    local session_id="$1"
+
+    # Use git to detect changes if available
+    if command -v git &> /dev/null && git rev-parse --git-dir &> /dev/null; then
+        local changes=$(git status --porcelain 2>/dev/null | wc -l)
+        log_session "$session_id" "DEBUG" "Detected $changes file changes"
+        echo "$changes"
+    else
+        # Fallback: check modification times in common source directories
+        local changes=0
+        for dir in src lib app tests; do
+            if [[ -d "$dir" ]]; then
+                local recent=$(find "$dir" -type f -mmin -1 2>/dev/null | wc -l)
+                changes=$((changes + recent))
+            fi
+        done
+        echo "$changes"
+    fi
+}
+
+# =============================================================================
+# Progress Detection
+# =============================================================================
+
+check_progress() {
+    local session_id="$1"
+    local output="$2"
+    local previous_length="$3"
+
+    local current_length=${#output}
+    local file_changes=$(detect_file_changes "$session_id")
+
+    # Progress indicators
+    local has_progress=false
+
+    # 1. Files were changed
+    if [[ $file_changes -gt 0 ]]; then
+        has_progress=true
+        log_session "$session_id" "INFO" "Progress: $file_changes files changed"
+    fi
+
+    # 2. Output length is significant (not just errors)
+    if [[ $current_length -gt 100 ]]; then
+        # Check if output contains actual work indicators
+        if echo "$output" | grep -qE "(created|modified|fixed|implemented|added|updated)" ; then
+            has_progress=true
+            log_session "$session_id" "INFO" "Progress: Work indicators found in output"
+        fi
+    fi
+
+    # Update metrics
+    update_session_state "$session_id" "metrics.file_changes" "$file_changes"
+
+    if [[ "$has_progress" == "true" ]]; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+# =============================================================================
+# Error Detection
+# =============================================================================
+
+detect_errors() {
+    local output="$1"
+    local errors=()
+
+    # Common error patterns
+    local error_patterns=(
+        "Error:"
+        "error:"
+        "FAILED"
+        "Exception"
+        "fatal:"
+        "Cannot"
+        "could not"
+        "Permission denied"
+        "No such file"
+        "command not found"
+    )
+
+    for pattern in "${error_patterns[@]}"; do
+        if echo "$output" | grep -q "$pattern"; then
+            errors+=("$pattern")
+        fi
+    done
+
+    if [[ ${#errors[@]} -gt 0 ]]; then
+        printf '%s\n' "${errors[@]}"
+        return 1
+    fi
+
+    return 0
+}
+
+# =============================================================================
+# Loop State
+# =============================================================================
+
+get_loop_state() {
+    local session_id="$1"
+    local state=$(get_session_state "$session_id")
+
+    echo "$state" | jq '{
+        iteration: .current_iteration,
+        status: .status,
+        circuit_breaker: .circuit_breaker,
+        dod_results: .dod_results
+    }'
+}
+
+should_continue_loop() {
+    local session_id="$1"
+    local iteration="$2"
+    local max_iterations="$3"
+
+    # Check max iterations
+    if [[ $iteration -ge $max_iterations ]]; then
+        return 1
+    fi
+
+    # Check circuit breaker
+    if check_circuit_breaker; then
+        return 1
+    fi
+
+    # Check session status
+    local status=$(get_session_state "$session_id" | jq -r '.status')
+    if [[ "$status" == "completed" || "$status" == "failed" ]]; then
+        return 1
+    fi
+
+    return 0
+}