@rpamis/comet 0.2.8 → 0.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 rpamis
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 rpamis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,9 +8,11 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/rpamis/comet/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/rpamis/comet/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="https://github.com/rpamis/comet/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/rpamis/comet/ci.yml?branch=master&style=flat-square&label=CI" /></a>
+  <a href="https://deepwiki.com/rpamis/comet"><img alt="DeepWiki" src="https://img.shields.io/badge/DeepWiki-rpamis%2Fcomet-blue?style=flat-square" /></a>
   <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm version" src="https://img.shields.io/npm/v/@rpamis/comet?style=flat-square" /></a>
   <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm download count" src="https://img.shields.io/npm/dm/@rpamis/comet?style=flat-square&label=Downloads/mo" /></a>
+  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm weekly download count" src="https://img.shields.io/npm/dw/@rpamis/comet?style=flat-square&label=Downloads/wk" /></a>
   <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
 </p>
 
@@ -30,7 +32,11 @@
 
 **OpenSpec + Superpowers dual-star development workflow** — one command from idea to archive.
 
-OpenSpec handles **WHAT** (outlines, proposals, spec lifecycle, archiving). Superpowers handles **HOW** (technical design, planning, execution, wrap-up). Comet chains both into a five-phase automated pipeline.
+OpenSpec handles **WHAT** (outlines, proposals, spec lifecycle, archiving). 
+
+Superpowers handles **HOW** (technical design, planning, execution, wrap-up). 
+
+Comet chains both into a five-phase automated pipeline.
 
 ## Why Comet
 
@@ -42,6 +48,28 @@ Superpowers generates Spec documents after brainstorming, but these documents ty
 
 The main entry `/comet` supports current Spec state detection, suitable for long tasks — after completing and closing CC midway, just `/comet continue` and Comet will automatically read the active Spec (lists multiple for selection), dynamically identify which phase is currently executing, and continue.
 
+At the same time, Comet provides full Spec lifecycle management. During execution, it links OpenSpec change/spec artifacts with Superpowers design and planning documents, then automates handoff, state updates, validation, and archive sync so users do not have to repeatedly remind the Agent to keep documents synchronized and connected.
+
+## What You'll Learn
+
+Many excellent Skill projects exist in the current Skill market, but they generally have preference issues — users may only like some features. For example, when using both OpenSpec and Superpowers, one might only use OpenSpec's Spec management capabilities, but prefer Superpowers' TDD-driven approach for coding.
+
+Long-term Skill users know these capabilities can be freely combined, but exactly how to do so still requires real practice. The Comet project can serve as a reference:
+
+- **How to reliably trigger nested Skills** — Not letting the Agent rely on document descriptions to perform "look-alike Skill trigger" operations (like writing files based on Skill descriptions), but truly triggering Skills (key feature: Skill trigger prints on CC). Comet triggers many capabilities from OpenSpec and Superpowers. How is this Prompt written?
+
+- **How to make combined Skills flow automatically across phases** — Not relying on manual intervention. Comet's 5-phase flow can automatically trigger Skills for the core process except for necessary user choices, while the state machine also protects state transition reliability.
+
+- **How to turn the Spec lifecycle into a resumable workflow** — Comet links OpenSpec change/spec artifacts with Superpowers design and planning documents, then records phase, execution mode, verification results, and archive status in `.comet.yaml`, so the Agent can resume after interruption instead of rereading documents and guessing progress.
+
+- **How to turn document synchronization from "user reminders" into automation** — Comet puts handoff, state updates, validation, and archive sync into scripted flows, reducing repeated prompts like "remember to update the design doc", "remember to sync the spec", and "remember to archive the change".
+
+- **How to design guard conditions that Agents can execute** — Comet does not simply trust the Agent saying "done" at phase exits. Scripts such as `comet-guard.sh`, `comet-yaml-validate.sh`, and `comet-state.sh` check tasks, state fields, verification evidence, and archive conditions before allowing the workflow to advance.
+
+- **How to distribute and install Skills across platforms** — Comet supports multiple AI coding platforms, project/global installation, Chinese/English Skill choices, and platform-specific directory differences such as Antigravity using different project-level and global paths. It can be a reference for CLI installers and Skill package structure.
+
+- **How to turn shell scripts into Agent workflow infrastructure** — Comet's scripts need to work across macOS, Linux, and Windows Git Bash while handling hashes, YAML fields, state machines, and archive flows. It shows how to move fragile workflow control out of scattered Prompt text and into testable, reusable tools.
+
 ## Install
 
 ```bash
@@ -70,6 +98,12 @@ comet init
 >
 > `comet update` or `npm install -g @rpamis/comet@latest` to get the latest features and fixes.
 
+## Support for OpenClaw and Hermes, and other AI platforms
+
+```bash
+npx skills add rpamis/comet
+```
+
 ## Screenshots
 
 <p align="center">
@@ -81,16 +115,10 @@ comet init
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `comet init [path]` | Initialize Comet workflow |
-| `comet status [path]` | Show active changes, task progress, and next workflow command |
-| `comet doctor [path]` | Diagnose project/global Comet installation health |
-| `comet update [path]` | Update the npm package and installed Comet skills |
-| `comet --help` | Show help |
-| `comet --version` | Show version |
+<details>
+<summary><code>comet init [path]</code> — Initialize Comet workflow</summary>
 
-### init Options
+Initializes OpenSpec, Superpowers, and Comet skills for selected AI coding platforms.
 
 | Option | Description |
 |--------|-------------|
@@ -102,20 +130,35 @@ comet init
 
 When multiple existing components are found on the same platform, interactive init offers one bulk choice: overwrite all, skip all, or choose per component.
 
-### status Options
+</details>
+
+<details>
+<summary><code>comet status [path]</code> — Show active changes and next workflow command</summary>
+
+Displays active changes, task progress, and the recommended next Comet workflow command.
 
 | Option | Description |
 |--------|-------------|
 | `--json` | Output active changes with `nextCommand` |
 
-### doctor Options
+</details>
+
+<details>
+<summary><code>comet doctor [path]</code> — Diagnose Comet installation health</summary>
+
+Checks project/global installation health, working directories, installed skills, scripts, and Comet state files.
 
 | Option | Description |
 |--------|-------------|
 | `--json` | Output structured diagnostic results |
 | `--scope <scope>` | Diagnose `auto`, `project`, or `global` scope (default: `auto`) |
 
-### update Options
+</details>
+
+<details>
+<summary><code>comet update [path]</code> — Update Comet package and skills</summary>
+
+Updates the npm package and refreshes installed Comet skills in detected project/global targets.
 
 | Option | Description |
 |--------|-------------|
@@ -123,10 +166,20 @@ When multiple existing components are found on the same platform, interactive in
 | `--language <lang>` | Override detected skill language (`en`, `zh`) |
 | `--scope <scope>` | Update only `global` or `project` scope |
 
+</details>
+
+| Command | Description |
+|---------|-------------|
+| `comet --help` | Show help |
+| `comet --version` | Show version |
+
 ## Supported Platforms
 
 `comet init` supports 28 AI coding platforms:
 
+<details>
+<summary>View full platform list</summary>
+
 | Platform | Skills Dir | Platform | Skills Dir |
 |----------|-----------|----------|-----------|
 | Claude Code | `.claude/` | Cursor | `.cursor/` |
@@ -141,15 +194,20 @@ When multiple existing components are found on the same platform, interactive in
 | CoStrict | `.cospec/` | Crush | `.crush/` |
 | Factory Droid | `.factory/` | iFlow | `.iflow/` |
 | Pi | `.pi/` | Qoder | `.qoder/` |
-| Antigravity | `.agent/` | Bob Shell | `.bob/` |
+| Antigravity | `.agents/` | Bob Shell | `.bob/` |
 | ForgeCode | `.forge/` | Trae | `.trae/` |
 
+</details>
+
 ## Skills
 
 After `comet init`, three groups of skills are installed to the selected platform's `skills/` directory:
 
 ### Comet Skills
 
+<details>
+<summary>View Comet skills</summary>
+
 | Skill | Description |
 |-------|-------------|
 | `/comet` | Main entry — auto-detects phase and dispatches to sub-commands |
@@ -161,8 +219,13 @@ After `comet init`, three groups of skills are installed to the selected platfor
 | `/comet-hotfix` | Preset: Quick bug fix (skips brainstorming) |
 | `/comet-tweak` | Preset: Small change (skips brainstorming and full plan) |
 
+</details>
+
 ### Guard & Automation Scripts
 
+<details>
+<summary>View script list</summary>
+
 | Script | Purpose |
 |--------|---------|
 | `comet-guard.sh` | Phase transition guard — validates exit conditions, `--apply` auto-updates `.comet.yaml` |
@@ -171,6 +234,8 @@ After `comet init`, three groups of skills are installed to the selected platfor
 | `comet-yaml-validate.sh` | Schema validator — validates `.comet.yaml` structure and field values |
 | `comet-state.sh` | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface |
 
+</details>
+
 ### OpenSpec Skills
 
 Spec lifecycle management: propose, explore, sync, verify, archive, and more.
@@ -221,6 +286,11 @@ Comet uses a decoupled state architecture with separate YAML files:
 | `.openspec.yaml` | OpenSpec | Spec lifecycle, change metadata |
 | `.comet.yaml` | Comet | Workflow phase, execution mode, verification status |
 
+All states and execution phases are updated via scripts, and each phase verifies that tasks are truly complete before advancing. Compared to storing complex state rules only in Skill text, this script-backed state machine gives Comet more reliable phase transitions, correct YAML, and easier breakpoint recovery; agents can read the current Spec situation through Comet's built-in commands.
+
+<details>
+<summary>View key .comet.yaml fields</summary>
+
 **Key Fields in `.comet.yaml`:**
 
 ```yaml
@@ -245,12 +315,15 @@ handoff_hash: <sha256>
 
 In full workflow, `build_mode`, `isolation`, and `verify_mode` may temporarily be `null`; `build_mode` and `isolation` must be resolved before `build → verify`. `verification_report` stays `null` until verification writes a report, and `verify-pass` requires that report to exist plus `branch_status: handled`. Fields after `archived` in the example are optional or script-derived: `direct_override` is only needed for full-workflow direct builds, project commands may be absent unless configured, and `handoff_context` / `handoff_hash` are recorded by `comet-handoff.sh` before leaving design. Projects can configure `build_command` / `verify_command` in the change or repo root, and guard will run those commands first and print failure output.
 
-All states and execution phases are updated via scripts, and **each phase verifies that tasks are truly completed before exiting — conditions are met before the phase exits and state is updated**. Compared to recording complex state management mechanisms in Skills, the script approach strongly guarantees the reliability of core state transitions, correctness of YAML files, and convenience of breakpoint recovery — Agents only need to use Comet's built-in commands to read state and know the current Spec's situation.
+</details>
 
 ### Reliability Features
 
 Comet ensures agent execution reliability through automated state transitions:
 
+<details>
+<summary>View reliability features</summary>
+
 1. **Entry Verification** — Each phase validates preconditions before execution
    - Checks file existence, state consistency, and phase transitions
    - Outputs `[HARD STOP]` with actionable suggestions if validation fails
@@ -284,7 +357,7 @@ Comet ensures agent execution reliability through automated state transitions:
    - Moves change to archive directory and updates `archived: true`
    - Supports `--dry-run` for preview
 
-**Security**: Path traversal protection on all change name inputs
+</details>
 
 ## Project Structure
 
@@ -316,55 +389,19 @@ your-project/
     └── plans/                   # Implementation plans
 ```
 
-## What You'll Learn
-
-Many excellent Skill projects exist in the current Skill market, but they generally have preference issues — users may only like some features. For example, when using both OpenSpec and Superpowers, one might only use OpenSpec's Spec management capabilities, but prefer Superpowers' TDD-driven approach for coding.
-
-Long-term Skill users know these capabilities can be freely combined, but exactly how to do so still requires real practice. The Comet project can serve as a reference:
-
-- **How to reliably trigger nested Skills** — Not letting the Agent rely on document descriptions to perform "look-alike Skill trigger" operations (like writing files based on Skill descriptions), but truly triggering Skills (key feature: Skill trigger prints on CC). Comet will trigger many capabilities from OpenSpec and Superpowers — how is this Prompt written?
-
-- **How to make combined Skills multi-phase auto-flow** — Not relying on manual intervention. Comet's 5-phase flow automatically triggers Skills for core processes except necessary user selections, while the **state machine mechanism** also ensures state transition reliability.
-
 ## Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, commit conventions, PR process, and guidance for adding platforms or skills.
 
-```bash
-# Clone
-git clone https://github.com/rpamis/comet
-cd comet
-
-# Install dependencies
-pnpm install
-
-# Dev mode (watch)
-pnpm dev
-
-# Build
-pnpm build
-
-# Test (unit + coverage)
-pnpm test
-pnpm test:coverage
-pnpm test:shell         # bats shell tests
-
-# Lint & format
-pnpm lint
-pnpm format
-```
-
 See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
 
 ## Roadmap
 
 Track our development progress and upcoming features on the [Comet Roadmap](https://github.com/orgs/rpamis/projects/1).
 
-## Security
+## Star History
 
-- Pre-publish scan for API keys, secrets, tokens, and private keys
-- `.npmignore` prevents source code and config files from entering the npm package
-- `.gitignore` covers secrets, credentials, IDE configs, and more
+[![Star History Chart](https://api.star-history.com/svg?repos=rpamis/comet&type=Date)](https://star-history.com/#rpamis/comet&Date)
 
 ## License
 

package/assets/manifest.json

@@ -2,6 +2,7 @@
   "version": "0.2.6",
   "skills": [
     "comet/SKILL.md",
+    "comet/reference/dirty-worktree.md",
     "comet/scripts/comet-guard.sh",
     "comet/scripts/comet-state.sh",
     "comet/scripts/comet-handoff.sh",

package/assets/skills/comet/SKILL.md

@@ -22,13 +22,19 @@ Agents need only read this section for decision-making. Refer to the Reference A
 
 ### Automatic Phase Detection
 
-**Step 0: Active Change Discovery**
+**Step 0: Active Change Discovery and Intent Detection**
 
-1. Run `openspec list --json` to get all active changes
+1. Detect presets first; if hotfix/tweak matches, invoke the corresponding preset skill directly and do not enter the normal open branch
+2. When no preset matches, run `openspec list --json` to get all active changes
+
+**Preset detection has highest priority**:
+- User explicitly describes a bug fix / hotfix + meets hotfix conditions → directly invoke `/comet-hotfix`
+- User explicitly describes copy/config/docs/prompt small adjustment + meets tweak conditions → directly invoke `/comet-tweak`
+- No preset match → follow the table below
 
 | Active changes | User input | Behavior |
 |----------------|------------|----------|
-| None | any | → Invoke `/comet-open` |
+| None | non-preset input | → Invoke `/comet-open` |
 | Exactly 1 | `/comet <description>` | → **Ask**: continue this change or create a new change |
 | Multiple | `/comet <description>` | → **Ask**: continue existing or create new; if continuing, list changes for selection |
 | Exactly 1 | `/comet` with no description | → Auto-select, enter Step 1 |
@@ -40,16 +46,13 @@ When the user chooses "create a new change", **must invoke `/comet-open`**. Do n
 Calling `/opsx:new` directly leaves `.comet.yaml` missing and breaks later phase detection.
 </IMPORTANT>
 
-**Preset detection**:
-- User describes as bug fix / hotfix + meets hotfix conditions → directly invoke `/comet-hotfix`
-- User describes as copy, config, docs, prompt or small non-bug adjustment + meets tweak conditions → directly invoke `/comet-tweak`
-
 **Step 1: Read `.comet.yaml` state metadata**
 
 Prefer reading `openspec/changes/<name>/.comet.yaml`. If not available, fall back to `openspec status --change "<name>" --json`, `tasks.md`, and `docs/superpowers/` file checks.
 
 **Resume rules**:
 - On every context resume, rerun Step 0 and Step 1; do not trust conversation history for phase detection
+- If there is an active change and the worktree has uncommitted changes, handle them through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions; this file does not repeat them
 - If `phase: build`, read the next unchecked task from tasks.md and continue
 - If `phase: verify` and `verify_result: fail`, first run `bash "$COMET_STATE" transition <name> verify-fail`, then invoke `/comet-build`
 - If `phase: open` but proposal/design/tasks are complete, run `bash "$COMET_GUARD" <change-name> open --apply` to repair state, then continue detection

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

@@ -0,0 +1,58 @@
+# 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.
+- 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-build/SKILL.md

@@ -158,6 +158,8 @@ Build is the longest phase and may span many tasks. To support resume after cont
 
 - **After each task**: immediately check off tasks.md and commit code so `.comet.yaml` and file state are durable
 - **After context compaction**: read `.comet.yaml` to confirm the phase is still build, read the plan header `base-ref`, then read tasks.md to find the next unchecked task
+- **User manual-change resume**: handle uncommitted changes through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions. Build-specific handling:
+  1. After attribution, if the diff implies plan or spec changes, handle it through Step 5 "Spec Incremental Updates"
 - **Long task split**: if a single task exceeds 200 lines of code changes, consider splitting it into multiple subtasks and commits
 
 ## Exit Conditions

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

@@ -47,6 +47,12 @@ Initialize Comet state file:
 bash "$COMET_STATE" init <name> hotfix
 ```
 
+Verify initialized state:
+
+```bash
+bash "$COMET_STATE" check <name> open
+```
+
 Run phase guard to transition open → build:
 
 ```bash
@@ -57,6 +63,8 @@ bash "$COMET_GUARD" <change-name> open --apply
 
 Use hotfix defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and `superpowers:writing-plans` (unless tasks > 3; if exceeds 3 tasks, transfer to `/comet-build`'s plan and execution method selection).
 
+Before continuing or starting changes, handle uncommitted changes through `comet/reference/dirty-worktree.md`. If attribution shows the fix scope exceeds hotfix, handle it through this file's "Upgrade Conditions".
+
 **Immediately execute:** Execute tasks one by one according to tasks.md:
 
 1. Read `openspec/changes/<name>/tasks.md`, get incomplete task list

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

@@ -50,6 +50,12 @@ Initialize Comet state file:
 bash "$COMET_STATE" init <name> tweak
 ```
 
+Verify initialized state:
+
+```bash
+bash "$COMET_STATE" check <name> open
+```
+
 Run phase guard to transition open → build:
 
 ```bash
@@ -60,6 +66,8 @@ bash "$COMET_GUARD" <change-name> open --apply
 
 Use tweak defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and `superpowers:writing-plans`.
 
+Before continuing or starting changes, handle uncommitted changes through `comet/reference/dirty-worktree.md`. If attribution shows the scope exceeds tweak, handle it through this file's "Upgrade Conditions".
+
 **Immediately execute:** Execute tasks one by one according to tasks.md:
 
 1. Read `openspec/changes/<name>/tasks.md`, get incomplete task list

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

@@ -20,7 +20,7 @@ Execute entry verification:
 COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
 COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
 COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
-bash "$COMET_STATE" check <name> verify
+bash "$COMET_STATE" check <change-name> verify
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -30,15 +30,27 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 Execute scale assessment:
 
 ```bash
-bash "$COMET_STATE" scale <name>
+bash "$COMET_STATE" scale <change-name>
 ```
 
 Script automatically counts tasks, delta specs, and changed files to determine whether to use light or full verification mode, and sets the verify_mode field.
 
+Before verification starts, inspect and handle uncommitted changes through `comet/reference/dirty-worktree.md`. Verify-specific handling:
+
+1. If dirty diff belongs to the current change and involves implementation, tests, tasks, delta spec, or design doc changes, do not fix or commit directly in verify; record failure and return to build
+2. If dirty diff is only a verify-phase artifact, such as a verification report draft or branch-handling record, continue in verify and record state
+3. If dirty diff has implemented work but tasks.md is unchecked, treat it as stale build state; record failure and return to build so `/comet-build` verifies the implementation, checks off tasks, and commits
+
+Return to build:
+
+```bash
+bash "$COMET_STATE" transition <change-name> verify-fail
+```
+
 Note: if the build phase committed after each task, worktree diff can underestimate change size. In that case, read the plan header `base-ref` and re-check the full commit range:
 
 ```bash
-PLAN=$(bash "$COMET_STATE" get <name> plan)
+PLAN=$(bash "$COMET_STATE" get <change-name> plan)
 BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
 git diff --stat "$BASE_REF"...HEAD
 ```
@@ -46,7 +58,7 @@ git diff --stat "$BASE_REF"...HEAD
 If the commit range exceeds lightweight thresholds (> 5 files, cross-module coordination, or more than 1 delta spec capability), manually switch to full verification:
 
 ```bash
-bash "$COMET_STATE" set <name> verify_mode full
+bash "$COMET_STATE" set <change-name> verify_mode full
 ```
 
 ### 2a. Lightweight Verification (Small Changes)
@@ -54,7 +66,7 @@ bash "$COMET_STATE" set <name> verify_mode full
 When scale assessment result is "small", skip `openspec-verify-change`, directly execute the following checks:
 
 1. All tasks in tasks.md completed `[x]`
-2. Changed files consistent with tasks.md description (compare `git diff --stat` against task content)
+2. Changed files consistent with tasks.md description (compare `git diff --stat` / `git diff --cached --stat` / `git diff --stat <base-ref>...HEAD` against task content)
 3. Build passes (run project-appropriate build command, e.g., `npm run build`, `mvn compile`, `cargo build`)
 4. Related tests pass
 5. No obvious security issues (no hardcoded secrets, no new unsafe operations)
@@ -64,7 +76,7 @@ When scale assessment result is "small", skip `openspec-verify-change`, directly
 **When failing**: report failed items, record failure, move back to build, then invoke `/comet-build`.
 
 ```bash
-bash "$COMET_STATE" transition <name> verify-fail
+bash "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Report format**: Brief table listing 5 check results + PASS/FAIL.
@@ -93,7 +105,7 @@ After the skill loads, follow its guidance to verify. Check items:
 When verification fails: report missing items, record failure, move back to build, then invoke `/comet-build`.
 
 ```bash
-bash "$COMET_STATE" transition <name> verify-fail
+bash "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Spec drift handling**:
@@ -118,10 +130,25 @@ After the skill loads, follow its guidance to complete. Branch handling options:
 - All tests pass
 - No hardcoded secrets or security issues
 
+### 4. Record Verification Evidence
+
+The verification report must be written to disk and recorded in `.comet.yaml`; branch handling must also be written to state after it completes. Do not manually set `verify_result: pass`; guard performs the transition.
+
+```bash
+mkdir -p docs/superpowers/reports
+# Write this verification result to a report file, for example:
+# docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+
+bash "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+bash "$COMET_STATE" set <change-name> branch_status handled
+```
+
 ## Exit Conditions
 
 - Verification report passed
 - Branch handled
+- `.comet.yaml` `verification_report` points to an existing verification report file
+- `.comet.yaml` has `branch_status: handled`
 - **Phase guard**: Run `bash "$COMET_GUARD" <change-name> verify --apply`; after all PASS, it uses `comet-state transition verify-pass` to advance to `phase: archive`
 
 After verification and branch handling are complete, run guard to auto-transition:

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

@@ -52,6 +52,7 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 **断点恢复规则**：
 - 每次恢复上下文时，先重新执行 Step 0 和 Step 1，不依赖对话历史判断阶段
+- 只要存在 active change 且工作区有未提交改动，必须按 `comet/reference/dirty-worktree.md` 协议处理。该协议定义了检查步骤、归因分类和禁令，本文件不重复
 - 若 `phase: build`，读取 tasks.md 的下一个未勾选任务继续
 - 若 `phase: verify` 且 `verify_result: fail`，先运行 `bash "$COMET_STATE" transition <name> verify-fail`，再调用 `/comet-build`
 - 若 `phase: open` 但 proposal/design/tasks 已完整，先运行 `bash "$COMET_GUARD" <change-name> open --apply` 修正状态，再继续判定