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

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 rpamis
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 rpamis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -16,9 +16,14 @@
   <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm weekly download count" src="https://img.shields.io/npm/dw/@rpamis/comet?style=flat-square&label=Downloads/wk" /></a>
   <a href="https://docs.comet.rpamis.com/"><img alt="Comet Docs" src="https://img.shields.io/badge/Docs-docs.comet.rpamis.com-FFD700?style=flat-square" /></a>
   <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
+  <a href="https://atomgit.com/rpamis/comet"><img alt="AtomGitStars" src="https://atomgit.com/rpamis/comet/star/badge.svg" /></a>
 </p>
 
-# @rpamis/comet
+<p align="center">
+<a href="https://trendshift.io/repositories/38989?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-38989" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/38989" alt="rpamis%2Fcomet | Trendshift" width="250" height="55"/></a>
+</p>
+
+## What is Comet ?
 
 ```
  ██████╗ ██████╗ ███╗   ███╗███████╗████████╗
@@ -532,7 +537,8 @@ build_mode: subagent-driven-development                  # Build mode: subagent-
 build_pause: null                                        # `build_pause` records an internal build-phase pause point: null none, `plan-ready` means the plan has been generated
 subagent_dispatch: null                                  # Dispatch confirmation; confirm before verify
 tdd_mode: null                                           # Full-workflow build choice: tdd | direct
-isolation: branch                                        # Isolation mode: branch | worktree
+isolation: branch                                        # Isolation mode: current | branch | worktree
+bound_branch: null                                       # Git branch bound by current/branch/worktree isolation; branch drift blocks progress
 verify_mode: null                                        # Verification mode: light | full
 design_doc: docs/superpowers/specs/<design-doc>.md       # Design doc path
 plan: docs/superpowers/plans/YYYY-MM-DD-feature.md       # Implementation plan path
@@ -576,7 +582,8 @@ Comet ensures agent execution reliability through automated state transitions:
    - Detects unknown/typos fields
 
 4. **Build Decision Enforcement** — Guard and state transitions both block skipped build choices
-   - `isolation` must be `branch` or `worktree`
+   - `isolation` must be `current`, `branch`, or `worktree`
+   - `isolation: current`, `branch`, and `worktree` bind the current Git branch, and later entry checks block accidental branch drift
    - `build_mode` must be selected before leaving build
    - `build_pause: plan-ready` is a recoverable pause after plan generation, not a `build_mode`
    - Full workflow `build_mode: direct` requires `direct_override: true`
@@ -716,7 +723,7 @@ Track our development progress and upcoming features on the [Comet Roadmap](http
       <b>DouYin (Recommended)</b>
     </td>
     <td align="center" width="180">
-      <img src="https://github.com/rpamis/comet/blob/master/img/wechat.jpg" width="120" height="120"><br>
+      <img src="https://github.com/rpamis/comet/blob/master/img/wechat.png" width="120" height="120"><br>
       <b>WeChat</b>
     </td>
     <td align="center" width="180">

package/assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.0-beta.4",
+  "version": "0.4.0-beta.6",
   "skills": [
     "comet/SKILL.md",
     "comet/reference/auto-transition.md",

package/assets/skills/comet/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comet
-description: "Use when the user wants to start or resume a Comet workflow and route by active change, .comet.yaml, and hotfix/tweak intent."
+description: "Use when the user explicitly invokes /comet, asks to start or resume a Comet-managed workflow, or repository evidence identifies one unambiguous active Comet change; route through the intent runtime and .comet.yaml."
 ---
 
 # Comet — OpenSpec + Superpowers Dual-Star Development Workflow
@@ -22,7 +22,7 @@ Agents need only read this section for decision-making. Refer to the Reference A
 
 ### Output Language Rule
 
-Use the configured Comet artifact language as the output language for every OpenSpec and Superpowers artifact. The configured value is a normalized language id, `en` or `zh-CN`. For an existing change, read `language` from `openspec/changes/<name>/.comet.yaml` using `"$COMET_BASH" "$COMET_STATE" get <name> language`. Before `.comet.yaml` exists, read `language` from project `.comet/config.yaml`, then fall back to global `~/.comet/config.yaml`; if neither exists, fall back to the current user request language. Include the resolved language explicitly in every prompt or ARGUMENTS passed to external OpenSpec/Superpowers skills.
+Use the configured Comet artifact language as the output language for every OpenSpec and Superpowers artifact. The configured value is a normalized language id, `en` or `zh-CN`. For an existing change, read `language` from `openspec/changes/<name>/.comet.yaml` using `comet state get <name> language`. Before `.comet.yaml` exists, read `language` from project `.comet/config.yaml`, then fall back to global `~/.comet/config.yaml`; if neither exists, fall back to the current user request language. Include the resolved language explicitly in every prompt or ARGUMENTS passed to external OpenSpec/Superpowers skills.
 
 ### Automatic Phase Detection
 
@@ -126,22 +126,22 @@ Prefer reading `openspec/changes/<name>/.comet.yaml`. If not available, fall bac
 - On every context resume, rerun Step 0 and Step 1; do not trust conversation history for phase detection
 - If there is an active change and the worktree has uncommitted changes, handle them through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions; this file does not repeat them
 - If `phase: build`, first check `build_pause`, `plan`, `isolation`, `build_mode`, `tdd_mode`, and `review_mode` (see details below):
-  - If `build_pause: plan-ready` but `isolation`, `build_mode`, `tdd_mode`, and `review_mode` are all already set, treat as stale pause: first output `[COMET] Detected stale pause (build_pause=plan-ready but isolation/build_mode/tdd_mode/review_mode are set), auto-clearing and continuing`, then run `node "$COMET_STATE" set <name> build_pause null`, then read the next unchecked task from tasks.md and resume execution per `build_mode`
+  - If `build_pause: plan-ready` but `isolation`, `build_mode`, `tdd_mode`, and `review_mode` are all already set, treat as stale pause: first output `[COMET] Detected stale pause (build_pause=plan-ready but isolation/build_mode/tdd_mode/review_mode are set), auto-clearing and continuing`, then run `comet state set <name> build_pause null`, then read the next unchecked task from tasks.md and resume execution per `build_mode`
   - If `build_pause: plan-ready` and the plan file exists, but `isolation`, `build_mode`, `tdd_mode`, or `review_mode` is not yet set, return to the `/comet-build` plan-ready resume point, prompt the user to complete/confirm workspace isolation, execution method, TDD mode, and code review mode, and do not regenerate the plan
   - If `build_pause: plan-ready` but the plan file is missing, return to `/comet-build` to handle corrupted state or regenerate the plan
   - If `isolation`, `build_mode`, `tdd_mode`, or `review_mode` is unset, return to the corresponding `/comet-build` step to supplement before executing
   - If all are set, read the next unchecked task from tasks.md and continue:
     - If `build_mode: subagent-driven-development`, do not execute tasks directly in the main window; return to `/comet-build`'s background subagent dispatch rules, main window only coordinates
     - Other execution modes follow `/comet-build`'s corresponding rules
-- If `phase: verify` and `verify_result: fail`, enter the verification failure decision blocking point: pause and ask the user to fix or accept deviation; only after the user chooses fix, run `node "$COMET_STATE" transition <name> verify-fail` and invoke `/comet-build`
-- If `phase: open` but proposal/design/tasks are complete, first run `node "$COMET_GUARD" <change-name> open --apply` to repair state, then continue detection
-- If `phase: archive`, only invoke `/comet-archive`; `/comet-archive` must first wait for final archive confirmation. After archive succeeds, the change moves to the archive directory, so do not run guard against the old active directory
+- If `verify_result: fail`, read `verify_failures`. At 3 or fewer failures, invoke `/comet-build` directly to continue the recorded repair loop without re-asking. Above the automatic limit, return to `/comet-verify` for the exception decision. User input is required only to accept a WARNING/SUGGESTION deviation or choose a strategy after the retry limit
+- If `phase: open` but OpenSpec `applyRequires` is complete, run `comet guard <change-name> open --apply` to repair state, then continue detection
+- If `phase: archive`, only invoke `/comet-archive`; confirm first, archive, commit exact archive paths, then handle the branch and run the archive guard
 
 **Step 2: Phase Determination** (check in order, first match wins)
 
 1. `archived: true` or change moved to archive → Workflow complete
 2. `verify_result: pass` and `archived` is not `true` → Invoke `/comet-archive` (first perform final archive confirmation)
-3. `verify_result: fail` → Enter verification failure decision blocking point (pause and ask fix or accept deviation; only after user chooses fix, run `verify-fail` then `/comet-build`)
+3. `verify_result: fail` → Invoke `/comet-build` automatically to continue repair. If `verify_failures` exceeds the automatic limit, enter `/comet-verify`'s retry-limit strategy decision
 4. `phase: verify` or tasks.md all checked → Invoke `/comet-verify`
 5. `phase: build` or has Design Doc but plan/execution incomplete → Route by workflow: `hotfix` → `/comet-hotfix`, `tweak` → `/comet-tweak`, `full` → `/comet-build`
 6. `phase: design` or has change but no Design Doc → Invoke `/comet-design`
@@ -156,11 +156,11 @@ hotfix/tweak scope assessment uses a three-layer division of labor, avoiding "us
 
 1. **Qualitative-change signals** (agent semantic recognition; hitting any one pauses and delegates a two-choice decision to the user): cross-module coordinated change, new capability needed, database schema change, introduces new public API, hits deep architecture issues (each preset reuses this core signal set and may add its own context-specific signal, such as tweak's "needing to split into multiple OpenSpec changes")
 2. **File-count tripwire** (user decides; not an automatic upgrade): when changed files exceed a hint threshold, pause and let the user decide whether to continue the preset or upgrade to full; do not auto-kick
-3. **Verification weight** (scale script decides): `comet-state scale` only decides `verify_mode` (verification weight); it does not block the flow or trigger an upgrade
+3. **Verification weight** (scale script decides): `comet state scale` only decides `verify_mode` (verification weight); it does not block the flow or trigger an upgrade
 
 **Upgrade decision point (user chooses one of two)**:
 - Continue the preset lightweight flow (user confirms scope is manageable)
-- Upgrade to full `/comet` (use `node "$COMET_STATE" transition <name> preset-escalate` to legally rewind to the design phase, supplementing Design Doc and Superpowers plan)
+- Upgrade to full `/comet` (use `comet state transition <name> preset-escalate` to legally rewind to design and clear preset-only build settings; after the Design Doc, choose the full workflow configuration again in one joint decision)
 
 See the "Upgrade Assessment" section of each `comet-hotfix` / `comet-tweak` for detailed rules.
 
@@ -170,7 +170,8 @@ See the "Upgrade Assessment" section of each `comet-hotfix` / `comet-tweak` for
 |----------|----------|
 | `openspec list --json` fails | Check if openspec is installed, prompt user to run `openspec init` |
 | Sub-skill unavailable | Stop workflow, prompt to install or enable the corresponding skill |
-| `.comet.yaml` malformed or missing | Use file state as source of truth, correct with `node "$COMET_STATE" set` then continue |
+| `.comet.yaml` missing | Enter the relevant preset's `/comet-open` initialization, then run `comet state select`; never skip initialization |
+| `.comet.yaml` malformed | Stop and report the parse error; repair from version control, backup, or verifiable artifacts, never overwrite it with `comet state set` |
 | Build/test fails | Return to build phase for fixes, do not enter verify |
 | Incomplete change directory structure | Fill missing files according to `comet-open` artifact requirements |
 
@@ -183,20 +184,21 @@ Flow chain: open → design → build → verify → archive
 
 **Continuous execution requirement**: starting from the detected phase, the agent automatically continues through all later phases. But **auto-advancing only applies at transition points without user decisions**. When encountering user decision points, **must use the current platform's available user input/confirmation mechanism to pause and wait for the user's explicit response**. Must not use recommendation rules, defaults, or historical preferences to substitute for user confirmation, and must not just output a text prompt and then continue executing.
 
-**Distinguish phase advancement vs automatic handoff**: each sub-skill runs phase guard `--apply` before exit to advance the `.comet.yaml` `phase` field. This step **always happens** and is not controlled by `auto_transition`. After that, the sub-skill runs `node "$COMET_STATE" next <name>` to resolve the next action: when `auto_transition` is not `false`, output is `NEXT: auto` (auto-invoke next skill); when `auto_transition` is `false`, output is `NEXT: manual` (do not invoke next skill, show a manual run hint). Therefore `auto_transition` **only controls next skill invocation, not phase advancement**. Regardless of `auto_transition`, user decision points below remain blocking.
+**Distinguish phase advancement vs automatic handoff**: each sub-skill runs phase guard `--apply` before exit to advance the `.comet.yaml` `phase` field. This step **always happens** and is not controlled by `auto_transition`. After that, the sub-skill runs `comet state next <name>` to resolve the next action: when `auto_transition` is not `false`, output is `NEXT: auto` (auto-invoke next skill); when `auto_transition` is `false`, output is `NEXT: manual` (do not invoke next skill; return control with `HINT`). `NEXT: manual` is not a user decision point and must not ask whether to continue. Therefore `auto_transition` **only controls next skill invocation, not phase advancement**. Regardless of `auto_transition`, genuine user decision points below remain blocking.
 
 **Decision points are blocking points**: whenever reaching any of the following nodes, the current `/comet` invocation must stop, and follow the `comet/reference/decision-point.md` protocol to obtain the user's explicit choice. Only after the user explicitly chooses can the corresponding state fields be written and operations executed, then auto-advance resumes.
 
 Nodes requiring user participation (pause only at these nodes):
-1. Open phase proposal/design/tasks review and confirmation
-2. Confirm design approach during brainstorming
-3. Plan-ready pause choice during build phase, followed by workflow configuration selection (workspace isolation + execution method + TDD mode + code review mode)
-4. Decide to fix or accept deviation when verify fails (including Spec drift handling)
-5. Choose branch handling method for finishing-branch
+1. Workflow target selection: multiple active changes, continue an existing change versus create a new one, or choose which completed batch item starts first
+2. Open-phase final proposal/design/tasks review, including the change name and scope; clear requests have no pre-artifact summary/name confirmation
+3. Confirm the design approach during brainstorming
+4. One joint build decision: plan-ready pause or all available workflow settings (workspace isolation + execution method + TDD mode + code review mode, plus branch name when branch is selected)
+5. Verify-phase acceptance of WARNING/SUGGESTION deviations, Spec drift handling, or continue/stop after the 4th failure; the first 3 clearly repairable failures close automatically
 6. Archive phase final confirmation before running the archive script
-7. Encounter an upgrade-assessment signal (hotfix/tweak → user chooses one of two: continue preset / upgrade to full workflow)
-8. Build phase scope expansion requiring redesign or new change split
-9. Open phase large PRD requiring confirmation to split into multiple changes
+7. Choose finishing-branch handling after exact archive changes are committed
+8. Encounter an upgrade-assessment signal (hotfix/tweak → user chooses one of two: continue preset / upgrade to full workflow)
+9. Build phase scope expansion requiring redesign or new change split
+10. Open phase large PRD split confirmation
 
 Agents should not skip these decision points; other unambiguous phase transitions must proceed automatically, must not exit midway. At decision points, **must not skip user confirmation or choose automatically — must explicitly obtain the user's choice through the current platform's available user input/confirmation mechanism before continuing**.
 
@@ -220,8 +222,8 @@ Agents should not skip these decision points; other unambiguous phase transition
 | `/comet-open` | 1. Open | OpenSpec | proposal.md, design.md, tasks.md |
 | `/comet-design` | 2. Deep Design | Superpowers | Design Doc, delta spec |
 | `/comet-build` | 3. Plan and Build | Superpowers | Implementation plan, code commits |
-| `/comet-verify` | 4. Verify and Close | Both | Verification report, branch handling |
-| `/comet-archive` | 5. Archive | OpenSpec | delta→main spec sync, design doc markup, archive |
+| `/comet-verify` | 4. Verify | Both | Verification report |
+| `/comet-archive` | 5. Archive and Close | OpenSpec | delta→main spec sync, design doc markup, archive commit, branch handling |
 | `/comet-hotfix` | Preset path | Both | Quick fix (skip brainstorming) |
 | `/comet-tweak` | Preset path | Both | OpenSpec-chained medium change (delta spec is first-class, skip brainstorming and full plan) |
 
@@ -246,14 +248,14 @@ Agents should not skip these decision points; other unambiguous phase transition
 
 ### State Machine Hard Constraints
 
-- Before `build → verify`, `isolation` must be `branch` or `worktree`
+- Before `build → verify`, `isolation` must be `current`, `branch`, or `worktree`; all three workspace modes must come from explicit user selection and bind the current branch
 - Before `build → verify`, `build_mode` must be selected
 - `build_mode: subagent-driven-development` must also have `subagent_dispatch: confirmed`
 - Before full workflow leaves build phase, `tdd_mode` must be selected as `tdd` or `direct`
 - Before full workflow leaves build phase, `review_mode` must be selected as `off`, `standard`, or `thorough`
 - `build_mode: direct` is allowed by default only for `hotfix` / `tweak`; full workflow requires `direct_override: true`
 - `build_pause` is not an execution method and must not be written to `build_mode`
-- These constraints are enforced by both `comet-guard.mjs build --apply` and `comet-state.mjs transition <name> build-complete`
+- These constraints are enforced by both `comet guard <name> build --apply` and `comet state transition <name> build-complete`
 
 ### .comet.yaml Field Reference
 
@@ -281,11 +283,11 @@ See `comet/reference/debug-gate.md` for the complete debug gate protocol.
 
 ### Script Location
 
-Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars. The full bootstrap block, command reference (`--apply`, `transition`, `next`, `archive`), and output formats live in `comet/reference/scripts.md`. Run that bootstrap once per session, then reuse `$COMET_GUARD`, `$COMET_STATE`, `$COMET_HANDOFF`, `$COMET_ARCHIVE`, `$COMET_RUNTIME` throughout. Key entry points:
+Use the stable `comet` CLI for workflow state, guards, handoff, and archive. Locate internal launchers through `comet/reference/scripts.md` only for intent/resume probes that do not yet have a public subcommand. Key entry points:
 
 ```bash
-node "$COMET_GUARD" <change-name> <phase> --apply    # phase guard + auto state update
-node "$COMET_STATE" transition <change-name> <event> # open-complete | design-complete | build-complete | verify-pass | verify-fail
-node "$COMET_STATE" next <change-name>               # NEXT: auto|manual|done  + SKILL: <skill-name>; auto_transition:false → manual, which pauses only the next skill invocation and does not block phase updates
-node "$COMET_ARCHIVE" <change-name>                  # full archive in one command
+comet guard <change-name> <phase> --apply             # phase guard + state update
+comet state transition <change-name> <event>          # open-complete | design-complete | build-complete | verify-pass | verify-fail
+comet state next <change-name>                        # NEXT: auto|manual|done + SKILL: <skill-name>
+comet archive <change-name>                           # full archive in one command
 ```

package/assets/skills/comet/reference/auto-transition.md

@@ -13,7 +13,7 @@ This protocol is shared by all comet sub-skills. It defines the automatic handof
 After exit conditions are met and the phase guard has advanced phase, run:
 
 ```bash
-node "$COMET_STATE" next <change-name>
+comet state next <change-name>
 ```
 
 The script outputs a deterministic next step based on `phase`, `workflow`, and `auto_transition`:

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

@@ -21,8 +21,10 @@ tdd_mode: tdd
 review_mode: standard
 auto_transition: true
 isolation: branch
+bound_branch: null
 verify_mode: light
 verify_result: pending
+verify_failures: 0
 verification_report: null
 branch_status: pending
 created_at: 2026-05-26
@@ -44,14 +46,16 @@ archived: false
 | `build_mode` | Selected execution mode; may be empty. Values: `subagent-driven-development` (isolated background subagents implement and review each task), `executing-plans` (main session executes sequentially by plan), `direct` (main session codes directly; allowed by default only for hotfix/tweak, full workflow requires `direct_override: true`) |
 | `build_pause` | Build phase internal pause point. `null` = no pause, `plan-ready` = plan generated, paused for user model switch |
 | `subagent_dispatch` | `null` or `confirmed`. Only when the platform's real background subagent/Task/multi-agent dispatch capability is confirmed may `build_mode: subagent-driven-development` be written and used to leave the build phase |
-| `tdd_mode` | `tdd` or `direct`. Full workflow must select before leaving build. `tdd` forces write-failing-test-first per task; `direct` skips TDD enforcement. hotfix/tweak default to `direct` |
+| `tdd_mode` | `tdd` or `direct`. Full workflow must select before leaving build. `tdd` forces write-failing-test-first per task; `direct` skips per-task TDD but still requires relevant tests and bug-regression evidence. hotfix/tweak default to `direct` |
 | `review_mode` | `off`, `standard`, or `thorough`. Full workflow must select before leaving build; hotfix/tweak default to `off` |
-| `isolation` | `branch` or `worktree`, workspace isolation mode. Full init may be `null` but only until `/comet-build` Step 3; hotfix/tweak default to `branch` |
+| `isolation` | `current`, `branch`, or `worktree`. Full init may be `null`, but before leaving build the user must explicitly select `current`, create/select a real `branch`, or create/select a real `worktree`; hotfix/tweak may also truthfully use all three modes after the entry user decision point, and must not claim branch isolation before creating one |
+| `bound_branch` | Workspace branch binding record; may be empty. `isolation: current` / `branch` / `worktree` records the current Git branch of the directory the command runs in on first setting or entry check (for worktree mode, run set/check/guard inside that worktree, or the wrong branch gets bound/compared); switching `isolation` between workspace modes re-binds to the current branch, while repeating the same mode keeps the existing binding. Later `comet state select` / `comet state check` must confirm the bound branch still matches the current branch. On drift, `select` refuses and checks return `BLOCKED`; follow the decision-point protocol so the user chooses whether to switch back to the bound branch or explicitly confirm and run `comet state rebind <change-name>`. Clearing `isolation` clears this field |
 | `verify_mode` | `light` or `full`; may be empty |
 | `auto_transition` | `true` or `false`. Only controls whether to automatically invoke the next skill after phase guard advances phase; `false` outputs `manual` from `comet-state next`, pausing next-skill invocation but not blocking phase field updates |
 | `verify_result` | `pending`, `pass`, or `fail` |
+| `verify_failures` | Machine-owned consecutive verification failure count. `verify-fail` increments it; `verify-pass` or `archive-reopen` resets it to `0`. At `3`, the next failure requires the retry-limit strategy decision |
 | `verification_report` | Verification report file path; must point to an existing file before verify passes |
-| `branch_status` | `pending` or `handled`; set to `handled` after branch handling completes |
+| `branch_status` | `pending` or `handled`; keep pending through verify/archive, then set handled after the archive commit and selected branch handling complete |
 | `created_at` | Change creation date (auto-written at init), format `YYYY-MM-DD` |
 | `verified_at` | Verification pass timestamp; may be empty |
 | `archive_confirmation` | `null`, `pending`, or `confirmed`. `verify-pass` writes `pending` when entering the archive phase; after the user selects "Confirm archive" in `/comet-archive`, the `archive-confirm` transition writes `confirmed`; `archive-reopen` clears the field so an earlier confirmation cannot be reused |
@@ -65,7 +69,7 @@ archived: false
 
 ## State Machine Hard Constraints
 
-- Before `build → verify`, `isolation` must be `branch` or `worktree`
+- Before `build → verify`, `isolation` must be `current`, `branch`, or `worktree`
 - Before `build → verify`, `build_mode` must be selected
 - `build_mode: subagent-driven-development` requires `subagent_dispatch: confirmed`
 - Full workflow must select `tdd_mode` as `tdd` or `direct` before leaving build

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

@@ -9,7 +9,7 @@ This protocol is shared by all comet sub-skills that may trigger context compres
 The user may resume the workflow directly from `/comet-open`, `/comet-design`, `/comet-build`, `/comet-verify`, `/comet-archive`, `/comet-hotfix`, or `/comet-tweak`. On entry to any sub-skill, first locate scripts via `comet/reference/scripts.md`, then run the entry check or recovery check for that sub-skill's phase. Do not infer phase from conversation history.
 
 ```bash
-node "$COMET_STATE" check <change-name> <phase> --recover
+comet state check <change-name> <phase> --recover
 ```
 
 If the check shows the actual phase, workflow, or evidence belongs to another skill, switch according to script output and `/comet` routing rules; do not keep writing state in the wrong phase. If the worktree has uncommitted changes, attribute them first via `comet/reference/dirty-worktree.md`.
@@ -27,7 +27,7 @@ Only `auto_resume` should resume automatically; `ask_user` must ask one short qu
 ## Recovery Steps
 
 ```bash
-node "$COMET_STATE" check <change-name> <phase> --recover
+comet state check <change-name> <phase> --recover
 ```
 
 The script outputs structured recovery context (phase, completed fields, pending fields, recovery action). Follow the **Recovery action** output for next steps.

package/assets/skills/comet/reference/decision-point.md

@@ -4,6 +4,17 @@ Canonical path: `comet/reference/decision-point.md`
 
 This protocol is shared by all comet sub-skills that contain user decision points. Any step labeled as a blocking point or user decision point must follow this protocol.
 
+## First Decide Whether User Input Is Actually Required
+
+Distinguish user decisions, automatic handling, and stop conditions:
+
+- **User decision**: two or more valid options change scope, behavior, accepted risk, or an irreversible outcome; the user must choose
+- **Automatic handling**: exactly one safe next action remains within the request, such as repairing an objective failure, reconciling verifiable state, retrying an idempotent check, or following persisted configuration; execute and report it without manufacturing confirmation
+- **Stop condition**: a missing dependency, corrupt state, path escape, or unavailable external command leaves no valid next action; report the blocker and recovery condition without inventing choices
+- **Manual handoff**: `NEXT: manual` returns control; it is not a new user decision point. Print `HINT`, end the current invocation, and do not ask whether to continue
+
+Only the first category uses this protocol. Merge adjacent choices that can be answered together, and do not re-ask persisted choices that remain valid. Preflight platform capabilities and state before presenting options, and show only executable choices. If a field has only one valid value, explain why and apply it without creating a separate pause.
+
 ## Core Rules
 
 - Decision points are blocking points. Pause and wait for an explicit user choice before continuing

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
@@ -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 openspec/changes/<name>/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.

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

@@ -25,8 +25,8 @@ Ordinary source writes are governed only by the selected change phase. With mult
 | `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.
 
@@ -44,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:
@@ -59,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.
@@ -123,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