specweave 0.33.3 → 0.33.5

package/plugins/specweave/scripts/session-watchdog.sh

@@ -1,7 +1,14 @@
 #!/usr/bin/env bash
-# SpecWeave Session Watchdog
-# Monitors Claude Code sessions and alerts when stuck
-# Usage: bash session-watchdog.sh [--daemon] [--interval=60]
+# SpecWeave Session Watchdog v2.0
+# Monitors Claude Code sessions and alerts ONLY when something is REALLY wrong
+#
+# FIXES (2025-12-10):
+# - ELIMINATED FALSE POSITIVES: No longer triggers on stale files alone
+# - SMART DETECTION: Verifies actual stuck processes, not just file ages
+# - SEVERITY LEVELS: Only CRITICAL issues trigger notifications
+# - DIAGNOSTICS: Writes detailed logs for /specweave:jobs to display
+#
+# Usage: bash session-watchdog.sh [--daemon] [--interval=60] [--threshold=300]
 
 set -euo pipefail
 
@@ -10,16 +17,24 @@ STUCK_THRESHOLD_SECONDS="${STUCK_THRESHOLD:-300}"  # 5 minutes
 CHECK_INTERVAL="${CHECK_INTERVAL:-60}"             # 1 minute
 SPECWEAVE_ROOT="${SPECWEAVE_ROOT:-.specweave}"
 SIGNAL_FILE="${SPECWEAVE_ROOT}/state/.session-stuck"
-HEARTBEAT_FILE="${SPECWEAVE_ROOT}/state/.heartbeat"
+DIAGNOSTICS_FILE="${SPECWEAVE_ROOT}/state/.watchdog-diagnostics.json"
 DAEMON_MODE=false
-PROJECT_ROOT="${PWD}"
-SESSION_ID="watchdog-$$-$(date +%s)"
-COORDINATION_THRESHOLD=30  # Heartbeat threshold for active watchdog detection
+QUIET_MODE=false
+
+# Severity levels (only CRITICAL triggers notifications)
+SEVERITY_INFO=0
+SEVERITY_WARNING=1
+SEVERITY_CRITICAL=2
+
+# Track consecutive warnings (avoids single-check false positives)
+CONSECUTIVE_WARNINGS=0
+CONSECUTIVE_THRESHOLD=3  # Need 3 consecutive warnings before alerting
 
 # Colors
 RED='\033[0;31m'
 YELLOW='\033[1;33m'
 GREEN='\033[0;32m'
+BLUE='\033[0;34m'
 NC='\033[0m'
 
 # Parse arguments
@@ -28,6 +43,9 @@ for arg in "$@"; do
     --daemon)
       DAEMON_MODE=true
       ;;
+    --quiet)
+      QUIET_MODE=true
+      ;;
     --interval=*)
       CHECK_INTERVAL="${arg#*=}"
       ;;
@@ -38,130 +56,316 @@ for arg in "$@"; do
 done
 
 log() {
+  [[ "$QUIET_MODE" == "true" ]] && return
   echo -e "[$(date '+%H:%M:%S')] $1"
 }
 
+log_debug() {
+  # Always write to diagnostics file even in quiet mode
+  echo "[$(date '+%H:%M:%S')] $1" >> "${SPECWEAVE_ROOT}/logs/watchdog.log" 2>/dev/null || true
+}
+
+# Send notification ONLY for critical issues
 send_notification() {
-  local title="$1"
-  local message="$2"
+  local severity="$1"
+  local title="$2"
+  local message="$3"
 
-  # macOS notification
+  # Only notify for CRITICAL severity
+  if [[ "$severity" -lt "$SEVERITY_CRITICAL" ]]; then
+    log_debug "Skipping notification (severity=$severity, need=$SEVERITY_CRITICAL): $message"
+    return
+  fi
+
+  # macOS notification - use "Submarine" for warnings (not alarming like "Basso")
+  # Per CLAUDE.md section 11: Basso = ONLY critical errors requiring IMMEDIATE action
+  # Zombie detection is recoverable - user can run cleanup script when convenient
   if command -v osascript &> /dev/null; then
-    osascript -e "display notification \"$message\" with title \"$title\" sound name \"Basso\""
+    osascript -e "display notification \"$message\" with title \"$title\" sound name \"Submarine\""
   fi
 
-  # Linux notification (if available)
+  # Linux notification (if available) - use "normal" urgency (not "critical")
+  # Critical urgency can bypass Do Not Disturb, which is too aggressive
   if command -v notify-send &> /dev/null; then
-    notify-send "$title" "$message" --urgency=critical
+    notify-send "$title" "$message" --urgency=normal
   fi
+
+  # Windows: notifications sent via PowerShell toast don't have urgency levels
+  # They're always non-alarming by design
 }
 
 get_file_age_seconds() {
   local file="$1"
   if [[ ! -f "$file" ]]; then
-    echo "999999"
+    echo "-1"  # -1 means file doesn't exist (not an error)
     return
   fi
 
-  local now
-  local mtime
+  local now mtime
   now=$(date +%s)
 
   if [[ "$(uname)" == "Darwin" ]]; then
-    mtime=$(stat -f %m "$file")
+    mtime=$(stat -f %m "$file" 2>/dev/null || echo "$now")
   else
-    mtime=$(stat -c %Y "$file")
+    mtime=$(stat -c %Y "$file" 2>/dev/null || echo "$now")
   fi
 
   echo $((now - mtime))
 }
 
+# Check if a process is actually running
+is_process_running() {
+  local pid="$1"
+  if [[ -z "$pid" ]] || [[ "$pid" == "0" ]]; then
+    return 1
+  fi
+  kill -0 "$pid" 2>/dev/null
+}
+
+# SMART lock file check - verifies the PROCESS is actually stuck, not just file age
 check_lock_file() {
+  local lock_dir="${SPECWEAVE_ROOT}/state/.processor.lock.d"
   local lock_file="${SPECWEAVE_ROOT}/state/.processor.lock"
-  if [[ -f "$lock_file" ]]; then
+  local result_severity=$SEVERITY_INFO
+  local result_message=""
+
+  # Check new lock directory format first (v2)
+  if [[ -d "$lock_dir" ]] && [[ -f "$lock_dir/pid" ]]; then
+    local lock_pid
+    lock_pid=$(cat "$lock_dir/pid" 2>/dev/null || echo "")
+
+    if [[ -n "$lock_pid" ]]; then
+      if is_process_running "$lock_pid"; then
+        # Process is actually running - check how long
+        local age
+        age=$(get_file_age_seconds "$lock_dir/pid")
+        if [[ "$age" -gt "$STUCK_THRESHOLD_SECONDS" ]]; then
+          result_severity=$SEVERITY_WARNING
+          result_message="Processor PID $lock_pid running for ${age}s (might be legitimate long operation)"
+        else
+          result_message="Processor PID $lock_pid active (${age}s)"
+        fi
+      else
+        # PID file exists but process is dead = STALE LOCK (cleanup needed, not stuck)
+        result_severity=$SEVERITY_WARNING
+        result_message="Stale lock: PID $lock_pid no longer running (auto-cleanup will handle)"
+        # Don't trigger alert - processor will clean this up on next run
+      fi
+    fi
+  # Check old lock file format (legacy)
+  elif [[ -f "$lock_file" ]]; then
     local age
     age=$(get_file_age_seconds "$lock_file")
     if [[ "$age" -gt "$STUCK_THRESHOLD_SECONDS" ]]; then
-      log "${RED}⚠️  STUCK DETECTED: Lock file held for ${age}s (threshold: ${STUCK_THRESHOLD_SECONDS}s)${NC}"
-      return 1
+      result_severity=$SEVERITY_WARNING
+      result_message="Legacy lock file age: ${age}s (consider running cleanup-state.sh)"
     fi
   fi
-  return 0
+
+  # Write diagnostic
+  echo "lock_status=$result_severity" >> "$DIAGNOSTICS_FILE.tmp"
+  echo "lock_message=$result_message" >> "$DIAGNOSTICS_FILE.tmp"
+
+  if [[ -n "$result_message" ]]; then
+    log_debug "Lock check: $result_message"
+  fi
+
+  return $result_severity
 }
 
-check_heartbeat() {
-  if [[ -f "$HEARTBEAT_FILE" ]]; then
-    local age
-    age=$(get_file_age_seconds "$HEARTBEAT_FILE")
-    if [[ "$age" -gt "$STUCK_THRESHOLD_SECONDS" ]]; then
-      log "${RED}⚠️  STUCK DETECTED: No heartbeat for ${age}s${NC}"
-      return 1
-    fi
+# Check for ACTUAL zombie heredoc processes (CRITICAL - this is a real stuck indicator)
+check_zombie_processes() {
+  local result_severity=$SEVERITY_INFO
+  local result_message=""
+
+  # Look for cat processes waiting for EOF (heredoc stuck)
+  local cat_zombies
+  cat_zombies=$(pgrep -f "cat.*EOF" 2>/dev/null | wc -l | tr -d ' \n' || echo "0")
+  cat_zombies="${cat_zombies:-0}"
+  [[ ! "$cat_zombies" =~ ^[0-9]+$ ]] && cat_zombies=0
+
+  # Look for bash processes that seem stuck on heredoc
+  local bash_heredocs
+  bash_heredocs=$(pgrep -f "bash.*<<" 2>/dev/null | wc -l | tr -d ' \n' || echo "0")
+  bash_heredocs="${bash_heredocs:-0}"
+  [[ ! "$bash_heredocs" =~ ^[0-9]+$ ]] && bash_heredocs=0
+
+  local total_zombies=$((cat_zombies + bash_heredocs))
+
+  if [[ "$total_zombies" -gt 0 ]]; then
+    result_severity=$SEVERITY_CRITICAL  # This is DEFINITELY stuck!
+    result_message="$total_zombies zombie heredoc processes detected (cat=$cat_zombies, bash=$bash_heredocs)"
+    log "${RED}🚨 CRITICAL: $result_message${NC}"
   fi
-  return 0
+
+  echo "zombie_count=$total_zombies" >> "$DIAGNOSTICS_FILE.tmp"
+  echo "zombie_message=$result_message" >> "$DIAGNOSTICS_FILE.tmp"
+
+  return $result_severity
 }
 
-check_mcp_drops() {
+# Check MCP connection health (WARNING level, not critical)
+check_mcp_health() {
+  local result_severity=$SEVERITY_INFO
+  local result_message=""
+  local drops=0
   local debug_log="$HOME/.claude/debug/latest"
+
   if [[ -f "$debug_log" ]]; then
-    local drops
-    drops=$(grep -c "WS-IDE connection dropped" "$debug_log" 2>/dev/null | head -1 || echo "0")
+    # Count MCP drops in last 500 lines
+    drops=$(tail -500 "$debug_log" 2>/dev/null | grep -c "WS-IDE connection dropped" 2>/dev/null || echo "0")
     drops="${drops//[^0-9]/}"
     drops="${drops:-0}"
-    if [[ "$drops" -gt 3 ]]; then
-      log "${YELLOW}⚠️  MCP instability: $drops connection drops detected${NC}"
-      return 1
+    [[ ! "$drops" =~ ^[0-9]+$ ]] && drops=0
+
+    if [[ "$drops" -gt 10 ]]; then
+      result_severity=$SEVERITY_WARNING
+      result_message="MCP instability: $drops connection drops (consider restarting VS Code Extension Host)"
+    elif [[ "$drops" -gt 3 ]]; then
+      result_message="MCP: $drops drops detected (minor instability)"
     fi
   fi
-  return 0
-}
 
-check_zombie_processes() {
-  local zombies
-  zombies=$(pgrep -f "cat.*EOF" 2>/dev/null | wc -l | tr -d ' ')
-  if [[ "$zombies" -gt 0 ]]; then
-    log "${RED}⚠️  STUCK DETECTED: $zombies zombie heredoc processes${NC}"
-    return 1
-  fi
-  return 0
-}
+  echo "mcp_drops=$drops" >> "$DIAGNOSTICS_FILE.tmp"
+  echo "mcp_message=$result_message" >> "$DIAGNOSTICS_FILE.tmp"
 
-check_session_health() {
-  local stuck=false
-  local reasons=()
+  return $result_severity
+}
 
-  if ! check_lock_file; then
-    stuck=true
-    reasons+=("Lock file stale")
+# Check for orphaned background jobs (informational, not critical)
+check_orphaned_jobs() {
+  local result_severity=$SEVERITY_INFO
+  local result_message=""
+  local jobs_dir="${SPECWEAVE_ROOT}/state/jobs"
+  local orphaned_count=0
+
+  if [[ -d "$jobs_dir" ]]; then
+    for job_dir in "$jobs_dir"/*/; do
+      [[ ! -d "$job_dir" ]] && continue
+
+      local pid_file="${job_dir}worker.pid"
+      local config_file="${job_dir}config.json"
+
+      if [[ -f "$pid_file" ]] && [[ -f "$config_file" ]]; then
+        local pid
+        pid=$(cat "$pid_file" 2>/dev/null || echo "")
+        if [[ -n "$pid" ]] && ! is_process_running "$pid"; then
+          orphaned_count=$((orphaned_count + 1))
+        fi
+      fi
+    done
   fi
 
-  if ! check_heartbeat; then
-    stuck=true
-    reasons+=("No heartbeat")
+  if [[ "$orphaned_count" -gt 0 ]]; then
+    result_message="$orphaned_count orphaned job(s) found (run /specweave:jobs to see details)"
   fi
 
-  if ! check_mcp_drops; then
-    reasons+=("MCP unstable")
-  fi
+  echo "orphaned_jobs=$orphaned_count" >> "$DIAGNOSTICS_FILE.tmp"
+  echo "orphaned_message=$result_message" >> "$DIAGNOSTICS_FILE.tmp"
+
+  return $result_severity
+}
+
+# Write diagnostics file for /specweave:jobs to read
+write_diagnostics() {
+  local overall_severity="$1"
+  local overall_status="$2"
+
+  {
+    echo "{"
+    echo "  \"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\","
+    echo "  \"severity\": $overall_severity,"
+    echo "  \"status\": \"$overall_status\","
+
+    # Parse temp file into JSON
+    local lock_status="" lock_message="" zombie_count="" zombie_message=""
+    local mcp_drops="" mcp_message="" orphaned_jobs="" orphaned_message=""
+
+    while IFS='=' read -r key value; do
+      case "$key" in
+        lock_status) lock_status="$value" ;;
+        lock_message) lock_message="$value" ;;
+        zombie_count) zombie_count="$value" ;;
+        zombie_message) zombie_message="$value" ;;
+        mcp_drops) mcp_drops="$value" ;;
+        mcp_message) mcp_message="$value" ;;
+        orphaned_jobs) orphaned_jobs="$value" ;;
+        orphaned_message) orphaned_message="$value" ;;
+      esac
+    done < "$DIAGNOSTICS_FILE.tmp" 2>/dev/null || true
+
+    # Sanitize numeric values (ensure single digit format)
+    lock_status="${lock_status:-0}"; [[ ! "$lock_status" =~ ^[0-9]+$ ]] && lock_status=0
+    zombie_count="${zombie_count:-0}"; [[ ! "$zombie_count" =~ ^[0-9]+$ ]] && zombie_count=0
+    mcp_drops="${mcp_drops:-0}"; [[ ! "$mcp_drops" =~ ^[0-9]+$ ]] && mcp_drops=0
+    orphaned_jobs="${orphaned_jobs:-0}"; [[ ! "$orphaned_jobs" =~ ^[0-9]+$ ]] && orphaned_jobs=0
+
+    echo "  \"checks\": {"
+    echo "    \"lock\": { \"severity\": $((lock_status)), \"message\": \"${lock_message:-ok}\" },"
+    echo "    \"zombies\": { \"count\": $((zombie_count)), \"message\": \"${zombie_message:-none}\" },"
+    echo "    \"mcp\": { \"drops\": $((mcp_drops)), \"message\": \"${mcp_message:-stable}\" },"
+    echo "    \"orphanedJobs\": { \"count\": $((orphaned_jobs)), \"message\": \"${orphaned_message:-none}\" }"
+    echo "  },"
+    echo "  \"consecutiveWarnings\": $CONSECUTIVE_WARNINGS,"
+    echo "  \"thresholdSeconds\": $STUCK_THRESHOLD_SECONDS,"
+    echo "  \"checkIntervalSeconds\": $CHECK_INTERVAL"
+    echo "}"
+  } > "$DIAGNOSTICS_FILE"
+
+  rm -f "$DIAGNOSTICS_FILE.tmp"
+}
 
-  if ! check_zombie_processes; then
-    stuck=true
-    reasons+=("Zombie processes")
+check_session_health() {
+  local max_severity=$SEVERITY_INFO
+  local issues=()
+
+  # Initialize temp diagnostics file
+  mkdir -p "$(dirname "$DIAGNOSTICS_FILE")"
+  : > "$DIAGNOSTICS_FILE.tmp"
+
+  # Run all checks
+  check_lock_file || true
+  local lock_sev=$?
+  [[ $lock_sev -gt $max_severity ]] && max_severity=$lock_sev
+
+  check_zombie_processes || true
+  local zombie_sev=$?
+  [[ $zombie_sev -gt $max_severity ]] && max_severity=$zombie_sev
+
+  check_mcp_health || true
+  local mcp_sev=$?
+  [[ $mcp_sev -gt $max_severity ]] && max_severity=$mcp_sev
+
+  check_orphaned_jobs || true
+
+  # Determine overall status
+  local overall_status="healthy"
+  if [[ $max_severity -eq $SEVERITY_CRITICAL ]]; then
+    overall_status="critical"
+    CONSECUTIVE_WARNINGS=$((CONSECUTIVE_WARNINGS + 1))
+  elif [[ $max_severity -eq $SEVERITY_WARNING ]]; then
+    overall_status="warning"
+    CONSECUTIVE_WARNINGS=$((CONSECUTIVE_WARNINGS + 1))
+  else
+    overall_status="healthy"
+    CONSECUTIVE_WARNINGS=0  # Reset on healthy check
   fi
 
-  if [[ "$stuck" == "true" ]]; then
-    local reason_str
-    reason_str=$(IFS=", "; echo "${reasons[*]}")
+  # Write diagnostics for /specweave:jobs
+  write_diagnostics "$max_severity" "$overall_status"
 
+  # Only alert if CRITICAL and seen multiple consecutive times
+  if [[ $max_severity -eq $SEVERITY_CRITICAL ]] && [[ $CONSECUTIVE_WARNINGS -ge $CONSECUTIVE_THRESHOLD ]]; then
     # Create signal file
     echo "stuck_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$SIGNAL_FILE"
-    echo "reasons=$reason_str" >> "$SIGNAL_FILE"
+    echo "severity=critical" >> "$SIGNAL_FILE"
+    echo "consecutive_warnings=$CONSECUTIVE_WARNINGS" >> "$SIGNAL_FILE"
 
-    send_notification "🚨 Claude Code Stuck" "$reason_str - Run cleanup-state.sh"
+    send_notification $SEVERITY_CRITICAL "🚨 Claude Code STUCK" "Zombie processes detected - Run cleanup-state.sh"
 
     log "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-    log "${RED}SESSION STUCK DETECTED${NC}"
-    log "${RED}Reasons: $reason_str${NC}"
+    log "${RED}CRITICAL: SESSION STUCK DETECTED${NC}"
+    log "${RED}Consecutive warnings: $CONSECUTIVE_WARNINGS${NC}"
     log ""
     log "Recovery steps:"
     log "  1. Press Ctrl+C multiple times in Claude Code terminal"
@@ -171,85 +375,35 @@ check_session_health() {
     log "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 
     return 1
+
+  elif [[ $max_severity -eq $SEVERITY_WARNING ]]; then
+    # Log warning but don't notify (might be false positive)
+    log "${YELLOW}⚠️  Warning detected (${CONSECUTIVE_WARNINGS}/${CONSECUTIVE_THRESHOLD} before alert)${NC}"
+    return 0
+
   else
-    # Remove signal file if exists
+    # Healthy - remove signal file if exists
     rm -f "$SIGNAL_FILE"
     log "${GREEN}✓ Session healthy${NC}"
     return 0
   fi
 }
 
-# Coordination Functions
-check_active_watchdog() {
-  # Check if another watchdog is running via session registry
-  node "${PROJECT_ROOT}/dist/src/cli/check-watchdog.js" 2>/dev/null || echo ""
-}
-
-register_watchdog() {
-  # Register this watchdog in session registry
-  node "${PROJECT_ROOT}/dist/src/cli/register-session.js" "$SESSION_ID" $$ "watchdog" 2>&1 | \
-    grep -v "^$" | head -3
-}
-
-update_watchdog_heartbeat() {
-  # Update watchdog heartbeat
-  node "${PROJECT_ROOT}/dist/src/cli/update-heartbeat.js" "$SESSION_ID" 2>/dev/null || true
-}
-
-cleanup_watchdog() {
-  # Remove watchdog from registry on exit
-  node "${PROJECT_ROOT}/dist/src/cli/remove-session.js" "$SESSION_ID" 2>&1 | \
-    grep -v "^$" | head -3
-  log "Watchdog cleanup complete"
-}
-
-run_cleanup_service() {
-  # Run zombie process cleanup
-  node "${PROJECT_ROOT}/dist/src/cli/cleanup-zombies.js" 60 2>&1 | \
-    grep -v "^$" | head -10 || true
-}
-
 # Main execution
 if [[ "$DAEMON_MODE" == "true" ]]; then
-  # Coordination check before starting daemon
-  active_watchdog=$(check_active_watchdog)
-
-  if [[ -n "$active_watchdog" ]]; then
-    log "${YELLOW}Watchdog already active (PID: $active_watchdog)${NC}"
-    log "Exiting to avoid duplicate watchdogs"
-    exit 0
-  fi
-
-  # Register as watchdog
-  register_watchdog
-
-  # Trap signals for graceful shutdown
-  trap cleanup_watchdog SIGTERM SIGINT EXIT
-
-  log "Starting session watchdog daemon (interval: ${CHECK_INTERVAL}s, threshold: ${STUCK_THRESHOLD_SECONDS}s)"
-  log "Watchdog session: $SESSION_ID (PID: $$)"
+  log "${BLUE}Starting session watchdog v2.0 (smart detection, CRITICAL-only alerts)${NC}"
+  log "  Interval: ${CHECK_INTERVAL}s | Threshold: ${STUCK_THRESHOLD_SECONDS}s"
+  log "  Consecutive warnings needed: ${CONSECUTIVE_THRESHOLD}"
+  log "  Diagnostics: ${DIAGNOSTICS_FILE}"
   log "Press Ctrl+C to stop"
 
-  while true; do
-    # Update own heartbeat
-    update_watchdog_heartbeat
+  # Create log directory
+  mkdir -p "${SPECWEAVE_ROOT}/logs"
 
-    # Check session health
+  while true; do
     check_session_health || true
-
-    # Run cleanup service
-    run_cleanup_service
-
-    # Check if parent process still exists (if we have a parent session)
-    if ! kill -0 $PPID 2>/dev/null; then
-      log "${YELLOW}Parent process died, exiting watchdog${NC}"
-      break
-    fi
-
     sleep "$CHECK_INTERVAL"
   done
-
-  cleanup_watchdog
 else
   log "Running single health check..."
   check_session_health

package/plugins/specweave/skills/increment-planner/SKILL.md

@@ -178,26 +178,29 @@ echo "Using coverageTarget: $coverageTarget"
 
 ### STEP 0B: Get Project Context (MANDATORY - BLOCKING!)
 
-**⛔ DO NOT PROCEED TO STEP 1 WITHOUT COMPLETING THIS STEP!**
+**⛔ THIS IS A HARD BLOCK - YOU CANNOT PROCEED WITHOUT PROJECT CONTEXT!**
 
-Before generating ANY spec.md content, you MUST run this CLI command:
+**🚨 FAILURE TO COMPLETE THIS STEP = spec.md WILL BE BLOCKED BY VALIDATION HOOK!**
 
+Before generating ANY spec.md content, you MUST:
+
+**1. RUN THE CONTEXT API (via Bash tool):**
 ```bash
 specweave context projects
 ```
 
-This returns JSON with available projects and structure level:
+**2. CAPTURE AND STORE THE OUTPUT:**
 
+For 1-level structures:
 ```json
 {
   "level": 1,
   "projects": [{"id": "my-app", "name": "My App"}],
-  "detectionReason": "multiProject configuration",
-  "source": "multi-project"
+  "detectionReason": "multiProject configuration"
 }
 ```
 
-**For 2-level structures**, output includes boards:
+For 2-level structures (ADO/JIRA boards):
 ```json
 {
   "level": 2,
@@ -207,27 +210,54 @@ This returns JSON with available projects and structure level:
       {"id": "digital-ops", "name": "Digital Operations"},
       {"id": "mobile-team", "name": "Mobile Team"}
     ]
-  },
-  "detectionReason": "ADO area path mapping configured",
-  "source": "ado-area-path"
+  }
 }
 ```
 
-**VALIDATION RULES:**
+**3. RESOLVE PROJECT/BOARD FOR EACH USER STORY:**
+
+```
+CONTEXT_OUTPUT = <output from specweave context projects>
+
+For each US you will generate:
+  IF CONTEXT_OUTPUT.level == 1:
+    US.project = select from CONTEXT_OUTPUT.projects[].id
+
+  IF CONTEXT_OUTPUT.level == 2:
+    US.project = select from CONTEXT_OUTPUT.projects[].id
+    US.board = select from CONTEXT_OUTPUT.boardsByProject[project][].id
+```
+
+**4. NOW PROCEED TO STEP 1 (with resolved values stored)**
+
+---
+
+**VALIDATION RULES (ENFORCED BY HOOK):**
 
 ```
-✅ REQUIRED: Parse the JSON output and use ONLY those project/board values
-✅ REQUIRED: project field MUST match one of the returned projects[].id
-✅ REQUIRED: board field (2-level) MUST match one of boardsByProject[project].id
-❌ FORBIDDEN: Inventing or guessing project names
-❌ FORBIDDEN: Using folder name as project (e.g., "sw-olysense")
-❌ FORBIDDEN: Creating spec.md with {{PROJECT_ID}} placeholder
+✅ REQUIRED: Actually RUN "specweave context projects" command
+✅ REQUIRED: Parse the JSON and extract project IDs
+✅ REQUIRED: project field MUST match one of projects[].id from output
+✅ REQUIRED: board field (2-level) MUST match one of boardsByProject[project][].id
+✅ REQUIRED: Each US has **Project**: and **Board**: (2-level) with RESOLVED values
+
+❌ FORBIDDEN: Skipping this step and generating spec.md directly
+❌ FORBIDDEN: Inventing project names not in the API output
+❌ FORBIDDEN: Using folder names as project (e.g., "my-project-folder")
+❌ FORBIDDEN: Using {{PROJECT_ID}} or {{BOARD_ID}} placeholders
 ❌ FORBIDDEN: Creating spec.md for 2-level without board: field
+❌ FORBIDDEN: Generating spec.md without running context API first
 ```
 
+**WHY THIS IS BLOCKING:**
+- Hook `spec-project-validator.sh` BLOCKS spec.md with placeholders or invalid projects
+- Without resolved project/board, living docs sync FAILS
+- Without resolved project/board, external tool sync (GitHub/JIRA/ADO) FAILS
+- User gets blocked error and must manually fix - BAD UX!
+
 **Structure Levels:**
-- **1-Level**: `internal/specs/{project}/FS-XXX/` - requires `project` in spec.md
-- **2-Level**: `internal/specs/{project}/{board}/FS-XXX/` - requires BOTH `project` AND `board`
+- **1-Level**: `internal/specs/{project}/FS-XXX/` - requires `project` per US
+- **2-Level**: `internal/specs/{project}/{board}/FS-XXX/` - requires `project` AND `board` per US
 
 **Alternative: Interactive Selection:**
 ```bash