specweave 1.0.31 → 1.0.33

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

@@ -1,33 +1,17 @@
 #!/bin/bash
-# common-setup.sh - Unified Hook Library for Crash Prevention
+# common-setup.sh - Minimal Hook Library
 #
-# 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.
+# Only essential utilities for hooks. Crash prevention is handled by:
+# - Claude Code's native tool timeouts
+# - fail-fast-wrapper.sh (5s timeout for hook scripts)
 #
 # 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=""
+set +e  # NEVER use set -e in hooks
 
 # ============================================================================
-# 1. PROJECT ROOT DETECTION (ADR-0068, ADR-0128)
+# PROJECT ROOT DETECTION
 # ============================================================================
 
 find_project_root() {
@@ -43,333 +27,75 @@ find_project_root() {
 }
 
 # ============================================================================
-# 2. EMERGENCY KILL SWITCH (ADR-0068 Layer 1, ADR-0157 Rule 4)
+# KILL SWITCH
 # ============================================================================
 
 check_kill_switch() {
-  if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
-    [[ "$HOOK_DEBUG" == "1" ]] && echo "[HOOK] Kill switch active" >&2
-    return 1
-  fi
-  return 0
+  [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]
 }
 
 # ============================================================================
-# 3. CIRCUIT BREAKER (ADR-0068 Layer 2)
+# PRE-TOOL-USE GUARD HELPERS
 # ============================================================================
 
-# 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
-}
+# Global variables set by init_pretool_guard
+HOOK_INPUT=""
+HOOK_TOOL_NAME=""
+HOOK_FILE_PATH=""
+HOOK_CONTENT=""
 
-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
+# Initialize PreToolUse guard environment
+# Returns 1 if hook should exit early (kill switch, no jq, etc.)
+init_pretool_guard() {
+  if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+    echo '{"decision":"allow"}'
+    return 1
   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
+  HOOK_INPUT=$(cat 2>/dev/null || echo '{}')
 
-    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
+  if ! command -v jq >/dev/null 2>&1; then
+    echo '{"decision":"allow"}'
+    return 1
   fi
-  return 0
-}
 
-acquire_recursion_guard() {
-  [[ -z "$_RECURSION_GUARD_FILE" ]] && return 1
+  HOOK_TOOL_NAME=$(echo "$HOOK_INPUT" | jq -r '.tool_name // ""' 2>/dev/null || echo "")
+  HOOK_FILE_PATH=$(echo "$HOOK_INPUT" | jq -r '.tool_input.file_path // .file_path // ""' 2>/dev/null || echo "")
+  HOOK_CONTENT=$(echo "$HOOK_INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null || echo "")
 
-  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
+# Allow the tool call with optional message
+guard_allow() {
+  local message="${1:-}"
+  if [[ -n "$message" ]]; then
+    printf '{"decision":"allow","message":"%s"}\n' "$message"
+  else
+    echo '{"decision":"allow"}'
   fi
-  return 0
-}
-
-record_debounce() {
-  [[ -n "$_DEBOUNCE_FILE" ]] && date +%s > "$_DEBOUNCE_FILE"
+  exit 0
 }
 
-# ============================================================================
-# 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
+# Block the tool call with reason
+guard_block() {
+  local reason="$1"
+  reason=$(echo "$reason" | sed 's/"/\\"/g' | sed ':a;N;$!ba;s/\n/\\n/g')
+  printf '{"decision":"block","reason":"%s"}\n' "$reason"
+  exit 2
 }
 
 # ============================================================================
-# 8. LOG ROTATION (ADR-0060)
+# SIMPLE LOGGING (optional, writes to .specweave/logs/hooks.log)
 # ============================================================================
 
-_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
+  local project_root
+  project_root=$(find_project_root) || return
+  local log_file="$project_root/.specweave/logs/hooks.log"
+  mkdir -p "$(dirname "$log_file")" 2>/dev/null
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [$level] $msg" >> "$log_file" 2>/dev/null
 }

package/plugins/specweave/hooks/lib/migrate-increment-work.sh

@@ -203,7 +203,7 @@ case "${1:-}" in
   transfer)
     if [[ $# -ne 3 ]]; then
       echo "Usage: $0 transfer <source_increment> <target_increment>"
-      exit 1
+      exit 0  # SAFETY: Never use exit 1 in hooks
     fi
     transfer_work "$2" "$3"
     ;;
@@ -211,7 +211,7 @@ case "${1:-}" in
   adjust-wip)
     if [[ $# -ne 2 ]]; then
       echo "Usage: $0 adjust-wip <new_limit>"
-      exit 1
+      exit 0  # SAFETY: Never use exit 1 in hooks
     fi
     adjust_wip_limit "$2"
     ;;
@@ -219,7 +219,7 @@ case "${1:-}" in
   force-close)
     if [[ $# -ne 2 ]]; then
       echo "Usage: $0 force-close <increment_id>"
-      exit 1
+      exit 0  # SAFETY: Never use exit 1 in hooks
     fi
     force_close "$2"
     ;;
@@ -227,7 +227,7 @@ case "${1:-}" in
   count-incomplete)
     if [[ $# -ne 2 ]]; then
       echo "Usage: $0 count-incomplete <increment_id>"
-      exit 1
+      exit 0  # SAFETY: Never use exit 1 in hooks
     fi
     count_incomplete_tasks "$2"
     ;;
@@ -240,6 +240,6 @@ case "${1:-}" in
     echo "  $0 adjust-wip <limit>             # Adjust WIP limit temporarily"
     echo "  $0 force-close <increment>        # Force-close increment"
     echo "  $0 count-incomplete <increment>   # Count incomplete tasks"
-    exit 1
+    exit 0  # SAFETY: Never use exit 1 in hooks
     ;;
 esac

package/plugins/specweave/hooks/lib/sync-spec-content.sh

@@ -21,10 +21,10 @@ set +e  # EMERGENCY FIX: Changed from set -euo pipefail to prevent Claude Code c
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
 
-# Input validation
+# Input validation - exit 0 for safety (never exit 1 in hooks)
 if [ $# -lt 1 ]; then
   echo "Usage: $0 <spec-path>" >&2
-  exit 1
+  exit 0  # SAFETY: Never use exit 1 in hooks
 fi
 
 SPEC_PATH="$1"
@@ -32,7 +32,7 @@ SPEC_PATH="$1"
 # Validate spec file exists
 if [ ! -f "$SPEC_PATH" ]; then
   echo "❌ Spec file not found: $SPEC_PATH" >&2
-  exit 1
+  exit 0  # SAFETY: Never use exit 1 in hooks
 fi
 
 # Check if sync is enabled
@@ -105,7 +105,7 @@ fi
 # Validate provider
 if [[ ! "$PROVIDER" =~ ^(github|jira|ado)$ ]]; then
   echo "❌ Invalid provider: $PROVIDER (must be github, jira, or ado)" >&2
-  exit 1
+  exit 0  # SAFETY: Never use exit 1 in hooks
 fi
 
 # Check if sync CLI command exists
@@ -119,7 +119,7 @@ fi
 # Check if Node.js is available
 if ! command -v node &> /dev/null; then
   echo "❌ Node.js not found, cannot sync spec content" >&2
-  exit 1
+  exit 0  # SAFETY: Never use exit 1 in hooks
 fi
 
 echo ""

package/plugins/specweave/hooks/universal/dispatcher.mjs

@@ -12,7 +12,7 @@
  *   - session-start
  *   - post-tool-use
  *   - completion-guard
- *   - bash-file-guard
+ *   - increment-duplicate-guard
  *
  * @module hooks/universal/dispatcher
  */
@@ -322,10 +322,9 @@ async function main() {
         await fallbackToBash('completion-guard.sh', 'guards');
         break;
 
-      case 'bash-file-guard':
-        // CRITICAL: Prevents infinite hangs from heredoc/echo file creation
-        // See CLAUDE.md Rule 9 for why this is essential
-        await fallbackToBash('bash-file-guard.sh', 'guards');
+      case 'increment-duplicate-guard':
+        // Prevents duplicate increment IDs
+        await fallbackToBash('increment-duplicate-guard.sh', 'guards');
         break;
 
       default: