agentic-loop 3.18.2 → 3.21.0

package/ralph/prd-check.sh

@@ -197,31 +197,19 @@ validate_prd() {
     fi
   fi
 
-  # Deprecation warnings for old root-level fields
+  # Auto-remove deprecated root-level fields (no longer used, safe to strip)
   local deprecated_fields=""
-  if jq -e '.techStack' "$prd_file" >/dev/null 2>&1; then
-    deprecated_fields+="techStack "
-  fi
-  if jq -e '.globalConstraints' "$prd_file" >/dev/null 2>&1; then
-    deprecated_fields+="globalConstraints "
-  fi
-  if jq -e '.originalContext' "$prd_file" >/dev/null 2>&1; then
-    deprecated_fields+="originalContext "
-  fi
-  if jq -e '.testing' "$prd_file" >/dev/null 2>&1; then
-    deprecated_fields+="testing "
-  fi
-  if jq -e '.architecture' "$prd_file" >/dev/null 2>&1; then
-    deprecated_fields+="architecture "
-  fi
-  if jq -e '.testUsers' "$prd_file" >/dev/null 2>&1; then
-    deprecated_fields+="testUsers "
-  fi
+  local deprecated_keys=("techStack" "globalConstraints" "originalContext" "testing" "architecture" "testUsers")
+  for key in "${deprecated_keys[@]}"; do
+    if jq -e ".$key" "$prd_file" >/dev/null 2>&1; then
+      deprecated_fields+="$key "
+    fi
+  done
   if [[ -n "$deprecated_fields" ]]; then
     echo ""
-    print_warning "Found deprecated root-level fields: $deprecated_fields"
-    echo "  These should be in each story instead. Regenerate with /prd."
-    echo ""
+    print_info "Removing deprecated root-level fields: $deprecated_fields"
+    update_json "$prd_file" \
+      'del(.techStack, .globalConstraints, .originalContext, .testing, .architecture, .testUsers)'
   fi
 
   # Validate API smoke test configuration in background (skip in fast/cached mode)
@@ -233,11 +221,23 @@ validate_prd() {
     api_check_pid=$!
   fi
 
+  # Validate batch assignments (warn, don't block)
+  local batch_errors batch_rc=0
+  batch_errors=$(validate_batch_assignments "$prd_file" 2>/dev/null) || batch_rc=$?
+  if [[ $batch_rc -ne 0 && -n "$batch_errors" ]]; then
+    echo ""
+    print_warning "Batch assignment issues:"
+    echo "$batch_errors" | while IFS= read -r line; do
+      [[ -n "$line" ]] && echo "    $line"
+    done
+    echo ""
+  fi
+
   # Replace hardcoded paths with config placeholders
   fix_hardcoded_paths "$prd_file" "$config"
 
   # Validate and fix individual stories
-  # dry_run flag — when "true", skip auto-fix
+  # dry_run flag — when "true", report issues but skip auto-fix
   _validate_and_fix_stories "$prd_file" "$dry_run" || return 1
 
   # Wait for background API health check and print its output
@@ -326,6 +326,107 @@ _validate_api_config() {
   return 0
 }
 
+# Check a single story for common issues
+# Outputs issue strings to stdout (one per line: "issue description")
+# $1: story_id  $2: prd_file
+_check_story_issues() {
+  local story_id="$1"
+  local prd_file="$2"
+
+  local story_type
+  story_type=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .type // "unknown"' "$prd_file")
+  local story_title
+  story_title=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .title // ""' "$prd_file")
+  local test_steps
+  test_steps=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testSteps // [] | join(" ")' "$prd_file")
+
+  # Backend must have curl tests
+  if [[ "$story_type" == "backend" ]] && [[ -n "$test_steps" ]] && ! echo "$test_steps" | grep -q "curl "; then
+    echo "backend needs curl tests"
+  fi
+
+  # Frontend must have tsc or playwright
+  if [[ "$story_type" == "frontend" ]] && [[ -n "$test_steps" ]] && ! echo "$test_steps" | grep -qE "(tsc --noEmit|playwright)"; then
+    echo "frontend needs tsc/playwright tests"
+  fi
+
+  # Backend needs apiContract
+  if [[ "$story_type" == "backend" ]]; then
+    local has_contract
+    has_contract=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .apiContract // empty' "$prd_file")
+    if [[ -z "$has_contract" || "$has_contract" == "null" ]]; then
+      echo "missing apiContract"
+    fi
+  fi
+
+  # Frontend needs testUrl, contextFiles, and mcp
+  if [[ "$story_type" == "frontend" ]]; then
+    local has_url
+    has_url=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testUrl // empty' "$prd_file")
+    [[ -z "$has_url" || "$has_url" == "null" ]] && echo "missing testUrl"
+
+    local context_files
+    context_files=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .contextFiles // [] | length' "$prd_file")
+    [[ "$context_files" == "0" ]] && echo "missing contextFiles"
+
+    local mcp_tools
+    mcp_tools=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .mcp // [] | length' "$prd_file")
+    [[ "$mcp_tools" == "0" ]] && echo "missing mcp (browser tools)"
+  fi
+
+  # Auth stories need security criteria
+  if echo "$story_title" | grep -qiE "(login|auth|password|register|signup|sign.?up)"; then
+    local criteria
+    criteria=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .acceptanceCriteria // [] | join(" ")' "$prd_file")
+    if ! echo "$criteria" | grep -qiE "(hash|bcrypt|sanitiz|inject|rate.?limit)"; then
+      echo "missing security criteria"
+    fi
+  fi
+
+  # List endpoints need pagination criteria
+  if echo "$story_title" | grep -qiE "(list|get all|fetch all|index)"; then
+    local criteria
+    criteria=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .acceptanceCriteria // [] | join(" ")' "$prd_file")
+    if ! echo "$criteria" | grep -qiE "(pagina|limit|page=|per.?page)"; then
+      echo "missing pagination criteria"
+    fi
+  fi
+
+  # API consumer needs camelCase transformation 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
+        echo "API consumer needs camelCase transformation note"
+      fi
+    fi
+  fi
+
+  # All testSteps are server-dependent
+  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
+      echo "all testSteps need a live server (add offline test: npm test, tsc --noEmit, pytest)"
+    fi
+  fi
+}
+
 # Validate individual stories and auto-fix with Claude if needed
 # $1: prd_file  $2: optional "dry_run" — when "true", report issues but skip auto-fix
 _validate_and_fix_stories() {
@@ -339,7 +440,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 cnt_frontend_mcp=0
   local cnt_auth_security=0 cnt_list_pagination=0 cnt_prose_steps=0
-  local cnt_naming_convention=0 cnt_bare_pytest=0
+  local cnt_naming_convention=0 cnt_bare_pytest=0 cnt_bare_python=0
   local cnt_server_only=0
   local cnt_custom=0
 
@@ -356,156 +457,64 @@ _validate_and_fix_stories() {
     [[ -z "$story_id" ]] && continue
 
     local story_issues=""
-    local story_type
-    story_type=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .type // "unknown"' "$prd_file")
-    local story_title
-    story_title=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .title // ""' "$prd_file")
-
-    # Check 1: testSteps quality
     local test_steps
     test_steps=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testSteps // [] | join(" ")' "$prd_file")
 
+    # Checks unique to full validation: empty testSteps, prose detection, bare pytest
     if [[ -z "$test_steps" ]]; then
       story_issues+="no testSteps, "
       cnt_no_tests=$((cnt_no_tests + 1))
     else
-      # Check test steps are executable commands, not prose
-      # Good: "curl -s POST /api/login | jq -e '.token'"
-      # Bad: "Verify the user can log in successfully"
       if ! echo "$test_steps" | grep -qE "(curl |npm |pytest|go test|cargo test|mix test|rails test|bundle exec|python |node |sh |bash |\| jq)"; then
         story_issues+="testSteps look like prose (need executable commands), "
         cnt_prose_steps=$((cnt_prose_steps + 1))
       fi
 
-      # Type-specific checks
-      if [[ "$story_type" == "backend" ]]; then
-        # Backend must have curl, not just npm test/pytest
-        if ! echo "$test_steps" | grep -q "curl "; then
-          story_issues+="backend needs curl tests, "
-          cnt_backend_curl=$((cnt_backend_curl + 1))
-        fi
-      elif [[ "$story_type" == "frontend" ]]; then
-        # Frontend must have tsc or playwright
-        if ! echo "$test_steps" | grep -qE "(tsc --noEmit|playwright)"; then
-          story_issues+="frontend needs tsc/playwright tests, "
-          cnt_frontend_tsc=$((cnt_frontend_tsc + 1))
-        fi
-      fi
-
-      # Check for bare pytest/python in projects using uv/poetry/pipenv
       local py_runner
       py_runner=$(detect_python_runner ".")
       if [[ -n "$py_runner" ]]; then
-        # Project uses a Python runner - check for bare pytest/python commands
-        # Match: "pytest " at start or after space/semicolon, but not preceded by "run "
         if echo "$test_steps" | grep -qE '(^|[; ])pytest ' && ! echo "$test_steps" | grep -qE "(uv run|poetry run|pipenv run) pytest"; then
           story_issues+="use '$py_runner pytest' not bare 'pytest', "
           cnt_bare_pytest=$((cnt_bare_pytest + 1))
         fi
       fi
-    fi
-
-    # Check 2: Backend needs apiContract
-    if [[ "$story_type" == "backend" ]]; then
-      local has_contract
-      has_contract=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .apiContract // empty' "$prd_file")
-      if [[ -z "$has_contract" || "$has_contract" == "null" ]]; then
-        story_issues+="missing apiContract, "
-        cnt_backend_contract=$((cnt_backend_contract + 1))
-      fi
-    fi
-
-    # Check 3: Frontend needs testUrl, contextFiles, and mcp
-    if [[ "$story_type" == "frontend" ]]; then
-      local has_url
-      has_url=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testUrl // empty' "$prd_file")
-      if [[ -z "$has_url" || "$has_url" == "null" ]]; then
-        story_issues+="missing testUrl, "
-        cnt_frontend_url=$((cnt_frontend_url + 1))
-      fi
-
-      local context_files
-      context_files=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .contextFiles // [] | length' "$prd_file")
-      if [[ "$context_files" == "0" ]]; then
-        story_issues+="missing contextFiles, "
-        cnt_frontend_context=$((cnt_frontend_context + 1))
-      fi
 
-      # Frontend must have mcp tools for browser verification
-      local mcp_tools
-      mcp_tools=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .mcp // [] | length' "$prd_file")
-      if [[ "$mcp_tools" == "0" ]]; then
-        story_issues+="missing mcp (browser tools), "
-        cnt_frontend_mcp=$((cnt_frontend_mcp + 1))
-      fi
-    fi
-
-    # Check 4: Auth stories need security criteria
-    if echo "$story_title" | grep -qiE "(login|auth|password|register|signup|sign.?up)"; then
-      local criteria
-      criteria=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .acceptanceCriteria // [] | join(" ")' "$prd_file")
-      if ! echo "$criteria" | grep -qiE "(hash|bcrypt|sanitiz|inject|rate.?limit)"; then
-        story_issues+="missing security criteria, "
-        cnt_auth_security=$((cnt_auth_security + 1))
-      fi
-    fi
-
-    # Check 5: List endpoints need scale criteria
-    # Note: "search" excluded - search endpoints often return single/filtered results
-    if echo "$story_title" | grep -qiE "(list|get all|fetch all|index)"; then
-      local criteria
-      criteria=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .acceptanceCriteria // [] | join(" ")' "$prd_file")
-      if ! echo "$criteria" | grep -qiE "(pagina|limit|page=|per.?page)"; then
-        story_issues+="missing pagination criteria, "
-        cnt_list_pagination=$((cnt_list_pagination + 1))
-      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
-
-    # Check 9: Stories where ALL testSteps depend on a live server
-    # If every testStep is a curl/wget/httpie command and none are offline
-    # (npm test, pytest, tsc, playwright, cargo test, go test, etc.),
-    # the story will always fail without a running server.
-    if [[ -n "$test_steps" ]]; then
-      local has_offline_step=false
-      local has_server_step=false
-      local step_list
-      step_list=$(jq -r --arg id "$story_id" \
-        '.stories[] | select(.id==$id) | .testSteps[]?' "$prd_file")
-
-      while IFS= read -r single_step; do
-        [[ -z "$single_step" ]] && continue
-        if echo "$single_step" | grep -qE "^(curl |wget |http )"; then
-          has_server_step=true
+      # Check for bare 'python' (fails on macOS which only has python3)
+      if echo "$test_steps" | grep -qE '(^|[;&| ])python ' && ! echo "$test_steps" | grep -qE "(uv run|poetry run|pipenv run|python3) "; then
+        if [[ -n "$py_runner" ]]; then
+          story_issues+="use '$py_runner python' not bare 'python', "
         else
-          has_offline_step=true
+          story_issues+="use 'python3' not bare 'python' (macOS has no 'python'), "
         fi
-      done <<< "$step_list"
-
-      if [[ "$has_server_step" == "true" && "$has_offline_step" == "false" ]]; then
-        story_issues+="all testSteps need a live server (add offline test: npm test, tsc --noEmit, pytest), "
-        cnt_server_only=$((cnt_server_only + 1))
+        cnt_bare_python=$((cnt_bare_python + 1))
       fi
     fi
 
+    # Shared checks (same as validate_stories_quick)
+    local shared_issues
+    shared_issues=$(_check_story_issues "$story_id" "$prd_file")
+    while IFS= read -r issue; do
+      [[ -z "$issue" ]] && continue
+      story_issues+="$issue, "
+      # Count by category for summary display
+      case "$issue" in
+        "backend needs curl tests") cnt_backend_curl=$((cnt_backend_curl + 1)) ;;
+        "frontend needs tsc/playwright tests") cnt_frontend_tsc=$((cnt_frontend_tsc + 1)) ;;
+        "missing apiContract") cnt_backend_contract=$((cnt_backend_contract + 1)) ;;
+        "missing testUrl") cnt_frontend_url=$((cnt_frontend_url + 1)) ;;
+        "missing contextFiles") cnt_frontend_context=$((cnt_frontend_context + 1)) ;;
+        "missing mcp (browser tools)") cnt_frontend_mcp=$((cnt_frontend_mcp + 1)) ;;
+        "missing security criteria") cnt_auth_security=$((cnt_auth_security + 1)) ;;
+        "missing pagination criteria") cnt_list_pagination=$((cnt_list_pagination + 1)) ;;
+        "API consumer needs camelCase transformation note") cnt_naming_convention=$((cnt_naming_convention + 1)) ;;
+        "all testSteps need a live server"*) cnt_server_only=$((cnt_server_only + 1)) ;;
+      esac
+    done <<< "$shared_issues"
+
     # Snapshot built-in issues before custom checks append
     local builtin_story_issues="$story_issues"
 
-    # Check 8: User-defined custom checks (.ralph/checks/prd/)
+    # 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")
@@ -546,7 +555,8 @@ _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_naming_convention -gt 0 ]] && echo "    ${cnt_naming_convention}x API consumer: add camelCase transformation note"
-    [[ $cnt_bare_pytest -gt 0 ]] && echo "    ${cnt_bare_pytest}x use 'uv run pytest' not bare 'pytest'"
+    [[ $cnt_bare_pytest -gt 0 ]] && echo "    ${cnt_bare_pytest}x use '${py_runner:-python3} pytest' not bare 'pytest'"
+    [[ $cnt_bare_python -gt 0 ]] && echo "    ${cnt_bare_python}x use 'python3' not bare 'python' (macOS compatibility)"
     [[ $cnt_server_only -gt 0 ]] && echo "    ${cnt_server_only}x all testSteps need live server (add offline fallback)"
     [[ $cnt_custom -gt 0 ]] && echo "    ${cnt_custom} stories with custom check issues"
 
@@ -662,8 +672,8 @@ _group_issues_by_story() {
 }
 
 # Apply instant mechanical fixes using jq (no LLM needed)
-# Fixes: missing mcp, bare pytest, missing camelCase note, missing migration prerequisites,
-# server-only testSteps
+# Fixes: missing mcp, bare pytest, bare python (macOS compat), missing camelCase note,
+# missing migration prerequisites, server-only testSteps
 _apply_mechanical_fixes() {
   local prd_file="$1"
   local fixed=0
@@ -701,6 +711,19 @@ _apply_mechanical_fixes() {
       fi
     fi
 
+    # Fix: Bare python → prefix with runner or replace with python3 (macOS compat)
+    local test_steps_for_python
+    test_steps_for_python=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testSteps // [] | join("\n")' "$prd_file")
+    if echo "$test_steps_for_python" | grep -qE '(^|[;&| ])python ' && ! echo "$test_steps_for_python" | grep -qE "(uv run|poetry run|pipenv run|python3) "; then
+      if [[ -n "$py_runner" ]]; then
+        update_json "$prd_file" --arg id "$story_id" --arg runner "$py_runner" \
+          '(.stories[] | select(.id==$id) | .testSteps) |= [.[]? | gsub("(?<pre>^|[;&| ])python "; "\(.pre)\($runner) python ")]' && fixed=$((fixed + 1))
+      else
+        update_json "$prd_file" --arg id "$story_id" \
+          '(.stories[] | select(.id==$id) | .testSteps) |= [.[]? | gsub("(?<pre>^|[;&| ])python "; "\(.pre)python3 ")]' && fixed=$((fixed + 1))
+      fi
+    fi
+
     # Fix: Frontend/general API consumer missing camelCase note
     if [[ "$story_type" == "frontend" || "$story_type" == "general" ]]; then
       local story_desc
@@ -910,100 +933,18 @@ validate_stories_quick() {
   local prd_file="$1"
   local issues=""
 
-  # Only check incomplete stories
   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")
-    local story_title
-    story_title=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .title // ""' "$prd_file")
-    local test_steps
-    test_steps=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testSteps // [] | join(" ")' "$prd_file")
-
-    # Check 1: testSteps quality
-    if [[ "$story_type" == "backend" ]] && ! echo "$test_steps" | grep -q "curl "; then
-      issues+="$story_id: missing curl tests, "
-    fi
-    if [[ "$story_type" == "frontend" ]] && ! echo "$test_steps" | grep -qE "(tsc --noEmit|playwright)"; then
-      issues+="$story_id: missing tsc/playwright tests, "
-    fi
-
-    # Check 2: Backend needs apiContract
-    if [[ "$story_type" == "backend" ]]; then
-      local has_contract
-      has_contract=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .apiContract // empty' "$prd_file")
-      if [[ -z "$has_contract" || "$has_contract" == "null" ]]; then
-        issues+="$story_id: missing apiContract, "
-      fi
-    fi
-
-    # Check 3: Frontend needs testUrl, contextFiles, and mcp
-    if [[ "$story_type" == "frontend" ]]; then
-      local has_url
-      has_url=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testUrl // empty' "$prd_file")
-      [[ -z "$has_url" || "$has_url" == "null" ]] && issues+="$story_id: missing testUrl, "
-
-      local context_files
-      context_files=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .contextFiles // [] | length' "$prd_file")
-      [[ "$context_files" == "0" ]] && issues+="$story_id: missing contextFiles, "
-
-      local mcp_tools
-      mcp_tools=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .mcp // [] | length' "$prd_file")
-      [[ "$mcp_tools" == "0" ]] && issues+="$story_id: missing mcp, "
-    fi
-
-    # Check 4: Auth stories need security criteria
-    if echo "$story_title" | grep -qiE "(login|auth|password|register|signup|sign.?up)"; then
-      local criteria
-      criteria=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .acceptanceCriteria // [] | join(" ")' "$prd_file")
-      if ! echo "$criteria" | grep -qiE "(hash|bcrypt|sanitiz|inject|rate.?limit)"; then
-        issues+="$story_id: missing security criteria, "
-      fi
-    fi
-
-    # Check 5: List endpoints need scale criteria
-    if echo "$story_title" | grep -qiE "(list|get all|fetch all|index)"; then
-      local criteria
-      criteria=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .acceptanceCriteria // [] | join(" ")' "$prd_file")
-      if ! echo "$criteria" | grep -qiE "(pagina|limit|page=|per.?page)"; then
-        issues+="$story_id: missing pagination criteria, "
-      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
-
-    # Check 8: All testSteps are server-dependent
-    if [[ -n "$test_steps" ]]; then
-      local has_offline=false has_server=false
-      local steps
-      steps=$(jq -r --arg id "$story_id" \
-        '.stories[] | select(.id==$id) | .testSteps[]?' "$prd_file")
-      while IFS= read -r s; do
-        [[ -z "$s" ]] && continue
-        if echo "$s" | grep -qE "^(curl |wget |http )"; then
-          has_server=true
-        else
-          has_offline=true
-        fi
-      done <<< "$steps"
-      [[ "$has_server" == "true" && "$has_offline" == "false" ]] && \
-        issues+="$story_id: all testSteps need live server, "
-    fi
+    local story_issues
+    story_issues=$(_check_story_issues "$story_id" "$prd_file")
+    while IFS= read -r issue; do
+      [[ -z "$issue" ]] && continue
+      issues+="$story_id: $issue, "
+    done <<< "$story_issues"
   done <<< "$story_ids"
 
   echo "$issues"

package/ralph/prd.sh

@@ -69,9 +69,10 @@ ralph_prd() {
   echo "Claude will ask clarifying questions to refine the PRD."
   echo ""
 
-  # Get testUrlBase from config (default to localhost:3000)
+  # Get frontend URL from config
   local test_url_base
-  test_url_base=$(get_config "testUrlBase" "http://localhost:3000")
+  test_url_base=$(get_config '.urls.frontend' "")
+  [[ -z "$test_url_base" ]] && test_url_base=$(get_config '.playwright.baseUrl' "http://localhost:3000")
 
   # Create the PRD generation prompt using printf to avoid heredoc issues
   local prompt_file
@@ -130,6 +131,8 @@ ralph_prd() {
   printf '%s\n' "GOOD: cd frontend && npx tsc --noEmit" >> "$prompt_file"
   printf '%s\n' "GOOD: npx playwright test tests/e2e/dashboard.spec.ts" >> "$prompt_file"
   printf '%s\n' "GOOD: npx playwright test --grep 'login flow'" >> "$prompt_file"
+  printf '%s\n' "GOOD: python3 -m pytest tests/ (use python3, NOT python — macOS has no 'python')" >> "$prompt_file"
+  printf '%s\n' "GOOD: uv run pytest tests/ (when project uses uv)" >> "$prompt_file"
   printf '\n%s\n' "For UI/visual checks, use Playwright tests that can verify:" >> "$prompt_file"
   printf '%s\n' "- Element visibility and positioning" >> "$prompt_file"
   printf '%s\n' "- Console errors (no errors in DevTools)" >> "$prompt_file"

package/ralph/setup/quick-setup.sh

@@ -96,22 +96,8 @@ show_completion_with_tour() {
   echo ""
 }
 
-detect_project_type() {
-  # Django + React (AllThrive pattern)
-  [[ -d "frontend" && -d "core" ]] && echo "django-react" && return
-  # Django alone
-  [[ -f "manage.py" ]] && echo "django" && return
-  # Rust
-  [[ -f "Cargo.toml" ]] && echo "rust" && return
-  # Go
-  [[ -f "go.mod" ]] && echo "go" && return
-  # Python
-  [[ -f "pyproject.toml" || -f "requirements.txt" ]] && echo "python" && return
-  # Node/TypeScript
-  [[ -f "package.json" ]] && echo "node" && return
-  # Minimal/unknown
-  echo "minimal"
-}
+# Source shared detect_project_type from utils.sh
+source "$VIBE_ROOT/ralph/utils.sh"
 
 install_claude_skills() {
   echo -e "  ${CYAN}Installing Claude skills...${NC}"