/restore

description: Restore archived increments back to active folder
disable-model-invocation: true

Restore Increment from Archive

Restore an archived increment back to the main increments folder. Useful when you need to reference, update, or continue work on an old increment.

Usage

# Restore specific increment
sw:restore 0031

# Restore multiple increments
sw:restore 0001 0002 0003

# List archived increments
sw:restore --list

Arguments

• `<increment-ids>`: Increment IDs to restore (e.g., "1", "0001", "0031")
• `--list`: List all archived increments without restoring

Examples

Example 1: Restore Specific Increment

sw:restore 0031

**Output**:

📦 Restoring increment from archive...

Increment: 0031-external-tool-status-sync
Source: .specweave/increments/_archive/0031-external-tool-status-sync/
Target: .specweave/increments/0031-external-tool-status-sync/

Checking target location...
  ✓ Target location is empty

✅ Restored: 0031-external-tool-status-sync
   Location: .specweave/increments/0031-external-tool-status-sync/

📊 Archive Statistics:
   Active: 33 increments (+ 1 restored)
   Archived: 30 increments (- 1)

Next: sw:do 0031 (to continue work)

Example 2: List Archived Increments

sw:restore --list

**Output**:

📦 Archived Increments:

.specweave/increments/_archive/
├── 0001-core-framework (152 days old)
├── 0002-plugin-system (148 days old)
├── 0003-auth-service (145 days old)
├── 0004-payment-integration (142 days old)
├── 0005-api-gateway (140 days old)
...
├── 0030-jira-integration (35 days old)
└── 0031-external-tool-status-sync (12 days old)

Total: 31 archived increments

To restore: sw:restore <increment-id>

Example 3: Restore Multiple Increments

sw:restore 0030 0031

**Output**:

📦 Restoring increments from archive...

Restoring 0030-jira-integration...
  ✅ Restored

Restoring 0031-external-tool-status-sync...
  ✅ Restored

✅ Restored: 2 increments

📊 Archive Statistics:
   Active: 34 increments (+ 2 restored)
   Archived: 29 increments (- 2)

Error Handling

Increment Not Found in Archive

❌ Error: Increment 0031 not found in archive

Archive location: .specweave/increments/_archive/

Available archived increments:
  • 0001-core-framework
  • 0002-plugin-system
  • 0003-auth-service
  ...

Use: sw:restore --list to see all

Target Location Already Exists

❌ Error: Cannot restore 0031 - already exists in active folder

Conflict:
  Archive: .specweave/increments/_archive/0031-external-tool-status-sync/
  Active: .specweave/increments/0031-external-tool-status-sync/

Options:
  1. Delete active version first (if it's a duplicate)
  2. Resolve duplicates: sw:fix-duplicates
  3. Archive active version: sw:archive 0031
  4. Rename one version manually

Recommended: sw:fix-duplicates (auto-resolves conflicts)

Permission Errors

❌ Error: Permission denied

Could not move:
  From: .specweave/increments/_archive/0031-external-tool-status-sync/
  To: .specweave/increments/0031-external-tool-status-sync/

Check:
  • File permissions
  • Disk space
  • Files not open in another program

Safety Checks

Before restoring, the system checks:

• ✅ **Increment exists in archive**: Source folder exists
• ✅ **Target location empty**: No conflict in main folder
• ✅ **Valid increment structure**: Has required files (metadata.json)
• ✅ **Disk space available**: Enough space for restored files

Related Commands

• `sw:archive <increment-id>` - Archive completed increments
• `sw:status` - View archive statistics
• `sw:fix-duplicates` - Auto-resolve duplicate increments
• `sw:do <increment-id>` - Resume work on restored increment

Implementation

import { Task } from '@claude/types';

const task = new Task('restore-increment', 'Restore increment from archive');

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);

  // List mode
  if (args.includes('--list')) {
    const archived = await archiver.listArchived();
    console.log('\n📦 Archived Increments:\n');

    if (archived.length === 0) {
      console.log('No archived increments found.');
      return;
    }

    console.log('.specweave/increments/_archive/');
    archived.forEach(inc => {
      console.log(`├── ${inc}`);
    });
    console.log(`\nTotal: ${archived.length} archived increments`);
    console.log('\nTo restore: sw:restore <increment-id>');
    return;
  }

  // Restore mode
  const incrementIds = args.filter(arg => !arg.startsWith('--'));

  if (incrementIds.length === 0) {
    console.error('❌ Error: No increment IDs provided');
    console.log('\nUsage:');
    console.log('  sw:restore <increment-id>');
    console.log('  sw:restore --list');
    return;
  }

  // Restore each increment
  let restored = 0;
  let errors = 0;

  for (const id of incrementIds) {
    try {
      // Normalize ID to 4-digit format
      const normalizedId = id.padStart(4, '0');

      // Find archived increment
      const archived = await archiver.listArchived();
      const match = archived.find(inc => inc.startsWith(normalizedId));

      if (!match) {
        console.error(`❌ Increment ${normalizedId} not found in archive`);
        errors++;
        continue;
      }

      // Restore increment
      await archiver.restore(match);
      console.log(`✅ Restored: ${match}`);
      restored++;
    } catch (error) {
      console.error(`❌ Failed to restore ${id}: ${error.message}`);
      errors++;
    }
  }

  // Show statistics
  if (restored > 0 || errors > 0) {
    console.log('\n📊 Restore Summary:');
    if (restored > 0) {
      console.log(`   ✅ Restored: ${restored} increment${restored > 1 ? 's' : ''}`);
    }
    if (errors > 0) {
      console.log(`   ❌ Errors: ${errors} increme