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

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

@@ -15,21 +15,22 @@ description: "Use when a Comet change has passed verification and needs archive
 
 ### 0. Output Language Constraint
 
-Archive summaries and lifecycle closure notes must use the configured Comet artifact language from `"$COMET_BASH" "$COMET_STATE" get <name> language`.
+Archive summaries and lifecycle closure notes must use the configured Comet artifact language from `comet state get <name> language`.
 
 ### 0. Entry State Verification (Entry Check)
 
-Locate scripts via `comet/reference/scripts.md`, then run entry verification. When resuming from any entry point, first run the recovery check in `comet/reference/context-recovery.md`:
+Use the stable `comet` CLI described in `comet/reference/scripts.md`, then run entry verification. When resuming from any entry point, first run the recovery check in `comet/reference/context-recovery.md`:
 
 ```bash
-node "$COMET_STATE" check <name> archive
+comet state select <change-name>
+comet state check <name> archive
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
 
 ### 1. Final Archive Confirmation (Blocking Point)
 
-After entry verification passes, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to confirm whether to archive immediately**. Must not run `node "$COMET_ARCHIVE" "<change-name>"` before user confirmation.
+After entry verification passes, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to confirm whether to archive immediately**. Must not run `comet archive "<change-name>"` before user confirmation.
 
 Before confirmation, show the user a brief summary:
 - Change name
@@ -38,22 +39,28 @@ Before confirmation, show the user a brief summary:
 - Irreversible actions this archive will perform: merge main specs with OpenSpec delta semantics, annotate design doc / plan, and move the change to the archive directory
 
 The user confirmation question must be presented as a single-select question with these options:
-- "Confirm archive" — immediately run the archive script to complete spec merge and change movement
-- "Needs adjustment or re-verification" — do not archive; run `node "$COMET_STATE" transition <change-name> archive-reopen` to return to `phase: verify`, then invoke `/comet-verify`. If verification confirms fixes are needed, follow `/comet-verify`'s verification-failure decision flow back to `/comet-build`
+- "Confirm archive" — record the final confirmation state, then run the archive script to complete spec merge and change movement
+- "Needs adjustment or re-verification" — do not archive; run `comet state transition <change-name> archive-reopen` to return to `phase: verify`, then invoke `/comet-verify`. If verification confirms fixes are needed, follow `/comet-verify`'s verification-failure decision flow back to `/comet-build`
 - "Do not archive yet" — do not archive; keep the current `phase: archive` state and wait for the user to invoke `/comet-archive` again later
 
-Only after the user selects "Confirm archive" may Step 2 continue. After the user selects "Needs adjustment or re-verification", must first run the `archive-reopen` state transition; do not edit `.comet.yaml` manually.
+After the user selects "Confirm archive", immediately run:
+
+```bash
+comet state transition <change-name> archive-confirm
+```
+
+If the transition returns a non-zero exit code, report the error and stop. Only after the transition succeeds may Step 2 continue. After the user selects "Needs adjustment or re-verification", must first run the `archive-reopen` state transition; do not edit `.comet.yaml` manually.
 
 ### 2. Execute Archive
 
-Run the archive script to automatically complete all steps:
+Run the archive script:
 
 ```bash
-node "$COMET_ARCHIVE" "<change-name>"
+comet archive "<change-name>"
 ```
 
 The script automatically executes:
-1. Entry state validation (phase=archive, verify_result=pass, archived=false)
+1. Entry state validation (phase=archive, verify_result=pass, archive_confirmation=confirmed, archived=false)
 2. Design doc frontmatter annotation (archived-with, status)
 3. Plan frontmatter annotation (archived-with)
 4. OpenSpec archive for delta-merge semantics and moving the change to the archive directory
@@ -62,6 +69,12 @@ The script automatically executes:
 
 If script returns non-zero exit code, report error and stop.
 If script returns zero exit code, archive is complete.
+
+After a successful archive, clear the current execution context; this command is idempotent:
+
+```bash
+comet state clear-selection
+```
 The summary `X/Y steps succeeded` counts real executed steps and does not double-count delta spec sync or document annotation.
 
 The script calls OpenSpec archive to merge `ADDED/MODIFIED/REMOVED/RENAMED` delta semantics into main specs, then verifies main specs do not contain delta-only section headings.
@@ -99,7 +112,7 @@ If branch handling (phase 4) chose not to merge into the main branch yet, finish
 
 The archive script moves `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`.
 
-> **WARNING**: After successful archive, **do not run** `node "$COMET_GUARD" <change-name> archive` against the old active change name; the active directory no longer exists. Doing so will cause the guard to error with "change directory not found". Archive completeness is determined by script exit code and archived directory state.
+> **WARNING**: After successful archive, **do not run** `comet guard <change-name> archive` against the old active change name; the active directory no longer exists. Doing so will cause the guard to error with "change directory not found". Archive completeness is determined by script exit code and archived directory state.
 
 ## Complete
 

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

@@ -14,10 +14,11 @@ description: "Use when a full Comet change has completed design and needs an imp
 
 ### 0. Entry State Verification (Entry Check)
 
-Locate scripts via `comet/reference/scripts.md`, then run entry verification. When resuming from any entry point, first run the recovery check in `comet/reference/context-recovery.md`:
+Use the stable `comet` CLI described in `comet/reference/scripts.md`, then run entry verification. When resuming from any entry point, first run the recovery check in `comet/reference/context-recovery.md`:
 
 ```bash
-node "$COMET_STATE" check <name> build
+comet state select <change-name>
+comet state check <name> build
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -26,13 +27,13 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 
 ### 1. Create Plan (Subagent Offload)
 
-Create the implementation plan through a subagent, avoiding planning skill occupying main session context. Plan files and execution feedback must use the configured Comet artifact language from `"$COMET_BASH" "$COMET_STATE" get <name> language`.
+Create the implementation plan through a subagent, avoiding planning skill occupying main session context. Plan files and execution feedback must use the configured Comet artifact language from `comet state get <name> language`.
 
 **Subagent instructions**:
 
 You are an implementation planning expert. Create an implementation plan based on the following inputs:
 
-1. **Immediately execute:** Use the Skill tool to load the Superpowers `writing-plans` skill. Skipping this step is prohibited. After the skill loads, ARGUMENTS must include: `Language: Use the configured Comet artifact language from "$COMET_BASH" "$COMET_STATE" get <name> language`
+1. **Immediately execute:** Use the Skill tool to load the Superpowers `writing-plans` skill. Skipping this step is prohibited. After the skill loads, ARGUMENTS must include: `Language: Use the configured Comet artifact language from comet state get <name> language`
 2. Read the Design Doc (technical design document under `docs/superpowers/specs/`)
 3. Read `openspec/changes/<name>/tasks.md` (task boundaries)
 4. Follow the skill's guidance to create the plan
@@ -69,7 +70,7 @@ After the subagent completes:
 Record plan path:
 
 ```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
 ```
 
 No manual phase update needed — guard auto-transitions when exit conditions are met.
@@ -86,13 +87,13 @@ This is a user decision point. **Must follow the `comet/reference/decision-point
 When the user chooses to continue:
 
 ```bash
-node "$COMET_STATE" set <name> build_pause null
+comet state set <name> build_pause null
 ```
 
 When the user chooses to pause:
 
 ```bash
-node "$COMET_STATE" set <name> build_pause plan-ready
+comet state set <name> build_pause plan-ready
 ```
 
 After setting `build_pause: plan-ready`, stop the current invocation. Do not choose `isolation` or `build_mode`, and do not load an execution skill.
@@ -102,7 +103,7 @@ After setting `build_pause: plan-ready`, stop the current invocation. Do not cho
 If resuming with `build_pause: plan-ready` and the `plan` file exists, do not rerun `writing-plans`. First tell the user the workflow is stopped at the plan-ready pause point; after the user confirms continuing, set:
 
 ```bash
-node "$COMET_STATE" set <name> build_pause null
+comet state set <name> build_pause null
 ```
 
 Then continue this step to choose workspace isolation, execution method, TDD mode, and code review mode.
@@ -137,11 +138,11 @@ This is a user decision point. **Must follow the `comet/reference/decision-point
 After user selection, update `isolation`, execution method, TDD mode, and code review mode fields:
 
 ```bash
-node "$COMET_STATE" set <name> isolation <branch|worktree>
+comet state set <name> isolation <branch|worktree>
 ```
 
-- If the user chooses `executing-plans`: run `node "$COMET_STATE" set <name> subagent_dispatch null`, then run `node "$COMET_STATE" set <name> build_mode executing-plans`
-- If the user chooses `subagent-driven-development`: first confirm the current platform has real background subagent / Task / multi-agent dispatch capability; after confirming, run `node "$COMET_STATE" set <name> subagent_dispatch confirmed`, then run `node "$COMET_STATE" set <name> build_mode subagent-driven-development`
+- If the user chooses `executing-plans`: run `comet state set <name> subagent_dispatch null`, then run `comet state set <name> build_mode executing-plans`
+- If the user chooses `subagent-driven-development`: first confirm the current platform has real background subagent / Task / multi-agent dispatch capability; after confirming, run `comet state set <name> subagent_dispatch confirmed`, then run `comet state set <name> build_mode subagent-driven-development`
 - If real background dispatch capability cannot be confirmed, must not write `build_mode: subagent-driven-development`; must pause and wait for the user to choose `executing-plans` instead
 
 **TDD Mode**:
@@ -151,7 +152,7 @@ node "$COMET_STATE" set <name> isolation <branch|worktree>
 | `tdd` | Write a failing test first for each task, then implement | Recommended. Changes involving business logic, new features, APIs |
 | `direct` | Implement directly, no enforced TDD flow | Changes that don't need test coverage, or user chooses to skip tests and write code directly. hotfix/tweak presets default to `direct` |
 
-Run `node "$COMET_STATE" set <name> tdd_mode <tdd|direct>`
+Run `comet state set <name> tdd_mode <tdd|direct>`
 
 **Code Review Mode**:
 
@@ -161,21 +162,21 @@ Run `node "$COMET_STATE" set <name> tdd_mode <tdd|direct>`
 | `standard` | No per-task reviewer by default; dispatch a per-task reviewer only when a task hits a risk signal, plus one final lightweight code review | Default recommended, suits most ordinary changes |
 | `thorough` | Dispatch a per-task reviewer (spec + quality) on every task, plus one final complete review | High-risk, multi-module, architecture or security-related changes |
 
-Run `node "$COMET_STATE" set <name> review_mode <off|standard|thorough>`
+Run `comet state set <name> review_mode <off|standard|thorough>`
 
-`isolation` is a script-enforced hard constraint. Full workflow init may temporarily leave it as `null`, but only before this step. If it remains `null`, both the `build → verify` guard and `comet-state transition build-complete` will fail.
+`isolation` is a script-enforced hard constraint. Full workflow init may temporarily leave it as `null`, but only before this step. If it remains `null`, both the `build → verify` guard and `comet state transition build-complete` will fail.
 
-`subagent_dispatch` is a script-enforced hard constraint. `build_mode: subagent-driven-development` requires `subagent_dispatch: confirmed` before leaving the build phase, otherwise both `comet-guard.mjs build --apply` and `comet-state transition build-complete` will fail.
+`subagent_dispatch` is a script-enforced hard constraint. `build_mode: subagent-driven-development` requires `subagent_dispatch: confirmed` before leaving the build phase, otherwise both `comet guard build --apply` and `comet state transition build-complete` will fail.
 
-`tdd_mode` is a script-enforced hard constraint. Full workflow must have `tdd_mode` selected as `tdd` or `direct` before leaving the build phase, otherwise both `comet-guard.mjs build --apply` and `comet-state transition build-complete` will fail.
+`tdd_mode` is a script-enforced hard constraint. Full workflow must have `tdd_mode` selected as `tdd` or `direct` before leaving the build phase, otherwise both `comet guard build --apply` and `comet state transition build-complete` will fail.
 
-`review_mode` is a script-enforced hard constraint. Full workflow must have `review_mode` selected as `off`, `standard`, or `thorough` before leaving the build phase, otherwise both `comet-guard.mjs build --apply` and `comet-state transition build-complete` will fail. Legacy state files without this field follow a compat path, but should be backfilled on recovery.
+`review_mode` is a script-enforced hard constraint. Full workflow must have `review_mode` selected as `off`, `standard`, or `thorough` before leaving the build phase, otherwise both `comet guard build --apply` and `comet state transition build-complete` will fail. Legacy state files without this field follow a compat path, but should be backfilled on recovery.
 
 `build_mode` defaults to `direct` only for hotfix/tweak presets. Full workflow must not default to `direct`. Use it only when the user explicitly asks to bypass the plan execution skills and you record an explicit 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
 ```
 
 Without `direct_override: true`, `build_mode=direct` in full workflow is blocked by both guard and state transition.
@@ -204,11 +205,19 @@ git add docs/superpowers/plans/YYYY-MM-DD-feature.md
 git commit -m "chore: add implementation plan"
 ```
 
+After entering the final execution branch or worktree, bind the current change again inside that actual workspace. A branch switch invalidates the entry binding, and a new worktree does not inherit the original workspace-local selection file:
+
+```bash
+comet state select <change-name>
+```
+
+Do not begin source writes until this binding succeeds.
+
 **Execute plan**: Must handle execution according to the actual runtime of `build_mode`.
 
-- `build_mode: executing-plans`: **Immediately execute:** Use the Skill tool to load the Superpowers `executing-plans` skill. Skipping this step is prohibited. If the skill is unavailable, stop the process and prompt to install or enable the corresponding skill; do not substitute with normal conversation. After the skill loads, ARGUMENTS must include the same Language constraint as Step 1: `Language: Use the configured Comet artifact language from "$COMET_BASH" "$COMET_STATE" get <name> language`. Execute according to plan.
+- `build_mode: executing-plans`: **Immediately execute:** Use the Skill tool to load the Superpowers `executing-plans` skill. Skipping this step is prohibited. If the skill is unavailable, stop the process and prompt to install or enable the corresponding skill; do not substitute with normal conversation. After the skill loads, ARGUMENTS must include the same Language constraint as Step 1: `Language: Use the configured Comet artifact language from comet state get <name> language`. Execute according to plan.
 - `build_mode: subagent-driven-development`: The main session only coordinates and must not write implementation code directly. **Immediately execute:** Use the Skill tool to load the Superpowers `subagent-driven-development` skill. After the skill loads, read `comet/reference/subagent-dispatch.md` for Comet-specific extensions (real background dispatch, task isolation, checkoff verification, TDD constraints, continuous execution, context recovery) and apply them alongside the skill's workflow. If they conflict, the more specific Comet extensions take precedence.
-- If the current platform has no real background agent dispatch capability, must pause and wait for the user to choose main window execution instead. After the user chooses, must run `node "$COMET_STATE" set <name> build_mode executing-plans`, then follow the `build_mode: executing-plans` branch to load the Superpowers `executing-plans` skill. Must not continue executing tasks before the user explicitly chooses.
+- If the current platform has no real background agent dispatch capability, must pause and wait for the user to choose main window execution instead. After the user chooses, must run `comet state set <name> build_mode executing-plans`, then follow the `build_mode: executing-plans` branch to load the Superpowers `executing-plans` skill. Must not continue executing tasks before the user explicitly chooses.
 
 **TDD Mode Execution Constraints**:
 
@@ -227,7 +236,7 @@ Under `executing-plans`, the main session executes tasks directly (no isolated i
 - **`review_mode: thorough`**: In addition to the single final review, request one segmented code review per task segment (every 3 tasks, scoped to that segment's diff). If total tasks ≤ 3, skip the mid-execution segments and only do the final review. Each segment review uses `requesting-code-review` against the segment's commit range. This is the closest equivalent to `subagent-driven-development`'s per-task review that `executing-plans` can offer, since it has no isolated implementer to review per task.
 
 Requirements (apply to `standard` and `thorough`):
-- the `requesting-code-review` skill must be loaded before `node "$COMET_GUARD" <change-name> build --apply`
+- the `requesting-code-review` skill must be loaded before `comet guard <change-name> build --apply`
 - if `requesting-code-review` skill is unavailable, skip the review gate but must record `<!-- review skipped: skill unavailable -->` in tasks.md, then continue guard transition
 - CRITICAL review findings (security vulnerabilities, data loss risk, build/test failures) must be fixed first and must not be carried into verify
 - if non-CRITICAL review findings are accepted, record the acceptance reason and impact scope in tasks.md, the commit body, a verification report draft, or another durable artifact
@@ -282,14 +291,22 @@ Build is the longest phase and may span many tasks. To support resume after cont
 - `tdd_mode` has been written as `tdd` or `direct`
 - `review_mode` has been written as `off`, `standard`, or `thorough`
 - Code review has been completed per the `executing-plans` review gate (Section "Execute plan") for the chosen `review_mode`: under `standard` or `thorough`, code review has been requested and CRITICAL review findings fixed or non-CRITICAL acceptance rationale recorded; under `review_mode: off`, the reason for skipping automatic code review has been recorded in a persistent artifact
-- **Phase guard**: Run `node "$COMET_GUARD" <change-name> build --apply`; after all PASS, state advances to `phase: verify`
+- **Phase guard**: Run `comet guard <change-name> build --apply`; after all PASS, state advances to `phase: verify`
 
 Guard runs the inferred project build check (`npm run build`, Maven, or Cargo when detected). When the inferred command fails, guard prints the command output as evidence for debugging.
 
+If the project has no automatically inferred build command, the user or Agent must run the real build command first, then record its evidence separately:
+
+```bash
+comet state record-check <change-name> build --command "<actual build command>" --exit-code 0
+```
+
+`--command` records command text only; Comet **never executes it**. Build and verify evidence are separate and cannot substitute for each other. `COMET_SKIP_BUILD=1` is only a compatibility bypass for legacy workflows, not auditable build evidence.
+
 Before exit, run guard to auto-transition:
 
 ```bash
-node "$COMET_GUARD" <change-name> build --apply
+comet guard <change-name> build --apply
 ```
 
 State file is automatically updated to `phase: verify`, `verify_result: pending`.
@@ -299,7 +316,7 @@ State file is automatically updated to `phase: verify`, `verify_result: pending`
 Follow `comet/reference/auto-transition.md`. Key command:
 
 ```bash
-node "$COMET_STATE" next <change-name>
+comet state next <change-name>
 ```
 
 - `NEXT: auto` → invoke the skill pointed to by `SKILL` to enter the next phase

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

@@ -19,6 +19,7 @@ description: "Use when a full Comet change has completed open but lacks a Superp
 Locate scripts via `comet/reference/scripts.md`, then run entry verification. When resuming from any entry point, first run the recovery check in `comet/reference/context-recovery.md`:
 
 ```bash
+comet state select <change-name>
 node "$COMET_STATE" check <name> design
 ```
 

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

@@ -20,12 +20,14 @@ Quick bug fix workflow: open → build → verify → archive. Skip brainstormin
 
 ### 0. Output Language Constraint
 
-Streamlined OpenSpec artifacts must use the configured Comet artifact language. Read `language` from `.comet/config.yaml` before `.comet.yaml` exists, then use `"$COMET_BASH" "$COMET_STATE" get <name> language` after initialization.
+Streamlined OpenSpec artifacts must use the configured Comet artifact language. Before `.comet.yaml` exists, read `language` from project `.comet/config.yaml`, then fall back to global `~/.comet/config.yaml`; after initialization, use `"$COMET_BASH" "$COMET_STATE" get <name> language`.
 
 Execution chain: open → build → root cause check → verify → archive. Hotfix provides default decisions for each phase: streamlined open, direct build, root cause confirmation, scale-based verification, and final archive confirmation after verification passes.
 
 Before starting, locate Comet scripts via `comet/reference/scripts.md`. When resuming from any entry point, first use `comet/reference/context-recovery.md` to confirm phase/workflow.
 
+When resuming an existing hotfix change, the first state operation must be `comet state select <change-name>`. For a new change, run the command immediately after `.comet.yaml` initialization and before source writes.
+
 ### 1. Quick Open (preset open)
 
 Reuse Comet open capability to create change, but use hotfix defaults: do not execute `openspec-explore` long exploration, directly enter streamlined change creation.

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

@@ -13,7 +13,17 @@ description: "Use when Comet needs to create a new OpenSpec change, or an active
 
 ### 0. Output Language Constraint
 
-Every prompt and artifact request passed to OpenSpec must include the resolved Comet artifact language, using normalized ids such as `en` or `zh-CN`. Before `.comet.yaml` exists, read `language` from `.comet/config.yaml`; after the change is initialized, use `"$COMET_BASH" "$COMET_STATE" get <name> language`. If no configured language exists, fall back to the current user request language. The generated `proposal.md`, `design.md`, and `tasks.md` must use that language as their main language.
+Every prompt and artifact request passed to OpenSpec must include the resolved Comet artifact language, using normalized ids such as `en` or `zh-CN`. Before `.comet.yaml` exists, read `language` from project `.comet/config.yaml`, then fall back to global `~/.comet/config.yaml`; after the change is initialized, use `"$COMET_BASH" "$COMET_STATE" get <name> language`. If no configured language exists, fall back to the current user request language. The generated `proposal.md`, `design.md`, and `tasks.md` must use that language as their main language.
+
+### 0a. Current Change Binding
+
+When resuming an existing change, the first state operation must be:
+
+```bash
+comet state select <change-name>
+```
+
+When creating a new change, initialize `.comet.yaml` first, then immediately run the same command; never fabricate a selection before state exists.
 
 ### 1. Explore Ideas and Clarify Requirements
 

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

@@ -23,12 +23,14 @@ Applicable for OpenSpec-chained lightweight changes, such as configuration adjus
 
 ### 0. Output Language Constraint
 
-Streamlined OpenSpec artifacts must use the configured Comet artifact language. Read `language` from `.comet/config.yaml` before `.comet.yaml` exists, then use `"$COMET_BASH" "$COMET_STATE" get <name> language` after initialization.
+Streamlined OpenSpec artifacts must use the configured Comet artifact language. Before `.comet.yaml` exists, read `language` from project `.comet/config.yaml`, then fall back to global `~/.comet/config.yaml`; after initialization, use `"$COMET_BASH" "$COMET_STATE" get <name> language`.
 
 Execution chain: open → OpenSpec apply → verify → archive. Tweak provides default decisions for each phase: streamlined open, direct build through OpenSpec apply, scale- and delta-spec-driven verification weight, and final archive confirmation after verification passes.
 
 Before starting, locate Comet scripts via `comet/reference/scripts.md`. When resuming from any entry point, first use `comet/reference/context-recovery.md` to confirm phase/workflow.
 
+When resuming an existing tweak change, the first state operation must be `comet state select <change-name>`. For a new change, run the command immediately after `.comet.yaml` initialization and before source writes.
+
 ### 1. Quick Open (preset open)
 
 Reuse Comet open capability to create change, but use tweak defaults: do not execute `openspec-explore` long exploration, directly enter streamlined change creation.

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

@@ -14,14 +14,15 @@ description: "Use when a Comet change has completed build and needs implementati
 
 ### 0a. Output Language Constraint
 
-Verification reports and branch-handling notes must use the configured Comet artifact language from `"$COMET_BASH" "$COMET_STATE" get <name> language`.
+Verification reports and branch-handling notes must use the configured Comet artifact language from `comet state get <name> language`.
 
 ### 0b. Entry State Verification (Entry Check)
 
-Locate scripts via `comet/reference/scripts.md`, then run entry verification. When resuming from any entry point, first run the recovery check in `comet/reference/context-recovery.md`:
+Use the stable `comet` CLI described in `comet/reference/scripts.md`, then run entry verification. When resuming from any entry point, first run the recovery check in `comet/reference/context-recovery.md`:
 
 ```bash
-node "$COMET_STATE" check <change-name> verify
+comet state select <change-name>
+comet state check <change-name> verify
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -33,7 +34,7 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 Execute scale assessment:
 
 ```bash
-node "$COMET_STATE" scale <change-name>
+comet state scale <change-name>
 ```
 
 The script automatically counts tasks, delta spec count, changed file count, determines light or full verification mode, and sets the verify_mode field. Decision rule (any condition triggers full): tasks > 3, delta spec capabilities > 1, changed files > 8.
@@ -48,7 +49,7 @@ Only after user chooses fix, allow rollback to build phase:
 
 ```bash
 # Execute only after user confirms fix
-node "$COMET_STATE" transition <change-name> verify-fail
+comet state transition <change-name> verify-fail
 ```
 
 Note: When verify-fail rolls back to build, `branch_status` is not reset. If branch handling was already completed during the first verify attempt, skip the branch handling step on re-verify and keep the existing `branch_status: handled`.
@@ -56,7 +57,7 @@ Note: When verify-fail rolls back to build, `branch_status` is not reset. If bra
 Note: If every task in build phase was committed, the script's file count based on working tree diff may underestimate change scale. In this case, must read plan file header `base-ref` and verify with commit range:
 
 ```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
 If commit range shows changes exceed lightweight threshold (> 8 files, cross-module coordination, or delta spec spans more than 1 capability), manually set to full verification:
 
 ```bash
-node "$COMET_STATE" set <change-name> verify_mode full
+comet state set <change-name> verify_mode full
 ```
 
-**Override mechanism**: If the agent or user believes the automated assessment is inappropriate, override at any time with `node "$COMET_STATE" set <change-name> verify_mode <light|full>`.
+**Override mechanism**: If the agent or user believes the automated assessment is inappropriate, override at any time with `comet state set <change-name> verify_mode <light|full>`.
 
 ### 1b. Verification Failure Decision (Blocking Point)
 
-When verification does not pass, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to decide whether to fix or accept the deviation**. Must not automatically run `node "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`.
+When verification does not pass, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to decide whether to fix or accept the deviation**. Must not automatically run `comet state transition <change-name> verify-fail`, nor automatically invoke `/comet-build`.
 
 When pausing, must list:
 - Failed items
@@ -81,7 +82,7 @@ When pausing, must list:
 **Uncertainty principle**: When severity is unclear, downgrade (SUGGESTION > WARNING > CRITICAL). Only use CRITICAL for build failures, test failures, and security issues; ambiguous or uncertain issues should be WARNING or SUGGESTION.
 
 After user selection, continue as follows:
-- **Fix all**: Run `node "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build` to fix
+- **Fix all**: Run `comet state transition <change-name> verify-fail`, then invoke `/comet-build` to fix
 - **Handle item by item**: CRITICAL or IMPORTANT failures must be fixed; WARNING/SUGGESTION failures may choose to accept deviation, but must record acceptance reason and impact scope in verification report. If any CRITICAL or IMPORTANT failure exists, skipping fix to accept all is not allowed
 
 **Retry limit**: After 3 consecutive verify-fail cycles, on the 4th failure the agent must not automatically choose to continue fixing; **must use the current platform's available user input/confirmation mechanism to pause** with only two options: "Accept all deviations and record" or "Continue fixing", for the user to explicitly decide.
@@ -91,8 +92,8 @@ After user selection, continue as follows:
 When verification needs to read OpenSpec artifacts, first check whether they have changed since the design phase:
 
 ```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 "")
 ```
 
 - If `RECORDED_HASH` = `CURRENT_HASH` and both are non-empty and neither is `null`: OpenSpec artifacts are unchanged. **tasks.md does not need to be re-read in full** (use `grep -c '\- \[ \]' tasks.md` to confirm completion count). proposal.md, design.md, and delta specs must still be read for comparison checks.
@@ -117,6 +118,14 @@ Run these 6 checks:
 
 The lightweight code review input should be limited to this change's diff, tasks.md, and necessary test results; the review scope covers implementation correctness, security risk, and edge cases only, and does not perform spec coverage, Design Doc consistency, or drift checks. If the review finds CRITICAL or IMPORTANT issues, treat verification as failed and enter Step 1b. `review_mode: off` only skips automatic code review, not build, test, security checks, or debug gate protocol.
 
+If the project has no automatically inferred verification command, the user or Agent must run the real verification command first, then record its evidence separately:
+
+```bash
+comet state record-check <change-name> verify --command "<actual verification command>" --exit-code 0
+```
+
+`--command` records command text only; Comet **never executes it**. Verify and build evidence are separate and cannot substitute for each other. Even when a compatibility workflow uses `COMET_SKIP_BUILD=1`, that bypass cannot be treated as auditable verification or build evidence.
+
 **Dedup with build-phase review**: if the build phase (`executing-plans` or `subagent-driven-development`) already completed a final code review of the same diff under `review_mode`, this lightweight verify review focuses on "whether the implementation is correct against spec/tasks" and "changes added after build", and does not re-review the diff that build already reviewed and that has not changed.
 
 **Pass criteria**: All 6 items OK, no CRITICAL or IMPORTANT issues.
@@ -125,7 +134,7 @@ The lightweight code review input should be limited to this change's diff, tasks
 
 ```bash
 # Execute only after user confirms fix
-node "$COMET_STATE" transition <change-name> verify-fail
+comet state transition <change-name> verify-fail
 ```
 
 **Report format**: Brief table listing 6 check results + PASS/FAIL.
@@ -155,13 +164,13 @@ When verification does not pass: report missing items, enter Step 1b verificatio
 
 ```bash
 # Execute only after user confirms fix
-node "$COMET_STATE" transition <change-name> verify-fail
+comet state transition <change-name> verify-fail
 ```
 
 **Spec Drift Handling** (user decision point):
 - If check item 6 finds contradictions (delta spec has content but design doc does not reflect it), **must use the current platform's available user input/confirmation mechanism as a single-select question to pause and wait for the user to choose the handling method**; must not select automatically. Options:
   - Option A: Append "Implementation Divergence" section to design doc recording deviation reason. Option A is a verify phase allowed artifact; after writing, must not re-trigger Step 1b dirty-worktree decision due to that design doc change
-  - Option B: After user selects B, run `node "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`; `/comet-build`'s Spec Incremental Update rules will load the Superpowers `brainstorming` skill to update Design Doc + delta spec
+  - Option B: After user selects B, run `comet state transition <change-name> verify-fail`, then invoke `/comet-build`; `/comet-build`'s Spec Incremental Update rules will load the Superpowers `brainstorming` skill to update Design Doc + delta spec
   - Option C: Confirm deviation is acceptable, continue verification (design doc will be marked as `superseded-by-main-spec` during archiving)
 
 ### 3. Finishing (Superpowers)
@@ -191,8 +200,8 @@ mkdir -p docs/superpowers/reports
 # Write verification conclusions to report file, e.g.:
 # 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
 ```
 
 ## Exit Conditions
@@ -201,12 +210,12 @@ node "$COMET_STATE" set <change-name> branch_status handled
 - Branch handled
 - `verification_report` in `.comet.yaml` points to an existing verification report file
 - `branch_status: handled` in `.comet.yaml`
-- **Phase guard**: Run `node "$COMET_GUARD" <change-name> verify --apply`; after all PASS, auto-transitions to `phase: archive` through `comet-state transition verify-pass`
+- **Phase guard**: Run `comet guard <change-name> verify --apply`; after all PASS, auto-transitions to `phase: archive` through `comet state transition verify-pass`
 
 After both verification and branch handling are complete, run guard for auto-transition:
 
 ```bash
-node "$COMET_GUARD" <change-name> verify --apply
+comet guard <change-name> verify --apply
 ```
 
 State file auto-updates to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
@@ -220,7 +229,7 @@ Follow `comet/reference/context-recovery.md` with phase set to `verify`.
 Follow `comet/reference/auto-transition.md`. Key command:
 
 ```bash
-node "$COMET_STATE" next <change-name>
+comet state next <change-name>
 ```
 
 - `NEXT: auto` → invoke the skill pointed to by `SKILL` to enter the next phase

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

@@ -22,7 +22,7 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 ### 输出语言规则
 
-所有 OpenSpec 和 Superpowers 产物都必须使用 Comet 配置的产物语言。配置值是规范化语言 ID，`en` 或 `zh-CN`。已有 change 优先通过 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取 `openspec/changes/<name>/.comet.yaml` 中的 `language`；`.comet.yaml` 尚不存在时读取 `.comet/config.yaml` 的 `language`；两者都不存在时才回退到当前用户请求语言。调用外部 OpenSpec/Superpowers skill 时，必须把解析后的语言显式写入 prompt 或 ARGUMENTS。
+所有 OpenSpec 和 Superpowers 产物都必须使用 Comet 配置的产物语言。配置值是规范化语言 ID，`en` 或 `zh-CN`。已有 change 优先通过 `"$COMET_BASH" "$COMET_STATE" get <name> language` 读取 `openspec/changes/<name>/.comet.yaml` 中的 `language`；`.comet.yaml` 尚不存在时依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `language`；都不存在时才回退到当前用户请求语言。调用外部 OpenSpec/Superpowers skill 时，必须把解析后的语言显式写入 prompt 或 ARGUMENTS。
 
 ### 阶段自动检测
 
@@ -40,6 +40,30 @@ agent 做决策只需读本节，参考附录按需查阅。
    - `ask_user` → 按 `comet/reference/decision-point.md` 暂停并等待用户选择
    - `out_of_scope` → 说明本次输入不是 Comet workflow 启动/恢复请求，不初始化 change
 
+当 runtime route、Ambient Resume 或用户选择已经解析出明确 change 后，进入对应阶段 Skill 前必须先绑定当前执行上下文：
+
+```bash
+comet state select <change-name>
+```
+
+多个 active change 且用户尚未明确选择时，不得提前绑定；继续按 `ask_user` 决策点等待选择。
+
+### Comet Ambient Resume
+
+当用户未显式输入 `/comet`，但当前仓库可能已有 active Comet change 时，开始处理需要改动或调查的任务前先运行只读探针：
+
+```bash
+node "$COMET_RESUME_PROBE" probe --stdin
+```
+
+探针只读仓库状态，不修改文件。按返回值处理：
+
+- `auto_resume`：输出一行 `[COMET] 检测到 active change <name>，按 <nextCommand> 恢复。`，然后进入 `nextCommand`。
+- `ask_user`：只问一个短问题并等待用户回复。
+- `out_of_scope` 或 `none`：不要进入 Comet workflow。
+
+原则：不把无关任务挂到 active Comet change，尤其不能只因为存在 `.comet.yaml` 就这样做。
+
 **CometIntentFrame 最小骨架**：
 
 ```json

package/assets/skills-zh/comet/reference/comet-yaml-fields.md

@@ -2,7 +2,7 @@
 
 规范路径：`comet/reference/comet-yaml-fields.md`
 
-本文件是 `openspec/changes/<name>/` 下每个 change 级 `.comet.yaml` 状态文件的字段参考。按需查阅，不随 skill 一次性加载。项目级默认配置只放在 `.comet/config.yaml`。
+本文件是 `openspec/changes/<name>/` 下每个 change 级 `.comet.yaml` 状态文件的字段参考。按需查阅，不随 skill 一次性加载。项目级默认配置放在 `.comet/config.yaml`，全局默认配置放在 `~/.comet/config.yaml`；项目配置优先于全局配置。
 
 ## 示例
 
@@ -26,6 +26,7 @@ verification_report: null
 branch_status: pending
 created_at: 2026-05-26
 verified_at: null
+archive_confirmation: null
 archived: false
 ```
 
@@ -34,7 +35,7 @@ archived: false
 | 字段 | 含义 |
 |------|------|
 | `workflow` | `full`、`hotfix` 或 `tweak` |
-| `language` | 产物语言，仅支持 `en` 或 `zh-CN`。由 `comet init` 的初始化语言写入 `.comet/config.yaml`，创建 change 时快照到 `.comet.yaml`，用于约束 OpenSpec / Superpowers 产物主语言 |
+| `language` | 产物语言，仅支持 `en` 或 `zh-CN`。由 `comet init` 按安装范围写入项目或全局 `.comet/config.yaml`，创建 change 时按“项目优先、全局回退”快照到 `.comet.yaml`，用于约束 OpenSpec / Superpowers 产物主语言 |
 | `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive`（init 统一设为 `open`，guard 负责过渡） |
 | `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
 | `plan` | 关联的 Superpowers Plan 路径，可为空 |
@@ -52,6 +53,7 @@ archived: false
 | `branch_status` | `pending` 或 `handled`，分支处理完成后设为 `handled` |
 | `created_at` | change 创建日期（init 时自动写入），格式 `YYYY-MM-DD` |
 | `verified_at` | 验证通过时间，可为空 |
+| `archive_confirmation` | `null`、`pending` 或 `confirmed`。`verify-pass` 进入 archive 阶段时写入 `pending`；用户在 `/comet-archive` 最终确认选择「确认归档」后，`archive-confirm` transition 写入 `confirmed`；`archive-reopen` 会清空该字段，防止复用旧确认 |
 | `archived` | change 是否已归档 |
 
 ## 可选字段
@@ -70,4 +72,5 @@ archived: false
 - `build_mode: direct` 默认只允许 `hotfix` / `tweak`；full workflow 需要 `direct_override: true`
 - `build_pause` 不是执行方式，不得写入 `build_mode`
 - 这些约束同时存在于 `comet-guard.mjs build --apply` 和 `comet-state.mjs transition <name> build-complete`
+- `archive_confirmation` 是 machine-owned 字段，只能由 `verify-pass`、`archive-confirm` 和 `archive-reopen` transition 更新，不能通过 `set` 直接伪造确认；`archived` transition 和真实归档命令都要求其值为 `confirmed`
 - `preset-escalate` 事件：仅允许 `hotfix`/`tweak` workflow 在 `phase: build` 时调用，原子地把 `workflow`/`classic_profile` 置为 `full`、`phase` 回退到 `design`、清空 `design_doc`（满足 comet-design 入口要求）。这是预设升级到 full 的唯一合法通道——直接 `set phase design` 会被状态机硬拦截，`set classic_profile` 属于 machine-owned 字段不可手动设置

package/assets/skills-zh/comet/reference/context-recovery.md

@@ -14,6 +14,16 @@ node "$COMET_STATE" check <change-name> <phase> --recover
 
 若检查结果显示实际 phase、workflow 或 evidence 应由其他 Skill 处理，按脚本输出和 `/comet` 路由规则切换；不要在错误阶段继续补写状态。若存在未提交改动，先按 `comet/reference/dirty-worktree.md` 归因。
 
+## 未显式 `/comet` 的恢复
+
+如果用户没有提 `/comet`，但本仓库可能有 active change，开始处理需要改动或调查的任务前先运行 Ambient Resume 探针。先按 `comet/reference/scripts.md` 定位脚本并确保 `$COMET_RESUME_PROBE` 可用，然后把当前用户请求从 stdin 传入：
+
+```bash
+node "$COMET_RESUME_PROBE" probe --stdin
+```
+
+只有返回 `auto_resume` 才自动恢复；`ask_user` 必须短问用户；`out_of_scope` 和 `none` 不进入 workflow。
+
 ## 恢复步骤
 
 ```bash