completion-progress-recorder

name	completion-progress-recorder
description	在用户提及“验收通过”“测试通过”“总结变更”“提交更改”“提交改动”“保持工作区干净”“清理工作区”“收尾记录”等表示当前需求或开发计划已完成的语义时使用。

完成进度记录器

目标

在开发收尾时，提交业务改动，追加或更新进度记录，并让工作区保持干净。进度记录只写需求纪要和关键决策，不写测试、构建、同步、推送等流水账。

渐进披露

默认只执行本文件。遇到以下情况时，先阅读 references/progress-audit.md 再继续：

• 仓库使用二级章节或自定义 PROGRESS 格式。
• 工作区同时存在进度文件和其他改动，需要拆分提交。
• 需要重试、去重、更新既有记录或处理格式偏差。

执行流程

1. 读取仓库约定文件和相关设计/计划文档，确定进度文件路径、条目格式、需求编号规则和提交要求；未指定时使用 docs/PROGRESS.md。
2. 检查 git status --porcelain。若存在进度文件以外的改动，先只提交这些业务改动，并获取该提交哈希；若工作区已干净或只有进度文件改动，则使用当前 HEAD。
3. 基于需求、设计/计划文档或业务提交区间生成约 150 字简体中文纪要，重点写需求目标、实现边界、方案取舍和关键约束。
4. 按仓库格式追加或更新进度记录。默认格式为 - ({hash:8}) : {YYYY.MM.dd} {content}；若仓库使用需求编号，默认格式为 - [{requirement_id}] ({hash:8}) : {YYYY.MM.dd} {content}。
5. 只提交进度文件改动。提交后不得再把记录中的哈希改成进度提交自身的哈希。
6. 若当前分支存在 upstream 且仓库约定和用户指令允许推送，则执行 git push；否则在最终回复中说明未推送原因。

硬性规则

• PROGRESS 记录中的哈希指向本次业务改动提交或既有 HEAD，不指向记录文件自身的提交。
• 未使用需求编号时，只能追加新记录，禁止修改、重排或插入历史记录中间。
• 使用需求编号时，同一编号只能有一条记录；若已存在，只更新该条记录。
• 若存在二级章节，只能追加到目标章节末尾；无法可靠判断目标章节时停止并询问用户。
• 提交信息必须遵守仓库 Conventional Commits 规则；禁止 git commit --amend。

完成校验

• 工作区干净。
• 进度记录路径、格式、位置、哈希正确。
• 没有重复记录或错误改写历史记录。
• 已推送，或最终回复说明未推送原因。