Back to Details

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>"
脚本自动执行：
  1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
  2. Delta spec 同步到主 spec
  3. Design doc 前置元数据标注（archived-with, status）
  4. Plan 前置元数据标注（archived-with）
  5. 移动 change 到归档目录
  6. 通过 
    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:
  1. Entry status check (phase=archive, verify_result=pass, archived=false)
  2. Sync delta spec to main spec
  3. Prepend metadata to Design doc (archived-with, status)
  4. Prepend metadata to Plan (archived-with)
  5. Move the change to the archive directory
  6. 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>/
to 
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
or 
/comet-open
.