@rpamis/comet 0.4.0-beta.1 → 0.4.0-beta.10

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

@@ -1,10 +1,12 @@
 ---
 name: comet-hotfix
-description: "Use when 用户要修复已有行为 bug，且不新增 capability、不需要完整设计；也用于恢复 hotfix workflow。"
+description: "仅在用户明确调用 /comet-hotfix，或由 Comet 根 Skill/runtime 路由到 hotfix preset 时使用；修复已有行为 bug，不用于普通的未托管 bugfix。"
 ---
 
 # Comet 预设路径：Hotfix
 
+开始或恢复前必须先读取并执行 `comet/reference/classic-layout.md`；本文件中的 OpenSpec CLI 调用必须使用 adapter，文件路径必须使用该协议绑定的 `<classic-*>` 逻辑根。
+
 快速 bug fix 工作流：open → build → verify → archive。跳过 brainstorming 和完整 plan，适用于行为修复、不涉及新 capability 设计的场景。
 
 **适用条件**（必须全部满足）：
@@ -12,7 +14,7 @@ description: "Use when 用户要修复已有行为 bug，且不新增 capability
 2. 不涉及接口变更或架构调整
 3. 改动范围可预估（文件数仅作提示，不作为硬性升级条件，见下方升级判定）
 
-**不适用**：如修复过程命中质变信号（见「升级判定」章节），由用户决定是否升级为完整 `/comet` 流程。
+**不适用**：如修复过程命中质变信号（见「升级判定」章节），由用户决定是否升级为完整 `/comet-classic` 流程。
 
 ---
 
@@ -20,64 +22,85 @@ description: "Use when 用户要修复已有行为 bug，且不新增 capability
 
 ### 0. 输出语言约束
 
-精简版 OpenSpec 产物必须使用 Comet 配置产物语言。`.comet.yaml` 尚不存在时读取 `.comet/config.yaml` 的 `language`，初始化后使用 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取。
+精简版 OpenSpec 产物必须使用 Comet 配置产物语言。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `classic.language`，初始化后使用 `comet state get <name> language` 读取。
 
 执行链路：open → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后进入归档前最终确认。
 
 开始前按 `comet/reference/scripts.md` 定位 Comet 脚本（定位 `comet-env.mjs`）；从任意入口恢复时先按 `comet/reference/context-recovery.md` 确认 phase/workflow。
 
+恢复已有 hotfix change 时，第一项状态操作必须是 `comet state select <change-name>`；创建新 change 时，在 `.comet.yaml` 初始化成功后立即运行该命令，再进入源码写入步骤。
+
 ### 1. 快速开启（预设 open）
 
 复用 Comet open 能力创建 change，但使用 hotfix 默认值：不执行 `openspec-explore` 长探索，直接进入精简 change 创建。
 
 **立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。禁止跳过此步骤。
 
-技能加载后，按其指引创建精简版产物：
-  - `proposal.md` — 问题描述 + 根因分析 + 修复目标（无需方案对比）
-  - `design.md` — 修复方案（1 个即可，无需多方案对比）
-  - `tasks.md` — 修复任务清单
-- **无需 delta spec**（除非修复改变了已有 spec 的验收场景）
+<!-- external-openspec-skill-override -->
+**外部 OpenSpec Skill 覆写：** 加载后不得执行其中直接官方 CLI、固定 cwd 或固定物理 OpenSpec 路径的指令；所有 OpenSpec 命令改用 `comet classic openspec -- <args...>`，所有 change 与 artifact 路径改用本轮绑定的 `<classic-*>` 逻辑根。
 
-初始化 Comet 状态文件：
+技能加载后先创建 change 骨架，立即初始化可恢复状态并绑定当前 change：
 
 ```bash
-node "$COMET_STATE" init <name> hotfix
+comet state init <name> hotfix
+comet state select <name>
+comet state check <name> open
 ```
 
-初始化后验证状态：
+若上述 `select` / `check` 输出 `BLOCKED`，且原因是 `bound_branch` 与当前分支不一致，立即按 `comet/reference/decision-point.md` 暂停，让用户单选：切回绑定分支后重新运行入口验证，或在用户明确确认当前分支应接管该 change 后运行 `comet state rebind <change-name>` 并重新入口验证。不得自行切换分支，不得自行换绑。
+
+入口工作区隔离是用户决策点，不再把 `current` 当作默认隔离模式写入。按 `comet/reference/decision-point.md` 暂停让用户单选：
+
+- A. 当前分支直接工作：运行 `comet state set <name> isolation current`，如实绑定当前分支
+- B. 创建分支：先创建并切换到 `hotfix/YYYYMMDD/<change-name>`，再运行 `comet state set <name> isolation branch`
+- C. 创建 worktree：必须先使用 Skill 工具加载 Superpowers `using-git-worktrees` 技能，由该技能创建隔离工作区；进入 worktree 后运行 `comet state set <name> isolation worktree`
+
+B/C 完成后，必须在实际执行分支或 worktree 中重新运行：
 
 ```bash
-node "$COMET_STATE" check <name> open
+comet state select <name>
 ```
 
+随后按指引创建精简版产物：
+  - `proposal.md` — 问题描述 + 根因分析 + 修复目标（无需方案对比）
+  - `design.md` — 修复方案（1 个即可，无需多方案对比）
+  - `tasks.md` — 修复任务清单
+- **无需 delta spec**（除非修复改变了已有 spec 的验收场景）
+
 阶段守卫完成 open → build 过渡：
 
 ```bash
-node "$COMET_GUARD" <change-name> open --apply
+comet guard <change-name> open --apply
 ```
 
 检查 `auto_transition` 决定是否继续：
 
 ```bash
-node "$COMET_STATE" next <name>
+comet state next <name>
 ```
 
 - `NEXT: auto` → 继续 Step 2
-- `NEXT: manual` → 暂停，按 `HINT` 提示用户手动运行 `/<SKILL>`
+- `NEXT: manual` → 按 `HINT` 交还控制权并结束当前调用；不要再询问用户是否继续
 
 ### 2. 直接构建（预设 build）
 
-使用 hotfix 默认值：`build_mode: direct`，`review_mode: off`（hotfix/tweak 跳过 review_mode 选择——guard 不要求预设工作流选择此项）。跳过 Superpowers `brainstorming` 和 `writing-plans`（除非任务 > 3 个；若超过 3 个任务，转入 `/comet-build` 的计划与执行方式选择——注意这不触发 full workflow 升级，仅切换执行方式）。
+使用 hotfix 默认值：`build_mode: direct`、`tdd_mode: direct`、`review_mode: off`。`isolation` 必须沿用 Step 1 中用户已确认的入口工作区隔离方式，不得自行改回 `current`。`direct` 表示不进入完整规划/TDD 编排，不表示可以跳过复现、回归测试或验证。跳过 Superpowers `brainstorming` 和 `writing-plans`；**任务数量本身不触发 `/comet-build`**，任务较多时仍在当前 hotfix 的 tasks.md 中按顺序执行，只有命中后文质变信号或范围 tripwire 才交给用户决定是否升级 full。
 
 继续或开始修改前，按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。若归因后发现修复命中质变信号或文件数 tripwire，按本文件「升级判定」处理。
 
-**立即执行：** 按 tasks.md 逐个执行任务：
+修改实现前，必须**先复现问题并记录失败证据**：
+
+1. 用最小可重复步骤确认用户报告的旧行为确实失败，并记录命令、输入和实际结果
+2. 能自动化时先新增一个会失败的回归测试并实际运行，确认失败原因对应本 bug，而不是环境或测试本身错误
+3. 暂时无法自动化时，在 proposal/验证报告中记录不可自动化原因和可重复的手工失败证据；不得无证据直接改代码
+
+完成 RED 证据后，按 tasks.md 逐个执行任务：
 
-1. 读取 `openspec/changes/<name>/tasks.md`，获取未完成任务列表
+1. 读取 `<classic-change-dir>/tasks.md`，获取未完成任务列表
 2. 对每个未完成任务：
    - 根据任务描述修改代码
    - 运行项目格式化命令（如 `mvn spotless:apply`、`npm run format` 等）
-   - 运行相关测试确认通过
+   - 先运行新增的失败回归测试确认转绿，再运行相关测试确认通过
    - 将 tasks.md 中对应 `- [ ]` 勾选为 `- [x]`
    - 提交代码，commit message 格式：`fix: <简述修复>`
 3. 全部任务完成后，显式运行项目相关测试和构建命令
@@ -87,7 +110,7 @@ node "$COMET_STATE" next <name>
 具体调查、最小失败测试、修复验证和保持当前 change 验证闭环的要求，按 `comet/reference/debug-gate.md` 执行。
 
 **如修复影响已有 spec 验收场景**：
-- 在 `openspec/changes/<name>/specs/<capability>/spec.md` 创建 delta spec
+- 在 `<classic-change-dir>/specs/<capability>/spec.md` 创建 delta spec
 - 仅包含 `## MODIFIED Requirements` 部分
 
 ### 3. 根因消除检查
@@ -105,7 +128,7 @@ node "$COMET_STATE" next <name>
 根因确认消除后，运行阶段守卫完成 build → verify 过渡：
 
 ```bash
-node "$COMET_GUARD" <change-name> build --apply
+comet guard <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
@@ -116,7 +139,7 @@ node "$COMET_GUARD" <change-name> build --apply
 
 **立即执行：** 使用 Skill 工具加载 `comet-verify` 技能。禁止跳过此步骤。
 
-无 delta spec 的小范围 hotfix 通常满足轻量验证条件（≤ 3 tasks、改动文件数低于 scale 阈值），comet-verify 的规模评估会选择轻量验证路径（6 项快速检查；默认 `review_mode: off` 时不自动派发代码审查）。若用户希望增加审查，可在验证前运行 `node "$COMET_STATE" set <name> review_mode standard` 或 `thorough`。若 hotfix 创建了 delta spec，则根据 comet-verify 的规模评估规则进入完整验证路径。
+无 delta spec 的小范围 hotfix 通常满足轻量验证条件（≤ 3 tasks、改动文件数低于 scale 阈值），comet-verify 的规模评估会选择轻量验证路径（6 项快速检查；默认 `review_mode: off` 时不自动派发代码审查）。若用户希望增加审查，可在验证前运行 `comet state set <name> review_mode standard` 或 `thorough`。若 hotfix 创建了 delta spec，则根据 comet-verify 的规模评估规则进入完整验证路径。
 
 验证通过后，按 `/comet-verify` 的规则将 `.comet.yaml` 的 `verify_result` 记录为 `pass`，归档前不得跳过该状态。验证通过后仍必须进入 `/comet-archive` 的归档前最终确认，不得自动运行归档脚本。
 
@@ -132,12 +155,11 @@ node "$COMET_GUARD" <change-name> build --apply
 ## 连续执行模式
 
 <IMPORTANT>
-Hotfix 流程默认 **一次性连续执行**。调用 `/comet-hotfix` 后，agent 在 hotfix 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界（build/verify/archive 之间）停下，由用户手动运行下一阶段命令——此时连续执行降级为逐阶段手动推进，详见下方「自动衔接下一阶段」。但无论 `auto_transition` 取何值，以下情况都必须暂停等待用户确认：
+Hotfix 流程默认 **一次性连续执行**。调用 `/comet-hotfix` 后，agent 在 hotfix 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界（build/verify/archive 之间）结束当前调用并按 `HINT` 交还控制权，由用户稍后手动运行下一阶段命令；这是手动衔接，不是新的确认点。无论 `auto_transition` 取何值，以下真正的用户决策仍需暂停：
 
-1. 遇到升级判定信号（见「升级判定」章节），**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确选择**：继续 hotfix 流程，还是升级为完整 `/comet` 流程
-2. 任务超过 3 个转入 `/comet-build` 时的工作区隔离和执行方式选择
-3. 验证阶段（comet-verify）的验证失败决策和分支处理决策
-4. 归档前最终确认（comet-archive 执行归档脚本前）
+1. 遇到升级判定信号（见「升级判定」章节），**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确选择**：继续 hotfix 流程，还是升级为完整 `/comet-classic` 流程
+2. 验证阶段（comet-verify）接受 WARNING/SUGGESTION 偏差、处理 Spec 漂移或超过自动修复上限后的策略决策；前 3 次明确可修复失败自动闭环
+3. 归档前最终确认，以及归档提交后的分支处理决策
 
 执行顺序：快速开启 → 直接构建 → 根因消除检查 → 验证 → 归档 → 完成
 
@@ -148,9 +170,9 @@ Hotfix 流程默认 **一次性连续执行**。调用 `/comet-hotfix` 后，age
 
 ## 升级判定
 
-hotfix 的升级判定只决定是否从预设流程转为 full；文件数不自动升级，`comet-state scale` 只决定验证轻重。
+hotfix 的升级判定只决定是否从预设流程转为 full；文件数不自动升级，`comet state scale` 只决定验证轻重。
 
-若由 `/comet` 入口传入 intent frame，hotfix 在 build 前只复核 `risk_signal` 和升级信号：新增 capability、public API、schema 变更、跨模块协调或深层架构问题。命中时进入现有升级决策点；不得重新实现入口意图识别。
+若由 `/comet-classic` 入口传入 intent frame，hotfix 在 build 前只复核 `risk_signal` 和升级信号：新增 capability、public API、schema 变更、跨模块协调或深层架构问题。命中时进入现有升级决策点；不得重新实现入口意图识别。
 
 持续检查以下质变信号：跨模块协调修改、需要新增 capability、数据库 schema 变更、引入新的 public API、触及深层架构问题（hotfix 语境下多在根因消除检查时暴露）。命中任一信号时，agent **不得自行升级或自行判定可继续**。
 
@@ -161,10 +183,10 @@ hotfix 的升级判定只决定是否从预设流程转为 full；文件数不
 用户选择升级（选项 B）后，使用状态机合法的升级通道，单条命令完成预设流程 → full 转换并回退到 design 阶段：
 
 ```bash
-node "$COMET_STATE" transition <name> preset-escalate
+comet state transition <name> preset-escalate
 ```
 
-该命令原子地把 `workflow`/`classic_profile` 置为 `full`、`phase` 回退到 `design`、清空 `design_doc`（满足 comet-design 入口要求）。然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**，后续正常走完整流程。
+该命令原子地把 `workflow`/`classic_profile` 置为 `full`、`phase` 回退到 `design`、清空 `design_doc`，并清除预设专属的 `build_mode`、`tdd_mode`、`review_mode`、`isolation` 和 `verify_mode`。然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**；进入 build 后必须重新进行一次完整的联合工作方式选择。
 
 用户选择继续（选项 A）时，继续 hotfix 流程，并记录用户确认继续的原因。
 
@@ -175,16 +197,16 @@ node "$COMET_STATE" transition <name> preset-escalate
 - Bug 已修复，测试通过
 - change 已归档
 - 如有 spec 变更，已同步到 main spec
-- **阶段守卫**：build → verify 前运行 `node "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `node "$COMET_GUARD" <change-name> verify --apply`
+- **阶段守卫**：build → verify 前运行 `comet guard <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `comet guard <change-name> verify --apply`
 
 ## 自动衔接下一阶段
 
 按 `comet/reference/auto-transition.md` 执行。关键命令：
 
 ```bash
-node "$COMET_STATE" next <name>
+comet state next <name>
 ```
 
 - `NEXT: auto` → 调用 `SKILL` 指向的 skill 继续 hotfix 流程（`phase: build` 返回 `comet-hotfix`，`verify` 返回 `comet-verify`，`archive` 返回 `comet-archive`）
-- `NEXT: manual` → 不要调用下一 skill，按 `HINT` 提示用户手动运行 `/<SKILL>`
+- `NEXT: manual` → 不调用下一 skill，按 `HINT` 交还控制权并结束当前调用；不再创建确认点
 - `NEXT: done` → 流程已完成，无需继续

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

@@ -0,0 +1,133 @@
+---
+name: comet-native
+description: 当用户明确调用 /comet-native、要求启动或恢复 Native change，或入口路由到 Native 时使用；负责澄清需求、读取状态并推动 Shape → Build → Verify → Archive。
+---
+
+# Comet Native
+
+Native 保存需求、完整目标规格、状态和证据。你负责理解、实现和验证；Runtime 负责状态、边界和恢复。
+
+## 按需加载
+
+先只使用本文件。遇到对应任务时再读取一份 reference：
+
+- Shape 中存在尚未确定的用户可见行为时，读取[澄清参考](reference/clarification.md)。
+- 需要高级参数、receipt、partial scope 或外部角色交接命令时，读取[命令参考](reference/commands.md)。
+- 需要编辑 brief、规格或 verification 时，读取[产物参考](reference/artifacts.md)。
+- 出现中断、失效证据、repair stop、冲突、锁或迁移问题时，读取[恢复参考](reference/recovery.md)。
+
+## 核心规则
+
+从 `.comet/config.yaml` 读取：
+
+- `native.clarification_mode`：默认 `sequential`；
+- `native.archive_confirmation`：默认 `automatic`；
+- `native.max_verify_failures`：默认 `5`。
+
+磁盘中的 config、selection、change 状态和正式产物优先于聊天记忆。不要直接编辑 Runtime 管理的状态、证据、锁或事务文件。
+
+Native 主流程不依赖任何外部 Skill。
+
+不要接收签名私钥，也不要代替外部审批角色。缺少外部动作时，按 Runtime continuation 等待并转交所需命令。
+
+## 开始或恢复
+
+1. 运行 `comet native status`，确认当前 change 和 phase。
+2. 对目标运行 `comet native show <change-name>`；Verify、Archive 或失败后的 Build 再运行 `status <change-name> --details`。
+3. 需要更多 acceptance 时，按 `acceptancePage.nextCursor` 分页；findings 被截断时，先处理已返回项，再重新读取。
+4. 确认目标后运行 `comet native select <change-name>`。
+5. 只读取当前 phase 需要的正式产物、实现、测试和项目规则。
+
+存在多个合理候选时让用户选择。只有确认没有对应 active change 时才创建：
+
+```text
+comet native new <change-name> \
+  --creation-authorization <owner-provided-path> \
+  --language zh-CN
+```
+
+如果 Runtime 报告缺少外部授权，停止创建并等待 owner。只使用配置指定的 Native artifact root。
+
+## Shape
+
+先调查能从仓库、工具和运行环境查明的事实。只有不同选择会实质改变用户可见结果，并且无法从已有要求可靠确定时，才询问用户；实现方式由你决定。
+
+存在未决行为时，按 `clarification_mode` 读取并执行澄清参考。每次用户回答后，立即更新同一个 change 的 Decisions、brief 和完整目标规格。未解决项继续以 `[blocking]` 保存；存在阻塞项时不修改项目实现，也不推进阶段。
+
+所有用户决定处理完后，重新检查是否仍有静默假设，并向用户提供目标、范围、关键决定、验收标准和非目标的共享理解摘要。只有用户明确确认后，才移除最终阻塞项并推进：
+
+```text
+comet native next <change-name> --summary <摘要> --confirmed
+```
+
+brief 或规格改变已确认的行为时，重新取得用户确认；不要手工修改确认状态。
+
+## Build
+
+实现满足 brief 和完整目标规格的最简单可靠方案。可以分批完成；长任务可使用 checkpoint 保存恢复摘要，但 checkpoint 不是完成证据。
+
+需求变化时先更新正式产物。出现新的用户决定时回到 Shape 的澄清与确认边界。
+
+候选实现完成后，对照完整规格和全部 acceptance 复核是否仍有遗漏，再提供真实项目产物推进：
+
+```text
+comet native next <change-name> \
+  --summary <摘要> \
+  --artifact <项目内路径>
+```
+
+没有代码变化或 Runtime 无法证明完整 scope 时，读取命令参考。不得把未知或不完整范围声明为 complete。
+
+## Completion Loop
+
+进入 Build 后按以下循环收敛：
+
+1. 运行 `status <change-name> --details` 并读取当前需要的 acceptance 页；上一轮 Verify 失败时，优先处理 failed/missing acceptance 和 failed check。
+2. 完成一批相关的实际修复。需要中断时可以写 checkpoint，但 checkpoint 不是完成证据。
+3. 形成候选实现后，重新读取 brief、完整规格和全部 acceptance，执行一次完整审查。
+4. 运行真实验证并提交 Verify 结果。
+5. `fail` 回到 Build，从第 1 步继续，且不运行 Archive；`pass` 才进入 Archive。
+
+Loop 只在 `done`、`await-user`、`blocked` 或调用方明确要求停止时结束。一次 Agent turn、一次 checkpoint 或 Agent 自述“已完成”都不是终态。Agent 负责发现并修复缺口，Runtime 负责判断是否完成。
+
+## Verify
+
+根据 acceptance、完整目标规格和改动风险运行真实验证。用实际结果完成 `verification.md` 和验收证据；未运行或失败的检查不能写成通过。
+
+使用 Runtime 返回的 acceptance ID 和 receipt。需要生成证据块、记录 automated/manual receipt、申请 waiver 或交接独立审核时，读取产物与命令参考。当前 Agent 不执行外部签名。
+
+只有 Runtime 接受完整且新鲜的验收矩阵、required checks 和独立审核时才能提交 `pass`。相关实现、规格、报告或证据改变后重新验证。
+
+`fail` 会回到 Build。先根据 Runtime 返回的 failed/missing acceptance 和 failed check 修复，再重新验证；不要把再次调用 `next` 当作修复。达到 Runtime 的重复缺口停止条件或 `native.max_verify_failures` 预算时，停止并等待用户决定。
+
+Verify 失败的中间循环不运行 Archive，也不触发归档确认。持续执行 Build → Verify，直到 pass、Runtime 阻塞或需要用户决定。
+
+## Archive
+
+只有最终 Verify pass 后才预演：
+
+```text
+comet native archive <change-name> --dry-run
+```
+
+预演成功后：
+
+- `automatic`：执行 continuation 返回的精确提交命令；
+- `required`：向用户展示实现、验证和规格操作摘要，等待用户选择立即归档或保留 change。
+
+不要复用旧 preflight。发生事实漂移、canonical 冲突或未完成事务时，按 continuation 和恢复参考处理。
+
+## Continuation 与停止条件
+
+Shape、Build 和 Verify 的 transition 都会返回 `next: auto | manual`、`continuation.disposition: continue | await-user | blocked | done`、所需输入与下一步动作；Archive 不通过 `next` 推进，归档成功才返回 `done`。每次 transition 后按该 Runtime continuation 行动：
+
+- `continue`：重新读取 phase 和当前所需产物后继续；
+- `await-user`：等待确实属于用户或外部角色的输入；
+- `blocked`：处理 findings，必要时读取恢复参考；
+- `done`：change 已完成。
+
+`next: auto` 只表示本次 transition 成功，不表示后续步骤已执行。调用方明确要求在某次 transition 后停止时，严格按“更新正式产物 → 执行一次允许的 transition → transition 成功后不再调用工具 → 输出约定标记并结束本轮”执行；即使 continuation 为 `continue` 也不得继续执行后续步骤。
+
+`workspace-root-changed` 与 `workspace-inspection-unavailable` 是只读提示，不单独阻止推进或归档。未知的 workspace 完整性 finding、确定冲突、失效证据和 repair stop 必须处理；Runtime 要求修复工作区身份时，先运行只读 doctor，再按报告执行显式 `doctor --repair`。
+
+摘要、理由、报告和产物中不得写入 token、密码、私钥、连接串或其他凭据。

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

@@ -0,0 +1,141 @@
+# Native 产物参考
+
+只在需要编辑 brief、完整目标规格、verification 或验收证据时读取本文件。
+
+## 产物边界
+
+Agent 主要编辑：
+
+```text
+<artifact-root>/comet/changes/<change-name>/
+  brief.md
+  specs/<capability>/spec.md
+  verification.md
+```
+
+项目配置、当前 selection 和 change 状态用于读取，不要手工改变 Runtime 管理的 phase、确认、规格操作、scope、evidence、checkpoint、锁或事务字段。
+
+Native artifact root 只由 `.comet/config.yaml` 指定。不要扫描其他 workflow 的目录，也不要自行创建第二个状态根。
+
+## Scope 快照边界
+
+Git 快照包含 tracked 和未被 ignore 的 untracked 文件，submodule/gitlink 作为原子条目。非 Git 项目使用有界物理树快照。
+
+- `git-selection-changed`：等待 Git 写入稳定后重试，不能授权为 partial scope。
+- `physical-selection-changed` 或 `physical-enumeration-limit`：等待文件系统稳定或缩小项目树后重试，不能授权为 partial scope。
+- scope 明细超出预算时，Runtime 用 `scope-detail-overflow` 的数量与内容 hash 汇总，而不是猜测遗漏路径。不要手改证据或把不完整快照视为完整。
+
+## 项目配置
+
+与 Agent 行为直接相关的配置：
+
+```yaml
+native:
+  artifact_root: docs
+  language: zh-CN
+  clarification_mode: sequential
+  archive_confirmation: automatic
+  max_verify_failures: 5
+```
+
+- `clarification_mode`：`sequential` 或 `batch`。
+- `archive_confirmation`：`automatic` 或 `required`。
+- `max_verify_failures`：同一份已确认 contract 允许提交的 Verify fail 总数。
+
+字段缺失时分别使用 `sequential`、`automatic` 和 `5`。配置改变不会让旧证据继续有效，也不会自动清除已有阻塞项。
+
+## Brief
+
+`brief.md` 使用以下一级标题：
+
+```text
+# Outcome
+# Scope
+# Non-goals
+# Acceptance examples
+# Constraints and invariants
+# Decisions
+# Open questions
+# Verification expectations
+```
+
+Outcome、Scope、Non-goals 和 Acceptance examples 必须有实质内容。
+
+Open questions 中的阻塞项使用固定格式：
+
+```text
+- [blocking] <Sequential 当前问题>
+- [blocking] Q1: <问题>
+- [blocking] CONFIRM: <最终共享理解>
+```
+
+未回答或不明确的问题继续保留。用户确认后，把决定写入 Decisions 和完整目标规格，再移除对应阻塞项。不要保存隐藏推理。
+
+## 完整目标规格
+
+规格写在：
+
+```text
+changes/<change-name>/specs/<capability>/spec.md
+```
+
+它描述归档后 capability 应有的完整行为，不是相对旧文本的增量 patch。
+
+- 新 capability：创建完整规格。
+- 已有 capability：写出替换后的完整规格。
+- 删除 capability：运行 `comet native spec remove`，不要只删除文件。
+
+Runtime 负责记录 create、replace、remove 和 canonical 基线。发生 canonical 冲突时，先重读并改写完整目标规格，再使用 `spec rebase`；不要手改 Runtime 状态或 hash。
+
+## Verification
+
+`verification.md` 使用以下非空一级标题：
+
+```text
+# Acceptance evidence
+# Commands and results
+# Skipped checks
+# Spec consistency
+# Known limitations and risks
+# Conclusion
+```
+
+记录真实命令、结果和可复核事实。未运行的检查放在 Skipped checks；失败结果不能写成 pass。
+
+## Acceptance evidence
+
+使用 Runtime 返回的 acceptance ID，不要自行计算。先准备条目数组，再运行：
+
+```text
+comet native evidence format [--entries <path>]
+```
+
+把命令输出原样放入 `# Acceptance evidence`。输入条目的基本形式：
+
+```json
+[
+  {
+    "acceptance_id": "acceptance-<sha256>",
+    "status": "passed",
+    "evidence_refs": ["runtime/evidence/receipts/<sha256>.json"]
+  },
+  {
+    "acceptance_id": "acceptance-<sha256>",
+    "status": "failed",
+    "evidence_refs": [],
+    "skipped_reason": "实际失败或未完成原因"
+  },
+  {
+    "acceptance_id": "acceptance-<sha256>",
+    "status": "waived",
+    "evidence_refs": [],
+    "waiver_ref": "runtime/evidence/waivers/<sha256>.json"
+  }
+]
+```
+
+- `passed` 引用当前有效的 typed receipt。
+- `failed` 说明真实失败或跳过原因。
+- `waived` 引用外部 signer 返回的 waiver。
+
+不要手工排版机器块，不要复用旧 change 的 evidence ref，也不要把失败、跳过或阻塞结果写成通过。

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

@@ -0,0 +1,54 @@
+# Native 澄清参考
+
+只在 Shape 存在尚未确定的用户可见行为时读取本文件。
+
+## 是否需要提问
+
+先区分三类信息：
+
+- **可调查事实**：仓库现状、工具能力、依赖默认值和运行环境。由 Agent 调查。
+- **用户决定**：不同选择会实质改变输出、默认行为、失败结果、范围或不可逆影响。由用户确认。
+- **实现选择**：不改变用户可见结果的算法、结构和工作方式。由 Agent 决定。
+
+只有歧义会实质改变用户可见结果，并且无法从用户要求、正式规格或适用契约中可靠确定时，才询问用户。不要为了覆盖清单制造问题，也不要把实现选择交给用户。
+
+把模糊行为改写为可比较的“输入 → 输出”或“触发 → 结果”。每个问题应包含：
+
+- 问题：需要决定的用户可见差异；
+- 推荐：首选项及理由；
+- 影响：各选项对结果的实际影响。
+
+## Sequential
+
+1. 调查当前问题依赖的事实。
+2. 找到前置条件已满足且最上游的一个未决问题。
+3. 在 brief 中保存一项 `- [blocking] <问题>`。
+4. 一次只提出这一道问题并等待回答。
+5. 用户回答后立即更新 Decisions、brief 和完整目标规格，再检查剩余问题。
+
+模糊、部分或未回答的内容继续保持 `[blocking]`。一个答案只决定它明确覆盖的行为。
+
+## Batch
+
+每轮只提出前置决定和环境事实已经确定、且答案彼此不依赖的问题：
+
+1. 在 brief 中保存 `- [blocking] Q1: <问题>`、`- [blocking] Q2: <问题>`。
+2. 一次提出本轮全部问题，并分别给出问题、推荐和影响。
+3. 用户回答后更新正式产物；未回答或不明确的问题继续保持 `[blocking]`。
+4. 根据新答案计算下一轮问题。
+
+不要把多个独立决定压缩成一道多选题，也不要把同一批问题拆成多轮。
+
+## 持久化与最终确认
+
+每次确认都立即写入现有 change 的 Decisions 和完整目标规格。不要只更新 brief，不要等到最终确认后再补规格，也不要为补充答案创建新 change。
+
+所有已识别问题解决后：
+
+1. 检查是否仍有静默假设；
+2. 向用户提供目标、范围、关键决定、验收标准和非目标摘要；
+3. 在 brief 中保存 `- [blocking] CONFIRM: <确认内容>`；
+4. 等待用户明确确认；
+5. 确认后移除阻塞项并使用 `--confirmed` 推进。
+
+用户最初提出需求不等于最终共享理解确认。用户补充或否定摘要时，更新正式产物并继续澄清。