# 闭环流程（稳定核心，编排无关）

本文件定义**与具体编排工具无关**的协作闭环。运行时调度可以用 Orca（见 `orca-adapter.md`），也可以手动跑（见下方「手动模式」）。

原则：调度消息只是运行时载体，**所有结论都必须回写到 `tasks.yaml`**（事实源），不要把消息当最终记录。

---

## 编排抽象

无论用什么工具，闭环都由这几个能力组成：

| 抽象动作 | 含义 | Orca 实现 | 手动实现 |
|----------|------|-----------|----------|
| `prepare(task)` | 把任务和验收标准写进 `tasks.yaml` | 同左 | 同左 |
| `dispatch(task, worker)` | 把任务连同上下文交给 Developer | `orca orchestration dispatch` | 复制 prompt 到 Developer 终端/会话 |
| `wait()` | 等待 `worker_done` / `escalation` / `decision_gate` | `orca orchestration check --wait` | 人工等待 Developer 回报 |
| `retest(task)` | Coordinator 独立黑盒复测 | 同左 | 同左 |
| `writeback(task, result)` | 把复测结果写回 `tasks.yaml` | 同左 | 同左 |

派发用的 prompt 见 `prompt-templates.md`。状态流转见 `roles-and-permissions.md` §「任务状态机」。

---

## 标准闭环

```text
Product/Test 发现或读取 open 任务
  -> prepare：写/补全 tasks.yaml 验收标准
  -> dispatch 给 Developer Worker
  -> wait：worker_done / escalation / decision_gate
  -> retest：Coordinator 构建并独立复测
  -> 通过：writeback verified
  -> 失败：writeback failed_retest，追加证据，最多再派发两轮
  -> 累计三轮失败：writeback leftover，继续下一个任务
```

一次派发只修一个明确问题（细则见 `optimization-method.md` §「每轮派发只修一个明确问题」）。

---

## 手动模式（无 Orca）

没有编排工具时，闭环不变，只是 `dispatch` / `wait` 由人工承担：

1. Coordinator 在 `tasks.yaml` 写好任务和验收标准。
2. 用 `prompt-templates.md` 的初始派发模板生成 prompt，手动发给 Developer（另一个会话/终端/人）。
3. Developer 完成后按 worker_done 模板回报（可直接贴回 Coordinator 会话）。
4. Coordinator 独立复测，回写 `tasks.yaml`。
5. 失败则用「复测失败再派发模板」继续，最多三轮。

手动模式下同样遵守：worker_done 不等于完成、只有 Coordinator 写 `tasks.yaml`、三轮失败留档。

---

## worker_done 后复测（编排无关）

即使 worker_done 写了"全部通过"，Coordinator 仍必须独立复测：

```bash
git status --short
<test_commands>
curl -s <base_url>/health-or-summary
```

浏览器复测建议记录：

```text
BASE_URL:
page:
steps:
expected:
actual:
snapshot evidence:
```

---

## 服务与 worktree 对齐（防假通过/假失败）

复测前记录运行环境：

```bash
pwd
git rev-parse --abbrev-ref HEAD
git rev-parse --short HEAD
```

```text
serverPid:
serverCommand:
BASE_URL:
frontendDir:
worktreePath:
```

如果开发在 `<dev_worktree>` 修复，但服务跑的是另一个 worktree，必须**停止并重启正确服务**后再测。长跑服务或静态前端尤其要确认加载的是最新构建产物。

---

## 结果回写

回写 `tasks.yaml` 时按状态填写（字段结构见 `templates/tasks.schema.json`）：

```yaml
# 通过
status: verified
resolution:
  verifiedAt: "<timestamp>"
  evidence:
    verification: "<commands passed>"
    browser: "<snapshot or API evidence>"
```

```yaml
# 失败但未满三轮
status: failed_retest
dispatch:
  rounds:
    - round: 1
      result: failed
      evidence: "<latest evidence>"
```

```yaml
# 累计三轮失败
status: leftover
resolution:
  leftoverReason: "failed after 3 supervised developer rounds"
  evidence:
    final: "<latest failing evidence>"
```