openspec-archiving

规范归档

归档已完成的变更提案，并将其规范增量合并到现行规范文档中。

快速入门

归档主要包括两项操作：

1. 将变更文件夹移至带有时间戳的归档目录
2. 将规范增量合并到现行规范中（ADDED/MODIFIED/REMOVED 操作）

关键规则：归档前，确认所有任务均已完成。归档意味着已部署并完成。

工作流

复制此清单并跟踪进度：

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

步骤 1：确认实现已完成

归档前，确认所有工作均已完成：

# 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

询问用户：

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

步骤 2：检查要合并的规范增量

了解将要合并的内容：

# 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

确定：

• 受影响的功能
• ADDED/MODIFIED/REMOVED 需求的数量
• 这些变更应归入现行规范中的哪些位置

步骤 3：创建带时间戳的归档目录

# 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

步骤 4：将 ADDED 需求合并到现行规范中

对于每个 ## ADDED Requirements 部分：

流程：

1. 找到目标现行规范文件
2. 将新需求追加到文件末尾
3. 保持正确的 Markdown 格式

示例：

源文件（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

目标文件（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

步骤 5：将 MODIFIED 需求合并到现行规范中

对于每个 ## MODIFIED Requirements 部分：

流程：

1. 在现行规范中找到已有需求
2. 替换整个需求块（包括所有场景）
3. 使用增量中的完整更新文本

使用 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)

手动操作（为确保安全，推荐此方式）：

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

步骤 6：将 REMOVED 需求从现行规范中移除

对于每个 ## REMOVED Requirements 部分：

流程：

1. 在现行规范中找到该需求
2. 删除整个需求块
3. 添加注释，记录移除情况

示例：

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

# Add deprecation comment
echo "" >> spec/specs/authentication/spec.md

# Delete the requirement block manually or with sed

格式：

~~### Requirement: SMS Password Reset~~

步骤 7：将变更文件夹移至归档目录

合并所有增量后：

# 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

步骤 8：验证现行规范的结构

合并后，验证现行规范格式正确：

# 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

手动检查：

• 打开每个已修改的规范文件
• 确认 Markdown 格式正确
• 检查需求的逻辑是否连贯
• 确保没有重复的需求

合并逻辑参考

ADDED 操作

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

MODIFIED 操作

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

REMOVED 操作

Action: Delete requirement, add deprecation comment
Location: Find by requirement name
Format: Delete entire block, optionally add 

RENAMED 操作（不常见）

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

最佳实践

模式 1：移动前先验证

务必在移至归档目录前验证增量合并结果：

# 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

模式 2：整体归档

归档整个变更，而非单个文件：

正确：

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

模式 3：保留归档内容

归档是历史记录。切勿修改已归档文件：

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

模式 4：Git 提交策略

建议的提交工作流：

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

进阶主题

复杂增量：参见 reference/MERGE_LOGIC.md

冲突解决：如果多个变更修改了同一项需求，则需要手动合并。

回滚策略：若要回滚归档，请逆向执行此流程（将文件从归档目录移回变更目录，并从现行规范中移除已合并内容）。

常见模式

模式 1：简单新增

Change adds 1 new requirement → Append to spec → Archive

模式 2：行为变更

Change modifies 1 requirement → Replace in spec → Archive

模式 3：弃用

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

模式 4：包含多项需求的功能

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

应避免的反模式

不要：

• 归档未完成的实现
• 在部署前合并增量
• 修改已归档的文件
• 合并后跳过验证
• 忘记 git commit 合并后的规范

应该：

• 归档前确认所有任务均已完成
• 谨慎且完整地合并增量
• 将归档视为不可变的历史记录
• 验证合并后的规范结构
• 在移动到归档前提交合并后的规范

故障排除

问题：合并冲突（需求已存在于现行规范中）

解决方案：

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

参考资料

• MERGE_LOGIC.md - 合并操作规则详解

---

Token 预算：此 SKILL.md 约 480 行，低于建议的 500 行上限。