specweave 0.23.10 → 0.23.12

package/plugins/specweave/commands/check-hooks.md

@@ -0,0 +1,257 @@
+---
+description: Validate hook health and display performance metrics (Tier 2 monitoring)
+---
+
+# /specweave:check-hooks - Hook Health Dashboard
+
+**Purpose:** Display comprehensive hook performance metrics, detection rates, and health status.
+
+**Tier 2 Feature:** This command validates the PreToolUse coordination layer is working correctly.
+
+---
+
+## Instructions for Claude
+
+When this command is executed, perform the following analysis:
+
+### 1. **Read Hook Metrics File**
+
+Location: `.specweave/state/hook-metrics.jsonl`
+
+The metrics file contains JSONL (JSON Lines) format - one JSON object per line.
+
+Each entry has:
+```json
+{
+  "timestamp": "2025-11-22T01:30:00Z",
+  "hook": "pre-edit-spec|post-edit-spec|pre-write-spec|post-write-spec",
+  "event": "file_detected|tier2_success|tier1_fallback",
+  "file_path": "/path/to/file.md",
+  "method": "pretooluse|env_content|env_result|env_args|mtime"
+}
+```
+
+### 2. **Calculate Key Metrics**
+
+**Tier 2 Success Rate:**
+```
+Tier 2 Rate = (tier2_success events) / (total post-tool events) * 100%
+```
+
+**Target:** >95% (Tier 2 should handle most cases)
+
+**Detection Method Breakdown:**
+- `pretooluse`: Tier 2 PreToolUse coordination (best)
+- `env_content`: Environment variable (TOOL_USE_CONTENT)
+- `env_result`: Environment variable (TOOL_RESULT)
+- `env_args`: Environment variable (TOOL_USE_ARGS)
+- `mtime`: File modification time fallback (Tier 1)
+
+**Fallback Rate:**
+```
+Fallback Rate = (mtime detections) / (total detections) * 100%
+```
+
+**Target:** <5% (should rarely need mtime fallback)
+
+### 3. **Check Hook Health Status**
+
+**Circuit Breaker Status:**
+- File: `.specweave/state/.hook-circuit-breaker`
+- If exists: Read failure count
+- If count ≥ 3: ⚠️ CIRCUIT BREAKER OPEN (hooks disabled)
+- If count < 3: ✅ Circuit breaker OK
+- If doesn't exist: ✅ No failures detected
+
+**Kill Switch Status:**
+- Check environment variable: `SPECWEAVE_DISABLE_HOOKS`
+- If set to "1": ⚠️ HOOKS MANUALLY DISABLED
+- If not set or "0": ✅ Hooks enabled
+
+**Lock Files Status:**
+- Check for stale locks:
+  - `.specweave/state/.hook-post-edit.lock`
+  - `.specweave/state/.hook-post-write.lock`
+- If older than 10 seconds: ⚠️ Stale lock detected
+- If not present: ✅ No locks
+
+### 4. **Read Recent Hook Logs**
+
+Location: `.specweave/logs/hooks-debug.log`
+
+**Look for:**
+- Recent errors or warnings
+- Debounce effectiveness (count "Debounced" messages)
+- PreToolUse signal messages
+- Circuit breaker trips
+
+**Time window:** Last 100 lines or last 1 hour
+
+### 5. **Output Format**
+
+Display results in this format:
+
+```
+🔍 SpecWeave Hook Health Dashboard (Tier 2)
+═══════════════════════════════════════════════════════════
+
+📊 DETECTION METRICS (Last 24 hours)
+────────────────────────────────────
+Total Hook Executions:        156
+Tier 2 Success (PreToolUse):  149 (95.5%) ✅
+Tier 1 Fallback (env vars):     5 (3.2%)
+Tier 1 Fallback (mtime):        2 (1.3%)
+
+Detection Method Breakdown:
+  • pretooluse:     149 (95.5%) ✅ Target: >95%
+  • env_content:      3 (1.9%)
+  • env_args:         2 (1.3%)
+  • mtime:            2 (1.3%)  ✅ Target: <5%
+
+🏥 HEALTH STATUS
+────────────────────────────────────
+Circuit Breaker:      ✅ OK (0 failures)
+Kill Switch:          ✅ Hooks enabled
+Stale Locks:          ✅ None detected
+Debounce Efficiency:  87% (136/156 skipped)
+
+⚡ PERFORMANCE
+────────────────────────────────────
+Average Hook Latency:     ~3ms
+Debounce Window:          5 seconds
+Background Updates:       Active
+Metrics Collection:       Active
+
+📝 RECENT ACTIVITY (Last 10 events)
+────────────────────────────────────
+[2025-11-22 01:30:15] post-edit-spec: File from PreToolUse signal: /path/to/spec.md
+[2025-11-22 01:30:10] pre-edit-spec: Signaled PostToolUse for: /path/to/spec.md
+[2025-11-22 01:29:45] post-edit-spec: Debounced (2s since last update)
+...
+
+✅ SUMMARY
+────────────────────────────────────
+Status: HEALTHY ✅
+
+Tier 2 coordination is working correctly (95.5% success rate).
+Fallback rate is within acceptable range (<5%).
+No health issues detected.
+
+Recommendations:
+  • None - system performing optimally
+
+To disable hooks temporarily:
+  export SPECWEAVE_DISABLE_HOOKS=1
+
+To reset circuit breaker:
+  rm .specweave/state/.hook-circuit-breaker
+```
+
+### 6. **Health Assessment Logic**
+
+**Determine overall status:**
+
+- ✅ **HEALTHY** if:
+  - Tier 2 success rate >90%
+  - Fallback rate <10%
+  - No circuit breaker trips
+  - Hooks enabled
+
+- ⚠️ **WARNING** if:
+  - Tier 2 success rate 70-90%
+  - Fallback rate 10-30%
+  - Circuit breaker count 1-2
+
+- ❌ **CRITICAL** if:
+  - Tier 2 success rate <70%
+  - Fallback rate >30%
+  - Circuit breaker open (count ≥ 3)
+  - Hooks manually disabled
+
+### 7. **Troubleshooting Recommendations**
+
+Based on status, provide targeted recommendations:
+
+**If Tier 2 success rate <95%:**
+```
+⚠️ PreToolUse coordination not working optimally
+
+Recommendations:
+1. Check if PreToolUse hooks are registered in plugin.json
+2. Verify hook files are executable (chmod +x)
+3. Review .specweave/logs/hooks-debug.log for PreToolUse errors
+4. Consider filing bug with Anthropic (environment variable passing)
+```
+
+**If fallback rate >10%:**
+```
+⚠️ High fallback rate detected
+
+Recommendations:
+1. Tier 2 coordination may not be working
+2. Environment variables still not being passed
+3. Consider Tier 3 implementation (filesystem watcher)
+```
+
+**If circuit breaker open:**
+```
+❌ Hooks disabled due to consecutive failures
+
+Immediate actions:
+1. Review .specweave/logs/hooks-debug.log for errors
+2. Fix underlying issues
+3. Reset circuit breaker: rm .specweave/state/.hook-circuit-breaker
+4. Restart Claude Code
+```
+
+### 8. **Error Handling**
+
+If metrics file doesn't exist:
+```
+⚠️ No metrics data available
+
+This is normal for:
+  • New SpecWeave installation
+  • First run after Tier 2 upgrade
+
+Metrics will be collected automatically as you work.
+Run this command again after a few Edit/Write operations.
+```
+
+If logs not accessible:
+```
+⚠️ Could not read hook logs
+
+Check file permissions:
+  .specweave/logs/hooks-debug.log
+  .specweave/state/hook-metrics.jsonl
+```
+
+---
+
+## Implementation Notes
+
+**For Claude:**
+1. Parse JSONL file line by line (each line is a JSON object)
+2. Calculate metrics using simple counting
+3. Display results using the template above
+4. Adjust recommendations based on actual metrics
+5. Keep output concise but informative
+
+**Time-based filtering:**
+- Default: Last 24 hours
+- Option: All time (if user requests)
+- Filter by comparing timestamp field
+
+**Edge cases:**
+- Empty metrics file → Show "waiting for data" message
+- Corrupted JSONL → Skip invalid lines, report count
+- Missing state directory → Create it, show initialization message
+
+---
+
+## Related Documentation
+
+- ADR-0060: Hook Performance Optimization
+- `.specweave/increments/0050-*/reports/hook-crash-analysis.md`
+- CLAUDE.md: "Hook Performance Best Practices"

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

@@ -8,12 +8,30 @@
 # This ensures status line stays in sync when ACs are marked complete via Edit tool
 # (not just TodoWrite, which only tracks internal todo lists)
 #
-# CRITICAL FIX (v0.24.1): Enhanced file detection to handle increment completion
+# 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 1 second 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 edits via TOOL_USE_CONTENT, TOOL_RESULT, and argument parsing
 # - Always updates status line for ANY spec.md/tasks.md edit in increments folder
-# - Fixes bug where status line wasn't updating on increment close
 
-set -e
+# CRITICAL: Remove set -e to prevent hook errors from crashing Claude Code
+set +e
+
+# EMERGENCY KILL SWITCH: Disable all hooks if env variable set
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
 
 # Find project root
 find_project_root() {
@@ -32,31 +50,129 @@ PROJECT_ROOT=$(find_project_root)
 LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
 DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
 
-# Ensure logs directory exists
-mkdir -p "$LOGS_DIR" 2>/dev/null || true
+# Ensure state and logs directories exist
+mkdir -p "$PROJECT_ROOT/.specweave/state" "$LOGS_DIR" 2>/dev/null || true
 
-# Extract edited file from multiple sources (Claude Code provides this in various ways)
-EDITED_FILE=""
+# EMERGENCY CIRCUIT BREAKER: Track consecutive failures
+CIRCUIT_BREAKER_FILE="$PROJECT_ROOT/.specweave/state/.hook-circuit-breaker"
+CIRCUIT_BREAKER_THRESHOLD=3
 
-# Method 1: TOOL_USE_CONTENT environment variable (primary)
-if [[ -n "${TOOL_USE_CONTENT:-}" ]]; then
-  EDITED_FILE="$TOOL_USE_CONTENT"
+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
 
-# Method 2: TOOL_RESULT environment variable (fallback)
-if [[ -z "$EDITED_FILE" ]] && [[ -n "${TOOL_RESULT:-}" ]]; then
-  # Extract file_path from tool result JSON
-  EDITED_FILE=$(echo "$TOOL_RESULT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+# EMERGENCY FILE LOCK: Prevent concurrent executions
+LOCK_FILE="$PROJECT_ROOT/.specweave/state/.hook-post-edit.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-spec: Could not acquire lock, skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
 fi
 
-# Method 3: Parse tool use arguments (last resort)
-if [[ -z "$EDITED_FILE" ]] && [[ -n "${TOOL_USE_ARGS:-}" ]]; then
-  # Extract file_path from tool arguments
-  EDITED_FILE=$(echo "$TOOL_USE_ARGS" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+# 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
 
-# Log detection attempt
-echo "[$(date)] post-edit-spec: Detected file: ${EDITED_FILE:-<none>}" >> "$DEBUG_LOG" 2>/dev/null || true
+# ============================================================================
+# TIER 1 FIX: Debouncing (Prevent Redundant Updates)
+# ============================================================================
+# Skip update if we updated less than 5 seconds ago (INCREASED FROM 1s)
+# This handles rapid consecutive edits (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-spec: 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"
+EDITED_FILE=""
+DETECTION_METHOD="none"
+
+# First, check if PreToolUse hook left a signal
+if [[ -f "$PENDING_FILE" ]]; then
+  EDITED_FILE=$(cat "$PENDING_FILE" 2>/dev/null || echo "")
+  # Delete pending file immediately (consume signal)
+  rm "$PENDING_FILE" 2>/dev/null || true
+
+  if [[ -n "$EDITED_FILE" ]]; then
+    DETECTION_METHOD="pretooluse"
+    echo "[$(date)] post-edit-spec: File from PreToolUse signal: $EDITED_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-spec\",\"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 "$EDITED_FILE" ]]; then
+  # Method 1: TOOL_USE_CONTENT environment variable
+  if [[ -n "${TOOL_USE_CONTENT:-}" ]]; then
+    EDITED_FILE="$TOOL_USE_CONTENT"
+    DETECTION_METHOD="env_content"
+  fi
+
+  # Method 2: TOOL_RESULT environment variable
+  if [[ -z "$EDITED_FILE" ]] && [[ -n "${TOOL_RESULT:-}" ]]; then
+    EDITED_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 "$EDITED_FILE" ]] && [[ -n "${TOOL_USE_ARGS:-}" ]]; then
+    EDITED_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 "$EDITED_FILE" ]]; then
+    echo "[$(date)] post-edit-spec: File from env vars ($DETECTION_METHOD): $EDITED_FILE" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+fi
 
 # Check if we detected a spec.md or tasks.md edit in increments folder
 SHOULD_UPDATE=false
@@ -72,23 +188,78 @@ if [[ -n "$EDITED_FILE" ]]; then
   fi
 fi
 
-# If we couldn't detect the file via environment variables, always update status line
-# This ensures we don't miss updates during increment closure
+# ============================================================================
+# 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 "$EDITED_FILE" ]]; then
-  echo "[$(date)] post-edit-spec: No file detected - updating status line as safety measure" >> "$DEBUG_LOG" 2>/dev/null || true
-  SHOULD_UPDATE=true
+  echo "[$(date)] post-edit-spec: 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 edited file
+        TIME_DIFF=$((NOW - MTIME))
+        if (( TIME_DIFF <= 2 )); then
+          EDITED_FILE="$file"
+          echo "[$(date)] post-edit-spec: 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 edit)
+  if [[ -z "$EDITED_FILE" ]]; then
+    echo "[$(date)] post-edit-spec: 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-spec: Running update-status-line.sh" >> "$DEBUG_LOG" 2>/dev/null || true
+  echo "[$(date)] post-edit-spec: Running update-status-line.sh (background)" >> "$DEBUG_LOG" 2>/dev/null || true
 
-  # Run status line update (capture errors for debugging)
-  if "$PROJECT_ROOT/plugins/specweave/hooks/lib/update-status-line.sh" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null; then
-    echo "[$(date)] post-edit-spec: Status line updated successfully" >> "$DEBUG_LOG" 2>/dev/null || true
-  else
-    echo "[$(date)] post-edit-spec: Warning - status line update failed (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
-  fi
+  # 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 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-spec: 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-spec: 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