agentic-loop 3.11.0 → 3.12.0

package/README.md

@@ -4,28 +4,51 @@
 
 You describe what you want to build. Claude Code writes a PRD (Product Requirements Document) with small, testable stories. Ralph executes each story automatically - coding, testing, and committing in a loop until everything passes.
 
-> **Optimized for:** Python, TypeScript, React, Go/Hugo, FastMCP, and Docker projects.
-
 ---
 
-## What It Does
+## What It Does and How to work with Agentic Loop
 
-**Brainstorm ideas with `/idea`**
-Describe a feature in plain English. Claude asks clarifying questions, explores your codebase, and generates a PRD with atomic stories that can be implemented one at a time.
+### The Two-Terminal Workflow
 
-**Execute with Ralph**
-Ralph reads the PRD and implements each story autonomously. It spawns Claude, runs verification (lint, tests, browser checks), and either commits on success or retries with error context on failure.
+```
+┌──────────────────────────────────────────────────────────────────────────────────┐
+│  TERMINAL 1: Claude CLI                │  TERMINAL 2: Execute                    │
+├────────────────────────────────────────┼─────────────────────────────────────────┤
+│                                        │                                         │
+│  claude --dangerously-skip-permissions │  npx agentic-loop run                   │
+│                                        │                                         │
+│  PLAN FEATURES                         │  ┌─ prd-check (once) ───────────────┐   │
+│  /idea 'your feature or bugfix'        │  │ Validate all stories upfront     │   │
+│  → Claude asks questions               │  │ Auto-fix missing test steps      │   │
+│  → Explores codebase                   │  └──────────────────────────────────┘   │
+│  → Generates PRD                       │            ↓                            │
+│                                        │  ┌─ loop (per story) ───────────────┐   │
+│  ENHANCE AS YOU LEARN                  │  │                                  │   │
+│  → Add signs when Ralph repeats        │  │ Read prd.json → get next story   │   │
+│    the same mistake                    │  │ Load signs.json, config.json     │   │
+│  → Tune timeouts, retries, checks      │  │ Load last_failure.txt (if retry) │   │
+│  → Refine test commands for your       │  │ Build prompt with full context   │   │
+│    stack                               │  │ Spawn Claude → write code        │   │
+│                                        │  │                                  │   │
+│  (OPTIONAL) CUSTOMIZE YOUR LOOP        │  │ code-check:                      │   │
+│  /my-dna      → your coding style      │  │   [1] Lint                       │   │
+│  /styleguide  → UI consistency         │  │   [2] Tests                      │   │
+│  /sign        → teach patterns         │  │   [3] PRD test steps             │   │
+│  config.json  → tune your setup        │  │   [4] API smoke                  │   │
+│                                        │  │   [5] Frontend smoke             │   │
+│                                        │  │                                  │   │
+│                                        │  │ Pass → commit, next story        │   │
+│                                        │  │ Fail → save to last_failure.txt, │   │
+│                                        │  │        retry                     │   │
+│                                        │  └──────────────────────────────────┘   │
+│                                        │                                         │
+└────────────────────────────────────────┴─────────────────────────────────────────┘
+```
 
-**Customize your output**
-- `/my-dna` - Add your voice and values so the code reflects your style
-- `/styleguide` - Generate a UI component reference for consistent design
+**Terminal 1** is where you shape *what* gets built and *how* Ralph builds it.
+**Terminal 2** is where Ralph executes autonomously.
 
-**Built-in guardrails**
-- `/vibe-check`, `/review` - On-demand quality and security checks
-- Pre-commit hooks - Block secrets, hardcoded URLs, debug statements
-- Claude Code hooks - Real-time warnings while coding
-- GitHub Actions CI/CD - Fast PR checks + comprehensive nightly tests
-- Test file enforcement - Fails if new code lacks corresponding tests
+Your loop gets smarter over time. When Ralph struggles with something, add a sign. When tests flake, tune the config. The customization never really stops—it's how you make Ralph work for *your* project.
 
 ---
 
@@ -54,34 +77,13 @@ npx agentic-loop run         # Execute PRDs autonomously
 
 ---
 
-## How Ralph Works
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        RALPH LOOP                           │
-├─────────────────────────────────────────────────────────────┤
-│  1. Read prd.json → find next story where passes=false      │
-│  2. Build prompt (story + context + failures + signs)       │
-│  3. Spawn Claude with prompt + MCP browser tools            │
-│  4. Run verification (lint, tests, testSteps)               │
-│  5. Pass? → commit, next story                              │
-│     Fail? → save error, retry with failure context          │
-│  6. Repeat until all stories pass                           │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**What's a PRD?**
-A JSON file (`.ralph/prd.json`) containing your feature broken into small stories. Each story has acceptance criteria, test steps, and a test URL. Ralph implements them one by one. See [`templates/prd-example.json`](templates/prd-example.json) for a complete example.
-
-**What are Signs?**
-Patterns Ralph learns from failures. If Ralph keeps making the same mistake, add a sign: `npx agentic-loop sign "Always use camelCase for API fields" backend`. Future stories will see this guidance.
-
----
-
 ## Docs
 
-- [How Ralph Works](docs/RALPH.md) - Architecture, config, verification pipeline
-- [Technical Architecture](docs/ARCHITECTURE.md) - Deep dive for developers
+- **[Beginners Guide](docs/BEGINNERS.md)** - New to this? Start here (no coding experience required)
+- [PRD Check](docs/PRD-CHECK.md) - Story validation before coding starts
+- [Code Check](docs/CODE-CHECK.md) - Verification pipeline after each story
+- [Customization](docs/CUSTOMIZATION.md) - Personalization and guardrails
+- [How Ralph Works](docs/RALPH.md) - Architecture, config, full reference
 - [Cheatsheet](docs/CHEATSHEET.md) - All commands at a glance
 - [Hooks Reference](docs/HOOKS.md) - Pre-commit and Claude Code hooks
 - [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and fixes

package/dist/checks/check-snake-case-ts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-snake-case-ts.d.ts","sourceRoot":"","sources":["../../src/checks/check-snake-case-ts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,IAAI,EAA2B,MAAM,mBAAmB,CAAC;AAEvE,eAAO,MAAM,gBAAgB,EAAE,IAmF9B,CAAC"}
+{"version":3,"file":"check-snake-case-ts.d.ts","sourceRoot":"","sources":["../../src/checks/check-snake-case-ts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,IAAI,EAA2B,MAAM,mBAAmB,CAAC;AAEvE,eAAO,MAAM,gBAAgB,EAAE,IAmH9B,CAAC"}

package/dist/checks/check-snake-case-ts.js

@@ -68,6 +68,34 @@ export const checkSnakeCaseTs = {
                     }
                 }
             }
+            // Check for snake_case property access (e.g., data.user_name, data?.user_name)
+            // This catches direct usage of snake_case from API responses without transformation
+            // Supports both regular (.) and optional chaining (?.) access
+            const propertyAccessRegex = /(\?)?\.([a-z][a-z0-9]*(?:_[a-z0-9]+)+)(?:\s*[,;)\]}]|\s*$|\s*\.|\s*\?\.|\s*!\.|\s*&&|\s*\|\||\s*\?|\s*:|\s*===|\s*!==|\s*==|\s*!=)/g;
+            let accessMatch;
+            while ((accessMatch = propertyAccessRegex.exec(line)) !== null) {
+                const isOptionalChain = accessMatch[1] === '?';
+                const propName = accessMatch[2];
+                const suggestedName = toCamelCase(propName);
+                const accessor = isOptionalChain ? '?.' : '.';
+                // Skip if it's in a comment
+                const beforeMatch = line.substring(0, accessMatch.index);
+                if (beforeMatch.includes('//') || beforeMatch.includes('/*')) {
+                    continue;
+                }
+                // Skip common exceptions (CSS properties, external library patterns)
+                if (['line_number', 'column_number', 'stack_trace'].includes(propName)) {
+                    continue;
+                }
+                results.push({
+                    line: lineNum,
+                    column: accessMatch.index + 1,
+                    message: `Property access "${accessor}${propName}" uses snake_case - transform API response to camelCase "${accessor}${suggestedName}"`,
+                    severity: 'warning',
+                    ruleId: 'snake-case/access',
+                    fix: suggestedName,
+                });
+            }
         }
         return results;
     },

package/dist/checks/check-snake-case-ts.js.map

@@ -1 +1 @@
-{"version":3,"file":"check-snake-case-ts.js","sourceRoot":"","sources":["../../src/checks/check-snake-case-ts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"check-snake-case-ts.js","sourceRoot":"","sources":["../../src/checks/check-snake-case-ts.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/ralph/init.sh

@@ -379,6 +379,30 @@ auto_configure_project() {
       echo "  Auto-detected api.baseUrl: $api_url"
       updated=true
     fi
+
+    # 4b. Detect api.healthEndpoint - probe common endpoints if server is running
+    if ! jq -e '.api.healthEndpoint' "$tmpfile" >/dev/null 2>&1 || [[ "$(jq -r '.api.healthEndpoint' "$tmpfile")" == "null" ]]; then
+      if command -v curl &>/dev/null; then
+        local health_endpoint=""
+        # Common health endpoint paths to try (most specific first)
+        local health_paths=("/api/v1/health" "/api/health" "/health" "/healthz" "/api/v1/healthz" "/status" "/")
+
+        for path in "${health_paths[@]}"; do
+          local http_code
+          http_code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 2 "${api_url}${path}" 2>/dev/null) || http_code="000"
+          if [[ "$http_code" =~ ^[23] ]]; then
+            health_endpoint="$path"
+            break
+          fi
+        done
+
+        if [[ -n "$health_endpoint" ]]; then
+          jq --arg ep "$health_endpoint" '.api.healthEndpoint = $ep' "$tmpfile" > "${tmpfile}.new" && mv "${tmpfile}.new" "$tmpfile"
+          echo "  Auto-detected api.healthEndpoint: $health_endpoint"
+          updated=true
+        fi
+      fi
+    fi
   fi
 
   # 5. Detect package manager

package/ralph/loop.sh

@@ -223,6 +223,21 @@ run_loop() {
     fi
 
     if [[ -z "$story" ]]; then
+      # Safety check: verify PRD is valid before claiming all stories passed
+      # An empty/corrupt PRD would also result in no stories found
+      local total_stories
+      total_stories=$(jq '.stories | length' "$RALPH_DIR/prd.json" 2>/dev/null || echo "0")
+      if [[ "$total_stories" == "0" || "$total_stories" == "null" ]]; then
+        print_error "PRD appears to be empty or corrupted!"
+        echo ""
+        echo "  The prd.json file has no stories. This usually means:"
+        echo "    - The file was accidentally cleared"
+        echo "    - A write operation failed"
+        echo ""
+        echo "  Check for backups: ls -la $RALPH_DIR/*.bak"
+        echo "  Or restore from git: git checkout $RALPH_DIR/prd.json"
+        return 1
+      fi
       print_progress_summary "$start_time" "$total_attempts" "${#skipped_stories[@]}"
       send_notification "✅ Ralph finished: All stories passed!"
       archive_feature

package/ralph/prd-check.sh

@@ -50,6 +50,11 @@
 #     - Has prerequisites array with DB reset command
 #     - Prevents infinite retries on schema mismatch errors
 #
+# API configuration validation:
+#   - If api.baseUrl configured, checks health endpoint is reachable
+#   - Warns if default /health returns 404 (misconfigured healthEndpoint)
+#   - Catches endpoint mismatches before loop starts
+#
 # ============================================================================
 # AUTO-FIX
 # ============================================================================
@@ -68,6 +73,8 @@
 #
 #   .checks.requireTests  - Warn if no test directory configured
 #   .tests.directory      - Where tests live (for requireTests check)
+#   .api.baseUrl          - API base URL (enables API config validation)
+#   .api.healthEndpoint   - Health check path (default: /health, empty to disable)
 #
 # ============================================================================
 # USAGE
@@ -177,6 +184,9 @@ validate_prd() {
     fi
   fi
 
+  # Validate API smoke test configuration
+  _validate_api_config "$config"
+
   # Replace hardcoded paths with config placeholders
   fix_hardcoded_paths "$prd_file" "$config"
 
@@ -190,6 +200,79 @@ validate_prd() {
 # INTERNAL FUNCTIONS
 # ============================================================================
 
+# Validate API smoke test configuration
+# Checks that configured health endpoint is reachable (warns if not)
+_validate_api_config() {
+  local config="$1"
+
+  [[ ! -f "$config" ]] && return 0
+
+  local base_url
+  base_url=$(jq -r '.api.baseUrl // empty' "$config" 2>/dev/null)
+
+  # No API configured, skip
+  [[ -z "$base_url" ]] && return 0
+
+  echo "  Validating API configuration..."
+
+  local health_endpoint
+  local health_endpoint_raw
+  health_endpoint_raw=$(jq -r '.api.healthEndpoint' "$config" 2>/dev/null)
+
+  # If explicitly set to empty string, disable health check
+  if [[ "$health_endpoint_raw" == "" ]]; then
+    print_info "Health check disabled (healthEndpoint is empty)"
+    return 0
+  fi
+
+  # If not configured at all (null), warn about the default
+  if [[ "$health_endpoint_raw" == "null" ]]; then
+    echo ""
+    print_warning "No api.healthEndpoint configured - defaulting to /health"
+    echo "  If your API uses a different health endpoint, add to .ralph/config.json:"
+    echo "    {\"api\": {\"baseUrl\": \"$base_url\", \"healthEndpoint\": \"/your/health/path\"}}"
+    echo ""
+    health_endpoint="/health"
+  else
+    health_endpoint="$health_endpoint_raw"
+  fi
+
+  # Test the health endpoint
+  local url="${base_url}${health_endpoint}"
+  local http_code
+
+  http_code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 "$url" 2>/dev/null) || http_code="000"
+
+  if [[ "$http_code" == "000" ]]; then
+    print_warning "API not reachable at $base_url (server may not be running yet)"
+    return 0
+  elif [[ "$http_code" == "404" ]]; then
+    echo ""
+    print_error "API health endpoint not found: $health_endpoint (HTTP 404)"
+    echo ""
+    echo "  The configured health endpoint doesn't exist at: $url"
+    echo ""
+    echo "  Fix in .ralph/config.json:"
+    echo "    {\"api\": {\"baseUrl\": \"$base_url\", \"healthEndpoint\": \"/correct/path\"}}"
+    echo ""
+    echo "  Common health endpoints:"
+    echo "    /api/health, /api/v1/health, /healthz, /status, /"
+    echo ""
+    echo "  Set to empty string to disable health check:"
+    echo "    {\"api\": {\"healthEndpoint\": \"\"}}"
+    echo ""
+    # Don't fail - API tests will fail later with more context
+    return 0
+  elif [[ "$http_code" =~ ^5 ]]; then
+    print_warning "API health check returned error: HTTP $http_code"
+    return 0
+  else
+    print_success "API health check passed: $health_endpoint (HTTP $http_code)"
+  fi
+
+  return 0
+}
+
 # Validate individual stories and auto-fix with Claude if needed
 _validate_and_fix_stories() {
   local prd_file="$1"
@@ -201,7 +284,7 @@ _validate_and_fix_stories() {
   local cnt_no_tests=0 cnt_backend_curl=0 cnt_backend_contract=0
   local cnt_frontend_tsc=0 cnt_frontend_url=0 cnt_frontend_context=0
   local cnt_auth_security=0 cnt_list_pagination=0 cnt_prose_steps=0
-  local cnt_migration_prereq=0
+  local cnt_migration_prereq=0 cnt_naming_convention=0
 
   echo "  Checking test coverage..."
 
@@ -311,6 +394,21 @@ _validate_and_fix_stories() {
       fi
     fi
 
+    # Check 7: Frontend stories consuming APIs need naming convention notes
+    # If story is frontend/general AND mentions API/fetch/axios, ensure notes include camelCase guidance
+    if [[ "$story_type" == "frontend" || "$story_type" == "general" ]]; then
+      local story_desc
+      story_desc=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | (.title + " " + (.acceptanceCriteria // [] | join(" ")) + " " + (.notes // ""))' "$prd_file")
+      if echo "$story_desc" | grep -qiE "(api|fetch|axios|endpoint|backend|response)"; then
+        local story_notes
+        story_notes=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .notes // ""' "$prd_file")
+        if ! echo "$story_notes" | grep -qiE "(camelCase|snake_case|naming)"; then
+          story_issues+="API consumer needs camelCase transformation note, "
+          cnt_naming_convention=$((cnt_naming_convention + 1))
+        fi
+      fi
+    fi
+
     # Track this story if it has issues
     if [[ -n "$story_issues" ]]; then
       needs_fix=true
@@ -335,6 +433,7 @@ _validate_and_fix_stories() {
     [[ $cnt_auth_security -gt 0 ]] && echo "    ${cnt_auth_security}x auth: add security criteria"
     [[ $cnt_list_pagination -gt 0 ]] && echo "    ${cnt_list_pagination}x list: add pagination"
     [[ $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"
 
     # Check if Claude is available for auto-fix
     if command -v claude &>/dev/null; then
@@ -375,6 +474,8 @@ RULES:
    - Accepts ?page=N&limit=N query params
 7. Migration stories (creating alembic/versions, migrations/, or modifying models) MUST have prerequisites:
    Example: \"prerequisites\": [{\"name\": \"Reset test DB\", \"command\": \"npm run db:reset:test\", \"when\": \"schema changes\"}]
+8. Frontend/general stories that consume APIs MUST have notes about naming conventions:
+   Example: \"notes\": \"Transform API responses from snake_case to camelCase. Create typed interfaces with camelCase properties and map: const user = { userName: data.user_name }\"
 
 CURRENT PRD:
 $(cat "$prd_file")
@@ -394,11 +495,34 @@ Output ONLY the fixed JSON, no explanation. Start with { and end with }."
     fixed_prd=$(echo "$raw_response" | sed 's/^```json//; s/^```//; s/```$//')
   fi
 
+  # Create backup BEFORE any validation/write attempts
+  local backup_file="${prd_file}.$(date +%Y%m%d-%H%M%S).bak"
+  cp "$prd_file" "$backup_file"
+
+  # Get original story count for validation
+  local orig_story_count
+  orig_story_count=$(jq '.stories | length' "$prd_file" 2>/dev/null || echo "0")
+
   # Validate the response is valid JSON with required structure
   if echo "$fixed_prd" | jq -e '.stories' >/dev/null 2>&1; then
-    # Timestamped backup (preserves history across multiple fixes)
-    local backup_file="${prd_file}.$(date +%Y%m%d-%H%M%S).bak"
-    cp "$prd_file" "$backup_file"
+    # Critical: Check story count is preserved (not just that .stories exists)
+    local new_story_count
+    new_story_count=$(echo "$fixed_prd" | jq '.stories | length' 2>/dev/null || echo "0")
+    if [[ "$new_story_count" -lt "$orig_story_count" ]]; then
+      print_warning "Fixed PRD has fewer stories ($orig_story_count -> $new_story_count) - keeping original"
+      echo "  Backup preserved at: $backup_file"
+      return 0
+    fi
+
+    # Safety check: ensure we're not writing drastically smaller content
+    local orig_size new_size
+    orig_size=$(wc -c < "$prd_file" | tr -d ' ')
+    new_size=${#fixed_prd}
+    if [[ $new_size -lt $((orig_size / 3)) ]]; then
+      print_warning "Fixed PRD seems too small ($orig_size -> $new_size bytes) - keeping original"
+      echo "  Backup preserved at: $backup_file"
+      return 0
+    fi
 
     # Write fixed PRD
     echo "$fixed_prd" > "$prd_file"
@@ -412,6 +536,7 @@ Output ONLY the fixed JSON, no explanation. Start with { and end with }."
     fi
   else
     print_warning "Could not auto-optimize - continuing with current PRD"
+    echo "  Backup preserved at: $backup_file"
     return 0  # Don't fail, just continue
   fi
 }
@@ -492,6 +617,19 @@ validate_stories_quick() {
         issues+="$story_id: migration needs prerequisites, "
       fi
     fi
+
+    # Check 7: Frontend/general stories consuming APIs need naming convention notes
+    if [[ "$story_type" == "frontend" || "$story_type" == "general" ]]; then
+      local story_desc
+      story_desc=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | (.title + " " + (.acceptanceCriteria // [] | join(" ")) + " " + (.notes // ""))' "$prd_file")
+      if echo "$story_desc" | grep -qiE "(api|fetch|axios|endpoint|backend|response)"; then
+        local story_notes
+        story_notes=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .notes // ""' "$prd_file")
+        if ! echo "$story_notes" | grep -qiE "(camelCase|snake_case|naming)"; then
+          issues+="$story_id: needs camelCase transformation note, "
+        fi
+      fi
+    fi
   done <<< "$story_ids"
 
   echo "$issues"

package/ralph/prd.sh

@@ -265,13 +265,20 @@ ralph_prd_accept() {
   # - Ensure all stories have passes: false
   # - Ensure all stories have id and title
   # - Set status to pending
-  prd_json=$(echo "$prd_json" | jq '
+  local normalized_json
+  normalized_json=$(echo "$prd_json" | jq '
     .feature.status = "pending" |
     .stories = [.stories[] | . + {passes: (.passes // false)}]
   ')
 
+  # Safety check: don't save if normalization failed
+  if [[ -z "$normalized_json" ]] || ! echo "$normalized_json" | jq -e '.stories' >/dev/null 2>&1; then
+    print_error "PRD normalization failed - saving original JSON instead"
+    normalized_json="$prd_json"
+  fi
+
   # Save
-  echo "$prd_json" > "$RALPH_DIR/prd.json"
+  echo "$normalized_json" > "$RALPH_DIR/prd.json"
 
   # Run full validation
   if ! validate_prd "$RALPH_DIR/prd.json"; then

package/ralph/utils.sh

@@ -429,6 +429,12 @@ send_notification() {
   return 0
 }
 
+# Escape special regex characters in a string for use in sed
+# Usage: escaped=$(escape_sed_pattern "http://localhost:8000")
+_escape_sed_pattern() {
+  printf '%s' "$1" | sed 's/[.[\/*^$()+?{|]/\\&/g'
+}
+
 # Replace hardcoded paths/URLs with config placeholders
 # Makes PRDs portable across machines and environments
 fix_hardcoded_paths() {
@@ -440,6 +446,11 @@ fix_hardcoded_paths() {
   local prd_content
   prd_content=$(cat "$prd_file")
 
+  # Safety check - don't proceed if file is empty
+  if [[ -z "$prd_content" ]]; then
+    return 0
+  fi
+
   # Get URLs from config (if available)
   local backend_url="" frontend_url=""
   if [[ -f "$config_file" ]]; then
@@ -447,6 +458,9 @@ fix_hardcoded_paths() {
     frontend_url=$(jq -r '.urls.frontend // .playwright.baseUrl // empty' "$config_file" 2>/dev/null)
   fi
 
+  # Store original for safety check
+  local original_content="$prd_content"
+
   # Check for hardcoded absolute paths (non-portable)
   if echo "$prd_content" | grep -qE '"/Users/|"/home/|"C:\\|"/var/|"/opt/' ; then
     echo "  Removing hardcoded absolute paths..."
@@ -457,16 +471,20 @@ 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" | grep -qF "$backend_url" ; then
     echo "  Replacing hardcoded backend URL with {config.urls.backend}..."
-    prd_content=$(echo "$prd_content" | sed "s|$backend_url|{config.urls.backend}|g")
+    local escaped_url
+    escaped_url=$(_escape_sed_pattern "$backend_url")
+    prd_content=$(echo "$prd_content" | sed "s|$escaped_url|{config.urls.backend}|g")
     modified=true
   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" | grep -qF "$frontend_url" ; then
     echo "  Replacing hardcoded frontend URL with {config.urls.frontend}..."
-    prd_content=$(echo "$prd_content" | sed "s|$frontend_url|{config.urls.frontend}|g")
+    local escaped_url
+    escaped_url=$(_escape_sed_pattern "$frontend_url")
+    prd_content=$(echo "$prd_content" | sed "s|$escaped_url|{config.urls.frontend}|g")
     modified=true
   fi
 
@@ -480,28 +498,54 @@ fix_hardcoded_paths() {
   fi
 
   # Replace common localhost patterns if no config URLs set
+  # 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
       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')
+      prd_content=$(echo "$prd_content" | sed -E 's#http://localhost:(8000|8001|8080|3001|4000|5000)#{config.urls.backend}#g')
       modified=true
     fi
   fi
 
   if [[ -z "$frontend_url" ]]; then
-    # Common frontend ports: 3000, 5173, 4200, 8080
+    # Common frontend ports: 3000, 5173, 4200
     if echo "$prd_content" | 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')
+      prd_content=$(echo "$prd_content" | sed -E 's#http://localhost:(3000|5173|4200)#{config.urls.frontend}#g')
       modified=true
     fi
   fi
 
-  # Write back if modified
+  # Write back if modified, but only if content is still valid
   if [[ "$modified" == "true" ]]; then
+    # Safety check: don't write empty or drastically smaller content
+    if [[ -z "$prd_content" ]]; then
+      print_error "Path replacement resulted in empty content - aborting write"
+      return 1
+    fi
+
+    # Validate the result is still valid JSON with stories
+    if ! echo "$prd_content" | jq -e '.stories' >/dev/null 2>&1; then
+      print_error "Path replacement produced invalid JSON - aborting write"
+      return 1
+    fi
+
+    local orig_len=${#original_content}
+    local new_len=${#prd_content}
+    if [[ $new_len -lt $((orig_len / 2)) ]]; then
+      print_error "Path replacement lost too much content ($orig_len -> $new_len bytes) - aborting write"
+      return 1
+    fi
+
+    # Create backup before writing
+    cp "$prd_file" "${prd_file}.pre-fix.bak"
+
     echo "$prd_content" > "$prd_file"
     print_success "Paths updated to use config placeholders"
+
+    # Remove backup on success
+    rm -f "${prd_file}.pre-fix.bak"
   fi
 }
 

package/ralph/verify/api.sh

@@ -29,8 +29,21 @@ run_api_smoke_test() {
   local endpoints_tested=0
 
   # 1. Health endpoint (most important)
+  # Check if explicitly disabled (empty string in config)
+  local health_endpoint_raw
+  health_endpoint_raw=$(jq -r '.api.healthEndpoint' "$RALPH_DIR/config.json" 2>/dev/null)
+
   local health_endpoint
-  health_endpoint=$(get_config '.api.healthEndpoint' "/health")
+  if [[ "$health_endpoint_raw" == "" ]]; then
+    # Explicitly disabled
+    health_endpoint=""
+  elif [[ "$health_endpoint_raw" == "null" ]]; then
+    # Not configured, use default
+    health_endpoint="/health"
+  else
+    health_endpoint="$health_endpoint_raw"
+  fi
+
   if [[ -n "$health_endpoint" ]]; then
     if ! _smoke_test_endpoint "$base_url" "$health_endpoint" "health"; then
       failed=1

package/ralph/verify/lint.sh

@@ -484,6 +484,82 @@ run_fastapi_response_check() {
   return $failed
 }
 
+# Verify naming conventions (snake_case vs camelCase)
+# Uses vibe-check to catch common naming issues in TypeScript
+verify_naming_conventions() {
+  local story_type="${1:-general}"
+  local naming_log="$RALPH_DIR/last_naming_failure.log"
+
+  # Skip for backend-only stories (Python uses snake_case correctly)
+  if [[ "$story_type" == "backend" ]]; then
+    echo "    Naming conventions... skipped (backend story)"
+    return 0
+  fi
+
+  # Skip if no TypeScript files or vibe-check not available
+  if [[ ! -f "tsconfig.json" ]] && [[ ! -f "package.json" ]]; then
+    return 0
+  fi
+
+  # Check if vibe-check is available (it's part of agentic-loop)
+  local vibe_check_cmd=""
+  if command -v vibe-check &>/dev/null; then
+    vibe_check_cmd="vibe-check"
+  elif command -v npx &>/dev/null && [[ -f "node_modules/.bin/vibe-check" ]]; then
+    vibe_check_cmd="npx vibe-check"
+  elif [[ -n "${RALPH_LIB:-}" ]] && [[ -f "${RALPH_LIB}/../bin/vibe-check" ]]; then
+    vibe_check_cmd="${RALPH_LIB}/../bin/vibe-check"
+  else
+    # vibe-check not available, skip silently
+    return 0
+  fi
+
+  # Clear previous failure log
+  rm -f "$naming_log"
+
+  echo -n "    Naming conventions (snake_case)... "
+
+  # Run vibe-check with snake-case check only
+  # Use --fail-on warning to catch all snake_case issues
+  local check_output
+
+  # Build array of directories to check (handles spaces/newlines in paths)
+  local -a check_dirs_arr=(".")
+  local fe_dirs
+  fe_dirs=$(get_frontend_dirs 2>/dev/null || echo "")
+  if [[ -n "$fe_dirs" ]]; then
+    check_dirs_arr=()  # Clear default, use frontend dirs instead
+    while IFS= read -r dir; do
+      [[ -n "$dir" ]] && check_dirs_arr+=("$dir")
+    done <<< "$fe_dirs"
+  fi
+
+  if check_output=$("$vibe_check_cmd" "${check_dirs_arr[@]}" --only snake-case --fail-on warning --format compact 2>&1); then
+    print_success "passed"
+    return 0
+  else
+    # Check if there are actual issues or just no files
+    if echo "$check_output" | grep -qE "snake_case|snake-case"; then
+      print_error "failed"
+      echo ""
+      echo "    Naming convention issues (use camelCase in TypeScript):"
+      echo "$check_output" | head -"$MAX_LINT_ERROR_LINES" | sed 's/^/      /'
+      {
+        echo "Naming convention errors:"
+        echo "$check_output"
+        echo ""
+        echo "Fix: Use camelCase for TypeScript properties and variables."
+        echo "     snake_case is only acceptable when mapping external API responses."
+      } > "$naming_log"
+      return 1
+    else
+      # No snake_case issues found, might be other error
+      print_success "passed"
+      return 0
+    fi
+  fi
+}
+
 # Check if a verification step is enabled in config
 # Values: true, false, "final" (only on last story)
 check_enabled() {
@@ -555,6 +631,14 @@ run_configured_checks() {
     run_fastapi_response_check
   fi
 
+  # Naming convention check (snake_case vs camelCase)
+  # Enabled by default for TypeScript projects
+  if check_enabled "naming" "true"; then
+    if ! verify_naming_conventions "$story_type"; then
+      return 1
+    fi
+  fi
+
   # Run pre-commit hooks if available (catches errors before commit attempt)
   run_precommit_hooks
 

package/templates/signs.json

@@ -23,7 +23,7 @@
     },
     {
       "id": "sign-004",
-      "pattern": "Use camelCase for TypeScript/JavaScript variables, functions, and API response fields - convert snake_case from backend to camelCase in frontend",
+      "pattern": "ALWAYS transform API responses from snake_case to camelCase at the boundary. Create a transform function: `const user = { userName: data.user_name, createdAt: data.created_at }`. NEVER use snake_case properties directly in TypeScript code like `data.user_name` - always map to camelCase first.",
       "category": "frontend",
       "learnedFrom": null,
       "createdAt": "2026-01-20T00:00:00-08:00"