openspec-archiving

Are all tasks complete and tested?
Has this change been deployed to production?
Should I proceed with archiving?

# 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

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

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

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

# 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

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

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

# 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

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

# Move entire change folder to archive
mv spec/changes/{change-id} spec/archive/${TIMESTAMP}-{change-id}

# Check archive exists
ls -la spec/archive/${TIMESTAMP}-{change-id}
 
# Check changes directory is clean
ls spec/changes/ | grep "{change-id}"  # Should return nothing

# Check requirement format
grep -n "### Requirement:" spec/specs/**/*.md
 
# Check scenario format
grep -n "#### Scenario:" spec/specs/**/*.md
 
# Count requirements per spec
for spec in spec/specs/**/spec.md; do
    count=$(grep -c "### Requirement:" "$spec")
    echo "$spec: $count requirements"
done

Action: Append to living spec
Location: End of file (before any footer/appendix)
Format: Copy requirement + all scenarios exactly as written

Action: Replace existing requirement
Location: Find by requirement name, replace entire block
Format: Use complete updated text from delta (don't merge, replace)
Note: Old version is preserved in archive

Action: Delete requirement, add deprecation comment
Location: Find by requirement name
Format: Delete entire block, optionally add <!-- Removed YYYY-MM-DD: reason -->

Action: Update requirement name, keep content
Location: Find by old name, update to new name
Format: Just change the header: ### Requirement: NewName
Note: Typically use MODIFIED instead

# After merging, check diff
git diff spec/specs/
 
# Review changes
git diff spec/specs/authentication/spec.md
 
# If correct, commit
git add spec/specs/
git commit -m "Merge spec deltas from add-user-auth"
 
# Then archive
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth

# Move complete change folder
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth

# Don't cherry-pick files
mv spec/changes/add-user-auth/proposal.md spec/archive/
# (leaves orphaned files)

❌ Don't: Edit files in spec/archive/
✓ Do: Treat archive as read-only history

# Commit 1: Merge deltas
git add spec/specs/
git commit -m "Merge spec deltas from add-user-auth
 
- Added User Login requirement
- Modified Password Policy requirement
- Removed Legacy Auth requirement"
 
# Commit 2: Archive change
git add spec/archive/ spec/changes/
git commit -m "Archive add-user-auth change"

Change adds 1 new requirement → Append to spec → Archive

Change modifies 1 requirement → Replace in spec → Archive

Change removes 1 requirement → Delete from spec with comment → Archive

Change adds 5 requirements across 2 specs
→ Append each to respective spec
→ Verify all are merged
→ Archive

1. If names match but content differs → Use MODIFIED pattern
2. If truly different requirements → Rename one
3. If duplicate by mistake → Use whichever is correct

1. Search by partial name: grep -i "login" spec/specs/**/*.md
2. Check if already removed
3. Check if in different capability file

1. Fix formatting manually
2. Re-run validation: grep -n "###" spec/specs/**/*.md
3. Ensure consistent heading levels