fix: allow refreshing a completed design handoff after spec changes

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to @rpamis/comet will be documented in this file.
 
-## What's Changed [0.4.0-beta.19] - 2026-08-15
+## What's Changed [0.4.0-beta.19] - 2026-08-20
 
 ### Added
 
@@ -13,9 +13,11 @@ All notable changes to @rpamis/comet will be documented in this file.
 - **Dashboard artifact previews**: Fullscreen previews now close with Escape, keep long tables horizontally scrollable, preserve readable table headers, and use a larger directory navigation scale.
 - **Hook allow-path documentation**: The website now explains how to configure project-relative `hook.allow_paths` directories for guarded workflow phases.
 - **On-demand change review**: The new `/comet-review` Skill reviews the current Native or Classic change against its implementation diff and existing evidence, reports prioritized correctness, security, edge-case, and coverage findings, and remains read-only without advancing or replacing Verify.
+- **Classic handoff refresh documentation**: `comet-design` now states that the handoff must be regenerated after a delta spec is added, modified, or removed, and `comet-build` documents that the handoff can be refreshed directly from the Build phase (`comet handoff <change> design --write`) without reverting the phase or Runtime step.
 
 ### Fixed
 
+- **Classic design handoff refresh after Spec Patch**: Running `comet handoff <change> design --write` after OpenSpec artifacts changed no longer fails with a stale-handoff error, so the design guard can pass and the Classic full workflow proceeds from Design to Build. Refreshing now rewrites stale context files even when a manually aligned hash would otherwise short-circuit success, regenerates the context pack when OpenSpec delta specs are added, changed, or removed, and remains available after the guard has advanced the phase to build.
 - **Classic Ambient Resume**: `comet init` and `comet update` now keep the managed Ambient Resume instructions for Classic-only projects when `ambient_resume` is enabled, so re-running the commands no longer removes the block from `AGENTS.md` or `CLAUDE.md`.
 - **Fork pull request greetings**: First-time contributors now receive the repository guidance comment when opening a pull request from a fork, without weakening the read-only permissions of workflows that execute contributor code.
 - **Pull request template checks**: Pull requests now receive an actionable comment and a failing check when items from the repository template are missing or its checklist is incomplete.

assets/skills-zh/comet-build/SKILL.md

@@ -240,6 +240,14 @@ Open 阶段已经根据 `isolation` 准备好当前目录、分支或 Worktree
 - 不提前同步到 main spec，归档时统一同步
 - 小规模增量直接改 delta spec 时，应在 commit message 中注明，便于归档时判断 design doc 漂移
 
+**handoff 同步**：delta spec 的增、改、删都会使设计交接包（`handoff_hash`）过期。Build 阶段可随时直接重新生成，无需回退当前 phase 或 step：
+
+```bash
+comet handoff <change-name> design --write
+```
+
+重新生成只更新 handoff 上下文与 hash，不会改变 `phase` 字段或 Runtime `currentStep`；设计守卫与构建守卫都会校验最新交接包，刷新后可按 build 阶段继续推进。
+
 ### 5. 上下文管理
 
 Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后断点恢复：

assets/skills-zh/comet-design/SKILL.md

@@ -207,7 +207,7 @@ canonical_spec: openspec
 
 ### 3. 更新 Comet 状态
 
-先记录 design_doc 路径。如果 Spec Patch 回写了 delta spec（新增或修改了 `specs/*/spec.md`），必须重新生成 handoff 以更新 hash：
+先记录 design_doc 路径。如果 Spec Patch 回写了 delta spec（新增、修改或删除了 `specs/*/spec.md`），必须重新生成 handoff 以更新 hash：
 
 ```bash
 # 记录 design_doc 路径
@@ -220,7 +220,7 @@ comet handoff <change-name> design --write
 comet guard <change-name> design --apply
 ```
 
-如果没有 delta spec 变更，跳过 handoff 重新生成步骤。状态文件自动更新，无需手动编辑其他字段。
+delta spec 的增、改、删都会改变 handoff hash，因此删除 delta spec 同样必须重新生成 handoff；否则旧交接包会残留已删除的 spec，design guard 的可追踪性检查也无法通过。如果没有 delta spec 变更，跳过 handoff 重新生成步骤。状态文件自动更新，无需手动编辑其他字段。
 
 ### 3a. 可选主动式上下文压缩
 

assets/skills/comet-build/SKILL.md

@@ -240,6 +240,14 @@ When creating an independent change, must invoke `/comet-open`, not `/opsx:new`
 - Do not sync to main spec in advance, sync uniformly during archiving
 - For small-scale incremental direct delta spec edits, note in commit message to facilitate design doc drift assessment during archiving
 
+**Handoff synchronization**: adding, modifying, or removing a delta spec expires the design handoff pack (`handoff_hash`). During Build you can regenerate it directly without reverting the current phase or step:
+
+```bash
+comet handoff <change-name> design --write
+```
+
+Regeneration only updates the handoff context and hash; it does not change the `phase` field or the Runtime `currentStep`. The design and build guards validate the latest handoff pack, so you can continue in the Build phase after refreshing.
+
 ### 5. Context Management
 
 Build is the longest phase and may span many tasks. To support resume after context compaction:

assets/skills/comet-design/SKILL.md

@@ -206,7 +206,7 @@ If Spec Patches need to be written back, also edit the corresponding `specs/*/sp
 
 ### 3. Update Comet State
 
-First record the design_doc path. If Spec Patches wrote back delta spec (added or modified `specs/*/spec.md`), must regenerate handoff to update hash:
+First record the design_doc path. If Spec Patches wrote back delta spec (added, modified, or removed `specs/*/spec.md`), must regenerate handoff to update hash:
 
 ```bash
 # Record design_doc path
@@ -219,7 +219,7 @@ comet handoff <change-name> design --write
 comet guard <change-name> design --apply
 ```
 
-If there are no delta spec changes, skip the handoff regeneration step. The state file updates automatically; no manual editing of other fields needed.
+Adding, modifying, or removing a delta spec changes the handoff hash, so deleting a delta spec also requires regenerating the handoff; otherwise the stale handoff pack still embeds the removed spec and the design guard's traceability check cannot pass. If there are no delta spec changes, skip the handoff regeneration step. The state file updates automatically; no manual editing of other fields needed.
 
 ### 3a. Optional Active Context Compaction