跳转到主要内容
archive 阶段把通过验证的 change 合并到 OpenSpec 主 spec，标注产物，并移动到 archive 目录。它是不可逆的收尾动作，因此 Comet 会在执行前确认归档与交付方式。
正常情况下只需调用 /comet。配置选择 Classic 后，内部 /comet-classic 会在 verify 通过后路由到 /comet-archive。

​
前置条件

  • phase: archive
  • verify_result: pass
  • branch_status: pending
  • 协调根属于 Git 工作树时，当前分支与 change 的 bound_branch 一致
Verify 只负责记录验证证据。branch_status 会一直保持 pending，直到本阶段按已确认的方式处理归档交付。

​
流程

​
调用的 skill

archive 阶段不加载任何 Skill。状态检查、归档和远端交付全部由 comet state、comet guard、comet archive 命令和 git 操作完成；comet archive 内部调用 OpenSpec archive 完成 delta 到主 spec 的合并。

​
归档与交付最终确认

确认前，Comet 会展示 change、验证报告、当前绑定分支、已有未提交改动的归属，以及即将执行的不可逆归档动作。 选择归档后，Comet 先保存交付选择，再确认归档：
archive_confirmation 由 Comet 自动维护（machine-owned），不能手工编辑。

​
执行归档

命令会写入可恢复 checkpoint，调用 OpenSpec 合并 delta、移动 change、校验主 spec、标注 Design Doc 和 Plan，并在实际归档目录中写入 archived: true。 归档前可以只读预览：

​
非 Git 协调目录的文档归档

协调根目录本身不属于 Git 工作树、业务代码分别放在独立子仓库时，选择“仅归档协调文档”。Comet 会合并主 Spec、移动 change，并保存归档时的主 Spec 快照和文件摘要回执。这项选择不创建 Git 提交；子仓库的提交和推送分别按各仓库的交付流程处理。 该方式的交付选择只包含以下内容，输入文件放在 change 目录之外：
归档后运行 comet guard <change-name> archive 和 comet state delivery <change-name> --verify。只有核对结果为 verification.status: complete 才清除当前选择。保留归档目录、主 Spec 快照和 .comet/classic-deliveries/ 中的回执；归档文件缺失或发生改动时，先处理核对失败，再继续完成流程。 Git 项目仍使用本地归档、推送或创建 PR 的交付选项，并执行下面的提交步骤。

​
把最终状态放入唯一归档提交

归档完成后，Comet 在提交前运行：
handled 不表示提交、push 或 PR 已经成功，也不能代替交付选择记录。guard 必须在提交前通过，确保 .comet.yaml 中的 archived: true 和 branch_status: handled 一起进入唯一归档提交。 Comet 只暂存能归因于当前 change 的路径：
  • 原 active change 路径和实际 archive 路径
  • 本次 delta 更新的 main specs
  • Design Doc / Plan 的归档元数据
  • 归档目录中最终的 .comet.yaml
检查 staged diff 后提交：
不得使用 git add -A，也不得混入用户已有改动。

​
远端交付与完成

归档提交成功后，Comet 只执行确认时选择的方式：
  • 仅保留本地提交；或
  • 推送当前绑定分支一次；或
  • 推送一次，然后创建 PR。
归档阶段不再加载 Superpowers finishing-a-development-branch，也不会在归档后再询问本地合并、保留分支或暂不推送。需要推迟交付时，应在不可逆归档前选择“暂不归档”。 完成所选操作后，运行 comet state delivery <change-name> --verify 核对实际结果。只有返回 verification.status: complete，Comet 才运行：
此时 Runtime 已核对所选交付完成，本地工作区没有 Comet 遗留的未提交 .comet.yaml。

​
失败处理

  • archive、状态写入、guard 或 commit 失败：停止，不执行远端操作。
  • push 失败：完整归档提交已在本地，当前任务只重试同一个 push。
  • PR 创建失败：分支已推送，当前任务只重试创建 PR。
  • 失败时不清除 current selection，也不宣告 workflow 完成。

​
下一步

​
SDK 实现与归档提交

新建 Classic 任务的交付提交需要包含本次 Verify 已检查、尚未提交的实现和相关测试，并包含当前归档产物。漏交实现、提交旧内容或混入检查后新增的无关文件都会被拒绝。已通过检查的删除与重命名同样需要进入提交。 让 Agent 显式暂存本 change 的文件，保留其他改动。完成实际提交及已批准的远端交付后，再按当前下一步运行 comet state complete-delivery <change-name> --commit <sha> --json。命令核对真实 Git 结果后才标记交付完成，不用归档目录代替实现提交。
最后修改于 2026年10月22日