一次写入只属于一个 change
项目初始化会在每个平台安装一份 Comet 工作流 Rule;支持 Hook 的平台只安装一个comet-hook-router.mjs。Router 读取 .comet/config.yaml 与 .comet/current-change.json,把一次原子多文件写入最多路由到一个 workflow Guard。
Native 与 Classic 的 Guard 保持独立:
- Native 只按 Shape、Build、Verify、Archive 和 Native 路径检查;
- Classic 只按自己的五阶段与 OpenSpec/Superpowers 路径检查;
- selection 无效、陈旧或歧义时,可能写入会失败关闭;
- 明确认定的只读工具不会触发写入 Guard。
验证证据为什么会失效
Runtime 把验证结论绑定到:- brief 与完整目标规格;
- implementation scope 中的项目产物;
- Acceptance ID 与验证报告快照;
- 当前 change revision;
- 可选的内置 check receipt。
next:先运行它退回 Build、生成新 scope 并验证。只有 brief/spec contract hash 也变化时才重新取得用户确认;仅项目 snapshot 或 implementation 变化时保留原 approval。Archive 中报告、receipt 或其他绑定事实漂移时也使用同一回退协议;不能删除 finding、手改 evidence ref 或复用旧 pass。
Native Runtime 仅在 Git 项目中调用 Git 生成有界的 Git-aware snapshot。comet native check 是独立的内置、有界、只读文本卫生检查,不调用 Git、shell、测试命令、外部 Skill 或任何外部进程,也不替代项目测试。
Baseline 与 schema migration
新 change 必须在创建状态前取得完整 baseline。Git snapshot 只纳入 tracked 与未被 ignore 的 untracked 文件,submodule/gitlink 作为原子条目;ignored cache 和未登记嵌套仓库的内容不会制造 omission。当前 snapshot 不完整时不会把缺失路径推断成删除。 对已经使用 v3 schema 的 change,baseline 缺失或不完整不是 doctor 可自动修复的问题。用当前文件重建会抹掉从创建以来的历史差异;只能从可信备份恢复原 baseline,或保留 brief/spec 和实现事实后新建 change。 v1/v2 schema migration 是唯一 cutover 例外。doctor --repair 会在任何状态写入前捕获完整的迁移时点 baseline;捕获不完整时旧状态保持不变。迁移后的证据只证明 cutover 之后的变化,不能继承迁移前的 scope 或 pass。旧 Verify/Archive 会受控退回 Build 重新建立 v3 证据。
自主修复不会无限循环
Verify 失败会回到 Build。Runtime 根据失败分类、检查 ID、contract 与 implementation scope 形成失败签名:- 相同 scope 下第三次出现相同签名时转为 manual stop;
- 真实 implementation scope 变化会开启新的 repair episode;
- 无进展 override 只允许一次,并与当前签名绑定;
- 单个 episode 最多记录 12 次 failure。
并发规格冲突
多个 Native change 可以并行存在,但对同一 canonical spec 的安全承诺有明确边界。Archive 会比较 Runtime 在 Shape 时冻结的base_hash 与当前 canonical hash;不一致时停止,不做最后写入覆盖。
处理步骤是:
- 阅读最新 canonical spec;
- 重写当前 change 的完整目标规格;
- 运行
comet native spec rebase <change> --summary <text>; - 重新完成 Build 与 Verify;
- 再次执行两步 Archive。
conflict radar 只报告当前 Native root 内可证明的 capability 重叠与范围信号,不声称理解任意外部分支或未纳入状态的并行工作。
事务与锁恢复
阶段推进、checkpoint、Archive 与 root move 都有明确的 journal 或恢复协议。普通写命令不会擅自接管陈旧锁;只有doctor --repair 能在证明本机 owner 已不存在、锁身份未变化且没有冲突事务时接管。
- 普通阶段 transition 只允许继续;
- Archive 与 root move 只有在 journal 所处阶段仍可逆时才能 rollback;
- Archive 最终 marker 写入后只允许 exactly-once continue;
- Doctor 不会重写用户的 brief、规格、验证报告或项目源码。
环境感知恢复
comet resume-probe 是只读探针。它先解析 .comet/config.yaml 的默认工作流,再只检查该侧状态:
配置或工作流状态损坏时,探针停止并给出原因,不扫描另一套目录猜测回退。
ambient_resume: false 可以关闭普通请求触发的自动探针;显式调用 /comet 不受影响。

