feat: support dirty worktree recovery

Author: benym

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to @rpamis/comet will be documented in this file.
 
+## What's Changed [0.3.0] - 2026-05-25
+
+### Added
+
+- **Dirty worktree recovery protocol**: Added shared English and Chinese `comet/reference/dirty-worktree.md` references so agents consistently protect, inspect, and attribute user or mixed-source working tree changes during resume
+
+### Changed
+
+- **Comet resume behavior**: Updated `/comet`, build, verify, hotfix, and tweak skills so manual code edits made during interruptions are treated as code evidence, not automatic state transitions; agents must attribute dirty worktree changes before continuing or advancing guards
+
+### Fixed
+
+- **Reference skill installation**: Added the dirty worktree reference file to the Comet manifest so installed English and Chinese skill sets can resolve `comet/reference/dirty-worktree.md`
+
 ## What's Changed [0.2.9] - 2026-05-24
 
 ### Changed

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",

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 行代码变更时，考虑拆分为多个子任务分别提交
 
 ## 退出条件

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`，获取未完成任务列表

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`，获取未完成任务列表

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,31 +30,43 @@ 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
 ```
 
 若提交区间显示改动超过轻量阈值（> 5 个文件、跨模块协调、或 delta spec 超过 1 个 capability），手动设置为完整验证：
 
 ```bash
-bash "$COMET_STATE" set <name> verify_mode full
+bash "$COMET_STATE" set <change-name> verify_mode full
 ```
 
 ### 2a. 轻量验证（小改动）
 
 当规模评估结果为"小"时，跳过 `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
 ```
 
 ## 退出条件

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

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 未解释清楚时判定验证通过

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

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