> ## 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 CLI

> 初始化 Native、管理 change、保存阶段内进度、推进状态、验证证据以及安全恢复和归档。

`comet native` 是 Native 工作流的确定性 Runtime 入口。它的状态与工作流产物只归属共享项目配置 `.comet/config.yaml` 和配置指定的 `<artifact-root>/comet/`，不会读取或转换 Classic/OpenSpec change。为生成 baseline 与 implementation scope，Runtime 会有界读取项目所有范围内的文件内容；项目存在 Git metadata 时，仅在构建 Git-aware snapshot 时调用 Git。它不会调用外部 Skill、shell 或项目命令；内置 `comet native check` 仍不调用 Git 或任何外部进程。

## 初始化与根目录

```bash theme={null}
comet native init [--root <artifact-root>] [--language en|zh-CN]
comet native root show
comet native root move <artifact-root>
```

示例：

```bash theme={null}
# 默认：<project>/docs/comet/
comet native init --language zh-CN

# 可选：<project>/comet/
comet native init --root . --language zh-CN

# 事务化迁移到 <project>/artifacts/comet/
comet native root move artifacts
```

`artifact-root` 必须是项目内相对路径，默认为 `docs`。`.` 表示 `<project>/comet/`，`docs` 表示 `<project>/docs/comet/`。

`init --language` 会把以后新建 Native change 的默认语言写入 `.comet/config.yaml`。`new --language` 可以覆盖单个 change；再次运行 `init --language` 只改变以后新建 change 的默认值，不改写已有 change。

已有配置会拒绝冲突的 `init --root`。改变目录必须使用 `root move`，不能直接编辑配置。迁移具有 `copying`、`ready`、`switched` 状态；存在 `pending_root_move` 时，普通写命令会失败关闭，避免两棵目录同时可写。

## Change 管理

```bash theme={null}
comet native new <change-name> [--language en|zh-CN]
comet native spec remove <change-name> <capability>
comet native spec rebase <change-name> --summary <text>
comet native list [--cursor <token>]
comet native show <change-name>
comet native status [--cursor <token>]
comet native status <change-name> [--details [--acceptance-cursor <token>]]
comet native select <change-name>
```

`change-name` 和 capability 使用字母开头的 lowercase kebab-case。`new` 在配置缺失时创建默认配置和 `<project>/docs/comet/`。

新增或替换长期行为时，把完整目标规格写入：

```text theme={null}
changes/<change-name>/specs/<capability>/spec.md
```

Runtime 根据 canonical spec 是否存在推导 `create` 或 `replace`，并冻结 `base_hash`。删除 capability 使用 `spec remove`，不要手工维护 `comet-state.yaml` 的 `spec_changes`。若并行 change 已改变同一 canonical spec，先重读并改写完整目标规格，再使用 `spec rebase` 刷新基线、重开 Build 并清除旧验证结论。

### Baseline 与 Git-aware snapshot

`new` 在提交 change 状态前捕获完整 baseline。Git 项目只纳入 tracked 和未被 ignore 的 untracked 文件；ignored cache 与未登记的嵌套仓库内容不属于项目所有范围，submodule/gitlink 作为一个原子条目。非 Git 项目使用有界物理树 provider。任何项目所有项被省略都会返回结构化 `baseline-incomplete`，并清理未完成的 change，而不是把问题拖到 Build。

Git selection 需要一次稳定且有界的枚举：

* `git-selection-changed` 表示枚举期间 Git index 变化。等待 `git add` 等 Git 写入结束后重新运行命令；不能用 partial-scope 授权越过。
* `git-enumeration-limit` 表示 tracked 与未忽略 untracked 的项目所有范围超过 Git 枚举安全预算。这是结构化不完整；应优先缩小或清理项目所有范围，或使用后续调整该产品预算的 Comet 版本，不能直接或默认越过。若确实无法恢复，只有 Runtime 返回带计数和内容 hash 的可授权 scope、且用户理解未知尾部风险时，才可按普通 partial 协议提交精确 hash、理由与 `--confirmed`。不能手改 snapshot/evidence 或猜测未枚举路径。

非 Git 项目的 physical selection 使用有界、顺序无关的前后枚举围栏：

* `physical-selection-changed` 表示项目树在捕获期间发生变化。等待并发文件操作结束后重试。
* `physical-enumeration-limit` 表示节点、路径、字节或协作式执行预算耗尽。缩小项目树或把非项目内容移出项目所有范围后重试。

这两种 physical 完整性失败都无法为未知尾部建立稳定 scope，因此在 current snapshot 中也不能通过 partial-scope 授权。

普通 omission 会带 reason、计数和有界样本路径。baseline 创建与 migration cutover 必须完整，两种 Git selection omission 都不能在这里授权。之后的 current snapshot 只有在 Runtime 明确返回可授权 partial scope 时才可按精确 hash 进入确认：`git-selection-changed` 仍必须先消除，`git-enumeration-limit` 仅能使用上一段所述的最终兜底。

### 有界状态视图

`list` 与不带 change 的 `status` 返回同一种只读分页投影：

* 每页最多 24 个 active change；
* 最多接受 4096 个可见 change；
* `nextCursor` 非空时原样传入下一次 `--cursor`；
* cursor 绑定完整 change 名称集合，增删 change 后旧 cursor 会明确失效。

`status <change-name>` 返回阶段、证据新鲜度、finding 摘要、checkpoint、repair 状态和结构化 continuation。使用 `--details` 可以取得最多 50 条详细 findings、恢复信息以及首个 `acceptancePage`。若 `findingsTruncated` 为 `true`，不能把未展示项当作不存在。

当 `acceptancePage.nextCursor` 非空时，用 `--acceptance-cursor` 逐页读取；每页最多 16 条，cursor 同时绑定 change 与当前 acceptance hash。`show` 对规格数量、单文件、累计读取和最终输出都有硬预算；超限时拒绝，不会通过截断需求正文伪装成功。

## 阶段内 checkpoint

```bash theme={null}
comet native checkpoint <change-name> \
  --summary <text> \
  --next-action <text> \
  [--artifact <project-relative-path>]... \
  [--expect-revision <n>]
```

Checkpoint 保存同阶段摘要、下一动作和内容寻址的产物 manifest，不改变 phase。`--expect-revision` 使用 CAS 防止旧会话覆盖更新后的状态。恢复会话应从 `status` 返回的 checkpoint 继续，而不是依赖聊天记忆。

## 内置只读检查

```bash theme={null}
comet native check <change-name>
```

`check` 只允许在 Verify 且已有 implementation scope 时运行。它执行 Comet 内置的有界只读文本策略，并把结果写入独立、内容寻址的 receipt。

它不会：

* 调用 Git、shell、项目脚本、测试命令或外部 Skill；
* 接受任意命令、环境变量、路径或超时参数；
* 修改项目源码、change phase、Run state 或 trajectory。

检查发现问题或 scope 已 stale 时返回退出码 `1`，但 receipt 仍会保存。模型仍应按任务风险自行运行真实项目测试；内置 check 是可复核的补充证据，不是通用测试执行器。

## 阶段推进

```bash theme={null}
comet native next <change-name> --summary <text> \
  [--confirmed] \
  [--artifact <project-relative-path>]... \
  [--no-code-reason <text>] \
  [--allow-partial-scope <sha256> --partial-reason <text> --confirmed] \
  [--result pass|fail] \
  [--report <change-relative-path>] \
  [--receipt <runtime/evidence/check-receipts/...json>] \
  [--failure-category <token>]... \
  [--failed-check <token>]... \
  [--override-repair <sha256> --override-summary <text>]
```

| 当前阶段    | Runtime 要求                                              | 推进结果                          |
| ------- | ------------------------------------------------------- | ----------------------------- |
| Shape   | 完整 brief、合法目标规格、无 `[blocking]` 问题                       | 进入 Build                      |
| Build   | brief/spec 仍有效；真实产物或 no-code 原因；完整 implementation scope | 进入 Verify                     |
| Verify  | 结构完整且绑定当前 acceptance/contract/scope 的报告                 | pass 进入 Archive；fail 返回 Build |
| Archive | 使用独立两步归档命令                                              | 更新 canonical spec 并归档         |

只有用户刚确认了会影响范围、用户可见行为、兼容性、风险或不可逆性的决定时，Shape/Build 才传 `--confirmed`。没有高影响决定时由 Runtime 记录隐式确认；任何确认都不能绕过 `[blocking]` 问题。进入 Build 时，Runtime 把 approval 绑定到当时的 `approved_contract_hash`。之后若 brief 或完整目标规格变化，Build 会保持阻塞并返回 `re-confirm-contract`；只有用户重新确认当前 contract 后才能再次传 `--confirmed`，不能复用旧确认或手改 hash。

Build 无法证明完整 scope 时，第一次调用只返回 scope hash 和未归属项，不推进。当前 snapshot 不完整时，Runtime 不会把未观察到的路径推断成删除；变化明细超过预算时，保留有界明细，并用带计数和内容 hash 的 `scope-detail-overflow` 表示其余变化。用户明确接受一组 Runtime 允许授权的具体风险后，使用完全匹配的 `--allow-partial-scope`、非空理由和 `--confirmed` 重试。Allowance 与 scope hash 绑定；实现变化后不能沿用旧授权。`git-selection-changed`、`physical-selection-changed` 与 `physical-enumeration-limit` 绝不可授权；`git-enumeration-limit` 只有在优先恢复无效、Runtime 返回可授权 scope 且用户理解未知尾部风险后，才能使用同一普通 partial 协议。

Verify 报告必须包含 Runtime 可解析的验收机器块，并逐项绑定当前 Acceptance ID。旧报告、旧 receipt、变化后的 brief/spec、变化后的 implementation scope 或不同 revision 的证据都会被判定 stale。

进入 Verify 后，若 contract 或项目 snapshot 变化，status 会返回只含摘要的受控 `next`。先运行该命令退回 Build 并生成新 scope；只有 brief/spec contract hash 也变化时才让用户重新确认。若只是项目 snapshot 或 implementation 变化，保留原 `approved_contract_hash`，不要制造无意义确认。不要在 stale scope 上提交 pass/fail；Archive 中任一绑定事实变化时使用同一回退协议，不能沿用旧 pass。

## 自主修复与停止语义

Verify fail 会自动返回 Build。模型可以自主修复，但 Runtime 会按失败分类、失败检查 ID、contract 和 implementation scope 形成语义签名：

* 相同 scope 下第三次出现相同失败签名时，continuation 变为 manual stop；
* scope 真正变化后，新的 Build 推进会结束旧 repair episode；
* scope 未变化时，只允许使用 `status` 返回的签名和非空摘要 override 一次；
* 单个 repair episode 最多记录 12 次 failure，达到上限后 hard stop。

这些限制按“有没有真实证据进展”计算，不按机械 phase 切换次数计算，因此长期 change 不会因为固定 Run iteration 上限永久锁死。

## 两步 Archive

```bash theme={null}
comet native archive <change-name> --dry-run
comet native archive <change-name> --expect-preflight <sha256>
```

Archive 不能用 `next` 代替，也不能单步提交：

1. 先运行 `--dry-run`，检查证据、canonical hash、目标路径和冲突，取得 `preflightHash`。
2. 把该 hash 原样传入 `--expect-preflight`。
3. Runtime 在锁内重算全部事实；只有完全一致时才提交。

Archive 对源树、canonical 文件和事务日志使用有界、身份绑定的读取。目录移动先进入事务绑定的 quarantine，再完成不可逆提交。若在最终 marker 前中断，可以按 journal 继续或回滚；marker 写入后只能 exactly-once continue，避免已经公开为归档的结果被反向撤销。

## 诊断与恢复

```bash theme={null}
comet native doctor [<change-name>]
comet native doctor [<change-name>] --repair
comet native doctor [<change-name>] --repair [--strategy continue|rollback]
```

只读 doctor 不改文件。`--repair` 只处理 Runtime 能证明安全的事项：

* 陈旧 selection 和锁；
* schema / workspace identity 迁移；
* 阶段 transition、Archive 和 root move 事务恢复；
* 未引用且超过保留窗口的派生 evidence/receipt；
* 中断的 retention quarantine。

Doctor 不会自动重写用户的 brief、规格、验证报告或项目源码。普通阶段 transition 只支持 `continue`；`rollback` 只适用于 journal 仍允许回滚的 Archive/root move。

新 change 和当前 schema 的 v3 change 都必须保留创建时的完整 baseline。v3 baseline 缺失或不完整时，doctor 不会用当前文件重新生成，因为那会抹掉 change 创建以来的差异；应从可信备份恢复，或保留用户产物和实现事实后新建 change。

显式 v1/v2 schema migration 是唯一 cutover 例外。`doctor --repair` 会在任何状态写入前捕获完整的迁移时点 baseline；捕获不完整时保持旧状态并停止。迁移后的 implementation evidence 只证明 cutover 之后的变化，不能把迁移前聊天、旧 scope 或旧 pass 当作当前证据。v2 位于 Verify/Archive 时会受控退回 Build 重新建立证据。

普通写命令不会自动接管陈旧锁。只有显式 `doctor --repair` 能在证明本机 owner 已不存在、锁身份未变化且没有冲突事务时接管；活动锁和无法证明陈旧的锁始终保留。

Evidence retention 只清理 active change 中至少 30 天、每种 evidence kind 最新 32 份之外、且依赖闭包证明未引用的派生证据。当前状态引用、归档证据、依赖项、较新文件和每类最新 32 份始终保留。

## Continuation 与退出码

`status` 和写命令会返回结构化 continuation，常见 disposition 包括：

* `continue-same-skill`：当前 Skill 可以按下一动作继续；
* `await-user`：需要真实用户决定或 partial scope 授权；
* `repair-runtime`：先执行 doctor/recovery；
* `stop`：已完成、手动停止或达到 hard stop。

`next: auto` 表示调用方可以继续同一个 Native Skill，不表示后台 daemon 会自行调用模型。

所有命令支持 `--json`。JSON 模式只输出一个对象，包含 `command`、`exitCode`、`data`，失败时增加结构化 `error`。

| 退出码  | 含义                                 |
| ---- | ---------------------------------- |
| `0`  | 成功                                 |
| `1`  | 内置 `check` 完成，但发现问题或结果 stale       |
| `64` | 参数或用法错误                            |
| `65` | 配置、状态或产物无效                         |
| `70` | 未预期的内部失败                           |
| `73` | 锁、事务、并发 hash 或根目录冲突                |
| `75` | repair stagnation 或 hard stop 阻塞继续 |

## 只提供 Skill 文件的环境

若宿主没有安装 `comet` CLI，可直接使用 `/comet-native` 随包发布的 Runtime：

```bash theme={null}
node <comet-native-skill-root>/scripts/comet-native-runtime.mjs <command> [options]
```

它与 `comet native` 使用相同参数、输出和退出码。Runtime 与 Skill 一起发布，不依赖 OpenSpec、Superpowers、grill-me 或其他外部 Skill。