> ## 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 安全与恢复

> 了解统一 Guard 路由、证据失效、并发冲突、事务恢复、修复停止与环境感知恢复。

Native 的安全边界由两层组成：Skill 负责让模型遵循需求与阶段协议，Runtime 负责可确定检查的状态、证据和事务不变量。两者互补；文案 Rule 本身不等于不可绕过的状态机。

## 一次写入只属于一个 change

项目初始化会在每个平台安装一份 Comet 工作流 Rule；支持 Hook 的平台只安装一个 `comet-hook-router.mjs`。Router 读取 `.comet/config.yaml` 与 `.comet/current-change.json`，把一次原子多文件写入最多路由到一个 workflow Guard。

Native 与 Classic 的 Guard 保持独立：

* Native 只按 Shape、Build、Verify、Archive 和 Native 路径检查；
* Classic 只按自己的五阶段与 OpenSpec/Superpowers 路径检查；
* selection 无效、陈旧或歧义时，可能写入会失败关闭；
* 明确认定的只读工具不会触发写入 Guard。

这个边界用于减少误写和双重阻塞。对于 shell、外部进程或平台未暴露给 Hook 的写入，最终仍以 Native Runtime 的状态和证据检查为准。

## 验证证据为什么会失效

Runtime 把验证结论绑定到：

* brief 与完整目标规格；
* implementation scope 中的项目产物；
* Acceptance ID 与验证报告快照；
* 当前 change revision；
* 可选的内置 check receipt。

这些输入变化后，旧证据会标记为 stale。若变化发生在 Verify，status 会返回只含摘要的受控 `next`：先运行它退回 Build、生成新 scope 并验证。只有 brief/spec contract hash 也变化时才重新取得用户确认；仅项目 snapshot 或 implementation 变化时保留原 approval。Archive 中报告、receipt 或其他绑定事实漂移时也使用同一回退协议；不能删除 finding、手改 evidence ref 或复用旧 pass。

Native Runtime 仅在 Git 项目中调用 Git 生成有界的 Git-aware snapshot。`comet native check` 是独立的内置、有界、只读文本卫生检查，不调用 Git、shell、测试命令、外部 Skill 或任何外部进程，也不替代项目测试。

## Baseline 与 schema migration

新 change 必须在创建状态前取得完整 baseline。Git snapshot 只纳入 tracked 与未被 ignore 的 untracked 文件，submodule/gitlink 作为原子条目；ignored cache 和未登记嵌套仓库的内容不会制造 omission。当前 snapshot 不完整时不会把缺失路径推断成删除。

对已经使用 v3 schema 的 change，baseline 缺失或不完整不是 doctor 可自动修复的问题。用当前文件重建会抹掉从创建以来的历史差异；只能从可信备份恢复原 baseline，或保留 brief/spec 和实现事实后新建 change。

v1/v2 schema migration 是唯一 cutover 例外。`doctor --repair` 会在任何状态写入前捕获完整的迁移时点 baseline；捕获不完整时旧状态保持不变。迁移后的证据只证明 cutover 之后的变化，不能继承迁移前的 scope 或 pass。旧 Verify/Archive 会受控退回 Build 重新建立 v3 证据。

## 自主修复不会无限循环

Verify 失败会回到 Build。Runtime 根据失败分类、检查 ID、contract 与 implementation scope 形成失败签名：

* 相同 scope 下第三次出现相同签名时转为 manual stop；
* 真实 implementation scope 变化会开启新的 repair episode；
* 无进展 override 只允许一次，并与当前签名绑定；
* 单个 episode 最多记录 12 次 failure。

停止条件基于证据是否有进展，不是简单计算 phase 往返次数。

## 并发规格冲突

多个 Native change 可以并行存在，但对同一 canonical spec 的安全承诺有明确边界。Archive 会比较 Runtime 在 Shape 时冻结的 `base_hash` 与当前 canonical hash；不一致时停止，不做最后写入覆盖。

处理步骤是：

1. 阅读最新 canonical spec；
2. 重写当前 change 的完整目标规格；
3. 运行 `comet native spec rebase <change> --summary <text>`；
4. 重新完成 Build 与 Verify；
5. 再次执行两步 Archive。

`conflict radar` 只报告当前 Native root 内可证明的 capability 重叠与范围信号，不声称理解任意外部分支或未纳入状态的并行工作。

## 事务与锁恢复

阶段推进、checkpoint、Archive 与 root move 都有明确的 journal 或恢复协议。普通写命令不会擅自接管陈旧锁；只有 `doctor --repair` 能在证明本机 owner 已不存在、锁身份未变化且没有冲突事务时接管。

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

* 普通阶段 transition 只允许继续；
* Archive 与 root move 只有在 journal 所处阶段仍可逆时才能 rollback；
* Archive 最终 marker 写入后只允许 exactly-once continue；
* Doctor 不会重写用户的 brief、规格、验证报告或项目源码。

## 环境感知恢复

`comet resume-probe` 是只读探针。它先解析 `.comet/config.yaml` 的默认工作流，再只检查该侧状态：

| 结果             | 含义                                |
| -------------- | --------------------------------- |
| `auto_resume`  | 目标唯一且请求确实要继续工作，按 `nextCommand` 恢复 |
| `ask_user`     | 多个候选或请求归属不明确，需要一个简短选择             |
| `out_of_scope` | 当前请求不是要进入可恢复工作流                   |
| `none`         | 没有可恢复 change                      |

配置或工作流状态损坏时，探针停止并给出原因，不扫描另一套目录猜测回退。`ambient_resume: false` 可以关闭普通请求触发的自动探针；显式调用 `/comet` 不受影响。

## Dashboard 的职责

Dashboard 只读取 Runtime projection，展示 phase、证据新鲜度、continuation、结构化 finding、冲突摘要与归档就绪状态。它不重新推导事实，也不提供推进、修复或归档写按钮。CLI/Runtime 是唯一写入方。

需要处理并行需求时，查看 [多 Change 与规格冲突](/zh/native/multi-change-and-conflicts)；遇到中断、跨设备发现或事务问题时，查看 [恢复与故障处理](/zh/native/recovery-playbook)。逐项命令和退出语义见 [Native CLI](/zh/cli/native)。