specweave 0.18.0 → 0.20.0

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

@@ -0,0 +1,434 @@
+/**
+ * Completion Calculator - Verifies actual work completion from markdown checkboxes
+ *
+ * CRITICAL FIX: Prevents premature GitHub issue closure by verifying actual
+ * AC and Task completion state, not just frontmatter status.
+ *
+ * Problem:
+ * - OLD: Issues closed based on frontmatter `status: complete`
+ * - Issue #574: Closed with 0/5 ACs complete!
+ *
+ * Solution:
+ * - NEW: Parse actual checkbox states ([x] vs [ ])
+ * - Close ONLY when ALL ACs and ALL tasks are verified [x]
+ *
+ * Architecture:
+ * - Acceptance Criteria: Read from us-*.md files
+ * - Tasks: Read from increment's tasks.md
+ * - Verification Gate: 100% completion required
+ */
+
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+
+/**
+ * Acceptance Criteria with completion status
+ */
+export interface AcceptanceCriteria {
+  id: string; // e.g., "AC-US1-01" or "AC-020"
+  description: string;
+  completed: boolean; // ✅ Read from [x] or [ ] checkbox
+}
+
+/**
+ * Implementation Task with completion status
+ */
+export interface Task {
+  id: string; // e.g., "T-001"
+  title: string;
+  completed: boolean; // ✅ Read from **Status**: [x] or [ ]
+  userStories: string[]; // ACs this task implements (e.g., ["AC-US1-01", "AC-US1-02"])
+}
+
+/**
+ * Complete verification status
+ */
+export interface CompletionStatus {
+  // Acceptance Criteria metrics
+  acsTotal: number;
+  acsCompleted: number;
+  acsPercentage: number;
+
+  // Task metrics
+  tasksTotal: number;
+  tasksCompleted: number;
+  tasksPercentage: number;
+
+  // Overall completion gate
+  overallComplete: boolean; // true ONLY if ALL ACs AND tasks are [x]
+
+  // Blocking items (for reopen)
+  blockingAcs: string[]; // List of incomplete AC-IDs
+  blockingTasks: string[]; // List of incomplete Task-IDs
+}
+
+/**
+ * User Story Frontmatter
+ */
+interface UserStoryFrontmatter {
+  id: string;
+  feature: string;
+  title: string;
+  status: 'complete' | 'active' | 'planning' | 'not-started';
+  project?: string;
+}
+
+export class CompletionCalculator {
+  private projectRoot: string;
+
+  constructor(projectRoot: string) {
+    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: string): Promise<CompletionStatus> {
+    // Step 1: Read and parse user story
+    const content = await readFile(userStoryPath, 'utf-8');
+    const frontmatter = this.parseUserStoryFrontmatter(content);
+
+    // Step 2: Extract Acceptance Criteria
+    const acs = this.extractAcceptanceCriteria(content);
+
+    // Step 3: Extract Tasks from increment (if linked)
+    const tasks = await this.extractTasks(content, frontmatter.id);
+
+    // Step 4: Calculate metrics
+    const acsCompleted = acs.filter((ac) => ac.completed).length;
+    const tasksCompleted = tasks.filter((t) => t.completed).length;
+
+    // Step 5: Determine overall completion
+    // MUST have:
+    // - At least 1 AC (no empty user stories)
+    // - ALL ACs completed
+    // - ALL Tasks completed (or no tasks if not implemented yet)
+    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
+   */
+  private parseUserStoryFrontmatter(content: string): UserStoryFrontmatter {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+
+    if (!match) {
+      throw new Error('Missing YAML frontmatter in user story');
+    }
+
+    return yaml.parse(match[1]) as UserStoryFrontmatter;
+  }
+
+  /**
+   * 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)
+   */
+  private extractAcceptanceCriteria(content: string): AcceptanceCriteria[] {
+    const criteria: AcceptanceCriteria[] = [];
+
+    // Look for "Acceptance Criteria" section
+    const acMatch = content.match(/##\s*Acceptance Criteria\s*\n+([\s\S]*?)(?=\n##|$)/i);
+
+    if (!acMatch) {
+      return criteria;
+    }
+
+    const acSection = acMatch[1];
+
+    // Pattern with checkboxes (PREFERRED)
+    // Matches: - [x] **AC-US1-01**: Description
+    //          - [ ] **AC-020**: Description
+    const acPatternWithCheckbox =
+      /(?:^|\n)\s*[-*]\s+\[([x ])\]\s+\*\*([A-Z]+-(?:[A-Z]+\d+-)?(\d+))\*\*:\s*([^\n]+)/g;
+
+    // Pattern without checkboxes (FALLBACK)
+    // Matches: - **AC-US1-01**: Description
+    const acPatternNoCheckbox =
+      /(?:^|\n)\s*[-*]?\s*\*\*([A-Z]+-(?:[A-Z]+\d+-)?(\d+))\*\*:\s*([^\n]+)/g;
+
+    // First try pattern with checkboxes
+    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 no checkboxes found, try pattern without checkboxes
+    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 [ ]
+   */
+  private async extractTasks(userStoryContent: string, userStoryId: string): Promise<Task[]> {
+    const tasks: Task[] = [];
+
+    // Look for "Implementation" section with increment link
+    const implMatch = userStoryContent.match(/##\s*Implementation\s*\n+([\s\S]*?)(?=\n##|$)/i);
+
+    if (!implMatch) {
+      return tasks; // No implementation yet
+    }
+
+    const implSection = implMatch[1];
+
+    // Extract increment ID from Implementation section
+    // Pattern: **Increment**: [0031-external-tool-status-sync](...)
+    const incrementMatch = implSection.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
+
+    if (!incrementMatch) {
+      return tasks; // No increment linked
+    }
+
+    const incrementId = incrementMatch[1];
+
+    // Try to read increment's tasks.md
+    const tasksPath = path.join(
+      this.projectRoot,
+      '.specweave',
+      'increments',
+      incrementId,
+      'tasks.md'
+    );
+
+    if (!existsSync(tasksPath)) {
+      return tasks; // Increment has no tasks.md yet
+    }
+
+    const tasksContent = await readFile(tasksPath, 'utf-8');
+
+    // Extract tasks that reference this User Story via AC-IDs
+    // Pattern:
+    // ### T-001: Task Title
+    // **User Story**: ...
+    // **Status**: [x] (100% - Completed) or [ ] (0% - Not started)
+    // **AC**: AC-US1-01, AC-US1-02
+    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];
+
+      // Extract AC list
+      const acMatch = taskBody.match(/\*\*AC\*\*:\s*([^\n]+)/);
+      if (!acMatch) {
+        continue; // Skip tasks without AC field
+      }
+      const acList = acMatch[1].trim();
+
+      // Check if any AC in this task belongs to current User Story
+      // AC-US1-01 → US-001
+      // AC-US001-01 → US-001
+      const acIds = acList.split(',').map((ac) => ac.trim());
+      const belongsToThisUS = acIds.some((acId) => {
+        // Extract US ID from AC-ID
+        // AC-US1-01 → US1 → US-001
+        // AC-US001-01 → US001 → US-001
+        const usMatch = acId.match(/AC-([A-Z]+\d+)-/);
+        if (!usMatch) return false;
+
+        // Normalize to US-XXX format (pad with zeros)
+        const extractedUsId = usMatch[1]; // e.g., "US1" or "US001"
+        const extractedNum = extractedUsId.replace(/^US/, ''); // "1" or "001"
+        const normalizedExtracted = `US-${extractedNum.padStart(3, '0')}`; // "US-001"
+
+        const currentNum = userStoryId.replace(/^US-?/, ''); // "001" or "1"
+        const normalizedCurrent = `US-${currentNum.padStart(3, '0')}`; // "US-001"
+
+        return normalizedExtracted === normalizedCurrent;
+      });
+
+      if (!belongsToThisUS) {
+        continue;
+      }
+
+      // ✅ Extract completion status from **Status**: [x] or [ ]
+      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: CompletionStatus): string {
+    return `✅ **User Story Verified Complete**
+
+**Completion Status**:
+- ✅ Acceptance Criteria: ${completion.acsCompleted}/${completion.acsTotal} (100%)
+- ✅ Implementation Tasks: ${completion.tasksCompleted}/${completion.tasksTotal} (100%)
+
+All work has been verified and completed. This issue is now closed.
+
+🤖 Auto-verified by SpecWeave AC Completion Gate`;
+  }
+
+  /**
+   * Build progress comment for GitHub issue update
+   *
+   * Used when issue stays open (not 100% complete)
+   */
+  buildProgressComment(completion: CompletionStatus): string {
+    const sections: string[] = [];
+
+    sections.push('📊 **Progress Update**');
+    sections.push('');
+
+    // AC progress
+    const acIcon = completion.acsPercentage === 100 ? '✅' : '🔄';
+    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('');
+
+    // Task progress
+    const taskIcon = completion.tasksPercentage === 100 ? '✅' : '🔄';
+    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('🤖 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: CompletionStatus,
+    reason: string = 'Work verification failed'
+  ): string {
+    const sections: string[] = [];
+
+    sections.push(`🔄 **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('⚠️ This issue cannot be closed until all ACs and tasks are verified complete.');
+    sections.push('');
+    sections.push('🤖 Auto-reopened by SpecWeave AC Completion Gate');
+
+    return sections.join('\n');
+  }
+}

package/plugins/specweave-github/lib/duplicate-detector.js

@@ -6,7 +6,7 @@ class DuplicateDetector {
    * Searches GitHub for existing issues matching the title pattern.
    * This is the PRIMARY defense against duplicates.
    *
-   * @param titlePattern - Pattern to search (e.g., "[FS-031]" or "[INC-0031]")
+   * @param titlePattern - Pattern to search (e.g., "[FS-031]" current, "[INC-0031]" deprecated)
    * @param incrementId - Optional increment ID for more precise matching
    * @param repo - Optional repo (format: "owner/repo")
    * @returns Existing issue if found, null otherwise
@@ -341,8 +341,8 @@ The original issue (#${keepIssueNumber}) should be used for tracking instead.
    * Utility: Extract title pattern from full title
    *
    * Examples:
-   * - "[FS-031] Feature Title" → "[FS-031]"
-   * - "[INC-0031] Increment Title" → "[INC-0031]"
+   * - "[FS-031] Feature Title" → "[FS-031]" (current format)
+   * - "[INC-0031] Increment Title" → "[INC-0031]" (deprecated, legacy support only)
    *
    * @param title - Full issue title
    * @returns Extracted pattern or null

package/plugins/specweave-github/lib/duplicate-detector.ts

@@ -63,7 +63,7 @@ export interface CorrectionResult {
 export interface CreateOptions {
   title: string;
   body: string;
-  titlePattern: string;  // e.g., "[FS-031]" or "[INC-0031]"
+  titlePattern: string;  // e.g., "[FS-031]" (current) or "[INC-0031]" (deprecated, legacy only)
   incrementId?: string;  // e.g., "0031-feature-name"
   labels?: string[];
   milestone?: string;
@@ -89,7 +89,7 @@ export class DuplicateDetector {
    * Searches GitHub for existing issues matching the title pattern.
    * This is the PRIMARY defense against duplicates.
    *
-   * @param titlePattern - Pattern to search (e.g., "[FS-031]" or "[INC-0031]")
+   * @param titlePattern - Pattern to search (e.g., "[FS-031]" current, "[INC-0031]" deprecated)
    * @param incrementId - Optional increment ID for more precise matching
    * @param repo - Optional repo (format: "owner/repo")
    * @returns Existing issue if found, null otherwise
@@ -498,8 +498,8 @@ The original issue (#${keepIssueNumber}) should be used for tracking instead.
    * Utility: Extract title pattern from full title
    *
    * Examples:
-   * - "[FS-031] Feature Title" → "[FS-031]"
-   * - "[INC-0031] Increment Title" → "[INC-0031]"
+   * - "[FS-031] Feature Title" → "[FS-031]" (current format)
+   * - "[INC-0031] Increment Title" → "[INC-0031]" (deprecated, legacy support only)
    *
    * @param title - Full issue title
    * @returns Extracted pattern or null