ITERATION_LOOP.md

解耦迭代循环设计

1. 目的

本文件定义“一个仓库如何被逐轮解耦治理”。

目标不是一次性大改，而是通过小步、可验证、可回退的方式持续迭代：

• 每轮只处理有限范围
• 每轮都必须验证
• 每轮都必须产出报告
• 每轮都必须决定是否允许进入下一轮

2. 迭代总原则

每一轮必须遵守下面这条硬规则：

只有“通过测试 + 通过策略 + 可运行”的改动，才允许进入下一轮。

这里的三个条件缺一不可。

2.1 通过测试

至少包括：

• 本系统自身测试通过
• 目标仓库相关测试通过
• 本轮变更范围的回归测试通过

2.2 通过策略

至少包括：

• 没越过 protected paths
• 没超出允许改动范围
• 没绕过人工门禁
• 没引入被禁止的自动执行

2.3 可运行

至少包括：

• 目标仓库主入口能启动或执行
• 关键命令仍可跑通
• 没出现明显结构性损坏

3. 一轮迭代的标准输入

每轮迭代输入包括：

• 目标仓库路径
• 当前仓库快照或 commit
• 当前 artifacts
• 上一轮 human report
• 上一轮 agent report
• 当前允许改动范围

4. 一轮迭代的标准输出

每轮迭代必须产出两类输出。

4.1 给 agent 的输出

建议产物：

• iteration_agent_report.json

内容至少包含：

• 本轮范围
• 模块状态
• 通过/失败测试
• gate 结果
• 建议下一步

4.2 给人的输出

建议产物：

• iteration_human_report.md

内容至少包含：

• 这轮做了什么
• 哪些模块被分析/修改
• 测试情况
• 风险情况
• 是否允许进入下一轮

5. 标准迭代步骤

一轮完整迭代建议按 9 步执行。

Step 1. 建立基线

确认当前目标仓库的基线状态：

• 当前能否运行
• 当前测试是否通过
• 当前主要入口是什么
• 当前哪些模块最热、最脆弱

如果基线本身已不可运行，要先记录“带病基线”，后续所有结果都要和这个现实对齐。

Step 2. 诊断

运行确定性扫描与规则引擎，产出：

• 扫描 artifacts
• findings.json

这里得到的是候选问题，不是最终结论。

Step 3. 复核

由 Validator Agent 对 finding 做二次确认，产出：

• validated_findings.json

每条 finding 至少要有：

• confirmation_status
• confidence
• validation_reason

只有 confirmed 或 needs_review 的 finding 才进入后续规划。

Step 4. 缩小范围

不要对全部问题一起动手。

每轮只选择有限范围，例如：

• 一个包
• 一条高优先级规则
• 一个热点模块
• 一个明确的边界问题

Step 5. 规划

由 Planner Agent 基于 actionable findings 生成：

• triage.json
• action_plan.json

要求：

• bounded
• file-scoped
• 不自动执行
• 有 success criteria
• 有 rollback 条件

Step 6. 审查

由 Critic Agent 和 Policy Engine 一起判断计划是否合理。

必须回答的问题：

• 风险是否过高
• 范围是否过大
• 是否越过保护边界
• 是否应该补测试

产物：

• critic_review.json

Step 7. 受控执行

当前仓库还没有完全开放自动改代码，因此这一阶段的目标设计是：

• 只生成 patch plan
• 不直接改文件
• 不自动落盘

未来进入真正执行阶段后，也必须是：

• 小步执行
• 每步验证
• 每步可回退

Step 8. 验证

这是整轮最重要的门禁。

至少要验证：

• 本系统测试通过
• 目标仓库测试通过
• 策略检查通过
• 目标仓库仍可运行

任何一项失败，整轮都不能进入下一轮。

Step 9. 出报告并决定是否进入下一轮

如果通过验证，则生成：

• agent report
• human report

并明确给出一个结论：

• allow_next_iteration
• hold_for_review
• blocked

6. 什么时候允许进入下一轮

只有满足以下条件才允许：

1. 本轮变更范围清晰
2. 本轮测试通过
3. 本轮策略检查通过
4. 目标仓库仍可运行
5. 本轮产物完整
6. 人类能够理解本轮结果

7. 什么时候必须停止

出现以下任一情况，必须停止自动推进：

• 新改动导致目标仓库不可运行
• 测试失败
• policy 阻断
• Critic 标记为高风险且未复核
• 本轮结果无法解释
• 模块边界不清，导致无法定义安全范围

8. “复现这个仓库” 的定义

这里的“复现”不是指重新写一个一模一样的新仓库，而是指：

• 能完成安装
• 能运行主入口
• 能执行关键命令
• 能通过核心测试
• 能理解关键模块职责
• 能解释关键依赖关系

也就是说，目标状态是：

可运行、可理解、可维护、可验证。

9. 推荐的门禁实现

建议最终把 gate 固化成三个明确阶段。

Gate A. 测试门禁

包括：

• 单元测试
• 金标测试
• 目标仓库回归测试

Gate B. 策略门禁

包括：

• protected path 检查
• 变更范围检查
• 禁止自动执行检查

Gate C. 运行门禁

包括：

• 主入口启动
• 最小 smoke run
• 关键命令可执行

只有 A + B + C 都通过，才写入“允许下一轮”。

10. 当前实现与目标实现的关系

当前仓库已经覆盖了：

• 诊断
• finding 复核
• triage
• action plan
• critic review
• LLM health check
• summary + artifacts 输出

未来还需要补：

• 目标仓库运行验证器
• 受控 patch plan executor
• 模块级双测试报告产物
• 每轮迭代状态管理
• stop/resume 机制

11. 推荐的迭代节奏

建议按“小步可回归”推进。

推荐节奏：

1. 先盯一个模块或一个规则
2. 先做金标与回归
3. 再做调整
4. 调整后马上跑 gate
5. 通过后再进入下一轮

不建议：

• 一次跨太多目录
• 一次改太多文件
• 在没有基线测试时推进
• 让 agent 连续多轮自动写代码

12. 一句话总结

解耦迭代不是“连续重构直到看起来更干净”，而是：

每一轮都可验证、可解释、可回退，并且只有通过测试、策略和运行门禁后，才允许继续推进的受控工程循环。