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

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

原则：调度消息只是运行时载体，所有结论都必须回写到 tasks.yaml（事实源），不要把消息当最终记录。角色定义见 roles-and-permissions.md：Coordinator 只编排、Test 只验证、Developer 只实现。

编排抽象

无论用什么工具，闭环都由这几个能力组成。注意 dispatch 有两个目标（Developer 与 Test）：

抽象动作	含义	Orca 实现	手动实现
`prepare(task)`	Coordinator 把任务和验收信号写进 `tasks.yaml`	同左	同左
`dispatch(task, developer)`	把修复任务连同上下文交给 Developer	`orca orchestration dispatch`	复制 prompt 到 Developer 终端/会话
`dispatch(task, test)`	把复测任务连同验收信号交给 Test	`orca orchestration dispatch`	复制 prompt 到 Test 终端/会话
`wait()`	等待 `worker_done` / `retest_result` / `escalation` / `decision_gate`	`orca orchestration check --wait`	人工等待回报
`gate(task)`	Coordinator 读 Test 证据并对齐原始意图（不重测）	同左	同左
`writeback(task, result)`	Coordinator 把结果写回 `tasks.yaml`	同左	同左

派发用的 prompt 见 prompt-templates.md。状态流转见 roles-and-permissions.md §「任务状态机」。独立复测由 Test 执行，不是 Coordinator；Coordinator 只做读证据的终检。

标准闭环

Coordinator 发现或读取 open 任务
  -> prepare：写/补全 tasks.yaml 验收信号
  -> dispatch 给 Developer
  -> wait：Developer 的 worker_done / escalation
  -> writeback fixed_by_dev
  -> dispatch 给 Test（retesting）
  -> wait：Test 的 retest_result
  -> Test 通过：gate（Coordinator 读证据对齐意图）
        -> 通过 gate：writeback verified
        -> gate 不满足意图：writeback failed_retest，带意图差异再派发 Developer
  -> Test 失败：writeback failed_retest，追加证据，再派发 Developer（最多累计三轮）
  -> 累计三轮失败：writeback leftover，继续下一个任务

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

手动模式（无 Orca）

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

Coordinator 在 tasks.yaml 写好任务和验收信号。
用 prompt-templates.md §1 的初始派发模板生成 prompt，手动发给 Developer（另一个会话/终端/人）。
Developer 完成后按 worker_done 模板回报。
Coordinator 写回 fixed_by_dev，用 prompt-templates.md §3 的复测派发模板把任务发给 Test。
Test 独立复测后按复测报告模板回报证据。
Coordinator 做终检并回写 tasks.yaml：通过 verified，不过 failed_retest。
失败则用「复测失败再派发模板」重新发给 Developer，最多累计三轮。

手动模式下同样遵守：worker_done / 复测报告都不等于最终结论、只有 Coordinator 写 tasks.yaml、三轮失败留档。

Test 复测（编排无关）

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

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

浏览器复测建议记录：

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

Test 只回传证据，不写 tasks.yaml；由 Coordinator 落盘。

Coordinator 终检（gate）

Test 报通过后，Coordinator 不重测，而是做一次读证据的终检：

Test 证据是否覆盖了任务的每一条验收信号（见 optimization-method.md §1）。
结果是否符合任务的原始意图，而不只是通过了字面文案。
运行环境是否对齐（见下方「服务与 worktree 对齐」）。

终检不通过（例如意图漂移、验收信号写漏）时，回写 failed_retest 并把意图差异带给下一轮 Developer，必要时先补全验收信号。

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

Test 复测前记录运行环境：

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

serverPid:
serverCommand:
BASE_URL:
frontendDir:
worktreePath:

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

结果回写

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

# 通过（Test 复测 + Coordinator 终检）
status: verified
resolution:
  verifiedAt: "<timestamp>"
  verifiedBy: "test"
  evidence:
    verification: "<commands passed>"
    browser: "<snapshot or API evidence>"

# 失败但未满三轮
status: failed_retest
dispatch:
  rounds:
    - round: 1
      result: failed
      evidence: "<latest evidence from Test or gate>"

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

5.3 KiB Raw Blame History Unescape Escape