specweave 0.18.0 → 0.20.0

package/plugins/specweave-github/lib/github-spec-content-sync.ts

@@ -20,6 +20,7 @@ import {
   SpecContent,
   ContentSyncResult,
 } from '../../../src/core/spec-content-sync.js';
+import { ProgressCommentBuilder } from './progress-comment-builder.js';
 import path from 'path';
 import fs from 'fs/promises';
 
@@ -215,6 +216,11 @@ async function createGitHubIssue(
 
 /**
  * Update existing GitHub issue with spec content
+ *
+ * ARCHITECTURE: IMMUTABLE DESCRIPTIONS (Phase 4)
+ * - Issue description is NEVER edited after creation
+ * - All content updates communicated via progress comments
+ * - Metadata updates only (labels, milestone, assignees)
  */
 async function updateGitHubIssue(
   client: GitHubClientV2,
@@ -262,36 +268,47 @@ async function updateGitHubIssue(
       }
     }
 
-    // Build updated content using compact format
-    const newTitle = `[${spec.identifier.compact}] ${spec.title}`;
-    const newBody = buildExternalDescription(spec);
-
     if (dryRun) {
-      console.log('\n🔍 Dry run - would update issue:');
-      console.log(`   Title: ${newTitle}`);
-      console.log(`   Body:\n${newBody}`);
+      console.log('\n🔍 Dry run - would post progress comment');
 
       return {
         success: true,
-        action: 'updated',
+        action: 'updated-via-comment',
         externalId: issueNumber.toString(),
         externalUrl: issue.html_url,
       };
     }
 
-    // Update issue (ONLY title and description, NOT status!)
-    await client.updateIssueBody(issueNumber, newBody);
+    // IMMUTABLE DESCRIPTION PATTERN:
+    // ❌ OLD: Update issue body (overwrites description)
+    // ✅ NEW: Post progress comment (preserves description)
 
-    // Note: We do NOT update status/state - that's managed in GitHub
-    // We also do NOT close/reopen issues - that's done by humans/automation in GitHub
+    // Update metadata only (labels via GitHub CLI - no direct API method)
+    const labels = [
+      'specweave',
+      'spec',
+      spec.project,
+      spec.metadata.priority || 'P2'
+    ].filter(Boolean);
+
+    await client.addLabels(issueNumber, labels);
+
+    // Post progress comment (NOT edit body)
+    await postProgressComment(
+      client,
+      specPath,
+      issueNumber,
+      spec,
+      verbose
+    );
 
     if (verbose) {
-      console.log(`✅ Updated issue #${issueNumber}`);
+      console.log(`✅ Posted progress comment to issue #${issueNumber}`);
     }
 
     return {
       success: true,
-      action: 'updated',
+      action: 'updated-via-comment',
       externalId: issueNumber.toString(),
       externalUrl: issue.html_url,
     };
@@ -304,6 +321,57 @@ async function updateGitHubIssue(
   }
 }
 
+/**
+ * Post progress comment to GitHub issue (IMMUTABLE DESCRIPTION PATTERN)
+ *
+ * This replaces the old pattern of editing issue body.
+ * Benefits:
+ * - Preserves original issue description
+ * - Creates audit trail of changes
+ * - Stakeholders get notifications on updates
+ */
+async function postProgressComment(
+  client: GitHubClientV2,
+  specPath: string,
+  issueNumber: number,
+  spec: SpecContent,
+  verbose: boolean = false
+): Promise<void> {
+  try {
+    // Extract increment ID from spec path or identifier
+    // Examples:
+    // - .specweave/increments/0031-external-tool-sync/spec.md → 0031
+    // - .specweave/docs/internal/specs/default/FS-031/us-001-*.md → FS-031
+
+    let incrementId = 'unknown';
+
+    // Try to extract from spec path
+    const incrementMatch = specPath.match(/increments\/([^/]+)/);
+    if (incrementMatch) {
+      incrementId = incrementMatch[1];
+    } else {
+      // Fallback: use spec identifier
+      incrementId = spec.identifier.compact;
+    }
+
+    // Build progress comment using ProgressCommentBuilder
+    const builder = new ProgressCommentBuilder(specPath);
+    const comment = await builder.buildProgressComment(incrementId);
+
+    // Post comment (using addComment method)
+    await client.addComment(issueNumber, comment);
+
+    if (verbose) {
+      console.log(`   📊 Progress comment posted (${comment.length} chars)`);
+    }
+  } catch (error: any) {
+    // Non-blocking: Log error but don't fail the sync
+    if (verbose) {
+      console.error(`   ⚠️  Failed to post progress comment: ${error.message}`);
+    }
+  }
+}
+
 /**
  * Count user stories in issue body
  */

package/plugins/specweave-github/lib/progress-comment-builder.js

@@ -0,0 +1,229 @@
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+class ProgressCommentBuilder {
+  constructor(userStoryPath, projectRoot = process.cwd()) {
+    this.userStoryPath = userStoryPath;
+    this.projectRoot = projectRoot;
+  }
+  /**
+   * Build complete progress comment
+   */
+  async buildProgressComment(incrementId) {
+    const summary = await this.calculateProgressSummary();
+    const frontmatter = await this.extractFrontmatter();
+    let comment = "";
+    comment += `\u{1F4CA} **Progress Update from Increment ${incrementId}**
+
+`;
+    comment += `**Status**: ${summary.statusSummary} (${summary.completedACs}/${summary.totalACs} AC implemented - ${summary.percentage}%)
+
+`;
+    if (summary.completedCriteria.length > 0) {
+      comment += `## \u2705 Completed Acceptance Criteria
+
+`;
+      for (const ac of summary.completedCriteria) {
+        const priority = ac.priority ? ` (${ac.priority})` : "";
+        const testable = ac.testable ? " [testable]" : "";
+        comment += `- [x] **${ac.id}**: ${ac.description}${priority}${testable}
+`;
+      }
+      comment += "\n";
+    }
+    if (summary.remainingCriteria.length > 0) {
+      const p1 = summary.remainingCriteria.filter((ac) => ac.priority === "P1");
+      const p2 = summary.remainingCriteria.filter((ac) => ac.priority === "P2");
+      const p3 = summary.remainingCriteria.filter((ac) => ac.priority === "P3");
+      if (p1.length > 0) {
+        comment += `## \u{1F534} Remaining Work (P1 - Critical)
+
+`;
+        for (const ac of p1) {
+          const testable = ac.testable ? " [testable]" : "";
+          comment += `- [ ] **${ac.id}**: ${ac.description} (P1)${testable}
+`;
+        }
+        comment += "\n";
+      }
+      if (p2.length > 0 || p3.length > 0) {
+        comment += `## \u23F3 Remaining Work (P2-P3)
+
+`;
+        for (const ac of [...p2, ...p3]) {
+          const priority = ac.priority ? ` (${ac.priority})` : "";
+          const testable = ac.testable ? " [testable]" : "";
+          comment += `- [ ] **${ac.id}**: ${ac.description}${priority}${testable}
+`;
+        }
+        comment += "\n";
+      }
+    }
+    if (summary.tasks.length > 0) {
+      const completedTasks = summary.tasks.filter((t) => t.status).length;
+      const totalTasks = summary.tasks.length;
+      comment += `## \u{1F4CB} Implementation Tasks (${completedTasks}/${totalTasks})
+
+`;
+      for (const task of summary.tasks) {
+        const checkbox = task.status ? "[x]" : "[ ]";
+        comment += `- ${checkbox} ${task.id}: ${task.title}
+`;
+      }
+      comment += "\n";
+    }
+    comment += `---
+
+`;
+    comment += `\u{1F916} Auto-synced by SpecWeave | `;
+    comment += `[View increment](../../increments/${incrementId}) | `;
+    comment += `${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}
+`;
+    return comment;
+  }
+  /**
+   * Calculate progress summary
+   */
+  async calculateProgressSummary() {
+    const content = await readFile(this.userStoryPath, "utf-8");
+    const acceptanceCriteria = this.extractAcceptanceCriteria(content);
+    const tasks = await this.extractTasks(content);
+    const completedCriteria = acceptanceCriteria.filter((ac) => ac.completed);
+    const remainingCriteria = acceptanceCriteria.filter((ac) => !ac.completed);
+    const totalACs = acceptanceCriteria.length;
+    const completedACs = completedCriteria.length;
+    const percentage = totalACs > 0 ? Math.round(completedACs / totalACs * 100) : 0;
+    let statusSummary = "In Progress";
+    if (completedACs === totalACs && totalACs > 0) {
+      statusSummary = "Complete";
+    } else if (completedACs > 0) {
+      const p1Criteria = acceptanceCriteria.filter((ac) => ac.priority === "P1");
+      const p1Completed = p1Criteria.filter((ac) => ac.completed).length;
+      if (p1Completed === p1Criteria.length && p1Criteria.length > 0) {
+        statusSummary = "Core Complete";
+      }
+    }
+    return {
+      totalACs,
+      completedACs,
+      percentage,
+      statusSummary,
+      completedCriteria,
+      remainingCriteria,
+      tasks
+    };
+  }
+  /**
+   * Format AC checkboxes (for inline display)
+   */
+  formatACCheckboxes() {
+    return "";
+  }
+  /**
+   * Format task checkboxes (for inline display)
+   */
+  formatTaskCheckboxes() {
+    return "";
+  }
+  /**
+   * Calculate progress percentage
+   */
+  async calculateProgressPercentage() {
+    const summary = await this.calculateProgressSummary();
+    return summary.percentage;
+  }
+  /**
+   * Extract frontmatter from user story file
+   */
+  async extractFrontmatter() {
+    const content = await readFile(this.userStoryPath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      throw new Error(`User story file missing YAML frontmatter: ${this.userStoryPath}`);
+    }
+    return yaml.parse(match[1]);
+  }
+  /**
+   * Extract acceptance criteria from content
+   */
+  extractAcceptanceCriteria(content) {
+    const criteria = [];
+    const acPattern = /- \[([ x])\] \*\*AC-US(\d+)-(\d+)\*\*:\s*([^(]+)(?:\(([^)]+)\))?/g;
+    let match;
+    while ((match = acPattern.exec(content)) !== null) {
+      const completed = match[1] === "x";
+      const usNumber = match[2];
+      const acNumber = match[3];
+      const description = match[4].trim();
+      const metadata = match[5] || "";
+      criteria.push({
+        id: `AC-US${usNumber}-${acNumber}`,
+        description,
+        completed,
+        priority: metadata.includes("P1") ? "P1" : metadata.includes("P2") ? "P2" : metadata.includes("P3") ? "P3" : "",
+        testable: metadata.includes("testable")
+      });
+    }
+    return criteria;
+  }
+  /**
+   * Extract tasks from Implementation section
+   */
+  async extractTasks(content) {
+    const tasks = [];
+    const incrementMatch = content.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 taskLinkPattern = /- \[([T-\d]+):\s*([^\]]+)\]/g;
+    let match;
+    while ((match = taskLinkPattern.exec(content)) !== null) {
+      const taskId = match[1];
+      const taskTitle = match[2].trim();
+      const taskPattern = new RegExp(`### ${taskId}[:\\s].*?\\n\\*\\*Status\\*\\*:\\s*\\[([x ]?)\\]`, "s");
+      const taskMatch = tasksContent.match(taskPattern);
+      const completed = taskMatch ? taskMatch[1] === "x" : false;
+      tasks.push({
+        id: taskId,
+        title: taskTitle,
+        status: completed
+      });
+    }
+    return tasks;
+  }
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length < 4) {
+    console.error("Usage: node progress-comment-builder.js --user-story <path> --increment <id>");
+    process.exit(1);
+  }
+  const userStoryPath = args[args.indexOf("--user-story") + 1];
+  const incrementId = args[args.indexOf("--increment") + 1];
+  const builder = new ProgressCommentBuilder(userStoryPath);
+  const comment = await builder.buildProgressComment(incrementId);
+  console.log(comment);
+}
+if (require.main === module) {
+  main().catch((error) => {
+    console.error("Error generating progress comment:", error.message);
+    process.exit(1);
+  });
+}
+export {
+  ProgressCommentBuilder,
+  main
+};

package/plugins/specweave-github/lib/progress-comment-builder.ts

@@ -0,0 +1,324 @@
+/**
+ * Progress Comment Builder - Generate progress update comments for GitHub issues
+ *
+ * Architecture:
+ * - Reads user story files from living docs
+ * - Extracts current AC completion status
+ * - Formats progress comment with checkboxes
+ * - Creates audit trail of changes over time
+ *
+ * Key Principle: IMMUTABLE DESCRIPTIONS
+ * - Issue description created once (snapshot)
+ * - All updates via progress comments (current state)
+ * - Complete audit trail preserved
+ */
+
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+
+interface UserStoryFrontmatter {
+  id: string;
+  epic: string;
+  title: string;
+  status: 'complete' | 'active' | 'planning' | 'not-started';
+  created: string;
+  completed?: string;
+}
+
+interface AcceptanceCriterion {
+  id: string; // AC-US4-01
+  description: string;
+  completed: boolean;
+  priority: string; // P1, P2, P3
+  testable: boolean;
+}
+
+interface Task {
+  id: string; // T-008
+  title: string;
+  status: boolean; // true = completed
+}
+
+export interface ProgressSummary {
+  totalACs: number;
+  completedACs: number;
+  percentage: number;
+  statusSummary: string; // "Core Complete", "Complete", "In Progress"
+  completedCriteria: AcceptanceCriterion[];
+  remainingCriteria: AcceptanceCriterion[];
+  tasks: Task[];
+}
+
+export class ProgressCommentBuilder {
+  private userStoryPath: string;
+  private projectRoot: string;
+
+  constructor(userStoryPath: string, projectRoot: string = process.cwd()) {
+    this.userStoryPath = userStoryPath;
+    this.projectRoot = projectRoot;
+  }
+
+  /**
+   * Build complete progress comment
+   */
+  async buildProgressComment(incrementId: string): Promise<string> {
+    const summary = await this.calculateProgressSummary();
+    const frontmatter = await this.extractFrontmatter();
+
+    let comment = '';
+
+    // Header
+    comment += `📊 **Progress Update from Increment ${incrementId}**\n\n`;
+    comment += `**Status**: ${summary.statusSummary} (${summary.completedACs}/${summary.totalACs} AC implemented - ${summary.percentage}%)\n\n`;
+
+    // Completed Acceptance Criteria
+    if (summary.completedCriteria.length > 0) {
+      comment += `## ✅ Completed Acceptance Criteria\n\n`;
+      for (const ac of summary.completedCriteria) {
+        const priority = ac.priority ? ` (${ac.priority})` : '';
+        const testable = ac.testable ? ' [testable]' : '';
+        comment += `- [x] **${ac.id}**: ${ac.description}${priority}${testable}\n`;
+      }
+      comment += '\n';
+    }
+
+    // Remaining Work
+    if (summary.remainingCriteria.length > 0) {
+      // Group by priority
+      const p1 = summary.remainingCriteria.filter(ac => ac.priority === 'P1');
+      const p2 = summary.remainingCriteria.filter(ac => ac.priority === 'P2');
+      const p3 = summary.remainingCriteria.filter(ac => ac.priority === 'P3');
+
+      if (p1.length > 0) {
+        comment += `## 🔴 Remaining Work (P1 - Critical)\n\n`;
+        for (const ac of p1) {
+          const testable = ac.testable ? ' [testable]' : '';
+          comment += `- [ ] **${ac.id}**: ${ac.description} (P1)${testable}\n`;
+        }
+        comment += '\n';
+      }
+
+      if (p2.length > 0 || p3.length > 0) {
+        comment += `## ⏳ Remaining Work (P2-P3)\n\n`;
+        for (const ac of [...p2, ...p3]) {
+          const priority = ac.priority ? ` (${ac.priority})` : '';
+          const testable = ac.testable ? ' [testable]' : '';
+          comment += `- [ ] **${ac.id}**: ${ac.description}${priority}${testable}\n`;
+        }
+        comment += '\n';
+      }
+    }
+
+    // Tasks (if any)
+    if (summary.tasks.length > 0) {
+      const completedTasks = summary.tasks.filter(t => t.status).length;
+      const totalTasks = summary.tasks.length;
+      comment += `## 📋 Implementation Tasks (${completedTasks}/${totalTasks})\n\n`;
+
+      for (const task of summary.tasks) {
+        const checkbox = task.status ? '[x]' : '[ ]';
+        comment += `- ${checkbox} ${task.id}: ${task.title}\n`;
+      }
+      comment += '\n';
+    }
+
+    // Footer
+    comment += `---\n\n`;
+    comment += `🤖 Auto-synced by SpecWeave | `;
+    comment += `[View increment](../../increments/${incrementId}) | `;
+    comment += `${new Date().toISOString().split('T')[0]}\n`;
+
+    return comment;
+  }
+
+  /**
+   * Calculate progress summary
+   */
+  async calculateProgressSummary(): Promise<ProgressSummary> {
+    const content = await readFile(this.userStoryPath, 'utf-8');
+    const acceptanceCriteria = this.extractAcceptanceCriteria(content);
+    const tasks = await this.extractTasks(content);
+
+    const completedCriteria = acceptanceCriteria.filter(ac => ac.completed);
+    const remainingCriteria = acceptanceCriteria.filter(ac => !ac.completed);
+
+    const totalACs = acceptanceCriteria.length;
+    const completedACs = completedCriteria.length;
+    const percentage = totalACs > 0 ? Math.round((completedACs / totalACs) * 100) : 0;
+
+    // Determine status summary
+    let statusSummary = 'In Progress';
+    if (completedACs === totalACs && totalACs > 0) {
+      statusSummary = 'Complete';
+    } else if (completedACs > 0) {
+      // Check if all P1 are done
+      const p1Criteria = acceptanceCriteria.filter(ac => ac.priority === 'P1');
+      const p1Completed = p1Criteria.filter(ac => ac.completed).length;
+      if (p1Completed === p1Criteria.length && p1Criteria.length > 0) {
+        statusSummary = 'Core Complete';
+      }
+    }
+
+    return {
+      totalACs,
+      completedACs,
+      percentage,
+      statusSummary,
+      completedCriteria,
+      remainingCriteria,
+      tasks,
+    };
+  }
+
+  /**
+   * Format AC checkboxes (for inline display)
+   */
+  formatACCheckboxes(): string {
+    // This method is for simple inline formatting
+    // The full buildProgressComment does structured formatting
+    return ''; // Placeholder for CLI usage if needed
+  }
+
+  /**
+   * Format task checkboxes (for inline display)
+   */
+  formatTaskCheckboxes(): string {
+    // This method is for simple inline formatting
+    // The full buildProgressComment does structured formatting
+    return ''; // Placeholder for CLI usage if needed
+  }
+
+  /**
+   * Calculate progress percentage
+   */
+  async calculateProgressPercentage(): Promise<number> {
+    const summary = await this.calculateProgressSummary();
+    return summary.percentage;
+  }
+
+  /**
+   * Extract frontmatter from user story file
+   */
+  private async extractFrontmatter(): Promise<UserStoryFrontmatter> {
+    const content = await readFile(this.userStoryPath, 'utf-8');
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+
+    if (!match) {
+      throw new Error(`User story file missing YAML frontmatter: ${this.userStoryPath}`);
+    }
+
+    return yaml.parse(match[1]) as UserStoryFrontmatter;
+  }
+
+  /**
+   * Extract acceptance criteria from content
+   */
+  private extractAcceptanceCriteria(content: string): AcceptanceCriterion[] {
+    const criteria: AcceptanceCriterion[] = [];
+
+    // Pattern: - [x] **AC-US4-01**: Description (P1, testable)
+    const acPattern =
+      /- \[([ x])\] \*\*AC-US(\d+)-(\d+)\*\*:\s*([^(]+)(?:\(([^)]+)\))?/g;
+
+    let match;
+    while ((match = acPattern.exec(content)) !== null) {
+      const completed = match[1] === 'x';
+      const usNumber = match[2];
+      const acNumber = match[3];
+      const description = match[4].trim();
+      const metadata = match[5] || '';
+
+      criteria.push({
+        id: `AC-US${usNumber}-${acNumber}`,
+        description,
+        completed,
+        priority: metadata.includes('P1') ? 'P1' : metadata.includes('P2') ? 'P2' : metadata.includes('P3') ? 'P3' : '',
+        testable: metadata.includes('testable'),
+      });
+    }
+
+    return criteria;
+  }
+
+  /**
+   * Extract tasks from Implementation section
+   */
+  private async extractTasks(content: string): Promise<Task[]> {
+    const tasks: Task[] = [];
+
+    // Extract increment ID from Implementation section
+    const incrementMatch = content.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
+    if (!incrementMatch) {
+      return tasks; // No increment linked
+    }
+
+    const incrementId = incrementMatch[1];
+
+    // Find tasks.md file
+    const tasksPath = path.join(
+      this.projectRoot,
+      '.specweave',
+      'increments',
+      incrementId,
+      'tasks.md'
+    );
+
+    if (!existsSync(tasksPath)) {
+      return tasks; // Tasks file not found
+    }
+
+    const tasksContent = await readFile(tasksPath, 'utf-8');
+
+    // Extract task links from user story (e.g., - [T-001: Title](link))
+    const taskLinkPattern = /- \[([T-\d]+):\s*([^\]]+)\]/g;
+    let match;
+
+    while ((match = taskLinkPattern.exec(content)) !== null) {
+      const taskId = match[1];
+      const taskTitle = match[2].trim();
+
+      // Check if task is completed in tasks.md
+      const taskPattern = new RegExp(`### ${taskId}[:\\s].*?\\n\\*\\*Status\\*\\*:\\s*\\[([x ]?)\\]`, 's');
+      const taskMatch = tasksContent.match(taskPattern);
+      const completed = taskMatch ? taskMatch[1] === 'x' : false;
+
+      tasks.push({
+        id: taskId,
+        title: taskTitle,
+        status: completed,
+      });
+    }
+
+    return tasks;
+  }
+}
+
+/**
+ * CLI entry point for generating progress comments
+ */
+export async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length < 4) {
+    console.error('Usage: node progress-comment-builder.js --user-story <path> --increment <id>');
+    process.exit(1);
+  }
+
+  const userStoryPath = args[args.indexOf('--user-story') + 1];
+  const incrementId = args[args.indexOf('--increment') + 1];
+
+  const builder = new ProgressCommentBuilder(userStoryPath);
+  const comment = await builder.buildProgressComment(incrementId);
+
+  console.log(comment);
+}
+
+// Run if called directly
+if (require.main === module) {
+  main().catch((error) => {
+    console.error('Error generating progress comment:', error.message);
+    process.exit(1);
+  });
+}