comet-state.yaml 和 verification.md；
项目布局
默认布局如下：<project>/
.comet/
config.yaml
current-change.json
runtime/native/
changes/<change-name>/
state.json
logs/
locks/
transactions/
docs/comet/
specs/
changes/
<change-name>/
brief.md
comet-state.yaml
specs/<capability>/
spec.md
verification.md
archive/
YYYY-MM-DD-<change-name>/
native.artifact_root 可以改成项目内其他相对目录，例如 artifacts/comet/。.comet/config.yaml 和 .comet/current-change.json 跟随项目绑定；.comet/runtime/native/ 由 Runtime 管理并默认加入.gitignore忽略，不会复制到 change 目录或提交为用户文档。
三类用户可读文件
brief.md
brief 说明目标、范围、非目标、已确认的用户决定、未解决问题、验收示例和验证期望。它是 Shape 阶段的工作说明，用户能直接阅读和修改需求。
手工编辑 brief 或 Spec 时，注意验收项的来源：Runtime 只从两处生成验收项——brief 顶层的验收示例，以及 Spec 中以 Scenario: 标题开头的完整场景。描述性段落、普通列表和单独的 WHEN/THEN 行不会被识别为验收项。因此，要调整验收范围，只能修改这两种格式的内容。
specs/<capability>/spec.md
capability 是项目的一项独立功能，例如“头像上传”或“会话超时”。Spec 按功能组织，每个 capability 一个目录，目录下的 spec.md 描述这项功能归档后的完整行为。归档时 Runtime 会按声明执行 create、modify 或 remove：创建、完整替换，或在受控路径内删除。要声明移除一个 capability，运行 comet native spec remove 表达删除意图——只删除 Spec 文件不会被当作移除声明，归档时该 Spec 仍按存在处理。当并行 change 尝试修改同一 capability，会先停下来要求确定归档顺序，不会自动覆盖文件。
comet-state.yaml
这是跨设备恢复的稳定状态。它记录以下内容：
- 当前阶段和状态；
- Loop 进度：
iteration是实现轮次，Builder 每提交一次新的候选实现加一；attempt是对同一份候选实现的验收尝试次数； - 完整验收项及结果；
- Builder handoff：Builder 提交候选实现时写下的交接说明，描述本次改动和声明受影响的验收项；
- 必要检查摘要、Verifier 结论和阻塞原因；
- 最近 50 条执行记录和下一步动作。
verification.md
这是 Runtime 根据状态生成的用户报告，包含实际检查、逐项验收、风险、限制和结论。它是可重建的展示文件，不是推进阶段的输入；缺失或落后时，Runtime 可以从 comet-state.yaml 重建。
本机 Runtime
.comet/runtime/native/ 只保存四类本机文件：执行状态文件（overlay）、日志、操作锁和可恢复事务。操作锁只在单个操作执行期间持有，用来防止两个并发操作同时修改同一个 change，操作结束就释放。这个目录可能因换设备或清理而缺失；Runtime 会依据同步的 YAML 重建，而不会把本机执行状态当成跨设备事实。日志适合排查命令输出，不能替代 verification.md。这些文件由哪些组件写入，见 Native Runtime 的组成。
.comet/current-change.json 只表示下一次写入归属哪个 workflow/change，不限制项目只能有一个 active change。状态查看是只读的；需要明确归属时使用 comet native select <change-name>。
跨设备恢复
你不需要手工执行恢复命令。在目标设备拉取或同步项目代码后，像平时一样告诉 Agent 继续当前需求即可。Comet 会先尝试通过自动恢复探测找到 active change，再由 Agent 根据 Runtime 返回的工作区和下一步动作，自动完成状态读取、change 选择和流程推进。 需要同步的是项目代码、.comet/config.yaml、brief.md、Specs 和 comet-state.yaml。如果已经生成 verification.md，可以一并同步；即使缺失，Runtime 也能根据 comet-state.yaml 重建，不会阻止 Shape 或 Build 恢复。.comet/runtime/native/ 属于本机执行状态，不需要跨设备复制。
目标设备缺少 Runtime，或本机执行状态已经过期时，Runtime 会按 comet-state.yaml 里记录的进度自动重建。执行到一半的检查会按中断处理；需要重新运行的检查会再次执行，不能安全复用的 Verifier 或 archive-ready 结果会重新验证。恢复不会依赖旧设备的 state.json，也不会因为复制了旧 Runtime 文件就直接归档。
只有代码未同步、当前分支或 worktree 与 change 不匹配、存在多个同样匹配的工作区，或 active/archive 目录冲突时，Comet 才会停下来请你选择或修正。
下面两个命令只在你想查看进度或排查问题时使用，也可以打开 Comet Dashboard 查看进度：
归档与交付
归档时的交付选择（保留工作区 / 本地合并 / 推送 / 建 PR / 暂缓）见归档与交付。归档后
成功归档的 change 只保留 brief、Specs、comet-state.yaml 和 verification.md 等用户可读内容。.comet/runtime/native/ 中该 change 的本机执行目录会清理；旧版本遗留的机器文件只通过迁移或只读适配器处理，不会成为新 Native 流程的输入。
继续阅读：验证与修复、连续推进、恢复手册 和 归档与交付。