@rpamis/comet 0.3.9 → 0.4.0-beta.10

package/eval/local/skills/benchmarks/040-beta/comet/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: comet
+description: "Use when 用户要启动或恢复 Comet 工作流，需要根据 active change、.comet.yaml、hotfix/tweak 意图路由到对应阶段 Skill。"
+---
+
+# Comet — OpenSpec + Superpowers 双星开发流程
+
+OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。
+
+```
+OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
+Superpowers 负责 HOW — 技术设计、计划、执行、收尾
+```
+
+**核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak 预设除外）。**
+
+<IMPORTANT>
+本文中的“调用 `/comet-*`”“调用 OpenSpec/Superpowers 技能”均指使用当前平台的 Skill 工具加载对应 Skill，并把必要上下文作为 ARGUMENTS 传入。不得把“调用”降级为在当前 `/comet` 上下文中手工执行子 Skill 的步骤，也不得只按记忆或本文摘要模拟子 Skill。
+
+当路由结果是 `/comet-hotfix`、`/comet-tweak`、`/comet-open`、`/comet-design`、`/comet-build`、`/comet-verify` 或 `/comet-archive` 时，必须立即用 Skill 工具加载对应的 Comet 子 Skill。该子 Skill 若要求 OpenSpec 或 Superpowers 技能，也必须继续用 Skill 工具加载对应依赖 Skill。Skill 工具调用是 workflow evidence 的一部分。
+</IMPORTANT>
+
+---
+
+## 决策核心（Decision Core）
+
+agent 做决策只需读本节，参考附录按需查阅。
+
+### 输出语言规则
+
+以触发本次工作流的用户请求语言作为默认输出语言。恢复已有 change 时，如果现有产物有明确主语言，除非用户明确要求切换，否则保持该语言。
+
+### 阶段自动检测
+
+**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
+
+**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` 深度设计/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 <描述>` | → **询问**：继续该变更 or 创建新变更 |
+| 多个 | `/comet <描述>` | → **询问**：继续现有变更 or 创建新变更；若选继续 → 列出清单让用户选择 |
+| 恰好 1 个 | `/comet`（无描述） | → 自动选中，进入 Step 1 |
+| 多个 | `/comet`（无描述） | → 列出清单让用户选择 |
+
+<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 已设置），自动清除并继续`，再运行 `node "$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` 的对应规则继续
+- 若 `phase: verify` 且 `verify_result: fail`，进入验证失败决策阻塞点：暂停并询问用户修复或接受偏差；用户选择修复后才运行 `node "$COMET_STATE" transition <name> verify-fail` 并调用 `/comet-build`
+- 若 `phase: open` 但 proposal/design/tasks 已完整，先运行 `node "$COMET_GUARD" <change-name> open --apply` 修正状态，再继续判定
+- 若 `phase: archive`，只允许调用 `/comet-archive`；`/comet-archive` 必须先等待归档前最终确认，归档成功后 change 会移动到 archive 目录，不再对原活跃目录运行 guard
+
+**Step 2: 阶段判定**（按顺序，命中即停）
+
+1. `archived: true` 或 change 已移入 archive → 流程已完成
+2. `verify_result: pass` 且 `archived` 不是 `true` → `/comet-archive`（先进行归档前最终确认）
+3. `verify_result: fail` → 进入验证失败决策阻塞点（暂停询问修复或接受偏差；用户选择修复后才 `verify-fail` 并 `/comet-build`）
+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`（使用 `node "$COMET_STATE" transition <name> preset-escalate` 合法回退到 design 阶段，补 Design Doc 和 Superpowers plan）
+
+详细判定规则见 `comet-hotfix` / `comet-tweak` 各自的「升级判定」章节。
+
+### 错误处理速查
+
+| 场景 | 处理方式 |
+|------|---------|
+| `openspec list --json` 失败 | 检查 openspec 是否已安装，提示 `openspec init` |
+| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
+| `.comet.yaml` 格式异常或缺失 | 以文件状态为准，用 `node "$COMET_STATE" set` 修正后继续 |
+| 构建/测试失败 | 返回 build 阶段修复，不进入 verify |
+| change 目录结构不完整 | 按 `comet-open` 产物要求补齐 |
+
+### 阶段衔接
+
+<IMPORTANT>
+单次 `/comet` 调用从检测到的阶段开始，退出条件满足后进入下一阶段。
+
+流转链：open → design → build → verify → archive
+
+**连续执行要求**：从检测到的阶段开始，agent 自动推进后续阶段。但**自动推进仅适用于没有用户决策的衔接点**。遇到用户决策点时，**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确回复**，不得用推荐规则、默认值或历史偏好代替用户确认，也不得仅输出文字提示后继续执行。
+
+**阶段推进与自动衔接的区分**：每个子 skill 退出前都会运行阶段守卫 `--apply` 推进 `.comet.yaml` 的 `phase` 字段——这一步**始终发生**，与 `auto_transition` 无关。之后子 skill 运行 `node "$COMET_STATE" next <name>` 解析下一步：`auto_transition` 不为 `false` 时输出 `NEXT: auto`（自动调用下一 skill），为 `false` 时输出 `NEXT: manual`（不调用下一 skill，提示用户手动运行）。因此 `auto_transition` **只控制是否自动调用下一个 skill，不影响 phase 推进**。无论 `auto_transition` 取何值，下方的用户决策点都必须阻塞等待。
+
+**决策点是阻塞点**：只要到达下列任一节点，当前 `/comet` 调用必须停住，并按 `comet/reference/decision-point.md` 的协议获取用户明确选择。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。
+
+需要用户参与的节点（仅在这些节点暂停）：
+1. open 阶段 proposal/design/tasks 审视确认
+2. brainstorming 确认设计方案
+3. build 阶段 plan-ready 暂停选择，以及随后选择工作方式（工作区隔离 + 执行方式 + TDD 模式 + 代码审查模式）
+4. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择）
+5. finishing-branch 选择分支处理方式
+6. archive 阶段执行归档脚本前的最终确认
+7. 遇到升级判定信号（hotfix/tweak → 用户二选一：继续预设流程 / 升级完整流程）
+8. build 阶段范围扩张需重新设计或拆分新 change
+9. open 阶段大型 PRD 需确认拆分为多个 change
+
+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
+  ↓ 自动检测
+/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` 查阅
+
+### 状态机硬约束
+
+- `build → verify` 前，`isolation` 必须是 `branch` 或 `worktree`
+- `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.mjs build --apply` 和 `comet-state.mjs transition <name> build-complete`
+
+### 脚本定位
+
+Comet 脚本随 skill 包分发在 `comet/scripts/` 下。**不硬编码路径** — 定位一次，缓存到环境变量。完整引导块、命令参考（`--apply`、`transition`、`next`、`archive`）和输出格式见 `comet/reference/scripts.md`。每会话运行一次该引导，后续全程复用 `$COMET_GUARD`、`$COMET_STATE`、`$COMET_HANDOFF`、`$COMET_ARCHIVE`、`$COMET_RUNTIME`。关键入口：
+
+```bash
+node "$COMET_GUARD" <change-name> <phase> --apply    # 阶段守卫 + 自动状态更新
+node "$COMET_STATE" transition <change-name> <event> # open-complete | design-complete | build-complete | verify-pass | verify-fail
+node "$COMET_STATE" next <change-name>               # NEXT: auto|manual|done  + SKILL: <skill-name>；auto_transition:false → manual，只暂停下一 skill 调用，不影响已发生的 phase 推进
+node "$COMET_ARCHIVE" <change-name>                  # 一键完成归档
+```
+
+### 文件结构
+
+按 `comet/reference/file-structure.md` 查阅完整目录结构。

package/eval/local/skills/benchmarks/040-beta/comet/reference/auto-transition.md

@@ -0,0 +1,27 @@
+# 自动衔接下一阶段协议
+
+规范路径：`comet/reference/auto-transition.md`
+
+本协议由所有 comet 子 skill 共享，定义阶段守卫推进后的自动衔接规则。
+
+## 术语区分
+
+「阶段守卫推进」由 guard `--apply` 完成，更新 `.comet.yaml` 的 `phase` 字段——这一步**始终发生**，与 `auto_transition` 无关。本协议的「自动衔接」只决定**是否自动调用下一个 skill**，由 `auto_transition` 控制。
+
+## 执行方式
+
+退出条件满足且阶段守卫推进 phase 后，运行：
+
+```bash
+node "$COMET_STATE" next <change-name>
+```
+
+脚本根据 `phase`、`workflow`、`auto_transition` 输出确定性的下一步：
+
+- `NEXT: auto` → 调用 `SKILL` 指向的 skill 进入下一阶段
+- `NEXT: manual` → 不要调用下一 skill，按 `HINT` 提示用户手动运行 `/<SKILL>`
+- `NEXT: done` → 流程已完成，无需继续
+
+## 预设路由
+
+`workflow: hotfix` 时，`phase: build` 返回 `comet-hotfix`；`workflow: tweak` 时返回 `comet-tweak`。其余 phase（`verify`、`archive`）按标准 Skill 名称返回（`comet-verify`、`comet-archive`），不受 workflow 类型影响。预设 Skill 内部的"连续执行模式"可能覆盖 `auto_transition` 行为——详见对应预设的 `<IMPORTANT>` 块。

package/eval/local/skills/benchmarks/040-beta/comet/reference/comet-yaml-fields.md

@@ -0,0 +1,73 @@
+# .comet.yaml 字段说明
+
+规范路径：`comet/reference/comet-yaml-fields.md`
+
+本文件是 `.comet.yaml` 状态文件的字段参考。按需查阅，不随 skill 一次性加载。
+
+## 示例
+
+```yaml
+workflow: full
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+base_ref: a1b2c3d4e5f6...
+build_mode: subagent-driven-development
+build_pause: null
+subagent_dispatch: confirmed
+tdd_mode: tdd
+review_mode: standard
+auto_transition: true
+isolation: branch
+verify_mode: light
+verify_result: pending
+verification_report: null
+branch_status: pending
+created_at: 2026-05-26
+verified_at: null
+archived: false
+```
+
+## 必需字段
+
+| 字段 | 含义 |
+|------|------|
+| `workflow` | `full`、`hotfix` 或 `tweak` |
+| `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive`（init 统一设为 `open`，guard 负责过渡） |
+| `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
+| `plan` | 关联的 Superpowers Plan 路径，可为空 |
+| `base_ref` | init 时记录的 git commit SHA，用于 scale 评估。无 plan 时作为改动文件数统计基准 |
+| `build_mode` | 已选择的执行方式，可为空。取值：`subagent-driven-development`（隔离后台 subagent 逐任务实现并审查）、`executing-plans`（主会话按计划顺序执行）、`direct`（主会话直接编码，默认仅 hotfix/tweak 允许，full workflow 需 `direct_override: true`） |
+| `build_pause` | build 阶段内部暂停点。`null` 表示无暂停，`plan-ready` 表示 plan 已生成，用户选择切换模型后暂停 |
+| `subagent_dispatch` | `null` 或 `confirmed`。仅当已确认当前平台存在真实后台 subagent / Task / multi-agent 调度能力时，`build_mode: subagent-driven-development` 才能写入并用于离开 build 阶段 |
+| `tdd_mode` | `tdd` 或 `direct`。full workflow 离开 build 阶段前必须已选择。`tdd` 强制每个任务先写失败测试再实现；`direct` 不强制 TDD。hotfix/tweak 默认 `direct` |
+| `review_mode` | `off`、`standard` 或 `thorough`。full workflow 离开 build 阶段前必须已选择；hotfix/tweak 默认 `off` |
+| `isolation` | `branch` 或 `worktree`，工作区隔离方式。full 初始化可为 `null`，但只允许持续到 `/comet-build` Step 3 前；hotfix/tweak 默认 `branch` |
+| `verify_mode` | `light` 或 `full`，可为空 |
+| `auto_transition` | `true` 或 `false`。只控制阶段守卫推进 phase 后是否自动调用下一个 skill；`false` 时由 `comet-state next` 输出 `manual`，暂停下一 skill 调用，但不阻止 phase 字段更新 |
+| `verify_result` | `pending`、`pass` 或 `fail` |
+| `verification_report` | 验证报告文件路径，verify 通过前必须指向已存在文件 |
+| `branch_status` | `pending` 或 `handled`，分支处理完成后设为 `handled` |
+| `created_at` | change 创建日期（init 时自动写入），格式 `YYYY-MM-DD` |
+| `verified_at` | 验证通过时间，可为空 |
+| `archived` | change 是否已归档 |
+
+## 可选字段
+
+| 字段 | 含义 |
+|------|------|
+| `direct_override` | `true`/`false`。full workflow 如需使用 `build_mode: direct`，必须显式设为 `true` |
+| `build_command` | 项目构建命令。guard 优先运行；支持命令词、引号、路径和 `&&` 顺序步骤；拒绝 `;`、管道、裸 `&`、`$` 和反引号 |
+| `verify_command` | 项目验证命令。verify guard 优先运行；使用与 `build_command` 相同的受限命令语法，未配置时回退到构建命令 |
+
+## 状态机硬约束
+
+- `build → verify` 前，`isolation` 必须是 `branch` 或 `worktree`
+- `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.mjs build --apply` 和 `comet-state.mjs transition <name> build-complete`
+- `preset-escalate` 事件：仅允许 `hotfix`/`tweak` workflow 在 `phase: build` 时调用，原子地把 `workflow`/`classic_profile` 置为 `full`、`phase` 回退到 `design`、清空 `design_doc`（满足 comet-design 入口要求）。这是预设升级到 full 的唯一合法通道——直接 `set phase design` 会被状态机硬拦截，`set classic_profile` 属于 machine-owned 字段不可手动设置

package/eval/local/skills/benchmarks/040-beta/comet/reference/context-recovery.md

@@ -0,0 +1,45 @@
+# 上下文压缩恢复协议
+
+规范路径：`comet/reference/context-recovery.md`
+
+本协议由所有可能触发上下文压缩的 comet 子 skill 共享。当 agent 怀疑发生上下文压缩（之前对话被摘要、找不到之前讨论的内容）时，按本协议恢复。
+
+## 任意入口恢复原则
+
+用户可能直接从 `/comet-open`、`/comet-design`、`/comet-build`、`/comet-verify`、`/comet-archive`、`/comet-hotfix` 或 `/comet-tweak` 回到流程。进入任意子 Skill 时，都先按 `comet/reference/scripts.md` 定位脚本，再用当前子 Skill 对应 phase 运行入口检查或恢复检查。不得依赖对话历史判断阶段。
+
+```bash
+node "$COMET_STATE" check <change-name> <phase> --recover
+```
+
+若检查结果显示实际 phase、workflow 或 evidence 应由其他 Skill 处理，按脚本输出和 `/comet` 路由规则切换；不要在错误阶段继续补写状态。若存在未提交改动，先按 `comet/reference/dirty-worktree.md` 归因。
+
+## 恢复步骤
+
+```bash
+node "$COMET_STATE" check <change-name> <phase> --recover
+```
+
+脚本输出结构化恢复上下文（phase、已完成字段、待完成字段、恢复动作）。按 **Recovery action** 决定下一步。
+
+## build 阶段特殊恢复
+
+若恢复脚本输出 `build_mode: subagent-driven-development`：
+
+1. 使用 Skill 工具重新加载 Superpowers `subagent-driven-development` 技能
+2. 重新阅读 `comet/reference/subagent-dispatch.md` 获取 Comet 专属扩展
+3. 读取 `openspec/changes/<name>/.comet/subagent-progress.md`，恢复当前 task 或 final review、实现提交、RED/GREEN 证据、已通过审查、未解决反馈和审查-修复轮次
+4. 禁止在主会话中直接执行 task
+5. 按检查点记录的精确阶段恢复；检查点缺失或不匹配时才从第一个未勾选 task 的 implementer 派发开始
+6. task 按 `review_mode` 完成验收并完成定向勾选验证后，立即继续下一个 task，不得总结或询问是否继续
+
+## design 阶段特殊恢复
+
+- 若用户尚未确认设计方案，回到 brainstorming 继续
+- 若用户已确认，继续创建 Design Doc
+- 恢复时重新加载 `brainstorm-summary.md` + handoff 上下文文件
+
+## verify/archive 阶段恢复
+
+- verify：脚本输出验证状态、分支状态和恢复动作
+- archive：若 `archived: true` 且归档目录存在，归档已完成，无需再次执行

package/eval/local/skills/benchmarks/040-beta/comet/reference/debug-gate.md

@@ -0,0 +1,33 @@
+# 异常调试协议
+
+规范路径：`comet/reference/debug-gate.md`
+
+本协议由 build、hotfix、tweak 等会直接修改代码的 comet 子 skill 共享。当运行程序、测试、构建或手动验证时出现崩溃、异常行为、测试失败或构建失败，必须进入异常调试协议。
+
+## 核心规则
+
+- 立即使用 Skill 工具加载 Superpowers `systematic-debugging` 技能
+- 在完成根因调查前，不得提出或实施源码修复
+
+## 四阶段流程
+
+1. 先复现并定位根因，读取完整错误、检查近期变更、追踪数据流
+2. 若根因指向源码 bug，先补充能复现该崩溃/异常的最小失败测试，再修改源码
+3. 修复后运行该失败测试、相关测试和项目构建/验证命令，确认全部通过
+4. 将测试、源码修复和 tasks.md 勾选保留在当前 change 内；不得通过另起一个“写测试用例”的 change 来替代当前 change 的验证闭环
+
+## 多失败并发调查
+
+进入四阶段流程前，先做一次失败独立性评估，决定串行还是并发调查：
+
+- **不并发（维持现有串行 `systematic-debugging`）**：失败 ≤ 2 个；失败之间相关（改一个可能修好其他）；共享状态；会改动同一批文件；尚未识别出失败是否独立
+- **并发（加载 Superpowers `dispatching-parallel-agents` 技能）**：≥ 3 个失败，且来自不同问题域（不同测试文件不同根因、不同子系统独立损坏），互不依赖、互不干扰
+
+当满足并发条件时：
+
+1. 立即使用 Skill 工具加载 Superpowers `dispatching-parallel-agents` 技能
+2. 按问题域为每个独立失败派发一个后台调查 agent，所有派发放在同一次回复里以并发执行；每个 agent 的 prompt 必须自包含（具体失败、错误信息、允许的调查范围、不得改动其他问题域的代码）
+3. 所有 agent 都受本协议“根因未明前不得动源码”的约束；它们只负责定位根因并返回调查结论，**不直接提交修复**
+4. 调查全部返回后，由主会话串行整合结论、串行执行修复，修复仍走当前 `review_mode` 的验证与评审闭环
+
+> 并发只用于**调查**阶段。修复始终串行，避免多个 agent 同时改同一批文件冲突——这与 `subagent-driven-development` “禁止并行派发多个实现 agent”的红线一致。

package/eval/local/skills/benchmarks/040-beta/comet/reference/decision-point.md

@@ -0,0 +1,31 @@
+# 用户决策点协议
+
+规范路径：`comet/reference/decision-point.md`
+
+本协议由所有包含用户决策点的 comet 子 skill 共享。凡标注为“阻塞点”或“用户决策点”的步骤，都必须按本协议处理。
+
+## 核心规则
+
+- 决策点是阻塞点。到达决策点时必须暂停，等待用户明确选择后才能继续
+- 必须使用当前平台可用的用户输入/确认机制获取选择；Claude Code 等平台提供 `AskUserQuestion` 时，优先使用 `AskUserQuestion` 展示单选/多选选项
+- 若当前工具列表没有 `AskUserQuestion`，或第一次调用 `AskUserQuestion` 失败，则判定本会话结构化提问不可用；本会话后续决策点不得反复重试 `AskUserQuestion`，直接使用文本选项降级模式
+- 若当前平台没有结构化提问工具，则必须在对话中提出明确选项并停止流程，等待用户回复
+- 不得用推荐规则、默认值、历史偏好或“用户应该会同意”的推断代替当前确认
+- 用户明确选择前，不得写入对应状态字段、执行对应分支操作或自动继续下一阶段
+
+## `AskUserQuestion` 优先策略
+
+使用结构化提问时：
+
+- 单选决策点用 `AskUserQuestion` 的单选问题；多选决策点用多选问题
+- 选项必须携带简短标签和影响说明；推荐项只能作为说明，不能自动选择
+- 若工具调用成功，等待用户通过该问题作答；不得同时再输出一套文本选项
+- 若工具不存在、工具调用失败或宿主报错，记录“本会话结构化提问不可用”，然后进入文本选项降级模式
+
+## 最低呈现要求
+
+- 说明当前决策点正在决定什么
+- 给出清晰可选项；需要用户单选时，选项必须互斥且可执行
+- 文本降级模式必须明确写出“单选”或“多选”、编号选项、每项影响，并要求用户回复编号；随后停止流程，等待用户回复
+- 如有推荐，只能作为说明，不能替代用户确认
+- 用户选择后，再执行对应命令或状态更新

package/eval/local/skills/benchmarks/040-beta/comet/reference/dirty-worktree.md

@@ -0,0 +1,59 @@
+# Dirty Worktree 协议
+
+规范路径：`comet/reference/dirty-worktree.md`
+
+本协议由所有涉及代码修改的 comet 子 skill 共享。当 agent 恢复上下文或继续执行时，必须按本协议处理未提交的工作区改动。各子 skill 可在本协议基础上定义阶段特例（如 verify 阶段对实现改动的特殊处理），详见对应子 skill 文件。本文件不重复阶段特例。
+
+## 1. 检查步骤
+
+继续或开始修改前，必须先运行以下命令：
+
+```bash
+git status --short
+git diff --stat
+git diff --cached --stat
+git ls-files --others --exclude-standard
+```
+
+必要时再查看 `git diff` / `git diff --cached` / 新建文件内容。
+
+## 2. 核心规则
+
+- 用户可能不会说明自己改了哪里。只要存在 dirty worktree（包括 Git 状态里显示为 `??` 的新建文件），就先假设改动可能来自用户或混合来源
+- **构建产物排除**：`??` 文件若匹配 `.gitignore` 中的模式（如 `node_modules/`、`dist/`、`__pycache__/`、`*.o`、`target/`、`build/` 等），自动跳过归因，不视为用户改动
+- dirty worktree 只代表代码事实，不会自动推进 `.comet.yaml` 的 `phase` 或勾选 `tasks.md`；只有完成归因、验证、同步必要文档，并通过对应阶段 guard 后，才允许推进 Comet 状态
+
+## 3. 归因分类
+
+将 dirty diff 分为三类：
+
+1. **属于当前 change**：文件和内容能对应当前 change 的目标、tasks.md、plan 或 delta spec。将其纳入当前任务继续，不重复改同一处
+2. **不属于当前 change**：文件或内容与当前目标无关。暂停并询问用户：并入当前 change、拆成新 change、保留不处理，或明确授权丢弃
+3. **来源不确定**：无法从 diff 和文档判断归属。暂停并向用户汇报文件列表和判断依据，不继续推进阶段
+
+## 4. 常见处理模式
+
+### 已实现但 tasks.md 未勾选
+
+先验证实现（运行构建和测试），通过后补勾任务。不要因为任务未勾选就重做一遍，也不要因为状态文件滞后而忽略代码事实。若当前子 skill 定义了阶段特例，以子 skill 为准。
+
+### 暗示计划或范围已变化
+
+按当前子 skill 的升级、增量更新或回退规则处理，本协议不重复阶段特例。
+
+### 模糊恢复意图
+
+用户说"继续""接着跑""我改了一点""刚才不满意""重新弄""代码动过""先按现在的来"等模糊恢复意图时，按本协议处理。不要要求用户先回忆具体改了哪里。
+
+### open/design 阶段出现代码改动
+
+若当前仍处于 `open` 或 `design`，但 dirty worktree 已经包含代码改动，先按本协议归因，不要直接推进阶段：
+
+- 属于当前 change 的改动：作为需求或设计输入记录到 proposal/design/spec/design doc/tasks 中；进入 build 前仍需完成对应阶段 guard
+- 不属于当前 change 或来源不确定：暂停询问用户是并入当前 change、拆成新 change、保留不处理，还是明确授权丢弃
+- 禁止在 open/design 阶段直接把代码改动当作已完成实现并推进到 verify
+
+## 5. 禁令
+
+- 禁止在未理解 dirty diff 来源时覆盖、回滚、格式化重写或忽略用户改动
+- 禁止在 dirty diff 未解释清楚时判定验证通过

package/eval/local/skills/benchmarks/040-beta/comet/reference/file-structure.md

@@ -0,0 +1,28 @@
+# 文件结构参考
+
+规范路径：`comet/reference/file-structure.md`
+
+本文件是 Comet 项目文件结构参考。按需查阅，不随 skill 一次性加载。
+
+```text
+openspec/                              # OpenSpec — WHAT
+├── config.yaml
+├── changes/
+│   ├── <name>/                        # 活跃 change
+│   │   ├── .openspec.yaml
+│   │   ├── .comet.yaml
+│   │   ├── proposal.md                # Why + What
+│   │   ├── design.md                  # 高层架构决策
+│   │   ├── specs/<capability>/spec.md # Delta 能力规格
+│   │   ├── .comet/handoff/            # 脚本生成的阶段交接包
+│   │   └── tasks.md                   # 任务清单
+│   └── archive/YYYY-MM-DD-<name>/     # 已归档
+└── specs/<capability>/spec.md         # 主 specs（归档时按 OpenSpec delta 语义合并）
+
+docs/superpowers/                      # Superpowers — HOW
+├── specs/YYYY-MM-DD-<topic>-design.md # 设计文档（技术 RFC，归档时标注状态）
+└── plans/YYYY-MM-DD-<feature>.md      # 实施计划（文件头含 change 关联元数据）
+
+.comet/
+└── config.yaml                        # Comet 项目配置（context_compression 默认 off，可设 beta）
+```

package/eval/local/skills/benchmarks/040-beta/comet/reference/intent-frame.md

@@ -0,0 +1,74 @@
+# CometIntentFrame 字段参考
+
+本文件只在需要解释字段含义时读取。正常 `/comet` 路由只需按主 Skill 的最小骨架填写；runtime 会补齐省略字段并输出最终 `route`。
+
+## 顶层字段
+
+| 字段 | 含义 |
+|------|------|
+| `schema_version` | frame 版本，当前固定为 `comet.intent.v1`。 |
+| `utterance` | 触发 `/comet` 的用户原话。 |
+| `intent` | 用户高层意图和置信度。低于 runtime 阈值时会路由到 `ask_user`。 |
+| `slots` | 从用户原话归一化出来的路由槽位。 |
+| `context` | 从仓库状态读取的上下文，不是用户原话抽取结果。 |
+| `evidence` | 支撑关键判断的证据。缺少关键 evidence 时 runtime 会倾向 `ask_user`。 |
+| `proposed_route` | Agent 提交的候选路由。最小输入只需 `name` 和 `confidence`，runtime 会复核并输出最终 `route`。 |
+
+## `intent`
+
+| 字段 | 含义 |
+|------|------|
+| `intent.name` | 用户高层意图：启动、恢复、修 bug、小改、提问或未知。 |
+| `intent.confidence` | Agent 对高层意图判断的置信度。它参与低置信度 fallback；`proposed_route.confidence` 不参与。 |
+
+## `slots`
+
+| 字段 | 含义 |
+|------|------|
+| `requested_action` | 用户想执行的动作，例如 `start`、`resume`、`continue`、`fix`、`modify`、`create`、`verify`、`archive`、`question`。 |
+| `workflow_candidate` | Agent 推断的候选流程：`full`、`hotfix`、`tweak` 或 `null`。这是推断值，runtime 会复核。 |
+| `user_explicit_workflow` | 用户是否明确指定流程。用户说“走 hotfix”时填 `hotfix`；没明确说时填 `null`。显式流程与风险信号冲突时仍会 `ask_user`。 |
+| `change_id` | 用户指定要恢复或操作的 active change 名。没有指定时填 `null`。 |
+| `existing_behavior` | 是否在修复已有行为或回归。`true` 且没有新增能力/API/schema/跨模块风险时倾向 `hotfix`。 |
+| `new_capability` | 是否新增能力。命中时通常倾向 `full`。 |
+| `public_api_change` | 是否改变用户可见接口或契约，例如 CLI 参数、配置字段、输出 JSON、Skill 对外流程。命中时通常倾向 `full`。 |
+| `schema_change` | 是否改变结构化数据格式，例如 `.comet.yaml`、`run-state.json`、eval manifest、bundle manifest、配置 schema。命中时通常倾向 `full`。 |
+| `cross_module_change` | 是否跨模块或跨 workflow 边界协作。命中时通常倾向 `full`。 |
+| `target_area` | 可选解释字段，表示用户提到的目标区域。最小骨架不需要填写。 |
+| `scope` | 可选解释字段，表示粗略范围大小。当前 scorer 不让它单独主导路由，最小骨架不需要填写。 |
+
+## `context`
+
+| 字段 | 含义 |
+|------|------|
+| `active_changes_count` | `openspec list --json` 得到的未归档 active change 数量。多个 active change 且用户未指定 `change_id` 时会 `ask_user`。 |
+| `active_change_names` | active change 名称列表。用户指定 `change_id` 时，runtime 用它检查 change 是否存在。 |
+| `dirty_worktree` | 可选状态字段。入口路由最小骨架不需要填写；dirty worktree 由 `comet/reference/dirty-worktree.md` 专门处理。 |
+
+## `evidence`
+
+每条 evidence 包含：
+
+| 字段 | 含义 |
+|------|------|
+| `field` | evidence 支撑的 frame 字段，例如 `intent.name` 或 `slots.workflow_candidate`。 |
+| `quote` | 来自用户原话、仓库状态或 `.comet.yaml` 的证据片段。 |
+| `source` | 证据来源：`user`、`repo` 或 `state`。 |
+
+## `proposed_route`
+
+| 字段 | 含义 |
+|------|------|
+| `name` | Agent 候选路由：`full`、`hotfix`、`tweak`、`resume`、`ask_user` 或 `out_of_scope`。 |
+| `confidence` | Agent 对候选路由的置信度，只用于诊断，不参与低置信度 fallback。 |
+| `next_skill` | 派生字段，runtime 会规范化；最小骨架不需要填写。 |
+| `requires_confirmation` | 派生字段，runtime 会规范化；最小骨架不需要填写。 |
+| `fallback_reason` | 派生字段，runtime 会规范化；最小骨架不需要填写。 |
+
+## 路由判断要点
+
+- 修复已有异常、回归、错误行为，且没有新增能力/API/schema/跨模块风险：倾向 `hotfix`。
+- 文案、配置、文档、prompt 或单一 OpenSpec change 的轻中量修改：倾向 `tweak`。
+- 新增能力、public API、schema 变更、跨模块协调或架构调整：倾向 `full`。
+- 多个 active change 且用户没指定 change：`ask_user`。
+- 低置信度、关键 evidence 缺失、显式流程与风险信号冲突：`ask_user`。