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

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

@@ -1,6 +1,6 @@
 ---
 name: comet-any
-description: "Use when the user wants to customize Comet five-phase skills, create a workflow skill, organize an existing skill, or compose skills with Workflow Node / Skill Binding / Output Schema."
+description: "Use only when explicitly invoked as /comet-any or when the user explicitly wants to customize Comet's five-phase workflow or create/upgrade a workflow Skill managed by Comet Creator. Do not use for general Skill authoring, cleanup, or review."
 ---
 
 # Comet Any - Skill Creator

package/assets/skills/comet-any/reference/authored-zone-example.md

@@ -62,21 +62,26 @@ Run `node "$WORKFLOW_STATE" status` to confirm the detected Node. If the script'
 - If workflow state shows a Node as complete but its expected artifacts are missing, treat the Node as incomplete and re-enter it.
 - If the user resumes mid-Node with a different topic, confirm whether to continue the current Node or start a new one.
 
-### Decision Points (must pause)
+### Decision Classification And Decision Points
+
+Classify before acting: a user decision has two or more valid options that change scope, behavior, accepted risk, or an irreversible outcome; a sole safe next action is automatic handling; a missing dependency, corrupt state, or guard failure with no valid continuation is a stop condition; `NEXT: manual` only returns control. Only the first category must pause.
 
 | Situation | Action |
 |-----------|--------|
-| First invocation, no workflow state exists | Initialize state, confirm the topic/scope with the user before starting the first Node |
-| User input is ambiguous between two Nodes | Ask the user which Node they mean; do not guess |
+| First invocation with an unambiguous topic and scope | Initialize state automatically and enter the first Node; do not pause to approve known information |
+| Topic, scope, or target Node has two or more mutually exclusive valid interpretations | Merge them into one question and let the user choose; do not guess |
 | Node requires user approval of output before advancing | Stop after recording evidence; wait for explicit confirmation |
-| Node fails its guard and the cause is unclear | Present the guard output and ask the user how to proceed |
+| Accepting a WARNING/deviation or performing an irreversible publish has a real tradeoff | Show only currently executable options and persist the choice |
+
+When a Node guard fails, inspect evidence and perform the sole safe repair first. If a missing dependency or corrupt state prevents progress, report the stop condition and recovery requirement. Escalate to the decision table only when multiple valid recovery options would change scope or risk.
 
 ### Red Flags
 
 | Agent Thought | Actual Risk |
 |--------------|-------------|
-| "The user mentioned the topic, so research is implicitly confirmed" | Mentioning ≠ confirming. Pause at the first Node boundary and confirm scope. |
+| "Every first invocation needs another confirmation" | Clear input does not need duplicate approval; ask only when mutually exclusive interpretations still change scope. |
 | "The script returned NEXT: auto, so I should immediately load the next Skill" | `NEXT: auto` means the Node is done, not that you should skip confirmation. Check if the next Node has a decision point. |
+| "The guard failed, so ask the user what to do" | Diagnose automatically and apply the sole safe repair first; if no valid action exists, report a stop condition instead of inventing options. |
 | "This looks like the same topic as last time, resume from where we left off" | Always re-read state. Conversation memory is unreliable after context compaction. |
 | "The exit check passed, so the work is good enough" | Exit checks are mechanical. Your job is to judge quality beyond the check — sparse notes, shallow analysis, or missing perspectives are not caught by scripts. |
 ```

package/assets/skills/comet-any/reference/subagents/pause-points-author.md

@@ -4,7 +4,7 @@ This file is a portable lane brief, not a platform-native custom agent. If you n
 
 ## Responsibilities
 
-Design the places where the user must pause and choose, plus cross-device recovery. Pause points must be explicit user choices that cannot be bypassed by default recommendations, historical preferences, or automatic advancement.
+Design only the places where the user genuinely must choose, plus cross-device recovery. First distinguish four categories: user decision, automatic handling, stop condition, and manual handoff. Create a user pause only when two or more valid options change scope, behavior, accepted risk, or an irreversible outcome. Execute a sole safe action directly, report a missing dependency or corrupt state as a stop condition, and return control for a manual handoff. Genuine user decisions cannot be bypassed by defaults, historical preferences, or automatic advancement.
 
 Must cover:
 
@@ -15,11 +15,10 @@ Must cover:
 
 Read the common input from the main session, especially:
 
-- `confirm-generate`, `revise-proposal`, and `cancel` from the Skill Creator confirmation page.
-- Eval workload choice: `skip / quick / full eval`.
-- Human approval before installation.
-- Blockers such as unresolved candidates, ambiguity, capability gaps, and executable disclosures.
-- Runner recovery state and cross-device recovery entry.
+- `confirm-generate`, `revise-proposal`, and `cancel` from the Skill Creator confirmation page: these are user decisions that change the generated result.
+- Eval workload (`skip / quick / full eval`) and human approval before installation: treat them as decisions only when multiple valid options actually remain.
+- Missing or stale eval evidence, unresolved candidates, ambiguity, capability gaps, and executable disclosures: classify each as automatically repairable, a no-path stop condition, or a real decision with multiple recovery choices. Do not turn all blockers into pause points.
+- Runner recovery state and cross-device recovery entry: reuse persisted choices that remain valid instead of asking again on resume.
 
 Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not inherit main-session history; use only this brief, common input, workflow protocol, and existing drafts.
 
@@ -33,21 +32,23 @@ model: <must explicitly specify model>
 prompt:
   You are the pause point author subagent.
   First read this brief, the common input path, workflow protocol path, Skill draft path, and report file path.
-  Start by asking questions: if user choices, blocker recovery, or cross-device state are unclear, return NEEDS_CONTEXT.
-  Do not guess or fill in missing pause points.
+  First classify each candidate as a user decision, automatic handling, stop condition, or manual handoff. If facts needed for classification are missing, return NEEDS_CONTEXT.
+  Do not guess missing choices, and do not disguise automatic repair, guard failure, capability gaps, a sole valid action, or manual handoff as a user pause.
   Only produce decision-points and recovery drafts; do not write Bundle state and do not execute candidate scripts.
   Write the full pause point draft to the report file path and return only a status summary of 15 lines or fewer.
 ```
 
 ## Output Requirements
 
-Return a pause point draft that explains:
+Return a classification table first, then describe genuine user pause points:
 
+- Which category each candidate belongs to and the evidence for that classification.
 - The trigger condition for every pause point.
 - The choices available to the user.
 - Which Node each choice enters.
 - Where pause point evidence is written.
-- During recovery, how to show current Node, blocking reason, suggested next step, and options.
+- How automatic handling advances directly, and how stop conditions report recovery requirements without inventing options.
+- During recovery, how to show the current Node, blocking reason, suggested next step, and real options while reusing persisted choices.
 
 Pause points must fit the current workflow protocol, not merely list original Comet pause points.
 
@@ -56,8 +57,10 @@ Pause points must fit the current workflow protocol, not merely list original Co
 Before returning, check:
 
 - Every user pause point has trigger condition, options, next Node, and evidence location.
+- Every pause has at least two currently executable valid options; adjacent choices that can be answered together are merged, and a sole valid value creates no pause.
+- Guard failures, deterministic retries, state reconciliation, capability gaps, and `NEXT: manual` are classified according to their actual semantics instead of defaulting to user questions.
 - Default recommendations, historical preferences, and automatic advancement cannot bypass required pause points.
-- The recovery summary can show current Node, blocking reason, suggested next step, and options.
+- The recovery summary can show the current Node, blocking reason, suggested next step, and real options without re-asking choices that remain valid.
 - Cross-device recovery does not rely on current-session memory.
 - Pause points fit the current composed Skill instead of copying original Comet pause points.
 

package/assets/skills/comet-any/reference/subagents/skill-reviewer.md

@@ -62,6 +62,8 @@ Any of these must produce blocking findings:
   Node Skill, or a subagent handoff Node does not require the implementation subagent prompt to load that
   Skill.
 - User pause points are missing, or can be bypassed by defaults.
+- Deterministic repair, guard failure, state reconciliation, a capability gap, a sole valid action, or `NEXT: manual` is treated as a user pause by default; or adjacent choices that can be answered together are split into serial confirmations.
+- The entry Skill frontmatter description does not identify it as the managed workflow entry/resume router, or an internal Node Skill description allows ordinary tasks to trigger it without explicit invocation or entry/runtime routing.
 - English Skills mix in Chinese process sentences.
 - Nested Skill calls use provider prefixes.
 - User-visible `SKILL.md` leaks generated audit sections, source hashes, or internal metadata.

package/assets/skills/comet-any/reference/subagents/workflow-entry-author.md

@@ -20,7 +20,7 @@ Quality bar: the `comet/SKILL.md` Decision Core (see `reference/authored-zone-ex
 
 - **Semantic current-Node detection** — how to determine which Node the user is in, beyond just running the script. Model comet's Step 0 (detect intent from user message, check Node order, handle "belongs to earlier/later Node" conflicts) + Step 1 (read state, trust files over stale state).
 - **Resume and drift rules** — what to do when context resumes (re-detect from scratch, never trust conversation history), when state says DONE but artifacts are missing, when the user's topic shifts mid-Node.
-- **Decision points** — explicit table of situations that MUST pause for user confirmation (first invocation scope, ambiguous Node, user approval required, guard failure).
+- **Decision classification and decision points** — first distinguish user decisions, automatic handling, stop conditions, and manual handoffs, then tabulate only genuine user choices. A clear first invocation, an objectively repairable guard failure, a sole valid next action, and `NEXT: manual` must not manufacture confirmation.
 - **Red flags** — the "agent thought → actual risk" pattern that catches self-deception (e.g., "user mentioned the topic so research is confirmed" → mentioning ≠ confirming).
 
 A Decision Core without these four sections is a stub, not a Decision Core. The entry is the most-loaded file — it is what makes the Skill feel intelligent or mechanical.
@@ -49,10 +49,10 @@ model: <must explicitly specify model>
 prompt:
   You are the workflow entry author subagent.
   First read this brief, the common input path, script contract path, workflow protocol path, and report file path.
-  Start by asking questions: if startup routing, recovery paths, current-Node detection, or user pause points are unclear, return NEEDS_CONTEXT.
+  First classify user decisions, automatic handling, stop conditions, and manual handoffs. If startup routing, recovery paths, current-Node detection, or genuine user choices are unclear, return NEEDS_CONTEXT.
   Do not guess or fill in missing flow details.
   Only write the entry SKILL.md draft; do not write internal Node Skills, Bundle state, or execute candidate scripts.
-  The Decision Core MUST include four subsections: ### Automatic Node Detection (Step 0 intent detection + Step 1 state read + resume rules), ### Decision Points (explicit pause table), ### Red Flags (agent thought → actual risk table). A Decision Core without these is a stub.
+  The Decision Core MUST include four subsections: ### Automatic Node Detection (Step 0 intent detection + Step 1 state read + resume rules), ### Decision Classification And Decision Points (genuine user choices only), ### Red Flags (agent thought → actual risk table). Do not list guard failures, deterministic repair, a sole valid action, or manual handoff as a user decision. A Decision Core without these is a stub.
   Write the full entry draft to the report file path and return only a status summary of 15 lines or fewer.
 ```
 
@@ -66,7 +66,7 @@ The entry draft must show:
 - The Node route table is reference only; it must not use "immediately execute" or "must load" execution directives.
 - When users customize existing Comet Skills, the entry must list Required Skill Calls as Node-local obligations,
   not as an immediate execution checklist.
-- User pause points, recovery paths, and reference files are visible.
+- User decisions, automatic handling, stop conditions, manual handoffs, recovery paths, and reference files are visible. Pause only when at least two real valid options remain, and merge adjacent choices.
 - When users customize existing Comet Skills, preserve the open / design / build / verify / archive main path and Guardrails.
 
 Forbidden:
@@ -85,6 +85,7 @@ Before returning, check:
 - The entry has no immediate-load checklist for Node Skills.
 - The Node route is reference, not execution steps.
 - Automatic advancement references script outputs `NEXT:` and `SKILL:`.
+- A clear first invocation initializes directly, guard failures are diagnosed automatically or reported as stop conditions, and `NEXT: manual` only returns control; none is presented as a fabricated user decision.
 - User-visible English prose is consistent and does not mix in Chinese process sentences.
 
 ## Required Claim

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

@@ -1,6 +1,6 @@
 ---
 name: comet-archive
-description: "Use when a Comet change has passed verification and needs archive confirmation, delta spec merge, or archive-phase recovery."
+description: "Use only when explicitly invoked as /comet-archive or routed by the root Comet skill/runtime to the archive phase; confirm archive, merge delta specs, and finish the branch."
 ---
 
 # Comet Phase 5: Archive (Archive)
@@ -8,52 +8,59 @@ description: "Use when a Comet change has passed verification and needs archive
 ## Prerequisites
 
 - Verification passed (Phase 4 complete)
-- Branch handled
+- Archive commit and branch handling are still pending (`branch_status: pending`)
 - `verify_result: pass` in `openspec/changes/<name>/.comet.yaml`
 
 ## Steps
 
 ### 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
 - Verification report path and result
-- Branch handling status
+- Current branch/workspace and attribution summary for pre-existing dirty changes
 - 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,7 @@ The script automatically executes:
 
 If script returns non-zero exit code, report error and stop.
 If script returns zero exit code, archive is complete.
+
 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.
@@ -75,31 +83,57 @@ Spec lifecycle completes here:
 brainstorming → delta spec → implementation → verification → main spec merge → design doc annotation → archive
 ```
 
-### 4. Commit the Archive Changes
+### 4. Commit Archive Changes with Exact Paths
 
 The archive script only moves files and merges the spec; it does not commit. After archiving, the worktree holds these uncommitted changes:
 - The change directory moved from `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`
 - The main spec content merged via delta semantics
 - Archive metadata annotations on the design doc / plan
 
-**You must prompt the user to commit these archive changes**, otherwise the archived result stays in the worktree. After showing the pending files, suggest:
+After archive, read `git status --short` and compare it with the pre-archive dirty-worktree attribution baseline. Stage only paths attributable to this change: the original active path, actual archive path printed by the command, main specs changed by this delta, and archive metadata on this Design Doc/Plan. Stop if any path cannot be attributed.
+
+Use explicit pathspecs, then inspect the staged diff. Never stage the whole repository or mix the user's pre-existing changes into the archive commit:
 
 ```bash
-git add -A
+git add -- <individually verified archive paths...>
+git diff --cached --stat
 git commit -m "chore: archive <change-name>"
 ```
 
-If branch handling (phase 4) chose not to merge into the main branch yet, finish up via the selected option (merge / PR / keep branch) together with this commit.
+Stop if the commit fails or the staged diff contains unrelated paths.
+
+### 5. Handle the Branch After the Archive Commit
+
+After the archive commit succeeds, **immediately execute:** use the Skill tool to load Superpowers `finishing-a-development-branch`. This ordering ensures the final branch or PR contains the main-spec merge and archive metadata.
+
+If the skill is unavailable, stop and prompt the user to enable/install it; do not mark `branch_status` handled. After loading it, pause under `comet/reference/decision-point.md` and let the user choose:
+
+1. Merge locally into the main branch
+2. Push and create a PR
+3. Keep the current branch for later
+
+Archive is already complete, so do not offer "discard work". Only after the selected operation succeeds (or the user explicitly keeps the branch), run:
+
+```bash
+comet state set <change-name> branch_status handled
+comet guard <change-name> archive
+comet state clear-selection
+```
+
+The archive guard must verify both archive completeness and `branch_status: handled`; a failure means the workflow is still incomplete.
 
 ## Exit Conditions
 
 - Archive script executed successfully (exit code 0)
 - Archive directory `openspec/changes/archive/YYYY-MM-DD-<change-name>/` exists
 - Archived `.comet.yaml` contains `archived: true`
+- Archive changes were committed with exact pathspecs
+- The user's branch decision completed and archived state has `branch_status: handled`
+- `comet guard <change-name> archive` passes
 
 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.
+`comet guard <change-name> archive` resolves the actual archive directory from the original change name; do not construct a dated archive path manually.
 
 ## Complete
 

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

@@ -1,6 +1,6 @@
 ---
 name: comet-build
-description: "Use when a full Comet change has completed design and needs an implementation plan, execution-mode selection, or resumed build tasks."
+description: "Use only when explicitly invoked as /comet-build or routed by the root Comet skill/runtime to a full workflow build phase; create or recover the implementation plan and execute tasks."
 ---
 
 # Comet Phase 3: Plan and Build (Build)
@@ -14,25 +14,26 @@ 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.
 
-**Idempotency**: All build phase operations can be safely re-executed. Read `.comet.yaml` `phase` field to confirm still in build, read plan header `base-ref`, then use `grep -n '\- \[ \]' tasks.md | head -1` to find the first unchecked task. Already-committed tasks must not be re-committed.
+**Idempotency**: All build phase operations can be safely re-executed. Read `.comet.yaml` `phase` to confirm build, read the plan header `base-ref`, then parse tasks.md checkboxes in document order and resume from the first unchecked task. Already-committed tasks must not be re-committed.
 
 ### 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
@@ -64,50 +65,52 @@ After the subagent completes:
 - If a valid file path is returned and the file exists, record it as the plan
 - If the subagent fails or returns an invalid path, fall back to loading the Superpowers `writing-plans` skill inline in the main session (degraded fallback)
 
-### 2. Update Plan Status and Provide Plan-Ready Pause Point
+### 2. Update Plan Status and Jointly Confirm Workflow Configuration
 
 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.
 
-After the plan is recorded, immediately provide a new user decision point:
+Check current platform capabilities before presenting the joint decision: verify whether `using-git-worktrees` is available, whether a real background subagent/Task/multi-agent dispatcher exists, and whether the repository can safely create a branch. Show only isolation and execution options that are currently executable. If a field has only one valid value, explain why and apply it without manufacturing another pause.
+
+After recording the plan, provide exactly **one joint decision point** that collects whether to continue now, available workspace isolation, available execution method, TDD mode, and code review mode. The branch name must be confirmed in the same Step 2 joint decision when `branch` is selected. Do not ask continue/pause first and then create another configuration or naming blocker.
 
 | Option | Behavior | Description |
 |--------|----------|-------------|
-| A | Continue execution | Stay in the current model and proceed to Step 3 to choose workspace isolation, execution method, TDD mode, and code review mode |
+| A | Continue with configuration | Provide all Step 3 isolation, execution, TDD, and review choices in the same response; include the branch name when branch is selected |
 | B | Pause to switch model | Record `build_pause: plan-ready`, stop this `/comet-build` invocation, and allow the user to resume later from `/comet` or `/comet-build` |
 
-This is a user decision point. **Must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to explicitly choose**. Must not auto-continue and must not write the pause into `build_mode`.
+This is a user decision point. **Follow `comet/reference/decision-point.md` once and show the plan summary, pause option, and every executable Step 3 setting together**. Continuing requires all settings and any conditional branch name in the same response. Do not auto-select or write the pause into `build_mode`.
 
-When the user chooses to continue:
+When the user chooses to continue and supplies complete configuration:
 
 ```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.
 
-### 3. Select Workflow Configuration
+### 3. Apply the Confirmed Workflow Configuration
 
-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:
+If resuming with `build_pause: plan-ready` and the `plan` file exists, do not rerun `writing-plans`. Reissue the same joint Step 2 decision and clear the pause only after the user supplies complete configuration:
 
 ```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.
+Then apply the workspace isolation, execution method, TDD mode, and code review mode below.
 
-Plan has been written to the current branch. Before starting execution, **ask the user to choose workspace isolation, execution method, TDD mode, and code review mode in a single interaction**:
+The plan is on the current branch. These settings are all part of the single Step 2 decision:
 
 **Workspace Isolation**:
 
@@ -132,26 +135,26 @@ Plan has been written to the current branch. Before starting execution, **ask th
 - Task count ≤ 2 and no cross-module dependencies → Recommend B
 - From hotfix path → Recommend B
 
-This is a user decision point. **Must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to explicitly choose isolation method, execution method, TDD mode, and code review mode**. Must not choose `branch` or `worktree` based on recommendation rules, and must not choose the execution method, TDD mode, or code review mode based on recommendation rules. Recommendation rules are for suggestion only, not a substitute for user confirmation.
+These tables are part of the Step 2 joint decision and do not create another pause. First remove options that capability preflight found unavailable. When multiple valid options remain, do not choose `branch` or `worktree`, execution method, TDD mode, or review mode from recommendations. Recommendations explain a preference; they never replace user confirmation.
 
 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 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
+- 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, do not show or write `build_mode: subagent-driven-development`. If recovered state already records that mode but capability is unavailable, return to the same Step 2 joint decision with only executable modes; do not create a separate "switch to executing-plans" pause
 
 **TDD Mode**:
 
 | Option | Meaning | Applicable Scenario |
 |--------|---------|---------------------|
 | `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` |
+| `direct` | Implementation-first, no per-task Red-Green-Refactor requirement | Still requires relevant tests and bug-regression evidence; 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,39 +164,39 @@ 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.
 
 **Execute isolation**:
 
-- **branch**: Recommend a branch name based on the workflow type and current date, then let the user confirm or input a custom name. This is a user decision point — **must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm or override the branch name**. Must not skip this step and create the branch directly.
+- **branch**: Use the branch name already confirmed in Step 2; do not pause again. If legacy recovery no longer has the branch name from that joint decision, re-enter the same Step 2 decision instead of creating a separate branch-naming decision.
 
   Branch naming convention:
   - Read the `workflow` field from `.comet.yaml` to determine the prefix
   - `workflow: full` → recommend `feature/YYYYMMDD/<change-name>`
   - `workflow: hotfix` → recommend `hotfix/YYYYMMDD/<change-name>`
   - `workflow: tweak` → recommend `tweak/YYYYMMDD/<change-name>`
-  - Date is derived from `date +%Y%m%d` at runtime
+  - Format the current runtime date as `YYYYMMDD`; do not depend on one shell's date command
 
   Example: if change name is `fix-login-bug` and today is 2026-06-09, recommend `feature/20260609/fix-login-bug`
 
-  After the user confirms or provides a custom branch name, run `git checkout -b <branch-name>`, subsequent work on the new branch.
+  Immediately after Step 2 confirms the branch name, run `git checkout -b <branch-name>` and continue on the new branch.
 
 - **worktree**: Must use the Skill tool to load the Superpowers `using-git-worktrees` skill to create isolated workspace. Do not bypass this skill with plain shell commands or native tools; if the skill is unavailable, stop the process and prompt to install or enable Superpowers skills.
 
@@ -204,11 +207,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 execution preflight finds that background dispatch capability has disappeared, do not execute directly in the main window and do not create a new second decision. Return to the same Step 2 joint decision with the unavailable mode removed. After the user selects main-window execution there, run `comet state set <name> build_mode executing-plans`, then continue through that branch.
 
 **TDD Mode Execution Constraints**:
 
@@ -227,8 +238,8 @@ 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`
-- 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
+- the `requesting-code-review` skill must be loaded before `comet guard <change-name> build --apply`
+- if `requesting-code-review` is unavailable under `standard` or `thorough`, stop and ask the user to install/enable it and retry, or explicitly switch to `review_mode: off` with a recorded reason; never skip the gate or continue guard before that explicit switch
 - 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
 
@@ -266,7 +277,7 @@ When creating an independent change, must invoke `/comet-open`, not `/opsx:new`
 
 Build is the longest phase and may span many tasks. To support resume after context compaction:
 
-- **After each task**: complete acceptance per the current execution branch and `review_mode` before checking off and committing. `subagent-driven-development` dispatches no per-task reviewer under `off`; under `standard`, a per-task reviewer fires only when the task hits a risk signal; under `thorough`, every task gets a per-task reviewer. All modes must perform targeted verification by unique task text. Use `grep -c '\- \[ \]' tasks.md` to check remaining unchecked count; no need to re-read the entire file
+- **After each task**: complete acceptance per the current execution branch and `review_mode` before checking off and committing. `subagent-driven-development` dispatches no per-task reviewer under `off`; under `standard`, a per-task reviewer fires only when the task hits a risk signal; under `thorough`, every task gets a per-task reviewer. All modes must perform targeted verification by unique task text. Parse tasks.md checkboxes to count remaining work without rereading unrelated task bodies
 - **Context compression recovery**: Follow `comet/reference/context-recovery.md` with phase set to `build`.
 - **User manual-change resume**: handle uncommitted changes through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions. Build-specific handling:
   1. After attribution, if the diff implies plan or spec changes, handle it through Step 4 "Spec Incremental Updates"
@@ -282,14 +293,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,9 +318,9 @@ 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
-- `NEXT: manual` → do not invoke the next skill; prompt user to run `/<SKILL>` manually
+- `NEXT: manual` → do not invoke the next skill; return control with `HINT`, end the invocation, and do not create another confirmation point
 - `NEXT: done` → workflow is complete, no further action needed