specweave 0.26.4 → 0.26.9

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

@@ -0,0 +1,258 @@
+#!/bin/bash
+
+# SpecWeave GitHub Sync Hook
+# Runs after task completion to sync progress to GitHub Projects
+#
+# ARCHITECTURE (v0.19.0+): IMMUTABLE DESCRIPTIONS + PROGRESS COMMENTS
+# - User Story files (.specweave/docs/internal/specs/) ↔ GitHub Issues
+# - Issue descriptions created once (IMMUTABLE snapshot)
+# - All updates via progress comments (audit trail)
+#
+# This hook is part of the specweave-github plugin and handles:
+# - Finding which spec user stories the current work belongs to
+# - Syncing progress via GitHub comments (NOT editing issue body)
+# - Creating audit trail of all changes over time
+# - Notifying stakeholders via GitHub notifications
+#
+# Dependencies:
+# - Node.js and TypeScript CLI (dist/cli/commands/sync-spec-content.js)
+# - GitHub CLI (gh) must be installed and authenticated
+# - ProgressCommentBuilder (lib/progress-comment-builder.ts)
+
+set -e
+
+# ============================================================================
+# PROJECT ROOT DETECTION
+# ============================================================================
+
+# Find project root by searching upward for .specweave/ directory
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # Fallback: try current directory
+  if [ -d "$(pwd)/.specweave" ]; then
+    pwd
+  else
+    echo "$(pwd)"
+  fi
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT" 2>/dev/null || true
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+LOGS_DIR=".specweave/logs"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+
+mkdir -p "$LOGS_DIR" 2>/dev/null || true
+
+# ============================================================================
+# PRECONDITIONS CHECK
+# ============================================================================
+
+echo "[$(date)] [GitHub] 🔗 GitHub sync hook fired" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# Check if Node.js is available
+if ! command -v node &> /dev/null; then
+  echo "[$(date)] [GitHub] ⚠️  Node.js not found, skipping GitHub sync" >> "$DEBUG_LOG" 2>/dev/null || true
+  cat <<EOF
+{
+  "continue": true
+}
+EOF
+  exit 0
+fi
+
+# Check if github-spec-content-sync CLI exists
+SYNC_CLI="$PROJECT_ROOT/dist/src/cli/commands/sync-spec-content.js"
+if [ ! -f "$SYNC_CLI" ]; then
+  echo "[$(date)] [GitHub] ⚠️  sync-spec-content CLI not found at $SYNC_CLI, skipping sync" >> "$DEBUG_LOG" 2>/dev/null || true
+  cat <<EOF
+{
+  "continue": true
+}
+EOF
+  exit 0
+fi
+
+# Check for gh CLI
+if ! command -v gh &> /dev/null; then
+  echo "[$(date)] [GitHub] ⚠️  GitHub CLI (gh) not found, skipping sync" >> "$DEBUG_LOG" 2>/dev/null || true
+  cat <<EOF
+{
+  "continue": true
+}
+EOF
+  exit 0
+fi
+
+# ============================================================================
+# DETECT ALL SPECS (Multi-Spec Support)
+# ============================================================================
+
+# Strategy: Use multi-spec detector to find ALL specs referenced in current increment
+
+# 1. Detect current increment (temporary context)
+CURRENT_INCREMENT=$(ls -td .specweave/increments/*/ 2>/dev/null | xargs -n1 basename | grep -v "_backlog" | grep -v "_archive" | grep -v "_working" | head -1)
+
+if [ -z "$CURRENT_INCREMENT" ]; then
+  echo "[$(date)] [GitHub] ℹ️  No active increment, checking for spec changes..." >> "$DEBUG_LOG" 2>/dev/null || true
+  # Fall through to sync all changed specs
+fi
+
+# 2. Use TypeScript CLI to detect all specs
+DETECT_CLI="$PROJECT_ROOT/dist/src/cli/commands/detect-specs.js"
+
+if [ -f "$DETECT_CLI" ]; then
+  echo "[$(date)] [GitHub] 🔍 Detecting all specs in increment $CURRENT_INCREMENT..." >> "$DEBUG_LOG" 2>/dev/null || true
+
+  # Call detect-specs CLI and capture JSON output
+  DETECTION_RESULT=$(node "$DETECT_CLI" 2>> "$DEBUG_LOG" || echo "{}")
+
+  # Extract spec count
+  SPEC_COUNT=$(echo "$DETECTION_RESULT" | node -e "const fs=require('fs'); const data=JSON.parse(fs.readFileSync(0,'utf-8')); console.log(data.specs?.length || 0)")
+
+  echo "[$(date)] [GitHub] 📋 Detected $SPEC_COUNT spec(s)" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  # Store detection result for later use
+  echo "$DETECTION_RESULT" > /tmp/specweave-detected-specs.json
+else
+  echo "[$(date)] [GitHub] ⚠️  detect-specs CLI not found at $DETECT_CLI, falling back to git diff" >> "$DEBUG_LOG" 2>/dev/null || true
+  SPEC_COUNT=0
+fi
+
+# ============================================================================
+# SYNC ALL DETECTED SPECS TO GITHUB (Multi-Spec Support)
+# ============================================================================
+
+if [ -f /tmp/specweave-detected-specs.json ] && [ "$SPEC_COUNT" -gt 0 ]; then
+  # Multi-spec sync: Loop through all detected specs
+  echo "[$(date)] [GitHub] 🔄 Syncing $SPEC_COUNT spec(s) to GitHub..." >> "$DEBUG_LOG" 2>/dev/null || true
+
+  # Extract spec paths using Node.js
+  SPEC_PATHS=$(node -e "
+    const fs = require('fs');
+    const data = JSON.parse(fs.readFileSync('/tmp/specweave-detected-specs.json', 'utf-8'));
+    const syncable = data.specs.filter(s => s.syncEnabled && s.project !== '_parent');
+    syncable.forEach(s => console.log(s.path));
+  " 2>> "$DEBUG_LOG")
+
+  # Count syncable specs
+  SYNCABLE_COUNT=$(echo "$SPEC_PATHS" | grep -v '^$' | wc -l | tr -d ' ')
+
+  if [ "$SYNCABLE_COUNT" -gt 0 ]; then
+    echo "[$(date)] [GitHub] 📋 Syncing $SYNCABLE_COUNT syncable spec(s) (excluding _parent)" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Sync each spec
+    echo "$SPEC_PATHS" | while read -r SPEC_FILE; do
+      if [ -n "$SPEC_FILE" ] && [ -f "$SPEC_FILE" ]; then
+        # Extract project and spec ID from path
+        SPEC_NAME=$(basename "$SPEC_FILE" .md)
+        PROJECT=$(basename "$(dirname "$SPEC_FILE")")
+
+        echo "[$(date)] [GitHub] 🔄 Syncing $PROJECT/$SPEC_NAME..." >> "$DEBUG_LOG" 2>/dev/null || true
+
+        (cd "$PROJECT_ROOT" && node "$SYNC_CLI" --spec "$SPEC_FILE" --provider github) 2>&1 | tee -a "$DEBUG_LOG" >/dev/null || {
+          echo "[$(date)] [GitHub] ⚠️  Spec sync failed for $PROJECT/$SPEC_NAME (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+        }
+
+        echo "[$(date)] [GitHub] ✅ Synced $PROJECT/$SPEC_NAME" >> "$DEBUG_LOG" 2>/dev/null || true
+      fi
+    done
+
+    echo "[$(date)] [GitHub] ✅ Multi-spec sync complete ($SYNCABLE_COUNT synced)" >> "$DEBUG_LOG" 2>/dev/null || true
+  else
+    echo "[$(date)] [GitHub] ℹ️  No syncable specs (all specs are _parent or syncEnabled=false)" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+
+  # Cleanup temp file
+  rm -f /tmp/specweave-detected-specs.json 2>/dev/null || true
+else
+  # Fallback: Sync all modified specs (check git diff)
+  echo "[$(date)] [GitHub] 🔄 Checking for modified specs..." >> "$DEBUG_LOG" 2>/dev/null || true
+
+  MODIFIED_SPECS=$(git diff --name-only HEAD .specweave/docs/internal/specs/**/*.md 2>/dev/null || echo "")
+
+  if [ -n "$MODIFIED_SPECS" ]; then
+    echo "[$(date)] [GitHub] 📝 Found modified specs:" >> "$DEBUG_LOG" 2>/dev/null || true
+    echo "$MODIFIED_SPECS" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Sync each modified spec
+    echo "$MODIFIED_SPECS" | while read -r SPEC_FILE; do
+      if [ -n "$SPEC_FILE" ] && [ -f "$SPEC_FILE" ]; then
+        echo "[$(date)] [GitHub] 🔄 Syncing $SPEC_FILE..." >> "$DEBUG_LOG" 2>/dev/null || true
+        (cd "$PROJECT_ROOT" && node "$SYNC_CLI" --spec "$SPEC_FILE" --provider github) 2>&1 | tee -a "$DEBUG_LOG" >/dev/null || true
+      fi
+    done
+
+    echo "[$(date)] [GitHub] ✅ Batch spec sync complete" >> "$DEBUG_LOG" 2>/dev/null || true
+  else
+    echo "[$(date)] [GitHub] ℹ️  No modified specs found, skipping sync" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+fi
+
+# ============================================================================
+# EPIC GITHUB ISSUE SYNC (DEPRECATED v0.24.0+)
+# ============================================================================
+#
+# ⚠️  DEPRECATED: SpecWeave now syncs ONLY at User Story level.
+#
+# Feature/Epic-level issues are no longer updated.
+# Use /specweave-github:sync instead to sync User Story issues.
+#
+# To re-enable (NOT recommended):
+#   export SPECWEAVE_ENABLE_EPIC_SYNC=true
+#
+# @see .specweave/increments/0047-us-task-linkage/reports/GITHUB-TITLE-FORMAT-FIX-PLAN.md
+# ============================================================================
+
+if [ "$SPECWEAVE_ENABLE_EPIC_SYNC" = "true" ]; then
+  echo "[$(date)] [GitHub] 🔄 Checking for Epic GitHub issue update (DEPRECATED)..." >> "$DEBUG_LOG" 2>/dev/null || true
+
+  # Find active increment ID
+  ACTIVE_INCREMENT=$(ls -t .specweave/increments/ | grep -v '^\.' | while read inc; do
+    if [ -f ".specweave/increments/$inc/metadata.json" ]; then
+      STATUS=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' ".specweave/increments/$inc/metadata.json" 2>/dev/null | sed 's/.*"\([^"]*\)".*/\1/' || true)
+      if [ "$STATUS" = "active" ]; then
+        echo "$inc"
+        break
+      fi
+    fi
+  done | head -1)
+
+  if [ -n "$ACTIVE_INCREMENT" ]; then
+    echo "[$(date)] [GitHub] 🎯 Active increment: $ACTIVE_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Run Epic sync script (silently, errors logged to debug log)
+    if [ -f "$PROJECT_ROOT/scripts/update-epic-github-issue.sh" ]; then
+      echo "[$(date)] [GitHub] 🚀 Updating Epic GitHub issue (DEPRECATED)..." >> "$DEBUG_LOG" 2>/dev/null || true
+      "$PROJECT_ROOT/scripts/update-epic-github-issue.sh" "$ACTIVE_INCREMENT" >> "$DEBUG_LOG" 2>&1 || true
+      echo "[$(date)] [GitHub] ⚠️  Epic sync is deprecated. Use /specweave-github:sync instead." >> "$DEBUG_LOG" 2>/dev/null || true
+    else
+      echo "[$(date)] [GitHub] ⚠️  Epic sync script not found, skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+    fi
+  else
+    echo "[$(date)] [GitHub] ℹ️  No active increment found, skipping Epic sync" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+else
+  echo "[$(date)] [GitHub] ℹ️  Epic sync disabled (sync at User Story level only)" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
+# ============================================================================
+# OUTPUT TO CLAUDE
+# ============================================================================
+
+cat <<EOF
+{
+  "continue": true
+}
+EOF

package/plugins/specweave-github/lib/completion-calculator.js

@@ -131,7 +131,7 @@ class CompletionCalculator {
       const taskId = match[1];
       const taskTitle = match[2].trim();
       const taskBody = match[3];
-      const acMatch = taskBody.match(/\*\*AC\*\*:\s*([^\n]+)/);
+      const acMatch = taskBody.match(/\*\*(?:Satisfies ACs?|AC)\*\*:\s*([^\n]+)/);
       if (!acMatch) {
         continue;
       }

package/plugins/specweave-github/lib/completion-calculator.ts

@@ -266,8 +266,8 @@ export class CompletionCalculator {
       const taskTitle = match[2].trim();
       const taskBody = match[3];
 
-      // Extract AC list
-      const acMatch = taskBody.match(/\*\*AC\*\*:\s*([^\n]+)/);
+      // Extract AC list (support both old and new field names)
+      const acMatch = taskBody.match(/\*\*(?:Satisfies ACs?|AC)\*\*:\s*([^\n]+)/);
       if (!acMatch) {
         continue; // Skip tasks without AC field
       }

package/plugins/specweave-github/lib/github-feature-sync.js

@@ -6,7 +6,8 @@ import { UserStoryIssueBuilder } from "./user-story-issue-builder.js";
 import { CompletionCalculator } from "./completion-calculator.js";
 import { DuplicateDetector } from "./duplicate-detector.js";
 import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
-class GitHubFeatureSync {
+const _GitHubFeatureSync = class _GitHubFeatureSync {
+  // 30 seconds
   constructor(client, specsDir, projectRoot) {
     this.client = client;
     this.specsDir = specsDir;
@@ -23,6 +24,23 @@ class GitHubFeatureSync {
    * 4. Update frontmatter with GitHub issue links
    */
   async syncFeatureToGitHub(featureId) {
+    const now = Date.now();
+    const lastSync = _GitHubFeatureSync.syncLocks.get(featureId);
+    if (lastSync && now - lastSync < _GitHubFeatureSync.LOCK_DURATION_MS) {
+      const secondsRemaining = Math.ceil((_GitHubFeatureSync.LOCK_DURATION_MS - (now - lastSync)) / 1e3);
+      console.log(`
+\u23ED\uFE0F  Sync already in progress for ${featureId} (or completed ${Math.floor((now - lastSync) / 1e3)}s ago)`);
+      console.log(`   \u2139\uFE0F  Sync will be available in ${secondsRemaining}s to prevent duplicates`);
+      console.log(`   \u{1F4A1} This prevents race conditions between task completion and status change syncs`);
+      return {
+        milestoneNumber: 0,
+        milestoneUrl: "",
+        issuesCreated: 0,
+        issuesUpdated: 0,
+        userStoriesProcessed: 0
+      };
+    }
+    _GitHubFeatureSync.syncLocks.set(featureId, now);
     console.log(`
 \u{1F504} Syncing Feature ${featureId} to GitHub...`);
     const featureFolder = await this.findFeatureFolder(featureId);
@@ -109,8 +127,8 @@ class GitHubFeatureSync {
         console.log(`      \u{1F6E1}\uFE0F  Duplicates detected: ${result.duplicatesFound}, auto-closed: ${result.duplicatesClosed}`);
       }
       await this.updateUserStoryFrontmatter(userStory.filePath, issueNumber);
+      await this.updateUserStoryIssue(issueNumber, issueContent, userStory.filePath);
       if (result.wasReused) {
-        await this.updateUserStoryIssue(issueNumber, issueContent, userStory.filePath);
         issuesUpdated++;
       } else {
         issuesCreated++;
@@ -201,10 +219,29 @@ class GitHubFeatureSync {
     return folders;
   }
   /**
-   * Create GitHub Milestone for Feature
+   * Create GitHub Milestone for Feature (with duplicate detection)
    */
   async createMilestone(featureData) {
     const title = `${featureData.id}: ${featureData.title}`;
+    const existingResult = await execFileNoThrow("gh", [
+      "api",
+      "repos/:owner/:repo/milestones",
+      "--jq",
+      `.[] | select(.title == "${title}") | {number, html_url}`
+    ]);
+    console.log(`   \u{1F50D} Milestone detection: exitCode=${existingResult.exitCode}, stdout length=${existingResult.stdout.length}`);
+    if (existingResult.exitCode !== 0) {
+      console.log(`   \u26A0\uFE0F  Detection failed: ${existingResult.stderr}`);
+    }
+    if (existingResult.exitCode === 0 && existingResult.stdout.trim()) {
+      const existing = JSON.parse(existingResult.stdout);
+      console.log(`   \u267B\uFE0F  Reusing existing Milestone #${existing.number}`);
+      return {
+        number: existing.number,
+        url: existing.html_url
+      };
+    }
+    console.log(`   \u2139\uFE0F  No existing milestone found, creating new one...`);
     const description = `Feature ${featureData.id}
 
 Status: ${featureData.status}
@@ -270,16 +307,7 @@ Created: ${featureData.created}`;
         `      \u2705 Created and verified complete: ${completion.acsCompleted}/${completion.acsTotal} ACs, ${completion.tasksCompleted}/${completion.tasksTotal} tasks`
       );
     } else {
-      await execFileNoThrow("gh", [
-        "issue",
-        "comment",
-        issueNumber.toString(),
-        "--body",
-        this.calculator.buildProgressComment(completion)
-      ]);
-      console.log(
-        `      \u{1F4CA} Created: ${completion.acsPercentage.toFixed(0)}% ACs, ${completion.tasksPercentage.toFixed(0)}% tasks`
-      );
+      await this.postProgressCommentIfChanged(issueNumber, completion);
     }
     return issueNumber;
   }
@@ -331,17 +359,118 @@ Created: ${featureData.created}`;
           `      \u26A0\uFE0F Reopened: ${completion.blockingAcs.length + completion.blockingTasks.length} items incomplete`
         );
       } else {
+        await this.postProgressCommentIfChanged(issueNumber, completion);
+      }
+    }
+    await this.updateStatusLabels(issueNumber, completion);
+  }
+  /**
+   * Update status labels on GitHub issue based on completion state
+   *
+   * SMART LABEL MANAGEMENT:
+   * - Only manages status:* labels (status:not_started, status:in-progress, status:completed)
+   * - Preserves all other labels (priority, type, custom labels)
+   * - Ensures exactly one status label is present
+   */
+  async updateStatusLabels(issueNumber, completion) {
+    try {
+      const issueData = await this.client.getIssue(issueNumber);
+      const currentLabels = issueData.labels || [];
+      const statusLabels = currentLabels.filter((label) => label.startsWith("status:"));
+      const otherLabels = currentLabels.filter((label) => !label.startsWith("status:"));
+      let newStatusLabel;
+      if (completion.overallComplete) {
+        newStatusLabel = "status:complete";
+      } else if (completion.acsPercentage > 0 || completion.tasksPercentage > 0) {
+        newStatusLabel = "status:active";
+      } else {
+        newStatusLabel = "status:not_started";
+      }
+      const needsUpdate = statusLabels.length !== 1 || !statusLabels.includes(newStatusLabel);
+      if (!needsUpdate) {
+        return;
+      }
+      if (statusLabels.length > 0) {
         await execFileNoThrow("gh", [
           "issue",
-          "comment",
+          "edit",
           issueNumber.toString(),
-          "--body",
-          this.calculator.buildProgressComment(completion)
+          "--remove-label",
+          ...statusLabels
         ]);
+      }
+      const result = await execFileNoThrow("gh", [
+        "issue",
+        "edit",
+        issueNumber.toString(),
+        "--add-label",
+        newStatusLabel
+      ]);
+      if (result.exitCode === 0) {
+        console.log(`      \u{1F3F7}\uFE0F  Updated label: ${newStatusLabel}`);
+      } else {
+        console.warn(`      \u26A0\uFE0F  Failed to add label ${newStatusLabel}: ${result.stderr}`);
+      }
+    } catch (error) {
+      console.warn(`      \u26A0\uFE0F  Failed to update status labels: ${error.message}`);
+    }
+  }
+  /**
+   * Post progress comment only if it differs from the last comment
+   *
+   * DEDUPLICATION FIX (2025-11-24):
+   * - Prevents posting identical consecutive comments
+   * - Fetches last comment from issue
+   * - Compares content (ignoring timestamps)
+   * - Only posts if progress has changed
+   *
+   * Root Cause: updateUserStoryIssue() was posting progress comments on EVERY sync,
+   * even when progress hadn't changed, causing 4+ duplicate comments.
+   *
+   * @param issueNumber - GitHub issue number
+   * @param completion - Completion status with AC/task metrics
+   */
+  async postProgressCommentIfChanged(issueNumber, completion) {
+    try {
+      const commentsResult = await execFileNoThrow("gh", [
+        "api",
+        "repos/:owner/:repo/issues/" + issueNumber + "/comments",
+        "--jq",
+        ".[-1] | {body: .body, created_at: .created_at}"
+        // Get last comment only
+      ]);
+      let lastCommentBody = "";
+      if (commentsResult.exitCode === 0 && commentsResult.stdout.trim()) {
+        try {
+          const lastComment = JSON.parse(commentsResult.stdout);
+          lastCommentBody = lastComment.body || "";
+        } catch {
+        }
+      }
+      const newCommentBody = this.calculator.buildProgressComment(completion);
+      const normalizeComment = (text) => {
+        return text.replace(/🤖 Auto-updated by SpecWeave AC Completion Gate/g, "").replace(/\s+/g, " ").trim();
+      };
+      const normalizedLast = normalizeComment(lastCommentBody);
+      const normalizedNew = normalizeComment(newCommentBody);
+      if (normalizedLast === normalizedNew) {
         console.log(
-          `      \u{1F4CA} Progress: ${completion.acsPercentage.toFixed(0)}% ACs, ${completion.tasksPercentage.toFixed(0)}% tasks`
+          `      \u23ED\uFE0F  Progress unchanged (${completion.acsPercentage.toFixed(0)}% ACs, ${completion.tasksPercentage.toFixed(0)}% tasks) - skipping duplicate comment`
         );
+        return;
       }
+      await execFileNoThrow("gh", [
+        "issue",
+        "comment",
+        issueNumber.toString(),
+        "--body",
+        newCommentBody
+      ]);
+      console.log(
+        `      \u{1F4CA} Progress: ${completion.acsPercentage.toFixed(0)}% ACs, ${completion.tasksPercentage.toFixed(0)}% tasks (updated)`
+      );
+    } catch (error) {
+      console.error(`      \u26A0\uFE0F  Failed to check/post progress comment: ${error.message}`);
     }
   }
   /**
@@ -388,7 +517,12 @@ ${newFrontmatter}---${bodyContent}`;
 ${newFrontmatter}---${bodyContent}`;
     await writeFile(userStoryPath, newContent, "utf-8");
   }
-}
+};
+// SYNC LOCK: Prevent concurrent syncs of the same feature
+// Maps featureId → last sync timestamp
+_GitHubFeatureSync.syncLocks = /* @__PURE__ */ new Map();
+_GitHubFeatureSync.LOCK_DURATION_MS = 3e4;
+let GitHubFeatureSync = _GitHubFeatureSync;
 export {
   GitHubFeatureSync
 };