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,9 @@
 # Orch `cleanup` 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 |
+| --- | --- | --- |
+| `cleanup-removes-completed-worktree` | [cleanup-removes-completed-worktree.md](./cleanup-removes-completed-worktree.md) | removes a completed attempt worktree and records the cleanup result |
+| `cleanup-rejects-attempt-without-task` | [cleanup-rejects-attempt-without-task.md](./cleanup-rejects-attempt-without-task.md) | rejects `--attempt` when no matching `--task` selector is provided |
+| `cleanup-returns-no-matching-work-when-filters-miss` | [cleanup-returns-no-matching-work-when-filters-miss.md](./cleanup-returns-no-matching-work-when-filters-miss.md) | returns the stable no-matching-work contract when cleanup filters yield no candidates |
@@ -0,0 +1,29 @@
+# Case: `cleanup-rejects-attempt-without-task`
+
+## 用例意义
+
+验证 `cleanup` 在使用 `--attempt` 精确选择尝试时，要求同时提供 `--task`，避免对 run 级别尝试号产生歧义。
+
+## 前置条件
+
+- 已创建运行 `run_blog_cleanup_002`
+
+## 输入
+
+```bash
+orch --db TMPDIR/coord.db --json cleanup --run run_blog_cleanup_002 --attempt 1
+```
+
+## 预期输出
+
+- 退出码为 `30`
+- JSON 错误码为 `invalid_input`
+
+## 断言结论
+
+- `cleanup` 的选择器组合在查询前就会进行基本输入校验
+- `--attempt` 不是独立的 run 级过滤器，必须依附具体 `task`
+
+## 补充约束
+
+- 若既未提供 `--task`，也未提供 `--attempt` 或 `--all-completed`，同样应返回 `invalid_input`
@@ -0,0 +1,37 @@
+# Case: `cleanup-removes-completed-worktree`
+
+## 用例意义
+
+验证 `cleanup` 会移除已完成尝试的 worktree，并把清理结果返回给 leader。
+
+## 前置条件
+
+- 已创建运行 `run_blog_cleanup_001`
+- 已创建任务 `T1`
+- `T1` 已通过严格 worktree 模式完成 `dispatch`
+- `worker-a` 已完成 `claim` 并通过 `inbox done` 把线程推进到 `done`
+- 最近一次 `reconcile` 已执行，使任务状态同步为 `done`
+- 已知当前尝试的 worktree 路径为 `WORKTREE_PATH`
+
+## 输入
+
+```bash
+orch --db TMPDIR/coord.db --json cleanup --run run_blog_cleanup_001 --task T1
+```
+
+## 预期输出
+
+- 退出码为 `0`
+- `cleanup.data.cleaned` 长度为 `1`
+- 唯一记录对应 `T1` 的已完成尝试
+- `WORKTREE_PATH` 在文件系统上已不存在
+
+## 断言结论
+
+- `cleanup` 针对的是尝试工作区资源，不会改变任务的完成结果
+- 成功清理后，leader 可以安全回收已终态尝试占用的 worktree
+
+## 补充约束
+
+- `cleanup` 支持按 `--task`、`--attempt` 或 `--all-completed` 选择范围
+- `--force` 用于非常规清理；本用例验证的是常规完成态清理路径
@@ -0,0 +1,33 @@
+# Case: `cleanup-returns-no-matching-work-when-filters-miss`
+
+## 用例意义
+
+验证 `cleanup` 在筛选条件没有命中任何可清理 worktree 时，返回稳定的“无匹配工作”契约，而不是成功空列表。
+
+## 前置条件
+
+- 已创建运行 `run_blog_cleanup_003`
+- 已创建任务 `T1`
+- 当前 run 中不存在 `workspace_status` 为 `completed` 或 `abandoned` 的 worktree 尝试
+
+## 输入
+
+```bash
+orch --db TMPDIR/coord.db --json run init --run run_blog_cleanup_003 --goal "Validate cleanup empty result"
+orch --db TMPDIR/coord.db --json task add --run run_blog_cleanup_003 --task T1 --title "Prepare cleanup target"
+orch --db TMPDIR/coord.db --json cleanup --run run_blog_cleanup_003 --task T1
+```
+
+## 预期输出
+
+- `cleanup` 退出码为 `10`
+- JSON 错误码为 `no_matching_work`
+
+## 断言结论
+
+- `cleanup` 对空筛选结果使用显式 no-matching-work 信号，而不是返回成功空数组
+- leader 或脚本可以据此区分“没有候选 worktree”与“清理已成功完成”
+
+## 补充约束
+
+- 该契约同样适用于使用 `--all-completed` 或 `--attempt` 时筛选不到候选的场景