comet-archive

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Comet 阶段 5：归档（Archive）

Comet Phase 5: Archive

前置条件

Prerequisites

验证已通过（阶段 4 完成）
分支已处理

openspec/changes/<name>/.comet.yaml

中

verify_result: pass

Verification passed (Phase 4 completed)
Branch has been processed

verify_result: pass

is set in

openspec/changes/<name>/.comet.yaml

步骤

Steps

0. 入口状态验证（Entry Check）

0. Entry Status Check

执行入口验证：

bash

COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
bash "$COMET_STATE" check <name> archive

验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。

Perform entry verification:

bash

COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
bash "$COMET_STATE" check <name> archive

Proceed to Step 1 after verification passes. If verification fails, the script will output the specific failure reason.

1. 执行归档

1. Execute Archiving

运行归档脚本，自动完成以下全部步骤：

bash

bash "$COMET_ARCHIVE" "<change-name>"

脚本自动执行：

入口状态验证（phase=archive, verify_result=pass, archived=false）
Delta spec 同步到主 spec
Design doc 前置元数据标注（archived-with, status）
Plan 前置元数据标注（archived-with）
移动 change 到归档目录

通过

comet-state transition <archive-name> archived

更新

archived: true

如脚本返回非零退出码，报告错误并停止。如脚本返回零退出码，归档完成。脚本摘要中的

X/Y steps succeeded

以真实执行步骤计数，不会因 delta spec 同步或文档标注重复累计。

当待同步的 delta spec 与已有主 spec 不一致时，脚本会在覆盖前打印 unified diff 预览，帮助确认归档同步内容。

如需预览而不实际执行，使用

--dry-run

参数。

Run the archive script to automatically complete all the following steps:

bash

bash "$COMET_ARCHIVE" "<change-name>"

The script automatically executes:

Entry status check (phase=archive, verify_result=pass, archived=false)
Sync delta spec to main spec
Prepend metadata to Design doc (archived-with, status)
Prepend metadata to Plan (archived-with)
Move the change to the archive directory

Update

archived: true

via

comet-state transition <archive-name> archived

If the script returns a non-zero exit code, report the error and stop. If the script returns a zero exit code, archiving is completed. The

X/Y steps succeeded

in the script summary counts the actual executed steps and will not accumulate repeatedly due to delta spec sync or document annotation.

When the delta spec to be synchronized is inconsistent with the existing main spec, the script will print a unified diff preview before overwriting to help confirm the archive synchronization content.

Use the

--dry-run

parameter to preview without actual execution.

2. 生命周期闭环

2. Lifecycle Closure

Spec 生命周期在此完成：

brainstorming → delta spec → 实施 → 验证 → 主 spec 覆盖 → design doc 标注 → 归档

The Spec lifecycle is completed here:

brainstorming → delta spec → implementation → verification → main spec overwrite → design doc annotation → archiving

退出条件

Exit Criteria

归档脚本执行成功（退出码 0）

归档目录

openspec/changes/archive/YYYY-MM-DD-<change-name>/

存在

归档后的
```
.comet.yaml
```
中
```
archived: true
```

归档脚本会把

openspec/changes/<name>/

移动到

openspec/changes/archive/YYYY-MM-DD-<name>/

。归档成功后不要再对原 change 名运行

bash "$COMET_GUARD" <change-name> archive

，因为原活跃目录已经不存在。归档完整性以脚本退出码和归档目录状态为准。

Archive script executes successfully (exit code 0)

Archive directory

openspec/changes/archive/YYYY-MM-DD-<change-name>/

exists

```
archived: true
```
is set in the archived
```
.comet.yaml
```

The archive script will move

openspec/changes/<name>/

openspec/changes/archive/YYYY-MM-DD-<name>/

. After successful archiving, do not run

bash "$COMET_GUARD" <change-name> archive

for the original change name anymore, as the original active directory no longer exists. Archive integrity is determined by the script exit code and archive directory status.

完成

Completion

Comet 流程全部完成。如需开始新工作，调用

/comet

或

/comet-open

。

The entire Comet process is completed. To start new work, invoke

/comet

/comet-open