specweave 1.0.593 → 2.0.3

package/plugins/specweave/commands/abandon.md

@@ -1,320 +0,0 @@
----
-description: Abandon an incomplete increment (requirements changed, obsolete)
-argument-hint: [increment-id] --reason="reason"
-disable-model-invocation: true
----
-
-# Abandon Increment Command
-
-**Usage**: `sw:abandon <increment-id> --reason="<reason>"`
-
-⚠️  **THIS ACTION MOVES THE INCREMENT TO `_archive/` FOLDER**
-
----
-
-## Purpose
-
-Abandon an increment when:
-- **Requirements changed** (feature no longer needed)
-- **Approach wrong** (discovered better solution)
-- **Superseded** (replaced by different increment)
-- **Experiment failed** (spike didn't pan out)
-
----
-
-## Behavior
-
-1. **Normalize increment ID**:
-   - If ID contains dash (e.g., "0153-feature-name"), extract numeric portion before first dash → "0153"
-   - Convert to 4-digit format (e.g., "1" → "0001", "153" → "0153")
-   - Both formats work: `sw:abandon 0153` or `sw:abandon 0153-feature-name`
-2. **Validates** increment exists and is NOT "completed"
-3. **Prompts** for reason if not provided
-4. **Confirmation prompt** ("This is permanent. Continue? [y/N]")
-5. **Updates** metadata.json:
-   - `status`: → "abandoned"
-   - `abandonedReason`: User-provided reason
-   - `abandonedAt`: Current timestamp
-6. **Moves folder**:
-   - From: `.specweave/increments/{id}/`
-   - To: `.specweave/increments/_archive/{id}/`
-7. **Displays** confirmation with preserved location
-
----
-
-## Examples
-
-### Abandon with reason
-```bash
-sw:abandon 0008 --reason="Requirements changed - feature no longer needed"
-
-⚠️  This will move increment 0008 to _archive/
-   Reason: Requirements changed - feature no longer needed
-
-Continue? [y/N]: y
-
-✅ Increment 0008 abandoned
-📦 Moved to: .specweave/increments/_archive/0008-old-feature/
-📝 Reason: Requirements changed - feature no longer needed
-💾 All work preserved for reference
-
-💡 To un-abandon: Manually move back to increments/ folder
-```
-
-### Abandon without reason (prompts)
-```bash
-sw:abandon 0009
-
-❓ Why are you abandoning this increment?
-   1. Requirements changed
-   2. Approach was wrong
-   3. Superseded by different work
-   4. Experiment failed
-   5. Other (type reason)
-
-> 1
-
-⚠️  This will move increment 0009 to _archive/
-   Reason: Requirements changed
-
-Continue? [y/N]: y
-
-✅ Increment 0009 abandoned
-📦 Moved to: .specweave/increments/_archive/0009-experiment/
-```
-
----
-
-## Edge Cases
-
-### Cannot Abandon Completed
-```bash
-sw:abandon 0005
-
-❌ Cannot abandon increment 0005
-   Status: completed
-   Completed increments cannot be abandoned
-
-💡 Increments are done - no need to abandon
-```
-
-### Already Abandoned
-```bash
-sw:abandon 0008
-
-⚠️  Increment 0008 is already abandoned
-   Location: .specweave/increments/_abandoned/0008-old-feature/
-   Reason: Requirements changed
-
-No action needed.
-```
-
-### Increment Not Found
-```bash
-sw:abandon 9999
-
-❌ Increment not found: 9999
-💡 Check available increments: sw:status
-```
-
-### Cancel Abandonment
-```bash
-sw:abandon 0008 --reason="Not needed"
-
-⚠️  This will move increment 0008 to _archive/
-   Reason: Not needed
-
-Continue? [y/N]: n
-
-❌ Abandonment cancelled
-   Increment 0008 remains active
-```
-
----
-
-## Implementation
-
-This command uses the MetadataManager and file system operations:
-
-```typescript
-import { MetadataManager, IncrementStatus } from '../src/core/increment/metadata-manager';
-import * as fs from 'fs-extra';
-import * as path from 'path';
-
-// Read current metadata
-const metadata = MetadataManager.read(incrementId);
-
-// Validate can abandon
-if (metadata.status === IncrementStatus.COMPLETED) {
-  throw new Error('Cannot abandon completed increment');
-}
-
-// Confirmation prompt
-const confirmed = await prompt('Continue? [y/N]');
-if (!confirmed) {
-  console.log('Abandonment cancelled');
-  return;
-}
-
-// Update metadata
-MetadataManager.updateStatus(incrementId, IncrementStatus.ABANDONED, reason);
-
-// Move to _archive/ folder
-const fromPath = path.join('.specweave/increments', incrementId);
-const toPath = path.join('.specweave/increments/_archive', incrementId);
-fs.moveSync(fromPath, toPath);
-
-console.log(`✅ Moved to: ${toPath}`);
-```
-
----
-
-## Status Flow
-
-```
-active ──abandon──> abandoned
-   │
-paused ──abandon──> abandoned
-   │
-abandoned (already abandoned - no-op)
-
-completed (CANNOT abandon)
-```
-
----
-
-## _archive/ Folder Structure
-
-```
-.specweave/increments/
-├── 0023-release-management/      # Active
-├── 0024-bidirectional-spec/      # Active
-├── 0025-per-project-config/      # Active
-├── _archive/                      # All archived/abandoned/old increments
-│   ├── 0001-core-framework/       # Completed (archived)
-│   ├── 0002-core-enhancements/    # Completed (archived)
-│   ├── 0008-old-approach/         # Abandoned
-│   │   ├── spec.md
-│   │   ├── plan.md
-│   │   ├── tasks.md
-│   │   └── metadata.json (status: abandoned)
-│   ├── 0009-failed-experiment/    # Abandoned
-│   └── 0029-cicd-auto-fix/        # Abandoned
-└── _backlog/                       # Future work
-```
-
----
-
-## Un-Abandoning (Manual Process)
-
-To un-abandon an increment:
-
-```bash
-# 1. Move back to increments/
-mv .specweave/increments/_archive/0008-feature \
-   .specweave/increments/0008-feature
-
-# 2. Resume via command
-sw:resume 0008
-
-✅ Increment 0008 resumed
-⚠️  Note: Was abandoned 10 days ago
-   Reason: Requirements changed
-💡 Review spec.md to ensure still relevant
-```
-
----
-
-## Related Commands
-
-- `sw:pause <id>` - Pause increment (temporary, can resume)
-- `sw:resume <id>` - Resume paused or abandoned increment
-- `sw:status` - Show all increments (including abandoned count)
-- `sw:status --abandoned` - Show only abandoned increments
-
----
-
-## Best Practices
-
-✅ **Always provide clear reason** - Future you will thank you
-
-✅ **Document learnings** - Add retrospective notes to spec.md before abandoning
-
-✅ **Extract reusable parts** - Move to _backlog/ if salvageable
-
-✅ **Communicate** - Let team know if collaborative
-
-❌ **Don't abandon as procrastination** - Pause if temporarily blocked
-
-❌ **Don't delete** - Abandon moves to _abandoned/, preserves history
-
----
-
-## Auto-Abandonment (Experiments)
-
-Experiments (--type=experiment) auto-abandon after **14 days** of inactivity:
-
-```bash
-# Create experiment
-sw:inc "Try GraphQL" --type=experiment
-
-# ... 15 days pass with no activity ...
-
-# Automatic abandonment
-sw:status
-
-📊 Auto-Abandoned (1):
-  🧪 0010-graphql-experiment [experiment]
-     Abandoned: automatically (14+ days inactive)
-     Created: 15 days ago
-     Last activity: 15 days ago
-
-💡 Experiments auto-abandon after 14 days of inactivity
-   To prevent: Update lastActivity via sw:do or manual touch
-```
-
----
-
-## Statistics
-
-View abandonment statistics:
-
-```bash
-sw:status
-
-✅ Completed (4):
-  0001-core-framework
-  0002-core-enhancements
-  0003-model-selection
-  0004-plugin-architecture
-
-❌ Abandoned (3):
-  0008-old-approach (Requirements changed)
-  0009-failed-experiment (Experiment failed)
-  0010-superseded (Replaced by 0011)
-
-📊 Summary:
-  - Success rate: 57% (4/7 completed)
-  - Abandonment rate: 43% (3/7 abandoned)
-  - Common reasons: Requirements changed (2), Experiment failed (1)
-```
-
----
-
-## Abandoned Increments as Learning
-
-Abandoned work is valuable!
-
-- **Retrospectives**: What went wrong? Why did requirements change?
-- **Patterns**: Are we over-committing? Under-planning?
-- **Learnings**: Failed experiments teach us what NOT to do
-- **Reference**: Abandoned specs can inform future work
-
-💡 Periodically review `_archive/` folder for insights
-
----
-
-**Command**: `sw:abandon`
-**Plugin**: specweave (core)
-**Version**: v0.7.0
-**Part of**: Increment 0007 - Smart Status Management

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

@@ -1,211 +0,0 @@
----
-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
-sw-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
-sw-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
-sw-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:
-   sw-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
-
-- `sw-ado:sync` - Sync Feature to ADO (with duplicate detection)
-- `sw-ado:reconcile` - Reconcile work item states
-- `sw: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**: `sw-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.