@rpamis/comet 0.4.0-beta.6 → 0.4.0-beta.8

package/assets/skills-zh/comet-native/reference/artifacts.md

@@ -0,0 +1,206 @@
+# Native 产物参考
+
+## 目录
+
+```text
+<project>/.comet/config.yaml
+<project>/.comet/current-change.json       # Native/Classic 共享的当前需求归属
+<artifact-root>/comet/
+  specs/<capability>/spec.md
+  changes/<change-name>/
+    comet-state.yaml
+    brief.md
+    specs/
+    verification.md
+    runtime/
+      baseline-manifest.json
+      workspace.json                 # process-free 物理 root 身份；只作提示
+      run-state.json                 # 通过 Native Protected Run I/O 读写
+      trajectory.jsonl               # 有事件数、单事件和总字节预算
+      pending-action.json            # 可选；仅在 Run 有待处理动作时存在
+      context.md                     # 可选；Run context ref
+      artifacts.json                 # 可选；Run artifact refs
+      transition.json                # 可选；未完成阶段推进日志
+      checkpoint-journal.json        # 可选；未完成 progress checkpoint 日志
+      checkpoints/
+        latest.json                  # 最近阶段边界 checkpoint
+        progress.json
+        manifests/<sha256>.json
+      evidence/
+        scopes/<sha256>.json
+        snapshots/<sha256>.json
+        allowances/<sha256>.json
+        verifications/<sha256>.json
+        check-receipts/<sha256>.json
+  archive/YYYY-MM-DD-<change-name>/
+  runtime/
+    locks/
+    transactions/<transaction-id>/
+      transaction.json
+      events.jsonl
+```
+
+`artifact-root` 由项目配置唯一指定。Native 不使用隐藏的 change 目录，也不从其他需求目录发现状态。项目级 `.comet/config.yaml` 是持久配置例外；`root move` 中断恢复期间还可能在源/目标 artifact root 旁出现 Runtime 管理的临时 staging 或 quarantine，事务收口后会清除。它们不是第二个可写 Native change 根。
+
+## 项目配置
+
+```yaml
+schema: comet.project.v1
+default_workflow: native
+workflows:
+  - native
+native:
+  artifact_root: docs
+  language: zh-CN
+  clarification_mode: sequential
+```
+
+`clarification_mode` 只控制 Native 如何组织用户决定：`sequential` 每轮询问一个最上游问题，`batch` 每轮询问所有前置条件已经确定的问题。字段缺失时使用 `sequential`。它不改变 change schema、生命周期、Guard、安全确认或调用方停点。
+
+根目录迁移期间会出现 runtime 管理的 `pending_root_move`。存在该字段时普通写命令必须停止，不能自行选择旧根或新根。
+
+## 当前需求归属
+
+```json
+{
+  "schema": "comet.selection.v2",
+  "workflow": "native",
+  "change": "add-sentence-counting",
+  "branch": null
+}
+```
+
+`.comet/current-change.json` 是 Native 与 Classic 共用的当前需求 selection，不是 Native change 产物。Native 的 `new` 和 `select` 会写入 `workflow: native`；Hook Router 每次只把写入交给这一个 workflow 的 Guard。selection 缺失时只有全项目恰好一个 active Comet change 才能只读推断；多个候选、失效 selection 或已归档目标都会失败关闭。
+
+项目配置最多 64 KiB，selection 最多 16 KiB，change YAML 最多 256 KiB。brief 与单个拟议规格最多各 1 MiB；一个 change 最多 64 个拟议规格，contract 的 brief + specs 总读取最多 4 MiB。拟议规格目录还限制可枚举条目，`show` 的序列化载荷最多 10 MiB。超过预算时 Runtime 保留原文件并失败关闭，不以静默截断替代完整需求。
+
+## Change 状态
+
+```yaml
+schema: comet.native.v3
+minimum_runtime_version: 3
+revision: 1
+name: add-sentence-counting
+language: zh-CN
+phase: shape
+brief: brief.md
+approval: null
+approved_contract_hash: null
+spec_changes:
+  - capability: sentence-counting
+    operation: create
+    source: specs/sentence-counting/spec.md
+    base_hash: null
+verification_result: pending
+verification_report: null
+implementation_scope: null
+verification_evidence: null
+partial_allowance: null
+archived: false
+created_at: 2026-07-14
+run_id: null
+```
+
+不要直接编辑 Runtime 管理字段。`phase`、`revision`、`approval`、`approved_contract_hash`、`spec_changes`、operation、`base_hash`、三个 evidence ref、`run_id` 和 `archived` 都由 Runtime 管理。
+
+`approved_contract_hash` 把 approval 绑定到当时的 brief/spec contract。contract 发生变化后，必须由用户重新确认。需要改变需求时，只更新 brief 和 `specs/<capability>/spec.md`；删除 capability 使用 `comet native spec remove`，再由命令检查并推进。
+
+## Brief
+
+`brief.md` 固定使用八个一级标题：
+
+```text
+# Outcome
+# Scope
+# Non-goals
+# Acceptance examples
+# Constraints and invariants
+# Decisions
+# Open questions
+# Verification expectations
+```
+
+前四节必须有实质内容。仍阻塞实现的问题在 Open questions 下以 `- [blocking]` 开头；普通备注不会阻塞 Shape。
+
+Sequential 模式的 Open questions 同时保存一个最上游阻塞问题。Batch 模式使用 `- [blocking] Q1: <问题>`、`- [blocking] Q2: <问题>` 保存本轮全部可回答问题；该无序列表前缀是 Runtime 识别阻塞的固定格式，不能改成 Markdown 有序列表。未回答项继续保持 `[blocking]`。本轮问题处理完且完整性复核通过后，Batch 模式使用 `- [blocking] CONFIRM: <确认内容>` 保存共享理解确认，明确确认前不能进入 Build。
+
+问题编号只服务于当前澄清轮次。已确认答案应写入 Decisions 和完整目标规格；不要新增决策树产物，也不要把隐藏推理写入 brief。
+
+## 完整目标规格
+
+拟议规格固定写在 `changes/<change-name>/specs/<capability>/spec.md`，描述归档后 capability 应有的完整行为，不写只在旧文本上成立的增量片段。每个 capability 只能出现一次操作：
+
+| operation | canonical 现状 | source | base_hash |
+| --- | --- | --- | --- |
+| `create` | 必须不存在 | 必填 | `null` |
+| `replace` | 必须存在 | 必填 | 当前 canonical 文件 SHA-256 |
+| `remove` | 必须存在 | 禁止 | 当前 canonical 文件 SHA-256 |
+
+`next` 首次发现 proposed spec 时推断 create/replace 并冻结 hash；`spec remove` 为 remove 冻结 hash。归档在锁内重新计算 hash，实际值与 `base_hash` 不同表示并发变化，必须重新读取并改写完整目标规格，再用 `spec rebase` 受控刷新基线、回到 Build 并重新验证，不能覆盖或手改 hash。
+
+## Verification
+
+`verification.md` 固定使用六个非空一级标题：
+
+```text
+# Acceptance evidence
+# Commands and results
+# Skipped checks
+# Spec consistency
+# Known limitations and risks
+# Conclusion
+```
+
+保存可复核事实，不保存隐藏推理文本。未运行的检查放在 Skipped checks，失败结果不能写成 pass。
+
+Runtime 最多从 brief 与拟议规格合计派生 1024 个验收项，超出就拒绝继续，不会先构造无界列表再截断。`acceptancePage` 每页最多 16 项；单项文字最多 512 UTF-8 字节、context 最多 4 项且每项最多 256 字节，整页最多 32 KiB。文字或 context 截断会显式标记，验收 ID 不会因分页或截断而丢失；cursor 绑定当前 acceptance hash，契约变化后旧 cursor 会失效。
+
+`# Acceptance evidence` 下必须恰好有一个固定机器块。ID 由 Runtime 从 brief/spec 派生，通过 Build 结果或 `status --details` 返回；不要自行计算或改写：
+
+```text
+<!-- comet-native:acceptance-evidence:start -->
+[
+  {
+    "acceptance_id": "acceptance-<sha256>",
+    "evidence_refs": [
+      "src/feature.ts"
+    ]
+  },
+  {
+    "acceptance_id": "acceptance-<sha256>",
+    "evidence_refs": [],
+    "skipped_reason": "该平台当前不可用。"
+  }
+]
+<!-- comet-native:acceptance-evidence:end -->
+```
+
+数组按 `acceptance_id` 排序，`evidence_refs` 也排序。每项只能二选一：至少一个项目相对 evidence ref，或空数组加非空 `skipped_reason`。不能同时给证据和跳过理由，也不能引用绝对路径、Native 外部路径、`.git` 或 `.env*`。
+
+## 内容寻址证据
+
+- `baseline-manifest.json`：change 创建时的有界项目快照。它只记录项目相对路径、size、hash、capture provider 和省略事实，不保存文件内容。Git provider 纳入 tracked 和未被 ignore 的 untracked 文件，并把 submodule/gitlink 作为原子条目；非 Git 项目使用带前后枚举围栏的有界物理树 provider。创建时若项目所有范围内仍有省略项，`new` 会失败并清理未完成 change。
+  - `git-selection-changed`：等待 Git 写入稳定后重试，不能授权为 partial scope。
+  - `git-enumeration-limit`：先缩小或清理项目所有范围。只有 current snapshot 返回可授权 scope，且用户接受未知尾部的具体风险时，才能按精确 hash、理由与 `--confirmed` 使用 partial 协议。
+  - `physical-selection-changed` 和 `physical-enumeration-limit`：稳定或缩小项目树后重试，不能授权为 partial scope。
+  - 任何情况都不能手改 evidence 或猜测未枚举路径。
+- `evidence/scopes/`：Build 离开时由 baseline、当前快照、声明产物和 contract 派生的 implementation scope。当前快照不完整时不会猜测删除；变化过多时只展开有界明细，其余由带数量与内容 hash 的 `scope-detail-overflow` 表示。scope 不完整时 Runtime 停止；用户显式接受后才生成 `allowances/`。
+- `evidence/verifications/`：Verify 结论的 envelope，绑定 Runtime 身份、change revision、contract、acceptance coverage、scope、报告 hash 和可选 check receipt。任一绑定事实变化都会 stale。
+- `evidence/check-receipts/`：`comet native check` 的内置策略结果。它只保存 policy/version、scope/snapshot 绑定、有界 issue 与计数，不保存文件内容，也不是测试完整性的证明。
+- `checkpoints/`：阶段内恢复摘要与真实产物 manifest。checkpoint 会递增 revision，但不改变 phase，也不能代替 brief、规格、scope 或 verification。
+
+所有 hash ref 都由 Runtime 写入并在读取时重算。不要复制旧 ref 到新状态、手改 JSON 或把 receipt 当作 pass；`next`、status 和 Archive 会重新读取并检查新鲜度。
+
+Evidence retention 只能由 doctor 显式执行，不在普通工作流中后台删除文件。只读 doctor 报告候选；`doctor --repair` 只清理 active change 中至少 30 天、每种 evidence kind 最新 32 份之外，并且能从当前 state refs 及其依赖闭包证明未引用的 snapshot、scope、allowance、verification 和 check receipt。
+
+候选按 dependents-before-dependencies 排序。每个文件先在父链与身份复核后改名到同目录唯一 `.gc` quarantine，再复核并删除。中断的 quarantine 会由后续 doctor 发现；显式 repair 仅在原路径不存在且内容与身份有效时无覆盖恢复。
+
+出现原文件与 quarantine 冲突、多份 quarantine、归档 change、pending transition/checkpoint、缺失依赖、损坏文档、未知目录项、symlink 或其他特殊文件时，推迟或拒绝清理。不要把 retention 当作修复损坏证据的办法。
+
+Build 与 Verify 使用 inspect-then-persist：先计算并校验 contract、scope、acceptance、repair、Run 与 trajectory，再把最终证据引用写入状态和 transition。Partial Build 可先内容寻址保存候选 scope 以返回稳定 hash，但没有确认时不会生成 allowance 或推进；被后续检查阻塞的 Verify 不会留下可被误认成已提交结论的 verification evidence。
+
+Run state、trajectory、checkpoint、pending action、context 和 artifact refs 只能经过 Native Protected Run I/O。读取拒绝 symlink/junction、非普通文件、路径或文件身份变化和越界，并执行打开前后复核；写入在原子提交前复核父链和目标身份。
+
+当前预算为：Run state 256 KiB；trajectory 8 MiB、4096 个事件、单事件 256 KiB；checkpoint 与 pending action 各 256 KiB；context 与 artifact refs 各 1 MiB。通用 Engine 存储函数不是 Native 文件边界。
+
+阶段 transition journal 最多 512 KiB，baseline manifest 的硬上限为 8 MiB。Archive/root move transaction journal 最多 256 KiB；`events.jsonl` 最多 1 MiB 或 1024 个事件，单个事件最多 16 KiB。摘要、无代码理由、partial 理由、repair override 摘要与跳过理由在持久化前执行长度校验和凭据形态脱敏；不要把 token、密码、私钥或连接串写入 workflow 证据。

package/assets/skills-zh/comet-native/reference/commands.md

@@ -0,0 +1,118 @@
+# Native 命令参考
+
+优先使用已安装的 `comet native`。若宿主环境只提供 Skill 文件，使用本 Skill 的自带 runtime：
+
+```text
+node <comet-native-skill-root>/scripts/comet-native-runtime.mjs <command> [options]
+```
+
+两种入口的参数、stdout、stderr 和退出码相同。普通发现从当前目录向上寻找 `.comet/config.yaml` 或仓库根；生成式 launcher 可附加隐藏参数 `--project-root <path>`。
+
+## 项目与根目录
+
+```text
+comet native init [--root <artifact-root>] [--language en|zh-CN]
+comet native root show
+comet native root move <artifact-root>
+```
+
+`artifact-root` 必须是项目内相对路径，默认值是 `docs`。`.` 生成 `<project>/comet/`，`docs` 生成 `<project>/docs/comet/`。`init --language` 会把项目的 Native 默认语言持久化到 `.comet/config.yaml`；后续 `new` 未显式传入 `--language` 时继承该值。再次运行 `init --language` 可以改变以后新建 change 的默认语言，不改写已有 change。已有配置拒绝冲突的 `--root`；改变根目录必须使用 `root move`，不能直接改配置。
+
+## Change 管理
+
+```text
+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>
+```
+
+`new` 在配置缺失时创建默认配置和 `<project>/docs/comet/`。完整目标规格写入 `specs/<capability>/spec.md`；`next` 自动推断 create/replace 并冻结 canonical hash。删除 capability 使用 `spec remove`，不要手工编辑 `spec_changes`。
+
+canonical 并发变化导致冲突时，先重读并改写完整目标规格，再用 `spec rebase` 刷新 operation/hash、回到 Build 并清除原验证结论。
+
+`show` 返回状态、brief 和拟议完整规格。`status` 返回有预算的阶段、证据新鲜度、finding 摘要、checkpoint、repair 状态和 continuation。`status <change-name> --details` 还会返回：
+
+- 最多 50 条详细 findings；
+- `findingsTruncated` 标记；
+- 恢复细节；
+- 首个 `acceptancePage`。
+
+findings 被截断时，先处理已返回项，再重新读取 details。`nextCursor` 非空时，用 `--acceptance-cursor` 逐页读取，直至为 null。acceptance cursor 只允许与具体 change 和 `--details` 同用，并绑定当前 acceptance hash。
+
+`status` 与 `show` 始终只读。恢复已确认的目标 change 时显式运行 `select`，不要新增 `resume` 命令。`new` 与 `select` 都会写项目级共享 `.comet/current-change.json`，并把 `workflow` 固定为 `native`；它们不会修改 Classic change。
+
+`list` 与不带 change 的 `status` 返回同一种只读分页投影，每页最多 24 个 change；`nextCursor` 非空时原样传给 `--cursor`。cursor 绑定当前完整名称集合，change 增删后旧 cursor 会明确失效，不会错位分页。最多接受 4096 个可见 change，整页序列化结果不超过 512 KiB。`show` 还会限制规格数量、单文件、累计读取和最终输出大小；超限时拒绝，不截断需求正文。
+
+## 阶段内进度与内置检查
+
+```text
+comet native checkpoint <change-name> \
+  --summary <text> \
+  --next-action <text> \
+  [--artifact <project-relative-path>]... \
+  [--expect-revision <n>]
+
+comet native check <change-name>
+```
+
+`checkpoint` 只保存同阶段摘要、下一动作和内容寻址的产物 manifest；它通过 revision/CAS 防止覆盖，不改变 phase。`check` 只允许在 Verify 且已有 implementation scope 时运行 Comet 内置的有界只读文本扫描。它不调用 Git、shell、项目脚本、外部 Skill 或任何外部进程，不接受任意命令、路径、环境或超时参数，也不修改项目文件或 change/Run/trajectory；结果、issue 计数和 scope 新鲜度会写入独立的内容寻址 receipt。检查发现问题或 stale 返回 1，但 receipt 仍会落盘。
+
+## 阶段推进
+
+```text
+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>]
+
+comet native archive <change-name> --dry-run
+comet native archive <change-name> --expect-preflight <sha256>
+```
+
+- Shape：brief 和拟议规格通过后推进；只有本轮包含用户刚确认的决定时才传 `--confirmed`。成功进入 Build 时，Runtime 会把 approval 绑定到当前 contract hash。
+- Build：重新检查 brief 和拟议规格；至少给出一个真实项目产物，或使用 `--no-code-reason`。若 contract 在 approval 后变化，status/next 会要求用户重新确认当前 contract；只有取得该确认后才传 `--confirmed`。无法证明完整 scope 时，第一次调用返回 scope hash 与有界未归属明细而不推进；超出明细预算的变化由 `scope-detail-overflow` 的数量与内容 hash 表示。只有用户接受具体风险后，才可用完全匹配的 `--allow-partial-scope`、理由与 `--confirmed` 重试。
+- Verify：必须提供 `--result` 和完整 `--report`；可选 `--receipt` 必须是当前 change、revision、contract 与 implementation scope 上 fresh 的内置 receipt。fail 回到 Build，可用失败分类和检查 ID 形成无进展签名；pass 进入 Archive。
+- Repair：第三次相同失败会返回 manual stop。scope 真正变化时普通 Build `next` 会结束旧 repair episode 并继续；scope 不变时只能用 status 返回的 signature 和非空摘要 override 一次。单个 episode 的 semantic repair budget 与已耗尽 override 不可绕过；通用 Run iteration 只提供事件序号，不是长期 change 的永久停止条件。
+- Archive：只能由 `archive` 命令完成，不能用 `next` 代替。先 `--dry-run`，再把同一次预演返回的 `preflightHash` 原样传给 `--expect-preflight`；Runtime 在锁内重算后才提交。
+
+## 诊断与恢复
+
+```text
+comet native doctor [<change-name>]
+comet native doctor [<change-name>] --repair
+comet native doctor [<change-name>] --repair [--strategy continue|rollback]
+```
+
+只读 doctor 不改文件。`--repair` 只处理可证明安全的 selection、陈旧锁、evidence retention、普通阶段 transition、workspace 身份修复和确定性事务恢复；用户编写的 YAML、Markdown 与规格不会被自动重写。
+
+`--strategy` 是可选的事务恢复参数，不是普通 repair 的必填项。普通 transition 只支持 `continue`，不支持 `rollback`。
+
+doctor 也会只读报告 evidence retention 候选。显式 `--repair` 只清理 active change 中至少 30 天、每种 evidence kind 最新 32 份之外、且依赖闭包证明未引用的派生 evidence/receipt；归档证据、当前状态引用、依赖项、较新文件和每类最新 32 份始终保留。删除按 dependents-before-dependencies 排序，并先进入同目录 quarantine；中断后只读 doctor 报告 recovery required，显式 repair 在无覆盖且身份匹配时恢复。存在 pending journal、损坏、原文件与 quarantine 冲突或未知/特殊文件时 fail closed，不为腾空间冒险删除。
+
+普通 `new`、`next`、`archive`、`root move` 等写命令不会自动接管陈旧锁。只有显式 `doctor --repair` 会在证明本机 owner 已不存在、锁身份未变化且没有相冲突恢复事务时接管；活动锁和无法证明陈旧的锁始终保留。
+
+## 输出与退出码
+
+所有命令支持 `--json`。JSON 模式只输出一个对象，包含 `command`、`exitCode`、`data`，失败时还包含结构化 `error`。
+
+| 退出码 | 含义 |
+| --- | --- |
+| `0` | 成功 |
+| `1` | 内置 `check` 完成但发现问题或结果 stale |
+| `64` | 参数或用法错误 |
+| `65` | 配置、状态或产物无效 |
+| `73` | 锁、事务、并发 hash 或根目录冲突 |
+| `75` | repair stagnation 或 hard stop 阻塞继续 |
+| `70` | 未预期的内部失败 |

package/assets/skills-zh/comet-native/reference/recovery.md

@@ -0,0 +1,143 @@
+# Native 恢复参考
+
+## 上下文恢复顺序
+
+每次恢复都从磁盘事实开始：
+
+1. 读取项目 `.comet/config.yaml`，确认唯一 artifact root 和 `native.clarification_mode`；该字段缺失时使用 `sequential`。若有 `pending_root_move`，先运行 doctor。
+2. 运行只读的 `comet native status`；多个 active change 时读取项目级共享 `.comet/current-change.json`，确认 `workflow: native` 和目标 change，或让用户明确选择。
+3. 对目标 change 运行只读的 `show` 和 `status <change-name> --details`，读取 `comet-state.yaml`、brief、拟议完整规格、verification、有界结构化 findings、`findingsTruncated` 标记和最新 checkpoint。若 findings 被截断，先处理已返回项，再重新读取 details；Verify/Archive 的验收 ID 则按 `acceptancePage.nextCursor` 独立分页取得，不依赖丢失的旧响应。
+4. 目标确认后运行 `comet native select <change-name>` 建立共享 selection；没有单独的 `resume` 命令，且只读命令不会隐式选择 change。
+5. 读取相关 canonical 规格、实现、规则、测试和当前工作区状态。
+6. 根据 phase 执行 Shape、Build、Verify 或 Archive，不依赖聊天记录猜阶段。
+
+状态、Run state、trajectory 或 transaction journal 畸形时停止写入并运行只读 doctor。不要通过手工改 phase 来绕过问题。
+
+## 澄清轮次恢复
+
+Shape 或 Build 存在 `[blocking]` 时，从 brief 的 Open questions 恢复当前未决事项，不依赖聊天记录重建答案。Sequential 模式恢复一个最上游问题；Batch 模式按已保存编号恢复本轮全部可回答问题。切换配置不会消除已有阻塞项：先把用户答案对应回已保存问题，再按当前 `clarification_mode` 计算下一轮。
+
+能从仓库、工具或运行环境查明的事实继续由 Agent 调查。宿主支持并行工作时可以并行查证，但恢复不能依赖任何可选的并行能力；调查中的事实只延后依赖它的问题。
+
+Batch 模式中，未回答的问题继续保持 `[blocking]`。全部问题解决后仍要恢复或建立最终共享理解确认；只有用户明确确认后，才能移除该阻塞项并进入 Build。该过程不增加新 phase、change 状态字段或独立决策树文件。
+
+长任务在同一 phase 内中断前可写 checkpoint：
+
+```text
+comet native checkpoint <change-name> \
+  --summary <已完成事实> \
+  --next-action <下一动作> \
+  [--artifact <项目相对路径>] \
+  [--expect-revision <n>]
+```
+
+恢复时先检查 checkpoint 的 freshness。phase、revision 或 manifest 已变化时把它当历史提示，不把旧下一动作强行应用到新状态；Runtime 会在 details 中显式报告 stale 原因。
+
+## 普通阶段推进
+
+`next` 在 change 的 `runtime/transition.json` 先写入 prepared journal，再更新 Run state、`comet-state.yaml`、trajectory 和 checkpoint。全部完成后才删除 journal。
+
+`status` 和 doctor 会报告未完成 transition。再次运行 `next` 或进入 Archive 时，runtime 会先确定性续做；也可以显式执行：
+
+```text
+comet native doctor <change-name> --repair --strategy continue
+```
+
+普通阶段推进没有 canonical 文件副作用，因此只支持 `continue`，不支持 `rollback`。journal 畸形时保留原文件并停止，不手工拼接状态。
+
+## Baseline 缺失或不完整
+
+`new` 要求 baseline 完整。Git 项目只评估 tracked 与未被 ignore 的 untracked 文件；ignored 缓存和嵌套仓库内容不会制造省略。
+
+若 Runtime 返回 `baseline-snapshot-missing` 或 `baseline-snapshot-incomplete`，不要用当前文件重建 baseline，也不要把它当成 doctor 可自动修复的问题。这会丢失 change 创建以来的历史差异。
+
+只能从可信备份恢复原 baseline，或保留用户编写的 brief、规格和实现事实后新建 change，重新建立完整 baseline。
+
+## 证据失效与受控回退
+
+进入 Verify 后，若 brief、拟议规格或项目快照变化，status 会先把失效的 implementation scope 指向受控回退；运行返回的仅含摘要的 `next` 命令回到 Build，再为变化后的 contract 取得重新确认并生成新 scope。进入 Archive 后，implementation scope、verification report 或 check receipt 等任一绑定事实变化也会触发同一回退。不要删除 finding、沿用旧 pass 或手工替换 hash ref。
+
+Archive 必须使用两步预演，不能把一次旧的 ready 判断当作提交授权：
+
+```text
+comet native archive <change-name> --dry-run
+comet native archive <change-name> --expect-preflight <刚返回的-sha256>
+```
+
+第二步在锁内重算 contract、canonical base、scope、verification、当前 root 冲突与恢复状态；任何变化都会拒绝并要求重新预演。
+
+## Verify fail 与修复停止
+
+Verify fail 会诚实回到 Build。提交稳定、非敏感的 `--failure-category` 和 `--failed-check` 后，Runtime 先校验 token、数量与边界，再以 failure + contract + scope 形成签名：同签名第二次告警，第三次且 scope 无进展时 manual stop，单个 episode 累计到语义上限时 hard stop。
+
+- implementation scope 真正变化：说明已有机械进展，普通 Build `next` 结束旧 episode 并自动开始新一轮；之前的 hard stop 不会锁死新实现。
+- scope 未变化但有一个明确新假设：只能使用 status 返回的 signature 和非空摘要做一次 `--override-repair`。
+- 同一签名已 override、或达到 hard stop：不能弱化验证或伪造 pass；保留现场并请用户决定范围、约束或是否停止。
+
+一次 pass 会结束当前 repair episode；之后若旧 Archive 证据失效并重新出现相同 failure，它是新的 episode，但原 trajectory 仍保留审计事实。通用 Engine iteration budget 不参与这个产品语义。
+
+## Canonical spec 冲突
+
+若另一个 change 在当前 change 冻结 `base_hash` 后改变了同一 canonical spec，Archive 会停止。不要手改 hash：
+
+1. 重读最新 canonical spec、brief 和拟议完整规格；
+2. 按用户意图改写完整目标规格，必要时先解决一个用户决定；
+3. 运行 `comet native spec rebase <change-name> --summary <摘要>`；
+4. runtime 刷新 operation/hash，把 change 受控重开到 Build，并清除旧验证结论；
+5. 重新实现、在需要时用 `--confirmed` 记录刚确认的决定、重新 Verify 和 Archive。
+
+若 remove 的目标已经被并发 change 删除，rebase 会移除已满足的 remove 意图；其他 remove 会冻结最新 canonical hash 后重新验证。
+
+## 当前工作区内的并行提示
+
+status/Archive 会比较当前 Native root 中可见 change 的 capability、operation、base hash 和声明产物：确定冲突必须先解决；可能重叠也会在归档前阻塞。它不能看到未集成 worktree、远端分支或其他机器，因此不是分布式锁。
+
+`workspace-root-changed` 和 `workspace-inspection-unavailable` 是显式 advisory，只用于解释当前 root 的事实来源，不单独阻止推进或归档。finding 会列出 `native-root-ref`、`project-root-path`、`native-root-path` 等具体漂移组件。Native 默认不读取 Git branch、HEAD 或 worktree changed paths。
+
+不要把任意 `workspace-*` 都当成提示。未知 workspace 完整性 finding 仍按错误处理；Runtime 要求修复 workspace 身份时，先运行只读 doctor，再按报告执行显式 `doctor --repair`。
+
+## Archive 事务
+
+Archive 使用全局锁、staged specs、逐操作事件日志和备份。中断时 canonical 树可能处于事务中间状态，但 journal 会保留未完成事实。
+
+Archive 的 stage、backup、apply 与 rollback copy 都通过受保护句柄读取：打开前后复核源文件、realpath、父目录身份、大小与预期 hash，目标在原子提交前再次检查。它不会因为事前路径包含检查通过，就信任后续路径仍指向同一文件。
+
+write/remove 会先把 canonical 原对象身份和原内容绑定进事务，再原子改名到同目录隔离位并复验；write 使用事务私有 candidate 和无覆盖安装，rollback 也必须先隔离并验证 post 对象，再无覆盖恢复 original。即使并发替换后的内容 hash 恰好相同，只要它已经是另一个文件对象，Runtime 仍会拒绝覆盖并保留现场。
+
+`events.jsonl` 读取有总字节、事件数量和单事件预算。崩溃若只留下最后一个 canonical JSON 事件的可证明前缀，Runtime 会在下一次 append 前按原始 bytes 的 hash/size 做 CAS，并原子重写到最后一个完整事件；中间坏行、完整但非法的尾行、非规范 JSON 尾部或并发改写一律 fail closed。完整但没有末尾换行的事件不会被误删，重复操作按 `type + operationId` 保持 exactly-once。
+
+```text
+comet native doctor <change-name>
+comet native doctor <change-name> --repair --strategy continue
+comet native doctor <change-name> --repair --strategy rollback
+```
+
+- `continue`：从最后一个已完成操作继续，收敛到 committed archive。
+- `rollback`：按逆序恢复 canonical 文件和 active change。
+- Runtime 会先验证已移动的 archive tree、最终 state、受保护 Run、trajectory 事件和完成决定，随后才写 `archive-finalization-started`。标记写入前仍可安全 rollback；标记写入后已经跨越不可回滚边界，只能 continue，避免产生“已完成证据但又恢复为 active”的矛盾状态。
+
+先阅读 doctor 的路径、transaction id 和冲突信息。若 hash 与 journal 两端都不一致，保留所有树并停止自动修复。
+
+## Artifact root 迁移
+
+`root move` 依次经过 `copying`、`ready`、`switched`。配置中的 `pending_root_move` 是恢复事实源；存在时普通 Native 写命令会失败关闭。
+
+- `copying`：旧 root 是当前根，目标 staging 可能不完整。
+- `ready`：staging 已通过逐文件路径、大小和 SHA-256 校验，尚未切换配置。
+- `switched`：配置已指向新 root，旧 root 只有在再次验证两棵树等价、父链与目录身份后，才会先改名到事务 ID 绑定的 sibling quarantine，再复核删除。中断时 continue/rollback 会识别该 quarantine 并确定性收口，不会按旧路径直接递归删除。
+
+使用 doctor 的显式 continue 或 rollback。若两棵树 hash 不一致，不删除任何一棵，并把报告中的两条路径交给用户处理。
+
+## 锁与安全修复
+
+doctor 区分活动锁、可证明陈旧的本机锁和无法判断的远端锁。只在 owner 进程确定不存在且没有未处理事务依赖时删除陈旧锁；不自动破坏活动或未知锁。
+
+锁同时绑定 owner 元数据、锁文件身份和进程内 FIFO。普通 mutation 不会因为看到“看似过期”的时间戳就自动恢复；只有显式 doctor repair 才能执行带身份复验的 takeover，避免旧 owner 在新 owner 获锁后删除新锁而形成 split-brain。
+
+doctor 可以安全清理指向不存在 change 的 selection。它不会自动重写损坏的配置、change YAML、brief、规格或 verification；这些内容必须根据用户意图人工修正后重新检查。
+
+Evidence retention 遵守显式修复边界。默认 doctor 只报告候选；`--repair` 仅删除至少 30 天、每种 evidence kind 最新 32 份之外，并且依赖闭包证明未引用的 active-change 派生 evidence/receipt。
+
+删除按 dependents-before-dependencies 排序，并先改名到同目录唯一 `.gc` quarantine。若在最终删除前中断，后续只读 doctor 报告 `evidence-retention-recovery-required`；显式 repair 仅在原路径不存在、quarantine 内容与身份有效时无覆盖恢复。
+
+出现原文件与 quarantine 冲突、多份 quarantine、归档证据、pending 恢复、缺失依赖、损坏文档、未知目录项、symlink 或其他特殊文件时，推迟清理并失败关闭。

package/assets/skills-zh/comet-open/SKILL.md

@@ -13,7 +13,7 @@ description: "仅在用户明确调用 /comet-open，或由 Comet 根 Skill/runt
 
 ### 0. 输出语言约束
 
-传递给 OpenSpec 的所有提问和产物要求都必须包含解析后的 Comet 产物语言，并使用 `en`、`zh-CN` 这类规范化 ID。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `language`；change 初始化后使用 `comet state get <name> language` 读取。没有配置语言时才回退到当前用户请求语言。生成的 `proposal.md`、`design.md`、`tasks.md` 必须以该语言为主语言。
+传递给 OpenSpec 的所有提问和产物要求都必须包含解析后的 Comet 产物语言，并使用 `en`、`zh-CN` 这类规范化 ID。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `classic.language`；change 初始化后使用 `comet state get <name> language` 读取。没有配置语言时才回退到当前用户请求语言。生成的 `proposal.md`、`design.md`、`tasks.md` 必须以该语言为主语言。
 
 ### 0a. 当前 change 绑定
 
@@ -85,7 +85,7 @@ openspec --version
 
 批量拆分模式下，进入每个拆分项的 `/comet-open` 时必须明确标注「已确认拆分项」并携带该拆分项的目标、范围、非目标和验收场景。已确认拆分项默认跳过 PRD 拆分预检，除非该拆分项本身仍明显包含多个独立 capability。
 
-批量拆分模式下，单个拆分项完成 open 阶段后不得自动流转到 `/comet-design`。
+批量拆分模式下，单个拆分项完成 open 阶段后不得自动流转到 `/comet-design`。拆分完毕后必须暂停询问用户开始哪一个 change；用户选择后，只推进该 change 进入 `/comet-design`，其他 change 保持 active，稍后通过 `/comet-classic` 恢复。
 
 **批量完成硬性检查（不得跳过）**：全部拆分项完成各自的 open 阶段后，对用户确认清单中的每个 `<name>` 逐个运行：
 
@@ -103,7 +103,7 @@ comet state check <name> design
 
 任一拆分项未通过检查时，不得宣告拆分完成，也不得询问用户开始哪个 change；必须停止并从该 change 的第一个 `ready` 或 `blocked` artifact 恢复 `/comet-open`。OpenSpec 检查通过但 Comet state 检查失败时，必须先修复 `.comet.yaml` 初始化或 phase，再重新执行整批检查。
 
-只有所有拆分项都通过两项 CLI 检查后，才暂停询问用户开始哪一个 change；用户选择后，把批量清单中的该项标记为 `selected`，只推进该 change 进入 `/comet-design`，其他 change 保持 active，稍后通过 `/comet` 恢复。
+只有所有拆分项都通过两项 CLI 检查后，才暂停询问用户开始哪一个 change；用户选择后，把批量清单中的该项标记为 `selected`，只推进该 change 进入 `/comet-design`，其他 change 保持 active，稍后通过 `/comet-classic` 恢复。
 
 断点恢复时先读取 `.comet/batches/<batch-id>.json`，再对清单中已创建的 active changes 运行上述 CLI 检查；已完整通过的拆分项不得重复创建，未通过的拆分项从 OpenSpec 返回的第一个 `ready` artifact 继续。未创建项按持久清单继续创建。清单缺失或损坏时停止并请求用户重建/确认，不能从目录列表猜测原始批次边界。
 
@@ -124,7 +124,7 @@ resolved brief 或 change 名称仍不明确时不得运行 `openspec new change
 
 **立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。禁止跳过此步骤。
 
-完整 `/comet` 流程默认不得使用 Skill 工具加载 `openspec-propose` 技能；只有用户明确要求一次性生成提案和 artifacts 时才允许加载。
+完整 `/comet-classic` 流程默认不得使用 Skill 工具加载 `openspec-propose` 技能；只有用户明确要求一次性生成提案和 artifacts 时才允许加载。
 
 技能加载后，按其指引创建 change 骨架；当 Step 1b 已形成范围明确的 resolved brief 时，覆盖其"STOP and wait for user direction"行为，避免重复询问。
 

package/assets/skills-zh/comet-tweak/SKILL.md

@@ -7,7 +7,7 @@ description: "仅在用户明确调用 /comet-tweak，或由 Comet 根 Skill/run
 
 Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程。它串联 OpenSpec 的核心流程，复用 open、build、verify、archive 能力，仅跳过 Superpowers brainstorming 和完整 plan。
 
-适用于串联 OpenSpec 的轻量改动，例如配置调整、文档或 prompt 优化，以及需 spec 驱动（含 delta spec）但不需要完整 `/comet` 深度设计流程的中等变更。delta spec 在 tweak 中是一等公民正常产物，需要 delta spec 本身不构成升级理由。
+适用于串联 OpenSpec 的轻量改动，例如配置调整、文档或 prompt 优化，以及需 spec 驱动（含 delta spec）但不需要完整 `/comet-classic` 深度设计流程的中等变更。delta spec 在 tweak 中是一等公民正常产物，需要 delta spec 本身不构成升级理由。
 
 **适用条件**（必须全部满足）：
 1. 可收敛为**单一 OpenSpec change**
@@ -15,7 +15,7 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 3. 不涉及跨模块、跨层级的架构协调
 4. 任务规模可预估（文件数和任务数仅作提示，不作为硬性升级条件，见下方升级判定）
 
-**不适用**：如变更过程中命中质变信号（见「升级判定」章节），由用户决定是否升级为完整 `/comet` 流程。
+**不适用**：如变更过程中命中质变信号（见「升级判定」章节），由用户决定是否升级为完整 `/comet-classic` 流程。
 
 ---
 
@@ -23,7 +23,7 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 
 ### 0. 输出语言约束
 
-精简版 OpenSpec 产物必须使用 Comet 配置产物语言。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `language`，初始化后使用 `comet state get <name> language` 读取。
+精简版 OpenSpec 产物必须使用 Comet 配置产物语言。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `classic.language`，初始化后使用 `comet state get <name> language` 读取。
 
 执行链路：open → OpenSpec apply → verify → archive。Tweak 为每个阶段提供默认决策：精简开启、通过 OpenSpec apply 直接构建、按规模与 delta spec 判定验证轻重、验证通过后进入归档前最终确认。
 
@@ -81,7 +81,7 @@ comet guard <change-name> open --apply
 使用 tweak 默认值：`build_mode: direct`。`isolation` 必须沿用 Step 1 中用户已确认的入口工作区隔离方式，不得自行改回 `current`。跳过 Superpowers `brainstorming` 和 `writing-plans`，改由 OpenSpec 的 apply action 执行当前 change 的 tasks。
 
 <IMPORTANT>
-这条 apply 路径只属于 tweak。完整 `/comet` 或 `workflow: full` 不得套用 tweak 的 `openspec-apply-change` 构建路径；full 仍必须先通过 `/comet-design` 生成 Design Doc，再由 `/comet-build` 通过 Superpowers `writing-plans`、执行方式选择和对应执行技能完成构建。
+这条 apply 路径只属于 tweak。完整 `/comet-classic` 或 `workflow: full` 不得套用 tweak 的 `openspec-apply-change` 构建路径；full 仍必须先通过 `/comet-design` 生成 Design Doc，再由 `/comet-build` 通过 Superpowers `writing-plans`、执行方式选择和对应执行技能完成构建。
 </IMPORTANT>
 
 继续或开始修改前，按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。若归因后发现命中质变信号或文件数 tripwire，按本文件「升级判定」处理。
@@ -106,7 +106,7 @@ comet guard <change-name> open --apply
 
 具体调查、最小失败测试、修复验证和保持当前 change 验证闭环的要求，按 `comet/reference/debug-gate.md` 执行。
 
-**升级判定检查**：build 全程持续判断，并在 build→verify 守卫执行前做一次集中复核。判定采用三层分工（详见「升级判定」章节）：质变信号靠 agent 语义识别、文件数仅作提示交用户拍板、scale 脚本仅管验证轻重。命中质变信号或文件数超提示阈值时，**不得自行升级或自行判定可继续**，必须按 `comet/reference/decision-point.md` 暂停并把决策权交给用户：继续 tweak 轻量流程，还是升级为完整 `/comet`。
+**升级判定检查**：build 全程持续判断，并在 build→verify 守卫执行前做一次集中复核。判定采用三层分工（详见「升级判定」章节）：质变信号靠 agent 语义识别、文件数仅作提示交用户拍板、scale 脚本仅管验证轻重。命中质变信号或文件数超提示阈值时，**不得自行升级或自行判定可继续**，必须按 `comet/reference/decision-point.md` 暂停并把决策权交给用户：继续 tweak 轻量流程，还是升级为完整 `/comet-classic`。
 
 运行阶段守卫完成 build → verify 过渡：
 
@@ -145,7 +145,7 @@ comet state set <change-name> verify_mode full
 <IMPORTANT>
 Tweak 流程默认 **一次性连续执行**。调用 `/comet-tweak` 后，agent 在 tweak 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界（build/verify/archive 之间）结束当前调用并按 `HINT` 交还控制权，由用户稍后手动运行下一阶段命令；这是手动衔接，不是新的确认点。无论 `auto_transition` 取何值，以下真正的用户决策仍需暂停：
 
-1. 遇到升级判定信号（见「升级判定」章节），**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确选择**：继续 tweak 轻量流程，还是升级为完整 `/comet` 流程
+1. 遇到升级判定信号（见「升级判定」章节），**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确选择**：继续 tweak 轻量流程，还是升级为完整 `/comet-classic` 流程
 2. 验证阶段（comet-verify）接受 WARNING/SUGGESTION 偏差、处理 Spec 漂移或超过自动修复上限后的策略决策；前 3 次明确可修复失败自动闭环
 3. 归档前最终确认，以及归档提交后的分支处理决策
 
@@ -160,7 +160,7 @@ Tweak 流程默认 **一次性连续执行**。调用 `/comet-tweak` 后，agent
 
 tweak 的升级判定只决定是否从轻量预设转为 full；delta spec 本身不是升级理由，文件数不自动升级，`comet state scale` 只决定验证轻重。
 
-若由 `/comet` 入口传入 intent frame，tweak 在 build 前只复核 `risk_signal` 和升级信号：新增 capability、public API、schema 变更、跨模块协调或深层架构问题。命中时进入现有升级决策点；delta spec 仍是 tweak 的正常产物，不因存在 delta spec 自动升级；不得重新实现入口意图识别。
+若由 `/comet-classic` 入口传入 intent frame，tweak 在 build 前只复核 `risk_signal` 和升级信号：新增 capability、public API、schema 变更、跨模块协调或深层架构问题。命中时进入现有升级决策点；delta spec 仍是 tweak 的正常产物，不因存在 delta spec 自动升级；不得重新实现入口意图识别。
 
 持续检查以下质变信号：跨模块协调修改、需要新增 capability、数据库 schema 变更、引入新的 public API、触及深层架构问题；以及 tweak 特有信号：需要拆分为多个 OpenSpec changes。命中任一信号时，agent **不得自行升级或自行判定可继续**。