先理解:phase 不能手动改
.comet.yaml 的 phase 是 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
永远不在 build 阶段同步。 所有 delta→main spec 合并统一在 archive 阶段完成。build 阶段只编辑 delta spec,不碰 main spec。场景二:写了代码不满意,想回 build 重来
如果已经在 verify 阶段但想改代码:verify-fail 回退
验证不通过或你想主动回 build 修复:
正常流程不会在 verify 处理分支，因此这里保留的应是
branch_status: pending。不要在重新验证时手工写 handled；交付方式统一由 Archive 在最终确认后记录。
场景三:验证通过但归档前想重新检查
verify 通过后进入 archive,但你在归档前确认时发现还想改:
然后进入
/comet-verify 重新验证。如果发现问题,再 verify-fail 回 build。
场景四:hotfix/tweak 做到一半发现要深度设计
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 恢复时,如果工作区有未提交改动,按 dirty-worktree 协议处理:
场景七: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。