@pageai/ralph-loop 1.0.0

package/scripts/lib/display.sh

@@ -0,0 +1,196 @@
+#!/bin/bash
+# Display module for ralph.sh
+# UI elements, ASCII art, and help display
+# Dependencies: constants.sh, timing.sh
+
+# Display BLOCKED message with reason and resume instructions
+# Usage: display_blocked_message "reason" iteration_number
+display_blocked_message() {
+  local reason="$1"
+  local iteration="$2"
+
+  echo ""
+  echo -e "${RD}░░▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒░░${R}"
+  echo -e "  🚫 ${RD}Agent is BLOCKED${R}"
+  echo -e "${RD}░░▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒░░${R}"
+  echo ""
+  echo -e "  ${Y}Reason:${R}"
+  echo -e "    $reason"
+  echo ""
+  echo -e "  ${C}How to resume:${R}"
+  echo -e "    1. Resolve the blocking issue described above"
+  echo -e "    2. Run ${GR}./ralph.sh${R} to continue from where you left off"
+  echo ""
+  echo -e "  ${G}Stopped at iteration ${Y}$iteration${R}"
+  echo ""
+}
+
+# Display DECIDE message with question and resume instructions
+# Usage: display_decide_message "question" iteration_number
+display_decide_message() {
+  local question="$1"
+  local iteration="$2"
+
+  echo ""
+  echo -e "${M}░░▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒░░${R}"
+  echo -e "  ❓ ${M}Agent needs a DECISION${R}"
+  echo -e "${M}░░▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒░░${R}"
+  echo ""
+  echo -e "  ${Y}Question:${R}"
+  echo -e "    $question"
+  echo ""
+  echo -e "  ${C}How to answer and resume:${R}"
+  echo -e "    1. Make a decision about the question above"
+  echo -e "    2. Update the relevant files or configuration"
+  echo -e "    3. Run ${GR}./ralph.sh${R} to continue with your decision"
+  echo ""
+  echo -e "  ${G}Stopped at iteration ${Y}$iteration${R}"
+  echo ""
+}
+
+# Ralph ASCII art and catchphrases
+show_ralph() {
+
+  local catchphrases=(
+    "■▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒I'm helping!▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒I'm doing my best!▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒I'm in danger!▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒I'm learnding!▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒▒My cat's breath smells like cat food.▒▒▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒▒▒Me fail English? That's unpossible!▒▒▒▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒▒▒▒I'm asking Claude to cook pasta!▒▒▒▒▒▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒▒▒▒▒I found a moon rock in my nose!▒▒▒▒▒▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒▒▒▒▒▒▒▒▒It tastes like burning!▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒When I grow up, I want to be a computer!▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒I'm a develotron!▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒I'm helpding AI!▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒I'm essential!▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒■▒▒▓■"
+    "■▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒■▒▒▓■"
+  )
+
+  local random_index=$((RANDOM % 15))
+  local phrase="${catchphrases[$random_index]}"
+
+  echo ""
+  echo -e "${Y}"
+  cat << 'RALPH'
+
+██████╗  █████╗ ██╗     ██████╗ ██╗  ██╗
+██╔══██╗██╔══██╗██║     ██╔══██╗██║  ██║
+██████╔╝███████║██║     ██████╔╝███████║
+██╔══██╗██╔══██║██║     ██╔═══╝ ██╔══██║
+██║  ██║██║  ██║███████╗██║     ██║  ██║
+╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝  ╚═╝
+
+██╗      ██████╗  ██████╗ ██████╗
+██║     ██╔═══██╗██╔═══██╗██╔══██╗
+██║     ██║   ██║██║   ██║██████╔╝
+██║     ██║   ██║██║   ██║██╔═══╝
+███████╗╚██████╔╝╚██████╔╝██║
+╚══════╝ ╚═════╝  ╚═════╝ ╚═╝
+
+■■■■■■■■■■■■■■■■■■■■■■■■■■■▓▓■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
+■■■■■■■■■■■■■■■■▓▒▓▒▓▒▒▓▒▒▓▢▒▒▓▒▓▒▓▓■■■■■■■■■■■■■■■■■■■■■■■
+■■■■■■■■■■■▓▓▓▒▓▒▒▓▒▒▓▒▒▓▒▢▓▒▢▓▢▒▓▒▒▓▒▓▓▓▓■■■■■■■■■■■■■■■■■
+■■■■■■■■■▒▢▒▒▓▒▢▓▒▢▒▓▢▒▓▢▢▒▒▢▒▓▢▢▒▒▢▢▓▒▒▓▒▓▒■■■■■■■■■■■■■■■
+■■■■■■■■■▓▒▒▓▢▒▒▒▢▒▓▢▢▓▢▢▢▓▢▢▒▒▢▢▢▓▒▢▒▒▒▒▓▒▓▒▒▓▓■■■■■■■■■■■
+■■■■■■■■▓▢▒▓▢▢▓▒▢▒▓▢▢▓▒▢▢▢▒▢▢▒▒▢▢▢▒▒▢▢▒▒▢▒▓▢▒▒▒▓■■■■■■■■■■■
+■■■■■■■▓▒▒▓▢▢▓▒▢▢▓▢▢▢▒▢▢▢▢▢▒▒▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▒▒▓■■■■■■■■■■
+■■■■■■▓▒▒▓▢▢▒▓▢▢▒▒▢▢▢▢▢▒▒▢    ▢▒▒▢▢▢▢▢▢▒▒▢   ▢▒▒▒■■■■■■■■■■
+■■■■■■▓▢▓▒▢▢▓▒▢▢▢▢▢▢▢▢▒▒        ▢▒▢▢▢▢▒        ▢▒▓■■■■■■■■■
+■■■■■▓▒▒▓▢▢▢▓▢▢▢▢▢▢▢▢▢▒  ▓👁️▓     ▒▢▢▢▢▒  ▓👁️▓  ▢▒▓■■■■■■■■■
+■■■■▓▒▒▒▒▒▢▢▢▢▢▢▢▢▢▢▢▢▢▓        ▒▒▢▢▢▢▒▒▢     ▢▒▒▓■■■■■■■■■
+■■■■▢▒▓▒▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▒▓▒  ▢▓▒▢▢▒▢▢▒▒▓▢▢▢▢▢▢▢▒▒▓■■■■■■■■■
+■■■■▓▢▒▒▒▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▒▒▒▒▒▒▢▢▢▢▢▢▢▢▢▢▒▒▓■■■■■■■■
+■■■■▓▢▒▒▒▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▒▒▒▒▒▒▒▒▒▒▢▢▢▢▢▢▢▢▢▒▒▓■■■■■■■
+■■■■■▓▓▒▒▒▒▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▓▓▒▢▒▓▒▢▒▒▓▢▢▢▢▢▢▢▢▢▢▒▒■■■■■■■■
+■■■■■▓▓▒▒▒▒▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▓▓▒▒▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▒▒■■■■■■■■
+■■■■■■■■▓▒▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▒▓▒▢▢▒▒▓▒▢▢▢▢▢▢▢▢▢▢▢▢▒▒▒▓■■■■■■
+■■■■■■■■▓■▒▒▢▢▢▢▢▢▢▢▢▢▢▒▒▢▢▓▒▢▢▢▒▓▓▓▓▒▒▒▢▢▢▢▢▢▢▢▒▒▒▒▓■■■■■■
+■■■■■■■■■■■■▒▢▢▢▢▢▢▢▢▢▢▓▓■■▒▢▢▢▢▒▒▢▢▢▒▓▒▒▢▢▢▒▒▒▒■■■■■■■■■■■
+■■■■■■■■■■▒▒▒▓▒▒▢▢▢▢▢▢▢▢▢▢▓▒▢▢▢▢▢▢▒▒▓▒▒▓▓▒▒▒▓■■■■■■■■■■■■■■
+■■■■■■■■■▓▒▒▒▒▒▒▒▓▓▒▢▢▢▢▢▢▓▒▢▢▢▢▢▢▢▢▢▢▢▒▓▒▒▓■■■■■■■■■■■■■■■
+■■■■■■■■■▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▒▒▓▓▒▢▢▢▢▢▢▢▒▓▒▓▓▓▒▓■■■■■■■■■■■■■■
+■■■■■■▓▒▒▒▒▓▒▒▒▒▒▒▒▒▒▒▒▓▒▒▒▒▒▒▒▓▒▢▢▢▒▒▓▒▒▓▓▒▓▓▓■■■■■■■■■■■■
+■■■■■▒▒▒▒▒▒▒▒▒▓▒▒▒▒▒▒▒▓▒▒▒▒▒▒▒▒▒▒▓▒▒▒▒▓▒▒▒▓▓■▒▒▓■■■■■■■■■■■
+■■■▓■▒▒▒▒▒▒▒▒▒▒▒▒▓▒▒▓▒▒▒▒▒▒▒▒▒▒▒▒▒▓▒▒▓▒▒▓▓▒▒▒▒▓▓▓■■■■■■■■■■
+■■■■■▒▒▒▒▒▒▒▒▒▒▒▒▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▒▒▒▒▒▒▒▒▒▒▓▓▒■■■■■■■■■
+■■■■■▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒■■■■■■■■
+■■■▓▢▢▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓■■■■■■■
+■■▓▢▢▒▒▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓■■■■■
+■▓▒▢▒▒▒▒▒▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓■■■■
+■▓▢▢▒▒▒▒▒▒▒▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▒▓■■■
+■▓▢▢▒▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▓▓▓■▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▒▓■■
+■▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒■▒▓■■
+RALPH
+
+  echo -e "$phrase"
+  echo -e "■■▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▒▓■${R}"
+  echo -e "═══════════════════════════════════════════════════════════"
+  echo -e " Ralph Wiggum Loop ・ Long-running AI agents"
+}
+
+# Show help and instructions
+show_help() {
+  show_ralph
+  echo ""
+  echo -e "${Y}Usage:${R} ./ralph.sh [options] [max_iterations]"
+  echo ""
+  echo -e "${Y}Options:${R}"
+  echo "  --max-iterations N, -n N    Set maximum iterations (default: 10)"
+  echo "  --once                      Run exactly 1 iteration (overrides --max-iterations)"
+  echo "  --help, -h                  Show this help message and exit"
+  echo ""
+  echo -e "${Y}Arguments:${R}"
+  echo "  max_iterations    Maximum number of iterations (positional, default: 10)"
+  echo ""
+  echo -e "${Y}Examples:${R}"
+  echo "  ./ralph.sh                      Run with default 10 iterations"
+  echo "  ./ralph.sh 5                    Run with 5 iterations max"
+  echo "  ./ralph.sh -n 5                 Run with 5 iterations max"
+  echo "  ./ralph.sh --max-iterations 5   Same as above"
+  echo "  ./ralph.sh --once               Run exactly 1 iteration"
+  echo ""
+  echo -e "${Y}Files:${R}"
+  echo "  📁 .agent/history/         Iteration output logs"
+  echo "  📋 .agent/logs/LOG.md      Progress log file"
+  echo "  📄 .agent/prd/PRD.md       PRD file with task definitions"
+  echo "  📄 .agent/tasks/           Detailed task descriptions"
+  echo "  📝 .agent/PROMPT.md        Prompt sent to Claude each iteration"
+  echo "  📄 .agent/tasks.json       Task lookup table"
+  echo ""
+  echo -e "${Y}Behavior:${R}"
+  echo "  🤔 Decides on what tasks to pick from .agent/tasks.json"
+  echo "  📋 Logs progress to .agent/logs/LOG.md"
+  echo "  🎉 Exits early if Claude outputs <promise>COMPLETE</promise>"
+  echo "  🖼️ Takes screenshots of progress"
+  echo ""
+  echo -e "${B}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${R}"
+  echo -e "${Y}📚 Getting Started:${R}"
+  echo -e "${B}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${R}"
+  echo ""
+  echo -e "  ${C}Step 1:${R} Create a PRD using the prd-creator skill"
+  echo -e "         ${G}Dump your requirements and ask AI to use the prd-creator skill${R}"
+  echo ""
+  echo -e "  ${C}Step 2:${R} Ensure your .agent/ directory has the required files:"
+  echo "         📄 .agent/prd/PRD.md        Your product requirements"
+  echo "         📄 .agent/prd/SUMMARY.md    Short project overview"
+  echo "         📋 .agent/tasks.json        Generated task list"
+  echo "         📁 .agent/tasks/            Individual task specs (TASK-{ID}.json)"
+  echo "         📝 .agent/PROMPT.md         Agent instructions"
+  echo "         📋 .agent/logs/LOG.md       Progress log (auto-created)"
+  echo ""
+  echo -e "  ${C}Step 3:${R} Run Ralph!"
+  echo -e "         ${G}./ralph.sh${R}              # Start the agent loop"
+  echo ""
+  echo -e "${Y}🔄 How it works:${R}"
+  echo "  Each iteration, Ralph will:"
+  echo "  1. Find the highest-priority incomplete task in tasks.json"
+  echo "  2. Work through the task steps in .agent/tasks/TASK-{ID}.json"
+  echo "  3. Run tests, linting, and type checking"
+  echo "  4. Update task status and commit changes"
+  echo "  5. Repeat until all tasks pass or max iterations reached"
+  echo ""
+  exit 0
+}

package/scripts/lib/logging.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Logging module for ralph.sh
+# Consistent, colored logging for different message types.
+# Dependencies: constants.sh
+#
+# Usage:
+#   log_info "Starting process..."
+#   log_success "Task completed"
+#   log_warn "This might take a while"
+#   log_error "Something went wrong"
+
+# Log info message with blue [INFO] prefix
+log_info() {
+  echo -e "${B}[INFO]${R} $1"
+}
+
+# Log success message with green [OK] prefix
+log_success() {
+  echo -e "${GR}[OK]${R} $1"
+}
+
+# Log warning message with yellow [WARN] prefix
+log_warn() {
+  echo -e "${Y}[WARN]${R} $1"
+}
+
+# Log error message with red [ERROR] prefix to stderr
+log_error() {
+  echo -e "${RD}[ERROR]${R} $1" >&2
+}

package/scripts/lib/notify.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Notification module for ralph.sh
+# Cross-platform sound and desktop notifications
+# Dependencies: None
+
+# Play notification sound cross-platform
+# Usage: play_notification_sound
+# Supports macOS, Linux (PulseAudio), Windows (WSL), with terminal bell fallback
+play_notification_sound() {
+  (
+    # Try macOS first (afplay)
+    if command -v afplay &> /dev/null; then
+      afplay /System/Library/Sounds/Glass.aiff 2>/dev/null || true
+    # Try Linux (PulseAudio)
+    elif command -v paplay &> /dev/null; then
+      paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null || true
+    # Try Windows/WSL (PowerShell)
+    elif command -v powershell.exe &> /dev/null; then
+      powershell.exe -Command "[System.Media.SystemSounds]::Asterisk.Play()" 2>/dev/null || true
+    fi
+    # Always try terminal bell as additional notification
+    echo -e '\a' 2>/dev/null || true
+  ) &
+}
+
+# Show desktop notification cross-platform
+# Usage: show_notification "title" "message"
+# Supports macOS (osascript), Linux (notify-send), fails silently on unsupported platforms
+show_notification() {
+  local title="$1"
+  local message="$2"
+  (
+    # Try macOS (osascript)
+    if command -v osascript &> /dev/null; then
+      osascript -e "display notification \"$message\" with title \"$title\"" 2>/dev/null || true
+    # Try Linux (notify-send)
+    elif command -v notify-send &> /dev/null; then
+      notify-send "$title" "$message" 2>/dev/null || true
+    fi
+  ) &
+}

package/scripts/lib/output.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+# Output module for ralph.sh
+# JSON parsing and ANSI stripping utilities
+# Dependencies: constants.sh, terminal.sh
+
+# Parse JSON stream and extract text content
+# Handles Agent's stream-json format
+parse_json_content() {
+  local json_line="$1"
+  # Try to extract text content from various JSON formats
+  # For example, Claude stream-json outputs {"type":"content_block_delta","delta":{"text":"..."}}
+  # or {"type":"text","text":"..."} etc.
+
+  # Extract text from delta
+  local text=$(echo "$json_line" | grep -o '"text":"[^"]*"' | head -1 | sed 's/"text":"//;s/"$//')
+  if [ -n "$text" ]; then
+    # Unescape common JSON escapes
+    # JSON \n -> actual newline, \t -> actual tab, etc.
+    text=$(echo "$text" | sed 's/\\n/\'$'\n''/g; s/\\t/\'$'\t''/g; s/\\"/"/g; s/\\\\/\\/g')
+    echo "$text"
+    return
+  fi
+
+  # If it doesn't look like JSON, return as-is
+  if ! echo "$json_line" | grep -q '^{'; then
+    echo "$json_line"
+  fi
+}
+
+# Strip ANSI escape sequences and control characters from text
+# Usage: clean_text=$(strip_ansi "$text")
+# Handles:
+#   - CSI sequences: ESC[...m (colors), ESC[...H (cursor), ESC[?...h/l (modes)
+#   - OSC sequences: ESC]0;...(BEL or ESC\) for window titles
+#   - OSC-like sequences without ESC prefix (from script command)
+#   - Caret notation for control chars: ^@ through ^_ (from script command)
+#   - Other escapes: ESC followed by various characters
+#   - Control chars: backspace, BEL, carriage return, etc.
+strip_ansi() {
+  local input="$1"
+  # First use sed to handle ESC sequences (must be done before tr removes ESC)
+  # Then use tr to remove remaining raw control characters
+  # tr removes: 0x00-0x08 (NUL through BS), 0x0B-0x0C (VT, FF), 0x0E-0x1A (SO through SUB),
+  #             0x1C-0x1F (FS through US) - excludes ESC (0x1B) for sed to process
+  # sed handles: ESC sequences, OSC-like patterns, caret notation
+  # Note: OSC pattern uses ^ anchor but also handles after caret removal via second pass
+  echo "$input" | sed \
+    -e 's/\x1b\[[0-9;?]*[A-Za-z]//g' \
+    -e 's/\x1b\][^\x07]*\x07//g' \
+    -e 's/\x1b\][^\x1b]*\x1b\\//g' \
+    -e 's/\x1b[()][AB012]//g' \
+    -e 's/\x1b[>=]//g' \
+    -e 's/\x1b.//g' \
+    -e 's/\^[][A-Z@\\^_]//g' \
+    -e 's/^0;[^]]*]//g' \
+    -e 's/<u0;//g' \
+    | tr -d '\000-\010\013\014\016-\032\034-\037' \
+    | sed -e 's/^0;[^]]*]//g'
+}
+
+# Strip ANSI from a file and write to output file
+# Usage: strip_ansi_file "$input_file" "$output_file"
+# First sed processes ESC sequences, then tr removes remaining control characters
+strip_ansi_file() {
+  local input_file="$1"
+  local output_file="$2"
+  # First sed processes ESC sequences (before tr removes anything)
+  # Then tr removes remaining control characters (excluding newline 0x0A, CR 0x0D)
+  # tr range excludes ESC (0x1B = octal 033) which sed already handled
+  # Final sed pass cleans up OSC patterns that were hidden by control chars
+  sed \
+    -e 's/\x1b\[[0-9;?]*[A-Za-z]//g' \
+    -e 's/\x1b\][^\x07]*\x07//g' \
+    -e 's/\x1b\][^\x1b]*\x1b\\//g' \
+    -e 's/\x1b[()][AB012]//g' \
+    -e 's/\x1b[>=]//g' \
+    -e 's/\x1b.//g' \
+    -e 's/\^[][A-Z@\\^_]//g' \
+    -e 's/^0;[^]]*]//g' \
+    -e 's/<u0;//g' \
+    "$input_file" | tr -d '\000-\010\013\014\016-\032\034-\037' \
+    | sed -e 's/^0;[^]]*]//g' \
+    > "$output_file"
+}
+
+# Extract final summary from JSON stream output
+# Looks for the result type message which contains the final output
+extract_final_summary() {
+  local output_file="$1"
+  local result_line=""
+  local summary=""
+
+  # Look for the result type message in the JSON stream
+  if [ -f "$output_file" ]; then
+    result_line=$(grep '"type":"result"' "$output_file" 2>/dev/null | tail -1)
+
+    if [ -n "$result_line" ]; then
+      # Extract the result text using jq
+      if command -v jq &> /dev/null; then
+        summary=$(echo "$result_line" | jq -r '.result // ""' 2>/dev/null)
+      fi
+    fi
+  fi
+
+  echo "$summary"
+}
+
+# Display the final summary with simple separators
+display_final_summary() {
+  local summary="$1"
+  local max_lines="${2:-15}"  # Default to max 15 lines
+
+  if [ -z "$summary" ]; then
+    return
+  fi
+
+  # Display with simple separators
+  echo ""
+  echo -e "${C}─────────────────────────────────────────────────────────────────${R}"
+  echo -e "${Y}Iteration Summary${R}"
+  echo -e "${C}─────────────────────────────────────────────────────────────────${R}"
+
+  # Wrap and display lines (max 70 chars wide, max 15 lines)
+  local line_count=0
+  local width=70
+  while IFS= read -r line || [ -n "$line" ]; do
+    while [ ${#line} -gt $width ] && [ $line_count -lt $max_lines ]; do
+      # Find last space within width for word wrap
+      local cut_at=$width
+      local segment="${line:0:$width}"
+      local last_space="${segment% *}"
+      if [ "$last_space" != "$segment" ] && [ ${#last_space} -gt 20 ]; then
+        cut_at=${#last_space}
+      fi
+      echo "${line:0:$cut_at}"
+      line="${line:$cut_at}"
+      line="${line# }"  # Remove leading space
+      ((line_count++))
+    done
+    if [ $line_count -lt $max_lines ] && [ -n "$line" ]; then
+      echo "$line"
+      ((line_count++))
+    fi
+  done <<< "$summary"
+
+  echo -e "${C}─────────────────────────────────────────────────────────────────${R}"
+}

package/scripts/lib/preflight.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# Preflight module for ralph.sh
+# Pre-flight checks before starting the main loop
+# Dependencies: constants.sh, logging.sh
+#
+# Verify required files exist before starting the main loop.
+# Required files cause script exit if missing.
+# Optional files trigger a warning but allow continuation.
+
+# Check if running inside a git repository
+# Usage: check_git_repo
+# Exits with code 1 if not in a git repository
+check_git_repo() {
+  if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    log_error "ralph.sh must be run inside a git repository"
+    exit 1
+  fi
+}
+
+# Ensure history directory exists for storing iteration logs
+# Usage: check_history_dir
+# Creates .agent/history/ directory if it doesn't exist
+check_history_dir() {
+  mkdir -p "$HISTORY_DIR"
+  if [ ! -d "$HISTORY_DIR" ]; then
+    log_error "Failed to create history directory: $HISTORY_DIR"
+    exit 1
+  fi
+}
+
+# Check for required files and exit if missing, warn for optional files
+# Usage: check_required_files
+check_required_files() {
+  local missing_required=false
+
+  # Required files - exit if missing
+  if [ ! -f "$SCRIPT_DIR/.agent/tasks.json" ]; then
+    log_error "Required file missing: .agent/tasks.json"
+    missing_required=true
+  fi
+
+  if [ ! -f "$SCRIPT_DIR/.agent/PROMPT.md" ]; then
+    log_error "Required file missing: .agent/PROMPT.md"
+    missing_required=true
+  fi
+
+  # Exit if any required files are missing
+  if [ "$missing_required" = true ]; then
+    log_error "Please create the required files before running Ralph"
+    exit 1
+  fi
+
+  # Optional files - warn if missing but continue
+  if [ ! -f "$SCRIPT_DIR/.agent/prd/SUMMARY.md" ]; then
+    log_warn "Optional file missing: .agent/prd/SUMMARY.md"
+  fi
+}

package/scripts/lib/preview.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# Preview module for ralph.sh
+# Rolling preview buffer display
+# Dependencies: constants.sh, terminal.sh
+
+# Rolling preview settings
+PREVIEW_LINES=50
+PREVIEW_WIDTH=80
+LINE_BUFFER=()
+LINES_DISPLAYED=0
+ANSI_SUPPORTED=true
+
+# Initialize the rolling preview display
+init_rolling_preview() {
+  LINE_BUFFER=()
+  LINES_DISPLAYED=0
+  PREVIEW_WIDTH=$(get_terminal_width)
+}
+
+# Add line to rolling buffer and update display
+add_to_rolling_preview() {
+  local line="$1"
+
+  # Skip empty lines
+  [ -z "$line" ] && return
+
+  # Truncate to terminal width
+  line=$(truncate_line "$line" $PREVIEW_WIDTH)
+
+  # Add to buffer
+  LINE_BUFFER+=("$line")
+
+  # Keep only last PREVIEW_LINES
+  if [ ${#LINE_BUFFER[@]} -gt $PREVIEW_LINES ]; then
+    LINE_BUFFER=("${LINE_BUFFER[@]:1}")
+  fi
+
+  # Update display
+  if [ "$ANSI_SUPPORTED" = true ]; then
+    redraw_rolling_preview
+  else
+    # Fallback: just print the line
+    echo "$line"
+  fi
+}
+
+# Redraw the rolling preview using ANSI cursor control
+redraw_rolling_preview() {
+  # Move cursor up to start of preview area
+  if [ $LINES_DISPLAYED -gt 0 ]; then
+    printf "\033[%dA" $LINES_DISPLAYED
+  fi
+
+  # Clear and redraw each line
+  local count=0
+  for line in "${LINE_BUFFER[@]}"; do
+    printf "\033[K%s\n" "$line"
+    count=$((count + 1))
+  done
+
+  # Update count of displayed lines
+  LINES_DISPLAYED=$count
+}
+
+# Clear the rolling preview area
+clear_rolling_preview() {
+  if [ "$ANSI_SUPPORTED" = true ] && [ $LINES_DISPLAYED -gt 0 ]; then
+    # Move up and clear each line
+    printf "\033[%dA" $LINES_DISPLAYED
+    for ((i=0; i<$LINES_DISPLAYED; i++)); do
+      printf "\033[K\n"
+    done
+    printf "\033[%dA" $LINES_DISPLAYED
+  fi
+  LINE_BUFFER=()
+  LINES_DISPLAYED=0
+}

package/scripts/lib/promise.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# Promise tags module for ralph.sh
+# Semantic signals for agent communication
+# Dependencies: None
+#
+# Promise tags allow the AI agent to communicate status to the loop controller.
+# The script detects these tags in the agent's output to determine next actions.
+#
+# Tag Format: <promise>TYPE:content</promise>
+#
+# Available Tags:
+#   <promise>COMPLETE</promise>     - All tasks finished successfully
+#   <promise>BLOCKED:reason</promise>  - Agent is blocked and needs human help
+#   <promise>DECIDE:question</promise> - Agent needs human decision/clarification
+#
+# Examples:
+#   <promise>COMPLETE</promise>
+#   <promise>BLOCKED:Missing API credentials for external service</promise>
+#   <promise>DECIDE:Should we use REST or GraphQL for the new endpoint?</promise>
+
+# Regex patterns for promise tags
+PROMISE_COMPLETE_PATTERN='<promise>COMPLETE</promise>'
+PROMISE_BLOCKED_PATTERN='<promise>BLOCKED:[^<]*</promise>'
+PROMISE_DECIDE_PATTERN='<promise>DECIDE:[^<]*</promise>'
+
+# Check if output contains a COMPLETE tag
+# Usage: if has_complete_tag "$output"; then ...
+has_complete_tag() {
+  local output="$1"
+  echo "$output" | grep -q "$PROMISE_COMPLETE_PATTERN"
+}
+
+# Check if output contains a BLOCKED tag
+# Usage: if has_blocked_tag "$output"; then ...
+has_blocked_tag() {
+  local output="$1"
+  echo "$output" | grep -qE "$PROMISE_BLOCKED_PATTERN"
+}
+
+# Check if output contains a DECIDE tag
+# Usage: if has_decide_tag "$output"; then ...
+has_decide_tag() {
+  local output="$1"
+  echo "$output" | grep -qE "$PROMISE_DECIDE_PATTERN"
+}
+
+# Extract the reason from a BLOCKED tag
+# Usage: reason=$(extract_blocked_reason "$output")
+# Returns: the reason string, or empty if no tag found
+extract_blocked_reason() {
+  local output="$1"
+  local match=$(echo "$output" | grep -oE "$PROMISE_BLOCKED_PATTERN" | head -1)
+  if [ -n "$match" ]; then
+    # Extract content between BLOCKED: and </promise>
+    echo "$match" | sed 's/<promise>BLOCKED://;s/<\/promise>//'
+  fi
+}
+
+# Extract the question from a DECIDE tag
+# Usage: question=$(extract_decide_question "$output")
+# Returns: the question string, or empty if no tag found
+extract_decide_question() {
+  local output="$1"
+  local match=$(echo "$output" | grep -oE "$PROMISE_DECIDE_PATTERN" | head -1)
+  if [ -n "$match" ]; then
+    # Extract content between DECIDE: and </promise>
+    echo "$match" | sed 's/<promise>DECIDE://;s/<\/promise>//'
+  fi
+}
+
+# Check if output contains any help-needed tag (BLOCKED or DECIDE)
+# Usage: if needs_help "$output"; then ...
+needs_help() {
+  local output="$1"
+  has_blocked_tag "$output" || has_decide_tag "$output"
+}