| name | completion-progress-recorder |
| description | 在用户提及“验收通过”“测试通过”“总结变更”“提交更改”“提交改动”“保持工作区干净”“清理工作区”“收尾记录”等表示当前需求或开发计划已完成的语义时使用。 |
完成进度记录器
目标
在开发收尾时，提交业务改动，追加或更新进度记录，并让工作区保持干净。进度记录只写需求纪要和关键决策，不写测试、构建、同步、推送等流水账。
渐进披露
默认只执行本文件。遇到以下情况时，先阅读 references/progress-audit.md 再继续：
- 仓库使用二级章节或自定义
PROGRESS 格式。
- 工作区同时存在进度文件和其他改动，需要拆分提交。
- 需要重试、去重、更新既有记录或处理格式偏差。
执行流程
- 读取仓库约定文件和相关设计/计划文档，确定进度文件路径、条目格式、需求编号规则和提交要求；未指定时使用
docs/PROGRESS.md。
- 检查
git status --porcelain。若存在进度文件以外的改动，先只提交这些业务改动，并获取该提交哈希；若工作区已干净或只有进度文件改动，则使用当前 HEAD。
- 基于需求、设计/计划文档或业务提交区间生成约 150 字简体中文纪要，重点写需求目标、实现边界、方案取舍和关键约束。
- 按仓库格式追加或更新进度记录。默认格式为
- ({hash:8}) : {YYYY.MM.dd} {content}；若仓库使用需求编号，默认格式为 - [{requirement_id}] ({hash:8}) : {YYYY.MM.dd} {content}。
- 只提交进度文件改动。提交后不得再把记录中的哈希改成进度提交自身的哈希。
- 若当前分支存在 upstream 且仓库约定和用户指令允许推送，则执行
git push；否则在最终回复中说明未推送原因。
硬性规则
PROGRESS 记录中的哈希指向本次业务改动提交或既有 HEAD，不指向记录文件自身的提交。- 未使用需求编号时，只能追加新记录，禁止修改、重排或插入历史记录中间。
- 使用需求编号时，同一编号只能有一条记录；若已存在，只更新该条记录。
- 若存在二级章节，只能追加到目标章节末尾；无法可靠判断目标章节时停止并询问用户。
- 提交信息必须遵守仓库 Conventional Commits 规则；禁止
git commit --amend。
完成校验
- 工作区干净。
- 进度记录路径、格式、位置、哈希正确。
- 没有重复记录或错误改写历史记录。
- 已推送，或最终回复说明未推送原因。
