/archive

description: Manually archive completed increments and sync living docs - NEVER auto-archives, explicit user action only
disable-model-invocation: true

Archive Increments (Manual Only)

**CRITICAL POLICY**: Increments are **NEVER** auto-archived. Archiving is **MANUAL ONLY** and requires explicit user action via this command.

NEW: CLI Command Available!

You can now use the CLI command for archiving:

specweave archive [increments...] [options]

This command automatically synchronizes living docs by archiving features in:

• `.specweave/docs/internal/specs/{project}/_archive/`

**Note**: Features live in project folders, NOT in `_features/`.

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

# Archive specific increment
sw:archive 0031

# Archive multiple increments
sw:archive 0001 0002 0003

# Archive all completed increments older than N days
sw:archive --older-than 90

# Keep last N increments, archive the rest
sw:archive --keep-last 10

# Archive by pattern
sw:archive --pattern "auth-*"

# Dry run (preview without archiving)
sw: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: 5** when no other filters)
• `--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
• `--external`: **Archive external living docs** (FS-XXXE folders imported from ADO/JIRA/GitHub)

External Living Docs Archiving

**CRITICAL POLICY**: External items (imported from ADO/JIRA/GitHub) are **NEVER auto-archived** during import. Archive is **USER-INITIATED ONLY** via the `--external` flag.

External features are identified by the `E` suffix (e.g., `FS-001E`, `FS-042E`).

External Archive Usage

# Archive specific external features
sw:archive --external FS-001E FS-002E

# Archive external features older than 90 days
sw:archive --external --older-than 90

# Keep last 10 external features, archive the rest
sw:archive --external --keep-last 10

# Preview external archive (dry run)
sw:archive --external --dry-run --keep-last 5

Why Separate External Archiving?

1. **Increments are source of truth** for new features you create 2. **External imports are READ-ONLY references** - they track work in external tools 3. **Different lifecycles** - increments close when work is done, external items may stay open indefinitely 4. **Prevent accidental archiving** - external items should only be archived when YOU decide

CRITICAL SAFETY FEATURE

**Default `--keep-last 5`**: When called without any filtering options (no increment IDs, no pattern, no `--older-than`, no `--archive-completed`), the archiver **automatically defaults to `--keep-last 5`** to prevent accidentally archiving ALL increments.

This safety feature ensures:

• ✅ Running `sw:archive` without options won't archive everything
• ✅ Last 5 increments always remain visible for easy reference
• ✅ Explicit criteria required to archive recent work

Archive Rules

Increments are archived when:

1. Explicitly specified by ID (e.g., `sw: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

sw: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/

🔄 Auto-archiving orphaned features...
✅ Auto-archived features: FS-031
📝 Updated 0 links in living docs

📊 Archive Statistics:
   Active: 32 increments
   Archived: 31 increments (+ 1 new)
   Auto-archived features: 1
   Auto-archived epics: 0

Next: sw:restore 0031 (if you need to unarchive)

Example 2: Archive Old Increments (Keep Last 10)

sw: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 St