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

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

@@ -84,7 +84,7 @@ comet state set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 | 选项 | 行为 | 说明 |
 |------|------|------|
 | A | 继续执行并提交配置 | 在同一次回复中选择 Step 3 的隔离、执行、TDD 和审查配置；如选择 branch，同时提交分支名 |
-| B | 暂停切换模型 | 记录 `build_pause: plan-ready`，本次 `/comet-build` 停止，用户稍后可从 `/comet` 或 `/comet-build` 恢复 |
+| B | 暂停切换模型 | 记录 `build_pause: plan-ready`，本次 `/comet-build` 停止，用户稍后可从 `/comet-classic` 或 `/comet-build` 恢复 |
 
 这是用户决策点。**必须按 `comet/reference/decision-point.md` 的协议一次性展示计划摘要、暂停选项和 Step 3 全部可执行配置**。用户选择继续时，必须在同一回复中给出所有配置以及条件性的分支名；不得自动选择，也不得把暂停写入 `build_mode`。
 

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

@@ -0,0 +1,281 @@
+---
+name: comet-classic
+description: "用于用户明确调用 /comet-classic、要求启动或恢复永久 Comet Classic，或仓库中存在可无歧义恢复的 active Classic change；负责通过 intent runtime 和 .comet.yaml 路由阶段。"
+---
+
+# Comet Classic — OpenSpec + Superpowers 双星开发流程
+
+OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。
+
+```
+OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
+Superpowers 负责 HOW — 技术设计、计划、执行、收尾
+```
+
+**核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak 预设除外）。**
+
+---
+
+## 决策核心（Decision Core）
+
+agent 做决策只需读本节，参考附录按需查阅。
+
+### 输出语言规则
+
+所有 OpenSpec 和 Superpowers 产物都必须使用 Comet 配置的产物语言。配置值是规范化语言 ID，`en` 或 `zh-CN`。已有 change 优先通过 `comet state get <name> language` 读取 `openspec/changes/<name>/.comet.yaml` 中的 `language`；`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `classic.language`；都不存在时才回退到当前用户请求语言。调用外部 OpenSpec/Superpowers skill 时，必须把解析后的语言显式写入 prompt 或 ARGUMENTS。
+
+### 阶段自动检测
+
+**Step 0: 活跃 Change 发现与意图判定**
+
+1. 先按 `comet/reference/scripts.md` 完成脚本定位，确保 `$COMET_INTENT` 可用。
+2. 运行 `openspec list --json` 获取所有活跃 change。
+3. 根据用户请求、active change 列表和必要仓库状态填写 `CometIntentFrame`。
+4. 优先用 `node "$COMET_INTENT" route --stdin` 传入 frame JSON，获取 runtime 规范化路由。`CometIntentFrame + runtime scorer` 是事实源；本节自然语言规则只用于意图识别槽位提取。
+5. 按 runtime route 处理：
+   - `hotfix` → 直接调用 `/comet-hotfix`
+   - `tweak` → 直接调用 `/comet-tweak`
+   - `full` → 按活跃 change 表决定 `/comet-open` 或用户确认
+   - `resume` → 进入 Step 1 读取对应 change 的 `.comet.yaml`
+   - `ask_user` → 按 `comet/reference/decision-point.md` 暂停并等待用户选择
+   - `out_of_scope` → 说明本次输入不是 Comet workflow 启动/恢复请求，不初始化 change
+
+当 runtime route、Ambient Resume 或用户选择已经解析出明确 change 后，进入对应阶段 Skill 前必须先绑定当前执行上下文：
+
+```bash
+comet state select <change-name>
+```
+
+多个 active change 且用户尚未明确选择时，不得提前绑定；继续按 `ask_user` 决策点等待选择。
+
+### Comet Ambient Resume
+
+当用户未显式输入 `/comet-classic`，但当前仓库可能已有 active Comet change 时，开始处理需要改动或调查的任务前先运行只读探针：
+
+```bash
+node "$COMET_RESUME_PROBE" probe --stdin
+```
+
+探针只读仓库状态，不修改文件。按返回值处理：
+
+- `auto_resume`：输出一行 `[COMET] 检测到 active change <name>，按 <nextCommand> 恢复。`，然后进入 `nextCommand`。
+- `ask_user`：只问一个短问题并等待用户回复。
+- `out_of_scope` 或 `none`：不要进入 Comet workflow。
+
+原则：不把无关任务挂到 active Comet change，尤其不能只因为存在 `.comet.yaml` 就这样做。
+
+**CometIntentFrame 最小骨架**：
+
+```json
+{
+  "schema_version": "comet.intent.v1",
+  "utterance": "<用户原话>",
+  "intent": { "name": "start_change", "confidence": 0.8 },
+  "slots": {
+    "requested_action": "start",
+    "workflow_candidate": "full",
+    "user_explicit_workflow": null,
+    "change_id": null,
+    "existing_behavior": null,
+    "new_capability": null,
+    "public_api_change": null,
+    "schema_change": null,
+    "cross_module_change": null
+  },
+  "context": {
+    "active_changes_count": 0,
+    "active_change_names": []
+  },
+  "evidence": [],
+  "proposed_route": {
+    "name": "ask_user",
+    "confidence": 0.5
+  }
+}
+```
+
+**意图识别槽位提取**：
+字段完整含义见 `comet/reference/intent-frame.md`；正常路由只需按上方最小骨架填写。
+
+- `fix_bug` + `existing_behavior: true` + 无新增 capability/public API/schema/cross-module 信号 → 倾向 `hotfix`
+- 用户明确描述为可收敛为单一 OpenSpec change 的轻量/中等变更，需通过 OpenSpec apply 执行，且不需要完整 `/comet-classic` 深度设计/plan → 倾向 `tweak`
+- 文案、配置、文档、prompt 或单一 OpenSpec change 的轻中量修改 → 倾向 `tweak`
+- 新增 capability、public API、schema 变更、跨模块协调或架构调整 → 倾向 `full`
+- 多个 active change 且用户未明确 change → `ask_user`
+- 置信度不足、关键 evidence 缺失或用户显式 workflow 与风险信号冲突 → `ask_user`
+
+| 活跃 change | 用户输入 | 行为 |
+|-------------|---------|------|
+| 无 | `full` 路由 | → 调用 `/comet-open` |
+| 恰好 1 个 | `/comet-classic <描述>` | → **询问**：继续该变更 or 创建新变更 |
+| 多个 | `/comet-classic <描述>` | → **询问**：继续现有变更 or 创建新变更；若选继续 → 列出清单让用户选择 |
+| 恰好 1 个 | `/comet-classic`（无描述） | → 自动选中，进入 Step 1 |
+| 多个 | `/comet-classic`（无描述） | → 列出清单让用户选择 |
+
+<IMPORTANT>
+当用户选择「创建新变更」时，**必须调用 `/comet-open`**（禁止直接调用 `/opsx:new`）。
+`/comet-open` 负责完整双初始化：OpenSpec artifacts（由内部 `/opsx:new` 创建）+ `.comet.yaml` 状态文件。
+直接调用 `/opsx:new` 会缺失 `.comet.yaml`，导致后续阶段判定失败。
+</IMPORTANT>
+
+**Step 1: 读取 `.comet.yaml` 状态元数据**
+
+优先读取 `openspec/changes/<name>/.comet.yaml`。不存在时回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
+
+**断点恢复规则**：
+- 每次恢复上下文时，先重新执行 Step 0 和 Step 1，不依赖对话历史判断阶段
+- 只要存在 active change 且工作区有未提交改动，必须按 `comet/reference/dirty-worktree.md` 协议处理。该协议定义了检查步骤、归因分类和禁令，本文件不重复
+- 若 `phase: build`，先检查 `build_pause`、`plan`、`isolation`、`build_mode`、`tdd_mode` 和 `review_mode`（详见下方）：
+  - 若 `build_pause: plan-ready` 但 `isolation`、`build_mode`、`tdd_mode` 和 `review_mode` 都已经设置，则视为 stale pause：先输出 `[COMET] 检测到 stale pause（build_pause=plan-ready 但 isolation/build_mode/tdd_mode/review_mode 已设置），自动清除并继续`，再运行 `comet state set <name> build_pause null`，然后读取 tasks.md 的下一个未勾选任务并按 `build_mode` 恢复执行
+  - 若 `build_pause: plan-ready` 且 plan 文件存在，但 `isolation`、`build_mode`、`tdd_mode` 或 `review_mode` 尚未设置，回到 `/comet-build` 的 plan-ready 恢复点，提示用户继续补齐/确认工作区隔离、执行方式、TDD 模式和代码审查模式，不重新生成 plan
+  - 若 `build_pause: plan-ready` 但 plan 文件缺失，回到 `/comet-build` 处理状态损坏或重新生成 plan
+  - 若 `isolation`、`build_mode`、`tdd_mode` 或 `review_mode` 未设置，回到 `/comet-build` 对应步骤补充后再执行
+  - 若均已设置，读取 tasks.md 的下一个未勾选任务，并按 `build_mode` 恢复执行：
+    - 若 `build_mode: subagent-driven-development`，不得在主窗口直接执行任务；必须回到 `/comet-build` 的后台 subagent 调度规则，由主窗口只做协调
+    - 其他执行方式按 `/comet-build` 的对应规则继续
+- 若 `verify_result: fail`，读取 `verify_failures`：未超过 3 次时直接调用 `/comet-build` 继续已记录的修复循环，不重复询问；超过自动修复上限时回到 `/comet-verify` 的例外决策点。只有接受 WARNING/SUGGESTION 偏差或超限后的继续/停止策略需要用户选择
+- 若 `phase: open` 但 OpenSpec `applyRequires` 已完整，先运行 `comet guard <change-name> open --apply` 修正状态，再继续判定
+- 若 `phase: archive`，只允许调用 `/comet-archive`；归档前先等待最终确认，归档后精确提交归档改动，再处理分支并运行 archive guard
+
+**Step 2: 阶段判定**（按顺序，命中即停）
+
+1. `archived: true` 或 change 已移入 archive → 流程已完成
+2. `verify_result: pass` 且 `archived` 不是 `true` → `/comet-archive`（先进行归档前最终确认）
+3. `verify_result: fail` → 自动调用 `/comet-build` 继续修复；若 `verify_failures` 已超过自动修复上限，则进入 `/comet-verify` 的超限策略决策点
+4. `phase: verify` 或 tasks.md 全部勾选 → `/comet-verify`
+5. `phase: build` 或已有 Design Doc 但计划/执行未完成 → 优先按 workflow 路由：`hotfix` → `/comet-hotfix`，`tweak` → `/comet-tweak`，`full` → `/comet-build`
+6. `phase: design` 或有 change 但无 Design Doc → `/comet-design`
+7. `phase: open` 或有活跃 change 但 `.comet.yaml` 缺失 → `/comet-open`
+8. 无活跃 change → `/comet-open`
+
+如果元数据与文件状态冲突，以文件状态为准，修正 `.comet.yaml` 后继续。
+
+### 预设升级判定
+
+hotfix/tweak 的范围判定采用三层分工，避免「用纯文件数当硬性升级条件」误杀正常小改动：
+
+1. **质变信号**（agent 语义识别，命中任一即暂停交用户二选一）：跨模块协调修改、需要新增 capability、数据库 schema 变更、引入新的 public API、触及深层架构问题（各预设沿用这套核心信号，并可追加自身语境的特有信号，如 tweak 的「需要拆分为多个 OpenSpec changes」）
+2. **文件数 tripwire**（用户拍板，非自动升级）：改动文件数超提示阈值时，暂停交用户决定继续预设流程还是升级 full，不自动踢
+3. **验证级别**（scale 脚本判定）：`comet state scale` 仅决定 `verify_mode`（验证轻重），不卡流程、不触发升级
+
+**升级决策点（用户二选一）**：
+- 继续预设轻量流程（用户确认范围可控）
+- 升级为完整 `/comet-classic`（使用 `comet state transition <name> preset-escalate` 合法回退到 design 阶段，同时清除预设专属的 build 配置；补 Design Doc 后重新联合选择完整工作方式）
+
+详细判定规则见 `comet-hotfix` / `comet-tweak` 各自的「升级判定」章节。
+
+### 错误处理速查
+
+| 场景 | 处理方式 |
+|------|---------|
+| `openspec list --json` 失败 | 检查 openspec 是否已安装，提示 `openspec init` |
+| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
+| `.comet.yaml` 缺失 | 进入对应 preset 的 `/comet-open` 初始化状态，再运行 `comet state select`；不得跳过初始化 |
+| `.comet.yaml` 格式异常 | 停止并报告解析错误；从版本控制、备份或可验证产物人工修复，不能用 `comet state set` 覆盖损坏文件 |
+| 构建/测试失败 | 返回 build 阶段修复，不进入 verify |
+| change 目录结构不完整 | 按 `comet-open` 产物要求补齐 |
+
+### 阶段衔接
+
+<IMPORTANT>
+单次 `/comet-classic` 调用从检测到的阶段开始，退出条件满足后进入下一阶段。
+
+流转链：open → design → build → verify → archive
+
+**连续执行要求**：从检测到的阶段开始，agent 自动推进后续阶段。但**自动推进仅适用于没有用户决策的衔接点**。遇到用户决策点时，**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确回复**，不得用推荐规则、默认值或历史偏好代替用户确认，也不得仅输出文字提示后继续执行。
+
+**阶段推进与自动衔接的区分**：每个子 skill 退出前都会运行阶段守卫 `--apply` 推进 `.comet.yaml` 的 `phase` 字段——这一步**始终发生**，与 `auto_transition` 无关。之后子 skill 运行 `comet state next <name>` 解析下一步：`auto_transition` 不为 `false` 时输出 `NEXT: auto`（自动调用下一 skill），为 `false` 时输出 `NEXT: manual`（不调用下一 skill，按 `HINT` 交还控制权）。`NEXT: manual` 不是用户决策点，不得再询问“是否继续”。因此 `auto_transition` **只控制是否自动调用下一个 skill，不影响 phase 推进**。无论 `auto_transition` 取何值，下方真正的用户决策点都必须阻塞等待。
+
+**决策点是阻塞点**：只要到达下列任一节点，当前 `/comet-classic` 调用必须停住，并按 `comet/reference/decision-point.md` 的协议获取用户明确选择。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。
+
+需要用户参与的节点（仅在这些节点暂停）：
+1. workflow 目标选择：多个 active changes、继续现有 change/创建新 change、或批量拆分完成后选择先启动哪一个
+2. open 阶段 proposal/design/tasks 最终审视确认（同时确认 change 名称与范围；清晰请求不做前置摘要/命名确认）
+3. brainstorming 确认设计方案
+4. build 阶段一次性联合选择 plan-ready 暂停或完整工作方式（可用的工作区隔离 + 执行方式 + TDD 模式 + 代码审查模式；选择 branch 时同时确认分支名）
+5. verify 阶段接受 WARNING/SUGGESTION 偏差、处理 Spec 漂移，或第 4 次失败后选择继续修复/停止；前 3 次明确可修复失败自动闭环
+6. archive 阶段执行归档脚本前的最终确认
+7. 归档改动精确提交后选择 finishing-branch 分支处理方式
+8. 遇到升级判定信号（hotfix/tweak → 用户二选一：继续预设流程 / 升级完整流程）
+9. build 阶段范围扩张需重新设计或拆分新 change
+10. open 阶段大型 PRD 是否拆分为多个 changes
+
+agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。到达决策点时，**禁止跳过用户确认或自动选择——必须通过当前平台可用的用户输入/确认机制明确获取用户选择后才能继续**。
+
+**红旗清单** — 以下想法出现时立即停止并检查：
+
+| Agent 心理 | 实际风险 |
+|-----------|---------|
+| "用户应该会同意这个方案" | 不能替用户决策，必须等待用户明确选择 |
+| "这只是个小改动，不需要确认" | 决策点无大小之分，阻塞点必须等待 |
+| "用户之前选过 A，这次也选 A" | 历史偏好不能替代当前确认 |
+| "我已经解释了方案，用户没反对" | 没反对 ≠ 同意，必须用工具获取明确选择 |
+| "流程走到这里应该没问题了" | 验证不通过 ≠ 通过，检查 verify_result |
+</IMPORTANT>
+
+---
+
+## 子命令速查
+
+| 命令 | 阶段 | 归属 | 产物 |
+|------|------|------|------|
+| `/comet-open` | 1. 开启 | OpenSpec | proposal.md、design.md、tasks.md |
+| `/comet-design` | 2. 深度设计 | Superpowers | Design Doc、delta spec |
+| `/comet-build` | 3. 计划与构建 | Superpowers | 实施计划、代码提交 |
+| `/comet-verify` | 4. 验证 | Both | 验证报告 |
+| `/comet-archive` | 5. 归档与收尾 | OpenSpec | delta→main spec 同步、design doc 标注、归档提交、分支处理 |
+| `/comet-hotfix` | 预设路径 | Both | 快速修复（跳过 brainstorming） |
+| `/comet-tweak` | 预设路径 | Both | 串联 OpenSpec 的中等改动（delta spec 为一等公民，跳过 brainstorming 和完整 plan） |
+
+```
+/comet-classic
+  ↓ 自动检测
+/comet-open ──→ /comet-design ──→ /comet-build ──→ /comet-verify ──→ /comet-archive
+  (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)
+
+/comet-hotfix（预设路径，跳过 brainstorming）
+  open ──→ build ──→ verify ──→ archive
+    ↑ 命中升级判定信号 → 用户二选一（继续预设流程 / 升级 full）→ 升级则 transition preset-escalate → 补 Design Doc → 回到完整流程
+
+/comet-tweak（轻量预设路径，串联 OpenSpec，delta spec 为一等公民）
+  open ──→ build ──→ verify ──→ archive
+    ↑ 命中升级判定信号 → 用户二选一（继续预设流程 / 升级 full）→ 升级则 transition preset-escalate → 补 Design Doc → 回到完整流程
+```
+
+---
+
+## 参考附录（Reference Appendix）
+
+> 字段说明、文件结构和自动衔接协议已提取为渐进式加载参考文档，按需查阅：
+> - **`.comet.yaml` 完整字段表**：按 `comet/reference/comet-yaml-fields.md` 查阅（含必需字段、可选字段和完整示例）
+> - **文件结构**：按 `comet/reference/file-structure.md` 查阅
+> - **自动衔接协议**：按 `comet/reference/auto-transition.md` 查阅
+> - **上下文压缩恢复**：按 `comet/reference/context-recovery.md` 查阅
+> - **用户决策点协议**：按 `comet/reference/decision-point.md` 查阅
+> - **异常调试协议**：按 `comet/reference/debug-gate.md` 查阅
+
+### 状态机硬约束
+
+- full workflow 的 `build → verify` 前，`isolation` 必须是 `branch` 或 `worktree`；hotfix/tweak 可如实使用 `current`
+- `build → verify` 前，`build_mode` 必须已选择
+- `build_mode: subagent-driven-development` 必须同时有 `subagent_dispatch: confirmed`
+- full workflow 离开 build 阶段前 `tdd_mode` 必须已选择为 `tdd` 或 `direct`
+- full workflow 离开 build 阶段前 `review_mode` 必须已选择为 `off`、`standard` 或 `thorough`
+- `build_mode: direct` 默认只允许 `hotfix` / `tweak`；full workflow 需要 `direct_override: true`
+- `build_pause` 不是执行方式，不得写入 `build_mode`
+- 这些约束同时由 `comet guard <name> build --apply` 和 `comet state transition <name> build-complete` 执行
+
+### 脚本定位
+
+面向 workflow 的状态、守卫、handoff 和 archive 操作统一使用稳定 `comet` CLI；只有尚无公开子命令的 intent/resume probe 才按 `comet/reference/scripts.md` 定位内部 launcher。关键入口：
+
+```bash
+comet guard <change-name> <phase> --apply             # 阶段守卫 + 自动状态更新
+comet state transition <change-name> <event>          # open-complete | design-complete | build-complete | verify-pass | verify-fail
+comet state next <change-name>                        # NEXT: auto|manual|done + SKILL: <skill-name>
+comet archive <change-name>                           # 一键完成归档
+```
+
+### 文件结构
+
+按 `comet/reference/file-structure.md` 查阅完整目录结构。

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

@@ -44,7 +44,7 @@ openspec/changes/<name>/.comet/handoff/design-context.json
 openspec/changes/<name>/.comet/handoff/design-context.md
 ```
 
-启用 beta（项目 `.comet/config.yaml` 中 `context_compression: beta`，创建 change 时快照进入 `.comet.yaml`）时生成：
+启用 beta（项目 `.comet/config.yaml` 中 `classic.context_compression: beta`，创建 change 时快照进入 `.comet.yaml`）时生成：
 
 ```text
 openspec/changes/<name>/.comet/handoff/spec-context.json

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

@@ -12,7 +12,7 @@ description: "仅在用户明确调用 /comet-hotfix，或由 Comet 根 Skill/ru
 2. 不涉及接口变更或架构调整
 3. 改动范围可预估（文件数仅作提示，不作为硬性升级条件，见下方升级判定）
 
-**不适用**：如修复过程命中质变信号（见「升级判定」章节），由用户决定是否升级为完整 `/comet` 流程。
+**不适用**：如修复过程命中质变信号（见「升级判定」章节），由用户决定是否升级为完整 `/comet-classic` 流程。
 
 ---
 
@@ -20,7 +20,7 @@ description: "仅在用户明确调用 /comet-hotfix，或由 Comet 根 Skill/ru
 
 ### 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 → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后进入归档前最终确认。
 
@@ -152,7 +152,7 @@ comet guard <change-name> build --apply
 <IMPORTANT>
 Hotfix 流程默认 **一次性连续执行**。调用 `/comet-hotfix` 后，agent 在 hotfix 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界（build/verify/archive 之间）结束当前调用并按 `HINT` 交还控制权，由用户稍后手动运行下一阶段命令；这是手动衔接，不是新的确认点。无论 `auto_transition` 取何值，以下真正的用户决策仍需暂停：
 
-1. 遇到升级判定信号（见「升级判定」章节），**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确选择**：继续 hotfix 流程，还是升级为完整 `/comet` 流程
+1. 遇到升级判定信号（见「升级判定」章节），**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确选择**：继续 hotfix 流程，还是升级为完整 `/comet-classic` 流程
 2. 验证阶段（comet-verify）接受 WARNING/SUGGESTION 偏差、处理 Spec 漂移或超过自动修复上限后的策略决策；前 3 次明确可修复失败自动闭环
 3. 归档前最终确认，以及归档提交后的分支处理决策
 
@@ -167,7 +167,7 @@ Hotfix 流程默认 **一次性连续执行**。调用 `/comet-hotfix` 后，age
 
 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 **不得自行升级或自行判定可继续**。
 

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

@@ -0,0 +1,257 @@
+---
+name: comet-native
+description: 当用户明确调用 /comet-native、要求启动或恢复 Native change，或入口路由到 Native 时使用；负责澄清需求、读取状态并推动 Shape → Build → Verify → Archive。
+---
+
+# Comet Native
+
+Native 保存需求、完整目标规格、状态和证据。你负责理解、实现和验证；Runtime 负责状态、边界和恢复。
+
+整个流程在本 Skill 内完成。不要加载阶段 Skill，也不要强制套用 Plan、TDD、Debug 或 Review 方法。
+
+## 需求澄清协议
+
+从 `.comet/config.yaml` 读取 `native.clarification_mode`。允许值为 `sequential` 和 `batch`；字段缺失时使用 `sequential`。该配置只决定用户问题的组织方式，不改变 Native 的阶段、状态、Guard、安全确认或调用方停点。
+
+先识别会改变用户可见结果、但尚未定义的分支。“规范化”“直观”“标准”“预期”等词不是产品契约；只有用户原话、用户确认的答案，或明确适用于当前行为的公开契约可以关闭这类分支。
+
+仓库现状、依赖默认值、相邻功能和行业惯例只能支持推荐，不能代替用户决定。“保持现有行为”只约束已经存在的结果，不自动定义新行为。
+
+先判断分支是否只影响实现方式，而不改变任何用户可见结果。不能证明这一点时，按用户决定处理。即使用户要求“不要询问实现选择”，也不能把产品决定重新归类为实现选择。
+
+能从仓库、工具或运行环境查明的事实由你负责调查，不交给用户回答。宿主支持并行工作时，可以并行调查相互独立的事实，但不能把并行能力作为流程前提。尚未查清的事实只阻塞依赖它的问题，不阻塞其他已经具备条件的问题。
+
+只有共同定义同一个用户决定的多个细节才合并为一道策略问题。彼此独立的用户决定不能合并：Sequential 模式逐轮处理，Batch 模式为每项分别编号。不要为了增加问题数量制造歧义，也不要把实现选择放入用户问题清单。若一道问题仍未覆盖同一决定的某种合理解释，应拓宽这道问题，而不是另造一个依赖关系不清的问题。
+
+### 提问载体
+
+提问前先检查当前宿主的工具列表。当前工具列表提供 `AskUserQuestion` 时，Claude Code 下优先使用它展示结构化选项；其他宿主使用等价的用户输入工具。每个选项都要有简短标签和影响说明，推荐项在说明中标明，但不能自动代用户选中。
+
+- Sequential 模式每轮提交一道结构化问题。选项互斥时使用单选；只有同一个用户决定本身允许同时选择多个彼此兼容的选项时，才使用多选。不能用一道多选题压缩多个独立的用户决定。
+- Batch 模式在整组问题都能满足当前工具的问题数、选项数和字段限制时，把本轮整组问题放在同一次调用中。不能把同一轮拆成多次工具调用，让后面的问题在用户回答前无法同时展示。
+- 当前宿主没有结构化提问工具，或 Batch 整轮无法在一次调用中完整表达时，整轮使用编号文本降级模式。文本必须保留相同的问题、选项、推荐和影响，然后停止并等待用户回复编号。
+- 若第一次调用失败或宿主报错，判定本会话结构化提问不可用，当轮改用文本降级模式，本会话后续不再重试。工具调用成功后直接等待用户作答，不再同时输出一套重复的文本问题。
+
+### Sequential 模式
+
+发现用户决定后：
+
+1. 在 brief 中记录一个 `[blocking]` 问题。
+2. 一次只问最上游的一个问题。
+3. 给出“问题 / 推荐 / 影响”，然后结束本轮。
+
+没有用户决定时直接继续，不增加通用的最终确认。
+
+### Batch 模式
+
+把尚未确定的用户决定按前置关系组织起来。只需要维护可复核的未决事项、依赖摘要和正式产物，不保存隐藏推理或完整内部推演。
+
+每轮计算“本轮可回答问题集”：其中每个问题的前置决定都已确定，所需环境事实也已查清，并且答案不依赖本轮其他问题。依赖仍未确定决定或调查中事实的问题留到后续轮次。
+
+对本轮可回答问题集执行以下步骤：
+
+1. 在 brief 的 Open questions 中使用 `- [blocking] Q1: <问题>`、`- [blocking] Q2: <问题>` 的固定格式分别保存各题；不要使用 Markdown 有序列表代替该前缀。
+2. 一次提出整组问题，并为每题给出“问题 / 推荐 / 影响”。编号应允许用户用“1 按推荐，2 选择 B”这类方式回答。
+3. 更新正式产物并提出问题后结束本轮，不进入 Build，也不调用 `next`。
+
+使用以下格式：
+
+```text
+1. 问题：……
+   推荐：……
+   影响：……
+
+2. 问题：……
+   推荐：……
+   影响：……
+```
+
+用户回答后，把已确认内容写入 Decisions 和完整目标规格，移除对应 `[blocking]`；没有回答或回答不明确的问题继续保持 `[blocking]`，不得按推荐项自行补全。随后根据新答案重新计算本轮可回答问题集，逐轮处理新出现的分支。
+
+当本轮可回答问题集为空、相关事实已经查清且所有已识别用户决定均已处理时，执行一次完整性复核，重新检查是否仍有未处理或被静默假设的用户可见分支。向用户给出包含目标、范围、关键决定、验收标准和明确非目标的共享理解摘要，并在 brief 中使用 `- [blocking] CONFIRM: <确认内容>` 记录最终确认。用户明确确认前，不进入 Build，也不调用 `next`；用户补充或否定时，更新相应分支并继续下一轮。明确确认后，移除该阻塞项、记录确认，并按正常 transition 推进。
+
+以文本“规范化”为例，一个完整问题应同时说明大小写折叠、外围标点、内部标点或撇号保留，并用反例展示不同选择的输出。
+
+达成共享理解前，可以调查仓库事实、创建或恢复 Native change，并在 brief 中记录 `[blocking]`。不要进入 Build、修改项目实现或调用 `next`。
+
+用户回答后，更新原有 change 的 brief 和完整目标规格，再重新检查是否还有用户决定。不要为补充答案创建第二个 change，也不要把未确认选项写成既定规格。
+
+离开 Shape 时，只有本轮刚记录了用户对既有阻塞问题的确认，才给 `next` 传 `--confirmed`。Batch 模式的最终共享理解确认属于这类确认；用户最初提出需求不算。
+
+若调用方要求在该 transition 后停下或切换会话，严格执行以下序列：更新正式产物 → 调用一次允许的 transition → transition 成功后不再调用工具 → 输出约定标记并结束本轮。即使 Runtime 返回 `continuation.disposition: continue`，也不能越过这个停点。
+
+## 执行边界与状态快照
+
+调用方指定停点时，只完成停点前允许的工作。下一会话重新调用 `/comet-native`，从磁盘读取 status、selection 和正式产物后继续，不依赖聊天记忆恢复进度。
+
+调用方若要求保留某次状态变化前的 Runtime 返回快照，应在执行该状态变化之前，使用真实命令的机器可读模式，并通过重定向直接保存标准输出。快照确认完整后不得重建、刷新或覆盖；它只反映生成时的真实状态，不能根据最终结果补写。
+
+## 开始或恢复
+
+`/comet-native` 是 Skill 入口，不是 shell 命令。通过宿主的 Skill 机制调用；不要在 shell 中执行 `/comet-native`。
+
+先运行 Native `status` 和 `show`。恢复 Verify 或 Archive 时，运行 `status <change-name> --details`，读取有预算的验收页、详细 findings、`findingsTruncated` 和最新 checkpoint。
+
+- findings 被截断时，先处理已返回项，再重新读取 details。
+- `acceptancePage.nextCursor` 非空时，按命令参考继续分页。
+- 随后读取 `.comet/config.yaml`，确定 `native.clarification_mode`，再读取 `comet-state.yaml`、brief、拟议规格、canonical 规格、仓库实现、项目规则和相关测试。
+- 磁盘与仓库事实优先于聊天记忆；能从环境取得的事实不要询问用户。
+
+已有 active change 时，先只读确认哪个 change 对应当前目标。确认后显式运行：
+
+```text
+comet native select <change-name>
+```
+
+该命令建立项目级共享 selection。不要新增 `resume` 命令，也不要依赖 `status` 或 `show` 的读取副作用建立归属。
+
+存在多个 active change，且 selection 不能唯一确定目标时，让用户选择。只有磁盘事实证明没有 active change 时，才把目标归纳为 lowercase kebab-case 名称并创建：
+
+```text
+comet native new <change-name> --language zh-CN
+```
+
+只使用配置指定的 `<artifact-root>/comet/`，不扫描或修改其他工作流目录。
+
+命令与 Runtime 定位见[命令参考](reference/commands.md)，产物格式见[产物参考](reference/artifacts.md)，中断与恢复见[恢复参考](reference/recovery.md)。自带 Runtime 位于 [scripts/comet-native-runtime.mjs](scripts/comet-native-runtime.mjs)。
+
+项目只安装一份 Comet 工作流 Rule；支持 Hook 的平台只安装一个 `comet-hook-router.mjs`。Rule 与 Router 根据 `.comet/config.yaml` 和 `.comet/current-change.json` 确定当前 workflow，一次写入最多路由给一个 Guard。
+
+当前 change 属于 Native 时，只应用 Native 的 Shape、Build、Verify、Archive 边界。不要同时运行 Native 与 Classic Guard，也不要用默认 workflow 猜测当前 change 的归属。Native 主流程不依赖任何外部 Skill。
+
+## 决策协议
+
+维护一份未决事项清单，按依赖顺序处理仍没有唯一答案的用户可见分支。重点检查：
+
+- 输出与默认行为；
+- 边界条件与失败结果；
+- 范围、风险和不可逆操作；
+- 明确适用于当前行为的已有约束。
+
+把关键名词或动作改写成可区分解释的“输入 → 输出”或“触发 → 结果”示例。一个反例能区分两种合理解释，就说明仍需用户决定。
+
+文本或 token 行为通常要检查大小写、首尾与内部标点、空白、Unicode、空输入、重复项、顺序和并列结果。CLI 或 API 行为通常要检查默认值和错误结果。不要为了覆盖清单制造不存在的歧义。
+
+只有用户给出的信息、明确非目标、已确认决定，或当前能力的明确公开契约可以消除分支。发现阻塞后，按需求澄清协议为当前模式计算并提出一个问题或本轮可回答问题集；回答前不要调用 `next` 或修改项目实现。
+
+当未决事项清单为空，且仅凭 brief、完整目标规格、仓库事实和项目规则就能实现并验收，Sequential 模式直接继续；Batch 模式先完成最终共享理解确认。
+
+## 推进契约
+
+Shape、Build、Verify 的 transition 会返回 `next: auto | manual`，以及 `continuation.disposition: continue | await-user | blocked | done`、所需输入和下一动作。Archive 不通过 `next` 推进；成功归档才返回 `done`。
+
+这些字段组成机器可读的 continuation 契约。`next: auto` 只表示当前 transition 已成功，不代表宿主会在后台执行后续工作。
+
+收到 `next: auto` 且 disposition 为 `continue` 后，重新读取返回的 phase 和必要产物。没有用户决定或 Runtime 阻塞时，在本 Skill 内持续推进下一阶段，不等待用户再次触发。
+
+若 disposition 为 `await-user`、`blocked` 或 `next: manual`，先根据磁盘事实和 blocking findings 处理。只有缺少的输入确实属于用户决定时才提问。
+
+Batch 模式中尚未回答的问题和最终共享理解确认都保持为 `[blocking]`。它们是需要等待用户输入的正常停点，不改变 continuation 契约，也不能通过自动推进绕过。
+
+`workspace-root-changed` 与 `workspace-inspection-unavailable` 是只读提示，不单独阻止推进或归档。未知 workspace finding、确定冲突、失效证据和 repair stop 必须处理。
+
+长任务需要保留阶段内进度时，使用 `comet native checkpoint` 保存简短摘要、下一动作和真实产物引用。checkpoint 不推进 phase，也不替代 brief、规格或验证报告；不要另建 resume、handoff 或任务清单。
+
+## Shape
+
+确认并写入：Outcome、Scope、Non-goals、Acceptance examples、Constraints and invariants、Decisions、Open questions、Verification expectations。阻塞问题在 brief 中标记为 `- [blocking]`；Batch 模式可以同时保存本轮全部可回答问题。
+
+只有当 brief、完整目标规格、仓库事实和项目规则足以让后续执行者在不猜测用户可见行为的情况下实现并验收，Shape 才算完成。
+
+- 更新 `brief.md`，使其能够约束实现与验收。
+- 用户明确给出的 lowercase kebab-case capability ID 必须原样用于 `specs/<capability>/spec.md`。
+- 用户只给出显示名称时，在正文保留原名，并稳定派生 lowercase kebab-case capability ID。
+- 长期行为发生变化时，写归档后的完整目标规格，不写增量 patch。
+- 删除 capability 时运行 `comet native spec remove <change-name> <capability>`；operation 和 canonical base hash 由 Runtime 推断并冻结。
+- 仍有未决事项时保留 `[blocking]` 并停下。
+
+准备完成后运行：
+
+```text
+comet native next <change-name> --summary <摘要>
+```
+
+仅在本轮刚记录用户对既有阻塞问题的确认时追加 `--confirmed`；Batch 模式必须先取得最终共享理解确认。Runtime 会把 approval 绑定到当时的 brief/spec contract hash；若 Build 中 contract 发生变化，先取得用户对当前 contract 的确认，再按 status 返回的命令重试。不要手工编辑 `approval` 或 `approved_contract_hash`。
+
+## Build
+
+选择满足 brief 与拟议规格的最简单可靠方案。实现方式、是否保存计划、测试粒度、调试方法和审查强度由你根据风险决定。
+
+不要为流程制造额外文档。发现需求或规格漂移时，先更新 Native 产物；出现新的用户决定时标记 `[blocking]`，按当前配置的澄清协议处理。Batch 模式需要重新计算问题集，并在继续实现前取得更新后共享理解的最终确认。
+
+完成后提供真实项目产物；没有代码变化时给出明确理由。然后运行：
+
+```text
+comet native next <change-name> --summary <摘要> --artifact <项目内路径> [--confirmed]
+```
+
+没有代码变化时按命令参考使用 `--no-code-reason`。Runtime 会返回 implementation scope 和首个 `acceptancePage`；保存 Runtime 派生的验收 ID，并按 `nextCursor` 读取全部页面。不要自行计算 ID。
+
+Git 快照只包含 tracked 和未被 ignore 的 untracked 文件，submodule/gitlink 作为原子条目。非 Git 项目使用有界物理树快照。
+
+- `git-selection-changed`：等待 Git 写入稳定后重试，不能授权为 partial scope。
+- `git-enumeration-limit`：先缩小或清理项目所有范围；只有 Runtime 返回可授权 scope，且用户接受未枚举尾部的具体风险时，才能使用 partial 协议。
+- `physical-selection-changed` 或 `physical-enumeration-limit`：等待文件系统稳定或缩小项目树后重试，不能授权为 partial scope。
+
+Runtime 无法证明 scope 完整时会停在 Build，返回 partial scope hash 和未归属项。先补充真实 artifact 或消除未归属变化。确实只能接受 partial 时，说明具体缺口并取得用户确认，再使用同一个 hash：
+
+```text
+--allow-partial-scope <sha256> --partial-reason <理由> --confirmed
+```
+
+不要手改 snapshot、evidence 或猜测未枚举路径，也不要把 partial 写成 complete。
+
+## Verify
+
+根据 Acceptance examples、完整目标规格和风险运行验证。记录实际命令、结果、跳过项、规格一致性、已知限制和结论；未运行的检查不能写成通过。
+
+在 `verification.md` 的固定 acceptance evidence 块中逐项使用 Runtime 返回的 `acceptance_id`。每项只能记录项目相对 evidence refs，或记录诚实的 `skipped_reason`。格式见产物参考。
+
+需要一份可重建的文本卫生证据时，可运行内置只读检查：
+
+```text
+comet native check <change-name>
+```
+
+该命令只扫描当前 implementation scope/current snapshot 中有界的项目内普通文本文件，不调用 Git、shell、项目脚本、外部进程或外部 Skill。它不会修改项目文件、phase、Run 或 trajectory；结果写入内容寻址 receipt。它不替代按风险选择的项目测试。
+
+写完报告后运行：
+
+```text
+comet native next <change-name> --summary <摘要> --result pass|fail --report verification.md [--receipt <ref>]
+```
+
+fail 会回到 Build。修复后重新验证，并用 `--failure-category` 与 `--failed-check` 提交稳定、非敏感的失败事实。
+
+同一失败第二次出现会告警；第三次且 scope 没有进展会停止。scope 发生真实变化会结束当前 repair episode。scope 未变化但有明确新假设时，可按 status 返回的 signature 使用一次 `--override-repair`；同一 signature 不得重复 override。达到停止条件后请用户决定，不要弱化检查或伪造 pass。
+
+进入 Archive 后，brief、规格、implementation scope、报告或 receipt 发生变化会使证据失效。按 Runtime continuation 回到 Build，重新封印 scope 并验证；不要沿用失效的 pass。
+
+## Archive
+
+状态进入 Archive 且 Verify 为 pass 后，先预演：
+
+```text
+comet native archive <change-name> --dry-run
+```
+
+检查 create/replace/remove、证据新鲜度、当前 Native root 内的 change 重叠和恢复状态。没有阻塞时，用本次预演返回的精确 hash 提交：
+
+```text
+comet native archive <change-name> --expect-preflight <sha256>
+```
+
+调用方要求保存预演或提交 envelope 时，首次调用本身就使用机器可读模式并写入目标文件。提交使用已保存预演中的 hash；文件验证成功后保持不可变，不得在归档后重跑命令覆盖。
+
+Runtime 会在锁内重新计算事实，发生漂移就拒绝提交。成功后更新 canonical 规格，并把 change 移入日期前缀的 archive 目录。
+
+遇到 canonical 冲突时，重读并改写完整目标规格，再运行 `comet native spec rebase <change-name> --summary <摘要>`。该命令会受控回到 Build；随后重新实现、确认、验证和归档。未完成事务按恢复参考处理。
+
+## 不变规则
+
+- 不直接编辑 `phase`、`approval`、`spec_changes`、Run state、trajectory、锁或 transaction journal。
+- 不跳过阶段检查。Shape、Build、Verify 使用 `comet native next`；Archive 使用两步预演与提交。
+- 不调用外部 Skill。Native 主流程只依赖 Comet 自带 Runtime。
+- 不保存隐藏推理，只保存摘要、产物引用、命令结果、hash、状态变化和时间戳。
+- 不把 token、密码、私钥、连接串或其他凭据写入摘要、理由与报告。
+- 没有用户决定或 Runtime 阻塞时持续推进；有用户决定时，Sequential 模式只问一个最上游问题，Batch 模式询问本轮全部可回答问题，随后等待回答。