@rpamis/comet 0.3.9 → 0.4.0-beta.1

package/assets/skills/comet-verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comet-verify
-description: "Comet Phase 4: Verify and Close. Invoke with /comet-verify. Verify implementation matches design, handle development branch."
+description: "Use when a Comet change has completed build and needs implementation verification, verification-failure decisions, or branch closeout."
 ---
 
 # Comet Phase 4: Verify and Close (Verify)
@@ -14,20 +14,14 @@ description: "Comet Phase 4: Verify and Close. Invoke with /comet-verify. Verify
 
 ### 0a. Output Language Constraint
 
-Verification reports and branch-handling notes must use the language of the user request that triggered this workflow.
+Verification reports and branch-handling notes must use the configured Comet artifact language from `"$COMET_BASH" "$COMET_STATE" get <name> language`.
 
 ### 0b. Entry State Verification (Entry Check)
 
-Execute entry verification:
+Locate scripts via `comet/reference/scripts.md`, then run entry verification. When resuming from any entry point, first run the recovery check in `comet/reference/context-recovery.md`:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
-if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
-  return 1
-fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <change-name> verify
+node "$COMET_STATE" check <change-name> verify
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -39,10 +33,10 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 Execute scale assessment:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" scale <change-name>
+node "$COMET_STATE" scale <change-name>
 ```
 
-The script automatically counts tasks, delta spec count, changed file count, determines light or full verification mode, and sets the verify_mode field. Decision rule (any condition triggers full): tasks > 3, delta spec capabilities > 1, changed files > 4.
+The script automatically counts tasks, delta spec count, changed file count, determines light or full verification mode, and sets the verify_mode field. Decision rule (any condition triggers full): tasks > 3, delta spec capabilities > 1, changed files > 8.
 
 Before verification begins, handle uncommitted changes through `comet/reference/dirty-worktree.md` protocol. Verify phase special handling:
 
@@ -54,7 +48,7 @@ Only after user chooses fix, allow rollback to build phase:
 
 ```bash
 # Execute only after user confirms fix
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 Note: When verify-fail rolls back to build, `branch_status` is not reset. If branch handling was already completed during the first verify attempt, skip the branch handling step on re-verify and keep the existing `branch_status: handled`.
@@ -62,22 +56,22 @@ Note: When verify-fail rolls back to build, `branch_status` is not reset. If bra
 Note: If every task in build phase was committed, the script's file count based on working tree diff may underestimate change scale. In this case, must read plan file header `base-ref` and verify with commit range:
 
 ```bash
-PLAN=$("$COMET_BASH" "$COMET_STATE" get <change-name> plan)
+PLAN=$(node "$COMET_STATE" get <change-name> plan)
 BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
 git diff --stat "$BASE_REF"...HEAD
 ```
 
-If commit range shows changes exceed lightweight threshold (> 4 files, cross-module coordination, or delta spec spans more than 1 capability), manually set to full verification:
+If commit range shows changes exceed lightweight threshold (> 8 files, cross-module coordination, or delta spec spans more than 1 capability), manually set to full verification:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <change-name> verify_mode full
+node "$COMET_STATE" set <change-name> verify_mode full
 ```
 
-**Override mechanism**: If the agent or user believes the automated assessment is inappropriate, override at any time with `"$COMET_BASH" "$COMET_STATE" set <change-name> verify_mode <light|full>`.
+**Override mechanism**: If the agent or user believes the automated assessment is inappropriate, override at any time with `node "$COMET_STATE" set <change-name> verify_mode <light|full>`.
 
 ### 1b. Verification Failure Decision (Blocking Point)
 
-When verification does not pass, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to decide whether to fix or accept the deviation**. Must not automatically run `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`.
+When verification does not pass, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to decide whether to fix or accept the deviation**. Must not automatically run `node "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`.
 
 When pausing, must list:
 - Failed items
@@ -87,7 +81,7 @@ When pausing, must list:
 **Uncertainty principle**: When severity is unclear, downgrade (SUGGESTION > WARNING > CRITICAL). Only use CRITICAL for build failures, test failures, and security issues; ambiguous or uncertain issues should be WARNING or SUGGESTION.
 
 After user selection, continue as follows:
-- **Fix all**: Run `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build` to fix
+- **Fix all**: Run `node "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build` to fix
 - **Handle item by item**: CRITICAL or IMPORTANT failures must be fixed; WARNING/SUGGESTION failures may choose to accept deviation, but must record acceptance reason and impact scope in verification report. If any CRITICAL or IMPORTANT failure exists, skipping fix to accept all is not allowed
 
 **Retry limit**: After 3 consecutive verify-fail cycles, on the 4th failure the agent must not automatically choose to continue fixing; **must use the current platform's available user input/confirmation mechanism to pause** with only two options: "Accept all deviations and record" or "Continue fixing", for the user to explicitly decide.
@@ -97,8 +91,8 @@ After user selection, continue as follows:
 When verification needs to read OpenSpec artifacts, first check whether they have changed since the design phase:
 
 ```bash
-RECORDED_HASH=$("$COMET_BASH" "$COMET_STATE" get <change-name> handoff_hash)
-CURRENT_HASH=$("$COMET_BASH" "$COMET_HANDOFF" <change-name> --hash-only 2>/dev/null || echo "")
+RECORDED_HASH=$(node "$COMET_STATE" get <change-name> handoff_hash)
+CURRENT_HASH=$(node "$COMET_HANDOFF" <change-name> --hash-only 2>/dev/null || echo "")
 ```
 
 - If `RECORDED_HASH` = `CURRENT_HASH` and both are non-empty and neither is `null`: OpenSpec artifacts are unchanged. **tasks.md does not need to be re-read in full** (use `grep -c '\- \[ \]' tasks.md` to confirm completion count). proposal.md, design.md, and delta specs must still be read for comparison checks.
@@ -119,9 +113,11 @@ Run these 6 checks:
 3. Build passes (run project-specific build command, e.g., `npm run build`, `mvn compile`, `cargo build`, etc.)
 4. Related tests pass
 5. No obvious security issues (no hardcoded keys, no new unsafe operations)
-6. Lightweight code review passes: use the Skill tool to load the Superpowers `requesting-code-review` skill and request a lightweight review that checks only correctness, security, and edge cases
+6. Code review strategy: when `review_mode: standard` or `thorough`, use the Skill tool to load the Superpowers `requesting-code-review` skill and request a lightweight review that checks only correctness, security, and edge cases; when `review_mode: off`, skip automatic code review and record the skip reason in the verification report
 
-The lightweight code review input should be limited to this change's diff, tasks.md, and necessary test results; the review scope covers implementation correctness, security risk, and edge cases only, and does not perform spec coverage, Design Doc consistency, or drift checks. If the review finds CRITICAL or IMPORTANT issues, treat verification as failed and enter Step 1b.
+The lightweight code review input should be limited to this change's diff, tasks.md, and necessary test results; the review scope covers implementation correctness, security risk, and edge cases only, and does not perform spec coverage, Design Doc consistency, or drift checks. If the review finds CRITICAL or IMPORTANT issues, treat verification as failed and enter Step 1b. `review_mode: off` only skips automatic code review, not build, test, security checks, or debug gate protocol.
+
+**Dedup with build-phase review**: if the build phase (`executing-plans` or `subagent-driven-development`) already completed a final code review of the same diff under `review_mode`, this lightweight verify review focuses on "whether the implementation is correct against spec/tasks" and "changes added after build", and does not re-review the diff that build already reviewed and that has not changed.
 
 **Pass criteria**: All 6 items OK, no CRITICAL or IMPORTANT issues.
 
@@ -129,7 +125,7 @@ The lightweight code review input should be limited to this change's diff, tasks
 
 ```bash
 # Execute only after user confirms fix
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Report format**: Brief table listing 6 check results + PASS/FAIL.
@@ -159,13 +155,13 @@ When verification does not pass: report missing items, enter Step 1b verificatio
 
 ```bash
 # Execute only after user confirms fix
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Spec Drift Handling** (user decision point):
 - If check item 6 finds contradictions (delta spec has content but design doc does not reflect it), **must use the current platform's available user input/confirmation mechanism as a single-select question to pause and wait for the user to choose the handling method**; must not select automatically. Options:
   - Option A: Append "Implementation Divergence" section to design doc recording deviation reason. Option A is a verify phase allowed artifact; after writing, must not re-trigger Step 1b dirty-worktree decision due to that design doc change
-  - Option B: After user selects B, run `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`; `/comet-build`'s Spec Incremental Update rules will load the Superpowers `brainstorming` skill to update Design Doc + delta spec
+  - Option B: After user selects B, run `node "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`; `/comet-build`'s Spec Incremental Update rules will load the Superpowers `brainstorming` skill to update Design Doc + delta spec
   - Option C: Confirm deviation is acceptable, continue verification (design doc will be marked as `superseded-by-main-spec` during archiving)
 
 ### 3. Finishing (Superpowers)
@@ -195,8 +191,8 @@ mkdir -p docs/superpowers/reports
 # Write verification conclusions to report file, e.g.:
 # docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
 
-"$COMET_BASH" "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
-"$COMET_BASH" "$COMET_STATE" set <change-name> branch_status handled
+node "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+node "$COMET_STATE" set <change-name> branch_status handled
 ```
 
 ## Exit Conditions
@@ -205,22 +201,26 @@ mkdir -p docs/superpowers/reports
 - Branch handled
 - `verification_report` in `.comet.yaml` points to an existing verification report file
 - `branch_status: handled` in `.comet.yaml`
-- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`; after all PASS, auto-transitions to `phase: archive` through `comet-state transition verify-pass`
+- **Phase guard**: Run `node "$COMET_GUARD" <change-name> verify --apply`; after all PASS, auto-transitions to `phase: archive` through `comet-state transition verify-pass`
 
 After both verification and branch handling are complete, run guard for auto-transition:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply
+node "$COMET_GUARD" <change-name> verify --apply
 ```
 
 State file auto-updates to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
 
+## Context Compression Recovery
+
+Follow `comet/reference/context-recovery.md` with phase set to `verify`.
+
 ## Automatic Handoff to Next Phase
 
 Follow `comet/reference/auto-transition.md`. Key command:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" next <change-name>
+node "$COMET_STATE" next <change-name>
 ```
 
 - `NEXT: auto` → invoke the skill pointed to by `SKILL` to enter the next phase
@@ -228,7 +228,3 @@ Follow `comet/reference/auto-transition.md`. Key command:
 - `NEXT: done` → workflow is complete, no further action needed
 
 Note: after `comet-archive` starts, it must first execute the final archive confirmation blocking point and wait for the user to explicitly choose "Confirm archive" before running the archive script. Must not automatically archive just because verification passed.
-
-## Context Compression Recovery
-
-Follow `comet/reference/context-recovery.md` with phase set to `verify`.

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

@@ -1,6 +1,6 @@
 ---
 name: comet
-description: "Comet — OpenSpec + Superpowers 双星开发流程。用 /comet 启动，自动检测阶段并分发到子命令。五阶段：开启 → 深度设计 → 计划与构建 → 验证与收尾 → 归档。"
+description: "Use when 用户要启动或恢复 Comet 工作流，需要根据 active change、.comet.yaml、hotfix/tweak 意图路由到对应阶段 Skill。"
 ---
 
 # Comet — OpenSpec + Superpowers 双星开发流程
@@ -12,7 +12,7 @@ OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
 Superpowers 负责 HOW — 技术设计、计划、执行、收尾
 ```
 
-**核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak preset 除外）。**
+**核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak 预设除外）。**
 
 ---
 
@@ -22,23 +22,67 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 ### 输出语言规则
 
-以触发本次工作流的用户请求语言作为默认输出语言。恢复已有 change 时，如果现有产物有明确主语言，除非用户明确要求切换，否则保持该语言。
+所有 OpenSpec 和 Superpowers 产物都必须使用 Comet 配置的产物语言。配置值是规范化语言 ID，`en` 或 `zh-CN`。已有 change 优先通过 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取 `openspec/changes/<name>/.comet.yaml` 中的 `language`；`.comet.yaml` 尚不存在时读取 `.comet/config.yaml` 的 `language`；两者都不存在时才回退到当前用户请求语言。调用外部 OpenSpec/Superpowers skill 时，必须把解析后的语言显式写入 prompt 或 ARGUMENTS。
 
 ### 阶段自动检测
 
 **Step 0: 活跃 Change 发现与意图判定**
 
-1. 先做 Preset 检测；命中 hotfix/tweak 时直接调用对应 preset skill，不进入普通 open 分支
-2. 未命中 preset 时，运行 `openspec list --json` 获取所有活跃 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`；正常路由只需按上方最小骨架填写。
 
-**Preset 检测优先级最高**：
-- 用户明确描述为 bug fix / 热修复 + 满足 hotfix 条件 → 直接 `/comet-hotfix`
-- 用户明确描述为文案/配置/文档/prompt 小调整 + 满足 tweak 条件 → 直接 `/comet-tweak`
-- 未命中 preset → 按下表处理
+- `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 | 用户输入 | 行为 |
 |-------------|---------|------|
-| 无 | 非 preset 输入 | → 调用 `/comet-open` |
+| 无 | `full` 路由 | → 调用 `/comet-open` |
 | 恰好 1 个 | `/comet <描述>` | → **询问**：继续该变更 or 创建新变更 |
 | 多个 | `/comet <描述>` | → **询问**：继续现有变更 or 创建新变更；若选继续 → 列出清单让用户选择 |
 | 恰好 1 个 | `/comet`（无描述） | → 自动选中，进入 Step 1 |
@@ -57,16 +101,16 @@ agent 做决策只需读本节，参考附录按需查阅。
 **断点恢复规则**：
 - 每次恢复上下文时，先重新执行 Step 0 和 Step 1，不依赖对话历史判断阶段
 - 只要存在 active change 且工作区有未提交改动，必须按 `comet/reference/dirty-worktree.md` 协议处理。该协议定义了检查步骤、归因分类和禁令，本文件不重复
-- 若 `phase: build`，先检查 `build_pause`、`plan`、`build_mode` 和 `isolation`（详见下方）：
-  - 若 `build_pause: plan-ready` 但 `isolation` 和 `build_mode` 已经设置，则视为 stale pause：先输出 `[COMET] 检测到 stale pause（build_pause=plan-ready 但 isolation/build_mode 已设置），自动清除并继续`，再运行 `"$COMET_BASH" "$COMET_STATE" set <name> build_pause null`，然后读取 tasks.md 的下一个未勾选任务并按 `build_mode` 恢复执行
-  - 若 `build_pause: plan-ready` 且 plan 文件存在，但 `isolation` 或 `build_mode` 尚未设置，回到 `/comet-build` 的 plan-ready 恢复点，提示用户继续选择隔离方式和执行方式，不重新生成 plan
+- 若 `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
-  - 若 `build_mode`、`isolation` 或 `tdd_mode` 未设置，回到 `/comet-build` 对应步骤补充后再执行
+  - 若 `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`，进入验证失败决策阻塞点：暂停并询问用户修复或接受偏差；用户选择修复后才运行 `"$COMET_BASH" "$COMET_STATE" transition <name> verify-fail` 并调用 `/comet-build`
-- 若 `phase: open` 但 proposal/design/tasks 已完整，先运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply` 修正状态，再继续判定
+- 若 `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: 阶段判定**（按顺序，命中即停）
@@ -82,22 +126,19 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 如果元数据与文件状态冲突，以文件状态为准，修正 `.comet.yaml` 后继续。
 
-### 预设升级条件
+### 预设升级判定
+
+hotfix/tweak 的范围判定采用三层分工，避免「用纯文件数当硬性升级条件」误杀正常小改动：
 
-**hotfix → full**（满足任一即升级）：
-- 改动涉及 **3+ 文件**
-- 涉及架构变更（新模块、新接口、新依赖）
-- 涉及数据库 schema 变更
-- 修复引入新的 public API
-- 修复范围超出单一函数/模块
+1. **质变信号**（agent 语义识别，命中任一即暂停交用户二选一）：跨模块协调修改、需要新增 capability、数据库 schema 变更、引入新的 public API、触及深层架构问题（各预设沿用这套核心信号，并可追加自身语境的特有信号，如 tweak 的「需要拆分为多个 OpenSpec changes」）
+2. **文件数 tripwire**（用户拍板，非自动升级）：改动文件数超提示阈值时，暂停交用户决定继续预设流程还是升级 full，不自动踢
+3. **验证级别**（scale 脚本判定）：`comet-state scale` 仅决定 `verify_mode`（验证轻重），不卡流程、不触发升级
 
-**tweak → full**（满足任一即升级）：
-- 改动涉及 **5+ 文件**
-- 涉及多个模块的协调修改
-- 需要新增测试用例 **5+**
-- 涉及配置项的新增或删除（非值修改）
-- 需要新增 capability
-- 需要 delta spec（影响了已有规格）
+**升级决策点（用户二选一）**：
+- 继续预设轻量流程（用户确认范围可控）
+- 升级为完整 `/comet`（使用 `node "$COMET_STATE" transition <name> preset-escalate` 合法回退到 design 阶段，补 Design Doc 和 Superpowers plan）
+
+详细判定规则见 `comet-hotfix` / `comet-tweak` 各自的「升级判定」章节。
 
 ### 错误处理速查
 
@@ -105,7 +146,7 @@ agent 做决策只需读本节，参考附录按需查阅。
 |------|---------|
 | `openspec list --json` 失败 | 检查 openspec 是否已安装，提示 `openspec init` |
 | 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
-| `.comet.yaml` 格式异常或缺失 | 以文件状态为准，用 `"$COMET_BASH" "$COMET_STATE" set` 修正后继续 |
+| `.comet.yaml` 格式异常或缺失 | 以文件状态为准，用 `node "$COMET_STATE" set` 修正后继续 |
 | 构建/测试失败 | 返回 build 阶段修复，不进入 verify |
 | change 目录结构不完整 | 按 `comet-open` 产物要求补齐 |
 
@@ -118,18 +159,18 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 **连续执行要求**：从检测到的阶段开始，agent 自动推进后续阶段。但**自动推进仅适用于没有用户决策的衔接点**。遇到用户决策点时，**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确回复**，不得用推荐规则、默认值或历史偏好代替用户确认，也不得仅输出文字提示后继续执行。
 
-**阶段推进与自动衔接的区分**：每个子 skill 退出前都会运行阶段守卫 `--apply` 推进 `.comet.yaml` 的 `phase` 字段——这一步**始终发生**，与 `auto_transition` 无关。之后子 skill 运行 `"$COMET_BASH" "$COMET_STATE" next <name>` 解析下一步：`auto_transition` 不为 `false` 时输出 `NEXT: auto`（自动调用下一 skill），为 `false` 时输出 `NEXT: manual`（不调用下一 skill，提示用户手动运行）。因此 `auto_transition` **只控制是否自动调用下一个 skill，不影响 phase 推进**。无论 `auto_transition` 取何值，下方的用户决策点都必须阻塞等待。
+**阶段推进与自动衔接的区分**：每个子 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 暂停选择，以及随后选择工作方式（隔离方式 + 执行方式）
+3. build 阶段 plan-ready 暂停选择，以及随后选择工作方式（工作区隔离 + 执行方式 + TDD 模式 + 代码审查模式）
 4. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择）
 5. finishing-branch 选择分支处理方式
 6. archive 阶段执行归档脚本前的最终确认
-7. 遇到升级条件（hotfix/tweak → 完整流程）
+7. 遇到升级判定信号（hotfix/tweak → 用户二选一：继续预设流程 / 升级完整流程）
 8. build 阶段范围扩张需重新设计或拆分新 change
 9. open 阶段大型 PRD 需确认拆分为多个 change
 
@@ -158,7 +199,7 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须
 | `/comet-verify` | 4. 验证与收尾 | Both | 验证报告、分支处理 |
 | `/comet-archive` | 5. 归档 | OpenSpec | delta→main spec 同步、design doc 标注、归档 |
 | `/comet-hotfix` | 预设路径 | Both | 快速修复（跳过 brainstorming） |
-| `/comet-tweak` | 预设路径 | Both | 小改动（跳过 brainstorming 和完整 plan） |
+| `/comet-tweak` | 预设路径 | Both | 串联 OpenSpec 的中等改动（delta spec 为一等公民，跳过 brainstorming 和完整 plan） |
 
 ```
 /comet
@@ -168,11 +209,11 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须
 
 /comet-hotfix（预设路径，跳过 brainstorming）
   open ──→ build ──→ verify ──→ archive
-    ↑ 如触发升级条件 → 阻塞确认升级 → 补充 Design Doc → 回到完整流程
+    ↑ 命中升级判定信号 → 用户二选一（继续预设流程 / 升级 full）→ 升级则 transition preset-escalate → 补 Design Doc → 回到完整流程
 
-/comet-tweak（预设路径，跳过 brainstorming 和完整 plan）
-  open ──→ lightweight build ──→ light verify ──→ archive
-    ↑ 如触发升级条件 → 阻塞确认升级 → 补充 Design Doc → 回到完整流程
+/comet-tweak（轻量预设路径，串联 OpenSpec，delta spec 为一等公民）
+  open ──→ build ──→ verify ──→ archive
+    ↑ 命中升级判定信号 → 用户二选一（继续预设流程 / 升级 full）→ 升级则 transition preset-escalate → 补 Design Doc → 回到完整流程
 ```
 
 ---
@@ -193,77 +234,22 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须
 - `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.sh build --apply` 和 `comet-state.sh transition <name> build-complete`
+- 这些约束同时存在于 `comet-guard.mjs build --apply` 和 `comet-state.mjs transition <name> build-complete`
 
 ### 脚本定位
 
-Comet 脚本随 skill 包分发在 `comet/scripts/` 下。**不硬编码路径** — 定位一次，缓存到环境变量。此块为标准样板，在每个子 skill 中独立重复以确保可独立加载；修改时必须保持所有文件同步（样板版本: `v2`，变更时更新此版本号便于定位需要同步的文件）：
-
-```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
-if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
-  return 1
-fi
-. "$COMET_ENV"
-
-# 脚本定位失败时停止流程
-if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_HANDOFF" ] || [ -z "$COMET_ARCHIVE" ]; then
-  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
-  echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
-  return 1
-fi
-```
-
-**自动状态更新**：guard 支持 `--apply` 参数，验证通过后自动更新 `.comet.yaml` 状态字段：
-
-```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> <phase> --apply
-```
-
-`--apply` 内部委托给 `comet-state transition`。需要直接表达状态事件时使用：
-
-```bash
-"$COMET_BASH" "$COMET_STATE" transition <change-name> open-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> design-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> build-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-pass
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
-"$COMET_BASH" "$COMET_STATE" transition <archive-name> archived
-```
-
-**解析下一步**：阶段守卫推进 phase 后，用 `next` 子命令解析是否自动调用下一个 skill：
-
-```bash
-"$COMET_BASH" "$COMET_STATE" next <change-name>
-```
-
-输出 `NEXT: auto|manual|done` + `SKILL: <skill-name>`（`done` 时省略）+ `HINT`（仅 `manual` 时）。`auto_transition: false` 时输出 `manual`，只暂停下一 skill 调用，不影响已发生的 phase 推进。
-
-**归档脚本**：一键完成归档全部步骤：
+Comet 脚本随 skill 包分发在 `comet/scripts/` 下。**不硬编码路径** — 定位一次，缓存到环境变量。完整引导块、命令参考（`--apply`、`transition`、`next`、`archive`）和输出格式见 `comet/reference/scripts.md`。每会话运行一次该引导，后续全程复用 `$COMET_GUARD`、`$COMET_STATE`、`$COMET_HANDOFF`、`$COMET_ARCHIVE`、`$COMET_RUNTIME`。关键入口：
 
 ```bash
-"$COMET_BASH" "$COMET_ARCHIVE" <change-name>
+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 后，agent 应执行以上变量赋值一次，后续全程复用 `$COMET_GUARD`、`$COMET_STATE`、`$COMET_HANDOFF`、`$COMET_ARCHIVE`。
-
 ### 文件结构
 
 按 `comet/reference/file-structure.md` 查阅完整目录结构。
-
-### 最佳实践
-
-1. **brainstorming 不可跳过** — 每次变更必须经过深度设计（hotfix 和 tweak 除外）
-2. **delta spec 是活文档** — 阶段 3 期间可自由修改，归档时同步
-3. **交接包由脚本生成** — OpenSpec → Superpowers 的上下文必须通过 `comet-handoff.sh` 生成 compact 可追溯摘录（需要全文时用 `--full`），并由 guard 校验 source/hash/mode
-4. **保持 tasks.md 同步** — 完成一个勾一个
-5. **频繁提交** — 每个任务一次提交，message 体现设计意图
-6. **先验证再确认归档** — `/comet-verify` 通过后进入 `/comet-archive`，但运行归档脚本前必须等待用户最终确认
-7. **增量更新分级** — 小编辑、中重 brainstorming、大新 change
-8. **Plan 必须关联 change** — 文件头包含 `change:` 和 `design-doc:` 元数据
-9. **归档闭环** — design doc 和 plan 必须标注 `archived-with` 状态
-10. **修改已有功能** — 直接 open 新 change 即可
-11. **Preset 有上限** — hotfix/tweak 满足升级条件时及时切换到完整流程

package/assets/skills-zh/comet/reference/auto-transition.md

@@ -13,7 +13,7 @@
 退出条件满足且阶段守卫推进 phase 后，运行：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" next <change-name>
+node "$COMET_STATE" next <change-name>
 ```
 
 脚本根据 `phase`、`workflow`、`auto_transition` 输出确定性的下一步：
@@ -22,6 +22,6 @@
 - `NEXT: manual` → 不要调用下一 skill，按 `HINT` 提示用户手动运行 `/<SKILL>`
 - `NEXT: done` → 流程已完成，无需继续
 
-## preset 路由
+## 预设路由
 
-`workflow: hotfix` 时，`phase: build` 返回 `comet-hotfix`；`workflow: tweak` 时返回 `comet-tweak`。其余 phase（`verify`、`archive`）按标准 skill 名称返回（`comet-verify`、`comet-archive`），不受 workflow 类型影响。preset skill 内部的"连续执行模式"可能覆盖 `auto_transition` 行为——详见对应 preset 的 `<IMPORTANT>` 块。
+`workflow: hotfix` 时，`phase: build` 返回 `comet-hotfix`；`workflow: tweak` 时返回 `comet-tweak`。其余 phase（`verify`、`archive`）按标准 Skill 名称返回（`comet-verify`、`comet-archive`），不受 workflow 类型影响。预设 Skill 内部的"连续执行模式"可能覆盖 `auto_transition` 行为——详见对应预设的 `<IMPORTANT>` 块。

package/assets/skills-zh/comet/reference/comet-yaml-fields.md

@@ -8,6 +8,7 @@
 
 ```yaml
 workflow: full
+language: zh-CN
 phase: build
 design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
@@ -17,6 +18,7 @@ build_pause: null
 subagent_dispatch: confirmed
 tdd_mode: tdd
 review_mode: standard
+auto_transition: true
 isolation: branch
 verify_mode: light
 verify_result: pending
@@ -32,11 +34,12 @@ archived: false
 | 字段 | 含义 |
 |------|------|
 | `workflow` | `full`、`hotfix` 或 `tweak` |
+| `language` | 产物语言，仅支持 `en` 或 `zh-CN`。由 `comet init` 的初始化语言写入 `.comet/config.yaml`，创建 change 时快照到 `.comet.yaml`，用于约束 OpenSpec / Superpowers 产物主语言 |
 | `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` | 已选择的执行方式，可为空 |
+| `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` |
@@ -56,8 +59,8 @@ archived: false
 | 字段 | 含义 |
 |------|------|
 | `direct_override` | `true`/`false`。full workflow 如需使用 `build_mode: direct`，必须显式设为 `true` |
-| `build_command` | 项目构建命令。guard 优先运行该命令，失败时打印命令输出 |
-| `verify_command` | 项目验证命令。verify guard 优先运行该命令，未配置时回退到构建命令 |
+| `build_command` | 项目构建命令。guard 优先运行；支持命令词、引号、路径和 `&&` 顺序步骤；拒绝 `;`、管道、裸 `&`、`$` 和反引号 |
+| `verify_command` | 项目验证命令。verify guard 优先运行；使用与 `build_command` 相同的受限命令语法，未配置时回退到构建命令 |
 
 ## 状态机硬约束
 
@@ -68,4 +71,5 @@ archived: false
 - full workflow 离开 build 阶段前 `review_mode` 必须已选择为 `off`、`standard` 或 `thorough`
 - `build_mode: direct` 默认只允许 `hotfix` / `tweak`；full workflow 需要 `direct_override: true`
 - `build_pause` 不是执行方式，不得写入 `build_mode`
-- 这些约束同时存在于 `comet-guard.sh build --apply` 和 `comet-state.sh transition <name> build-complete`
+- 这些约束同时存在于 `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/assets/skills-zh/comet/reference/context-recovery.md

@@ -4,10 +4,20 @@
 
 本协议由所有可能触发上下文压缩的 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
-"$COMET_BASH" "$COMET_STATE" check <change-name> <phase> --recover
+node "$COMET_STATE" check <change-name> <phase> --recover
 ```
 
 脚本输出结构化恢复上下文（phase、已完成字段、待完成字段、恢复动作）。按 **Recovery action** 决定下一步。

package/assets/skills-zh/comet/reference/debug-gate.md

@@ -14,4 +14,20 @@
 1. 先复现并定位根因，读取完整错误、检查近期变更、追踪数据流
 2. 若根因指向源码 bug，先补充能复现该崩溃/异常的最小失败测试，再修改源码
 3. 修复后运行该失败测试、相关测试和项目构建/验证命令，确认全部通过
-4. 将测试、源码修复和 tasks.md 勾选保留在当前 change 内；不得通过另起一个“写测试用例”的 change 来替代当前 change 的验证闭环
+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/assets/skills-zh/comet/reference/decision-point.md

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