specweave 0.17.15 → 0.18.0

package/plugins/specweave-ado/lib/ado-status-sync.ts

@@ -0,0 +1,121 @@
+/**
+ * Azure DevOps Status Sync
+ *
+ * Synchronizes SpecWeave increment statuses with ADO work item states.
+ *
+ * ADO Work Item State Updates:
+ * - Uses JSON Patch format for updates
+ * - System.State field controls work item state
+ * - Available states: New, Active, On Hold, Resolved, Closed, Removed
+ *
+ * @module ado-status-sync
+ */
+
+import axios, { AxiosInstance } from 'axios';
+
+/**
+ * External status representation (ADO-specific)
+ */
+export interface ExternalStatus {
+  state: string; // e.g., "New", "Active", "Closed"
+}
+
+/**
+ * Azure DevOps Status Sync
+ *
+ * Handles status synchronization with ADO work items.
+ */
+export class AdoStatusSync {
+  private client: AxiosInstance;
+  private organization: string;
+  private project: string;
+
+  constructor(
+    organization: string,
+    project: string,
+    personalAccessToken: string
+  ) {
+    this.organization = organization;
+    this.project = project;
+
+    // Create ADO API client
+    this.client = axios.create({
+      baseURL: `https://dev.azure.com/${organization}/${project}/_apis`,
+      auth: {
+        username: '', // Empty for PAT auth
+        password: personalAccessToken
+      },
+      headers: {
+        'Content-Type': 'application/json-patch+json',
+        'Accept': 'application/json'
+      }
+    });
+  }
+
+  /**
+   * Get current status from ADO work item
+   *
+   * @param workItemId - ADO work item ID (e.g., 123)
+   * @returns Current work item state
+   */
+  async getStatus(workItemId: number): Promise<ExternalStatus> {
+    const response = await this.client.get(
+      `/wit/workitems/${workItemId}?api-version=7.0`
+    );
+
+    return {
+      state: response.data.fields['System.State']
+    };
+  }
+
+  /**
+   * Update ADO work item state
+   *
+   * Uses JSON Patch format to update System.State field.
+   *
+   * @param workItemId - ADO work item ID (e.g., 123)
+   * @param status - Desired status
+   */
+  async updateStatus(workItemId: number, status: ExternalStatus): Promise<void> {
+    // ADO uses JSON Patch format for updates
+    const patch = [
+      {
+        op: 'add',
+        path: '/fields/System.State',
+        value: status.state
+      }
+    ];
+
+    await this.client.patch(
+      `/wit/workitems/${workItemId}?api-version=7.0`,
+      patch
+    );
+  }
+
+  /**
+   * Post comment about status change to ADO work item
+   *
+   * @param workItemId - ADO work item ID (e.g., 123)
+   * @param oldStatus - Previous SpecWeave status
+   * @param newStatus - New SpecWeave status
+   */
+  async postStatusComment(
+    workItemId: number,
+    oldStatus: string,
+    newStatus: string
+  ): Promise<void> {
+    const text = `🔄 Status Update\n\n` +
+      `SpecWeave status changed:\n` +
+      `• From: ${oldStatus}\n` +
+      `• To: ${newStatus}\n` +
+      `• When: ${new Date().toISOString()}\n\n` +
+      `Synced from SpecWeave`;
+
+    await this.client.post(
+      `/wit/workitems/${workItemId}/comments?api-version=7.0-preview.3`,
+      {
+        text
+      }
+    );
+  }
+}

package/plugins/specweave-github/commands/specweave-github-cleanup-duplicates.md

@@ -0,0 +1,205 @@
+---
+name: specweave-github-cleanup-duplicates
+description: Clean up duplicate GitHub issues for an Epic. Finds issues with duplicate titles and closes all except the first created issue.
+---
+
+# Clean Up Duplicate GitHub Issues
+
+**CRITICAL**: This command detects and closes duplicate GitHub issues created by multiple syncs.
+
+## Usage
+
+```bash
+/specweave-github:cleanup-duplicates <epic-id> [--dry-run]
+```
+
+## What It Does
+
+**Duplicate Detection & Cleanup**:
+
+1. **Find all issues** for the Epic (searches by Epic ID in title)
+2. **Group by title** (detect duplicates)
+3. **For each duplicate group**:
+   - Keep the **FIRST created** issue (lowest number)
+   - Close all **LATER** issues with comment: "Duplicate of #XXX"
+4. **Update Epic README** with correct issue numbers
+
+## Examples
+
+### Dry Run (No Changes)
+
+```bash
+/specweave-github:cleanup-duplicates FS-031 --dry-run
+```
+
+**Output**:
+```
+🔍 Scanning for duplicates in Epic FS-031...
+   Found 25 total issues
+   Detected 10 duplicate groups:
+
+   📋 Group 1: "[FS-031] External Tool Status Synchronization"
+      - #250 (KEEP) - Created 2025-11-10
+      - #255 (CLOSE) - Created 2025-11-11 - DUPLICATE
+      - #260 (CLOSE) - Created 2025-11-12 - DUPLICATE
+
+   📋 Group 2: "[FS-031] Multi-Project GitHub Sync"
+      - #251 (KEEP) - Created 2025-11-10
+      - #256 (CLOSE) - Created 2025-11-11 - DUPLICATE
+
+   ...
+
+✅ Dry run complete!
+   Total issues: 25
+   Duplicate groups: 10
+   Issues to close: 15
+
+⚠️  This was a DRY RUN - no changes made.
+   Run without --dry-run to actually close duplicates.
+```
+
+### Actual Cleanup
+
+```bash
+/specweave-github:cleanup-duplicates FS-031
+```
+
+**Output**:
+```
+🔍 Scanning for duplicates in Epic FS-031...
+   Found 25 total issues
+   Detected 10 duplicate groups
+
+⚠️  CONFIRM: Close 15 duplicate issues? [y/N]
+> y
+
+🗑️  Closing duplicates...
+   ✅ Closed #255 (duplicate of #250)
+   ✅ Closed #256 (duplicate of #251)
+   ✅ Closed #260 (duplicate of #250)
+   ...
+
+📝 Updating Epic README frontmatter...
+   ✅ Updated frontmatter with correct issue numbers
+
+✅ Cleanup complete!
+   Closed: 15 duplicates
+   Kept: 10 original issues
+```
+
+## Arguments
+
+- `<epic-id>` - Epic ID (e.g., `FS-031` or just `031`)
+- `--dry-run` - Preview changes without actually closing issues (optional)
+
+## Safety Features
+
+✅ **Confirmation prompt**: Asks before closing issues (unless --dry-run)
+✅ **Dry run mode**: Preview changes safely
+✅ **Keeps oldest issue**: Preserves the first created issue
+✅ **Adds closure comment**: Links to the original issue
+✅ **Updates metadata**: Fixes Epic README frontmatter
+
+## What Gets Closed
+
+**Closed issues**:
+- ✅ Duplicate titles (second, third, etc. occurrences)
+- ✅ Closed with comment: "Duplicate of #XXX"
+- ✅ Original issue kept open (or maintains its status)
+
+**Example comment on closed duplicate**:
+```markdown
+Duplicate of #250
+
+This issue was automatically closed by SpecWeave cleanup because it is a duplicate.
+
+The original issue (#250) contains the same content and should be used for tracking instead.
+
+🤖 Auto-closed by SpecWeave Duplicate Cleanup
+```
+
+## Requirements
+
+1. **GitHub CLI** (`gh`) installed and authenticated
+2. **Write access** to repository (for closing issues)
+3. **Epic folder exists** at `.specweave/docs/internal/specs/FS-XXX-name/`
+
+## When to Use
+
+**Use this command when**:
+- ✅ You see multiple issues with the same title in GitHub
+- ✅ Epic sync ran multiple times and created duplicates
+- ✅ Epic README frontmatter got corrupted and reset
+- ✅ Post-sync validation warns about duplicates
+
+**Example warning that triggers this**:
+```
+⚠️  WARNING: 10 duplicate(s) detected!
+   Run cleanup command to resolve:
+   /specweave-github:cleanup-duplicates FS-031
+```
+
+## Troubleshooting
+
+**"No duplicates found"**:
+- Good! Your Epic has no duplicate issues
+- Run epic sync is working correctly with duplicate detection
+
+**"GitHub CLI not authenticated"**:
+- Run: `gh auth login`
+- Ensure you have write access to the repository
+
+**"Could not find Epic folder"**:
+- Check Epic exists: `ls .specweave/docs/internal/specs/`
+- Verify Epic ID format: `FS-031-epic-name/`
+
+**"Error closing issue"**:
+- Check GitHub CLI: `gh auth status`
+- Verify write permissions: `gh repo view`
+
+## Architecture
+
+**Duplicate Detection Logic**:
+1. Group issues by **exact title match**
+2. Within each group, sort by **issue number** (ascending)
+3. Keep **first issue** (lowest number = oldest)
+4. Close **all others** as duplicates
+
+**Why lowest number?**:
+- Lower issue numbers were created first
+- Preserves chronological order
+- Maintains links from old documentation
+
+## Related Commands
+
+- `/specweave-github:sync-epic` - Sync Epic (now with duplicate detection!)
+- `/specweave:validate` - Validate increment completeness
+- `gh issue list` - View all issues (GitHub CLI)
+
+## Implementation
+
+**File**: `plugins/specweave-github/lib/github-epic-sync.ts`
+
+**Method**: `cleanupDuplicates(epicId: string, dryRun: boolean)`
+
+**Algorithm**:
+1. Search GitHub for all issues with Epic ID
+2. Group by title (Map<string, number[]>)
+3. Filter groups with >1 issue (duplicates)
+4. For each duplicate group:
+   - Keep first issue (lowest number)
+   - Close others with gh CLI
+5. Update Epic README frontmatter
+
+## Next Steps
+
+After cleanup:
+
+1. **Verify cleanup**: `gh issue list --search "[FS-031]"`
+2. **Check Epic README**: Verify frontmatter has correct issue numbers
+3. **Re-run sync**: `/specweave-github:sync-epic FS-031` (should show no duplicates)
+4. **Enable duplicate detection**: Already enabled in v0.18.0+
+
+---
+
+**✅ SAFE TO USE**: This command is idempotent and safe to run multiple times.

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