specweave 0.24.11 → 0.26.2

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

@@ -36,10 +36,13 @@
 
 set +e  # NEVER use set -e in hooks - it causes crashes
 
-# EMERGENCY KILL SWITCH FIRST (before anything else)
-if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
-  exit 0
-fi
+# ============================================================================
+# PROJECT ROOT DETECTION (MUST BE FIRST - v0.26.1 FIX)
+# ============================================================================
+# CRITICAL FIX: PROJECT_ROOT must be defined BEFORE recursion guard creation
+# BUG (v0.26.0): Used $PROJECT_ROOT on line 71 but defined it on line 112
+# RESULT: Guard file created at wrong path (/.specweave/...) → recursion not prevented
+# See: Incident 2025-11-24 (3x PreToolUse hook fires, Claude Code crash)
 
 # Find project root by searching upward for .specweave/ directory
 # Works regardless of where hook is installed (source or .claude/hooks/)
@@ -63,6 +66,60 @@ find_project_root() {
 PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
 cd "$PROJECT_ROOT" 2>/dev/null || true
 
+# ============================================================================
+# 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
+#
+# Example infinite loop (BEFORE fix):
+#   TodoWrite → post-task-completion.sh (sets SPECWEAVE_IN_HOOK=1)
+#     → spawns background process (&)
+#       → consolidated-sync.js (SPECWEAVE_IN_HOOK=0! lost!)
+#         → fs.writeFile(tasks.md)
+#           → post-edit-write-consolidated.sh (guard fails!)
+#             → INFINITE RECURSION → 27 duplicate GitHub comments!
+#
+# With file-based guard (AFTER fix):
+#   TodoWrite → post-task-completion.sh (creates .hook-recursion-guard file)
+#     → spawns background process (&)
+#       → consolidated-sync.js (inherits guard file!)
+#         → fs.writeFile(tasks.md)
+#           → post-edit-write-consolidated.sh (checks file, exits)
+#             → NO RECURSION ✅
+#
+# 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
+  echo "[$(date)] ⏭️  Recursion guard detected - skipping (already in hook)" >> "$DEBUG_LOG" 2>/dev/null || true
+  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
+
+echo "[$(date)] 🔒 Recursion guard created" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# EMERGENCY KILL SWITCH (after recursion guard)
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
+
 # ============================================================================
 # EMERGENCY SAFETY CHECKS
 # ============================================================================
@@ -349,13 +406,25 @@ fi
   # ============================================================================
   # CONSOLIDATED SYNC (v0.24.4 - PERFORMANCE OPTIMIZATION)
   # ============================================================================
-  # REPLACES: 5-6 separate Node.js spawns with SINGLE consolidated process
-  # BEFORE: update-tasks-md.js, sync-living-docs.js, update-ac-status.js,
-  #         translate-living-docs.js, prepare-reflection-context.js
-  # AFTER:  consolidated-sync.js (runs all operations sequentially)
-  # IMPACT: 83% reduction in process spawning overhead
+  # EMERGENCY FIX (v0.26.0-hotfix): DISABLED TO PREVENT CLAUDE CODE CRASHES
+  #
+  # ROOT CAUSE: consolidated-sync.js makes 5+ Edit/Write operations, each triggering
+  # 3 hooks (PreToolUse, PostToolUse×2), resulting in 15+ hook invocations per task.
+  # This causes process exhaustion and Claude Code crashes.
+  #
+  # NEW STRATEGY: Run consolidated sync ONLY at:
+  # 1. Session end (all tasks done + 120s inactivity)
+  # 2. Manual sync (/specweave:sync-docs command)
+  # 3. Increment closure (/specweave:done validation)
+  #
+  # See: .specweave/increments/0051-*/reports/CLAUDE-CODE-CRASH-ROOT-CAUSE-2025-11-23.md
+  # See: ADR-0072 (Post-Task Hook Simplification)
   # ============================================================================
 
+  # RE-ENABLED: Automatic sync on each TodoWrite (ACCEPTING CRASH RISK)
+  # WARNING: This can cause Claude Code crashes if too many TodoWrite events fire rapidly
+  # User explicitly requested re-enabling despite crash risk
+
   echo "[$(date)] 🚀 Running consolidated sync" >> "$DEBUG_LOG" 2>/dev/null || true
 
   # Find consolidated sync script
@@ -371,6 +440,28 @@ fi
   fi
 
   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 "[$(date)] ✅ GitHub token loaded from .env" >> "$DEBUG_LOG" 2>/dev/null || true
+      fi
+    fi
+
+    # FIX (v0.26.0): Skip GitHub sync in post-task-completion hook
+    # GitHub sync should ONLY run on increment COMPLETION, not task completion
+    # This prevents 27 duplicate comments (see root cause analysis)
+    export SKIP_GITHUB_SYNC=true
+
+    # EMERGENCY FIX (v0.25.1): Skip US sync in post-task-completion hook
+    # CRITICAL: US sync triggers livingDocsSync.syncIncrement() which calls
+    # syncToExternalTools() without respecting SKIP_GITHUB_SYNC, causing
+    # Edit/Write operations that trigger new hook chains → infinite recursion → crash
+    # See: ROOT-CAUSE-ANALYSIS-TODOWRITE-CRASH-2025-11-24.md
+    export SKIP_US_SYNC=true
+
     # Run consolidated sync (single Node.js process handles ALL operations)
     if (cd "$PROJECT_ROOT" && node "$CONSOLIDATED_SCRIPT" "$CURRENT_INCREMENT") >> "$DEBUG_LOG" 2>&1; then
       echo "[$(date)] ✅ Consolidated sync completed" >> "$DEBUG_LOG" 2>/dev/null || true

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

@@ -101,17 +101,6 @@ else
   exit 0  # Let PostToolUse handle it with mtime fallback
 fi
 
-# ============================================================================
-# EARLY EXIT: Only process .specweave/ files (v0.24.4 Performance Fix)
-# ============================================================================
-# 90% of Edit operations are on non-SpecWeave files (src/, tests/, node_modules/)
-# Exit immediately for non-.specweave/ files to reduce hook overhead by 90%
-
-if [[ "$FILE_PATH" != *"/.specweave/"* ]]; then
-  echo "[$(date)] pre-edit-spec: Not a .specweave/ file, skipping (performance optimization)" >> "$DEBUG_LOG" 2>/dev/null || true
-  exit 0
-fi
-
 # Check if this is a spec.md or tasks.md file in increments folder
 IS_SPEC_FILE=false
 if [[ "$FILE_PATH" == *"/spec.md" ]] || [[ "$FILE_PATH" == *"/tasks.md" ]]; then

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

@@ -0,0 +1,225 @@
+#!/bin/bash
+#
+# Pre-Edit/Write Consolidated Hook: Capture File Path BEFORE Edit/Write Executes
+#
+# Purpose: Unified hook for both Edit and Write tools
+# Strategy: Hierarchical early exit for maximum performance
+#
+# CONSOLIDATION (v0.25.0):
+# - Replaces pre-edit-spec.sh and pre-write-spec.sh (identical code)
+# - Reduces hook overhead by 50% (2 pre-hooks → 1)
+# - Single point of maintenance
+#
+# HIERARCHICAL EARLY EXIT (v0.26.1):
+# - Tier 0: TOOL_USE_ARGS check (< 1ms) - Exit if empty (Claude Code bug)
+# - Tier 1: .specweave/ path check (< 5ms) - Exit if not SpecWeave file
+# - Tier 2: Active increment check (< 10ms) - Exit if archived/completed
+# - Tier 3: Full processing - AC sync, status line, living docs
+#
+# GRACEFUL DEGRADATION:
+# - PreToolUse works if TOOL_USE_ARGS is available (fast filtering)
+# - PostToolUse fallback uses mtime if PreToolUse disabled (slower but works)
+# - Self-tuning: Disables PreToolUse if consistently useless
+#
+# Architecture:
+#   PreToolUse:Edit/Write → pre-edit-write-consolidated.sh (this file)
+#     ↓ writes to
+#   .specweave/state/.pending-status-update
+#     ↓ read by
+#   PostToolUse:Edit/Write → post-edit-write-consolidated.sh
+#
+# Version: v0.26.1 (HIERARCHICAL EARLY EXIT)
+# Date: 2025-11-24
+#
+# 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
+# - Complete error isolation: Never let errors reach Claude Code
+
+# EMERGENCY FIX: Remove set -e - it causes Claude Code crashes!
+set +e
+
+# ============================================================================
+# TIER 0: ULTRA-FAST REJECTION (< 1ms) - v0.26.1 CRITICAL FIX
+# ============================================================================
+# Problem: Claude Code doesn't pass TOOL_USE_ARGS to PreToolUse hooks (bug)
+# Result: PreToolUse hooks are "blind" - can't filter files, fire for everything
+# Impact: Massive overhead (1 pre-hook per Edit/Write on ANY file)
+#
+# Solution: Exit immediately if TOOL_USE_ARGS is empty
+# - No find_project_root, no file path extraction, no processing
+# - Eliminates 33% of hook overhead (1 of 3 hooks per operation)
+# - Falls back to PostToolUse mtime detection (slower but works)
+#
+# See: ADR-0128 (Hierarchical Hook Early Exit Strategy)
+
+if [[ -z "${TOOL_USE_ARGS:-}" ]]; then
+  # Telemetry: Track PreToolUse disabled events (lightweight counter)
+  # This helps us understand if Claude Code ever fixes the TOOL_USE_ARGS bug
+  TELEMETRY_DIR="${HOME}/.claude/.specweave-telemetry"
+  mkdir -p "$TELEMETRY_DIR" 2>/dev/null || true
+  echo "$(date -u +%s)" >> "$TELEMETRY_DIR/pretooluse-disabled.log" 2>/dev/null || true
+
+  # Silent exit - PreToolUse is useless without TOOL_USE_ARGS
+  # PostToolUse will handle via mtime fallback
+  exit 0
+fi
+
+# Telemetry: Track PreToolUse enabled events (TOOL_USE_ARGS available)
+TELEMETRY_DIR="${HOME}/.claude/.specweave-telemetry"
+mkdir -p "$TELEMETRY_DIR" 2>/dev/null || true
+echo "$(date -u +%s)" >> "$TELEMETRY_DIR/pretooluse-enabled.log" 2>/dev/null || true
+
+# 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)
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+PENDING_FILE="$STATE_DIR/.pending-status-update"
+METRICS_FILE="$STATE_DIR/hook-metrics.jsonl"
+
+# ============================================================================
+# RECURSION PREVENTION (CRITICAL - v0.26.0 - FILE-BASED GUARD)
+# ============================================================================
+# NEW SOLUTION (v0.26.0): File-based recursion guard
+# - Guard file exists = already inside hook chain
+# - Works across ALL processes (not just current shell)
+#
+# 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
+  exit 0
+fi
+
+# EMERGENCY KILL SWITCH: Disable all hooks if env variable set
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
+
+# Ensure directories exist
+mkdir -p "$STATE_DIR" "$LOGS_DIR" 2>/dev/null || true
+
+# ============================================================================
+# TIER 2: Extract File Path from Tool Arguments
+# ============================================================================
+# PreToolUse should have access to tool arguments BEFORE execution
+# Try multiple methods to extract file_path
+
+FILE_PATH=""
+
+# Method 1: TOOL_USE_ARGS environment variable (primary for PreToolUse)
+if [[ -n "${TOOL_USE_ARGS:-}" ]]; then
+  # Try to parse JSON with jq if available
+  if command -v jq &> /dev/null; then
+    FILE_PATH=$(echo "$TOOL_USE_ARGS" | jq -r '.file_path // empty' 2>/dev/null || echo "")
+  fi
+
+  # Fallback: Regex extraction if jq not available or failed
+  if [[ -z "$FILE_PATH" ]]; then
+    FILE_PATH=$(echo "$TOOL_USE_ARGS" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+  fi
+fi
+
+# Method 2: TOOL_USE_CONTENT (fallback)
+if [[ -z "$FILE_PATH" ]] && [[ -n "${TOOL_USE_CONTENT:-}" ]]; then
+  FILE_PATH="$TOOL_USE_CONTENT"
+fi
+
+# Method 3: Parse from stdin (last resort - experimental)
+if [[ -z "$FILE_PATH" ]] && [[ ! -t 0 ]]; then
+  # Read stdin and try to extract file_path
+  STDIN_DATA=$(cat 2>/dev/null || echo "")
+  if [[ -n "$STDIN_DATA" ]] && command -v jq &> /dev/null; then
+    FILE_PATH=$(echo "$STDIN_DATA" | jq -r '.file_path // empty' 2>/dev/null || echo "")
+  fi
+fi
+
+# ============================================================================
+# TIER 2: Signal Detection and Validation
+# ============================================================================
+
+# Log what we detected (for debugging PreToolUse effectiveness)
+if [[ -n "$FILE_PATH" ]]; then
+  echo "[$(date)] pre-edit-write: Detected file_path: $FILE_PATH" >> "$DEBUG_LOG" 2>/dev/null || true
+else
+  echo "[$(date)] pre-edit-write: No file_path detected (will fall back to Tier 1)" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0  # Let PostToolUse handle it with mtime fallback
+fi
+
+# ============================================================================
+# EARLY EXIT: Only process .specweave/ files (v0.24.4 Performance Fix)
+# ============================================================================
+# 90% of Edit/Write operations are on non-SpecWeave files (src/, tests/, node_modules/)
+# Exit immediately for non-.specweave/ files to reduce hook overhead by 90%
+
+# Handle both absolute and relative paths: /.specweave/ or .specweave/
+if [[ "$FILE_PATH" != *"/.specweave/"* ]] && [[ "$FILE_PATH" != ".specweave/"* ]]; then
+  echo "[$(date)] pre-edit-write: Not a .specweave/ file, skipping (performance optimization)" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+# Check if this is a spec.md or tasks.md file in increments folder
+IS_SPEC_FILE=false
+if [[ "$FILE_PATH" == *"/spec.md" ]] || [[ "$FILE_PATH" == *"/tasks.md" ]]; then
+  # Handle both absolute (/.specweave/increments/) and relative (.specweave/increments/) paths
+  if [[ "$FILE_PATH" == *"/.specweave/increments/"* ]] || [[ "$FILE_PATH" == ".specweave/increments/"* ]]; then
+    # Exclude archived increments
+    if [[ "$FILE_PATH" != *"/_archive/"* ]]; then
+      IS_SPEC_FILE=true
+    fi
+  fi
+fi
+
+# If not a spec/tasks file, exit silently (no signal to PostToolUse)
+if [[ "$IS_SPEC_FILE" != "true" ]]; then
+  echo "[$(date)] pre-edit-write: Not a spec/tasks file - no signal" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+# ============================================================================
+# TIER 2: Write Signal for PostToolUse Hook
+# ============================================================================
+
+# Write file path to pending file for PostToolUse to consume
+echo "$FILE_PATH" > "$PENDING_FILE" 2>/dev/null || true
+
+echo "[$(date)] pre-edit-write: Signaled PostToolUse for: $FILE_PATH" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# TIER 2: Metrics Collection
+# ============================================================================
+
+# Record metrics (JSONL format - one JSON object per line)
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+METRIC_ENTRY="{\"timestamp\":\"$TIMESTAMP\",\"hook\":\"pre-edit-write\",\"event\":\"file_detected\",\"file_path\":\"$FILE_PATH\",\"method\":\"TOOL_USE_ARGS\"}"
+
+# Append to metrics file (JSONL)
+echo "$METRIC_ENTRY" >> "$METRICS_FILE" 2>/dev/null || true
+
+# Log rotation for metrics (keep last 1000 entries)
+if [[ -f "$METRICS_FILE" ]]; then
+  LINE_COUNT=$(wc -l < "$METRICS_FILE" 2>/dev/null || echo 0)
+  if (( LINE_COUNT > 1000 )); then
+    tail -1000 "$METRICS_FILE" > "$METRICS_FILE.tmp" 2>/dev/null || true
+    mv "$METRICS_FILE.tmp" "$METRICS_FILE" 2>/dev/null || true
+  fi
+fi
+
+# ALWAYS exit 0 - NEVER let hook errors crash Claude Code
+exit 0

package/plugins/specweave/hooks/pre-task-completion.sh

@@ -22,6 +22,17 @@
 
 set +e  # EMERGENCY FIX: Prevents Claude Code crashes
 
+# ============================================================================
+# RECURSION PREVENTION (CRITICAL - v0.25.1)
+# ============================================================================
+# Skip if we're already inside a hook to prevent infinite recursion
+if [[ "${SPECWEAVE_IN_HOOK:-0}" == "1" ]]; then
+  exit 0
+fi
+
+# Mark that we're now inside a hook
+export SPECWEAVE_IN_HOOK=1
+
 # EMERGENCY KILL SWITCH
 if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
   exit 0

package/plugins/specweave/hooks/pre-write-spec.sh

@@ -101,17 +101,6 @@ else
   exit 0  # Let PostToolUse handle it with mtime fallback
 fi
 
-# ============================================================================
-# EARLY EXIT: Only process .specweave/ files (v0.24.4 Performance Fix)
-# ============================================================================
-# 90% of Write operations are on non-SpecWeave files (src/, tests/, node_modules/)
-# Exit immediately for non-.specweave/ files to reduce hook overhead by 90%
-
-if [[ "$FILE_PATH" != *"/.specweave/"* ]]; then
-  echo "[$(date)] pre-write-spec: Not a .specweave/ file, skipping (performance optimization)" >> "$DEBUG_LOG" 2>/dev/null || true
-  exit 0
-fi
-
 # Check if this is a spec.md or tasks.md file in increments folder
 IS_SPEC_FILE=false
 if [[ "$FILE_PATH" == *"/spec.md" ]] || [[ "$FILE_PATH" == *"/tasks.md" ]]; then

package/plugins/specweave/hooks/shared/bulk-operation-detector.sh

@@ -0,0 +1,167 @@
+#!/bin/bash
+# Bulk Operation Detector (v0.26.0)
+#
+# Detects bulk edit operations (5+ edits in 10 seconds) and triggers batch mode.
+# Part of ADR-0130: Hook Bulk Operation Detection and Batching
+#
+# Usage:
+#   source bulk-operation-detector.sh
+#   BULK_STATUS=$(detect_bulk_operation "$INCREMENT_ID")
+#
+#   if [ "$BULK_STATUS" = "BULK_MODE_DETECTED" ]; then
+#     # Skip individual hook, batch job will run later
+#     exit 0
+#   fi
+
+# Configuration
+BULK_THRESHOLD=${SPECWEAVE_BULK_THRESHOLD:-5}      # 5+ operations = bulk mode
+BULK_WINDOW=${SPECWEAVE_BULK_WINDOW:-10}            # seconds
+IDLE_DELAY=${SPECWEAVE_IDLE_DELAY:-5}               # seconds before batch execution
+
+# State files
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+OPERATION_COUNTER="$STATE_DIR/.hook-operation-counter"
+OPERATION_TIMESTAMP="$STATE_DIR/.hook-operation-timestamp"
+
+# Ensure state directory exists
+mkdir -p "$STATE_DIR"
+
+##
+# Detect bulk operation
+#
+# Uses sliding window counter to detect operation bursts:
+# - Counts operations within BULK_WINDOW (10 seconds)
+# - If count >= BULK_THRESHOLD (5 operations) → bulk mode
+# - Resets counter after idle period
+#
+# Args:
+#   $1 - INCREMENT_ID (optional, for logging)
+#
+# Returns:
+#   BULK_MODE_DETECTED - Bulk operation detected, skip individual hook
+#   SINGLE_OPERATION   - Single operation, run hook normally
+##
+detect_bulk_operation() {
+  local INCREMENT_ID="${1:-unknown}"
+  local CURRENT_TIME=$(date +%s)
+
+  # Read existing counter and timestamp
+  local RECENT_OPS=0
+  local LAST_OP_TIME=0
+
+  if [ -f "$OPERATION_COUNTER" ]; then
+    RECENT_OPS=$(cat "$OPERATION_COUNTER" 2>/dev/null || echo 0)
+  fi
+
+  if [ -f "$OPERATION_TIMESTAMP" ]; then
+    LAST_OP_TIME=$(cat "$OPERATION_TIMESTAMP" 2>/dev/null || echo 0)
+  fi
+
+  # Reset counter if outside window (idle period detected)
+  local TIME_SINCE_LAST_OP=$((CURRENT_TIME - LAST_OP_TIME))
+  if (( TIME_SINCE_LAST_OP > BULK_WINDOW )); then
+    RECENT_OPS=0
+  fi
+
+  # Increment operation counter
+  RECENT_OPS=$((RECENT_OPS + 1))
+
+  # Write atomically (use temp file + rename for atomicity)
+  echo "$RECENT_OPS" > "${OPERATION_COUNTER}.tmp"
+  mv "${OPERATION_COUNTER}.tmp" "$OPERATION_COUNTER"
+
+  echo "$CURRENT_TIME" > "${OPERATION_TIMESTAMP}.tmp"
+  mv "${OPERATION_TIMESTAMP}.tmp" "$OPERATION_TIMESTAMP"
+
+  # Bulk operation detected?
+  if (( RECENT_OPS >= BULK_THRESHOLD )); then
+    # Log bulk mode activation
+    local DEBUG_LOG="$PROJECT_ROOT/.specweave/logs/hook-debug.log"
+    echo "[$(date)] [BULK] Detected bulk operation for $INCREMENT_ID (op #$RECENT_OPS)" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Schedule batch job (if not already scheduled)
+    schedule_batch_job "$INCREMENT_ID"
+
+    echo "BULK_MODE_DETECTED"
+    return 0
+  fi
+
+  # Single operation
+  echo "SINGLE_OPERATION"
+  return 0
+}
+
+##
+# Schedule batch job
+#
+# Schedules a batch job to run after idle period (IDLE_DELAY seconds).
+# If a batch job is already scheduled, it gets canceled and rescheduled.
+#
+# Args:
+#   $1 - INCREMENT_ID
+##
+schedule_batch_job() {
+  local INCREMENT_ID="$1"
+  local BATCH_LOCK="$STATE_DIR/.batch-job-${INCREMENT_ID}.lock"
+  local DEBUG_LOG="$PROJECT_ROOT/.specweave/logs/hook-debug.log"
+
+  # Cancel existing batch job (if any)
+  if [ -f "$BATCH_LOCK" ]; then
+    local OLD_PID=$(cat "$BATCH_LOCK" 2>/dev/null || echo "")
+    if [ -n "$OLD_PID" ] && kill -0 "$OLD_PID" 2>/dev/null; then
+      kill "$OLD_PID" 2>/dev/null || true
+      echo "[$(date)] [BATCH] Canceled previous batch job (PID: $OLD_PID)" >> "$DEBUG_LOG" 2>/dev/null || true
+    fi
+    rm -f "$BATCH_LOCK"
+  fi
+
+  # Schedule new batch job (background process)
+  (
+    # Wait for idle period
+    sleep "$IDLE_DELAY"
+
+    # If operation counter still exists → run batched hook
+    if [ -f "$OPERATION_COUNTER" ]; then
+      local OPERATION_COUNT=$(cat "$OPERATION_COUNTER" 2>/dev/null || echo 0)
+
+      echo "[$(date)] [BATCH] Idle period detected, running batch job for $INCREMENT_ID ($OPERATION_COUNT ops)" >> "$DEBUG_LOG" 2>/dev/null || true
+
+      # Clear operation counter (batch job starting)
+      rm -f "$OPERATION_COUNTER" "$OPERATION_TIMESTAMP"
+
+      # Run consolidated hook in batch mode
+      bash "$PROJECT_ROOT/plugins/specweave/hooks/post-task-completion.sh" \
+        --batch-mode \
+        --increment "$INCREMENT_ID" \
+        >> "$PROJECT_ROOT/.specweave/logs/batch-jobs.log" 2>&1
+
+      echo "[$(date)] [BATCH] ✅ Batch job completed for $INCREMENT_ID" >> "$DEBUG_LOG" 2>/dev/null || true
+    else
+      echo "[$(date)] [BATCH] Operation counter cleared before batch job ran (duplicate batch?)" >> "$DEBUG_LOG" 2>/dev/null || true
+    fi
+
+    # Cleanup batch lock
+    rm -f "$BATCH_LOCK"
+  ) &
+
+  # Save PID for cancellation
+  local BATCH_PID=$!
+  echo "$BATCH_PID" > "$BATCH_LOCK"
+
+  echo "[$(date)] [BATCH] Scheduled batch job for $INCREMENT_ID (PID: $BATCH_PID, delay: ${IDLE_DELAY}s)" >> "$DEBUG_LOG" 2>/dev/null || true
+}
+
+##
+# Reset bulk operation counter
+#
+# Manually resets the operation counter (useful for testing or troubleshooting).
+##
+reset_bulk_counter() {
+  rm -f "$OPERATION_COUNTER" "$OPERATION_TIMESTAMP"
+  echo "[$(date)] [BULK] Operation counter reset" >> "$PROJECT_ROOT/.specweave/logs/hook-debug.log" 2>/dev/null || true
+}
+
+# Export functions for use in hooks
+export -f detect_bulk_operation
+export -f schedule_batch_job
+export -f reset_bulk_counter