# Orca 适配器（稳定核心，一种编排实现）

Orca orchestration 是运行时调度层的一种实现。闭环流程本身与工具无关（见 `closed-loop.md`）；本文件只提供 Orca 的具体命令。没有 Orca 时用 `closed-loop.md` §「手动模式」。

所有结论仍以 `tasks.yaml` 为准，Orca 消息不是最终记录。

---

## 何时用 Orca 编排

用：需要监督、等待结果、闭环修复、三轮重试；有多个可独立派发的任务；需要 `worker_done` 后再复测。

不用：单次问答；用户只要求完整 handoff 不需监督；不需要复测的小改动。

---

## 运行前检查

```bash
orca status --json
orca terminal list --json
orca orchestration task-list --json
orca orchestration inbox --limit 20 --json
```

确认：Orca runtime 可达；Coordinator、Developer、Test 三个终端都存在；Developer 在正确 worktree；当前没有冲突的活跃编排任务。

---

## 创建父任务

```bash
orca orchestration task-create --spec "$(cat <<'EOF'
Goal: Complete <release_or_feature> with supervised Coordinator -> Developer -> Test loop.

Coordinator (PM): owns task board, decomposition, dispatch, and final gate (reads Test evidence, does not test).
Developer: owns implementation and white-box verification.
Test: owns independent black-box retest and evidence (verifier != implementer).

Policy:
- Each issue can be dispatched at most 3 rounds.
- If still failing after 3 rounds, record as leftover and continue next issue.
- worker_done and retest reports are not final completion; only Coordinator writes tasks.yaml.
EOF
)" --json
```

## 创建子任务

```bash
orca orchestration task-create --parent <parent_task_id> --spec "$(cat <<'EOF'
Fix <task_id>: <title>

Repository:
- Path: <repo_path>
- Worktree: <dev_worktree>

Read: <overlay_file> (project overlay), tasks.yaml, <relevant_spec_or_test_doc>
Failure evidence: <copy latest Test evidence>
Acceptance: <copy expected behavior + verification commands>

Constraints:
- Follow the overlay file path scope.
- Do not write tasks.yaml, do not mark verified.
- Do not commit or push unless user asks.
EOF
)" --json
```

---

## 派发给 Developer Worker

终端是 Orca 可识别的 Agent CLI 时：

```bash
orca orchestration dispatch --task <task_id> --to <developer_handle> --inject --json
```

不能 `--inject` 时，先登记 dispatch，再手动投递 `prompt-templates.md` §1 的初始派发 prompt：

```bash
orca orchestration dispatch --task <task_id> --to <developer_handle> --json
orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF'
<粘贴 prompt-templates.md §1 初始派发模板，已填占位符>
EOF
)" --enter --json
```

---

## 派发给 Test 复测

Developer 回报 worker_done、Coordinator 写回 `fixed_by_dev` 后，把复测任务发给 Test：

```bash
orca orchestration dispatch --task <task_id> --to <test_handle> --inject --json
```

不能 `--inject` 时，先登记再手动投递 `prompt-templates.md` §3 的复测派发 prompt：

```bash
orca orchestration dispatch --task <task_id> --to <test_handle> --json
orca terminal send --terminal <test_handle> --text "$(cat <<'EOF'
<粘贴 prompt-templates.md §3 复测派发模板，已填占位符>
EOF
)" --enter --json
```

---

## 等待结果

```bash
orca orchestration check \
  --terminal <coordinator_handle> \
  --wait \
  --types worker_done,retest_result,escalation,decision_gate \
  --timeout-ms 900000 \
  --json
```

等待超时不等于失败。长任务可继续等待，或检查 worker 终端活性。`worker_done` 来自 Developer，`retest_result`（无该类型时用 `worker_done` + subject 区分）来自 Test。

---

## Developer 回报 worker_done

字段含义见 `prompt-templates.md` §3：

```bash
orca orchestration send \
  --to <coordinator_handle> \
  --type worker_done \
  --subject "<task_id> fix ready round <n>" \
  --body "<修了什么。跑了哪些验证。如何复现。还有什么风险。>" \
  --payload '{
    "taskId": "<orca_task_id>",
    "dispatchId": "<orca_dispatch_id>",
    "filesModified": ["<file_a>", "<file_b>"],
    "verification": ["<command_a>: passed", "<command_b>: passed"],
    "risk": "<remaining risk or none>"
  }' \
  --json
```

收到 worker_done 后，Coordinator 写回 `fixed_by_dev`，再按上文派发给 Test 复测。

---

## Test 回报复测结果

字段含义见 `prompt-templates.md` §5：

```bash
orca orchestration send \
  --to <coordinator_handle> \
  --type retest_result \
  --subject "<task_id> retest round <n>" \
  --body "<逐条验收信号结论 + 实际观察 + 证据>" \
  --payload '{
    "taskId": "<orca_task_id>",
    "dispatchId": "<orca_dispatch_id>",
    "env": {"worktree": "<path>", "branch": "<branch>", "commit": "<sha>", "baseUrl": "<base_url>"},
    "signals": ["<signal 1>: pass", "<signal 2>: fail (<evidence>)"],
    "conclusion": "all-signals-pass | signals-failed"
  }' \
  --json
```

无 `retest_result` 类型时用 `--type worker_done`，靠 subject `retest round <n>` 区分。收到复测结果后，Coordinator 按 `closed-loop.md` 做终检并回写 `tasks.yaml`：通过 `verified`，不过 `failed_retest`。