Skip to content

refactor: 重构提交检视与目标分支闭环 #936

Description

@CodeCasterX

问题摘要 / Issue Summary

重构提交检视与目标分支闭环

详细描述 / Detailed Description

重构任务代码提交、代码检视范围、目标分支传递、PR 创建与任务收尾之间的生命周期契约。项目配置应声明默认开发/交付目标分支,任务允许显式传入 base 分支覆盖默认值;任务分支准备阶段将交付目标作为长期意图持久化,review-code 每轮把目标 ref 解析为当时的稳定 commit,并以 merge-base 计算完整检视范围、记录稳定的 target-head/base/head 证据。code-task 每轮实现和测试完成后直接通过共享的原子 commit-operation 创建 checkpoint commit,再进入 review-code;独立 commit 技能继续保留,用于任务外或直接提交场景并自动生成 message,但不让一个 LLM 技能阅读和模拟另一个技能。Approved 后 last_reviewed_commit 必须锚定当前 HEAD,任何修复提交、rebase 或 head 漂移都使旧审查失效并要求复审。create-pr 必须复用任务中已绑定的目标分支,不得到 PR 阶段再次独立猜测。无需新增 rebase 技能;Git 拓扑足以在每轮审查动态计算 merge-base,现有或未来的分支同步能力只需正确使审查失效。同步修复此前暴露的 commit anchor 回归、沙箱跨挂载收尾失败、认证错误诊断和最终完成报告门禁,并补齐单元、集成、真实挂载拓扑及端到端测试。

相关背景 / Related Context

N/A

影响评估 / Impact Assessment

N/A

补充信息 / Additional Information

N/A

任务输入

来源

  • 用户当前请求:通过配置文件声明默认开发分支,允许手动传入 base 分支;不新增 rebase 技能;创建任务保存此前全部上下文和方案。
  • 用户前序确认:commit 技能不能删除,但可简化;code-task 最后应直接包含提交动作;commit 仍需支持任务外直接调用并自动生成 message。
  • 用户前序关注:分支引用会随其他 PR 合入而变化,检视证据必须使用稳定 commit id;需要澄清动态计算与持久化 base commit 的关系。
  • Agent 已核实的两次任务收尾与代码历史证据,以及随后提出并经用户确认方向的生命周期方案。

已确认事实与证据

  • TASK-20260830-090047 已完整收尾;TASK-20260830-090131 初次收尾留下 lifecycle=done、taskComment=pending、verification=pending,修复并重试后 receipt revision 29 全部为 done,complete-task.completed 为 10 passed, 0 failed。
  • TASK-20260830-090131 的沙箱曾执行 active 到 completed 的本地 rename,并报 EXDEV: cross-device link not permitted;active/completed 在真实沙箱中是不同挂载,临时目录测试使用同一文件系统,未覆盖该拓扑。
  • 宿主 gh 凭据无效时,请求曾表现为匿名 GitHub API rate limit;任务沙箱内一度存在有效 GH_TOKEN。该问题主要是执行环境凭据故障,同时诊断缺少明确的 auth-invalid 分类。
  • TASK-20260830-090131 完成验证还发现 last_reviewed_commit 缺失及任务评论内容不一致;最终 review snapshot tree c81d9a171969f99a937b646b610ea351532b58e2 与提交 a96a128 的 tree 相同,PR refactor(cli): 隔离历史日志与旧 archive importer  #934 head 为该提交,后以 ab1771a squash merge。
  • 当前 lib/task/commit-operation.ts 的 syncTaskCommit 只写 assigned_to,没有写 last_reviewed_commit;commit 的 verify.json 也未检查 anchor,因此提交可能错误通过完成校验。
  • 历史提交 dfee22f 曾加入 approved review 后的提交锚点行为;28750a05 曾以可恢复、幂等的 commit finalization 在 Git commit 后受锁写入 anchor;5e9e106f 简化生命周期并引入 commit-operation 时遗漏了该行为。
  • Git commit 与 task.md 状态写入无法成为一个真正的文件系统事务,只能通过 intent/receipt、锁、预期 HEAD/tree 与幂等重放形成可恢复协议。
  • 当前 .agents/.airc.json 没有默认 delivery/base branch 配置;create-pr 在较晚阶段根据 branch-strategy 推断目标分支;sandbox create 接受 base 或默认宿主当前分支,但没有把交付目标持久化到任务元数据。
  • 目标分支名是交付意图而非稳定证据;每轮审查可把目标 ref 解析为目标 head M,以 R=HEAD、D=git merge-base(R,M) 计算范围,并在审查产物记录不可变的 M/D/R。
  • 目标分支前进但任务未 rebase 时,merge-base 通常仍保持任务分叉点;任务 rebase 后 Git 拓扑会自然产生新的 merge-base,无需维护一个随 rebase 手工更新的 base_commit。
  • rebase 或任何新提交都会改变 HEAD;若 last_reviewed_commit 与 HEAD 不同,则旧审查锚点失效,必须重新执行 review-code。
  • task comment 在 finalization 状态机中因 warning projection 可能反复回到 pending,重试能够收敛,但当前用户体验不清晰;Agent 在 task-verify 通过前宣称完成属于执行/报告违规。

约束

  • 保留独立 commit 技能,并保持其可在无任务上下文时直接调用和自动生成 Conventional Commit message。
  • 生命周期上 code-task 必须包含提交,但不应让 code-task 的 LLM 去阅读、模拟或嵌套执行另一个 LLM commit 技能;二者复用确定性的 commit-operation core。
  • 默认目标分支放入项目配置;用户显式传入的 base 分支可覆盖默认配置。
  • 不新增 rebase 技能;审查范围依赖 Git 拓扑动态计算,rebase 只触发 head/审查失效语义。
  • 分支 ref 不得作为某轮检视完成的稳定证据;审查产物必须记录 commit SHA。
  • create-pr 不得重新独立推断一个可能与 review-code 不一致的目标分支,必须消费同一任务交付目标。
  • 不为假设中的旧调用方增加双写、shim 或长期兼容状态机;若确有兼容需求,需按 compatibility policy 提供消费者、期限和删除条件证据。
  • 测试不得用自然语言关键词断言 SKILL 文案,也不得为已删除概念增加反向不存在断言;跨平台守卫统一使用 tests/helpers.ts 的 onPlatforms()。
  • 沙箱收尾必须经宿主 Task Control Authority,真实跨挂载拓扑下不得回退为沙箱内直接 rename。

已确认决策

  • 用户确认:在配置文件中增加默认开发/交付目标分支。
  • 用户确认:允许调用方手动传入 base 分支覆盖默认值。
  • 用户确认:不需要额外的 rebase 技能,整体技能应通过动态 merge-base 与审查失效规则闭环。
  • 用户确认:保留并简化 commit 技能;code-task 结束时直接完成 checkpoint commit。
  • 用户确认:稳定检视依据使用 commit id,而不是随时可能更新的 base 分支指针。

候选与否决方案

  • 已否决:删除 commit 技能,只在 code-task 内实现提交;这会失去任务外直接提交和自动生成 message 的独立能力。
  • 已否决:让 code-task 的 LLM 调用并模拟完整 commit SKILL;这会产生重复的流程状态、产物和职责嵌套。
  • 已否决:在 task.md 维护一个每次 rebase 后人工更新的可变 base_commit;它容易漂移且与 Git 拓扑重复。
  • 已否决:专门新增 rebase 技能仅用于更新 base;动态 merge-base 已能从当前提交图计算审查基点。
  • 已否决:直到 create-pr 阶段才根据历史猜测目标分支;review-code 在此之前无法获得一致、可验证的检视边界。
  • Agent 候选:由集中式 task-branch prepare 边界在创建沙箱或非沙箱 code-task preflight 时解析优先级、创建任务分支并持久化 delivery remote/base ref 与不可变 branch origin。
  • Agent 候选:配置字段形态可采用 delivery.defaultBaseRef 与 delivery.remote;最终 schema 名称仍应在需求分析和方案阶段结合现有配置风格确定。
  • Agent 候选:若任务已绑定 PR,则平台 PR base 应成为权威目标;显式参数优先于项目默认;缺少任何目标时 fail closed,不在 review 阶段猜测。
  • Agent 候选:如未来需要受控分支同步,可抽取 sync-task-branch/branch-sync core 供 watch-pr 等复用,但它不是完成本闭环所必需的新技能。

验收标准

  • 给定配置中的默认目标分支且任务未显式覆盖,当任务分支准备、review-code 和 create-pr 依次执行时,三者使用同一目标分支;每轮 review 记录解析出的 target-head SHA、merge-base SHA 和 reviewed-head SHA。
  • 给定用户显式传入 base 分支,当任务创建/分支准备执行时,该值覆盖配置默认值并贯穿 review-code 与 create-pr。
  • 给定目标分支因其他 PR 合入而前进、任务分支未改变,当再次审查时,系统解析新的目标 head,但通过 merge-base 只检视当前任务相对共同祖先的完整变更,不把目标分支新增提交误算为任务改动。
  • 给定任务分支完成 rebase 或产生修复提交,当 HEAD 不再等于 last_reviewed_commit 时,create-pr/watch-pr/complete-task 不得继续沿用旧 Approved 结果,并要求重新 review-code。
  • 给定一轮 code-task 成功完成实现和测试,当进入 review-code 前,当前工作已形成唯一 checkpoint commit,code.completed 只在提交与任务状态协议闭合后成立;恢复重试不得制造重复 commit。
  • 给定无任务上下文的普通代码变更,当直接执行 commit 技能时,仍可自动生成 message 并提交,且不产生任务状态副作用。
  • 给定 Approved review,last_reviewed_commit 精确等于当轮 reviewed-head;给定 Changes Requested,不得推进该锚点。
  • 给定真实沙箱 active/completed 为不同挂载,当 complete-task 收尾时,目录转移由宿主 authority 完成且不出现 EXDEV;缺少或过期控制通道时 fail closed。
  • 给定 GitHub 凭据无效或匿名额度耗尽,诊断应区分认证无效、真实 rate limit 与网络阻塞,不得在平台验证未通过时宣称任务完成。
  • 测试覆盖 checkpoint 首轮/修复轮、恢复幂等、HEAD/tree 漂移、敏感文件与无关 dirty 文件、目标分支前进、rebase、多提交、缺失/过期/不可达 ref、PR base 一致性、lease 失败、真实挂载拓扑和 code→checkpoint→review→PR→rebase→review→complete 端到端流程。

未决事项

  • 配置字段和 task.md 字段的最终命名、remote 是否必须显式持久化,需要在需求分析阶段结合现有 schema 与多 remote 场景确认。
  • 交付目标的唯一绑定边界采用 sandbox/task branch prepare、create-task 后置步骤还是 code-task preflight,需要在方案阶段以非沙箱流程和现有控制面职责验证。
  • 任务已存在且后来绑定或改换 PR base 时,受控 retarget 的权限、审查失效与迁移边界需要明确。
  • commit-operation 的最小可恢复协议是恢复历史 intent 机制还是采用更小的 receipt/checkpoint 状态,需要结合当前锁与事件内核设计。
  • 沙箱 EXDEV 与旧容器/全局 CLI 版本漂移之间的确切责任比例仍需通过真实运行时版本一致性测试确认。

Metadata

Metadata

Assignees

Labels

in: cliModule: cliin: coreModule: corein: metaModule: meta (repo internals / CI / test infra)in: templatesModule: templatestype: enhancementA general enhancement

Type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions