agentic-loop 3.16.2 → 3.17.0

package/.claude/skills/prd/SKILL.md

@@ -101,7 +101,7 @@ Break the idea into small, executable stories:
 
 - Each story completable in one Claude session (~10-15 min)
 - Max 3-4 acceptance criteria per story
-- Max 10 stories (suggest phases if more needed)
+- No limit on story count — generate as many stories as the idea needs
 - If appending, start IDs from the next available number
 - **Each story must include its own `techStack`, `constraints`, and `contextFiles`.** Include only what's relevant to that story — don't copy-paste identical context into every story.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-loop",
-  "version": "3.16.2",
+  "version": "3.17.0",
   "description": "Autonomous AI coding loop - PRD-driven development with Claude Code",
   "author": "Allie Jones <allie@allthrive.ai>",
   "license": "MIT",

package/ralph/loop.sh

@@ -2,9 +2,13 @@
 # shellcheck shell=bash
 # loop.sh - The autonomous development loop
 
-# Pre-flight checks to catch common issues before wasting iterations
+# Pre-loop checks to catch common issues before wasting iterations
 preflight_checks() {
-  echo "--- Pre-flight Checks ---"
+  echo ""
+  echo "  ┌──────────────────────────────────┐"
+  echo "  │  ✅ Pre-Loop Checks              │"
+  echo "  └──────────────────────────────────┘"
+  echo ""
   local warnings=0
 
   # Check API connectivity if configured
@@ -86,7 +90,7 @@ preflight_checks() {
 
   echo ""
   if [[ $warnings -gt 0 ]]; then
-    print_warning "$warnings pre-flight warning(s) - loop may fail on connectivity issues"
+    print_warning "$warnings pre-loop warning(s) - loop may fail on connectivity issues"
     echo ""
     read -r -p "Continue anyway? [Y/n] " response
     if [[ "$response" =~ ^[Nn] ]]; then
@@ -96,6 +100,214 @@ preflight_checks() {
   fi
 }
 
+# Check if failure context is trivial (lint/format-only retries)
+# Returns 0 (trivial) if ALL error lines match trivial patterns
+_is_trivial_failure() {
+  local context="$1"
+
+  # Count non-empty, non-whitespace lines
+  local total_lines
+  total_lines=$(printf '%s\n' "$context" | grep -cE '\S' || echo "0")
+
+  # If very short context, consider trivial
+  [[ "$total_lines" -lt 3 ]] && return 0
+
+  # Count error/warning/fail lines that do NOT match trivial patterns
+  # Trivial patterns: auto-fix, formatting tools, style-only issues
+  local non_trivial_errors
+  non_trivial_errors=$(printf '%s\n' "$context" | grep -iE '(error|warning|fail)' | \
+    grep -cviE '(auto.?fix|prettier|eslint --fix|trailing whitespace|import order|isort|black|ruff format|ruff check.*--fix|no-unused-vars|Missing semicolon|Expected indentation)' \
+    || echo "0")
+
+  # Trivial if no error lines survive the trivial-pattern filter
+  [[ "$non_trivial_errors" -eq 0 ]] && return 0
+
+  return 1
+}
+
+# Check if a proposed sign pattern is a duplicate of existing signs
+# Returns 0 (is duplicate) if pattern is too similar to existing
+_sign_is_duplicate() {
+  local pattern="$1"
+
+  [[ ! -f "$RALPH_DIR/signs.json" ]] && return 1
+
+  # Normalize: lowercase, strip punctuation
+  local normalized
+  normalized=$(printf '%s\n' "$pattern" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9 ]//g' | tr -s ' ')
+
+  # Check each existing sign
+  local existing_patterns
+  existing_patterns=$(jq -r '.signs[].pattern' "$RALPH_DIR/signs.json" 2>/dev/null)
+
+  while IFS= read -r existing; do
+    [[ -z "$existing" ]] && continue
+
+    local existing_normalized
+    existing_normalized=$(printf '%s\n' "$existing" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9 ]//g' | tr -s ' ')
+
+    # Substring match in either direction (only for patterns long enough to be meaningful)
+    local shorter_len=${#normalized}
+    [[ ${#existing_normalized} -lt $shorter_len ]] && shorter_len=${#existing_normalized}
+    if [[ $shorter_len -ge 30 ]]; then
+      if [[ "$normalized" == *"$existing_normalized"* ]] || [[ "$existing_normalized" == *"$normalized"* ]]; then
+        return 0
+      fi
+    fi
+
+    # Keyword overlap: extract words 4+ chars, flag as duplicate if >60% overlap
+    local new_words existing_words
+    new_words=$(printf '%s\n' "$normalized" | tr ' ' '\n' | awk 'length >= 4' | sort -u)
+    existing_words=$(printf '%s\n' "$existing_normalized" | tr ' ' '\n' | awk 'length >= 4' | sort -u)
+
+    local new_count overlap_count
+    new_count=$(printf '%s\n' "$new_words" | grep -cE '\S' || echo "0")
+    [[ "$new_count" -eq 0 ]] && continue
+
+    # Count overlapping words (use -xF for whole-line match, not substring)
+    overlap_count=0
+    while IFS= read -r word; do
+      [[ -z "$word" ]] && continue
+      if printf '%s\n' "$existing_words" | grep -qxF "$word"; then
+        overlap_count=$((overlap_count + 1))
+      fi
+    done <<< "$new_words"
+
+    # >60% overlap = duplicate
+    if [[ $((overlap_count * 100 / new_count)) -gt 60 ]]; then
+      return 0
+    fi
+  done <<< "$existing_patterns"
+
+  return 1
+}
+
+# Auto-promote a sign from retry failure context
+# Called when a story passes after multiple retries
+_maybe_promote_sign() {
+  local story="$1"
+  local retries="$2"
+  local config="$RALPH_DIR/config.json"
+
+  # Check config: read .autoPromoteSigns directly (avoid get_config - its // operator
+  # treats false as falsy and returns the default). Default to true if key is absent/null.
+  if [[ -f "$config" ]]; then
+    local auto_promote
+    auto_promote=$(jq -r '.autoPromoteSigns' "$config" 2>/dev/null)
+    if [[ "$auto_promote" == "false" ]]; then
+      return 0
+    fi
+  fi
+
+  # Read failure context (safety check - caller also gates on file existence)
+  local failure_context
+  if [[ ! -f "$RALPH_DIR/last_failure.txt" ]]; then
+    return 0
+  fi
+  failure_context=$(head -"$MAX_SIGN_CONTEXT_LINES" "$RALPH_DIR/last_failure.txt")
+
+  # Skip trivial failures (lint/format only)
+  if _is_trivial_failure "$failure_context"; then
+    log_progress "$story" "SIGN_AUTO" "Skipped - trivial failure (lint/format only)"
+    return 0
+  fi
+
+  # Load existing sign patterns for dedup context
+  local existing_signs=""
+  if [[ -f "$RALPH_DIR/signs.json" ]]; then
+    existing_signs=$(jq -r '.signs[].pattern' "$RALPH_DIR/signs.json" 2>/dev/null | head -"$MAX_SIGN_DEDUP_EXISTING")
+  fi
+
+  # Build extraction prompt
+  local prompt
+  prompt="You are analyzing a development failure that was resolved after $retries attempts.
+
+Extract ONE reusable pattern (a \"sign\") that would prevent this failure in future stories.
+
+## Failure Context
+\`\`\`
+$failure_context
+\`\`\`
+
+## Existing Signs (do NOT duplicate these)
+$existing_signs
+
+## Rules
+- Extract a single, actionable pattern that prevents this class of failure
+- The pattern should be general enough to apply to future stories, not specific to this one
+- If the failure is trivial, unclear, or you can't extract a useful pattern, respond with just: NONE
+- Category must be one of: backend, frontend, testing, general, database, security
+
+## Good Examples
+CATEGORY: backend
+PATTERN: Always run database migrations before executing test suites
+
+CATEGORY: testing
+PATTERN: Use waitFor() instead of fixed delays when testing async UI updates
+
+CATEGORY: frontend
+PATTERN: Import CSS modules with .module.css extension in Next.js projects
+
+## Bad Examples (too specific, too vague)
+PATTERN: Fix the login button color  (too specific to one story)
+PATTERN: Write better code  (too vague to be actionable)
+PATTERN: Always check for errors  (too vague)
+
+## Response Format
+Respond with exactly two lines (or just NONE):
+CATEGORY: <category>
+PATTERN: <pattern>"
+
+  # Call Claude with timeout (one-shot, non-interactive)
+  local response
+  response=$(printf '%s\n' "$prompt" | run_with_timeout "$SIGN_EXTRACTION_TIMEOUT_SECONDS" claude -p 2>/dev/null) || {
+    log_progress "$story" "SIGN_AUTO" "Skipped - Claude extraction timed out"
+    return 0
+  }
+
+  # Check for NONE response
+  if printf '%s\n' "$response" | grep -qi '^NONE'; then
+    log_progress "$story" "SIGN_AUTO" "Skipped - no actionable pattern found"
+    return 0
+  fi
+
+  # Parse response for CATEGORY: and PATTERN: lines (use sed, not grep -P for macOS)
+  local category pattern
+  category=$(echo "$response" | sed -n 's/^CATEGORY:[[:space:]]*//p' | head -1 | tr -d '\r')
+  pattern=$(echo "$response" | sed -n 's/^PATTERN:[[:space:]]*//p' | head -1 | tr -d '\r')
+
+  # Validate extracted values
+  if [[ -z "$category" || -z "$pattern" ]]; then
+    log_progress "$story" "SIGN_AUTO" "Skipped - could not parse Claude response"
+    return 0
+  fi
+
+  # Validate category
+  case "$category" in
+    backend|frontend|testing|general|database|security) ;;
+    *)
+      log_progress "$story" "SIGN_AUTO" "Skipped - invalid category: $category"
+      return 0
+      ;;
+  esac
+
+  # Check for duplicates before adding
+  if _sign_is_duplicate "$pattern"; then
+    log_progress "$story" "SIGN_AUTO" "Skipped - duplicate of existing sign"
+    return 0
+  fi
+
+  # Add the sign (3rd arg = autoPromoted, 4th arg = learnedFrom override)
+  if ralph_sign "$pattern" "$category" "true" "$story"; then
+    log_progress "$story" "SIGN_AUTO" "Added [$category]: $pattern"
+    print_info "Auto-promoted sign: [$category] $pattern"
+  else
+    log_progress "$story" "SIGN_AUTO" "Failed to add sign"
+  fi
+
+  return 0
+}
+
 run_loop() {
   local max_iterations="$DEFAULT_MAX_ITERATIONS"
   local specific_story=""
@@ -128,7 +340,7 @@ run_loop() {
   # Validate prerequisites
   check_dependencies
 
-  # Pre-flight checks to catch issues before wasting iterations
+  # Pre-loop checks to catch issues before wasting iterations
   preflight_checks
 
   if [[ ! -f "$RALPH_DIR/prd.json" ]]; then
@@ -181,9 +393,9 @@ run_loop() {
   local consecutive_timeouts=0
   local max_story_retries
   local max_timeouts=5  # Skip after 5 consecutive timeouts (likely too large/complex)
-  # Default to 8 retries - enough for transient issues, catches infinite loops
-  # Override with config.json: "maxStoryRetries": 12
-  max_story_retries=$(get_config '.maxStoryRetries' "8")
+  # Default to 5 retries - enough for transient issues, stops before wasting cycles
+  # Override with config.json: "maxStoryRetries": 8
+  max_story_retries=$(get_config '.maxStoryRetries' "5")
   local total_attempts=0
   local skipped_stories=()
   local start_time
@@ -264,12 +476,10 @@ run_loop() {
       '(.stories[] | select(.id==$id)) |= . + {retryCount: $count}' \
       "$RALPH_DIR/prd.json" > "$RALPH_DIR/prd.json.tmp" && mv "$RALPH_DIR/prd.json.tmp" "$RALPH_DIR/prd.json"
 
-    # Circuit breaker: skip to next story after max retries (prevents infinite loops)
-    # Note: This is NOT meant to stop legitimate retrying - 8 attempts is enough.
-    # If a story consistently fails after this many tries, it likely needs manual review
-    # (vague test steps, missing prerequisites, or fundamentally broken requirements).
+    # Circuit breaker: stop the loop after max retries (stories depend on each other)
+    # If a story consistently fails after this many tries, it needs manual review.
     if [[ $consecutive_failures -gt $max_story_retries ]]; then
-      print_error "Story $story has failed $consecutive_failures times - likely needs manual review"
+      print_error "Story $story has failed $consecutive_failures times - stopping loop"
       echo ""
       echo "  This usually means:"
       echo "    - Test steps are too vague or ambiguous"
@@ -279,20 +489,18 @@ run_loop() {
       echo "  Failure context saved to: $RALPH_DIR/failures/$story.txt"
       mkdir -p "$RALPH_DIR/failures"
       cp "$RALPH_DIR/last_failure.txt" "$RALPH_DIR/failures/$story.txt" 2>/dev/null || true
-      rm -f "$RALPH_DIR/last_failure.txt"
-      skipped_stories+=("$story")
-      jq --arg id "$story" '(.stories[] | select(.id==$id)) |= . + {skipped: true, skipReason: "exceeded max retries"}' "$RALPH_DIR/prd.json" > "$RALPH_DIR/prd.json.tmp" && mv "$RALPH_DIR/prd.json.tmp" "$RALPH_DIR/prd.json"
-      last_story=""
-      consecutive_failures=0
-      continue
+      local passed failed
+      passed=$(jq '[.stories[] | select(.passes==true)] | length' "$RALPH_DIR/prd.json" 2>/dev/null || echo "0")
+      failed=$(jq '[.stories[] | select(.passes==false)] | length' "$RALPH_DIR/prd.json" 2>/dev/null || echo "0")
+      send_notification "🛑 Ralph stopped: $story failed $consecutive_failures times. $passed passed, $failed remaining"
+      print_progress_summary "$start_time" "$total_attempts" "0"
+      return 1
     fi
 
     # Show retry status (but don't make it scary - retrying is normal!)
     if [[ $consecutive_failures -gt 1 ]]; then
       if [[ $consecutive_failures -le 3 ]]; then
         print_info "Attempt $consecutive_failures for $story (normal - refining solution)"
-      elif [[ $consecutive_failures -le 8 ]]; then
-        print_warning "Attempt $consecutive_failures/$max_story_retries for $story"
       else
         print_warning "Attempt $consecutive_failures/$max_story_retries for $story (getting close to limit)"
       fi
@@ -494,6 +702,11 @@ run_loop() {
       update_json "$RALPH_DIR/prd.json" \
         --arg id "$story" '(.stories[] | select(.id==$id)) |= . + {passes: true, retryCount: 0}'
 
+      # Auto-promote sign if story required retries
+      if [[ $consecutive_failures -gt 1 && -f "$RALPH_DIR/last_failure.txt" ]]; then
+        _maybe_promote_sign "$story" "$consecutive_failures"
+      fi
+
       # Clear failure context on success
       rm -f "$RALPH_DIR/last_failure.txt"
       rm -f "$RALPH_DIR/last_verification.log"

package/ralph/prd.sh

@@ -158,10 +158,7 @@ ralph_prd() {
   printf '%s\n' "- Context for the next story" >> "$prompt_file"
   printf '\n%s\n' "## Context Rot Check" >> "$prompt_file"
   printf '\n%s\n' "Before finalizing, validate:" >> "$prompt_file"
-  printf '%s\n' "- If > 10 stories, recommend splitting into phases" >> "$prompt_file"
-  printf '%s\n' '- If complexity is "high" AND > 5 stories, MUST split' >> "$prompt_file"
   printf '%s\n' "- Each story should be completable in one Claude session (~10 min)" >> "$prompt_file"
-  printf '\n%s\n' "If splitting is needed, generate ONLY phase 1 and note deferred items." >> "$prompt_file"
   printf '\n%s\n' "## Context in Stories - IMPORTANT" >> "$prompt_file"
   printf '\n%s\n' "Each story must be self-contained. Include the idea file path in each story's 'contextFiles' array." >> "$prompt_file"
   printf '%s\n' "Include 'techStack' with the relevant subset of detected technologies for that story." >> "$prompt_file"

package/ralph/signs.sh

@@ -16,6 +16,8 @@ ralph_sign() {
 
   local pattern="$1"
   local category="${2:-general}"
+  local auto_promoted="${3:-false}"
+  local learned_from_override="${4:-}"
 
   # Ensure .ralph directory exists
   if [[ ! -d "$RALPH_DIR" ]]; then
@@ -34,8 +36,11 @@ ralph_sign() {
   local sign_id="sign-$(printf '%03d' $((sign_count + 1)))"
 
   # Get current story if available (for learnedFrom field)
+  # Override can be passed as 4th arg (used by auto-promote, since story is already marked passed)
   local learned_from=""
-  if [[ -f "$RALPH_DIR/prd.json" ]]; then
+  if [[ -n "$learned_from_override" ]]; then
+    learned_from="$learned_from_override"
+  elif [[ -f "$RALPH_DIR/prd.json" ]]; then
     learned_from=$(jq -r '.stories[] | select(.passes==false) | .id' "$RALPH_DIR/prd.json" 2>/dev/null | head -1)
   fi
 
@@ -52,11 +57,13 @@ ralph_sign() {
      --arg category "$category" \
      --arg learnedFrom "$learned_from" \
      --arg createdAt "$timestamp" \
+     --argjson autoPromoted "$( [[ "$auto_promoted" == "true" ]] && echo "true" || echo "false" )" \
      '.signs += [{
        id: $id,
        pattern: $pattern,
        category: $category,
        learnedFrom: (if $learnedFrom == "" then null else $learnedFrom end),
+       autoPromoted: $autoPromoted,
        createdAt: $createdAt
      }]' "$RALPH_DIR/signs.json" > "$tmpfile" && jq -e . "$tmpfile" >/dev/null 2>&1; then
     mv "$tmpfile" "$RALPH_DIR/signs.json"
@@ -100,7 +107,7 @@ ralph_signs() {
     [[ -z "$category" ]] && continue
 
     echo "[$category]"
-    jq -r --arg cat "$category" '.signs[] | select(.category==$cat) | "  - \(.pattern)"' "$RALPH_DIR/signs.json"
+    jq -r --arg cat "$category" '.signs[] | select(.category==$cat) | "  - \(.pattern)\(if .autoPromoted == true then " (auto)" else "" end)"' "$RALPH_DIR/signs.json"
     echo ""
   done <<< "$categories"
 }

package/ralph/utils.sh

@@ -10,6 +10,8 @@ readonly MAX_OUTPUT_PREVIEW_LINES=20
 readonly MAX_ERROR_PREVIEW_LINES=40
 readonly MAX_LINT_ERROR_LINES=20
 readonly MAX_PROGRESS_FILE_LINES=1000
+readonly MAX_SIGN_CONTEXT_LINES=150
+readonly MAX_SIGN_DEDUP_EXISTING=20
 
 # Constants - Timeouts (centralized to avoid magic numbers)
 readonly ITERATION_DELAY_SECONDS=0
@@ -19,6 +21,7 @@ readonly CODE_REVIEW_TIMEOUT_SECONDS=120
 readonly BROWSER_TIMEOUT_SECONDS=60
 readonly BROWSER_PAGE_TIMEOUT_MS=30000
 readonly CURL_TIMEOUT_SECONDS=10
+readonly SIGN_EXTRACTION_TIMEOUT_SECONDS=30
 
 # Common project directories (avoid duplication across files)
 readonly FRONTEND_DIRS=("apps/web" "frontend" "client" "web")
@@ -598,7 +601,9 @@ fix_hardcoded_paths() {
   local original_content="$prd_content"
 
   # Check for hardcoded absolute paths (non-portable)
-  if echo "$prd_content" | grep -qE '"/Users/|"/home/|"C:\\|"/var/|"/opt/' ; then
+  # Note: stderr suppressed on echo|grep -q pipes to silence "broken pipe" noise
+  # (grep -q exits early on match, closing the pipe while echo is still writing)
+  if echo "$prd_content" 2>/dev/null | grep -qE '"/Users/|"/home/|"C:\\|"/var/|"/opt/' ; then
     echo "  Removing hardcoded absolute paths..."
     # Remove common absolute path prefixes, keep relative path
     prd_content=$(echo "$prd_content" | sed -E 's|"/Users/[^"]*/([^"]+)"|"\1"|g')
@@ -607,7 +612,7 @@ fix_hardcoded_paths() {
   fi
 
   # Replace hardcoded backend URLs with {config.urls.backend}
-  if [[ -n "$backend_url" ]] && echo "$prd_content" | grep -qF "$backend_url" ; then
+  if [[ -n "$backend_url" ]] && echo "$prd_content" 2>/dev/null | grep -qF "$backend_url" ; then
     echo "  Replacing hardcoded backend URL with {config.urls.backend}..."
     local escaped_url
     escaped_url=$(_escape_sed_pattern "$backend_url")
@@ -616,7 +621,7 @@ fix_hardcoded_paths() {
   fi
 
   # Replace hardcoded frontend URLs with {config.urls.frontend}
-  if [[ -n "$frontend_url" ]] && echo "$prd_content" | grep -qF "$frontend_url" ; then
+  if [[ -n "$frontend_url" ]] && echo "$prd_content" 2>/dev/null | grep -qF "$frontend_url" ; then
     echo "  Replacing hardcoded frontend URL with {config.urls.frontend}..."
     local escaped_url
     escaped_url=$(_escape_sed_pattern "$frontend_url")
@@ -625,7 +630,7 @@ fix_hardcoded_paths() {
   fi
 
   # Replace hardcoded health endpoints with config placeholder
-  if echo "$prd_content" | grep -qE '/api(/v[0-9]+)?/health|/health' ; then
+  if echo "$prd_content" 2>/dev/null | grep -qE '/api(/v[0-9]+)?/health|/health' ; then
     echo "  Replacing hardcoded health endpoints with {config.api.healthEndpoint}..."
     prd_content=$(echo "$prd_content" | sed -E 's|/api/v[0-9]+/health|{config.api.healthEndpoint}|g')
     prd_content=$(echo "$prd_content" | sed -E 's|/api/health|{config.api.healthEndpoint}|g')
@@ -637,7 +642,7 @@ fix_hardcoded_paths() {
   # Note: Use # as delimiter since | appears in regex alternation
   if [[ -z "$backend_url" ]]; then
     # Common backend ports: 8000, 8001, 8080, 3001, 4000, 5000
-    if echo "$prd_content" | grep -qE 'http://localhost:(8000|8001|8080|3001|4000|5000)' ; then
+    if echo "$prd_content" 2>/dev/null | grep -qE 'http://localhost:(8000|8001|8080|3001|4000|5000)' ; then
       echo "  Replacing hardcoded localhost backend URLs with {config.urls.backend}..."
       prd_content=$(echo "$prd_content" | sed -E 's#http://localhost:(8000|8001|8080|3001|4000|5000)#{config.urls.backend}#g')
       modified=true
@@ -646,7 +651,7 @@ fix_hardcoded_paths() {
 
   if [[ -z "$frontend_url" ]]; then
     # Common frontend ports: 3000, 5173, 4200
-    if echo "$prd_content" | grep -qE 'http://localhost:(3000|5173|4200)' ; then
+    if echo "$prd_content" 2>/dev/null | grep -qE 'http://localhost:(3000|5173|4200)' ; then
       echo "  Replacing hardcoded localhost frontend URLs with {config.urls.frontend}..."
       prd_content=$(echo "$prd_content" | sed -E 's#http://localhost:(3000|5173|4200)#{config.urls.frontend}#g')
       modified=true