@rpamis/comet 0.3.7 → 0.3.9

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

@@ -0,0 +1,27 @@
+# Automatic Handoff to Next Phase Protocol
+
+Canonical path: `comet/reference/auto-transition.md`
+
+This protocol is shared by all comet sub-skills. It defines the automatic handoff rules after phase guard advancement.
+
+## Terminology Distinction
+
+"Phase advancement" is performed by guard `--apply`, which updates the `phase` field in `.comet.yaml` — this **always happens** and is independent of `auto_transition`. This protocol's "automatic handoff" only determines **whether to automatically invoke the next skill**, controlled by `auto_transition`.
+
+## Execution
+
+After exit conditions are met and the phase guard has advanced phase, run:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
+
+The script outputs a deterministic next step based on `phase`, `workflow`, and `auto_transition`:
+
+- `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 manually run `/<SKILL>` per `HINT`
+- `NEXT: done` → workflow is complete, no further action needed
+
+## Preset Routing
+
+When `workflow: hotfix`, `phase: build` returns `comet-hotfix`; when `workflow: tweak`, it returns `comet-tweak`. All other phases (`verify`, `archive`) return standard skill names (`comet-verify`, `comet-archive`) regardless of workflow type. The "continuous execution mode" within preset skills may override `auto_transition` behavior — see the corresponding preset's `<IMPORTANT>` block.

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

@@ -0,0 +1,68 @@
+# .comet.yaml Field Reference
+
+Canonical path: `comet/reference/comet-yaml-fields.md`
+
+This file is the field reference for the `.comet.yaml` state file. Consult on demand; not loaded inline with skills.
+
+## Example
+
+```yaml
+workflow: full
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+base_ref: a1b2c3d4e5f6...
+build_mode: subagent-driven-development
+build_pause: null
+subagent_dispatch: confirmed
+tdd_mode: tdd
+isolation: branch
+verify_mode: light
+verify_result: pending
+verification_report: null
+branch_status: pending
+created_at: 2026-05-26
+verified_at: null
+archived: false
+```
+
+## Required Fields
+
+| Field | Meaning |
+|-------|---------|
+| `workflow` | `full`, `hotfix`, or `tweak` |
+| `phase` | Current phase: `open`, `design`, `build`, `verify`, `archive` (init sets `open`; guard handles transitions) |
+| `design_doc` | Associated Superpowers Design Doc path; may be empty |
+| `plan` | Associated Superpowers Plan path; may be empty |
+| `base_ref` | Git commit SHA recorded at init for scale assessment. Used as baseline for changed-file counting when no plan exists |
+| `build_mode` | Selected execution mode; may be empty |
+| `build_pause` | Build phase internal pause point. `null` = no pause, `plan-ready` = plan generated, paused for user model switch |
+| `subagent_dispatch` | `null` or `confirmed`. Only when the platform's real background subagent/Task/multi-agent dispatch capability is confirmed may `build_mode: subagent-driven-development` be written and used to leave the build phase |
+| `tdd_mode` | `tdd` or `direct`. Full workflow must select before leaving build. `tdd` forces write-failing-test-first per task; `direct` skips TDD enforcement. hotfix/tweak default to `direct` |
+| `isolation` | `branch` or `worktree`, workspace isolation mode. Full init may be `null` but only until `/comet-build` Step 3; hotfix/tweak default to `branch` |
+| `verify_mode` | `light` or `full`; may be empty |
+| `auto_transition` | `true` or `false`. Only controls whether to automatically invoke the next skill after phase guard advances phase; `false` outputs `manual` from `comet-state next`, pausing next-skill invocation but not blocking phase field updates |
+| `verify_result` | `pending`, `pass`, or `fail` |
+| `verification_report` | Verification report file path; must point to an existing file before verify passes |
+| `branch_status` | `pending` or `handled`; set to `handled` after branch handling completes |
+| `created_at` | Change creation date (auto-written at init), format `YYYY-MM-DD` |
+| `verified_at` | Verification pass timestamp; may be empty |
+| `archived` | Whether the change has been archived |
+
+## Optional Fields
+
+| Field | Meaning |
+|-------|---------|
+| `direct_override` | `true`/`false`. Full workflow must explicitly set to `true` to use `build_mode: direct` |
+| `build_command` | Project build command. Guard runs this first; prints command output on failure |
+| `verify_command` | Project verify command. Verify guard runs this first; falls back to build command when unset |
+
+## State Machine Hard Constraints
+
+- Before `build → verify`, `isolation` must be `branch` or `worktree`
+- Before `build → verify`, `build_mode` must be selected
+- `build_mode: subagent-driven-development` requires `subagent_dispatch: confirmed`
+- Full workflow must select `tdd_mode` as `tdd` or `direct` before leaving build
+- `build_mode: direct` defaults to `hotfix`/`tweak` only; full workflow requires `direct_override: true`
+- `build_pause` is not an execution mode; must not be written to `build_mode`
+- These constraints exist in both `comet-guard.sh build --apply` and `comet-state.sh transition <name> build-complete`

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

@@ -0,0 +1,35 @@
+# Context Compression Recovery Protocol
+
+Canonical path: `comet/reference/context-recovery.md`
+
+This protocol is shared by all comet sub-skills that may trigger context compression. When the agent suspects context compression has occurred (previous conversation summarized, cannot find previously discussed content), follow this protocol to recover.
+
+## Recovery Steps
+
+```bash
+"$COMET_BASH" "$COMET_STATE" check <change-name> <phase> --recover
+```
+
+The script outputs structured recovery context (phase, completed fields, pending fields, recovery action). Follow the **Recovery action** output for next steps.
+
+## Build Phase Special Recovery
+
+If the recovery script outputs `build_mode: subagent-driven-development`:
+
+1. Use the Skill tool to reload the Superpowers `subagent-driven-development` skill
+2. Re-read `comet/reference/subagent-dispatch.md` for Comet-specific extensions
+3. Read `openspec/changes/<name>/.comet/subagent-progress.md` to recover the current task or final review, implementation commit, RED/GREEN evidence, passed reviews, unresolved feedback, and review-fix round
+4. Do not execute tasks directly in the main session
+5. Resume from the checkpoint's exact stage; begin implementer dispatch for the first unchecked task only when the checkpoint is missing or mismatched
+6. After dual review and targeted checkoff verification pass, immediately continue to the next task without summarizing or asking whether to continue
+
+## Design Phase Special Recovery
+
+- If the user has not yet confirmed the design approach, return to brainstorming
+- If the user has confirmed, continue creating the Design Doc
+- On recovery, reload `brainstorm-summary.md` + handoff context files
+
+## Verify/Archive Phase Recovery
+
+- Verify: script outputs verification status, branch status, and recovery action
+- Archive: if `archived: true` and archive directory exists, archival is complete — do not re-execute

package/assets/skills/comet/reference/debug-gate.md

@@ -0,0 +1,17 @@
+# Debug Gate Protocol
+
+Canonical path: `comet/reference/debug-gate.md`
+
+This protocol is shared by comet sub-skills that directly modify code, including build, hotfix, and tweak. Enter the Debug Gate when a crash, unexpected behavior, test failure, or build failure appears while running the program, tests, build, or manual verification.
+
+## Core Rules
+
+- Immediately use the Skill tool to load the Superpowers `systematic-debugging` skill
+- Do not propose or implement source fixes before the root cause investigation is complete
+
+## Four-Stage Flow
+
+1. Reproduce and locate the root cause first by reading the full error, checking recent changes, and tracing data flow
+2. If the root cause is a source bug, first add a minimal failing test that reproduces the crash or unexpected behavior, then modify the source
+3. After the fix, run that failing test, related tests, and the project's build or verification commands until all pass
+4. Keep the test, the source fix, and the tasks.md checkoff in the current change; do not replace the current change verification loop by starting a separate “write test cases” change

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

@@ -0,0 +1,20 @@
+# Decision Point Protocol
+
+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.
+
+## 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
+- 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
+
+## 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
+- Recommendations may explain tradeoffs, but may not replace user confirmation
+- Only execute the corresponding commands or state updates after the user chooses

package/assets/skills/comet/reference/dirty-worktree.md

@@ -1,59 +1,59 @@
-# Dirty Worktree Protocol
-
-Canonical path: `comet/reference/dirty-worktree.md`
-
-This protocol is shared by all Comet sub-skills that may modify code. When an agent resumes context or continues execution, it must handle uncommitted working tree changes through this protocol.
-
-## 1. Checks
-
-Before continuing or starting code changes, run:
-
-```bash
-git status --short
-git diff --stat
-git diff --cached --stat
-git ls-files --others --exclude-standard
-```
-
-When needed, inspect `git diff`, `git diff --cached`, and newly created file contents.
-
-## 2. Core Rules
-
-- The user may not say which files they changed. If the worktree is dirty, including new files shown as `??` in Git status, assume changes may come from the user or mixed sources.
-- **Build artifact exclusion**: `??` files matching `.gitignore` patterns (e.g., `node_modules/`, `dist/`, `__pycache__/`, `*.o`, `target/`, `build/`) are automatically skipped during attribution and not treated as user changes.
-- A dirty worktree is code evidence only. It does not automatically advance `.comet.yaml` `phase` or check off `tasks.md`; Comet state may advance only after attribution, verification, required document synchronization, and the relevant phase guard.
-
-## 3. Attribution
-
-Classify dirty diffs into three groups:
-
-1. **Belongs to the current change**: Files and content match the current change goal, tasks.md, plan, or delta spec. Incorporate the diff into the current task and avoid redoing the same work.
-2. **Does not belong to the current change**: Files or content are unrelated. Pause and ask whether to include it in the current change, split it into a new change, leave it alone, or discard it with explicit authorization.
-3. **Unclear source**: The diff and documents are not enough to determine ownership. Pause, report the file list and reasoning, and do not advance the phase.
-
-## 4. Common Patterns
-
-### Implemented But tasks.md Is Not Checked
-
-Verify the implementation with build and tests. If it passes, check off the task. Do not redo work just because the task is unchecked, and do not ignore code evidence because state files lag behind. If the current sub-skill defines a phase-specific rule, follow that sub-skill.
-
-### Plan Or Scope Changed
-
-Follow the current sub-skill's escalation, incremental-update, or rollback rules. This protocol does not repeat phase-specific details.
-
-### Ambiguous Resume Intent
-
-When the user says things like "continue", "keep going", "I changed a bit", "I wasn't happy with it", "redo it", "code changed", or "use what is there", follow this protocol. Do not require the user to remember exactly what they changed.
-
-### Code Changes During open/design
-
-If the current phase is still `open` or `design` but the dirty worktree already contains code changes, first attribute the changes through this protocol and do not advance the phase directly:
-
-- If the changes belong to the current change, treat them as requirements or design input and record them in proposal/design/spec/design doc/tasks as appropriate. The current phase guard must still pass before entering build.
-- If the changes do not belong to the current change or ownership is unclear, pause and ask whether to include them, split them into a new change, leave them alone, or discard them with explicit authorization.
-- Do not treat code changes made during open/design as completed implementation ready for verify.
-
-## 5. Prohibitions
-
-- Do not overwrite, revert, reformat over, or ignore user changes before understanding the dirty diff source.
-- Do not mark verification as passed while dirty diff remains unexplained.
+# Dirty Worktree Protocol
+
+Canonical path: `comet/reference/dirty-worktree.md`
+
+This protocol is shared by all Comet sub-skills that may modify code. When an agent resumes context or continues execution, it must handle uncommitted working tree changes through this protocol.
+
+## 1. Checks
+
+Before continuing or starting code changes, run:
+
+```bash
+git status --short
+git diff --stat
+git diff --cached --stat
+git ls-files --others --exclude-standard
+```
+
+When needed, inspect `git diff`, `git diff --cached`, and newly created file contents.
+
+## 2. Core Rules
+
+- The user may not say which files they changed. If the worktree is dirty, including new files shown as `??` in Git status, assume changes may come from the user or mixed sources.
+- **Build artifact exclusion**: `??` files matching `.gitignore` patterns (e.g., `node_modules/`, `dist/`, `__pycache__/`, `*.o`, `target/`, `build/`) are automatically skipped during attribution and not treated as user changes.
+- A dirty worktree is code evidence only. It does not automatically advance `.comet.yaml` `phase` or check off `tasks.md`; Comet state may advance only after attribution, verification, required document synchronization, and the relevant phase guard.
+
+## 3. Attribution
+
+Classify dirty diffs into three groups:
+
+1. **Belongs to the current change**: Files and content match the current change goal, tasks.md, plan, or delta spec. Incorporate the diff into the current task and avoid redoing the same work.
+2. **Does not belong to the current change**: Files or content are unrelated. Pause and ask whether to include it in the current change, split it into a new change, leave it alone, or discard it with explicit authorization.
+3. **Unclear source**: The diff and documents are not enough to determine ownership. Pause, report the file list and reasoning, and do not advance the phase.
+
+## 4. Common Patterns
+
+### Implemented But tasks.md Is Not Checked
+
+Verify the implementation with build and tests. If it passes, check off the task. Do not redo work just because the task is unchecked, and do not ignore code evidence because state files lag behind. If the current sub-skill defines a phase-specific rule, follow that sub-skill.
+
+### Plan Or Scope Changed
+
+Follow the current sub-skill's escalation, incremental-update, or rollback rules. This protocol does not repeat phase-specific details.
+
+### Ambiguous Resume Intent
+
+When the user says things like "continue", "keep going", "I changed a bit", "I wasn't happy with it", "redo it", "code changed", or "use what is there", follow this protocol. Do not require the user to remember exactly what they changed.
+
+### Code Changes During open/design
+
+If the current phase is still `open` or `design` but the dirty worktree already contains code changes, first attribute the changes through this protocol and do not advance the phase directly:
+
+- If the changes belong to the current change, treat them as requirements or design input and record them in proposal/design/spec/design doc/tasks as appropriate. The current phase guard must still pass before entering build.
+- If the changes do not belong to the current change or ownership is unclear, pause and ask whether to include them, split them into a new change, leave them alone, or discard them with explicit authorization.
+- Do not treat code changes made during open/design as completed implementation ready for verify.
+
+## 5. Prohibitions
+
+- Do not overwrite, revert, reformat over, or ignore user changes before understanding the dirty diff source.
+- Do not mark verification as passed while dirty diff remains unexplained.

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

@@ -0,0 +1,28 @@
+# File Structure Reference
+
+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
+├── config.yaml
+├── changes/
+│   ├── <name>/                        # Active change
+│   │   ├── .openspec.yaml
+│   │   ├── .comet.yaml
+│   │   ├── proposal.md                # Why + What
+│   │   ├── design.md                  # High-level architecture decisions
+│   │   ├── specs/<capability>/spec.md # Delta capability spec
+│   │   ├── .comet/handoff/            # Script-generated phase handoff packages
+│   │   └── tasks.md                   # Task checklist
+│   └── archive/YYYY-MM-DD-<name>/     # Archived
+└── specs/<capability>/spec.md         # Main specs (merged on archive via OpenSpec delta semantics)
+
+docs/superpowers/                      # Superpowers — HOW
+├── 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)
+
+.comet/
+└── config.yaml                        # Comet project config (context_compression defaults to off; set to beta to enable)
+```

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

@@ -0,0 +1,113 @@
+# Comet Extensions for Subagent-Driven Development
+
+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.
+
+> **⚠️ 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.
+>
+> Only stop and wait for user input when:
+> - A task is **BLOCKED** (3 review-fix rounds exhausted)
+> - 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
+>
+> 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.
+
+## Per-Task Comet Extensions
+
+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:
+
+- **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.
+- **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`.
+
+### 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`
+- 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.
+
+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.
+
+### 2. Implementer Scope Restriction
+
+The implementer is only responsible for implementation, testing, and committing code. **The implementer must not check off plan or OpenSpec tasks**, nor update only the built-in Todo or in-chat checklists.
+
+### 3. TDD Hard Constraint
+
+If `tdd_mode: tdd`, every implementer and fix agent must first use the Skill tool to load the Superpowers `test-driven-development` skill, and its prompt must also inject:
+
+```text
+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.
+
+### 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`
+- Implementation commit hash, changed files, and RED/GREEN evidence
+- Review stages already passed and unresolved reviewer feedback
+- The current task or final-review review-fix round (maximum 3)
+
+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
+
+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.
+
+### 6. Task Checkoff and Verification
+
+**After both reviews pass**, 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
+3. Commits this progress update
+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"
+```
+
+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.
+- 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 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.

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

@@ -0,0 +1,123 @@
+# 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;
+> this Rule is a universal soft defense line for all platforms.
+
+## Global Rules
+
+### Phase Awareness (Highest Priority)
+
+When there is an active comet change (`openspec/changes/<name>/.comet.yaml` exists), **before starting any operation** you must read the `phase` field to confirm the current phase.
+
+**Phases and allowed operations:**
+
+| Phase | Allowed | Prohibited |
+|-------|---------|------------|
+| `open` | Create proposal/design/tasks, run guard | Write source code |
+| `design` | brainstorming, create Design Doc, run guard | Write source code |
+| `build` | Write source code, tests, execute plans | Skip user confirmation points |
+| `verify` | Verification, branch handling | Skip failure handling |
+| `archive` | Confirm archive, run archive script | Write source code |
+### 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.
+
+| 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: archive` + `verify_result` ≠ `pass` | Skipped verify | Return to `/comet-verify` to complete verification |
+
+Exception: `workflow: hotfix/tweak` intentionally skips design, so an empty `design_doc` is normal and not an illegal jump.
+### 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:
+
+- **brainstorming** — design phase, build phase medium-scale spec changes
+- **writing-plans** — build phase creating implementation plans
+- **executing-plans** / **subagent-driven-development** — build phase execution
+- **test-driven-development** — in `executing-plans`, the main session loads it before the first task; in `subagent-driven-development`, each background implementer and fix agent loads it
+- **systematic-debugging** — when encountering crashes/test failures/build failures
+- **verification-before-completion** — verify phase
+- **using-git-worktrees** — build phase when selecting worktree isolation
+
+### Script Execution (Cannot Skip)
+
+- **Phase exit**: `comet-guard <name> <phase> --apply` (must see ALL CHECKS PASSED)
+- **Compression recovery**: `comet-state check <name> <phase> --recover`
+- **State update**: After key operations, update fields through `comet-state set`; manually editing .comet.yaml is prohibited
+- **Phase advancement only via guard/transition**: directly running `comet-state set <name> phase <value>` to jump phases is prohibited (it bypasses evidence checks and the script now hard-blocks it); use the `COMET_FORCE_PHASE=1` escape hatch only to repair a malformed state
+- **handoff generation**: `comet-handoff <name> design --write` (handwriting summaries is prohibited)
+
+### User Confirmation (Cannot Auto-Skip)
+
+The following decision points must pause to wait for explicit user selection; do not auto-fill based on recommendation rules:
+
+- **open**: Requirements clarification completion confirmation, artifact review confirmation
+- **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
+- **verify**: Verification failure handling strategy, branch handling selection
+- **archive**: Final confirmation before archiving
+
+## Design Phase Specifics
+
+1. First script operation = `comet-handoff <name> design --write` (loading brainstorming before generating handoff is prohibited)
+2. brainstorming in progress: incrementally update brainstorm-summary.md (update recovery checkpoint after each clarification round or proposal iteration; unconfirmed content marked as pending/candidate)
+3. After brainstorming completes, next step = brainstorm-summary.md finalization → Design Doc → guard
+4. active compaction gate: after brainstorm-summary.md is finalized and before creating Design Doc, prioritize triggering host platform's native context compression; when programmatic triggering is unavailable, pause to prompt user to manually compress or confirm continuing
+5. **Absolutely cannot start writing implementation code directly** — must first create Design Doc and pass guard
+
+## Build Phase Specifics
+
+1. After plan creation, must ask user to choose continue or pause (`build_pause` mechanism)
+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
+3. When encountering failures, must load **systematic-debugging** skill; do not propose source code fixes before root cause is located
+4. spec change grading: small changes edit directly | medium changes load brainstorming | large changes pause and wait for user confirmation to split
+
+## Verify Phase Specifics
+
+1. First step run `comet-state scale <name>` to determine verification level
+2. After verification fails, list failed items and wait for user selection; CRITICAL must be fixed
+3. After 3 consecutive failures, must let user choose to accept deviation or continue fixing
+
+## 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
+```
+
+Decide next step according to the script's **Recovery action** output.
+
+After recovery, first re-run the "Phase-Entry Self-Consistency Check" table: if `phase` is inconsistent with the artifacts (design_doc / three artifacts / verify_result mismatch), treat it as an illegal jump, return to the corresponding phase to fill the gap, and do not trust the `phase` field to keep going.
+
+**Special attention to `build_mode`**: If recovery script outputs `build_mode: subagent-driven-development`, you are the coordinator, not the executor. Must:
+1. Use the Skill tool to reload the Superpowers `subagent-driven-development` skill
+2. Re-read `comet/reference/subagent-dispatch.md` for Comet-specific extensions
+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
+
+## Automatic Transition After Phase Exit
+
+After guard `--apply` succeeds, do not hardcode the next skill in this rule. First run:
+
+```bash
+comet-state next <change-name>
+```
+
+If `comet-env.sh` has already located the scripts, the equivalent command is:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
+
+Decide the next step from the script output:
+
+- `NEXT: auto` → use the Skill tool to load the skill named by `SKILL`
+- `NEXT: manual` → do not load the next skill; show `HINT` so the user can continue manually
+- `NEXT: done` → the workflow is complete; no further action is needed