@rpamis/comet 0.3.9 → 0.4.0-beta.2

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

@@ -0,0 +1,69 @@
+# Script Location and Commands
+
+Canonical path: `comet/reference/scripts.md`
+
+This file is the single source of truth for locating Comet scripts and the state/guard/handoff/archive command surface. Load it once per session, then reuse the cached env vars.
+
+## Bootstrap (run once per session)
+
+Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars. Sub-skills may reference this section directly and only inline this block when they must be fully self-contained; this file is the single source of truth for updates:
+
+```bash
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.mjs' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.mjs not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+COMET_SCRIPTS_DIR="$(node "$COMET_ENV")"
+COMET_STATE="$COMET_SCRIPTS_DIR/comet-state.mjs"
+COMET_GUARD="$COMET_SCRIPTS_DIR/comet-guard.mjs"
+COMET_HANDOFF="$COMET_SCRIPTS_DIR/comet-handoff.mjs"
+COMET_ARCHIVE="$COMET_SCRIPTS_DIR/comet-archive.mjs"
+COMET_INTENT="$COMET_SCRIPTS_DIR/comet-intent.mjs"
+
+# Stop workflow when script location fails
+if [ -z "$COMET_SCRIPTS_DIR" ]; then
+  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+```
+
+After loading comet, agents should run this bootstrap block once, then reuse `$COMET_GUARD`, `$COMET_STATE`, `$COMET_HANDOFF`, `$COMET_ARCHIVE`, and `$COMET_INTENT` throughout the session.
+
+## Auto state update
+
+Guard supports `--apply` flag, automatically updating `.comet.yaml` state fields after checks pass:
+
+```bash
+node "$COMET_GUARD" <change-name> <phase> --apply
+```
+
+`--apply` delegates to `comet-state transition`. Use these semantic events when state changes need to be expressed directly:
+
+```bash
+node "$COMET_STATE" transition <change-name> open-complete
+node "$COMET_STATE" transition <change-name> design-complete
+node "$COMET_STATE" transition <change-name> build-complete
+node "$COMET_STATE" transition <change-name> verify-pass
+node "$COMET_STATE" transition <change-name> verify-fail
+```
+
+Archive completion is handled by `node "$COMET_ARCHIVE" <change-name>` after OpenSpec moves the change into its date-prefixed archive directory; do not manually transition an `<archive-name>`.
+
+## Resolve next action
+
+After guard-based phase advancement, use the `next` subcommand to determine whether to auto-invoke the next skill:
+
+```bash
+node "$COMET_STATE" next <change-name>
+```
+
+Output format: `NEXT: auto|manual|done` + `SKILL: <skill-name>` (omitted for `done`) + `HINT` (for `manual` only). With `auto_transition: false`, output is `manual`, which pauses only the next skill invocation and does not block phase updates.
+
+## Archive script
+
+Complete all archive steps in one command:
+
+```bash
+node "$COMET_ARCHIVE" <change-name>
+```

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

@@ -2,14 +2,14 @@
 
 Canonical path: `comet/reference/subagent-dispatch.md`
 
-This document provides Comet-specific extensions applied **on top of** the Superpowers `subagent-driven-development` skill. The skill handles the core dispatch loop (fresh implementer per task → spec compliance review → code quality review → next task) and enforces continuous execution. This document adds Comet-specific real background dispatch, task tracking, state verification, and context recovery. If the Superpowers skill conflicts with this document, the more specific Comet constraints here take precedence.
+This document provides Comet-specific extensions applied **on top of** the Superpowers `subagent-driven-development` skill. The Superpowers `subagent-driven-development` skill provides the base continuous dispatch loop (a fresh implementer for each task, including the default task reviewer node) and enforces continuous execution. This document adds Comet-specific real background dispatch, task tracking, state verification, context recovery, and review/fix budgets; Comet's `review_mode` takes over the reviewer stage to decide which tasks need reviewers, how many fix rounds are allowed, and which final review runs. If the Superpowers skill conflicts with this document, the more specific Comet constraints here take precedence.
 
 > **⚠️ CRITICAL — No Pause Between Tasks**
 >
-> After a task passes both reviews and is checked off, **immediately dispatch the next task** without stopping, summarizing, or asking the user whether to continue. The user expects all tasks to execute in sequence without manual intervention. Pausing between tasks breaks the workflow and requires the user to manually resume each time.
+> After a task passes `review_mode` validation and is checked off, **immediately dispatch the next task** without stopping, summarizing, or asking the user whether to continue. The user expects all tasks to execute in sequence without manual intervention. Pausing between tasks breaks the workflow and requires the user to manually resume each time.
 >
 > Only stop and wait for user input when:
-> - A task is **BLOCKED** (3 review-fix rounds exhausted)
+> - 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
@@ -18,9 +18,10 @@ This document provides Comet-specific extensions applied **on top of** the Super
 
 ## Before Starting
 
-1. Read the plan once, extracting the full text of all unchecked tasks in order.
-2. Save a unique identifier for each task: the full task text after the checkbox in the plan, and the full OpenSpec task text it maps to (if any). If the text is not unique, stop and fix the plan first; never rely on "first match."
-3. Respect dependencies; do not dispatch a task whose dependencies are not yet complete.
+1. Before dispatching the first task, complete the Superpowers `subagent-driven-development` skill pre-flight plan review: scan the plan and global constraints for contradictions or plan-mandated defects a reviewer would flag. If found, ask one batched question with the conflicting plan text before implementation starts; if clean, proceed without ceremony.
+2. Read the plan once, extracting the full text of all unchecked tasks in order.
+3. Save a unique identifier for each task: the full task text after the checkbox in the plan, and the full OpenSpec task text it maps to (if any). If the text is not unique, stop and fix the plan first; never rely on "first match."
+4. Respect dependencies; do not dispatch a task whose dependencies are not yet complete.
 
 ## Per-Task Comet Extensions
 
@@ -28,9 +29,9 @@ Apply these on every task, in addition to the Superpowers skill's dispatch loop:
 
 ### 0. Dispatch Enforcement (Critical)
 
-The main session is the **coordinator only** and must NOT execute tasks directly or modify source code. The coordinator may modify only the plan, OpenSpec task, and subagent progress checkpoint for durable tracking. Never bundle multiple tasks into one agent. Dispatch a fresh background implementer agent for every task; spec reviewers, code quality reviewers, fix agents, and the final reviewer must also each use a fresh background agent:
+The main session is the **coordinator only** and must NOT execute tasks directly or modify source code. The coordinator may modify only the plan, OpenSpec task, and subagent progress checkpoint for durable tracking. Never bundle multiple tasks into one agent. Dispatch a fresh background implementer agent for every task; when `review_mode` requires review or fixes, the task reviewer, fix agents, and the final reviewer must also each use a fresh background agent:
 
-- **Claude Code**: Use the `Agent` tool with `run_in_background: true` for each implementer, spec reviewer, code quality reviewer, fix agent, and final reviewer. Never execute tasks inline and do not accidentally enter team mode, which requires a pre-created team.
+- **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`.
@@ -40,14 +41,40 @@ The main session is the **coordinator only** and must NOT execute tasks directly
 Every implementer or fix-agent prompt must include:
 
 - The full text of the single current task, architecture background, and dependency context
-- `Language: Use the language of the user request that triggered this workflow`
+- `Language: Use the configured Comet artifact language from "$COMET_BASH" "$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
 
-The agent return status must be `DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT` and include implementation details, test results, commit hash, changed files, and concerns. Before review, the coordinator must verify that the commit and changed files are visible in the current worktree; on isolated-copy platforms, pull or merge the changes first.
+Large task text, implementation reports, and review material must move through the file-handoff mechanism exposed by the loaded Superpowers `subagent-driven-development` skill, not be pasted wholesale into the main session. The dispatch prompt should point agents to those handoff artifacts while still naming the role, allowed scope, required tests, report contract, and any Comet-specific constraints. Comet may record returned artifact paths or short summaries for recovery, but must not depend on the internal names or directory layout of those artifacts.
 
-Every reviewer prompt must include the full task, the implementation commit or diff and the RED/GREEN evidence (when `tdd_mode: tdd`). A reviewer must not review from the implementer's summary alone.
+The agent return status must be `DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT` and include or point to implementation details, test results, commit hash, changed files, and concerns. **The implementer/fix agent must also report whether this task hits any risk signal** (see the list below); if so, list each one hit. This is the first signal source for whether a per-task reviewer is dispatched under `review_mode: standard`. Before review, the coordinator must verify that the commit and changed files are visible in the current worktree; on isolated-copy platforms, pull or merge the changes first.
+
+**Risk signal list** (hitting any one marks the task as a risk task):
+
+- Cross-module / cross-subsystem coordinated change
+- Security-sensitive surface: auth, authorization, crypto, SQL, external input handling, secrets/credentials
+- Concurrency, locks, shared mutable state
+- Data or schema migration
+- Public API contract or external interface change
+- Implementer returns `DONE_WITH_CONCERNS`
+- Single-task diff exceeds 200 lines
+
+When `review_mode` requires a reviewer, each reviewer prompt must include or point to the full task requirements, the implementation commit or diff, and the RED/GREEN evidence (when `tdd_mode: tdd`). A reviewer must not review from the implementer's summary alone.
+
+Reviewer prompts must stay neutral:
+
+- Do not ask a reviewer to re-run the same tests the implementer already ran and reported; the reviewer verifies the reported evidence and the code/diff.
+- Do not pre-judge, suppress, or down-rank findings in the reviewer prompt. If a likely finding conflicts with the plan, let the reviewer report it, then ask the user which requirement governs.
+- Do not paste accumulated prior-task history into later dispatches. Give only the current task, the relevant interfaces/constraints, and the handoff artifacts exposed by the loaded Superpowers `subagent-driven-development` skill.
+
+**Model selection (mandatory)**: Every dispatch must specify the model explicitly. An omitted model silently inherits the session's most expensive model, slowing execution and raising cost. Follow the Superpowers `subagent-driven-development` Model Selection rules:
+
+- **Implementer / fix agent**: prose-described implementation work uses at least the standard tier; multi-file integration, pattern matching, or debugging → standard tier; requires design judgment or broad codebase understanding → most capable tier. Use the cheapest tier only when the plan text already contains the complete code to write (transcription + testing) or for a single-file mechanical fix.
+- **Reviewer (task-level / final)**: scale to the diff's size, complexity, and risk. A small mechanical diff does not need the most capable model; a subtle concurrency change does.
+- **Final whole-branch review**: use the most capable available model, not the session default.
+
+Omitting the model equals letting it run the session's most expensive model — directly defeating this section's goal.
 
 ### 2. Implementer Scope Restriction
 
@@ -61,27 +88,53 @@ If `tdd_mode: tdd`, every implementer and fix agent must first use the Skill too
 You MUST follow TDD: write a failing test first, watch it fail, then write minimal code to pass. No production code without a failing test first.
 ```
 
-The implementer or fix-agent return must provide **RED failure command and failure summary**, **GREEN pass command and pass summary**; missing either piece of evidence blocks entry into review. Both spec compliance reviewer and code quality reviewer must verify RED/GREEN evidence and test coverage.
+The implementer or fix-agent return must provide **RED failure command and failure summary**, **GREEN pass command and pass summary**; missing either piece of evidence blocks entry into review. When `review_mode` requires a task reviewer, that reviewer must verify RED/GREEN evidence and test coverage while checking both spec compliance and code quality.
 
 ### 4. Durable Progress Checkpoint
 
 The coordinator must maintain `openspec/changes/<name>/.comet/subagent-progress.md` and update it immediately after every dispatch, agent return, review result, review-fix round change, and task checkoff. The checkpoint must record at least:
 
 - The unique current plan task text and mapped OpenSpec task text
-- Current stage: `implementing | spec-review | quality-review | checkoff | done | blocked | final-review | final-fix`
+- Current stage: `implementing | task-review | checkoff | done | blocked | final-review | final-fix`
 - Implementation commit hash, changed files, and RED/GREEN evidence
+- The selected `review_mode`
 - Review stages already passed and unresolved reviewer feedback
-- The current task or final-review review-fix round (maximum 3)
+- The current task or final-review review-fix round (`standard`: max 1, `thorough`: max 2, `off`: 0)
+- Under `review_mode: standard`, whether this task has already triggered a risk task-level review and which risk signals it hit (on recovery, do not re-dispatch an already-completed task-level review)
 
 This file stores only coordinator recovery state and does not replace plan or OpenSpec checkboxes. Retain the final record when a task completes, then replace it with the next task's record when that task begins.
 
-### 5. Review-Fix Round Limit
+Comet does not read, write, or require any Superpowers `subagent-driven-development` internal scripts or workspace paths. If the installed Superpowers `subagent-driven-development` skill maintains its own scratch artifacts, review material, task requirement files, or progress records, those remain owned by Superpowers. Comet's durable source of truth is limited to Comet workflow state, the plan/OpenSpec checkboxes, and this coordinator checkpoint.
+
+### 5. Review Mode Behavior
+
+> **⚠️ CRITICAL — review_mode takes over the Superpowers default flow, no double review**
+>
+> The Superpowers `subagent-driven-development` Process flowchart makes "dispatch a task reviewer after every task" a mandatory node. **Comet's `review_mode` takes over this stage, deciding which tasks get a per-task reviewer** (see the per-task reviewer column in the table below). **Do not dispatch additional reviewers beyond what `review_mode` prescribes.** Tasks that do not get a reviewer (`off`: all; `standard`: non-risk tasks) must go straight to task checkoff and dispatch of the next task.
+>
+> The total review count for a change is decided solely by the table below — do not add more.
+
+**Build-phase review budget** (these only — do not add more). This table covers the build phase only; the verify phase has its own review handling (see note below):
+
+| `review_mode` | per-task reviewer (build) | final review (build) |
+|---------------|---------------------------|----------------------|
+| `off` | 0 | 0 |
+| `standard` | risk tasks only (see rules below) | 1 (lightweight) |
+| `thorough` | every task (spec + quality) | 1 (complete) |
+
+**Verify-phase review is not in this table.** The verify phase's review is driven by `verify_mode` (light/full), with `review_mode` only gating whether automatic code review fires at all (`off` skips it; `standard`/`thorough` run a lightweight code review under lightweight verification, or rely on `openspec-verify-change` under full verification). There is no separate per-`review_mode` "complete" code review in verify — see `comet-verify` for the authoritative verify-phase behavior.
+
+**When `review_mode: standard`**: By default no per-task reviewer is dispatched; instead, a **risk trigger** decides: after the implementer self-tests, commits, and reports evidence (including the risk-signal self-report), the coordinator reads the self-report and reviews the task's diff. **Only when the implementer's self-report hits any risk signal, or the coordinator's diff review finds any risk signal**, dispatch one per-task reviewer for that task, checking both spec compliance and code quality; CRITICAL/IMPORTANT findings enter one review-fix round (max 1), and a failed re-review marks it **BLOCKED**. Tasks that hit no risk signal go straight through targeted checkoff verification. After all tasks complete, still dispatch one final lightweight code reviewer (scope: correctness, security, edge cases). If the final lightweight review finds CRITICAL or IMPORTANT issues, dispatch at most one fix agent and re-review once; if still not passed, mark **BLOCKED** and pause, handing feedback to the user. Non-CRITICAL findings may be accepted with rationale recorded.
+
+**When `review_mode: thorough`**: **Dispatch one per-task reviewer per task, checking both spec compliance and code quality**: after the implementer self-tests, commits, and reports evidence, the coordinator dispatches a fresh background reviewer for that task. CRITICAL/IMPORTANT findings enter review-fix (max 2 rounds); if still not passed, mark **BLOCKED** and pause, handing feedback to the user. After all tasks, dispatch one final complete reviewer. Thorough does not run batched review — a high-risk change demands immediate, focused review on every task; deferring to a batch boundary to catch issues is too costly.
+
+When a reviewer returns an item that cannot be verified from review material alone, the coordinator must resolve it before task checkoff. If direct repository inspection confirms a real gap, treat it as a failed spec/quality review and send it through the appropriate fix and re-review loop. If it is satisfied by unchanged code or a cross-task constraint, record the rationale in the checkpoint and continue.
 
-Each task allows at most 3 review-fix rounds. When either reviewer finds an issue, dispatch a fresh background fix agent and restart from the corresponding review. If the task still does not pass after 3 rounds, mark it **BLOCKED**, pause, and hand the accumulated feedback to the user.
+**When `review_mode: off`**: No automatic task reviewer, final reviewer, or review-fix agent is dispatched. Task completion is determined by implementer test/build evidence, current worktree confirmation, targeted task text checkoff verification, and explicit user request. If test failures, build failures, or abnormal behavior occur during execution, the debug gate protocol must still be followed - `off` does not skip real issues.
 
 ### 6. Task Checkoff and Verification
 
-**After both reviews pass**, the main session:
+**After `review_mode` validation**, the main session:
 
 1. Changes the saved unique task text from `- [ ]` to `- [x]` in the plan
 2. If a mapping exists, also checks off the OpenSpec task
@@ -89,25 +142,28 @@ Each task allows at most 3 review-fix rounds. When either reviewer finds an issu
 4. Runs targeted verification:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" task-checkoff "$PLAN_FILE" "$PLAN_TASK_TEXT"
-"$COMET_BASH" "$COMET_STATE" task-checkoff "openspec/changes/<name>/tasks.md" "$OPENSPEC_TASK_TEXT"
+node "$COMET_STATE" task-checkoff "$PLAN_FILE" "$PLAN_TASK_TEXT"
+node "$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.
 
 ## Wrap-up
 
-- **AUTO-CONTINUE**: After both reviews pass and the task is checked off, immediately dispatch the next unchecked task. Do NOT summarize, do NOT ask the user whether to continue, do NOT wait for user input between tasks. This is non-negotiable — the Superpowers skill enforces continuous execution, and the CRITICAL warning at the top of this document reinforces it.
-- After all tasks complete, switch the checkpoint to `final-review`, then dispatch a fresh background final code quality reviewer. For CRITICAL issues, switch the checkpoint to `final-fix`, record feedback and the round, dispatch a fresh background fix agent, and re-review. Final review also has a maximum of 3 rounds; when exhausted, mark the checkpoint `blocked` and pause. Non-CRITICAL findings may be accepted with rationale recorded in tasks.md.
+- **AUTO-CONTINUE**: After `review_mode` validation and the task is checked off, immediately dispatch the next unchecked task. Do NOT summarize, do NOT ask the user whether to continue, do NOT wait for user input between tasks. This is non-negotiable — the Superpowers skill enforces continuous execution, and the CRITICAL warning at the top of this document reinforces it.
+- After all tasks complete, if `review_mode: standard`, switch the checkpoint to `final-review` and dispatch exactly one final lightweight code reviewer. CRITICAL or IMPORTANT issues allow at most one auto-fix and re-review; if still not passed, pause and hand to the user. After passing or accepting non-CRITICAL findings, continue to return to `comet-build`.
+- After all tasks complete, if `review_mode: thorough`, switch the checkpoint to `final-review` and dispatch one final complete reviewer. CRITICAL or IMPORTANT issues allow at most two auto-fix and re-review rounds; if still not passed, pause and hand to the user. After passing or accepting non-CRITICAL findings, continue to return to `comet-build`.
+- After all tasks complete, if `review_mode: off`, do not enter `final-review` or `final-fix`, but must record the reason for skipping automatic code review in a durable artifact, then return to `comet-build`.
 - After final review passes, only the subagent dispatch loop is complete, not the Comet workflow. The coordinator must not load `finishing-a-development-branch` or pause to ask what comes next; it must return control to `comet-build` for exit checks, the phase guard, and phase handoff.
 
 ## Context Recovery
 
 Reload the Superpowers `subagent-driven-development` skill and re-read this document. Read `openspec/changes/<name>/.comet/subagent-progress.md`, then compare it with the first unchecked task and the current worktree:
 
-- When the checkpoint matches the unchecked task, resume from its exact recorded stage while preserving the implementation commit, RED/GREEN evidence, review stages already passed, unresolved feedback, and current review-fix round. Never reset the round or repeat an already passed stage.
+- When the checkpoint matches the unchecked task, resume from its exact recorded stage while preserving the implementation commit, RED/GREEN evidence, `review_mode`, review stages already passed, unresolved feedback, and current review-fix round. Never reset the round or repeat an already passed stage.
+- If the loaded Superpowers `subagent-driven-development` skill reports a task complete through its own progress record, reconcile that report against git history and Comet plan/OpenSpec checkboxes before dispatching. When the commits and task identity match, update Comet's checkpoint/checkoff state instead of re-dispatching completed work.
 - When the checkpoint is missing or does not match the unchecked task, create a new checkpoint for the first unchecked task and begin with implementer dispatch.
 - When a recorded commit or file is not visible in the current worktree, pull, merge, or recover the corresponding changes before proceeding; never assume the implementation exists.
 - When all tasks are checked and the checkpoint stage is `final-review` or `final-fix`, resume the exact final-review stage while preserving final feedback and its review-fix round; never re-enter completed tasks.
 
-Tasks committed without dual-review approval remain unchecked and re-enter the review or fix loop according to the checkpoint.
+Tasks committed without passing `review_mode` validation remain unchecked and re-enter the corresponding validation, review, or fix loop according to the checkpoint.

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

@@ -1,7 +1,7 @@
 # Comet Phase Awareness (Anti-Drift Rules)
 
 > This rule is injected every round to prevent forgetting Comet workflow state during long context.
-> The Hook platform additionally executes `comet-hook-guard.sh` for hard interception;
+> The Hook platform additionally executes `comet-hook-guard.mjs` for hard interception;
 > this Rule is a universal soft defense line for all platforms.
 
 ## Global Rules
@@ -19,6 +19,9 @@ When there is an active comet change (`openspec/changes/<name>/.comet.yaml` exis
 | `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 |
+
+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.
+
 ### Phase-Entry Self-Consistency Check (Before Writing Source Code)
 
 Reading the `phase` field alone is not enough — you must also confirm **how** that phase was reached. Before writing any source code, self-check whether `.comet.yaml` is in an **illegal jump** state (a prior phase was skipped) using the table below. If any row matches, immediately stop writing source code, go back to the corresponding phase to fill the missing artifact, and do not trust the `phase` field to keep going.
@@ -26,10 +29,14 @@ Reading the `phase` field alone is not enough — you must also confirm **how**
 | Detected | Verdict | Action |
 |----------|---------|--------|
 | `phase: build` + `workflow: full` + `design_doc` empty/null | Skipped design | Stop writing source; run `/comet-design` to create the Design Doc and pass guard |
-| `phase: build/verify` + any of proposal/design/tasks missing or empty | Skipped open | Return to `/comet-open` to fill the three artifacts |
+| `phase: build` + any of proposal/design/tasks missing or empty | Skipped open | Return to `/comet-open` to fill the three artifacts |
 | `phase: archive` + `verify_result` ≠ `pass` | Skipped verify | Return to `/comet-verify` to complete verification |
 
+> Note: the table above only covers what the hook hard-gate actually detects (the `design_doc` empty-jump at the build phase; proposal/design/tasks completeness is validated at the open→build guard exit). The `verify` phase is not covered by this write-source self-consistency gate — if artifacts are found missing during verify, follow the verify-fail rewind handling under "Verify Phase Specifics" below.
+
 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`).
 ### 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:
@@ -47,7 +54,7 @@ The following operations must be loaded through the Skill tool. When Skill is un
 - **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
+- **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)
 
 ### User Confirmation (Cannot Auto-Skip)
@@ -56,7 +63,7 @@ The following decision points must pause to wait for explicit user selection; do
 
 - **open**: Requirements clarification completion confirmation, artifact review confirmation
 - **design**: brainstorming proposal confirmation (Design Doc cannot be created before confirmation)
-- **build**: plan-ready pause, isolation/build_mode/tdd_mode selection, spec large-scale change 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
 
@@ -71,7 +78,7 @@ The following decision points must pause to wait for explicit user selection; do
 ## Build Phase Specifics
 
 1. After plan creation, must ask user to choose continue or pause (`build_pause` mechanism)
-2. After each task acceptance, must: tasks.md checkmark → git commit (do not accumulate). `subagent-driven-development` must wait for both spec compliance and code quality reviews to pass, then the coordinator performs targeted verification by unique task text; do not use an incomplete task summary table to replace current task verification
+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
 
@@ -80,13 +87,14 @@ The following decision points must pause to wait for explicit user selection; do
 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
 
 ## Context Compression Recovery
 
 If context compression is suspected (previous conversation was summarized, previous discussion cannot be found), immediately run:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> <phase> --recover
+node "$COMET_STATE" check <name> <phase> --recover
 ```
 
 Decide next step according to the script's **Recovery action** output.
@@ -99,8 +107,8 @@ After recovery, first re-run the "Phase-Entry Self-Consistency Check" table: if
 3. Read `openspec/changes/<name>/.comet/subagent-progress.md` to recover the exact stage, evidence, and review-fix round
 4. Do not execute tasks directly in the main session
 5. Resume from the checkpoint; start from the first unchecked task only when it is missing or mismatched
-6. Already committed but not yet passed both reviews tasks remain unchecked; continue review/fix loop
-7. After dual review and targeted checkoff verification pass, immediately continue to the next task without summarizing or asking whether to continue
+6. Tasks already committed but not yet validated according to `review_mode` remain unchecked; continue the corresponding validation/review/fix loop
+7. After a task passes `review_mode` validation and targeted checkoff verification, immediately continue to the next task without summarizing or asking whether to continue
 
 ## Automatic Transition After Phase Exit
 
@@ -110,10 +118,10 @@ After guard `--apply` succeeds, do not hardcode the next skill in this rule. Fir
 comet-state next <change-name>
 ```
 
-If `comet-env.sh` has already located the scripts, the equivalent command is:
+If `comet-env.mjs` has already located the scripts, the equivalent command is:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" next <change-name>
+node "$COMET_STATE" next <change-name>
 ```
 
 Decide the next step from the script output:

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

@@ -1,7 +1,7 @@
 # Comet 阶段感知（防漂移规则）
 
 > 此规则每轮注入，防止长上下文时遗忘 Comet 流程状态。
-> Hook 平台额外执行 `comet-hook-guard.sh` 进行硬性拦截；
+> Hook 平台额外执行 `comet-hook-guard.mjs` 进行硬性拦截；
 > 此 Rule 是所有平台通用的软性防线。
 
 ## 全局规则
@@ -20,6 +20,8 @@
 | `verify` | 验证、branch handling | 跳过失败处理 |
 | `archive` | 确认归档、运行归档脚本 | 写源代码 |
 
+Hook 硬拦截白名单包括 `openspec/*`、`docs/superpowers/*`、`.superpowers/*`、`.claude/*` 和 `.comet/*` 等流程/平台工作区；这些路径可写不代表可以跳过当前阶段的产物和确认要求。
+
 ### 阶段进入自洽性校验（写源代码前必查）
 
 仅看 `phase` 字段不够——还必须确认"是如何到达这个阶段的"。每次准备写源代码前，先用下表自检 `.comet.yaml` 是否处于**非法空跳**状态（绕过了前置阶段）。命中任一行，立即停止写源代码，按动作回到对应阶段补齐产物，不得信任 `phase` 字段直接续跑。
@@ -27,11 +29,15 @@
 | 检测到 | 判定 | 动作 |
 |--------|------|------|
 | `phase: build` + `workflow: full` + `design_doc` 为空/null | 绕过 design 空跳 | 停止写源代码，运行 `/comet-design` 补 Design Doc 并过 guard |
-| `phase: build/verify` + proposal/design/tasks 任一缺失或为空 | 绕过 open 空跳 | 回 `/comet-open` 补齐三件套 |
+| `phase: build` + proposal/design/tasks 任一缺失或为空 | 绕过 open 空跳 | 回 `/comet-open` 补齐三件套 |
 | `phase: archive` + `verify_result` ≠ `pass` | 绕过 verify 空跳 | 回 `/comet-verify` 完成验证 |
 
+> 说明：上表只覆盖 hook 硬门实际检测的范围（`design_doc` 空跳在 build 阶段；proposal/design/tasks 三件套完整性在 open→build 的 guard 退出时校验）。`verify` 阶段不在此写源码自洽门内——若 verify 发现产物缺失，按下方「Verify 阶段专项」的 verify-fail 回退处理。
+
 预设例外：`workflow: hotfix/tweak` 本就跳过 design，`design_doc` 为空属正常，不算非法。
 
+升级态说明：预设（hotfix/tweak）命中升级信号并经用户确认升级后，通过 `comet-state transition <name> preset-escalate` 合法地变为 `workflow: full` + `phase: design` + `design_doc: null`。此时 `phase: design` + `design_doc` 为空**属正常升级前置态**，不是非法空跳——agent 应进入 `/comet-design` 补 Design Doc。该终态不命中上表「绕过 design 空跳」行（该行仅检测 `phase: build`）。
+
 ### Skill 调用（不可用普通对话替代）
 
 以下操作必须通过 Skill 工具加载，Skill 不可用时应停止流程并提示安装：
@@ -49,7 +55,7 @@
 - **阶段退出**: `comet-guard <name> <phase> --apply`（必须看到 ALL CHECKS PASSED）
 - **压缩恢复**: `comet-state check <name> <phase> --recover`
 - **状态更新**: 关键操作后通过 `comet-state set` 更新字段，禁止手工编辑 .comet.yaml
-- **阶段推进只能经 guard/transition**: 禁止用 `comet-state set <name> phase <值>` 手动跳阶段（会绕过证据校验，脚本已硬拦截）；确需修复畸形状态时才用 `COMET_FORCE_PHASE=1` 逃生阀
+- **阶段推进只能经 guard/transition**: 禁止用 `comet-state set <name> phase <值>` 手动跳阶段（会绕过证据校验，脚本已硬拦截）；确需修复畸形状态时才用 `COMET_FORCE_PHASE=1` 逃生阀。预设（hotfix/tweak）升级到 full 必须用 `comet-state transition <name> preset-escalate`——这是唯一能合法回退 phase 到 design 并同步 workflow/classic_profile 的通道，直接 `set phase design` 和 `set classic_profile` 都会被硬拦截
 - **handoff 生成**: `comet-handoff <name> design --write`（禁止手写摘要）
 
 ### 用户确认（不可自动跳过）
@@ -58,7 +64,7 @@
 
 - **open**: 需求澄清完成确认、artifact 评审确认
 - **design**: brainstorming 方案确认（确认前不得创建 Design Doc）
-- **build**: plan-ready 暂停、isolation/build_mode/tdd_mode 选择、spec 大规模变更确认
+- **build**: plan-ready 暂停、`isolation` / `build_mode` / `tdd_mode` / `review_mode` 四项选择（工作区隔离、执行方式、TDD 模式、代码审查模式）、spec 大规模变更确认、预设（hotfix/tweak）升级判定二选一（命中质变信号或文件数 tripwire 时，交用户决定继续预设流程还是升级 full）
 - **verify**: 验证失败处理策略、branch handling 选择
 - **archive**: 归档前最终确认
 
@@ -73,7 +79,7 @@
 ## Build 阶段专项
 
 1. plan 创建后必须询问用户选择继续或暂停（`build_pause` 机制）
-2. 每个 task 验收后必须: tasks.md 打勾 → git commit（不得积攒）。`subagent-driven-development` 必须等 spec compliance 与 code quality 两个审查都通过，再由协调者按任务唯一文本定向勾选和验证；不得用未完成任务总表代替当前任务验证
+2. 每个 task 验收后必须: tasks.md 打勾 → git commit（不得积攒）。`subagent-driven-development` 必须按当前 `review_mode` 完成验收，再由协调者按任务唯一文本定向勾选和验证；不得用未完成任务总表代替当前任务验证
 3. 遇到失败必须加载 **systematic-debugging** skill，根因未定位前不得提出源码修复
 4. spec 变更分级: 小改直接编辑 | 中改加载 brainstorming | 大改暂停等用户确认拆分
 
@@ -82,13 +88,14 @@
 1. 第一步运行 `comet-state scale <name>` 确定验证级别
 2. 验证失败后列出失败项等用户选择，CRITICAL 必须修
 3. 连续 3 次失败后必须让用户选择接受偏差或继续修
+4. 用户选择修复时运行 `comet-state transition <name> verify-fail`：该转移会把 `phase` 回退到 `build`（不是停在 verify），随后进入 `/comet-build` 修复，修完重新过 build→verify guard
 
 ## 上下文压缩恢复
 
 如果怀疑发生上下文压缩（之前对话被摘要、找不到之前讨论的内容），立即运行：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> <phase> --recover
+node "$COMET_STATE" check <name> <phase> --recover
 ```
 
 按脚本输出的 **Recovery action** 决定下一步。
@@ -101,8 +108,8 @@
 3. 读取 `openspec/changes/<name>/.comet/subagent-progress.md` 恢复精确阶段、证据和审查-修复轮次 (Read `openspec/changes/<name>/.comet/subagent-progress.md` to recover the exact stage, evidence, and review-fix round)
 4. 禁止在主会话中直接执行 task (Do not execute the pending task directly in the main window)
 5. 按检查点恢复；缺失或不匹配时才从第一个未勾选 task 开始
-6. 已提交但未通过双审查的 task 保持未勾选，继续审查/修复循环
-7. task 通过双审查和定向勾选验证后立即继续下一个 task，不得总结或询问是否继续
+6. 已提交但未按 `review_mode` 完成验收的 task 保持未勾选，继续对应的验证/审查/修复循环
+7. task 按 `review_mode` 完成验收并通过定向勾选验证后立即继续下一个 task，不得总结或询问是否继续
 
 ## 阶段退出后自动过渡
 
@@ -112,10 +119,10 @@ guard `--apply` 成功后，不得在本规则中硬编码下一阶段 skill。
 comet-state next <change-name>
 ```
 
-若已通过 `comet-env.sh` 定位脚本，等价运行：
+若已通过 `comet-env.mjs` 定位脚本，等价运行：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" next <change-name>
+node "$COMET_STATE" next <change-name>
 ```
 
 按脚本输出决定下一步：

package/assets/skills/comet/runtime/classic/checks.yaml

@@ -0,0 +1,6 @@
+runtime:
+  - id: classic-completed
+    scope: completion
+    type: state_equals
+    field: status
+    equals: completed

package/assets/skills/comet/runtime/classic/guardrails.yaml

@@ -0,0 +1,13 @@
+allowedSkills:
+  - comet-open
+  - comet-design
+  - comet-build
+  - comet-verify
+  - comet-archive
+  - comet-hotfix
+  - comet-tweak
+allowedAgents: []
+allowedTools: []
+maxIterations: 500
+maxRetriesPerAction: 3
+confirmationRequiredFor: []

package/assets/skills/comet/runtime/classic/skill.yaml

@@ -0,0 +1,122 @@
+apiVersion: comet/v1alpha1
+kind: Skill
+metadata:
+  name: comet-classic
+  version: "1"
+  description: Internal compatibility orchestration for classic Comet full, hotfix, and tweak workflows
+goal:
+  statement: Advance or restore a classic Comet Run without changing the user command surface
+  inputs:
+    - name: classic-state
+      description: Validated ClassicState consistent with the Run projection
+      required: true
+    - name: evidence
+      description: Structured evidence produced by the Classic Evidence collector
+      required: true
+  outputs:
+    - name: run-state
+      description: Atomically synchronized Classic and Run state
+      required: true
+  success:
+    - Legacy fields and Run fields remain consistent
+    - Every step invokes only a declared public Comet Skill
+    - The completed state passes its completion eval
+orchestration:
+  mode: deterministic
+  entry: full.open
+  steps:
+    - id: full.open
+      action: { type: invoke_skill, ref: comet-open }
+      next: full.design.handoff
+    - id: full.design.handoff
+      action: { type: invoke_skill, ref: comet-design }
+      next: full.design.document
+    - id: full.design.document
+      action: { type: invoke_skill, ref: comet-design }
+      next: full.build.plan
+    - id: full.build.plan
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.plan-ready
+    - id: full.build.plan-ready
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.configure
+    - id: full.build.configure
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.execute
+    - id: full.build.execute
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.complete
+    - id: full.build.complete
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.verify.run
+    - id: full.build.fix
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.execute
+    - id: full.verify.run
+      action: { type: invoke_skill, ref: comet-verify }
+      next: full.verify.branch
+    - id: full.verify.branch
+      action: { type: invoke_skill, ref: comet-verify }
+      next: full.archive.confirm
+    - id: full.archive.confirm
+      action: { type: invoke_skill, ref: comet-archive }
+      next: full.archive.execute
+    - id: full.archive.execute
+      action: { type: invoke_skill, ref: comet-archive }
+      next: completed
+    - id: hotfix.open
+      action: { type: invoke_skill, ref: comet-hotfix }
+      next: hotfix.build.execute
+    - id: hotfix.build.execute
+      action: { type: invoke_skill, ref: comet-build }
+      next: hotfix.build.complete
+    - id: hotfix.build.complete
+      action: { type: invoke_skill, ref: comet-build }
+      next: hotfix.verify.run
+    - id: hotfix.verify.run
+      action: { type: invoke_skill, ref: comet-verify }
+      next: hotfix.verify.branch
+    - id: hotfix.verify.branch
+      action: { type: invoke_skill, ref: comet-verify }
+      next: hotfix.archive.confirm
+    - id: hotfix.archive.confirm
+      action: { type: invoke_skill, ref: comet-archive }
+      next: hotfix.archive.execute
+    - id: hotfix.archive.execute
+      action: { type: invoke_skill, ref: comet-archive }
+      next: completed
+    - id: tweak.open
+      action: { type: invoke_skill, ref: comet-tweak }
+      next: tweak.build.execute
+    - id: tweak.build.execute
+      action: { type: invoke_skill, ref: comet-build }
+      next: tweak.build.complete
+    - id: tweak.build.complete
+      action: { type: invoke_skill, ref: comet-build }
+      next: tweak.verify.run
+    - id: tweak.verify.run
+      action: { type: invoke_skill, ref: comet-verify }
+      next: tweak.verify.branch
+    - id: tweak.verify.branch
+      action: { type: invoke_skill, ref: comet-verify }
+      next: tweak.archive.confirm
+    - id: tweak.archive.confirm
+      action: { type: invoke_skill, ref: comet-archive }
+      next: tweak.archive.execute
+    - id: tweak.archive.execute
+      action: { type: invoke_skill, ref: comet-archive }
+      next: completed
+    - id: completed
+      action: { type: checkpoint }
+      completionEvals:
+        - classic-completed
+skills:
+  - id: comet-open
+  - id: comet-design
+  - id: comet-build
+  - id: comet-verify
+  - id: comet-archive
+  - id: comet-hotfix
+  - id: comet-tweak
+agents: []
+tools: []

package/assets/skills/comet/scripts/comet-archive.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './comet-runtime.mjs';
+process.exitCode = await main(["archive", ...process.argv.slice(2)]);