specweave 0.18.1 → 0.20.0

package/plugins/specweave/commands/specweave-fix-duplicates.md

@@ -0,0 +1,517 @@
+---
+name: specweave:fix-duplicates
+description: Automatically detect and resolve duplicate increments with smart conflict resolution
+---
+
+# Fix Duplicate Increments
+
+**Intelligent conflict resolution**: Automatically detects duplicate increments and resolves conflicts by selecting the winner, merging valuable content, and cleaning up losers.
+
+## Philosophy
+
+**Data safety first** - This command provides multiple safety layers:
+- ✅ Shows resolution plan before making changes
+- ✅ Dry-run mode for preview
+- ✅ Merges valuable content before deletion
+- ✅ Creates detailed resolution reports
+- ✅ Requires confirmation unless `--force` flag
+
+## Usage
+
+```bash
+# Detect and fix all duplicates interactively
+/specweave:fix-duplicates
+
+# Preview what would be done (dry-run)
+/specweave:fix-duplicates --dry-run
+
+# Auto-fix with content merging
+/specweave:fix-duplicates --merge
+
+# Force fix without confirmation (use with caution!)
+/specweave:fix-duplicates --force --merge
+
+# Fix specific increment number
+/specweave:fix-duplicates 0031
+```
+
+## Options
+
+- `<increment-number>`: Optional. Fix only duplicates of specific increment number (e.g., "31", "0031")
+- `--dry-run`: Show what would be done without making changes
+- `--merge`: Merge valuable content from losers to winner before deletion
+- `--force`: Skip confirmation prompts (for automated scripts)
+- `--strategy <name>`: Override default resolution strategy (advanced)
+
+## How It Works
+
+### Step 1: Detection
+
+Scans `.specweave/increments/` and all special folders:
+- Active increments (`.specweave/increments/NNNN-*`)
+- Archive (`.specweave/increments/_archive/`)
+- Abandoned (`.specweave/increments/_abandoned/`)
+- Backlog (`.specweave/increments/_backlog/`)
+
+Detects duplicates by increment number (e.g., all folders starting with `0031-`).
+
+### Step 2: Winner Selection
+
+**Automatic prioritization algorithm**:
+
+1. **Status priority** (highest wins):
+   - active = 5 points
+   - completed = 4 points
+   - paused = 3 points
+   - backlog = 2 points
+   - abandoned = 1 point
+
+2. **Most recent activity** (tiebreaker):
+   - Uses `lastActivity` from metadata.json
+   - Falls back to directory modification time
+
+3. **Completeness** (second tiebreaker):
+   - More files = more complete
+   - Larger total size = more complete
+
+4. **Location preference** (final tiebreaker):
+   - Active folder > Paused > Archive > Abandoned
+
+**Example**:
+```
+Increment 0031 exists in 3 locations:
+  1. active/0031-external-tool-sync (status: active, activity: 2025-11-14) → WINNER
+  2. archive/0031-external-tool-sync (status: completed, activity: 2025-11-12)
+  3. abandoned/0031-old-attempt (status: abandoned, activity: 2025-10-01)
+
+Winner: Location 1 (active status + most recent activity)
+```
+
+### Step 3: Content Merging (Optional)
+
+When `--merge` flag is enabled:
+
+1. **Merge reports/ folder**:
+   - Copy all files from losers' `reports/` to winner's `reports/`
+   - Rename conflicting files: `REPORT.md` → `REPORT-{timestamp}.md`
+   - Preserves completion summaries, session notes, analysis
+
+2. **Merge metadata.json**:
+   - Take union of external links (GitHub, JIRA, ADO)
+   - Preserve all external issue numbers
+   - Keep winner's primary metadata (status, dates)
+
+3. **Create resolution report**:
+   - `reports/DUPLICATE-RESOLUTION-{timestamp}.md`
+   - Documents what was merged from where
+   - Lists all deleted paths
+
+**Example merge**:
+```
+Winner: .specweave/increments/0031-external-tool-sync/
+  reports/
+    ├─ IMPLEMENTATION-COMPLETE.md (original)
+    ├─ SESSION-NOTES-2025-11-12.md (merged from archive)
+    └─ DUPLICATE-RESOLUTION-20251115-070000.md (NEW)
+
+Loser 1: .specweave/increments/_archive/0031-external-tool-sync/
+  reports/
+    └─ SESSION-NOTES-2025-11-12.md → MERGED to winner
+
+Loser 2: .specweave/increments/_abandoned/0031-old-attempt/
+  (No valuable content to merge)
+```
+
+### Step 4: Deletion
+
+**Safety measures**:
+- Shows confirmation prompt: `Delete {path}? This will permanently remove {N} files. [y/N]`
+- Default answer: `N` (no deletion unless confirmed)
+- `--force` flag skips prompts (for CI/automated scripts)
+- Dry-run mode never deletes (shows preview only)
+
+## Examples
+
+### Example 1: Interactive Fix (Recommended)
+
+```bash
+/specweave:fix-duplicates
+```
+
+**Output**:
+```
+🔍 Scanning for duplicate increments...
+
+Found 2 duplicates:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Duplicate 1: Increment 0031-external-tool-status-sync
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Locations:
+  1. ✓ (recommended) active/0031-external-tool-status-sync
+     Status: active | Activity: 2025-11-14 | Files: 12
+     Reason: Active status + most recent
+
+  2. ✗ archive/0031-external-tool-sync
+     Status: completed | Activity: 2025-11-12 | Files: 10
+
+Resolution Plan:
+  • Keep: active/0031-external-tool-status-sync
+  • Delete: archive/0031-external-tool-sync
+
+Delete archive/0031-external-tool-sync? [y/N]: y
+
+✅ Resolved duplicate 0031
+   • Kept: active/0031-external-tool-status-sync
+   • Deleted: archive/0031-external-tool-sync (10 files removed)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Summary
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Duplicates found: 2
+Duplicates resolved: 2
+Files deleted: 15
+Space freed: 2.3 MB
+
+📝 Resolution reports:
+   • active/0031-external-tool-status-sync/reports/DUPLICATE-RESOLUTION-20251115-070000.md
+```
+
+### Example 2: Dry-Run Preview
+
+```bash
+/specweave:fix-duplicates --dry-run
+```
+
+**Output**:
+```
+🔍 DRY RUN - No files will be deleted
+
+Found 2 duplicates:
+
+Duplicate 1: Increment 0031
+  [DRY RUN] Would keep: active/0031-external-tool-status-sync
+  [DRY RUN] Would delete: archive/0031-external-tool-sync (10 files)
+
+Duplicate 2: Increment 0032
+  [DRY RUN] Would keep: active/0032-increment-number-gap-prevention
+  [DRY RUN] Would delete: active/0032-prevent-increment-number-gaps (8 files)
+
+Summary:
+  Would resolve: 2 duplicates
+  Would delete: 18 files
+  Would free: 2.5 MB
+
+Run without --dry-run to proceed:
+  /specweave:fix-duplicates --merge
+```
+
+### Example 3: Auto-Fix with Merge
+
+```bash
+/specweave:fix-duplicates --merge --force
+```
+
+**Output**:
+```
+🔍 Scanning for duplicate increments...
+
+Found 2 duplicates:
+
+Duplicate 1: Increment 0031
+  ✓ Winner: active/0031-external-tool-status-sync
+  📦 Merging content from losers...
+     • Merged: reports/SESSION-NOTES-2025-11-12.md
+     • Created: reports/DUPLICATE-RESOLUTION-20251115-070000.md
+  ✓ Deleted: archive/0031-external-tool-sync
+
+Duplicate 2: Increment 0032
+  ✓ Winner: active/0032-increment-number-gap-prevention
+  ⚠️  No content to merge (loser empty)
+  ✓ Deleted: active/0032-prevent-increment-number-gaps
+
+✅ All duplicates resolved!
+
+Summary:
+  Resolved: 2 duplicates
+  Merged: 1 file
+  Deleted: 2 paths (18 files)
+  Space freed: 2.5 MB
+```
+
+### Example 4: Fix Specific Increment
+
+```bash
+/specweave:fix-duplicates 0031
+```
+
+**Output**:
+```
+🔍 Scanning for duplicates of increment 0031...
+
+Found 1 duplicate:
+
+Duplicate: Increment 0031-external-tool-status-sync
+  Locations:
+    1. ✓ active/0031-external-tool-status-sync (recommended)
+    2. ✗ archive/0031-external-tool-sync
+
+Delete archive/0031-external-tool-sync? [y/N]: y
+
+✅ Duplicate 0031 resolved
+   • Kept: active/0031-external-tool-status-sync
+   • Deleted: archive/0031-external-tool-sync
+```
+
+## Error Handling
+
+### No Duplicates Found
+
+```
+🔍 Scanning for duplicate increments...
+
+✅ No duplicates found!
+
+All increments have unique numbers and locations.
+```
+
+### User Declines Deletion
+
+```
+Delete archive/0031-external-tool-sync? [y/N]: n
+
+⏭️  Skipped deletion of archive/0031-external-tool-sync
+
+Summary:
+  Duplicates found: 2
+  Duplicates resolved: 0
+  User declined: 2
+
+💡 Tip: Use --force to skip confirmation prompts
+```
+
+### Filesystem Error
+
+```
+❌ Error resolving duplicate 0031:
+   Failed to delete archive/0031-external-tool-sync
+   Reason: Permission denied
+
+Recommendation:
+  1. Check file permissions
+  2. Close any programs using these files
+  3. Retry with sudo (if appropriate)
+```
+
+## Resolution Report Format
+
+**File**: `reports/DUPLICATE-RESOLUTION-{timestamp}.md`
+
+```markdown
+# Duplicate Resolution Report
+
+**Increment**: 0031-external-tool-status-sync
+**Resolved**: 2025-11-15 07:00:00 UTC
+**Command**: /specweave:fix-duplicates --merge
+
+## Detected Duplicates
+
+Increment 0031 existed in 2 locations:
+1. active/0031-external-tool-status-sync (status: active, activity: 2025-11-14)
+2. archive/0031-external-tool-sync (status: completed, activity: 2025-11-12)
+
+## Winner Selection
+
+**Winner**: active/0031-external-tool-status-sync
+
+**Reason**: Active status (5 points) + Most recent activity (2025-11-14)
+
+## Content Merged
+
+Merged from archive/0031-external-tool-sync:
+- reports/SESSION-NOTES-2025-11-12.md → reports/SESSION-NOTES-2025-11-12.md
+- metadata.json (union of external links)
+
+## Deleted Paths
+
+- archive/0031-external-tool-sync (10 files, 1.2 MB)
+
+## Metadata Union
+
+**GitHub**:
+- Issue #45 (from winner)
+- Issue #42 (from archive) ← merged
+
+**JIRA**:
+- PROJ-123 (from winner)
+
+## Summary
+
+- Duplicates resolved: 1
+- Files merged: 1
+- Paths deleted: 1
+- Space freed: 1.2 MB
+- Total time: 0.5s
+```
+
+## Implementation
+
+```typescript
+import { Task } from '@claude/types';
+
+const task = new Task('fix-duplicates', 'Fix duplicate increments');
+
+task.run(async () => {
+  const { detectAllDuplicates } = await import('../../../dist/src/core/increment/duplicate-detector.js');
+  const { resolveConflict } = await import('../../../dist/src/core/increment/conflict-resolver.js');
+
+  // Parse arguments
+  const args = process.argv.slice(2);
+  const incrementNumber = args.find(arg => /^\d+$/.test(arg));
+
+  // Parse options
+  const options = {
+    dryRun: args.includes('--dry-run'),
+    merge: args.includes('--merge'),
+    force: args.includes('--force'),
+    strategy: args.includes('--strategy') ? args[args.indexOf('--strategy') + 1] : undefined
+  };
+
+  // Detect duplicates
+  console.log('🔍 Scanning for duplicate increments...\n');
+  const report = await detectAllDuplicates(process.cwd());
+
+  // Filter by increment number if specified
+  let duplicates = report.duplicates;
+  if (incrementNumber) {
+    const paddedNumber = incrementNumber.padStart(4, '0');
+    duplicates = duplicates.filter(d => d.incrementNumber === paddedNumber);
+  }
+
+  if (duplicates.length === 0) {
+    console.log('✅ No duplicates found!\n');
+    console.log('All increments have unique numbers and locations.');
+    return;
+  }
+
+  console.log(`Found ${duplicates.length} duplicate${duplicates.length > 1 ? 's' : ''}:\n`);
+
+  // Display resolution plan
+  if (options.dryRun) {
+    console.log('🔍 DRY RUN - No files will be deleted\n');
+  }
+
+  // Resolve each duplicate
+  const results = [];
+  for (const duplicate of duplicates) {
+    console.log('━'.repeat(60));
+    console.log(`Duplicate: Increment ${duplicate.incrementNumber}`);
+    console.log('━'.repeat(60));
+
+    // Show locations
+    console.log('\nLocations:');
+    duplicate.locations.forEach((loc, index) => {
+      const isWinner = loc === duplicate.recommendedWinner;
+      const marker = isWinner ? '✓ (recommended)' : '✗';
+      console.log(`  ${index + 1}. ${marker} ${path.basename(loc.path)}`);
+      console.log(`     Status: ${loc.metadata?.status || 'unknown'} | Activity: ${loc.metadata?.lastActivity || 'unknown'} | Files: ${loc.fileCount}`);
+    });
+
+    // Show resolution reason
+    console.log(`\nResolution reason: ${duplicate.resolutionReason}`);
+
+    // Resolve conflict
+    try {
+      const result = await resolveConflict(duplicate, options);
+      results.push(result);
+
+      if (options.dryRun) {
+        console.log(`\n[DRY RUN] Would keep: ${path.basename(result.winner)}`);
+        console.log(`[DRY RUN] Would delete: ${result.deleted.map(p => path.basename(p)).join(', ')}`);
+      } else {
+        console.log(`\n✅ Resolved duplicate ${duplicate.incrementNumber}`);
+        console.log(`   • Kept: ${path.basename(result.winner)}`);
+        console.log(`   • Deleted: ${result.deleted.map(p => path.basename(p)).join(', ')}`);
+        if (result.merged.length > 0) {
+          console.log(`   • Merged: ${result.merged.length} file(s)`);
+        }
+      }
+    } catch (error) {
+      console.error(`\n❌ Error resolving duplicate ${duplicate.incrementNumber}:`);
+      console.error(`   ${error.message}`);
+    }
+
+    console.log();
+  }
+
+  // Summary
+  console.log('━'.repeat(60));
+  console.log('Summary');
+  console.log('━'.repeat(60));
+
+  const totalDeleted = results.reduce((sum, r) => sum + r.deleted.length, 0);
+  const totalMerged = results.reduce((sum, r) => sum + r.merged.length, 0);
+
+  if (options.dryRun) {
+    console.log(`\nWould resolve: ${results.length} duplicate${results.length > 1 ? 's' : ''}`);
+    console.log(`Would delete: ${totalDeleted} path${totalDeleted > 1 ? 's' : ''}`);
+    if (totalMerged > 0) {
+      console.log(`Would merge: ${totalMerged} file${totalMerged > 1 ? 's' : ''}`);
+    }
+    console.log('\nRun without --dry-run to proceed:');
+    console.log('  /specweave:fix-duplicates --merge');
+  } else {
+    console.log(`\nDuplicates resolved: ${results.length}`);
+    console.log(`Paths deleted: ${totalDeleted}`);
+    if (totalMerged > 0) {
+      console.log(`Files merged: ${totalMerged}`);
+    }
+    console.log('\n📝 Resolution reports:');
+    results.forEach(r => {
+      console.log(`   • ${r.reportPath}`);
+    });
+  }
+});
+
+export default task;
+```
+
+## Configuration
+
+No configuration needed - all options are provided via command-line flags.
+
+## Related Commands
+
+- `/specweave:archive <id>` - Archive specific increment (prevents duplicates)
+- `/specweave:restore <id>` - Restore increment from archive
+- `/specweave:status` - View all increment statuses
+
+## Safety Notes
+
+### ⚠️ Important Warnings
+
+1. **Backup before bulk operations**: If fixing many duplicates, consider git commit first
+2. **Review dry-run output**: Always run with `--dry-run` first to preview changes
+3. **Merge valuable content**: Use `--merge` flag to preserve reports and session notes
+4. **Force flag caution**: `--force` skips confirmations - use only in automated scripts
+
+### 🔒 What Gets Preserved
+
+**Always preserved** (in winner):
+- spec.md, plan.md, tasks.md (core files)
+- metadata.json (merged external links if `--merge`)
+- All files in winner's directory
+
+**Conditionally preserved** (if `--merge`):
+- reports/ folder from losers → merged to winner
+- External links (GitHub, JIRA, ADO) → union in metadata.json
+
+**Always deleted**:
+- Losing increment directories and all their contents
+- Creates resolution report documenting what was deleted
+
+---
+
+**Best Practice**: Run with `--dry-run --merge` first to see what would happen, then run without `--dry-run` to apply changes.

package/plugins/specweave/commands/specweave-increment.md

@@ -449,9 +449,10 @@ Proceeding with hotfix 0006...
 
 ### Step 1: Find next increment number
 
-- Scan `.specweave/increments/` directory
-- Find highest number (e.g., 002)
-- Next increment: 003
+- Scan `.specweave/increments/` directory (active increments)
+- Scan `.specweave/increments/_archive/` directory (archived/abandoned increments)
+- Find highest number across both directories (e.g., 032)
+- Next increment: 033
 
 ### Step 2: Detect tech stack (CRITICAL - framework-agnostic)
    - Settings auto-detected