specweave 0.26.2 → 0.26.4

package/dist/src/utils/external-tool-drift-detector.js

@@ -0,0 +1,235 @@
+/**
+ * External Tool Drift Detector
+ *
+ * Detects when external tools (GitHub/JIRA/ADO) haven't been synced recently,
+ * indicating potential drift between living docs and external systems.
+ *
+ * Used by:
+ * - /specweave:done (validation warning if drift > 24h)
+ * - Status line (show "sync pending" indicator)
+ * - /specweave:progress (show last sync time)
+ *
+ * See: ADR-0131 (External Tool Sync Context Detection)
+ */
+import * as path from 'path';
+import { promises as fs } from 'fs';
+import { consoleLogger } from './logger.js';
+// Drift thresholds (extracted constants for P0-5 fix)
+const DRIFT_THRESHOLD_HOURS = 24; // Warning threshold
+const WARNING_THRESHOLD_HOURS = 48; // Elevated warning
+const CRITICAL_THRESHOLD_HOURS = 168; // 7 days - critical staleness
+export class ExternalToolDriftDetector {
+    constructor(projectRoot, options = {}) {
+        this.projectRoot = projectRoot;
+        this.logger = options.logger ?? consoleLogger;
+    }
+    /**
+     * Validate increment ID format to prevent path traversal attacks
+     * P0-1: Path traversal vulnerability fix
+     *
+     * @param incrementId - Increment ID to validate
+     * @throws Error if increment ID format is invalid
+     */
+    validateIncrementId(incrementId) {
+        // Expected format: 4 digits + hyphen + kebab-case (e.g., "0053-safe-feature-deletion")
+        if (!/^\d{4}-[a-z0-9-]+$/.test(incrementId)) {
+            throw new Error(`Invalid increment ID format: ${incrementId}. Expected format: XXXX-kebab-case`);
+        }
+        // Additional safety: reject path traversal attempts
+        if (incrementId.includes('..') || incrementId.includes('/') || incrementId.includes('\\')) {
+            throw new Error(`Path traversal attempt detected in increment ID: ${incrementId}`);
+        }
+    }
+    /**
+     * Safely parse and validate metadata.json
+     * P0-2: JSON injection protection
+     *
+     * @param metadataPath - Path to metadata.json
+     * @returns Parsed metadata object
+     * @throws Error if JSON is invalid or malformed
+     */
+    async readAndValidateMetadata(metadataPath) {
+        const content = await fs.readFile(metadataPath, 'utf-8');
+        let metadata;
+        try {
+            metadata = JSON.parse(content);
+        }
+        catch (error) {
+            throw new Error(`Invalid JSON in metadata file: ${error instanceof Error ? error.message : 'Parse error'}`);
+        }
+        // Validate JSON structure
+        if (typeof metadata !== 'object' || metadata === null) {
+            throw new Error('Metadata must be a valid JSON object');
+        }
+        return metadata;
+    }
+    /**
+     * Get most recent sync time across ALL external tools
+     * P1-1: Check all tools instead of just first configured tool
+     *
+     * @param metadata - Parsed metadata.json
+     * @returns Most recent sync date or null if no syncs found
+     */
+    getMostRecentSync(metadata) {
+        const syncTimes = [];
+        // Collect all sync times from configured external tools
+        if (metadata.github?.lastSync) {
+            const date = this.parseSafeDate(metadata.github.lastSync);
+            if (date)
+                syncTimes.push(date);
+        }
+        if (metadata.jira?.lastSync) {
+            const date = this.parseSafeDate(metadata.jira.lastSync);
+            if (date)
+                syncTimes.push(date);
+        }
+        if (metadata.ado?.lastSync) {
+            const date = this.parseSafeDate(metadata.ado.lastSync);
+            if (date)
+                syncTimes.push(date);
+        }
+        if (syncTimes.length === 0) {
+            return null;
+        }
+        // Return most recent sync time (sort descending, take first)
+        return syncTimes.sort((a, b) => b.getTime() - a.getTime())[0];
+    }
+    /**
+     * Safely parse date string with validation
+     *
+     * @param dateString - ISO date string
+     * @returns Date object or null if invalid
+     */
+    parseSafeDate(dateString) {
+        if (typeof dateString !== 'string')
+            return null;
+        const date = new Date(dateString);
+        // Check if date is valid
+        if (isNaN(date.getTime())) {
+            this.logger.warn(`Invalid date format: ${dateString}`);
+            return null;
+        }
+        return date;
+    }
+    /**
+     * Detect drift for a specific increment
+     *
+     * @param incrementId - Increment ID (e.g., "0053-safe-feature-deletion")
+     * @returns Drift status with recommendations
+     */
+    async detectDrift(incrementId) {
+        try {
+            // P0-1: Validate increment ID to prevent path traversal
+            this.validateIncrementId(incrementId);
+            // P0-4: Use async fs operations (replaced existsSync/readFileSync)
+            const metadataPath = path.join(this.projectRoot, '.specweave/increments', incrementId, 'metadata.json');
+            // Check if metadata exists (async)
+            try {
+                await fs.access(metadataPath);
+            }
+            catch {
+                return {
+                    hasDrift: false,
+                    lastSyncTime: null,
+                    hoursSinceSync: null,
+                    externalToolsConfigured: false,
+                    recommendation: 'No metadata found'
+                };
+            }
+            // P0-2: Safe JSON parsing with validation
+            const metadata = await this.readAndValidateMetadata(metadataPath);
+            // Check if external tools are configured
+            const hasGitHub = metadata.github && metadata.github.issues && metadata.github.issues.length > 0;
+            const hasJira = metadata.jira && metadata.jira.issues && metadata.jira.issues.length > 0;
+            const hasADO = metadata.ado && metadata.ado.workItems && metadata.ado.workItems.length > 0;
+            const externalToolsConfigured = hasGitHub || hasJira || hasADO;
+            if (!externalToolsConfigured) {
+                return {
+                    hasDrift: false,
+                    lastSyncTime: null,
+                    hoursSinceSync: null,
+                    externalToolsConfigured: false,
+                    recommendation: 'No external tools configured'
+                };
+            }
+            // P1-1: Get most recent sync time across ALL external tools (not just first one)
+            const lastSyncTime = this.getMostRecentSync(metadata);
+            if (!lastSyncTime) {
+                return {
+                    hasDrift: true,
+                    lastSyncTime: null,
+                    hoursSinceSync: null,
+                    externalToolsConfigured: true,
+                    recommendation: 'External tools never synced - run /specweave:sync-progress'
+                };
+            }
+            // Calculate hours since last sync
+            const now = new Date();
+            const hoursSinceSync = (now.getTime() - lastSyncTime.getTime()) / (1000 * 60 * 60);
+            // Use extracted constants (P0-5 fix)
+            const hasDrift = hoursSinceSync > DRIFT_THRESHOLD_HOURS;
+            let recommendation = '';
+            if (hasDrift) {
+                if (hoursSinceSync < WARNING_THRESHOLD_HOURS) {
+                    recommendation = 'External tools synced 1-2 days ago - consider running /specweave:sync-progress';
+                }
+                else if (hoursSinceSync < CRITICAL_THRESHOLD_HOURS) {
+                    recommendation = `External tools synced ${Math.floor(hoursSinceSync / 24)} days ago - run /specweave:sync-progress soon`;
+                }
+                else {
+                    recommendation = `External tools synced ${Math.floor(hoursSinceSync / 168)} weeks ago - URGENT: run /specweave:sync-progress`;
+                }
+            }
+            else {
+                recommendation = `External tools synced ${Math.floor(hoursSinceSync)} hours ago - up to date`;
+            }
+            return {
+                hasDrift,
+                lastSyncTime,
+                hoursSinceSync,
+                externalToolsConfigured,
+                recommendation
+            };
+        }
+        catch (error) {
+            // P0-5: Don't mask errors - expose them in return value
+            this.logger.error(`Error detecting drift for ${incrementId}:`, error);
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                hasDrift: false,
+                lastSyncTime: null,
+                hoursSinceSync: null,
+                externalToolsConfigured: false,
+                recommendation: `Error detecting drift: ${errorMessage}`,
+                error: errorMessage // Expose error for caller to handle
+            };
+        }
+    }
+    /**
+     * Get human-readable drift message for display
+     *
+     * @param drift - Drift status from detectDrift()
+     * @returns Formatted message with emoji indicator
+     */
+    getDriftMessage(drift) {
+        if (!drift.externalToolsConfigured) {
+            return '';
+        }
+        if (!drift.lastSyncTime) {
+            return '⚠️  External tools never synced';
+        }
+        if (drift.hasDrift) {
+            if (drift.hoursSinceSync && drift.hoursSinceSync < 48) {
+                return `⚠️  External sync: ${Math.floor(drift.hoursSinceSync)}h ago`;
+            }
+            else if (drift.hoursSinceSync && drift.hoursSinceSync < 168) {
+                return `🔴 External sync: ${Math.floor(drift.hoursSinceSync / 24)}d ago`;
+            }
+            else {
+                return `🔴 External sync: ${Math.floor((drift.hoursSinceSync || 0) / 168)}w ago (STALE)`;
+            }
+        }
+        return `✅ External sync: ${Math.floor(drift.hoursSinceSync || 0)}h ago`;
+    }
+}
+//# sourceMappingURL=external-tool-drift-detector.js.map

package/dist/src/utils/external-tool-drift-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-tool-drift-detector.js","sourceRoot":"","sources":["../../../src/utils/external-tool-drift-detector.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.26.2",
+  "version": "0.26.4",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",
@@ -77,7 +77,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.20.0",
+    "@anthropic-ai/sdk": "^0.70.1",
     "@octokit/rest": "^22.0.1",
     "@types/handlebars": "^4.0.40",
     "axios": "^1.13.2",
@@ -86,9 +86,9 @@
     "glob": "^11.0.3",
     "gray-matter": "^4.0.3",
     "handlebars": "^4.7.8",
-    "inquirer": "^12.10.0",
+    "inquirer": "^13.0.1",
     "js-yaml": "^4.1.0",
-    "open": "^10.2.0",
+    "open": "^11.0.0",
     "ora": "^9.0.0",
     "yaml": "^2.3.4"
   },

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

@@ -455,12 +455,12 @@ 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
+    # v0.26.1: SKIP_US_SYNC removed - no longer needed!
+    # Automatic US sync restored with multi-layer protection:
+    # 1. SKIP_EXTERNAL_SYNC guard at LivingDocsSync layer (prevents recursion)
+    # 2. Smart throttle (60s window prevents spam)
+    # 3. fs.writeFile() confirmed to NOT trigger hooks (test validated)
+    # See: FS-WRITEFILE-HOOK-TEST-RESULTS-2025-11-24.md, ADR-0129
 
     # Run consolidated sync (single Node.js process handles ALL operations)
     if (cd "$PROJECT_ROOT" && node "$CONSOLIDATED_SCRIPT" "$CURRENT_INCREMENT") >> "$DEBUG_LOG" 2>&1; then

package/plugins/specweave/hooks/pre-increment-start.sh

@@ -19,7 +19,12 @@
 # **See**: ADR-0062 (AC Embedding Architecture)
 #
 
-set -euo pipefail
+# CRITICAL (v0.25.2): NEVER use 'set -e' in hooks - causes Claude Code crashes
+# See: CLAUDE.md Section 9a (Hook Safety Checklist), ADR-0060 (Hook Performance)
+# NOTE: This validation hook explicitly exits with code 1 on failures (controlled behavior)
+set +e  # Allow commands to fail without terminating script
+set -u  # Fail on undefined variables
+set -o pipefail  # Fail if any command in pipeline fails
 
 # Get increment path from environment or argument
 INCREMENT_PATH="${1:-}"

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

@@ -1,96 +1,67 @@
 #!/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) {
+import { USCompletionDetector } from "../../../../dist/src/core/us-completion-detector.js";
+import { LivingDocsSync } from "../../../../dist/src/core/living-docs/living-docs-sync.js";
+import { USSyncThrottle } from "../../../../dist/src/core/us-sync-throttle.js";
+import { consoleLogger } from "../vendor/utils/logger.js";
+async function syncCompletedUserStories(incrementId) {
   try {
-    console.log(`\n🎯 [6/6] Detecting completed user stories for ${incrementId}...`);
-
+    console.log(`
+\u{1F3AF} [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 };
+    const throttle = USSyncThrottle.getInstance({ projectRoot });
+    if (throttle.shouldSkipSync(incrementId)) {
+      const timeSinceLastSync = throttle.getTimeSinceLastSync(incrementId);
+      const secondsRemaining = Math.ceil((6e4 - timeSinceLastSync) / 1e3);
+      console.log(`\u23ED\uFE0F  US sync throttled (last sync ${Math.floor(timeSinceLastSync / 1e3)}s ago)`);
+      console.log(`   \u2139\uFE0F  Sync will be available in ${secondsRemaining}s`);
+      console.log(`   \u{1F4A1} Manual sync: /specweave:sync-progress ${incrementId}`);
+      return {
+        success: true,
+        message: "Sync throttled",
+        throttled: true,
+        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("\u2705 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:`);
+    console.log(`
+\u{1F389} 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}...`);
-
+    console.log(`
+\u{1F4DA} 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(`\u2705 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)`);
+      console.log(`
+\u{1F4E1} External tool sync completed (GitHub/JIRA/ADO updated if configured)`);
+      throttle.recordSync(incrementId);
+      console.log(`   \u23F1\uFE0F  Throttle recorded (next sync allowed in 60s)`);
     } else {
-      console.warn(`⚠️  Living docs sync had errors (see logs)`);
-      console.warn(`   Errors: ${syncResult.errors.join(', ')}`);
+      console.warn(`\u26A0\uFE0F  Living docs sync had errors (see logs)`);
+      console.warn(`   Errors: ${syncResult.errors.join(", ")}`);
     }
-
     return {
       success: true,
-      newlyCompleted: newlyCompleted.map(us => ({
+      newlyCompleted: newlyCompleted.map((us) => ({
         usId: us.usId,
         title: us.title,
         totalACs: us.totalACs,
@@ -99,37 +70,39 @@ export async function syncCompletedUserStories(incrementId) {
       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 };
+    console.error("\u274C Error in US completion orchestrator:", error.message);
+    return {
+      success: false,
+      error: error.message,
+      message: "Orchestrator error"
+    };
   }
 }
-
-// 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');
+    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);
+  syncCompletedUserStories(incrementId).then((result) => {
+    if (result.success) {
+      console.log("\n\u2705 US completion orchestration completed successfully");
+      if (result.throttled) {
+        console.log("   (Throttled - no sync performed)");
       }
-    })
-    .catch(error => {
-      console.error('\n❌ Fatal error:', error);
+      process.exit(0);
+    } else {
+      console.error("\n\u274C US completion orchestration failed");
       process.exit(1);
-    });
+    }
+  }).catch((error) => {
+    console.error("\n\u274C Fatal error:", error);
+    process.exit(1);
+  });
 }
+export {
+  syncCompletedUserStories
+};