agentic-loop 3.7.3 → 3.8.0

package/.claude/commands/idea.md

@@ -44,13 +44,25 @@ Help the user flesh out the idea through conversation:
 
 1. **Understand the goal** - What problem does this solve? Who benefits?
 2. **Explore the codebase** - Use Glob/Grep/Read to understand what exists and what patterns to follow
-3. **Ask clarifying questions** - Up to 5 questions about:
-   - Scope boundaries (what's in/out)
-   - User experience (what does the user see/do)
-   - Edge cases (what could go wrong)
-   - Dependencies (what does this touch)
-   - Security/permissions (who can do what)
-   - Scale (how many users/items/requests?)
+3. **Ask clarifying questions** about:
+
+**Scope & UX:**
+- What's in scope vs out of scope?
+- What does the user see/do? (ask for mockup if UI)
+- What are the edge cases?
+
+**Security (IMPORTANT - ask if feature involves):**
+- Authentication: Who can access this? Login required?
+- Passwords: How stored? (must be hashed, never plain text)
+- User input: What validation needed? (prevent injection)
+- Sensitive data: What should NEVER be in API responses?
+- Rate limiting: Should this be rate limited? (login attempts, API calls)
+
+**Scale (IMPORTANT - ask if feature involves lists/data):**
+- How many items expected? (10s, 1000s, millions?)
+- Pagination needed? What's the max per page?
+- Caching needed? How fresh must data be?
+- Database indexes: What will be queried/sorted frequently?
 
 ### Step 3: Summarize Before Writing
 
@@ -107,9 +119,25 @@ Once the user confirms, write the idea file:
    ### Do NOT Create
    - List things that already exist (avoid duplication)
 
-   ## Technical Notes
-   - Dependencies
-   - Security considerations
+   ## Security Requirements
+   - **Authentication**: Who can access? Login required?
+   - **Password handling**: Must be hashed with bcrypt (cost 10+), never in responses
+   - **Input validation**: What must be validated/sanitized?
+   - **Rate limiting**: What should be rate limited?
+   - **Sensitive data**: What must NEVER appear in logs/responses?
+
+   ## Scale Requirements
+   - **Expected volume**: How many users/items/requests?
+   - **Pagination**: Max items per page (recommend 100)
+   - **Caching**: What can be cached? For how long?
+   - **Database**: What indexes are needed?
+
+   ## UI Mockup (if applicable)
+   ```
+   ┌─────────────────────────────────┐
+   │  [ASCII mockup of the UI]       │
+   └─────────────────────────────────┘
+   ```
 
    ## Open Questions
    - Any unresolved decisions

package/.claude/commands/prd.md

@@ -124,29 +124,50 @@ Write the initial PRD to `.ralph/prd.json`:
 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?
+For EACH story, check:
+
+#### 6a. Testability
+- ❌ `grep -q 'function' file.py` → Only checks code exists, not behavior
+- ❌ `test -f src/component.tsx` → Only checks file exists
+- ❌ `npm test` alone for backend → Mocks can pass without real behavior
+- ✅ `curl ... | jq -e` → Tests actual API response
+- ✅ `npx playwright test` → Real browser tests
+- ✅ `npx tsc --noEmit` → Real type checking
+
+#### 6b. Dependencies
+- Can this story's tests pass given prior stories completed?
+- If TASK-003 needs a user, does TASK-001/002 create one?
+
+#### 6c. Security (for auth/input stories)
+Does acceptanceCriteria include:
+- Password handling → "Passwords hashed with bcrypt (cost 10+)"
+- Auth responses → "Password/tokens NEVER in response body"
+- User input → "Input sanitized to prevent SQL injection/XSS"
+- Login endpoints → "Rate limited to N attempts per minute"
+- Token expiry → "JWT expires after N hours"
+
+#### 6d. Scale (for list/data stories)
+Does acceptanceCriteria include:
+- List endpoints → "Returns paginated results (max 100 per page)"
+- Query params → "Accepts ?page=N&limit=N"
+- Large datasets → "Database query uses index on [column]"
+
+#### 6e. Context (for frontend stories)
+- Does `contextFiles` include the idea file (has ASCII mockups)?
+- Does `contextFiles` include styleguide (if exists)?
+- Is `testUrl` set?
 
 **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` |
+| testSteps use grep/test only | Replace with curl, playwright |
+| Backend story has only `npm test` | Add curl commands that hit real endpoints |
+| Story depends on something not created | Reorder or add missing dependency |
+| Auth story missing security criteria | Add password hashing, rate limiting to acceptanceCriteria |
+| List endpoint missing pagination | Add pagination criteria to acceptanceCriteria |
+| Frontend missing contextFiles | Add idea file + styleguide paths |
+| Frontend missing testUrl | Add URL from config |
 
 ### Step 7: Reorder if Needed
 

package/package.json

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

package/ralph/utils.sh

@@ -509,29 +509,212 @@ 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"
+  # Validate and fix individual stories
+  validate_and_fix_stories "$prd_file" || return 1
+
+  return 0
+}
+
+# Validate individual stories and auto-fix with Claude if needed
+# Checks: testSteps quality, apiContract, testUrl, contextFiles, security, scale
+validate_and_fix_stories() {
+  local prd_file="$1"
+  local needs_fix=false
+  local issues=""
+
+  echo "  Validating story quality..."
+
+  # Get all story IDs
+  local story_ids
+  story_ids=$(jq -r '.stories[].id' "$prd_file" 2>/dev/null)
+
+  while IFS= read -r story_id; do
+    [[ -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")
+
+    if [[ -z "$test_steps" ]]; then
+      story_issues+="no testSteps, "
+    elif [[ "$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 (npm test alone uses mocks), "
+      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 --noEmit or playwright tests, "
+      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+="backend missing apiContract, "
+      fi
+    fi
+
+    # Check 3: Frontend needs testUrl and contextFiles
+    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+="frontend missing testUrl, "
+      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+="frontend missing contextFiles (idea file + styleguide), "
+      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+="auth story missing security criteria (password hashing/rate limiting), "
+      fi
+    fi
+
+    # Check 5: List endpoints need scale criteria
+    if echo "$story_title" | grep -qiE "(list|get all|fetch all|index|search)"; 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+="list endpoint missing pagination criteria, "
+      fi
+    fi
+
+    # Report issues for this story
+    if [[ -n "$story_issues" ]]; then
+      needs_fix=true
+      issues+="$story_id: ${story_issues%%, }
+"
+    fi
+  done <<< "$story_ids"
+
+  # If issues found, attempt to fix with Claude
+  if [[ "$needs_fix" == "true" ]]; then
+    print_warning "Story quality issues found:"
+    echo "$issues" | while IFS= read -r line; do
+      [[ -n "$line" ]] && echo "    $line"
     done
     echo ""
-    echo "Grep verifies code exists, not that it works. Add curl/playwright tests."
-    echo ""
+
+    # Check if Claude is available for auto-fix
+    if command -v claude &>/dev/null; then
+      echo "  Attempting auto-fix with Claude..."
+      fix_stories_with_claude "$prd_file" "$issues"
+    else
+      echo "  Claude CLI not found - fix these issues manually or regenerate PRD."
+      echo ""
+      return 1
+    fi
+  else
+    print_success "All stories validated"
   fi
 
   return 0
 }
 
+# Fix story issues using Claude
+fix_stories_with_claude() {
+  local prd_file="$1"
+  local issues="$2"
+
+  local fix_prompt="Fix the following issues in this PRD. Output the COMPLETE fixed prd.json.
+
+ISSUES FOUND:
+$issues
+
+RULES FOR FIXING:
+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
+4. Frontend stories MUST have contextFiles array (include idea file path from originalContext)
+5. Auth stories MUST have security acceptanceCriteria:
+   - Passwords hashed with bcrypt (cost 10+)
+   - Passwords NEVER in API responses
+   - Rate limiting on login attempts
+6. List endpoints MUST have pagination acceptanceCriteria:
+   - Returns paginated results (max 100 per page)
+   - Accepts ?page=N&limit=N query params
+
+CURRENT PRD:
+$(cat "$prd_file")
+
+Output ONLY the fixed JSON, no explanation."
+
+  local fixed_prd
+  fixed_prd=$(echo "$fix_prompt" | claude -p 2>/dev/null)
+
+  # Validate the response is valid JSON
+  if echo "$fixed_prd" | jq -e . >/dev/null 2>&1; then
+    # Backup original
+    cp "$prd_file" "${prd_file}.bak"
+
+    # Write fixed PRD
+    echo "$fixed_prd" > "$prd_file"
+    print_success "PRD auto-fixed (backup at ${prd_file}.bak)"
+
+    # Re-validate to confirm fixes
+    echo "  Re-validating..."
+    local remaining_issues
+    remaining_issues=$(validate_stories_quick "$prd_file")
+    if [[ -n "$remaining_issues" ]]; then
+      print_warning "Some issues remain - may need manual fixes"
+    else
+      print_success "All issues resolved"
+    fi
+  else
+    print_error "Claude returned invalid JSON - fix manually"
+    return 1
+  fi
+}
+
+# Quick validation without auto-fix (for re-checking after fix)
+validate_stories_quick() {
+  local prd_file="$1"
+  local issues=""
+
+  local story_ids
+  story_ids=$(jq -r '.stories[].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 test_steps
+    test_steps=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testSteps // [] | join(" ")' "$prd_file")
+
+    if [[ "$story_type" == "backend" ]] && ! echo "$test_steps" | grep -q "curl "; then
+      issues+="$story_id: still missing curl tests, "
+    fi
+
+    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" ]] && issues+="$story_id: still missing testUrl, "
+    fi
+  done <<< "$story_ids"
+
+  echo "$issues"
+}
+
 # Detect Python runner (uv, poetry, pipenv, or plain python)
 detect_python_runner() {
   local search_dir="${1:-.}"

package/templates/prd-example.json

@@ -26,7 +26,9 @@
 
   "globalConstraints": [
     "All API calls must have error handling",
-    "Use existing UI components from src/components/ui"
+    "Use existing UI components from src/components/ui",
+    "Never store passwords in plain text",
+    "Sanitize all user input before database operations"
   ],
 
   "metadata": {
@@ -51,13 +53,17 @@
 
       "acceptanceCriteria": [
         "POST /api/users creates a new user with email and password",
-        "Returns 201 with user id and email (no password in response)",
-        "Returns 400 if email already exists"
+        "Returns 201 with user id and email (password NEVER in response)",
+        "Returns 400 if email already exists",
+        "Passwords hashed with bcrypt (cost factor 10+) before storing",
+        "Email validated for format before insert",
+        "Input sanitized to prevent SQL injection"
       ],
 
       "errorHandling": [
         "Duplicate email returns {error: 'Email already registered'}",
-        "Invalid email returns {error: 'Invalid email format'}"
+        "Invalid email returns {error: 'Invalid email format'}",
+        "Missing fields returns {error: 'Email and password required'}"
       ],
 
       "testing": {
@@ -69,9 +75,9 @@
       },
 
       "testSteps": [
-        "curl -s -X POST {config.urls.backend}/api/users -H 'Content-Type: application/json' -d '{\"email\":\"test@example.com\",\"password\":\"secret123\"}' | jq -e '.id and .email'",
-        "curl -s -X POST {config.urls.backend}/api/users -H 'Content-Type: application/json' -d '{\"email\":\"test@example.com\",\"password\":\"secret123\"}' | jq -e '.error'",
-        "npm test -- --testPathPattern=users"
+        "curl -s -X POST {config.urls.backend}/api/users -H 'Content-Type: application/json' -d '{\"email\":\"test@example.com\",\"password\":\"secret123\"}' | jq -e '.id and .email and (has(\"password\") | not)'",
+        "curl -s -X POST {config.urls.backend}/api/users -H 'Content-Type: application/json' -d '{\"email\":\"test@example.com\",\"password\":\"secret123\"}' | jq -e '.error == \"Email already registered\"'",
+        "curl -s -X POST {config.urls.backend}/api/users -H 'Content-Type: application/json' -d '{\"email\":\"invalid\",\"password\":\"x\"}' | jq -e '.error'"
       ],
 
       "apiContract": {
@@ -80,7 +86,7 @@
         "response": {"id": "string", "email": "string"}
       },
 
-      "notes": "Hash passwords with bcrypt before storing.",
+      "notes": "SECURITY: Use bcrypt with cost 10+. Never log passwords. Validate email format server-side even if validated client-side.",
       "dependsOn": []
     },
     {
@@ -97,15 +103,20 @@
       },
 
       "acceptanceCriteria": [
-        "Form has email and password fields",
+        "Form has email and password fields with proper input types",
+        "Password field uses type='password' (masked input)",
         "Submit button calls POST /api/users",
         "Shows success message on 201 response",
-        "Shows error message on 400 response"
+        "Shows error message on 400 response",
+        "Client-side validation before submit (email format, password length)",
+        "Disable submit button while request in flight (prevent double-submit)",
+        "Form matches mockup in docs/ideas/auth.md"
       ],
 
       "errorHandling": [
         "Network error shows 'Unable to connect' message",
-        "Validation errors display inline"
+        "Validation errors display inline below each field",
+        "Server errors display at form level"
       ],
 
       "testing": {
@@ -119,15 +130,67 @@
 
       "testSteps": [
         "npx tsc --noEmit",
-        "npm test -- --testPathPattern=RegisterForm",
         "npx playwright test tests/e2e/register.spec.ts"
       ],
 
       "testUrl": "{config.urls.frontend}/register",
 
+      "contextFiles": [
+        "docs/ideas/auth.md",
+        "src/styles/styleguide.html"
+      ],
+
       "mcp": ["playwright", "devtools"],
 
-      "notes": "Use existing Button and Input components from ui folder.",
+      "notes": "IMPORTANT: Reference the ASCII mockup in docs/ideas/auth.md for layout. Use existing Button and Input components from ui folder per styleguide.",
+      "dependsOn": ["TASK-001"]
+    },
+    {
+      "id": "TASK-003",
+      "type": "backend",
+      "title": "List users endpoint with pagination",
+      "priority": 3,
+      "passes": false,
+
+      "files": {
+        "create": [],
+        "modify": ["src/api/users.ts"],
+        "reuse": ["src/db/client.ts"]
+      },
+
+      "acceptanceCriteria": [
+        "GET /api/users returns paginated list of users",
+        "Accepts ?page=1&limit=20 query params",
+        "Default limit is 20, max limit is 100",
+        "Returns {data: [...], total: N, page: N, limit: N}",
+        "Passwords NEVER included in response",
+        "Results ordered by created_at desc",
+        "Database query uses index on created_at"
+      ],
+
+      "errorHandling": [
+        "Invalid page/limit returns 400 with error message",
+        "limit > 100 returns 400 'Limit cannot exceed 100'"
+      ],
+
+      "testing": {
+        "types": ["integration"],
+        "approach": "TDD",
+        "files": {}
+      },
+
+      "testSteps": [
+        "curl -s '{config.urls.backend}/api/users?page=1&limit=10' | jq -e '.data and .total and .page and .limit'",
+        "curl -s '{config.urls.backend}/api/users?limit=200' | jq -e '.error'"
+      ],
+
+      "apiContract": {
+        "endpoint": "GET /api/users",
+        "request": {"page": "number (optional)", "limit": "number (optional)"},
+        "response": {"data": "User[]", "total": "number", "page": "number", "limit": "number"}
+      },
+
+      "notes": "SCALE: Always paginate list endpoints. Enforce max limit to prevent memory issues. Add database index for sort column.",
       "dependsOn": ["TASK-001"]
     }
   ]