@rpamis/comet 0.3.9 → 0.4.0-beta.10

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

@@ -4,17 +4,39 @@ Canonical path: `comet/reference/decision-point.md`
 
 This protocol is shared by all comet sub-skills that contain user decision points. Any step labeled as a blocking point or user decision point must follow this protocol.
 
+## First Decide Whether User Input Is Actually Required
+
+Distinguish user decisions, automatic handling, and stop conditions:
+
+- **User decision**: two or more valid options change scope, behavior, accepted risk, or an irreversible outcome; the user must choose
+- **Automatic handling**: exactly one safe next action remains within the request, such as repairing an objective failure, reconciling verifiable state, retrying an idempotent check, or following persisted configuration; execute and report it without manufacturing confirmation
+- **Stop condition**: a missing dependency, corrupt state, path escape, or unavailable external command leaves no valid next action; report the blocker and recovery condition without inventing choices
+- **Manual handoff**: `NEXT: manual` returns control; it is not a new user decision point. Print `HINT`, end the current invocation, and do not ask whether to continue
+
+Only the first category uses this protocol. Merge adjacent choices that can be answered together, and do not re-ask persisted choices that remain valid. Preflight platform capabilities and state before presenting options, and show only executable choices. If a field has only one valid value, explain why and apply it without creating a separate pause.
+
 ## Core Rules
 
 - Decision points are blocking points. Pause and wait for an explicit user choice before continuing
-- Use the current platform's available user input or confirmation mechanism to collect the choice
+- Use the current platform's available user input or confirmation mechanism to collect the choice; when platforms such as Claude Code provide `AskUserQuestion`, prefer `AskUserQuestion` to present single-select or multi-select options
+- If the current tool list does not include `AskUserQuestion`, or the first `AskUserQuestion` call fails, treat structured questions as unavailable for this session; do not repeatedly retry `AskUserQuestion` for later decision points in the same session, and use the text-options fallback directly
 - If the current platform has no structured question tool, ask clear options in the conversation and stop until the user replies
 - Never substitute recommendation rules, defaults, historical preferences, or “the user would probably agree” for current confirmation
 - Do not write state fields, execute the chosen branch, or auto-continue before the user explicitly chooses
 
+## `AskUserQuestion` Priority Strategy
+
+When using structured questions:
+
+- Use a single-select `AskUserQuestion` question for single-choice decision points, and a multi-select question for multi-choice decision points
+- Each option must include a short label and impact description; recommendations may explain tradeoffs but must not auto-select
+- If the tool call succeeds, wait for the user to answer through that question; do not also print a duplicate text option list
+- If the tool is missing, the call fails, or the host reports an error, record that structured questions are unavailable for this session, then use the text-options fallback
+
 ## Minimum Presentation Requirements
 
 - State what the current decision point is deciding
 - Present clear options; when the user must pick one option, keep the options mutually exclusive and actionable
+- In text-options fallback mode, explicitly state "single-select" or "multi-select", number the options, describe each option's impact, ask the user to reply with the option number(s), then stop until the user replies
 - Recommendations may explain tradeoffs, but may not replace user confirmation
-- Only execute the corresponding commands or state updates after the user chooses
+- Only execute the corresponding commands or state updates after the user chooses

package/assets/skills/comet/reference/file-structure.md

@@ -5,7 +5,7 @@ Canonical path: `comet/reference/file-structure.md`
 This file is the Comet project file structure reference. Consult on demand; not loaded inline with skills.
 
 ```text
-openspec/                              # OpenSpec — WHAT
+<classic-open-spec-root>/              # OpenSpec — WHAT; returned by the Classic layout resolver
 ├── config.yaml
 ├── changes/
 │   ├── <name>/                        # Active change
@@ -19,7 +19,7 @@ openspec/                              # OpenSpec — WHAT
 │   └── archive/YYYY-MM-DD-<name>/     # Archived
 └── specs/<capability>/spec.md         # Main specs (merged on archive via OpenSpec delta semantics)
 
-docs/superpowers/                      # Superpowers — HOW
+<classic-superpowers-root>/            # Superpowers — HOW; returned by the Classic layout resolver
 ├── specs/YYYY-MM-DD-<topic>-design.md # Design doc (technical RFC; annotated on archive)
 └── plans/YYYY-MM-DD-<feature>.md      # Implementation plan (file header contains change metadata)
 

package/assets/skills/comet/reference/intent-frame.md

@@ -0,0 +1,74 @@
+# CometIntentFrame Field Reference
+
+Read this file only when field meanings are needed. Normal `/comet-classic` routing only needs the minimal skeleton in the main Skill; the runtime fills omitted defaults and outputs the final `route`.
+
+## Top-Level Fields
+
+| Field | Meaning |
+|-------|---------|
+| `schema_version` | Frame version. Currently fixed to `comet.intent.v1`. |
+| `utterance` | The user request that triggered `/comet-classic`. |
+| `intent` | High-level user intent and confidence. If confidence is below the runtime threshold, routing falls back to `ask_user`. |
+| `slots` | Routing slots normalized from the user request. |
+| `context` | Repository context read from local state; this is not extracted from the user utterance. |
+| `evidence` | Evidence for key routing conclusions. Missing key evidence makes the runtime prefer `ask_user`. |
+| `proposed_route` | Agent-submitted route candidate. Minimal input only needs `name` and `confidence`; the runtime reviews it and outputs the final `route`. |
+
+## `intent`
+
+| Field | Meaning |
+|-------|---------|
+| `intent.name` | High-level user intent: start, resume, fix bug, make tweak, ask question, or unknown. |
+| `intent.confidence` | Agent confidence in the high-level intent. This participates in low-confidence fallback; `proposed_route.confidence` does not. |
+
+## `slots`
+
+| Field | Meaning |
+|-------|---------|
+| `requested_action` | The action the user wants, such as `start`, `resume`, `continue`, `fix`, `modify`, `create`, `verify`, `archive`, or `question`. |
+| `workflow_candidate` | Agent-inferred candidate workflow: `full`, `hotfix`, `tweak`, or `null`. This is an inference and the runtime reviews it. |
+| `user_explicit_workflow` | Whether the user explicitly named a workflow. If the user says "use hotfix", set `hotfix`; otherwise set `null`. Explicit workflow still falls back to `ask_user` when it conflicts with risk signals. |
+| `change_id` | Active change name explicitly requested by the user for resume or operation. Use `null` when unspecified. |
+| `existing_behavior` | Whether the request fixes existing behavior or a regression. `true` with no new capability/API/schema/cross-module risk tends toward `hotfix`. |
+| `new_capability` | Whether the request adds a new capability. Usually tends toward `full`. |
+| `public_api_change` | Whether the request changes a user-visible contract, such as CLI flags, config fields, JSON output, or public Skill flow. Usually tends toward `full`. |
+| `schema_change` | Whether the request changes structured data formats, such as `.comet.yaml`, `run-state.json`, eval manifests, bundle manifests, or config schema. Usually tends toward `full`. |
+| `cross_module_change` | Whether the request crosses module or workflow boundaries. Usually tends toward `full`. |
+| `target_area` | Optional explanation field for the target area the user mentioned. The minimal skeleton does not need it. |
+| `scope` | Optional explanation field for rough scope size. The current scorer does not let it drive routing by itself, and the minimal skeleton does not need it. |
+
+## `context`
+
+| Field | Meaning |
+|-------|---------|
+| `active_changes_count` | Number of unarchived active changes from `comet classic openspec -- list --json`. Multiple active changes without a `change_id` route to `ask_user`. |
+| `active_change_names` | Names of active changes. When the user supplies `change_id`, the runtime checks it against this list. |
+| `dirty_worktree` | Optional state field. The entry-route minimal skeleton does not need it; dirty worktree handling belongs to `comet/reference/dirty-worktree.md`. |
+
+## `evidence`
+
+Each evidence item contains:
+
+| Field | Meaning |
+|-------|---------|
+| `field` | Frame field supported by the evidence, such as `intent.name` or `slots.workflow_candidate`. |
+| `quote` | Evidence snippet from the user request, repository state, or `.comet.yaml`. |
+| `source` | Evidence source: `user`, `repo`, or `state`. |
+
+## `proposed_route`
+
+| Field | Meaning |
+|-------|---------|
+| `name` | Agent route candidate: `full`, `hotfix`, `tweak`, `resume`, `ask_user`, or `out_of_scope`. |
+| `confidence` | Agent confidence in the route candidate. Diagnostic only; it does not participate in low-confidence fallback. |
+| `next_skill` | Derived field normalized by the runtime. The minimal skeleton does not need it. |
+| `requires_confirmation` | Derived field normalized by the runtime. The minimal skeleton does not need it. |
+| `fallback_reason` | Derived field normalized by the runtime. The minimal skeleton does not need it. |
+
+## Routing Notes
+
+- Existing bug, regression, or broken behavior with no new capability/API/schema/cross-module risk: prefer `hotfix`.
+- Copy, config, docs, prompt, or lightweight/medium single OpenSpec change: prefer `tweak`.
+- New capability, public API, schema change, cross-module coordination, or architecture work: prefer `full`.
+- Multiple active changes without an explicit change: `ask_user`.
+- Low confidence, missing key evidence, or explicit workflow conflicting with risk signals: `ask_user`.

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

@@ -0,0 +1,101 @@
+# Stable CLI and Internal Script Compatibility
+
+Canonical path: `comet/reference/scripts.md`
+
+This file is the single source of truth for Comet's public CLI and internal script compatibility. Public workflows must prefer the stable command surface: `comet state`, `comet guard`, `comet handoff`, and `comet archive`.
+
+## Public Workflow Contract
+
+Normal installations and everyday workflows use the `comet` CLI directly. They do not need to locate launchers and must not expose the internal `classic` name to users:
+
+```bash
+comet state select <change-name>
+comet state current
+comet state clear-selection
+comet state check <change-name> <phase>
+comet guard <change-name> <phase> --apply
+comet handoff <change-name>
+comet archive <change-name>
+```
+
+When multiple active changes coexist, run `comet state select <change-name>` after resolving the intended change. Ordinary source writes are governed only by that selection; without one, the hook blocks and asks for a choice. A single active change retains automatic routing. Select again after switching branch/worktree or when the recorded selection becomes stale.
+
+Guard `--apply` advances state after checks pass. Use `comet state transition` when expressing a state event directly, and `comet state next` after phase advancement to determine whether to invoke the next Skill automatically.
+
+## Compatibility, Recovery, and Internal Command Bootstrap
+
+The script discovery below is only for legacy compatibility, recovery when the CLI is unavailable, and internal `/comet-classic` entry commands. Normal public workflows must not prefer it. Comet scripts are distributed in `comet/scripts/`; recovery code must locate them once and cache environment variables instead of hardcoding paths:
+
+```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"
+COMET_RESUME_PROBE="$COMET_SCRIPTS_DIR/comet-resume-probe.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
+```
+
+Agents run this bootstrap only when entering one of the compatibility, recovery, or internal-command paths above. `COMET_INTENT` and `COMET_RESUME_PROBE` remain necessary for internal entry routing and must not be removed globally.
+
+| Variable | Purpose |
+|----------|---------|
+| `COMET_STATE` | `.comet.yaml` state reads/writes, phase checks, and recovery context |
+| `COMET_GUARD` | Phase exit guard and `--apply` state advancement |
+| `COMET_HANDOFF` | Design/Build handoff context pack generation |
+| `COMET_ARCHIVE` | One-command archive and main spec sync |
+| `COMET_INTENT` | `/comet-classic` entry intent recognition and route scoring |
+| `COMET_RESUME_PROBE` | Read-only Ambient Resume probe that decides whether to resume an active Comet workflow |
+
+## Auto state update
+
+Guard supports `--apply` flag, automatically updating `.comet.yaml` state fields after checks pass:
+
+```bash
+comet guard <change-name> <phase> --apply
+```
+
+`--apply` delegates to the state-machine transition. Use these semantic events when state changes need to be expressed directly:
+
+```bash
+comet state transition <change-name> open-complete
+comet state transition <change-name> design-complete
+comet state transition <change-name> build-complete
+comet state transition <change-name> verify-pass
+comet state transition <change-name> verify-fail
+comet state transition <change-name> archive-confirm
+comet state transition <change-name> archive-reopen
+comet state transition <change-name> archived
+comet state transition <change-name> preset-escalate
+```
+
+Archive completion is handled by `comet archive <change-name>` after OpenSpec moves the change into its date-prefixed archive directory. Use `archive-confirm` or `archive-reopen` for the pre-archive decision, and do not manually run the `archived` transition outside that flow.
+
+## Resolve next action
+
+After guard-based phase advancement, use the `next` subcommand to determine whether to auto-invoke the next skill:
+
+```bash
+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
+comet archive <change-name>
+```

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

@@ -2,25 +2,27 @@
 
 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
 >
+> Background dispatch capability disappearing during execution is a runtime stop condition, not automatically a new user decision point. Exit the dispatch loop and return to the same `/comet-build` Step 2 joint decision with `subagent-driven-development` removed. If only one execution method remains, explain why and apply it directly; wait for the user only when multiple valid methods remain.
+>
 > This rule applies to the ENTIRE dispatch loop, not just individual tasks.
 
 ## Before Starting
 
-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,26 +30,52 @@ 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`.
+- If real background dispatch capability disappears during execution, stop dispatching and do not let the main session implement the task. Return to the same `/comet-build` Step 2 joint decision with the unavailable mode removed. Do not create a separate "switch to executing-plans" pause; apply the only valid mode directly when just one remains.
 
 ### 1. Dispatch Prompt and Return Contract
 
 Every implementer or fix-agent prompt must include:
 
 - The full text of the single current task, architecture background, and dependency context
-- `Language: Use the language of the user request that triggered this workflow`
+- `Language: Use the configured Comet artifact language from comet state get <name> language`
 - The allowed file scope and prohibited modification scope
 - The required test commands and commit requirements
 - For a fix agent, the corresponding reviewer's complete feedback
 
-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.
+
+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.
 
-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.
+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 +89,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 coordinator must maintain `<classic-change-dir>/.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 +143,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"
+comet state task-checkoff <plan-file> <plan-task-text>
+comet state task-checkoff <classic-change-dir>/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:
+Reload the Superpowers `subagent-driven-development` skill and re-read this document. Read `<classic-change-dir>/.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.