Openspec Archiving

# Specification Archiving

Archives completed change proposals and merges their spec deltas into the living specification documentation.

## Quick Start

Archiving involves two main operations:
1. **Move change folder** to archive with timestamp
2. **Merge spec deltas** into living specs (ADDED/MODIFIED/REMOVED operations)

**Critical rule**: Verify all tasks are complete before archiving. Archiving signifies deployment and completion.

## Workflow

Copy this checklist and track progress:

```
Archive Progress:
- [ ] Step 1: Verify implementation is complete
- [ ] Step 2: Review spec deltas to merge
- [ ] Step 3: Create timestamped archive directory
- [ ] Step 4: Merge ADDED requirements into living specs
- [ ] Step 5: Merge MODIFIED requirements into living specs
- [ ] Step 6: Merge REMOVED requirements into living specs
- [ ] Step 7: Move change folder to archive
- [ ] Step 8: Validate living spec structure
```

### Step 1: Verify implementation is complete

Before archiving, confirm all work is done:

```bash
# Check for IMPLEMENTED marker
test -f spec/changes/{change-id}/IMPLEMENTED && echo "✓ Implemented" || echo "✗ Not implemented"

# Review tasks
cat spec/changes/{change-id}/tasks.md

# Check git status for uncommitted work
git status
```

**Ask the user**:
```markdown
Are all tasks complete and tested?
Has this change been deployed to production?
Should I proceed with archiving?
```

### Step 2: Review spec deltas to merge

Understand what will be merged:

```bash
# List all spec delta files
find spec/changes/{change-id}/specs -name "*.md" -type f

# Read each delta
for file in spec/changes/{change-id}/specs/**/*.md; do
    echo "=== $file ==="
    cat "$file"
done
```

**Identify**:
- Which capabilities are affected
- How many requirements are ADDED/MODIFIED/REMOVED
- Where in living specs these changes belong

### Step 3: Create timestamped archive directory

```bash
# Create archive with today's date
TIMESTAMP=$(date +%Y-%m-%d)
mkdir -p spec/archive/${TIMESTAMP}-{change-id}
```

**Example**:
```bash
# For change "add-user-auth" archived on Oct 26, 2025
mkdir -p spec/archive/2025-10-26-add-user-auth
```

### Step 4: Merge ADDED requirements into living specs

For each `## ADDED Requirements` section:

**Process**:
1. Locate the target living spec file
2. Append the new requirements to the end of the file
3. Maintain proper markdown formatting

**Example**:

**Source** (`spec/changes/add-user-auth/specs/authentication/spec-delta.md`):
```markdown
## ADDED Requirements

### Requirement: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN valid credentials
WHEN user submits login form
THEN system creates session
```

**Target** (`spec/specs/authentication/spec.md`):
```bash
# Append to living spec
cat >> spec/specs/authentication/spec.md << 'EOF'

### Requirement: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN valid credentials
WHEN user submits login form
THEN system creates session
EOF
```

### Step 5: Merge MODIFIED requirements into living specs

For each `## MODIFIED Requirements` section:

**Process**:
1. Locate the existing requirement in the living spec
2. Replace the ENTIRE requirement block (including all scenarios)
3. Use the complete updated text from the delta

**Example using sed**:

```bash
# Find and replace requirement block
# This is conceptual - actual implementation depends on structure

# First, identify the line range of the old requ