specweave 0.18.1 → 0.20.0

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

@@ -8,7 +8,7 @@ usage: /specweave:abandon <increment-id> --reason="<reason>"
 
 **Usage**: `/specweave:abandon <increment-id> --reason="<reason>"`
 
-⚠️  **THIS ACTION MOVES THE INCREMENT TO `_abandoned/` FOLDER**
+⚠️  **THIS ACTION MOVES THE INCREMENT TO `_archive/` FOLDER**
 
 ---
 
@@ -33,7 +33,7 @@ Abandon an increment when:
    - `abandonedAt`: Current timestamp
 5. **Moves folder**:
    - From: `.specweave/increments/{id}/`
-   - To: `.specweave/increments/_abandoned/{id}/`
+   - To: `.specweave/increments/_archive/{id}/`
 6. **Displays** confirmation with preserved location
 
 ---
@@ -44,13 +44,13 @@ Abandon an increment when:
 ```bash
 /specweave:abandon 0008 --reason="Requirements changed - feature no longer needed"
 
-⚠️  This will move increment 0008 to _abandoned/
+⚠️  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/_abandoned/0008-old-feature/
+📦 Moved to: .specweave/increments/_archive/0008-old-feature/
 📝 Reason: Requirements changed - feature no longer needed
 💾 All work preserved for reference
 
@@ -70,13 +70,13 @@ Continue? [y/N]: y
 
 > 1
 
-⚠️  This will move increment 0009 to _abandoned/
+⚠️  This will move increment 0009 to _archive/
    Reason: Requirements changed
 
 Continue? [y/N]: y
 
 ✅ Increment 0009 abandoned
-📦 Moved to: .specweave/increments/_abandoned/0009-experiment/
+📦 Moved to: .specweave/increments/_archive/0009-experiment/
 ```
 
 ---
@@ -117,7 +117,7 @@ No action needed.
 ```bash
 /specweave:abandon 0008 --reason="Not needed"
 
-⚠️  This will move increment 0008 to _abandoned/
+⚠️  This will move increment 0008 to _archive/
    Reason: Not needed
 
 Continue? [y/N]: n
@@ -155,9 +155,9 @@ if (!confirmed) {
 // Update metadata
 MetadataManager.updateStatus(incrementId, IncrementStatus.ABANDONED, reason);
 
-// Move to _abandoned/ folder
+// Move to _archive/ folder
 const fromPath = path.join('.specweave/increments', incrementId);
-const toPath = path.join('.specweave/increments/_abandoned', incrementId);
+const toPath = path.join('.specweave/increments/_archive', incrementId);
 fs.moveSync(fromPath, toPath);
 
 console.log(`✅ Moved to: ${toPath}`);
@@ -179,22 +179,24 @@ completed (CANNOT abandon)
 
 ---
 
-## _abandoned/ Folder Structure
+## _archive/ Folder Structure
 
 ```
 .specweave/increments/
-├── 0001-core-framework/          # Active/completed
-├── 0002-core-enhancements/       # Active/completed
-├── 0003-model-selection/         # Active/completed
-├── _abandoned/                    # Abandoned increments
-│   ├── 0008-old-approach/        # Abandoned
+├── 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/
-│   └── 0010-superseded-feature/
-└── _backlog/                      # Future work
+│   ├── 0009-failed-experiment/    # Abandoned
+│   └── 0029-cicd-auto-fix/        # Abandoned
+└── _backlog/                       # Future work
 ```
 
 ---
@@ -205,7 +207,7 @@ To un-abandon an increment:
 
 ```bash
 # 1. Move back to increments/
-mv .specweave/increments/_abandoned/0008-feature \
+mv .specweave/increments/_archive/0008-feature \
    .specweave/increments/0008-feature
 
 # 2. Resume via command
@@ -304,7 +306,7 @@ Abandoned work is valuable!
 - **Learnings**: Failed experiments teach us what NOT to do
 - **Reference**: Abandoned specs can inform future work
 
-💡 Periodically review `_abandoned/` folder for insights
+💡 Periodically review `_archive/` folder for insights
 
 ---
 

package/plugins/specweave/commands/specweave-archive-features.md

@@ -0,0 +1,121 @@
+---
+name: specweave-archive-features
+description: Archive features and epics when all related increments are archived
+---
+
+# Archive Features and Epics
+
+Archive features and epics based on their increment archive status. Features are archived when all their increments are archived, and epics are archived when all their features are archived.
+
+## Usage
+
+```bash
+/specweave:archive-features [options]
+```
+
+## Options
+
+- `--dry-run`: Show what would be archived without actually moving files
+- `--update-links`: Update all links to archived items (default: true)
+- `--preserve-active`: Don't archive features with active projects (default: true)
+- `--orphaned`: Also archive orphaned features/epics with no increments/features
+
+## Examples
+
+```bash
+# Preview what would be archived
+/specweave:archive-features --dry-run
+
+# Archive features and update all links
+/specweave:archive-features
+
+# Archive including orphaned features
+/specweave:archive-features --orphaned
+```
+
+## Archive Rules
+
+### Features are archived when:
+1. All linked increments are in _archive folder
+2. No active projects remain (unless --preserve-active=false)
+3. Feature is orphaned (no increments) and --orphaned is set
+
+### Epics are archived when:
+1. All linked features are in _archive folder
+2. Epic is orphaned (no features) and --orphaned is set
+
+### Archive Structure:
+```
+.specweave/docs/internal/specs/
+├── _features/
+│   ├── FS-023/              # Active feature
+│   └── _archive/
+│       └── FS-001/          # Archived feature
+├── _epics/
+│   ├── EPIC-2025-Q1/        # Active epic
+│   └── _archive/
+│       └── EPIC-2024-Q4/    # Archived epic
+└── default/
+    ├── FS-023/              # Active project files
+    └── _archive/
+        └── FS-001/          # Archived project files
+```
+
+## Important Notes
+
+- Archives are LOCAL ONLY (not synced to GitHub/JIRA/ADO)
+- All links are automatically updated to point to archive locations
+- Use `/specweave:restore-feature FS-001` to restore from archive
+
+## Implementation
+
+```typescript
+import { Task } from '@claude/types';
+
+const task = new Task('feature-archiver', 'Archive features and epics');
+
+// Main logic
+task.run(async () => {
+  const { FeatureArchiver } = await import('../../../dist/src/core/living-docs/feature-archiver.js');
+  const archiver = new FeatureArchiver(process.cwd());
+
+  // Parse options
+  const options = {
+    dryRun: process.argv.includes('--dry-run'),
+    updateLinks: !process.argv.includes('--no-update-links'),
+    preserveActiveFeatures: !process.argv.includes('--no-preserve-active'),
+    archiveOrphanedFeatures: process.argv.includes('--orphaned'),
+    archiveOrphanedEpics: process.argv.includes('--orphaned')
+  };
+
+  // Execute archiving
+  const result = await archiver.archiveFeatures(options);
+
+  // Display results
+  console.log('\n📦 Archive Results:');
+  console.log(`  Features archived: ${result.archivedFeatures.length}`);
+  console.log(`  Epics archived: ${result.archivedEpics.length}`);
+  console.log(`  Links updated: ${result.updatedLinks.length}`);
+
+  if (result.errors.length > 0) {
+    console.error('\n❌ Errors:');
+    result.errors.forEach(err => console.error(`  - ${err}`));
+  }
+
+  // Show stats
+  const stats = await archiver.getArchiveStats();
+  console.log('\n📊 Archive Statistics:');
+  console.log(`  Features: ${stats.features.active} active, ${stats.features.archived} archived`);
+  console.log(`  Epics: ${stats.epics.active} active, ${stats.epics.archived} archived`);
+
+  // Show per-project stats
+  if (Object.keys(stats.projects).length > 0) {
+    console.log('\n  Per Project:');
+    for (const [project, counts] of Object.entries(stats.projects)) {
+      console.log(`    ${project}: ${counts.active} active, ${counts.archived} archived`);
+    }
+  }
+});
+
+export default task;
+```

package/plugins/specweave/commands/specweave-archive-increments.md

@@ -0,0 +1,82 @@
+---
+name: specweave-archive-increments
+description: Archive completed increments to keep workspace clean
+---
+
+# Archive Increments Command
+
+Archives completed increments to `_archive/` folder, keeping only the most recent N increments in the main folder.
+
+## Usage
+
+```bash
+# Interactive mode - prompts for options
+/specweave:archive-increments
+
+# Keep last 5 increments, archive the rest
+/specweave:archive-increments --keep-last 5
+
+# Archive specific increments
+/specweave:archive-increments --increments 0001,0002,0003
+
+# Dry run - see what would be archived without moving
+/specweave:archive-increments --dry-run
+
+# Archive all completed increments older than 30 days
+/specweave:archive-increments --older-than 30d
+
+# Keep only active/paused, archive all completed
+/specweave:archive-increments --archive-completed
+```
+
+## Default Behavior
+
+- Keeps last 10 increments by default
+- Preserves all active/paused increments
+- Never archives abandoned increments (they stay in `_abandoned/`)
+- Creates `_archive/` folder if it doesn't exist
+- Preserves increment structure and all contents
+
+## Smart Detection
+
+The command intelligently:
+- Checks increment status from metadata.json
+- Preserves increments with active GitHub/JIRA/ADO issues
+- Warns before archiving increments with uncommitted changes
+- Groups related increments (e.g., all v0.8.0 stabilization increments)
+
+## Configuration
+
+Set defaults in `.specweave/config.json`:
+
+```json
+{
+  "archiving": {
+    "keepLast": 10,
+    "autoArchive": true,
+    "archiveAfterDays": 60,
+    "preserveActive": true,
+    "archiveCompleted": true
+  }
+}
+```
+
+## Examples
+
+### Keep workspace clean
+```bash
+# Archive all but last 5 increments
+/specweave:archive-increments --keep-last 5
+```
+
+### Prepare for release
+```bash
+# Archive all v0.7.x increments after v0.8.0 release
+/specweave:archive-increments --pattern "v0.7"
+```
+
+### Clean old work
+```bash
+# Archive increments older than 2 months
+/specweave:archive-increments --older-than 60d
+```

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

@@ -0,0 +1,363 @@
+---
+name: specweave:archive
+description: Manually archive completed increments - NEVER auto-archives, explicit user action only
+---
+
+# Archive Increments (Manual Only)
+
+**CRITICAL POLICY**: Increments are **NEVER** auto-archived. Archiving is **MANUAL ONLY** and requires explicit user action via this command.
+
+## Philosophy
+
+**Keep recent work visible** - Completed increments remain in the main folder for easy reference until you explicitly archive them. This allows:
+- ✅ Quick reference to recent implementations
+- ✅ Easy linking in new increments
+- ✅ Visible completion history
+- ✅ ~10-20 completed increments available without searching archives
+
+## Usage
+
+```bash
+# Archive specific increment
+/specweave:archive 0031
+
+# Archive multiple increments
+/specweave:archive 0001 0002 0003
+
+# Archive all completed increments older than N days
+/specweave:archive --older-than 90
+
+# Keep last N increments, archive the rest
+/specweave:archive --keep-last 10
+
+# Archive by pattern
+/specweave:archive --pattern "auth-*"
+
+# Dry run (preview without archiving)
+/specweave:archive --dry-run --older-than 90
+```
+
+## Options
+
+- `<increment-ids>`: Specific increment IDs to archive (e.g., "1", "0001", "0031")
+- `--older-than <days>`: Archive increments older than N days
+- `--keep-last <n>`: Keep last N increments, archive the rest (default: 10)
+- `--pattern <regex>`: Archive increments matching pattern
+- `--archive-completed`: Archive all completed increments (use with caution!)
+- `--preserve-active`: Never archive active/paused increments (default: true)
+- `--dry-run`: Show what would be archived without moving files
+
+## Archive Rules
+
+### Increments are archived when:
+1. Explicitly specified by ID (e.g., `/specweave:archive 0031`)
+2. Match age criteria (e.g., `--older-than 90`)
+3. Match pattern criteria (e.g., `--pattern "old-*"`)
+4. Not in last N increments (e.g., `--keep-last 10`)
+
+### Safety Checks (Always Applied):
+- ✅ **Active/paused protection**: Never archive active or paused increments
+- ✅ **External sync protection**: Skip increments with open GitHub/JIRA/ADO issues
+- ✅ **Uncommitted changes**: Warn if git has uncommitted changes
+- ✅ **Duplicate prevention**: Refuse if increment already exists in archive
+
+### Archive Structure:
+```
+.specweave/increments/
+├── 0030-recent-work/           # Active/recent increments
+├── 0031-recent-work/           # Stay visible for reference
+├── 0032-recent-work/
+├── 0033-recent-work/
+│
+├── _archive/                   # Archived increments
+│   ├── 0001-old-work/          # Manually archived
+│   ├── 0002-old-work/
+│   └── 0003-old-work/
+│
+└── _abandoned/                 # Abandoned work (separate)
+    └── 0004-abandoned-work/
+```
+
+## Examples
+
+### Example 1: Archive Specific Increment
+
+```bash
+/specweave:archive 0031
+```
+
+**Output**:
+```
+📦 Archiving increments...
+
+Checking increment 0031-external-tool-status-sync...
+  ✓ Status: completed
+  ✓ No active external sync
+  ✓ No uncommitted changes
+  ✓ Not already in archive
+
+✅ Archived: 0031-external-tool-status-sync
+   Location: .specweave/increments/_archive/0031-external-tool-status-sync/
+
+📊 Archive Statistics:
+   Active: 32 increments
+   Archived: 31 increments (+ 1 new)
+
+Next: /specweave:restore 0031 (if you need to unarchive)
+```
+
+### Example 2: Archive Old Increments (Keep Last 10)
+
+```bash
+/specweave:archive --keep-last 10
+```
+
+**Output**:
+```
+📦 Archiving increments (keeping last 10)...
+
+Found 33 total increments
+Keeping: 0024-0033 (last 10)
+Candidates for archive: 0001-0023 (23 increments)
+
+Filtering by status and safety checks...
+  ✓ 0001-core-framework (completed, no blockers)
+  ✓ 0002-plugin-system (completed, no blockers)
+  ...
+  ⚠ 0015-auth-service (GitHub issue still open) - SKIPPED
+  ✓ 0016-payment-integration (completed, no blockers)
+  ...
+
+✅ Archived: 22 increments
+⚠️  Skipped: 1 increment (external sync active)
+
+📊 Archive Statistics:
+   Active: 11 increments (10 recent + 1 with open issue)
+   Archived: 53 increments (+ 22 new)
+   Total size: 245 MB
+```
+
+### Example 3: Dry Run (Preview)
+
+```bash
+/specweave:archive --older-than 90 --dry-run
+```
+
+**Output**:
+```
+🔍 DRY RUN - No files will be moved
+
+Increments older than 90 days:
+  [DRY RUN] Would archive: 0001-core-framework (152 days old)
+  [DRY RUN] Would archive: 0002-plugin-system (148 days old)
+  [DRY RUN] Would archive: 0003-auth-service (145 days old)
+  [DRY RUN] Would skip: 0004-payment (GitHub issue open)
+
+Summary:
+  Would archive: 18 increments
+  Would skip: 5 increments (active sync)
+  Total size: 180 MB
+
+Run without --dry-run to proceed:
+  /specweave:archive --older-than 90
+```
+
+### Example 4: Archive by Pattern
+
+```bash
+/specweave:archive --pattern "auth-|payment-|legacy-"
+```
+
+**Output**:
+```
+📦 Archiving increments matching pattern: auth-|payment-|legacy-
+
+Found matches:
+  ✓ 0015-auth-service
+  ✓ 0016-payment-integration
+  ✓ 0007-legacy-migration
+  ⚠ 0025-auth-enhancements (still active) - SKIPPED
+
+✅ Archived: 3 increments
+⚠️  Skipped: 1 increment (active)
+
+📊 Archive Statistics:
+   Active: 30 increments
+   Archived: 34 increments (+ 3 new)
+```
+
+## Error Handling
+
+### Increment Already Archived
+
+```
+❌ Error: Increment 0031 already exists in archive
+
+Location: .specweave/increments/_archive/0031-external-tool-status-sync/
+
+Options:
+  1. Delete from archive first, then retry
+  2. Restore from archive: /specweave:restore 0031
+  3. Resolve duplicates: /specweave:fix-duplicates
+```
+
+### Active Increment Protection
+
+```
+⚠️  Cannot archive active increments
+
+Skipped:
+  • 0032-duplicate-prevention (status: active)
+  • 0033-current-work (status: in-progress)
+
+Recommendation:
+  1. Close increments first: /specweave:done 0032
+  2. Then archive: /specweave:archive 0032
+```
+
+### External Sync Active
+
+```
+⚠️  Cannot archive increments with active external sync
+
+Skipped:
+  • 0031-external-tool-sync (GitHub issue #45 still open)
+  • 0030-jira-integration (JIRA PROJ-123 In Progress)
+
+Recommendation:
+  1. Close external issues first
+  2. Then retry: /specweave:archive 0031 0030
+
+Or force archive (not recommended):
+  /specweave:archive 0031 --force
+```
+
+## Related Commands
+
+- `/specweave:restore <increment-id>` - Restore increment from archive
+- `/specweave:done <increment-id>` - Close increment (does NOT archive!)
+- `/specweave:archive-features` - Archive features/epics (separate system)
+- `/specweave:status` - View archive statistics
+
+## Important Notes
+
+### ⚠️ Manual Only Policy
+
+**Increments are NEVER auto-archived!** This is a deliberate design decision:
+- ✅ `/specweave:done` closes increments but leaves them visible
+- ✅ You control when increments are archived
+- ✅ Keep ~10-20 recent increments visible for reference
+- ✅ Archive older work when you're ready
+
+### 🔗 Feature Archiving (Automatic)
+
+**Features/epics ARE auto-archived** when all their increments are archived:
+- After archiving increment 0031, run: `/specweave:archive-features`
+- This updates living docs and archives orphaned features
+- Keeps feature docs in sync with increment archives
+
+### 📦 Archive is Local Only
+
+Archives are **NOT** synced to GitHub/JIRA/ADO. They're local file management only.
+
+## Implementation
+
+```typescript
+import { Task } from '@claude/types';
+
+const task = new Task('archive-increments', 'Archive completed increments');
+
+task.run(async () => {
+  const { IncrementArchiver } = await import('../../../dist/src/core/increment/increment-archiver.js');
+  const archiver = new IncrementArchiver(process.cwd());
+
+  // Parse arguments
+  const args = process.argv.slice(2);
+  const incrementIds = args.filter(arg => !arg.startsWith('--'));
+
+  // Parse options
+  const options = {
+    increments: incrementIds.length > 0 ? incrementIds : undefined,
+    olderThanDays: parseOption(args, '--older-than'),
+    keepLast: parseOption(args, '--keep-last') || 10,
+    archiveCompleted: args.includes('--archive-completed'),
+    preserveActive: !args.includes('--no-preserve-active'),
+    pattern: parseOption(args, '--pattern'),
+    dryRun: args.includes('--dry-run')
+  };
+
+  // Execute archiving
+  const result = await archiver.archive(options);
+
+  // Display results
+  if (options.dryRun) {
+    console.log('\n🔍 DRY RUN - No files will be moved\n');
+  }
+
+  console.log(`✅ Archived: ${result.archived.length} increments`);
+  if (result.skipped.length > 0) {
+    console.log(`⚠️  Skipped: ${result.skipped.length} increments`);
+  }
+  if (result.errors.length > 0) {
+    console.error(`❌ Errors: ${result.errors.length} increments`);
+  }
+
+  // Show statistics
+  const stats = await archiver.getStats();
+  console.log('\n📊 Archive Statistics:');
+  console.log(`   Active: ${stats.active} increments`);
+  console.log(`   Archived: ${stats.archived} increments`);
+  console.log(`   Abandoned: ${stats.abandoned} increments`);
+  console.log(`   Total archive size: ${formatSize(stats.totalSize)}`);
+
+  // Suggest next steps
+  if (result.archived.length > 0 && !options.dryRun) {
+    console.log('\n💡 Next: Run /specweave:archive-features to sync feature docs');
+  }
+});
+
+function parseOption(args: string[], flag: string): number | string | undefined {
+  const index = args.indexOf(flag);
+  if (index !== -1 && index + 1 < args.length) {
+    const value = args[index + 1];
+    return isNaN(Number(value)) ? value : Number(value);
+  }
+  return undefined;
+}
+
+function formatSize(bytes: number): string {
+  const mb = bytes / (1024 * 1024);
+  return mb < 1 ? `${Math.round(bytes / 1024)} KB` : `${Math.round(mb)} MB`;
+}
+
+export default task;
+```
+
+## Configuration
+
+No configuration needed - all options are provided via command-line flags.
+
+Default behavior:
+- Preserves active/paused increments
+- Skips increments with open external issues
+- Warns about uncommitted changes
+- Requires explicit user action (no auto-archiving)
+
+---
+
+**Best Practice**: Archive completed increments periodically (e.g., monthly or quarterly) to keep your workspace clean while preserving all history.
+
+**Recommended Workflow**:
+```bash
+# 1. Check what would be archived
+/specweave:archive --keep-last 10 --dry-run
+
+# 2. Archive old increments
+/specweave:archive --keep-last 10
+
+# 3. Archive related features
+/specweave:archive-features
+
+# 4. Check results
+/specweave:status
+```