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 `ready` 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 |
+| --- | --- | --- |
+| `ready-lists-only-eligible-tasks` | [ready-lists-only-eligible-tasks.md](./ready-lists-only-eligible-tasks.md) | returns only dependency-cleared tasks in priority-aware ready order |
+| `ready-orders-by-priority-and-respects-limit` | [ready-orders-by-priority-and-respects-limit.md](./ready-orders-by-priority-and-respects-limit.md) | sorts ready tasks by priority and applies `--limit` after ordering |
@@ -0,0 +1,38 @@
+# Case: `ready-lists-only-eligible-tasks`
+
+## 用例意义
+
+验证 `ready` 只返回当前真正可调度的任务，而不会把仍受依赖阻塞的任务混入结果。
+
+## 前置条件
+
+- 已存在 run `run_blog_002`
+- `T1` 与 `T2` 已创建
+- `T2` 已通过 `dep add` 依赖 `T1`
+
+## 输入
+
+```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" --default-to worker-a
+orch --db TMPDIR/coord.db --json task add --run run_blog_002 --task T2 --title "Build frontend" --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
+```
+
+## 预期输出
+
+- `ready` 退出码为 `0`
+- `data.tasks` 长度为 `1`
+- 唯一返回项是 `T1`
+- 返回任务状态为 `ready`
+
+## 断言结论
+
+- `ready` 是经过依赖和状态过滤后的结果，不是“所有未完成任务”的简单列表
+- 新 agent 可以依赖该命令决定可立即 dispatch 的工作
+
+## 补充约束
+
+- 未显式传 `--limit` 时，默认上限是 `20`
+- `--run` 指向不存在的 run 时，应返回 `not_found`
@@ -0,0 +1,39 @@
+# Case: `ready-orders-by-priority-and-respects-limit`
+
+## 用例意义
+
+验证 `ready` 会先按优先级排序可调度任务，再应用 `--limit` 截断结果，而不是按创建顺序直接裁剪。
+
+## 前置条件
+
+- 已存在 run `run_blog_005`
+- 该 run 下有至少三个无依赖且处于 `ready` 的任务
+- 三个任务优先级分别为 `high`、`normal`、`low`
+
+## 输入
+
+```bash
+orch --db TMPDIR/coord.db --json run init --run run_blog_005 --goal "Validate ready ordering"
+orch --db TMPDIR/coord.db --json task add --run run_blog_005 --task T1 --title "Low priority task" --priority low
+orch --db TMPDIR/coord.db --json task add --run run_blog_005 --task T2 --title "Normal priority task" --priority normal
+orch --db TMPDIR/coord.db --json task add --run run_blog_005 --task T3 --title "High priority task" --priority high
+orch --db TMPDIR/coord.db --json ready --run run_blog_005 --limit 2
+```
+
+## 预期输出
+
+- `ready` 退出码为 `0`
+- `data.tasks` 长度为 `2`
+- 第一个返回项是高优先级任务 `T3`
+- 第二个返回项是普通优先级任务 `T2`
+- 低优先级任务 `T1` 不出现在本次结果中
+
+## 断言结论
+
+- `ready` 的用户可见顺序是 `high -> normal -> low`
+- `--limit` 的截断发生在优先级排序之后，因此 leader 可以依赖该命令优先看到更重要的可调度任务
+
+## 补充约束
+
+- 当多个 ready 任务优先级相同时，当前实现会按创建时间升序稳定返回
+- 未显式传 `--limit` 时，默认上限仍是 `20`