@rpamis/comet 0.4.0-beta.1 → 0.4.0-beta.11

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

@@ -1,12 +1,30 @@
-# Script Location and Commands
+# Stable CLI and Internal Script Compatibility
 
 Canonical path: `comet/reference/scripts.md`
 
-This file is the single source of truth for locating Comet scripts and the state/guard/handoff/archive command surface. Load it once per session, then reuse the cached env vars.
+This file is the single source of truth for Comet's public CLI and internal script compatibility. Public workflows must prefer the stable command surface: `comet state`, `comet guard`, `comet handoff`, and `comet archive`.
 
-## Bootstrap (run once per session)
+## Public Workflow Contract
 
-Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars. Sub-skills may reference this section directly and only inline this block when they must be fully self-contained; this file is the single source of truth for updates:
+Normal installations and everyday workflows use the `comet` CLI directly. They do not need to locate launchers and must not expose the internal `classic` name to users:
+
+```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>
+```
+
+When multiple active changes coexist, run `comet state select <change-name>` after resolving the intended change. Ordinary source writes are governed only by that selection; without one, the hook blocks and asks for a choice. A single active change retains automatic routing. Select again after switching branch/worktree or when the recorded selection becomes stale.
+
+Guard `--apply` advances state after checks pass. Use `comet state transition` when expressing a state event directly, and `comet state next` after phase advancement to determine whether to invoke the next Skill automatically.
+
+## Compatibility, Recovery, and Internal Command Bootstrap
+
+The script discovery below is only for legacy compatibility, recovery when the CLI is unavailable, and internal `/comet-classic` entry commands. Normal public workflows must not prefer it. Comet scripts are distributed in `comet/scripts/`; recovery code must locate them once and cache environment variables instead of hardcoding paths:
 
 ```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"
 
 # Stop workflow when script location fails
 if [ -z "$COMET_SCRIPTS_DIR" ]; then
@@ -28,34 +47,47 @@ if [ -z "$COMET_SCRIPTS_DIR" ]; then
 fi
 ```
 
-After loading comet, agents should run this bootstrap block once, then reuse `$COMET_GUARD`, `$COMET_STATE`, `$COMET_HANDOFF`, `$COMET_ARCHIVE`, and `$COMET_INTENT` throughout the session.
+Agents run this bootstrap only when entering one of the compatibility, recovery, or internal-command paths above. `COMET_INTENT` and `COMET_RESUME_PROBE` remain necessary for internal entry routing and must not be removed globally.
+
+| Variable | Purpose |
+|----------|---------|
+| `COMET_STATE` | `.comet.yaml` state reads/writes, phase checks, and recovery context |
+| `COMET_GUARD` | Phase exit guard and `--apply` state advancement |
+| `COMET_HANDOFF` | Design/Build handoff context pack generation |
+| `COMET_ARCHIVE` | One-command archive and main spec sync |
+| `COMET_INTENT` | `/comet-classic` entry intent recognition and route scoring |
+| `COMET_RESUME_PROBE` | Read-only Ambient Resume probe that decides whether to resume an active Comet workflow |
 
 ## Auto state update
 
 Guard supports `--apply` flag, automatically updating `.comet.yaml` state fields after checks pass:
 
 ```bash
-node "$COMET_GUARD" <change-name> <phase> --apply
+comet guard <change-name> <phase> --apply
 ```
 
-`--apply` delegates to `comet-state transition`. Use these semantic events when state changes need to be expressed directly:
+`--apply` delegates to the state-machine transition. Use these semantic events when state changes need to be expressed directly:
 
 ```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
 ```
 
-Archive completion is handled by `node "$COMET_ARCHIVE" <change-name>` after OpenSpec moves the change into its date-prefixed archive directory; do not manually transition an `<archive-name>`.
+Archive completion is handled by `comet archive <change-name>` after OpenSpec moves the change into its date-prefixed archive directory. Use `archive-confirm` or `archive-reopen` for the pre-archive decision, and do not manually run the `archived` transition outside that flow.
 
 ## Resolve next action
 
 After guard-based phase advancement, use the `next` subcommand to determine whether to auto-invoke the next skill:
 
 ```bash
-node "$COMET_STATE" next <change-name>
+comet state next <change-name>
 ```
 
 Output format: `NEXT: auto|manual|done` + `SKILL: <skill-name>` (omitted for `done`) + `HINT` (for `manual` only). With `auto_transition: false`, output is `manual`, which pauses only the next skill invocation and does not block phase updates.
@@ -65,5 +97,5 @@ Output format: `NEXT: auto|manual|done` + `SKILL: <skill-name>` (omitted for `do
 Complete all archive steps in one command:
 
 ```bash
-node "$COMET_ARCHIVE" <change-name>
+comet archive <change-name>
 ```

package/assets/skills/comet/reference/subagent-dispatch.md

@@ -11,9 +11,10 @@ This document provides Comet-specific extensions applied **on top of** the Super
 > Only stop and wait for user input when:
 > - A task is **BLOCKED** (review-fix rounds exhausted: `review_mode: standard` — 1 round of risk-task review-fix or final lightweight review not passed; `review_mode: thorough` — 2 rounds of task-level/final review-fix not passed)
 > - There is irreducible ambiguity that cannot be resolved from the repository, plan, or existing context
-> - The platform lacks real background agent dispatch capability and the user must choose `executing-plans`
 > - The user **explicitly** asks to pause
 >
+> Background dispatch capability disappearing during execution is a runtime stop condition, not automatically a new user decision point. Exit the dispatch loop and return to the same `/comet-build` Step 2 joint decision with `subagent-driven-development` removed. If only one execution method remains, explain why and apply it directly; wait for the user only when multiple valid methods remain.
+>
 > This rule applies to the ENTIRE dispatch loop, not just individual tasks.
 
 ## Before Starting
@@ -34,14 +35,14 @@ The main session is the **coordinator only** and must NOT execute tasks directly
 - **Claude Code**: Use the `Agent` tool with `run_in_background: true` for each implementer, task reviewer, fix agent, and final reviewer. Never execute tasks inline and do not accidentally enter team mode, which requires a pre-created team.
 - **Other platforms**: Use the platform's equivalent background agent / Task / multi-agent dispatch mechanism.
 - **Never** reuse implementers, reviewers, or fix agents across tasks or roles. Each agent gets a fresh, isolated context containing only the single task and role-specific context it needs.
-- If the platform has no real background dispatch capability, do not proceed; pause and wait for the user to choose `build_mode: executing-plans`.
+- If real background dispatch capability disappears during execution, stop dispatching and do not let the main session implement the task. Return to the same `/comet-build` Step 2 joint decision with the unavailable mode removed. Do not create a separate "switch to executing-plans" pause; apply the only valid mode directly when just one remains.
 
 ### 1. Dispatch Prompt and Return Contract
 
 Every implementer or fix-agent prompt must include:
 
 - The full text of the single current task, architecture background, and dependency context
-- `Language: Use the configured Comet artifact language from "$COMET_BASH" "$COMET_STATE" get <name> language`
+- `Language: Use the configured Comet artifact language from comet state get <name> language`
 - The allowed file scope and prohibited modification scope
 - The required test commands and commit requirements
 - For a fix agent, the corresponding reviewer's complete feedback
@@ -92,7 +93,7 @@ The implementer or fix-agent return must provide **RED failure command and failu
 
 ### 4. Durable Progress Checkpoint
 
-The coordinator must maintain `openspec/changes/<name>/.comet/subagent-progress.md` and update it immediately after every dispatch, agent return, review result, review-fix round change, and task checkoff. The checkpoint must record at least:
+The coordinator must maintain `<classic-change-dir>/.comet/subagent-progress.md` and update it immediately after every dispatch, agent return, review result, review-fix round change, and task checkoff. The checkpoint must record at least:
 
 - The unique current plan task text and mapped OpenSpec task text
 - Current stage: `implementing | task-review | checkoff | done | blocked | final-review | final-fix`
@@ -142,8 +143,8 @@ When a reviewer returns an item that cannot be verified from review material alo
 4. Runs targeted verification:
 
 ```bash
-node "$COMET_STATE" task-checkoff "$PLAN_FILE" "$PLAN_TASK_TEXT"
-node "$COMET_STATE" task-checkoff "openspec/changes/<name>/tasks.md" "$OPENSPEC_TASK_TEXT"
+comet state task-checkoff <plan-file> <plan-task-text>
+comet state task-checkoff <classic-change-dir>/tasks.md <openspec-task-text>
 ```
 
 Run the second command only when the corresponding mapping exists. The script requires the task text to appear exactly once and be checked; verification failure blocks moving to the next task.
@@ -158,7 +159,7 @@ Run the second command only when the corresponding mapping exists. The script re
 
 ## Context Recovery
 
-Reload the Superpowers `subagent-driven-development` skill and re-read this document. Read `openspec/changes/<name>/.comet/subagent-progress.md`, then compare it with the first unchecked task and the current worktree:
+Reload the Superpowers `subagent-driven-development` skill and re-read this document. Read `<classic-change-dir>/.comet/subagent-progress.md`, then compare it with the first unchecked task and the current worktree:
 
 - When the checkpoint matches the unchecked task, resume from its exact recorded stage while preserving the implementation commit, RED/GREEN evidence, `review_mode`, review stages already passed, unresolved feedback, and current review-fix round. Never reset the round or repeat an already passed stage.
 - If the loaded Superpowers `subagent-driven-development` skill reports a task complete through its own progress record, reconcile that report against git history and Comet plan/OpenSpec checkboxes before dispatching. When the commits and task identity match, update Comet's checkpoint/checkoff state instead of re-dispatching completed work.

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

@@ -8,7 +8,15 @@
 
 ### Phase Awareness (Highest Priority)
 
-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 there is an active comet change (`<classic-change-dir>/.comet.yaml` bound by the Classic layout resolver 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:**
 
@@ -17,10 +25,10 @@ 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.
+The hook hard interception allowlist includes the OpenSpec and Superpowers roots returned by the Classic layout resolver, plus workflow and platform workspaces such as `.superpowers/*`, `.claude/*`, and `.comet/*`; write access to these paths does not allow skipping the current phase's artifacts or confirmation requirements.
 
 ### Phase-Entry Self-Consistency Check (Before Writing Source Code)
 
@@ -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.
@@ -104,7 +113,7 @@ After recovery, first re-run the "Phase-Entry Self-Consistency Check" table: if
 **Special attention to `build_mode`**: If recovery script outputs `build_mode: subagent-driven-development`, you are the coordinator, not the executor. Must:
 1. Use the Skill tool to reload the Superpowers `subagent-driven-development` skill
 2. Re-read `comet/reference/subagent-dispatch.md` for Comet-specific extensions
-3. Read `openspec/changes/<name>/.comet/subagent-progress.md` to recover the exact stage, evidence, and review-fix round
+3. Read `<classic-change-dir>/.comet/subagent-progress.md` to recover the exact stage, evidence, and review-fix round
 4. Do not execute tasks directly in the main session
 5. Resume from the checkpoint; start from the first unchecked task only when it is missing or mismatched
 6. Tasks already committed but not yet validated according to `review_mode` remain unchecked; continue the corresponding validation/review/fix loop
@@ -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

@@ -8,7 +8,15 @@
 
 ### 阶段感知（最高优先级）
 
-有活跃 comet change 时（`openspec/changes/<name>/.comet.yaml` 存在），**每次开始执行操作前**必须读取 `phase` 字段确认当前阶段。
+有活跃 comet change 时（Classic layout resolver 绑定的 `<classic-change-dir>/.comet.yaml` 存在），**每次开始执行操作前**必须读取 `phase` 字段确认当前阶段。
+
+当存在多个 active change 时，必须先明确当前 change，再运行：
+
+```bash
+comet state select <change-name>
+```
+
+普通源码写入只受已选择 change 的阶段约束。多个 active change 且没有有效选择时，Hook 必须阻塞并提示选择；不得按字母序猜测，也不得让无关 change 的 `open`、`design` 或 `archive` 阶段全局封锁合法 build。单 active change 无选择时可保持自动归属。
 
 **阶段与允许操作：**
 
@@ -17,10 +25,10 @@
 | `open` | 创建 proposal/design/tasks, 运行 guard | 写源代码 |
 | `design` | brainstorming, 创建 Design Doc, 运行 guard | 写源代码 |
 | `build` | 写源代码、测试、执行计划 | 跳过用户确认点 |
-| `verify` | 验证、branch handling | 跳过失败处理 |
-| `archive` | 确认归档、运行归档脚本 | 写源代码 |
+| `verify` | 验证、记录验证报告 | 跳过失败处理、提前处理分支 |
+| `archive` | 确认归档、运行归档脚本、提交归档改动、分支处理 | 写源代码 |
 
-Hook 硬拦截白名单包括 `openspec/*`、`docs/superpowers/*`、`.superpowers/*`、`.claude/*` 和 `.comet/*` 等流程/平台工作区；这些路径可写不代表可以跳过当前阶段的产物和确认要求。
+Hook 硬拦截白名单包括 Classic layout resolver 返回的 OpenSpec 与 Superpowers roots，以及 `.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** 决定下一步。
@@ -105,7 +113,7 @@ node "$COMET_STATE" check <name> <phase> --recover
 **特别注意 `build_mode`**：若恢复脚本输出 `build_mode: subagent-driven-development`，你是协调者，不是执行者。必须：
 1. 使用 Skill 工具重新加载 Superpowers `subagent-driven-development` 技能 (Use the Skill tool to reload the Superpowers `subagent-driven-development` skill)
 2. 读取 `comet/reference/subagent-dispatch.md` 获取 Comet 专属扩展 (re-read `comet/reference/subagent-dispatch.md` for Comet-specific extensions)
-3. 读取 `openspec/changes/<name>/.comet/subagent-progress.md` 恢复精确阶段、证据和审查-修复轮次 (Read `openspec/changes/<name>/.comet/subagent-progress.md` to recover the exact stage, evidence, and review-fix round)
+3. 读取 `<classic-change-dir>/.comet/subagent-progress.md` 恢复精确阶段、证据和审查-修复轮次 (Read `<classic-change-dir>/.comet/subagent-progress.md` to recover the exact stage, evidence, and review-fix round)
 4. 禁止在主会话中直接执行 task (Do not execute the pending task directly in the main window)
 5. 按检查点恢复；缺失或不匹配时才从第一个未勾选 task 开始
 6. 已提交但未按 `review_mode` 完成验收的 task 保持未勾选，继续对应的验证/审查/修复循环
@@ -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/rules/comet-workflow-guard.en.md

@@ -0,0 +1,32 @@
+# Comet Current-Change Phase Rule
+
+This Rule is the persistent soft safeguard shared by Native and Classic. A project may enable both workflows, but one request must be owned by exactly one workflow/change; never apply both phase models at the same time.
+
+## Resolve the current request first
+
+At the start of every turn, when resuming work, or after possible context compression:
+
+1. Read `.comet/config.yaml`: `workflows` lists enabled capabilities, while `default_workflow` only selects the default `/comet` entry.
+2. Read `.comet/current-change.json`: its `workflow + change` identifies the current request owner.
+3. Without a selection, infer read-only ownership only when exactly one active Comet change exists across the project. Multiple candidates require an explicit user selection.
+4. Stop on an invalid, stale, cross-branch, missing, or archived selection. Never fall back to `default_workflow` to guess ownership.
+
+A legacy Classic project without the current project schema uses only the Classic legacy fallback; that fallback never enables Native.
+
+## Apply only the selected phase model
+
+| Workflow | Ordinary implementation writes blocked | Ordinary implementation writes allowed |
+| --- | --- | --- |
+| Native | Shape, Verify, Archive | Build |
+| Classic | Open, Design, Archive | Build, Verify |
+
+- Native Verify only runs checks and records evidence. When it exposes an implementation problem, record the failed result and use the Native Runtime to return to Build before modifying the implementation. Ordinary dot-prefixed project files do not become cross-phase allowlisted paths merely because of their names.
+- For Native ownership, resume `/comet-native` and continue from Native state, evidence, and automatic-progression rules.
+- For Classic ownership, resume `/comet-classic` and continue from Classic state, decision points, and phase rules.
+- Never convert a Native change into a Classic change or vice versa. Switching workflows means selecting a separate change.
+
+## Hook constraint
+
+Each platform must install exactly one Comet Hook Router. One write event may invoke at most one workflow Guard; do not run separate Native and Classic Hooks.
+
+The Hook evaluates multi-file and patch targets atomically. It fails closed when the current phase blocks ordinary project writes, ownership is ambiguous, state is stale, or a write target cannot be determined safely. Never bypass the Hook; follow its denial message to resume the owning workflow and select the current change again.

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

@@ -0,0 +1,32 @@
+# Comet 当前需求阶段规则
+
+本规则是 Native 与 Classic 共用的常驻软性防线。项目可以启用两种 workflow，但一个需求只能由一个 workflow/change 管理；不得同时套用两套阶段规则。
+
+## 先确定当前需求
+
+每轮开始、恢复工作或怀疑上下文被压缩后，按以下顺序检查：
+
+1. 读取 `.comet/config.yaml`：`workflows` 表示项目启用的能力，`default_workflow` 只决定 `/comet` 的默认入口。
+2. 读取 `.comet/current-change.json`：其中的 `workflow + change` 才是当前需求所有者。
+3. selection 缺失时，只有全项目恰好一个 Comet 活跃 change 才能只读推断；存在多个候选时必须暂停并让用户选择。
+4. selection 无效、过期、跨分支失效或指向已归档 change 时停止，不得回退到 `default_workflow` 猜测。
+
+Classic 旧项目没有新版配置时只按 Classic legacy fallback 处理，不得因此启用 Native。
+
+## 只应用选中的阶段规则
+
+| Workflow | 禁止普通实现写入 | 允许普通实现写入 |
+| --- | --- | --- |
+| Native | Shape、Verify、Archive | Build |
+| Classic | Open、Design、Archive | Build、Verify |
+
+- Native 的 Verify 只运行检查并记录证据；发现实现问题时，先记录失败并通过 Native Runtime 回到 Build，再修改实现。点号开头的普通项目文件不因名称而自动成为跨阶段白名单。
+- 当前 workflow 是 Native：恢复 `/comet-native`，由 Native 状态、证据和自动推进协议继续。
+- 当前 workflow 是 Classic：恢复 `/comet-classic`，由 Classic 状态、确认点和阶段协议继续。
+- 不要把 Native change 转换成 Classic change，或反向转换；切换 workflow 必须选择另一个独立 change。
+
+## Hook 约束
+
+平台只应安装一个 Comet Hook Router。一次写入事件最多进入一个 workflow Guard；不得分别运行 Native 和 Classic Hook。
+
+Hook 会对多文件和 patch 目标整体裁决。当前阶段不允许普通项目写入、selection 不明确、状态失效或目标无法安全判断时会失败关闭。不要绕过 Hook；按拒绝信息恢复对应 workflow 并重新选择当前 change。