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

package/assets/skills-zh/comet/reference/scripts.md

@@ -1,12 +1,30 @@
-# 脚本定位与命令
+# 稳定 CLI 与内部脚本兼容说明
 
 规范路径：`comet/reference/scripts.md`
 
-本文件是 Comet 脚本定位和 state/guard/handoff/archive 命令面的单一事实来源。每会话加载一次，然后复用缓存的环境变量。
+本文件是 Comet 公开 CLI 与内部脚本兼容方式的单一事实来源。公开工作流必须优先使用稳定命令面：`comet state`、`comet guard`、`comet handoff`、`comet archive`。
 
-## 引导（每会话运行一次）
+## 公开工作流协议
 
-Comet 脚本随 skill 包分发在 `comet/scripts/` 下。**不硬编码路径** — 定位一次，缓存到环境变量。子 Skill 可以直接引用本节，只有需要完全自包含执行时才内联此块；修改时以本文件为单一事实源：
+正常安装和日常工作流直接使用 `comet` CLI，不需要定位 launcher，也不要向用户暴露内部 `classic` 命名：
+
+```bash
+comet state select <change-name>
+comet state current
+comet state clear-selection
+comet state check <change-name> <phase>
+comet guard <change-name> <phase> --apply
+comet handoff <change-name>
+comet archive <change-name>
+```
+
+当多个 active change 共存时，进入明确的 change 后先运行 `comet state select <change-name>`。普通源码写入只受该选择管辖；尚未选择时 hook 会阻塞并要求选择。单 active change 可继续自动归属。切换 branch/worktree 或选择失效后必须重新运行 `select`。
+
+guard 的 `--apply` 在检查通过后推进状态。需要直接表达状态事件时使用 `comet state transition`；阶段推进后使用 `comet state next` 解析是否自动调用下一 Skill。
+
+## 兼容、恢复与内部命令引导
+
+以下脚本定位只用于旧版兼容、CLI 不可用时的恢复，以及 `/comet` 内部入口命令。正常公开工作流不得优先采用此方式。Comet 脚本随 Skill 包分发在 `comet/scripts/` 下；需要恢复时不要硬编码路径，而应定位一次并缓存环境变量：
 
 ```bash
 COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.mjs' -type f -print -quit 2>/dev/null)}"
@@ -20,6 +38,7 @@ COMET_GUARD="$COMET_SCRIPTS_DIR/comet-guard.mjs"
 COMET_HANDOFF="$COMET_SCRIPTS_DIR/comet-handoff.mjs"
 COMET_ARCHIVE="$COMET_SCRIPTS_DIR/comet-archive.mjs"
 COMET_INTENT="$COMET_SCRIPTS_DIR/comet-intent.mjs"
+COMET_RESUME_PROBE="$COMET_SCRIPTS_DIR/comet-resume-probe.mjs"
 
 # 脚本定位失败时停止流程
 if [ -z "$COMET_SCRIPTS_DIR" ]; then
@@ -28,34 +47,47 @@ if [ -z "$COMET_SCRIPTS_DIR" ]; then
 fi
 ```
 
-加载 comet 后，agent 应执行以上变量赋值一次，后续全程复用 `$COMET_GUARD`、`$COMET_STATE`、`$COMET_HANDOFF`、`$COMET_ARCHIVE`、`$COMET_INTENT`。
+只有进入上述兼容、恢复或内部命令路径时，Agent 才执行这些变量赋值。`COMET_INTENT` 和 `COMET_RESUME_PROBE` 仍是内部入口引导所需变量，不应全局移除。
+
+| 变量 | 用途 |
+|------|------|
+| `COMET_STATE` | `.comet.yaml` 状态读写、phase 检查和恢复上下文 |
+| `COMET_GUARD` | 阶段退出守卫和 `--apply` 状态推进 |
+| `COMET_HANDOFF` | Design/Build handoff 上下文包生成 |
+| `COMET_ARCHIVE` | 一键归档和主 spec 同步 |
+| `COMET_INTENT` | `/comet` 入口意图识别和路由评分 |
+| `COMET_RESUME_PROBE` | 只读 Ambient Resume 探针，判断是否应恢复 active Comet workflow |
 
 ## 自动状态更新
 
 guard 支持 `--apply` 参数，验证通过后自动更新 `.comet.yaml` 状态字段：
 
 ```bash
-node "$COMET_GUARD" <change-name> <phase> --apply
+comet guard <change-name> <phase> --apply
 ```
 
-`--apply` 内部委托给 `comet-state transition`。需要直接表达状态事件时使用：
+`--apply` 内部委托给状态机 transition。需要直接表达状态事件时使用：
 
 ```bash
-node "$COMET_STATE" transition <change-name> open-complete
-node "$COMET_STATE" transition <change-name> design-complete
-node "$COMET_STATE" transition <change-name> build-complete
-node "$COMET_STATE" transition <change-name> verify-pass
-node "$COMET_STATE" transition <change-name> verify-fail
+comet state transition <change-name> open-complete
+comet state transition <change-name> design-complete
+comet state transition <change-name> build-complete
+comet state transition <change-name> verify-pass
+comet state transition <change-name> verify-fail
+comet state transition <change-name> archive-confirm
+comet state transition <change-name> archive-reopen
+comet state transition <change-name> archived
+comet state transition <change-name> preset-escalate
 ```
 
-归档完成由 `node "$COMET_ARCHIVE" <change-name>` 负责；OpenSpec 会把 change 移到带日期前缀的归档目录，不要手动 transition 一个 `<archive-name>`。
+归档完成由 `comet archive <change-name>` 负责；OpenSpec 会先把 change 移到带日期前缀的归档目录，再由 Comet 完成状态记录。预归档确认使用 `archive-confirm` 或 `archive-reopen`；不要在归档流程之外手动执行 `archived` transition。
 
 ## 解析下一步
 
 阶段守卫推进 phase 后，用 `next` 子命令解析是否自动调用下一个 skill：
 
 ```bash
-node "$COMET_STATE" next <change-name>
+comet state next <change-name>
 ```
 
 输出 `NEXT: auto|manual|done` + `SKILL: <skill-name>`（`done` 时省略）+ `HINT`（仅 `manual` 时）。`auto_transition: false` 时输出 `manual`，只暂停下一 skill 调用，不影响已发生的 phase 推进。
@@ -65,5 +97,5 @@ node "$COMET_STATE" next <change-name>
 一键完成归档全部步骤：
 
 ```bash
-node "$COMET_ARCHIVE" <change-name>
+comet archive <change-name>
 ```

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

@@ -15,21 +15,22 @@ description: "Use when Comet change 验证已通过，需要用户确认归档
 
 ### 0. 输出语言约束
 
-归档摘要和生命周期闭环说明必须使用 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取到的 Comet 配置产物语言。
+归档摘要和生命周期闭环说明必须使用 `comet state get <name> language` 读取到的 Comet 配置产物语言。
 
 ### 0b. 入口状态验证（Entry Check）
 
-按 `comet/reference/scripts.md` 定位脚本（定位 `comet-env.mjs`），然后执行入口验证；从任意入口恢复时先按 `comet/reference/context-recovery.md` 运行恢复检查：
+按 `comet/reference/scripts.md` 使用稳定 `comet` CLI，然后执行入口验证；从任意入口恢复时先按 `comet/reference/context-recovery.md` 运行恢复检查：
 
 ```bash
-node "$COMET_STATE" check <name> archive
+comet state select <change-name>
+comet state check <name> archive
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
 
 ### 1. 归档前最终确认（阻塞点）
 
-入口验证通过后，**必须按 `comet/reference/decision-point.md` 的协议暂停并等待用户确认是否立即归档**。不得在用户确认前运行 `node "$COMET_ARCHIVE" "<change-name>"`。
+入口验证通过后，**必须按 `comet/reference/decision-point.md` 的协议暂停并等待用户确认是否立即归档**。不得在用户确认前运行 `comet archive "<change-name>"`。
 
 确认前必须向用户展示简短摘要：
 - change 名称
@@ -38,22 +39,28 @@ node "$COMET_STATE" check <name> archive
 - 本次归档将执行的不可逆动作：按 OpenSpec delta 语义合并主 spec、标注 design doc / plan、移动 change 到 archive 目录
 
 用户确认问题必须以单选题形式呈现，包含以下选项：
-- 「确认归档」— 立即执行归档脚本，完成 spec 合并和 change 移动
-- 「需要调整或重新验证」— 不执行归档；运行 `node "$COMET_STATE" transition <change-name> archive-reopen` 回到 `phase: verify`，再调用 `/comet-verify`。若验证阶段确认需要修复，再按 `/comet-verify` 的验证失败决策回到 `/comet-build`
+- 「确认归档」— 写入最终确认状态后执行归档脚本，完成 spec 合并和 change 移动
+- 「需要调整或重新验证」— 不执行归档；运行 `comet state transition <change-name> archive-reopen` 回到 `phase: verify`，再调用 `/comet-verify`。若验证阶段确认需要修复，再按 `/comet-verify` 的验证失败决策回到 `/comet-build`
 - 「暂不归档」— 不执行归档，保留当前 `phase: archive` 状态，等待用户稍后再次调用 `/comet-archive`
 
-只有用户选择「确认归档」后，才允许继续 Step 2。用户选择「需要调整或重新验证」后，必须先执行 `archive-reopen` 状态回退，不得手动编辑 `.comet.yaml`。
+用户选择「确认归档」后，立即执行：
+
+```bash
+comet state transition <change-name> archive-confirm
+```
+
+如 transition 返回非零退出码，报告错误并停止。只有 transition 成功后，才允许继续 Step 2。用户选择「需要调整或重新验证」后，必须先执行 `archive-reopen` 状态回退，不得手动编辑 `.comet.yaml`。
 
 ### 2. 执行归档
 
-运行归档脚本，自动完成以下全部步骤：
+运行归档脚本：
 
 ```bash
-node "$COMET_ARCHIVE" "<change-name>"
+comet archive "<change-name>"
 ```
 
 脚本自动执行：
-1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
+1. 入口状态验证（phase=archive, verify_result=pass, archive_confirmation=confirmed, archived=false）
 2. Design doc 前置元数据标注（archived-with, status）
 3. Plan 前置元数据标注（archived-with）
 4. 调用 OpenSpec archive 按 delta 语义合并主 spec 并移动 change 到归档目录
@@ -62,6 +69,12 @@ node "$COMET_ARCHIVE" "<change-name>"
 
 如脚本返回非零退出码，报告错误并停止。
 如脚本返回零退出码，归档完成。
+
+归档成功后清理当前执行上下文；该命令幂等：
+
+```bash
+comet state clear-selection
+```
 脚本摘要中的 `X/Y steps succeeded` 以真实执行步骤计数，不会因 delta spec 同步或文档标注重复累计。
 
 脚本会调用 OpenSpec 归档能力按 `ADDED/MODIFIED/REMOVED/RENAMED` 语义合并主 spec，并在归档后校验主 spec 中没有残留 delta-only section 标题。
@@ -99,7 +112,7 @@ git commit -m "chore: archive <change-name>"
 
 归档脚本会把 `openspec/changes/<name>/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。
 
-> **WARNING**: 归档成功后**不要再对原 change 名运行** `node "$COMET_GUARD" <change-name> archive`，因为原活跃目录已经不存在。误调会导致 guard 报错"change directory not found"。归档完整性以脚本退出码和归档目录状态为准。
+> **WARNING**: 归档成功后**不要再对原 change 名运行** `comet guard <change-name> archive`，因为原活跃目录已经不存在。误调会导致 guard 报错"change directory not found"。归档完整性以脚本退出码和归档目录状态为准。
 
 ## 完成
 

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

@@ -14,10 +14,11 @@ description: "Use when full Comet change 已完成 design 阶段，需要创建/
 
 ### 0. 入口状态验证（Entry Check）
 
-按 `comet/reference/scripts.md` 定位脚本（定位 `comet-env.mjs`），然后执行入口验证；从任意入口恢复时先按 `comet/reference/context-recovery.md` 运行恢复检查：
+按 `comet/reference/scripts.md` 使用稳定 `comet` CLI，然后执行入口验证；从任意入口恢复时先按 `comet/reference/context-recovery.md` 运行恢复检查：
 
 ```bash
-node "$COMET_STATE" check <name> build
+comet state select <change-name>
+comet state check <name> build
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
@@ -26,13 +27,13 @@ node "$COMET_STATE" check <name> build
 
 ### 1. 制定计划（Subagent Offload）
 
-通过 subagent 创建实施计划，避免 planning skill 占用主 session 上下文。计划文件和执行反馈必须使用 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取到的 Comet 配置产物语言。
+通过 subagent 创建实施计划，避免 planning skill 占用主 session 上下文。计划文件和执行反馈必须使用 `comet state get <name> language` 读取到的 Comet 配置产物语言。
 
 **Subagent 指令**：
 
 你是实施计划专家。基于以下输入创建实施计划：
 
-1. **立即执行：** 使用 Skill 工具加载 Superpowers `writing-plans` 技能。禁止跳过此步骤。技能加载后，ARGUMENTS 必须包含：`Language: 使用 "$COMET_BASH" "$COMET_STATE" get <name> language 读取到的 Comet 配置产物语言输出`
+1. **立即执行：** 使用 Skill 工具加载 Superpowers `writing-plans` 技能。禁止跳过此步骤。技能加载后，ARGUMENTS 必须包含：`Language: 使用 comet state get <name> language 读取到的 Comet 配置产物语言输出`
 2. 读取 Design Doc（`docs/superpowers/specs/` 下的技术设计文档）
 3. 读取 `openspec/changes/<name>/tasks.md`（任务边界）
 4. 按技能指引创建计划
@@ -69,7 +70,7 @@ Subagent 完成后：
 先记录 plan 路径：
 
 ```bash
-node "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
+comet state set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 ```
 
 无需手动更新 phase，阶段守卫（guard `--apply`）会在退出条件满足后推进 `phase` 字段。
@@ -86,13 +87,13 @@ node "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 用户选择继续时：
 
 ```bash
-node "$COMET_STATE" set <name> build_pause null
+comet state set <name> build_pause null
 ```
 
 用户选择暂停时：
 
 ```bash
-node "$COMET_STATE" set <name> build_pause plan-ready
+comet state set <name> build_pause plan-ready
 ```
 
 设置 `build_pause: plan-ready` 后，当前调用停止。不要选择 `isolation` 或 `build_mode`，不要加载执行技能。
@@ -102,7 +103,7 @@ node "$COMET_STATE" set <name> build_pause plan-ready
 如果恢复时检测到 `build_pause: plan-ready` 且 `plan` 文件存在，不要重新运行 `writing-plans`。先告知用户当前停在 plan-ready 暂停点；用户确认继续后，设置：
 
 ```bash
-node "$COMET_STATE" set <name> build_pause null
+comet state set <name> build_pause null
 ```
 
 然后继续本步骤选择工作区隔离、执行方式、TDD 模式和代码审查模式。
@@ -137,11 +138,11 @@ node "$COMET_STATE" set <name> build_pause null
 用户选择后，更新 `isolation`、执行方式、TDD 模式和代码审查模式相关字段：
 
 ```bash
-node "$COMET_STATE" set <name> isolation <branch|worktree>
+comet state set <name> isolation <branch|worktree>
 ```
 
-- 若用户选择 `executing-plans`：运行 `node "$COMET_STATE" set <name> subagent_dispatch null`，再运行 `node "$COMET_STATE" set <name> build_mode executing-plans`
-- 若用户选择 `subagent-driven-development`：先确认当前平台存在可调用的真实后台 subagent / Task / multi-agent 调度能力；确认后先运行 `node "$COMET_STATE" set <name> subagent_dispatch confirmed`，再运行 `node "$COMET_STATE" set <name> build_mode subagent-driven-development`
+- 若用户选择 `executing-plans`：运行 `comet state set <name> subagent_dispatch null`，再运行 `comet state set <name> build_mode executing-plans`
+- 若用户选择 `subagent-driven-development`：先确认当前平台存在可调用的真实后台 subagent / Task / multi-agent 调度能力；确认后先运行 `comet state set <name> subagent_dispatch confirmed`，再运行 `comet state set <name> build_mode subagent-driven-development`
 - 若无法确认真实后台调度能力，不得写入 `build_mode: subagent-driven-development`；必须暂停等待用户改选 `executing-plans`
 
 **TDD 模式**：
@@ -151,7 +152,7 @@ node "$COMET_STATE" set <name> isolation <branch|worktree>
 | `tdd` | 每个任务先写失败测试再写实现 | 推荐。变更涉及业务逻辑、新功能、API |
 | `direct` | 直接实现，不强制 TDD 流程 | 变更不需要测试覆盖，或用户选择跳过测试直接写代码。hotfix/tweak 预设默认使用 `direct` |
 
-运行 `node "$COMET_STATE" set <name> tdd_mode <tdd|direct>`
+运行 `comet state set <name> tdd_mode <tdd|direct>`
 
 **代码审查模式**：
 
@@ -161,21 +162,21 @@ node "$COMET_STATE" set <name> isolation <branch|worktree>
 | `standard` | 默认不为每任务派发 reviewer，仅当任务命中风险信号时派发每任务 reviewer，外加一次最终轻量代码审查 | 默认推荐，适合大多数普通改动 |
 | `thorough` | 为每个任务派发每任务 reviewer（spec + quality），外加一次最终完整审查 | 高风险、多模块、架构或安全相关改动 |
 
-运行 `node "$COMET_STATE" set <name> review_mode <off|standard|thorough>`
+运行 `comet state set <name> review_mode <off|standard|thorough>`
 
-`isolation` 是脚本级硬约束。full workflow 初始化时可以为 `null`，但只允许存在到本步骤之前。若保持 `null`，`build → verify` 的 guard 和 `comet-state transition build-complete` 都会失败。
+`isolation` 是脚本级硬约束。full workflow 初始化时可以为 `null`，但只允许存在到本步骤之前。若保持 `null`，`build → verify` 的 guard 和 `comet state transition build-complete` 都会失败。
 
-`subagent_dispatch` 是脚本级硬约束。`build_mode: subagent-driven-development` 离开 build 阶段前必须同时满足 `subagent_dispatch: confirmed`，否则 `comet-guard.mjs build --apply` 和 `comet-state transition build-complete` 都会失败。
+`subagent_dispatch` 是脚本级硬约束。`build_mode: subagent-driven-development` 离开 build 阶段前必须同时满足 `subagent_dispatch: confirmed`，否则 `comet guard build --apply` 和 `comet state transition build-complete` 都会失败。
 
-`tdd_mode` 是脚本级硬约束。full workflow 离开 build 阶段前 `tdd_mode` 必须已选择为 `tdd` 或 `direct`，否则 `comet-guard.mjs build --apply` 和 `comet-state transition build-complete` 都会失败。
+`tdd_mode` 是脚本级硬约束。full workflow 离开 build 阶段前 `tdd_mode` 必须已选择为 `tdd` 或 `direct`，否则 `comet guard build --apply` 和 `comet state transition build-complete` 都会失败。
 
-`review_mode` 是脚本级硬约束。新建 full workflow 离开 build 阶段前 `review_mode` 必须已选择为 `off`、`standard` 或 `thorough`，否则 `comet-guard.mjs build --apply` 和 `comet-state transition build-complete` 都会失败。旧状态文件若没有该字段，按兼容路径继续，但恢复时应补写该字段。
+`review_mode` 是脚本级硬约束。新建 full workflow 离开 build 阶段前 `review_mode` 必须已选择为 `off`、`standard` 或 `thorough`，否则 `comet guard build --apply` 和 `comet state transition build-complete` 都会失败。旧状态文件若没有该字段，按兼容路径继续，但恢复时应补写该字段。
 
 `build_mode` 默认仅 hotfix/tweak 预设使用 `direct`。full workflow 不得默认使用 `direct`。只有用户明确要求跳过计划执行技能，且你已记录显式 override 时，才允许：
 
 ```bash
-node "$COMET_STATE" set <name> direct_override true
-node "$COMET_STATE" set <name> build_mode direct
+comet state set <name> direct_override true
+comet state set <name> build_mode direct
 ```
 
 没有 `direct_override: true` 时，full workflow 的 `build_mode=direct` 会被 guard 和状态转换同时拦截。
@@ -204,11 +205,19 @@ git add docs/superpowers/plans/YYYY-MM-DD-feature.md
 git commit -m "chore: add implementation plan"
 ```
 
+进入最终执行分支或 worktree 后，必须在该实际工作区重新绑定当前 change。branch 切换会使入口绑定失效，新 worktree 也不会继承原工作区的本地选择文件：
+
+```bash
+comet state select <change-name>
+```
+
+重新绑定成功后才能开始源码写入。
+
 **执行计划**：必须按 `build_mode` 的真实运行位置处理。
 
-- `build_mode: executing-plans`：**立即执行：** 使用 Skill 工具加载 Superpowers `executing-plans` 技能。禁止跳过此步骤。若该技能不可用，停止流程并提示安装或启用对应技能，不要用普通对话替代该步骤。技能加载后，ARGUMENTS 必须包含与 Step 1 相同的 Language 约束：`Language: 使用 "$COMET_BASH" "$COMET_STATE" get <name> language 读取到的 Comet 配置产物语言输出`。按计划执行。
+- `build_mode: executing-plans`：**立即执行：** 使用 Skill 工具加载 Superpowers `executing-plans` 技能。禁止跳过此步骤。若该技能不可用，停止流程并提示安装或启用对应技能，不要用普通对话替代该步骤。技能加载后，ARGUMENTS 必须包含与 Step 1 相同的 Language 约束：`Language: 使用 comet state get <name> language 读取到的 Comet 配置产物语言输出`。按计划执行。
 - `build_mode: subagent-driven-development`：主会话只负责协调，禁止直接编写实现代码。**立即执行：** 使用 Skill 工具加载 Superpowers `subagent-driven-development` 技能。技能加载后，读取 `comet/reference/subagent-dispatch.md` 获取 Comet 专属扩展（真实后台调度、任务隔离、勾选验证、TDD 约束、连续执行、上下文恢复），与技能工作流配合应用。若两者发生冲突，以更具体的 Comet 扩展为准。
-- 如果当前平台没有真实后台 agent 调度能力，必须暂停并等待用户选择改用主窗口执行。用户选择改用主窗口执行后，必须先运行 `node "$COMET_STATE" set <name> build_mode executing-plans`，再按 `build_mode: executing-plans` 分支加载 Superpowers `executing-plans` 技能。用户未明确选择前，不得继续执行任务。
+- 如果当前平台没有真实后台 agent 调度能力，必须暂停并等待用户选择改用主窗口执行。用户选择改用主窗口执行后，必须先运行 `comet state set <name> build_mode executing-plans`，再按 `build_mode: executing-plans` 分支加载 Superpowers `executing-plans` 技能。用户未明确选择前，不得继续执行任务。
 
 **TDD 模式执行约束**：
 
@@ -227,7 +236,7 @@ git commit -m "chore: add implementation plan"
 - **`review_mode: thorough`**：除最终那次审查外，按任务分段每 3 个任务请求一次分段代码审查（范围限于该段的 diff）。若总任务数 ≤ 3，跳过执行中分段，只做最终审查。每次分段审查用 `requesting-code-review` 针对该段的提交区间进行。这是 `executing-plans` 下最接近 `subagent-driven-development` 每任务审查的等价物，因为它没有隔离的 implementer 可供逐任务审查。
 
 要求（适用于 `standard` 和 `thorough`）：
-- `requesting-code-review` 技能必须在 `node "$COMET_GUARD" <change-name> build --apply` 之前加载
+- `requesting-code-review` 技能必须在 `comet guard <change-name> build --apply` 之前加载
 - 若 `requesting-code-review` 技能不可用，跳过 review gate 但必须在 tasks.md 中记录 `<!-- review skipped: skill unavailable -->`，并继续 guard 流转
 - CRITICAL review 发现（安全漏洞、数据丢失风险、构建/测试失败）必须先修复，不得带入 verify
 - 非 CRITICAL review 发现如选择接受，必须在 tasks.md、commit body、验证报告草稿或其他持久产物中记录接受原因和影响范围
@@ -282,14 +291,22 @@ Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后
 - `tdd_mode` 已写为 `tdd` 或 `direct`
 - `review_mode` 已写为 `off`、`standard` 或 `thorough`
 - 已按所选 `review_mode` 完成"执行计划"章节中 executing-plans review gate 规定的代码审查：`standard` 或 `thorough` 下已请求代码审查且 CRITICAL review 发现已修复、非 CRITICAL review 发现已记录接受理由；`review_mode: off` 下已在持久产物中记录跳过自动代码审查的原因
-- **阶段守卫**：运行 `node "$COMET_GUARD" <change-name> build --apply`，全部 PASS 后由守卫推进到 `phase: verify`（此步骤更新 `phase` 字段，与 `auto_transition` 无关）
+- **阶段守卫**：运行 `comet guard <change-name> build --apply`，全部 PASS 后由守卫推进到 `phase: verify`（此步骤更新 `phase` 字段，与 `auto_transition` 无关）
 
 Guard 会运行自动探测到的项目构建检查（检测到时使用 `npm run build`、Maven 或 Cargo）。构建失败时 guard 会打印失败命令输出，作为排查证据。
 
+若项目没有可自动探测的构建命令，用户或 Agent 必须先自行运行真实构建命令，再单独记录构建证据：
+
+```bash
+comet state record-check <change-name> build --command "<实际运行的构建命令>" --exit-code 0
+```
+
+`--command` 只记录命令文本，Comet **绝不会执行该文本**。build 与 verify 证据彼此独立，不能互相替代。`COMET_SKIP_BUILD=1` 仅是旧流程的兼容绕过方式，不是可审计的构建证据。
+
 退出前运行阶段守卫推进 phase（此步骤与 `auto_transition` 无关）：
 
 ```bash
-node "$COMET_GUARD" <change-name> build --apply
+comet guard <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`。
@@ -299,7 +316,7 @@ node "$COMET_GUARD" <change-name> build --apply
 按 `comet/reference/auto-transition.md` 执行。关键命令：
 
 ```bash
-node "$COMET_STATE" next <change-name>
+comet state next <change-name>
 ```
 
 - `NEXT: auto` → 调用 `SKILL` 指向的 skill 进入下一阶段

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

@@ -19,6 +19,7 @@ description: "Use when full Comet change 已完成 open 阶段但缺少 Superpow
 按 `comet/reference/scripts.md` 定位脚本（定位 `comet-env.mjs`），然后执行入口验证；从任意入口恢复时先按 `comet/reference/context-recovery.md` 运行恢复检查：
 
 ```bash
+comet state select <change-name>
 node "$COMET_STATE" check <name> design
 ```
 

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

@@ -20,12 +20,14 @@ description: "Use when 用户要修复已有行为 bug，且不新增 capability
 
 ### 0. 输出语言约束
 
-精简版 OpenSpec 产物必须使用 Comet 配置产物语言。`.comet.yaml` 尚不存在时读取 `.comet/config.yaml` 的 `language`，初始化后使用 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取。
+精简版 OpenSpec 产物必须使用 Comet 配置产物语言。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `language`，初始化后使用 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取。
 
 执行链路：open → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后进入归档前最终确认。
 
 开始前按 `comet/reference/scripts.md` 定位 Comet 脚本（定位 `comet-env.mjs`）；从任意入口恢复时先按 `comet/reference/context-recovery.md` 确认 phase/workflow。
 
+恢复已有 hotfix change 时，第一项状态操作必须是 `comet state select <change-name>`；创建新 change 时，在 `.comet.yaml` 初始化成功后立即运行该命令，再进入源码写入步骤。
+
 ### 1. 快速开启（预设 open）
 
 复用 Comet open 能力创建 change，但使用 hotfix 默认值：不执行 `openspec-explore` 长探索，直接进入精简 change 创建。

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

@@ -13,7 +13,17 @@ description: "Use when Comet 需要创建新的 OpenSpec change，或 active cha
 
 ### 0. 输出语言约束
 
-传递给 OpenSpec 的所有提问和产物要求都必须包含解析后的 Comet 产物语言，并使用 `en`、`zh-CN` 这类规范化 ID。`.comet.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_BASH" "$COMET_STATE" get <name> language` 读取。没有配置语言时才回退到当前用户请求语言。生成的 `proposal.md`、`design.md`、`tasks.md` 必须以该语言为主语言。
+
+### 0a. 当前 change 绑定
+
+恢复已有 change 时，第一项状态操作必须是：
+
+```bash
+comet state select <change-name>
+```
+
+创建新 change 时，必须先完成 `.comet.yaml` 初始化，再立即运行同一命令；状态文件不存在前不得伪造选择。
 
 ### 1. 探索想法与需求澄清
 

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

@@ -23,12 +23,14 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 
 ### 0. 输出语言约束
 
-精简版 OpenSpec 产物必须使用 Comet 配置产物语言。`.comet.yaml` 尚不存在时读取 `.comet/config.yaml` 的 `language`，初始化后使用 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取。
+精简版 OpenSpec 产物必须使用 Comet 配置产物语言。`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `language`，初始化后使用 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取。
 
 执行链路：open → OpenSpec apply → verify → archive。Tweak 为每个阶段提供默认决策：精简开启、通过 OpenSpec apply 直接构建、按规模与 delta spec 判定验证轻重、验证通过后进入归档前最终确认。
 
 开始前按 `comet/reference/scripts.md` 定位 Comet 脚本（定位 `comet-env.mjs`）；从任意入口恢复时先按 `comet/reference/context-recovery.md` 确认 phase/workflow。
 
+恢复已有 tweak change 时，第一项状态操作必须是 `comet state select <change-name>`；创建新 change 时，在 `.comet.yaml` 初始化成功后立即运行该命令，再进入源码写入步骤。
+
 ### 1. 快速开启（预设 open）
 
 复用 Comet open 能力创建 change，但使用 tweak 默认值：不执行 `openspec-explore` 长探索，直接进入精简 change 创建。

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

@@ -14,14 +14,15 @@ description: "Use when Comet change 已完成 build 阶段，需要验证实现
 
 ### 0a. 输出语言约束
 
-验证报告和分支处理说明必须使用 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取到的 Comet 配置产物语言。
+验证报告和分支处理说明必须使用 `comet state get <name> language` 读取到的 Comet 配置产物语言。
 
 ### 0b. 入口状态验证（Entry Check）
 
-按 `comet/reference/scripts.md` 定位脚本（定位 `comet-env.mjs`），然后执行入口验证；从任意入口恢复时先按 `comet/reference/context-recovery.md` 运行恢复检查：
+按 `comet/reference/scripts.md` 使用稳定 `comet` CLI，然后执行入口验证；从任意入口恢复时先按 `comet/reference/context-recovery.md` 运行恢复检查：
 
 ```bash
-node "$COMET_STATE" check <change-name> verify
+comet state select <change-name>
+comet state check <change-name> verify
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
@@ -33,7 +34,7 @@ node "$COMET_STATE" check <change-name> verify
 执行规模评估：
 
 ```bash
-node "$COMET_STATE" scale <change-name>
+comet state scale <change-name>
 ```
 
 脚本自动统计任务数、增量规格数、变更文件数，判断使用 light 或 full 验证模式，并设置 verify_mode 字段。判定规则（满足任一即 full）：任务数 > 3、delta spec 能力数 > 1、变更文件数 > 8。
@@ -48,15 +49,15 @@ node "$COMET_STATE" scale <change-name>
 
 ```bash
 # 仅在用户确认修复后执行
-node "$COMET_STATE" transition <change-name> verify-fail
+comet state transition <change-name> verify-fail
 ```
 
-注意：verify-fail 回退到 build 时 `branch_status` 不会被重置。如果首次 verify 已完成分支处理，修复后再次进入 verify 时跳过已完成的分支处理步骤，直接使用 `node "$COMET_STATE" set <change-name> branch_status handled` 保留原有分支处理结果。
+注意：verify-fail 回退到 build 时 `branch_status` 不会被重置。如果首次 verify 已完成分支处理，修复后再次进入 verify 时跳过已完成的分支处理步骤，直接使用 `comet state set <change-name> branch_status handled` 保留原有分支处理结果。
 
 注意：如果 build 阶段每个任务都已提交，脚本基于工作区 diff 的文件数可能低估改动规模。此时必须读取 plan 文件头的 `base-ref` 并用提交区间复核：
 
 ```bash
-PLAN=$(node "$COMET_STATE" get <change-name> plan)
+PLAN=$(comet state get <change-name> plan)
 BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
 git diff --stat "$BASE_REF"...HEAD
 ```
@@ -64,14 +65,14 @@ git diff --stat "$BASE_REF"...HEAD
 若提交区间显示改动超过轻量阈值（> 8 个文件、跨模块协调、或 delta spec 超过 1 个 capability），手动设置为完整验证：
 
 ```bash
-node "$COMET_STATE" set <change-name> verify_mode full
+comet state set <change-name> verify_mode full
 ```
 
-**覆盖机制**：如 agent 或用户认为自动评估结果不合适，可随时通过 `node "$COMET_STATE" set <change-name> verify_mode <light|full>` 手动覆盖。
+**覆盖机制**：如 agent 或用户认为自动评估结果不合适，可随时通过 `comet state set <change-name> verify_mode <light|full>` 手动覆盖。
 
 ### 1b. 验证失败决策（阻塞点）
 
-验证不通过时**必须按 `comet/reference/decision-point.md` 的协议暂停并等待用户决定修复或接受偏差**。不得自动运行 `node "$COMET_STATE" transition <change-name> verify-fail`，也不得自动调用 `/comet-build`。
+验证不通过时**必须按 `comet/reference/decision-point.md` 的协议暂停并等待用户决定修复或接受偏差**。不得自动运行 `comet state transition <change-name> verify-fail`，也不得自动调用 `/comet-build`。
 
 暂停时必须列出：
 - 失败项
@@ -81,7 +82,7 @@ node "$COMET_STATE" set <change-name> verify_mode full
 **不确定性原则**：无法确定严重程度时，降级处理（SUGGESTION > WARNING > CRITICAL）。仅对构建失败、测试失败、安全问题使用 CRITICAL；模糊或不确定的问题标为 WARNING 或 SUGGESTION。
 
 用户选择后按以下方式继续：
-- **全部修复**：运行 `node "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build` 修复
+- **全部修复**：运行 `comet state transition <change-name> verify-fail`，然后调用 `/comet-build` 修复
 - **逐项处理**：CRITICAL 或 IMPORTANT 失败项必须修复；WARNING/SUGGESTION 失败项可选择接受偏差，但必须在验证报告中记录接受原因和影响范围。若存在任何 CRITICAL 或 IMPORTANT 失败项，不允许跳过修复直接全部接受
 
 **重试上限**：连续 3 次 verify-fail 循环后，第 4 次失败时代理不得自动选择继续修复；**必须使用当前平台可用的用户输入/确认机制暂停**，仅给出两个选项：「接受所有偏差并记录」或「继续修复」，由用户明确决定。
@@ -91,8 +92,8 @@ node "$COMET_STATE" set <change-name> verify_mode full
 验证需要读取 OpenSpec 产物时，先检查产物是否自 design 阶段以来发生变化：
 
 ```bash
-RECORDED_HASH=$(node "$COMET_STATE" get <change-name> handoff_hash)
-CURRENT_HASH=$(node "$COMET_HANDOFF" <change-name> --hash-only 2>/dev/null || echo "")
+RECORDED_HASH=$(comet state get <change-name> handoff_hash)
+CURRENT_HASH=$(comet handoff <change-name> --hash-only 2>/dev/null || echo "")
 ```
 
 - 若 `RECORDED_HASH` = `CURRENT_HASH` 且均非空且均非 `null`：OpenSpec 产物未变化，**tasks.md 无需重新读取全文**（用 `grep -c '\- \[ \]' tasks.md` 确认完成数即可）。proposal.md、design.md、delta spec 仍需读取用于对照检查。
@@ -115,6 +116,14 @@ CURRENT_HASH=$(node "$COMET_HANDOFF" <change-name> --hash-only 2>/dev/null || ec
 5. 无明显安全问题（无硬编码密钥、无新增 unsafe 操作）
 6. 代码审查策略：当 `review_mode: standard` 或 `thorough` 时，必须使用 Skill 工具加载 Superpowers `requesting-code-review` 技能，请求只检查正确性、安全、边界条件的轻量代码审查；当 `review_mode: off` 时跳过自动代码审查，并在验证报告中记录跳过原因
 
+若项目没有可自动探测的验证命令，用户或 Agent 必须先自行运行真实验证命令，再单独记录验证证据：
+
+```bash
+comet state record-check <change-name> verify --command "<实际运行的验证命令>" --exit-code 0
+```
+
+`--command` 只记录命令文本，Comet **绝不会执行该文本**。verify 与 build 证据彼此独立，不能互相替代；即使兼容流程使用 `COMET_SKIP_BUILD=1`，也不能把该绕过标记视为可审计的验证或构建证据。
+
 简化代码审查的输入应限定为本次改动 diff、tasks.md 和必要的测试结果；审查范围只覆盖实现正确性、安全风险和边界条件，不执行 spec 覆盖率、Design Doc 一致性或漂移检查。若审查发现 CRITICAL 或 IMPORTANT 问题，按验证失败处理并进入 Step 1b。`review_mode: off` 只跳过自动 code review，不跳过构建、测试、安全检查或异常调试协议。
 
 **与 build 阶段审查的去重**：若 build 阶段（`executing-plans` 或 `subagent-driven-development`）已按 `review_mode` 对同一 diff 完成最终代码审查，verify 的这次轻量审查聚焦「实现是否符合 spec/tasks 的正确性」与「build 之后新增的改动」，不重复评审 build 已审过且未变化的 diff。
@@ -125,7 +134,7 @@ CURRENT_HASH=$(node "$COMET_HANDOFF" <change-name> --hash-only 2>/dev/null || ec
 
 ```bash
 # 仅在用户确认修复后执行
-node "$COMET_STATE" transition <change-name> verify-fail
+comet state transition <change-name> verify-fail
 ```
 
 **报告格式**：简表列出 6 项检查结果 + PASS/FAIL。
@@ -155,13 +164,13 @@ node "$COMET_STATE" transition <change-name> verify-fail
 
 ```bash
 # 仅在用户确认修复后执行
-node "$COMET_STATE" transition <change-name> verify-fail
+comet state transition <change-name> verify-fail
 ```
 
 **Spec 漂移处理**（用户决策点）：
 - 若检查项 6 发现矛盾（delta spec 有内容但 design doc 未体现），**必须使用当前平台可用的用户输入/确认机制以单选题形式暂停并等待用户选择处理方式**，不得自动选择。选项：
   - 选项 A：在 design doc 追加 "Implementation Divergence" 节记录偏差原因。选项 A 属于 verify 阶段允许产物；写入后不得因该 design doc 变更再次触发 Step 1b dirty-worktree 决策
-  - 选项 B：用户选择 B 后，运行 `node "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build`；由 `/comet-build` 的 Spec 增量更新规则加载 Superpowers `brainstorming` 更新 Design Doc + delta spec
+  - 选项 B：用户选择 B 后，运行 `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）
@@ -191,8 +200,8 @@ mkdir -p docs/superpowers/reports
 # 将本次验证结论写入报告文件，例如：
 # docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
 
-node "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
-node "$COMET_STATE" set <change-name> branch_status handled
+comet state set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+comet state set <change-name> branch_status handled
 ```
 
 ## 退出条件
@@ -201,12 +210,12 @@ node "$COMET_STATE" set <change-name> branch_status handled
 - 分支已处理
 - `.comet.yaml` 中 `verification_report` 指向已存在的验证报告文件
 - `.comet.yaml` 中 `branch_status: handled`
-- **阶段守卫**：运行 `node "$COMET_GUARD" <change-name> verify --apply`，全部 PASS 后由守卫通过 `comet-state transition verify-pass` 推进到 `phase: archive`（此步骤更新 `phase` 字段，与 `auto_transition` 无关）
+- **阶段守卫**：运行 `comet guard <change-name> verify --apply`，全部 PASS 后由守卫通过 `comet state transition verify-pass` 推进到 `phase: archive`（此步骤更新 `phase` 字段，与 `auto_transition` 无关）
 
 验证和分支处理均完成后，运行阶段守卫推进 phase（此步骤与 `auto_transition` 无关）：
 
 ```bash
-node "$COMET_GUARD" <change-name> verify --apply
+comet guard <change-name> verify --apply
 ```
 
 状态文件自动更新为 `phase: archive`、`verify_result: pass`、`verified_at: YYYY-MM-DD`。
@@ -220,7 +229,7 @@ node "$COMET_GUARD" <change-name> verify --apply
 按 `comet/reference/auto-transition.md` 执行。关键命令：
 
 ```bash
-node "$COMET_STATE" next <change-name>
+comet state next <change-name>
 ```
 
 - `NEXT: auto` → 调用 `SKILL` 指向的 skill 进入下一阶段

package/dist/app/cli/comet-banner.d.ts

@@ -0,0 +1,25 @@
+import type { Writable } from 'node:stream';
+export declare const COMET_TAGLINE = "Agent Skill Harness For Turning Ideas Into Evaluated Workflows";
+export declare const COMET_LOGO: readonly ["   ██████╗ ██████╗ ███╗   ███╗███████╗████████╗", "  ██╔════╝██╔═══██╗████╗ ████║██╔════╝╚══██╔══╝", "  ██║     ██║   ██║██╔████╔██║█████╗     ██║   ", "  ██║     ██║   ██║██║╚██╔╝██║██╔══╝     ██║   ", "  ╚██████╗╚██████╔╝██║ ╚═╝ ██║███████╗   ██║   ", "   ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚══════╝   ╚═╝   "];
+type AnimationPhase = 'preheat' | 'sweep' | 'settle';
+export declare const COMET_BANNER_LINE_COUNT: number;
+export declare function renderCometAnimationFrame(phase: AnimationPhase, progress: number): string;
+export declare function renderCometBanner(options?: {
+    color?: boolean;
+}): string;
+export declare function renderCometBannerFrame(litColumns: number, particleFrame?: number): string;
+export type BannerRuntime = {
+    isTTY: boolean;
+    env: NodeJS.ProcessEnv;
+    getColumns: () => number | undefined;
+    write: (chunk: string) => void | Promise<void>;
+    sleep: (milliseconds: number) => Promise<void>;
+};
+export declare function createBannerStreamWriter(stream: Writable): BannerRuntime['write'];
+export declare function canAnimateCometBanner(runtime: Pick<BannerRuntime, 'isTTY' | 'env' | 'getColumns'>): boolean;
+export declare function printCometBanner(options?: {
+    enabled?: boolean;
+    runtime?: Partial<BannerRuntime>;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=comet-banner.d.ts.map