用途:iterate-cr 用于在变更请求(CR)实现完成后进行最后一公里迭代,把“大致正确”的交付结果调整到“确实想要”的行为。规范先于代码存在,因此差距需要通过人机交互循环来弥合。
调用方式:/iterate-cr 不带参数时开启一个不关联任何 CR 的探索会话;/iterate-cr CR-XXXX 针对指定 CR 开启或恢复会话;/iterate-cr CR-XXXX CR-YYYY 覆盖多个命名 CR。没有关闭或状态子命令——台账是受 Git 跟踪的文档,会话内容在文件中,落地时间在 git log 中。将会话结果纳入治理由单独的 /reconcile-cr 步骤完成。每个命名的 CR 必须能解析到 docs/cr/{CR_ID}-*.md 的既有文档,不存在隐式的“当前会话”。
滚动前进模型:保留是隐式的(留在工作树中的改动即成立,无需裁决);取代是显式的(新条目点名其所取代的旧条目并说明理由,旧条目不编辑、不重写、不删除);当前状态是推导出来的,通过从条目向前读取并遵循取代关系得到,重新生成派生摘要不违反只追加规则。
角色分工:用户发起会话、指明每次尝试内容并控制节奏;智能体实施代码修改、运行项目检查,并作为副产品写入台账条目和提交,不单独收集裁决。会话只能由用户显式发起,不得自动或由实现流水线创建。
工作流程:1) 解析并校验被覆盖的 CR,任一标识无法解析即拒绝并停止,不创建台账;无标识则为探索会话。2) 创建或恢复台账:查找覆盖所命名 CR 的开放台账(crs: 列出全部命名 CR 且 frontmatter 无 reconciled:),若多个匹配则拒绝并列出,不猜测;若唯一匹配则恢复;若唯一匹配但已带 reconciled: 则不得追加,需告知用户另开新会话;若不存在则从模板创建。恢复时通过重hydration流程无额外提问地重建状态,并先报告当前有效内容与被取代方案。3) 循环:用户指示→智能体修改并运行检查→追加台账条目(改了什么、为何尝试、证据、归属 CR 或 none)并创建提交→等待下一指示。会话在用户停止时结束,无需关闭仪式。会话不对自身台账做任何提炼或结论。
提交协议:每次变更通过 /checkpoint-commit 持续提交,使用带后缀的 scope(checkpoint(CR-XXXX-iterate) 或 checkpoint(iterate-{slug})),携带 Iteration: {slug} trailer,正文以要点复述变更、理由与证据。代码与证据必须原子提交,同一提交中包含对应台账条目;只暂存变更涉及的路径与台账,不得暂存整个工作树。
重hydration 与并发:上下文中断后,重新以相同调用方式打开会话,依次运行 /checkpoint-read、读取所有覆盖 CR 与完整台账(含被取代条目)、按 scope/trailer 查询提交、对比工作树与最后提交并报告恢复状态;不得在未说明原因的情况下重新提出已被取代的方案。并发方面,每个工作树只能有一个活跃会话,第二个会话应使用独立 Git worktree(由用户创建),台账记录其打开时的工作树,若在异于记录的工作树中恢复必须检测并报告。
安全规则:禁止破坏性 Git 操作(reset、rebase、commit --amend、push --force);回退仅限于工作树;不得对文档不存在的 CR 开会话;不得向已 reconciled 的台账追加;多个开放台账匹配时拒绝并列明;不得编辑、重写或删除被取代的早期条目。台账位于 docs/cr/ 下,可自由引用其覆盖的 CR,但条目不得触及项目常设指令。