> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# comet archive

> 完成 OpenSpec archive、主 spec 校验、frontmatter 标注和归档收尾。

`comet archive` 是归档阶段的稳定、确定性入口。真实归档会把通过验证且已获最终确认的 change 合并 delta spec 到主 spec，并移入 OpenSpec archive 目录；`--dry-run` 可以在最终确认前安全预览。

下文用 `<classic-root>` 表示当前 Classic OpenSpec 根目录：新项目默认是 `docs/openspec/`，保留旧布局的项目是 `openspec/`。实际位置由 `classic.artifact_layout` 决定，详见[项目文件结构](/zh/guides/project-structure)。

## 基本形式

```bash theme={null}
comet archive <change-name>
```

预览（不真正执行 OpenSpec）：

```bash theme={null}
comet archive <change-name> --dry-run
```

## 它会做什么

按顺序执行：

1. **校验 change 名**（kebab-case）。
2. **定位 change 目录**，如果已被之前的归档移走，扫描 archive 目录恢复。
3. **校验共同入口状态**：`phase` 必须是 `archive`，`verify_result` 必须是 `pass`。
4. **检查归档目标可用**：`<classic-root>/changes/archive/YYYY-MM-DD-<name>` 不能已存在。
5. **处理执行模式**：`--dry-run` 到此只报告预览，不要求最终确认、不写 pending action；真实归档要求 `archive_confirmation: confirmed`。
6. **写 pending action checkpoint**，支持真实归档中断后恢复。
7. **调用 OpenSpec archive**：`openspec archive <change> --yes`，执行 delta→主 spec 合并（按 `ADDED`/`MODIFIED`/`REMOVED`/`RENAMED` 语义）并移动 change 目录。
8. **解析归档目录**：重新定位 OpenSpec 实际放的位置（日期前缀可能变化）。
9. **校验主 spec 干净**：扫描 `<classic-root>/specs/*/spec.md`，残留 delta-only 标题就 FATAL。
10. **标注并完成状态**：幂等标注 design doc/plan，设置 `archived: true`，Run 转为 `completed`，清除 pending action。

Design Doc 和 Plan 的归档注释可以安全重复执行，不会重复追加字段，并会保留正常的 Markdown 文件结尾，避免产生 `git diff --check` 格式错误。

## 不自动提交

脚本执行完只移动文件、合并 spec、标注 frontmatter——**不调用 `git`**。完成后工作树里会留下这些未提交变更：

* `<classic-root>/changes/<name>/` → `<classic-root>/changes/archive/YYYY-MM-DD-<name>/` 的目录移动
* 主 spec 的 delta 合并结果
* Design Doc / Plan frontmatter 的归档标注

需要你手动提交，否则归档结果悬在工作树：

```bash theme={null}
git add -A
git commit -m "chore: archive <change-name>"
```

归档命令本身不提交或推送。Archive Skill 会在执行前确认立即推送或推送并创建 PR，并在归档后先写入 `branch_status: handled`、通过 archive guard，再创建并推送唯一完整提交。

## 归档目录结构

```text theme={null}
<classic-root>/changes/archive/YYYY-MM-DD-<change-name>/
```

日期取 UTC，保证跨时区一致。

## 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 会报错。归档完整性由退出码和归档目录状态判断。

<Note>
  已归档的 Design Doc、Plan 和验证报告仍从项目根的 <code>docs/superpowers/</code>{' '}
  解析，因此可以继续在 Dashboard 中查看。安装包保留 <code>comet-archive.mjs</code> 兼容
  launcher，但普通使用应优先采用 <code>comet archive</code>。
</Note>

## 下一步

* [工作流概念](/zh/concepts/workflow) — 归档在五阶段中的位置和完整生命周期
* [状态与配置](/zh/concepts/state-management) — `archived` 字段和归档状态