specweave 0.17.15 → 0.17.17

package/plugins/specweave-github/commands/specweave-github-sync-epic.md

@@ -0,0 +1,248 @@
+---
+name: specweave-github-sync-epic
+description: Sync SpecWeave Epic folder to GitHub (Milestone + Issues). Implements Universal Hierarchy architecture - Epic → Milestone, Increments → Issues.
+---
+
+# Sync Epic to GitHub (Universal Hierarchy)
+
+**Architecture**: Hierarchical sync using Epic folder structure
+
+- **Epic (FS-001)** → **GitHub Milestone**
+- **Increment (0001-core-framework)** → **GitHub Issue** (linked to Milestone)
+
+## Usage
+
+```bash
+/specweave-github:sync-epic <epic-id>
+```
+
+## What It Does
+
+**Hierarchical Sync Process**:
+
+1. **Load Epic folder** from `.specweave/docs/internal/specs/FS-XXX-name/`
+2. **Parse Epic README.md** to get Epic metadata (title, increments, status)
+3. **Create or update GitHub Milestone**:
+   - Title: `[FS-001] Epic Title`
+   - Description: Epic overview + progress stats
+   - State: Open (active/planning) or Closed (complete)
+4. **Sync each increment as GitHub Issue**:
+   - Title: `[INC-0001-core-framework] Title`
+   - Body: Increment overview + link to tasks.md
+   - Milestone: Linked to Epic Milestone
+   - Labels: `increment`, `epic-sync`
+5. **Update frontmatter** in Epic README.md and increment files
+
+## Examples
+
+### Sync Epic FS-001 (Core Framework Architecture)
+
+```bash
+/specweave-github:sync-epic FS-001
+```
+
+**Output**:
+```
+🔄 Syncing Epic FS-001 to GitHub...
+   📦 Epic: Core Framework Architecture
+   📊 Increments: 4
+   🚀 Creating GitHub Milestone...
+   ✅ Created Milestone #10
+
+   📝 Syncing 4 increments...
+   ✅ Created Issue #130 for 0001-core-framework
+   ✅ Created Issue #131 for 0002-core-enhancements
+   ✅ Created Issue #132 for 0004-plugin-architecture
+   ✅ Created Issue #133 for 0005-cross-platform-cli
+
+✅ Epic sync complete!
+   Milestone: https://github.com/owner/repo/milestone/10
+   Issues created: 4
+   Issues updated: 0
+```
+
+### Sync Epic with short ID
+
+```bash
+/specweave-github:sync-epic 031
+# Resolves to FS-031
+```
+
+### Re-sync Epic (updates existing Milestone/Issues)
+
+```bash
+/specweave-github:sync-epic FS-001
+```
+
+**Output**:
+```
+🔄 Syncing Epic FS-001 to GitHub...
+   ♻️  Updating existing Milestone #10...
+   ✅ Updated Milestone #10
+
+   📝 Syncing 4 increments...
+   ♻️  Updated Issue #130 for 0001-core-framework
+   ♻️  Updated Issue #131 for 0002-core-enhancements
+   ♻️  Updated Issue #132 for 0004-plugin-architecture
+   ♻️  Updated Issue #133 for 0005-cross-platform-cli
+
+✅ Epic sync complete!
+   Milestone: https://github.com/owner/repo/milestone/10
+   Issues created: 0
+   Issues updated: 4
+```
+
+## Arguments
+
+- `<epic-id>` - Epic ID (e.g., `FS-001` or just `001`)
+
+## What Gets Created
+
+### GitHub Milestone (Epic-level)
+
+```
+Title: [FS-001] Core Framework Architecture
+Description:
+  Epic: Core Framework Architecture
+
+  Progress: 4/4 increments (100%)
+
+  Priority: P0
+  Status: complete
+
+State: Closed (if complete) or Open (if active/planning)
+```
+
+### GitHub Issues (Increment-level)
+
+```markdown
+Title: [INC-0001-core-framework] Core Framework
+
+# Core Framework
+
+Foundation framework with CLI, plugin system, and agent architecture...
+
+---
+
+**Increment**: 0001-core-framework
+**Milestone**: See milestone for Epic progress
+
+🤖 Auto-created by SpecWeave Epic Sync
+```
+
+**Labels**: `increment`, `epic-sync`
+**Milestone**: Linked to Epic Milestone
+
+## Frontmatter Updates
+
+### Epic README.md (after sync)
+
+```yaml
+---
+id: FS-001
+title: "Core Framework Architecture"
+external_tools:
+  github:
+    type: milestone
+    id: 10                              # ← Added
+    url: https://github.com/.../milestone/10  # ← Added
+increments:
+  - id: 0001-core-framework
+    external:
+      github: 130                       # ← Added
+  - id: 0002-core-enhancements
+    external:
+      github: 131                       # ← Added
+---
+```
+
+### Increment file (0001-core-framework.md)
+
+```yaml
+---
+id: 0001-core-framework
+epic: FS-001
+external:
+  github:
+    issue: 130                          # ← Added
+    url: https://github.com/.../issues/130  # ← Added
+---
+```
+
+## Benefits
+
+✅ **Hierarchical tracking**: GitHub Milestones group related increments
+✅ **Epic-level progress**: See completion percentage in Milestone
+✅ **Automatic linking**: All Issues linked to Milestone
+✅ **Idempotent**: Safe to re-run (updates existing Milestone/Issues)
+✅ **Brownfield-ready**: Links existing GitHub Milestones/Issues
+
+## Requirements
+
+1. **GitHub CLI** (`gh`) installed and authenticated
+2. **Git repository** with GitHub remote
+3. **Write access** to repository (for creating Milestones/Issues)
+4. **Epic folder exists** at `.specweave/docs/internal/specs/FS-XXX-name/`
+
+## Architecture: Why Milestones?
+
+**GitHub's Hierarchy**:
+- GitHub Milestones = Epic-level grouping
+- GitHub Issues = Increment-level work items
+- GitHub Projects = Optional (cross-Epic tracking)
+
+**Comparison with JIRA/ADO**:
+- JIRA: Epic → Epic, Increment → Story (with Epic Link field)
+- ADO: Epic → Feature, Increment → User Story (with Parent link)
+- GitHub: Epic → Milestone, Increment → Issue (with Milestone link)
+
+All three implement the same Universal Hierarchy, just with different terminology.
+
+## Troubleshooting
+
+**"Epic FS-001 not found"**:
+- Check Epic folder exists: `ls .specweave/docs/internal/specs/`
+- Verify Epic ID format: `FS-001-epic-name/`
+
+**"Epic README.md missing YAML frontmatter"**:
+- Ensure Epic was migrated with `migrate-to-epic-folders.ts`
+- Frontmatter must start with `---` on line 1
+
+**"Failed to create GitHub Milestone"**:
+- Check GitHub CLI auth: `gh auth status`
+- Verify write access: `gh repo view`
+- Check rate limits: `gh api rate_limit`
+
+**"Could not extract issue number"**:
+- GitHub CLI output format may have changed
+- Check CLI version: `gh --version` (need v2.0.0+)
+
+## Related Commands
+
+- `/specweave-github:sync-spec` - OLD (flat spec → project) - DEPRECATED for Epic architecture
+- `/specweave-jira:sync-epic` - Sync to JIRA Epic + Stories
+- `/specweave-ado:sync-epic` - Sync to ADO Feature + User Stories
+
+## Implementation
+
+**File**: `plugins/specweave-github/lib/github-epic-sync.ts`
+
+**Core Class**: `GitHubEpicSync`
+
+**Methods**:
+- `syncEpicToGitHub(epicId)` - Main sync logic
+- `createMilestone(epic)` - Create GitHub Milestone
+- `updateMilestone(number, epic)` - Update existing Milestone
+- `createIssue(increment, milestone)` - Create GitHub Issue
+- `updateIssue(number, increment, milestone)` - Update existing Issue
+- `updateEpicReadme(path, github)` - Update frontmatter
+- `updateIncrementExternalLink(...)` - Update increment frontmatter
+
+## Next Steps
+
+After syncing Epic to GitHub:
+
+1. **View Milestone progress**: `gh milestone view 10`
+2. **List Issues in Milestone**: `gh issue list --milestone 10`
+3. **Track completion**: GitHub automatically calculates Milestone progress
+4. **Close Milestone**: When all increments complete, Milestone auto-closes

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

@@ -0,0 +1,370 @@
+import { execFileSync } from "child_process";
+class DuplicateDetector {
+  /**
+   * PHASE 1: Detection (Before Creating Issue)
+   *
+   * 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 incrementId - Optional increment ID for more precise matching
+   * @param repo - Optional repo (format: "owner/repo")
+   * @returns Existing issue if found, null otherwise
+   */
+  static async checkBeforeCreate(titlePattern, incrementId, repo) {
+    console.log(`\u{1F50D} DETECTION: Checking for existing issue with pattern: ${titlePattern}`);
+    try {
+      const args = [
+        "issue",
+        "list",
+        "--search",
+        `"${titlePattern}" in:title`,
+        "--json",
+        "number,title,url,body,createdAt",
+        "--limit",
+        "20",
+        "--state",
+        "all"
+        // Check both open and closed
+      ];
+      if (repo) {
+        args.push("--repo", repo);
+      }
+      const output = execFileSync("gh", args, { encoding: "utf-8" });
+      const issues = JSON.parse(output);
+      if (issues.length === 0) {
+        console.log("   \u2705 No existing issues found (safe to create)");
+        return null;
+      }
+      console.log(`   \u{1F4CB} Found ${issues.length} issue(s) matching pattern`);
+      const exactMatch = issues.find(
+        (issue) => issue.title.includes(titlePattern)
+      );
+      if (exactMatch) {
+        console.log(`   \u26A0\uFE0F  DUPLICATE DETECTED: Issue #${exactMatch.number}`);
+        console.log(`   \u{1F4CE} URL: ${exactMatch.url}`);
+        return exactMatch;
+      }
+      if (incrementId) {
+        const bodyMatch = issues.find(
+          (issue) => issue.body && (issue.body.includes(`**Increment**: ${incrementId}`) || issue.body.includes(incrementId))
+        );
+        if (bodyMatch) {
+          console.log(`   \u26A0\uFE0F  DUPLICATE DETECTED (body match): Issue #${bodyMatch.number}`);
+          console.log(`   \u{1F4CE} URL: ${bodyMatch.url}`);
+          return bodyMatch;
+        }
+      }
+      console.log("   \u2705 No exact match found (safe to create)");
+      return null;
+    } catch (error) {
+      console.warn(`   \u26A0\uFE0F  Detection failed (continuing anyway): ${error.message}`);
+      return null;
+    }
+  }
+  /**
+   * PHASE 2: Verification (After Creating Issue)
+   *
+   * Counts issues matching the pattern and identifies duplicates.
+   * This is the SECONDARY defense - catches duplicates that slipped through.
+   *
+   * @param titlePattern - Pattern to search (e.g., "[FS-031]")
+   * @param expectedCount - Expected number of issues (usually 1)
+   * @param repo - Optional repo (format: "owner/repo")
+   * @returns Verification result with duplicate list
+   */
+  static async verifyAfterCreate(titlePattern, expectedCount = 1, repo) {
+    console.log(`
+\u{1F50D} VERIFICATION: Checking issue count for pattern: ${titlePattern}`);
+    try {
+      const args = [
+        "issue",
+        "list",
+        "--search",
+        `"${titlePattern}" in:title`,
+        "--json",
+        "number,title,url,createdAt",
+        "--limit",
+        "50",
+        "--state",
+        "all"
+      ];
+      if (repo) {
+        args.push("--repo", repo);
+      }
+      const output = execFileSync("gh", args, { encoding: "utf-8" });
+      const issues = JSON.parse(output);
+      const exactMatches = issues.filter(
+        (issue) => issue.title.includes(titlePattern)
+      );
+      const actualCount = exactMatches.length;
+      console.log(`   Expected: ${expectedCount} issue(s)`);
+      console.log(`   Actual: ${actualCount} issue(s)`);
+      if (actualCount === expectedCount) {
+        console.log(`   \u2705 VERIFICATION PASSED: Count matches!`);
+        return {
+          success: true,
+          expectedCount,
+          actualCount,
+          duplicates: [],
+          message: "Verification passed"
+        };
+      } else if (actualCount > expectedCount) {
+        console.warn(`   \u26A0\uFE0F  VERIFICATION FAILED: ${actualCount - expectedCount} duplicate(s) detected!`);
+        const sorted = exactMatches.sort((a, b) => {
+          const dateA = new Date(a.createdAt || 0).getTime();
+          const dateB = new Date(b.createdAt || 0).getTime();
+          return dateA - dateB;
+        });
+        const duplicates = sorted.slice(1);
+        console.warn(`   \u{1F4CB} Duplicate issues:`);
+        duplicates.forEach((dup) => {
+          console.warn(`      - #${dup.number}: ${dup.title}`);
+        });
+        return {
+          success: false,
+          expectedCount,
+          actualCount,
+          duplicates,
+          message: `${duplicates.length} duplicate(s) found`
+        };
+      } else {
+        console.warn(`   \u26A0\uFE0F  VERIFICATION WARNING: Expected ${expectedCount} but found ${actualCount}`);
+        return {
+          success: false,
+          expectedCount,
+          actualCount,
+          duplicates: [],
+          message: "Count mismatch (fewer than expected)"
+        };
+      }
+    } catch (error) {
+      console.error(`   \u274C Verification failed: ${error.message}`);
+      return {
+        success: false,
+        expectedCount,
+        actualCount: -1,
+        duplicates: [],
+        message: `Verification error: ${error.message}`
+      };
+    }
+  }
+  /**
+   * PHASE 3: Reflection (Auto-Correct Duplicates)
+   *
+   * Automatically closes duplicate issues and keeps the oldest one.
+   * This is the CLEANUP phase - fixes problems that occurred.
+   *
+   * @param duplicates - List of duplicate issues to close
+   * @param keepIssueNumber - Issue number to keep (usually the oldest)
+   * @param repo - Optional repo (format: "owner/repo")
+   * @returns Correction result with count of closed issues
+   */
+  static async correctDuplicates(duplicates, keepIssueNumber, repo) {
+    if (duplicates.length === 0) {
+      return {
+        success: true,
+        duplicatesClosed: 0,
+        keptIssue: keepIssueNumber,
+        errors: []
+      };
+    }
+    console.log(`
+\u{1F527} REFLECTION: Auto-correcting ${duplicates.length} duplicate(s)...`);
+    const errors = [];
+    let closed = 0;
+    for (const duplicate of duplicates) {
+      try {
+        console.log(`   \u{1F5D1}\uFE0F  Closing duplicate #${duplicate.number}...`);
+        const comment = `Duplicate of #${keepIssueNumber}
+
+This issue was automatically closed by SpecWeave's Global Duplicate Detection System.
+
+The original issue (#${keepIssueNumber}) should be used for tracking instead.
+
+\u{1F916} Auto-closed by SpecWeave`;
+        const commentArgs = [
+          "issue",
+          "comment",
+          duplicate.number.toString(),
+          "--body",
+          comment
+        ];
+        if (repo) {
+          commentArgs.push("--repo", repo);
+        }
+        execFileSync("gh", commentArgs, { encoding: "utf-8" });
+        const closeArgs = [
+          "issue",
+          "close",
+          duplicate.number.toString()
+        ];
+        if (repo) {
+          closeArgs.push("--repo", repo);
+        }
+        execFileSync("gh", closeArgs, { encoding: "utf-8" });
+        console.log(`      \u2705 Closed #${duplicate.number}`);
+        closed++;
+      } catch (error) {
+        const errorMsg = `Failed to close #${duplicate.number}: ${error.message}`;
+        console.error(`      \u274C ${errorMsg}`);
+        errors.push(errorMsg);
+      }
+    }
+    console.log(`
+   \u2705 REFLECTION COMPLETE: Kept #${keepIssueNumber}, closed ${closed}/${duplicates.length} duplicate(s)`);
+    return {
+      success: errors.length === 0,
+      duplicatesClosed: closed,
+      keptIssue: keepIssueNumber,
+      errors
+    };
+  }
+  /**
+   * ALL-IN-ONE: Create Issue with Full Protection
+   *
+   * This is the RECOMMENDED way to create GitHub issues in SpecWeave.
+   * Combines all 3 phases: Detection → Creation → Verification → Reflection
+   *
+   * GUARANTEES:
+   * - No duplicates will be created
+   * - Existing duplicates will be detected and closed
+   * - Idempotent: can run multiple times safely
+   *
+   * @param options - Create options (title, body, labels, etc.)
+   * @returns Create result with issue details and duplicate stats
+   */
+  static async createWithProtection(options) {
+    const {
+      title,
+      body,
+      titlePattern,
+      incrementId,
+      labels = ["specweave"],
+      milestone,
+      assignees = [],
+      repo
+    } = options;
+    console.log(`
+\u{1F6E1}\uFE0F  Creating GitHub issue with FULL PROTECTION...`);
+    console.log(`   Title: ${title}`);
+    console.log(`   Pattern: ${titlePattern}`);
+    console.log(`
+\u2501\u2501\u2501 PHASE 1: DETECTION \u2501\u2501\u2501`);
+    const existing = await this.checkBeforeCreate(titlePattern, incrementId, repo);
+    let issueNumber;
+    let issueUrl;
+    let wasReused = false;
+    if (existing) {
+      console.log(`
+\u267B\uFE0F  Using existing issue #${existing.number} (skipping creation)`);
+      issueNumber = existing.number;
+      issueUrl = existing.url;
+      wasReused = true;
+    } else {
+      console.log(`
+\u2501\u2501\u2501 PHASE 2: CREATION \u2501\u2501\u2501`);
+      console.log(`   Creating new GitHub issue...`);
+      try {
+        const args = [
+          "issue",
+          "create",
+          "--title",
+          title,
+          "--body",
+          body
+        ];
+        if (repo) {
+          args.push("--repo", repo);
+        }
+        labels.forEach((label) => {
+          args.push("--label", label);
+        });
+        if (milestone) {
+          args.push("--milestone", milestone);
+        }
+        assignees.forEach((assignee) => {
+          args.push("--assignee", assignee);
+        });
+        const output = execFileSync("gh", args, { encoding: "utf-8" });
+        const match = output.match(/\/issues\/(\d+)/);
+        if (!match) {
+          throw new Error("Could not extract issue number from gh CLI output");
+        }
+        issueNumber = parseInt(match[1], 10);
+        issueUrl = output.trim();
+        console.log(`   \u2705 Created issue #${issueNumber}`);
+        console.log(`   \u{1F4CE} ${issueUrl}`);
+      } catch (error) {
+        throw new Error(`Failed to create GitHub issue: ${error.message}`);
+      }
+    }
+    console.log(`
+\u2501\u2501\u2501 PHASE 3: VERIFICATION \u2501\u2501\u2501`);
+    const verification = await this.verifyAfterCreate(titlePattern, 1, repo);
+    let duplicatesClosed = 0;
+    if (!verification.success && verification.duplicates.length > 0) {
+      console.log(`
+\u2501\u2501\u2501 PHASE 4: REFLECTION \u2501\u2501\u2501`);
+      console.warn(`   \u26A0\uFE0F  ${verification.duplicates.length} duplicate(s) detected!`);
+      const correction = await this.correctDuplicates(
+        verification.duplicates,
+        issueNumber,
+        repo
+      );
+      duplicatesClosed = correction.duplicatesClosed;
+      if (correction.errors.length > 0) {
+        console.warn(`   \u26A0\uFE0F  Some duplicates could not be closed:`);
+        correction.errors.forEach((err) => console.warn(`      - ${err}`));
+      }
+    } else if (verification.success) {
+      console.log(`   \u2705 No duplicates detected!`);
+    }
+    console.log(`
+\u2705 Issue creation complete!`);
+    console.log(`   Issue: #${issueNumber}`);
+    console.log(`   Duplicates found: ${verification.duplicates.length}`);
+    console.log(`   Duplicates closed: ${duplicatesClosed}`);
+    console.log(`   Reused existing: ${wasReused ? "Yes" : "No"}`);
+    return {
+      issue: {
+        number: issueNumber,
+        title,
+        url: issueUrl
+      },
+      duplicatesFound: verification.duplicates.length,
+      duplicatesClosed,
+      wasReused
+    };
+  }
+  /**
+   * Utility: Extract title pattern from full title
+   *
+   * Examples:
+   * - "[FS-031] Feature Title" → "[FS-031]"
+   * - "[INC-0031] Increment Title" → "[INC-0031]"
+   *
+   * @param title - Full issue title
+   * @returns Extracted pattern or null
+   */
+  static extractTitlePattern(title) {
+    const match = title.match(/^(\[[^\]]+\])/);
+    return match ? match[1] : null;
+  }
+  /**
+   * Utility: Check if GitHub CLI is available and authenticated
+   *
+   * @returns true if gh CLI is ready, false otherwise
+   */
+  static checkGitHubCLI() {
+    try {
+      execFileSync("gh", ["auth", "status"], { encoding: "utf-8" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+export {
+  DuplicateDetector
+};