specweave 0.32.0 → 0.32.3

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

@@ -0,0 +1,212 @@
+---
+name: specweave-ado:cleanup-duplicates
+description: Clean up duplicate Azure DevOps work items for a Feature. Finds work items with duplicate titles and closes all except the first created item.
+justification: |
+  CRITICAL INCIDENT RESPONSE TOOL - DO NOT DELETE!
+
+  Why This Command Exists:
+  - Prevention systems work for single-process execution
+  - Multiple parallel Claude Code instances bypass all prevention (file-based cache, no distributed locking)
+  - ADO API race conditions: Time gap between "check exists" and "create work item" allows duplicates
+  - Historical duplicates from pre-v0.33.0 users (before prevention was added)
+
+  Evidence of Need:
+  - GitHub had 123 duplicate issues incident (cleaned to 29 unique) - same risk exists for ADO
+  - Parallel execution creates race conditions that prevention CANNOT solve
+  - Industry standard: Prevention + Detection + Cleanup (defense in depth)
+
+  When to Delete:
+  - ONLY if distributed locking implemented
+  - AND parallel execution tested (100+ concurrent syncs with zero duplicates)
+  - AND zero duplicates for 6+ months in production
+---
+
+# Clean Up Duplicate ADO Work Items
+
+**CRITICAL**: This command detects and closes duplicate ADO work items created by multiple syncs.
+
+## Usage
+
+```bash
+/specweave-ado:cleanup-duplicates <feature-id> [--dry-run]
+```
+
+## What It Does
+
+**Duplicate Detection & Cleanup**:
+
+1. **Find all work items** for the Feature (searches by Feature ID in title)
+2. **Group by title** (detect duplicates)
+3. **For each duplicate group**:
+   - Keep the **FIRST created** work item (lowest ID)
+   - Close all **LATER** work items with comment: "Duplicate of #XXX"
+4. **Update Feature README** with correct work item IDs
+
+## Examples
+
+### Dry Run (No Changes)
+
+```bash
+/specweave-ado:cleanup-duplicates FS-031 --dry-run
+```
+
+**Output**:
+```
+Scanning for duplicates in Feature FS-031...
+   Found 25 total work items
+   Detected 10 duplicate groups:
+
+   Group 1: "[FS-031] External Tool Status Synchronization"
+      - #1250 (KEEP) - Created 2025-11-10
+      - #1255 (CLOSE) - Created 2025-11-11 - DUPLICATE
+      - #1260 (CLOSE) - Created 2025-11-12 - DUPLICATE
+
+   Group 2: "[FS-031] Multi-Project ADO Sync"
+      - #1251 (KEEP) - Created 2025-11-10
+      - #1256 (CLOSE) - Created 2025-11-11 - DUPLICATE
+
+   ...
+
+Dry run complete!
+   Total work items: 25
+   Duplicate groups: 10
+   Work items to close: 15
+
+This was a DRY RUN - no changes made.
+   Run without --dry-run to actually close duplicates.
+```
+
+### Actual Cleanup
+
+```bash
+/specweave-ado:cleanup-duplicates FS-031
+```
+
+**Output**:
+```
+Scanning for duplicates in Feature FS-031...
+   Found 25 total work items
+   Detected 10 duplicate groups
+
+CONFIRM: Close 15 duplicate work items? [y/N]
+> y
+
+Closing duplicates...
+   Closed #1255 (duplicate of #1250)
+   Closed #1256 (duplicate of #1251)
+   Closed #1260 (duplicate of #1250)
+   ...
+
+Updating Feature README frontmatter...
+   Updated frontmatter with correct work item IDs
+
+Cleanup complete!
+   Closed: 15 duplicates
+   Kept: 10 original work items
+```
+
+## Arguments
+
+- `<feature-id>` - Feature ID (e.g., `FS-031` or just `031`)
+- `--dry-run` - Preview changes without actually closing work items (optional)
+
+## Safety Features
+
+- **Confirmation prompt**: Asks before closing work items (unless --dry-run)
+- **Dry run mode**: Preview changes safely
+- **Keeps oldest work item**: Preserves the first created item
+- **Adds closure comment**: Links to the original work item
+- **Updates metadata**: Fixes Feature README frontmatter
+
+## What Gets Closed
+
+**Closed work items**:
+- Duplicate titles (second, third, etc. occurrences)
+- Closed with comment: "Duplicate of #XXX"
+- Original work item kept open (or maintains its status)
+
+**Example comment on closed duplicate**:
+```markdown
+## Duplicate of #1250
+
+This work item was automatically closed by SpecWeave cleanup because it is a duplicate.
+
+The original work item (#1250) contains the same content and should be used for tracking instead.
+
+Auto-closed by SpecWeave Duplicate Cleanup
+```
+
+## Requirements
+
+1. **Azure DevOps PAT** configured (`AZURE_DEVOPS_PAT`)
+2. **Organization** configured (`AZURE_DEVOPS_ORG`)
+3. **Project** configured (`AZURE_DEVOPS_PROJECT`)
+4. **Write access** to project (for closing work items)
+5. **Feature folder exists** at `.specweave/docs/internal/specs/FS-XXX-name/`
+
+## When to Use
+
+**Use this command when**:
+- You see multiple work items with the same title in ADO
+- Feature sync ran multiple times and created duplicates
+- Feature 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-ado:cleanup-duplicates FS-031
+```
+
+## Architecture
+
+**Duplicate Detection Logic**:
+1. Query WIQL for work items with Feature ID in title
+2. Group work items by **exact title match**
+3. Within each group, sort by **work item ID** (ascending)
+4. Keep **first work item** (lowest ID = oldest)
+5. Close **all others** as duplicates via state transition
+
+**Why lowest ID?**:
+- Lower work item IDs were created first
+- Preserves chronological order
+- Maintains links from old documentation
+
+## Related Commands
+
+- `/specweave-ado:sync` - Sync Feature to ADO (with duplicate detection)
+- `/specweave-ado:reconcile` - Reconcile work item states
+- `/specweave:validate` - Validate increment completeness
+
+## Implementation
+
+**File**: `plugins/specweave-ado/lib/ado-duplicate-detector.ts`
+
+**Class**: `AdoDuplicateDetector`
+
+**Algorithm** (3-phase protection):
+1. **Detection**: WIQL query for existing work items matching pattern
+2. **Verification**: Count check to detect duplicates after creation
+3. **Reflection**: Auto-close duplicates automatically
+
+For manual cleanup:
+1. WIQL query for all work items with Feature ID
+2. Group by title (Map<string, number[]>)
+3. Filter groups with >1 item (duplicates)
+4. For each duplicate group:
+   - Keep first work item (lowest ID)
+   - Close others via ADO REST API
+
+## Next Steps
+
+After cleanup:
+
+1. **Verify cleanup**: Check ADO for remaining work items
+2. **Check Feature FEATURE.md**: Verify frontmatter has correct work item IDs
+3. **Re-run sync**: `/specweave-ado:sync` (should show no duplicates)
+4. **Duplicate detection**: Automatically enabled via AdoDuplicateDetector
+
+---
+
+**SAFE TO USE**: This command is idempotent and safe to run multiple times.

package/plugins/specweave-ado/commands/reconcile.md

@@ -0,0 +1,120 @@
+---
+name: specweave-ado:reconcile
+description: Reconcile Azure DevOps work item states with increment statuses. Fixes drift by closing work items for completed increments and reactivating work items for resumed increments.
+---
+
+# Azure DevOps Status Reconciliation
+
+Scan all increments and fix any drift between local metadata.json status and ADO work item states.
+
+## Usage
+
+```bash
+/specweave-ado:reconcile [options]
+```
+
+## Options
+
+- `--dry-run`: Preview changes without making them
+- `--verbose`: Show detailed output for each work item checked
+
+## What It Does
+
+1. **Scans** all non-archived increments
+2. **Compares** metadata.json status with ADO work item state
+3. **Fixes** mismatches:
+   - `metadata=completed` + `ADO=Active` → **Close** the work item
+   - `metadata=in-progress` + `ADO=Closed` → **Reactivate** the work item
+
+## When to Use
+
+- After manual metadata.json edits
+- After git pulls that changed increment statuses
+- When you notice active work items for completed work
+- As a periodic health check
+
+## Implementation
+
+Run the reconciliation using the AdoReconciler:
+
+```typescript
+import { AdoReconciler } from '../../../src/sync/ado-reconciler.js';
+
+const reconciler = new AdoReconciler({
+  projectRoot: process.cwd(),
+  dryRun: args.includes('--dry-run'),
+});
+
+const result = await reconciler.reconcile();
+
+// Report results
+console.log(`\nReconciliation complete:`);
+console.log(`  Scanned: ${result.scanned} increments`);
+console.log(`  Fixed: ${result.closed} closed, ${result.reopened} reopened`);
+if (result.errors.length > 0) {
+  console.log(`  Errors: ${result.errors.length}`);
+}
+```
+
+## Example Output
+
+```
+📊 Scanning 5 increment(s) for ADO state drift...
+
+  ✅ Work Item #1234 (0056-plugin-fix/US-001): State matches (Active)
+  ❌ Work Item #1240 (0066-import-wizard/US-003): Active but should be CLOSED (status=completed)
+     ✅ Closed work item #1240
+  ❌ Work Item #1238 (0063-multi-repo/US-001): CLOSED but should be ACTIVE (status=in-progress)
+     ✅ Reactivated work item #1238
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 ADO RECONCILIATION SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   Increments scanned:   5
+   Mismatches found:     2
+   Work items closed:    1
+   Work items reopened:  1
+   Errors:               0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Dry Run Mode
+
+```bash
+/specweave-ado:reconcile --dry-run
+```
+
+Shows what would be changed without making any modifications:
+
+```
+  ❌ Work Item #1240 (0066-import-wizard/US-003): Active but should be CLOSED
+     [DRY RUN] Would close work item #1240
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 ADO RECONCILIATION SUMMARY
+   ⚠️  DRY RUN - No changes were made
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Requirements
+
+- Azure DevOps PAT configured (`AZURE_DEVOPS_PAT`)
+- `sync.ado.enabled = true` in config.json
+- `sync.settings.canUpdateExternalItems = true` in config.json
+
+## ADO Status Mapping
+
+| SpecWeave Status | Expected ADO State |
+|-----------------|-------------------|
+| `completed` | Closed, Done, Resolved |
+| `abandoned` | Closed, Removed |
+| `in-progress` | Active, In Progress |
+| `active` | Active, New |
+| `planning` | New |
+
+## Related Commands
+
+- `/specweave-ado:status`: View sync status for increments
+- `/specweave-ado:sync`: Manual sync to ADO
+- `/specweave:done`: Close increment (triggers auto-close)
+- `/specweave:resume`: Resume increment (now triggers auto-reopen)

package/plugins/specweave-ado/hooks/post-living-docs-update.sh.backup

@@ -0,0 +1,353 @@
+#!/bin/bash
+
+# ============================================================================
+# Post Living Docs Update Hook - Azure DevOps Sync
+# ============================================================================
+#
+# Triggered after living docs are updated to sync with Azure DevOps.
+# CRITICAL: External tool status ALWAYS wins in conflicts!
+#
+# Triggers:
+# 1. After /specweave:done (increment completion)
+# 2. After /specweave:sync-docs update
+# 3. After manual spec edits
+# 4. After webhook from ADO
+#
+# ============================================================================
+
+set -e
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+LIVING_DOCS_DIR="$PROJECT_ROOT/.specweave/docs/internal/specs"
+LOG_FILE="$PROJECT_ROOT/.specweave/logs/ado-sync.log"
+DEBUG=${DEBUG:-0}
+
+# Ensure log directory exists
+mkdir -p "$(dirname "$LOG_FILE")"
+
+# ============================================================================
+# Logging
+# ============================================================================
+
+log() {
+    local level=$1
+    shift
+    local message="$@"
+    local timestamp=$(date '+%Y-%m-%d %H:%M:%S')
+    echo "[$timestamp] [$level] $message" >> "$LOG_FILE"
+    [ "$DEBUG" -eq 1 ] && echo "[$level] $message" >&2
+}
+
+log_info() {
+    log "INFO" "$@"
+}
+
+log_error() {
+    log "ERROR" "$@"
+}
+
+log_debug() {
+    [ "$DEBUG" -eq 1 ] && log "DEBUG" "$@"
+}
+
+# ============================================================================
+# External Tool Detection
+# ============================================================================
+
+detect_external_tool() {
+    local spec_path=$1
+
+    # Check for external links in spec metadata
+    if grep -q "externalLinks:" "$spec_path"; then
+        if grep -q "ado:" "$spec_path"; then
+            echo "ado"
+        elif grep -q "jira:" "$spec_path"; then
+            echo "jira"
+        elif grep -q "github:" "$spec_path"; then
+            echo "github"
+        fi
+    fi
+}
+
+# ============================================================================
+# Status Mapping
+# ============================================================================
+
+map_ado_status_to_local() {
+    local ado_status=$1
+
+    case "$ado_status" in
+        "New")
+            echo "draft"
+            ;;
+        "Active")
+            echo "in-progress"
+            ;;
+        "Resolved")
+            echo "implemented"
+            ;;
+        "Closed")
+            echo "complete"
+            ;;
+        "In Review"|"In QA")
+            echo "in-qa"
+            ;;
+        *)
+            echo "unknown"
+            ;;
+    esac
+}
+
+map_local_status_to_ado() {
+    local local_status=$1
+
+    case "$local_status" in
+        "draft")
+            echo "New"
+            ;;
+        "in-progress")
+            echo "Active"
+            ;;
+        "implemented")
+            echo "Resolved"
+            ;;
+        "complete")
+            echo "Closed"
+            ;;
+        "in-qa")
+            echo "In Review"
+            ;;
+        *)
+            echo "Active"
+            ;;
+    esac
+}
+
+# ============================================================================
+# ADO API Functions
+# ============================================================================
+
+get_ado_work_item_status() {
+    local work_item_id=$1
+    local org="${AZURE_DEVOPS_ORG}"
+    local project="${AZURE_DEVOPS_PROJECT}"
+    local pat="${AZURE_DEVOPS_PAT}"
+
+    if [ -z "$org" ] || [ -z "$pat" ]; then
+        log_error "ADO credentials not configured"
+        return 1
+    fi
+
+    local api_url="https://dev.azure.com/${org}/${project}/_apis/wit/workitems/${work_item_id}?api-version=7.0"
+
+    log_debug "Fetching ADO work item $work_item_id status"
+
+    local response=$(curl -s -u ":${pat}" \
+        -H "Content-Type: application/json" \
+        "$api_url")
+
+    if [ $? -ne 0 ]; then
+        log_error "Failed to fetch ADO work item status"
+        return 1
+    fi
+
+    # Extract status from response
+    local status=$(echo "$response" | jq -r '.fields["System.State"]')
+
+    if [ "$status" = "null" ] || [ -z "$status" ]; then
+        log_error "Could not extract status from ADO response"
+        return 1
+    fi
+
+    echo "$status"
+}
+
+update_ado_work_item() {
+    local work_item_id=$1
+    local spec_content=$2
+    local org="${AZURE_DEVOPS_ORG}"
+    local project="${AZURE_DEVOPS_PROJECT}"
+    local pat="${AZURE_DEVOPS_PAT}"
+
+    if [ -z "$org" ] || [ -z "$pat" ]; then
+        log_error "ADO credentials not configured"
+        return 1
+    fi
+
+    # Extract current status from spec
+    local local_status=$(echo "$spec_content" | grep "^status:" | cut -d: -f2 | tr -d ' ')
+    local ado_status=$(map_local_status_to_ado "$local_status")
+
+    local api_url="https://dev.azure.com/${org}/${project}/_apis/wit/workitems/${work_item_id}?api-version=7.0"
+
+    # Create update payload
+    local payload=$(cat <<EOF
+[
+    {
+        "op": "add",
+        "path": "/fields/System.State",
+        "value": "$ado_status"
+    },
+    {
+        "op": "add",
+        "path": "/fields/System.History",
+        "value": "Updated from SpecWeave living docs"
+    }
+]
+EOF
+)
+
+    log_debug "Updating ADO work item $work_item_id with status: $ado_status"
+
+    curl -s -X PATCH \
+        -u ":${pat}" \
+        -H "Content-Type: application/json-patch+json" \
+        -d "$payload" \
+        "$api_url" > /dev/null
+
+    if [ $? -ne 0 ]; then
+        log_error "Failed to update ADO work item"
+        return 1
+    fi
+
+    log_info "Updated ADO work item $work_item_id"
+}
+
+# ============================================================================
+# Conflict Resolution - CRITICAL: External Wins!
+# ============================================================================
+
+resolve_status_conflict() {
+    local spec_path=$1
+    local local_status=$2
+    local external_status=$3
+
+    local mapped_external=$(map_ado_status_to_local "$external_status")
+
+    if [ "$local_status" != "$mapped_external" ]; then
+        log_info "Status conflict detected:"
+        log_info "  Local: $local_status"
+        log_info "  External: $external_status (mapped: $mapped_external)"
+        log_info "  Resolution: EXTERNAL WINS - applying $mapped_external"
+
+        # Update local spec with external status
+        sed -i.bak "s/^status: .*/status: $mapped_external/" "$spec_path"
+
+        # Add sync metadata
+        local timestamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
+
+        # Check if syncedAt exists, update or add
+        if grep -q "syncedAt:" "$spec_path"; then
+            sed -i.bak "s/syncedAt: .*/syncedAt: \"$timestamp\"/" "$spec_path"
+        else
+            # Add after externalLinks section
+            sed -i.bak "/externalLinks:/a\\
+    syncedAt: \"$timestamp\"" "$spec_path"
+        fi
+
+        # Clean up backup files
+        rm -f "${spec_path}.bak"
+
+        log_info "Local spec updated with external status: $mapped_external"
+        return 0
+    else
+        log_debug "No status conflict - local and external match: $local_status"
+        return 0
+    fi
+}
+
+# ============================================================================
+# Main Sync Function
+# ============================================================================
+
+sync_spec_with_ado() {
+    local spec_path=$1
+
+    if [ ! -f "$spec_path" ]; then
+        log_error "Spec file not found: $spec_path"
+        return 1
+    fi
+
+    local spec_name=$(basename "$spec_path")
+    log_info "Syncing spec: $spec_name"
+
+    # Read spec content
+    local spec_content=$(cat "$spec_path")
+
+    # Extract ADO work item ID from metadata
+    local work_item_id=$(echo "$spec_content" | grep -A5 "externalLinks:" | grep -A3 "ado:" | grep "featureId:" | cut -d: -f2 | tr -d ' ')
+
+    if [ -z "$work_item_id" ]; then
+        log_debug "No ADO work item linked to spec, skipping sync"
+        return 0
+    fi
+
+    log_info "Found ADO work item ID: $work_item_id"
+
+    # Step 1: Push updates to ADO (content changes)
+    update_ado_work_item "$work_item_id" "$spec_content"
+
+    # Step 2: CRITICAL - Pull status from ADO (external wins!)
+    local external_status=$(get_ado_work_item_status "$work_item_id")
+
+    if [ -z "$external_status" ]; then
+        log_error "Could not fetch ADO status"
+        return 1
+    fi
+
+    log_info "ADO status: $external_status"
+
+    # Step 3: Extract local status
+    local local_status=$(echo "$spec_content" | grep "^status:" | cut -d: -f2 | tr -d ' ')
+
+    log_info "Local status: $local_status"
+
+    # Step 4: Resolve conflicts - EXTERNAL WINS
+    resolve_status_conflict "$spec_path" "$local_status" "$external_status"
+
+    log_info "Sync completed for $spec_name"
+}
+
+# ============================================================================
+# Entry Point
+# ============================================================================
+
+main() {
+    log_info "=== Post Living Docs Update Hook Started ==="
+
+    # Get the spec path from arguments or environment
+    local spec_path="${1:-$SPECWEAVE_UPDATED_SPEC}"
+
+    if [ -z "$spec_path" ]; then
+        log_error "No spec path provided"
+        exit 1
+    fi
+
+    # Detect external tool
+    local tool=$(detect_external_tool "$spec_path")
+
+    if [ "$tool" != "ado" ]; then
+        log_debug "Not an ADO-linked spec, skipping"
+        exit 0
+    fi
+
+    log_info "Detected ADO integration for spec"
+
+    # Perform sync
+    sync_spec_with_ado "$spec_path"
+
+    local exit_code=$?
+
+    if [ $exit_code -eq 0 ]; then
+        log_info "=== Sync completed successfully ==="
+    else
+        log_error "=== Sync failed with exit code: $exit_code ==="
+    fi
+
+    exit $exit_code
+}
+
+# Run main function
+main "$@"