comet archive 是归档阶段的稳定、确定性入口。真实归档会把通过验证且已获最终确认的 change 合并 delta spec 到主 spec，并移入 OpenSpec archive 目录；--dry-run 可以在最终确认前安全预览。
下文用 <classic-root> 表示当前 Classic OpenSpec 根目录：新项目默认是 docs/openspec/，保留旧布局的项目是 openspec/。实际位置由 classic.artifact_layout 决定，详见项目文件结构。
基本形式
它会做什么
按顺序执行：- 校验 change 名（kebab-case）。
- 定位 change 目录，如果已被之前的归档移走，扫描 archive 目录恢复。
- 校验共同入口状态：
phase必须是archive，verify_result必须是pass。 - 检查归档目标可用：
<classic-root>/changes/archive/YYYY-MM-DD-<name>不能已存在。 - 处理执行模式：
--dry-run到此只报告预览，不要求最终确认、不写 pending action；真实归档要求archive_confirmation: confirmed。 - 写 pending action checkpoint，支持真实归档中断后恢复。
- 调用 OpenSpec archive：
openspec archive <change> --yes，执行 delta→主 spec 合并（按ADDED/MODIFIED/REMOVED/RENAMED语义）并移动 change 目录。 - 解析归档目录：重新定位 OpenSpec 实际放的位置（日期前缀可能变化）。
- 校验主 spec 干净：扫描
<classic-root>/specs/*/spec.md，残留 delta-only 标题就 FATAL。 - 标注并完成状态：幂等标注 design doc/plan，设置
archived: true，Run 转为completed，清除 pending action。
git diff --check 格式错误。
不自动提交
脚本执行完只移动文件、合并 spec、标注 frontmatter——不调用git。完成后工作树里会留下这些未提交变更：
<classic-root>/changes/<name>/→<classic-root>/changes/archive/YYYY-MM-DD-<name>/的目录移动- 主 spec 的 delta 合并结果
- Design Doc / Plan frontmatter 的归档标注
branch_status: handled、通过 archive guard，再创建并推送唯一完整提交。
归档目录结构
delta spec 合并语义
delta spec 的ADDED/MODIFIED/REMOVED/RENAMED 是 OpenSpec 原生概念。实际的 delta→主 spec 合并由 OpenSpec CLI 执行，Comet 只负责：
- 调用
openspec archive --yes - 事后检查主 spec 里没有残留 delta-only 标题（防止
## ADDED/MODIFIED/REMOVED/RENAMED Requirements泄漏到稳定 spec）
重要边界
- 不要手工把 change 标记为 archived。手工 transition 容易造成状态和文件位置不一致。
- 用户确认通过
comet state transition <name> archive-confirm写入 machine-owned 确认状态；重新打开会清除旧确认。不要直接编辑字段伪造批准。 - 归档成功后不要再跑
comet guard <name> archive——活跃目录已不存在，guard 会报错。归档完整性由退出码和归档目录状态判断。
已归档的 Design Doc、Plan 和验证报告仍从项目根的
docs/superpowers/
解析，因此可以继续在 Dashboard 中查看。安装包保留 comet-archive.mjs 兼容
launcher，但普通使用应优先采用 comet archive。