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

package/assets/skills/comet/rules/comet-phase-guard.en.md

@@ -10,6 +10,14 @@
 
 When there is an active comet change (`openspec/changes/<name>/.comet.yaml` exists), **before starting any operation** you must read the `phase` field to confirm the current phase.
 
+When multiple active changes exist, resolve the current change first, then run:
+
+```bash
+comet state select <change-name>
+```
+
+Ordinary source writes are governed only by the selected change phase. With multiple active changes and no valid selection, the Hook must block and ask for a choice; it must not guess alphabetically or let an unrelated open, design, or archive change globally block a legal build. A single active change may retain automatic routing.
+
 **Phases and allowed operations:**
 
 | Phase | Allowed | Prohibited |
@@ -17,8 +25,8 @@ When there is an active comet change (`openspec/changes/<name>/.comet.yaml` exis
 | `open` | Create proposal/design/tasks, run guard | Write source code |
 | `design` | brainstorming, create Design Doc, run guard | Write source code |
 | `build` | Write source code, tests, execute plans | Skip user confirmation points |
-| `verify` | Verification, branch handling | Skip failure handling |
-| `archive` | Confirm archive, run archive script | Write source code |
+| `verify` | Verification, record verification report | Skip failure handling, handle the branch early |
+| `archive` | Confirm archive, run archive script, commit archive changes, handle the branch | Write source code |
 
 The hook hard interception allowlist includes workflow and platform workspaces such as `openspec/*`, `docs/superpowers/*`, `.superpowers/*`, `.claude/*`, and `.comet/*`; write access to these paths does not allow skipping the current phase's artifacts or confirmation requirements.
 
@@ -36,7 +44,8 @@ Reading the `phase` field alone is not enough — you must also confirm **how**
 
 Exception: `workflow: hotfix/tweak` intentionally skips design, so an empty `design_doc` is normal and not an illegal jump.
 
-Upgrade state note: after a preset (hotfix/tweak) hits an upgrade signal and the user confirms upgrading, `comet-state transition <name> preset-escalate` legally converts it to `workflow: full` + `phase: design` + `design_doc: null`. At this point `phase: design` with an empty `design_doc` **is a normal upgrade pre-state**, not an illegal jump — the agent should enter `/comet-design` to supplement the Design Doc. This terminal state does not match the "skipped design" row above (that row only detects `phase: build`).
+Upgrade state note: after a preset (hotfix/tweak) hits an upgrade signal and the user confirms upgrading, `comet state transition <name> preset-escalate` legally converts it to `workflow: full` + `phase: design` + `design_doc: null` and clears preset-only build settings. At this point `phase: design` with an empty `design_doc` **is a normal upgrade pre-state**, not an illegal jump — the agent should enter `/comet-design` to supplement the Design Doc, then choose the full workflow configuration again in build. This terminal state does not match the "skipped design" row above (that row only detects `phase: build`).
+
 ### Skill Invocation (Cannot Replace with Normal Conversation)
 
 The following operations must be loaded through the Skill tool. When Skill is unavailable, stop the workflow and prompt to install:
@@ -51,50 +60,50 @@ The following operations must be loaded through the Skill tool. When Skill is un
 
 ### Script Execution (Cannot Skip)
 
-- **Phase exit**: `comet-guard <name> <phase> --apply` (must see ALL CHECKS PASSED)
-- **Compression recovery**: `comet-state check <name> <phase> --recover`
-- **State update**: After key operations, update fields through `comet-state set`; manually editing .comet.yaml is prohibited
-- **Phase advancement only via guard/transition**: directly running `comet-state set <name> phase <value>` to jump phases is prohibited (it bypasses evidence checks and the script now hard-blocks it); use the `COMET_FORCE_PHASE=1` escape hatch only to repair a malformed state. A preset (hotfix/tweak) upgrade to full must use `comet-state transition <name> preset-escalate` — this is the only channel that can legally rewind phase to design and sync workflow/classic_profile; direct `set phase design` and `set classic_profile` are both hard-blocked
-- **handoff generation**: `comet-handoff <name> design --write` (handwriting summaries is prohibited)
+- **Phase exit**: `comet guard <name> <phase> --apply` (must see ALL CHECKS PASSED)
+- **Compression recovery**: `comet state check <name> <phase> --recover`
+- **State update**: After key operations, update fields through `comet state set`; manually editing .comet.yaml is prohibited
+- **Phase advancement only via guard/transition**: directly running `comet state set <name> phase <value>` to jump phases is prohibited. A preset (hotfix/tweak) upgrade to full must use `comet state transition <name> preset-escalate`
+- **handoff generation**: `comet handoff <name> design --write` (handwriting summaries is prohibited)
 
 ### User Confirmation (Cannot Auto-Skip)
 
 The following decision points must pause to wait for explicit user selection; do not auto-fill based on recommendation rules:
 
-- **open**: Requirements clarification completion confirmation, artifact review confirmation
+- **open**: Final artifact review, which also confirms the change name and scope. Add an earlier decision only for unresolved target/scope alternatives or a large-PRD split
 - **design**: brainstorming proposal confirmation (Design Doc cannot be created before confirmation)
-- **build**: plan-ready pause, four choices: `isolation` / `build_mode` / `tdd_mode` / `review_mode` (workspace isolation, execution method, TDD mode, code review mode), spec large-scale change confirmation, preset (hotfix/tweak) upgrade-assessment two-choice (when a qualitative-change signal or file-count tripwire is hit, let the user decide whether to continue the preset or upgrade to full)
-- **verify**: Verification failure handling strategy, branch handling selection
-- **archive**: Final confirmation before archiving
+- **build**: After capability preflight, use one joint decision for a plan-ready pause or every executable `isolation` / `build_mode` / `tdd_mode` / `review_mode`; include the branch name when branch is selected, plus large spec-change and preset-upgrade decisions
+- **verify**: Accepting WARNING/SUGGESTION deviations, handling Spec drift, or choosing continue/stop after the automatic repair limit
+- **archive**: Final confirmation before archiving, plus branch-handling selection after the archive commit
 
 ## Design Phase Specifics
 
-1. First script operation = `comet-handoff <name> design --write` (loading brainstorming before generating handoff is prohibited)
+1. First script operation = `comet handoff <name> design --write` (loading brainstorming before generating handoff is prohibited)
 2. brainstorming in progress: incrementally update brainstorm-summary.md (update recovery checkpoint after each clarification round or proposal iteration; unconfirmed content marked as pending/candidate)
 3. After brainstorming completes, next step = brainstorm-summary.md finalization → Design Doc → guard
-4. active compaction gate: after brainstorm-summary.md is finalized and before creating Design Doc, prioritize triggering host platform's native context compression; when programmatic triggering is unavailable, pause to prompt user to manually compress or confirm continuing
+4. Active context compaction is optional only after the Design Doc, state evidence, and latest handoff are persisted; when programmatic triggering is unavailable, provide a non-blocking suggestion and continue
 5. **Absolutely cannot start writing implementation code directly** — must first create Design Doc and pass guard
 
 ## Build Phase Specifics
 
-1. After plan creation, must ask user to choose continue or pause (`build_pause` mechanism)
+1. After plan creation, filter unavailable options, then ask one joint question: pause, or submit workspace/execution/TDD/review settings and any conditional branch name together
 2. After each task acceptance, must: tasks.md checkmark → git commit (do not accumulate). `subagent-driven-development` must complete acceptance according to the current `review_mode`, then the coordinator performs targeted verification by unique task text; do not use an incomplete task summary table to replace current task verification
 3. When encountering failures, must load **systematic-debugging** skill; do not propose source code fixes before root cause is located
 4. spec change grading: small changes edit directly | medium changes load brainstorming | large changes pause and wait for user confirmation to split
 
 ## Verify Phase Specifics
 
-1. First step run `comet-state scale <name>` to determine verification level
-2. After verification fails, list failed items and wait for user selection; CRITICAL must be fixed
-3. After 3 consecutive failures, must let user choose to accept deviation or continue fixing
-4. When the user chooses to fix, run `comet-state transition <name> verify-fail`: this transition rewinds `phase` back to `build` (not staying in verify), then enter `/comet-build` to fix; after fixing, re-run the build→verify guard
+1. First step run `comet state scale <name>` to determine verification level
+2. For the first 3 clearly repairable failures, automatically run `comet state transition <name> verify-fail`, return to build, and enter `/comet-build`. CRITICAL/IMPORTANT failures cannot be accepted as deviations
+3. The state machine owns `verify_failures`. After it reaches `3`, the next failure must ask whether to continue fixing or stop the workflow for an external decision
+4. Ask whether to fix or accept WARNING/SUGGESTION only when repair introduces a behavior, scope, or risk tradeoff. Safe, local, tradeoff-free repairs close automatically
 
 ## Context Compression Recovery
 
 If context compression is suspected (previous conversation was summarized, previous discussion cannot be found), immediately run:
 
 ```bash
-node "$COMET_STATE" check <name> <phase> --recover
+comet state check <name> <phase> --recover
 ```
 
 Decide next step according to the script's **Recovery action** output.
@@ -115,17 +124,11 @@ After recovery, first re-run the "Phase-Entry Self-Consistency Check" table: if
 After guard `--apply` succeeds, do not hardcode the next skill in this rule. First run:
 
 ```bash
-comet-state next <change-name>
-```
-
-If `comet-env.mjs` has already located the scripts, the equivalent command is:
-
-```bash
-node "$COMET_STATE" next <change-name>
+comet state next <change-name>
 ```
 
 Decide the next step from the script output:
 
 - `NEXT: auto` → use the Skill tool to load the skill named by `SKILL`
-- `NEXT: manual` → do not load the next skill; show `HINT` so the user can continue manually
+- `NEXT: manual` → do not load the next skill; return control with `HINT`, end the invocation, and do not create another confirmation point
 - `NEXT: done` → the workflow is complete; no further action is needed

package/assets/skills/comet/rules/comet-phase-guard.md

@@ -10,6 +10,14 @@
 
 有活跃 comet change 时（`openspec/changes/<name>/.comet.yaml` 存在），**每次开始执行操作前**必须读取 `phase` 字段确认当前阶段。
 
+当存在多个 active change 时，必须先明确当前 change，再运行：
+
+```bash
+comet state select <change-name>
+```
+
+普通源码写入只受已选择 change 的阶段约束。多个 active change 且没有有效选择时，Hook 必须阻塞并提示选择；不得按字母序猜测，也不得让无关 change 的 `open`、`design` 或 `archive` 阶段全局封锁合法 build。单 active change 无选择时可保持自动归属。
+
 **阶段与允许操作：**
 
 | 阶段 | 允许 | 禁止 |
@@ -17,8 +25,8 @@
 | `open` | 创建 proposal/design/tasks, 运行 guard | 写源代码 |
 | `design` | brainstorming, 创建 Design Doc, 运行 guard | 写源代码 |
 | `build` | 写源代码、测试、执行计划 | 跳过用户确认点 |
-| `verify` | 验证、branch handling | 跳过失败处理 |
-| `archive` | 确认归档、运行归档脚本 | 写源代码 |
+| `verify` | 验证、记录验证报告 | 跳过失败处理、提前处理分支 |
+| `archive` | 确认归档、运行归档脚本、提交归档改动、分支处理 | 写源代码 |
 
 Hook 硬拦截白名单包括 `openspec/*`、`docs/superpowers/*`、`.superpowers/*`、`.claude/*` 和 `.comet/*` 等流程/平台工作区；这些路径可写不代表可以跳过当前阶段的产物和确认要求。
 
@@ -32,11 +40,11 @@ Hook 硬拦截白名单包括 `openspec/*`、`docs/superpowers/*`、`.superpower
 | `phase: build` + proposal/design/tasks 任一缺失或为空 | 绕过 open 空跳 | 回 `/comet-open` 补齐三件套 |
 | `phase: archive` + `verify_result` ≠ `pass` | 绕过 verify 空跳 | 回 `/comet-verify` 完成验证 |
 
-> 说明：上表只覆盖 hook 硬门实际检测的范围（`design_doc` 空跳在 build 阶段；proposal/design/tasks 三件套完整性在 open→build 的 guard 退出时校验）。`verify` 阶段不在此写源码自洽门内——若 verify 发现产物缺失，按下方「Verify 阶段专项」的 verify-fail 回退处理。
+> 说明：上表只覆盖 hook 硬拦截实际检测的范围（`design_doc` 空跳在 build 阶段；proposal/design/tasks 三件套完整性在 open→build 的 guard 退出时校验）。`verify` 阶段不在此写源码自洽检查内——若 verify 发现产物缺失，按下方「Verify 阶段专项」的 verify-fail 回退处理。
 
 预设例外：`workflow: hotfix/tweak` 本就跳过 design，`design_doc` 为空属正常，不算非法。
 
-升级态说明：预设（hotfix/tweak）命中升级信号并经用户确认升级后，通过 `comet-state transition <name> preset-escalate` 合法地变为 `workflow: full` + `phase: design` + `design_doc: null`。此时 `phase: design` + `design_doc` 为空**属正常升级前置态**，不是非法空跳——agent 应进入 `/comet-design` 补 Design Doc。该终态不命中上表「绕过 design 空跳」行（该行仅检测 `phase: build`）。
+升级态说明：预设（hotfix/tweak）命中升级信号并经用户确认升级后，通过 `comet state transition <name> preset-escalate` 合法地变为 `workflow: full` + `phase: design` + `design_doc: null`，同时清除预设专属 build 配置。此时 `phase: design` + `design_doc` 为空**属正常升级前置态**，不是非法空跳——agent 应进入 `/comet-design` 补 Design Doc，并在 build 重新完成联合工作方式选择。该终态不命中上表「绕过 design 空跳」行（该行仅检测 `phase: build`）。
 
 ### Skill 调用（不可用普通对话替代）
 
@@ -52,50 +60,50 @@ Hook 硬拦截白名单包括 `openspec/*`、`docs/superpowers/*`、`.superpower
 
 ### 脚本执行（不可跳过）
 
-- **阶段退出**: `comet-guard <name> <phase> --apply`（必须看到 ALL CHECKS PASSED）
-- **压缩恢复**: `comet-state check <name> <phase> --recover`
-- **状态更新**: 关键操作后通过 `comet-state set` 更新字段，禁止手工编辑 .comet.yaml
-- **阶段推进只能经 guard/transition**: 禁止用 `comet-state set <name> phase <值>` 手动跳阶段（会绕过证据校验，脚本已硬拦截）；确需修复畸形状态时才用 `COMET_FORCE_PHASE=1` 逃生阀。预设（hotfix/tweak）升级到 full 必须用 `comet-state transition <name> preset-escalate`——这是唯一能合法回退 phase 到 design 并同步 workflow/classic_profile 的通道，直接 `set phase design` 和 `set classic_profile` 都会被硬拦截
-- **handoff 生成**: `comet-handoff <name> design --write`（禁止手写摘要）
+- **阶段退出**: `comet guard <name> <phase> --apply`（必须看到 ALL CHECKS PASSED）
+- **压缩恢复**: `comet state check <name> <phase> --recover`
+- **状态更新**: 关键操作后通过 `comet state set` 更新字段，禁止手工编辑 .comet.yaml
+- **阶段推进只能经 guard/transition**: 禁止用 `comet state set <name> phase <值>` 手动跳阶段；预设升级到 full 必须用 `comet state transition <name> preset-escalate`
+- **handoff 生成**: `comet handoff <name> design --write`（禁止手写摘要）
 
 ### 用户确认（不可自动跳过）
 
 以下决策点必须暂停等待用户明确选择，不得根据推荐规则自动填写：
 
-- **open**: 需求澄清完成确认、artifact 评审确认
+- **open**: artifact 最终审视（同时确认 change 名称与范围）；只有目标/范围仍有互斥选择或大型 PRD 拆分时增加前置决策
 - **design**: brainstorming 方案确认（确认前不得创建 Design Doc）
-- **build**: plan-ready 暂停、`isolation` / `build_mode` / `tdd_mode` / `review_mode` 四项选择（工作区隔离、执行方式、TDD 模式、代码审查模式）、spec 大规模变更确认、预设（hotfix/tweak）升级判定二选一（命中质变信号或文件数 tripwire 时，交用户决定继续预设流程还是升级 full）
-- **verify**: 验证失败处理策略、branch handling 选择
-- **archive**: 归档前最终确认
+- **build**: 能力预检后，在一个联合决策中选择 plan-ready 暂停或所有可执行的 `isolation` / `build_mode` / `tdd_mode` / `review_mode`；选择 branch 时同时确认分支名，另含 spec 大规模变更确认、预设升级判定
+- **verify**: 接受 WARNING/SUGGESTION 偏差、Spec 漂移处理，或超过自动修复上限后的继续/停止策略
+- **archive**: 归档前最终确认，以及归档提交后的 branch handling 选择
 
 ## Design 阶段专项
 
-1. 第一个脚本操作 = `comet-handoff <name> design --write`（未生成 handoff 禁止加载 brainstorming）
+1. 第一个脚本操作 = `comet handoff <name> design --write`（未生成 handoff 禁止加载 brainstorming）
 2. brainstorming in progress: incrementally update brainstorm-summary.md（每轮澄清或方案迭代后增量更新恢复检查点，未确认内容标注为待确认/候选）
 3. brainstorming 完成后下一步 = brainstorm-summary.md 定稿 → Design Doc → guard
-4. active compaction gate: brainstorm-summary.md 定稿后、创建 Design Doc 前，优先触发宿主平台原生上下文压缩；无法程序化触发时暂停提示用户手动压缩或确认继续
+4. 主动式上下文压缩只能在 Design Doc、状态和最新 handoff 落盘后按需执行；无法程序化触发时给出非阻塞建议并继续
 5. **绝对不能直接开始写实现代码** — 必须先创建 Design Doc 并通过 guard
 
 ## Build 阶段专项
 
-1. plan 创建后必须询问用户选择继续或暂停（`build_pause` 机制）
+1. plan 创建后先过滤不可执行选项，再只发起一个联合决策：暂停，或一次性提交工作区/执行/TDD/审查配置及条件性的分支名
 2. 每个 task 验收后必须: tasks.md 打勾 → git commit（不得积攒）。`subagent-driven-development` 必须按当前 `review_mode` 完成验收，再由协调者按任务唯一文本定向勾选和验证；不得用未完成任务总表代替当前任务验证
 3. 遇到失败必须加载 **systematic-debugging** skill，根因未定位前不得提出源码修复
 4. spec 变更分级: 小改直接编辑 | 中改加载 brainstorming | 大改暂停等用户确认拆分
 
 ## Verify 阶段专项
 
-1. 第一步运行 `comet-state scale <name>` 确定验证级别
-2. 验证失败后列出失败项等用户选择，CRITICAL 必须修
-3. 连续 3 次失败后必须让用户选择接受偏差或继续修
-4. 用户选择修复时运行 `comet-state transition <name> verify-fail`：该转移会把 `phase` 回退到 `build`（不是停在 verify），随后进入 `/comet-build` 修复，修完重新过 build→verify guard
+1. 第一步运行 `comet state scale <name>` 确定验证级别
+2. 前 3 次明确可修复失败自动运行 `comet state transition <name> verify-fail` 回到 build，并进入 `/comet-build`；CRITICAL/IMPORTANT 不得接受偏差
+3. `verify_failures` 由状态机维护。达到 `3` 后的下一次失败必须让用户选择继续修复或停止 workflow 寻求外部决策
+4. WARNING/SUGGESTION 只有在修复涉及行为、范围或风险取舍时才询问修复/接受；安全、局部、无取舍的修复自动闭环
 
 ## 上下文压缩恢复
 
 如果怀疑发生上下文压缩（之前对话被摘要、找不到之前讨论的内容），立即运行：
 
 ```bash
-node "$COMET_STATE" check <name> <phase> --recover
+comet state check <name> <phase> --recover
 ```
 
 按脚本输出的 **Recovery action** 决定下一步。
@@ -116,17 +124,11 @@ node "$COMET_STATE" check <name> <phase> --recover
 guard `--apply` 成功后，不得在本规则中硬编码下一阶段 skill。必须先运行：
 
 ```bash
-comet-state next <change-name>
-```
-
-若已通过 `comet-env.mjs` 定位脚本，等价运行：
-
-```bash
-node "$COMET_STATE" next <change-name>
+comet state next <change-name>
 ```
 
 按脚本输出决定下一步：
 
 - `NEXT: auto` → 使用 Skill 工具加载 `SKILL` 指向的 skill
-- `NEXT: manual` → 不加载下一 skill，按 `HINT` 提示用户手动继续
+- `NEXT: manual` → 不加载下一 skill，按 `HINT` 交还控制权并结束当前调用；不再创建确认点
 - `NEXT: done` → 流程已完成，无需继续

package/assets/skills/comet/scripts/comet-resume-probe.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './comet-runtime.mjs';
+process.exitCode = await main(["resume-probe", ...process.argv.slice(2)]);