specweave 0.26.11 → 0.26.14

package/plugins/specweave/hooks/lib/update-status-line.sh

@@ -1,225 +1,189 @@
 #!/usr/bin/env bash
 #
-# update-status-line.sh (Enhanced with AC Metrics)
+# update-status-line.sh (v0.26.13 - ULTRA-OPTIMIZED for crash prevention)
 #
 # Updates status line cache with current increment progress.
 # Shows: [increment-name] ████░░░░ X/Y tasks | A/B ACs (Z open)
 #
-# Logic:
-# 1. Scan all spec.md for status=active/planning (SOURCE OF TRUTH!)
-# 2. Take first (oldest) as current increment
-# 3. Count all active/planning as openCount
-# 4. Parse current increment's tasks.md for task progress
-# 5. Parse current increment's spec.md for AC progress
-# 6. Write to cache
+# OPTIMIZATIONS (v0.26.13):
+# 1. TTL-based throttling (10s) - longer cache = fewer runs
+# 2. Mtime checking via find -newer (no stat loops!)
+# 3. Pure bash counting + JSON generation (NO jq!)
+# 4. Single-pass awk for all counting (1 process vs 5 greps)
+# 5. Exclude _archive/ with find -not -path
+# 6. Lock file to prevent concurrent runs
 #
-# Performance: 50-100ms (runs async, user doesn't wait)
+# Performance: <5ms (cached) / 15-25ms (full scan)
 #
-# EMERGENCY FIX (v0.24.4): Changed from set -euo pipefail to set +e
-# CRITICAL: Hooks MUST use set +e to prevent Claude Code crashes!
-# See: CLAUDE.md section 9a - Hook Performance & Safety
-
 set +e
 
-# Find project root
-find_project_root() {
-  local dir="$PWD"
-  while [[ "$dir" != "/" ]]; do
-    if [[ -d "$dir/.specweave" ]]; then
-      echo "$dir"
-      return 0
-    fi
-    dir=$(dirname "$dir")
+# ============================================================================
+# PROJECT ROOT (FAST - cached in env if available)
+# ============================================================================
+if [[ -n "$SPECWEAVE_PROJECT_ROOT" ]] && [[ -d "$SPECWEAVE_PROJECT_ROOT/.specweave" ]]; then
+  PROJECT_ROOT="$SPECWEAVE_PROJECT_ROOT"
+else
+  PROJECT_ROOT="$PWD"
+  while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.specweave" ]]; do
+    PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
   done
-  echo "$PWD"
-}
-
-PROJECT_ROOT=$(find_project_root)
+  [[ ! -d "$PROJECT_ROOT/.specweave" ]] && PROJECT_ROOT="$PWD"
+fi
 
 # ============================================================================
-# RECURSION PREVENTION (CRITICAL - v0.26.0 - FILE-BASED GUARD)
+# ULTRA-FAST EXITS
 # ============================================================================
-# FIX: Don't update status line from within hook chain
-# WHY: Status line writes status-line.json which triggers post-edit-write hook
-#      which tries to update status line AGAIN → infinite recursion!
-#
-# This is a CRITICAL part of Fix #4 in the root cause analysis:
-# See: .specweave/increments/0051-*/reports/GITHUB-COMMENT-RECURSION-ROOT-CAUSE-2025-11-24.md
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+CACHE_FILE="$STATE_DIR/status-line.json"
+INCREMENTS_DIR="$PROJECT_ROOT/.specweave/increments"
+LOCK_FILE="$STATE_DIR/.status-update.lock"
 
-RECURSION_GUARD_FILE="$PROJECT_ROOT/.specweave/state/.hook-recursion-guard"
+# No .specweave? Exit immediately
+[[ ! -d "$PROJECT_ROOT/.specweave" ]] && exit 0
 
-if [[ -f "$RECURSION_GUARD_FILE" ]]; then
-  # We're inside a hook chain - skip status line update to prevent recursion
-  # This is NORMAL behavior (not an error!)
-  exit 0
+# Recursion guard
+[[ -f "$STATE_DIR/.hook-recursion-guard" ]] && exit 0
+
+# Lock check (prevent concurrent runs - causes crashes!)
+if [[ -f "$LOCK_FILE" ]]; then
+  # Check if lock is stale (>30s)
+  if [[ "$(uname)" == "Darwin" ]]; then
+    LOCK_AGE=$(( $(date +%s) - $(stat -f %m "$LOCK_FILE" 2>/dev/null || echo 0) ))
+  else
+    LOCK_AGE=$(( $(date +%s) - $(stat -c %Y "$LOCK_FILE" 2>/dev/null || echo 0) ))
+  fi
+  [[ $LOCK_AGE -lt 30 ]] && exit 0
 fi
 
-CACHE_FILE="$PROJECT_ROOT/.specweave/state/status-line.json"
-INCREMENTS_DIR="$PROJECT_ROOT/.specweave/increments"
-TMP_FILE="$PROJECT_ROOT/.specweave/state/.status-line-tmp.txt"
-
-# Ensure state directory exists
-mkdir -p "$PROJECT_ROOT/.specweave/state"
-
-# Step 1: Find all open increments (active/planning)
-# Read from spec.md (source of truth), not metadata.json
-# ONLY accepts official IncrementStatus enum values
-# Write to temp file: "timestamp increment_id"
-> "$TMP_FILE"
-
-if [[ -d "$INCREMENTS_DIR" ]]; then
-  for spec_file in "$INCREMENTS_DIR"/*/spec.md; do
-    if [[ -f "$spec_file" ]]; then
-      # Parse YAML frontmatter for status (source of truth)
-      status=$(grep -m1 "^status:" "$spec_file" 2>/dev/null | cut -d: -f2 | tr -d ' ' || echo "")
-
-      # Check if increment is open (active, planning, or in-progress)
-      # ONLY accepts official IncrementStatus enum values
-      if [[ "$status" == "active" ]] || [[ "$status" == "planning" ]] || [[ "$status" == "in-progress" ]]; then
-        increment_id=$(basename "$(dirname "$spec_file")")
-        # Parse created date from spec.md YAML frontmatter
-        created=$(grep -m1 "^created:" "$spec_file" 2>/dev/null | cut -d: -f2- | tr -d ' ' || echo "1970-01-01")
-
-        # Write to temp file
-        echo "$created $increment_id" >> "$TMP_FILE"
-      fi
-    fi
-  done
+# ============================================================================
+# TTL CHECK (10 seconds - balanced for UX vs performance)
+# ============================================================================
+TTL_SECONDS=10
+
+if [[ -f "$CACHE_FILE" ]]; then
+  if [[ "$(uname)" == "Darwin" ]]; then
+    CACHE_AGE=$(( $(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || echo 0) ))
+  else
+    CACHE_AGE=$(( $(date +%s) - $(stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0) ))
+  fi
+  [[ $CACHE_AGE -lt $TTL_SECONDS ]] && exit 0
 fi
 
-# Step 2: Count open increments
-OPEN_COUNT=$(wc -l < "$TMP_FILE" | tr -d ' ')
-
-if [[ $OPEN_COUNT -eq 0 ]]; then
-  # No open increments
-  jq -n '{
-    current: null,
-    openCount: 0,
-    lastUpdate: (now | strftime("%Y-%m-%dT%H:%M:%SZ"))
-  }' > "$CACHE_FILE"
-  rm -f "$TMP_FILE"
+# ============================================================================
+# NO INCREMENTS? Write empty cache and exit
+# ============================================================================
+if [[ ! -d "$INCREMENTS_DIR" ]]; then
+  mkdir -p "$STATE_DIR"
+  printf '{"current":null,"openCount":0,"lastUpdate":"%s"}' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$CACHE_FILE"
   exit 0
 fi
 
-# Step 3: Sort by timestamp (oldest first) and take first
-CURRENT_INCREMENT=$(sort "$TMP_FILE" | head -1 | awk '{print $2}')
+# ============================================================================
+# ACQUIRE LOCK
+# ============================================================================
+mkdir -p "$STATE_DIR"
+echo $$ > "$LOCK_FILE"
+trap 'rm -f "$LOCK_FILE"' EXIT
+
+# ============================================================================
+# FIND ACTIVE INCREMENTS (single find, no xargs)
+# ============================================================================
+ACTIVE_FILES=""
+OPEN_COUNT=0
+OLDEST_DATE="9999-99-99"
+CURRENT_INCREMENT=""
 
-# Clean up temp file
-rm -f "$TMP_FILE"
+while IFS= read -r spec_file; do
+  [[ -z "$spec_file" ]] && continue
 
-# Step 4: Parse current increment's tasks.md for progress
-TASKS_FILE="$INCREMENTS_DIR/$CURRENT_INCREMENT/tasks.md"
-TOTAL_TASKS=0
-COMPLETED_TASKS=0
-PERCENTAGE=0
+  # Quick status check with head + grep (faster than full file grep)
+  if head -20 "$spec_file" 2>/dev/null | grep -qE '^status:\s*(active|planning|in-progress)'; then
+    OPEN_COUNT=$((OPEN_COUNT + 1))
+    increment_id=$(basename "$(dirname "$spec_file")")
 
-if [[ -f "$TASKS_FILE" ]]; then
-  # Use TaskCounter CLI for accurate counting (fixes overcounting bug)
-  COUNT_TASKS_CLI="$PROJECT_ROOT/dist/src/cli/count-tasks.js"
+    # Get created date (first 30 lines only)
+    created=$(head -30 "$spec_file" 2>/dev/null | grep -m1 "^created:" | cut -d: -f2- | tr -d ' "' || echo "9999-99-99")
 
-  if [[ -f "$COUNT_TASKS_CLI" ]]; then
-    # Call CLI and parse JSON output
-    TASK_COUNTS=$(node "$COUNT_TASKS_CLI" "$TASKS_FILE" 2>/dev/null || echo '{"total":0,"completed":0,"percentage":0}')
-    TOTAL_TASKS=$(echo "$TASK_COUNTS" | jq -r '.total' 2>/dev/null || echo 0)
-    COMPLETED_TASKS=$(echo "$TASK_COUNTS" | jq -r '.completed' 2>/dev/null || echo 0)
-    PERCENTAGE=$(echo "$TASK_COUNTS" | jq -r '.percentage' 2>/dev/null || echo 0)
-  else
-    # Fallback to legacy counting if CLI not available (graceful degradation)
-    # Count total tasks (## T- or ### T- headings)
-    TOTAL_TASKS=$(grep -cE '^##+ T-' "$TASKS_FILE" 2>/dev/null || echo 0)
-    TOTAL_TASKS=$(echo "$TOTAL_TASKS" | tr -d '\n\r ' || echo 0)
-
-    # Count completed tasks - recognize all three completion marker formats:
-    # 1. **Completed**: <date> (preferred format)
-    # 2. **Status**: [x] (legacy format)
-    # 3. [x] at line start (legacy checkbox format)
-    COMPLETED_TASKS=$(grep -cE '(\*\*Completed\*\*:|\*\*Status\*\*:\s*\[x\]|^\[x\])' "$TASKS_FILE" 2>/dev/null || echo 0)
-    COMPLETED_TASKS=$(echo "$COMPLETED_TASKS" | tr -d '\n\r ' || echo 0)
-
-    # Calculate percentage
-    if [[ $TOTAL_TASKS -gt 0 ]]; then
-      PERCENTAGE=$((COMPLETED_TASKS * 100 / TOTAL_TASKS))
+    if [[ "$created" < "$OLDEST_DATE" ]]; then
+      OLDEST_DATE="$created"
+      CURRENT_INCREMENT="$increment_id"
     fi
+
+    ACTIVE_FILES="$ACTIVE_FILES $spec_file"
   fi
-fi
+done < <(find "$INCREMENTS_DIR" -maxdepth 2 -name "spec.md" -not -path "*/_archive/*" 2>/dev/null)
 
-# Step 4b: Parse spec.md for AC (Acceptance Criteria) progress
-SPEC_FILE="$INCREMENTS_DIR/$CURRENT_INCREMENT/spec.md"
-TOTAL_ACS=0
-COMPLETED_ACS=0
-OPEN_ACS=0
-
-if [[ -f "$SPEC_FILE" ]]; then
-  # Count total ACs: both checked and unchecked
-  # Pattern: - [ ] **AC- OR - [x] **AC-
-  TOTAL_ACS=$(grep -cE '^- \[(x| )\] \*\*AC-' "$SPEC_FILE" 2>/dev/null || echo 0)
-  TOTAL_ACS=$(echo "$TOTAL_ACS" | tr -d '\n\r ' || echo 0)
-
-  # Count completed ACs (checked)
-  # Pattern: - [x] **AC-
-  COMPLETED_ACS=$(grep -cE '^- \[x\] \*\*AC-' "$SPEC_FILE" 2>/dev/null || echo 0)
-  COMPLETED_ACS=$(echo "$COMPLETED_ACS" | tr -d '\n\r ' || echo 0)
-
-  # Count open ACs (unchecked)
-  # Pattern: - [ ] **AC-
-  OPEN_ACS=$(grep -cE '^- \[ \] \*\*AC-' "$SPEC_FILE" 2>/dev/null || echo 0)
-  OPEN_ACS=$(echo "$OPEN_ACS" | tr -d '\n\r ' || echo 0)
+# No active increments?
+if [[ -z "$CURRENT_INCREMENT" ]]; then
+  printf '{"current":null,"openCount":0,"lastUpdate":"%s"}' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$CACHE_FILE"
+  exit 0
 fi
 
-# Step 5: Extract increment ID and name
-# Format: XXXX-name where XXXX is 4-digit prefix (brackets added by manager)
-INCREMENT_ID=$(echo "$CURRENT_INCREMENT" | grep -oE '^[0-9]{4}')
-INCREMENT_NAME_ONLY=$(echo "$CURRENT_INCREMENT" | sed 's/^[0-9]\{4\}-//')
-INCREMENT_NAME="$INCREMENT_ID-$INCREMENT_NAME_ONLY"
-
-# Step 6: Write cache with atomic validation (v0.24.4 - prevents corruption)
-TMP_CACHE_FILE="$PROJECT_ROOT/.specweave/state/.status-line-tmp.json"
-
-# Validate all numeric inputs before jq (prevents jq failures)
-[[ "$TOTAL_TASKS" =~ ^[0-9]+$ ]] || TOTAL_TASKS=0
-[[ "$COMPLETED_TASKS" =~ ^[0-9]+$ ]] || COMPLETED_TASKS=0
-[[ "$PERCENTAGE" =~ ^[0-9]+$ ]] || PERCENTAGE=0
-[[ "$TOTAL_ACS" =~ ^[0-9]+$ ]] || TOTAL_ACS=0
-[[ "$COMPLETED_ACS" =~ ^[0-9]+$ ]] || COMPLETED_ACS=0
-[[ "$OPEN_ACS" =~ ^[0-9]+$ ]] || OPEN_ACS=0
-[[ "$OPEN_COUNT" =~ ^[0-9]+$ ]] || OPEN_COUNT=0
-
-# Generate cache to temp file first (atomic operation)
-if jq -n \
-  --arg id "$CURRENT_INCREMENT" \
-  --arg name "$INCREMENT_NAME" \
-  --argjson completed "$COMPLETED_TASKS" \
-  --argjson total "$TOTAL_TASKS" \
-  --argjson percentage "$PERCENTAGE" \
-  --argjson acsCompleted "$COMPLETED_ACS" \
-  --argjson acsTotal "$TOTAL_ACS" \
-  --argjson openCount "$OPEN_COUNT" \
-  '{
-    current: {
-      id: $id,
-      name: $name,
-      completed: $completed,
-      total: $total,
-      percentage: $percentage,
-      acsCompleted: $acsCompleted,
-      acsTotal: $acsTotal
-    },
-    openCount: $openCount,
-    lastUpdate: (now | strftime("%Y-%m-%dT%H:%M:%SZ"))
-  }' > "$TMP_CACHE_FILE" 2>/dev/null; then
-
-  # Validate generated JSON before replacing cache (corruption prevention)
-  if jq empty "$TMP_CACHE_FILE" 2>/dev/null; then
-    mv "$TMP_CACHE_FILE" "$CACHE_FILE"
-  else
-    # Invalid JSON generated - keep old cache
-    echo "[$(date)] ERROR: Generated invalid JSON, keeping old cache" >> "$DEBUG_LOG" 2>/dev/null || true
-    rm -f "$TMP_CACHE_FILE"
+# ============================================================================
+# MTIME CHECK (using find -newer - single syscall!)
+# ============================================================================
+MTIME_FILE="$STATE_DIR/.status-mtime-$CURRENT_INCREMENT"
+
+if [[ -f "$MTIME_FILE" ]] && [[ -f "$CACHE_FILE" ]]; then
+  # Check if any relevant files are newer than our marker
+  TASKS_FILE="$INCREMENTS_DIR/$CURRENT_INCREMENT/tasks.md"
+  SPEC_FILE="$INCREMENTS_DIR/$CURRENT_INCREMENT/spec.md"
+
+  NEWER_FILES=$(find "$SPEC_FILE" "$TASKS_FILE" -newer "$MTIME_FILE" 2>/dev/null | head -1)
+
+  if [[ -z "$NEWER_FILES" ]]; then
+    # No changes - just touch cache to reset TTL
+    touch "$CACHE_FILE"
+    exit 0
   fi
-else
-  # jq generation failed - keep old cache
-  echo "[$(date)] ERROR: jq failed to generate status cache (exit $?)" >> "$DEBUG_LOG" 2>/dev/null || true
-  rm -f "$TMP_CACHE_FILE"
 fi
 
+# ============================================================================
+# SINGLE-PASS COUNTING WITH AWK (replaces 5 grep calls!)
+# ============================================================================
+TASKS_FILE="$INCREMENTS_DIR/$CURRENT_INCREMENT/tasks.md"
+SPEC_FILE="$INCREMENTS_DIR/$CURRENT_INCREMENT/spec.md"
+
+# Count tasks with single awk call
+read -r TOTAL_TASKS COMPLETED_TASKS < <(
+  awk '
+    /^###? T-/ { total++ }
+    /\*\*Completed\*\*:|\*\*Status\*\*:[ \t]*\[x\]/ { completed++ }
+    END { print total+0, completed+0 }
+  ' "$TASKS_FILE" 2>/dev/null || echo "0 0"
+)
+
+# Count ACs with single awk call
+# Supports both formats: "- [ ] AC-US1-01:" and "- [ ] **AC-US1-01**:"
+read -r TOTAL_ACS COMPLETED_ACS < <(
+  awk '
+    /^- \[(x| )\] (\*\*)?AC-/ { total++ }
+    /^- \[x\] (\*\*)?AC-/ { completed++ }
+    END { print total+0, completed+0 }
+  ' "$SPEC_FILE" 2>/dev/null || echo "0 0"
+)
+
+# Calculate percentage (pure bash)
+PERCENTAGE=0
+[[ ${TOTAL_TASKS:-0} -gt 0 ]] && PERCENTAGE=$((${COMPLETED_TASKS:-0} * 100 / TOTAL_TASKS))
+
+# ============================================================================
+# WRITE CACHE (PURE BASH - NO jq!)
+# ============================================================================
+# Sanitize values
+TOTAL_TASKS=${TOTAL_TASKS:-0}
+COMPLETED_TASKS=${COMPLETED_TASKS:-0}
+TOTAL_ACS=${TOTAL_ACS:-0}
+COMPLETED_ACS=${COMPLETED_ACS:-0}
+OPEN_COUNT=${OPEN_COUNT:-0}
+PERCENTAGE=${PERCENTAGE:-0}
+
+# Generate JSON directly (avoids jq subprocess entirely!)
+cat > "$CACHE_FILE" << EOF
+{"current":{"id":"$CURRENT_INCREMENT","name":"$CURRENT_INCREMENT","completed":$COMPLETED_TASKS,"total":$TOTAL_TASKS,"percentage":$PERCENTAGE,"acsCompleted":$COMPLETED_ACS,"acsTotal":$TOTAL_ACS},"openCount":$OPEN_COUNT,"lastUpdate":"$(date -u +%Y-%m-%dT%H:%M:%SZ)"}
+EOF
+
+# Update mtime marker
+touch "$MTIME_FILE"
+
 exit 0

package/plugins/specweave/hooks/post-edit-write-consolidated.sh

@@ -49,6 +49,12 @@ find_project_root() {
 }
 
 PROJECT_ROOT=$(find_project_root)
+
+# ULTRA-FAST EARLY EXIT FOR NON-SPECWEAVE PROJECTS (T-006 - v0.26.15)
+if [[ ! -d "$PROJECT_ROOT/.specweave" ]]; then
+  exit 0
+fi
+
 LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
 DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
 

package/plugins/specweave/hooks/post-metadata-change.sh

@@ -192,6 +192,15 @@ case "$CURRENT_STATUS" in
     fi
     ;;
 
+  active|planning|in-progress)
+    # Increment became active - MUST register in active-increment.json!
+    # CRITICAL FIX (v0.26.15): post-task-completion.sh depends on this file
+    # Without registration, ALL sync operations are skipped!
+    echo "[$(date)] post-metadata-change: Status is $CURRENT_STATUS - registering as active + updating status line" >> "$DEBUG_LOG" 2>/dev/null || true
+    bash "$HOOK_DIR/lib/update-active-increment.sh" 2>/dev/null || true
+    bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+    ;;
+
   *)
     # Other metadata changes (e.g., task completion count, AC count)
     # Just update status line to reflect new progress

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

@@ -66,6 +66,14 @@ find_project_root() {
 PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
 cd "$PROJECT_ROOT" 2>/dev/null || true
 
+# ============================================================================
+# ULTRA-FAST EARLY EXIT FOR NON-SPECWEAVE PROJECTS (T-006 - v0.26.15)
+# ============================================================================
+# Skip ALL processing if not a SpecWeave project - saves ~50-100ms
+if [[ ! -d "$PROJECT_ROOT/.specweave" ]]; then
+  exit 0
+fi
+
 # ============================================================================
 # RECURSION PREVENTION (CRITICAL - v0.26.0 - FILE-BASED GUARD)
 # ============================================================================

package/plugins/specweave/hooks/post-task-edit.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+#
+# post-task-edit.sh (v0.26.16)
+#
+# Lightweight hook triggered after Edit on tasks.md
+# ONLY updates status line cache - no heavy processing!
+#
+# Purpose: Keep status line in sync when tasks are marked complete via Edit
+#
+# Performance target: <20ms (just calls update-status-line.sh)
+#
+set +e
+
+# EMERGENCY KILL SWITCH
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
+# Find hook directory
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Consume stdin (required for PostToolUse hooks)
+cat > /dev/null
+
+# Update status line cache (force refresh by removing mtime marker)
+PROJECT_ROOT="$PWD"
+while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.specweave" ]]; do
+  PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
+done
+
+if [[ -d "$PROJECT_ROOT/.specweave" ]]; then
+  # Remove mtime markers to force full refresh
+  rm -f "$PROJECT_ROOT/.specweave/state/.status-mtime-"* 2>/dev/null || true
+
+  # Update status line
+  bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+fi
+
+exit 0

package/plugins/specweave/hooks/post-user-story-complete.sh

@@ -45,17 +45,50 @@ echo "🎉 Post-User-Story-Complete Hook"
 echo "   Spec: $SPEC_ID"
 echo "   User Story: $USER_STORY_ID"
 
-# Find spec file
-SPEC_FILE=""
-if [[ -f ".specweave/docs/internal/specs/$SPEC_ID.md" ]]; then
-  SPEC_FILE=".specweave/docs/internal/specs/$SPEC_ID.md"
-elif [[ -f ".specweave/docs/internal/projects/default/specs/$SPEC_ID.md" ]]; then
-  SPEC_FILE=".specweave/docs/internal/projects/default/specs/$SPEC_ID.md"
-else
-  echo "❌ Error: Spec file not found for $SPEC_ID"
+# Find user story file in living docs
+# Input: SPEC_ID = increment ID (e.g., "0059-context-optimization-crash-prevention")
+#        USER_STORY_ID = US ID (e.g., "US-001")
+# Search in: .specweave/docs/internal/specs/**/us-*.md
+
+# STEP 1: Get feature ID from increment spec.md
+INCREMENT_SPEC=".specweave/increments/$SPEC_ID/spec.md"
+FEATURE_ID=""
+
+if [[ -f "$INCREMENT_SPEC" ]]; then
+  FEATURE_ID=$(head -20 "$INCREMENT_SPEC" | grep "^feature_id:" | head -1 | sed 's/feature_id: *//; s/ *$//' || echo "")
+fi
+
+echo "   🔍 Looking for $USER_STORY_ID in feature $FEATURE_ID"
+
+# STEP 2: Find user story file by ID AND feature
+# Prioritize files in the correct feature folder
+US_FILE=""
+while IFS= read -r file; do
+  # Check if file has matching user story ID in frontmatter
+  if head -20 "$file" 2>/dev/null | grep -q "^id: $USER_STORY_ID"; then
+    # If feature ID is known, verify the file is in the correct feature folder
+    if [[ -n "$FEATURE_ID" ]]; then
+      FILE_FEATURE=$(head -20 "$file" 2>/dev/null | grep "^feature:" | head -1 | sed 's/feature: *//; s/ *$//' || echo "")
+      if [[ "$FILE_FEATURE" == "$FEATURE_ID" ]]; then
+        US_FILE="$file"
+        break
+      fi
+    else
+      # No feature filter - take first match
+      US_FILE="$file"
+      break
+    fi
+  fi
+done < <(find .specweave/docs/internal/specs -name "us-*.md" -type f 2>/dev/null)
+
+if [[ -z "$US_FILE" ]]; then
+  echo "❌ Error: User story file not found for $USER_STORY_ID (feature: $FEATURE_ID) in increment $SPEC_ID"
   exit 1
 fi
 
+echo "   📄 Found user story file: $US_FILE"
+SPEC_FILE="$US_FILE"
+
 # Load config to check if auto-sync is enabled
 CONFIG_FILE=".specweave/config.json"
 if [[ ! -f "$CONFIG_FILE" ]]; then
@@ -71,41 +104,48 @@ if [[ "$AUTO_SYNC" != "true" ]]; then
   exit 0
 fi
 
-# Parse spec frontmatter to detect external links
-# Check if GitHub link exists
-GITHUB_LINK=$(grep -A 10 "^externalLinks:" "$SPEC_FILE" | grep -A 5 "github:" | grep "projectId:" | sed 's/.*projectId: *//; s/ *$//' || echo "")
+# Parse user story frontmatter to detect external links
+# User story files have format:
+#   external:
+#     github:
+#       issue: 745
+#       url: https://github.com/...
+
+# Extract GitHub issue number from frontmatter
+GITHUB_ISSUE=$(head -20 "$SPEC_FILE" | grep -A 5 "github:" | grep "issue:" | head -1 | sed 's/.*issue: *//; s/ *$//' || echo "")
 
-# Check if Jira link exists
-JIRA_LINK=$(grep -A 10 "^externalLinks:" "$SPEC_FILE" | grep -A 5 "jira:" | grep "epicKey:" | sed 's/.*epicKey: *//; s/ *$//' || echo "")
+# Extract Jira issue from frontmatter
+JIRA_ISSUE=$(head -20 "$SPEC_FILE" | grep -A 5 "jira:" | grep "issue:" | head -1 | sed 's/.*issue: *//; s/ *$//' || echo "")
 
-# Check if ADO link exists
-ADO_LINK=$(grep -A 10 "^externalLinks:" "$SPEC_FILE" | grep -A 5 "ado:" | grep "featureId:" | sed 's/.*featureId: *//; s/ *$//' || echo "")
+# Extract ADO work item from frontmatter
+ADO_ITEM=$(head -20 "$SPEC_FILE" | grep -A 5 "ado:" | grep "item:" | head -1 | sed 's/.*item: *//; s/ *$//' || echo "")
 
 # Determine which provider to sync
 PROVIDER=""
-if [[ -n "$GITHUB_LINK" ]]; then
+EXTERNAL_ID=""
+if [[ -n "$GITHUB_ISSUE" ]]; then
   PROVIDER="github"
-  EXTERNAL_ID="$GITHUB_LINK"
-elif [[ -n "$JIRA_LINK" ]]; then
+  EXTERNAL_ID="$GITHUB_ISSUE"
+elif [[ -n "$JIRA_ISSUE" ]]; then
   PROVIDER="jira"
-  EXTERNAL_ID="$JIRA_LINK"
-elif [[ -n "$ADO_LINK" ]]; then
+  EXTERNAL_ID="$JIRA_ISSUE"
+elif [[ -n "$ADO_ITEM" ]]; then
   PROVIDER="ado"
-  EXTERNAL_ID="$ADO_LINK"
+  EXTERNAL_ID="$ADO_ITEM"
 fi
 
 # No external link found - skip sync
 if [[ -z "$PROVIDER" ]]; then
-  echo "   ℹ️  Spec not linked to external tool, skipping sync"
+  echo "   ℹ️  User story not linked to external tool, skipping sync"
   exit 0
 fi
 
-echo "   🔗 Detected external link: $PROVIDER"
+echo "   🔗 Detected external link: $PROVIDER (ID: $EXTERNAL_ID)"
 
 # Update external tool based on provider
 case "$PROVIDER" in
   github)
-    echo "   🔄 Updating GitHub Issue for $USER_STORY_ID..."
+    echo "   🔄 Updating GitHub Issue #$EXTERNAL_ID for $USER_STORY_ID..."
 
     # Check if GitHub CLI is available
     if ! command -v gh &> /dev/null; then
@@ -113,26 +153,37 @@ case "$PROVIDER" in
       exit 0
     fi
 
-    # Find GitHub Issue for this user story
-    # Search for issue with title pattern "[USER_STORY_ID]"
+    # Use issue number from frontmatter (EXTERNAL_ID = issue number)
+    ISSUE_NUMBER="$EXTERNAL_ID"
     REPO=$(git remote get-url origin | sed -E 's/.*github\.com[:/]([^/]+\/[^/]+)(\.git)?$/\1/')
 
-    # Search for issue
-    ISSUE_NUMBER=$(gh issue list --repo "$REPO" --search "\"[$USER_STORY_ID]\" in:title" --json number --jq '.[0].number' 2>/dev/null || echo "")
+    if [[ -z "$ISSUE_NUMBER" || "$ISSUE_NUMBER" == "null" ]]; then
+      echo "   ⚠️  No GitHub Issue number found in user story metadata"
+      exit 0
+    fi
+
+    echo "   📝 Using GitHub Issue #$ISSUE_NUMBER from metadata"
 
-    if [[ -z "$ISSUE_NUMBER" ]]; then
-      echo "   ⚠️  GitHub Issue not found for $USER_STORY_ID"
+    # Check if issue is already closed
+    ISSUE_STATE=$(gh issue view "$ISSUE_NUMBER" --repo "$REPO" --json state --jq '.state' 2>/dev/null || echo "")
+    if [[ "$ISSUE_STATE" == "CLOSED" ]]; then
+      echo "   ✅ GitHub Issue #$ISSUE_NUMBER already closed"
       exit 0
     fi
 
-    echo "   📝 Found GitHub Issue #$ISSUE_NUMBER"
+    # Close issue with completion comment
+    gh issue close "$ISSUE_NUMBER" --repo "$REPO" --comment "✅ **User Story Verified Complete**
+
+📊 **Completion Status**:
+- ✅ All Acceptance Criteria satisfied
+- ✅ All implementation tasks complete
 
-    # Close issue
-    gh issue close "$ISSUE_NUMBER" --repo "$REPO" --comment "✅ User story completed
+**User Story**: $USER_STORY_ID
+**Increment**: $SPEC_ID
 
-🤖 Auto-closed by SpecWeave hook
+🤖 Auto-closed by SpecWeave US Completion Hook
 Completed at: $(date -u +%Y-%m-%dT%H:%M:%SZ)" 2>/dev/null || {
-      echo "   ⚠️  Failed to close issue"
+      echo "   ⚠️  Failed to close issue (may already be closed)"
       exit 0
     }