agentic-loop 3.16.3 → 3.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-loop",
-  "version": "3.16.3",
+  "version": "3.17.1",
   "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

@@ -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,14 +90,287 @@ 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
       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() {
+  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() {
@@ -128,8 +405,16 @@ run_loop() {
   # Validate prerequisites
   check_dependencies
 
-  # Pre-flight checks to catch issues before wasting iterations
-  preflight_checks
+  # Pre-loop checks to catch issues before wasting iterations
+  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
@@ -171,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
@@ -181,9 +475,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,35 +558,32 @@ 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"
-      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
-      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
+      # 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")
+      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
@@ -424,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"
@@ -494,8 +789,15 @@ 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_*_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/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/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

@@ -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,8 @@ 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
+readonly PREFLIGHT_CACHE_TTL_SECONDS=600
 
 # Common project directories (avoid duplication across files)
 readonly FRONTEND_DIRS=("apps/web" "frontend" "client" "web")
@@ -598,7 +602,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 +613,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 +622,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 +631,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 +643,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 +652,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

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"
 }