codeharness 0.6.1

package/ralph/exec_plans.sh

@@ -0,0 +1,252 @@
+#!/usr/bin/env bash
+# exec_plans.sh — Exec-Plan Lifecycle Management
+# Generates per-story exec-plan files and moves them from active→completed.
+#
+# Usage:
+#   ralph/exec_plans.sh generate --progress PATH --output-dir DIR
+#   ralph/exec_plans.sh complete --story-id ID --output-dir DIR --proof-path PATH
+
+set -e
+
+# Portable in-place sed (macOS uses -i '', Linux uses -i)
+sed_i() {
+    if sed --version 2>/dev/null | grep -q GNU; then
+        sed -i "$@"
+    else
+        sed -i '' "$@"
+    fi
+}
+
+# ─── CLI ──────────────────────────────────────────────────────────────────
+
+ACTION=""
+PROGRESS_FILE=""
+OUTPUT_DIR=""
+STORY_ID=""
+PROOF_PATH=""
+
+show_help() {
+    cat << 'HELPEOF'
+Exec-Plan Lifecycle — track stories from active to completed
+
+Usage:
+    ralph/exec_plans.sh generate --progress PATH --output-dir DIR
+    ralph/exec_plans.sh complete --story-id ID --output-dir DIR --proof-path PATH
+
+Commands:
+    generate    Create exec-plan files from progress.json
+                Pending/in_progress → active/, complete → completed/
+    complete    Move an exec-plan from active/ to completed/
+                Appends verification summary and Showboat proof link
+
+Options:
+    --progress PATH     Path to ralph/progress.json
+    --output-dir DIR    Base directory for exec-plans (contains active/ and completed/)
+    --story-id ID       Story ID to complete (e.g., "1.1")
+    --proof-path PATH   Relative path to Showboat proof document
+    -h, --help          Show this help message
+HELPEOF
+}
+
+# Parse action first
+if [[ $# -gt 0 && "$1" != -* ]]; then
+    ACTION="$1"
+    shift
+fi
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            show_help
+            exit 0
+            ;;
+        --progress)
+            PROGRESS_FILE="$2"
+            shift 2
+            ;;
+        --output-dir)
+            OUTPUT_DIR="$2"
+            shift 2
+            ;;
+        --story-id)
+            STORY_ID="$2"
+            shift 2
+            ;;
+        --proof-path)
+            PROOF_PATH="$2"
+            shift 2
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# ─── Generate exec-plan for a single task ─────────────────────────────────
+
+generate_exec_plan_from_index() {
+    local progress_file="$1"
+    local index="$2"
+    local target_dir="$3"
+
+    local id title epic description status proof_path
+    id=$(jq -r ".tasks[$index].id" "$progress_file")
+    title=$(jq -r ".tasks[$index].title" "$progress_file")
+    epic=$(jq -r ".tasks[$index].epic // \"Unknown\"" "$progress_file")
+    description=$(jq -r ".tasks[$index].description // \"\"" "$progress_file")
+    status=$(jq -r ".tasks[$index].status // \"pending\"" "$progress_file")
+    proof_path=$(jq -r ".tasks[$index].verification.proof_path // \"\"" "$progress_file")
+
+    local file="$target_dir/$id.md"
+
+    # Don't overwrite existing exec-plans (idempotency)
+    if [[ -f "$file" ]]; then
+        return 0
+    fi
+
+    # Build acceptance criteria list
+    local ac_list=""
+    local ac_count
+    ac_count=$(jq ".tasks[$index].acceptance_criteria | length" "$progress_file")
+    local j
+    for ((j=0; j<ac_count; j++)); do
+        local ac
+        ac=$(jq -r ".tasks[$index].acceptance_criteria[$j]" "$progress_file")
+        ac_list="${ac_list}- ${ac}
+"
+    done
+
+    {
+        echo "# Story $id: $title"
+        echo ""
+        echo "**Epic:** $epic"
+        echo "**Status:** $status"
+        echo ""
+        echo "## Description"
+        echo ""
+        echo "$description"
+        echo ""
+        echo "## Acceptance Criteria"
+        echo ""
+        if [[ -n "$ac_list" ]]; then
+            echo "$ac_list"
+        else
+            echo "_No acceptance criteria defined._"
+            echo ""
+        fi
+        echo "## Progress Log"
+        echo ""
+        echo "_No entries yet._"
+        echo ""
+        echo "## Verification Status"
+        echo ""
+        echo "- **Proof document:** ${proof_path:-N/A}"
+        echo "- **Verified:** No"
+        echo "- **Iterations:** 0"
+    } > "$file"
+}
+
+# ─── Generate command ─────────────────────────────────────────────────────
+
+do_generate() {
+    if [[ -z "$PROGRESS_FILE" ]]; then
+        echo "Error: --progress is required" >&2
+        exit 1
+    fi
+    if [[ ! -f "$PROGRESS_FILE" ]]; then
+        echo "Error: progress file not found: $PROGRESS_FILE" >&2
+        exit 1
+    fi
+    if [[ -z "$OUTPUT_DIR" ]]; then
+        echo "Error: --output-dir is required" >&2
+        exit 1
+    fi
+
+    mkdir -p "$OUTPUT_DIR/active" "$OUTPUT_DIR/completed"
+
+    local task_count
+    task_count=$(jq '.tasks | length' "$PROGRESS_FILE")
+
+    for ((i=0; i<task_count; i++)); do
+        local status
+        status=$(jq -r ".tasks[$i].status" "$PROGRESS_FILE")
+
+        if [[ "$status" == "complete" ]]; then
+            generate_exec_plan_from_index "$PROGRESS_FILE" "$i" "$OUTPUT_DIR/completed"
+        else
+            generate_exec_plan_from_index "$PROGRESS_FILE" "$i" "$OUTPUT_DIR/active"
+        fi
+    done
+
+    local active_count completed_count
+    active_count=$(find "$OUTPUT_DIR/active" -maxdepth 1 -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    completed_count=$(find "$OUTPUT_DIR/completed" -maxdepth 1 -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    echo "[OK] Exec-plans: $active_count active, $completed_count completed"
+}
+
+# ─── Complete command ─────────────────────────────────────────────────────
+
+do_complete() {
+    if [[ -z "$STORY_ID" ]]; then
+        echo "Error: --story-id is required" >&2
+        exit 1
+    fi
+    if [[ -z "$OUTPUT_DIR" ]]; then
+        echo "Error: --output-dir is required" >&2
+        exit 1
+    fi
+
+    local active_file="$OUTPUT_DIR/active/$STORY_ID.md"
+    local completed_file="$OUTPUT_DIR/completed/$STORY_ID.md"
+
+    if [[ ! -f "$active_file" ]]; then
+        echo "Error: exec-plan not found: $active_file" >&2
+        exit 1
+    fi
+
+    mkdir -p "$OUTPUT_DIR/completed"
+
+    # Append verification summary
+    local timestamp
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    cat >> "$active_file" << COMPLETION
+
+---
+
+## Verified
+
+- **Completed at:** $timestamp
+- **Showboat proof:** [${PROOF_PATH}](${PROOF_PATH})
+- **Result:** All verification gates passed
+COMPLETION
+
+    # Update status in the file
+    sed_i "s/\*\*Status:\*\* .*/\*\*Status:\*\* complete/" "$active_file"
+    sed_i "s/\*\*Verified:\*\* No/\*\*Verified:\*\* Yes/" "$active_file"
+
+    # Move to completed
+    mv "$active_file" "$completed_file"
+    echo "[OK] Exec-plan $STORY_ID moved to completed/"
+}
+
+# ─── Main ─────────────────────────────────────────────────────────────────
+
+case "$ACTION" in
+    generate)
+        do_generate
+        ;;
+    complete)
+        do_complete
+        ;;
+    "")
+        echo "Error: specify a command: generate or complete" >&2
+        show_help
+        exit 1
+        ;;
+    *)
+        echo "Unknown command: $ACTION" >&2
+        exit 1
+        ;;
+esac

package/ralph/harness_status.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# harness_status.sh — Show harness health, sprint progress, and verification state
+# Follows the `git status` model: health → enforcement → progress → next action
+#
+# Usage: ralph/harness_status.sh --project-dir DIR
+
+set -e
+
+PROJECT_DIR=""
+
+show_help() {
+    cat << 'HELPEOF'
+Harness Status — show health, progress, and verification at a glance
+
+Usage:
+    ralph/harness_status.sh --project-dir DIR
+
+Output sections:
+    1. Health line (version, stack, Docker, Victoria)
+    2. Enforcement config (frontend, database, api, observability)
+    3. Sprint progress (per-story pass/pending/in-progress)
+    4. Next action hint
+
+Options:
+    --project-dir DIR   Project root directory
+    -h, --help          Show this help message
+HELPEOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            show_help
+            exit 0
+            ;;
+        --project-dir)
+            PROJECT_DIR="$2"
+            shift 2
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+if [[ -z "$PROJECT_DIR" ]]; then
+    echo "Error: --project-dir is required" >&2
+    exit 1
+fi
+
+STATE_FILE="$PROJECT_DIR/.claude/codeharness.local.md"
+PROGRESS_FILE="$PROJECT_DIR/ralph/progress.json"
+LOOP_STATUS_FILE="$PROJECT_DIR/ralph/status.json"
+
+# ─── Check initialized ───────────────────────────────────────────────────
+
+if [[ ! -f "$STATE_FILE" ]]; then
+    echo "Harness not initialized."
+    echo ""
+    echo "  → Run /harness-init to set up the harness"
+    exit 1
+fi
+
+# ─── Parse state file ────────────────────────────────────────────────────
+
+get_yaml_val() {
+    local key="$1"
+    grep -o "${key}: *[^ ]*" "$STATE_FILE" 2>/dev/null | head -1 | sed "s/${key}: *//" | tr -d '"'
+}
+
+VERSION=$(get_yaml_val "harness_version")
+STACK=$(get_yaml_val "stack")
+
+# Enforcement
+E_FRONTEND=$(get_yaml_val "frontend")
+E_DATABASE=$(get_yaml_val "database")
+E_API=$(get_yaml_val "api")
+E_OBSERVABILITY=$(get_yaml_val "observability")
+
+on_off() {
+    if [[ "$1" == "true" ]]; then echo "ON"; else echo "OFF"; fi
+}
+
+# ─── Health line ──────────────────────────────────────────────────────────
+
+echo "Harness Status — codeharness v${VERSION:-0.1.0}"
+echo ""
+
+# Stack
+echo "  Stack: ${STACK:-unknown}"
+
+# Loop status
+if [[ -f "$LOOP_STATUS_FILE" ]]; then
+    local_loop=$(jq -r '.loop_count // 0' "$LOOP_STATUS_FILE" 2>/dev/null || echo "0")
+    local_status=$(jq -r '.status // "idle"' "$LOOP_STATUS_FILE" 2>/dev/null || echo "idle")
+    echo "  Loop: iteration $local_loop ($local_status)"
+fi
+
+echo ""
+
+# ─── Enforcement ──────────────────────────────────────────────────────────
+
+echo "  Enforcement:"
+printf "    frontend:%-4s database:%-4s api:%-4s observability:%-4s\n" \
+    "$(on_off "$E_FRONTEND")" "$(on_off "$E_DATABASE")" \
+    "$(on_off "$E_API")" "$(on_off "$E_OBSERVABILITY")"
+echo ""
+
+# ─── Sprint progress ─────────────────────────────────────────────────────
+
+if [[ -f "$PROGRESS_FILE" ]]; then
+    total=$(jq '.tasks | length' "$PROGRESS_FILE" 2>/dev/null || echo "0")
+    completed=$(jq '[.tasks[] | select(.status == "complete")] | length' "$PROGRESS_FILE" 2>/dev/null || echo "0")
+
+    echo "  Sprint: $completed/$total stories"
+    echo ""
+
+    # Per-story status
+    jq -r '.tasks[] | "\(.status)\t\(.id)\t\(.title)"' "$PROGRESS_FILE" 2>/dev/null | \
+    while IFS=$'\t' read -r st id title; do
+        case "$st" in
+            complete)    marker="[PASS]" ;;
+            in_progress) marker="[ >> ]" ;;
+            *)           marker="[    ]" ;;
+        esac
+        # Truncate title to keep under 100 chars
+        printf "    %s %s: %s\n" "$marker" "$id" "${title:0:60}"
+    done
+
+    echo ""
+
+    # Verification summary
+    VLOG="$PROJECT_DIR/ralph/verification-log.json"
+    if [[ -f "$VLOG" ]]; then
+        v_total=$(jq '.events | length' "$VLOG" 2>/dev/null || echo "0")
+        v_pass=$(jq '[.events[] | select(.result == "pass")] | length' "$VLOG" 2>/dev/null || echo "0")
+        echo "  Verification: $v_pass passed / $v_total checks"
+        echo ""
+    fi
+
+    # Next action
+    current=$(jq -r '.tasks[] | select(.status == "pending" or .status == "in_progress") | .id' "$PROGRESS_FILE" 2>/dev/null | head -1)
+    if [[ -n "$current" && "$current" != "null" ]]; then
+        current_title=$(jq -r --arg id "$current" '.tasks[] | select(.id == $id) | .title' "$PROGRESS_FILE" 2>/dev/null)
+        echo "  → Current: $current ($current_title)"
+    elif [[ "$completed" == "$total" && "$total" != "0" ]]; then
+        echo "  → All stories complete!"
+    else
+        echo "  → Run /harness-run to start execution"
+    fi
+else
+    echo "  No sprint progress file found."
+    echo ""
+    echo "  → Run /harness-run to start execution"
+fi

package/ralph/lib/circuit_breaker.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+# circuit_breaker.sh - Prevents runaway token consumption by detecting stagnation
+# Vendored from snarktank/ralph, adapted for codeharness
+# Based on Michael Nygard's "Release It!" pattern
+
+source "$(dirname "${BASH_SOURCE[0]}")/date_utils.sh"
+
+CB_STATE_CLOSED="CLOSED"
+CB_STATE_HALF_OPEN="HALF_OPEN"
+CB_STATE_OPEN="OPEN"
+
+# Use HARNESS_STATE_DIR if set, otherwise default
+HARNESS_STATE_DIR="${HARNESS_STATE_DIR:-.}"
+CB_STATE_FILE="${HARNESS_STATE_DIR}/.circuit_breaker_state"
+CB_HISTORY_FILE="${HARNESS_STATE_DIR}/.circuit_breaker_history"
+
+CB_NO_PROGRESS_THRESHOLD=${CB_NO_PROGRESS_THRESHOLD:-3}
+CB_SAME_ERROR_THRESHOLD=${CB_SAME_ERROR_THRESHOLD:-5}
+CB_PERMISSION_DENIAL_THRESHOLD=${CB_PERMISSION_DENIAL_THRESHOLD:-2}
+CB_COOLDOWN_MINUTES=${CB_COOLDOWN_MINUTES:-30}
+CB_AUTO_RESET=${CB_AUTO_RESET:-false}
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+init_circuit_breaker() {
+    if [[ -f "$CB_STATE_FILE" ]]; then
+        if ! jq '.' "$CB_STATE_FILE" > /dev/null 2>&1; then
+            rm -f "$CB_STATE_FILE"
+        fi
+    fi
+
+    if [[ ! -f "$CB_STATE_FILE" ]]; then
+        jq -n \
+            --arg state "$CB_STATE_CLOSED" \
+            --arg last_change "$(get_iso_timestamp)" \
+            '{
+                state: $state,
+                last_change: $last_change,
+                consecutive_no_progress: 0,
+                consecutive_same_error: 0,
+                consecutive_permission_denials: 0,
+                last_progress_loop: 0,
+                total_opens: 0,
+                reason: ""
+            }' > "$CB_STATE_FILE"
+    fi
+
+    if [[ -f "$CB_HISTORY_FILE" ]]; then
+        if ! jq '.' "$CB_HISTORY_FILE" > /dev/null 2>&1; then
+            rm -f "$CB_HISTORY_FILE"
+        fi
+    fi
+
+    if [[ ! -f "$CB_HISTORY_FILE" ]]; then
+        echo '[]' > "$CB_HISTORY_FILE"
+    fi
+}
+
+get_circuit_state() {
+    if [[ ! -f "$CB_STATE_FILE" ]]; then
+        echo "$CB_STATE_CLOSED"
+        return
+    fi
+    jq -r '.state' "$CB_STATE_FILE" 2>/dev/null || echo "$CB_STATE_CLOSED"
+}
+
+can_execute() {
+    local state=$(get_circuit_state)
+    if [[ "$state" == "$CB_STATE_OPEN" ]]; then
+        return 1
+    else
+        return 0
+    fi
+}
+
+record_loop_result() {
+    local loop_number=$1
+    local files_changed=$2
+    local has_errors=$3
+    local output_length=$4
+
+    init_circuit_breaker
+
+    local state_data=$(cat "$CB_STATE_FILE")
+    local current_state=$(echo "$state_data" | jq -r '.state')
+    local consecutive_no_progress=$(echo "$state_data" | jq -r '.consecutive_no_progress' | tr -d '[:space:]')
+    local consecutive_same_error=$(echo "$state_data" | jq -r '.consecutive_same_error' | tr -d '[:space:]')
+    local last_progress_loop=$(echo "$state_data" | jq -r '.last_progress_loop' | tr -d '[:space:]')
+
+    consecutive_no_progress=$((consecutive_no_progress + 0))
+    consecutive_same_error=$((consecutive_same_error + 0))
+    last_progress_loop=$((last_progress_loop + 0))
+
+    local has_progress=false
+
+    if [[ $files_changed -gt 0 ]]; then
+        has_progress=true
+        consecutive_no_progress=0
+        last_progress_loop=$loop_number
+    else
+        consecutive_no_progress=$((consecutive_no_progress + 1))
+    fi
+
+    if [[ "$has_errors" == "true" ]]; then
+        consecutive_same_error=$((consecutive_same_error + 1))
+    else
+        consecutive_same_error=0
+    fi
+
+    local new_state="$current_state"
+    local reason=""
+
+    case $current_state in
+        "$CB_STATE_CLOSED")
+            if [[ $consecutive_no_progress -ge $CB_NO_PROGRESS_THRESHOLD ]]; then
+                new_state="$CB_STATE_OPEN"
+                reason="No progress detected in $consecutive_no_progress consecutive loops"
+            elif [[ $consecutive_same_error -ge $CB_SAME_ERROR_THRESHOLD ]]; then
+                new_state="$CB_STATE_OPEN"
+                reason="Same error repeated in $consecutive_same_error consecutive loops"
+            elif [[ $consecutive_no_progress -ge 2 ]]; then
+                new_state="$CB_STATE_HALF_OPEN"
+                reason="Monitoring: $consecutive_no_progress loops without progress"
+            fi
+            ;;
+        "$CB_STATE_HALF_OPEN")
+            if [[ "$has_progress" == "true" ]]; then
+                new_state="$CB_STATE_CLOSED"
+                reason="Progress detected, circuit recovered"
+            elif [[ $consecutive_no_progress -ge $CB_NO_PROGRESS_THRESHOLD ]]; then
+                new_state="$CB_STATE_OPEN"
+                reason="No recovery, opening circuit after $consecutive_no_progress loops"
+            fi
+            ;;
+        "$CB_STATE_OPEN")
+            reason="Circuit breaker is open, execution halted"
+            ;;
+    esac
+
+    local total_opens=$(echo "$state_data" | jq -r '.total_opens' | tr -d '[:space:]')
+    total_opens=$((total_opens + 0))
+    if [[ "$new_state" == "$CB_STATE_OPEN" && "$current_state" != "$CB_STATE_OPEN" ]]; then
+        total_opens=$((total_opens + 1))
+    fi
+
+    jq -n \
+        --arg state "$new_state" \
+        --arg last_change "$(get_iso_timestamp)" \
+        --argjson consecutive_no_progress "$consecutive_no_progress" \
+        --argjson consecutive_same_error "$consecutive_same_error" \
+        --argjson consecutive_permission_denials 0 \
+        --argjson last_progress_loop "$last_progress_loop" \
+        --argjson total_opens "$total_opens" \
+        --arg reason "$reason" \
+        --argjson current_loop "$loop_number" \
+        '{
+            state: $state,
+            last_change: $last_change,
+            consecutive_no_progress: $consecutive_no_progress,
+            consecutive_same_error: $consecutive_same_error,
+            consecutive_permission_denials: $consecutive_permission_denials,
+            last_progress_loop: $last_progress_loop,
+            total_opens: $total_opens,
+            reason: $reason,
+            current_loop: $current_loop
+        }' > "$CB_STATE_FILE"
+
+    if [[ "$new_state" == "$CB_STATE_OPEN" ]]; then
+        return 1
+    else
+        return 0
+    fi
+}
+
+reset_circuit_breaker() {
+    local reason=${1:-"Manual reset"}
+    jq -n \
+        --arg state "$CB_STATE_CLOSED" \
+        --arg last_change "$(get_iso_timestamp)" \
+        --arg reason "$reason" \
+        '{
+            state: $state,
+            last_change: $last_change,
+            consecutive_no_progress: 0,
+            consecutive_same_error: 0,
+            consecutive_permission_denials: 0,
+            last_progress_loop: 0,
+            total_opens: 0,
+            reason: $reason
+        }' > "$CB_STATE_FILE"
+}
+
+should_halt_execution() {
+    local state=$(get_circuit_state)
+    if [[ "$state" == "$CB_STATE_OPEN" ]]; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+export -f init_circuit_breaker
+export -f get_circuit_state
+export -f can_execute
+export -f record_loop_result
+export -f reset_circuit_breaker
+export -f should_halt_execution

package/ralph/lib/date_utils.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# date_utils.sh - Cross-platform date utility functions for codeharness Ralph loop
+# Vendored from snarktank/ralph with modifications for codeharness
+
+# Get current timestamp in ISO 8601 format with seconds precision
+get_iso_timestamp() {
+    local result
+    if result=$(date -u -Iseconds 2>/dev/null) && [[ -n "$result" ]]; then
+        echo "$result"
+        return
+    fi
+    date -u +"%Y-%m-%dT%H:%M:%S%z" | sed 's/\(..\)$/:\1/'
+}
+
+# Get time component (HH:MM:SS) for one hour from now
+get_next_hour_time() {
+    if date -d '+1 hour' '+%H:%M:%S' 2>/dev/null; then
+        return
+    fi
+    if date -v+1H '+%H:%M:%S' 2>/dev/null; then
+        return
+    fi
+    local future_epoch=$(($(date +%s) + 3600))
+    date -r "$future_epoch" '+%H:%M:%S' 2>/dev/null || date '+%H:%M:%S'
+}
+
+# Get current Unix epoch time in seconds
+get_epoch_seconds() {
+    date +%s
+}
+
+# Convert ISO 8601 timestamp to Unix epoch seconds
+parse_iso_to_epoch() {
+    local iso_timestamp=$1
+
+    if [[ -z "$iso_timestamp" || "$iso_timestamp" == "null" ]]; then
+        date +%s
+        return
+    fi
+
+    local result
+    if result=$(date -d "$iso_timestamp" +%s 2>/dev/null) && [[ "$result" =~ ^[0-9]+$ ]]; then
+        echo "$result"
+        return
+    fi
+
+    local tz_fixed
+    tz_fixed=$(echo "$iso_timestamp" | sed -E 's/Z$/+0000/; s/([+-][0-9]{2}):([0-9]{2})$/\1\2/')
+    if result=$(date -j -f "%Y-%m-%dT%H:%M:%S%z" "$tz_fixed" +%s 2>/dev/null) && [[ "$result" =~ ^[0-9]+$ ]]; then
+        echo "$result"
+        return
+    fi
+
+    date +%s
+}
+
+export -f get_iso_timestamp
+export -f get_next_hour_time
+export -f get_epoch_seconds
+export -f parse_iso_to_epoch