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

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,7 +8,7 @@ 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
@@ -35,7 +35,7 @@ After entry verification passes, **must follow the `comet/reference/decision-poi
 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:
@@ -70,11 +70,6 @@ The script automatically executes:
 If script returns non-zero exit code, report error and stop.
 If script returns zero exit code, archive is complete.
 
-After a successful archive, clear the current execution context; this command is idempotent:
-
-```bash
-comet state clear-selection
-```
 The summary `X/Y steps succeeded` counts real executed steps and does not double-count delta spec sync or document annotation.
 
 The script calls OpenSpec archive to merge `ADDED/MODIFIED/REMOVED/RENAMED` delta semantics into main specs, then verifies main specs do not contain delta-only section headings.
@@ -88,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** `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)
@@ -23,7 +23,7 @@ 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)
 
@@ -65,7 +65,7 @@ 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:
 
@@ -75,16 +75,18 @@ 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
 comet state set <name> build_pause null
@@ -98,17 +100,17 @@ 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
 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**:
 
@@ -133,7 +135,7 @@ 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:
 
@@ -143,14 +145,14 @@ comet state set <name> isolation <branch|worktree>
 
 - If the user chooses `executing-plans`: run `comet state set <name> subagent_dispatch null`, then run `comet state set <name> build_mode executing-plans`
 - If the user chooses `subagent-driven-development`: first confirm the current platform has real background subagent / Task / multi-agent dispatch capability; after confirming, run `comet state set <name> subagent_dispatch confirmed`, then run `comet state set <name> build_mode subagent-driven-development`
-- If real background dispatch capability cannot be confirmed, must not write `build_mode: subagent-driven-development`; must pause and wait for the user to choose `executing-plans` instead
+- 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 `comet state set <name> tdd_mode <tdd|direct>`
 
@@ -183,18 +185,18 @@ Without `direct_override: true`, `build_mode=direct` in full workflow is blocked
 
 **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.
 
@@ -217,7 +219,7 @@ Do not begin source writes until this binding succeeds.
 
 - `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 `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**:
 
@@ -237,7 +239,7 @@ Under `executing-plans`, the main session executes tasks directly (no isolated i
 
 Requirements (apply to `standard` and `thorough`):
 - the `requesting-code-review` skill must be loaded before `comet guard <change-name> build --apply`
-- if `requesting-code-review` skill is unavailable, skip the review gate but must record `<!-- review skipped: skill unavailable -->` in tasks.md, then continue guard transition
+- 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
 
@@ -275,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"
@@ -320,5 +322,5 @@ 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

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

@@ -1,6 +1,6 @@
 ---
 name: comet-design
-description: "Use when a full Comet change has completed open but lacks a Superpowers Design Doc, or design must resume from an OpenSpec handoff package."
+description: "Use only when explicitly invoked as /comet-design or routed by the root Comet skill/runtime to a full workflow design phase; create or recover the deep technical Design Doc."
 ---
 
 # Comet Phase 2: Deep Design (Design)
@@ -20,7 +20,7 @@ Locate scripts via `comet/reference/scripts.md`, then run entry verification. Wh
 
 ```bash
 comet state select <change-name>
-node "$COMET_STATE" check <name> design
+comet state check <name> design
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -32,7 +32,7 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 **Must be generated by script. Agent writing summaries on the fly is not allowed.**
 
 ```bash
-node "$COMET_HANDOFF" <change-name> design --write
+comet handoff <change-name> design --write
 ```
 
 The script reads the change `.comet.yaml` `context_compression` snapshot, then generates and records the matching handoff package.
@@ -71,7 +71,7 @@ The beta handoff package is a **structured spec projection** that reduces OpenSp
 If full context is genuinely needed, explicitly run:
 
 ```bash
-node "$COMET_HANDOFF" <change-name> design --write --full
+comet handoff <change-name> design --write --full
 ```
 
 Handoff package sources come from OpenSpec open phase artifacts:
@@ -87,7 +87,7 @@ Handoff package sources come from OpenSpec open phase artifacts:
 When loading the skill, ARGUMENTS must include:
 
 ```text
-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`
 ```
 
 After the skill loads, follow its guidance and use the following context:
@@ -146,9 +146,7 @@ Only after the user explicitly confirms, proceed to Step 2. If the user requests
 
 After the user confirms the design proposal, before creating the Design Doc, create or update the incrementally maintained checkpoint file and finalize it as the confirmed design summary:
 
-```bash
-mkdir -p openspec/changes/<name>/.comet/handoff
-```
+Use the current platform's file API to ensure `openspec/changes/<name>/.comet/handoff/` exists; do not rely on a POSIX-only directory command.
 
 `openspec/changes/<name>/.comet/handoff/brainstorm-summary.md` structure:
 
@@ -180,14 +178,9 @@ mkdir -p openspec/changes/<name>/.comet/handoff
 - `openspec/changes/<name>/.comet/handoff/design-context.md` (or `spec-context.md` in beta mode)
 - `openspec/changes/<name>/.comet/handoff/design-context.json` (or `spec-context.json` in beta mode)
 
-### 1e. Active Context Compaction Gate
-
-After Step 1d completes and `brainstorm-summary.md` is written, enter the active compaction gate before creating the Design Doc. At this point the OpenSpec handoff, brainstorming decisions, and pending items are durable, so the agent should proactively release the earlier Spec and brainstorming context to preserve window space for Step 2 and the later Build phase.
+### 1e. Compaction Policy (Non-blocking Here)
 
-Rules:
-- If the current platform provides a native context compaction/cleanup mechanism (for example, the host agent's compact/compaction command, tool, or UI action), trigger active compaction here once; do not try to fake compaction through a shell script.
-- The compaction resume prompt must include the change name, current step (Design Step 2), and the three handoff file categories listed above.
-- If the current platform cannot be compacted programmatically by the agent, pause and tell the user to run the host platform's manual compaction action; continue to Step 2 only after the user confirms compaction is unavailable or asks to continue.
+`brainstorm-summary.md` is a recovery checkpoint, but do not discard live design context before the Design Doc is persisted. Continue directly to Step 2. Active compaction moves until after the Design Doc, state, and latest handoff are all durable.
 
 ### 2. Create Design Doc
 
@@ -214,17 +207,25 @@ First record the design_doc path. If Spec Patches wrote back delta spec (added o
 
 ```bash
 # Record design_doc path
-node "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+comet state set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
 # If delta spec changes exist, regenerate handoff (update hash)
-node "$COMET_HANDOFF" <change-name> design --write
+comet handoff <change-name> design --write
 
 # Auto-transition to next phase
-node "$COMET_GUARD" <change-name> design --apply
+comet guard <change-name> design --apply
 ```
 
 If there are no delta spec changes, skip the handoff regeneration step. The state file updates automatically; no manual editing of other fields needed.
 
+### 3a. Optional Active Context Compaction
+
+Consider active compaction only **after the Design Doc and state evidence are persisted** and before Build. First confirm `design_doc`, the latest handoff, `handoff_hash`, and the design guard are durable so recovery never depends on an unwritten design judgment.
+
+- If the host exposes a programmatically callable native compaction mechanism and the context window is under pressure, invoke it once and include the change, next step, Design Doc, and handoff files in the resume prompt
+- If only the user can trigger compaction, give one non-blocking suggestion and continue; it **must not block when programmatic compaction is unavailable** and must not create another confirmation point
+- Never fake host compaction with a shell command or an agent summary
+
 ## Exit Conditions
 
 - Design Doc created and saved
@@ -235,12 +236,12 @@ If there are no delta spec changes, skip the handoff regeneration step. The stat
 - In beta mode, `spec-context.json` must be structurally valid and reference the current source files (enforced by guard)
 - If new capabilities or supplementary acceptance scenarios exist, OpenSpec delta spec has been created/updated
 - `design_doc` written to `.comet.yaml`
-- **Phase guard**: Run `node "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
+- **Phase guard**: Run `comet guard <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
 
 Must use `--apply` before exit:
 
 ```bash
-node "$COMET_GUARD" <change-name> design --apply
+comet guard <change-name> design --apply
 ```
 
 ## Context Compression Recovery
@@ -252,9 +253,9 @@ Follow `comet/reference/context-recovery.md` with phase set to `design`.
 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