agentic-loop 3.14.2 → 3.16.2

package/ralph/prd-check.sh

@@ -50,6 +50,11 @@
 #     - Has prerequisites array with DB reset command
 #     - Prevents infinite retries on schema mismatch errors
 #
+#   CUSTOM CHECKS (.ralph/checks/prd/ or ~/.config/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)
+#
 # API configuration validation:
 #   - If api.baseUrl configured, checks health endpoint is reachable
 #   - Warns if default /health returns 404 (misconfigured healthEndpoint)
@@ -75,6 +80,9 @@
 #   .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)
+#   .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
 #
 # ============================================================================
 # USAGE
@@ -184,6 +192,33 @@ validate_prd() {
     fi
   fi
 
+  # Deprecation warnings for old root-level fields
+  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
+  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 ""
+  fi
+
   # Validate API smoke test configuration
   _validate_api_config "$config"
 
@@ -191,7 +226,8 @@ validate_prd() {
   fix_hardcoded_paths "$prd_file" "$config"
 
   # Validate and fix individual stories
-  _validate_and_fix_stories "$prd_file" || return 1
+  # $2 is optional dry_run flag — when "true", skip auto-fix
+  _validate_and_fix_stories "$prd_file" "${2:-}" || return 1
 
   return 0
 }
@@ -274,8 +310,10 @@ _validate_api_config() {
 }
 
 # 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() {
   local prd_file="$1"
+  local dry_run="${2:-false}"
   local needs_fix=false
   local issues=""
   local story_count=0
@@ -285,9 +323,13 @@ _validate_and_fix_stories() {
   local cnt_frontend_tsc=0 cnt_frontend_url=0 cnt_frontend_context=0 cnt_frontend_mcp=0
   local cnt_auth_security=0 cnt_list_pagination=0 cnt_prose_steps=0
   local cnt_migration_prereq=0 cnt_naming_convention=0 cnt_bare_pytest=0
+  local cnt_custom=0
 
   echo "  Checking test coverage..."
 
+  # Truncate custom check log per validation pass (name says "last", keep only current run)
+  : > "$RALPH_DIR/last_custom_check.log"
+
   # Only validate incomplete stories (skip stories that already passed)
   local story_ids
   story_ids=$(jq -r '.stories[] | select(.passes != true) | .id' "$prd_file" 2>/dev/null)
@@ -429,12 +471,31 @@ _validate_and_fix_stories() {
       fi
     fi
 
+    # 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
+      local story_json
+      story_json=$(jq --arg id "$story_id" '.stories[] | select(.id==$id)' "$prd_file")
+      local custom_output
+      custom_output=$(_run_custom_prd_checks "$story_id" "$prd_file" "$story_json")
+      if [[ -n "$custom_output" ]]; then
+        story_issues+="$custom_output"
+        cnt_custom=$((cnt_custom + 1))
+      fi
+    fi
+
     # Track this story if it has issues
     if [[ -n "$story_issues" ]]; then
       needs_fix=true
       story_count=$((story_count + 1))
-      issues+="$story_id: ${story_issues%%, }
+      # Only include built-in issues in auto-fix context
+      # Custom issues are user-defined rules that Claude auto-fix can't meaningfully address
+      if [[ -n "$builtin_story_issues" ]]; then
+        issues+="$story_id: ${builtin_story_issues%%, }
 "
+      fi
     fi
   done <<< "$story_ids"
 
@@ -456,6 +517,12 @@ _validate_and_fix_stories() {
     [[ $cnt_migration_prereq -gt 0 ]] && echo "    ${cnt_migration_prereq}x migration: add prerequisites (DB reset)"
     [[ $cnt_naming_convention -gt 0 ]] && echo "    ${cnt_naming_convention}x API consumer: add camelCase transformation note"
     [[ $cnt_bare_pytest -gt 0 ]] && echo "    ${cnt_bare_pytest}x use 'uv run pytest' not bare 'pytest'"
+    [[ $cnt_custom -gt 0 ]] && echo "    ${cnt_custom} stories with custom check issues"
+
+    # Skip auto-fix in dry-run mode
+    if [[ "$dry_run" == "true" ]]; then
+      return 0
+    fi
 
     # Check if Claude is available for auto-fix
     if command -v claude &>/dev/null; then
@@ -471,6 +538,55 @@ _validate_and_fix_stories() {
   return 0
 }
 
+# Run user-defined custom PRD checks for a story
+# Stdin to script: full story JSON | $1: story_id | $2: prd_file
+# Output: issues on stdout (empty = no issues)
+_run_custom_prd_checks() {
+  local story_id="$1"
+  local prd_file="$2"
+  local story_json="$3"
+  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"
+      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
+  done
+
+  echo "$custom_issues"
+}
+
 # Optimize story test coverage using Claude
 _fix_stories_with_claude() {
   local prd_file="$1"
@@ -499,7 +615,7 @@ RULES:
 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 from originalContext)
+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+)
@@ -512,6 +628,8 @@ RULES:
    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.
 
 CURRENT PRD:
 $(cat "$prd_file")
@@ -674,3 +792,53 @@ validate_stories_quick() {
 
   echo "$issues"
 }
+
+# CLI entry point for on-demand PRD validation
+# Usage: ralph prd-check [--dry-run] [prd-file]
+ralph_prd_check() {
+  local dry_run=false
+  local prd_file=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --dry-run) dry_run=true; shift ;;
+      *) prd_file="$1"; shift ;;
+    esac
+  done
+
+  prd_file="${prd_file:-$RALPH_DIR/prd.json}"
+
+  if [[ ! -f "$prd_file" ]]; then
+    print_error "PRD not found: $prd_file"
+    echo "Generate one with: ralph prd  or  /prd"
+    return 1
+  fi
+
+  echo ""
+  print_info "=== PRD Validation ==="
+  echo ""
+
+  if [[ "$dry_run" == "true" ]]; then
+    # Dry run: validate structure + show issues without auto-fix
+    validate_prd "$prd_file" "true"
+    local rc=$?
+    local remaining
+    remaining=$(validate_stories_quick "$prd_file")
+    if [[ -n "$remaining" ]]; then
+      echo ""
+      echo "  Remaining issues:"
+      echo "$remaining" | sed 's/^/    /'
+    fi
+    return $rc
+  else
+    if validate_prd "$prd_file"; then
+      echo ""
+      print_success "PRD validation passed!"
+      return 0
+    else
+      echo ""
+      print_error "PRD validation failed"
+      return 1
+    fi
+  fi
+}

package/ralph/prd.sh

@@ -96,43 +96,18 @@ ralph_prd() {
   printf '%s\n' '    "branch": "feature/feature-name",' >> "$prompt_file"
   printf '%s\n' '    "status": "pending"' >> "$prompt_file"
   printf '%s\n' '  },' >> "$prompt_file"
-  printf '%s\n' '  "originalContext": "PASTE THE FULL ORIGINAL NOTES/DESCRIPTION HERE - this preserves intent for Claude during implementation",' >> "$prompt_file"
   printf '%s\n' '  "metadata": {' >> "$prompt_file"
-  printf '%s\n' '    "security": ["list of security requirements"],' >> "$prompt_file"
-  printf '%s\n' '    "scaling": ["list of scaling concerns"],' >> "$prompt_file"
-  printf '%s\n' '    "relatedFeatures": ["list of related features"],' >> "$prompt_file"
+  printf '%s\n' '    "createdAt": "ISO timestamp",' >> "$prompt_file"
   printf '%s\n' '    "estimatedStories": 5,' >> "$prompt_file"
   printf '%s\n' '    "complexity": "low|medium|high"' >> "$prompt_file"
   printf '%s\n' '  },' >> "$prompt_file"
-  printf '%s\n' '  "scalability": {' >> "$prompt_file"
-  printf '%s\n' '    "expectedScale": "100s | 1000s | 10000s+ users",' >> "$prompt_file"
-  printf '%s\n' '    "pagination": "cursor | offset | none",' >> "$prompt_file"
-  printf '%s\n' '    "caching": "none | in-memory | redis",' >> "$prompt_file"
-  printf '%s\n' '    "rateLimiting": "if needed, requests per minute"' >> "$prompt_file"
-  printf '%s\n' '  },' >> "$prompt_file"
-  printf '%s\n' '  "architecture": {' >> "$prompt_file"
-  printf '%s\n' '    "directories": {' >> "$prompt_file"
-  printf '%s\n' '      "components": "src/components/{feature}/",' >> "$prompt_file"
-  printf '%s\n' '      "api": "src/api/",' >> "$prompt_file"
-  printf '%s\n' '      "types": "src/types/",' >> "$prompt_file"
-  printf '%s\n' '      "scripts": "scripts/",' >> "$prompt_file"
-  printf '%s\n' '      "docs": "docs/"' >> "$prompt_file"
-  printf '%s\n' '    },' >> "$prompt_file"
-  printf '%s\n' '    "patterns": {' >> "$prompt_file"
-  printf '%s\n' '      "reuse": ["existing components/utils to use"],' >> "$prompt_file"
-  printf '%s\n' '      "follow": ["existing patterns to match"]' >> "$prompt_file"
-  printf '%s\n' '    },' >> "$prompt_file"
-  printf '%s\n' '    "principles": {' >> "$prompt_file"
-  printf '%s\n' '      "maxFileLines": 300,' >> "$prompt_file"
-  printf '%s\n' '      "singleResponsibility": true' >> "$prompt_file"
-  printf '%s\n' '    },' >> "$prompt_file"
-  printf '%s\n' '    "doNotCreate": ["things that already exist"]' >> "$prompt_file"
-  printf '%s\n' '  },' >> "$prompt_file"
   printf '%s\n' '  "stories": [' >> "$prompt_file"
   printf '%s\n' '    {' >> "$prompt_file"
   printf '%s\n' '      "id": "TASK-001",' >> "$prompt_file"
   printf '%s\n' '      "title": "Story title",' >> "$prompt_file"
   printf '%s\n' '      "passes": false,' >> "$prompt_file"
+  printf '%s\n' '      "techStack": {"backend": "detected tech", "frontend": "detected tech"},' >> "$prompt_file"
+  printf '%s\n' '      "constraints": ["relevant rules for this story"],' >> "$prompt_file"
   printf '%s\n' "      \"testUrl\": \"${test_url_base}/path/to/test\"," >> "$prompt_file"
   printf '%s\n' '      "files": {' >> "$prompt_file"
   printf '%s\n' '        "create": ["paths to new files"],' >> "$prompt_file"
@@ -142,6 +117,7 @@ ralph_prd() {
   printf '%s\n' '      "acceptanceCriteria": ["AC 1", "AC 2"],' >> "$prompt_file"
   printf '%s\n' '      "errorHandling": ["what happens on failure"],' >> "$prompt_file"
   printf '%s\n' '      "testSteps": ["executable shell commands only"],' >> "$prompt_file"
+  printf '%s\n' '      "contextFiles": ["docs/ideas/feature.md"],' >> "$prompt_file"
   printf '%s\n' '      "notes": ""' >> "$prompt_file"
   printf '%s\n' '    }' >> "$prompt_file"
   printf '%s\n' '  ]' >> "$prompt_file"
@@ -186,10 +162,11 @@ ralph_prd() {
   printf '%s\n' '- If complexity is "high" AND > 5 stories, MUST split' >> "$prompt_file"
   printf '%s\n' "- Each story should be completable in one Claude session (~10 min)" >> "$prompt_file"
   printf '\n%s\n' "If splitting is needed, generate ONLY phase 1 and note deferred items." >> "$prompt_file"
-  printf '\n%s\n' "## Original Context - IMPORTANT" >> "$prompt_file"
-  printf '\n%s\n' "Copy the FULL original feature notes into the 'originalContext' field verbatim." >> "$prompt_file"
-  printf '%s\n' "This preserves the user's original intent for Claude during implementation." >> "$prompt_file"
-  printf '%s\n' "Do NOT summarize - include the complete text." >> "$prompt_file"
+  printf '\n%s\n' "## Context in Stories - IMPORTANT" >> "$prompt_file"
+  printf '\n%s\n' "Each story must be self-contained. Include the idea file path in each story's 'contextFiles' array." >> "$prompt_file"
+  printf '%s\n' "Include 'techStack' with the relevant subset of detected technologies for that story." >> "$prompt_file"
+  printf '%s\n' "Include 'constraints' with any rules that apply to that specific story." >> "$prompt_file"
+  printf '%s\n' "Do NOT put techStack, constraints, or context at the PRD root level." >> "$prompt_file"
   printf '\n%s\n' "## Output" >> "$prompt_file"
   printf '\n%s\n' "After questions are answered, output the prd.json content between these exact markers:" >> "$prompt_file"
   printf '%s\n' "--- BEGIN PRD.JSON ---" >> "$prompt_file"

package/ralph/setup.sh

@@ -94,6 +94,7 @@ ralph_setup() {
 
   # Run all setup steps
   setup_ralph_dir "$pkg_root"
+  setup_custom_checks
   setup_gitignore
   setup_claude_hooks "$pkg_root"
   setup_slash_commands "$pkg_root"
@@ -247,6 +248,24 @@ setup_ralph_dir() {
   fi
 }
 
+# Set up custom PRD checks directory
+setup_custom_checks() {
+  local checks_dir=".ralph/checks/prd"
+
+  # Skip if directory already exists
+  if [[ -d "$checks_dir" ]]; then
+    local count
+    count=$(ls -1 "$checks_dir"/check-* 2>/dev/null | wc -l | tr -d ' ')
+    if [[ "$count" -gt 0 ]]; then
+      echo "  Custom PRD checks: $count script(s) in $checks_dir/"
+    fi
+    return 0
+  fi
+
+  mkdir -p "$checks_dir"
+  echo "  Created $checks_dir/ (add custom check scripts here)"
+}
+
 # Ensure .gitignore has necessary patterns
 setup_gitignore() {
   local patterns=(

package/templates/checks/prd/check-example.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+#
+# Example custom PRD check for Ralph
+#
+# Place in: .ralph/checks/prd/  (project) or ~/.config/ralph/checks/prd/ (global)
+# Must be executable: chmod +x check-example.sh
+#
+# Interface:
+#   stdin  = story JSON object
+#   $1     = story ID
+#   $2     = PRD file path
+#   stdout = issue descriptions, one per line (empty = pass)
+#
+# Disable: {"checks": {"custom": {"check-example": false}}}
+
+# story_id="$1"  # available if you need the story ID
+# prd_file="$2"  # available if you need full PRD context
+story_json=$(cat)
+
+# Example: require all stories to have a description field
+has_description=$(echo "$story_json" | jq -r '.description // empty')
+if [[ -z "$has_description" ]]; then
+  echo "missing description field"
+fi

package/templates/prd-example.json

@@ -6,34 +6,9 @@
     "status": "pending"
   },
 
-  "originalContext": "docs/ideas/auth.md",
-
-  "techStack": {
-    "frontend": "React",
-    "backend": "Node.js",
-    "database": "PostgreSQL"
-  },
-
-  "testing": {
-    "approach": "TDD",
-    "unit": {
-      "frontend": "vitest",
-      "backend": "jest"
-    },
-    "integration": "playwright",
-    "e2e": "playwright"
-  },
-
-  "globalConstraints": [
-    "All API calls must have error handling",
-    "Use existing UI components from src/components/ui",
-    "Never store passwords in plain text",
-    "Sanitize all user input before database operations"
-  ],
-
   "metadata": {
     "createdAt": "2026-01-27T10:00:00Z",
-    "estimatedStories": 2,
+    "estimatedStories": 3,
     "complexity": "medium"
   },
 
@@ -45,6 +20,17 @@
       "priority": 1,
       "passes": false,
 
+      "techStack": {
+        "backend": "Node.js",
+        "database": "PostgreSQL"
+      },
+
+      "constraints": [
+        "All API calls must have error handling",
+        "Never store passwords in plain text",
+        "Sanitize all user input before database operations"
+      ],
+
       "files": {
         "create": ["src/api/users.ts", "src/api/users.test.ts"],
         "modify": ["src/api/index.ts"],
@@ -69,6 +55,7 @@
       "testing": {
         "types": ["unit", "integration"],
         "approach": "TDD",
+        "runner": "jest",
         "files": {
           "unit": ["src/api/users.test.ts"]
         }
@@ -86,6 +73,15 @@
         "response": {"id": "string", "email": "string"}
       },
 
+      "testUsers": {
+        "admin": {"email": "admin@test.com", "password": "test123"},
+        "user": {"email": "user@test.com", "password": "test123"}
+      },
+
+      "contextFiles": [
+        "docs/ideas/auth.md"
+      ],
+
       "notes": "SECURITY: Use bcrypt with cost 10+. Never log passwords. Validate email format server-side even if validated client-side.",
       "dependsOn": []
     },
@@ -96,6 +92,14 @@
       "priority": 2,
       "passes": false,
 
+      "techStack": {
+        "frontend": "React"
+      },
+
+      "constraints": [
+        "Use existing UI components from src/components/ui"
+      ],
+
       "files": {
         "create": ["src/components/RegisterForm.tsx", "src/components/RegisterForm.test.tsx"],
         "modify": ["src/pages/index.tsx"],
@@ -122,6 +126,7 @@
       "testing": {
         "types": ["unit", "e2e"],
         "approach": "TDD",
+        "runner": "vitest",
         "files": {
           "unit": ["src/components/RegisterForm.test.tsx"],
           "e2e": ["tests/e2e/register.spec.ts"]
@@ -152,6 +157,15 @@
       "priority": 3,
       "passes": false,
 
+      "techStack": {
+        "backend": "Node.js",
+        "database": "PostgreSQL"
+      },
+
+      "constraints": [
+        "All API calls must have error handling"
+      ],
+
       "files": {
         "create": [],
         "modify": ["src/api/users.ts"],
@@ -176,6 +190,7 @@
       "testing": {
         "types": ["integration"],
         "approach": "TDD",
+        "runner": "jest",
         "files": {}
       },
 
@@ -190,6 +205,10 @@
         "response": {"data": "User[]", "total": "number", "page": "number", "limit": "number"}
       },
 
+      "contextFiles": [
+        "docs/ideas/auth.md"
+      ],
+
       "notes": "SCALE: Always paginate list endpoints. Enforce max limit to prevent memory issues. Add database index for sort column.",
       "dependsOn": ["TASK-001"]
     }