specweave 0.24.11 → 0.26.2

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

@@ -0,0 +1,335 @@
+#!/bin/bash
+#
+# Post-Edit/Write Consolidated Hook: Update Status Line After spec.md or tasks.md Changes
+#
+# Purpose: Unified hook for both Edit and Write tools
+# Triggers: After Edit/Write modifies spec.md (AC updates) or tasks.md (task completion)
+# Action: Updates status line cache to reflect latest AC/task progress
+#
+# CONSOLIDATION (v0.25.0):
+# - Replaces post-edit-spec.sh and post-write-spec.sh (identical code)
+# - Reduces hook overhead by 50% (2 post-hooks → 1)
+# - Single point of maintenance
+# - Combined with pre-edit-write-consolidated.sh, reduces 4 hooks → 2 hooks
+#
+# This ensures status line stays in sync when ACs are marked complete via Edit tool
+# (not just TodoWrite, which only tracks internal todo lists)
+#
+# EMERGENCY FIXES (v0.24.3):
+# - Kill switch: Set SPECWEAVE_DISABLE_HOOKS=1 to disable ALL hooks
+# - Circuit breaker: Auto-disable after 3 consecutive failures
+# - File locking: Prevent concurrent executions (max 1 at a time)
+# - Aggressive debouncing: Increased from 1s to 5s
+# - Complete error isolation: Never let errors reach Claude Code
+#
+# TIER 1 IMPROVEMENTS (v0.24.2):
+# - Debouncing: Skip if updated less than 5 seconds ago (90% overhead reduction)
+# - File mtime detection: Check recently modified spec.md/tasks.md as fallback
+# - Non-blocking: Run update-status-line.sh in background
+# - Smart detection: Only update if spec/tasks files actually changed
+#
+# Previous fix (v0.24.1): Enhanced file detection for increment completion
+# - Detects changes via TOOL_USE_CONTENT, TOOL_RESULT, and argument parsing
+# - Always updates status line for ANY spec.md/tasks.md change in increments folder
+
+# CRITICAL: Remove set -e to prevent hook errors from crashing Claude Code
+set +e
+
+# Find project root (must be BEFORE recursion guard to get PROJECT_ROOT)
+find_project_root() {
+  local dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -d "$dir/.specweave" ]]; then
+      echo "$dir"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+  done
+  echo "$PWD"
+}
+
+PROJECT_ROOT=$(find_project_root)
+LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+
+# ============================================================================
+# RECURSION PREVENTION (CRITICAL - v0.26.0 - FILE-BASED GUARD)
+# ============================================================================
+# PROBLEM: Hooks that write files trigger other hooks, causing infinite loops.
+# OLD SOLUTION (v0.25.1): Environment variable SPECWEAVE_IN_HOOK=1
+# WHY IT FAILED: Background processes (&) create NEW shells that don't inherit env vars!
+#
+# NEW SOLUTION (v0.26.0): File-based recursion guard
+# - Guard file exists = already inside hook chain
+# - Works across ALL processes (not just current shell)
+# - Atomic operation (mkdir -p ensures thread safety)
+# - Cleanup guaranteed by trap EXIT
+#
+# See: .specweave/increments/0051-*/reports/GITHUB-COMMENT-RECURSION-ROOT-CAUSE-2025-11-24.md
+# See: ADR-0073 (Hook Recursion Prevention Strategy)
+
+RECURSION_GUARD_FILE="$PROJECT_ROOT/.specweave/state/.hook-recursion-guard"
+
+if [[ -f "$RECURSION_GUARD_FILE" ]]; then
+  # Silent exit - we're already inside a hook chain
+  # This is NORMAL and prevents recursion (not an error!)
+  exit 0
+fi
+
+# Don't create guard file here - we only CHECK it
+# Guard file is ONLY created by post-task-completion.sh (the entry point)
+# All other hooks just check for its existence
+
+# EMERGENCY KILL SWITCH: Disable all hooks if env variable set
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
+
+# Ensure state and logs directories exist
+mkdir -p "$PROJECT_ROOT/.specweave/state" "$LOGS_DIR" 2>/dev/null || true
+
+# EMERGENCY CIRCUIT BREAKER: Track consecutive failures
+CIRCUIT_BREAKER_FILE="$PROJECT_ROOT/.specweave/state/.hook-circuit-breaker"
+CIRCUIT_BREAKER_THRESHOLD=3
+
+if [[ -f "$CIRCUIT_BREAKER_FILE" ]]; then
+  FAILURE_COUNT=$(cat "$CIRCUIT_BREAKER_FILE" 2>/dev/null || echo 0)
+  if (( FAILURE_COUNT >= CIRCUIT_BREAKER_THRESHOLD )); then
+    echo "[$(date)] CIRCUIT BREAKER OPEN: Hooks disabled after $FAILURE_COUNT failures. Run: rm $CIRCUIT_BREAKER_FILE" >> "$DEBUG_LOG" 2>/dev/null || true
+    exit 0
+  fi
+fi
+
+# EMERGENCY FILE LOCK: Prevent concurrent executions
+LOCK_FILE="$PROJECT_ROOT/.specweave/state/.hook-post-edit-write.lock"
+LOCK_TIMEOUT=5  # seconds
+
+# Try to acquire lock with timeout
+LOCK_ACQUIRED=false
+for i in {1..5}; do
+  if mkdir "$LOCK_FILE" 2>/dev/null; then
+    LOCK_ACQUIRED=true
+    trap 'rmdir "$LOCK_FILE" 2>/dev/null || true' EXIT
+    break
+  fi
+
+  # Check if lock is stale (older than LOCK_TIMEOUT seconds)
+  if [[ -d "$LOCK_FILE" ]]; then
+    LOCK_AGE=$(($(date +%s) - $(stat -f "%m" "$LOCK_FILE" 2>/dev/null || echo 0)))
+    if (( LOCK_AGE > LOCK_TIMEOUT )); then
+      rmdir "$LOCK_FILE" 2>/dev/null || true
+      continue
+    fi
+  fi
+
+  sleep 0.2
+done
+
+if [[ "$LOCK_ACQUIRED" == "false" ]]; then
+  echo "[$(date)] post-edit-write: Could not acquire lock, skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+# Log rotation: Keep debug log under 100KB
+if [[ -f "$DEBUG_LOG" ]] && [[ $(wc -c < "$DEBUG_LOG" 2>/dev/null || echo 0) -gt 102400 ]]; then
+  tail -100 "$DEBUG_LOG" > "$DEBUG_LOG.tmp" 2>/dev/null || true
+  mv "$DEBUG_LOG.tmp" "$DEBUG_LOG" 2>/dev/null || true
+  echo "[$(date)] Log rotated" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
+# ============================================================================
+# BURST WRITE DETECTION (v0.26.2 - Prevent Write Storms)
+# ============================================================================
+# Problem: Architect agent creating multiple ADRs in one response (6+ writes/minute)
+# Solution: Detect burst writes and throttle if necessary
+# Incident: 2025-11-24 (Increment 0052 - architect created 6 ADRs at once)
+BURST_TIMESTAMPS_FILE="$PROJECT_ROOT/.specweave/state/.write-timestamps"
+BURST_WINDOW=10      # seconds
+BURST_THRESHOLD=5    # max writes in window
+BURST_THROTTLE=2     # seconds to wait if burst detected
+
+# Record this write timestamp
+mkdir -p "$(dirname "$BURST_TIMESTAMPS_FILE")" 2>/dev/null || true
+echo "$(date +%s)" >> "$BURST_TIMESTAMPS_FILE" 2>/dev/null || true
+
+# Count writes in the last BURST_WINDOW seconds
+if [[ -f "$BURST_TIMESTAMPS_FILE" ]]; then
+  NOW=$(date +%s)
+  CUTOFF=$((NOW - BURST_WINDOW))
+
+  # Clean up old timestamps (older than BURST_WINDOW)
+  grep -v "^$" "$BURST_TIMESTAMPS_FILE" 2>/dev/null | \
+    awk -v cutoff="$CUTOFF" '$1 > cutoff' > "$BURST_TIMESTAMPS_FILE.tmp" 2>/dev/null || true
+  mv "$BURST_TIMESTAMPS_FILE.tmp" "$BURST_TIMESTAMPS_FILE" 2>/dev/null || true
+
+  # Count recent writes
+  RECENT_WRITES=$(wc -l < "$BURST_TIMESTAMPS_FILE" 2>/dev/null || echo 0)
+
+  if (( RECENT_WRITES > BURST_THRESHOLD )); then
+    echo "[$(date)] ⚠️  BURST DETECTED: $RECENT_WRITES writes in ${BURST_WINDOW}s (threshold: $BURST_THRESHOLD)" >> "$DEBUG_LOG" 2>/dev/null || true
+    echo "[$(date)] Throttling for ${BURST_THROTTLE}s to prevent overload..." >> "$DEBUG_LOG" 2>/dev/null || true
+    sleep "$BURST_THROTTLE"
+  fi
+fi
+
+# ============================================================================
+# TIER 1 FIX: Debouncing (Prevent Redundant Updates)
+# ============================================================================
+# Skip update if we updated less than 5 seconds ago (INCREASED FROM 1s)
+# This handles rapid consecutive changes (e.g., 10 tasks marked complete quickly)
+LAST_UPDATE_FILE="$PROJECT_ROOT/.specweave/state/.last-status-update"
+DEBOUNCE_SECONDS=5
+
+if [[ -f "$LAST_UPDATE_FILE" ]]; then
+  LAST_UPDATE=$(cat "$LAST_UPDATE_FILE" 2>/dev/null || echo 0)
+  NOW=$(date +%s)
+  TIME_SINCE_UPDATE=$((NOW - LAST_UPDATE))
+
+  if (( TIME_SINCE_UPDATE < DEBOUNCE_SECONDS )); then
+    echo "[$(date)] post-edit-write: Debounced (${TIME_SINCE_UPDATE}s since last update)" >> "$DEBUG_LOG" 2>/dev/null || true
+    exit 0  # Skip this update
+  fi
+fi
+
+# ============================================================================
+# TIER 2: Check for PreToolUse Signal (Primary Detection Method)
+# ============================================================================
+PENDING_FILE="$PROJECT_ROOT/.specweave/state/.pending-status-update"
+METRICS_FILE="$PROJECT_ROOT/.specweave/state/hook-metrics.jsonl"
+DETECTED_FILE=""
+DETECTION_METHOD="none"
+
+# First, check if PreToolUse hook left a signal
+if [[ -f "$PENDING_FILE" ]]; then
+  DETECTED_FILE=$(cat "$PENDING_FILE" 2>/dev/null || echo "")
+  # Delete pending file immediately (consume signal)
+  rm "$PENDING_FILE" 2>/dev/null || true
+
+  if [[ -n "$DETECTED_FILE" ]]; then
+    DETECTION_METHOD="pretooluse"
+    echo "[$(date)] post-edit-write: File from PreToolUse signal: $DETECTED_FILE" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Record Tier 2 success metric
+    TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    echo "{\"timestamp\":\"$TIMESTAMP\",\"hook\":\"post-edit-write\",\"event\":\"tier2_success\",\"method\":\"pretooluse\"}" >> "$METRICS_FILE" 2>/dev/null || true
+  fi
+fi
+
+# ============================================================================
+# TIER 1 FALLBACK: Environment Variable Detection
+# ============================================================================
+# If PreToolUse didn't provide signal, fall back to Tier 1 methods
+if [[ -z "$DETECTED_FILE" ]]; then
+  # Method 1: TOOL_USE_CONTENT environment variable
+  if [[ -n "${TOOL_USE_CONTENT:-}" ]]; then
+    DETECTED_FILE="$TOOL_USE_CONTENT"
+    DETECTION_METHOD="env_content"
+  fi
+
+  # Method 2: TOOL_RESULT environment variable
+  if [[ -z "$DETECTED_FILE" ]] && [[ -n "${TOOL_RESULT:-}" ]]; then
+    DETECTED_FILE=$(echo "$TOOL_RESULT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+    DETECTION_METHOD="env_result"
+  fi
+
+  # Method 3: TOOL_USE_ARGS
+  if [[ -z "$DETECTED_FILE" ]] && [[ -n "${TOOL_USE_ARGS:-}" ]]; then
+    DETECTED_FILE=$(echo "$TOOL_USE_ARGS" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+    DETECTION_METHOD="env_args"
+  fi
+
+  # Log env var detection (for metrics)
+  if [[ -n "$DETECTED_FILE" ]]; then
+    echo "[$(date)] post-edit-write: File from env vars ($DETECTION_METHOD): $DETECTED_FILE" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+fi
+
+# Check if we detected a spec.md or tasks.md change in increments folder
+SHOULD_UPDATE=false
+
+if [[ -n "$DETECTED_FILE" ]]; then
+  # Check if the file is spec.md or tasks.md
+  if [[ "$DETECTED_FILE" == *"/spec.md" ]] || [[ "$DETECTED_FILE" == *"/tasks.md" ]]; then
+    # Check if it's in an increment folder
+    if [[ "$DETECTED_FILE" == *"/.specweave/increments/"* ]]; then
+      SHOULD_UPDATE=true
+      echo "[$(date)] post-edit-write: Increment file changed - will update status line" >> "$DEBUG_LOG" 2>/dev/null || true
+    fi
+  fi
+fi
+
+# ============================================================================
+# TIER 1 FIX: File Modification Time Detection (Fallback)
+# ============================================================================
+# If we couldn't detect the file via environment variables, check which files
+# were modified recently (within last 2 seconds) instead of blindly updating
+if [[ -z "$DETECTED_FILE" ]]; then
+  echo "[$(date)] post-edit-write: Env vars empty - checking file mtimes" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  NOW=$(date +%s)
+  INCREMENTS_DIR="$PROJECT_ROOT/.specweave/increments"
+
+  # Check for recently modified spec.md or tasks.md files
+  if [[ -d "$INCREMENTS_DIR" ]]; then
+    for file in "$INCREMENTS_DIR"/*/spec.md "$INCREMENTS_DIR"/*/tasks.md; do
+      if [[ -f "$file" ]]; then
+        # Get file modification time (platform-specific)
+        if [[ "$(uname)" == "Darwin" ]]; then
+          MTIME=$(stat -f "%m" "$file" 2>/dev/null || echo 0)
+        else
+          MTIME=$(stat -c "%Y" "$file" 2>/dev/null || echo 0)
+        fi
+
+        # If file was modified in last 2 seconds, consider it the changed file
+        TIME_DIFF=$((NOW - MTIME))
+        if (( TIME_DIFF <= 2 )); then
+          DETECTED_FILE="$file"
+          echo "[$(date)] post-edit-write: Detected recent modification: $file (${TIME_DIFF}s ago)" >> "$DEBUG_LOG" 2>/dev/null || true
+          SHOULD_UPDATE=true
+          break
+        fi
+      fi
+    done
+  fi
+
+  # If still no file detected, skip update (not a spec/tasks change)
+  if [[ -z "$DETECTED_FILE" ]]; then
+    echo "[$(date)] post-edit-write: No spec/tasks modifications detected - skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+    exit 0
+  fi
+fi
+
+# ============================================================================
+# TIER 1 FIX: Non-Blocking Background Update with COMPLETE ERROR ISOLATION
+# ============================================================================
+# Update status line if needed
+if [[ "$SHOULD_UPDATE" == "true" ]]; then
+  echo "[$(date)] post-edit-write: Running update-status-line.sh (background)" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  # Record update time BEFORE spawning background process
+  # This ensures debouncing works even if update hasn't completed yet
+  echo "$(date +%s)" > "$LAST_UPDATE_FILE"
+
+  # Run status line update in background with COMPLETE error isolation
+  # This prevents Edit/Write tool from waiting for status line computation
+  (
+    set +e  # Disable error propagation
+
+    if "$PROJECT_ROOT/plugins/specweave/hooks/lib/update-status-line.sh" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null; then
+      echo "[$(date)] post-edit-write: Status line updated successfully" >> "$DEBUG_LOG" 2>/dev/null || true
+      # Reset circuit breaker on success
+      echo "0" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
+    else
+      echo "[$(date)] post-edit-write: Warning - status line update failed (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+      # Increment circuit breaker
+      CURRENT_FAILURES=$(cat "$CIRCUIT_BREAKER_FILE" 2>/dev/null || echo 0)
+      echo "$((CURRENT_FAILURES + 1))" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
+    fi
+  ) &
+
+  # Disown the background process so it's not killed when hook exits
+  disown 2>/dev/null || true
+fi
+
+# Always exit 0 to prevent hook errors from crashing Claude Code
+exit 0

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

@@ -25,6 +25,32 @@ fi
 PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"
 INCREMENT_DIR="$PROJECT_ROOT/.specweave/increments/$INCREMENT_ID"
 
+# ============================================================================
+# RECURSION PREVENTION (v0.26.1 - CRITICAL)
+# ============================================================================
+# PROBLEM: consolidated-sync.js does Edit/Write operations which trigger hooks.
+# If no guard exists, those hooks will run full sync → more Edit/Write → INFINITE LOOP.
+#
+# SOLUTION: Create recursion guard file BEFORE calling any sync scripts.
+# Other hooks check this file and exit early if it exists.
+#
+# See: ADR-0073 (Hook Recursion Prevention Strategy)
+# See: .specweave/increments/0051-*/reports/GITHUB-COMMENT-RECURSION-ROOT-CAUSE-2025-11-24.md
+
+RECURSION_GUARD_FILE="$PROJECT_ROOT/.specweave/state/.hook-recursion-guard"
+
+if [[ -f "$RECURSION_GUARD_FILE" ]]; then
+  # Silent exit - we're already inside a hook chain
+  exit 0
+fi
+
+# Create guard file (atomic operation)
+mkdir -p "$PROJECT_ROOT/.specweave/state" 2>/dev/null || true
+touch "$RECURSION_GUARD_FILE"
+
+# Ensure guard file is ALWAYS removed when script exits (even on error)
+trap 'rm -f "$RECURSION_GUARD_FILE" 2>/dev/null || true' EXIT SIGINT SIGTERM
+
 # Check if increment exists
 if [ ! -d "$INCREMENT_DIR" ]; then
   echo "⚠️  $HOOK_NAME: Increment $INCREMENT_ID not found" >&2
@@ -233,4 +259,111 @@ else
   echo ""
 fi
 
+# ============================================================================
+# GITHUB SYNC (v0.26.1 - CRITICAL FIX)
+# ============================================================================
+# After living docs sync, create GitHub issues for user stories.
+# This is the AUTOMATIC GitHub sync that runs once per increment completion.
+#
+# CRITICAL: This was MISSING in v0.26.0, causing GitHub issues to NEVER be
+# created automatically. The consolidated-sync.js has the full logic for:
+# - Creating GitHub issues for user stories (with 3-layer idempotency)
+# - Syncing task completion comments to existing issues
+# - Format preservation sync for external tools
+#
+# GATE SYSTEM (4 gates - all checked inside consolidated-sync.js):
+# - GATE 1: canUpsertInternalItems (living docs sync enabled)
+# - GATE 2: canUpdateExternalItems (external tool sync enabled)
+# - GATE 3: autoSyncOnCompletion (automatic sync enabled)
+# - GATE 4: sync.github.enabled (GitHub-specific sync enabled)
+#
+# RECURSION SAFETY:
+# - Recursion guard created at script start (line 49)
+# - consolidated-sync.js does Edit/Write operations
+# - Other hooks see the guard and exit early
+# - Guard removed via trap on script exit
+#
+# USER PROJECT COMPATIBILITY:
+# - Script detection works for: development, dist/, node_modules/, marketplace
+# - Works in both SpecWeave framework repo AND user projects using SpecWeave
+# - GITHUB_TOKEN loaded from project's .env file
+#
+# See: Root cause analysis in initial implementation planning
+# See: ADR-0073 (Hook Recursion Prevention Strategy)
+
+if command -v node &> /dev/null; then
+  echo ""
+  echo "🔗 Creating GitHub issues for user stories..."
+
+  # ========================================================================
+  # LOCATE CONSOLIDATED SYNC SCRIPT
+  # ========================================================================
+  # Find consolidated-sync.js in order of preference:
+  # 1. In-place compiled (development, esbuild output)
+  # 2. Local dist (development, tsc output)
+  # 3. node_modules (installed as dependency) ← USER PROJECTS
+  # 4. Plugin marketplace (Claude Code global installation)
+
+  CONSOLIDATED_SCRIPT=""
+  if [ -f "$PROJECT_ROOT/plugins/specweave/lib/hooks/consolidated-sync.js" ]; then
+    # Development: Use in-place compiled hooks (esbuild, not tsc)
+    CONSOLIDATED_SCRIPT="$PROJECT_ROOT/plugins/specweave/lib/hooks/consolidated-sync.js"
+    echo "  🔧 Using in-place compiled hook (development mode)"
+  elif [ -f "$PROJECT_ROOT/dist/plugins/specweave/lib/hooks/consolidated-sync.js" ]; then
+    # Development: Use project's compiled files (has node_modules)
+    CONSOLIDATED_SCRIPT="$PROJECT_ROOT/dist/plugins/specweave/lib/hooks/consolidated-sync.js"
+    echo "  🔧 Using local dist (development mode)"
+  elif [ -f "$PROJECT_ROOT/node_modules/specweave/dist/plugins/specweave/lib/hooks/consolidated-sync.js" ]; then
+    # Installed as dependency: Use node_modules version (MOST USER PROJECTS)
+    CONSOLIDATED_SCRIPT="$PROJECT_ROOT/node_modules/specweave/dist/plugins/specweave/lib/hooks/consolidated-sync.js"
+    echo "  📦 Using node_modules version"
+  elif [ -n "${CLAUDE_PLUGIN_ROOT}" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/lib/hooks/consolidated-sync.js" ]; then
+    # Fallback: Plugin marketplace (may fail if deps missing)
+    CONSOLIDATED_SCRIPT="${CLAUDE_PLUGIN_ROOT}/lib/hooks/consolidated-sync.js"
+    echo "  🌐 Using plugin marketplace version"
+  fi
+
+  # ========================================================================
+  # EXECUTE GITHUB SYNC
+  # ========================================================================
+  # Run consolidated sync to create GitHub issues and sync task completion.
+  # Non-blocking: Errors logged but don't crash hook (increment already closed)
+  #
+  # CRITICAL: Do NOT set SKIP_GITHUB_SYNC=true here!
+  # That flag is ONLY for post-task-completion hook to prevent duplicate comments.
+  # On increment completion, we WANT GitHub sync to run.
+
+  if [ -n "$CONSOLIDATED_SCRIPT" ]; then
+    # Load GITHUB_TOKEN from .env for gh CLI authentication
+    if [ -f "$PROJECT_ROOT/.env" ]; then
+      # Extract GITHUB_TOKEN from .env (handles various formats)
+      GITHUB_TOKEN_FROM_ENV=$(grep -E '^GITHUB_TOKEN=' "$PROJECT_ROOT/.env" 2>/dev/null | head -1 | cut -d'=' -f2- | sed 's/^["'\'']//' | sed 's/["'\'']$//')
+      if [ -n "$GITHUB_TOKEN_FROM_ENV" ]; then
+        export GITHUB_TOKEN="$GITHUB_TOKEN_FROM_ENV"
+        echo "  🔑 GitHub token loaded from .env"
+      fi
+    fi
+
+    # Run consolidated sync (synchronous - user sees immediate feedback)
+    # This creates GitHub issues, syncs comments, and performs format preservation
+    if (cd "$PROJECT_ROOT" && node "$CONSOLIDATED_SCRIPT" "$INCREMENT_ID") 2>&1; then
+      echo "  ✅ GitHub sync complete"
+      echo ""
+    else
+      echo "  ⚠️  Failed to sync GitHub issues (non-blocking - you can run /specweave-github:sync manually)" >&2
+      echo "  💡 Check that sync.github.enabled=true in .specweave/config.json" >&2
+      echo ""
+    fi
+  else
+    echo "  ⚠️  consolidated-sync.js not found in any location - skipping GitHub sync" >&2
+    echo "  💡 To manually sync: /specweave-github:sync" >&2
+    echo ""
+  fi
+else
+  echo ""
+  echo "  ⚠️  Node.js not found - skipping GitHub sync" >&2
+  echo "  💡 Install Node.js to enable automatic GitHub sync" >&2
+  echo ""
+fi
+
 exit 0

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

@@ -22,12 +22,7 @@
 # EMERGENCY FIX v0.24.3: Remove set -e - it causes Claude Code crashes!
 set +e
 
-# EMERGENCY KILL SWITCH
-if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
-  exit 0
-fi
-
-# Find project root
+# Find project root (must be BEFORE recursion guard to get PROJECT_ROOT)
 find_project_root() {
   local dir="$PWD"
   while [[ "$dir" != "/" ]]; do
@@ -45,27 +40,71 @@ LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
 DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
 HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-# Ensure logs directory exists
-mkdir -p "$LOGS_DIR" 2>/dev/null || true
+# ============================================================================
+# RECURSION PREVENTION (CRITICAL - v0.26.0 - FILE-BASED GUARD)
+# ============================================================================
+# NEW SOLUTION (v0.26.0): File-based recursion guard
+# See: ADR-0073 (Hook Recursion Prevention Strategy)
 
-# Extract modified file from environment variables (Claude Code provides this)
-MODIFIED_FILE=""
+RECURSION_GUARD_FILE="$PROJECT_ROOT/.specweave/state/.hook-recursion-guard"
 
-# Method 1: TOOL_USE_CONTENT environment variable (primary for Write)
-if [[ -n "${TOOL_USE_CONTENT:-}" ]]; then
-  MODIFIED_FILE="$TOOL_USE_CONTENT"
+if [[ -f "$RECURSION_GUARD_FILE" ]]; then
+  # Silent exit - we're already inside a hook chain
+  exit 0
 fi
 
-# Method 2: TOOL_RESULT environment variable (fallback)
-if [[ -z "$MODIFIED_FILE" ]] && [[ -n "${TOOL_RESULT:-}" ]]; then
-  MODIFIED_FILE=$(echo "$TOOL_RESULT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+# EMERGENCY KILL SWITCH
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
 fi
 
-# Method 3: Parse tool use arguments (last resort for Edit)
-if [[ -z "$MODIFIED_FILE" ]] && [[ -n "${TOOL_USE_ARGS:-}" ]]; then
-  MODIFIED_FILE=$(echo "$TOOL_USE_ARGS" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+# Ensure logs directory exists
+mkdir -p "$LOGS_DIR" 2>/dev/null || true
+
+# ============================================================================
+# READ STDIN (v0.26.1 - CRITICAL FIX)
+# ============================================================================
+# PostToolUse hooks receive JSON data from Claude Code via STDIN, NOT env vars!
+# This was the critical bug: hook was looking for environment variables that don't exist.
+#
+# Example STDIN data:
+# {"tool": "Edit", "tool_input": {"file_path": "/path/to/file.md", ...}}
+# {"tool": "Write", "tool_input": {"file_path": "/path/to/file.md", ...}}
+
+STDIN_DATA=$(mktemp)
+cat > "$STDIN_DATA"
+
+echo "[$(date)] post-metadata-change: Hook fired" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "[$(date)] Input JSON:" >> "$DEBUG_LOG" 2>/dev/null || true
+cat "$STDIN_DATA" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# EARLY EXIT OPTIMIZATION (v0.25.0): Ultra-Fast Rejection of Non-Metadata Changes
+# ============================================================================
+# This hook should ONLY run for metadata.json changes.
+# 99.9% of Edit/Write operations are NOT metadata.json.
+# Do fastest possible check first to minimize overhead.
+
+# Quick check: If STDIN doesn't contain "metadata.json", exit immediately
+if ! grep -q "metadata\.json" "$STDIN_DATA" 2>/dev/null; then
+  echo "[$(date)] post-metadata-change: Not metadata.json - exiting" >> "$DEBUG_LOG" 2>/dev/null || true
+  rm -f "$STDIN_DATA"
+  exit 0  # Fast path: Not metadata.json
 fi
 
+echo "[$(date)] post-metadata-change: metadata.json detected in input" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# EXTRACT FILE PATH FROM STDIN JSON
+# ============================================================================
+
+# Parse file_path from JSON (handles both Edit and Write tool formats)
+MODIFIED_FILE=$(grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' "$STDIN_DATA" | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+
+# Clean up temp file
+rm -f "$STDIN_DATA"
+
 echo "[$(date)] post-metadata-change: Detected file: ${MODIFIED_FILE:-<none>}" >> "$DEBUG_LOG" 2>/dev/null || true
 
 # Check if this is a metadata.json change in an increment folder