specweave 0.33.3 → 0.33.5

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

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

@@ -0,0 +1,406 @@
+#!/bin/bash
+# Comprehensive test suite for per-us-project-validator.sh
+# Tests that each User Story in spec.md has **Project**: (and **Board**: for 2-level)
+#
+# Usage: bash per-us-project-validator.test.sh
+#
+# v0.34.0 - Initial test suite with all US formats
+
+set -e
+
+GUARD="$(dirname "$0")/per-us-project-validator.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
+
+# Test helper: should block
+test_should_block() {
+  local name="$1"
+  local spec_content="$2"
+  TOTAL=$((TOTAL + 1))
+
+  local file_path="$TEST_DIR/.specweave/increments/0001-test/spec.md"
+  mkdir -p "$(dirname "$file_path")"
+
+  # Build JSON input for the guard
+  # Use printf + jq -Rs to properly escape newlines in the content
+  local json_input
+  json_input=$(printf '%s' "$spec_content" | jq -Rs \
+    --arg tool_name "Write" \
+    --arg file_path "$file_path" \
+    '{tool_name: $tool_name, tool_input: {file_path: $file_path, 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" ]] && echo "$result" | grep -q '"decision".*"block"'; then
+    echo -e "${GREEN}✓ BLOCKED${NC}: $name"
+    PASS=$((PASS + 1))
+  else
+    echo -e "${RED}✗ NOT BLOCKED${NC}: $name"
+    echo "  Exit code: $exit_code"
+    echo "  Result: $(echo "$result" | head -3)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# Test helper: should allow
+test_should_allow() {
+  local name="$1"
+  local spec_content="$2"
+  TOTAL=$((TOTAL + 1))
+
+  local file_path="$TEST_DIR/.specweave/increments/0001-test/spec.md"
+  mkdir -p "$(dirname "$file_path")"
+
+  # Build JSON input for the guard
+  # Use printf + jq -Rs to properly escape newlines in the content
+  local json_input
+  json_input=$(printf '%s' "$spec_content" | jq -Rs \
+    --arg tool_name "Write" \
+    --arg file_path "$file_path" \
+    '{tool_name: $tool_name, tool_input: {file_path: $file_path, 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" ]] && echo "$result" | grep -q '"decision".*"allow"'; then
+    echo -e "${GREEN}✓ ALLOWED${NC}: $name"
+    PASS=$((PASS + 1))
+  else
+    echo -e "${RED}✗ WRONGLY BLOCKED${NC}: $name"
+    echo "  Exit code: $exit_code"
+    echo "  Result: $(echo "$result" | head -5)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "========================================"
+echo "  PER-US PROJECT VALIDATOR - COMPREHENSIVE TESTS"
+echo "========================================"
+echo ""
+echo "Test directory: $TEST_DIR"
+echo ""
+
+echo -e "${YELLOW}=== SIMPLE US FORMAT (### US-001:) ===${NC}"
+
+test_should_allow "Simple US with Project field" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-001: Login Form
+**Project**: frontend-app
+
+**As a** user
+**I want** to log in
+**So that** I can access the app
+
+**Acceptance Criteria**:
+- [ ] **AC-US1-01**: Form exists
+'
+
+test_should_block "Simple US WITHOUT Project field" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-001: Login Form
+
+**As a** user
+**I want** to log in
+**So that** I can access the app
+'
+
+echo ""
+echo -e "${YELLOW}=== MULTI-PROJECT US FORMAT (#### US-FE-001:) ===${NC}"
+
+test_should_allow "Multi-project US-FE-001 with Project field" '---
+increment: 0001-test
+project: my-app
+multi_project: true
+---
+# Feature
+
+#### US-FE-001: Login Form UI
+**Project**: frontend-app
+
+**As a** user
+**I want** to see a login form
+
+#### US-BE-001: Auth API
+**Project**: backend-api
+
+**As a** frontend
+**I want** auth endpoints
+'
+
+test_should_block "Multi-project US-FE-001 WITHOUT Project field" '---
+increment: 0001-test
+project: my-app
+multi_project: true
+---
+# Feature
+
+#### US-FE-001: Login Form UI
+
+**As a** user
+**I want** to see a login form
+'
+
+echo ""
+echo -e "${YELLOW}=== MIXED FORMAT (### with prefixes) ===${NC}"
+
+test_should_allow "Mixed: ### US-FE-001 with Project" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-FE-001: Frontend Story
+**Project**: frontend
+
+### US-BE-001: Backend Story
+**Project**: backend
+'
+
+test_should_block "Mixed: ### US-FE-001 without Project" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-FE-001: Frontend Story
+
+### US-BE-001: Backend Story
+**Project**: backend
+'
+
+echo ""
+echo -e "${YELLOW}=== SHARED PROJECT PREFIX ===${NC}"
+
+test_should_allow "US-SHARED-001 with Project" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+#### US-SHARED-001: Shared Types
+**Project**: shared-lib
+
+**As a** developer
+**I want** shared types
+'
+
+test_should_block "US-SHARED-001 without Project" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+#### US-SHARED-001: Shared Types
+
+**As a** developer
+**I want** shared types
+'
+
+echo ""
+echo -e "${YELLOW}=== MULTIPLE PROJECTS (1:1 VIOLATION - COMMA SEPARATED) ===${NC}"
+
+test_should_block "Multiple projects (comma separated) - FORBIDDEN" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-001: Cross-cutting Story
+**Project**: frontend-app, backend-api
+
+**As a** user
+**I want** everything
+'
+
+test_should_block "Multiple projects with spaces" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-001: Cross-cutting Story
+**Project**: frontend-app,backend-api,shared
+
+**As a** user
+**I want** everything
+'
+
+echo ""
+echo -e "${YELLOW}=== NO USER STORIES (should allow) ===${NC}"
+
+test_should_allow "Spec without any User Stories" '---
+increment: 0001-test
+project: my-app
+---
+# Feature Overview
+
+This is just an overview document.
+
+## Goals
+
+- Goal 1
+- Goal 2
+'
+
+test_should_allow "Tasks-only spec (no US headings)" '---
+increment: 0001-test
+project: my-app
+---
+# Implementation Tasks
+
+## T-001: Setup
+
+Do setup stuff.
+'
+
+echo ""
+echo -e "${YELLOW}=== ALL USER STORIES HAVE PROJECT ===${NC}"
+
+test_should_allow "Multiple US, all with Project" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-001: First Story
+**Project**: app-a
+
+### US-002: Second Story
+**Project**: app-b
+
+### US-003: Third Story
+**Project**: app-c
+'
+
+test_should_block "Multiple US, one missing Project" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-001: First Story
+**Project**: app-a
+
+### US-002: Second Story
+
+### US-003: Third Story
+**Project**: app-c
+'
+
+echo ""
+echo -e "${YELLOW}=== NON-WRITE TOOLS ===${NC}"
+
+# Test with Edit tool (should allow - no full content)
+TOTAL=$((TOTAL + 1))
+json_input=$(jq -n \
+  --arg tool_name "Edit" \
+  --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${NC}: Edit tool (no full content validation)"
+  PASS=$((PASS + 1))
+else
+  echo -e "${RED}✗ FAILED${NC}: Edit tool should be allowed"
+  FAIL=$((FAIL + 1))
+fi
+
+echo ""
+echo -e "${YELLOW}=== BYPASS MODES ===${NC}"
+
+# Test SPECWEAVE_FORCE_PROJECT bypass
+TOTAL=$((TOTAL + 1))
+spec_content='---
+increment: 0001-test
+---
+### US-001: No Project
+**As a** user
+**I want** something
+'
+json_input=$(jq -n \
+  --arg tool_name "Write" \
+  --arg file_path "$TEST_DIR/.specweave/increments/0001-test/spec.md" \
+  --arg content "$spec_content" \
+  '{tool_name: $tool_name, tool_input: {file_path: $file_path, content: $content}}')
+
+result=$(SPECWEAVE_FORCE_PROJECT=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_PROJECT=1"
+  PASS=$((PASS + 1))
+else
+  echo -e "${RED}✗ BYPASS FAILED${NC}: SPECWEAVE_FORCE_PROJECT=1"
+  FAIL=$((FAIL + 1))
+fi
+
+# Test SPECWEAVE_LEGACY_SPEC bypass
+TOTAL=$((TOTAL + 1))
+result=$(SPECWEAVE_LEGACY_SPEC=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 "legacy"; then
+  echo -e "${GREEN}✓ ALLOWED (bypass)${NC}: SPECWEAVE_LEGACY_SPEC=1"
+  PASS=$((PASS + 1))
+else
+  echo -e "${RED}✗ BYPASS FAILED${NC}: SPECWEAVE_LEGACY_SPEC=1"
+  FAIL=$((FAIL + 1))
+fi
+
+echo ""
+echo -e "${YELLOW}=== FILES OUTSIDE INCREMENTS ===${NC}"
+
+# Test file outside increments folder
+TOTAL=$((TOTAL + 1))
+json_input=$(jq -n \
+  --arg tool_name "Write" \
+  --arg file_path "$TEST_DIR/other/spec.md" \
+  --arg content "no project" \
+  '{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" ]] && echo "$result" | grep -q '"decision".*"allow"'; then
+  echo -e "${GREEN}✓ ALLOWED${NC}: spec.md outside increments folder"
+  PASS=$((PASS + 1))
+else
+  echo -e "${RED}✗ FAILED${NC}: Files outside increments should be allowed"
+  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