WslLoopBuild/loop-build

loop-build（Codex CLI harness）

本目录提供一套受控的长周期执行流程：PLAN -> APPROVE -> 单步 LOOP -> VERIFY -> RE-APPROVE -> 重复。

1）一次性初始化

1. 运行：

./.loop-build/scripts/init.sh

2. 阅读依赖检查结果；建议在工作树基本干净（clean）时开始任务。
3. 保留生成的 .loop-build/TASKS.md，作为任务记录模板。

2）创建任务并产出 PLAN

你需要提供：

• goal
• constraints
• repo_context_hint
• current_state_summary

随后在 Codex CLI 会话中使用 prompts/planner.md，生成严格 JSON，且 plan_steps 需为 3~7 步。

将结果写入：

./.loop-build/state/current_task.json

推荐包含字段：

• task_id、goal、constraints、plan_steps[]、success_criteria、risk_notes、required_files、verify_targets

每个 plan_step 必须包含：

• step_id
• action
• verification
• rollback
• risk_level
• expected_output

Plan 审批（强制）

未记录审批前，不要执行任何 step。

执行：

./.loop-build/scripts/run_task.sh APPROVE_PLAN

需要修改 plan 时：

./.loop-build/scripts/run_task.sh REVISE_PLAN "need narrower scope"

取消任务：

./.loop-build/scripts/run_task.sh CANCEL_TASK

run_task.sh 会读取 current_task.json，输出 plan 概览（步骤、风险、文件、验证、回滚），并等待一次性人类回复。

3）循环执行（每次只跑 1 步）

审批通过后：

./.loop-build/scripts/run_task.sh step 1

执行行为：

• 仅执行一个 plan step。
• 默认输出统一 diff（git diff 风格）。
• 仅当该 step 的 plan 指定 verification 时才执行验证。
• 向 .loop-build/state/history.ndjson 追加一条 NDJSON 记录。
• 更新 .loop-build/state/current_task.json 的 completed_steps / next_step / open_questions。
• 暂停并等待 APPROVE_NEXT，再继续下一步。

每步后再次审批

一步完成后，选择其中一个：

./.loop-build/scripts/run_task.sh APPROVE_NEXT
./.loop-build/scripts/run_task.sh REVISE_PLAN "scope too large for current diff"
./.loop-build/scripts/run_task.sh CANCEL_TASK

继续执行：

./.loop-build/scripts/run_task.sh step 2

4）验证流程

verify.sh 支持：

./.loop-build/scripts/verify.sh unit
./.loop-build/scripts/verify.sh lint
./.loop-build/scripts/verify.sh typecheck
./.loop-build/scripts/verify.sh all

手动验证时：

APPROVE=1 ./.loop-build/scripts/verify.sh unit

在 run_task.sh 的循环中，验证会经过同一套策略门禁。

5）防“代码倾泻”规则（由 prompt 与脚本共同执行）

• 默认只输出统一 diff，不输出完整文件。
• 每个 step 默认最多改动 2 个文件（超过则必须拆分 step）。
• 单步失败会自动重试，最多 2 次。
• 错误输出只保留前后关键片段，避免噪声。

6）安全策略模型

策略文件位于 .loop-build/config/：

• policy.env：开关配置和显式解锁变量。
• allowlist.txt：默认只读安全前缀（无需审批）。
• denylist.txt：默认禁止的动作，需显式解锁。

run_task.sh 执行任何命令前都会经过 check_policy（前缀匹配 + 显式解锁校验）。

默认受限动作示例：sudo、rm -rf、curl、wget、git clone、curl|bash / 下载并执行类写法。

7）示例任务

示例 1：修复一个失败测试

1. 填写 goal/constraints。
2. 生成 3~7 步 PLAN。
3. 执行 APPROVE_PLAN。
4. step 1 -> verify（如配置）。
5. APPROVE_NEXT -> step 2 -> step ...。

示例 2：小范围重构（<=2 文件）

1. 明确范围仅限文件 A/B。
2. 要求 plan step 包含 risk_level=LOW 且有回滚说明。
3. 每步独立执行，并在每个 diff 后重新审批。

示例 3：新增一个测试用例

1. Plan 应包含 fixtures/setup、断言、针对性验证。
2. 确保每步最多触及 1 个测试文件 + 1 个源码文件。
3. 步骤间重新审批以控制变更边界。

8）文件清单

• .loop-build/README.md
• .loop-build/TASKS.md
• .loop-build/state/current_task.json
• .loop-build/state/history.ndjson
• .loop-build/prompts/planner.md
• .loop-build/prompts/executor.md
• .loop-build/prompts/reviewer.md
• .loop-build/scripts/init.sh
• .loop-build/scripts/verify.sh
• .loop-build/scripts/run_task.sh
• .loop-build/scripts/apply_patch.sh
• .loop-build/scripts/snapshot.sh
• .loop-build/config/policy.env
• .loop-build/config/allowlist.txt
• .loop-build/config/denylist.txt