agentic-loop 3.6.2 → 3.7.1

package/.claude/commands/prd.md

@@ -99,31 +99,83 @@ Break the idea into small, executable stories:
 
 - Each story completable in one Claude session (~10-15 min)
 - Max 3-4 acceptance criteria per story
-- Order by dependency
 - Max 10 stories (suggest phases if more needed)
 - If appending, start IDs from the next available number
 
-### Step 5: Write PRD
+### Step 5: Write Draft PRD
 
-1. Ensure .ralph directory exists and allow PRD edit:
+Write the initial PRD to `.ralph/prd.json`:
+
+1. Ensure .ralph directory exists:
    ```bash
    mkdir -p .ralph && touch .ralph/.prd-edit-allowed
    ```
 
-2. Write to `.ralph/prd.json`:
-   - If **overwriting** or no existing PRD: Create new file with full structure
-   - If **appending**: Read existing JSON, add new stories to the `stories` array, update `metadata.estimatedStories` count, write back
+2. Write all stories to `.ralph/prd.json`
+   - If **appending**: Read existing JSON, add new stories, update count
+
+**Do not present to user yet - validation comes next.**
+
+### Step 6: Validate and Fix (MANDATORY)
+
+**Read back the PRD you just wrote and validate EVERY story.**
+
+```bash
+cat .ralph/prd.json
+```
+
+For EACH story, ask yourself:
+
+1. **"Is this testable?"** - Can the testSteps actually run?
+   - ❌ `grep -q 'function' file.py` → Only checks code exists, not behavior
+   - ❌ `test -f src/component.tsx` → Only checks file exists
+   - ❌ "Visit the page and verify" → Not executable
+   - ✅ `curl ... | jq -e` → Tests actual API response
+   - ✅ `npm test` / `pytest` → Runs real tests
+   - ✅ `npx playwright test` → Runs real tests
+
+2. **"Is this passable?"** - Given prior stories completed, can this story's tests pass?
+   - If TASK-003 needs a user to exist, does TASK-001 or TASK-002 create one?
+   - If TASK-004 tests a login flow, does a prior story create the auth endpoint?
+
+**Fix any issues you find:**
+
+| Problem | Fix |
+|---------|-----|
+| testSteps use grep/test only | Replace with curl, pytest, npm test, playwright |
+| Story depends on something not yet created | Reorder stories or add missing dependency story |
+| testSteps would pass on current code | Strengthen tests to verify NEW behavior |
+| No testSteps for backend story | Add `curl -s {config.urls.backend}/endpoint \| jq -e '.field'` |
+| No testSteps for frontend story | Add `npx tsc --noEmit` + `npm test` |
 
-3. Say: "I've {created|updated} the PRD with {N} stories ({X} new).
+### Step 7: Reorder if Needed
 
-   Review `.ralph/prd.json` and let me know:
-   - **'approved'** - Ready for `ralph run`
-   - **'edit [changes]'** - Tell me what to change
-   - Or edit the JSON directly and say **'done'**"
+If validation found dependency issues, reorder stories:
+
+1. Stories that create foundations (DB schemas, base components) come first
+2. Stories that depend on others come after their dependencies
+3. Update `dependsOn` arrays to reflect the order
+4. Re-number story IDs if needed (TASK-001, TASK-002, etc.)
+
+**After reordering, re-run Step 6 validation to confirm the new order works.**
+
+### Step 8: Present Final PRD
+
+Open the PRD for review:
+```bash
+open -a TextEdit .ralph/prd.json
+```
+
+Say: "I've {created|updated} the PRD with {N} stories and opened it in TextEdit.
+
+Review the PRD and let me know:
+- **'approved'** - Ready for `ralph run`
+- **'edit [changes]'** - Tell me what to change
+- Or edit the JSON directly and say **'done'**"
 
 **STOP and wait for user response.**
 
-### Step 6: Final Instructions
+### Step 9: Final Instructions
 
 Once approved, say:
 
@@ -232,7 +284,8 @@ Ralph will work through each story, running tests and committing as it goes."
       },
 
       "testSteps": [
-        "Executable shell commands - see examples below"
+        "curl -s {config.urls.backend}/endpoint | jq -e '.expected == true'",
+        "npx playwright test tests/e2e/feature.spec.ts"
       ],
 
       "testUrl": "{config.urls.frontend}/feature-page",
@@ -412,19 +465,6 @@ Example for a Dashboard component:
 
 ### Testing Anti-Patterns (AVOID THESE)
 
-**The "grep for code" trap:**
-```json
-// ❌ BAD - verifies code exists, not that it works
-"testSteps": [
-  "grep -q 'astream_events' app/domains/chat/agent/graph.py"
-]
-
-// ✅ GOOD - verifies actual behavior
-"testSteps": [
-  "curl -N {config.urls.backend}/chat -d '{\"message\":\"test\"}' | grep -q 'progress'"
-]
-```
-
 **Missing integration points:**
 ```json
 // ❌ BAD - creates function but doesn't verify callers use it
@@ -443,6 +483,8 @@ Example for a Dashboard component:
 }
 ```
 
+**(See "The Grep for Code Trap" section above for the #1 anti-pattern)**
+
 ### Removing/Modifying UI - Update Tests!
 
 **CRITICAL: When a story removes or modifies UI elements, it MUST update related tests.**
@@ -572,8 +614,28 @@ Example:
 
 ## Test Steps - CRITICAL
 
+⚠️ **THE #1 CAUSE OF FALSE PASSES: grep-only test steps that verify code exists but not behavior.**
+
 **Test steps MUST be executable shell commands.** Ralph runs them with bash.
 
+### The "Grep for Code" Trap - NEVER DO THIS
+
+```json
+// ❌ BAD - This will PASS even when the feature is completely broken!
+"testSteps": [
+  "grep -q 'astream_events' app/domains/chat/agent/graph.py",
+  "grep -q 'export function' src/api/users.ts"
+]
+
+// ✅ GOOD - This actually tests if the feature works
+"testSteps": [
+  "curl -N {config.urls.backend}/chat -d '{\"message\":\"test\"}' | grep -q 'progress'",
+  "curl -s {config.urls.backend}/users | jq -e '.data | length >= 0'"
+]
+```
+
+**Why is grep bad?** Ralph runs `grep -q 'function' file.py` → returns 0 → marks story as PASSED. But the function could be completely broken, have wrong parameters, or never get called. The test passed but the feature doesn't work.
+
 ### Backend Stories MUST Have Curl Tests
 
 **CRITICAL: Every backend story MUST include curl commands that verify actual API behavior.**
@@ -591,15 +653,7 @@ Use `{config.urls.backend}` - Ralph expands this from `.ralph/config.json`:
 
 Ralph reads `.ralph/config.json` and expands `{config.urls.backend}` before running.
 
-**Why?** Grep tests verify code exists. Curl tests verify the feature works.
-
-```json
-// ❌ NEVER DO THIS for backend stories
-"testSteps": [
-  "grep -q 'astream_events' app/domains/chat/agent/graph.py"
-]
-// This passed but the feature was broken!
-```
+**Why?** Grep tests verify code exists. Curl tests verify the feature works. (See "The Grep for Code Trap" above.)
 
 ### Test Steps by Story Type
 
@@ -640,15 +694,19 @@ Ralph reads `.ralph/config.json` and expands `{config.urls.backend}` before runn
 ]
 ```
 
-### Bad Test Steps (will fail or miss bugs)
+### Bad Test Steps (will PASS but miss bugs)
 ```json
 "testSteps": [
-  "grep -q 'function createUser' app/services/user.py",  // ❌ Just checks code exists
+  "grep -q 'function createUser' app/services/user.py",  // ❌ PASSES if code exists, even if broken
+  "grep -q 'export default' src/components/Dashboard.tsx", // ❌ PASSES even if component crashes
+  "test -f src/api/users.ts",                            // ❌ PASSES if file exists, even if empty
   "Visit http://localhost:3000/dashboard",                // ❌ Not executable
   "User can see the dashboard"                            // ❌ Not executable
 ]
 ```
 
+**NEVER use grep/test to verify behavior.** These will mark stories as PASSED when the feature is broken.
+
 **If a step can't be automated**, put it in `acceptanceCriteria` instead. Claude will verify it visually using MCP tools.
 
 ---

package/README.md

@@ -8,24 +8,6 @@ You describe what you want to build. Claude Code writes a PRD (Product Requireme
 
 ---
 
-## Supported Project Types
-
-Ralph auto-detects your project type and configures itself accordingly:
-
-| Type | Detection | Auto-Configured |
-|------|-----------|-----------------|
-| **FastMCP** | `fastmcp` in pyproject.toml | Server module, MCP port, transport, subprojects |
-| **FastAPI** | `fastapi` in pyproject.toml | uvicorn dev server, pytest, ruff |
-| **Django** | `django` in pyproject.toml or manage.py | migrations, pytest, ruff |
-| **Python** | pyproject.toml or requirements.txt | pytest, ruff, uv/poetry detection |
-| **Node.js** | package.json | npm/yarn/pnpm, vitest/jest, eslint |
-| **React** | `react` in package.json | Vite/Next.js, TypeScript, Tailwind |
-| **Go/Hugo** | go.mod or hugo.toml | Hugo server, Go build |
-| **Rust** | Cargo.toml | cargo build/test/clippy |
-| **Fullstack** | frontend + backend directories | Monorepo support, separate configs |
-
----
-
 ## What It Does
 
 **Brainstorm ideas with `/idea`**

package/package.json

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

package/ralph/init.sh

@@ -145,6 +145,8 @@ detect_project_type() {
     project_type="rust"
   elif [[ -f "go.mod" ]]; then
     project_type="go"
+  elif [[ -f "mix.exs" ]]; then
+    project_type="elixir"
   # Check for Python framework variants (more specific first)
   elif [[ -f "pyproject.toml" ]]; then
     # FastMCP detection (check for fastmcp in any quote style)

package/ralph/loop.sh

@@ -336,7 +336,43 @@ run_loop() {
       claude_args=(--continue "${claude_args[@]}")
     fi
 
-    if ! cat "$prompt_file" | run_with_timeout "$timeout_seconds" claude "${claude_args[@]}"; then
+    # Run Claude with crash detection and retry logic
+    local claude_output_log claude_exit_code max_crash_retries=3 crash_attempt=0
+    claude_output_log=$(create_temp_file ".log") || { rm -f "$prompt_file"; return 1; }
+
+    while [[ $crash_attempt -lt $max_crash_retries ]]; do
+      claude_exit_code=0
+      # Use pipefail to capture Claude's exit code, not tee's
+      set -o pipefail
+      cat "$prompt_file" | run_with_timeout "$timeout_seconds" claude "${claude_args[@]}" 2>&1 | tee "$claude_output_log" || claude_exit_code=$?
+      set +o pipefail
+
+      # Check for recoverable CLI crashes
+      if grep -qE "(No messages returned|unhandled.*promise.*rejection)" "$claude_output_log" 2>/dev/null; then
+        ((crash_attempt++))
+        print_warning "Claude CLI crashed (attempt $crash_attempt/$max_crash_retries) - retrying..."
+        log_progress "$story" "CLI_CRASH" "Claude crashed, retry $crash_attempt"
+        session_started=false  # Reset session on crash
+        sleep 2  # Brief pause before retry
+        continue
+      fi
+
+      # Not a crash - exit retry loop
+      break
+    done
+
+    rm -f "$claude_output_log"
+
+    if [[ $crash_attempt -ge $max_crash_retries ]]; then
+      print_error "Claude CLI crashed $max_crash_retries times - stopping loop"
+      log_progress "$story" "CLI_CRASH" "Gave up after $max_crash_retries crashes"
+      rm -f "$prompt_file"
+      echo ""
+      echo "Claude CLI is unstable. Try again with: ralph run $story"
+      return 1
+    fi
+
+    if [[ $claude_exit_code -ne 0 ]]; then
       print_warning "Claude session ended (timeout or error)"
       log_progress "$story" "TIMEOUT" "Claude session ended after ${timeout_seconds}s"
       rm -f "$prompt_file"

package/ralph/utils.sh

@@ -181,6 +181,7 @@ run_with_timeout() {
   fi
 }
 
+
 # Safely update JSON file atomically
 # Usage: update_json <file> [jq args...] <filter>
 # Example: update_json file.json --arg id "TASK-001" '.stories[] | select(.id==$id)'
@@ -191,12 +192,25 @@ update_json() {
   tmpfile=$(mktemp)
   lockdir="${file}.lock"
 
+  # Remove stale locks (from crashed processes)
+  if [[ -d "$lockdir" ]]; then
+    local lock_age=0
+    local now=$(date +%s)
+    # Cross-platform: macOS uses -f %m, Linux uses -c %Y
+    local lock_mtime=$(stat -f %m "$lockdir" 2>/dev/null || stat -c %Y "$lockdir" 2>/dev/null || echo "$now")
+    lock_age=$((now - lock_mtime))
+    if [[ $lock_age -gt 30 ]]; then
+      print_warning "Removing stale lock (${lock_age}s old): $lockdir"
+      rm -rf "$lockdir"
+    fi
+  fi
+
   # Acquire lock (mkdir is atomic)
   local attempts=0
   while ! mkdir "$lockdir" 2>/dev/null; do
     ((attempts++))
     if [[ $attempts -gt 50 ]]; then
-      print_error "Could not acquire lock on $file"
+      print_error "Could not acquire lock on $file (locked for 5s+)"
       rm -f "$tmpfile"
       return 1
     fi
@@ -495,6 +509,26 @@ validate_prd() {
     print_warning "PRD is missing feature name (will show as 'unnamed')"
   fi
 
+  # Check for grep-only testSteps (the #1 cause of false passes)
+  # Matches: grep, test -f/-e/-d, [ -f file ], [[ -f file ]]
+  local grep_only_stories
+  grep_only_stories=$(jq -r '
+    .stories[] |
+    select(.testSteps != null and (.testSteps | length > 0)) |
+    select(.testSteps | all(test("^(grep|test\\s+-[fed]|\\[\\[?\\s+-[fed])"; "x"))) |
+    .id
+  ' "$prd_file" 2>/dev/null)
+
+  if [[ -n "$grep_only_stories" ]]; then
+    print_warning "These stories have grep-only testSteps (may cause false passes):"
+    echo "$grep_only_stories" | while read -r story_id; do
+      [[ -n "$story_id" ]] && echo "  - $story_id"
+    done
+    echo ""
+    echo "Grep verifies code exists, not that it works. Add curl/playwright tests."
+    echo ""
+  fi
+
   return 0
 }
 
@@ -537,6 +571,12 @@ detect_migration_tool() {
     return 0
   fi
 
+  # Ecto (Elixir/Phoenix)
+  if [[ -f "$search_dir/mix.exs" ]] && [[ -d "$search_dir/priv/repo/migrations" ]]; then
+    echo "cd $search_dir && mix ecto.migrate"
+    return 0
+  fi
+
   # Prisma (Node.js)
   if [[ -d "$search_dir/prisma/migrations" ]] || [[ -f "$search_dir/prisma/schema.prisma" ]]; then
     echo "cd $search_dir && npx prisma migrate deploy"

package/ralph/verify/api.sh

@@ -0,0 +1,279 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+# api.sh - API and frontend smoke test verification module for ralph
+#
+# Catches broken APIs/frontends that unit tests miss (because they mock everything).
+# Uses config.json for endpoints - no project-specific hardcoding.
+
+# Run API smoke test against configured endpoints
+# Config options:
+#   api.baseUrl        - Base URL (e.g., http://localhost:8001)
+#   api.healthEndpoint - Health check path (e.g., /health)
+#   api.smokeEndpoints - Array of paths to test (e.g., ["/api/v1/users", "/api/v1/items"])
+#
+# Also tests story-specific apiEndpoints from PRD if defined.
+run_api_smoke_test() {
+  local story="$1"
+
+  # Check if API smoke tests are enabled (default: true if baseUrl configured)
+  local base_url
+  base_url=$(get_config '.api.baseUrl' "")
+
+  # No API configured, skip silently
+  [[ -z "$base_url" ]] && return 0
+
+  echo ""
+  echo "  [4/4] Running API smoke tests..."
+
+  local failed=0
+  local endpoints_tested=0
+
+  # 1. Health endpoint (most important)
+  local health_endpoint
+  health_endpoint=$(get_config '.api.healthEndpoint' "/health")
+  if [[ -n "$health_endpoint" ]]; then
+    if ! _smoke_test_endpoint "$base_url" "$health_endpoint" "health"; then
+      failed=1
+    fi
+    ((endpoints_tested++))
+  fi
+
+  # 2. Configured smoke endpoints
+  local smoke_endpoints
+  smoke_endpoints=$(get_config '.api.smokeEndpoints' "[]")
+  if [[ "$smoke_endpoints" != "[]" && "$smoke_endpoints" != "null" ]]; then
+    while IFS= read -r endpoint; do
+      [[ -z "$endpoint" ]] && continue
+      if ! _smoke_test_endpoint "$base_url" "$endpoint" "smoke"; then
+        failed=1
+      fi
+      ((endpoints_tested++))
+    done < <(echo "$smoke_endpoints" | jq -r '.[]' 2>/dev/null)
+  fi
+
+  # 3. Story-specific apiEndpoints from PRD
+  local story_endpoints
+  story_endpoints=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .apiEndpoints[]?' "$RALPH_DIR/prd.json" 2>/dev/null)
+  if [[ -n "$story_endpoints" ]]; then
+    while IFS= read -r endpoint_spec; do
+      [[ -z "$endpoint_spec" ]] && continue
+      # Format: "GET /api/v1/users" or "POST /api/v1/items" or just "/api/v1/users"
+      local method="GET"
+      local path="$endpoint_spec"
+      if [[ "$endpoint_spec" =~ ^(GET|POST|PUT|DELETE|PATCH)[[:space:]]+(.*) ]]; then
+        method="${BASH_REMATCH[1]}"
+        path="${BASH_REMATCH[2]}"
+      fi
+      if ! _smoke_test_endpoint "$base_url" "$path" "story" "$method"; then
+        failed=1
+      fi
+      ((endpoints_tested++))
+    done <<< "$story_endpoints"
+  fi
+
+  if [[ $endpoints_tested -eq 0 ]]; then
+    echo "    (no endpoints configured, skipping)"
+    return 0
+  fi
+
+  return $failed
+}
+
+# Run frontend smoke test
+# Config options:
+#   urls.frontend      - Frontend URL (e.g., http://localhost:3000)
+#   frontend.smokePages - Array of paths to test (e.g., ["/", "/login", "/dashboard"])
+run_frontend_smoke_test() {
+  local story="$1"
+  local story_type="${RALPH_STORY_TYPE:-general}"
+
+  # Get frontend URL from config (try multiple locations)
+  local frontend_url
+  frontend_url=$(get_config '.urls.frontend' "")
+  [[ -z "$frontend_url" ]] && frontend_url=$(get_config '.playwright.baseUrl' "")
+
+  # No frontend configured, skip silently
+  [[ -z "$frontend_url" ]] && return 0
+
+  # Skip for backend-only stories (optional optimization)
+  # [[ "$story_type" == "backend" ]] && return 0
+
+  echo ""
+  echo "  [5/5] Running frontend smoke tests..."
+
+  local failed=0
+  local pages_tested=0
+
+  # 1. Test root page (most important)
+  if ! _smoke_test_page "$frontend_url" "/" "root"; then
+    failed=1
+  fi
+  ((pages_tested++))
+
+  # 2. Configured smoke pages
+  local smoke_pages
+  smoke_pages=$(get_config '.frontend.smokePages' "[]")
+  if [[ "$smoke_pages" != "[]" && "$smoke_pages" != "null" ]]; then
+    while IFS= read -r page; do
+      [[ -z "$page" ]] && continue
+      [[ "$page" == "/" ]] && continue  # Already tested root
+      if ! _smoke_test_page "$frontend_url" "$page" "smoke"; then
+        failed=1
+      fi
+      ((pages_tested++))
+    done < <(echo "$smoke_pages" | jq -r '.[]' 2>/dev/null)
+  fi
+
+  # 3. Story-specific testUrl from PRD
+  local test_url
+  test_url=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .testUrl // empty' "$RALPH_DIR/prd.json" 2>/dev/null)
+  if [[ -n "$test_url" ]]; then
+    # testUrl can be full URL or just path
+    if [[ "$test_url" =~ ^https?:// ]]; then
+      if ! _smoke_test_page "" "$test_url" "story"; then
+        failed=1
+      fi
+    else
+      if ! _smoke_test_page "$frontend_url" "$test_url" "story"; then
+        failed=1
+      fi
+    fi
+    ((pages_tested++))
+  fi
+
+  return $failed
+}
+
+# Test a single page
+# Usage: _smoke_test_page <base_url> <path> <type>
+_smoke_test_page() {
+  local base_url="$1"
+  local path="$2"
+  local test_type="$3"
+
+  local url
+  if [[ -z "$base_url" ]]; then
+    url="$path"
+  else
+    url="${base_url}${path}"
+  fi
+
+  echo -n "    GET $path... "
+
+  local response_file
+  response_file=$(mktemp)
+  local http_code
+
+  http_code=$(curl -s -o "$response_file" -w "%{http_code}" \
+    --max-time "$CURL_TIMEOUT_SECONDS" \
+    "$url" 2>/dev/null) || http_code="000"
+
+  # Check response
+  if [[ "$http_code" == "000" ]]; then
+    print_error "connection failed (is frontend running?)"
+    rm -f "$response_file"
+    return 1
+  elif [[ "$http_code" =~ ^5 ]]; then
+    print_error "HTTP $http_code - Server Error"
+
+    # Save for failure context
+    {
+      echo "Frontend smoke test failed: $url"
+      echo "HTTP Status: $http_code"
+      echo "Response (first 50 lines):"
+      head -50 "$response_file"
+    } >> "$RALPH_DIR/last_frontend_failure.log"
+
+    rm -f "$response_file"
+    return 1
+  elif [[ "$http_code" =~ ^4 ]]; then
+    # 404 on a specific page is a real error (unlike API auth)
+    if [[ "$http_code" == "404" ]]; then
+      print_error "HTTP 404 - Page not found"
+      rm -f "$response_file"
+      return 1
+    fi
+    # Other 4xx (401, 403) might be OK - auth required
+    print_warning "HTTP $http_code (may need auth)"
+    rm -f "$response_file"
+    return 0
+  else
+    # Check for React/Next.js error boundary or crash indicators
+    if grep -qi "application error\|something went wrong\|error boundary\|chunk load error" "$response_file" 2>/dev/null; then
+      print_error "HTTP $http_code but page shows error"
+      {
+        echo "Frontend smoke test failed: $url"
+        echo "Page loaded but contains error indicators"
+        head -50 "$response_file"
+      } >> "$RALPH_DIR/last_frontend_failure.log"
+      rm -f "$response_file"
+      return 1
+    fi
+    print_success "HTTP $http_code"
+    rm -f "$response_file"
+    return 0
+  fi
+}
+
+# Test a single endpoint
+# Usage: _smoke_test_endpoint <base_url> <path> <type> [method]
+_smoke_test_endpoint() {
+  local base_url="$1"
+  local path="$2"
+  local test_type="$3"
+  local method="${4:-GET}"
+
+  local url="${base_url}${path}"
+  echo -n "    $method $path... "
+
+  local response_file
+  response_file=$(mktemp)
+  local http_code
+
+  # Make request with timeout, capture status code
+  if [[ "$method" == "GET" ]]; then
+    http_code=$(curl -s -o "$response_file" -w "%{http_code}" \
+      --max-time "$CURL_TIMEOUT_SECONDS" \
+      "$url" 2>/dev/null) || http_code="000"
+  else
+    # For non-GET, just check endpoint exists (OPTIONS or empty body)
+    http_code=$(curl -s -o "$response_file" -w "%{http_code}" \
+      --max-time "$CURL_TIMEOUT_SECONDS" \
+      -X "$method" \
+      -H "Content-Type: application/json" \
+      -d '{}' \
+      "$url" 2>/dev/null) || http_code="000"
+  fi
+
+  # Check response
+  if [[ "$http_code" == "000" ]]; then
+    print_error "connection failed (is server running?)"
+    rm -f "$response_file"
+    return 1
+  elif [[ "$http_code" =~ ^5 ]]; then
+    print_error "HTTP $http_code - Internal Server Error"
+    echo ""
+    echo "    Response body:"
+    head -20 "$response_file" | sed 's/^/      /'
+
+    # Save for failure context
+    {
+      echo "API smoke test failed: $method $url"
+      echo "HTTP Status: $http_code"
+      echo "Response:"
+      cat "$response_file"
+    } >> "$RALPH_DIR/last_api_failure.log"
+
+    rm -f "$response_file"
+    return 1
+  elif [[ "$http_code" =~ ^4 ]]; then
+    # 4xx might be OK (auth required, etc.) - warn but don't fail
+    print_warning "HTTP $http_code (may need auth)"
+    rm -f "$response_file"
+    return 0
+  else
+    print_success "HTTP $http_code"
+    rm -f "$response_file"
+    return 0
+  fi
+}

package/ralph/verify/lint.sh

@@ -355,6 +355,46 @@ verify_go() {
   return 0
 }
 
+# Verify Elixir code with mix credo
+verify_elixir() {
+  local elixir_log="$RALPH_DIR/last_elixir_failure.log"
+
+  # Skip if not an Elixir project
+  [[ ! -f "mix.exs" ]] && return 0
+  command -v mix &>/dev/null || return 0
+
+  # Clear previous failure log
+  rm -f "$elixir_log"
+
+  # Mix credo (Elixir's static analysis tool)
+  echo -n "    Mix credo... "
+  local credo_output
+  if credo_output=$(mix credo --strict 2>&1); then
+    print_success "passed"
+    return 0
+  fi
+
+  # Check if credo is installed
+  if echo "$credo_output" | grep -qi "could not find.*credo\|mix credo.*not found"; then
+    echo -n "not installed, trying mix compile... "
+    if credo_output=$(mix compile --warnings-as-errors 2>&1); then
+      print_success "passed"
+      return 0
+    fi
+  fi
+
+  # Failed
+  print_error "failed"
+  echo ""
+  echo "    Elixir errors:"
+  echo "$credo_output" | head -"$MAX_LINT_ERROR_LINES" | sed 's/^/      /'
+  {
+    echo "Elixir errors:"
+    echo "$credo_output"
+  } >> "$elixir_log"
+  return 1
+}
+
 # Verify Rust code with clippy
 verify_rust() {
   local rust_log="$RALPH_DIR/last_rust_failure.log"
@@ -505,6 +545,9 @@ run_configured_checks() {
     if ! verify_rust; then
       return 1
     fi
+    if ! verify_elixir; then
+      return 1
+    fi
   fi
 
   # FastAPI response model check

package/ralph/verify/tests.sh

@@ -200,6 +200,8 @@ run_unit_tests() {
       test_cmd="cargo test"
     elif [[ -f "go.mod" ]]; then
       test_cmd="go test ./..."
+    elif [[ -f "mix.exs" ]]; then
+      test_cmd="mix test"
     else
       echo "    (no test command found, skipping)"
       return 0

package/ralph/verify.sh

@@ -9,6 +9,7 @@
 VERIFY_DIR="${RALPH_LIB:-$(dirname "${BASH_SOURCE[0]}")}"
 source "$VERIFY_DIR/verify/lint.sh"
 source "$VERIFY_DIR/verify/tests.sh"
+source "$VERIFY_DIR/verify/api.sh"
 
 run_verification() {
   local story="$1"
@@ -27,7 +28,7 @@ run_verification() {
   # ========================================
   # STEP 1: Run lint checks
   # ========================================
-  echo "  [1/3] Running lint checks..."
+  echo "  [1/5] Running lint checks..."
   if ! run_configured_checks "$story_type"; then
     failed=1
   fi
@@ -37,7 +38,7 @@ run_verification() {
   # ========================================
   if [[ $failed -eq 0 ]]; then
     echo ""
-    echo "  [2/3] Running tests..."
+    echo "  [2/5] Running tests..."
     # First check that test files exist for new code
     if ! verify_test_files_exist; then
       failed=1
@@ -51,12 +52,30 @@ run_verification() {
   # ========================================
   if [[ $failed -eq 0 ]]; then
     echo ""
-    echo "  [3/3] Running PRD test steps..."
+    echo "  [3/5] Running PRD test steps..."
     if ! verify_prd_criteria "$story"; then
       failed=1
     fi
   fi
 
+  # ========================================
+  # STEP 4: API smoke test (if configured)
+  # ========================================
+  if [[ $failed -eq 0 ]]; then
+    if ! run_api_smoke_test "$story"; then
+      failed=1
+    fi
+  fi
+
+  # ========================================
+  # STEP 5: Frontend smoke test (if configured)
+  # ========================================
+  if [[ $failed -eq 0 ]]; then
+    if ! run_frontend_smoke_test "$story"; then
+      failed=1
+    fi
+  fi
+
   # ========================================
   # Final result
   # ========================================

package/templates/config/elixir.json

@@ -0,0 +1,84 @@
+{
+  "auth": {
+    "testUser": "",
+    "testPassword": "",
+    "loginEndpoint": "/api/auth/login",
+    "loginMethod": "POST",
+    "tokenType": "jwt",
+    "tokenHeader": "Authorization",
+    "tokenPrefix": "Bearer"
+  },
+
+  "docker": {
+    "enabled": false,
+    "composeFile": "docker-compose.yml",
+    "serviceName": "app",
+    "execPrefix": "docker compose exec -T"
+  },
+
+  "paths": {
+    "src": "lib",
+    "tests": "test",
+    "e2e": "test/e2e"
+  },
+
+  "commands": {
+    "dev": "mix phx.server",
+    "install": "mix deps.get",
+    "seed": "mix run priv/repo/seeds.exs",
+    "resetDb": "mix ecto.reset"
+  },
+
+  "migrations": {
+    "command": "mix ecto.migrate",
+    "pattern": "priv/repo/migrations/.*\\.exs$"
+  },
+
+  "checks": {
+    "lint": true,
+    "typecheck": false,
+    "build": true,
+    "test": true,
+    "fastapi": false
+  },
+
+  "api": {
+    "baseUrl": "http://localhost:4000",
+    "healthEndpoint": "/api/health",
+    "smokeEndpoints": [],
+    "timeout": 30
+  },
+
+  "playwright": {
+    "enabled": false,
+    "testDir": "test/e2e",
+    "projects": ["chromium"],
+    "baseUrl": "http://localhost:4000"
+  },
+
+  "verification": {
+    "codeReviewEnabled": true,
+    "browserEnabled": true,
+    "a11yEnabled": false,
+    "mobileViewport": 375,
+    "screenshotOnFailure": true
+  },
+
+  "urls": {
+    "app": "http://localhost:4000",
+    "docs": "http://localhost:4000/dev/dashboard"
+  },
+
+  "env": {
+    "required": ["DATABASE_URL"],
+    "optional": ["SECRET_KEY_BASE", "PHX_HOST"]
+  },
+
+  "maxIterations": 20,
+  "maxSessionSeconds": 600,
+
+  "contextRotThreshold": {
+    "maxStories": 10,
+    "maxFilesChanged": 20
+  }
+}

package/templates/config/fullstack.json

@@ -47,6 +47,7 @@
   "api": {
     "baseUrl": "http://localhost:8000",
     "healthEndpoint": "/api/health",
+    "smokeEndpoints": [],
     "timeout": 30
   },
 
@@ -71,6 +72,10 @@
     "docs": "http://localhost:8000/api/docs"
   },
 
+  "frontend": {
+    "smokePages": ["/", "/login"]
+  },
+
   "env": {
     "required": ["DATABASE_URL", "SECRET_KEY"],
     "optional": ["REDIS_URL", "SENTRY_DSN"]

package/templates/config/node.json

@@ -45,6 +45,7 @@
   "api": {
     "baseUrl": "http://localhost:3000",
     "healthEndpoint": "/api/health",
+    "smokeEndpoints": [],
     "timeout": 30
   },
 
@@ -65,9 +66,14 @@
 
   "urls": {
     "app": "http://localhost:3000",
+    "frontend": "http://localhost:3000",
     "docs": "http://localhost:3000/api/docs"
   },
 
+  "frontend": {
+    "smokePages": ["/"]
+  },
+
   "env": {
     "required": ["DATABASE_URL"],
     "optional": ["REDIS_URL", "SENTRY_DSN"]

package/templates/config/python.json

@@ -45,6 +45,7 @@
   "api": {
     "baseUrl": "http://localhost:8000",
     "healthEndpoint": "/api/health",
+    "smokeEndpoints": [],
     "timeout": 30
   },