Author orch Markdown test plan

2026-03-19 16:27:28 +08:00
parent b448d98e71
commit a20bec1cac
68 changed files with 2225 additions and 160 deletions
@@ -1,7 +1,8 @@
 # Orch `council wait` Test Plan Index

-## Status
+## Case Files

-No command case files are authored yet.
-
-Use [../ROADMAP.md](../ROADMAP.md) for planned case slugs and document progress.
+| Case Slug | File | Coverage Note |
+| --- | --- | --- |
+| `council-wait-wakes-when-all-reviewers-complete` | [council-wait-wakes-when-all-reviewers-complete.md](./council-wait-wakes-when-all-reviewers-complete.md) | wakes successfully once all three reviewer threads reach terminal success |
+| `council-wait-times-out-when-reviewers-incomplete` | [council-wait-times-out-when-reviewers-incomplete.md](./council-wait-times-out-when-reviewers-incomplete.md) | returns a stable timeout result while reviewer work remains incomplete |
@@ -0,0 +1,35 @@
+# Case: `council-wait-times-out-when-reviewers-incomplete`
+
+## 用例意义
+
+验证 `council wait` 在 reviewer 尚未全部完成时返回稳定的超时结果，而不是误判为成功唤醒。
+
+## 前置条件
+
+- 使用隔离的临时目录 `TMPDIR`
+- 目标数据库 `TMPDIR/coord.db` 尚不存在
+
+## 输入
+
+```bash
+orch --db TMPDIR/coord.db --json council start \
+  --run council_blog_wait_002 \
+  --target "Review the current blog architecture."
+
+orch --db TMPDIR/coord.db --json council wait \
+  --run council_blog_wait_002 \
+  --timeout-seconds 1
+```
+
+## 预期输出
+
+- `council wait` 退出码为 `0`
+- `wait.data.woke == false`
+- `wait.data.all_complete == false`
+- `wait.data.reviewers` 长度为 `3`
+- 返回 reviewer 状态集合时，不要求每个 reviewer 已完成
+
+## 断言结论
+
+- `council wait` 的超时结果是显式的“未唤醒”状态，而不是错误退出
+- leader 可以基于同一个返回结构同时处理唤醒与超时两种路径
@@ -0,0 +1,53 @@
+# Case: `council-wait-wakes-when-all-reviewers-complete`
+
+## 用例意义
+
+验证 `council wait` 在三位 reviewer 都完成后会被唤醒，并返回完整 reviewer 状态集合。
+
+## 前置条件
+
+- 使用隔离的临时目录 `TMPDIR`
+- 已通过 `council start` 创建 run `council_blog_wait_001`
+- 本地可使用 `sqlite3` 从 `task_attempts` 中读取 reviewer thread ID，用于构造 `inbox` 完成态
+
+## 输入
+
+```bash
+orch --db TMPDIR/coord.db --json council start \
+  --run council_blog_wait_001 \
+  --target "Review the current blog architecture."
+
+THREAD_ID_CR1=$(sqlite3 TMPDIR/coord.db "SELECT thread_id FROM task_attempts WHERE run_id = 'council_blog_wait_001' AND task_id = 'CR1' AND attempt_no = 1;")
+THREAD_ID_CR2=$(sqlite3 TMPDIR/coord.db "SELECT thread_id FROM task_attempts WHERE run_id = 'council_blog_wait_001' AND task_id = 'CR2' AND attempt_no = 1;")
+THREAD_ID_CR3=$(sqlite3 TMPDIR/coord.db "SELECT thread_id FROM task_attempts WHERE run_id = 'council_blog_wait_001' AND task_id = 'CR3' AND attempt_no = 1;")
+
+inbox --db TMPDIR/coord.db --json claim --agent architecture-reviewer --thread "$THREAD_ID_CR1"
+inbox --db TMPDIR/coord.db --json done --agent architecture-reviewer --thread "$THREAD_ID_CR1" --summary "Review complete"
+
+inbox --db TMPDIR/coord.db --json claim --agent implementation-reviewer --thread "$THREAD_ID_CR2"
+inbox --db TMPDIR/coord.db --json done --agent implementation-reviewer --thread "$THREAD_ID_CR2" --summary "Review complete"
+
+inbox --db TMPDIR/coord.db --json claim --agent risk-reviewer --thread "$THREAD_ID_CR3"
+inbox --db TMPDIR/coord.db --json done --agent risk-reviewer --thread "$THREAD_ID_CR3" --summary "Review complete"
+
+orch --db TMPDIR/coord.db --json council wait \
+  --run council_blog_wait_001 \
+  --timeout-seconds 2
+```
+
+## 预期输出
+
+- `council wait` 退出码为 `0`
+- `wait.data.woke == true`
+- `wait.data.all_complete == true`
+- `wait.data.reviewers` 长度为 `3`
+- 三个 reviewer 的 `status` 都是 `done`
+
+## 断言结论
+
+- `council wait` 的唤醒条件是“三位 reviewer 全部达到终态成功”
+- 返回结果不仅告知已唤醒，还会携带完整 reviewer 状态快照，便于 leader 继续执行 tally/report
+
+## 补充约束
+
+- 当前手工复现实例需要通过 `task_attempts` 提取 reviewer `thread_id`，因为 `orch` CLI 还不直接暴露 attempt-thread mapping