@rpamis/comet 0.3.4 → 0.3.6

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

@@ -23,17 +23,19 @@ if [ -z "$COMET_ENV" ]; then
   return 1
 fi
 . "$COMET_ENV"
-bash "$COMET_STATE" check <name> design
+"$COMET_BASH" "$COMET_STATE" check <name> design
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
 
+**幂等性**：所有 design 阶段操作可以安全重试。如果 `handoff_context` 和 `handoff_hash` 已存在，先确认它们与当前产物一致再决定是否重新生成。
+
 ### 1a. 生成 OpenSpec → Superpowers 交接包
 
 **必须由脚本生成，不允许 agent 临场手写 summary 代替。**
 
 ```bash
-bash "$COMET_HANDOFF" <change-name> design --write
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
 ```
 
 脚本会生成并记录：
@@ -58,7 +60,7 @@ handoff_hash: <sha256>
 如确实需要全文上下文，可显式运行：
 
 ```bash
-bash "$COMET_HANDOFF" <change-name> design --write --full
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write --full
 ```
 
 交接包来源来自 OpenSpec open 阶段产物：
@@ -69,7 +71,7 @@ bash "$COMET_HANDOFF" <change-name> design --write --full
 
 ### 1b. 执行 Brainstorming（带上下文）
 
-**立即执行：** 使用 Skill 工具加载 `superpowers:brainstorming` 技能，ARGUMENTS 包含：
+**立即执行：** 使用 Skill 工具加载 Superpowers `brainstorming` 技能，ARGUMENTS 包含：
 
 ```
 Change: <change-name>
@@ -92,7 +94,7 @@ canonical_spec: openspec
 
 禁止跳过此步骤，禁止在未加载该技能的情况下继续。
 
-如 `superpowers:brainstorming` 不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。
+如 Superpowers `brainstorming` 技能不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。
 
 技能加载后，按其指引产出设计方案（以对话形式呈现）：
 - 技术方案：架构、数据流、关键技术选型与风险
@@ -103,7 +105,7 @@ brainstorming 阶段不写入 Design Doc 文件，仅产出设计方案供 Step
 
 ### 1c. 用户确认设计方案（阻塞点）
 
-brainstorming 产出设计方案后，**必须暂停并等待用户明确确认设计方案**。不得在用户确认前创建最终 Design Doc、写入 `design_doc`、运行 design guard，或进入 `/comet-build`。
+brainstorming 产出设计方案后，**必须使用 AskUserQuestion 工具暂停并等待用户明确确认设计方案**。不得在用户确认前创建最终 Design Doc、写入 `design_doc`、运行 design guard，或进入 `/comet-build`。也不得仅输出文字提示后继续执行。
 
 暂停时只展示必要摘要：
 - 采用的技术方案
@@ -119,13 +121,13 @@ brainstorming 产出设计方案后，**必须暂停并等待用户明确确认
 
 ```bash
 # 记录 design_doc 路径
-bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+"$COMET_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
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
 
 # 自动流转到下一阶段
-bash "$COMET_GUARD" <change-name> design --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
 ```
 
 如果没有 delta spec 变更，跳过 handoff 重新生成步骤。状态文件自动更新，无需手动编辑其他字段。
@@ -139,16 +141,26 @@ bash "$COMET_GUARD" <change-name> design --apply
 - `design-context.md` 必须是脚本生成，且包含 source path、mode、sha256 等可追溯标记（由 guard 强制校验）
 - 如有新能力或补充验收场景，OpenSpec delta spec 已创建/更新
 - `design_doc` 已写入 `.comet.yaml`
-- **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> design --apply`，全部 PASS 后自动流转到 `phase: build`
+- **阶段守卫**：运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply`，全部 PASS 后自动流转到 `phase: build`
 
 退出前必须使用 `--apply`：
 
 ```bash
-bash "$COMET_GUARD" <change-name> design --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
 ```
 
+## 上下文压缩恢复
+
+design 阶段在 brainstorming 过程中可能触发上下文压缩。恢复时先运行：
+
+```bash
+"$COMET_BASH" "$COMET_STATE" check <change-name> design --recover
+```
+
+脚本输出结构化恢复上下文（阶段、已完成字段、待完成字段、恢复动作）。按 Recovery action 判断下一步。
+
 ## 自动流转
 
-退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+退出条件满足后（包括用户确认设计方案），自动流转到下一阶段：
 
 > **REQUIRED NEXT SKILL:** 调用 `comet-build` skill 进入计划与构建阶段。

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

@@ -46,24 +46,24 @@ fi
 初始化 Comet 状态文件：
 
 ```bash
-bash "$COMET_STATE" init <name> hotfix
+"$COMET_BASH" "$COMET_STATE" init <name> hotfix
 ```
 
 初始化后验证状态：
 
 ```bash
-bash "$COMET_STATE" check <name> open
+"$COMET_BASH" "$COMET_STATE" check <name> open
 ```
 
 阶段守卫完成 open → build 过渡：
 
 ```bash
-bash "$COMET_GUARD" <change-name> open --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
 ```
 
 ### 2. 直接构建（preset build）
 
-使用 hotfix 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`（除非任务 > 3 个；若超过 3 个任务，转入 `/comet-build` 的计划与执行方式选择）。
+使用 hotfix 默认值：`build_mode: direct`。跳过 Superpowers `brainstorming` 和 `writing-plans`（除非任务 > 3 个；若超过 3 个任务，转入 `/comet-build` 的计划与执行方式选择）。
 
 继续或开始修改前，按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。若归因后发现修复范围超出 hotfix，按本文件“升级条件”处理。
 
@@ -97,7 +97,7 @@ bash "$COMET_GUARD" <change-name> open --apply
 根因确认消除后，运行阶段守卫完成 build → verify 过渡：
 
 ```bash
-bash "$COMET_GUARD" <change-name> build --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
@@ -126,7 +126,7 @@ bash "$COMET_GUARD" <change-name> build --apply
 <IMPORTANT>
 Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent 在 hotfix 自有步骤间自动推进，不主动停顿。但以下情况必须暂停等待用户确认：
 
-1. 遇到升级条件（见"升级条件"章节）
+1. 遇到升级条件（见"升级条件"章节），**必须使用 AskUserQuestion 工具暂停并等待用户明确确认**升级为完整流程
 2. 任务超过 3 个转入 `/comet-build` 时的工作区隔离和执行方式选择
 3. 验证阶段（comet-verify）的验证失败决策和分支处理决策
 
@@ -149,12 +149,12 @@ Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent
 | 引入新的 public API | 修复产生了新的对外接口 |
 | 修复范围超出单一函数/模块 | 需要多处协调修改 |
 
-满足升级条件时必须暂停并等待用户明确确认升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。
+满足升级条件时**必须使用 AskUserQuestion 工具暂停并等待用户明确确认**升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。不得仅输出文字提示后继续执行。
 
 用户确认升级后，**必须先更新 workflow 字段**再进入完整流程：
 
 ```bash
-bash "$COMET_STATE" set <name> workflow full
+"$COMET_BASH" "$COMET_STATE" set <name> workflow full
 ```
 
 然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**，后续正常走完整流程。若用户不确认升级，停止 hotfix 并报告当前变更已超出 hotfix 适用范围。
@@ -166,4 +166,4 @@ bash "$COMET_STATE" set <name> workflow full
 - Bug 已修复，测试通过
 - change 已归档
 - 如有 spec 变更，已同步到 main spec
-- **阶段守卫**：build → verify 前运行 `bash "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `bash "$COMET_GUARD" <change-name> verify --apply`
+- **阶段守卫**：build → verify 前运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`

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

@@ -21,6 +21,8 @@ description: "Comet 阶段 1：开启。用 /comet-open 调用。通过 OpenSpec
 
 **立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。若用户意图未明确、需要先形成建议，改为加载 `openspec-propose`。禁止跳过此步骤。
 
+**命名与范围守卫**：change name 必须使用用户指定或通过 AskUserQuestion 确认的名称，不得自动生成或推断。变更范围必须与用户描述一致，不得自行扩大或缩小。
+
 确认以下产物已创建：
 
 ```
@@ -47,7 +49,7 @@ if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
   return 1
 fi
 
-bash "$COMET_STATE" init <name> full
+"$COMET_BASH" "$COMET_STATE" init <name> full
 ```
 
 ### 3. 入口状态验证
@@ -55,11 +57,13 @@ bash "$COMET_STATE" init <name> full
 验证状态机已正确初始化：
 
 ```bash
-bash "$COMET_STATE" check <name> open
+"$COMET_BASH" "$COMET_STATE" check <name> open
 ```
 
 验证通过后继续 Step 4。验证失败时脚本会输出具体失败原因。
 
+**幂等性**：open 阶段所有操作可安全重复执行。如 `.comet.yaml` 已处于 `phase: open` 且三个产物文件均已存在，跳过已完成步骤，从第一个缺失步骤继续。
+
 ### 4. 内容完整性检查
 
 确认三个文档内容完整：
@@ -67,22 +71,42 @@ bash "$COMET_STATE" check <name> open
 - **design.md**：高层架构决策、方案选型、数据流
 - **tasks.md**：任务列表，每个任务有明确描述
 
+**文件存在性验证**：逐个确认三个文件路径存在且非空。任一文件缺失或为空时，不得进入 Step 5 或执行阶段守卫，必须回到创建步骤补充。
+
+### 5. 用户审视确认（阻塞点）
+
+三个文档创建完成且内容完整性检查通过后，**必须使用 AskUserQuestion 工具暂停并等待用户确认**。不得在用户确认前执行阶段守卫或自动流转。
+
+AskUserQuestion 必须以单选题形式呈现，包含以下摘要和选项：
+
+**摘要内容**：
+- **proposal.md**：问题背景、目标、范围
+- **design.md**：高层架构决策、方案选型
+- **tasks.md**：任务数量和关键任务描述
+
+**选项**：
+- 「确认，继续下一阶段」— 产物符合预期，执行阶段守卫流转
+- 「需要调整」— 附带调整说明，修改后重新请求确认
+
+用户选择「确认」后继续执行退出条件。用户选择「需要调整」时，按其说明修改对应文件，然后重新使用 AskUserQuestion 请求确认。
+
 ## 退出条件
 
 - proposal.md、design.md、tasks.md 均已创建且内容完整
-- **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> open --apply`，全部 PASS 后自动流转到下一阶段
+- **用户已确认** proposal、design、tasks 内容符合预期
+- **阶段守卫**：运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply`，全部 PASS 后自动流转到下一阶段
 
 退出前必须使用 `--apply`，否则 `.comet.yaml` 仍停留在 `phase: open`，下一阶段入口检查会失败。
 
 ```bash
-bash "$COMET_GUARD" <change-name> open --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
 ```
 
 完整流程会自动更新为 `phase: design`；hotfix/tweak preset 会自动更新为 `phase: build`。
 
 ## 自动流转
 
-退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+用户确认后，退出条件满足，自动流转到下一阶段：
 
 > **REQUIRED NEXT SKILL（完整流程）:** 调用 `comet-design` skill 进入深度设计阶段。
 >

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

@@ -49,24 +49,24 @@ fi
 初始化 Comet 状态文件：
 
 ```bash
-bash "$COMET_STATE" init <name> tweak
+"$COMET_BASH" "$COMET_STATE" init <name> tweak
 ```
 
 初始化后验证状态：
 
 ```bash
-bash "$COMET_STATE" check <name> open
+"$COMET_BASH" "$COMET_STATE" check <name> open
 ```
 
 阶段守卫完成 open → build 过渡：
 
 ```bash
-bash "$COMET_GUARD" <change-name> open --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
 ```
 
 ### 2. 轻量构建（preset build）
 
-使用 tweak 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`。
+使用 tweak 默认值：`build_mode: direct`。跳过 Superpowers `brainstorming` 和 `writing-plans`。
 
 继续或开始修改前，按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。若归因后发现范围超出 tweak，按本文件“升级条件”处理。
 
@@ -83,7 +83,7 @@ bash "$COMET_GUARD" <change-name> open --apply
 4. 运行阶段守卫完成 build → verify 过渡：
 
 ```bash
-bash "$COMET_GUARD" <change-name> build --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
@@ -111,7 +111,7 @@ bash "$COMET_GUARD" <change-name> build --apply
 <IMPORTANT>
 Tweak 流程为 **一次性连续执行**。调用 `/comet-tweak` 后，agent 在 tweak 自有步骤间自动推进，不主动停顿。但以下情况必须暂停等待用户确认：
 
-1. 遇到升级条件（见"升级条件"章节）
+1. 遇到升级条件（见"升级条件"章节），**必须使用 AskUserQuestion 工具暂停并等待用户明确确认**升级为完整流程
 2. 验证阶段（comet-verify）的验证失败决策和分支处理决策
 
 执行顺序：快速开启 → 轻量构建 → 轻量验证 → 归档 → 完成
@@ -134,12 +134,12 @@ Tweak 流程为 **一次性连续执行**。调用 `/comet-tweak` 后，agent
 | 需要新增 capability | 超出局部优化 |
 | 需要 delta spec | 影响了已有规格 |
 
-满足升级条件时必须暂停并等待用户明确确认升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。
+满足升级条件时**必须使用 AskUserQuestion 工具暂停并等待用户明确确认**升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。不得仅输出文字提示后继续执行。
 
 用户确认升级后，**必须先更新 workflow 字段**再进入完整流程：
 
 ```bash
-bash "$COMET_STATE" set <name> workflow full
+"$COMET_BASH" "$COMET_STATE" set <name> workflow full
 ```
 
 然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**，后续正常走完整流程。若用户不确认升级，停止 tweak 并报告当前变更已超出 tweak 适用范围。
@@ -151,4 +151,4 @@ bash "$COMET_STATE" set <name> workflow full
 - 小改动已完成，测试通过
 - change 已归档
 - 未新增 capability、架构调整或接口变化
-- **阶段守卫**：build → verify 前运行 `bash "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `bash "$COMET_GUARD" <change-name> verify --apply`
+- **阶段守卫**：build → verify 前运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`

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

@@ -23,17 +23,19 @@ if [ -z "$COMET_ENV" ]; then
   return 1
 fi
 . "$COMET_ENV"
-bash "$COMET_STATE" check <change-name> verify
+"$COMET_BASH" "$COMET_STATE" check <change-name> verify
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
 
+**幂等性**：verify 阶段所有检查可安全重复执行。如 `verify_result` 已为 `pass` 且 `branch_status` 已为 `handled`，说明验证已完成，直接执行 guard 流转。如 `verify_result` 为 `pending`，从头开始验证。
+
 ### 1. 改动规模评估
 
 执行规模评估：
 
 ```bash
-bash "$COMET_STATE" scale <change-name>
+"$COMET_BASH" "$COMET_STATE" scale <change-name>
 ```
 
 脚本自动统计任务数、增量规格数、变更文件数，判断使用 light 或 full 验证模式，并设置 verify_mode 字段。
@@ -48,13 +50,13 @@ bash "$COMET_STATE" scale <change-name>
 
 ```bash
 # 仅在用户确认修复后执行
-bash "$COMET_STATE" transition <change-name> verify-fail
+"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 注意：如果 build 阶段每个任务都已提交，脚本基于工作区 diff 的文件数可能低估改动规模。此时必须读取 plan 文件头的 `base-ref` 并用提交区间复核：
 
 ```bash
-PLAN=$(bash "$COMET_STATE" get <change-name> plan)
+PLAN=$("$COMET_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
 ```
@@ -62,20 +64,22 @@ git diff --stat "$BASE_REF"...HEAD
 若提交区间显示改动超过轻量阈值（> 4 个文件、跨模块协调、或 delta spec 超过 1 个 capability），手动设置为完整验证：
 
 ```bash
-bash "$COMET_STATE" set <change-name> verify_mode full
+"$COMET_BASH" "$COMET_STATE" set <change-name> verify_mode full
 ```
 
 ### 1b. 验证失败决策（阻塞点）
 
-验证不通过时必须暂停并等待用户决定修复或接受偏差。不得自动运行 `bash "$COMET_STATE" transition <change-name> verify-fail`，也不得自动调用 `/comet-build`。
+验证不通过时**必须使用 AskUserQuestion 工具暂停并等待用户决定修复或接受偏差**。不得自动运行 `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`，也不得自动调用 `/comet-build`。禁止仅输出文字提示后继续执行。
 
 暂停时必须列出：
 - 失败项
 - 是否属于 CRITICAL（构建失败、测试失败、安全问题、核心验收场景失败）
 - 推荐处理方式
 
+**不确定性原则**：无法确定严重程度时，降级处理（SUGGESTION > WARNING > CRITICAL）。仅对构建失败、测试失败、安全问题使用 CRITICAL；模糊或不确定的问题标为 WARNING 或 SUGGESTION。
+
 用户选择后按以下方式继续：
-- **全部修复**：运行 `bash "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build` 修复
+- **全部修复**：运行 `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build` 修复
 - **逐项处理**：CRITICAL 失败项必须修复；非 CRITICAL 失败项可选择接受偏差，但必须在验证报告中记录接受原因和影响范围。若存在任何 CRITICAL 失败项，不允许跳过修复直接全部接受
 
 ### 2a. 轻量验证（小改动）
@@ -94,7 +98,7 @@ bash "$COMET_STATE" set <change-name> verify_mode full
 
 ```bash
 # 仅在用户确认修复后执行
-bash "$COMET_STATE" transition <change-name> verify-fail
+"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **报告格式**：简表列出 5 项检查结果 + PASS/FAIL。
@@ -124,20 +128,20 @@ bash "$COMET_STATE" transition <change-name> verify-fail
 
 ```bash
 # 仅在用户确认修复后执行
-bash "$COMET_STATE" transition <change-name> verify-fail
+"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Spec 漂移处理**（用户决策点）：
-- 若检查项 6 发现矛盾（delta spec 有内容但 design doc 未体现），**必须暂停并等待用户选择处理方式**，不得自动选择。选项：
+- 若检查项 6 发现矛盾（delta spec 有内容但 design doc 未体现），**必须使用 AskUserQuestion 工具以单选题形式暂停并等待用户选择处理方式**，不得自动选择。选项：
   - 选项 A：在 design doc 追加 "Implementation Divergence" 节记录偏差原因。选项 A 属于 verify 阶段允许产物；写入后不得因该 design doc 变更再次触发 Step 1b dirty-worktree 决策
-  - 选项 B：用户选择 B 后，运行 `bash "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build`；由 `/comet-build` 的 Spec 增量更新规则加载 `superpowers:brainstorming` 更新 Design Doc + delta spec
+  - 选项 B：用户选择 B 后，运行 `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build`；由 `/comet-build` 的 Spec 增量更新规则加载 Superpowers `brainstorming` 更新 Design Doc + delta spec
   - 选项 C：确认偏差可接受，继续验证（归档时 design doc 将标记为 `superseded-by-main-spec`）
 
 ### 3. 收尾（Superpowers）
 
-**立即执行：** 使用 Skill 工具加载 `superpowers:finishing-a-development-branch` 技能。禁止跳过此步骤。
+**立即执行：** 使用 Skill 工具加载 Superpowers `finishing-a-development-branch` 技能。禁止跳过此步骤。
 
-如 `superpowers:finishing-a-development-branch` 不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。
+如 Superpowers `finishing-a-development-branch` 技能不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。
 
 技能加载后，按其指引收尾。分支处理选项：
 1. 本地合并到主分支
@@ -145,7 +149,7 @@ bash "$COMET_STATE" transition <change-name> verify-fail
 3. 保持分支（稍后处理）
 4. 丢弃工作
 
-这是用户决策点。**必须暂停并等待用户选择分支处理方式**，不得根据推荐、默认值或当前分支状态自行选择。只有在用户完成选择且对应操作完成后，才允许写入 `branch_status: handled`。
+这是用户决策点。**必须使用 AskUserQuestion 工具暂停并等待用户选择分支处理方式**，不得根据推荐、默认值或当前分支状态自行选择。禁止仅输出文字提示后继续执行。只有在用户完成选择且对应操作完成后，才允许写入 `branch_status: handled`。
 
 **确认项**：
 - 全部测试通过
@@ -160,8 +164,8 @@ mkdir -p docs/superpowers/reports
 # 将本次验证结论写入报告文件，例如：
 # 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
+"$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
 ```
 
 ## 退出条件
@@ -170,18 +174,28 @@ bash "$COMET_STATE" set <change-name> branch_status handled
 - 分支已处理
 - `.comet.yaml` 中 `verification_report` 指向已存在的验证报告文件
 - `.comet.yaml` 中 `branch_status: handled`
-- **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> verify --apply`，全部 PASS 后通过 `comet-state transition verify-pass` 自动流转到 `phase: archive`
+- **阶段守卫**：运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`，全部 PASS 后通过 `comet-state transition verify-pass` 自动流转到 `phase: archive`
 
 验证和分支处理均完成后，运行 guard 自动流转：
 
 ```bash
-bash "$COMET_GUARD" <change-name> verify --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply
 ```
 
 状态文件自动更新为 `phase: archive`、`verify_result: pass`、`verified_at: YYYY-MM-DD`。
 
+## 上下文压缩恢复
+
+Verify 阶段可能触发上下文压缩。恢复时先运行：
+
+```bash
+"$COMET_BASH" "$COMET_STATE" check <change-name> verify --recover
+```
+
+脚本输出结构化恢复上下文（phase、验证状态、分支状态、恢复动作），根据输出的 Recovery action 决定下一步。
+
 ## 自动流转
 
-退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+退出条件满足后（包括用户选择分支处理方式），自动流转到下一阶段：
 
 > **REQUIRED NEXT SKILL:** 调用 `comet-archive` skill 进入归档阶段。

package/bin/comet.js

@@ -1,3 +1,3 @@
-#!/usr/bin/env node
-
-import '../dist/cli/index.js';
+#!/usr/bin/env node
+
+import '../dist/cli/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpamis/comet",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "OpenSpec + Superpowers dual-star development workflow",
   "keywords": [
     "comet",

package/scripts/postinstall.js

@@ -1,44 +1,44 @@
-#!/usr/bin/env node
-
-/**
- * Postinstall script that hints about comet init.
- *
- * The tip is suppressed when:
- * - CI=true environment variable is set
- * - COMET_NO_HINTS=1 environment variable is set
- * - dist/ directory doesn't exist (dev setup scenario)
- */
-
-import { promises as fs } from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-function shouldSkip() {
-  if (process.env.CI === 'true' || process.env.CI === '1') return true;
-  if (process.env.COMET_NO_HINTS === '1') return true;
-  return false;
-}
-
-async function distExists() {
-  try {
-    const stat = await fs.stat(path.join(__dirname, '..', 'dist'));
-    return stat.isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-async function main() {
-  try {
-    if (shouldSkip()) return;
-    if (!(await distExists())) return;
-    console.log(`\nTip: Run 'comet init' to set up Comet workflow in your project`);
-  } catch {
-    // Never break npm install
-  }
-}
-
-main().catch(() => process.exit(0));
+#!/usr/bin/env node
+
+/**
+ * Postinstall script that hints about comet init.
+ *
+ * The tip is suppressed when:
+ * - CI=true environment variable is set
+ * - COMET_NO_HINTS=1 environment variable is set
+ * - dist/ directory doesn't exist (dev setup scenario)
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function shouldSkip() {
+  if (process.env.CI === 'true' || process.env.CI === '1') return true;
+  if (process.env.COMET_NO_HINTS === '1') return true;
+  return false;
+}
+
+async function distExists() {
+  try {
+    const stat = await fs.stat(path.join(__dirname, '..', 'dist'));
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  try {
+    if (shouldSkip()) return;
+    if (!(await distExists())) return;
+    console.log(`\nTip: Run 'comet init' to set up Comet workflow in your project`);
+  } catch {
+    // Never break npm install
+  }
+}
+
+main().catch(() => process.exit(0));