Comet ArchiveSAFE

Comet: agent skill harness for turning ideas into evaluated workflows

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: comet-archive
description: '归档并交付 Classic change。在用户调用 /comet-archive,或 Classic Runtime 进入 Archive、恢复交付时使用。'
---

# Comet 阶段 5:归档(Archive)

收到入口返回的 layout 后,按 `comet-classic/reference/classic-layout.md` 确定各逻辑根对应的目录。当前上下文已有这份协议时,无需重复加载。本文件中的 OpenSpec CLI 调用均通过适配器执行,文件路径均基于已绑定的 `<classic-*>` 根目录,无需先额外运行 root show。

## 前置条件

- 验证已通过(阶段 4 完成)
- 归档或所选交付动作尚未完成;恢复不要求 branch_status 仍为 pending
- `<classic-change-dir>/.comet.yaml` 中 `verify_result: pass`

## 步骤

### 0. 设置输出语言

归档摘要和流程完成说明,使用本轮入口返回的 configuration.language,不再单独查询语言。

### 0b. 入口状态验证(Entry Check)

按 `comet-classic/reference/scripts.md` 使用正式支持的 `comet` CLI,执行以下入口验证。从任意入口恢复任务时,先按 `comet-classic/reference/context-recovery.md` 检查恢复状态:

```bash
comet state select <change-name>
comet state check <name> archive --json
```

上一阶段 guard 已成功返回本阶段状态信息时,直接使用其中的状态与 `agent.continuation` 继续,不重复 select/check;恢复任务、工作区变化或外部状态变化时,才执行上述入口验证。使用入口返回的 layout、configuration、nextAction 和 delivery 摘要继续。丢失上下文后恢复任务时,按 context-recovery.md 读取所需详情。已有授权仍然有效、交付目标也没有变化时,只继续未完成的动作,不重复询问。失败时,处理返回的具体原因。

若上述 `select` / `check` 输出 `BLOCKED` 或分支绑定 `ERROR`,且原因是 `bound_branch` 与当前分支不一致,立即按 `comet-classic/reference/decision-point.md` 暂停,让用户单选:切回绑定分支后重新运行入口验证,或在用户明确确认当前分支应接管该 change 后运行 `comet state rebind <change-name>` 并重新入口验证。不得自行切换分支,不得自行换绑。

### 1. 请用户确认归档与交付方式

读取入口返回的 configuration.isolation 与 delivery。没有有效授权,或交付目标发生变化时,**按 decision-point.md 暂停,请用户确认归档和交付方式**。已有授权时,先由 Runtime 核对实际 Git 状态和交付进度,再按 nextAction 继续。不能仅凭 branch_status: handled 就认定用户已授权归档、push 或创建 PR,也不能在获得授权前运行 archive-confirm 或 archive。

确认前必须向用户展示简短摘要:

- change 名称
- 验证报告路径和结论
- 当前分支、工作区,以及未提交改动分别属于哪些工作的核对结果
- 本次归档将执行的不可逆动作:按 OpenSpec delta 语义合并主 spec、标注 design doc / plan、移动 change 到 archive 目录
- 归档完成后将采用的提交处理方式:只保留在本地、推送当前绑定分支,或推送后创建 PR

Git 协调根的用户确认问题必须以单选题形式呈现,包含以下全部选项。文本降级模式必须使用下表;使用结构化提问时,将“方式”作为短标签、“实际影响”作为说明,不得缩短为含义不明确的选项:

| 选项 | 方式                            | 实际影响                                                                                                                                                             |
| ---- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A    | 仅归档(不推送)                | 完成归档并创建唯一归档提交;提交只保留在当前绑定分支,不推送、不创建 PR                                                                                              |
| B    | 「确认归档并立即推送」          | 完成归档并创建唯一归档提交,然后推送当前绑定分支;不创建 PR                                                                                                          |
| C    | 「确认归档、立即推送并创建 PR」 | 完成归档并创建唯一归档提交,推送当前绑定分支,然后创建 PR                                                                                                            |
| D    | 「需要调整或重新验证」          | 不归档;运行 `comet state transition <change-name> archive-reopen` 回到 `phase: verify`,再调用 `/comet-verify`;若确认需要修复,再按验证失败决策回到 `/comet-build` |
| E    | 「暂不归档」                    | 不运行 `archive-confirm` 或归档命令,不提交、不推送;保留未归档的 change、`phase: archive` 和 `branch_status: pending`,等待稍后再次调用 `/comet-archive`            |

若协调根目录本身不属于 Git 工作树,而业务代码在独立的子仓库,改为向用户确认“仅归档协调文档”或选择 D/E。说明该方式会合并主 spec、移动并保存归档文档,在协调根的 `.comet/classic-deliveries/` 留下文件摘要回执;子仓库的提交和推送须按各仓库单独核对,不能作为协调文档的归档提交。用户确认后写入 `{ "action": "archive-only" }`,不填写 `targetBranch`、`remote`、`commit` 或 `prUrl`。该方式仅适用于非 Git 协调根;Git 项目仍使用 A/B/C。

只有用户选择 A、B、C 或明确确认上述“仅归档协调文档”后,才将选择保存为 JSON 并通过 Runtime 记录,再确认归档:

```bash
comet state delivery <change-name> --file <json-path>
comet state transition <change-name> archive-confirm
```

Git 交付的 JSON 包含 action(A=local、B=push、C=pr)、targetBranch,以及可选的 remote、commit 和 prUrl。文档归档的 JSON 只包含 `action: archive-only`。初次记录时,只填写已确认的动作和目标;尚不知道的 commit/prUrl 不得伪造,等操作实际完成后再补写。

targetBranch 是接收归档提交的绑定分支,与 PR 的 base 分支含义不同。PR base 使用已有的明确配置;存在歧义时先澄清。存在多个 remote 时,明确推送目的地,不自行猜测。例如,用户已确认推送时:

```json
{
  "action": "push",
  "targetBranch": "<confirmed-bound-branch>",
  "remote": "<confirmed-remote>"
}
```

用文件工具保存 JSON,再传给 delivery --file。输入文件放在 change 目录之外(例如仓库根的 `delivery-input.json`),用后删除;不得写进 change 目录,尤其不得使用 `<change-dir>/.comet/delivery.json`——那是 Runtime 的交付记录,Runtime 会识别同一路径的大小写写法和文件系统别名,并直接报告输入路径冲突。输入只包含 action、targetBranch 和可选的 remote、commit、prUrl;schemaVersion 等字段属于 Runtime 记录,不得出现在输入中。归档提交确认后,在同一完整记录中追加 `"commit": "<actual-archive-commit-sha>"`;action 为 pr 且 PR 已创建时,再追加真实 prUrl。commit 由 Runtime 保存在 Git 忽略的交付回执中,change 目录内被跟踪的 `delivery.json` 始终不含 commit;归档提交后 change 目录必须与该提交保持零差异,不得在其中新增、修改或删除文件,否则完整性校验失败。local 示例只需 action:local 和已确认 targetBranch,不要求 remote。

普通 `comet state delivery <change-name>` 只读取已保存的记录,入口摘要也不访问网络。恢复远端交付、上次调用没有返回明确结果,或准备宣告完成时,必须显式运行:

```bash
comet state delivery <change-name> --verify
```

返回结果为 `{delivery, verification}`。delivery 是已保存的用户选择和执行进度,verification 是 Runtime 对实际 Git、远端分支和 PR 的只读核对结果。仅有 delivery 记录或入口检查成功,不能证明远端交付已经完成。按核对结果处理:

- 已确认 not-yet-delivered,例如尚未首次 push,或已推送但尚未创建 PR:授权和目标仍然有效时,继续未完成的动作,再用 --verify 核对;不能仅因为 notVerified/needsVerification 就停止。
- unavailable,即网络、权限或服务故障导致无法确定实际结果,或出现目标冲突、结果不确定:保留记录并停止。先解决只读核对遇到的问题,不盲目重试 push,也不重复创建 PR。

delivery 写入或 transition 失败均停止。只有两者成功才继续 Step 2。用户选择 D 时运行 archive-reopen,旧交付授权应失效,重新验证后重新确认;选择 E 直接停止,不归档、提交、推送或设置 handled。

### 2. 执行归档

运行归档脚本:

```bash
comet archive "<change-name>"
```

脚本自动执行:

1. 入口状态验证(phase=archive, verify_result=pass, archive_confirmation=confirmed, archived=false)
2. 在归档前更新 Design Doc 的元数据(archived-with, status)
3. 在归档前更新 Plan 的元数据(archived-with)
4. 调用 OpenSpec archive 按 delta 语义合并主 spec 并移动 change 到归档目录
5. 检查主 spec 中没有残留仅用于增量规格的章节标题(delta-only section)
6. 在 OpenSpec 实际归档目录中更新 archived 状态,并处理 pending recovery 元数据,保证中断后能够恢复

如脚本返回非零退出码,报告错误并停止。
如脚本返回零退出码,归档完成。

脚本摘要中的 `X/Y steps succeeded` 以真实执行步骤计数,不会因 delta spec 同步或文档标注重复累计。

脚本会调用 OpenSpec 归档能力按 `ADDED/MODIFIED/REMOVED/RENAMED` 语义合并主 spec,并在归档后校验主 spec 中没有残留 delta-only section 标题。

如需预览而不实际执行,使用 `--dry-run` 参数。

### 3. Spec 流程完成

Spec 从需求讨论到归档的完整流程如下,到此全部完成:

```
brainstorming → delta spec → 实施 → 验证 → 主 spec 合并 → design do

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Comet Archive](https://modelsatlas.com/skills/rpamis/comet-archive/badge.svg)](https://modelsatlas.com/skills/rpamis/comet-archive/)

Not your listing, or something out of date? Claim or update your listing.