先理解:phase 不能手动改
.comet.yaml 的 phase 由 Comet 自动维护(machine-owned)。你不能直接 set phase build 回退,状态机会拒绝。回退只能通过合法的 transition 事件,每个事件都有守卫检查。
紧急修复状态时可以使用 COMET_FORCE_PHASE=1,命令会输出 WARNING:
可用的 transition 事件

phase 不能手动改;回退必须走状态机允许的 transition 事件
场景一:build 阶段中途修改 spec
delta spec 在 build 阶段可以修改。根据修改范围采用以下处理方式:小和中档修改不回退 phase——它们在 build 阶段原地处理。只有大档(开新
change)才会另起一个完整的 open→design→build 流程。full workflow 没有
build→design 的直接回退,设计问题在 build 阶段通过 brainstorming 原地更新 Design Doc 解决。
50% 阈值
新增任务超过初始 tasks.md 的 50% 时,视为超出原始计划范围,必须暂停让你选择:拆分新 change 或继续在当前 change。delta spec 什么时候同步到 main spec
delta spec 只在 archive 阶段合并到 main spec。build 阶段不修改 main spec。场景二:写了代码不满意,想回 build 重来
如果已经在 verify 阶段但想改代码:verify-fail 回退
验证未通过或需要返回 build 修复时:
正常流程不会在 verify 处理分支,因此这里保留的应是
branch_status: pending。不要在重新验证时手工写 handled;交付方式统一由 Archive 在最终确认后记录。
场景三:验证通过但归档前想重新检查
verify 通过后进入 archive,但你在归档前确认时发现还想改:
然后进入
/comet-verify 重新验证。发现问题时,再用 verify-fail 返回 build。
场景四:将 hotfix 或 tweak 升级为 full
hotfix 或 tweak 执行过程中命中升级信号,并确认升级到 full 时:workflow 和 classic_profile 设为 full,将 phase 回退到 design,并清空 design_doc。随后加载 comet-design 创建 Design Doc。
场景五:design 阶段修改了 delta spec
design 阶段 brainstorming 时可能需要写 Spec Patch(补充验收场景、修正描述、加边界用例)。写完后必须重新生成 handoff 更新 hash:场景六:恢复时发现工作区有未提交改动
恢复/comet 时,如果工作区存在未提交改动,先按未提交改动的归因规则处理:
场景七:build_pause 卡住了
build_pause: plan-ready 是计划生成后的暂停点。恢复规则如下:
回退路径速查
回退关系图
红色(verify/archive)是有回退出口的阶段。绿色(build)是可以原地改 spec 的阶段。常见问题
我能直接编辑 .comet.yaml 改 phase 吗
我能直接编辑 .comet.yaml 改 phase 吗
不能。phase 是 machine-owned,直接改会被拒绝。用
transition 事件回退,或用
COMET_FORCE_PHASE=1(仅修复,会 WARNING)。full workflow 能从 build 回到 design 吗
full workflow 能从 build 回到 design 吗
不能直接回。full workflow 的设计问题在 build 阶段通过 brainstorming 原地更新 Design Doc
解决,不回退 phase。只有 hotfix/tweak 能用
preset-escalate 回 design。verify-fail 后 branch_status 是什么
verify-fail 后 branch_status 是什么
正常流程中它仍是 pending。Verify 不处理分支,也不写 handled;只有 Archive
在用户确认立即远端交付后才写 handled,并把它包含在唯一归档提交中。
build 阶段改了 delta spec,要同步 main spec 吗
build 阶段改了 delta spec,要同步 main spec 吗
不要。delta→main spec 合并统一在 archive 阶段完成。build 阶段只编辑 delta spec。

