specweave 1.0.29 → 1.0.31

package/plugins/specweave/hooks/universal/fail-fast-wrapper.sh

@@ -1,37 +1,70 @@
 #!/bin/bash
-# fail-fast-wrapper.sh - HARD TIMEOUT wrapper for all hooks
+# fail-fast-wrapper.sh - HARD TIMEOUT wrapper for all hooks with proper concurrency control
 # If ANY hook takes longer than HOOK_TIMEOUT, it gets KILLED.
 #
 # Usage: bash fail-fast-wrapper.sh <hook-script> [args...]
 #
 # Environment:
-#   HOOK_TIMEOUT - max seconds (default: 5)
-#   HOOK_DEBUG   - set to 1 for verbose logging
+#   HOOK_TIMEOUT        - max seconds (default: 5)
+#   HOOK_DEBUG          - set to 1 for verbose logging
+#   HOOK_MAX_CONCURRENT - max concurrent hooks (default: 15)
+#   HOOK_ACQUIRE_TIMEOUT_MS - semaphore acquire timeout (default: 3000)
 #
 # Exit behavior:
 #   - Returns hook output on success
 #   - Returns safe JSON on timeout ({"continue":true} or {"decision":"approve"})
 #   - NEVER hangs - timeout is enforced with SIGKILL
 #
-# CRASH PREVENTION:
-#   - Integrates with crash-prevention.sh for process storm detection
-#   - Auto-kills zombie processes on timeout
-#   - Records failures for circuit breaker
+# CONCURRENCY CONTROL (v1.0.30):
+#   - Semaphore-based concurrency limiting (NOT process storm detection)
+#   - Proper circuit breaker with CLOSED/OPEN/HALF_OPEN states
+#   - Structured logging with request tracing
+#   - Metrics collection for observability
 #
 # v0.33.0 - Enhanced with crash prevention integration
+# v1.0.30 - Complete rewrite with proper concurrency primitives
 
 set -o pipefail
 
 # === Configuration ===
 HOOK_TIMEOUT="${HOOK_TIMEOUT:-5}"  # 5 seconds - more than enough for any hook
 HOOK_DEBUG="${HOOK_DEBUG:-0}"
+HOOK_MAX_CONCURRENT="${HOOK_MAX_CONCURRENT:-15}"  # Max concurrent hooks
+HOOK_ACQUIRE_TIMEOUT_MS="${HOOK_ACQUIRE_TIMEOUT_MS:-3000}"  # 3 seconds to acquire semaphore
 LOG_FILE="${HOME}/.claude/hook-failures.log"
 
-# === Crash Prevention Integration ===
+# === Library paths ===
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-CRASH_PREVENTION="${SCRIPT_DIR}/../lib/crash-prevention.sh"
+LIB_DIR="${SCRIPT_DIR}/../lib"
 
-# Source crash prevention if available (non-blocking)
+# === Source libraries (fail gracefully if missing) ===
+SEMAPHORE_LOADED=false
+CIRCUIT_BREAKER_LOADED=false
+LOGGING_LOADED=false
+METRICS_LOADED=false
+
+# Set state dir for all libraries
+export SPECWEAVE_STATE_DIR="${SPECWEAVE_STATE_DIR:-.specweave/state}"
+export SPECWEAVE_LOG_DIR="${SPECWEAVE_LOG_DIR:-.specweave/logs/hooks}"
+
+if [[ -f "$LIB_DIR/semaphore.sh" ]]; then
+  source "$LIB_DIR/semaphore.sh" 2>/dev/null && SEMAPHORE_LOADED=true
+fi
+
+if [[ -f "$LIB_DIR/circuit-breaker.sh" ]]; then
+  source "$LIB_DIR/circuit-breaker.sh" 2>/dev/null && CIRCUIT_BREAKER_LOADED=true
+fi
+
+if [[ -f "$LIB_DIR/logging.sh" ]]; then
+  source "$LIB_DIR/logging.sh" 2>/dev/null && LOGGING_LOADED=true
+fi
+
+if [[ -f "$LIB_DIR/metrics.sh" ]]; then
+  source "$LIB_DIR/metrics.sh" 2>/dev/null && METRICS_LOADED=true
+fi
+
+# Legacy crash prevention (fallback)
+CRASH_PREVENTION="${LIB_DIR}/crash-prevention.sh"
 if [[ -f "$CRASH_PREVENTION" ]]; then
   source "$CRASH_PREVENTION" 2>/dev/null || true
 fi
@@ -44,7 +77,7 @@ log_debug() {
 log_failure() {
   local msg="$1"
   mkdir -p "$(dirname "$LOG_FILE")"
-  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] HOOK TIMEOUT: $msg" >> "$LOG_FILE"
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] HOOK FAILURE: $msg" >> "$LOG_FILE"
 }
 
 # === Safe JSON output based on hook type ===
@@ -58,6 +91,12 @@ get_safe_output() {
   fi
 }
 
+# === Get hook name from script path ===
+get_hook_name() {
+  local script="$1"
+  basename "$script" .sh | tr '/' '-'
+}
+
 # === Read stdin with timeout ===
 # Critical: stdin can block forever if not handled properly
 read_stdin_with_timeout() {
@@ -92,18 +131,68 @@ main() {
     exit 0
   fi
 
-  # === CRASH PREVENTION: Process Storm Detection ===
-  # If too many hooks are running, skip this one to prevent cascade
-  if type detect_process_storm &>/dev/null; then
-    local storm_status
-    storm_status=$(detect_process_storm 25)
-    if [[ "$storm_status" == STORM* ]]; then
-      log_failure "$script - BLOCKED due to process storm: $storm_status"
+  local hook_name
+  hook_name=$(get_hook_name "$script")
+
+  # === Initialize libraries ===
+  if [[ "$LOGGING_LOADED" == "true" ]]; then
+    log_init "$hook_name"
+    log_debug "Starting hook execution" "script=$script"
+  fi
+
+  if [[ "$METRICS_LOADED" == "true" ]]; then
+    metrics_init "$hook_name"
+    metrics_start_request
+  fi
+
+  # === CIRCUIT BREAKER CHECK ===
+  # If circuit is open for this hook, fail fast
+  if [[ "$CIRCUIT_BREAKER_LOADED" == "true" ]]; then
+    if ! cb_allow_request "$hook_name"; then
+      local cb_status
+      cb_status=$(cb_get_status "$hook_name")
+      log_debug "Circuit breaker OPEN for $hook_name: $cb_status"
+
+      if [[ "$LOGGING_LOADED" == "true" ]]; then
+        log_warn "Circuit breaker open - failing fast" "hook=$hook_name"
+      fi
+
+      if [[ "$METRICS_LOADED" == "true" ]]; then
+        metrics_end_request "skipped"
+      fi
+
+      get_safe_output "$script"
+      exit 0
+    fi
+  fi
+
+  # === SEMAPHORE: Acquire concurrency slot ===
+  local semaphore_acquired=false
+  if [[ "$SEMAPHORE_LOADED" == "true" ]]; then
+    if acquire_semaphore "hooks" "$HOOK_MAX_CONCURRENT" "$HOOK_ACQUIRE_TIMEOUT_MS"; then
+      semaphore_acquired=true
+      log_debug "Acquired semaphore slot for $hook_name"
+    else
+      # Could not acquire semaphore in time - graceful degradation
+      log_debug "Semaphore timeout for $hook_name - graceful skip"
+
+      if [[ "$LOGGING_LOADED" == "true" ]]; then
+        log_warn "Semaphore acquisition timeout - graceful degradation" "hook=$hook_name" "max_concurrent=$HOOK_MAX_CONCURRENT"
+      fi
+
+      if [[ "$METRICS_LOADED" == "true" ]]; then
+        metrics_end_request "skipped"
+      fi
+
+      # DON'T record as failure - this is graceful degradation, not an error
       get_safe_output "$script"
       exit 0
     fi
   fi
 
+  # Ensure semaphore is released on exit
+  trap 'release_semaphore 2>/dev/null || true' EXIT INT TERM
+
   log_debug "Executing: $script (timeout: ${HOOK_TIMEOUT}s)"
 
   # Read stdin first (with its own timeout)
@@ -111,11 +200,8 @@ main() {
   stdin_content=$(read_stdin_with_timeout)
 
   # Execute the hook with hard timeout
-  # Using timeout with --kill-after to ensure SIGKILL if SIGTERM doesn't work
   local output
   local exit_code
-
-  # Create temp file for output (avoid subshell issues)
   local tmp_out
   tmp_out=$(mktemp)
 
@@ -156,12 +242,30 @@ main() {
   output=$(cat "$tmp_out" 2>/dev/null)
   rm -f "$tmp_out"
 
+  # Release semaphore immediately after execution
+  if [[ "$semaphore_acquired" == "true" ]]; then
+    release_semaphore
+  fi
+
   # Handle timeout (exit code 124 or 137)
   if [[ $exit_code -eq 124 ]] || [[ $exit_code -eq 137 ]]; then
     log_failure "$script - killed after ${HOOK_TIMEOUT}s"
     log_debug "TIMEOUT: $script killed after ${HOOK_TIMEOUT}s"
 
-    # === CRASH PREVENTION: Clean up potential zombie processes ===
+    if [[ "$LOGGING_LOADED" == "true" ]]; then
+      log_error "Hook timeout - killed after ${HOOK_TIMEOUT}s" "hook=$hook_name"
+    fi
+
+    if [[ "$METRICS_LOADED" == "true" ]]; then
+      metrics_end_request "timeout"
+    fi
+
+    # Record failure for circuit breaker
+    if [[ "$CIRCUIT_BREAKER_LOADED" == "true" ]]; then
+      cb_record_failure "$hook_name"
+    fi
+
+    # Clean up potential zombie processes (legacy)
     if type kill_zombie_heredocs &>/dev/null; then
       kill_zombie_heredocs 2>/dev/null || true
     fi
@@ -170,6 +274,36 @@ main() {
     exit 0
   fi
 
+  # Handle hook errors (non-zero exit, excluding block exit code 2)
+  if [[ $exit_code -ne 0 ]] && [[ $exit_code -ne 2 ]]; then
+    log_debug "Hook error: $script exited with $exit_code"
+
+    if [[ "$LOGGING_LOADED" == "true" ]]; then
+      log_warn "Hook exited with error" "hook=$hook_name" "exit_code=$exit_code"
+    fi
+
+    if [[ "$METRICS_LOADED" == "true" ]]; then
+      metrics_end_request "failure"
+    fi
+
+    if [[ "$CIRCUIT_BREAKER_LOADED" == "true" ]]; then
+      cb_record_failure "$hook_name"
+    fi
+  else
+    # Success!
+    if [[ "$METRICS_LOADED" == "true" ]]; then
+      metrics_end_request "success"
+    fi
+
+    if [[ "$CIRCUIT_BREAKER_LOADED" == "true" ]]; then
+      cb_record_success "$hook_name"
+    fi
+
+    if [[ "$LOGGING_LOADED" == "true" ]]; then
+      log_debug "Hook completed successfully" "hook=$hook_name"
+    fi
+  fi
+
   # Return output or safe default
   if [[ -n "$output" ]]; then
     echo "$output"

package/plugins/specweave/hooks/v2/handlers/project-bridge-handler.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# project-bridge-handler.sh - Bridge increment events to project-level EDA
+#
+# This handler connects the increment-level EDA (hooks v2) to the
+# project-level EDA (ProjectRegistry + Adapters).
+#
+# Events bridged:
+# - increment.created -> May create project labels in GitHub
+# - increment.done -> Triggers project sync to all external tools
+# - increment.archived -> Updates project sync status
+# - increment.reopened -> Triggers project sync
+#
+# Architecture:
+# [Increment Event] -> [This Handler] -> [project-bridge.js] -> [ProjectService]
+#                                                                      |
+#                                                                      v
+#                                                          [ProjectEventBus]
+#                                                                      |
+#                                    +----------------+----------------+
+#                                    v                v                v
+#                              [GitHub]          [ADO]           [JIRA]
+#                              Adapter           Adapter         Adapter
+#
+# IMPORTANT: Never crash Claude, always exit 0
+set +e
+
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
+EVENT_TYPE="${1:-}"
+EVENT_DATA="${2:-}"
+
+[[ -z "$EVENT_TYPE" ]] && exit 0
+[[ -z "$EVENT_DATA" ]] && exit 0
+
+# Find project root
+PROJECT_ROOT="$PWD"
+while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.specweave" ]]; do
+  PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
+done
+[[ ! -d "$PROJECT_ROOT/.specweave" ]] && exit 0
+
+# Throttle: max once per 2 minutes per increment for project sync
+# (More aggressive throttle since this triggers external API calls)
+INC_ID="${EVENT_DATA%%:*}"  # Extract increment ID from INC_ID:US_ID format
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+THROTTLE_FILE="$STATE_DIR/.project-bridge-$INC_ID"
+THROTTLE_WINDOW=120  # 2 minutes
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+if [[ -f "$THROTTLE_FILE" ]]; then
+  if [[ "$(uname)" == "Darwin" ]]; then
+    AGE=$(($(date +%s) - $(stat -f %m "$THROTTLE_FILE" 2>/dev/null || echo 0)))
+  else
+    AGE=$(($(date +%s) - $(stat -c %Y "$THROTTLE_FILE" 2>/dev/null || echo 0)))
+  fi
+  [[ $AGE -lt $THROTTLE_WINDOW ]] && exit 0
+fi
+touch "$THROTTLE_FILE"
+
+# Log event
+LOG_FILE="$PROJECT_ROOT/.specweave/logs/hooks.log"
+mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] project-bridge-handler: $EVENT_TYPE $EVENT_DATA" >> "$LOG_FILE" 2>/dev/null
+
+# Find the bridge script
+BRIDGE_SCRIPT=""
+for path in \
+  "$PROJECT_ROOT/dist/plugins/specweave/lib/hooks/project-bridge.js" \
+  "$PROJECT_ROOT/plugins/specweave/lib/hooks/project-bridge.js" \
+  "${CLAUDE_PLUGIN_ROOT:-}/lib/hooks/project-bridge.js"; do
+  [[ -f "$path" ]] && { BRIDGE_SCRIPT="$path"; break; }
+done
+
+# Cross-platform timeout wrapper
+run_with_timeout() {
+  local timeout_secs="$1"
+  shift
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$timeout_secs" "$@" 2>/dev/null || true
+  elif command -v gtimeout >/dev/null 2>&1; then
+    gtimeout "$timeout_secs" "$@" 2>/dev/null || true
+  else
+    "$@" 2>/dev/null || true
+  fi
+}
+
+# Run bridge script if available
+if [[ -n "$BRIDGE_SCRIPT" ]]; then
+  cd "$PROJECT_ROOT" || exit 0
+  # Run with 60s timeout (external API calls can be slow)
+  run_with_timeout 60 node "$BRIDGE_SCRIPT" "$EVENT_TYPE" "$EVENT_DATA" >> "$LOG_FILE" 2>&1 &
+else
+  echo "[$(date '+%Y-%m-%d %H:%M:%S')] project-bridge-handler: No bridge script found, skipping" >> "$LOG_FILE" 2>/dev/null
+fi
+
+exit 0

package/plugins/specweave/hooks/v2/queue/processor.sh

@@ -4,10 +4,14 @@
 #
 # Usage: processor.sh [--daemon]
 #
-# Event routing:
-# - increment.created/done/archived/reopened -> living-specs-handler
-# - user-story.completed/reopened -> status-line-handler
+# Event routing (EDA v2):
+# - increment.created/done/archived/reopened -> living-specs-handler + status-line-handler + project-bridge-handler
+# - user-story.completed/reopened -> status-line-handler + project-bridge-handler
 # - task.updated/spec.updated -> living-docs-handler (legacy)
+# - metadata.changed -> github-sync-handler
+#
+# The project-bridge-handler connects increment events to project-level EDA,
+# enabling automatic sync to GitHub, ADO, and JIRA via ProjectService.
 #
 # Self-terminates after 60s of idle
 #
@@ -148,16 +152,20 @@ process_event() {
     # EDA Event Routing (new architecture)
     # ========================================
 
-    # Lifecycle events -> living-specs-handler
+    # Lifecycle events -> living-specs-handler + status-line-handler + project-bridge-handler
     increment.created|increment.done|increment.archived|increment.reopened)
       run_handler "$HANDLER_DIR/living-specs-handler.sh" "$EVENT_TYPE" "$EVENT_DATA"
       # Also update status line on lifecycle changes
       run_handler "$HANDLER_DIR/status-line-handler.sh" "$EVENT_TYPE" "$EVENT_DATA"
+      # Bridge to project-level EDA (triggers sync to GitHub/ADO/JIRA)
+      run_handler "$HANDLER_DIR/project-bridge-handler.sh" "$EVENT_TYPE" "$EVENT_DATA"
       ;;
 
-    # User story events -> status-line-handler
+    # User story events -> status-line-handler + project-bridge-handler
     user-story.completed|user-story.reopened)
       run_handler "$HANDLER_DIR/status-line-handler.sh" "$EVENT_TYPE" "$EVENT_DATA"
+      # Bridge to project-level EDA (may trigger issue updates)
+      run_handler "$HANDLER_DIR/project-bridge-handler.sh" "$EVENT_TYPE" "$EVENT_DATA"
       ;;
 
     # ========================================

package/plugins/specweave/lib/hooks/project-bridge.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * project-bridge.js - Bridge increment events to project-level EDA
+ *
+ * Called by project-bridge-handler.sh to connect increment-level
+ * events to the ProjectService and trigger project sync.
+ *
+ * Usage: node project-bridge.js <event-type> <event-data>
+ *
+ * Event types:
+ * - increment.created - New increment created
+ * - increment.done - Increment completed
+ * - increment.archived - Increment archived
+ * - increment.reopened - Increment reopened
+ * - user-story.completed - User story completed
+ * - user-story.reopened - User story reopened
+ */
+
+import { ProjectService } from '../../../../dist/src/core/project/project-service.js';
+import { consoleLogger } from '../vendor/utils/logger.js';
+
+/**
+ * Bridge increment event to project-level EDA
+ */
+async function bridgeIncrementEvent(eventType, eventData) {
+  try {
+    console.log(`[project-bridge] Processing: ${eventType} ${eventData}`);
+
+    const projectRoot = process.cwd();
+    const service = ProjectService.getInstance(projectRoot, consoleLogger);
+
+    // Initialize adapters (no-op if already initialized)
+    await service.initialize();
+
+    // Emit the increment event to project-level EDA
+    await service.emitIncrementEvent(eventType, eventData);
+
+    console.log(`[project-bridge] Successfully bridged: ${eventType}`);
+    return { success: true };
+  } catch (error) {
+    console.error(`[project-bridge] Error: ${error.message}`);
+    return { success: false, error: error.message };
+  }
+}
+
+// Main entry point
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+
+if (isMainModule) {
+  const eventType = process.argv[2];
+  const eventData = process.argv[3];
+
+  if (!eventType || !eventData) {
+    console.error('Usage: node project-bridge.js <event-type> <event-data>');
+    console.error('Example: node project-bridge.js increment.done 0145-project-registry');
+    process.exit(1);
+  }
+
+  bridgeIncrementEvent(eventType, eventData)
+    .then((result) => {
+      if (result.success) {
+        process.exit(0);
+      } else {
+        // Non-blocking error - don't fail the hook
+        console.error(`[project-bridge] Bridge failed: ${result.error}`);
+        process.exit(0);
+      }
+    })
+    .catch((error) => {
+      console.error('[project-bridge] Fatal error:', error);
+      // Non-blocking - don't fail the hook
+      process.exit(0);
+    });
+}
+
+export { bridgeIncrementEvent };

package/plugins/specweave/lib/vendor/core/increment/metadata-manager.d.ts

@@ -4,7 +4,7 @@
  * Handles CRUD operations for increment metadata (status, type, timestamps).
  * Part of increment 0007: Smart Status Management
  */
-import { IncrementMetadata, IncrementMetadataExtended, IncrementStatus, IncrementType } from '../types/increment-metadata.js';
+import { IncrementMetadata, IncrementMetadataExtended, IncrementMetadataV2, IncrementStatus, IncrementType, SyncTarget } from '../types/increment-metadata.js';
 import { Logger } from '../../utils/logger.js';
 /**
  * Error thrown when metadata operations fail
@@ -163,5 +163,71 @@ export declare class MetadataManager {
      * Get human-readable status transition error message
      */
     static getTransitionError(from: IncrementStatus, to: IncrementStatus): string;
+    /**
+     * Set the external tool sync target for an increment
+     *
+     * This explicitly specifies which sync profile the increment uses.
+     * The sync target provides audit trail and deterministic sync behavior.
+     *
+     * @param incrementId - Increment ID
+     * @param syncTarget - Sync target configuration
+     * @param rootDir - Optional root directory
+     * @returns Updated metadata
+     *
+     * @example
+     * ```typescript
+     * MetadataManager.setSyncTarget('0142-feature', {
+     *   profileId: 'github-frontend',
+     *   provider: 'github',
+     *   derivedFrom: 'project-mapping',
+     *   setAt: new Date().toISOString(),
+     *   sourceProjectId: 'frontend-app'
+     * });
+     * ```
+     */
+    static setSyncTarget(incrementId: string, syncTarget: SyncTarget, rootDir?: string): IncrementMetadataV2;
+    /**
+     * Get the sync target for an increment
+     *
+     * @param incrementId - Increment ID
+     * @param rootDir - Optional root directory
+     * @returns Sync target or undefined if not set
+     */
+    static getSyncTarget(incrementId: string, rootDir?: string): SyncTarget | undefined;
+    /**
+     * Clear the sync target for an increment
+     *
+     * Use this when the external tool configuration changes and
+     * the increment needs to be re-resolved.
+     *
+     * @param incrementId - Increment ID
+     * @param rootDir - Optional root directory
+     * @returns Updated metadata
+     */
+    static clearSyncTarget(incrementId: string, rootDir?: string): IncrementMetadataV2;
+    /**
+     * Check if increment has a sync target configured
+     *
+     * @param incrementId - Increment ID
+     * @param rootDir - Optional root directory
+     * @returns true if sync target is set
+     */
+    static hasSyncTarget(incrementId: string, rootDir?: string): boolean;
+    /**
+     * Get all increments with a specific sync provider
+     *
+     * Useful for bulk operations on all GitHub/JIRA/ADO synced increments.
+     *
+     * @param provider - Provider type ('github', 'jira', 'ado')
+     * @returns Array of increments with that provider configured
+     */
+    static getByProvider(provider: 'github' | 'jira' | 'ado'): IncrementMetadataV2[];
+    /**
+     * Get all increments with a specific sync profile
+     *
+     * @param profileId - Profile ID from config.sync.profiles
+     * @returns Array of increments using that profile
+     */
+    static getByProfile(profileId: string): IncrementMetadataV2[];
 }
 //# sourceMappingURL=metadata-manager.d.ts.map

package/plugins/specweave/lib/vendor/core/increment/metadata-manager.js

@@ -619,6 +619,99 @@ export class MetadataManager {
         }
         return `Invalid transition: ${from} → ${to}`;
     }
+    // ==========================================================================
+    // Sync Target Methods (v1.0.31+ - ADR-0211)
+    // ==========================================================================
+    /**
+     * Set the external tool sync target for an increment
+     *
+     * This explicitly specifies which sync profile the increment uses.
+     * The sync target provides audit trail and deterministic sync behavior.
+     *
+     * @param incrementId - Increment ID
+     * @param syncTarget - Sync target configuration
+     * @param rootDir - Optional root directory
+     * @returns Updated metadata
+     *
+     * @example
+     * ```typescript
+     * MetadataManager.setSyncTarget('0142-feature', {
+     *   profileId: 'github-frontend',
+     *   provider: 'github',
+     *   derivedFrom: 'project-mapping',
+     *   setAt: new Date().toISOString(),
+     *   sourceProjectId: 'frontend-app'
+     * });
+     * ```
+     */
+    static setSyncTarget(incrementId, syncTarget, rootDir) {
+        const metadata = this.read(incrementId, rootDir);
+        metadata.syncTarget = syncTarget;
+        metadata.lastActivity = new Date().toISOString();
+        this.write(incrementId, metadata, rootDir);
+        this.logger.debug(`Set sync target for ${incrementId}: ${syncTarget.profileId} (${syncTarget.provider})`);
+        return metadata;
+    }
+    /**
+     * Get the sync target for an increment
+     *
+     * @param incrementId - Increment ID
+     * @param rootDir - Optional root directory
+     * @returns Sync target or undefined if not set
+     */
+    static getSyncTarget(incrementId, rootDir) {
+        const metadata = this.read(incrementId, rootDir);
+        return metadata.syncTarget;
+    }
+    /**
+     * Clear the sync target for an increment
+     *
+     * Use this when the external tool configuration changes and
+     * the increment needs to be re-resolved.
+     *
+     * @param incrementId - Increment ID
+     * @param rootDir - Optional root directory
+     * @returns Updated metadata
+     */
+    static clearSyncTarget(incrementId, rootDir) {
+        const metadata = this.read(incrementId, rootDir);
+        delete metadata.syncTarget;
+        metadata.lastActivity = new Date().toISOString();
+        this.write(incrementId, metadata, rootDir);
+        this.logger.debug(`Cleared sync target for ${incrementId}`);
+        return metadata;
+    }
+    /**
+     * Check if increment has a sync target configured
+     *
+     * @param incrementId - Increment ID
+     * @param rootDir - Optional root directory
+     * @returns true if sync target is set
+     */
+    static hasSyncTarget(incrementId, rootDir) {
+        const metadata = this.read(incrementId, rootDir);
+        return !!metadata.syncTarget;
+    }
+    /**
+     * Get all increments with a specific sync provider
+     *
+     * Useful for bulk operations on all GitHub/JIRA/ADO synced increments.
+     *
+     * @param provider - Provider type ('github', 'jira', 'ado')
+     * @returns Array of increments with that provider configured
+     */
+    static getByProvider(provider) {
+        return this.getAll().filter(m => m.syncTarget?.provider === provider);
+    }
+    /**
+     * Get all increments with a specific sync profile
+     *
+     * @param profileId - Profile ID from config.sync.profiles
+     * @returns Array of increments using that profile
+     */
+    static getByProfile(profileId) {
+        return this.getAll().filter(m => m.syncTarget?.profileId === profileId);
+    }
 }
 /**
  * Logger instance (injectable for testing)