fix: allow refreshing a completed design handoff after spec changes (#326)

* fix: allow refreshing a completed design handoff after spec changes

The design guard requires regenerating the handoff when OpenSpec
artifacts change, and 'comet handoff <change> design --write' is the
only legal invocation mode. The stale-handoff check rejected every
such refresh, permanently blocking the Classic workflow at Design.

Explicit --write now refreshes the completed handoff instead of
failing; non-write invocations keep the original guard behavior.

Fixes #324

* chore: bump version to 0.4.0-beta.21 for Classic handoff refresh fix

* test: assert refreshed handoff remains traceable by the design guard

Extend the handoff-refresh test to verify the regenerated markdown
lists the current SHA256 of every source file, satisfying the design
guard's designHandoffMarkdownTraceable check.

* fix: refresh design handoff from build and rewrite aligned stale context

Issue #324 follow-ups from the issue thread:

- A --write invocation no longer reports success while leaving stale
  context files behind when the recorded handoff_hash was aligned to
  the new source hash by hand. The short-circuit now also verifies the
  on-disk markdown lists the current SHA256 of every source file.
- A design handoff can now be regenerated after the guard advanced the
  phase to build, so a later Spec Patch no longer requires a repair-only
  phase escape hatch. The write path only updates handoff context/hash
  and never transitions the run state outside full.design.handoff.

* chore: align version to 0.4.0-beta.19 and consolidate changelog

Per maintainer feedback: beta.19 is the intended next release version;
the beta.20 entry was a merge error from a previous fix. Consolidate all
entries newer than beta.18 into a single beta.19 changelog entry.

* fix: regenerate design handoff context when delta specs are removed

* ci: retrigger checks after Dashboard E2E timeout

* docs: document handoff refresh in Classic design/build skills

* refactor: drop unreachable stale-handoff branch and unused test env option

* docs: align handoff refresh wording with design guard checks

---------

Co-authored-by: benym <benyuanming@gmail.com>

Author: baobaolaodie

CHANGELOG.md

@@ -18,6 +18,7 @@ All notable changes to @rpamis/comet will be documented in this file.
 ### Fixed
 
 - **Windows Eval skill copies**: `comet eval` no longer copies the framework's own `.comet` runtime state into test sandboxes and artifact snapshots, preventing nested-cache `MAX_PATH` failures on Windows.
+- **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
+```
+
+重新生成会从当前 OpenSpec artifacts 重建 handoff 并更新 `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；否则记录的 `handoff_hash` 与当前 OpenSpec artifacts 不再匹配，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 rebuilds the handoff from the current OpenSpec artifacts and updates `handoff_hash`; it does not change the `phase` field or the Runtime `currentStep`, 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 recorded `handoff_hash` no longer matches the current OpenSpec artifacts and the design guard blocks progress. 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