specweave 0.30.19 → 0.32.2

package/plugins/specweave/commands/specweave-validate-features.md

@@ -1,11 +1,14 @@
 ---
 name: specweave:validate-features
-description: Validate feature folder consistency between _features/ and project folders. Detects orphaned features and auto-repairs discrepancies. Use when features appear in _features but not in project folders.
+description: Validate feature folder consistency across project folders. Detects orphaned features, missing FEATURE.md, and auto-repairs discrepancies. Use for periodic health checks of living docs structure.
 ---
 
 # Validate Feature Folder Consistency
 
-Validates that features in `_features/` have corresponding project folders (e.g., `specweave/FS-XXX/`).
+Validates that feature folders in project directories (e.g., `specweave/FS-XXX/`) have proper structure.
+
+**Note (v5.0.0+)**: The `_features/` folder is OBSOLETE. Features live in `{project}/FS-XXX/`.
+If you find features in `_features/`, they should be migrated to the correct project folder.
 
 ---
 
@@ -120,9 +123,9 @@ Manual intervention required for:
 {list orphaned features}
 
 Options:
-  1. Delete orphaned _features folder if no longer needed
+  1. Delete orphaned folder if no longer needed
   2. Re-sync from increment if increment still exists
-  3. Create project folder manually
+  3. Move to correct project folder manually
 {/if}
 ```
 
@@ -147,8 +150,8 @@ Discrepancies found: 1
 ⚠️  DISCREPANCIES FOUND
 
 Feature: FS-062
-Type: missing_project_folder
-Description: Feature FS-062 exists in _features/ but not in any project folder
+Type: missing_feature_md
+Description: Feature FS-062 folder exists but missing FEATURE.md
 Auto-repairable: Yes
 Linked increment: 0062-test-living-docs-auto-sync (not found)
 
@@ -184,15 +187,17 @@ Discrepancies found: 1
 ## WHEN TO USE
 
 **Use this command when**:
-- Features appear in `_features/` but not in project folders
+- Feature folders are missing FEATURE.md or us-*.md files
 - After interrupted/failed sync operations
 - After manual cleanup of increments
 - Periodic health check of living docs structure
+- Legacy migration from `_features/` to `{project}/` folders
 
 **Root cause of discrepancies**:
-1. Sync interrupted between creating _features and project folders
+1. Sync interrupted during feature creation
 2. Increment deleted without cleaning up living docs
 3. Manual editing of living docs structure
+4. Legacy `_features/` folders not yet migrated (v5.0.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/hooks.json

@@ -5,19 +5,38 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash -c 'F=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/dispatcher.mjs\"; [ -f \"$F\" ] && node \"$F\" session-start || printf \"{\\\"continue\\\":true}\"' 2>/dev/null || printf '{\"continue\":true}'"
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/dispatchers/session-start.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"continue\\\":true}\")'"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-submit.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"approve\\\"}\")'"
           }
         ]
       }
     ],
     "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/bash-file-guard.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
+          }
+        ]
+      },
       {
         "matcher": "Edit|Write",
         "matcher_content": "metadata\\.json.*completed",
         "hooks": [
           {
             "type": "command",
-            "command": "bash -c 'F=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/dispatcher.mjs\"; [ -f \"$F\" ] && node \"$F\" completion-guard || printf \"{\\\"continue\\\":true}\"' 2>/dev/null || printf '{\"continue\":true}'"
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/completion-guard.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
           }
         ]
       },
@@ -27,7 +46,17 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash -c 'F=\"${CLAUDE_PLUGIN_ROOT}/hooks/spec-project-validator.sh\"; [ -f \"$F\" ] && \"$F\" || printf \"{\\\"decision\\\":\\\"allow\\\"}\"' 2>/dev/null || printf '{\"decision\":\"allow\"}'"
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/spec-project-validator.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "matcher_content": "\\.specweave/docs/internal/specs/_features/",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/features-folder-guard.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
           }
         ]
       }
@@ -39,7 +68,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash -c 'F=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/dispatcher.mjs\"; [ -f \"$F\" ] && node \"$F\" post-tool-use || printf \"{\\\"continue\\\":true}\"' 2>/dev/null || printf '{\"continue\":true}'"
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/dispatchers/post-tool-use.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"continue\\\":true}\")'"
           }
         ]
       }

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"

package/plugins/specweave/hooks/lib/common-setup.sh

@@ -0,0 +1,375 @@
+#!/bin/bash
+# common-setup.sh - Unified Hook Library for Crash Prevention
+#
+# This library consolidates ALL common patterns from 19+ hooks into
+# a single source of truth. Extracted from ADRs: 0060, 0068, 0073,
+# 0128, 0130, 0157, 0189.
+#
+# USAGE:
+#   source "${CLAUDE_PLUGIN_ROOT}/hooks/lib/common-setup.sh"
+#   setup_hook_environment || exit 0
+#
+# v0.33.0 - Consolidated from 7 ADRs (2,500+ lines → 200 lines)
+
+set +e  # NEVER use set -e in hooks (ADR-0157 Rule 2)
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+export HOOK_VERSION="0.33.0"
+export HOOK_TIMEOUT="${HOOK_TIMEOUT:-5}"
+export HOOK_DEBUG="${HOOK_DEBUG:-0}"
+
+# State directories (lazy-created)
+_STATE_DIR=""
+_CACHE_DIR=""
+_LOG_DIR=""
+
+# ============================================================================
+# 1. PROJECT ROOT DETECTION (ADR-0068, ADR-0128)
+# ============================================================================
+
+find_project_root() {
+  local dir="${1:-$(pwd)}"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -d "$dir/.specweave" ]]; then
+      echo "$dir"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+  done
+  return 1
+}
+
+# ============================================================================
+# 2. EMERGENCY KILL SWITCH (ADR-0068 Layer 1, ADR-0157 Rule 4)
+# ============================================================================
+
+check_kill_switch() {
+  if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+    [[ "$HOOK_DEBUG" == "1" ]] && echo "[HOOK] Kill switch active" >&2
+    return 1
+  fi
+  return 0
+}
+
+# ============================================================================
+# 3. CIRCUIT BREAKER (ADR-0068 Layer 2)
+# ============================================================================
+
+# Circuit breaker state (3 failures = trip)
+_CIRCUIT_BREAKER_FILE=""
+_CIRCUIT_BREAKER_THRESHOLD=3
+
+init_circuit_breaker() {
+  local project_root="$1"
+  _CIRCUIT_BREAKER_FILE="${project_root}/.specweave/state/.hook-circuit-breaker"
+  mkdir -p "$(dirname "$_CIRCUIT_BREAKER_FILE")" 2>/dev/null
+}
+
+check_circuit_breaker() {
+  [[ -z "$_CIRCUIT_BREAKER_FILE" ]] && return 0
+
+  if [[ -f "$_CIRCUIT_BREAKER_FILE" ]]; then
+    local failures
+    failures=$(cat "$_CIRCUIT_BREAKER_FILE" 2>/dev/null || echo "0")
+    if [[ "$failures" -ge "$_CIRCUIT_BREAKER_THRESHOLD" ]]; then
+      [[ "$HOOK_DEBUG" == "1" ]] && echo "[HOOK] Circuit breaker OPEN ($failures failures)" >&2
+      return 1
+    fi
+  fi
+  return 0
+}
+
+record_circuit_breaker_failure() {
+  [[ -z "$_CIRCUIT_BREAKER_FILE" ]] && return
+
+  local failures
+  failures=$(cat "$_CIRCUIT_BREAKER_FILE" 2>/dev/null || echo "0")
+  echo "$((failures + 1))" > "$_CIRCUIT_BREAKER_FILE"
+}
+
+reset_circuit_breaker() {
+  [[ -n "$_CIRCUIT_BREAKER_FILE" ]] && rm -f "$_CIRCUIT_BREAKER_FILE"
+}
+
+# ============================================================================
+# 4. FILE-BASED RECURSION GUARD (ADR-0073 - replaces failed env var approach)
+# ============================================================================
+
+_RECURSION_GUARD_FILE=""
+
+init_recursion_guard() {
+  local project_root="$1"
+  _RECURSION_GUARD_FILE="${project_root}/.specweave/state/.hook-recursion-guard"
+}
+
+check_recursion_guard() {
+  [[ -z "$_RECURSION_GUARD_FILE" ]] && return 0
+
+  if [[ -f "$_RECURSION_GUARD_FILE" ]]; then
+    # Check if guard is stale (>30s old)
+    local guard_age
+    if [[ "$(uname)" == "Darwin" ]]; then
+      guard_age=$(( $(date +%s) - $(stat -f %m "$_RECURSION_GUARD_FILE" 2>/dev/null || echo "0") ))
+    else
+      guard_age=$(( $(date +%s) - $(stat -c %Y "$_RECURSION_GUARD_FILE" 2>/dev/null || echo "0") ))
+    fi
+
+    if [[ "$guard_age" -lt 30 ]]; then
+      [[ "$HOOK_DEBUG" == "1" ]] && echo "[HOOK] Recursion guard active (${guard_age}s old)" >&2
+      return 1
+    else
+      # Stale guard - clean it up
+      rm -f "$_RECURSION_GUARD_FILE"
+    fi
+  fi
+  return 0
+}
+
+acquire_recursion_guard() {
+  [[ -z "$_RECURSION_GUARD_FILE" ]] && return 1
+
+  touch "$_RECURSION_GUARD_FILE"
+  # Auto-cleanup on exit
+  trap 'rm -f "$_RECURSION_GUARD_FILE" 2>/dev/null' EXIT
+  return 0
+}
+
+release_recursion_guard() {
+  [[ -n "$_RECURSION_GUARD_FILE" ]] && rm -f "$_RECURSION_GUARD_FILE" 2>/dev/null
+}
+
+# ============================================================================
+# 5. LOCK FILE ACQUISITION (ADR-0068 Layer 3)
+# ============================================================================
+
+_LOCK_FILE=""
+_LOCK_TIMEOUT=5
+
+acquire_hook_lock() {
+  local lock_name="${1:-default}"
+  local project_root="${2:-$(find_project_root)}"
+
+  _LOCK_FILE="${project_root}/.specweave/state/.hook-${lock_name}.lock"
+  mkdir -p "$(dirname "$_LOCK_FILE")" 2>/dev/null
+
+  local attempts=0
+  while [[ $attempts -lt $((_LOCK_TIMEOUT * 5)) ]]; do
+    if mkdir "$_LOCK_FILE" 2>/dev/null; then
+      trap 'rmdir "$_LOCK_FILE" 2>/dev/null || true' EXIT
+      return 0
+    fi
+
+    # Check for stale lock (>60s old)
+    if [[ -d "$_LOCK_FILE" ]]; then
+      local lock_age
+      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
+
+      if [[ "$lock_age" -gt 60 ]]; then
+        rmdir "$_LOCK_FILE" 2>/dev/null
+        continue
+      fi
+    fi
+
+    sleep 0.2
+    attempts=$((attempts + 1))
+  done
+
+  [[ "$HOOK_DEBUG" == "1" ]] && echo "[HOOK] Lock acquisition timeout: $lock_name" >&2
+  return 1
+}
+
+release_hook_lock() {
+  [[ -n "$_LOCK_FILE" ]] && rmdir "$_LOCK_FILE" 2>/dev/null
+  _LOCK_FILE=""
+}
+
+# ============================================================================
+# 6. DEBOUNCING (ADR-0060 Tier 1, ADR-0130)
+# ============================================================================
+
+_DEBOUNCE_FILE=""
+_DEBOUNCE_WINDOW=5  # seconds
+
+check_debounce() {
+  local debounce_key="${1:-default}"
+  local project_root="${2:-$(find_project_root)}"
+
+  _DEBOUNCE_FILE="${project_root}/.specweave/state/.last-hook-${debounce_key}"
+
+  if [[ -f "$_DEBOUNCE_FILE" ]]; then
+    local last_run
+    last_run=$(cat "$_DEBOUNCE_FILE" 2>/dev/null || echo "0")
+    local now
+    now=$(date +%s)
+
+    if [[ $((now - last_run)) -lt $_DEBOUNCE_WINDOW ]]; then
+      [[ "$HOOK_DEBUG" == "1" ]] && echo "[HOOK] Debounced: $debounce_key" >&2
+      return 1
+    fi
+  fi
+  return 0
+}
+
+record_debounce() {
+  [[ -n "$_DEBOUNCE_FILE" ]] && date +%s > "$_DEBOUNCE_FILE"
+}
+
+# ============================================================================
+# 7. BULK OPERATION DETECTION (ADR-0130)
+# ============================================================================
+
+_BULK_COUNTER_FILE=""
+_BULK_THRESHOLD=5  # 5+ ops in 10s = bulk mode
+_BULK_WINDOW=10
+
+is_bulk_operation() {
+  local project_root="${1:-$(find_project_root)}"
+
+  _BULK_COUNTER_FILE="${project_root}/.specweave/state/.bulk-op-counter"
+  mkdir -p "$(dirname "$_BULK_COUNTER_FILE")" 2>/dev/null
+
+  local now
+  now=$(date +%s)
+
+  # Read current count and timestamp
+  local count=0
+  local start_time=$now
+
+  if [[ -f "$_BULK_COUNTER_FILE" ]]; then
+    read -r count start_time < "$_BULK_COUNTER_FILE" 2>/dev/null || true
+
+    # Reset if window expired
+    if [[ $((now - start_time)) -gt $_BULK_WINDOW ]]; then
+      count=0
+      start_time=$now
+    fi
+  fi
+
+  # Increment and save
+  count=$((count + 1))
+  echo "$count $start_time" > "$_BULK_COUNTER_FILE"
+
+  if [[ $count -ge $_BULK_THRESHOLD ]]; then
+    [[ "$HOOK_DEBUG" == "1" ]] && echo "[HOOK] Bulk operation detected ($count ops in window)" >&2
+    return 0  # IS bulk operation
+  fi
+  return 1  # NOT bulk operation
+}
+
+# ============================================================================
+# 8. LOG ROTATION (ADR-0060)
+# ============================================================================
+
+_LOG_FILE=""
+_LOG_MAX_SIZE=1048576  # 1MB
+
+init_log() {
+  local log_name="${1:-hooks}"
+  local project_root="${2:-$(find_project_root)}"
+
+  _LOG_DIR="${project_root}/.specweave/logs"
+  mkdir -p "$_LOG_DIR" 2>/dev/null
+  _LOG_FILE="${_LOG_DIR}/${log_name}.log"
+
+  # Rotate if too large
+  if [[ -f "$_LOG_FILE" ]]; then
+    local size
+    size=$(stat -f%z "$_LOG_FILE" 2>/dev/null || stat -c%s "$_LOG_FILE" 2>/dev/null || echo "0")
+    if [[ "$size" -gt "$_LOG_MAX_SIZE" ]]; then
+      mv "$_LOG_FILE" "${_LOG_FILE}.1" 2>/dev/null
+    fi
+  fi
+}
+
+log_hook() {
+  local level="$1"
+  shift
+  local msg="$*"
+
+  [[ -z "$_LOG_FILE" ]] && return
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [$level] $msg" >> "$_LOG_FILE"
+}
+
+# ============================================================================
+# 9. UNIFIED SETUP (ALL CHECKS IN ONE CALL)
+# ============================================================================
+
+setup_hook_environment() {
+  local hook_name="${1:-unnamed}"
+  local require_lock="${2:-false}"
+  local enable_recursion_guard="${3:-false}"
+
+  # Find project root
+  PROJECT_ROOT=$(find_project_root)
+  if [[ -z "$PROJECT_ROOT" ]]; then
+    [[ "$HOOK_DEBUG" == "1" ]] && echo "[HOOK] Not in SpecWeave project" >&2
+    return 1
+  fi
+  export PROJECT_ROOT
+
+  # Initialize state directory
+  _STATE_DIR="${PROJECT_ROOT}/.specweave/state"
+  mkdir -p "$_STATE_DIR" 2>/dev/null
+
+  # Layer 1: Kill switch
+  check_kill_switch || return 1
+
+  # Layer 2: Circuit breaker
+  init_circuit_breaker "$PROJECT_ROOT"
+  check_circuit_breaker || return 1
+
+  # Layer 3: Recursion guard (if enabled)
+  if [[ "$enable_recursion_guard" == "true" ]]; then
+    init_recursion_guard "$PROJECT_ROOT"
+    check_recursion_guard || return 1
+  fi
+
+  # Layer 4: Lock (if required)
+  if [[ "$require_lock" == "true" ]]; then
+    acquire_hook_lock "$hook_name" "$PROJECT_ROOT" || return 1
+  fi
+
+  # Layer 5: Debouncing
+  check_debounce "$hook_name" "$PROJECT_ROOT" || return 1
+
+  # Initialize logging
+  init_log "hooks" "$PROJECT_ROOT"
+
+  [[ "$HOOK_DEBUG" == "1" ]] && echo "[HOOK] Environment ready: $hook_name" >&2
+  return 0
+}
+
+# ============================================================================
+# 10. SAFE EXIT HANDLERS
+# ============================================================================
+
+# Always exit 0 from hooks (ADR-0157 Rule 6)
+# Exception: PreToolUse guards exit 2 to block
+hook_exit_success() {
+  release_hook_lock
+  release_recursion_guard
+  exit 0
+}
+
+hook_exit_block() {
+  release_hook_lock
+  release_recursion_guard
+  exit 2  # Block PreToolUse
+}
+
+# Record failure and exit safely
+hook_exit_with_failure() {
+  local msg="$1"
+  record_circuit_breaker_failure
+  log_hook "ERROR" "$msg"
+  release_hook_lock
+  release_recursion_guard
+  exit 0  # Still exit 0 to not break Claude
+}