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 阶段的工作说明，用户能直接阅读和修改需求。
简单任务只需填写四个核心章节：Outcome、Scope、Non-goals 和 Acceptance examples。有实际内容时，再补充约束、关键决定、未决问题或特殊检查要求；不需要为满足模板逐节填写“无”。
Scope 下的 ## 目录结构 说明预计改动的模块和关键文件，分为 ### 新建、### 修改、### 删除 和 ### 明确不建 四个子节。每个路径用一句话说明职责或改动点；有目录归属关系时用树形，独立文件用列表，没有内容的子节写“无”。单文件任务只需列出实际路径，无需展开目录树。
目录结构随完整 Shape 一起确认。在已确认模块内新增常规辅助文件无需重新确认；扩大范围或改变职责分配时，先更新目录结构和相关决定，再确认方案。0.4.5 之前已确认的 change 保留原有规则和进度，重新确认 Shape 时才采用这项要求。
手工编辑 brief 或 Spec 时，注意验收项的来源：Runtime 只从两处生成验收项——brief 顶层的验收示例，以及 Spec 中以 Scenario: 标题开头的完整场景。描述性段落、普通列表和单独的 WHEN/THEN 行不会被识别为验收项。因此，要调整验收范围，只能修改这两种格式的内容。
Spec 场景与 brief 已有验收项描述同一行为时，在场景正文单独写 Acceptance: A1，或 验收：A1，引用当前 brief 的真实验收 ID。一个场景只引用一个 ID，不再生成重复验收项；新增行为仍需要独立场景。引用不会省略完整 Spec，Verifier 仍会核对其中的行为与约束。
按新版规则确认的 Shape 允许修正 brief 和 Spec 的纯 Markdown 排版，不会因此丢失实现进度。目标、范围、验收文字或子任务变化仍需返回 Shape；旧 change 保留原有确认规则。写错章节结构时，Runtime 会指出需要修正的文档。
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 流程的输入。
继续阅读：验证与修复、连续推进、恢复手册 和 归档与交付。