# .comet.yaml 字段说明

规范路径：`comet-classic/reference/comet-yaml-fields.md`

本文件是 `<classic-change-dir>/` 下每个 change 级 `.comet.yaml` 状态文件的字段参考。`<classic-change-dir>` 来自 `comet-classic/reference/classic-layout.md` 的 resolver 绑定。按需查阅，不随 skill 一次性加载。项目级默认配置放在 `.comet/config.yaml`，全局默认配置放在 `~/.comet/config.yaml`；项目配置优先于全局配置。

## 示例

```yaml
workflow: full
language: zh-CN
phase: build
design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
base_ref: a1b2c3d4e5f6...
build_mode: subagent-driven-development
build_pause: null
subagent_dispatch: confirmed
tdd_mode: tdd
review_mode: standard
auto_transition: true
isolation: branch
bound_branch: null
verify_mode: light
verify_result: pending
verify_failures: 0
verification_report: null
branch_status: pending
created_at: 2026-05-26
verified_at: null
archive_confirmation: null
archived: false
```

## 必需字段

| 字段 | 含义 |
|------|------|
| `workflow` | `full`、`hotfix` 或 `tweak` |
| `language` | 产物语言，仅支持 `en` 或 `zh-CN`。由 `comet init` 按安装范围写入项目或全局 `.comet/config.yaml` 的 `classic.language`，创建 change 时按“项目优先、全局回退”快照到 `.comet.yaml`，用于约束 OpenSpec / Superpowers 产物主语言 |
| `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive`（init 统一设为 `open`，guard 负责过渡） |
| `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
| `plan` | 关联的 Superpowers Plan 路径，可为空 |
| `base_ref` | init 时记录的 git commit SHA，用于 scale 评估。无 plan 时作为改动文件数统计基准 |
| `build_mode` | 已选择的执行方式，可为空。取值：`subagent-driven-development`（隔离后台 subagent 逐任务实现并审查）、`executing-plans`（主会话按计划顺序执行）、`direct`（主会话直接编码，默认仅 hotfix/tweak 允许，full workflow 需 `direct_override: true`） |
| `build_pause` | build 阶段内部暂停点。`null` 表示无暂停，`plan-ready` 表示 plan 已生成，用户选择切换模型后暂停 |
| `subagent_dispatch` | `null` 或 `confirmed`。`confirmed` 记录用户已选择 `subagent-driven-development`；该模式只有带此记录时才能离开 build 阶段 |
| `tdd_mode` | `tdd` 或 `direct`。full workflow 离开 build 阶段前必须已选择。`tdd` 强制每个任务先写失败测试再实现；`direct` 不强制逐任务 TDD，但仍需相关测试与 bug 回归证据。hotfix/tweak 默认 `direct` |
| `review_mode` | `off`、`standard` 或 `thorough`。full workflow 离开 build 阶段前必须已选择；hotfix/tweak 默认 `off` |
| `isolation` | `current`、`branch` 或 `worktree`。full change 在 Open 阶段创建产物前决定工作区；hotfix/tweak 在入口决策点后也可如实使用三种模式，不得在未创建分支时虚构为 `branch` |
| `bound_branch` | 工作区分支绑定记录，可为空。`isolation: current` / `branch` / `worktree` 首次设置或入口检查时记录命令执行目录所在的当前 Git 分支（worktree 模式请在对应工作区内执行 set/check/guard，否则会绑定/比对错误的分支）；在不同工作区模式之间切换 `isolation` 会重新绑定到当前分支，重复设置同一模式保持原绑定。后续 `comet state select` / `comet state check` 必须确认绑定分支与当前分支一致；漂移时 `select` 直接拒绝、检查进入 `BLOCKED`，按决策点协议让用户选择切回绑定分支或明确确认后运行 `comet state rebind <change-name>`。清空 `isolation` 时会清空该字段 |
| `verify_mode` | `light` 或 `full`，可为空 |
| `auto_transition` | `true` 或 `false`。只控制阶段守卫推进 phase 后是否自动调用下一个 skill；`false` 时由 `comet-state next` 输出 `manual`，暂停下一 skill 调用，但不阻止 phase 字段更新 |
| `verify_result` | `pending`、`pass` 或 `fail` |
| `verify_failures` | 机器维护的连续验证失败次数；`verify-fail` 自动加一，`verify-pass` 或 `archive-reopen` 重置为 `0`。达到 `3` 后下一次失败必须进入超限策略决策 |
| `verification_report` | 验证报告文件路径，verify 通过前必须指向已存在文件 |
| `branch_status` | `pending` 或 `handled`。verify 阶段保持 `pending`；用户在归档前确认立即远端交付后，归档完成时设为 `handled` 并包含在唯一归档提交中。`handled` 只表示交付方式已经确认，不表示 push 或 PR 创建已经成功；只有远端操作成功后才能清除 current selection 并宣告 workflow 完成 |
| `created_at` | change 创建日期（init 时自动写入），格式 `YYYY-MM-DD` |
| `verified_at` | 验证通过时间，可为空 |
| `archive_confirmation` | `null`、`pending` 或 `confirmed`。`verify-pass` 进入 archive 阶段时写入 `pending`；用户在 `/comet-archive` 最终确认选择任一“确认归档并立即远端交付”选项后，`archive-confirm` transition 写入 `confirmed`；`archive-reopen` 会清空该字段，防止复用旧确认 |
| `archived` | change 是否已归档 |

## 可选字段

| 字段 | 含义 |
|------|------|
| `direct_override` | `true`/`false`。full workflow 如需使用 `build_mode: direct`，必须显式设为 `true` |

## 状态机硬约束

- `build → verify` 前，`isolation` 必须是 `current`、`branch` 或 `worktree`
- `build → verify` 前，`build_mode` 必须已选择
- `build_mode: subagent-driven-development` 必须同时有 `subagent_dispatch: confirmed`
- full workflow 离开 build 阶段前 `tdd_mode` 必须已选择为 `tdd` 或 `direct`
- full workflow 离开 build 阶段前 `review_mode` 必须已选择为 `off`、`standard` 或 `thorough`
- `build_mode: direct` 默认只允许 `hotfix` / `tweak`；full workflow 需要 `direct_override: true`
- `build_pause` 不是执行方式，不得写入 `build_mode`
- 这些约束同时存在于 `comet-guard.mjs build --apply` 和 `comet-state.mjs transition <name> build-complete`
- `archive_confirmation` 是 machine-owned 字段，只能由 `verify-pass`、`archive-confirm` 和 `archive-reopen` transition 更新，不能通过 `set` 直接伪造确认；`archived` transition 和真实归档命令都要求其值为 `confirmed`
- `preset-escalate` 事件：仅允许 `hotfix`/`tweak` workflow 在 `phase: build` 时调用，原子地把 `workflow`/`classic_profile` 置为 `full`、`phase` 回退到 `design`、清空 `design_doc`（满足 comet-design 入口要求）。这是预设升级到 full 的唯一合法通道——直接 `set phase design` 会被状态机硬拦截，`set classic_profile` 属于 machine-owned 字段不可手动设置