specweave 0.24.11 → 0.24.13

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━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');