# Orca Closed Loop Workflow

Orca orchestration 是运行时调度层，`tasks.yaml` 是持久事实源。不要把 Orca 消息当成最终记录；所有结论都要回写任务板。

## 什么时候使用 Orca 编排

使用：

- 用户要求监督、等待结果、闭环修复、三轮重试。
- 有多个 bug 或多个可独立派发的任务。
- Product/Test 与 Developer 需要明确分工。
- 需要 `worker_done` 后再复测。

不使用：

- 单次问答。
- 用户只是要求完整 handoff，不需要你监督。
- 不需要测试和复测的小改动。

## 标准闭环

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

## 运行前检查

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

确认：

- Orca runtime 可达。
- Coordinator 终端和 Developer Worker 终端都存在。
- Developer Worker 在正确 worktree。
- 当前没有会冲突的活跃编排任务。

## 创建父任务

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

Coordinator:
- Owns task board, black-box tests, retest, final verification.

Developer:
- Owns implementation and white-box verification.

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 is not final completion.
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:
- AGENTS.md
- tasks.yaml
- <relevant_spec_or_test_doc>

Failure evidence:
- <copy latest Product/Test evidence>

Acceptance:
- <copy expected behavior>
- <copy verification commands>

Constraints:
- Follow AGENTS.md path scope.
- 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：

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

```bash
orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF'
You are receiving a supervised Orca task.

taskId: <task_id>
dispatchId: <dispatch_id>
coordinator: <coordinator_handle>

Task:
- Fix <task_id>: <title>

Acceptance:
- <expected behavior>

Verification:
- <test_commands>

When done, send exactly one worker_done:
orca orchestration send --to <coordinator_handle> --type worker_done --subject "<task_id> fixed" --body "<summary>" --payload '{"taskId":"<task_id>","dispatchId":"<dispatch_id>","filesModified":["<paths>"],"verification":["<commands>"]}' --json
EOF
)" --enter --json
```

## 等待结果

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

等待超时不等于失败。长任务可以继续等待，或检查 worker 终端活性。

## worker_done 后复测

Product/Test 必须自己验证：

```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，必须停止并重启正确服务后再测。

## 结果回写

通过：

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

失败但未满三轮：

```yaml
status: failed_retest
attempts:
  - round: 1
    result: failed
    evidence: "<latest evidence>"
```

三轮失败：

```yaml
status: leftover
leftoverReason: "failed after 3 supervised developer rounds"
evidence:
  final: "<latest failing evidence>"
```