@rpamis/comet 0.3.8 → 0.3.9

package/assets/skills/comet/scripts/comet-state.sh

@@ -235,6 +235,33 @@ project_auto_transition_default() {
   esac
 }
 
+project_review_mode_default() {
+  local value="null"
+  local source="default"
+  if [ -n "${COMET_REVIEW_MODE:-}" ]; then
+    value="$COMET_REVIEW_MODE"
+    source="COMET_REVIEW_MODE"
+  elif [ -f ".comet/config.yaml" ]; then
+    local raw
+    raw=$(yaml_field "review_mode" ".comet/config.yaml" 2>/dev/null || true)
+    if [ -n "$raw" ]; then
+      value="$raw"
+      source=".comet/config.yaml"
+    fi
+  fi
+
+  case "$value" in
+    null|off|standard|thorough)
+      printf '%s\n' "$value"
+      ;;
+    *)
+      red "ERROR: Invalid review_mode from ${source}: '$value'" >&2
+      red "Valid values: off, standard, thorough" >&2
+      exit 1
+      ;;
+  esac
+}
+
 # --- Subcommands ---
 
 cmd_init() {
@@ -258,7 +285,7 @@ cmd_init() {
   mkdir -p "$change_dir"
 
   # Set workflow-appropriate defaults
-  local phase build_mode isolation verify_mode context_compression auto_transition
+  local phase build_mode isolation verify_mode context_compression auto_transition review_mode
   phase="open"
   context_compression=$(project_context_compression)
   auto_transition="$(project_auto_transition_default)"
@@ -267,12 +294,14 @@ cmd_init() {
     full)
       build_mode="null"
       tdd_mode="null"
+      review_mode="$(project_review_mode_default)"
       isolation="null"
       verify_mode="null"
       ;;
     hotfix|tweak)
       build_mode="direct"
       tdd_mode="direct"
+      review_mode="off"
       isolation="branch"
       verify_mode="light"
       ;;
@@ -293,6 +322,7 @@ build_mode: $build_mode
 build_pause: null
 subagent_dispatch: null
 tdd_mode: $tdd_mode
+review_mode: $review_mode
 isolation: $isolation
 verify_mode: $verify_mode
 auto_transition: $auto_transition
@@ -353,16 +383,25 @@ cmd_set() {
   # Validate field name
   case "$field" in
     phase)
-      yellow "WARNING: Setting 'phase' directly bypasses state machine constraints." >&2
-      yellow "  Consider using: comet-state.sh transition <change-name> <event>" >&2
+      # Direct phase writes bypass state-machine evidence checks (open artifacts,
+      # design_doc, build decisions, verification evidence). Block them unless the
+      # call originates from cmd_transition (dynamic-scope flag) or the operator
+      # explicitly opts into the repair escape hatch.
+      if [ "${_COMET_IN_TRANSITION:-}" != "1" ] && [ "${COMET_FORCE_PHASE:-}" != "1" ]; then
+        red "ERROR: Setting 'phase' directly is not allowed; it bypasses state machine evidence checks." >&2
+        red "  Use: comet-state.sh transition <change-name> <event>" >&2
+        red "  Repair-only escape hatch: COMET_FORCE_PHASE=1 comet-state.sh set <change-name> phase <value>" >&2
+        exit 1
+      fi
+      validate_enum "$value" "open" "design" "build" "verify" "archive"
       ;;
-    workflow|context_compression|build_mode|build_pause|subagent_dispatch|tdd_mode|isolation|verify_mode|auto_transition|verify_result|verification_report|branch_status|archived|design_doc|plan|verified_at|created_at|direct_override|build_command|verify_command|handoff_context|handoff_hash|base_ref)
+    workflow|context_compression|build_mode|build_pause|subagent_dispatch|tdd_mode|review_mode|isolation|verify_mode|auto_transition|verify_result|verification_report|branch_status|archived|design_doc|plan|verified_at|created_at|direct_override|build_command|verify_command|handoff_context|handoff_hash|base_ref)
       # Valid field
       ;;
     *)
       red "ERROR: Unknown field: '$field'" >&2
       red "Valid fields:" >&2
-      red "  workflow, phase, context_compression, design_doc, plan, build_mode, build_pause, subagent_dispatch, tdd_mode, isolation," >&2
+      red "  workflow, phase, context_compression, design_doc, plan, build_mode, build_pause, subagent_dispatch, tdd_mode, review_mode, isolation," >&2
       red "  verify_mode, auto_transition, verify_result, verification_report, branch_status," >&2
       red "  verified_at, created_at, archived, base_ref, direct_override," >&2
       red "  build_command, verify_command, handoff_context, handoff_hash" >&2
@@ -393,6 +432,9 @@ cmd_set() {
     tdd_mode)
       validate_enum "$value" "tdd" "direct"
       ;;
+    review_mode)
+      validate_enum "$value" "off" "standard" "thorough"
+      ;;
     isolation)
       validate_enum "$value" "branch" "worktree"
       ;;
@@ -444,6 +486,33 @@ require_phase() {
   fi
 }
 
+require_open_artifacts() {
+  local change_name="$1"
+  local change_dir workflow f
+  change_dir=$(change_dir_for "$change_name")
+  workflow=$(cmd_get "$change_name" "workflow")
+  for f in proposal.md tasks.md; do
+    if [ ! -s "$change_dir/$f" ]; then
+      red "ERROR: Cannot transition '$change_name': $f must exist and be non-empty before leaving open" >&2
+      exit 1
+    fi
+  done
+  if [ "$workflow" = "full" ] && [ ! -s "$change_dir/design.md" ]; then
+    red "ERROR: Cannot transition '$change_name': design.md must exist and be non-empty before leaving open" >&2
+    exit 1
+  fi
+}
+
+require_design_evidence() {
+  local change_name="$1"
+  local design_doc
+  design_doc=$(cmd_get "$change_name" "design_doc")
+  if [ -z "$design_doc" ] || [ "$design_doc" = "null" ] || [ ! -s "$design_doc" ]; then
+    red "ERROR: Cannot transition '$change_name': design_doc must point to an existing Design Doc before leaving design" >&2
+    exit 1
+  fi
+}
+
 require_verification_evidence() {
   local change_name="$1"
   local report branch_status
@@ -463,13 +532,14 @@ require_verification_evidence() {
 
 require_build_decisions() {
   local change_name="$1"
-  local workflow build_mode isolation direct_override subagent_dispatch tdd_mode
+  local workflow build_mode isolation direct_override subagent_dispatch tdd_mode review_mode
   workflow=$(cmd_get "$change_name" "workflow")
   build_mode=$(cmd_get "$change_name" "build_mode")
   isolation=$(cmd_get "$change_name" "isolation")
   direct_override=$(cmd_get "$change_name" "direct_override" 2>/dev/null || true)
   subagent_dispatch=$(cmd_get "$change_name" "subagent_dispatch" 2>/dev/null || true)
   tdd_mode=$(cmd_get "$change_name" "tdd_mode" 2>/dev/null || true)
+  review_mode=$(cmd_get "$change_name" "review_mode" 2>/dev/null || true)
 
   case "$isolation" in
     branch|worktree) ;;
@@ -501,11 +571,24 @@ require_build_decisions() {
     red "ERROR: Cannot transition '$change_name': tdd_mode must be selected before leaving build (full workflow)" >&2
     exit 1
   fi
+
+  if [ "$workflow" = "full" ]; then
+    case "$review_mode" in
+      off|standard|thorough) ;;
+      *)
+        red "ERROR: Cannot transition '$change_name': review_mode must be selected before leaving build (full workflow); review_mode must be off, standard, or thorough, got '${review_mode:-null}'" >&2
+        exit 1
+        ;;
+    esac
+  fi
 }
 
 cmd_transition() {
   local change_name="$1"
   local event="$2"
+  # Dynamic-scope flag: authorizes the internal cmd_set phase writes below while
+  # still blocking direct `set <name> phase` from the CLI.
+  local _COMET_IN_TRANSITION=1
 
   validate_change_name "$change_name"
   validate_enum "$event" "open-complete" "design-complete" "build-complete" "verify-pass" "verify-fail" "archive-reopen" "archived"
@@ -513,6 +596,7 @@ cmd_transition() {
   case "$event" in
     open-complete)
       require_phase "$change_name" "open"
+      require_open_artifacts "$change_name"
       local workflow
       workflow=$(cmd_get "$change_name" "workflow")
       if [ "$workflow" = "full" ]; then
@@ -523,6 +607,7 @@ cmd_transition() {
       ;;
     design-complete)
       require_phase "$change_name" "design"
+      require_design_evidence "$change_name"
       cmd_set "$change_name" phase build
       ;;
     build-complete)
@@ -566,6 +651,12 @@ cmd_transition() {
       ;;
     archived)
       require_phase "$change_name" "archive"
+      local archived_verify_result
+      archived_verify_result=$(cmd_get "$change_name" "verify_result")
+      if [ "$archived_verify_result" != "pass" ]; then
+        red "ERROR: Cannot transition '$change_name': verify_result must be pass before archiving" >&2
+        exit 1
+      fi
       cmd_set "$change_name" archived true
       ;;
   esac
@@ -772,7 +863,7 @@ cmd_recover() {
 
   # Read all relevant fields
   local design_doc plan verify_result verify_mode verification_report
-  local branch_status handoff_context handoff_hash isolation build_mode build_pause subagent_dispatch tdd_mode direct_override
+  local branch_status handoff_context handoff_hash isolation build_mode build_pause subagent_dispatch tdd_mode review_mode direct_override
   design_doc=$(cmd_get "$change_name" "design_doc")
   plan=$(cmd_get "$change_name" "plan")
   verify_result=$(cmd_get "$change_name" "verify_result")
@@ -786,6 +877,7 @@ cmd_recover() {
   build_pause=$(cmd_get "$change_name" "build_pause" 2>/dev/null || true)
   subagent_dispatch=$(cmd_get "$change_name" "subagent_dispatch" 2>/dev/null || true)
   tdd_mode=$(cmd_get "$change_name" "tdd_mode" 2>/dev/null || true)
+  review_mode=$(cmd_get "$change_name" "review_mode" 2>/dev/null || true)
   direct_override=$(cmd_get "$change_name" "direct_override" 2>/dev/null || true)
 
   echo "State fields:"
@@ -841,6 +933,7 @@ cmd_recover() {
       field_status "build_mode" "$build_mode"
       field_status "build_pause" "$build_pause"
       field_status "tdd_mode" "$tdd_mode"
+      field_status "review_mode" "$review_mode"
       if [ "$build_mode" = "subagent-driven-development" ] || { [ -n "$subagent_dispatch" ] && [ "$subagent_dispatch" != "null" ]; }; then
         field_status "subagent_dispatch" "$subagent_dispatch"
       fi

package/assets/skills/comet/scripts/comet-yaml-validate.sh

@@ -143,6 +143,7 @@ build_mode=$(field_value "build_mode")
 build_pause=$(field_value "build_pause")
 subagent_dispatch=$(field_value "subagent_dispatch")
 tdd_mode=$(field_value "tdd_mode")
+review_mode=$(field_value "review_mode")
 isolation=$(field_value "isolation")
 verify_mode=$(field_value "verify_mode")
 auto_transition=$(field_value "auto_transition")
@@ -162,6 +163,7 @@ validate_enum "build_mode"    "$build_mode"     "subagent-driven-development exe
 validate_enum "build_pause"   "$build_pause"     "null plan-ready"
 validate_enum "subagent_dispatch" "$subagent_dispatch" "null confirmed"
 validate_enum "tdd_mode"      "$tdd_mode"       "tdd direct null"
+validate_enum "review_mode"   "$review_mode"    "off standard thorough"
 validate_enum "isolation"     "$isolation"      "branch worktree"
 validate_enum "verify_mode"   "$verify_mode"    "light full"
 if grep -q "^auto_transition:" "$YAML" 2>/dev/null; then
@@ -199,7 +201,7 @@ if [ -n "$handoff_hash" ] && [ "$handoff_hash" != "null" ]; then
 fi
 
 # --- Unknown keys check ---
-KNOWN_KEYS="workflow phase context_compression design_doc plan build_mode build_pause subagent_dispatch tdd_mode isolation verify_mode auto_transition verify_result verification_report branch_status verified_at created_at archived direct_override build_command verify_command handoff_context handoff_hash base_ref"
+KNOWN_KEYS="workflow phase context_compression design_doc plan build_mode build_pause subagent_dispatch tdd_mode review_mode isolation verify_mode auto_transition verify_result verification_report branch_status verified_at created_at archived direct_override build_command verify_command handoff_context handoff_hash base_ref"
 while IFS=: read -r key _; do
   key="${key// /}"
   [ -z "$key" ] && continue

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

@@ -71,6 +71,23 @@ When pausing, present the clarification summary: goals, non-goals, scope boundar
 
 Must not create proposal.md, design.md, or tasks.md before the user confirms requirements clarification is complete, and must not use the Skill tool to load the `openspec-propose` skill to generate all artifacts in one pass.
 
+### 1c. Change Name Confirmation (Blocking Point)
+
+Before creating the change directory (`openspec new change`), must follow the `comet/reference/decision-point.md` protocol to pause and let the user decide the change name. Must not auto-generate or silently infer the change name.
+
+OpenSpec change names must be **kebab-case English** (lowercase letters, digits, hyphens; e.g. `refine-requirements-doc`). Chinese or other non-conforming names are invalid.
+
+When pausing, present:
+- **2-3 recommended kebab-case English names** derived from the confirmed clarification summary, each with a one-line description of the scope it implies
+- An explicit option for the user to **enter their own name**
+- A note that **if the user enters Chinese (or any non-kebab-case text), it will be converted into a compliant kebab-case English name**, and the converted result must be shown back to the user for confirmation before use
+
+The decision options must include:
+- Pick one of the recommended names
+- "Enter a custom name" — accept the user's input; if it is already valid kebab-case English, use it directly; if it is Chinese or otherwise non-conforming, convert it to compliant kebab-case English and show the converted name for confirmation before continuing
+
+Must not run `openspec new change` or create `.comet.yaml` before the user confirms the final change name. If the chosen/converted name collides with an existing change, report the collision and ask the user to choose another name.
+
 ### 2. Create Change Structure + Initialize State
 
 **Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. Skipping this step is prohibited.
@@ -105,7 +122,7 @@ After the change skeleton is created, generate `proposal`, `design`, and `tasks`
 
 **Failure handling**: If `openspec instructions` fails, returns invalid JSON, reports unmet `dependencies`, or does not provide a usable `resolvedOutputPath`, must immediately stop artifact creation and report the OpenSpec error. Must not fall back to hard-coded artifact prose because that would silently bypass project rules.
 
-**Naming and scope guard**: Change name must use a user-specified name or a name confirmed through the current platform's available user input/confirmation mechanism — must not auto-generate or infer. Change scope must match the user's description — must not expand or narrow it independently.
+**Naming and scope guard**: Change name must be the kebab-case English name confirmed by the user in Step 1c — must not auto-generate, infer, or use a non-kebab-case (e.g. Chinese) name. Change scope must match the user's description — must not expand or narrow it independently.
 
 Confirm the following artifacts have been created:
 

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

@@ -185,7 +185,7 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须
 > - **自动衔接协议**：按 `comet/reference/auto-transition.md` 查阅
 > - **上下文压缩恢复**：按 `comet/reference/context-recovery.md` 查阅
 > - **用户决策点协议**：按 `comet/reference/decision-point.md` 查阅
-> - **调试门协议**：按 `comet/reference/debug-gate.md` 查阅
+> - **异常调试协议**：按 `comet/reference/debug-gate.md` 查阅
 
 ### 状态机硬约束
 

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

@@ -16,6 +16,7 @@ build_mode: subagent-driven-development
 build_pause: null
 subagent_dispatch: confirmed
 tdd_mode: tdd
+review_mode: standard
 isolation: branch
 verify_mode: light
 verify_result: pending
@@ -39,6 +40,7 @@ archived: false
 | `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 字段更新 |
@@ -63,6 +65,7 @@ archived: false
 - `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`

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

@@ -21,7 +21,7 @@
 3. 读取 `openspec/changes/<name>/.comet/subagent-progress.md`，恢复当前 task 或 final review、实现提交、RED/GREEN 证据、已通过审查、未解决反馈和审查-修复轮次
 4. 禁止在主会话中直接执行 task
 5. 按检查点记录的精确阶段恢复；检查点缺失或不匹配时才从第一个未勾选 task 的 implementer 派发开始
-6. task 通过双审查并完成定向勾选验证后，立即继续下一个 task，不得总结或询问是否继续
+6. task 按 `review_mode` 完成验收并完成定向勾选验证后，立即继续下一个 task，不得总结或询问是否继续
 
 ## design 阶段特殊恢复
 

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

@@ -1,8 +1,8 @@
-# Debug Gate 协议
+# 异常调试协议
 
 规范路径：`comet/reference/debug-gate.md`
 
-本协议由 build、hotfix、tweak 等会直接修改代码的 comet 子 skill 共享。当运行程序、测试、构建或手动验证时出现崩溃、异常行为、测试失败或构建失败，必须进入 Debug Gate。
+本协议由 build、hotfix、tweak 等会直接修改代码的 comet 子 skill 共享。当运行程序、测试、构建或手动验证时出现崩溃、异常行为、测试失败或构建失败，必须进入异常调试协议。
 
 ## 核心规则
 

package/assets/skills-zh/comet/reference/dirty-worktree.md

@@ -1,59 +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 未解释清楚时判定验证通过
+# 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/assets/skills-zh/comet/reference/subagent-dispatch.md

@@ -2,14 +2,14 @@
 
 规范路径：`comet/reference/subagent-dispatch.md`
 
-本文档提供在 Superpowers `subagent-driven-development` 技能**之上**应用的 Comet 专属扩展。该技能负责核心派发循环（每个 task 派发全新 implementer → spec compliance review → code quality review → 下一个 task）并强制连续执行。本文档添加 Comet 特有的真实后台调度、任务追踪、状态验证和上下文恢复。若 Superpowers 技能与本文档发生冲突时，以本文档中更具体的 Comet 约束为准。
+本文档提供在 Superpowers `subagent-driven-development` 技能**之上**应用的 Comet 专属扩展。该技能负责核心派发循环（每个 task 派发全新 implementer → spec compliance review → code quality review → 下一个 task）并强制连续执行。本文档添加 Comet 特有的真实后台调度、任务追踪、状态验证、代码审查模式和上下文恢复。若 Superpowers 技能与本文档发生冲突时，以本文档中更具体的 Comet 约束为准。
 
 > **⚠️ 关键约束 — 任务之间禁止暂停**
 >
-> 当一个 task 通过双审查并被勾选后，**立即派发下一个 task**，不得停止、总结或询问用户是否继续。用户期望所有 task 按顺序自动执行，无需手动干预。任务之间暂停会中断工作流，导致用户每次都需要手动恢复。
+> 当一个 task 按 `review_mode` 完成验收并被勾选后，**立即派发下一个 task**，不得停止、总结或询问用户是否继续。用户期望所有 task 按顺序自动执行，无需手动干预。任务之间暂停会中断工作流，导致用户每次都需要手动恢复。
 >
 > 仅在以下情况才停止并等待用户输入：
-> - 任务处于 **BLOCKED** 状态（3 轮审查-修复仍未通过）
+> - 任务处于 **BLOCKED** 状态（`review_mode: standard` 下一轮轻量复查仍未通过，或 `review_mode: thorough` 下批次/最终审查 2 轮审查-修复仍未通过）
 > - 存在无法从仓库、计划或既有上下文消除的真实歧义
 > - 平台没有真实后台 agent 调度能力，需要用户改选 `executing-plans`
 > - 用户**明确**要求暂停
@@ -28,9 +28,9 @@
 
 ### 0. 派发强制约束（关键）
 
-主会话**仅负责协调**，禁止直接执行 task。主会话禁止修改源代码。协调者唯一允许的文件修改是 plan、OpenSpec task 和 subagent 进度检查点的持久化更新。不得把多个 task 打包给同一个 agent。每个 task 派发一个全新的后台 implementer agent，spec reviewer、code quality reviewer、修复 agent 和 final reviewer 也必须分别使用全新的后台 agent：
+主会话**仅负责协调**，禁止直接执行 task。主会话禁止修改源代码。协调者唯一允许的文件修改是 plan、OpenSpec task 和 subagent 进度检查点的持久化更新。不得把多个 task 打包给同一个 agent。每个 task 派发一个全新的后台 implementer agent；当 `review_mode` 需要审查或修复时，spec reviewer、code quality reviewer、修复 agent 和 final reviewer 也必须分别使用全新的后台 agent：
 
-- **Claude Code**：对每个 implementer、spec reviewer、code quality reviewer、修复 agent 和 final reviewer 使用 `Agent` 工具并设置 `run_in_background: true`。禁止内联执行 task，禁止错误进入需要预先创建 team 的团队模式。
+- **Claude Code**：对每个 implementer，以及 `review_mode` 要求的 spec reviewer、code quality reviewer、修复 agent 和 final reviewer 使用 `Agent` 工具并设置 `run_in_background: true`。禁止内联执行 task，禁止错误进入需要预先创建 team 的团队模式。
 - **其他平台**：使用平台等效的后台 agent / Task / 多 agent 派发机制。
 - **禁止**跨 task 或角色复用 implementer、reviewer 或修复 agent。每个 agent 拥有全新的隔离上下文，并且只接收当前角色所需的单个 task 上下文。
 - 若平台无真实后台派发能力，不得继续；暂停并等待用户改选 `build_mode: executing-plans`。
@@ -47,7 +47,7 @@
 
 agent 回报状态必须为 `DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT`，并包含实现内容、测试结果、提交哈希、变更文件和顾虑。进入审查前，主会话必须确认提交和文件在当前工作树可见；若平台使用隔离副本，先拉取或合并变更。
 
-每个 reviewer prompt 必须包含完整 task、实现提交或差异以及 RED/GREEN 证据（`tdd_mode: tdd` 时）。reviewer 不得只依据 implementer 的总结进行审查。
+当 `review_mode` 需要 reviewer 时，每个 reviewer prompt 必须包含完整 task、实现提交或差异以及 RED/GREEN 证据（`tdd_mode: tdd` 时）。reviewer 不得只依据 implementer 的总结进行审查。
 
 ### 2. Implementer 范围限制
 
@@ -70,18 +70,23 @@ implementer 或修复 agent 回报必须提供 **RED 失败命令与失败摘要
 - 当前 plan task 唯一文本及映射的 OpenSpec task 文本
 - 当前阶段：`implementing | spec-review | quality-review | checkoff | done | blocked | final-review | final-fix`
 - 实现提交哈希、变更文件和 RED/GREEN 证据
+- 已选择的 `review_mode`
 - 已通过的审查阶段及尚未解决的 reviewer 反馈
-- 当前 task 或 final review 的审查-修复轮次（最多 3 轮）
+- 当前 task、批次或 final review 的审查-修复轮次（`standard` 最多 1 轮，`thorough` 最多 2 轮，`off` 为 0 轮）
 
 该文件只保存恢复所需的协调状态，不替代 plan 或 OpenSpec checkbox。当前 task 完成后保留其最终记录，开始下一个 task 时用下一 task 的记录替换。
 
-### 5. 审查-修复轮次限制
+### 5. 代码审查模式与轮次限制
 
-每个 task 最多 3 轮审查-修复。任一 reviewer 发现问题时，派发全新的后台修复 agent，并从对应审查重新开始。3 轮后仍未通过则将 task 标记为 **BLOCKED**，暂停并把累计反馈交给用户。
+当 `review_mode: standard` 时，每个 task 不自动派发 per-task reviewer；implementer 必须自测、提交并回报证据，协调者完成定向勾选验证。所有 task 完成后只派发一次最终轻量 code reviewer，审查范围限定为正确性、安全和边界条件。若最终轻量审查发现 CRITICAL 或 IMPORTANT 问题，最多自动派发一轮修复 agent 并复查一次；复查仍未通过时标记 **BLOCKED**，暂停并把反馈交给用户。非 CRITICAL 发现可记录接受理由后继续。
+
+当 `review_mode: thorough` 时，不执行每 task 双审查。协调者按批次或风险边界运行合并审查：每完成最多 3 个 task、或完成一个跨模块/高风险边界时，派发一个 reviewer 同时检查 spec compliance 与 code quality。若总 task 数不超过 3 且没有高风险边界，可跳过中途批次审查，只做最终完整审查。所有 task 完成后再派发一次最终完整 reviewer。批次和最终审查各最多 2 轮审查-修复；仍未通过则标记 **BLOCKED**，暂停并把累计反馈交给用户。
+
+当 `review_mode: off` 时，不自动派发 spec reviewer、code quality reviewer、final reviewer 或审查修复 agent。任务完成依据 implementer 的测试/构建证据、当前工作树确认、任务唯一文本勾选验证和用户显式要求。若执行过程中出现测试失败、构建失败或异常行为，仍必须按异常调试协议处理，不得用 `off` 跳过真实问题。
 
 ### 6. Task 勾选与验证
 
-**两个审查都通过后**，主会话：
+**按 `review_mode` 完成验收后**，主会话：
 
 1. 将 plan 中保存的唯一 task 文本从 `- [ ]` 改为 `- [x]`
 2. 若存在映射，再同步勾选 OpenSpec task
@@ -97,17 +102,19 @@ implementer 或修复 agent 回报必须提供 **RED 失败命令与失败摘要
 
 ## 收尾
 
-- **自动继续**：双审查通过并勾选 task 后，立即派发下一个未勾选的 task。禁止总结、禁止询问用户是否继续、禁止在任务之间等待用户输入。这是不可协商的 —— Superpowers 技能强制连续执行，文档顶部的关键约束进一步强化此规则。
-- 所有 task 完成后，将检查点切换为 `final-review`，然后派发全新的后台 final code quality reviewer 审查整体实现。CRITICAL 问题必须将检查点切换为 `final-fix`，记录反馈和轮次，派发新的后台修复 agent 并重新审查；final review 同样最多 3 轮，耗尽后标记 `blocked` 并暂停。接受非 CRITICAL 发现时，在 tasks.md 中记录理由。
+- **自动继续**：按 `review_mode` 完成验收并勾选 task 后，立即派发下一个未勾选的 task。禁止总结、禁止询问用户是否继续、禁止在任务之间等待用户输入。这是不可协商的 —— Superpowers 技能强制连续执行，文档顶部的关键约束进一步强化此规则。
+- 所有 task 完成后，若 `review_mode: standard`，将检查点切换为 `final-review`，只派发一次最终轻量 code reviewer。CRITICAL 或 IMPORTANT 问题最多自动修复和复查一轮；仍未通过则暂停交给用户。通过或接受非 CRITICAL 发现后继续返回 `comet-build`。
+- 所有 task 完成后，若 `review_mode: thorough`，将检查点切换为 `final-review`，派发一次最终完整 reviewer。CRITICAL 或 IMPORTANT 问题最多自动修复和复查两轮；仍未通过则暂停交给用户。通过或接受非 CRITICAL 发现后继续返回 `comet-build`。
+- 所有 task 完成后，若 `review_mode: off`，不进入 `final-review` 或 `final-fix`，但必须在持久产物中记录跳过自动代码审查的原因，然后返回 `comet-build`。
 - final review 通过后，结束的只是 subagent 派发循环，不是 Comet workflow。不得加载 `finishing-a-development-branch`，不得停下来询问用户下一步；必须返回 `comet-build` 继续执行退出条件、阶段守卫和后续阶段衔接。
 
 ## 上下文恢复
 
 重新加载 Superpowers `subagent-driven-development` 技能并重新阅读本文档。先读取 `openspec/changes/<name>/.comet/subagent-progress.md`，再与第一个未勾选 task 和当前工作树核对：
 
-- 检查点与未勾选 task 匹配时，从记录的精确阶段恢复，保留实现提交、RED/GREEN 证据、已通过的审查阶段、未解决反馈和当前审查-修复轮次；不得重置轮次或重复已经通过的阶段。
+- 检查点与未勾选 task 匹配时，从记录的精确阶段恢复，保留实现提交、RED/GREEN 证据、`review_mode`、已通过的审查阶段、未解决反馈和当前审查-修复轮次；不得重置轮次或重复已经通过的阶段。
 - 检查点缺失或与未勾选 task 不匹配时，为第一个未勾选 task 创建新检查点并从 implementer 派发开始。
 - 检查点中的提交或文件在当前工作树不可见时，先拉取、合并或恢复对应变更；不得假定实现已存在。
 - 所有 task 已勾选且检查点处于 `final-review` 或 `final-fix` 时，从最终审查的精确阶段恢复，并保留最终反馈和审查-修复轮次；不得重新进入已完成的 task。
 
-已提交但未通过双审查的 task 保持未勾选，并按检查点重新进入审查或修复循环。
+已提交但未按 `review_mode` 完成验收的 task 保持未勾选，并按检查点重新进入对应的验证、审查或修复流程。