# Orch Workflow Test Plan

## Scope

This document tracks cross-command scenarios where the main value is the interaction between multiple `orch` commands, and often between `orch` and `inbox`.

All examples assume:

- isolated temp database
- `orch --db TMPDIR/coord.db --json` is used consistently
- assertions follow the shared rules in [../_shared/README.md](../_shared/README.md)

## case: run-dispatch-reconcile-status-happy-path

### 用例意义

验证 `orch` 的主干领导者流程可用：创建 run、加入 task、查看 ready、dispatch、通过 `inbox` 推进 worker 状态、reconcile，再用 `status` 看到最终完成态。

### 前置条件

- 空数据库路径 `TMPDIR/coord.db`
- 执行者为 `worker-a`

### 输入

```bash
orch --db TMPDIR/coord.db --json run init --run run_blog_001 --goal "Build blog MVP" --summary "Public blog plus admin CRUD"
orch --db TMPDIR/coord.db --json task add --run run_blog_001 --task T1 --title "Implement retry policy" --summary "Add retry policy to HTTP client" --default-to worker-a
orch --db TMPDIR/coord.db --json ready --run run_blog_001
orch --db TMPDIR/coord.db --json dispatch --run run_blog_001 --task T1 --body "Implement retry handling for the HTTP client."
inbox --db TMPDIR/coord.db --json claim --agent worker-a --thread THREAD_ID
inbox --db TMPDIR/coord.db --json update --agent worker-a --thread THREAD_ID --status in_progress --summary "Implementation started"
orch --db TMPDIR/coord.db --json reconcile --run run_blog_001
inbox --db TMPDIR/coord.db --json done --agent worker-a --thread THREAD_ID --summary "Retry policy implemented" --body "The HTTP client now retries transient failures."
orch --db TMPDIR/coord.db --json reconcile --run run_blog_001
orch --db TMPDIR/coord.db --json status --run run_blog_001
```

### 预期输出

- `run init` 成功创建 `run_blog_001`
- `task add` 返回的新 task 初始状态为 `ready`
- `ready` 只返回 `T1`
- `dispatch` 创建 attempt 与 inbox thread，并将 task 推进到 `dispatched`
- 第一次 `reconcile` 后 task 状态变为 `running`
- 第二次 `reconcile` 后 task 状态变为 `done`
- `status` 返回 `run.status == "done"`

### 断言结论

- `orch` 的主干 happy path 不是单命令行为，而是 `orch` 与 `inbox` 共同完成的闭环
- `reconcile` 是把 worker-side 线程状态折叠回 leader-side task 状态的关键步骤

## case: dependency-blocked-answer-resume-flow

### 用例意义

验证依赖门控、blocked 列表、`answer` 反馈以及最终恢复到完成态的完整交互链路。

### 前置条件

- 空数据库路径 `TMPDIR/coord.db`
- `worker-a` 负责 `T1`
- `worker-b` 负责 `T2`

### 输入

```bash
orch --db TMPDIR/coord.db --json run init --run run_blog_002 --goal "Build dependency-aware workflow"
orch --db TMPDIR/coord.db --json task add --run run_blog_002 --task T1 --title "Build backend" --summary "Implement backend APIs" --default-to worker-a
orch --db TMPDIR/coord.db --json task add --run run_blog_002 --task T2 --title "Build frontend" --summary "Implement frontend flows" --default-to worker-b
orch --db TMPDIR/coord.db --json dep add --run run_blog_002 --task T2 --depends-on T1
orch --db TMPDIR/coord.db --json ready --run run_blog_002
orch --db TMPDIR/coord.db --json dispatch --run run_blog_002 --task T1
inbox --db TMPDIR/coord.db --json claim --agent worker-a --thread THREAD_BACKEND
inbox --db TMPDIR/coord.db --json done --agent worker-a --thread THREAD_BACKEND --summary "Backend complete"
orch --db TMPDIR/coord.db --json reconcile --run run_blog_002
orch --db TMPDIR/coord.db --json ready --run run_blog_002
orch --db TMPDIR/coord.db --json dispatch --run run_blog_002 --task T2
inbox --db TMPDIR/coord.db --json claim --agent worker-b --thread THREAD_FRONTEND
inbox --db TMPDIR/coord.db --json update --agent worker-b --thread THREAD_FRONTEND --status blocked --summary "Need logging decision" --payload-json '{"question":"stdout or stderr?"}'
orch --db TMPDIR/coord.db --json reconcile --run run_blog_002
orch --db TMPDIR/coord.db --json blocked --run run_blog_002
orch --db TMPDIR/coord.db --json answer --run run_blog_002 --task T2 --body "Use stdout for MVP."
inbox --db TMPDIR/coord.db --json update --agent worker-b --thread THREAD_FRONTEND --status in_progress --summary "Decision applied"
inbox --db TMPDIR/coord.db --json done --agent worker-b --thread THREAD_FRONTEND --summary "Frontend complete"
orch --db TMPDIR/coord.db --json reconcile --run run_blog_002
orch --db TMPDIR/coord.db --json status --run run_blog_002
```

### 预期输出

- 初始 `ready` 仅包含 `T1`
- `T1` 完成并 `reconcile` 后，`T2` 才出现在 `ready`
- `blocked` 返回 `T2` 与最新 question
- `answer` 向活跃 thread 追加一条 `kind=answer` 消息
- 最终 `status` 中 run 进入 `done`

### 断言结论

- 依赖门控和 blocked-answer 机制在同一个 run 中可以顺序衔接
- `answer` 不直接改 task 状态；真正的状态恢复仍依赖 worker 继续推进线程并由 `reconcile` 采集

## case: strict-worktree-dispatch-to-cleanup

### 用例意义

验证代码任务的 strict worktree 路径能从 dispatch 一直走到 cleanup，确保隔离工作区既会被创建，也能在完成后被移除。

### 前置条件

- `TMPDIR/repo` 是一个已提交初始内容的 Git 仓库
- `worker-a` 负责代码任务

### 输入

```bash
orch --db TMPDIR/coord.db --json run init --run run_blog_worktree_001 --goal "Validate strict worktree dispatch"
orch --db TMPDIR/coord.db --json task add --run run_blog_worktree_001 --task T1 --title "Implement backend" --default-to worker-a
orch --db TMPDIR/coord.db --json dispatch --run run_blog_worktree_001 --task T1 --repo-path TMPDIR/repo --workspace-root .orch/worktrees --strict-worktree --body "Implement inside isolated worktree."
inbox --db TMPDIR/coord.db --json claim --agent worker-a --thread THREAD_ID
inbox --db TMPDIR/coord.db --json done --agent worker-a --thread THREAD_ID --summary "Backend complete"
orch --db TMPDIR/coord.db --json reconcile --run run_blog_worktree_001
orch --db TMPDIR/coord.db --json cleanup --run run_blog_worktree_001 --task T1 --attempt 1
```

### 预期输出

- `dispatch` 返回非空的 `attempt.base_ref`、`attempt.base_commit`、`attempt.branch_name`、`attempt.worktree_path`
- `attempt.workspace_status == "created"`
- `cleanup` 返回被清理的 attempt 记录
- 清理后 `worktree_path` 不再存在于文件系统

### 断言结论

- strict worktree 不是单次 dispatch 细节，而是完整 attempt 生命周期的一部分
- `cleanup` 的目标是已完成或废弃的工作区，不应误删仍在活动中的执行目录

## case: council-review-end-to-end

### 用例意义

验证 `orch council` 高层工作流可从 reviewer dispatch 一直走到 final report，且 grouped recommendations 与最终输出衔接一致。

### 前置条件

- 空数据库路径 `TMPDIR/coord.db`
- 三个固定 reviewer 分别为 `architecture-reviewer`、`implementation-reviewer`、`risk-reviewer`

### 输入

```bash
orch --db TMPDIR/coord.db --json council start --run council_blog_001 --target "Review the current blog architecture."
inbox --db TMPDIR/coord.db --json claim --agent architecture-reviewer --thread THREAD_CR1
inbox --db TMPDIR/coord.db --json done --agent architecture-reviewer --thread THREAD_CR1 --summary "Review complete" --body '{"reviewer_role":"architecture-reviewer","findings":[...]}'
inbox --db TMPDIR/coord.db --json claim --agent implementation-reviewer --thread THREAD_CR2
inbox --db TMPDIR/coord.db --json done --agent implementation-reviewer --thread THREAD_CR2 --summary "Review complete" --body '{"reviewer_role":"implementation-reviewer","findings":[...]}'
inbox --db TMPDIR/coord.db --json claim --agent risk-reviewer --thread THREAD_CR3
inbox --db TMPDIR/coord.db --json done --agent risk-reviewer --thread THREAD_CR3 --summary "Review complete" --body '{"reviewer_role":"risk-reviewer","findings":[...]}'
orch --db TMPDIR/coord.db --json council wait --run council_blog_001 --timeout-seconds 2
orch --db TMPDIR/coord.db --json council tally --run council_blog_001 --similarity normal
orch --db TMPDIR/coord.db --json council report --run council_blog_001
```

### 预期输出

- `council start` 创建 3 个 reviewer task 并完成 dispatch
- `council wait` 在 3 个 reviewer 全部完成后返回 `all_complete == true`
- `council tally` 返回 grouped recommendations，并按 `consensus|majority|minority` 分桶
- `council report` 返回默认 `show == ["consensus","majority"]`，并产出 markdown artifact

### 断言结论

- council workflow 是建立在 `orch` 调度面之上的高层流程，而不是独立基础设施
- final report 依赖已持久化的 grouped recommendations，因此 `tally` 与 `report` 必须在契约上连续