@rpamis/comet 0.4.0-beta.4 → 0.4.0-beta.5

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

@@ -1,9 +1,9 @@
 ---
 name: comet-verify
-description: "Use when a Comet change has completed build and needs implementation verification, verification-failure decisions, or branch closeout."
+description: "Use only when explicitly invoked as /comet-verify or routed by the root Comet skill/runtime to the verify phase; verify a Comet change, record evidence, and manage repair loops."
 ---
 
-# Comet Phase 4: Verify and Close (Verify)
+# Comet Phase 4: Verify
 
 ## Prerequisites
 
@@ -14,7 +14,7 @@ description: "Use when a Comet change has completed build and needs implementati
 
 ### 0a. Output Language Constraint
 
-Verification reports and branch-handling notes must use the configured Comet artifact language from `comet state get <name> language`.
+Verification reports must use the configured Comet artifact language from `comet state get <name> language`.
 
 ### 0b. Entry State Verification (Entry Check)
 
@@ -27,7 +27,7 @@ comet state check <change-name> verify
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
 
-**Idempotency**: All verify phase checks can be safely re-executed. If `verify_result` is already `pass` and `branch_status` is `handled`, verification is complete — execute guard to transition. If `verify_result` is `pending`, start verification from the beginning.
+**Idempotency**: All verify checks are safe to repeat. If `verify_result` is already `pass`, verification is complete and archive should continue; keep `branch_status: pending` until archive changes are committed and final branch handling finishes. If `verify_result` is `pending`, start verification from the beginning.
 
 ### 1. Scale Assessment
 
@@ -41,27 +41,26 @@ The script automatically counts tasks, delta spec count, changed file count, det
 
 Before verification begins, handle uncommitted changes through `comet/reference/dirty-worktree.md` protocol. Verify phase special handling:
 
-1. If dirty diff belongs to current change and involves implementation, tests, tasks, delta spec, or design doc changes, do not fix or commit directly in verify phase; report failures and enter Step 1b verification failure decision blocking point
-2. If dirty diff is only verify phase artifacts (e.g., verification report draft, branch handling records), may continue and record state in verify phase
-3. If dirty diff shows implementation but tasks.md not checked, treat as build state lag; report failures and enter Step 1b, let user decide to roll back for fix or accept deviation
+1. If dirty diff clearly belongs to the current change, it is verification input. Continue verification, but do not modify or commit implementation, tests, tasks, delta specs, or the Design Doc in verify
+2. If dirty diff is only a verify phase artifact such as a verification report draft, may continue and record state in verify phase
+3. If dirty diff shows implementation but tasks.md remains unchecked, treat it as lagging build state. This has one valid next action: run `verify-fail`, return to build, verify evidence, and update task state without asking whether to accept incomplete tasks
+4. If dirty diff cannot be attributed or belongs to another change, report a stop condition through the dirty-worktree protocol. Do not disguise attribution failure as a continue/ignore choice
 
-Only after user chooses fix, allow rollback to build phase:
+When repair or state reconciliation must return to build, run:
 
 ```bash
-# Execute only after user confirms fix
 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`.
-
 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 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
+comet state get <change-name> plan
+git diff --stat <base-ref read from plan frontmatter>...HEAD
 ```
 
+The first command returns the plan path. Use the host's file reader to parse the single `base-ref` frontmatter field, validate it as a commit, then substitute it into the second command. Do not depend on POSIX text pipelines.
+
 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
@@ -70,33 +69,34 @@ 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 state set <change-name> verify_mode <light|full>`.
 
-### 1b. Verification Failure Decision (Blocking Point)
+### 1b. Automatic Verification Repair and Exception Decisions
 
-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 state transition <change-name> verify-fail`, nor automatically invoke `/comet-build`.
+Run `comet state get <change-name> verify_failures` first to read the persisted consecutive failure count. Automatically return to build for the first 3 repairable failures: report the failures, run `comet state transition <change-name> verify-fail`, then invoke `/comet-build` without asking for confirmation.
 
-When pausing, must list:
+The report must list:
 - Failed items
 - Whether CRITICAL or IMPORTANT (build failure, test failure, security issues, core acceptance scenario failure, lightweight code review correctness/security/edge-case issue)
 - Recommended handling approach
 
-**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.
+**Uncertainty principle**: Use a lower severity when evidence is unclear. Reserve CRITICAL for build failures, test failures, and security issues; use IMPORTANT for confirmed core-acceptance or correctness failures; mark ambiguous findings WARNING or SUGGESTION.
 
-After user selection, continue as follows:
-- **Fix all**: Run `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
+Handle failures as follows:
+- **CRITICAL/IMPORTANT or objectively repairable in-scope issues**: automatically return to build below the retry limit. Do not manufacture a "whether to fix" decision, and never accept these as deviations
+- **WARNING/SUGGESTION whose fix introduces a behavior, scope, or risk tradeoff**: use `comet/reference/decision-point.md` to ask whether to fix or accept. Record the reason and impact scope when accepted
+- **WARNING/SUGGESTION with a safe, local, tradeoff-free fix**: repair automatically below the retry limit; low severity alone does not justify a pause
 
-**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.
+Only accepting WARNING/SUGGESTION deviations or choosing a strategy after the 4th failure is a user decision point. When `verify_failures >= 3`, do not automatically execute another `verify-fail`. Offer only "Continue fixing" or "Stop this workflow and seek an external decision" under the decision protocol. Record the next failure and return to build only after the user chooses continue. CRITICAL/IMPORTANT findings are never waivable.
 
 ### 2. Artifact Context Loading (Hash On-Demand Read)
 
 When verification needs to read OpenSpec artifacts, first check whether they have changed since the design phase:
 
 ```bash
-RECORDED_HASH=$(comet state get <change-name> handoff_hash)
-CURRENT_HASH=$(comet handoff <change-name> --hash-only 2>/dev/null || echo "")
+comet state get <change-name> handoff_hash
+comet handoff <change-name> --hash-only
 ```
 
-- 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.
+- Read the two standard outputs separately. If they match and both are non-empty and non-`null`, OpenSpec artifacts are unchanged. **tasks.md does not need to be re-read in full**; parse its checkboxes to confirm none remain unchecked. proposal.md, design.md, and delta specs must still be read for comparison checks.
 - If `RECORDED_HASH` is empty, is `null`, or differs from `CURRENT_HASH`: artifacts have changed or hash was never recorded. Read all required files in full normally.
 
 This optimization only skips re-reading tasks.md in full. proposal.md and design.md contain the full context needed for verification checks and must not be skipped due to hash match.
@@ -116,7 +116,7 @@ Run these 6 checks:
 5. No obvious security issues (no hardcoded keys, no new unsafe operations)
 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. `review_mode: off` only skips automatic code review, not build, test, security checks, or debug gate protocol.
+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, follow Step 1b automatic repair and retry handling. `review_mode: off` only skips automatic code review, not build, test, security checks, or debug gate protocol.
 
 If the project has no automatically inferred verification command, the user or Agent must run the real verification command first, then record its evidence separately:
 
@@ -130,10 +130,9 @@ comet state record-check <change-name> verify --command "<actual verification co
 
 **Pass criteria**: All 6 items OK, no CRITICAL or IMPORTANT issues.
 
-**When not passing**: Report failures, enter Step 1b verification failure decision blocking point. Only after user confirms fix, execute the following command to record failure and roll back to build phase, then invoke `/comet-build` to fix:
+**When not passing**: Report failures and classify them under Step 1b. Below the automatic retry limit, when an issue must or should be repaired, run the following command directly and invoke `/comet-build`:
 
 ```bash
-# Execute only after user confirms fix
 comet state transition <change-name> verify-fail
 ```
 
@@ -160,10 +159,9 @@ After the skill loads, follow its guidance to verify. Check items:
 6. No contradictions between delta spec and design doc (if Build phase had incremental spec modifications, check if design doc has corresponding records)
 7. Associated design documents under `docs/superpowers/specs/` are locatable (file exists and is related to current change)
 
-When verification does not pass: report missing items, enter Step 1b verification failure decision blocking point. Only after user confirms fix, execute the following command to record failure and roll back to build phase, then invoke `/comet-build` to supplement:
+When verification does not pass, report missing items and classify them under Step 1b. Below the automatic retry limit, when the current change can supply the missing evidence, run the following command directly and invoke `/comet-build`:
 
 ```bash
-# Execute only after user confirms fix
 comet state transition <change-name> verify-fail
 ```
 
@@ -173,46 +171,24 @@ comet state transition <change-name> verify-fail
   - Option B: After user selects B, run `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)
-
-**Immediately execute:** Use the Skill tool to load the Superpowers `finishing-a-development-branch` skill. Skipping this step is prohibited.
-
-If the Superpowers `finishing-a-development-branch` skill is unavailable, stop the process and prompt to install or enable Superpowers skills. Do not substitute this step with normal conversation.
-
-After the skill loads, follow its guidance to finish. Branch handling options:
-1. Merge to main branch locally
-2. Push and create PR
-3. Keep branch (handle later)
-4. Discard work
+### 3. Record Verification Evidence
 
-This is a user decision point. **Must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to choose branch handling method**. Must not select based on recommendations, defaults, or current branch status. Only after the user completes selection and the corresponding operation finishes, may `branch_status: handled` be written.
-
-**Confirmation items**:
-- All tests pass
-- No hardcoded keys or security issues
-
-### 4. Record Verification Evidence
-
-Verification report must be saved to disk and recorded in `.comet.yaml`; after branch handling completes, state fields must also be written. Do not manually set `verify_result: pass`; use guard for auto-transition.
+Save the verification report and record it in `.comet.yaml`. Do not handle, merge, or discard branches in verify and do not write `branch_status: handled`: archive creates spec and metadata changes that belong in the final commit, so `/comet-archive` owns branch finishing after that commit. Do not set `verify_result: pass` manually; use the phase guard.
 
 ```bash
-mkdir -p docs/superpowers/reports
-# Write verification conclusions to report file, e.g.:
-# docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
-
 comet state set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
-comet state set <change-name> branch_status handled
 ```
 
+Use the host's file API to create `docs/superpowers/reports/` and the report file; do not depend on a POSIX-only directory command.
+
 ## Exit Conditions
 
 - Verification report passed
-- Branch handled
 - `verification_report` in `.comet.yaml` points to an existing verification report file
-- `branch_status: handled` in `.comet.yaml`
+- `branch_status` remains `pending`
 - **Phase guard**: Run `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:
+After verification evidence is complete, run guard for auto-transition:
 
 ```bash
 comet guard <change-name> verify --apply
@@ -233,7 +209,7 @@ comet state next <change-name>
 ```
 
 - `NEXT: auto` → invoke the skill pointed to by `SKILL` to enter the next phase
-- `NEXT: manual` → do not invoke the next skill; prompt user to run `/<SKILL>` manually
+- `NEXT: manual` → do not invoke the next skill; return control with `HINT`, end the invocation, and do not create another confirmation point
 - `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.

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

@@ -1,6 +1,6 @@
 ---
 name: comet
-description: "Use when 用户要启动或恢复 Comet 工作流，需要根据 active change、.comet.yaml、hotfix/tweak 意图路由到对应阶段 Skill。"
+description: "用于用户明确调用 /comet、要求启动或恢复 Comet 托管工作流，或仓库中存在可无歧义恢复的 active Comet change；负责通过 intent runtime 和 .comet.yaml 路由阶段。"
 ---
 
 # Comet — OpenSpec + Superpowers 双星开发流程
@@ -22,7 +22,7 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 ### 输出语言规则
 
-所有 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` 和全局 `~/.comet/config.yaml` 的 `language`；都不存在时才回退到当前用户请求语言。调用外部 OpenSpec/Superpowers skill 时，必须把解析后的语言显式写入 prompt 或 ARGUMENTS。
+所有 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` 的 `language`；都不存在时才回退到当前用户请求语言。调用外部 OpenSpec/Superpowers skill 时，必须把解析后的语言显式写入 prompt 或 ARGUMENTS。
 
 ### 阶段自动检测
 
@@ -126,22 +126,22 @@ node "$COMET_RESUME_PROBE" probe --stdin
 - 每次恢复上下文时，先重新执行 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` 但 `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` 的对应规则继续
-- 若 `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
+- 若 `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` → 进入验证失败决策阻塞点（暂停询问修复或接受偏差；用户选择修复后才 `verify-fail` 并 `/comet-build`）
+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`
@@ -156,11 +156,11 @@ hotfix/tweak 的范围判定采用三层分工，避免「用纯文件数当硬
 
 1. **质变信号**（agent 语义识别，命中任一即暂停交用户二选一）：跨模块协调修改、需要新增 capability、数据库 schema 变更、引入新的 public API、触及深层架构问题（各预设沿用这套核心信号，并可追加自身语境的特有信号，如 tweak 的「需要拆分为多个 OpenSpec changes」）
 2. **文件数 tripwire**（用户拍板，非自动升级）：改动文件数超提示阈值时，暂停交用户决定继续预设流程还是升级 full，不自动踢
-3. **验证级别**（scale 脚本判定）：`comet-state scale` 仅决定 `verify_mode`（验证轻重），不卡流程、不触发升级
+3. **验证级别**（scale 脚本判定）：`comet state scale` 仅决定 `verify_mode`（验证轻重），不卡流程、不触发升级
 
 **升级决策点（用户二选一）**：
 - 继续预设轻量流程（用户确认范围可控）
-- 升级为完整 `/comet`（使用 `node "$COMET_STATE" transition <name> preset-escalate` 合法回退到 design 阶段，补 Design Doc 和 Superpowers plan）
+- 升级为完整 `/comet`（使用 `comet state transition <name> preset-escalate` 合法回退到 design 阶段，同时清除预设专属的 build 配置；补 Design Doc 后重新联合选择完整工作方式）
 
 详细判定规则见 `comet-hotfix` / `comet-tweak` 各自的「升级判定」章节。
 
@@ -170,7 +170,8 @@ hotfix/tweak 的范围判定采用三层分工，避免「用纯文件数当硬
 |------|---------|
 | `openspec list --json` 失败 | 检查 openspec 是否已安装，提示 `openspec init` |
 | 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
-| `.comet.yaml` 格式异常或缺失 | 以文件状态为准，用 `node "$COMET_STATE" set` 修正后继续 |
+| `.comet.yaml` 缺失 | 进入对应 preset 的 `/comet-open` 初始化状态，再运行 `comet state select`；不得跳过初始化 |
+| `.comet.yaml` 格式异常 | 停止并报告解析错误；从版本控制、备份或可验证产物人工修复，不能用 `comet state set` 覆盖损坏文件 |
 | 构建/测试失败 | 返回 build 阶段修复，不进入 verify |
 | change 目录结构不完整 | 按 `comet-open` 产物要求补齐 |
 
@@ -183,20 +184,21 @@ hotfix/tweak 的范围判定采用三层分工，避免「用纯文件数当硬
 
 **连续执行要求**：从检测到的阶段开始，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` 取何值，下方的用户决策点都必须阻塞等待。
+**阶段推进与自动衔接的区分**：每个子 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` 调用必须停住，并按 `comet/reference/decision-point.md` 的协议获取用户明确选择。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。
 
 需要用户参与的节点（仅在这些节点暂停）：
-1. open 阶段 proposal/design/tasks 审视确认
-2. brainstorming 确认设计方案
-3. build 阶段 plan-ready 暂停选择，以及随后选择工作方式（工作区隔离 + 执行方式 + TDD 模式 + 代码审查模式）
-4. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择）
-5. finishing-branch 选择分支处理方式
+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. 遇到升级判定信号（hotfix/tweak → 用户二选一：继续预设流程 / 升级完整流程）
-8. build 阶段范围扩张需重新设计或拆分新 change
-9. open 阶段大型 PRD 需确认拆分为多个 change
+7. 归档改动精确提交后选择 finishing-branch 分支处理方式
+8. 遇到升级判定信号（hotfix/tweak → 用户二选一：继续预设流程 / 升级完整流程）
+9. build 阶段范围扩张需重新设计或拆分新 change
+10. open 阶段大型 PRD 是否拆分为多个 changes
 
 agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。到达决策点时，**禁止跳过用户确认或自动选择——必须通过当前平台可用的用户输入/确认机制明确获取用户选择后才能继续**。
 
@@ -220,8 +222,8 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须
 | `/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-verify` | 4. 验证 | Both | 验证报告 |
+| `/comet-archive` | 5. 归档与收尾 | OpenSpec | delta→main spec 同步、design doc 标注、归档提交、分支处理 |
 | `/comet-hotfix` | 预设路径 | Both | 快速修复（跳过 brainstorming） |
 | `/comet-tweak` | 预设路径 | Both | 串联 OpenSpec 的中等改动（delta spec 为一等公民，跳过 brainstorming 和完整 plan） |
 
@@ -254,24 +256,24 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须
 
 ### 状态机硬约束
 
-- `build → verify` 前，`isolation` 必须是 `branch` 或 `worktree`
+- 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.mjs build --apply` 和 `comet-state.mjs transition <name> build-complete`
+- 这些约束同时由 `comet guard <name> build --apply` 和 `comet state 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`。关键入口：
+面向 workflow 的状态、守卫、handoff 和 archive 操作统一使用稳定 `comet` CLI；只有尚无公开子命令的 intent/resume probe 才按 `comet/reference/scripts.md` 定位内部 launcher。关键入口：
 
 ```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 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>                           # 一键完成归档
 ```
 
 ### 文件结构

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

@@ -13,7 +13,7 @@
 退出条件满足且阶段守卫推进 phase 后，运行：
 
 ```bash
-node "$COMET_STATE" next <change-name>
+comet state next <change-name>
 ```
 
 脚本根据 `phase`、`workflow`、`auto_transition` 输出确定性的下一步：

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

@@ -22,6 +22,7 @@ auto_transition: true
 isolation: branch
 verify_mode: light
 verify_result: pending
+verify_failures: 0
 verification_report: null
 branch_status: pending
 created_at: 2026-05-26
@@ -43,14 +44,15 @@ archived: false
 | `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` |
+| `tdd_mode` | `tdd` 或 `direct`。full workflow 离开 build 阶段前必须已选择。`tdd` 强制每个任务先写失败测试再实现；`direct` 不强制逐任务 TDD，但仍需相关测试与 bug 回归证据。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` |
+| `isolation` | `current`、`branch` 或 `worktree`。full 初始化可为 `null`，离开 build 前必须实际创建/选择 `branch` 或 `worktree`；hotfix/tweak 默认 `current`，不得在未创建分支时虚构为 `branch` |
 | `verify_mode` | `light` 或 `full`，可为空 |
 | `auto_transition` | `true` 或 `false`。只控制阶段守卫推进 phase 后是否自动调用下一个 skill；`false` 时由 `comet-state next` 输出 `manual`，暂停下一 skill 调用，但不阻止 phase 字段更新 |
 | `verify_result` | `pending`、`pass` 或 `fail` |
+| `verify_failures` | 机器维护的连续验证失败次数；`verify-fail` 自动加一，`verify-pass` 或 `archive-reopen` 重置为 `0`。达到 `3` 后下一次失败必须进入超限策略决策 |
 | `verification_report` | 验证报告文件路径，verify 通过前必须指向已存在文件 |
-| `branch_status` | `pending` 或 `handled`，分支处理完成后设为 `handled` |
+| `branch_status` | `pending` 或 `handled`。verify 和 archive 执行期间保持 `pending`；归档改动提交且用户选择的分支处理完成后设为 `handled` |
 | `created_at` | change 创建日期（init 时自动写入），格式 `YYYY-MM-DD` |
 | `verified_at` | 验证通过时间，可为空 |
 | `archive_confirmation` | `null`、`pending` 或 `confirmed`。`verify-pass` 进入 archive 阶段时写入 `pending`；用户在 `/comet-archive` 最终确认选择「确认归档」后，`archive-confirm` transition 写入 `confirmed`；`archive-reopen` 会清空该字段，防止复用旧确认 |
@@ -64,7 +66,7 @@ archived: false
 
 ## 状态机硬约束
 
-- `build → verify` 前，`isolation` 必须是 `branch` 或 `worktree`
+- 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`

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

@@ -9,7 +9,7 @@
 用户可能直接从 `/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
+comet state check <change-name> <phase> --recover
 ```
 
 若检查结果显示实际 phase、workflow 或 evidence 应由其他 Skill 处理，按脚本输出和 `/comet` 路由规则切换；不要在错误阶段继续补写状态。若存在未提交改动，先按 `comet/reference/dirty-worktree.md` 归因。
@@ -27,7 +27,7 @@ node "$COMET_RESUME_PROBE" probe --stdin
 ## 恢复步骤
 
 ```bash
-node "$COMET_STATE" check <change-name> <phase> --recover
+comet state check <change-name> <phase> --recover
 ```
 
 脚本输出结构化恢复上下文（phase、已完成字段、待完成字段、恢复动作）。按 **Recovery action** 决定下一步。

package/assets/skills-zh/comet/reference/decision-point.md

@@ -4,6 +4,17 @@
 
 本协议由所有包含用户决策点的 comet 子 skill 共享。凡标注为“阻塞点”或“用户决策点”的步骤，都必须按本协议处理。
 
+## 先判断是否真的需要用户决策
+
+区分用户决策点、自动处理与停止条件：
+
+- **用户决策点**：存在两个或更多均合法、会改变范围、行为、风险承担或不可逆结果的选项，必须由用户选择
+- **自动处理**：只有一个安全且在当前请求范围内的下一步，例如修复明确失败、补齐可验证状态、重试幂等检查或按已持久化配置继续；直接执行并报告，不得制造确认
+- **停止条件**：依赖缺失、状态损坏、路径越界或外部命令不可用，导致当前没有合法下一步；报告阻塞原因和恢复条件，不得伪造选项
+- **手动衔接**：`NEXT: manual` 只是交还控制权，不是新的用户决策点；输出 `HINT` 后结束当前调用，不再询问“是否继续”
+
+只有第一类使用本协议。相邻且可同时回答的选择必须合并；已经持久化且仍有效的选择不得重复询问。展示选项前先检查平台能力和状态，只展示真实可执行的选项；若某字段只剩一个合法值，说明原因后直接采用，不为它单独创建停顿点。
+
 ## 核心规则
 
 - 决策点是阻塞点。到达决策点时必须暂停，等待用户明确选择后才能继续

package/assets/skills-zh/comet/reference/subagent-dispatch.md

@@ -11,9 +11,10 @@
 > 仅在以下情况才停止并等待用户输入：
 > - 任务处于 **BLOCKED** 状态（`review_mode: standard` 下风险任务 1 轮 review-fix 或最终轻量复查仍未通过，或 `review_mode: thorough` 下任务级/最终审查 2 轮审查-修复仍未通过）
 > - 存在无法从仓库、计划或既有上下文消除的真实歧义
-> - 平台没有真实后台 agent 调度能力，需要用户改选 `executing-plans`
 > - 用户**明确**要求暂停
 >
+> 后台调度能力在执行中失效属于运行停止条件，不自动构成新的用户决策点：退出派发循环并返回 `/comet-build` Step 2 的同一个联合决策，移除 `subagent-driven-development`。若只剩一个合法执行方式，说明原因后直接采用；仍有多个合法方式时才等待用户重新选择。
+>
 > 此规则适用于整个派发循环，而非单个任务。
 
 ## 开始前
@@ -34,14 +35,14 @@
 - **Claude Code**：对每个 implementer，以及 `review_mode` 要求的 task reviewer、修复 agent 和 final reviewer 使用 `Agent` 工具并设置 `run_in_background: true`。禁止内联执行 task，禁止错误进入需要预先创建 team 的团队模式。
 - **其他平台**：使用平台等效的后台 agent / Task / 多 agent 派发机制。
 - **禁止**跨 task 或角色复用 implementer、reviewer 或修复 agent。每个 agent 拥有全新的隔离上下文，并且只接收当前角色所需的单个 task 上下文。
-- 若平台无真实后台派发能力，不得继续；暂停并等待用户改选 `build_mode: executing-plans`。
+- 若真实后台派发能力在执行中失效，不得继续派发或由主会话代写实现；返回 `/comet-build` Step 2 的同一个联合决策并移除不可用模式。不得另设“是否改用 executing-plans”的停顿点；只剩一个合法模式时直接采用。
 
 ### 1. 派发 Prompt 与回报契约
 
 每个 implementer 或修复 agent prompt 必须包含：
 
 - 当前单个 task 的完整文本、架构背景和依赖上下文
-- `Language: 使用 "$COMET_BASH" "$COMET_STATE" get <name> language 读取到的 Comet 配置产物语言输出`
+- `Language: 使用 comet state get <name> language 读取到的 Comet 配置产物语言输出`
 - 允许修改的文件范围和禁止修改的范围
 - 必须执行的测试命令和提交要求
 - 修复 agent 还必须收到对应 reviewer 的完整反馈
@@ -142,8 +143,8 @@ Comet 不读取、不写入、也不要求任何 Superpowers `subagent-driven-de
 4. 运行定向验证：
 
 ```bash
-node "$COMET_STATE" task-checkoff "$PLAN_FILE" "$PLAN_TASK_TEXT"
-node "$COMET_STATE" task-checkoff "openspec/changes/<name>/tasks.md" "$OPENSPEC_TASK_TEXT"
+comet state task-checkoff <plan-file> <plan-task-text>
+comet state task-checkoff openspec/changes/<name>/tasks.md <openspec-task-text>
 ```
 
 仅在对应映射存在时运行第二条。脚本会要求任务文本恰好出现一次且该项已勾选；验证失败时不得进入下一个 task。

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

@@ -1,6 +1,6 @@
 ---
 name: comet-any
-description: "Use when 用户想定制 Comet 五阶段 Skill、创建 workflow Skill、整理已有 Skill，或用 Workflow Node / Skill Binding / Output Schema 编排 Skill。"
+description: "仅在用户明确调用 /comet-any，或明确要求定制 Comet 五阶段流程、创建或升级由 Comet Creator 管理的 workflow Skill 时使用；不要用于一般 Skill 的编写、整理或评审。"
 ---
 
 # Comet Any - Skill Creator

package/assets/skills-zh/comet-any/reference/authored-zone-example.md

@@ -62,21 +62,26 @@ Decision Core 应建模 Auto 区不处理的三件事：(1) **语义化当前节
 - 若状态显示某 Node 已完成但预期 artifact 缺失，视为未完成并重新进入。
 - 若用户在某个 Node 中途恢复但话题变了，确认是继续当前 Node 还是开始新的。
 
-### 决策点（必须暂停）
+### 决策分类与决策点
+
+先分类再行动：有两个或以上会改变范围、行为、风险接受或不可逆结果的合法选项才是用户决策；唯一安全下一步直接执行；缺少依赖、状态损坏或无法继续的 guard 失败是停止条件；`NEXT: manual` 只是交还控制权。只有第一类必须暂停。
 
 | 情况 | 处理 |
 |------|------|
-| 首次调用，无 workflow 状态 | 初始化状态，在开始第一个 Node 前与用户确认主题/范围 |
-| 用户输入在两个 Node 间有歧义 | 询问用户指哪个 Node；不要猜测 |
+| 首次调用且主题/范围明确 | 自动初始化状态并进入第一个 Node；不得为了确认已知信息而停顿 |
+| 主题、范围或目标 Node 存在两个以上互斥且合法的解释 | 合并为一个问题，让用户选择；不要猜测 |
 | Node 需要用户确认输出才能推进 | 记录 evidence 后停下；等待明确确认 |
-| Node guard 失败且原因不明 | 展示 guard 输出，询问用户如何继续 |
+| WARNING/偏差接受或不可逆发布存在真实取舍 | 只展示当前可执行选项，并记录用户选择 |
+
+Node guard 失败时先自动读取证据并执行唯一安全修复；若缺少依赖或状态损坏导致无法继续，报告停止条件和恢复要求。只有恢复方式存在多个会改变范围或风险的合法选项时，才升级为上表中的用户决策。
 
 ### Red Flags
 
 | Agent 想法 | 实际风险 |
 |-----------|---------|
-| "用户提到了主题，所以研究隐式确认" | 提到 ≠ 确认。在第一个 Node 边界暂停并确认范围。 |
+| "首次调用都应该再确认一次" | 清晰输入不需要重复批准；只有互斥解释仍会改变范围时才询问。 |
 | "脚本返回 NEXT: auto，应该立即加载下一个 Skill" | `NEXT: auto` 表示 Node 完成，不是跳过确认。检查下一个 Node 是否有决策点。 |
+| "guard 失败，所以让用户决定怎么办" | 先自动诊断并执行唯一安全修复；无合法动作时报告停止条件，不要发明选项。 |
 | "看起来和上次一样的话题，从上次断点继续" | 始终重新读取状态。对话记忆在上下文压缩后不可靠。 |
 | "Exit Check 通过了，所以工作够好了" | Exit Check 是机械的。你的职责是判断检查之外的质量——稀疏笔记、浅层分析、缺失视角，脚本抓不到。 |
 ```