@rpamis/comet 0.2.9 → 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

@@ -32,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
 
@@ -94,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">
@@ -389,6 +399,10 @@ See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
 
 Track our development progress and upcoming features on the [Comet Roadmap](https://github.com/orgs/rpamis/projects/1).
 
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=rpamis/comet&type=Date)](https://star-history.com/#rpamis/comet&Date)
+
 ## License
 
 [MIT](LICENSE.md)

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` 修正状态，再继续判定

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

@@ -0,0 +1,58 @@
+# Dirty Worktree 协议
+
+规范路径：`comet/reference/dirty-worktree.md`
+
+本协议由所有涉及代码修改的 comet 子 skill 共享。当 agent 恢复上下文或继续执行时，必须按本协议处理未提交的工作区改动。
+
+## 1. 检查步骤
+
+继续或开始修改前，必须先运行以下命令：
+
+```bash
+git status --short
+git diff --stat
+git diff --cached --stat
+git ls-files --others --exclude-standard
+```
+
+必要时再查看 `git diff` / `git diff --cached` / 新建文件内容。
+
+## 2. 核心规则
+
+- 用户可能不会说明自己改了哪里。只要存在 dirty worktree（包括 Git 状态里显示为 `??` 的新建文件），就先假设改动可能来自用户或混合来源
+- dirty worktree 只代表代码事实，不会自动推进 `.comet.yaml` 的 `phase` 或勾选 `tasks.md`；只有完成归因、验证、同步必要文档，并通过对应阶段 guard 后，才允许推进 Comet 状态
+
+## 3. 归因分类
+
+将 dirty diff 分为三类：
+
+1. **属于当前 change**：文件和内容能对应当前 change 的目标、tasks.md、plan 或 delta spec。将其纳入当前任务继续，不重复改同一处
+2. **不属于当前 change**：文件或内容与当前目标无关。暂停并询问用户：并入当前 change、拆成新 change、保留不处理，或明确授权丢弃
+3. **来源不确定**：无法从 diff 和文档判断归属。暂停并向用户汇报文件列表和判断依据，不继续推进阶段
+
+## 4. 常见处理模式
+
+### 已实现但 tasks.md 未勾选
+
+先验证实现（运行构建和测试），通过后补勾任务。不要因为任务未勾选就重做一遍，也不要因为状态文件滞后而忽略代码事实。若当前子 skill 定义了阶段特例，以子 skill 为准。
+
+### 暗示计划或范围已变化
+
+按当前子 skill 的升级、增量更新或回退规则处理，本协议不重复阶段特例。
+
+### 模糊恢复意图
+
+用户说"继续""接着跑""我改了一点""刚才不满意""重新弄""代码动过""先按现在的来"等模糊恢复意图时，按本协议处理。不要要求用户先回忆具体改了哪里。
+
+### open/design 阶段出现代码改动
+
+若当前仍处于 `open` 或 `design`，但 dirty worktree 已经包含代码改动，先按本协议归因，不要直接推进阶段：
+
+- 属于当前 change 的改动：作为需求或设计输入记录到 proposal/design/spec/design doc/tasks 中；进入 build 前仍需完成对应阶段 guard
+- 不属于当前 change 或来源不确定：暂停询问用户是并入当前 change、拆成新 change、保留不处理，还是明确授权丢弃
+- 禁止在 open/design 阶段直接把代码改动当作已完成实现并推进到 verify
+
+## 5. 禁令
+
+- 禁止在未理解 dirty diff 来源时覆盖、回滚、格式化重写或忽略用户改动
+- 禁止在 dirty diff 未解释清楚时判定验证通过

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

@@ -158,6 +158,8 @@ Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后
 
 - **每完成一个 task**：立即勾选 tasks.md 并提交代码，确保 `.comet.yaml` 和文件状态持久化
 - **上下文压缩后恢复**：读取 `.comet.yaml` 的 `phase` 字段确认仍在 build 阶段，读取 plan 文件头的 `base-ref`，再读取 tasks.md 找到下一个未勾选任务继续执行
+- **用户手动修改恢复**：按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。该协议定义了检查步骤、归因分类和禁令。build 阶段的特殊处理：
+  1. 归因后，若 diff 暗示计划或 spec 已变化，按 Step 5「Spec 增量更新」分级处理
 - **长任务拆分**：单任务超过 200 行代码变更时，考虑拆分为多个子任务分别提交
 
 ## 退出条件

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

@@ -63,6 +63,8 @@ bash "$COMET_GUARD" <change-name> open --apply
 
 使用 hotfix 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`（除非任务 > 3 个；若超过 3 个任务，转入 `/comet-build` 的计划与执行方式选择）。
 
+继续或开始修改前，按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。若归因后发现修复范围超出 hotfix，按本文件“升级条件”处理。
+
 **立即执行：** 按 tasks.md 逐个执行任务：
 
 1. 读取 `openspec/changes/<name>/tasks.md`，获取未完成任务列表

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

@@ -66,6 +66,8 @@ bash "$COMET_GUARD" <change-name> open --apply
 
 使用 tweak 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`。
 
+继续或开始修改前，按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。若归因后发现范围超出 tweak，按本文件“升级条件”处理。
+
 **立即执行：** 按 tasks.md 逐个执行任务：
 
 1. 读取 `openspec/changes/<name>/tasks.md`，获取未完成任务列表

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

@@ -20,7 +20,7 @@ description: "Comet 阶段 4：验证与收尾。用 /comet-verify 调用。验
 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
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
@@ -30,15 +30,27 @@ bash "$COMET_STATE" check <name> verify
 执行规模评估：
 
 ```bash
-bash "$COMET_STATE" scale <name>
+bash "$COMET_STATE" scale <change-name>
 ```
 
 脚本自动统计任务数、增量规格数、变更文件数，判断使用 light 或 full 验证模式，并设置 verify_mode 字段。
 
+验证开始前，按 `comet/reference/dirty-worktree.md` 协议检查并处理未提交改动。verify 阶段的特殊处理：
+
+1. 若 dirty diff 属于当前 change 且涉及实现、测试、tasks、delta spec 或 design doc 变更，不在 verify 阶段直接修复或提交；先记录失败并回退到 build 阶段
+2. 若 dirty diff 只是 verify 本阶段产物（例如验证报告草稿、分支处理记录），可继续在 verify 阶段完成并记录状态
+3. 若 dirty diff 已实现但 tasks.md 未勾选，视为 build 状态滞后；先记录失败并回退到 build 阶段，由 `/comet-build` 验证实现、补勾任务并提交
+
+回退到 build 阶段：
+
+```bash
+bash "$COMET_STATE" transition <change-name> verify-fail
+```
+
 注意：如果 build 阶段每个任务都已提交，脚本基于工作区 diff 的文件数可能低估改动规模。此时必须读取 plan 文件头的 `base-ref` 并用提交区间复核：
 
 ```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
 若提交区间显示改动超过轻量阈值（> 5 个文件、跨模块协调、或 delta spec 超过 1 个 capability），手动设置为完整验证：
 
 ```bash
-bash "$COMET_STATE" set <name> verify_mode full
+bash "$COMET_STATE" set <change-name> verify_mode full
 ```
 
 ### 2a. 轻量验证（小改动）
@@ -54,7 +66,7 @@ bash "$COMET_STATE" set <name> verify_mode full
 当规模评估结果为"小"时，跳过 `openspec-verify-change`，直接执行以下检查：
 
 1. tasks.md 全部任务已完成 `[x]`
-2. 改动文件与 tasks.md 描述一致（`git diff --stat` 对照 tasks 内容）
+2. 改动文件与 tasks.md 描述一致（`git diff --stat` / `git diff --cached --stat` / `git diff --stat <base-ref>...HEAD` 对照 tasks 内容）
 3. 编译通过（执行项目对应的构建命令，如 `npm run build`、`mvn compile`、`cargo build` 等）
 4. 相关测试通过
 5. 无明显安全问题（无硬编码密钥、无新增 unsafe 操作）
@@ -64,7 +76,7 @@ bash "$COMET_STATE" set <name> verify_mode full
 **不通过时**：报告失败项，记录失败并回退到 build 阶段，然后调用 `/comet-build` 修复。
 
 ```bash
-bash "$COMET_STATE" transition <name> verify-fail
+bash "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **报告格式**：简表列出 5 项检查结果 + PASS/FAIL。
@@ -93,7 +105,7 @@ bash "$COMET_STATE" transition <name> verify-fail
 验证不通过时：报告缺失项，记录失败并回退到 build 阶段，然后调用 `/comet-build` 补充。
 
 ```bash
-bash "$COMET_STATE" transition <name> verify-fail
+bash "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Spec 漂移处理**：
@@ -127,8 +139,8 @@ mkdir -p docs/superpowers/reports
 # 将本次验证结论写入报告文件，例如：
 # docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
 
-bash "$COMET_STATE" set <name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
-bash "$COMET_STATE" set <name> branch_status handled
+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
 ```
 
 ## 退出条件

package/bin/comet.js

@@ -1,3 +1,3 @@
-#!/usr/bin/env node
-
-import '../dist/cli/index.js';
+#!/usr/bin/env node
+
+import '../dist/cli/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpamis/comet",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "OpenSpec + Superpowers dual-star development workflow",
   "keywords": [
     "comet",

package/scripts/postinstall.js

@@ -1,44 +1,44 @@
-#!/usr/bin/env node
-
-/**
- * Postinstall script that hints about comet init.
- *
- * The tip is suppressed when:
- * - CI=true environment variable is set
- * - COMET_NO_HINTS=1 environment variable is set
- * - dist/ directory doesn't exist (dev setup scenario)
- */
-
-import { promises as fs } from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-function shouldSkip() {
-  if (process.env.CI === 'true' || process.env.CI === '1') return true;
-  if (process.env.COMET_NO_HINTS === '1') return true;
-  return false;
-}
-
-async function distExists() {
-  try {
-    const stat = await fs.stat(path.join(__dirname, '..', 'dist'));
-    return stat.isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-async function main() {
-  try {
-    if (shouldSkip()) return;
-    if (!(await distExists())) return;
-    console.log(`\nTip: Run 'comet init' to set up Comet workflow in your project`);
-  } catch {
-    // Never break npm install
-  }
-}
-
-main().catch(() => process.exit(0));
+#!/usr/bin/env node
+
+/**
+ * Postinstall script that hints about comet init.
+ *
+ * The tip is suppressed when:
+ * - CI=true environment variable is set
+ * - COMET_NO_HINTS=1 environment variable is set
+ * - dist/ directory doesn't exist (dev setup scenario)
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function shouldSkip() {
+  if (process.env.CI === 'true' || process.env.CI === '1') return true;
+  if (process.env.COMET_NO_HINTS === '1') return true;
+  return false;
+}
+
+async function distExists() {
+  try {
+    const stat = await fs.stat(path.join(__dirname, '..', 'dist'));
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  try {
+    if (shouldSkip()) return;
+    if (!(await distExists())) return;
+    console.log(`\nTip: Run 'comet init' to set up Comet workflow in your project`);
+  } catch {
+    // Never break npm install
+  }
+}
+
+main().catch(() => process.exit(0));