specweave 0.23.10 → 0.23.14

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/docs-changed.sh

@@ -5,7 +5,12 @@
 # Detects if documentation was changed during implementation
 # Triggers review workflow if needed
 
-set -e
+set +e  # EMERGENCY FIX: Prevents Claude Code crashes
+
+# EMERGENCY KILL SWITCH
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
 
 # Find project root by searching upward for .specweave/ directory
 # Works regardless of where hook is installed (source or .claude/hooks/)
@@ -77,3 +82,6 @@ if [ -n "$DOC_CHANGES" ]; then
   mkdir -p "$LOGS_DIR"
   echo "[$(date)] Documentation changed: $DOC_CHANGES" >> "$LOGS_DIR/hooks.log"
 fi
+
+# ALWAYS exit 0 - NEVER let hook errors crash Claude Code
+exit 0

package/plugins/specweave/hooks/docs-changed.sh.backup

@@ -0,0 +1,79 @@
+#!/bin/bash
+
+# SpecWeave Docs-Changed Hook
+# Runs after file changes are detected
+# Detects if documentation was changed during implementation
+# Triggers review workflow if needed
+
+set -e
+
+# Find project root by searching upward for .specweave/ directory
+# Works regardless of where hook is installed (source or .claude/hooks/)
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # Fallback: try current directory
+  if [ -d "$(pwd)/.specweave" ]; then
+    pwd
+  else
+    echo "$(pwd)"
+  fi
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT"
+
+# Colors
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+# Get changed files (git)
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+  # Not a git repository, skip
+  exit 0
+fi
+
+CHANGED_FILES=$(git diff --name-only HEAD 2>/dev/null || echo "")
+
+if [ -z "$CHANGED_FILES" ]; then
+  # No changes
+  exit 0
+fi
+
+# Check if any documentation files changed
+DOC_CHANGES=$(echo "$CHANGED_FILES" | grep -E '\.specweave/(docs|increments/.*/.*\.md)' || true)
+
+if [ -n "$DOC_CHANGES" ]; then
+  echo -e "${RED}⚠️  Documentation changed during implementation${NC}"
+  echo ""
+  echo "📋 Files changed:"
+  echo "$DOC_CHANGES" | sed 's/^/   /'
+  echo ""
+  echo -e "${YELLOW}🔔 Recommended actions:${NC}"
+  echo "  1. Review documentation changes"
+  echo "  2. Update tasks.md if architecture changed"
+  echo "  3. Type /review-docs to see full impact"
+  echo ""
+
+  # Play notification sound
+  case "$(uname -s)" in
+    Darwin)
+      afplay /System/Library/Sounds/Ping.aiff 2>/dev/null &
+      ;;
+    Linux)
+      paplay /usr/share/sounds/freedesktop/stereo/dialog-warning.oga 2>/dev/null || true
+      ;;
+  esac
+
+  # Log to hooks log
+  LOGS_DIR=".specweave/logs"
+  mkdir -p "$LOGS_DIR"
+  echo "[$(date)] Documentation changed: $DOC_CHANGES" >> "$LOGS_DIR/hooks.log"
+fi

package/plugins/specweave/hooks/human-input-required.sh

@@ -8,7 +8,12 @@
 # 2. Log the question/requirement
 # 3. Record in current increment's work log (if applicable)
 
-set -e
+set +e  # EMERGENCY FIX: Prevents Claude Code crashes
+
+# EMERGENCY KILL SWITCH
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
 
 # Find project root by searching upward for .specweave/ directory
 # Works regardless of where hook is installed (source or .claude/hooks/)
@@ -73,3 +78,6 @@ if [ -n "$CURRENT_WORK" ] && [ -d "$CURRENT_WORK" ]; then
 fi
 
 echo "✅ Hook complete"
+
+# ALWAYS exit 0 - NEVER let hook errors crash Claude Code
+exit 0

package/plugins/specweave/hooks/human-input-required.sh.backup

@@ -0,0 +1,75 @@
+#!/bin/bash
+
+# SpecWeave Human-Input-Required Hook
+# Runs when Claude needs clarification or approval
+#
+# Actions:
+# 1. Play notification sound (Ping.aiff)
+# 2. Log the question/requirement
+# 3. Record in current increment's work log (if applicable)
+
+set -e
+
+# Find project root by searching upward for .specweave/ directory
+# Works regardless of where hook is installed (source or .claude/hooks/)
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # Fallback: try current directory
+  if [ -d "$(pwd)/.specweave" ]; then
+    pwd
+  else
+    echo "$(pwd)"
+  fi
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT"
+
+# Get question/requirement (passed as argument or default)
+QUESTION="${1:-User input required}"
+
+echo "❓ Human input required"
+
+# 1. Play notification sound (cross-platform)
+play_sound() {
+  case "$(uname -s)" in
+    Darwin)
+      afplay /System/Library/Sounds/Ping.aiff 2>/dev/null &
+      ;;
+    Linux)
+      paplay /usr/share/sounds/freedesktop/stereo/dialog-question.oga 2>/dev/null || \
+      aplay /usr/share/sounds/alsa/Side_Left.wav 2>/dev/null || true
+      ;;
+    MINGW*|MSYS*|CYGWIN*)
+      powershell -c "(New-Object Media.SoundPlayer 'C:\Windows\Media\notify.wav').PlaySync();" 2>/dev/null || true
+      ;;
+  esac
+}
+
+play_sound &
+
+# 2. Log to main hooks log
+LOGS_DIR=".specweave/logs"
+mkdir -p "$LOGS_DIR"
+echo "[$(date)] Human input required: $QUESTION" >> "$LOGS_DIR/hooks.log"
+
+# 3. Log to current work context (if exists)
+CURRENT_WORK=$(find .specweave/work -maxdepth 1 -type d -name "current-*" | head -1 || true)
+
+if [ -n "$CURRENT_WORK" ] && [ -d "$CURRENT_WORK" ]; then
+    echo "" >> "$CURRENT_WORK/notes.md"
+    echo "## Input Required ($(date +%Y-%m-%d\ %H:%M))" >> "$CURRENT_WORK/notes.md"
+    echo "" >> "$CURRENT_WORK/notes.md"
+    echo "$QUESTION" >> "$CURRENT_WORK/notes.md"
+    echo "" >> "$CURRENT_WORK/notes.md"
+    echo "📝 Logged to $CURRENT_WORK/notes.md"
+fi
+
+echo "✅ Hook complete"