@rpamis/comet 0.2.9 → 0.3.1

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

@@ -1,14 +1,14 @@
 ---
 name: comet-verify
-description: "Comet Phase 4: Verify and Complete. Invoke with /comet-verify. Verify implementation matches design, handle development branch."
+description: "Comet Phase 4: Verify and Close. Invoke with /comet-verify. Verify implementation matches design, handle development branch."
 ---
 
-# Comet Phase 4: Verify and Complete (Verify)
+# Comet Phase 4: Verify and Close (Verify)
 
 ## Prerequisites
 
-- Code has been committed (Phase 3 complete)
-- All tasks in tasks.md are complete
+- Code committed (Phase 3 complete)
+- All tasks.md tasks completed
 
 ## Steps
 
@@ -20,51 +20,78 @@ Execute entry verification:
 COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
 COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
 COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
-bash "$COMET_STATE" check <name> verify
+bash "$COMET_STATE" check <change-name> verify
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
 
-### 1. Change Scale Assessment
+### 1. Scale Assessment
 
 Execute scale assessment:
 
 ```bash
-bash "$COMET_STATE" scale <name>
+bash "$COMET_STATE" scale <change-name>
 ```
 
-Script automatically counts tasks, delta specs, and changed files to determine whether to use light or full verification mode, and sets the verify_mode field.
+The script automatically counts tasks, delta spec count, changed file count, determines light or full verification mode, and sets the verify_mode field.
 
-Note: if the build phase committed after each task, worktree diff can underestimate change size. In that case, read the plan header `base-ref` and re-check the full commit range:
+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
+
+Only after user chooses fix, allow rollback to build phase:
 
 ```bash
-PLAN=$(bash "$COMET_STATE" get <name> plan)
+# Execute only after user confirms fix
+bash "$COMET_STATE" transition <change-name> verify-fail
+```
+
+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=$(bash "$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 the commit range exceeds lightweight thresholds (> 5 files, cross-module coordination, or more than 1 delta spec capability), manually switch to full verification:
+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:
 
 ```bash
-bash "$COMET_STATE" set <name> verify_mode full
+bash "$COMET_STATE" set <change-name> verify_mode full
 ```
 
+### 1b. Verification Failure Decision (Blocking Point)
+
+When verification does not pass, must pause and wait for the user to decide fix or accept deviation. Must not automatically run `bash "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`.
+
+When pausing, must list:
+- Failed items
+- Whether CRITICAL (build failure, test failure, security issues, core acceptance scenario failure)
+- Recommended handling approach
+
+After user selection, continue as follows:
+- **Fix all**: Run `bash "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build` to fix
+- **Handle item by item**: CRITICAL failures must be fixed; non-CRITICAL failures may choose to accept deviation, but must record acceptance reason and impact scope in verification report. If any CRITICAL failure exists, skipping fix to accept all is not allowed
+
 ### 2a. Lightweight Verification (Small Changes)
 
-When scale assessment result is "small", skip `openspec-verify-change`, directly execute the following checks:
+When scale assessment result is "small", skip `openspec-verify-change` and directly execute these checks:
 
-1. All tasks in tasks.md completed `[x]`
-2. Changed files consistent with tasks.md description (compare `git diff --stat` against task content)
-3. Build passes (run project-appropriate build command, e.g., `npm run build`, `mvn compile`, `cargo build`)
+1. All tasks.md tasks completed `[x]`
+2. Changed files match tasks.md descriptions (`git diff --stat` / `git diff --cached --stat` / `git diff --stat <base-ref>...HEAD` compared against tasks content)
+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 secrets, no new unsafe operations)
+5. No obvious security issues (no hardcoded keys, no new unsafe operations)
 
-**Pass standard**: All 5 items OK, no CRITICAL issues.
+**Pass criteria**: All 5 items OK, no CRITICAL issues.
 
-**When failing**: report failed items, record failure, move back to build, then invoke `/comet-build`.
+**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:
 
 ```bash
-bash "$COMET_STATE" transition <name> verify-fail
+# Execute only after user confirms fix
+bash "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Report format**: Brief table listing 5 check results + PASS/FAIL.
@@ -72,7 +99,7 @@ bash "$COMET_STATE" transition <name> verify-fail
 **Skipped items** (not checked in lightweight verification):
 - spec scenario coverage
 - design doc consistency deep comparison
-- code pattern consistency recommendations
+- code pattern consistency suggestions
 - delta spec and design doc drift detection
 
 ### 2b. Full Verification (Large Changes)
@@ -82,58 +109,76 @@ When scale assessment result is "large":
 **Immediately execute:** Use the Skill tool to load the `openspec-verify-change` skill. Skipping this step is prohibited.
 
 After the skill loads, follow its guidance to verify. Check items:
-1. All tasks in tasks.md completed (`[x]`)
-2. Implementation matches design.md design decisions
-3. Implementation matches brainstorming design document
-4. All capability specification scenarios pass
-5. proposal.md goals satisfied
-6. No contradiction between delta spec and design doc (if Build phase had incremental spec modifications, check if design doc has corresponding records)
-7. `docs/superpowers/specs/` associated design document can be located (file exists and relates to current change)
+1. All tasks.md tasks completed (`[x]`)
+2. Implementation matches `openspec/changes/<name>/design.md` high-level design decisions
+3. Implementation matches Design Doc (technical design documents under `docs/superpowers/specs/`)
+4. All capability spec scenarios pass
+5. proposal.md goals are satisfied
+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 fails: report missing items, record failure, move back to build, then invoke `/comet-build`.
+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:
 
 ```bash
-bash "$COMET_STATE" transition <name> verify-fail
+# Execute only after user confirms fix
+bash "$COMET_STATE" transition <change-name> verify-fail
 ```
 
-**Spec drift handling**:
-- If check item 6 finds contradiction (delta spec has content but design doc doesn't reflect it), prompt user:
-  - Option A: Append "Implementation Divergence" section to design doc recording deviation reason
-  - Option B: Roll back to Build phase, supplement brainstorming to update design doc
-  - Option C: Confirm deviation acceptable, continue verification (design doc will be marked as `superseded-by-main-spec` during archiving)
+**Spec Drift Handling** (user decision point):
+- If check item 6 finds contradictions (delta spec has content but design doc does not reflect it), **must pause and wait for user to choose 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 `bash "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`; `/comet-build`'s Spec Incremental Update rules will load `superpowers:brainstorming` 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. Completion (Superpowers)
+### 3. Finishing (Superpowers)
 
 **Immediately execute:** Use the Skill tool to load the `superpowers:finishing-a-development-branch` skill. Skipping this step is prohibited.
 
 If `superpowers:finishing-a-development-branch` 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 complete. Branch handling options:
-1. Local merge to main branch
+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
 
+This is a user decision point. **Must pause and wait for 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 secrets or security issues
+- 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.
+
+```bash
+mkdir -p docs/superpowers/reports
+# Write verification conclusions to report file, e.g.:
+# docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+
+bash "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+bash "$COMET_STATE" set <change-name> branch_status handled
+```
 
 ## Exit Conditions
 
 - Verification report passed
 - Branch handled
-- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> verify --apply`; after all PASS, it uses `comet-state transition verify-pass` to advance to `phase: archive`
+- `verification_report` in `.comet.yaml` points to an existing verification report file
+- `branch_status: handled` in `.comet.yaml`
+- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> verify --apply`; after all PASS, auto-transitions to `phase: archive` through `comet-state transition verify-pass`
 
-After verification and branch handling are complete, run guard to auto-transition:
+After both verification and branch handling are complete, run guard for auto-transition:
 
 ```bash
 bash "$COMET_GUARD" <change-name> verify --apply
 ```
 
-State file is automatically updated to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
+State file auto-updates to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
 
 ## Automatic Transition
 
 After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
 
-> **REQUIRED NEXT SKILL:** Invoke `comet-archive` skill to enter the archiving phase.
+> **REQUIRED NEXT SKILL:** Invoke `comet-archive` skill to enter the archive phase.

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

@@ -52,8 +52,9 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 **断点恢复规则**：
 - 每次恢复上下文时，先重新执行 Step 0 和 Step 1，不依赖对话历史判断阶段
-- 若 `phase: build`，读取 tasks.md 的下一个未勾选任务继续
-- 若 `phase: verify` 且 `verify_result: fail`，先运行 `bash "$COMET_STATE" transition <name> verify-fail`，再调用 `/comet-build`
+- 只要存在 active change 且工作区有未提交改动，必须按 `comet/reference/dirty-worktree.md` 协议处理。该协议定义了检查步骤、归因分类和禁令，本文件不重复
+- 若 `phase: build`，先检查 `build_mode` 和 `isolation` 是否已设置；若有未设置的字段，回到 `/comet-build` 对应步骤补充后再执行；若均已设置，读取 tasks.md 的下一个未勾选任务继续
+- 若 `phase: verify` 且 `verify_result: fail`，进入验证失败决策阻塞点：暂停并询问用户修复或接受偏差；用户选择修复后才运行 `bash "$COMET_STATE" transition <name> verify-fail` 并调用 `/comet-build`
 - 若 `phase: open` 但 proposal/design/tasks 已完整，先运行 `bash "$COMET_GUARD" <change-name> open --apply` 修正状态，再继续判定
 - 若 `phase: archive`，只允许调用 `/comet-archive`；归档成功后 change 会移动到 archive 目录，不再对原活跃目录运行 guard
 
@@ -61,9 +62,9 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 1. `archived: true` 或 change 已移入 archive → 流程已完成
 2. `verify_result: pass` 且 `archived` 不是 `true` → `/comet-archive`
-3. `verify_result: fail` → `bash "$COMET_STATE" transition <name> verify-fail` 后 `/comet-build`
+3. `verify_result: fail` → 进入验证失败决策阻塞点（暂停询问修复或接受偏差；用户选择修复后才 `verify-fail` 并 `/comet-build`）
 4. `phase: verify` 或 tasks.md 全部勾选 → `/comet-verify`
-5. `phase: build` 或已有 Design Doc 但计划/执行未完成 → `/comet-build`
+5. `phase: build` 或已有 Design Doc 但计划/执行未完成 → 优先按 workflow 路由：`hotfix` → `/comet-hotfix`，`tweak` → `/comet-tweak`，`full` → `/comet-build`
 6. `phase: design` 或有 change 但无 Design Doc → `/comet-design`
 7. `phase: open` 或有活跃 change 但 `.comet.yaml` 缺失 → `/comet-open`
 8. 无活跃 change → `/comet-open`
@@ -102,14 +103,17 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 流转链：open → design → build → verify → archive
 
-**连续执行要求**：从检测到的阶段开始，agent 必须自动走完后续所有阶段，中间不停顿等待用户输入（除非遇到需要用户决策的节点）。每个阶段完成后立即进入下一阶段，无需用户再次输入。
+**连续执行要求**：从检测到的阶段开始，agent 必须自动推进后续阶段；自动推进只适用于没有用户决策的衔接点。遇到用户决策点时必须暂停并等待用户明确回复，不得用推荐规则、默认值或历史偏好代替用户确认。
+
+**决策点是阻塞点**：只要到达下列任一节点，当前 `/comet` 调用必须停住。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。
 
 需要用户参与的节点（仅在这些节点暂停）：
 1. brainstorming 确认设计方案
-2. build 阶段选择执行方式
-3. verify 不通过时决定修复或接受偏差
+2. build 阶段选择工作方式（隔离方式 + 执行方式，一次交互完成）
+4. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择）
 4. finishing-branch 选择分支处理方式
 5. 遇到升级条件（hotfix/tweak → 完整流程）
+6. build 阶段范围扩张需重新设计或拆分新 change
 
 agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。
 </IMPORTANT>
@@ -136,11 +140,11 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须
 
 /comet-hotfix（预设路径，跳过 brainstorming）
   open ──→ build ──→ verify ──→ archive
-    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
+    ↑ 如触发升级条件 → 阻塞确认升级 → 补充 Design Doc → 回到完整流程
 
 /comet-tweak（预设路径，跳过 brainstorming 和完整 plan）
   open ──→ lightweight build ──→ light verify ──→ archive
-    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
+    ↑ 如触发升级条件 → 阻塞确认升级 → 补充 Design Doc → 回到完整流程
 ```
 
 ---
@@ -154,12 +158,14 @@ workflow: full
 phase: build
 design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+base_ref: a1b2c3d4e5f6...
 build_mode: subagent-driven-development
 isolation: branch
 verify_mode: light
 verify_result: pending
 verification_report: null
 branch_status: pending
+created_at: 2026-05-26
 verified_at: null
 archived: false
 ```
@@ -170,12 +176,14 @@ archived: false
 | `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` | 已选择的执行方式，可为空 |
 | `isolation` | `branch` 或 `worktree`，工作区隔离方式。full 初始化可为 `null`，但只允许持续到 `/comet-build` Step 3 前；hotfix/tweak 默认 `branch` |
 | `verify_mode` | `light` 或 `full`，可为空 |
 | `verify_result` | `pending`、`pass` 或 `fail` |
 | `verification_report` | 验证报告文件路径，verify 通过前必须指向已存在文件 |
 | `branch_status` | `pending` 或 `handled`，分支处理完成后设为 `handled` |
+| `created_at` | change 创建日期（init 时自动写入），格式 `YYYY-MM-DD` |
 | `verified_at` | 验证通过时间，可为空 |
 | `archived` | change 是否已归档 |
 

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

@@ -0,0 +1,58 @@
+# Dirty Worktree 协议
+
+规范路径：`comet/reference/dirty-worktree.md`
+
+本协议由所有涉及代码修改的 comet 子 skill 共享。当 agent 恢复上下文或继续执行时，必须按本协议处理未提交的工作区改动。
+
+## 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 状态里显示为 `??` 的新建文件），就先假设改动可能来自用户或混合来源
+- 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-build/SKILL.md

@@ -58,9 +58,11 @@ bash "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 
 无需手动更新 phase，guard 会在退出条件满足后自动流转。
 
-### 3. 工作区隔离
+### 3. 选择工作方式
 
-计划已写入当前分支。在开始执行前，选择工作区隔离方式：
+计划已写入当前分支。在开始执行前，**一次性询问用户**选择工作区隔离方式和执行方式：
+
+**工作区隔离**：
 
 | 选项 | 方式 | 说明 |
 |------|------|------|
@@ -71,52 +73,30 @@ bash "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 - 变更涉及 ≤ 3 个文件 → 推荐 A
 - 需要并行开发、当前分支有未提交工作 → 推荐 B
 
-用户选择后，更新 `isolation` 字段。`isolation` 只允许以下值之一：
-
-```bash
-bash "$COMET_STATE" set <name> isolation <value>
-```
-
-- `branch`
-- `worktree`
-
-<IMPORTANT>
-这是脚本级硬约束，不是建议。full workflow 初始化时 `isolation` 可以暂时为 `null`，但只允许存在到本步骤之前。
-进入实现前必须停下来询问用户并写入 `branch` 或 `worktree`。若保持 `null`，`build → verify` 的 guard 和 `comet-state transition build-complete` 都会失败。
-</IMPORTANT>
-
-**执行隔离**：
-
-- **branch**：执行 `git checkout -b <change-name>`，后续工作在新分支上进行
-- **worktree**：调用 `superpowers:using-git-worktrees` 技能或使用原生 `EnterWorktree` 工具创建隔离工作区
-
-创建隔离后，确认计划文件可访问（分支方式天然可访问；worktree 方式需确认计划已提交）。
-
-### 4. 选择执行方式
-
-向用户展示计划摘要（任务数、涉及模块），然后询问执行方式：
+**执行方式**：
 
 | 选项 | 技能 | 适用场景 |
 |------|------|---------|
 | A | `superpowers:subagent-driven-development` | 任务独立、复杂度高、需要双阶段审查 |
 | B | `superpowers:executing-plans` | 任务简单、无子agent环境、轻量快速 |
 
-**推荐规则**：
+**执行方式推荐规则**：
 - 任务数 ≥ 3 → 推荐 A
 - 任务数 ≤ 2 且无跨模块依赖 → 推荐 B
 - 来自 hotfix 路径 → 推荐 B
 
-用户选择后，更新 `build_mode` 字段。`build_mode` 只允许以下值之一：
+这是用户决策点。必须暂停并等待用户明确选择隔离方式和执行方式，**不得根据推荐规则自行选择 `branch` 或 `worktree`**，也**不得根据推荐规则自行选择执行方式**。推荐规则只能用于说明建议，不能替代用户确认。
+
+用户选择后，更新 `isolation` 和 `build_mode` 字段：
 
 ```bash
-bash "$COMET_STATE" set <name> build_mode <value>
+bash "$COMET_STATE" set <name> isolation <branch|worktree>
+bash "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
 ```
 
-- `subagent-driven-development`
-- `executing-plans`
-- `direct`（默认仅 hotfix/tweak preset 使用）
+`isolation` 是脚本级硬约束。full workflow 初始化时可以为 `null`，但只允许存在到本步骤之前。若保持 `null`，`build → verify` 的 guard 和 `comet-state transition build-complete` 都会失败。
 
-full workflow 不得默认使用 `direct`。只有用户明确要求跳过计划执行技能，且你已记录显式 override 时，才允许：
+`build_mode` 默认仅 hotfix/tweak preset 使用 `direct`。full workflow 不得默认使用 `direct`。只有用户明确要求跳过计划执行技能，且你已记录显式 override 时，才允许：
 
 ```bash
 bash "$COMET_STATE" set <name> direct_override true
@@ -125,7 +105,14 @@ bash "$COMET_STATE" set <name> build_mode direct
 
 没有 `direct_override: true` 时，full workflow 的 `build_mode=direct` 会被 guard 和状态转换同时拦截。
 
-然后，**立即执行：** 使用 Skill 工具加载对应技能。禁止跳过此步骤。
+**执行隔离**：
+
+- **branch**：执行 `git checkout -b <change-name>`，后续工作在新分支上进行
+- **worktree**：必须使用 Skill 工具加载 `superpowers:using-git-worktrees` 技能创建隔离工作区。禁止用普通 shell 命令或原生工具绕过该技能；如该技能不可用，停止流程并提示安装或启用 Superpowers 技能。
+
+创建隔离后，确认计划文件可访问（分支方式天然可访问；worktree 方式需确认计划已提交）。
+
+**加载执行技能**：使用 Skill 工具加载对应技能。禁止跳过此步骤。
 
 如所选 Superpowers 技能不可用，停止流程并提示安装或启用对应技能，不要用普通对话替代该步骤。
 
@@ -134,17 +121,19 @@ bash "$COMET_STATE" set <name> build_mode direct
 - 完成 tasks.md 勾选（`- [ ]` → `- [x]`）
 - 每个任务完成后提交代码
 
-### 5. Spec 增量更新
+### 4. Spec 增量更新
 
 实施过程中发现初版 spec 不完整时，按变更规模分级处理：
 
 | 规模 | 触发条件 | 做法 |
 |------|---------|------|
 | 小 | 遗漏验收场景、边界条件 | 直接编辑 delta spec + design.md，追加 tasks.md 任务 |
-| 中 | 接口变更、新增组件、数据流变化 | 重新 `superpowers:brainstorming` 更新 Design Doc + delta spec |
-| 大 | 全新 capability 需求 | `/opsx:new` 创建独立 change |
+| 中 | 接口变更、新增组件、数据流变化 | 暂停并等待用户确认后，必须使用 Skill 工具加载 `superpowers:brainstorming` 更新 Design Doc + delta spec |
+| 大 | 全新 capability 需求 | 必须暂停并等待用户确认拆分；用户确认后，通过 `/comet-open` 创建独立 change |
+
+**50% 阈值判定**：以 tasks.md 初始任务总数为基准，若新增任务数超过该总数的一半，视为超出原计划范围，必须暂停并等待用户决定是否拆分为新 change。
 
-**50% 阈值判定**：以 tasks.md 初始任务总数为基准，若新增任务数超过该总数的一半，视为超出原计划范围，应考虑拆分为新 change。
+创建独立 change 时必须调用 `/comet-open`，不得直接调用 `/opsx:new`。`/comet-open` 会同时创建 OpenSpec 产物和 `.comet.yaml`，避免新 change 脱离 Comet 状态机。
 
 **原则**：
 - delta spec 是活文档，本阶段期间随时可修改
@@ -152,12 +141,14 @@ bash "$COMET_STATE" set <name> build_mode direct
 - 不提前同步到 main spec，归档时统一同步
 - 小规模增量直接改 delta spec 时，应在 commit message 中注明，便于归档时判断 design doc 漂移
 
-### 6. 上下文管理
+### 5. 上下文管理
 
 Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后断点恢复：
 
 - **每完成一个 task**：立即勾选 tasks.md 并提交代码，确保 `.comet.yaml` 和文件状态持久化
 - **上下文压缩后恢复**：读取 `.comet.yaml` 的 `phase` 字段确认仍在 build 阶段，读取 plan 文件头的 `base-ref`，再读取 tasks.md 找到下一个未勾选任务继续执行
+- **用户手动修改恢复**：按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。该协议定义了检查步骤、归因分类和禁令。build 阶段的特殊处理：
+  1. 归因后，若 diff 暗示计划或 spec 已变化，按 Step 4「Spec 增量更新」分级处理
 - **长任务拆分**：单任务超过 200 行代码变更时，考虑拆分为多个子任务分别提交
 
 ## 退出条件

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

@@ -92,23 +92,41 @@ canonical_spec: openspec
 
 如 `superpowers:brainstorming` 不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。
 
-技能加载后，按其指引产出：
-- `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` — 设计文档（技术 RFC）
-- 如需补充验收场景，回写 `openspec/changes/<name>/specs/<capability>/spec.md` — OpenSpec delta 能力规格
+技能加载后，按其指引产出设计方案（以对话形式呈现）：
+- 技术方案：架构、数据流、关键技术选型与风险
+- 测试策略
+- 如需补充验收场景，标明将回写的 delta spec 变更
+
+brainstorming 阶段不写入 Design Doc 文件，仅产出设计方案供 Step 1c 用户确认。确认后才创建 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` 并回写 delta spec。
+
+### 1c. 用户确认设计方案（阻塞点）
+
+brainstorming 产出设计方案后，**必须暂停并等待用户明确确认设计方案**。不得在用户确认前创建最终 Design Doc、写入 `design_doc`、运行 design guard，或进入 `/comet-build`。
+
+暂停时只展示必要摘要：
+- 采用的技术方案
+- 关键取舍与风险
+- 测试策略
+- 如有 Spec Patch，列出将回写的 delta spec 变更
+
+用户明确确认后，才继续 Step 2。若用户要求调整，继续 brainstorming 迭代，直到用户确认。
 
 ### 2. 更新 Comet 状态
 
-先记录 design_doc 路径，再运行 guard 自动流转：
+先记录 design_doc 路径。如果 Step 1c 回写了 delta spec（新增或修改了 `specs/*/spec.md`），必须重新生成 handoff 以更新 hash：
 
 ```bash
 # 记录 design_doc 路径
 bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
+# 如有 delta spec 变更，重新生成 handoff（更新 hash）
+bash "$COMET_HANDOFF" <change-name> design --write
+
 # 自动流转到下一阶段
 bash "$COMET_GUARD" <change-name> design --apply
 ```
 
-状态文件自动更新，无需手动编辑其他字段。
+如果没有 delta spec 变更，跳过 handoff 重新生成步骤。状态文件自动更新，无需手动编辑其他字段。
 
 ## 退出条件
 

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

@@ -63,6 +63,8 @@ bash "$COMET_GUARD" <change-name> open --apply
 
 使用 hotfix 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`（除非任务 > 3 个；若超过 3 个任务，转入 `/comet-build` 的计划与执行方式选择）。
 
+继续或开始修改前，按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。若归因后发现修复范围超出 hotfix，按本文件“升级条件”处理。
+
 **立即执行：** 按 tasks.md 逐个执行任务：
 
 1. 读取 `openspec/changes/<name>/tasks.md`，获取未完成任务列表
@@ -73,33 +75,34 @@ bash "$COMET_GUARD" <change-name> open --apply
    - 将 tasks.md 中对应 `- [ ]` 勾选为 `- [x]`
    - 提交代码，commit message 格式：`fix: <简述修复>`
 3. 全部任务完成后，显式运行项目相关测试和构建命令
-4. 运行阶段守卫完成 build → verify 过渡：
-
-```bash
-bash "$COMET_GUARD" <change-name> build --apply
-```
-
-状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
 
 **如修复影响已有 spec 验收场景**：
 - 在 `openspec/changes/<name>/specs/<capability>/spec.md` 创建 delta spec
 - 仅包含 `## MODIFIED Requirements` 部分
 
-### 3a. Hotfix 专属检查：根因消除
+### 3. 根因消除检查
 
-**在加载 comet-verify 之前执行**，确保修复确实消除了问题根因：
+**在运行 build guard 之前执行**，确保修复确实消除了问题根因：
 
 1. 读取 proposal.md 中的 bug 描述和根因
 2. 搜索验证问题代码不再存在
-3. 如根因未消除，返回 Step 2 继续修复
+3. 如根因未消除，回到 Step 2 继续修复（此时仍在 build 阶段，无需状态回退）
 
 **升级条件**：
-- 根因消除检查发现深层架构问题 → 停止 hotfix，升级为 `/comet`
-- 修复需要额外接口变更 → 停止 hotfix，升级为 `/comet`
+- 根因消除检查发现深层架构问题 → 停止 hotfix，按升级条件阻塞确认处理
+- 修复需要额外接口变更 → 停止 hotfix，按升级条件阻塞确认处理
+
+根因确认消除后，运行阶段守卫完成 build → verify 过渡：
+
+```bash
+bash "$COMET_GUARD" <change-name> build --apply
+```
 
-### 3b. 验证（preset verify）
+状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
 
-根因消除检查通过后，复用 `/comet-verify`，由 comet-verify 的规模评估决定轻量或完整验证。
+### 4. 验证（preset verify）
+
+复用 `/comet-verify`，由 comet-verify 的规模评估决定轻量或完整验证。
 
 **立即执行：** 使用 Skill 工具加载 `comet-verify` 技能。禁止跳过此步骤。
 
@@ -119,11 +122,15 @@ bash "$COMET_GUARD" <change-name> build --apply
 ## 连续执行模式
 
 <IMPORTANT>
-Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent 必须自动走完全部 4 个阶段，中间不停顿等待用户输入（除非遇到升级条件需要用户确认）。
+Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent 在 hotfix 自有步骤间自动推进，不主动停顿。但以下情况必须暂停等待用户确认：
+
+1. 遇到升级条件（见"升级条件"章节）
+2. 任务超过 3 个转入 `/comet-build` 时的工作区隔离和执行方式选择
+3. 验证阶段（comet-verify）的验证失败决策和分支处理决策
 
 执行顺序：快速开启 → 直接构建 → 验证 → 归档 → 完成
 
-每个阶段完成后立即进入下一阶段，无需用户再次输入。阶段内部仍必须按上文要求调用对应 Comet/OpenSpec/Superpowers skill。
+每个阶段完成后立即进入下一阶段。阶段内部仍必须按上文要求调用对应 Comet/OpenSpec/Superpowers skill，被调用的 skill 如有自己的用户决策点，按该 skill 规则执行。
 </IMPORTANT>
 
 ---
@@ -140,7 +147,15 @@ Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent
 | 引入新的 public API | 修复产生了新的对外接口 |
 | 修复范围超出单一函数/模块 | 需要多处协调修改 |
 
-升级方式：在当前 change 基础上补充 Design Doc（执行 `/comet-design`），后续正常走完整流程。
+满足升级条件时必须暂停并等待用户明确确认升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。
+
+用户确认升级后，**必须先更新 workflow 字段**再进入完整流程：
+
+```bash
+bash "$COMET_STATE" set <name> workflow full
+```
+
+然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**，后续正常走完整流程。若用户不确认升级，停止 hotfix 并报告当前变更已超出 hotfix 适用范围。
 
 ---