# Dirty Worktree 协议

规范路径：`comet-classic/reference/dirty-worktree.md`

所有涉及代码修改的 Comet 子 Skill 都遵循本协议。Agent 恢复上下文或继续执行时，必须按本协议处理工作区内尚未提交的改动。各阶段可以补充自己的处理规则，例如 Verify 对实现改动的特殊要求；具体以对应子 Skill 为准，本文件不重复这些规则。

## 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 状态中显示为 `??` 的新建文件），就先考虑这些改动可能来自用户，也可能由多方共同产生
- **排除构建产物**：`??` 文件若匹配 `.gitignore` 中的模式（如 `node_modules/`、`dist/`、`__pycache__/`、`*.o`、`target/`、`build/` 等），自动跳过来源核对，不视为用户改动
- 工作区中存在代码改动，不代表可以更新 `.comet.yaml` 的 `phase` 或勾选 `tasks.md`。必须先核对来源和归属、完成验证、同步必要文档，并通过对应阶段 guard，才能推进 Comet 状态

## 3. 判断改动属于哪项工作

将未提交的改动分为三类：

1. **属于当前 change**：文件和内容能对应当前 change 的目标、tasks.md、plan 或 delta spec。将其纳入当前任务继续，不重复改同一处
2. **不属于当前 change**：文件或内容与当前目标无关。暂停并询问用户：并入当前 change、拆成新 change、保留不处理，或明确授权丢弃
3. **来源不确定**：无法从 diff 和文档判断归属。暂停并向用户汇报文件列表和判断依据，不继续推进阶段

## 4. 常见处理模式

### 已实现但 tasks.md 未勾选

先验证实现（运行构建和测试），通过后补记任务完成状态。不要因为任务未勾选就重做一遍，也不要因为状态文件尚未更新就忽略已有实现。若当前子 Skill 有该阶段的特殊要求，以子 Skill 为准。

### 发现计划或范围变化时

按当前子 skill 的升级、增量更新或回退规则处理，本协议不重复阶段特例。

### 用户没有说明具体改动时

用户说“继续”“接着跑”“我改了一点”“刚才不满意”“重新弄”“代码动过”“先按现在的来”等话，但没有说明具体改动时，按本协议处理。不要要求用户先回忆自己改了哪里。

### open/design 阶段出现代码改动

若当前仍处于 `open` 或 `design`，但工作区已经有代码改动，先按本协议核对来源和归属，不要直接推进阶段：

- 属于当前 change 的改动：作为需求或设计输入记录到 proposal/design/spec/design doc/tasks 中；进入 build 前仍需完成对应阶段 guard
- 不属于当前 change 或来源不确定：暂停询问用户是并入当前 change、拆成新 change、保留不处理，还是明确授权丢弃
- 禁止在 open/design 阶段直接把代码改动当作已完成实现并推进到 verify

## 5. 禁令

- 未查清未提交改动的来源时，不得覆盖、回滚、通过格式化重写或忽略用户改动
- 未说明清楚这些改动的来源和归属时，不得判定验证通过