specweave 0.32.0 → 0.32.3

package/plugins/specweave/hooks/pre-task-completion.sh

@@ -167,11 +167,7 @@ fi
 if [ "$COMPLETING_TASK" = "false" ]; then
   echo "[$(date)] ⏭️  No tasks being completed, skipping validation" >> "$DEBUG_LOG" 2>/dev/null || true
   rm -f "$STDIN_DATA"
-  cat <<EOF
-{
-  "continue": true
-}
-EOF
+  echo '{"continue":true}'
   exit 0
 fi
 
@@ -184,11 +180,7 @@ CURRENT_INCREMENT=$(ls -td .specweave/increments/*/ 2>/dev/null | xargs -n1 base
 if [ -z "$CURRENT_INCREMENT" ]; then
   echo "[$(date)] ℹ️  No active increment found, skipping validation" >> "$DEBUG_LOG" 2>/dev/null || true
   rm -f "$STDIN_DATA"
-  cat <<EOF
-{
-  "continue": true
-}
-EOF
+  echo '{"continue":true}'
   exit 0
 fi
 
@@ -197,11 +189,7 @@ TASKS_MD=".specweave/increments/$CURRENT_INCREMENT/tasks.md"
 if [ ! -f "$TASKS_MD" ]; then
   echo "[$(date)] ℹ️  tasks.md not found for $CURRENT_INCREMENT (increment may be in planning stage)" >> "$DEBUG_LOG" 2>/dev/null || true
   rm -f "$STDIN_DATA"
-  cat <<EOF
-{
-  "continue": true
-}
-EOF
+  echo '{"continue":true}'
   exit 0
 fi
 
@@ -231,12 +219,7 @@ fi
 if [ -z "$VALIDATOR_SCRIPT" ] || ! command -v node &> /dev/null; then
   echo "[$(date)] ⚠️  AC test validator not found or Node.js missing" >> "$DEBUG_LOG" 2>/dev/null || true
   rm -f "$STDIN_DATA"
-  cat <<EOF
-{
-  "continue": true,
-  "systemMessage": "⚠️  Warning: AC test validator not available. Task completion validation skipped. Install Node.js and rebuild SpecWeave to enable validation."
-}
-EOF
+  echo '{"continue":true,"systemMessage":"⚠️  Warning: AC test validator not available. Task completion validation skipped. Install Node.js and rebuild SpecWeave to enable validation."}'
   exit 0
 fi
 
@@ -262,16 +245,11 @@ if [ "$VALIDATION_EXIT_CODE" = "0" ]; then
   # Reset circuit breaker on success
   echo "0" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
 
-  VALIDATION_SUMMARY=$(cat "$VALIDATION_OUTPUT" | tail -5 | tr '\n' ' ')
+  VALIDATION_SUMMARY=$(cat "$VALIDATION_OUTPUT" | tail -5 | tr '\n' ' ' | sed 's/"/\\"/g')
 
   rm -f "$VALIDATION_OUTPUT"
 
-  cat <<EOF
-{
-  "continue": true,
-  "systemMessage": "✅ AC Test Validation Passed: All acceptance criteria have passing tests. Task completion allowed. ${VALIDATION_SUMMARY}"
-}
-EOF
+  printf '{"continue":true,"systemMessage":"✅ AC Test Validation Passed: All acceptance criteria have passing tests. Task completion allowed. %s"}\n' "$VALIDATION_SUMMARY"
 else
   # Validation failed - block completion
   echo "[$(date)] ❌ AC test validation failed" >> "$DEBUG_LOG" 2>/dev/null || true
@@ -280,18 +258,11 @@ else
   CURRENT_FAILURES=$(cat "$CIRCUIT_BREAKER_FILE" 2>/dev/null || echo 0)
   echo "$((CURRENT_FAILURES + 1))" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
 
-  VALIDATION_ERROR=$(cat "$VALIDATION_OUTPUT" | grep -A 10 "VALIDATION FAILED" | tr '\n' ' ' | cut -c 1-300)
+  VALIDATION_ERROR=$(cat "$VALIDATION_OUTPUT" | grep -A 10 "VALIDATION FAILED" | tr '\n' ' ' | cut -c 1-300 | sed 's/"/\\"/g')
 
   rm -f "$VALIDATION_OUTPUT"
 
-  cat <<EOF
-{
-  "continue": false,
-  "systemMessage": "❌ AC TEST VALIDATION FAILED: Cannot mark task as complete until all acceptance criteria have passing tests. ${VALIDATION_ERROR}
-
-Fix the failing tests and try again. Run tests manually: npm test"
-}
-EOF
+  printf '{"continue":false,"systemMessage":"❌ AC TEST VALIDATION FAILED: Cannot mark task as complete until all acceptance criteria have passing tests. %s\\n\\nFix the failing tests and try again. Run tests manually: npm test"}\n' "$VALIDATION_ERROR"
 fi
 
 # ALWAYS exit 0 - NEVER let hook errors crash Claude Code

package/plugins/specweave/hooks/pre-task-completion.sh.backup

@@ -0,0 +1,194 @@
+#!/bin/bash
+
+# SpecWeave Pre-Task-Completion Hook
+# CRITICAL QUALITY GATE: Validates AC tests before allowing task completion
+#
+# Runs automatically BEFORE any task is marked complete via TodoWrite
+#
+# WORKFLOW:
+# =========
+# 1. TodoWrite called with status="completed"
+# 2. This hook fires (pre-completion validation)
+# 3. Extract task ID from TodoWrite input
+# 4. Find task in tasks.md
+# 5. Run AC test validator
+# 6. If tests PASS → Allow completion (continue: true)
+# 7. If tests FAIL → Block completion (continue: false, show error)
+#
+# ENFORCEMENT:
+# ============
+# This is the ONLY way to mark tasks complete in SpecWeave.
+# Manual edits to tasks.md are detected and flagged by pre-commit hooks.
+
+set -e
+
+# Find project root
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  pwd
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT" 2>/dev/null || true
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+LOGS_DIR=".specweave/logs"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+
+mkdir -p "$LOGS_DIR" 2>/dev/null || true
+
+echo "[$(date)] 🔒 Pre-task-completion hook fired" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# CAPTURE INPUT
+# ============================================================================
+
+STDIN_DATA=$(mktemp)
+cat > "$STDIN_DATA"
+
+echo "[$(date)] Input JSON:" >> "$DEBUG_LOG" 2>/dev/null || true
+cat "$STDIN_DATA" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# CHECK FOR TASK COMPLETION
+# ============================================================================
+
+# Only validate if a task is being marked complete
+COMPLETING_TASK=false
+
+if command -v jq >/dev/null 2>&1; then
+  # Check if any task is transitioning to "completed" status
+  COMPLETED_COUNT=$(jq -r '.tool_input.todos // [] | map(select(.status == "completed")) | length' "$STDIN_DATA" 2>/dev/null || echo "0")
+
+  if [ "$COMPLETED_COUNT" != "0" ]; then
+    COMPLETING_TASK=true
+    echo "[$(date)] ✓ Detected task completion (${COMPLETED_COUNT} tasks)" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+fi
+
+# If no tasks being completed, allow without validation
+if [ "$COMPLETING_TASK" = "false" ]; then
+  echo "[$(date)] ⏭️  No tasks being completed, skipping validation" >> "$DEBUG_LOG" 2>/dev/null || true
+  rm -f "$STDIN_DATA"
+  cat <<EOF
+{
+  "continue": true
+}
+EOF
+  exit 0
+fi
+
+# ============================================================================
+# DETECT CURRENT INCREMENT
+# ============================================================================
+
+CURRENT_INCREMENT=$(ls -td .specweave/increments/*/ 2>/dev/null | xargs -n1 basename | grep -v "_backlog" | grep -v "_archive" | grep -v "_working" | head -1)
+
+if [ -z "$CURRENT_INCREMENT" ]; then
+  echo "[$(date)] ℹ️  No active increment found, skipping validation" >> "$DEBUG_LOG" 2>/dev/null || true
+  rm -f "$STDIN_DATA"
+  cat <<EOF
+{
+  "continue": true
+}
+EOF
+  exit 0
+fi
+
+TASKS_MD=".specweave/increments/$CURRENT_INCREMENT/tasks.md"
+
+if [ ! -f "$TASKS_MD" ]; then
+  echo "[$(date)] ℹ️  tasks.md not found for $CURRENT_INCREMENT (increment may be in planning stage)" >> "$DEBUG_LOG" 2>/dev/null || true
+  rm -f "$STDIN_DATA"
+  cat <<EOF
+{
+  "continue": true
+}
+EOF
+  exit 0
+fi
+
+# ============================================================================
+# RUN AC TEST VALIDATION
+# ============================================================================
+
+echo "[$(date)] 🧪 Running AC test validation for $CURRENT_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# Determine which validation script to use
+VALIDATOR_SCRIPT=""
+if [ -f "$PROJECT_ROOT/dist/src/core/ac-test-validator-cli.js" ]; then
+  VALIDATOR_SCRIPT="$PROJECT_ROOT/dist/src/core/ac-test-validator-cli.js"
+elif [ -f "$PROJECT_ROOT/node_modules/specweave/dist/src/core/ac-test-validator-cli.js" ]; then
+  VALIDATOR_SCRIPT="$PROJECT_ROOT/node_modules/specweave/dist/src/core/ac-test-validator-cli.js"
+elif [ -n "${CLAUDE_PLUGIN_ROOT}" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/dist/src/core/ac-test-validator-cli.js" ]; then
+  VALIDATOR_SCRIPT="${CLAUDE_PLUGIN_ROOT}/dist/src/core/ac-test-validator-cli.js"
+fi
+
+if [ -z "$VALIDATOR_SCRIPT" ] || ! command -v node &> /dev/null; then
+  echo "[$(date)] ⚠️  AC test validator not found or Node.js missing" >> "$DEBUG_LOG" 2>/dev/null || true
+  rm -f "$STDIN_DATA"
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "⚠️  Warning: AC test validator not available. Task completion validation skipped. Install Node.js and rebuild SpecWeave to enable validation."
+}
+EOF
+  exit 0
+fi
+
+# Run validator (captures exit code)
+VALIDATION_OUTPUT=$(mktemp)
+VALIDATION_EXIT_CODE=0
+
+(cd "$PROJECT_ROOT" && node "$VALIDATOR_SCRIPT" "$CURRENT_INCREMENT") > "$VALIDATION_OUTPUT" 2>&1 || VALIDATION_EXIT_CODE=$?
+
+echo "[$(date)] Validator exit code: $VALIDATION_EXIT_CODE" >> "$DEBUG_LOG" 2>/dev/null || true
+cat "$VALIDATION_OUTPUT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+rm -f "$STDIN_DATA"
+
+# ============================================================================
+# DECISION LOGIC
+# ============================================================================
+
+if [ "$VALIDATION_EXIT_CODE" = "0" ]; then
+  # Validation passed - allow completion
+  echo "[$(date)] ✅ AC test validation passed" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  VALIDATION_SUMMARY=$(cat "$VALIDATION_OUTPUT" | tail -5 | tr '\n' ' ')
+
+  rm -f "$VALIDATION_OUTPUT"
+
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "✅ AC Test Validation Passed: All acceptance criteria have passing tests. Task completion allowed. ${VALIDATION_SUMMARY}"
+}
+EOF
+else
+  # Validation failed - block completion
+  echo "[$(date)] ❌ AC test validation failed" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  VALIDATION_ERROR=$(cat "$VALIDATION_OUTPUT" | grep -A 10 "VALIDATION FAILED" | tr '\n' ' ' | cut -c 1-300)
+
+  rm -f "$VALIDATION_OUTPUT"
+
+  cat <<EOF
+{
+  "continue": false,
+  "systemMessage": "❌ AC TEST VALIDATION FAILED: Cannot mark task as complete until all acceptance criteria have passing tests. ${VALIDATION_ERROR}
+
+Fix the failing tests and try again. Run tests manually: npm test"
+}
+EOF
+fi

package/plugins/specweave/hooks/pre-tool-use.sh

@@ -128,18 +128,9 @@ rm -f "$STDIN_DATA"
 # ============================================================================
 
 if [ "$TOOL_NAME" = "AskUserQuestion" ]; then
-  cat <<EOF
-{
-  "continue": true,
-  "systemMessage": "🔔 Sound played - user notified of question request"
-}
-EOF
+  echo '{"continue":true,"systemMessage":"🔔 Sound played - user notified of question request"}'
 else
-  cat <<EOF
-{
-  "continue": true
-}
-EOF
+  echo '{"continue":true}'
 fi
 
 # ALWAYS exit 0 - NEVER let hook errors crash Claude Code

package/plugins/specweave/hooks/pre-tool-use.sh.backup

@@ -0,0 +1,133 @@
+#!/bin/bash
+
+# SpecWeave Pre-Tool-Use Hook
+# Runs BEFORE Claude calls any tool (PreToolUse event)
+#
+# PURPOSE: Detect when Claude asks questions via AskUserQuestion
+# - Plays sound IMMEDIATELY when question is about to be asked
+# - Complements post-task-completion hook (which only fires after TodoWrite)
+# - Ensures user is always notified when Claude needs input
+#
+# SCOPE:
+# - This hook fires for ALL tool calls (Read, Edit, Write, AskUserQuestion, etc.)
+# - We filter for AskUserQuestion specifically to play sound
+# - Non-blocking and fast (<10ms overhead)
+
+set -e
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+# Find project root
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # Fallback
+  if [ -d "$(pwd)/.specweave" ]; then
+    pwd
+  else
+    echo "$(pwd)"
+  fi
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT" 2>/dev/null || true
+
+LOGS_DIR=".specweave/logs"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+
+mkdir -p "$LOGS_DIR" 2>/dev/null || true
+
+# ============================================================================
+# CAPTURE INPUT (Tool Call Details)
+# ============================================================================
+
+STDIN_DATA=$(mktemp)
+cat > "$STDIN_DATA"
+
+# Log the tool call for debugging
+echo "[$(date)] 🔧 PreToolUse hook fired" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "[$(date)] Tool call JSON:" >> "$DEBUG_LOG" 2>/dev/null || true
+cat "$STDIN_DATA" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# DETECT AskUserQuestion TOOL
+# ============================================================================
+
+TOOL_NAME=""
+
+if command -v jq >/dev/null 2>&1; then
+  # Use jq if available (most reliable)
+  TOOL_NAME=$(jq -r '.tool_name // empty' "$STDIN_DATA" 2>/dev/null)
+else
+  # Fallback: grep-based detection
+  if grep -q '"tool_name"' "$STDIN_DATA" 2>/dev/null; then
+    TOOL_NAME=$(grep -o '"tool_name":"[^"]*"' "$STDIN_DATA" | cut -d'"' -f4)
+  fi
+fi
+
+echo "[$(date)] Tool name: $TOOL_NAME" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# PLAY SOUND IF AskUserQuestion
+# ============================================================================
+
+play_sound() {
+  case "$(uname -s)" in
+    Darwin)
+      # macOS: Use afplay with a distinctive sound for questions
+      afplay /System/Library/Sounds/Tink.aiff 2>/dev/null || true
+      ;;
+    Linux)
+      # Linux: Use paplay or aplay
+      paplay /usr/share/sounds/freedesktop/stereo/dialog-question.oga 2>/dev/null || \
+      paplay /usr/share/sounds/freedesktop/stereo/message-new-instant.oga 2>/dev/null || \
+      aplay /usr/share/sounds/alsa/Front_Center.wav 2>/dev/null || true
+      ;;
+    MINGW*|MSYS*|CYGWIN*)
+      # Windows: Use PowerShell
+      powershell -c "(New-Object Media.SoundPlayer 'C:\Windows\Media\Windows Notify.wav').PlaySync();" 2>/dev/null || true
+      ;;
+  esac
+}
+
+if [ "$TOOL_NAME" = "AskUserQuestion" ]; then
+  echo "[$(date)] 🔔 QUESTION DETECTED! Playing notification sound" >> "$DEBUG_LOG" 2>/dev/null || true
+  play_sound
+
+  # Log this event
+  echo "[$(date)] Claude is asking for user input via AskUserQuestion" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
+# ============================================================================
+# CLEANUP
+# ============================================================================
+
+rm -f "$STDIN_DATA"
+
+# ============================================================================
+# OUTPUT TO CLAUDE (Always continue)
+# ============================================================================
+
+if [ "$TOOL_NAME" = "AskUserQuestion" ]; then
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "🔔 Sound played - user notified of question request"
+}
+EOF
+else
+  cat <<EOF
+{
+  "continue": true
+}
+EOF
+fi

package/plugins/specweave/hooks/spec-project-validator.sh

@@ -12,11 +12,21 @@
 # Rules:
 # - 1-level structure: spec.md MUST have `project:` in YAML frontmatter
 # - 2-level structure: spec.md MUST have BOTH `project:` AND `board:` in frontmatter
+# - Project MUST exist in configuration (validated via specweave context projects)
+# - Board MUST exist under project for 2-level (validated via specweave context boards)
 #
 # Returns exit code 1 (block) if validation fails, 0 (allow) otherwise.
+#
+# Bypass: Set SPECWEAVE_FORCE_PROJECT=1 to skip validation
 
 set -e
 
+# Check for force bypass
+if [ "$SPECWEAVE_FORCE_PROJECT" = "1" ]; then
+  echo '{"decision": "allow", "message": "⚠️  Project validation bypassed (SPECWEAVE_FORCE_PROJECT=1)"}'
+  exit 0
+fi
+
 # Read tool input from stdin
 INPUT=$(cat)
 
@@ -33,7 +43,7 @@ fi
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
 
 # Only validate spec.md files in increments folder
-if [[ ! "$FILE_PATH" =~ \.specweave/increments/[0-9]{4}-[^/]+/spec\.md$ ]]; then
+if [[ ! "$FILE_PATH" =~ \.specweave/increments/[0-9]{4}E?-[^/]+/spec\.md$ ]]; then
   echo '{"decision": "allow"}'
   exit 0
 fi
@@ -52,58 +62,103 @@ FRONTMATTER=$(echo "$CONTENT" | sed -n '/^---$/,/^---$/p' | tail -n +2 | head -n
 
 # Check for unresolved project placeholder
 if echo "$FRONTMATTER" | grep -q 'project:\s*{{PROJECT_ID}}'; then
-  echo '{"decision": "block", "reason": "spec.md has unresolved placeholder {{PROJECT_ID}}. Run STEP 0B to select project before creating spec.md."}'
+  echo '{"decision": "block", "reason": "spec.md has unresolved placeholder {{PROJECT_ID}}. Run '\''specweave context projects'\'' to get available projects, then select one."}'
   exit 0
 fi
 
 # Check for unresolved board placeholder
 if echo "$FRONTMATTER" | grep -q 'board:\s*{{BOARD_ID}}'; then
-  echo '{"decision": "block", "reason": "spec.md has unresolved placeholder {{BOARD_ID}}. Run STEP 0B to select board before creating spec.md."}'
+  echo '{"decision": "block", "reason": "spec.md has unresolved placeholder {{BOARD_ID}}. Run '\''specweave context boards --project=<id>'\'' to get available boards, then select one."}'
   exit 0
 fi
 
-# Check for project field
+# Extract project and board from frontmatter
 PROJECT=$(echo "$FRONTMATTER" | grep -E '^project:\s*' | sed 's/^project:\s*//' | tr -d '"'"'" | tr -d '[:space:]')
+BOARD=$(echo "$FRONTMATTER" | grep -E '^board:\s*' | sed 's/^board:\s*//' | tr -d '"'"'" | tr -d '[:space:]')
 
-# Detect structure level by checking config
+# Get project root from file path
 PROJECT_ROOT="${FILE_PATH%%/.specweave/*}"
-CONFIG_PATH="$PROJECT_ROOT/.specweave/config.json"
 
-IS_2_LEVEL=false
+# Change to project root for specweave command
+cd "$PROJECT_ROOT" 2>/dev/null || true
 
-if [ -f "$CONFIG_PATH" ]; then
-  # Check for ADO area path mapping (indicates 2-level)
-  if jq -e '.sync.profiles | to_entries[] | select(.value.provider == "ado") | .value.config.areaPathMapping.mappings | length > 0' "$CONFIG_PATH" >/dev/null 2>&1; then
-    IS_2_LEVEL=true
-  fi
+# Get project context via CLI command
+CONTEXT_OUTPUT=$(specweave context projects 2>/dev/null || echo '{"level": 1, "projects": []}')
 
-  # Check for ADO areaPaths (indicates 2-level)
-  if jq -e '.sync.profiles | to_entries[] | select(.value.provider == "ado") | .value.config.areaPaths | length > 0' "$CONFIG_PATH" >/dev/null 2>&1; then
-    IS_2_LEVEL=true
-  fi
-fi
+# Parse structure level
+STRUCTURE_LEVEL=$(echo "$CONTEXT_OUTPUT" | jq -r '.level // 1')
+
+# Parse available projects
+AVAILABLE_PROJECTS=$(echo "$CONTEXT_OUTPUT" | jq -r '.projects[].id // empty' | tr '\n' ', ' | sed 's/,$//')
 
 # Validation based on structure level
-if [ "$IS_2_LEVEL" = true ]; then
+if [ "$STRUCTURE_LEVEL" = "2" ]; then
   # 2-level: BOTH project AND board required
+
+  # Check project field exists
   if [ -z "$PROJECT" ] || [ "$PROJECT" = "null" ]; then
-    echo '{"decision": "block", "reason": "spec.md missing required '\''project:'\'' field in YAML frontmatter. This is a 2-level structure - add '\''project: <project_name>'\'' to frontmatter."}'
+    echo "{\"decision\": \"block\", \"reason\": \"spec.md missing required 'project:' field in YAML frontmatter.\\n\\n2-level structure detected.\\n\\nAvailable projects: ${AVAILABLE_PROJECTS:-none detected}\\n\\nAdd 'project: <project_name>' to frontmatter.\\n\\nRun 'specweave context projects' to see all options.\"}"
     exit 0
   fi
 
-  BOARD=$(echo "$FRONTMATTER" | grep -E '^board:\s*' | sed 's/^board:\s*//' | tr -d '"'"'" | tr -d '[:space:]')
-
+  # Check board field exists
   if [ -z "$BOARD" ] || [ "$BOARD" = "null" ]; then
-    echo '{"decision": "block", "reason": "spec.md missing required '\''board:'\'' field in YAML frontmatter. This is a 2-level structure - add '\''board: <board_name>'\'' to frontmatter."}'
+    # Get available boards for the project
+    AVAILABLE_BOARDS=$(specweave context boards --project="$PROJECT" 2>/dev/null | jq -r '.boards[].id // empty' | tr '\n' ', ' | sed 's/,$//')
+
+    echo "{\"decision\": \"block\", \"reason\": \"spec.md missing required 'board:' field in YAML frontmatter.\\n\\n2-level structure detected (project: ${PROJECT}).\\n\\nAvailable boards: ${AVAILABLE_BOARDS:-none detected}\\n\\nAdd 'board: <board_name>' to frontmatter.\\n\\nRun 'specweave context boards --project=${PROJECT}' to see all options.\"}"
     exit 0
   fi
+
+  # Validate project exists in configuration
+  PROJECT_EXISTS=$(echo "$CONTEXT_OUTPUT" | jq --arg proj "$PROJECT" '.projects[] | select(.id == $proj)' 2>/dev/null)
+  if [ -z "$PROJECT_EXISTS" ]; then
+    # Try case-insensitive match
+    PROJECT_EXISTS=$(echo "$CONTEXT_OUTPUT" | jq --arg proj "$PROJECT" '.projects[] | select(.id | ascii_downcase == ($proj | ascii_downcase))' 2>/dev/null)
+  fi
+
+  if [ -z "$PROJECT_EXISTS" ] && [ -n "$AVAILABLE_PROJECTS" ]; then
+    echo "{\"decision\": \"block\", \"reason\": \"Project '${PROJECT}' not found in configuration.\\n\\nAvailable projects: ${AVAILABLE_PROJECTS}\\n\\nEither:\\n1. Update project: field to a valid project\\n2. Set SPECWEAVE_FORCE_PROJECT=1 to bypass validation\"}"
+    exit 0
+  fi
+
+  # Validate board exists under project
+  BOARDS_OUTPUT=$(specweave context boards --project="$PROJECT" 2>/dev/null || echo '{"boards": []}')
+  BOARD_EXISTS=$(echo "$BOARDS_OUTPUT" | jq --arg board "$BOARD" '.boards[] | select(.id == $board)' 2>/dev/null)
+
+  if [ -z "$BOARD_EXISTS" ]; then
+    # Try case-insensitive match
+    BOARD_EXISTS=$(echo "$BOARDS_OUTPUT" | jq --arg board "$BOARD" '.boards[] | select(.id | ascii_downcase == ($board | ascii_downcase))' 2>/dev/null)
+  fi
+
+  AVAILABLE_BOARDS=$(echo "$BOARDS_OUTPUT" | jq -r '.boards[].id // empty' | tr '\n' ', ' | sed 's/,$//')
+
+  if [ -z "$BOARD_EXISTS" ] && [ -n "$AVAILABLE_BOARDS" ]; then
+    echo "{\"decision\": \"block\", \"reason\": \"Board '${BOARD}' not found under project '${PROJECT}'.\\n\\nAvailable boards: ${AVAILABLE_BOARDS}\\n\\nEither:\\n1. Update board: field to a valid board\\n2. Set SPECWEAVE_FORCE_PROJECT=1 to bypass validation\"}"
+    exit 0
+  fi
+
 else
-  # 1-level: project is strongly recommended (warning, not block)
+  # 1-level: project is REQUIRED (not just recommended)
+
   if [ -z "$PROJECT" ] || [ "$PROJECT" = "null" ]; then
-    # For 1-level, we warn but don't block (backward compatibility)
-    echo '{"decision": "allow", "message": "⚠️  spec.md should have '\''project:'\'' field in YAML frontmatter for explicit sync target."}'
+    echo "{\"decision\": \"block\", \"reason\": \"spec.md missing required 'project:' field in YAML frontmatter.\\n\\nAvailable projects: ${AVAILABLE_PROJECTS:-none detected}\\n\\nAdd 'project: <project_name>' to frontmatter.\\n\\nRun 'specweave context projects' to see all options.\"}"
     exit 0
   fi
+
+  # Validate project exists in configuration (if we have projects configured)
+  if [ -n "$AVAILABLE_PROJECTS" ]; then
+    PROJECT_EXISTS=$(echo "$CONTEXT_OUTPUT" | jq --arg proj "$PROJECT" '.projects[] | select(.id == $proj)' 2>/dev/null)
+    if [ -z "$PROJECT_EXISTS" ]; then
+      # Try case-insensitive match
+      PROJECT_EXISTS=$(echo "$CONTEXT_OUTPUT" | jq --arg proj "$PROJECT" '.projects[] | select(.id | ascii_downcase == ($proj | ascii_downcase))' 2>/dev/null)
+    fi
+
+    if [ -z "$PROJECT_EXISTS" ]; then
+      echo "{\"decision\": \"block\", \"reason\": \"Project '${PROJECT}' not found in configuration.\\n\\nAvailable projects: ${AVAILABLE_PROJECTS}\\n\\nEither:\\n1. Update project: field to a valid project\\n2. Set SPECWEAVE_FORCE_PROJECT=1 to bypass validation\"}"
+      exit 0
+    fi
+  fi
 fi
 
 # All validations passed