kurihada/ai-workflow-skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve orch status reconciliation view

Browse Source
This commit is contained in:
kurihada
2026-03-20 17:57:58 +08:00
parent 693a79345b
commit cf3c3cbe60
11 changed files with 374 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+3 -1
View File
@@ -36,6 +36,7 @@ If `inbox` is reduced to pure chat storage, the scheduler must reconstruct state
- The leader may use `inbox` directly for inspection or manual repair.
- Workers should use `inbox` only.
- Workers should not use `orch`.
- `orch dispatch` creates handoff state, not execution. Leaders still need a separate worker runtime or worker agent to consume the assigned inbox thread.
- User-facing discussion stays with the leader.
- Code-writing workers should run in `orch`-assigned Git worktrees, not in the user's primary checkout.
@@ -59,6 +60,7 @@ For code tasks, execution should be isolated from the user's primary checkout.
- the assigned worktree path should be stored in attempt metadata and inbox task payload
- the worker runtime should execute inside that worktree
- strict mode should require a committed base revision
- non-code tasks may stay on a thread-only dispatch path with no worktree, but they still require a separate worker runtime to claim the inbox thread
See [worktree-execution.md](/home/kurihada/project/ai-workflow-skill/docs/worktree-execution.md) for the full lifecycle.
@@ -156,5 +158,5 @@ Do not put these into `orch`:
The intended skill split mirrors the CLI split.
- `inbox` skill: used when an agent needs to fetch work, claim a thread, send progress, ask blocked questions, reply, or return results through `inbox`
- `orch` skill: used when the leader needs to create runs, decompose tasks, manage dependencies, dispatch ready work, inspect blocks, answer them, retry failures, or reassign work through `orch`
- `orch` skill: used when the leader needs to create runs, decompose tasks, manage dependencies, dispatch ready work, inspect blocks, answer them, retry failures, or reassign work through `orch`; it is not itself the worker launcher
- `council-review` skill: used when the user explicitly wants a structured three-reviewer brainstorm or review with grouped and tallied recommendations
docs/orch-cli.md
+18 -6
View File
@@ -11,6 +11,7 @@ In normal operation:
- leaders use `orch`
- `orch` creates and monitors `inbox` threads
- workers continue using `inbox`
- a separate worker runtime or worker agent must still consume the assigned inbox thread after `dispatch`
## Responsibilities
@@ -34,6 +35,7 @@ In normal operation:
- worker claiming
- direct worker polling
- automatic worker-runtime launch
- raw message append storage
- low-level thread history management
@@ -93,12 +95,13 @@ The normal leader loop is:
3. add dependencies
4. inspect `ready`
5. `dispatch` tasks
6. `reconcile` inbox state back into task state
7. inspect `blocked`
8. answer blocked questions
9. if nothing is actionable, call `wait`
10. retry or reassign failures when needed
11. finish when all required tasks are `done`
6. arrange or launch a separate worker runtime that consumes the assigned inbox threads
7. use `status` for the current operational view; it reconciles first and includes latest attempt and message context
8. inspect `blocked`
9. answer blocked questions
10. if nothing is actionable, call `wait`
11. retry or reassign failures when needed
12. finish when all required tasks are `done`
The leader should block on `orch wait`, not on ad hoc `sleep`.
@@ -194,6 +197,7 @@ Behavior:
- creates or links an `inbox` thread
- writes workspace metadata into attempt storage and task payload
- moves the task to `dispatched`
- does not start a worker runtime on its own
Strict-mode recommendation:
@@ -316,6 +320,14 @@ Suggested flags:
- `--run RUN_ID`
Behavior:
- reconciles inbox thread state before returning the view
- returns run aggregate counts plus per-task detail
- includes the latest attempt for each task when one exists
- includes the latest thread message for each task when one exists
- includes the latest blocked question for blocked tasks so the leader can inspect the current issue without a separate `blocked` call in the common case
### `orch show`
Show one task with dependencies, attempts, and inbox mapping.
docs/tests/orch/ROADMAP.md
+9 -6
View File
@@ -18,12 +18,13 @@ It is not a replacement for automated Go tests.
Snapshot date:
- `2026-03-19`
- `2026-03-20`
Current state:
- `orch` CLI is implemented for the current scheduler, strict worktree, wait, and council review surfaces
- automated Go tests now cover every currently documented `orch` command case and workflow case, combining the original integration suite with focused contract tests for run/task/ready/dispatch/blocked/answer/cleanup/status/reconcile/workflow/council-report edges
- `status` coverage now also documents the richer leader view: auto-reconcile plus latest attempt, latest message, and blocked-question context
- this roadmap now exists under `docs/tests/orch/ROADMAP.md`
- all planned global, shared, workflow, command-index, and command-case Markdown documents in the current `orch` test-plan set have been authored
- every implemented `orch` leaf-command folder now uses `README.md` as an index plus one Markdown file per planned case
@@ -31,10 +32,10 @@ Current state:
Progress summary for planned test-plan documents, excluding `ROADMAP.md`:
- planned document files: `64`
- authored document files: `64`
- planned case slugs in this roadmap: `46`
- authored case slugs in this roadmap: `46`
- planned document files: `65`
- authored document files: `65`
- planned case slugs in this roadmap: `47`
- authored case slugs in this roadmap: `47`
## Scope
@@ -270,6 +271,7 @@ docs/tests/orch/
| `docs/tests/orch/cleanup/cleanup-returns-no-matching-work-when-filters-miss.md` | `cleanup` command case | 1 | 1 | done |
| `docs/tests/orch/status/README.md` | `status` command case index | 0 | 0 | done |
| `docs/tests/orch/status/status-returns-run-summary-and-task-list.md` | `status` command case | 1 | 1 | done |
| `docs/tests/orch/status/status-auto-reconciles-and-includes-blocked-context.md` | `status` command case | 1 | 1 | done |
| `docs/tests/orch/council-start/README.md` | `council start` command case index | 0 | 0 | done |
| `docs/tests/orch/council-start/council-start-dispatches-three-reviewers.md` | `council start` command case | 1 | 1 | done |
| `docs/tests/orch/council-wait/README.md` | `council wait` command case index | 0 | 0 | done |
@@ -333,7 +335,8 @@ docs/tests/orch/
| `docs/tests/orch/cleanup/cleanup-removes-completed-worktree.md` | `cleanup-removes-completed-worktree` | cleanup removes completed attempt worktree artifacts | done |
| `docs/tests/orch/cleanup/cleanup-rejects-attempt-without-task.md` | `cleanup-rejects-attempt-without-task` | cleanup enforces `--task` when `--attempt` is specified | done |
| `docs/tests/orch/cleanup/cleanup-returns-no-matching-work-when-filters-miss.md` | `cleanup-returns-no-matching-work-when-filters-miss` | cleanup returns no_matching_work when selectors find no candidates | done |
| `docs/tests/orch/status/status-returns-run-summary-and-task-list.md` | `status-returns-run-summary-and-task-list` | status reports aggregate run state and per-task statuses | done |
| `docs/tests/orch/status/status-returns-run-summary-and-task-list.md` | `status-returns-run-summary-and-task-list` | status reports aggregate run state, per-task statuses, and latest attempt context | done |
| `docs/tests/orch/status/status-auto-reconciles-and-includes-blocked-context.md` | `status-auto-reconciles-and-includes-blocked-context` | status auto-reconciles inbox state and exposes blocked-task question context | done |
| `docs/tests/orch/council-start/council-start-dispatches-three-reviewers.md` | `council-start-dispatches-three-reviewers` | council start creates and dispatches three fixed reviewer tasks | done |
| `docs/tests/orch/council-wait/council-wait-wakes-when-all-reviewers-complete.md` | `council-wait-wakes-when-all-reviewers-complete` | council wait wakes when all reviewer tasks complete | done |
| `docs/tests/orch/council-wait/council-wait-times-out-when-reviewers-incomplete.md` | `council-wait-times-out-when-reviewers-incomplete` | council wait timeout stays machine-readable | done |
docs/tests/orch/status/README.md
+2 -1
View File
@@ -4,4 +4,5 @@
| Case Slug | File | Coverage Note |
| --- | --- | --- |
| `status-returns-run-summary-and-task-list` | [status-returns-run-summary-and-task-list.md](./status-returns-run-summary-and-task-list.md) | returns aggregate run status plus the per-task status list |
| `status-returns-run-summary-and-task-list` | [status-returns-run-summary-and-task-list.md](./status-returns-run-summary-and-task-list.md) | returns aggregate run status plus the per-task status list and latest attempt context |
| `status-auto-reconciles-and-includes-blocked-context` | [status-auto-reconciles-and-includes-blocked-context.md](./status-auto-reconciles-and-includes-blocked-context.md) | auto-reconciles inbox state and exposes blocked-task attempt and question context |
docs/tests/orch/status/status-auto-reconciles-and-includes-blocked-context.md
+41
View File
@@ -0,0 +1,41 @@
# Case: `status-auto-reconciles-and-includes-blocked-context`
## 用例意义
验证 `status` 在返回结果前会先 reconcile 当前 inbox 线程状态，并附带 blocked 任务的 latest attempt、latest message 与 latest blocked question 上下文，方便 leader 直接判断谁在执行、卡在什么问题上。
## 前置条件
- 已存在 run `run_blog_002`
- 任务 `T1` 已 dispatch 到 `worker-a`
- `worker-a` 已 `claim` 对应线程，并写入一次 `blocked` 问题
- leader 尚未显式执行 `reconcile`
## 输入
```bash
orch --db TMPDIR/coord.db --json run init --run run_blog_002 --goal "Build blog MVP"
orch --db TMPDIR/coord.db --json task add --run run_blog_002 --task T1 --title "Implement retry policy" --default-to worker-a
orch --db TMPDIR/coord.db --json dispatch --run run_blog_002 --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 blocked --summary "Need logging decision" --payload-json '{"question":"Should retry attempts be logged?"}'
orch --db TMPDIR/coord.db --json status --run run_blog_002
```
## 预期输出
- `status` 退出码为 `0`
- `data.run.status == "blocked"`
- `data.tasks[0].status == "blocked"`
- `data.tasks[0].latest_attempt.thread_id == THREAD_ID`
- `data.tasks[0].latest_attempt.status == "blocked"`
- `data.tasks[0].latest_message.kind == "question"`
- `data.tasks[0].latest_message.summary == "Need logging decision"`
- `data.tasks[0].blocked_question.kind == "question"`
- `data.tasks[0].blocked_question.summary == "Need logging decision"`
## 断言结论
- `status` 现在是更偏 operational 的 leader 视图，而不是只读的任务列表查询
- leader 在常见排障场景里，不必先手工 `reconcile` 再额外跑 `blocked`
- enriched task context 能直接暴露当前 attempt 与问题摘要，减少二次查询
docs/tests/orch/status/status-returns-run-summary-and-task-list.md
+6 -1
View File
@@ -2,7 +2,7 @@
## 用例意义
验证 `status` 会返回 run 聚合视图以及任务明细列表，是 leader 端的完整状态检查入口。
验证 `status` 会返回 run 聚合视图、任务明细列表以及最新 attempt/message 上下文，是 leader 端的完整状态检查入口。
## 前置条件
@@ -30,8 +30,13 @@ orch --db TMPDIR/coord.db --json status --run run_blog_001
- 返回 `data.tasks` 数组
- `data.tasks[0].task_id == "T1"`
- `data.tasks[0].status == "done"`
- `data.tasks[0].latest_attempt.assigned_to == "worker-a"`
- `data.tasks[0].latest_attempt.status == "done"`
- `data.tasks[0].latest_message.kind == "result"`
- `data.tasks[0].latest_message.summary == "Retry policy implemented"`
## 断言结论
- `status` 比 `run show` 更完整，适合做 run 级收口检查
- 任务清单与 run 聚合状态应保持一致，不应出现 run 已完成而任务仍显示旧状态的结果
- leader 不必再单独查询 attempt 或 thread 历史，常见收口信息可直接从 `status` 拿到