aios/docs/aios-v2/adr/ADR-003-gitops-only-change-flow.md

ADR-003：所有变更必须通过 GitOps

• 状态：已采纳
• 日期：2026-07-20
• 影响范围：代码、配置、文档、测试、部署、回滚、生产修复

1. 背景

直接在生产目录、长期 worktree、主分支或运行容器中修改代码，会造成以下问题：

• 变更不可追踪；
• 无法稳定回滚；
• 本地仓库与 Gitea 不一致；
• Worktree 和 Branch Ref 冲突；
• 紧急修复无法统一审视；
• 文档、测试和部署资产无法同步。

2. 决策

所有代码、配置、文档、测试、部署和回滚资产必须经过以下流程：

非 main 分支
   -> Commit
   -> 本地仓库同步
   -> Gitea 镜像与 OID 校验
   -> 自动测试
   -> Codex 监督审查
   -> 候选集成
   -> Owner 批准
   -> Merge / Tag / Deploy

GitOps Controller worktree 必须长期保持 detached 且 clean。相同分支写入必须串行，任务工作区必须可回收。

3. 必需证据

每个任务必须记录：

• 任务 ID；
• 执行器；
• 分支；
• Commit；
• 修改文件；
• claim；
• heartbeat；
• progress；
• blocker；
• 测试命令、exit code 和结果；
• 本地/Gitea 同步状态；
• 回滚说明；
• 最终结果和监督结论。

4. 禁止事项

• 直接 push main；
• 未审批创建生产 Tag；
• 未记录任务直接修改生产；
• 在生产目录手工修复后不回写 Git；
• fetch 到已被 worktree 检出的本地 branch ref；
• 以新分支名反复规避 Worktree 生命周期缺陷；
• 在 Git 中提交明文凭据；
• 缺少文档和测试时标记为完成。

5. 备选方案

方案 A：允许紧急生产手工修改

拒绝原因：即使紧急修复也必须形成 Patch、Commit 和证据，否则无法统一审视和回滚。

方案 B：只同步本地 Bare Repo

拒绝原因：Web Gitea 无法看到真实任务进度，团队无法审查。

方案 C：Controller 长期检出任务分支

拒绝原因：会触发 refusing to fetch into branch checked out at worktree，并破坏并发任务。

6. 正面影响

• 所有变更可审计；
• 本地和 Web 远端一致；
• 紧急修复也可回滚；
• OpenClaw/Codex 进度可统一查询；
• 文档与代码可通过门禁同步。

7. 负面影响与风险

• 生产修复增加提交与证据步骤；
• GitOps Runtime 成为关键基础设施；
• 需要处理分支锁、任务恢复和镜像失败；
• 自动执行器必须遵循统一任务格式。

8. 运行规则

• Controller：detached + clean；
• Fetch：更新 remote-tracking ref，不写已检出本地 branch；
• Write：独立任务工作区或受控写入；
• Lock：同一分支串行；
• Mirror：本地成功和 Gitea 成功分别记录；
• Failure：状态标记为 degraded/blocked，不得伪报 synced。

9. 紧急 Bug 修复流程

1. 创建 patch/bugfix/*；
2. 登记 blocker 和影响；
3. 添加复现测试；
4. 修复代码；
5. 同步文档；
6. 执行验收；
7. Codex 审核；
8. Owner 批准发布；
9. 生产观察并记录结果。

10. 实现与验收映射

• GitOps 状态：active-runtime/app/aios_v2/gitops_status.py
• 健康检查：deploy/aios-v2/healthcheck/check.sh
• 回滚：deploy/aios-v2/rollback/rollback.sh
• 任务：tasks/openclaw-production-deploy-task.yaml、tasks/codex-production-supervisor-task.yaml
• 文档门禁：tools/aios_v2_docs_code_check.py