specweave 0.24.9 → 0.24.13

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

@@ -22,12 +22,7 @@
 # EMERGENCY FIX v0.24.3: Remove set -e - it causes Claude Code crashes!
 set +e
 
-# EMERGENCY KILL SWITCH
-if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
-  exit 0
-fi
-
-# Find project root
+# Find project root (must be BEFORE recursion guard to get PROJECT_ROOT)
 find_project_root() {
   local dir="$PWD"
   while [[ "$dir" != "/" ]]; do
@@ -45,9 +40,48 @@ LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
 DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
 HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
+# ============================================================================
+# RECURSION PREVENTION (CRITICAL - v0.26.0 - FILE-BASED GUARD)
+# ============================================================================
+# NEW SOLUTION (v0.26.0): File-based recursion guard
+# 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
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
+
 # Ensure logs directory exists
 mkdir -p "$LOGS_DIR" 2>/dev/null || true
 
+# ============================================================================
+# EARLY EXIT OPTIMIZATION (v0.25.0): Ultra-Fast Rejection of Non-Metadata Changes
+# ============================================================================
+# This hook should ONLY run for metadata.json changes.
+# 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
+  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
+
+# ============================================================================
+# STANDARD FILE DETECTION (Only if quick checks passed)
+# ============================================================================
+
 # Extract modified file from environment variables (Claude Code provides this)
 MODIFIED_FILE=""
 

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,21 @@ 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
+
     # 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,188 @@
+#!/bin/bash
+#
+# 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
+#
+# 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
+#
+# 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.25.0 (HOOK CONSOLIDATION)
+# Date: 2025-11-23
+#
+# 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
+
+# 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/lib/hooks/consolidated-sync.js

@@ -42,6 +42,11 @@ import { translateLivingDocs } from './translate-living-docs.js';
 // Import for AC status (uses ACStatusManager directly)
 import { ACStatusManager } from '../vendor/core/increment/ac-status-manager.js';
 
+// Import for GitHub sync (uses SyncCoordinator directly)
+// NOTE: Import from project root dist (not relative path)
+import { SyncCoordinator } from '../../../../dist/src/sync/sync-coordinator.js';
+import { consoleLogger } from '../vendor/utils/logger.js';
+
 // ============================================================================
 // WRAPPER: UPDATE AC STATUS
 // ============================================================================
@@ -87,6 +92,36 @@ async function updateACStatus(incrementId) {
   }
 }
 
+// ============================================================================
+// WRAPPER: GITHUB SYNC
+// ============================================================================
+async function syncGitHub(incrementId) {
+  try {
+    console.log(`\n🔗 [5/5] Syncing to GitHub...`);
+
+    const projectRoot = process.cwd();
+
+    const coordinator = new SyncCoordinator({
+      projectRoot,
+      incrementId,
+      logger: consoleLogger
+    });
+
+    const result = await coordinator.syncIncrementCompletion();
+
+    if (result.success) {
+      console.log(`✅ GitHub sync completed (${result.userStoriesSynced} user stories synced)`);
+    } else {
+      console.warn(`⚠️  GitHub sync had errors (see logs)`);
+    }
+
+    return { success: result.success, result };
+  } catch (error) {
+    console.error('❌ Error syncing to GitHub:', error.message);
+    return { success: false, error: error.message };
+  }
+}
+
 // ============================================================================
 // MAIN EXECUTION
 // ============================================================================
@@ -100,7 +135,7 @@ async function runConsolidatedSync(incrementId) {
 
   try {
     // OPERATION 1: Update tasks.md (uses imported function)
-    console.log('\n🔄 [1/4] Updating tasks.md...');
+    console.log('\n🔄 [1/5] Updating tasks.md...');
     try {
       await updateTasksMd(incrementId);
       results.updateTasks = { success: true };
@@ -110,7 +145,7 @@ async function runConsolidatedSync(incrementId) {
     }
 
     // OPERATION 2: Sync living docs (uses imported function)
-    console.log('\n📚 [2/4] Syncing living docs...');
+    console.log('\n📚 [2/5] Syncing living docs...');
     try {
       await syncLivingDocs(incrementId);
       results.syncDocs = { success: true };
@@ -128,7 +163,7 @@ async function runConsolidatedSync(incrementId) {
     }
 
     // OPERATION 4: Translate living docs (uses imported function)
-    console.log('\n🌐 [4/4] Checking translation needs...');
+    console.log('\n🌐 [4/5] Checking translation needs...');
     try {
       await translateLivingDocs(incrementId);
       results.translate = { success: true };
@@ -137,6 +172,29 @@ async function runConsolidatedSync(incrementId) {
       results.translate = { success: false, error: error.message };
     }
 
+    // OPERATION 5: 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)
+    //
+    // GitHub sync is now ONLY triggered by:
+    // - post-increment-completion.sh (when status → "completed")
+    // - Manual sync via /specweave-github:sync command
+    //
+    // 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('    GitHub sync will run automatically on increment completion.');
+      results.syncGitHub = { success: true, skipped: true };
+    } else {
+      try {
+        results.syncGitHub = await syncGitHub(incrementId);
+      } catch (error) {
+        console.error('❌ Error syncing to GitHub:', error.message);
+        results.syncGitHub = { success: false, error: error.message };
+      }
+    }
+
     const duration = Date.now() - startTime;
 
     console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');