specweave 0.18.0 → 0.20.0

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

@@ -3,20 +3,21 @@
 # SpecWeave GitHub Sync Hook
 # Runs after task completion to sync progress to GitHub Projects
 #
-# CORRECT ARCHITECTURE (v0.17.0+):
-# - Syncs .specweave/docs/internal/specs/spec-*.md ↔ GitHub Projects
-# - NOT increments ↔ GitHub Issues (that was wrong!)
+# 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 the current work belongs to
-# - Updating spec user stories based on task completion
-# - Syncing spec state to GitHub Projects
-# - Updating GitHub Project cards/issues
+# - 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/*)
+# - Node.js and TypeScript CLI (dist/cli/commands/sync-spec-content.js)
 # - GitHub CLI (gh) must be installed and authenticated
-# - Spec metadata must have .externalLinks.github field
+# - ProgressCommentBuilder (lib/progress-comment-builder.ts)
 
 set -e
 
@@ -199,6 +200,38 @@ else
   fi
 fi
 
+# ============================================================================
+# EPIC GITHUB ISSUE SYNC (Update Epic issue with fresh task progress)
+# ============================================================================
+
+echo "[$(date)] [GitHub] 🔄 Checking for Epic GitHub issue update..." >> "$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..." >> "$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 complete (see logs for details)" >> "$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
+
 # ============================================================================
 # OUTPUT TO CLAUDE
 # ============================================================================

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

@@ -0,0 +1,262 @@
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+class CompletionCalculator {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+  }
+  /**
+   * Calculate ACTUAL completion from markdown checkboxes
+   *
+   * Returns true only if:
+   * - All ACs have [x] (not [ ])
+   * - All Tasks have **Status**: [x] (not [ ])
+   * - At least 1 AC exists (no empty user stories)
+   *
+   * @param userStoryPath - Path to us-*.md file
+   * @returns Completion status with detailed metrics
+   */
+  async calculateCompletion(userStoryPath) {
+    const content = await readFile(userStoryPath, "utf-8");
+    const frontmatter = this.parseUserStoryFrontmatter(content);
+    const acs = this.extractAcceptanceCriteria(content);
+    const tasks = await this.extractTasks(content, frontmatter.id);
+    const acsCompleted = acs.filter((ac) => ac.completed).length;
+    const tasksCompleted = tasks.filter((t) => t.completed).length;
+    const overallComplete = acs.length > 0 && acsCompleted === acs.length && (tasks.length === 0 || tasksCompleted === tasks.length);
+    return {
+      acsTotal: acs.length,
+      acsCompleted,
+      acsPercentage: acs.length > 0 ? acsCompleted / acs.length * 100 : 0,
+      tasksTotal: tasks.length,
+      tasksCompleted,
+      tasksPercentage: tasks.length > 0 ? tasksCompleted / tasks.length * 100 : 0,
+      overallComplete,
+      blockingAcs: acs.filter((ac) => !ac.completed).map((ac) => ac.id),
+      blockingTasks: tasks.filter((t) => !t.completed).map((t) => t.id)
+    };
+  }
+  /**
+   * Parse User Story frontmatter
+   */
+  parseUserStoryFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      throw new Error("Missing YAML frontmatter in user story");
+    }
+    return yaml.parse(match[1]);
+  }
+  /**
+   * Extract Acceptance Criteria with checkbox state
+   *
+   * Supports TWO formats:
+   * - Format 1 (preferred): AC-US1-01, AC-US1-02 (project-specific)
+   * - Format 2 (legacy): AC-001, AC-002, AC-020 (global)
+   *
+   * Patterns:
+   * - [x] **AC-US1-01**: Description (completed)
+   * - [ ] **AC-US1-01**: Description (not completed)
+   * - **AC-US1-01**: Description (no checkbox, default to not completed)
+   */
+  extractAcceptanceCriteria(content) {
+    const criteria = [];
+    const acMatch = content.match(/##\s*Acceptance Criteria\s*\n+([\s\S]*?)(?=\n##|$)/i);
+    if (!acMatch) {
+      return criteria;
+    }
+    const acSection = acMatch[1];
+    const acPatternWithCheckbox = /(?:^|\n)\s*[-*]\s+\[([x ])\]\s+\*\*([A-Z]+-(?:[A-Z]+\d+-)?(\d+))\*\*:\s*([^\n]+)/g;
+    const acPatternNoCheckbox = /(?:^|\n)\s*[-*]?\s*\*\*([A-Z]+-(?:[A-Z]+\d+-)?(\d+))\*\*:\s*([^\n]+)/g;
+    let match;
+    let foundAny = false;
+    while ((match = acPatternWithCheckbox.exec(acSection)) !== null) {
+      foundAny = true;
+      criteria.push({
+        id: match[2],
+        // e.g., "AC-US1-01" or "AC-020"
+        description: match[4].trim(),
+        completed: match[1] === "x"
+        // ✅ Read checkbox state from source!
+      });
+    }
+    if (!foundAny) {
+      while ((match = acPatternNoCheckbox.exec(acSection)) !== null) {
+        criteria.push({
+          id: match[1],
+          // e.g., "AC-US1-01" or "AC-020"
+          description: match[3].trim(),
+          completed: false
+          // Default to not completed
+        });
+      }
+    }
+    return criteria;
+  }
+  /**
+   * Extract tasks from increment's tasks.md that map to this User Story
+   *
+   * Process:
+   * 1. Find increment link in user story's "Implementation" section
+   * 2. Read increment's tasks.md
+   * 3. Filter tasks that reference this user story's ACs
+   * 4. Extract completion status from **Status**: [x] or [ ]
+   */
+  async extractTasks(userStoryContent, userStoryId) {
+    const tasks = [];
+    const implMatch = userStoryContent.match(/##\s*Implementation\s*\n+([\s\S]*?)(?=\n##|$)/i);
+    if (!implMatch) {
+      return tasks;
+    }
+    const implSection = implMatch[1];
+    const incrementMatch = implSection.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
+    if (!incrementMatch) {
+      return tasks;
+    }
+    const incrementId = incrementMatch[1];
+    const tasksPath = path.join(
+      this.projectRoot,
+      ".specweave",
+      "increments",
+      incrementId,
+      "tasks.md"
+    );
+    if (!existsSync(tasksPath)) {
+      return tasks;
+    }
+    const tasksContent = await readFile(tasksPath, "utf-8");
+    const taskPattern = /###?\s+(T-\d+):\s*([^\n]+)\n([\s\S]*?)(?=\n###?\s+T-\d+:|$)/g;
+    let match;
+    while ((match = taskPattern.exec(tasksContent)) !== null) {
+      const taskId = match[1];
+      const taskTitle = match[2].trim();
+      const taskBody = match[3];
+      const acMatch = taskBody.match(/\*\*AC\*\*:\s*([^\n]+)/);
+      if (!acMatch) {
+        continue;
+      }
+      const acList = acMatch[1].trim();
+      const acIds = acList.split(",").map((ac) => ac.trim());
+      const belongsToThisUS = acIds.some((acId) => {
+        const usMatch = acId.match(/AC-([A-Z]+\d+)-/);
+        if (!usMatch) return false;
+        const extractedUsId = usMatch[1];
+        const extractedNum = extractedUsId.replace(/^US/, "");
+        const normalizedExtracted = `US-${extractedNum.padStart(3, "0")}`;
+        const currentNum = userStoryId.replace(/^US-?/, "");
+        const normalizedCurrent = `US-${currentNum.padStart(3, "0")}`;
+        return normalizedExtracted === normalizedCurrent;
+      });
+      if (!belongsToThisUS) {
+        continue;
+      }
+      const statusMatch = taskBody.match(/\*\*Status\*\*:\s*\[([x ])\]/);
+      const completed = statusMatch ? statusMatch[1] === "x" : false;
+      tasks.push({
+        id: taskId,
+        title: taskTitle,
+        completed,
+        // ✅ Now reads actual completion status!
+        userStories: acIds
+      });
+    }
+    return tasks;
+  }
+  /**
+   * Build completion comment for GitHub issue closure
+   *
+   * Used when closing issue after verification
+   */
+  buildCompletionComment(completion) {
+    return `\u2705 **User Story Verified Complete**
+
+**Completion Status**:
+- \u2705 Acceptance Criteria: ${completion.acsCompleted}/${completion.acsTotal} (100%)
+- \u2705 Implementation Tasks: ${completion.tasksCompleted}/${completion.tasksTotal} (100%)
+
+All work has been verified and completed. This issue is now closed.
+
+\u{1F916} Auto-verified by SpecWeave AC Completion Gate`;
+  }
+  /**
+   * Build progress comment for GitHub issue update
+   *
+   * Used when issue stays open (not 100% complete)
+   */
+  buildProgressComment(completion) {
+    const sections = [];
+    sections.push("\u{1F4CA} **Progress Update**");
+    sections.push("");
+    const acIcon = completion.acsPercentage === 100 ? "\u2705" : "\u{1F504}";
+    sections.push(
+      `${acIcon} **Acceptance Criteria**: ${completion.acsCompleted}/${completion.acsTotal} (${completion.acsPercentage.toFixed(0)}%)`
+    );
+    if (completion.blockingAcs.length > 0) {
+      sections.push("");
+      sections.push("**Incomplete ACs**:");
+      for (const acId of completion.blockingAcs) {
+        sections.push(`- [ ] ${acId}`);
+      }
+    }
+    sections.push("");
+    const taskIcon = completion.tasksPercentage === 100 ? "\u2705" : "\u{1F504}";
+    sections.push(
+      `${taskIcon} **Implementation Tasks**: ${completion.tasksCompleted}/${completion.tasksTotal} (${completion.tasksPercentage.toFixed(0)}%)`
+    );
+    if (completion.blockingTasks.length > 0) {
+      sections.push("");
+      sections.push("**Incomplete Tasks**:");
+      for (const taskId of completion.blockingTasks) {
+        sections.push(`- [ ] ${taskId}`);
+      }
+    }
+    sections.push("");
+    sections.push("---");
+    sections.push("\u{1F916} Auto-updated by SpecWeave AC Completion Gate");
+    return sections.join("\n");
+  }
+  /**
+   * Build reopen comment for GitHub issue
+   *
+   * Used when reopening prematurely closed issue
+   */
+  buildReopenComment(completion, reason = "Work verification failed") {
+    const sections = [];
+    sections.push(`\u{1F504} **Reopening Issue - ${reason}**`);
+    sections.push("");
+    sections.push("**Current Status**:");
+    sections.push(
+      `- Acceptance Criteria: ${completion.acsCompleted}/${completion.acsTotal} (${completion.acsPercentage.toFixed(0)}%)`
+    );
+    sections.push(
+      `- Implementation Tasks: ${completion.tasksCompleted}/${completion.tasksTotal} (${completion.tasksPercentage.toFixed(0)}%)`
+    );
+    const totalBlocking = completion.blockingAcs.length + completion.blockingTasks.length;
+    if (totalBlocking > 0) {
+      sections.push("");
+      sections.push(`**Blocking Items** (${totalBlocking}):`);
+      if (completion.blockingAcs.length > 0) {
+        sections.push("");
+        sections.push("**Acceptance Criteria**:");
+        for (const acId of completion.blockingAcs) {
+          sections.push(`- [ ] ${acId}`);
+        }
+      }
+      if (completion.blockingTasks.length > 0) {
+        sections.push("");
+        sections.push("**Implementation Tasks**:");
+        for (const taskId of completion.blockingTasks) {
+          sections.push(`- [ ] ${taskId}`);
+        }
+      }
+    }
+    sections.push("");
+    sections.push("\u26A0\uFE0F This issue cannot be closed until all ACs and tasks are verified complete.");
+    sections.push("");
+    sections.push("\u{1F916} Auto-reopened by SpecWeave AC Completion Gate");
+    return sections.join("\n");
+  }
+}
+export {
+  CompletionCalculator
+};