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:

# 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:

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:

# 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

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

Example:

# 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):

## 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):

# 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:

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

# First, identify the line range of the old requirement
START_LINE=$(grep -n "### Requirement: User Login" spec/specs/authentication/spec.md | cut -d: -f1)

# Find the end (next requirement or end of file)
END_LINE=$(tail -n +$((START_LINE + 1)) spec/specs/authentication/spec.md | \
           grep -n "^### Requirement:" | head -1 | cut -d: -f1)

# Delete old requirement
sed -i "${START_LINE},${END_LINE}d" spec/specs/authentication/spec.md

# Insert new requirement at same position
# (Extract from delta and insert)

Manual approach (recommended for safety):

1. Open living spec in editor
2. Find the requirement by name
3. Delete entire block (requirement + all scenarios)
4. Paste updated requirement from delta
5. Save

Step 6: Merge REMOVED requirements into living specs

For each ## REMOVED Requirements section:

Process:

1. Locate the requirement in the living spec
2. Delete the entire requirement block
3. Add a comment documenting the removal

Example:

# Option 1: Delete with comment
# Manually edit spec/specs/authentication/spec.md

# Add deprecation comment
echo "<!-- Requirement 'Legacy Password Reset' removed $(date +%Y-%m-%d) -->" >> spec/specs/authentication/spec.md

# Delete the requirement block manually or with sed

Pattern:

<!-- Removed 2025-10-26: User must use email-based password reset -->
~~### Requirement: SMS Passwor

...