# loop-build（Codex CLI harness）

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

## 1）一次性初始化

1. 运行：

```bash
./.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 步。

将结果写入：

```bash
./.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`。

执行：

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

需要修改 plan 时：

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

取消任务：

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

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

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

审批通过后：

```bash
./.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`，再继续下一步。

### 每步后再次审批

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

```bash
./.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
```

继续执行：

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

## 4）验证流程

`verify.sh` 支持：

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

手动验证时：

```bash
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`