@rpamis/comet 0.3.3 → 0.3.5

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

@@ -21,6 +21,8 @@ After the skill loads, freely explore the problem space following its guidance.
 
 **Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. If the user's intent is unclear and needs proposal formation first, load `openspec-propose` instead. Skipping this step is prohibited.
 
+**Naming and scope guard**: Change name must use a user-specified or AskUserQuestion-confirmed name — must not auto-generate or infer. Change scope must match the user's description — must not expand or narrow it independently.
+
 Confirm the following artifacts have been created:
 
 ```
@@ -60,6 +62,8 @@ bash "$COMET_STATE" check <name> open
 
 Proceed to Step 4 after verification passes. The script outputs specific failure reasons when verification fails.
 
+**Idempotency**: All open phase operations can be safely re-executed. If `.comet.yaml` is already at `phase: open` and all three artifact files exist, skip completed steps and continue from the first missing step.
+
 ### 4. Content Completeness Check
 
 Confirm the three documents have complete content:
@@ -67,9 +71,29 @@ Confirm the three documents have complete content:
 - **design.md**: high-level architecture decisions, approach selection, data flow
 - **tasks.md**: task list, each task has a clear description
 
+**File existence verification**: Confirm all three file paths exist and are non-empty. If any file is missing or empty, must not enter Step 5 or execute phase guard — return to creation step to fill the gap.
+
+### 5. User Review and Confirmation (Blocking Point)
+
+After the three documents are created and content completeness check passes, **must use the AskUserQuestion tool to pause and wait for user confirmation**. Must not execute phase guard or auto-transition before user confirmation.
+
+AskUserQuestion must be presented as a single-select question with the following summary and options:
+
+**Summary content**:
+- **proposal.md**: problem background, goals, scope
+- **design.md**: high-level architecture decisions, approach selection
+- **tasks.md**: task count and key task descriptions
+
+**Options**:
+- "Confirm, proceed to next phase" — artifacts meet expectations, execute phase guard transition
+- "Needs adjustment" — include adjustment notes, modify and re-request confirmation
+
+After user selects "Confirm", proceed to exit conditions. When user selects "Needs adjustment", modify the corresponding files per their notes, then re-use AskUserQuestion to request confirmation.
+
 ## Exit Conditions
 
 - proposal.md, design.md, tasks.md all created with complete content
+- **User has confirmed** proposal, design, tasks content meets expectations
 - **Phase guard**: Run `bash "$COMET_GUARD" <change-name> open --apply`; after all PASS, auto-transitions to next phase
 
 Must use `--apply` before exit, otherwise `.comet.yaml` remains at `phase: open` and the next phase entry check will fail.
@@ -82,7 +106,7 @@ Full workflow auto-transitions to `phase: design`; hotfix/tweak presets auto-tra
 
 ## Automatic Transition
 
-After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
+After user confirmation and exit conditions are met, auto-transition to next phase:
 
 > **REQUIRED NEXT SKILL (full workflow):** Invoke `comet-design` skill to enter the deep design phase.
 >

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

@@ -111,7 +111,7 @@ Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` befo
 <IMPORTANT>
 Tweak workflow is **one-time continuous execution**. After invoking `/comet-tweak`, agent must automatically advance through tweak steps, without pausing to wait for user input mid-way. But the following situations must pause and wait for user confirmation:
 
-1. Encountering upgrade conditions (see "Upgrade Conditions" section). Handle through the upgrade-condition blocking confirmation
+1. Encountering upgrade conditions (see "Upgrade Conditions" section). **Must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm** upgrading to full workflow
 2. verify phase (comet-verify) verification-failure and branch-handling decisions
 
 Execution order: quick open → lightweight build → lightweight verification → archive → complete
@@ -134,7 +134,7 @@ Upgrade to full `/comet` when **any** of the following conditions are met:
 | New capability needed | Exceeds local optimization |
 | Delta spec needed | Affects existing specs |
 
-When upgrade conditions are met, must pause and wait for the user to explicitly confirm upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc.
+When upgrade conditions are met, **must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm** upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc. Must not just output a text prompt and then continue executing.
 
 After user confirms upgrade, **must first update the workflow field** before entering full flow:
 

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

@@ -28,6 +28,8 @@ bash "$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.
+
 ### 1. Scale Assessment
 
 Execute scale assessment:
@@ -67,13 +69,15 @@ 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 verification does not pass, **must use the AskUserQuestion tool to 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`. Must not just output a text prompt and then continue executing.
 
 When pausing, must list:
 - Failed items
 - Whether CRITICAL (build failure, test failure, security issues, core acceptance scenario failure)
 - 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.
+
 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
@@ -128,7 +132,7 @@ bash "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Spec Drift Handling** (user decision point):
-- If check item 6 finds contradictions (delta spec has content but design doc does not reflect it), **must pause and wait for user to choose handling method**; must not select automatically. Options:
+- If check item 6 finds contradictions (delta spec has content but design doc does not reflect it), **must use the AskUserQuestion tool as a single-select question to 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)
@@ -145,7 +149,7 @@ After the skill loads, follow its guidance to finish. Branch handling options:
 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.
+This is a user decision point. **Must use the AskUserQuestion tool to pause and wait for user to choose branch handling method**. Must not select based on recommendations, defaults, or current branch status. Must not just output a text prompt and then continue executing. Only after the user completes selection and the corresponding operation finishes, may `branch_status: handled` be written.
 
 **Confirmation items**:
 - All tests pass
@@ -182,6 +186,16 @@ State file auto-updates to `phase: archive`, `verify_result: pass`, `verified_at
 
 ## Automatic Transition
 
-After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
+After exit conditions are met (including user selecting branch handling method), auto-transition to next phase:
 
 > **REQUIRED NEXT SKILL:** Invoke `comet-archive` skill to enter the archive phase.
+
+## Context Compaction Recovery
+
+The verify phase may trigger context compaction. To recover, first run:
+
+```bash
+bash "$COMET_STATE" check <change-name> verify --recover
+```
+
+The script outputs structured recovery context (phase, verification status, branch status, recovery action). Follow the Recovery action to determine next step.

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

@@ -103,19 +103,30 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 流转链：open → design → build → verify → archive
 
-**连续执行要求**：从检测到的阶段开始，agent 必须自动推进后续阶段；自动推进只适用于没有用户决策的衔接点。遇到用户决策点时必须暂停并等待用户明确回复，不得用推荐规则、默认值或历史偏好代替用户确认。
+**连续执行要求**：从检测到的阶段开始，agent 自动推进后续阶段。但**自动推进仅适用于没有用户决策的衔接点**。遇到用户决策点时，**必须使用 AskUserQuestion 工具暂停并等待用户明确回复**，不得用推荐规则、默认值或历史偏好代替用户确认，也不得仅输出文字提示后继续执行。
 
-**决策点是阻塞点**：只要到达下列任一节点，当前 `/comet` 调用必须停住。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。
+**决策点是阻塞点**：只要到达下列任一节点，当前 `/comet` 调用必须停住，**使用 AskUserQuestion 工具等待用户选择**。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。
 
 需要用户参与的节点（仅在这些节点暂停）：
-1. brainstorming 确认设计方案
-2. build 阶段选择工作方式（隔离方式 + 执行方式，一次交互完成）
-3. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择）
-4. finishing-branch 选择分支处理方式
-5. 遇到升级条件（hotfix/tweak → 完整流程）
-6. build 阶段范围扩张需重新设计或拆分新 change
-
-agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。
+1. open 阶段 proposal/design/tasks 审视确认
+2. brainstorming 确认设计方案
+3. build 阶段选择工作方式（隔离方式 + 执行方式，一次交互完成）
+4. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择）
+5. finishing-branch 选择分支处理方式
+6. 遇到升级条件（hotfix/tweak → 完整流程）
+7. build 阶段范围扩张需重新设计或拆分新 change
+
+agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。到达决策点时，**禁止以文字输出代替工具等待——必须通过 AskUserQuestion 明确获取用户选择后才能继续**。
+
+**红旗清单** — 以下想法出现时立即停止并检查：
+
+| Agent 心理 | 实际风险 |
+|-----------|---------|
+| "用户应该会同意这个方案" | 不能替用户决策，用 AskUserQuestion |
+| "这只是个小改动，不需要确认" | 决策点无大小之分，阻塞点必须等待 |
+| "用户之前选过 A，这次也选 A" | 历史偏好不能替代当前确认 |
+| "我已经解释了方案，用户没反对" | 没反对 ≠ 同意，必须用工具获取明确选择 |
+| "流程走到这里应该没问题了" | 验证不通过 ≠ 通过，检查 verify_result |
 </IMPORTANT>
 
 ---

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

@@ -28,6 +28,8 @@ bash "$COMET_STATE" check <name> build
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
 
+**幂等性**：build 阶段所有操作可安全重复执行。读取 `.comet.yaml` 的 `phase` 字段确认仍在 build 阶段，读取 plan 文件头的 `base-ref`，再读取 tasks.md 找到第一个未勾选任务继续执行。已提交的任务不得重复提交。
+
 ### 1. 制定计划
 
 **立即执行：** 使用 Skill 工具加载 `superpowers:writing-plans` 技能。禁止跳过此步骤。
@@ -88,7 +90,7 @@ bash "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 - 任务数 ≤ 2 且无跨模块依赖 → 推荐 B
 - 来自 hotfix 路径 → 推荐 B
 
-这是用户决策点。必须暂停并等待用户明确选择隔离方式和执行方式，**不得根据推荐规则自行选择 `branch` 或 `worktree`**，也**不得根据推荐规则自行选择执行方式**。推荐规则只能用于说明建议，不能替代用户确认。
+这是用户决策点。**必须使用 AskUserQuestion 工具暂停并等待用户明确选择隔离方式和执行方式**，不得根据推荐规则自行选择 `branch` 或 `worktree`，也不得根据推荐规则自行选择执行方式。推荐规则只能用于说明建议，不能替代用户确认。禁止仅输出文字提示后继续执行。
 
 用户选择后，更新 `isolation` 和 `build_mode` 字段：
 
@@ -131,10 +133,10 @@ bash "$COMET_STATE" set <name> build_mode direct
 | 规模 | 触发条件 | 做法 |
 |------|---------|------|
 | 小 | 遗漏验收场景、边界条件 | 直接编辑 delta spec + design.md，追加 tasks.md 任务 |
-| 中 | 接口变更、新增组件、数据流变化 | 暂停并等待用户确认后，必须使用 Skill 工具加载 `superpowers:brainstorming` 更新 Design Doc + delta spec |
-| 大 | 全新 capability 需求 | 必须暂停并等待用户确认拆分；用户确认后，通过 `/comet-open` 创建独立 change |
+| 中 | 接口变更、新增组件、数据流变化 | **使用 AskUserQuestion 工具暂停并等待用户确认后**，必须使用 Skill 工具加载 `superpowers:brainstorming` 更新 Design Doc + delta spec |
+| 大 | 全新 capability 需求 | **必须使用 AskUserQuestion 工具暂停并等待用户确认拆分**；用户确认后，通过 `/comet-open` 创建独立 change |
 
-**50% 阈值判定**：以 tasks.md 初始任务总数为基准，若新增任务数超过该总数的一半，视为超出原计划范围，必须暂停并等待用户决定是否拆分为新 change。
+**50% 阈值判定**：以 tasks.md 初始任务总数为基准，若新增任务数超过该总数的一半，视为超出原计划范围，**必须使用 AskUserQuestion 工具暂停并等待用户决定是否拆分为新 change**。
 
 创建独立 change 时必须调用 `/comet-open`，不得直接调用 `/opsx:new`。`/comet-open` 会同时创建 OpenSpec 产物和 `.comet.yaml`，避免新 change 脱离 Comet 状态机。
 
@@ -149,7 +151,7 @@ bash "$COMET_STATE" set <name> build_mode direct
 Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后断点恢复：
 
 - **每完成一个 task**：立即勾选 tasks.md 并提交代码，确保 `.comet.yaml` 和文件状态持久化
-- **上下文压缩后恢复**：读取 `.comet.yaml` 的 `phase` 字段确认仍在 build 阶段，读取 plan 文件头的 `base-ref`，再读取 tasks.md 找到下一个未勾选任务继续执行
+- **上下文压缩后恢复**：先运行 `bash "$COMET_STATE" check <change-name> build --recover`，脚本输出结构化恢复上下文（isolation/build_mode 状态、plan 路径、任务完成进度、恢复动作）。根据 Recovery action 决定下一步。
 - **用户手动修改恢复**：按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。该协议定义了检查步骤、归因分类和禁令。build 阶段的特殊处理：
   1. 归因后，若 diff 暗示计划或 spec 已变化，按 Step 4「Spec 增量更新」分级处理
 - **长任务拆分**：单任务超过 200 行代码变更时，考虑拆分为多个子任务分别提交
@@ -183,6 +185,6 @@ bash "$COMET_GUARD" <change-name> build --apply
 
 ## 自动流转
 
-退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+退出条件满足后（包括用户选择工作方式），自动流转到下一阶段：
 
 > **REQUIRED NEXT SKILL:** 调用 `comet-verify` skill 进入验证与收尾阶段。

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

@@ -28,6 +28,8 @@ bash "$COMET_STATE" check <name> design
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
 
+**幂等性**：所有 design 阶段操作可以安全重试。如果 `handoff_context` 和 `handoff_hash` 已存在，先确认它们与当前产物一致再决定是否重新生成。
+
 ### 1a. 生成 OpenSpec → Superpowers 交接包
 
 **必须由脚本生成，不允许 agent 临场手写 summary 代替。**
@@ -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`。也不得仅输出文字提示后继续执行。
 
 暂停时只展示必要摘要：
 - 采用的技术方案
@@ -147,8 +149,18 @@ bash "$COMET_GUARD" <change-name> design --apply
 bash "$COMET_GUARD" <change-name> design --apply
 ```
 
+## 上下文压缩恢复
+
+design 阶段在 brainstorming 过程中可能触发上下文压缩。恢复时先运行：
+
+```bash
+bash "$COMET_STATE" check <change-name> design --recover
+```
+
+脚本输出结构化恢复上下文（阶段、已完成字段、待完成字段、恢复动作）。按 Recovery action 判断下一步。
+
 ## 自动流转
 
-退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+退出条件满足后（包括用户确认设计方案），自动流转到下一阶段：
 
 > **REQUIRED NEXT SKILL:** 调用 `comet-build` skill 进入计划与构建阶段。

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

@@ -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,7 +149,7 @@ Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent
 | 引入新的 public API | 修复产生了新的对外接口 |
 | 修复范围超出单一函数/模块 | 需要多处协调修改 |
 
-满足升级条件时必须暂停并等待用户明确确认升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。
+满足升级条件时**必须使用 AskUserQuestion 工具暂停并等待用户明确确认**升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。不得仅输出文字提示后继续执行。
 
 用户确认升级后，**必须先更新 workflow 字段**再进入完整流程：
 

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 确认的名称，不得自动生成或推断。变更范围必须与用户描述一致，不得自行扩大或缩小。
+
 确认以下产物已创建：
 
 ```
@@ -60,6 +62,8 @@ bash "$COMET_STATE" check <name> open
 
 验证通过后继续 Step 4。验证失败时脚本会输出具体失败原因。
 
+**幂等性**：open 阶段所有操作可安全重复执行。如 `.comet.yaml` 已处于 `phase: open` 且三个产物文件均已存在，跳过已完成步骤，从第一个缺失步骤继续。
+
 ### 4. 内容完整性检查
 
 确认三个文档内容完整：
@@ -67,9 +71,29 @@ 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 均已创建且内容完整
+- **用户已确认** proposal、design、tasks 内容符合预期
 - **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> open --apply`，全部 PASS 后自动流转到下一阶段
 
 退出前必须使用 `--apply`，否则 `.comet.yaml` 仍停留在 `phase: open`，下一阶段入口检查会失败。
@@ -82,7 +106,7 @@ bash "$COMET_GUARD" <change-name> open --apply
 
 ## 自动流转
 
-退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+用户确认后，退出条件满足，自动流转到下一阶段：
 
 > **REQUIRED NEXT SKILL（完整流程）:** 调用 `comet-design` skill 进入深度设计阶段。
 >

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

@@ -111,7 +111,7 @@ bash "$COMET_GUARD" <change-name> build --apply
 <IMPORTANT>
 Tweak 流程为 **一次性连续执行**。调用 `/comet-tweak` 后，agent 在 tweak 自有步骤间自动推进，不主动停顿。但以下情况必须暂停等待用户确认：
 
-1. 遇到升级条件（见"升级条件"章节）
+1. 遇到升级条件（见"升级条件"章节），**必须使用 AskUserQuestion 工具暂停并等待用户明确确认**升级为完整流程
 2. 验证阶段（comet-verify）的验证失败决策和分支处理决策
 
 执行顺序：快速开启 → 轻量构建 → 轻量验证 → 归档 → 完成
@@ -134,7 +134,7 @@ Tweak 流程为 **一次性连续执行**。调用 `/comet-tweak` 后，agent
 | 需要新增 capability | 超出局部优化 |
 | 需要 delta spec | 影响了已有规格 |
 
-满足升级条件时必须暂停并等待用户明确确认升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。
+满足升级条件时**必须使用 AskUserQuestion 工具暂停并等待用户明确确认**升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。不得仅输出文字提示后继续执行。
 
 用户确认升级后，**必须先更新 workflow 字段**再进入完整流程：
 

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

@@ -28,6 +28,8 @@ bash "$COMET_STATE" check <change-name> verify
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
 
+**幂等性**：verify 阶段所有检查可安全重复执行。如 `verify_result` 已为 `pass` 且 `branch_status` 已为 `handled`，说明验证已完成，直接执行 guard 流转。如 `verify_result` 为 `pending`，从头开始验证。
+
 ### 1. 改动规模评估
 
 执行规模评估：
@@ -67,13 +69,15 @@ bash "$COMET_STATE" set <change-name> verify_mode full
 
 ### 1b. 验证失败决策（阻塞点）
 
-验证不通过时必须暂停并等待用户决定修复或接受偏差。不得自动运行 `bash "$COMET_STATE" transition <change-name> verify-fail`，也不得自动调用 `/comet-build`。
+验证不通过时**必须使用 AskUserQuestion 工具暂停并等待用户决定修复或接受偏差**。不得自动运行 `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` 修复
 - **逐项处理**：CRITICAL 失败项必须修复；非 CRITICAL 失败项可选择接受偏差，但必须在验证报告中记录接受原因和影响范围。若存在任何 CRITICAL 失败项，不允许跳过修复直接全部接受
@@ -128,7 +132,7 @@ 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
   - 选项 C：确认偏差可接受，继续验证（归档时 design doc 将标记为 `superseded-by-main-spec`）
@@ -145,7 +149,7 @@ bash "$COMET_STATE" transition <change-name> verify-fail
 3. 保持分支（稍后处理）
 4. 丢弃工作
 
-这是用户决策点。**必须暂停并等待用户选择分支处理方式**，不得根据推荐、默认值或当前分支状态自行选择。只有在用户完成选择且对应操作完成后，才允许写入 `branch_status: handled`。
+这是用户决策点。**必须使用 AskUserQuestion 工具暂停并等待用户选择分支处理方式**，不得根据推荐、默认值或当前分支状态自行选择。禁止仅输出文字提示后继续执行。只有在用户完成选择且对应操作完成后，才允许写入 `branch_status: handled`。
 
 **确认项**：
 - 全部测试通过
@@ -180,8 +184,18 @@ bash "$COMET_GUARD" <change-name> verify --apply
 
 状态文件自动更新为 `phase: archive`、`verify_result: pass`、`verified_at: YYYY-MM-DD`。
 
+## 上下文压缩恢复
+
+Verify 阶段可能触发上下文压缩。恢复时先运行：
+
+```bash
+bash "$COMET_STATE" check <change-name> verify --recover
+```
+
+脚本输出结构化恢复上下文（phase、验证状态、分支状态、恢复动作），根据输出的 Recovery action 决定下一步。
+
 ## 自动流转
 
-退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+退出条件满足后（包括用户选择分支处理方式），自动流转到下一阶段：
 
 > **REQUIRED NEXT SKILL:** 调用 `comet-archive` skill 进入归档阶段。

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAQrD,KAAK,WAAW,GAAG,YAAY,GAAG,MAAM,CAAC;AAgNzC,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAiBf"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAQrD,KAAK,WAAW,GAAG,YAAY,GAAG,MAAM,CAAC;AA2NzC,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/dist/commands/doctor.js

@@ -20,6 +20,23 @@ const VALID_YAML_FIELDS = new Set([
     'archived',
     'verified_at',
 ]);
+function collectTopLevelYamlKeys(yamlContent) {
+    const topLevelKeys = [];
+    for (const line of yamlContent.split(/\r?\n/u)) {
+        const trimmedLine = line.trim();
+        if (!trimmedLine || trimmedLine.startsWith('#'))
+            continue;
+        if (/^\s/u.test(line))
+            continue;
+        if (trimmedLine.startsWith('- '))
+            continue;
+        const keyMatch = line.match(/^['"]?([A-Za-z0-9_-]+)['"]?\s*:/u);
+        if (keyMatch) {
+            topLevelKeys.push(keyMatch[1]);
+        }
+    }
+    return topLevelKeys;
+}
 async function checkOpenSpecCli() {
     if (!isCommandAvailable('openspec')) {
         return {
@@ -145,13 +162,7 @@ async function checkCometYamlValidity(projectPath) {
         if (!(await fileExists(yamlPath)))
             continue;
         const raw = await fs.readFile(yamlPath, 'utf-8');
-        const unknownFields = [];
-        for (const line of raw.split('\n')) {
-            const match = line.match(/^(\w[\w_]*):/);
-            if (match && !VALID_YAML_FIELDS.has(match[1])) {
-                unknownFields.push(match[1]);
-            }
-        }
+        const unknownFields = collectTopLevelYamlKeys(raw).filter((key) => !VALID_YAML_FIELDS.has(key));
         results.push(unknownFields.length === 0
             ? { check: `.comet.yaml: ${entry}`, status: 'pass', message: 'valid' }
             : {

package/dist/commands/doctor.js.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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"}

package/dist/core/openspec.d.ts

@@ -1,7 +1,11 @@
 import type { InstallScope } from './types.js';
-declare function quoteShellArg(value: string, platform?: NodeJS.Platform): string;
-declare function buildOpenSpecInitCommand(projectPath: string, toolIds: string[], scope: InstallScope, homeDir?: string, platform?: NodeJS.Platform): string;
+declare function getNpmExecutable(platform?: NodeJS.Platform): string;
+declare function buildOpenSpecInitInvocation(projectPath: string, toolIds: string[], scope: InstallScope, homeDir?: string): {
+    command: string;
+    args: string[];
+};
 declare function isCommandAvailable(command: string): boolean;
+declare function migrateOpenCodeOpenSpecPaths(homeDir: string): void;
 declare function installOpenSpec(projectPath: string, toolIds: string[], scope: InstallScope): Promise<'installed' | 'failed' | 'skipped'>;
-export { installOpenSpec, isCommandAvailable, buildOpenSpecInitCommand, quoteShellArg };
+export { installOpenSpec, isCommandAvailable, buildOpenSpecInitInvocation, getNpmExecutable, migrateOpenCodeOpenSpecPaths, };
 //# sourceMappingURL=openspec.d.ts.map

package/dist/core/openspec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openspec.d.ts","sourceRoot":"","sources":["../../src/core/openspec.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAiB/C,iBAAS,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,MAAM,CAK1F;AAED,iBAAS,wBAAwB,CAC/B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,YAAY,EACnB,OAAO,SAAe,EACtB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,CAGR;AA0GD,iBAAS,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQpD;AAsBD,iBAAe,eAAe,CAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC,CAuC7C;AAED,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"openspec.d.ts","sourceRoot":"","sources":["../../src/core/openspec.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAiB/C,iBAAS,gBAAgB,CAAC,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,MAAM,CAE9E;AAED,iBAAS,2BAA2B,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,YAAY,EACnB,OAAO,SAAe,GACrB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAMrC;AA0GD,iBAAS,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQpD;AA2BD,iBAAS,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CA+C3D;AAED,iBAAe,eAAe,CAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC,CA8C7C;AAED,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,2BAA2B,EAC3B,gBAAgB,EAChB,4BAA4B,GAC7B,CAAC"}