specweave 0.24.13 → 0.26.3

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

@@ -25,6 +25,32 @@ fi
 PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"
 INCREMENT_DIR="$PROJECT_ROOT/.specweave/increments/$INCREMENT_ID"
 
+# ============================================================================
+# RECURSION PREVENTION (v0.26.1 - CRITICAL)
+# ============================================================================
+# PROBLEM: consolidated-sync.js does Edit/Write operations which trigger hooks.
+# If no guard exists, those hooks will run full sync → more Edit/Write → INFINITE LOOP.
+#
+# SOLUTION: Create recursion guard file BEFORE calling any sync scripts.
+# Other hooks check this file and exit early if it exists.
+#
+# See: ADR-0073 (Hook Recursion Prevention Strategy)
+# See: .specweave/increments/0051-*/reports/GITHUB-COMMENT-RECURSION-ROOT-CAUSE-2025-11-24.md
+
+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
+
+# 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
+
 # Check if increment exists
 if [ ! -d "$INCREMENT_DIR" ]; then
   echo "⚠️  $HOOK_NAME: Increment $INCREMENT_ID not found" >&2
@@ -233,4 +259,111 @@ else
   echo ""
 fi
 
+# ============================================================================
+# GITHUB SYNC (v0.26.1 - CRITICAL FIX)
+# ============================================================================
+# After living docs sync, create GitHub issues for user stories.
+# This is the AUTOMATIC GitHub sync that runs once per increment completion.
+#
+# CRITICAL: This was MISSING in v0.26.0, causing GitHub issues to NEVER be
+# created automatically. The consolidated-sync.js has the full logic for:
+# - Creating GitHub issues for user stories (with 3-layer idempotency)
+# - Syncing task completion comments to existing issues
+# - Format preservation sync for external tools
+#
+# GATE SYSTEM (4 gates - all checked inside consolidated-sync.js):
+# - GATE 1: canUpsertInternalItems (living docs sync enabled)
+# - GATE 2: canUpdateExternalItems (external tool sync enabled)
+# - GATE 3: autoSyncOnCompletion (automatic sync enabled)
+# - GATE 4: sync.github.enabled (GitHub-specific sync enabled)
+#
+# RECURSION SAFETY:
+# - Recursion guard created at script start (line 49)
+# - consolidated-sync.js does Edit/Write operations
+# - Other hooks see the guard and exit early
+# - Guard removed via trap on script exit
+#
+# USER PROJECT COMPATIBILITY:
+# - Script detection works for: development, dist/, node_modules/, marketplace
+# - Works in both SpecWeave framework repo AND user projects using SpecWeave
+# - GITHUB_TOKEN loaded from project's .env file
+#
+# See: Root cause analysis in initial implementation planning
+# See: ADR-0073 (Hook Recursion Prevention Strategy)
+
+if command -v node &> /dev/null; then
+  echo ""
+  echo "🔗 Creating GitHub issues for user stories..."
+
+  # ========================================================================
+  # LOCATE CONSOLIDATED SYNC SCRIPT
+  # ========================================================================
+  # Find consolidated-sync.js in order of preference:
+  # 1. In-place compiled (development, esbuild output)
+  # 2. Local dist (development, tsc output)
+  # 3. node_modules (installed as dependency) ← USER PROJECTS
+  # 4. Plugin marketplace (Claude Code global installation)
+
+  CONSOLIDATED_SCRIPT=""
+  if [ -f "$PROJECT_ROOT/plugins/specweave/lib/hooks/consolidated-sync.js" ]; then
+    # Development: Use in-place compiled hooks (esbuild, not tsc)
+    CONSOLIDATED_SCRIPT="$PROJECT_ROOT/plugins/specweave/lib/hooks/consolidated-sync.js"
+    echo "  🔧 Using in-place compiled hook (development mode)"
+  elif [ -f "$PROJECT_ROOT/dist/plugins/specweave/lib/hooks/consolidated-sync.js" ]; then
+    # Development: Use project's compiled files (has node_modules)
+    CONSOLIDATED_SCRIPT="$PROJECT_ROOT/dist/plugins/specweave/lib/hooks/consolidated-sync.js"
+    echo "  🔧 Using local dist (development mode)"
+  elif [ -f "$PROJECT_ROOT/node_modules/specweave/dist/plugins/specweave/lib/hooks/consolidated-sync.js" ]; then
+    # Installed as dependency: Use node_modules version (MOST USER PROJECTS)
+    CONSOLIDATED_SCRIPT="$PROJECT_ROOT/node_modules/specweave/dist/plugins/specweave/lib/hooks/consolidated-sync.js"
+    echo "  📦 Using node_modules version"
+  elif [ -n "${CLAUDE_PLUGIN_ROOT}" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/lib/hooks/consolidated-sync.js" ]; then
+    # Fallback: Plugin marketplace (may fail if deps missing)
+    CONSOLIDATED_SCRIPT="${CLAUDE_PLUGIN_ROOT}/lib/hooks/consolidated-sync.js"
+    echo "  🌐 Using plugin marketplace version"
+  fi
+
+  # ========================================================================
+  # EXECUTE GITHUB SYNC
+  # ========================================================================
+  # Run consolidated sync to create GitHub issues and sync task completion.
+  # Non-blocking: Errors logged but don't crash hook (increment already closed)
+  #
+  # CRITICAL: Do NOT set SKIP_GITHUB_SYNC=true here!
+  # That flag is ONLY for post-task-completion hook to prevent duplicate comments.
+  # On increment completion, we WANT GitHub sync to run.
+
+  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 "  🔑 GitHub token loaded from .env"
+      fi
+    fi
+
+    # Run consolidated sync (synchronous - user sees immediate feedback)
+    # This creates GitHub issues, syncs comments, and performs format preservation
+    if (cd "$PROJECT_ROOT" && node "$CONSOLIDATED_SCRIPT" "$INCREMENT_ID") 2>&1; then
+      echo "  ✅ GitHub sync complete"
+      echo ""
+    else
+      echo "  ⚠️  Failed to sync GitHub issues (non-blocking - you can run /specweave-github:sync manually)" >&2
+      echo "  💡 Check that sync.github.enabled=true in .specweave/config.json" >&2
+      echo ""
+    fi
+  else
+    echo "  ⚠️  consolidated-sync.js not found in any location - skipping GitHub sync" >&2
+    echo "  💡 To manually sync: /specweave-github:sync" >&2
+    echo ""
+  fi
+else
+  echo ""
+  echo "  ⚠️  Node.js not found - skipping GitHub sync" >&2
+  echo "  💡 Install Node.js to enable automatic GitHub sync" >&2
+  echo ""
+fi
+
 exit 0

package/plugins/specweave/hooks/post-metadata-change.sh

@@ -61,6 +61,24 @@ fi
 # Ensure logs directory exists
 mkdir -p "$LOGS_DIR" 2>/dev/null || true
 
+# ============================================================================
+# READ STDIN (v0.26.1 - CRITICAL FIX)
+# ============================================================================
+# PostToolUse hooks receive JSON data from Claude Code via STDIN, NOT env vars!
+# This was the critical bug: hook was looking for environment variables that don't exist.
+#
+# Example STDIN data:
+# {"tool": "Edit", "tool_input": {"file_path": "/path/to/file.md", ...}}
+# {"tool": "Write", "tool_input": {"file_path": "/path/to/file.md", ...}}
+
+STDIN_DATA=$(mktemp)
+cat > "$STDIN_DATA"
+
+echo "[$(date)] post-metadata-change: Hook fired" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "[$(date)] Input JSON:" >> "$DEBUG_LOG" 2>/dev/null || true
+cat "$STDIN_DATA" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "" >> "$DEBUG_LOG" 2>/dev/null || true
+
 # ============================================================================
 # EARLY EXIT OPTIMIZATION (v0.25.0): Ultra-Fast Rejection of Non-Metadata Changes
 # ============================================================================
@@ -68,37 +86,24 @@ mkdir -p "$LOGS_DIR" 2>/dev/null || true
 # 99.9% of Edit/Write operations are NOT metadata.json.
 # Do fastest possible check first to minimize overhead.
 
-# Quick check: If TOOL_USE_CONTENT doesn't contain "metadata.json", exit immediately
-if [[ -n "${TOOL_USE_CONTENT:-}" ]] && [[ "$TOOL_USE_CONTENT" != *"metadata.json"* ]]; then
+# Quick check: If STDIN doesn't contain "metadata.json", exit immediately
+if ! grep -q "metadata\.json" "$STDIN_DATA" 2>/dev/null; then
+  echo "[$(date)] post-metadata-change: Not metadata.json - exiting" >> "$DEBUG_LOG" 2>/dev/null || true
+  rm -f "$STDIN_DATA"
   exit 0  # Fast path: Not metadata.json
 fi
 
-# Quick check: If TOOL_USE_ARGS doesn't contain "metadata.json", exit immediately
-if [[ -n "${TOOL_USE_ARGS:-}" ]] && [[ "$TOOL_USE_ARGS" != *"metadata.json"* ]]; then
-  exit 0  # Fast path: Not metadata.json
-fi
+echo "[$(date)] post-metadata-change: metadata.json detected in input" >> "$DEBUG_LOG" 2>/dev/null || true
 
 # ============================================================================
-# STANDARD FILE DETECTION (Only if quick checks passed)
+# EXTRACT FILE PATH FROM STDIN JSON
 # ============================================================================
 
-# Extract modified file from environment variables (Claude Code provides this)
-MODIFIED_FILE=""
-
-# Method 1: TOOL_USE_CONTENT environment variable (primary for Write)
-if [[ -n "${TOOL_USE_CONTENT:-}" ]]; then
-  MODIFIED_FILE="$TOOL_USE_CONTENT"
-fi
-
-# Method 2: TOOL_RESULT environment variable (fallback)
-if [[ -z "$MODIFIED_FILE" ]] && [[ -n "${TOOL_RESULT:-}" ]]; then
-  MODIFIED_FILE=$(echo "$TOOL_RESULT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
-fi
+# Parse file_path from JSON (handles both Edit and Write tool formats)
+MODIFIED_FILE=$(grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' "$STDIN_DATA" | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
 
-# Method 3: Parse tool use arguments (last resort for Edit)
-if [[ -z "$MODIFIED_FILE" ]] && [[ -n "${TOOL_USE_ARGS:-}" ]]; then
-  MODIFIED_FILE=$(echo "$TOOL_USE_ARGS" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
-fi
+# Clean up temp file
+rm -f "$STDIN_DATA"
 
 echo "[$(date)] post-metadata-change: Detected file: ${MODIFIED_FILE:-<none>}" >> "$DEBUG_LOG" 2>/dev/null || true
 

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

@@ -455,6 +455,13 @@ fi
     # 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-write-consolidated.sh

@@ -3,17 +3,23 @@
 # Pre-Edit/Write Consolidated Hook: Capture File Path BEFORE Edit/Write Executes
 #
 # Purpose: Unified hook for both Edit and Write tools
-# Strategy: Detect file path, signal post-hook if it's a spec/tasks file
+# 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
 #
-# TIER 2 COORDINATION:
-# 1. Extract file_path from TOOL_USE_ARGS (reliable in PreToolUse)
-# 2. If it's spec.md/tasks.md in increments folder, signal PostToolUse hook
-# 3. Write file path to .pending-status-update for PostToolUse to consume
+# 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)
@@ -22,8 +28,8 @@
 #     ↓ read by
 #   PostToolUse:Edit/Write → post-edit-write-consolidated.sh
 #
-# Version: v0.25.0 (HOOK CONSOLIDATION)
-# Date: 2025-11-23
+# 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
@@ -34,6 +40,37 @@
 # 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"

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

package/plugins/specweave/lib/hooks/consolidated-sync.js

@@ -47,6 +47,9 @@ import { ACStatusManager } from '../vendor/core/increment/ac-status-manager.js';
 import { SyncCoordinator } from '../../../../dist/src/sync/sync-coordinator.js';
 import { consoleLogger } from '../vendor/utils/logger.js';
 
+// Import US completion orchestrator (NEW in v0.25.0+)
+import { syncCompletedUserStories } from './us-completion-orchestrator.js';
+
 // ============================================================================
 // WRAPPER: UPDATE AC STATUS
 // ============================================================================
@@ -172,7 +175,20 @@ async function runConsolidatedSync(incrementId) {
       results.translate = { success: false, error: error.message };
     }
 
-    // OPERATION 5: Sync to GitHub (NEW in v0.24.0+)
+    // OPERATION 5: Detect and sync newly completed user stories (NEW in v0.25.0+)
+    // CRITICAL: This operation runs AFTER AC sync to ensure ACs are up-to-date
+    // When a user story becomes fully complete (all ACs satisfied), this:
+    // - Detects the completion
+    // - Updates living docs
+    // - Triggers external tool sync (GitHub/JIRA/ADO)
+    try {
+      results.usCompletion = await syncCompletedUserStories(incrementId);
+    } catch (error) {
+      console.error('❌ Error detecting completed user stories:', error.message);
+      results.usCompletion = { success: false, error: error.message };
+    }
+
+    // OPERATION 6: Sync to GitHub (NEW in v0.24.0+)
     // FIX (v0.26.0): Skip GitHub sync in post-task-completion hook!
     // WHY: GitHub sync should ONLY run on increment COMPLETION, not task completion
     // This prevents 27 duplicate comments on every TodoWrite (see root cause analysis)
@@ -180,10 +196,11 @@ async function runConsolidatedSync(incrementId) {
     // GitHub sync is now ONLY triggered by:
     // - post-increment-completion.sh (when status → "completed")
     // - Manual sync via /specweave-github:sync command
+    // - US completion orchestrator (OPERATION 5) when user stories complete
     //
     // See: .specweave/increments/0051-*/reports/GITHUB-COMMENT-RECURSION-ROOT-CAUSE-2025-11-24.md
     if (process.env.SKIP_GITHUB_SYNC === 'true') {
-      console.log('\n⏭️  [5/5] GitHub sync SKIPPED (called from post-task-completion hook)');
+      console.log('\n⏭️  [6/6] GitHub sync SKIPPED (called from post-task-completion hook)');
       console.log('    GitHub sync will run automatically on increment completion.');
       results.syncGitHub = { success: true, skipped: true };
     } else {

package/plugins/specweave/lib/hooks/us-completion-orchestrator.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * User Story Completion Orchestrator
+ *
+ * Orchestrates the sync cascade when user stories become complete:
+ * 1. Detect newly completed user stories (all ACs satisfied)
+ * 2. Update living docs for completed USs
+ * 3. Trigger external tool sync (GitHub/JIRA/ADO)
+ *
+ * CRITICAL: This is the bridge between AC-level completion and US-level sync.
+ * Called by consolidated-sync.js after AC sync completes.
+ *
+ * Architecture:
+ * - Uses USCompletionDetector to find newly completed USs
+ * - Uses LivingDocsSync to update living docs (which triggers external tools)
+ * - Non-blocking: Errors logged but don't break workflow
+ *
+ * Integration:
+ * - Called from consolidated-sync.js (OPERATION 6)
+ * - Runs after AC sync (ensures ACs are up-to-date)
+ * - Skipped if SKIP_US_SYNC=true (performance optimization)
+ */
+
+// Import REAL implementations
+import { USCompletionDetector } from '../../../../dist/src/core/us-completion-detector.js';
+import { LivingDocsSync } from '../../../../dist/src/core/living-docs/living-docs-sync.js';
+import { consoleLogger } from '../vendor/utils/logger.js';
+
+/**
+ * Detect and sync newly completed user stories
+ *
+ * @param incrementId - Increment ID (e.g., "0053-safe-feature-deletion")
+ * @returns Result object with success status and sync details
+ */
+export async function syncCompletedUserStories(incrementId) {
+  try {
+    console.log(`\n🎯 [6/6] Detecting completed user stories for ${incrementId}...`);
+
+    const projectRoot = process.cwd();
+
+    // Skip if disabled (performance optimization)
+    if (process.env.SKIP_US_SYNC === 'true') {
+      console.log('ℹ️  User story sync skipped (SKIP_US_SYNC=true)');
+      return { success: true, message: 'Sync skipped', skipped: true };
+    }
+
+    // 1. Initialize US completion detector
+    const detector = new USCompletionDetector(projectRoot, {
+      logger: consoleLogger
+    });
+
+    // 2. Detect newly completed user stories
+    const newlyCompleted = await detector.getNewlyCompletedUSs(incrementId);
+
+    if (newlyCompleted.length === 0) {
+      console.log('✅ No newly completed user stories detected (no sync needed)');
+      return { success: true, newlyCompleted: [], message: 'No new completions' };
+    }
+
+    console.log(`\n🎉 DETECTED ${newlyCompleted.length} NEWLY COMPLETED USER STORIES:`);
+    for (const us of newlyCompleted) {
+      console.log(`   ${us.usId}: ${us.title} (${us.completedACs}/${us.totalACs} ACs complete)`);
+    }
+
+    // 3. Save completion state (mark USs as complete to prevent re-sync)
+    const allCompletions = await detector.detectCompletions(incrementId);
+    await detector.saveCompletionState(incrementId, allCompletions);
+
+    // 4. Trigger living docs sync (which will sync to external tools)
+    console.log(`\n📚 Syncing living docs for ${incrementId}...`);
+
+    const livingDocsSync = new LivingDocsSync(projectRoot, {
+      logger: consoleLogger
+    });
+
+    const syncResult = await livingDocsSync.syncIncrement(incrementId);
+
+    if (syncResult.success) {
+      console.log(`✅ Living docs synced successfully`);
+      console.log(`   Feature: ${syncResult.featureId}`);
+      console.log(`   Files updated: ${syncResult.filesCreated.length + syncResult.filesUpdated.length}`);
+
+      // External tool sync happens automatically inside livingDocsSync.syncIncrement()
+      // It calls syncToExternalTools() which handles GitHub/JIRA/ADO
+      console.log(`\n📡 External tool sync completed (GitHub/JIRA/ADO updated if configured)`);
+    } else {
+      console.warn(`⚠️  Living docs sync had errors (see logs)`);
+      console.warn(`   Errors: ${syncResult.errors.join(', ')}`);
+    }
+
+    return {
+      success: true,
+      newlyCompleted: newlyCompleted.map(us => ({
+        usId: us.usId,
+        title: us.title,
+        totalACs: us.totalACs,
+        completedACs: us.completedACs
+      })),
+      syncResult,
+      message: `${newlyCompleted.length} user stories synced`
+    };
+
+  } catch (error) {
+    // Non-blocking: Log error but don't break workflow
+    console.error('❌ Error in US completion orchestrator:', error.message);
+    return { success: false, error: error.message };
+  }
+}
+
+// CLI Interface (for manual testing)
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  const incrementId = process.argv[2];
+
+  if (!incrementId) {
+    console.error('Usage: node us-completion-orchestrator.js <increment-id>');
+    console.error('Example: node us-completion-orchestrator.js 0053-safe-feature-deletion');
+    process.exit(1);
+  }
+
+  syncCompletedUserStories(incrementId)
+    .then(result => {
+      if (result.success) {
+        console.log('\n✅ US completion orchestration completed successfully');
+        process.exit(0);
+      } else {
+        console.error('\n❌ US completion orchestration failed');
+        process.exit(1);
+      }
+    })
+    .catch(error => {
+      console.error('\n❌ Fatal error:', error);
+      process.exit(1);
+    });
+}