/sdd-archive

Close a completed change and sync specs to source of truth

Overview

The /sdd-archive command finalizes a completed change by merging delta specs into the main specs (source of truth) and moving the change folder to the archive. This closes the SDD cycle.

Only run this command after successful verification. The change should be code-complete and tested.

Usage

/sdd-archive [change-name]

change-name · string

Optional. The change to archive. If omitted, archives the most recent verified change.

What It Does

1. Validates Readiness

Checks prerequisites:

• ✓ Verification report exists?
• ✓ Verification status is PASS or PASS WITH WARNINGS?
• ✓ No CRITICAL issues?
• ✓ All MUST/SHALL requirements met?

2. Merges Delta Specs

Syncs change specs into main specs:

ADDED specs

Copies new spec files to main specs directory:

changes/add-csv-export/specs/api/csv-export.md
                             ↓
specs/api/csv-export.md

MODIFIED specs

Merges changes into existing spec files:

• Adds new requirements
• Updates modified requirements
• Preserves existing unaffected content

REMOVED specs

Deletes obsolete spec files or sections:

• Warns before large removals
• Asks for confirmation on destructive changes

3. Moves to Archive

Relocates the change folder with timestamp:

openspec/changes/add-dark-mode/
              ↓
openspec/changes/archive/2024-03-04-add-dark-mode/

Archive preserves:

• Proposal
• Exploration
• Specs (delta)
• Design
• Tasks
• Verification report

4. Generates Archive Report

Creates a summary:

• Change name and date
• Specs merged
• Files affected
• Audit trail reference

Example Output

Successful Archive

/sdd-archive

Output:

## Archiving change: add-dark-mode

### Pre-Archive Validation
✓ Verification report exists
✓ Status: PASS WITH WARNINGS
✓ No CRITICAL issues
✓ All MUST/SHALL requirements met
✓ Ready to archive

---

## Merging Delta Specs

### ADDED Specs

Copying new spec files to main specs...

✓ specs/ui/theme-toggle.md
  - 3 requirements added
  - 7 scenarios added
  
✓ specs/core/theme-system.md
  - 4 requirements added
  - 9 scenarios added

### MODIFIED Specs

Updating existing spec files...

✓ specs/ui/layout.md
  - Updated requirement: "Layout SHOULD support theme variants"
  - Added scenario: "Layout applies theme class to root element"

### REMOVED Specs
None

---

## Moving to Archive

Relocating change folder...

openspec/changes/add-dark-mode/ ↓ openspec/changes/archive/2024-03-04-add-dark-mode/

✓ Moved successfully

---

## Archive Summary

**Change**: add-dark-mode
**Completed**: 2024-03-04
**Specs Merged**: 3 files (2 added, 1 modified)
**Files Affected**: 5 implementation files

### Source of Truth Updated
Main specs now reflect the current system state including dark mode support.

### Audit Trail
Full change history preserved in:
`openspec/changes/archive/2024-03-04-add-dark-mode/`

Includes:
- proposal.md - Original intent and scope
- exploration.md - Codebase analysis
- specs/ - Delta specifications
- design.md - Technical approach
- tasks.md - Implementation checklist
- verification-report.md - Quality validation

---

✅ Archive complete. Change closed successfully.

The specs directory is now the source of truth for the current system.

Archive with Warnings

## Archiving change: refactor-auth

### Pre-Archive Validation
✓ Verification report exists
⚠️  Status: PASS WITH WARNINGS
✓ No CRITICAL issues
⚠️  1 WARNING: TODO comment in auth-service.ts
✓ All MUST/SHALL requirements met

---

⚠️  Warning Found

The verification report contains 1 WARNING:
- TODO comment: "Add rate limiting to login endpoint"

This doesn't block archiving, but consider:
1. Creating a follow-up issue/change for this TODO
2. Or removing the TODO if not planned

Proceed with archive? (yes/no)

User types: yes

---

## Merging Delta Specs

### REMOVED Specs

⚠️  Destructive changes detected!

The following specs will be REMOVED:
- specs/auth/session-cookies.md (replaced by JWT approach)

This will DELETE 237 lines including:
- 5 requirements
- 12 scenarios

Confirm deletion? (yes/no)

User types: yes

✓ Removed specs/auth/session-cookies.md

### ADDED Specs

✓ specs/auth/jwt-tokens.md
  - 6 requirements added
  - 14 scenarios added

---

## Moving to Archive

✓ Moved to openspec/changes/archive/2024-03-04-refactor-auth/

---

✅ Archive complete with warnings addressed.

Archive Structure

The archive preserves complete change history:

openspec/changes/archive/
├── 2024-03-04-add-dark-mode/
│   ├── proposal.md
│   ├── exploration.md
│   ├── specs/
│   │   ├── ui/theme-toggle.md
│   │   └── core/theme-system.md
│   ├── design.md
│   ├── tasks.md
│   └── verification-report.md
├── 2024-03-01-fix-auth-bug/
│   └── ...
└── 2024-02-28-add-csv-export/
    └── ...

Delta Spec Merging

The archiver intelligently merges specs:

ADDED Requirements

Change spec:

## ADDED Requirements

### Requirement: CSV Export
The system SHALL support exporting data to CSV format.

Main spec after merge:

## Requirements

### Requirement: JSON Export
{existing content}

### Requirement: CSV Export
The system SHALL support exporting data to CSV format.

MODIFIED Requirements

Change spec:

## MODIFIED Requirements

### Requirement: Data Export
The system SHALL support multiple export formats.
(Previously: The system SHALL support JSON export.)

Main spec after merge:

### Requirement: Data Export
The system SHALL support multiple export formats.

REMOVED Requirements

Change spec:

## REMOVED Requirements

### Requirement: CSV Email Delivery
{content that's being removed}

Main spec after merge:

{Section deleted, asks for confirmation first}

When to Use

After Verification

Run after /sdd-verify passes successfully

Change Complete

All code written, tested, and reviewed

Before Deployment

Close the change before deploying to production

Cycle Completion

Final step in the SDD workflow

Don’t archive if:

• Verification has CRITICAL issues
• Tests are failing
• MUST/SHALL requirements not met
• Code review pending

Archive Checklist

Before archiving, confirm:

✓ Verification passed

• /sdd-verify run successfully
• Status is PASS or PASS WITH WARNINGS
• No CRITICAL issues
• All tests passing

✓ Implementation complete

• All tasks marked done
• Code reviewed (if team process)
• No TODOs (or documented as follow-up)
• Ready to deploy

✓ Specs accurate

• Delta specs reflect actual changes
• No placeholder content
• Scenarios match implementation

✓ Documentation updated

• README updated if needed
• API docs updated if needed
• Migration guide written if needed

Rollback After Archive

If you need to revert an archived change:

1. Find archive

   cd openspec/changes/archive/2024-03-04-add-dark-mode/
   
2. Read rollback plan

   cat proposal.md
   # See "Rollback Plan" section
   
3. Revert code changes

   Use git to revert commits or manually undo changes

4. Revert spec changes

   Manually undo spec merges (ADDED → delete, MODIFIED → restore previous)

Spec Sync Behavior

How specs are synced:

Change Spec	Main Spec	Action
ADDED new file	Doesn’t exist	Copy file to main specs
ADDED section	File exists	Append section to file
MODIFIED section	Exists	Replace section in file
REMOVED section	Exists	Delete section (with warning)
REMOVED file	Exists	Delete file (with confirmation)

Archive Reports

The archive report includes:

# Archive Report: add-dark-mode

Date: 2024-03-04

## Change Summary
- **Intent**: Add user-toggleable dark mode
- **Complexity**: Medium (2-3 days)
- **Risk Level**: Medium

## Implementation
- **Tasks Completed**: 9/9
- **Files Modified**: 5
- **Tests Added**: 5
- **Lines Changed**: +387 / -12

## Specs Synced
- **Added**: 2 files (11 requirements, 16 scenarios)
- **Modified**: 1 file (1 requirement updated)
- **Removed**: 0 files

## Verification
- **Status**: PASS WITH WARNINGS
- **Tests**: 52 passing
- **Coverage**: 89%
- **Warnings**: 1 (TODO comment)

## Archive Location
openspec/changes/archive/2024-03-04-add-dark-mode/

## Next Steps
Specs now reflect current system state. Archive preserved for audit trail.

Related Commands

• /sdd-verify - Always verify before archiving
• /sdd-apply - Implement before archiving
• /sdd-new - Start the next change