agentic-loop 3.17.0 → 3.17.2

package/package.json

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

package/ralph/code-check.sh

@@ -100,6 +100,7 @@ run_verification() {
   export RALPH_STORY_TYPE="$story_type"
 
   local failed=0
+  local failed_step=""
 
   # ========================================
   # STEP 1: Run lint checks
@@ -107,6 +108,7 @@ run_verification() {
   echo "  [1/5] Running lint checks..."
   if ! run_configured_checks "$story_type"; then
     failed=1
+    failed_step="lint"
   fi
 
   # ========================================
@@ -118,8 +120,10 @@ run_verification() {
     # First check that test files exist for new code
     if ! verify_test_files_exist; then
       failed=1
+      failed_step="test files missing"
     elif ! run_unit_tests; then
       failed=1
+      failed_step="unit tests"
     fi
   fi
 
@@ -131,6 +135,7 @@ run_verification() {
     echo "  [3/5] Running PRD test steps..."
     if ! verify_prd_criteria "$story"; then
       failed=1
+      failed_step="PRD test steps"
     fi
   fi
 
@@ -140,6 +145,7 @@ run_verification() {
   if [[ $failed -eq 0 ]]; then
     if ! run_api_smoke_test "$story"; then
       failed=1
+      failed_step="API smoke test"
     fi
   fi
 
@@ -149,6 +155,7 @@ run_verification() {
   if [[ $failed -eq 0 ]]; then
     if ! run_frontend_smoke_test "$story"; then
       failed=1
+      failed_step="frontend smoke test"
     fi
   fi
 
@@ -160,7 +167,7 @@ run_verification() {
     print_success "=== All verification passed ==="
     return 0
   else
-    print_error "=== Verification failed ==="
+    print_error "=== Verification failed at: $failed_step ==="
     save_failure_context "$story"
     return 1
   fi
@@ -194,8 +201,20 @@ save_failure_context() {
     echo ""
     echo "=== Attempt $attempt failed for $story ==="
     echo ""
+    # Include migration failure if present (verification may not have run)
+    if [[ -f "$RALPH_DIR/last_migration_failure.log" ]]; then
+      echo "--- Migration Error ---"
+      tail -30 "$RALPH_DIR/last_migration_failure.log"
+      echo ""
+    fi
+    # Include pre-commit failure if present
+    if [[ -f "$RALPH_DIR/last_precommit_failure.log" ]]; then
+      echo "--- Pre-commit Error ---"
+      tail -30 "$RALPH_DIR/last_precommit_failure.log"
+      echo ""
+    fi
+    # Include verification output (lint, tests, API, etc.)
     if [[ -f "$RALPH_DIR/last_verification.log" ]]; then
-      # Shorter excerpt per attempt since we're accumulating
       tail -50 "$RALPH_DIR/last_verification.log"
     fi
     echo ""

package/ralph/loop.sh

@@ -97,9 +97,74 @@ preflight_checks() {
       echo "Aborted. Fix the issues and try again."
       exit 1
     fi
+    return 1  # Had warnings — don't cache this result
   fi
 }
 
+# ============================================================================
+# PREFLIGHT / PRD CACHE
+# ============================================================================
+# Caches preflight and PRD validation results so restarts within 10 minutes
+# skip the slow connectivity checks and Claude auto-fix.
+# Cache is invalidated by TTL expiry or config/PRD file changes (by hash).
+
+_file_hash() {
+  [[ ! -f "$1" ]] && echo "no_file" && return
+  if command -v md5sum &>/dev/null; then
+    md5sum "$1" 2>/dev/null | cut -d' ' -f1
+  else
+    md5 -q "$1" 2>/dev/null
+  fi
+}
+
+_is_preflight_cached() {
+  local cache_file="$RALPH_DIR/.preflight_cache"
+  [[ ! -f "$cache_file" ]] && return 1
+
+  local cached_time cached_hash
+  read -r cached_time cached_hash < "$cache_file"
+
+  local now
+  now=$(date +%s)
+  [[ $(( now - cached_time )) -gt $PREFLIGHT_CACHE_TTL_SECONDS ]] && return 1
+
+  local config_hash
+  config_hash=$(_file_hash "$RALPH_DIR/config.json")
+  [[ "$cached_hash" != "$config_hash" ]] && return 1
+
+  return 0
+}
+
+_write_preflight_cache() {
+  local config_hash
+  config_hash=$(_file_hash "$RALPH_DIR/config.json")
+  echo "$(date +%s) $config_hash" > "$RALPH_DIR/.preflight_cache"
+}
+
+_is_prd_cached() {
+  local cache_file="$RALPH_DIR/.prd_validated"
+  [[ ! -f "$cache_file" ]] && return 1
+
+  local cached_time cached_hash
+  read -r cached_time cached_hash < "$cache_file"
+
+  local now
+  now=$(date +%s)
+  [[ $(( now - cached_time )) -gt $PREFLIGHT_CACHE_TTL_SECONDS ]] && return 1
+
+  local prd_hash
+  prd_hash=$(_file_hash "$RALPH_DIR/prd.json")
+  [[ "$cached_hash" != "$prd_hash" ]] && return 1
+
+  return 0
+}
+
+_write_prd_cache() {
+  local prd_hash
+  prd_hash=$(_file_hash "$RALPH_DIR/prd.json")
+  echo "$(date +%s) $prd_hash" > "$RALPH_DIR/.prd_validated"
+}
+
 # Check if failure context is trivial (lint/format-only retries)
 # Returns 0 (trivial) if ALL error lines match trivial patterns
 _is_trivial_failure() {
@@ -341,7 +406,15 @@ run_loop() {
   check_dependencies
 
   # Pre-loop checks to catch issues before wasting iterations
-  preflight_checks
+  if [[ "$fast_mode" == "true" ]]; then
+    print_info "Fast mode: skipping connectivity checks"
+  elif _is_preflight_cached; then
+    print_info "Pre-loop checks passed recently, skipping"
+  else
+    if preflight_checks; then
+      _write_preflight_cache
+    fi
+  fi
 
   if [[ ! -f "$RALPH_DIR/prd.json" ]]; then
     # Check for misplaced PRD in subdirectories
@@ -383,8 +456,17 @@ run_loop() {
   fi
 
   # Validate PRD structure
-  if ! validate_prd "$RALPH_DIR/prd.json"; then
-    return 1
+  if [[ "$fast_mode" == "true" ]]; then
+    print_info "Fast mode: structural PRD check only"
+    validate_prd "$RALPH_DIR/prd.json" "true" || return 1
+  elif _is_prd_cached; then
+    print_info "PRD validated recently, structural check only"
+    validate_prd "$RALPH_DIR/prd.json" "true" || return 1
+  else
+    if ! validate_prd "$RALPH_DIR/prd.json"; then
+      return 1
+    fi
+    _write_prd_cache
   fi
 
   local iteration=0
@@ -481,14 +563,15 @@ run_loop() {
     if [[ $consecutive_failures -gt $max_story_retries ]]; then
       print_error "Story $story has failed $consecutive_failures times - stopping loop"
       echo ""
-      echo "  This usually means:"
-      echo "    - Test steps are too vague or ambiguous"
-      echo "    - Missing prerequisites (DB setup, env vars, etc.)"
-      echo "    - Story scope is too large - consider breaking it up"
-      echo ""
-      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
+      # Show the actual last error instead of generic guesses
+      if [[ -f "$RALPH_DIR/last_failure.txt" ]]; then
+        echo "  Last failure:"
+        tail -20 "$RALPH_DIR/last_failure.txt" | sed 's/^/    /'
+      fi
+      echo ""
+      echo "  Full failure context saved to: $RALPH_DIR/failures/$story.txt"
       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")
@@ -632,18 +715,22 @@ run_loop() {
       break
     done
 
-    rm -f "$claude_output_log"
-
     if [[ $crash_attempt -ge $max_crash_retries ]]; then
       echo ""
       print_warning "Claude API unavailable after $max_crash_retries attempts"
+      if [[ -f "$claude_output_log" ]]; then
+        echo "  Last error:"
+        tail -5 "$claude_output_log" | sed 's/^/    /'
+      fi
       print_info "Waiting 60s before retrying... (Ctrl+C to stop, then 'npx agentic-loop run' to restart)"
       log_progress "$story" "CLI_CRASH" "API unavailable, waiting 60s before next iteration"
-      rm -f "$prompt_file"
+      rm -f "$prompt_file" "$claude_output_log"
       sleep 60  # Longer cooldown before retrying
       continue  # Continue main loop instead of stopping
     fi
 
+    rm -f "$claude_output_log"
+
     if [[ $claude_exit_code -ne 0 ]]; then
       ((consecutive_timeouts++))
       print_warning "Claude session ended (timeout or error) - timeout $consecutive_timeouts/$max_timeouts"
@@ -709,6 +796,8 @@ run_loop() {
 
       # Clear failure context on success
       rm -f "$RALPH_DIR/last_failure.txt"
+      rm -f "$RALPH_DIR"/last_*_failure.log
+      rm -f "$RALPH_DIR"/last_*_check.log
       rm -f "$RALPH_DIR/last_verification.log"
 
       # Get story title for commit message and completion display

package/ralph/prd-check.sh

@@ -102,6 +102,7 @@
 # Returns 0 if valid (possibly after auto-fix), 1 if unrecoverable error
 validate_prd() {
   local prd_file="$1"
+  local dry_run="${2:-false}"
 
   # Check file exists
   if [[ ! -f "$prd_file" ]]; then
@@ -219,15 +220,17 @@ validate_prd() {
     echo ""
   fi
 
-  # Validate API smoke test configuration
-  _validate_api_config "$config"
+  # Validate API smoke test configuration (skip in fast/cached mode)
+  if [[ "$dry_run" != "true" ]]; then
+    _validate_api_config "$config"
+  fi
 
   # Replace hardcoded paths with config placeholders
   fix_hardcoded_paths "$prd_file" "$config"
 
   # Validate and fix individual stories
-  # $2 is optional dry_run flag — when "true", skip auto-fix
-  _validate_and_fix_stories "$prd_file" "${2:-}" || return 1
+  # dry_run flag — when "true", skip auto-fix
+  _validate_and_fix_stories "$prd_file" "$dry_run" || return 1
 
   return 0
 }
@@ -323,6 +326,7 @@ _validate_and_fix_stories() {
   local cnt_frontend_tsc=0 cnt_frontend_url=0 cnt_frontend_context=0 cnt_frontend_mcp=0
   local cnt_auth_security=0 cnt_list_pagination=0 cnt_prose_steps=0
   local cnt_migration_prereq=0 cnt_naming_convention=0 cnt_bare_pytest=0
+  local cnt_server_only=0
   local cnt_custom=0
 
   echo "  Checking test coverage..."
@@ -471,6 +475,32 @@ _validate_and_fix_stories() {
       fi
     fi
 
+    # Check 9: Stories where ALL testSteps depend on a live server
+    # If every testStep is a curl/wget/httpie command and none are offline
+    # (npm test, pytest, tsc, playwright, cargo test, go test, etc.),
+    # the story will always fail without a running server.
+    if [[ -n "$test_steps" ]]; then
+      local has_offline_step=false
+      local has_server_step=false
+      local step_list
+      step_list=$(jq -r --arg id "$story_id" \
+        '.stories[] | select(.id==$id) | .testSteps[]?' "$prd_file")
+
+      while IFS= read -r single_step; do
+        [[ -z "$single_step" ]] && continue
+        if echo "$single_step" | grep -qE "^(curl |wget |http )"; then
+          has_server_step=true
+        else
+          has_offline_step=true
+        fi
+      done <<< "$step_list"
+
+      if [[ "$has_server_step" == "true" && "$has_offline_step" == "false" ]]; then
+        story_issues+="all testSteps need a live server (add offline test: npm test, tsc --noEmit, pytest), "
+        cnt_server_only=$((cnt_server_only + 1))
+      fi
+    fi
+
     # Snapshot built-in issues before custom checks append
     local builtin_story_issues="$story_issues"
 
@@ -517,6 +547,7 @@ _validate_and_fix_stories() {
     [[ $cnt_migration_prereq -gt 0 ]] && echo "    ${cnt_migration_prereq}x migration: add prerequisites (DB reset)"
     [[ $cnt_naming_convention -gt 0 ]] && echo "    ${cnt_naming_convention}x API consumer: add camelCase transformation note"
     [[ $cnt_bare_pytest -gt 0 ]] && echo "    ${cnt_bare_pytest}x use 'uv run pytest' not bare 'pytest'"
+    [[ $cnt_server_only -gt 0 ]] && echo "    ${cnt_server_only}x all testSteps need live server (add offline fallback)"
     [[ $cnt_custom -gt 0 ]] && echo "    ${cnt_custom} stories with custom check issues"
 
     # Skip auto-fix in dry-run mode
@@ -630,6 +661,10 @@ RULES:
    Example: \"notes\": \"Transform API responses from snake_case to camelCase. Create typed interfaces with camelCase properties and map: const user = { userName: data.user_name }\"
 10. Each story should include its own techStack and constraints fields. Do NOT add these at the PRD root level.
     Move any root-level techStack, globalConstraints, originalContext, testing, architecture, or testUsers into the relevant stories.
+11. Stories where ALL testSteps are curl commands MUST also include at least one offline test step
+    that can verify code correctness without a running server.
+    Examples: \"npm test\", \"npx tsc --noEmit\", \"pytest tests/unit/\", \"go test ./...\"
+    This prevents wasted retries when the server isn't running.
 
 CURRENT PRD:
 $(cat "$prd_file")
@@ -788,6 +823,24 @@ validate_stories_quick() {
         fi
       fi
     fi
+
+    # Check 8: All testSteps are server-dependent
+    if [[ -n "$test_steps" ]]; then
+      local has_offline=false has_server=false
+      local steps
+      steps=$(jq -r --arg id "$story_id" \
+        '.stories[] | select(.id==$id) | .testSteps[]?' "$prd_file")
+      while IFS= read -r s; do
+        [[ -z "$s" ]] && continue
+        if echo "$s" | grep -qE "^(curl |wget |http )"; then
+          has_server=true
+        else
+          has_offline=true
+        fi
+      done <<< "$steps"
+      [[ "$has_server" == "true" && "$has_offline" == "false" ]] && \
+        issues+="$story_id: all testSteps need live server, "
+    fi
   done <<< "$story_ids"
 
   echo "$issues"

package/ralph/test.sh

@@ -134,11 +134,15 @@ run_all_prd_tests() {
       [[ -z "$step" ]] && continue
       ((total++))
 
-      echo -n "  $step... "
+      # Expand config placeholders (e.g., {config.urls.backend})
+      local expanded_step
+      expanded_step=$(_expand_config_vars "$step")
+
+      echo -n "  $expanded_step... "
 
       local step_log
       step_log=$(mktemp)
-      if safe_exec "$step" "$step_log"; then
+      if safe_exec "$expanded_step" "$step_log"; then
         print_success "passed"
         ((passed++))
       else

package/ralph/utils.sh

@@ -22,6 +22,7 @@ readonly BROWSER_TIMEOUT_SECONDS=60
 readonly BROWSER_PAGE_TIMEOUT_MS=30000
 readonly CURL_TIMEOUT_SECONDS=10
 readonly SIGN_EXTRACTION_TIMEOUT_SECONDS=30
+readonly PREFLIGHT_CACHE_TTL_SECONDS=600
 
 # Common project directories (avoid duplication across files)
 readonly FRONTEND_DIRS=("apps/web" "frontend" "client" "web")

package/ralph/verify/tests.sh

@@ -226,8 +226,11 @@ run_unit_tests() {
 }
 
 # Expand config placeholders in a string
-# Usage: expand_config_vars "curl {config.urls.backend}/api"
-# Expands: {config.urls.backend}, {config.urls.frontend}, {config.directories.*}
+# Usage: _expand_config_vars "curl {config.urls.backend}/api"
+# Expands any {config.X.Y} placeholder from .ralph/config.json via jq.
+# Known placeholders have fallback paths for backward compatibility:
+#   {config.urls.backend}  -> .urls.backend // .api.baseUrl
+#   {config.urls.frontend} -> .urls.frontend // .testUrlBase
 _expand_config_vars() {
   local input="$1"
   local config="$RALPH_DIR/config.json"
@@ -237,41 +240,38 @@ _expand_config_vars() {
 
   local result="$input"
 
-  # Expand {config.urls.backend}
+  # Known placeholders with backward-compatible fallback paths
   if [[ "$result" == *"{config.urls.backend}"* ]]; then
-    local backend_url
-    backend_url=$(jq -r '.urls.backend // .api.baseUrl // empty' "$config" 2>/dev/null)
-    if [[ -n "$backend_url" ]]; then
-      result="${result//\{config.urls.backend\}/$backend_url}"
-    fi
+    local val
+    val=$(jq -r '.urls.backend // .api.baseUrl // empty' "$config" 2>/dev/null)
+    [[ -n "$val" ]] && result="${result//\{config.urls.backend\}/$val}"
   fi
 
-  # Expand {config.urls.frontend}
   if [[ "$result" == *"{config.urls.frontend}"* ]]; then
-    local frontend_url
-    frontend_url=$(jq -r '.urls.frontend // .testUrlBase // empty' "$config" 2>/dev/null)
-    if [[ -n "$frontend_url" ]]; then
-      result="${result//\{config.urls.frontend\}/$frontend_url}"
-    fi
-  fi
-
-  # Expand {config.directories.backend}
-  if [[ "$result" == *"{config.directories.backend}"* ]]; then
-    local backend_dir
-    backend_dir=$(jq -r '.directories.backend // empty' "$config" 2>/dev/null)
-    if [[ -n "$backend_dir" ]]; then
-      result="${result//\{config.directories.backend\}/$backend_dir}"
-    fi
+    local val
+    val=$(jq -r '.urls.frontend // .testUrlBase // empty' "$config" 2>/dev/null)
+    [[ -n "$val" ]] && result="${result//\{config.urls.frontend\}/$val}"
   fi
 
-  # Expand {config.directories.frontend}
-  if [[ "$result" == *"{config.directories.frontend}"* ]]; then
-    local frontend_dir
-    frontend_dir=$(jq -r '.directories.frontend // empty' "$config" 2>/dev/null)
-    if [[ -n "$frontend_dir" ]]; then
-      result="${result//\{config.directories.frontend\}/$frontend_dir}"
+  # Generic expansion for any remaining {config.X.Y.Z} placeholders
+  # Handles {config.urls.app}, {config.api.healthEndpoint}, {config.directories.*}, etc.
+  local max_expansions=10
+  while [[ "$result" =~ \{config\.([a-zA-Z0-9_.]+)\} ]] && [[ $max_expansions -gt 0 ]]; do
+    local placeholder="${BASH_REMATCH[0]}"
+    local config_path="${BASH_REMATCH[1]}"
+    local jq_path=".${config_path}"
+
+    local val
+    val=$(jq -r "$jq_path // empty" "$config" 2>/dev/null)
+    if [[ -n "$val" ]]; then
+      result="${result//$placeholder/$val}"
+    else
+      # Unresolvable — warn and stop to avoid infinite loop
+      print_warning "Unresolved config placeholder: $placeholder (key '$config_path' not in config.json)" >&2
+      break
     fi
-  fi
+    ((max_expansions--))
+  done
 
   echo "$result"
 }