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

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

@@ -1,6 +1,6 @@
 ---
 name: comet-hotfix
-description: "Use when 用户要修复已有行为 bug，且不新增 capability、不需要完整设计；也用于恢复 hotfix workflow。"
+description: "仅在用户明确调用 /comet-hotfix，或由 Comet 根 Skill/runtime 路由到 hotfix preset 时使用；修复已有行为 bug，不用于普通的未托管 bugfix。"
 ---
 
 # Comet 预设路径：Hotfix
@@ -20,7 +20,7 @@ description: "Use when 用户要修复已有行为 bug，且不新增 capability
 
 ### 0. 输出语言约束
 
-精简版 OpenSpec 产物必须使用 Comet 配置产物语言。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `language`，初始化后使用 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取。
+精简版 OpenSpec 产物必须使用 Comet 配置产物语言。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `language`，初始化后使用 `comet state get <name> language` 读取。
 
 执行链路：open → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后进入归档前最终确认。
 
@@ -34,52 +34,54 @@ description: "Use when 用户要修复已有行为 bug，且不新增 capability
 
 **立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。禁止跳过此步骤。
 
-技能加载后，按其指引创建精简版产物：
-  - `proposal.md` — 问题描述 + 根因分析 + 修复目标（无需方案对比）
-  - `design.md` — 修复方案（1 个即可，无需多方案对比）
-  - `tasks.md` — 修复任务清单
-- **无需 delta spec**（除非修复改变了已有 spec 的验收场景）
-
-初始化 Comet 状态文件：
+技能加载后先创建 change 骨架，立即初始化可恢复状态并绑定当前 change：
 
 ```bash
-node "$COMET_STATE" init <name> hotfix
+comet state init <name> hotfix
+comet state select <name>
+comet state check <name> open
 ```
 
-初始化后验证状态：
-
-```bash
-node "$COMET_STATE" check <name> open
-```
+hotfix 默认 `isolation: current`，表示在当前工作区执行；只有用户实际创建/选择了分支或 worktree 后，才能把它改为 `branch` 或 `worktree`。随后按指引创建精简版产物：
+  - `proposal.md` — 问题描述 + 根因分析 + 修复目标（无需方案对比）
+  - `design.md` — 修复方案（1 个即可，无需多方案对比）
+  - `tasks.md` — 修复任务清单
+- **无需 delta spec**（除非修复改变了已有 spec 的验收场景）
 
 阶段守卫完成 open → build 过渡：
 
 ```bash
-node "$COMET_GUARD" <change-name> open --apply
+comet guard <change-name> open --apply
 ```
 
 检查 `auto_transition` 决定是否继续：
 
 ```bash
-node "$COMET_STATE" next <name>
+comet state next <name>
 ```
 
 - `NEXT: auto` → 继续 Step 2
-- `NEXT: manual` → 暂停，按 `HINT` 提示用户手动运行 `/<SKILL>`
+- `NEXT: manual` → 按 `HINT` 交还控制权并结束当前调用；不要再询问用户是否继续
 
 ### 2. 直接构建（预设 build）
 
-使用 hotfix 默认值：`build_mode: direct`，`review_mode: off`（hotfix/tweak 跳过 review_mode 选择——guard 不要求预设工作流选择此项）。跳过 Superpowers `brainstorming` 和 `writing-plans`（除非任务 > 3 个；若超过 3 个任务，转入 `/comet-build` 的计划与执行方式选择——注意这不触发 full workflow 升级，仅切换执行方式）。
+使用 hotfix 默认值：`build_mode: direct`、`tdd_mode: direct`、`review_mode: off`、`isolation: current`。`direct` 表示不进入完整规划/TDD 编排，不表示可以跳过复现、回归测试或验证。跳过 Superpowers `brainstorming` 和 `writing-plans`；**任务数量本身不触发 `/comet-build`**，任务较多时仍在当前 hotfix 的 tasks.md 中按顺序执行，只有命中后文质变信号或范围 tripwire 才交给用户决定是否升级 full。
 
 继续或开始修改前，按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。若归因后发现修复命中质变信号或文件数 tripwire，按本文件「升级判定」处理。
 
-**立即执行：** 按 tasks.md 逐个执行任务：
+修改实现前，必须**先复现问题并记录失败证据**：
+
+1. 用最小可重复步骤确认用户报告的旧行为确实失败，并记录命令、输入和实际结果
+2. 能自动化时先新增一个会失败的回归测试并实际运行，确认失败原因对应本 bug，而不是环境或测试本身错误
+3. 暂时无法自动化时，在 proposal/验证报告中记录不可自动化原因和可重复的手工失败证据；不得无证据直接改代码
+
+完成 RED 证据后，按 tasks.md 逐个执行任务：
 
 1. 读取 `openspec/changes/<name>/tasks.md`，获取未完成任务列表
 2. 对每个未完成任务：
    - 根据任务描述修改代码
    - 运行项目格式化命令（如 `mvn spotless:apply`、`npm run format` 等）
-   - 运行相关测试确认通过
+   - 先运行新增的失败回归测试确认转绿，再运行相关测试确认通过
    - 将 tasks.md 中对应 `- [ ]` 勾选为 `- [x]`
    - 提交代码，commit message 格式：`fix: <简述修复>`
 3. 全部任务完成后，显式运行项目相关测试和构建命令
@@ -107,7 +109,7 @@ node "$COMET_STATE" next <name>
 根因确认消除后，运行阶段守卫完成 build → verify 过渡：
 
 ```bash
-node "$COMET_GUARD" <change-name> build --apply
+comet guard <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
@@ -118,7 +120,7 @@ node "$COMET_GUARD" <change-name> build --apply
 
 **立即执行：** 使用 Skill 工具加载 `comet-verify` 技能。禁止跳过此步骤。
 
-无 delta spec 的小范围 hotfix 通常满足轻量验证条件（≤ 3 tasks、改动文件数低于 scale 阈值），comet-verify 的规模评估会选择轻量验证路径（6 项快速检查；默认 `review_mode: off` 时不自动派发代码审查）。若用户希望增加审查，可在验证前运行 `node "$COMET_STATE" set <name> review_mode standard` 或 `thorough`。若 hotfix 创建了 delta spec，则根据 comet-verify 的规模评估规则进入完整验证路径。
+无 delta spec 的小范围 hotfix 通常满足轻量验证条件（≤ 3 tasks、改动文件数低于 scale 阈值），comet-verify 的规模评估会选择轻量验证路径（6 项快速检查；默认 `review_mode: off` 时不自动派发代码审查）。若用户希望增加审查，可在验证前运行 `comet state set <name> review_mode standard` 或 `thorough`。若 hotfix 创建了 delta spec，则根据 comet-verify 的规模评估规则进入完整验证路径。
 
 验证通过后，按 `/comet-verify` 的规则将 `.comet.yaml` 的 `verify_result` 记录为 `pass`，归档前不得跳过该状态。验证通过后仍必须进入 `/comet-archive` 的归档前最终确认，不得自动运行归档脚本。
 
@@ -134,12 +136,11 @@ node "$COMET_GUARD" <change-name> build --apply
 ## 连续执行模式
 
 <IMPORTANT>
-Hotfix 流程默认 **一次性连续执行**。调用 `/comet-hotfix` 后，agent 在 hotfix 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界（build/verify/archive 之间）停下，由用户手动运行下一阶段命令——此时连续执行降级为逐阶段手动推进，详见下方「自动衔接下一阶段」。但无论 `auto_transition` 取何值，以下情况都必须暂停等待用户确认：
+Hotfix 流程默认 **一次性连续执行**。调用 `/comet-hotfix` 后，agent 在 hotfix 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界（build/verify/archive 之间）结束当前调用并按 `HINT` 交还控制权，由用户稍后手动运行下一阶段命令；这是手动衔接，不是新的确认点。无论 `auto_transition` 取何值，以下真正的用户决策仍需暂停：
 
 1. 遇到升级判定信号（见「升级判定」章节），**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确选择**：继续 hotfix 流程，还是升级为完整 `/comet` 流程
-2. 任务超过 3 个转入 `/comet-build` 时的工作区隔离和执行方式选择
-3. 验证阶段（comet-verify）的验证失败决策和分支处理决策
-4. 归档前最终确认（comet-archive 执行归档脚本前）
+2. 验证阶段（comet-verify）接受 WARNING/SUGGESTION 偏差、处理 Spec 漂移或超过自动修复上限后的策略决策；前 3 次明确可修复失败自动闭环
+3. 归档前最终确认，以及归档提交后的分支处理决策
 
 执行顺序：快速开启 → 直接构建 → 根因消除检查 → 验证 → 归档 → 完成
 
@@ -150,7 +151,7 @@ Hotfix 流程默认 **一次性连续执行**。调用 `/comet-hotfix` 后，age
 
 ## 升级判定
 
-hotfix 的升级判定只决定是否从预设流程转为 full；文件数不自动升级，`comet-state scale` 只决定验证轻重。
+hotfix 的升级判定只决定是否从预设流程转为 full；文件数不自动升级，`comet state scale` 只决定验证轻重。
 
 若由 `/comet` 入口传入 intent frame，hotfix 在 build 前只复核 `risk_signal` 和升级信号：新增 capability、public API、schema 变更、跨模块协调或深层架构问题。命中时进入现有升级决策点；不得重新实现入口意图识别。
 
@@ -163,10 +164,10 @@ hotfix 的升级判定只决定是否从预设流程转为 full；文件数不
 用户选择升级（选项 B）后，使用状态机合法的升级通道，单条命令完成预设流程 → full 转换并回退到 design 阶段：
 
 ```bash
-node "$COMET_STATE" transition <name> preset-escalate
+comet state transition <name> preset-escalate
 ```
 
-该命令原子地把 `workflow`/`classic_profile` 置为 `full`、`phase` 回退到 `design`、清空 `design_doc`（满足 comet-design 入口要求）。然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**，后续正常走完整流程。
+该命令原子地把 `workflow`/`classic_profile` 置为 `full`、`phase` 回退到 `design`、清空 `design_doc`，并清除预设专属的 `build_mode`、`tdd_mode`、`review_mode`、`isolation` 和 `verify_mode`。然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**；进入 build 后必须重新进行一次完整的联合工作方式选择。
 
 用户选择继续（选项 A）时，继续 hotfix 流程，并记录用户确认继续的原因。
 
@@ -177,16 +178,16 @@ node "$COMET_STATE" transition <name> preset-escalate
 - Bug 已修复，测试通过
 - change 已归档
 - 如有 spec 变更，已同步到 main spec
-- **阶段守卫**：build → verify 前运行 `node "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `node "$COMET_GUARD" <change-name> verify --apply`
+- **阶段守卫**：build → verify 前运行 `comet guard <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `comet guard <change-name> verify --apply`
 
 ## 自动衔接下一阶段
 
 按 `comet/reference/auto-transition.md` 执行。关键命令：
 
 ```bash
-node "$COMET_STATE" next <name>
+comet state next <name>
 ```
 
 - `NEXT: auto` → 调用 `SKILL` 指向的 skill 继续 hotfix 流程（`phase: build` 返回 `comet-hotfix`，`verify` 返回 `comet-verify`，`archive` 返回 `comet-archive`）
-- `NEXT: manual` → 不要调用下一 skill，按 `HINT` 提示用户手动运行 `/<SKILL>`
+- `NEXT: manual` → 不调用下一 skill，按 `HINT` 交还控制权并结束当前调用；不再创建确认点
 - `NEXT: done` → 流程已完成，无需继续

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

@@ -1,6 +1,6 @@
 ---
 name: comet-open
-description: "Use when Comet 需要创建新的 OpenSpec change，或 active change 缺少 proposal/design/tasks/.comet.yaml 初始化产物。"
+description: "仅在用户明确调用 /comet-open，或由 Comet 根 Skill/runtime 路由到 open 阶段时使用；创建或恢复 OpenSpec change，并补齐 proposal/design/tasks/.comet.yaml。"
 ---
 
 # Comet 阶段 1：开启（Open）
@@ -13,11 +13,15 @@ description: "Use when Comet 需要创建新的 OpenSpec change，或 active cha
 
 ### 0. 输出语言约束
 
-传递给 OpenSpec 的所有提问和产物要求都必须包含解析后的 Comet 产物语言，并使用 `en`、`zh-CN` 这类规范化 ID。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `language`；change 初始化后使用 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取。没有配置语言时才回退到当前用户请求语言。生成的 `proposal.md`、`design.md`、`tasks.md` 必须以该语言为主语言。
+传递给 OpenSpec 的所有提问和产物要求都必须包含解析后的 Comet 产物语言，并使用 `en`、`zh-CN` 这类规范化 ID。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `language`；change 初始化后使用 `comet state get <name> language` 读取。没有配置语言时才回退到当前用户请求语言。生成的 `proposal.md`、`design.md`、`tasks.md` 必须以该语言为主语言。
 
 ### 0a. 当前 change 绑定
 
-恢复已有 change 时，第一项状态操作必须是：
+恢复已有 change 时先检查 `openspec/changes/<change-name>/.comet.yaml`：
+
+- 状态文件存在且可解析：第一项状态操作是选择 change
+- 状态文件缺失但 change 目录有效：先运行 `comet state init <change-name> full`，再选择 change
+- 状态文件格式异常：停止并报告解析错误；从版本控制、备份或可验证产物人工修复后再继续，不得用 `state set` 覆盖损坏文件
 
 ```bash
 comet state select <change-name>
@@ -25,6 +29,16 @@ comet state select <change-name>
 
 创建新 change 时，必须先完成 `.comet.yaml` 初始化，再立即运行同一命令；状态文件不存在前不得伪造选择。
 
+### 0b. OpenSpec 兼容性检查
+
+在任何 OpenSpec 状态或指令命令前运行：
+
+```bash
+openspec --version
+```
+
+本流程要求 **OpenSpec >= 1.5.0**。版本低于 1.5.0、无法解析版本、命令不可用或返回非零退出码时立即停止，并提示运行 `npm install -g @fission-ai/openspec@latest` 后重试；不得继续使用缺少 `applyRequires`、`artifactPaths`、`changeRoot` 或 `resolvedOutputPath` 契约的旧 CLI。
+
 ### 1. 探索想法与需求澄清
 
 **立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过此步骤。
@@ -67,36 +81,44 @@ comet state select <change-name>
 
 不得在用户完成 PRD 拆分选择前创建 proposal.md、design.md 或 tasks.md。若用户选择创建多个 change，当前 `/comet-open` 调用只负责完成拆分确认与调度，随后按用户确认的顺序分别进入每个拆分项的 `/comet-open`。
 
+用户确认创建多个 changes 后，必须立即把确认结果持久化到 `.comet/batches/<batch-id>.json`。`batch-id` 使用稳定的 kebab-case 标识；文件至少记录 `version`、原始目标摘要、创建时间、按顺序排列的 change 名称，以及每项的目标、范围、非目标、验收场景和 `pending|open-complete|selected` 状态。每创建或完成一个拆分项后原子更新该文件。它只是批量编排清单，不替代各 change 的 `.comet.yaml`。
+
 批量拆分模式下，进入每个拆分项的 `/comet-open` 时必须明确标注「已确认拆分项」并携带该拆分项的目标、范围、非目标和验收场景。已确认拆分项默认跳过 PRD 拆分预检，除非该拆分项本身仍明显包含多个独立 capability。
 
-批量拆分模式下，单个拆分项完成 open 阶段后不得自动流转到 `/comet-design`。拆分完毕后必须暂停询问用户开始哪一个 change；用户选择后，只推进该 change 进入 `/comet-design`，其他 change 保持 active，稍后通过 `/comet` 恢复。
+批量拆分模式下，单个拆分项完成 open 阶段后不得自动流转到 `/comet-design`。
 
-最小断点恢复规则：不新增专用批量状态文件。若批量拆分过程中断，恢复时先检查已创建的 active changes；已存在且包含 `.comet.yaml` 的拆分项不得重复创建，未创建的拆分项按用户已确认的拆分清单继续通过 `/comet-open` 创建。若对话中已确认的拆分清单不可恢复，必须重新向用户确认拆分清单后再继续。
+**批量完成硬性检查（不得跳过）**：全部拆分项完成各自的 open 阶段后，对用户确认清单中的每个 `<name>` 逐个运行：
 
-### 1b. 需求澄清完成确认（阻塞点）
+```bash
+openspec status --change "<name>" --json
+comet state check <name> design
+```
 
-创建 OpenSpec artifacts 前，必须按 `comet/reference/decision-point.md` 的协议暂停并等待用户确认需求澄清完成。
+解析 OpenSpec JSON 时必须同时确认：
+- `changeRoot` 解析后必须等于仓库内 `openspec/changes/<name>`；不匹配时停止，Classic runtime 不支持仓库外 change root
+- schema 必须包含核心 artifact ID `proposal`、`design`、`tasks`；允许存在额外 artifacts，但核心 ID 缺失时停止并报告不兼容 schema
+- `applyRequires` 列出的每个 artifact 在 `artifacts` 中都必须为 `done`
+- `artifactPaths.<artifact-id>.existingOutputPaths`（或 instructions 返回的 `resolvedOutputPath`）对应的实际输出必须存在且非空
+- `isComplete` 仅作诊断信息；不能替代 `applyRequires` 的实现就绪判定，也不能要求非必需 artifact 阻塞阶段推进
 
-暂停时必须展示澄清摘要：目标、非目标、范围边界、关键未知项、验收场景草案。
+任一拆分项未通过检查时，不得宣告拆分完成，也不得询问用户开始哪个 change；必须停止并从该 change 的第一个 `ready` 或 `blocked` artifact 恢复 `/comet-open`。OpenSpec 检查通过但 Comet state 检查失败时，必须先修复 `.comet.yaml` 初始化或 phase，再重新执行整批检查。
 
-不得在用户确认需求澄清完成前创建 proposal.md、design.md 或 tasks.md，也不得使用 Skill 工具加载 `openspec-propose` 技能一次性生成全部 artifacts。
+只有所有拆分项都通过两项 CLI 检查后，才暂停询问用户开始哪一个 change；用户选择后，把批量清单中的该项标记为 `selected`，只推进该 change 进入 `/comet-design`，其他 change 保持 active，稍后通过 `/comet` 恢复。
 
-### 1c. Change 名称确认（阻塞点）
+断点恢复时先读取 `.comet/batches/<batch-id>.json`，再对清单中已创建的 active changes 运行上述 CLI 检查；已完整通过的拆分项不得重复创建，未通过的拆分项从 OpenSpec 返回的第一个 `ready` artifact 继续。未创建项按持久清单继续创建。清单缺失或损坏时停止并请求用户重建/确认，不能从目录列表猜测原始批次边界。
 
-创建 change 目录（`openspec new change`）前，必须按 `comet/reference/decision-point.md` 的协议暂停，让用户决定 change 名称。不得自动生成或静默推断 change 名称。
+### 1b. 需求与 Change 名称解析（默认不阻塞）
 
-OpenSpec change 名称必须是 **kebab-case 英文**（小写字母、数字、连字符；如 `refine-requirements-doc`）。中文或其他不合规名称无效。
+创建 OpenSpec artifacts 前，把 Step 1 的澄清结果整理为 resolved brief：目标、非目标、范围边界、关键未知项和验收场景草案，并基于它派生一个能准确表达范围的 kebab-case 英文 change 名称。
 
-暂停时必须展示：
-- 基于已确认澄清摘要派生的 **2-3 个推荐 kebab-case 英文名**，每个附一行说明其隐含范围
-- 一个让用户 **自行输入名称** 的明确选项
-- 提示：**若用户输入中文（或任何非 kebab-case 文本），会被转换为合规的 kebab-case 英文名**，转换结果必须回显给用户确认后才能使用
+- **范围与命名都明确时直接继续**，不得仅为了让用户批准摘要或名称而创建停顿点；最终审视会统一确认 change 名称、范围和产物内容
+- 用户已经提供名称时，规范化为 kebab-case 并在进度说明中回显；规范化不改变含义时无需再次确认
+- 已确认批量拆分项直接复用批量清单中的摘要与名称；检测到范围漂移或清单信息缺失时，才重新澄清
+- 只有仍存在会改变范围或目标 change 身份的互斥选择时，才按 `comet/reference/decision-point.md` 提出一个联合问题；命名偏好本身不是独立阻塞点
 
-决策选项必须包含：
-- 选择某个推荐名称
-- 「自行输入名称」——接收用户输入；若已是合规 kebab-case 英文则直接使用；若为中文或其他不合规形式，则转换为合规 kebab-case 英文并回显转换后的名称，确认后再继续
+OpenSpec change 名称必须是 kebab-case 英文（小写字母、数字、单连字符）。若名称冲突但目标仍明确，派生一个不冲突且语义稳定的名称并继续；只有无法判断应复用现有 change 还是创建新 change 时才交给用户选择。
 
-不得在用户确认最终 change 名称前运行 `openspec new change` 或创建 `.comet.yaml`。若选定/转换后的名称与已有 change 冲突，必须报告冲突并请用户另选名称。
+resolved brief 或 change 名称仍不明确时不得运行 `openspec new change`，也不得创建 proposal/design/tasks；继续澄清或处理真正的用户决策后再进入 Step 2。
 
 ### 2. 创建 Change 结构 + 初始化状态
 
@@ -104,35 +126,50 @@ OpenSpec change 名称必须是 **kebab-case 英文**（小写字母、数字、
 
 完整 `/comet` 流程默认不得使用 Skill 工具加载 `openspec-propose` 技能；只有用户明确要求一次性生成提案和 artifacts 时才允许加载。
 
-技能加载后，按其指引创建 change 骨架，但当 Step 1b 的已确认澄清摘要已存在于对话上下文时，覆盖其"STOP and wait for user direction"行为。
+技能加载后，按其指引创建 change 骨架；当 Step 1b 已形成范围明确的 resolved brief 时，覆盖其"STOP and wait for user direction"行为，避免重复询问。
+
+直接使用 Step 1b 的 resolved brief 填充产物内容。只有 brief 仍有会改变范围的歧义时，才回退到技能的提问流程。
+
+change 骨架创建后立即初始化可恢复状态，不能等 artifacts 全部生成后再写 `.comet.yaml`：
 
-如果用户已确认澄清摘要（Step 1b），直接使用该摘要填充产物内容。如果不存在澄清摘要（边缘情况），回退到技能的默认行为，询问用户。
+```bash
+comet state init <name> full
+comet state select <name>
+comet state check <name> open
+```
+
+任一命令失败都停止。随后运行一次 `openspec status --change "<name>" --json` 并执行兼容性预检：
 
-change 骨架创建后，按以下标准产物循环逐个生成 `proposal`、`design`、`tasks`：
+- `changeRoot` 解析后必须等于当前仓库的 `openspec/changes/<name>`，`planningHome`（如存在）也必须位于当前仓库；不支持仓库外 artifact 路径
+- `artifacts` 必须包含核心 ID `proposal`、`design`、`tasks`，额外 artifacts 允许存在
+- `applyRequires` 必须是可解析的 artifact ID 列表，且每个 ID 都存在于 `artifacts`
+- 载荷缺字段、路径越界或核心 ID 缺失时立即停止，不能回退为猜测的固定模板
 
-**标准产物循环**（对每个 `artifact-id`：`proposal` → `design` → `tasks`）：
+预检通过后，按 OpenSpec CLI 返回的 schema 和依赖图生成实现所需 artifacts：
 
-1. 刷新状态：`openspec status --change "<name>" --json`
-2. 获取产物指令：
+**OpenSpec 状态驱动产物循环**：
+
+1. 运行 `openspec status --change "<name>" --json` 并解析完整 JSON。
+2. 若 `applyRequires` 中每一项都已是 `done`，退出循环；`isComplete` 只记录为诊断信息，不作为阶段阻塞条件。
+3. 从尚未完成且为 `status: "ready"` 的 artifacts 中，优先选择能够推进 `applyRequires` 依赖闭包的项，并按 CLI 返回顺序处理。不得硬编码生成顺序，也不得假设 schema 只有 proposal/design/tasks。
+4. 对每个 ready 的 `<artifact-id>` 获取实时指令：
 
    ```bash
-   openspec instructions proposal --change "<name>" --json
-   openspec instructions design --change "<name>" --json
-   openspec instructions tasks --change "<name>" --json
+   openspec instructions <artifact-id> --change "<name>" --json
    ```
 
-3. 对返回的 JSON 指令载荷，必须：
+5. 对返回的 JSON 指令载荷，必须：
    - 读取 `dependencies` 中列出的每个已完成依赖产物
    - 以 `template` 作为产物结构
    - 遵循 `instruction` 的指引
    - 将 `context` 和 `rules` 作为约束条件应用，**不得复制到 artifact 内容中**
-   - 写入 `resolvedOutputPath`
-   - 验证输出文件存在且非空
-4. 每创建一个 artifact 后，重新运行 `openspec status --change "<name>" --json` 确认状态，然后继续下一个 artifact
+   - 写入 `resolvedOutputPath`；通配输出必须按 instruction 创建每个实际文件
+   - 验证 CLI 返回的实际输出文件存在且非空
+6. 每创建一个 artifact 后，重新运行 status，并再次校验 `changeRoot`、核心 ID 和 `applyRequires`。已经变为 `done` 的项不得重复生成；新变为 `ready` 的项进入下一轮。
 
-**失败处理**：如果 `openspec instructions` 失败、返回无效 JSON、报告未满足的 `dependencies`、或未提供可用的 `resolvedOutputPath`，必须立即停止 artifact 创建并报告 OpenSpec 错误。不得回退为硬编码文档结构，因为那样会绕过项目规则。
+**阻塞与失败处理**：`applyRequires` 尚未全部完成但没有任何可推进其依赖闭包的 ready artifact 时，必须报告相关 `blocked` artifact 的 `missingDeps` 并停止，不得猜测顺序或跳过依赖。如果 `openspec status` / `openspec instructions` 失败、返回无效 JSON、路径逃逸仓库、或未提供可用的 `resolvedOutputPath`，也必须立即停止并报告 OpenSpec 错误。不得回退为硬编码文档结构。
 
-**命名与范围守卫**：change name 必须使用 Step 1c 中用户确认的 kebab-case 英文名，不得自动生成、推断或使用非 kebab-case（如中文）名称。变更范围必须与用户描述一致，不得自行扩大或缩小。
+**命名与范围守卫**：change name 必须使用 Step 1b 解析出的 kebab-case 英文名，不得使用非 kebab-case（如中文）名称。变更范围必须与 resolved brief 和用户描述一致，不得自行扩大或缩小。
 
 确认以下产物已创建：
 
@@ -145,43 +182,45 @@ openspec/changes/<name>/
 └── tasks.md          # 任务清单（勾选框）
 ```
 
-创建 `.comet.yaml` 状态文件：
-
-先按 `comet/reference/scripts.md` 定位脚本（定位 `comet-env.mjs`），然后初始化状态：
-
-```bash
-node "$COMET_STATE" init <name> full
-```
-
 ### 3. 入口状态验证
 
 验证状态机已正确初始化：
 
 ```bash
-node "$COMET_STATE" check <name> open
+comet state check <name> open
 ```
 
 验证通过后继续 Step 4。验证失败时脚本会输出具体失败原因。
 
-**幂等性**：open 阶段所有操作可安全重复执行。如 `.comet.yaml` 已处于 `phase: open` 且三个产物文件均已存在，跳过已完成步骤，从第一个缺失步骤继续。
+**幂等恢复算法**：open 阶段所有操作可安全重复执行。恢复时按以下顺序处理：
+
+1. 状态文件缺失时先运行 `comet state init <name> full`；格式异常时停止并修复，不得覆盖。随后选择 change 并运行 `comet state check <name> open`。
+2. 运行 `openspec status --change "<name>" --json`，重新验证 `changeRoot`、核心 ID、`applyRequires`、`artifacts` 和 `missingDeps`。
+3. `done`：该 artifact 已完成，保持原文件不变，不重复生成。
+4. `ready`：依赖已经满足，可以生成。先运行该 artifact 的 `openspec instructions`，按返回内容写入；写完后立刻重新运行 status。
+5. `blocked`：读取 `missingDeps`，先完成属于 `applyRequires` 依赖闭包的依赖 artifact；每完成一个依赖都重新运行 status，不能直接生成 blocked artifact。
+6. 重复上述处理，直到 `applyRequires` 全部为 `done`。
+
+如果必需依赖图无法推进，必须列出相关 blocked artifact 及其 `missingDeps` 后停止并报告。目录或固定三个文件存在不能替代 CLI 判定；反过来，非 `applyRequires` 的可选 artifact 也不能仅因 `isComplete: false` 阻塞进入实现阶段。
 
 ### 4. 内容完整性检查
 
-确认三个文档内容完整：
-- **proposal.md**：问题背景、目标、范围、非目标
-- **design.md**：高层架构决策、方案选型、数据流
-- **tasks.md**：任务列表，每个任务有明确描述
+再次运行 `openspec status --change "<name>" --json`，确认核心 ID 存在、`applyRequires` 每项均为 `done`，且这些必需 artifacts 的 `artifactPaths.<id>.existingOutputPaths` 返回的实际输出文件存在且非空。任一条件不满足时，不得进入 Step 5 或执行阶段守卫。
 
-**文件存在性验证**：逐个确认三个文件路径存在且非空。任一文件缺失或为空时，不得进入 Step 5 或执行阶段守卫，必须回到创建步骤补充。
+随后检查关键 artifact 内容：proposal 覆盖问题、目标、范围和非目标；design 覆盖高层决策与数据流；tasks 包含明确任务；schema 返回 specs 等其他 artifact 时，也必须按其 instructions 检查内容，不能因固定三件套存在而跳过。
 
 ### 5. 用户审视确认（阻塞点）
 
-三个文档创建完成且内容完整性检查通过后，**必须按 `comet/reference/decision-point.md` 的协议暂停并等待用户确认**。不得在用户确认前执行阶段守卫或自动流转。
+全部 OpenSpec artifacts 完成且内容完整性检查通过后，**必须按 `comet/reference/decision-point.md` 的协议暂停并等待用户确认**。不得在用户确认前执行阶段守卫或自动流转。
+
+最终审视同时确认 change 名称、范围和产物内容；不得因 Step 1b 已完成解析而省略，也不得在此之前再增加一次常规摘要/命名确认。
 
 用户确认问题必须以单选题形式呈现，包含以下摘要和选项：
 
 **摘要内容**：
+- **change 名称与 resolved brief**：最终名称、目标、非目标、范围边界和关键未知项
 - **proposal.md**：问题背景、目标、范围
+- **specs 等 schema artifacts**：能力、需求和关键验收场景
 - **design.md**：高层架构决策、方案选型
 - **tasks.md**：任务数量和关键任务描述
 
@@ -193,14 +232,14 @@ node "$COMET_STATE" check <name> open
 
 ## 退出条件
 
-- proposal.md、design.md、tasks.md 均已创建且内容完整
-- **用户已确认** proposal、design、tasks 内容符合预期
-- **阶段守卫**：运行 `node "$COMET_GUARD" <change-name> open --apply`，全部 PASS 后由守卫推进到下一阶段（此步骤更新 `phase` 字段，与 `auto_transition` 无关）
+- `openspec status --change "<name>" --json` 的兼容性预检通过，`applyRequires` 全部为 `done` 且必需输出非空
+- **用户已确认** 全部 OpenSpec artifacts 内容符合预期
+- **阶段守卫**：运行 `comet guard <change-name> open --apply`，全部 PASS 后由守卫推进到下一阶段（此步骤更新 `phase` 字段，与 `auto_transition` 无关）
 
 退出前必须使用 `--apply`，否则 `.comet.yaml` 仍停留在 `phase: open`，下一阶段入口检查会失败。
 
 ```bash
-node "$COMET_GUARD" <change-name> open --apply
+comet guard <change-name> open --apply
 ```
 
 完整流程会自动更新为 `phase: design`；hotfix/tweak 预设会自动更新为 `phase: build`。
@@ -210,11 +249,11 @@ node "$COMET_GUARD" <change-name> open --apply
 按 `comet/reference/auto-transition.md` 执行。关键命令：
 
 ```bash
-node "$COMET_STATE" next <change-name>
+comet state next <change-name>
 ```
 
 - `NEXT: auto` → 调用 `SKILL` 指向的 skill 进入下一阶段
-- `NEXT: manual` → 不要调用下一 skill，按 `HINT` 提示用户手动运行 `/<SKILL>`
+- `NEXT: manual` → 不调用下一 skill，按 `HINT` 交还控制权并结束当前调用；不再创建确认点
 - `NEXT: done` → 流程已完成，无需继续
 
 hotfix/tweak 预设由对应预设 Skill 控制后续流转（phase 直接进入 build），其 `next` 会返回对应预设 Skill。

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

@@ -1,6 +1,6 @@
 ---
 name: comet-tweak
-description: "Use when 用户要进行可收敛为单一 OpenSpec change 的轻量或中等变更，且不需要完整设计；也用于恢复 tweak workflow。"
+description: "仅在用户明确调用 /comet-tweak，或由 Comet 根 Skill/runtime 路由到 tweak preset 时使用；处理可收敛为单一 OpenSpec change 的轻量或中等变更。"
 ---
 
 # Comet 预设路径：Tweak
@@ -23,7 +23,7 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 
 ### 0. 输出语言约束
 
-精简版 OpenSpec 产物必须使用 Comet 配置产物语言。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `language`，初始化后使用 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取。
+精简版 OpenSpec 产物必须使用 Comet 配置产物语言。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `language`，初始化后使用 `comet state get <name> language` 读取。
 
 执行链路：open → OpenSpec apply → verify → archive。Tweak 为每个阶段提供默认决策：精简开启、通过 OpenSpec apply 直接构建、按规模与 delta spec 判定验证轻重、验证通过后进入归档前最终确认。
 
@@ -46,19 +46,22 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 初始化 Comet 状态文件：
 
 ```bash
-node "$COMET_STATE" init <name> tweak
+comet state init <name> tweak
+comet state select <name>
 ```
 
+tweak 默认 `isolation: current`，表示在当前工作区执行；只有用户实际创建/选择了分支或 worktree 后，才能改为 `branch` 或 `worktree`。
+
 初始化后验证状态：
 
 ```bash
-node "$COMET_STATE" check <name> open
+comet state check <name> open
 ```
 
 阶段守卫完成 open → build 过渡：
 
 ```bash
-node "$COMET_GUARD" <change-name> open --apply
+comet guard <change-name> open --apply
 ```
 
 ### 2. OpenSpec apply 构建（tweak 专用预设 build）
@@ -96,7 +99,7 @@ node "$COMET_GUARD" <change-name> open --apply
 运行阶段守卫完成 build → verify 过渡：
 
 ```bash
-node "$COMET_GUARD" <change-name> build --apply
+comet guard <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
@@ -110,10 +113,10 @@ node "$COMET_GUARD" <change-name> build --apply
 **带 delta spec 的验证分流**：tweak 接受 delta spec 作为正常产物。若本次 change 创建了 delta spec，进入 comet-verify 前显式设置完整验证模式，走 OpenSpec 原生验证（`openspec-verify-change`）以覆盖 delta spec 一致性：
 
 ```bash
-node "$COMET_STATE" set <change-name> verify_mode full
+comet state set <change-name> verify_mode full
 ```
 
-无 delta spec 的 tweak 通常满足轻量验证条件（≤ 3 tasks、改动文件数低于 scale 阈值），由 comet-verify 的规模评估选择轻量验证路径（6 项快速检查）。若用户希望增加审查，可在验证前运行 `node "$COMET_STATE" set <name> review_mode standard` 或 `thorough`。
+无 delta spec 的 tweak 通常满足轻量验证条件（≤ 3 tasks、改动文件数低于 scale 阈值），由 comet-verify 的规模评估选择轻量验证路径（6 项快速检查）。若用户希望增加审查，可在验证前运行 `comet state set <name> review_mode standard` 或 `thorough`。
 
 验证通过后，按 `/comet-verify` 的规则将 `.comet.yaml` 的 `verify_result` 记录为 `pass`，归档前不得跳过该状态。验证通过后仍必须进入 `/comet-archive` 的归档前最终确认，不得自动运行归档脚本。
 
@@ -128,11 +131,11 @@ node "$COMET_STATE" set <change-name> verify_mode full
 ## 连续执行模式
 
 <IMPORTANT>
-Tweak 流程默认 **一次性连续执行**。调用 `/comet-tweak` 后，agent 在 tweak 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界（build/verify/archive 之间）停下，由用户手动运行下一阶段命令——此时连续执行降级为逐阶段手动推进，详见下方「自动衔接下一阶段」。但无论 `auto_transition` 取何值，以下情况都必须暂停等待用户确认：
+Tweak 流程默认 **一次性连续执行**。调用 `/comet-tweak` 后，agent 在 tweak 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界（build/verify/archive 之间）结束当前调用并按 `HINT` 交还控制权，由用户稍后手动运行下一阶段命令；这是手动衔接，不是新的确认点。无论 `auto_transition` 取何值，以下真正的用户决策仍需暂停：
 
 1. 遇到升级判定信号（见「升级判定」章节），**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确选择**：继续 tweak 轻量流程，还是升级为完整 `/comet` 流程
-2. 验证阶段（comet-verify）的验证失败决策和分支处理决策
-3. 归档前最终确认（comet-archive 执行归档脚本前）
+2. 验证阶段（comet-verify）接受 WARNING/SUGGESTION 偏差、处理 Spec 漂移或超过自动修复上限后的策略决策；前 3 次明确可修复失败自动闭环
+3. 归档前最终确认，以及归档提交后的分支处理决策
 
 执行顺序：快速开启 → 构建（含升级判定检查）→ 验证 → 归档 → 完成
 
@@ -143,7 +146,7 @@ Tweak 流程默认 **一次性连续执行**。调用 `/comet-tweak` 后，agent
 
 ## 升级判定
 
-tweak 的升级判定只决定是否从轻量预设转为 full；delta spec 本身不是升级理由，文件数不自动升级，`comet-state scale` 只决定验证轻重。
+tweak 的升级判定只决定是否从轻量预设转为 full；delta spec 本身不是升级理由，文件数不自动升级，`comet state scale` 只决定验证轻重。
 
 若由 `/comet` 入口传入 intent frame，tweak 在 build 前只复核 `risk_signal` 和升级信号：新增 capability、public API、schema 变更、跨模块协调或深层架构问题。命中时进入现有升级决策点；delta spec 仍是 tweak 的正常产物，不因存在 delta spec 自动升级；不得重新实现入口意图识别。
 
@@ -156,10 +159,10 @@ tweak 的升级判定只决定是否从轻量预设转为 full；delta spec 本
 用户选择升级（选项 B）后，使用状态机合法的升级通道，单条命令完成预设流程 → full 转换并回退到 design 阶段：
 
 ```bash
-node "$COMET_STATE" transition <name> preset-escalate
+comet state transition <name> preset-escalate
 ```
 
-该命令原子地把 `workflow`/`classic_profile` 置为 `full`、`phase` 回退到 `design`、清空 `design_doc`（满足 comet-design 入口要求）。然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**，后续正常走完整流程。
+该命令原子地把 `workflow`/`classic_profile` 置为 `full`、`phase` 回退到 `design`、清空 `design_doc`，并清除预设专属的 `build_mode`、`tdd_mode`、`review_mode`、`isolation` 和 `verify_mode`。然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**；进入 build 后必须重新进行一次完整的联合工作方式选择。
 
 用户选择继续（选项 A）时，继续 tweak 流程，并记录用户确认继续的原因。
 
@@ -170,16 +173,16 @@ node "$COMET_STATE" transition <name> preset-escalate
 - 变更已完成，测试通过
 - change 已归档
 - 如有 spec 变更，已同步到 main spec
-- **阶段守卫**：build → verify 前运行 `node "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `node "$COMET_GUARD" <change-name> verify --apply`
+- **阶段守卫**：build → verify 前运行 `comet guard <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `comet guard <change-name> verify --apply`
 
 ## 自动衔接下一阶段
 
 按 `comet/reference/auto-transition.md` 执行。关键命令：
 
 ```bash
-node "$COMET_STATE" next <name>
+comet state next <name>
 ```
 
 - `NEXT: auto` → 调用 `SKILL` 指向的 skill 继续 tweak 流程（`phase: build` 返回 `comet-tweak`，`verify` 返回 `comet-verify`，`archive` 返回 `comet-archive`）
-- `NEXT: manual` → 不要调用下一 skill，按 `HINT` 提示用户手动运行 `/<SKILL>`
+- `NEXT: manual` → 不调用下一 skill，按 `HINT` 交还控制权并结束当前调用；不再创建确认点
 - `NEXT: done` → 流程已完成，无需继续