specweave 0.17.16 → 0.17.19

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

@@ -20,8 +20,9 @@ import {
   ContentSyncResult,
 } from '../../../src/core/spec-content-sync.js';
 import { SyncProfile } from '../../../src/core/types/sync-profile.js';
-import path from 'path';
-import fs from 'fs/promises';
+import { SpecIncrementMapper, TaskInfo } from '../../../src/core/sync/spec-increment-mapper.js';
+import * as path from 'path';
+import * as fs from 'fs/promises';
 
 export interface AdoContentSyncOptions {
   specPath: string;
@@ -91,9 +92,12 @@ async function createAdoFeature(
   const { specPath, dryRun, verbose } = options;
 
   try {
+    // Get task mappings (if available)
+    const tasks = await getTaskMappings(specPath, spec.id);
+
     // Build feature title and description
     const title = `[${spec.id.toUpperCase()}] ${spec.title}`;
-    const description = buildAdoDescription(spec);
+    const description = buildAdoDescription(spec, tasks);
 
     if (verbose) {
       console.log(`\n📝 Creating ADO feature:`);
@@ -196,9 +200,12 @@ async function updateAdoFeature(
       }
     }
 
+    // Get task mappings (if available)
+    const tasks = await getTaskMappings(specPath, spec.id);
+
     // Build updated content
     const newTitle = `[${spec.id.toUpperCase()}] ${spec.title}`;
-    const newDescription = buildAdoDescription(spec);
+    const newDescription = buildAdoDescription(spec, tasks);
 
     if (dryRun) {
       console.log('\n🔍 Dry run - would update feature:');
@@ -242,10 +249,10 @@ async function updateAdoFeature(
 }
 
 /**
- * Build ADO description from spec content
+ * Build ADO description from spec content with optional task mappings
  * ADO supports HTML in description
  */
-function buildAdoDescription(spec: SpecContent): string {
+function buildAdoDescription(spec: SpecContent, tasks?: TaskInfo[]): string {
   let html = '';
 
   // Add spec description
@@ -271,6 +278,20 @@ function buildAdoDescription(spec: SpecContent): string {
     }
   }
 
+  // Add task mappings (if provided)
+  if (tasks && tasks.length > 0) {
+    html += '<h2>Implementation Tasks</h2>';
+    html += '<ul>';
+    for (const task of tasks) {
+      html += `<li><strong>${task.id}</strong>: ${escapeHtml(task.title)}`;
+      if (task.userStories && task.userStories.length > 0) {
+        html += ` (${task.userStories.join(', ')})`;
+      }
+      html += '</li>';
+    }
+    html += '</ul>';
+  }
+
   // Add metadata
   if (spec.metadata.priority) {
     html += `<p><strong>Priority:</strong> ${spec.metadata.priority}</p>`;
@@ -279,6 +300,51 @@ function buildAdoDescription(spec: SpecContent): string {
   return html;
 }
 
+/**
+ * Get task mappings for a spec (if available)
+ */
+async function getTaskMappings(specPath: string, specId: string): Promise<TaskInfo[] | undefined> {
+  try {
+    // Find SpecWeave root
+    const rootDir = await findSpecWeaveRoot(specPath);
+
+    // Use SpecIncrementMapper to get task mappings
+    const mapper = new SpecIncrementMapper(rootDir);
+    const mapping = await mapper.mapSpecToIncrements(specId);
+
+    if (mapping.increments.length > 0) {
+      // Return tasks from the first (most recent) increment
+      return mapping.increments[0].tasks;
+    }
+
+    return undefined;
+  } catch (error) {
+    // If mapping fails, just return undefined (not critical)
+    return undefined;
+  }
+}
+
+/**
+ * Find SpecWeave root directory from spec path
+ */
+async function findSpecWeaveRoot(specPath: string): Promise<string> {
+  let currentDir = path.dirname(specPath);
+
+  while (true) {
+    const specweaveDir = path.join(currentDir, '.specweave');
+    try {
+      await fs.access(specweaveDir);
+      return currentDir;
+    } catch {
+      const parentDir = path.dirname(currentDir);
+      if (parentDir === currentDir) {
+        throw new Error('.specweave directory not found');
+      }
+      currentDir = parentDir;
+    }
+  }
+}
+
 /**
  * Escape HTML special characters
  */

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

@@ -0,0 +1,80 @@
+import axios from "axios";
+class AdoStatusSync {
+  constructor(organization, project, personalAccessToken) {
+    this.organization = organization;
+    this.project = project;
+    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) {
+    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, status) {
+    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, oldStatus, newStatus) {
+    const text = `\u{1F504} Status Update
+
+SpecWeave status changed:
+\u2022 From: ${oldStatus}
+\u2022 To: ${newStatus}
+\u2022 When: ${(/* @__PURE__ */ new Date()).toISOString()}
+
+Synced from SpecWeave`;
+    await this.client.post(
+      `/wit/workitems/${workItemId}/comments?api-version=7.0-preview.3`,
+      {
+        text
+      }
+    );
+  }
+}
+export {
+  AdoStatusSync
+};

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-ado/lib/enhanced-ado-sync.js

@@ -0,0 +1,170 @@
+import { AdoClientV2 } from "./ado-client-v2.js";
+import { EnhancedContentBuilder } from "../../../src/core/sync/enhanced-content-builder.js";
+import { SpecIncrementMapper } from "../../../src/core/sync/spec-increment-mapper.js";
+import { parseSpecContent } from "../../../src/core/spec-content-sync.js";
+import path from "path";
+import fs from "fs/promises";
+async function syncSpecToAdoWithEnhancedContent(options) {
+  const { specPath, organization, project, dryRun = false, verbose = false } = options;
+  try {
+    const baseSpec = await parseSpecContent(specPath);
+    if (!baseSpec) {
+      return {
+        success: false,
+        action: "error",
+        error: "Failed to parse spec content"
+      };
+    }
+    if (verbose) {
+      console.log(`\u{1F4C4} Parsed spec: ${baseSpec.identifier.compact}`);
+    }
+    const specId = baseSpec.identifier.full || baseSpec.identifier.compact;
+    const rootDir = await findSpecWeaveRoot(specPath);
+    const mapper = new SpecIncrementMapper(rootDir);
+    const mapping = await mapper.mapSpecToIncrements(specId);
+    if (verbose) {
+      console.log(`\u{1F517} Found ${mapping.increments.length} related increments`);
+    }
+    const taskMapping = buildTaskMapping(mapping.increments, organization, project);
+    const architectureDocs = await findArchitectureDocs(rootDir, specId);
+    const enhancedSpec = {
+      ...baseSpec,
+      summary: baseSpec.description,
+      taskMapping,
+      architectureDocs
+    };
+    const builder = new EnhancedContentBuilder();
+    const description = builder.buildExternalDescription(enhancedSpec);
+    if (verbose) {
+      console.log(`\u{1F4DD} Generated description: ${description.length} characters`);
+    }
+    if (dryRun) {
+      console.log("\u{1F50D} DRY RUN - Would create/update feature with:");
+      console.log(`   Title: ${baseSpec.title}`);
+      console.log(`   Description length: ${description.length}`);
+      return {
+        success: true,
+        action: "no-change",
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    }
+    if (!organization || !project) {
+      return {
+        success: false,
+        action: "error",
+        error: "Azure DevOps organization/project not specified"
+      };
+    }
+    const profile = {
+      provider: "ado",
+      displayName: `${organization}/${project}`,
+      config: {
+        organization,
+        project
+      },
+      timeRange: { default: "1M", max: "6M" }
+    };
+    const pat = process.env.AZURE_DEVOPS_PAT || "";
+    const client = new AdoClientV2(profile, pat);
+    const existingFeature = await findExistingFeature(client, baseSpec.identifier.compact);
+    let result;
+    if (existingFeature) {
+      await client.updateWorkItem(existingFeature.id, {
+        title: `[${baseSpec.identifier.compact}] ${baseSpec.title}`,
+        description
+      });
+      result = {
+        success: true,
+        action: "updated",
+        featureId: existingFeature.id,
+        featureUrl: `https://dev.azure.com/${organization}/${project}/_workitems/edit/${existingFeature.id}`,
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    } else {
+      const feature = await client.createEpic({
+        title: `[${baseSpec.identifier.compact}] ${baseSpec.title}`,
+        description,
+        tags: ["spec", "external-tool-sync"]
+      });
+      result = {
+        success: true,
+        action: "created",
+        featureId: feature.id,
+        featureUrl: `https://dev.azure.com/${organization}/${project}/_workitems/edit/${feature.id}`,
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    }
+    if (verbose) {
+      console.log(`\u2705 ${result.action === "created" ? "Created" : "Updated"} feature #${result.featureId}`);
+    }
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      action: "error",
+      error: error.message
+    };
+  }
+}
+async function findSpecWeaveRoot(specPath) {
+  let currentDir = path.dirname(specPath);
+  while (true) {
+    const specweaveDir = path.join(currentDir, ".specweave");
+    try {
+      await fs.access(specweaveDir);
+      return currentDir;
+    } catch {
+      const parentDir = path.dirname(currentDir);
+      if (parentDir === currentDir) {
+        throw new Error(".specweave directory not found");
+      }
+      currentDir = parentDir;
+    }
+  }
+}
+function buildTaskMapping(increments, organization, project) {
+  if (increments.length === 0) return void 0;
+  const firstIncrement = increments[0];
+  const tasks = firstIncrement.tasks.map((task) => ({
+    id: task.id,
+    title: task.title,
+    userStories: task.userStories
+  }));
+  return {
+    incrementId: firstIncrement.id,
+    tasks,
+    tasksUrl: `https://dev.azure.com/${organization}/${project}/_git/repo?path=/.specweave/increments/${firstIncrement.id}/tasks.md`
+  };
+}
+async function findArchitectureDocs(rootDir, specId) {
+  const docs = [];
+  const archDir = path.join(rootDir, ".specweave/docs/internal/architecture");
+  try {
+    const adrDir = path.join(archDir, "adr");
+    try {
+      const adrs = await fs.readdir(adrDir);
+      const relatedAdrs = adrs.filter((file) => file.includes(specId.replace("spec-", "")));
+      for (const adr of relatedAdrs) {
+        docs.push({
+          type: "adr",
+          path: path.join(adrDir, adr),
+          title: adr.replace(".md", "").replace(/-/g, " ")
+        });
+      }
+    } catch {
+    }
+  } catch {
+  }
+  return docs;
+}
+async function findExistingFeature(client, specId) {
+  try {
+    const features = await client.queryWorkItems(`[System.Title] Contains '[${specId}]' AND [System.WorkItemType] = 'Feature'`);
+    return features[0] || null;
+  } catch {
+    return null;
+  }
+}
+export {
+  syncSpecToAdoWithEnhancedContent
+};

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.