agentic-loop 3.17.3 → 3.18.0

package/package.json

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

package/ralph/hooks/hooks-config.json

@@ -2,18 +2,6 @@
   "_comment": "Copy this 'hooks' section into your ~/.claude/settings.json or .claude/settings.json",
   "_instructions": "Replace VIBE_PATH with the path to your agentic-loop installation",
   "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "VIBE_PATH/ralph/hooks/protect-prd.sh",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
     "PostToolUse": [
       {
         "matcher": "Edit|Write",

package/ralph/hooks/install.sh

@@ -111,18 +111,6 @@ fi
 # Build hooks config with actual path
 HOOKS_CONFIG=$(cat <<EOF
 {
-  "PreToolUse": [
-    {
-      "matcher": "Edit|Write",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/protect-prd.sh",
-          "timeout": 5
-        }
-      ]
-    }
-  ],
   "PostToolUse": [
     {
       "matcher": "Edit|Write",
@@ -195,7 +183,6 @@ echo "$MERGED" > "$SETTINGS_FILE"
 echo -e "${GREEN}✓ Hooks installed successfully!${NC}"
 echo ""
 echo "Hooks enabled:"
-echo "  • protect-prd.sh      - Blocks edits to prd.json"
 echo "  • warn-debug.sh       - Warns about console.log/debugger"
 echo "  • warn-secrets.sh     - Warns about hardcoded secrets/API keys"
 echo "  • warn-urls.sh        - Warns about hardcoded localhost URLs"

package/ralph/loop.sh

@@ -88,6 +88,23 @@ preflight_checks() {
     fi
   done
 
+  # Check for timeout utility (critical for session enforcement)
+  printf "  Timeout utility... "
+  if command -v timeout &>/dev/null; then
+    print_success "ok (timeout)"
+  elif command -v gtimeout &>/dev/null; then
+    print_success "ok (gtimeout)"
+  else
+    print_warning "not found (using bash fallback)"
+    echo "    Session timeouts use a bash fallback. For better reliability:"
+    if [[ "$(uname)" == "Darwin" ]]; then
+      echo "    brew install coreutils"
+    else
+      echo "    Install GNU coreutils"
+    fi
+    ((warnings++))
+  fi
+
   echo ""
   if [[ $warnings -gt 0 ]]; then
     print_warning "$warnings pre-loop warning(s) - loop may fail on connectivity issues"

package/ralph/prd-check.sh

@@ -50,7 +50,7 @@
 #     - Has prerequisites array with DB reset command
 #     - Prevents infinite retries on schema mismatch errors
 #
-#   CUSTOM CHECKS (.ralph/checks/prd/ or ~/.config/ralph/checks/prd/):
+#   CUSTOM CHECKS (.ralph/checks/prd/):
 #     - User-provided scripts that receive story JSON on stdin
 #     - Output issue descriptions to stdout (one per line)
 #     - Excluded from auto-fix (reported for manual review)
@@ -63,12 +63,22 @@
 # ============================================================================
 # AUTO-FIX
 # ============================================================================
-# When issues are found, Claude is invoked to fix them automatically:
+# When issues are found, a two-tier fix runs automatically:
 #
-#   1. Issues are summarized (e.g., "3x backend: add curl tests")
-#   2. Claude receives the PRD + issues + fix rules
-#   3. Fixed PRD is validated and saved
-#   4. Timestamped backup preserved (prd.json.20240115-143022.bak)
+#   Tier 1 — Mechanical fixes (instant, no LLM):
+#     - Missing mcp on frontend → ["playwright", "devtools"]
+#     - Bare pytest → prefixed with detected runner (uv/poetry/pipenv)
+#     - Missing camelCase note → standard text appended to .notes
+#     - Missing migration prerequisites → template prerequisite array
+#     - Server-only testSteps → offline fallback appended
+#
+#   Tier 2 — Parallel Claude subagents (one per story, concurrent):
+#     - For issues needing creative input (apiContract, prose testSteps, etc.)
+#     - Each story gets a small prompt with just its JSON + specific issues
+#     - All stories fix in parallel (wall-clock = time for 1 story)
+#     - Results merged back via update_json; failures left unchanged
+#
+#   Timestamped backup preserved before any modifications.
 #
 # If Claude is unavailable or fix fails, loop continues with warnings.
 #
@@ -81,7 +91,6 @@
 #   .api.baseUrl          - API base URL (enables API config validation)
 #   .api.healthEndpoint   - Health check path (default: /health, empty to disable)
 #   .ralph/checks/prd/check-*     - Project-level custom checks (per-story)
-#   ~/.config/ralph/checks/prd/   - User-global custom checks (per-story)
 #   .checks.custom.<name>         - Enable/disable individual custom checks
 #
 # ============================================================================
@@ -220,9 +229,13 @@ validate_prd() {
     echo ""
   fi
 
-  # Validate API smoke test configuration (skip in fast/cached mode)
+  # Validate API smoke test configuration in background (skip in fast/cached mode)
+  # Capture output to a temp file to avoid garbled terminal output
+  local api_check_pid="" api_check_output=""
   if [[ "$dry_run" != "true" ]]; then
-    _validate_api_config "$config"
+    api_check_output=$(create_temp_file ".api-check.out")
+    _validate_api_config "$config" > "$api_check_output" 2>&1 &
+    api_check_pid=$!
   fi
 
   # Replace hardcoded paths with config placeholders
@@ -232,6 +245,12 @@ validate_prd() {
   # dry_run flag — when "true", skip auto-fix
   _validate_and_fix_stories "$prd_file" "$dry_run" || return 1
 
+  # Wait for background API health check and print its output
+  if [[ -n "$api_check_pid" ]]; then
+    wait "$api_check_pid" 2>/dev/null
+    [[ -s "$api_check_output" ]] && cat "$api_check_output"
+  fi
+
   return 0
 }
 
@@ -504,8 +523,8 @@ _validate_and_fix_stories() {
     # Snapshot built-in issues before custom checks append
     local builtin_story_issues="$story_issues"
 
-    # Check 8: User-defined custom checks (.ralph/checks/prd/ or ~/.config/ralph/checks/prd/)
-    if [[ -d ".ralph/checks/prd" ]] || [[ -d "$HOME/.config/ralph/checks/prd" ]]; then
+    # Check 8: User-defined custom checks (.ralph/checks/prd/)
+    if [[ -d ".ralph/checks/prd" ]]; then
       local story_json
       story_json=$(jq --arg id "$story_id" '.stories[] | select(.id==$id)' "$prd_file")
       local custom_output
@@ -555,12 +574,32 @@ _validate_and_fix_stories() {
       return 0
     fi
 
-    # Check if Claude is available for auto-fix
-    if command -v claude &>/dev/null; then
-      _fix_stories_with_claude "$prd_file" "$issues"
+    # Create backup before any modifications
+    local backup_file="${prd_file}.$(date +%Y%m%d-%H%M%S).bak"
+    cp "$prd_file" "$backup_file"
+
+    # Tier 1: Instant mechanical fixes (no LLM needed)
+    _apply_mechanical_fixes "$prd_file"
+
+    # Re-check what's still broken after mechanical fixes
+    # validate_stories_quick returns "ID: issue, ID: issue, ..." on one line
+    # Group into one line per story for _fix_stories_parallel
+    local remaining_raw
+    remaining_raw=$(validate_stories_quick "$prd_file")
+    local remaining_grouped=""
+    [[ -n "$remaining_raw" ]] && remaining_grouped=$(_group_issues_by_story "$remaining_raw")
+
+    if [[ -n "$remaining_grouped" ]]; then
+      # Tier 2: Parallel Claude subagents for creative fixes
+      if command -v claude &>/dev/null; then
+        _fix_stories_parallel "$prd_file" "$remaining_grouped" "$backup_file"
+      else
+        print_warning "Claude CLI not found - mechanical fixes applied, but some stories need manual review"
+        echo "  Backup at: $backup_file"
+        return 0
+      fi
     else
-      print_warning "Claude CLI not found - run manually to optimize test coverage"
-      return 1
+      print_success "All issues resolved with mechanical fixes (backup at $backup_file)"
     fi
   else
     print_success "Test coverage looks good"
@@ -579,49 +618,188 @@ _run_custom_prd_checks() {
   local custom_issues=""
   local custom_log="$RALPH_DIR/last_custom_check.log"
 
-  local check_dirs=()
-  [[ -d ".ralph/checks/prd" ]] && check_dirs+=(".ralph/checks/prd")
-  [[ -d "$HOME/.config/ralph/checks/prd" ]] && check_dirs+=("$HOME/.config/ralph/checks/prd")
-  [[ ${#check_dirs[@]} -eq 0 ]] && return 0
-
-  for check_dir in "${check_dirs[@]}"; do
-    for check_script in "$check_dir"/check-*; do
-      [[ ! -f "$check_script" || ! -x "$check_script" ]] && continue
-
-      local check_key
-      check_key=$(basename "$check_script")
-      check_key="${check_key%.*}"
-      # Read directly instead of get_config — jq's // operator treats false as falsy
-      local enabled="true"
-      if [[ -f "$RALPH_DIR/config.json" ]]; then
-        local raw
-        raw=$(jq -r --arg key "$check_key" '.checks.custom[$key]' "$RALPH_DIR/config.json" 2>/dev/null)
-        [[ -n "$raw" && "$raw" != "null" ]] && enabled="$raw"
+  local check_dir=".ralph/checks/prd"
+  [[ ! -d "$check_dir" ]] && return 0
+
+  for check_script in "$check_dir"/check-*; do
+    [[ ! -f "$check_script" || ! -x "$check_script" ]] && continue
+
+    local check_key
+    check_key=$(basename "$check_script")
+    check_key="${check_key%.*}"
+    # Read directly instead of get_config — jq's // operator treats false as falsy
+    local enabled="true"
+    if [[ -f "$RALPH_DIR/config.json" ]]; then
+      local raw
+      raw=$(jq -r --arg key "$check_key" '.checks.custom[$key]' "$RALPH_DIR/config.json" 2>/dev/null)
+      [[ -n "$raw" && "$raw" != "null" ]] && enabled="$raw"
+    fi
+    [[ "$enabled" == "false" ]] && continue
+
+    # Run check — capture stdout for issues, stderr to log for debugging
+    local output=""
+    if ! output=$(echo "$story_json" | run_with_timeout 30 "$check_script" "$story_id" "$prd_file" 2>>"$custom_log"); then
+      # Script failed to execute — warn, don't silently swallow
+      print_warning "Custom check '$check_key' failed for story $story_id (see .ralph/last_custom_check.log)"
+    fi
+
+    if [[ -n "$output" ]]; then
+      while IFS= read -r line; do
+        [[ -n "$line" ]] && custom_issues+="${line}, "
+      done <<< "$output"
+    fi
+  done
+
+  echo "$custom_issues"
+}
+
+# Group flat "ID: issue, ID: issue, ..." string into one line per story
+# Input:  "S1: missing curl tests, S1: missing apiContract, S2: missing testUrl, "
+# Output: "S1: missing curl tests, missing apiContract\nS2: missing testUrl"
+_group_issues_by_story() {
+  local raw="$1"
+  # Split on ", " boundaries that precede a story ID pattern (word: )
+  # Use awk to accumulate issues per story ID
+  echo "$raw" | tr ',' '\n' | sed 's/^ *//' | while IFS= read -r entry; do
+    [[ -z "$entry" ]] && continue
+    if [[ "$entry" =~ ^([A-Za-z0-9._-]+):\ (.+) ]]; then
+      echo "${BASH_REMATCH[1]}	${BASH_REMATCH[2]}"
+    fi
+  done | awk -F'\t' '{
+    if (seen[$1]) {
+      issues[$1] = issues[$1] ", " $2
+    } else {
+      seen[$1] = 1
+      issues[$1] = $2
+      order[++n] = $1
+    }
+  } END {
+    for (i = 1; i <= n; i++) {
+      print order[i] ": " issues[order[i]]
+    }
+  }'
+}
+
+# Apply instant mechanical fixes using jq (no LLM needed)
+# Fixes: missing mcp, bare pytest, missing camelCase note, missing migration prerequisites,
+# server-only testSteps
+_apply_mechanical_fixes() {
+  local prd_file="$1"
+  local fixed=0
+
+  # Detect Python runner once for bare pytest fixes
+  local py_runner
+  py_runner=$(detect_python_runner ".")
+
+  local story_ids
+  story_ids=$(jq -r '.stories[] | select(.passes != true) | .id' "$prd_file" 2>/dev/null)
+
+  while IFS= read -r story_id; do
+    [[ -z "$story_id" ]] && continue
+
+    local story_type
+    story_type=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .type // "unknown"' "$prd_file")
+
+    # Fix: Frontend missing mcp → set to ["playwright", "devtools"]
+    if [[ "$story_type" == "frontend" ]]; then
+      local mcp_len
+      mcp_len=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .mcp // [] | length' "$prd_file")
+      if [[ "$mcp_len" == "0" ]]; then
+        update_json "$prd_file" --arg id "$story_id" \
+          '(.stories[] | select(.id==$id) | .mcp) = ["playwright", "devtools"]' && fixed=$((fixed + 1))
       fi
-      [[ "$enabled" == "false" ]] && continue
+    fi
 
-      # Run check — capture stdout for issues, stderr to log for debugging
-      local output=""
-      if ! output=$(echo "$story_json" | run_with_timeout 30 "$check_script" "$story_id" "$prd_file" 2>>"$custom_log"); then
-        # Script failed to execute — warn, don't silently swallow
-        print_warning "Custom check '$check_key' failed for story $story_id (see .ralph/last_custom_check.log)"
+    # Fix: Bare pytest → prefix with detected runner
+    if [[ -n "$py_runner" ]]; then
+      local test_steps_raw
+      test_steps_raw=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testSteps // [] | join("\n")' "$prd_file")
+      if echo "$test_steps_raw" | grep -qE '(^|[; ])pytest ' && ! echo "$test_steps_raw" | grep -qE "(uv run|poetry run|pipenv run) pytest"; then
+        update_json "$prd_file" --arg id "$story_id" --arg runner "$py_runner" \
+          '(.stories[] | select(.id==$id) | .testSteps) |= [.[]? | gsub("(?<pre>^|[; ])pytest "; "\(.pre)\($runner) pytest ")]' && fixed=$((fixed + 1))
       fi
+    fi
 
-      if [[ -n "$output" ]]; then
-        while IFS= read -r line; do
-          [[ -n "$line" ]] && custom_issues+="${line}, "
-        done <<< "$output"
+    # Fix: Frontend/general API consumer missing camelCase note
+    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
+          local camel_note="Transform API responses from snake_case to camelCase. Create typed interfaces with camelCase properties."
+          if [[ -z "$story_notes" ]]; then
+            update_json "$prd_file" --arg id "$story_id" --arg note "$camel_note" \
+              '(.stories[] | select(.id==$id) | .notes) = $note' && fixed=$((fixed + 1))
+          else
+            update_json "$prd_file" --arg id "$story_id" --arg note "$camel_note" \
+              '(.stories[] | select(.id==$id) | .notes) += (" " + $note)' && fixed=$((fixed + 1))
+          fi
+        fi
       fi
-    done
-  done
+    fi
 
-  echo "$custom_issues"
+    # Fix: Migration story missing prerequisites
+    local story_files
+    story_files=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | (.files.create // []) + (.files.modify // []) | join(" ")' "$prd_file")
+    if echo "$story_files" | grep -qiE "(alembic/versions|migrations/|\.migration\.|models\.py|models/|schema\.)"; then
+      local has_prereq
+      has_prereq=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .prerequisites // [] | length' "$prd_file")
+      if [[ "$has_prereq" == "0" ]]; then
+        update_json "$prd_file" --arg id "$story_id" \
+          '(.stories[] | select(.id==$id) | .prerequisites) = [{"name": "Reset test DB", "command": "npm run db:reset:test", "when": "schema changes"}]' && fixed=$((fixed + 1))
+      fi
+    fi
+
+    # Fix: All testSteps are server-dependent → append offline test step
+    local test_steps
+    test_steps=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testSteps // [] | join(" ")' "$prd_file")
+    if [[ -n "$test_steps" ]]; then
+      local has_offline=false has_server=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=true
+        else
+          has_offline=true
+        fi
+      done <<< "$step_list"
+
+      if [[ "$has_server" == "true" && "$has_offline" == "false" ]]; then
+        # Pick an offline step based on story type and project tooling
+        local offline_step="npx tsc --noEmit"
+        if [[ "$story_type" == "backend" ]]; then
+          if [[ -n "$py_runner" ]]; then
+            offline_step="$py_runner pytest tests/unit/"
+          elif [[ -f "go.mod" ]]; then
+            offline_step="go test ./..."
+          else
+            offline_step="npm test"
+          fi
+        fi
+        update_json "$prd_file" --arg id "$story_id" --arg step "$offline_step" \
+          '(.stories[] | select(.id==$id) | .testSteps) += [$step]' && fixed=$((fixed + 1))
+      fi
+    fi
+
+  done <<< "$story_ids"
+
+  if [[ $fixed -gt 0 ]]; then
+    echo "    Applied $fixed mechanical fixes (no LLM needed)"
+  fi
+
+  return 0
 }
 
-# Optimize story test coverage using Claude
-_fix_stories_with_claude() {
+# Fix stories with remaining issues using parallel Claude subagents (one per story)
+# $1: prd_file  $2: newline-separated "story_id: issues" lines  $3: backup file path
+_fix_stories_parallel() {
   local prd_file="$1"
   local issues="$2"
+  local backup_file="$3"
 
   # Read config values for context
   local config_file="$RALPH_DIR/config.json"
@@ -631,102 +809,129 @@ _fix_stories_with_claude() {
     frontend_url=$(jq -r '.urls.frontend // .playwright.baseUrl // "http://localhost:3000"' "$config_file" 2>/dev/null)
   fi
 
-  local fix_prompt="Enhance test coverage for these stories. Output the COMPLETE updated prd.json.
+  # Parse issues into per-story fix jobs
+  local pids=()
+  local story_ids_to_fix=()
+  local output_files=()
+
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    local sid="${line%%:*}"
+    local story_issues="${line#*: }"
+    [[ -z "$sid" || -z "$story_issues" ]] && continue
+
+    # Extract this story's JSON
+    local story_json
+    story_json=$(jq --arg id "$sid" '.stories[] | select(.id==$id)' "$prd_file" 2>/dev/null)
+    [[ -z "$story_json" ]] && continue
+
+    # Build a small per-story prompt
+    local prompt_file
+    prompt_file=$(create_temp_file ".prompt.txt")
+    local output_file
+    output_file=$(create_temp_file ".fix.json")
+
+    cat > "$prompt_file" <<PROMPT_EOF
+Fix this story's issues. Output ONLY the fixed story JSON object (not the full PRD).
+
+STORY JSON:
+$story_json
 
-STORIES TO OPTIMIZE:
-$issues
+ISSUES TO FIX:
+$story_issues
 
-CONFIG VALUES (use these):
+CONFIG VALUES:
 - Backend URL: $backend_url (use as {config.urls.backend} in testSteps)
 - Frontend URL: $frontend_url (use as {config.urls.frontend} in testUrl)
 
 RULES:
-1. Backend stories MUST have testSteps with curl commands that hit real endpoints
-   Example: curl -s -X POST {config.urls.backend}/api/users -d '...' | jq -e '.id'
-2. Backend stories MUST have apiContract with endpoint, request, response
-3. Frontend stories MUST have testUrl set to {config.urls.frontend}/[page-path]
-   - Derive page path from story title (e.g., 'login form' → '/login', 'dashboard' → '/dashboard')
-4. Frontend stories MUST have contextFiles array (include idea file path in each story's contextFiles)
-5. Frontend stories MUST have mcp array with browser tools: [\"playwright\", \"devtools\"]
-6. Auth stories MUST have security acceptanceCriteria:
-   - Passwords hashed with bcrypt (cost 10+)
-   - Passwords NEVER in API responses
-   - Rate limiting on login attempts
-7. List endpoints MUST have pagination acceptanceCriteria:
-   - Returns paginated results (max 100 per page)
-   - Accepts ?page=N&limit=N query params
-8. 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\"}]
-9. 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 }\"
-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")
-
-Output ONLY the fixed JSON, no explanation. Start with { and end with }."
-
-  local raw_response
-  raw_response=$(echo "$fix_prompt" | run_with_timeout "$CODE_REVIEW_TIMEOUT_SECONDS" claude -p 2>/dev/null)
-
-  # Extract JSON from response (Claude often wraps in markdown code fences)
-  local fixed_prd
-  # First strip markdown code fences if present
-  fixed_prd=$(echo "$raw_response" | sed 's/^```json//; s/^```$//' | sed -n '/^[[:space:]]*{/,/^[[:space:]]*}[[:space:]]*$/p' | head -1000)
-
-  # If sed extraction failed, try removing fences and using raw
-  if [[ -z "$fixed_prd" ]]; then
-    fixed_prd=$(echo "$raw_response" | sed 's/^```json//; s/^```//; s/```$//')
+- Backend stories MUST have testSteps with curl commands hitting real endpoints
+  Example: curl -s -X POST {config.urls.backend}/api/users -d '...' | jq -e '.id'
+- Backend stories MUST have apiContract with endpoint, request, response
+- Frontend stories MUST have testUrl set to {config.urls.frontend}/[page-path]
+- Frontend stories MUST have contextFiles array
+- Auth stories MUST have security acceptanceCriteria (bcrypt, rate limiting)
+- List endpoints MUST have pagination acceptanceCriteria (?page=N&limit=N)
+- Stories with only curl testSteps MUST also have an offline test step (npm test, tsc --noEmit, pytest)
+- Keep ALL existing fields. Only add/fix what's missing.
+
+Output ONLY the fixed story JSON object. Start with { and end with }.
+PROMPT_EOF
+
+    # Background a Claude call for this story
+    ( run_with_timeout 60 claude -p < "$prompt_file" > "$output_file" 2>/dev/null ) &
+    pids+=($!)
+    story_ids_to_fix+=("$sid")
+    output_files+=("$output_file")
+  done <<< "$issues"
+
+  local job_count=${#pids[@]}
+  if [[ $job_count -eq 0 ]]; then
+    return 0
   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
-    # 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
+  echo "    Fixing $job_count stories in parallel..."
 
-    # 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
+  # Wait for all background jobs
+  for pid in "${pids[@]}"; do
+    wait "$pid" 2>/dev/null
+  done
+
+  # Merge results back into PRD
+  local merged=0 failed=0
+  for i in "${!story_ids_to_fix[@]}"; do
+    local sid="${story_ids_to_fix[$i]}"
+    local output_file="${output_files[$i]}"
+
+    [[ ! -s "$output_file" ]] && { failed=$((failed + 1)); continue; }
+
+    # Extract JSON from response (strip markdown fences if present)
+    local raw_response
+    raw_response=$(cat "$output_file")
+    local fixed_story
+    fixed_story=$(echo "$raw_response" | sed 's/^```json//; s/^```$//' | sed -n '/^[[:space:]]*{/,/^[[:space:]]*}[[:space:]]*$/p')
+
+    if [[ -z "$fixed_story" ]]; then
+      fixed_story=$(echo "$raw_response" | sed 's/^```json//; s/^```//; s/```$//')
     fi
 
-    # Write fixed PRD
-    echo "$fixed_prd" > "$prd_file"
-    print_success "Test coverage optimized (backup at $backup_file)"
+    # Validate it's a valid JSON object with an id field matching this story
+    local response_id
+    response_id=$(echo "$fixed_story" | jq -r '.id // empty' 2>/dev/null)
+    if [[ "$response_id" != "$sid" ]]; then
+      # Try to salvage: if valid JSON, force the correct id
+      if echo "$fixed_story" | jq -e '.' >/dev/null 2>&1; then
+        fixed_story=$(echo "$fixed_story" | jq --arg id "$sid" '.id = $id')
+        response_id="$sid"
+      else
+        failed=$((failed + 1))
+        continue
+      fi
+    fi
 
-    # Re-validate to confirm
-    local remaining_issues
-    remaining_issues=$(validate_stories_quick "$prd_file")
-    if [[ -n "$remaining_issues" ]]; then
-      echo "  Some stories may need manual review"
+    # Merge fixed story back into PRD using update_json
+    local fixed_story_escaped
+    fixed_story_escaped=$(echo "$fixed_story" | jq -c '.')
+    if update_json "$prd_file" --arg id "$sid" --argjson fixed "$fixed_story_escaped" \
+      '(.stories[] | select(.id==$id)) = $fixed'; then
+      merged=$((merged + 1))
+    else
+      failed=$((failed + 1))
     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
+  done
+
+  if [[ $merged -gt 0 ]]; then
+    print_success "Fixed $merged stories with Claude (backup at $backup_file)"
+  fi
+  if [[ $failed -gt 0 ]]; then
+    print_warning "$failed stories could not be auto-fixed — review with /prd"
+  fi
+
+  # Final validation pass
+  local remaining_issues
+  remaining_issues=$(validate_stories_quick "$prd_file")
+  if [[ -n "$remaining_issues" ]]; then
+    echo "  Some stories may still need manual review"
   fi
 }
 

package/ralph/setup.sh

@@ -92,6 +92,33 @@ ralph_setup() {
   local pkg_root
   pkg_root="$(cd "$RALPH_LIB/.." && pwd)"
 
+  # Install timeout utility if missing (critical for session enforcement)
+  if ! command -v timeout &>/dev/null && ! command -v gtimeout &>/dev/null; then
+    if [[ "$(uname)" == "Darwin" ]]; then
+      if command -v brew &>/dev/null; then
+        echo ""
+        echo "  Installing coreutils (provides gtimeout for session enforcement)..."
+        if brew install coreutils 2>/dev/null; then
+          print_success "  coreutils installed"
+        else
+          print_warning "  Failed to install coreutils — session timeouts will use a bash fallback"
+          echo "    Try manually: brew install coreutils"
+        fi
+        echo ""
+      else
+        echo ""
+        print_warning "No timeout utility found — session timeouts will use a bash fallback"
+        echo "  Install Homebrew (https://brew.sh), then: brew install coreutils"
+        echo ""
+      fi
+    else
+      echo ""
+      print_warning "No timeout utility found — session timeouts will use a bash fallback"
+      echo "  Install GNU coreutils for reliable timeout enforcement"
+      echo ""
+    fi
+  fi
+
   # Run all setup steps
   setup_ralph_dir "$pkg_root"
   setup_custom_checks
@@ -353,8 +380,7 @@ setup_claude_hooks() {
   }
 
   # Resolve each hook path (project hooks take priority over global)
-  local protect_prd warn_debug warn_secrets warn_urls warn_empty_catch log_tools inject_context save_learnings
-  protect_prd=$(_resolve_hook "protect-prd.sh")
+  local warn_debug warn_secrets warn_urls warn_empty_catch log_tools inject_context save_learnings
   warn_debug=$(_resolve_hook "warn-debug.sh")
   warn_secrets=$(_resolve_hook "warn-secrets.sh")
   warn_urls=$(_resolve_hook "warn-urls.sh")
@@ -364,11 +390,7 @@ setup_claude_hooks() {
   save_learnings=$(_resolve_hook "save-learnings.sh")
 
   # Build hooks arrays using jq for proper JSON
-  local pre_tool_hooks post_edit_hooks post_all_hooks session_start_hooks stop_hooks
-
-  # PreToolUse: protect-prd on Edit|Write
-  pre_tool_hooks="[]"
-  [[ -n "$protect_prd" ]] && pre_tool_hooks=$(jq -n --arg cmd "$protect_prd" '[{"type": "command", "command": $cmd, "timeout": 5}]')
+  local post_edit_hooks post_all_hooks session_start_hooks stop_hooks
 
   # PostToolUse: warn-* hooks on Edit|Write
   post_edit_hooks="[]"
@@ -391,13 +413,11 @@ setup_claude_hooks() {
   # Build the complete hooks config
   local hooks_config
   hooks_config=$(jq -n \
-    --argjson pre_tool "$pre_tool_hooks" \
     --argjson post_edit "$post_edit_hooks" \
     --argjson post_all "$post_all_hooks" \
     --argjson session_start "$session_start_hooks" \
     --argjson stop "$stop_hooks" \
     '{
-      "PreToolUse": [{"matcher": "Edit|Write", "hooks": $pre_tool}],
       "PostToolUse": [
         {"matcher": "Edit|Write", "hooks": $post_edit},
         {"matcher": "*", "hooks": $post_all}

package/ralph/utils.sh

@@ -316,8 +316,27 @@ run_with_timeout() {
   elif command -v gtimeout &>/dev/null; then
     gtimeout "$seconds" "$@"
   else
-    # Fallback: just run without timeout (safe - Claude sessions complete on their own)
-    "$@"
+    # Bash-native fallback: background the command, kill after timeout.
+    # Capture stdin to a temp file so the backgrounded process can read it
+    # (backgrounded commands lose access to the pipeline's stdin).
+    local stdin_file
+    stdin_file=$(mktemp)
+    cat > "$stdin_file"
+    "$@" < "$stdin_file" &
+    local cmd_pid=$!
+    rm -f "$stdin_file"
+    ( sleep "$seconds" && kill -TERM "$cmd_pid" 2>/dev/null ) &
+    local watchdog_pid=$!
+    wait "$cmd_pid" 2>/dev/null
+    local exit_code=$?
+    kill "$watchdog_pid" 2>/dev/null
+    wait "$watchdog_pid" 2>/dev/null
+    # If the process received SIGTERM, return 124 (same as GNU timeout).
+    # Note: this cannot distinguish our watchdog from other SIGTERM sources.
+    if [[ $exit_code -eq 143 ]]; then  # 143 = 128 + 15 (SIGTERM)
+      return 124
+    fi
+    return "$exit_code"
   fi
 }
 

package/ralph/verify/api.sh

@@ -140,6 +140,7 @@ run_frontend_smoke_test() {
   # 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)
+  test_url=$(_expand_config_vars "$test_url")
   if [[ -n "$test_url" ]]; then
     # testUrl can be full URL or just path
     if [[ "$test_url" =~ ^https?:// ]]; then

package/ralph/hooks/protect-prd.sh

@@ -1,30 +0,0 @@
-#!/usr/bin/env bash
-# protect-prd.sh - Protect prd.json from marking stories as passed
-# Hook: PreToolUse matcher: "Edit|Write"
-#
-# Allows: Most edits to prd.json (adding fields, fixing test steps, etc.)
-# Blocks: Edits that mark stories as "passes": true (Ralph handles this)
-
-set -euo pipefail
-
-INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')
-
-# Check if editing prd.json
-if [[ "$FILE_PATH" == *"prd.json"* ]]; then
-  # Get the new content being written
-  NEW_STRING=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""')
-
-  # Block if trying to set passes to true (Ralph handles story completion)
-  if echo "$NEW_STRING" | grep -qE '"passes"\s*:\s*true'; then
-    echo "BLOCKED: Cannot mark stories as passed. Ralph handles this after verification." >&2
-    exit 2  # Exit code 2 = blocking error
-  fi
-
-  # Allow all other prd.json edits (adding mcp, constraints, fixing testSteps, etc.)
-  echo '{"continue": true}'
-  exit 0
-fi
-
-# Allow all other edits
-echo '{"continue": true}'