specweave 0.33.4 → 0.33.5

package/plugins/specweave/hooks/hooks.json

@@ -40,6 +40,16 @@
           }
         ]
       },
+      {
+        "matcher": "Write",
+        "matcher_content": "\\.specweave/increments/\\d{3,4}E?-[^/]+/spec\\.md",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/metadata-json-guard.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
+          }
+        ]
+      },
       {
         "matcher": "Write",
         "matcher_content": "\\.specweave/increments/\\d{3,4}E?-[^/]+/spec\\.md",

package/plugins/specweave/hooks/v2/guards/metadata-json-guard.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+#
+# metadata-json-guard.sh
+#
+# Pre-tool-use hook that ensures metadata.json exists BEFORE spec.md can be created.
+# This prevents increments from being created without proper metadata.
+#
+# ROOT CAUSE: When Claude creates increments via user prompt (not /specweave:increment),
+# metadata.json may be forgotten, causing:
+# - Status tracking broken
+# - WIP limits don't work
+# - External sync fails (GitHub/Jira/ADO)
+# - All increment commands fail
+#
+# SOLUTION: Block spec.md creation if metadata.json doesn't exist in same increment folder.
+# Claude MUST create metadata.json FIRST, then spec.md.
+#
+# Activation:
+# - tool_name: Write
+# - file_path matches: .specweave/increments/*/spec.md
+#
+# Returns exit code 2 (block) if metadata.json missing, 0 (allow) otherwise.
+#
+# Bypass: Set SPECWEAVE_FORCE_METADATA=1 to skip validation
+#
+# v0.34.0 - Initial implementation based on user project bug analysis
+
+set -e
+
+# Check for force bypass
+if [ "$SPECWEAVE_FORCE_METADATA" = "1" ]; then
+  echo '{"decision": "allow", "message": "metadata.json guard bypassed (SPECWEAVE_FORCE_METADATA=1)"}'
+  exit 0
+fi
+
+# Disable hooks bypass
+if [ "$SPECWEAVE_DISABLE_HOOKS" = "1" ]; then
+  echo '{"decision": "allow"}'
+  exit 0
+fi
+
+# Read tool input from stdin
+INPUT=$(cat)
+
+# Extract tool name
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // .tool_input.tool_name // ""' 2>/dev/null || echo "")
+
+# Only validate Write tool calls
+if [ "$TOOL_NAME" != "Write" ]; then
+  echo '{"decision": "allow"}'
+  exit 0
+fi
+
+# Extract file path - handle both formats
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .file_path // ""' 2>/dev/null || echo "")
+
+# Only validate spec.md files in increments folder
+# Match: 3-4 digits, optional E suffix, kebab-case name, spec.md
+if [[ ! "$FILE_PATH" =~ \.specweave/increments/([0-9]{3,4}E?-[^/]+)/spec\.md$ ]]; then
+  echo '{"decision": "allow"}'
+  exit 0
+fi
+
+# Extract increment folder path
+INCREMENT_DIR=$(dirname "$FILE_PATH")
+INCREMENT_ID="${BASH_REMATCH[1]}"
+
+# Check if metadata.json exists in the same increment folder
+METADATA_PATH="${INCREMENT_DIR}/metadata.json"
+
+if [ -f "$METADATA_PATH" ]; then
+  # metadata.json exists, allow spec.md creation
+  echo '{"decision": "allow"}'
+  exit 0
+fi
+
+# metadata.json doesn't exist - BLOCK spec.md creation
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+cat << BLOCK_EOF
+{
+  "decision": "block",
+  "reason": "🚫 BLOCKED: Cannot create spec.md without metadata.json\n\n⚠️ CRITICAL RULE: metadata.json MUST be created FIRST!\n\nWithout metadata.json:\n  - ❌ Status tracking broken\n  - ❌ WIP limits don't work\n  - ❌ External sync fails (GitHub/Jira/ADO)\n  - ❌ All increment commands fail\n\n📋 CORRECT WORKFLOW:\n1. Create metadata.json FIRST:\n   Write({\n     file_path: \"${METADATA_PATH}\",\n     content: {\n       \"id\": \"${INCREMENT_ID}\",\n       \"status\": \"planned\",\n       \"type\": \"feature\",\n       \"priority\": \"P1\",\n       \"created\": \"${NOW}\",\n       \"lastActivity\": \"${NOW}\",\n       \"testMode\": \"TDD\",\n       \"coverageTarget\": 95,\n       \"feature_id\": null,\n       \"epic_id\": null,\n       \"externalLinks\": {}\n     }\n   })\n\n2. THEN create spec.md\n\n📖 See: CLAUDE.md section '3. metadata.json is MANDATORY'\n\n💡 Bypass: Set SPECWEAVE_FORCE_METADATA=1 to skip this validation"
+}
+BLOCK_EOF
+
+exit 2

package/plugins/specweave/hooks/v2/guards/metadata-json-guard.test.sh

@@ -0,0 +1,302 @@
+#!/bin/bash
+# Comprehensive test suite for metadata-json-guard.sh
+# Tests that spec.md creation is blocked when metadata.json is missing
+#
+# Usage: bash metadata-json-guard.test.sh
+#
+# v0.34.0 - Initial test suite
+
+set -e
+
+GUARD="$(dirname "$0")/metadata-json-guard.sh"
+TEST_DIR=$(mktemp -d)
+PASS=0
+FAIL=0
+TOTAL=0
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+cleanup() {
+  rm -rf "$TEST_DIR"
+}
+trap cleanup EXIT
+
+# Create test increment structure
+setup_test_increment() {
+  local with_metadata="$1"
+  local increment_name="${2:-0001-test-feature}"
+
+  mkdir -p "$TEST_DIR/.specweave/increments/$increment_name"
+
+  if [ "$with_metadata" = "true" ]; then
+    cat > "$TEST_DIR/.specweave/increments/$increment_name/metadata.json" << 'EOF'
+{
+  "id": "0001-test-feature",
+  "status": "planned",
+  "type": "feature",
+  "priority": "P1",
+  "created": "2025-12-10T00:00:00Z",
+  "lastActivity": "2025-12-10T00:00:00Z",
+  "testMode": "TDD",
+  "coverageTarget": 95,
+  "feature_id": null,
+  "epic_id": null,
+  "externalLinks": {}
+}
+EOF
+  fi
+}
+
+# Test helper: should block
+test_should_block() {
+  local name="$1"
+  local file_path="$2"
+  local content="$3"
+  TOTAL=$((TOTAL + 1))
+
+  # Build JSON input for the guard
+  local json_input
+  json_input=$(jq -n \
+    --arg tool_name "Write" \
+    --arg file_path "$file_path" \
+    --arg content "$content" \
+    '{tool_name: $tool_name, tool_input: {file_path: $file_path, content: $content}}')
+
+  result=$(echo "$json_input" | bash "$GUARD" 2>&1; echo "EXIT:$?")
+  exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+
+  if [[ "$exit_code" == "2" ]]; then
+    echo -e "${GREEN}✓ BLOCKED${NC}: $name"
+    PASS=$((PASS + 1))
+  else
+    echo -e "${RED}✗ NOT BLOCKED${NC}: $name"
+    echo "  File: $file_path"
+    echo "  Exit code: $exit_code (expected 2)"
+    echo "  Output: $(echo "$result" | head -5)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# Test helper: should allow
+test_should_allow() {
+  local name="$1"
+  local file_path="$2"
+  local content="$3"
+  TOTAL=$((TOTAL + 1))
+
+  # Build JSON input for the guard
+  local json_input
+  json_input=$(jq -n \
+    --arg tool_name "Write" \
+    --arg file_path "$file_path" \
+    --arg content "$content" \
+    '{tool_name: $tool_name, tool_input: {file_path: $file_path, content: $content}}')
+
+  result=$(echo "$json_input" | bash "$GUARD" 2>&1; echo "EXIT:$?")
+  exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+
+  if [[ "$exit_code" == "0" ]]; then
+    echo -e "${GREEN}✓ ALLOWED${NC}: $name"
+    PASS=$((PASS + 1))
+  else
+    echo -e "${RED}✗ WRONGLY BLOCKED${NC}: $name"
+    echo "  File: $file_path"
+    echo "  Exit code: $exit_code (expected 0)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# Test non-Write tools (should always allow)
+test_non_write_tool() {
+  local name="$1"
+  local tool_name="$2"
+  TOTAL=$((TOTAL + 1))
+
+  local json_input
+  json_input=$(jq -n \
+    --arg tool_name "$tool_name" \
+    --arg file_path "$TEST_DIR/.specweave/increments/0001-test/spec.md" \
+    '{tool_name: $tool_name, tool_input: {file_path: $file_path}}')
+
+  result=$(echo "$json_input" | bash "$GUARD" 2>&1; echo "EXIT:$?")
+  exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+
+  if [[ "$exit_code" == "0" ]]; then
+    echo -e "${GREEN}✓ ALLOWED (non-Write)${NC}: $name"
+    PASS=$((PASS + 1))
+  else
+    echo -e "${RED}✗ WRONGLY BLOCKED${NC}: $name"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "========================================"
+echo "  METADATA JSON GUARD - COMPREHENSIVE TESTS"
+echo "========================================"
+echo ""
+echo "Test directory: $TEST_DIR"
+echo ""
+
+echo -e "${YELLOW}=== CORE FUNCTIONALITY: BLOCK WHEN METADATA MISSING ===${NC}"
+
+# Setup without metadata
+setup_test_increment "false" "0001-no-metadata"
+test_should_block "spec.md without metadata.json (3-digit)" \
+  "$TEST_DIR/.specweave/increments/0001-no-metadata/spec.md" \
+  "---\nincrement: 0001-no-metadata\n---"
+
+setup_test_increment "false" "0012-no-metadata"
+test_should_block "spec.md without metadata.json (4-digit)" \
+  "$TEST_DIR/.specweave/increments/0012-no-metadata/spec.md" \
+  "---\nincrement: 0012-no-metadata\n---"
+
+setup_test_increment "false" "123-short"
+test_should_block "spec.md without metadata.json (3-digit short)" \
+  "$TEST_DIR/.specweave/increments/123-short/spec.md" \
+  "---\nincrement: 123-short\n---"
+
+setup_test_increment "false" "0001E-external"
+test_should_block "spec.md without metadata.json (external E suffix)" \
+  "$TEST_DIR/.specweave/increments/0001E-external/spec.md" \
+  "---\nincrement: 0001E-external\n---"
+
+echo ""
+echo -e "${YELLOW}=== CORE FUNCTIONALITY: ALLOW WHEN METADATA EXISTS ===${NC}"
+
+# Setup with metadata
+setup_test_increment "true" "0002-has-metadata"
+test_should_allow "spec.md WITH metadata.json present" \
+  "$TEST_DIR/.specweave/increments/0002-has-metadata/spec.md" \
+  "---\nincrement: 0002-has-metadata\n---"
+
+setup_test_increment "true" "0123E-external-with-meta"
+test_should_allow "spec.md WITH metadata.json (external E suffix)" \
+  "$TEST_DIR/.specweave/increments/0123E-external-with-meta/spec.md" \
+  "---\nincrement: 0123E-external-with-meta\n---"
+
+echo ""
+echo -e "${YELLOW}=== NON-SPEC FILES: SHOULD NOT VALIDATE ===${NC}"
+
+# Create increment without metadata for these tests
+setup_test_increment "false" "0003-other-files"
+test_should_allow "plan.md (not spec.md)" \
+  "$TEST_DIR/.specweave/increments/0003-other-files/plan.md" \
+  "# Plan"
+
+test_should_allow "tasks.md (not spec.md)" \
+  "$TEST_DIR/.specweave/increments/0003-other-files/tasks.md" \
+  "# Tasks"
+
+test_should_allow "metadata.json itself" \
+  "$TEST_DIR/.specweave/increments/0003-other-files/metadata.json" \
+  '{"id": "test"}'
+
+test_should_allow "report in subfolder" \
+  "$TEST_DIR/.specweave/increments/0003-other-files/reports/COMPLETION.md" \
+  "# Report"
+
+echo ""
+echo -e "${YELLOW}=== FILES OUTSIDE INCREMENTS: SHOULD NOT VALIDATE ===${NC}"
+
+test_should_allow "spec.md outside increments (docs)" \
+  "$TEST_DIR/.specweave/docs/internal/spec.md" \
+  "# Documentation"
+
+test_should_allow "spec.md in root" \
+  "$TEST_DIR/spec.md" \
+  "# Root spec"
+
+test_should_allow "Random file" \
+  "$TEST_DIR/random.txt" \
+  "Random content"
+
+echo ""
+echo -e "${YELLOW}=== NON-WRITE TOOLS: SHOULD ALWAYS ALLOW ===${NC}"
+
+test_non_write_tool "Read tool" "Read"
+test_non_write_tool "Edit tool" "Edit"
+test_non_write_tool "Glob tool" "Glob"
+test_non_write_tool "Grep tool" "Grep"
+test_non_write_tool "Bash tool" "Bash"
+
+echo ""
+echo -e "${YELLOW}=== BYPASS MODES ===${NC}"
+
+# Test SPECWEAVE_FORCE_METADATA bypass
+setup_test_increment "false" "0004-bypass"
+TOTAL=$((TOTAL + 1))
+json_input=$(jq -n \
+  --arg tool_name "Write" \
+  --arg file_path "$TEST_DIR/.specweave/increments/0004-bypass/spec.md" \
+  --arg content "---\nincrement: 0004-bypass\n---" \
+  '{tool_name: $tool_name, tool_input: {file_path: $file_path, content: $content}}')
+
+result=$(SPECWEAVE_FORCE_METADATA=1 bash -c "echo '$json_input' | bash '$GUARD'" 2>&1; echo "EXIT:$?")
+exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+if [[ "$exit_code" == "0" ]] && echo "$result" | grep -q "bypassed"; then
+  echo -e "${GREEN}✓ ALLOWED (bypass)${NC}: SPECWEAVE_FORCE_METADATA=1 works"
+  PASS=$((PASS + 1))
+else
+  echo -e "${RED}✗ BYPASS FAILED${NC}: SPECWEAVE_FORCE_METADATA=1"
+  echo "  Exit code: $exit_code"
+  FAIL=$((FAIL + 1))
+fi
+
+# Test SPECWEAVE_DISABLE_HOOKS bypass
+TOTAL=$((TOTAL + 1))
+result=$(SPECWEAVE_DISABLE_HOOKS=1 bash -c "echo '$json_input' | bash '$GUARD'" 2>&1; echo "EXIT:$?")
+exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+if [[ "$exit_code" == "0" ]]; then
+  echo -e "${GREEN}✓ ALLOWED (bypass)${NC}: SPECWEAVE_DISABLE_HOOKS=1 works"
+  PASS=$((PASS + 1))
+else
+  echo -e "${RED}✗ BYPASS FAILED${NC}: SPECWEAVE_DISABLE_HOOKS=1"
+  FAIL=$((FAIL + 1))
+fi
+
+echo ""
+echo -e "${YELLOW}=== EDGE CASES ===${NC}"
+
+# Test with empty file path
+TOTAL=$((TOTAL + 1))
+json_input='{"tool_name": "Write", "tool_input": {"file_path": "", "content": "test"}}'
+result=$(echo "$json_input" | bash "$GUARD" 2>&1; echo "EXIT:$?")
+exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+if [[ "$exit_code" == "0" ]]; then
+  echo -e "${GREEN}✓ ALLOWED${NC}: Empty file path"
+  PASS=$((PASS + 1))
+else
+  echo -e "${RED}✗ FAILED${NC}: Empty file path should be allowed"
+  FAIL=$((FAIL + 1))
+fi
+
+# Test with malformed JSON (should fail gracefully)
+TOTAL=$((TOTAL + 1))
+result=$(echo "not json" | bash "$GUARD" 2>&1; echo "EXIT:$?")
+exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+if [[ "$exit_code" == "0" ]]; then
+  echo -e "${GREEN}✓ ALLOWED${NC}: Malformed JSON handled gracefully"
+  PASS=$((PASS + 1))
+else
+  echo -e "${RED}✗ FAILED${NC}: Malformed JSON should be allowed (fail-safe)"
+  FAIL=$((FAIL + 1))
+fi
+
+echo ""
+echo "========================================"
+echo "  RESULTS"
+echo "========================================"
+echo -e "Total: $TOTAL"
+echo -e "${GREEN}Passed: $PASS${NC}"
+if [[ $FAIL -gt 0 ]]; then
+  echo -e "${RED}Failed: $FAIL${NC}"
+  exit 1
+else
+  echo -e "Failed: 0"
+  echo ""
+  echo -e "${GREEN}ALL TESTS PASSED!${NC}"
+fi

package/plugins/specweave/hooks/v2/guards/per-us-project-validator.sh

@@ -12,9 +12,16 @@
 # - file_path matches: .specweave/increments/*/spec.md
 #
 # Rules:
-# - Each ### US-XXX section MUST have **Project**: <value> on next few lines
+# - Each US section MUST have **Project**: <value> on next few lines
 # - For 2-level structures, each US MUST also have **Board**: <value>
 # - Project values MUST match configured projects (not generic keywords)
+# - Supports ALL US formats:
+#   - ### US-001: (simple)
+#   - #### US-001: (4 hashes)
+#   - ### US-FE-001: (with project prefix)
+#   - #### US-FE-001: (multi-project)
+#   - #### US-BE-001: (backend)
+#   - #### US-SHARED-001: (shared)
 # - Fallback allowed for existing specs via SPECWEAVE_LEGACY_SPEC=1
 #
 # Returns exit code 1 (block) if validation fails, 0 (allow) otherwise.
@@ -23,6 +30,7 @@
 # - SPECWEAVE_FORCE_PROJECT=1 - Skip all project validation
 # - SPECWEAVE_LEGACY_SPEC=1 - Allow specs without per-US project (legacy mode)
 #
+# v0.34.0 - Fixed to handle all US ID formats (US-001, US-FE-001, etc.)
 
 set -e
 
@@ -75,8 +83,13 @@ log_debug "Validating per-US project fields for: $FILE_PATH"
 # Extract file content
 CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""')
 
-# Count User Stories (### US-XXX pattern)
-US_PATTERN='### US-[0-9]+'
+# Count User Stories - support ALL formats:
+# - ### US-001: (simple, 3 hashes)
+# - #### US-001: (4 hashes)
+# - ### US-FE-001: (with project prefix like FE, BE, SHARED)
+# - #### US-FE-001: (multi-project with 4 hashes)
+# Pattern: 3-4 hashes, space, US-, optional prefix (letters+dash), digits, colon
+US_PATTERN='^#{3,4} US-([A-Z]+-)?[0-9]+:'
 TOTAL_US=$(echo "$CONTENT" | grep -cE "$US_PATTERN" || echo 0)
 
 log_debug "Total User Stories found: $TOTAL_US"
@@ -88,7 +101,7 @@ if [ "$TOTAL_US" -eq 0 ]; then
 fi
 
 # Extract User Story sections and check for **Project**: field
-# Strategy: For each ### US-XXX, look at next 10 lines for **Project**:
+# Strategy: For each US heading, look at next 10 lines for **Project**:
 
 MISSING_PROJECT=()
 MISSING_BOARD=()
@@ -96,26 +109,46 @@ MULTI_PROJECT=()   # USs with multiple projects (comma-separated)
 MULTI_BOARD=()     # USs with multiple boards (comma-separated)
 US_WITH_PROJECT=0
 
-# Use awk to extract US sections and check for Project field
+# Use grep to find all US headings (both ### and ####, with or without prefix)
 while IFS= read -r us_line; do
-  # Extract US ID (e.g., US-001)
-  US_ID=$(echo "$us_line" | grep -oE 'US-[0-9]+' | head -1)
+  # Extract US ID - handles US-001, US-FE-001, US-BE-001, US-SHARED-001, etc.
+  US_ID=$(echo "$us_line" | grep -oE 'US-([A-Z]+-)?[0-9]+' | head -1)
 
   if [ -z "$US_ID" ]; then
     continue
   fi
 
-  # Get line number of this US heading
-  LINE_NUM=$(echo "$CONTENT" | grep -nE "^### $US_ID:" | head -1 | cut -d: -f1)
+  # Get line number of this US heading (works with both ### and ####)
+  # Escape the US_ID for grep (the dash needs no escape, but be safe)
+  LINE_NUM=$(echo "$CONTENT" | grep -nE "^#{3,4} ${US_ID}:" | head -1 | cut -d: -f1)
 
   if [ -z "$LINE_NUM" ]; then
+    log_debug "Could not find line number for $US_ID"
     continue
   fi
 
-  # Extract next 10 lines after heading
-  SECTION=$(echo "$CONTENT" | tail -n +$((LINE_NUM + 1)) | head -n 10)
+  # Extract lines after heading UNTIL next US heading, separator (---), or max 15 lines
+  # This prevents reading **Project** from a DIFFERENT user story
+  SECTION=""
+  line_count=0
+  while IFS= read -r line; do
+    # Stop at next US heading (### US- or #### US-)
+    if [[ "$line" =~ ^#{3,4}\ US- ]] && [ "$line_count" -gt 0 ]; then
+      break
+    fi
+    # Stop at separator
+    if [[ "$line" =~ ^---$ ]] && [ "$line_count" -gt 0 ]; then
+      break
+    fi
+    # Max 15 lines
+    if [ "$line_count" -ge 15 ]; then
+      break
+    fi
+    SECTION+="$line"$'\n'
+    line_count=$((line_count + 1))
+  done < <(echo "$CONTENT" | tail -n +$((LINE_NUM + 1)))
 
-  # Check for **Project**: field
+  # Check for **Project**: field within this US section only
   PROJECT_LINE=$(echo "$SECTION" | grep -E '^\*\*Project\*\*:\s*\S' | head -1)
 
   if [ -n "$PROJECT_LINE" ]; then
@@ -136,7 +169,7 @@ while IFS= read -r us_line; do
     log_debug "$US_ID MISSING **Project**: field ✗"
   fi
 
-done < <(echo "$CONTENT" | grep -E "^### US-[0-9]+:")
+done < <(echo "$CONTENT" | grep -E "^#{3,4} US-([A-Z]+-)?[0-9]+:")
 
 log_debug "User Stories with **Project**: $US_WITH_PROJECT / $TOTAL_US"
 
@@ -167,21 +200,42 @@ log_debug "Structure level: $STRUCTURE_LEVEL"
 # For 2-level structures, also check for **Board**: field
 if [ "$STRUCTURE_LEVEL" = "2" ]; then
   while IFS= read -r us_line; do
-    US_ID=$(echo "$us_line" | grep -oE 'US-[0-9]+' | head -1)
+    # Extract US ID - handles all formats (US-001, US-FE-001, etc.)
+    US_ID=$(echo "$us_line" | grep -oE 'US-([A-Z]+-)?[0-9]+' | head -1)
 
     if [ -z "$US_ID" ]; then
       continue
     fi
 
-    LINE_NUM=$(echo "$CONTENT" | grep -nE "^### $US_ID:" | head -1 | cut -d: -f1)
+    # Get line number (works with both ### and ####)
+    LINE_NUM=$(echo "$CONTENT" | grep -nE "^#{3,4} ${US_ID}:" | head -1 | cut -d: -f1)
 
     if [ -z "$LINE_NUM" ]; then
+      log_debug "Could not find line number for $US_ID (board check)"
       continue
     fi
 
-    SECTION=$(echo "$CONTENT" | tail -n +$((LINE_NUM + 1)) | head -n 10)
+    # Extract lines after heading UNTIL next US heading, separator, or max 15 lines
+    SECTION=""
+    line_count=0
+    while IFS= read -r line; do
+      # Stop at next US heading
+      if [[ "$line" =~ ^#{3,4}\ US- ]] && [ "$line_count" -gt 0 ]; then
+        break
+      fi
+      # Stop at separator
+      if [[ "$line" =~ ^---$ ]] && [ "$line_count" -gt 0 ]; then
+        break
+      fi
+      # Max 15 lines
+      if [ "$line_count" -ge 15 ]; then
+        break
+      fi
+      SECTION+="$line"$'\n'
+      line_count=$((line_count + 1))
+    done < <(echo "$CONTENT" | tail -n +$((LINE_NUM + 1)))
 
-    # Check for **Board**: field
+    # Check for **Board**: field within this US section only
     BOARD_LINE=$(echo "$SECTION" | grep -E '^\*\*Board\*\*:\s*\S' | head -1)
 
     if [ -n "$BOARD_LINE" ]; then
@@ -200,7 +254,7 @@ if [ "$STRUCTURE_LEVEL" = "2" ]; then
       log_debug "$US_ID MISSING **Board**: field ✗"
     fi
 
-  done < <(echo "$CONTENT" | grep -E "^### US-[0-9]+:")
+  done < <(echo "$CONTENT" | grep -E "^#{3,4} US-([A-Z]+-)?[0-9]+:")
 fi
 
 # Build error message if validation fails