ai-workflow-skill/docs/tests/orch/workflows/README.md

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

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

用例意义

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

前置条件

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

输入

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

输入

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 负责代码任务

输入

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

输入

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 必须在契约上连续