> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Native 产物与状态

> 理解 .comet/config.yaml、brief、完整目标规格、comet-state.yaml、证据与归档目录的职责。

Native 把需要跨会话保留的事实写入文件。Agent 恢复时以这些文件和仓库现状为准，而不是依赖聊天记忆。用户通常只需要阅读 brief、规格和验证报告；状态、hash、锁与事务由 Runtime 维护。

## 项目布局

默认布局如下：

```text theme={null}
<project>/
  .comet/
    config.yaml
    current-change.json
  docs/comet/
    specs/
    changes/
      <change-name>/
        brief.md
        comet-state.yaml
        specs/<capability>/spec.md
        verification.md
        runtime/
          baseline-manifest.json
          run-state.json
          trajectory.jsonl
          checkpoints/
          evidence/
            snapshots/
            scopes/
            allowances/
            verifications/
            check-receipts/
    archive/
      YYYY-MM-DD-<change-name>/
    runtime/
```

`native.artifact_root` 可以把 `comet/` 放到项目内的其他相对目录。例如 `artifact_root: docs` 对应 `docs/comet/`。共享配置和当前选择仍位于 `.comet/`。

## `.comet/config.yaml`

这是 Native 与 Classic 共用的项目配置位置。完整 schema、示例和修改方式见 [Native 配置](/zh/native/configuration)；这里列出与 Native 产物直接相关的字段：

| 字段                          | 作用                                 |
| --------------------------- | ---------------------------------- |
| `schema`                    | 配置格式，当前为 `comet.project.v1`        |
| `default_workflow`          | `/comet` 默认进入 `native` 或 `classic` |
| `workflows`                 | 项目启用 Native、Classic 或两者            |
| `ambient_resume`            | 是否允许普通请求触发只读环境感知恢复                 |
| `native.artifact_root`      | Native 的 `comet/` 产物根目录            |
| `native.language`           | 新建 Native change 的默认文档语言           |
| `native.clarification_mode` | 每轮询问一个问题或本轮全部可回答问题                 |

Classic 自有设置可以保留在同一个文件中，但不会改变 Native 状态机。修改 artifact root 应使用 `comet native root move`，让 Runtime 事务化迁移；不要只改 YAML 后手动移动目录。

<p align="center">
  <img src="https://mintcdn.com/comet-bb5f5294/7jNUkQ90KjmwXcBK/assets/native-illustrations/04-artifacts-and-state.png?fit=max&auto=format&n=7jNUkQ90KjmwXcBK&q=85&s=7e07845694593b1274ed8a11e103d958" alt="小鱼把用户可读文档放进文件柜上层，将状态记录和哈希索引收进带锁盒子，表示可恢复的职责分层" width="1672" height="941" data-path="assets/native-illustrations/04-artifacts-and-state.png" />
</p>

## 用户可读产物

### `brief.md`

Brief 定义这次 change 的目标和边界，包括 Outcome、Scope、Non-goals、Acceptance examples、约束、已确认决定、未解决问题和验证期望。`[blocking]` 表示仍存在必须由用户决定的行为。

### 完整目标规格

`changes/<change>/specs/<capability>/spec.md` 描述归档后该 capability 的完整行为。它不是只能与旧文档合并阅读的 delta patch。

Runtime 根据 canonical spec 是否存在推导操作：

* `create`：归档时创建新的 canonical spec；
* `replace`：用完整目标规格替换旧版本，但要求旧版本 hash 未变化；
* `remove`：通过 CLI 明确删除 capability。

并发变更导致基线变化时，使用 `spec rebase` 重新绑定最新 canonical spec；旧验证会失效。

### `verification.md`

验证报告记录实际命令、结果、跳过理由、已知限制、总体结论和逐项 Acceptance evidence。Runtime 会保存不可变报告快照，并把它与当时的 contract、scope 和 revision 绑定。

## Runtime 管理的状态

### `comet-state.yaml`

每个 active 或 archived Native change 都有独立的 `comet-state.yaml`。它记录 phase、revision、approval、`approved_contract_hash`、verification 与规格操作等机器状态。进入 Build 时，`approved_contract_hash` 把 approval 绑定到当时的 brief/spec contract；后续 contract 漂移必须取得用户重新确认。不要手改这些字段，也不要把它与 Classic change 的 `.comet.yaml` 混为一谈。

### Run、trajectory 与 checkpoint

* Run state 保存当前 continuation 与修复状态；
* trajectory 保存有界的阶段摘要、时间点和证据引用，不保存隐藏推理；
* checkpoint 保存当前阶段内的摘要、下一动作和内容寻址 artifact manifest，供新会话恢复。

Checkpoint 不替代 brief、规格或验证报告，也不推进 phase。

### Selection

`.comet/current-change.json` 记录当前写入属于哪个 workflow/change。它让共享 Hook Router 在一个项目启用多套工作流或多个 change 时仍能把写入交给唯一 Guard。只读 `status` 不会靠副作用改变 selection；选择 change 使用 `comet native select <change-name>`。

## 有界读取与内容寻址

Native 对 change 数量、规格大小、finding、Acceptance ID、输出和归档树设置预算。列表与详情使用绑定当前内容集合的 cursor；输入变化后旧 cursor 会明确失效。

`baseline-manifest.json` 是创建 change 时捕获的有界项目快照。Git provider 只纳入 tracked 与未被 ignore 的 untracked 文件并原子表示 submodule/gitlink；非 Git 项目使用带前后枚举围栏的有界物理树 provider。创建或 v1/v2 migration cutover 时 baseline 必须完整；当前 v3 baseline 不能用当前文件自动重建。

实现范围、规格基线、当前 snapshot、验证报告、check receipt、checkpoint manifest 与归档预检都使用 hash 绑定。当前 snapshot 不完整时不会推断删除；变化明细超预算时，`scope-detail-overflow` 用计数与内容 hash 保留其余变化的结构化事实。这样可以判断证据是否仍对应当前事实，而不是只相信“已经验证过”的文字声明。

Git 枚举还会显式报告 `git-selection-changed` 与 `git-enumeration-limit`。前者必须等 index 稳定后重试，绝不可授权；后者应优先通过缩小或清理项目所有范围、或后续产品预算调整来恢复。baseline 创建与 migration cutover 必须完整，没有 partial 授权；仅在之后的 current snapshot 中恢复不可行、Runtime 返回带计数与内容 hash 的可授权 scope，且用户理解未知尾部风险时，`git-enumeration-limit` 才可使用精确 hash、理由与 `--confirmed` 走普通 partial 协议。两者都不能通过手改 evidence 绕过。

物理树枚举会显式报告 `physical-selection-changed` 与 `physical-enumeration-limit`。前者要求等待并发文件操作结束，后者要求缩小项目树或移出非项目内容；两者都无法稳定绑定未知尾部，在 current snapshot 中也不能通过 partial scope 授权。

下一步阅读 [安全与恢复](/zh/native/safety-and-recovery)，或在 [Native CLI](/zh/cli/native) 查看对应命令。