jpicklyk/task-orchestrator/work-summary

Work Summary

Attention-first project dashboard. The default (lean) mode answers four questions - what's moving, what's stuck, what's next, what's queued - in a bounded view (~45 lines) regardless of workspace size. The exhaustive inventory is an explicit mode: mature workspaces accumulate hundreds of terminal items, and rendering them all buries the actionable content.

Every call below is a 4.0 tool call. Shapes are in `../_generated/call-shapes.md` and are not restated here. Every answer is the response envelope: read ok, then data; on ok: false read error.code (an unknown field is unknown_parameter, so a typo fails loudly rather than being ignored). All calls here are reads, so there is no per-element write envelope to check.

Supplement the data with brief observations only for a genuine anomaly or actionable insight.

Director mode

Director mode is the session state entered by /task-orchestrator:director (or by running as the hardened director agent); its guard denies the file read of Step 0.5 and most of the reads below. Runs, decisions and blocked work belong to the director board: re-invoke /task-orchestrator:director for them. For a backlog view in director mode run only these reads: Lean step 1 (overview), steps 5 and 6 (list), In Flight from items_read list with role work and again with review, items_read blocked, and the Runs reads. Skip the health context read, history, next, the Blocked-item decisions context reads, a scoped search and the Step 0.5 file read (with no session rootId run unscoped), and omit every dashboard section whose read was skipped. For the complete dashboard, dispatch ONE background Agent (run_in_background: true, model set) that runs the steps below and reports the rendered dashboard text, never note bodies. A background agent dispatched by a director is not in director mode: it runs the steps below.

Step 0 - Mode Selection

Step 0.5 - Project Scope Resolution

• Check the SessionStart context. A ## Project Scope section carries a project rootId, which scopes reads (ancestorId / anchorId). A ## Personal Scope section carries a personal root, which only anchors new items: in personal scope every call runs unscoped and the header says personal scope - whole database.
• Otherwise read the top-level project.rootId of .taskorchestrator/config.yaml (a file read).
• With no rootId from either path, every call runs unscoped: drop ancestorId / anchorId / rootId from the examples below.

Below, "<rootId>" marks a field you include only when a project rootId is known. Scoped mode resolves its own scope per invocation and ignores the project rootId.

Lean Mode (default)

Data collection (all parallel)

1. Non-terminal roots with childCounts roll-ups (`items_read-overview`). excludeTerminal keeps a terminal root that still has open descendants (active work parked under a done container) and drops the rest; page.truncated / page.next page it.

{"tool": "items_read", "select": "overview", "args": {"excludeTerminal": true, "anchorId": "<rootId>"}}

1. Health: data.active.items (work and review, longest in the role first), data.blocked.items, data.stalled, data.claimSummary (`items_read-context`). blocked holds explicit blocks (blockType: "explicit", with reason and, for awaiting_decision, decisionId) AND open items with an unsatisfied dependency (blockType: "dependency"). Each stalled entry is {id, title, role, missing[], guidanceKey?, skillPointer?}.

{"tool": "items_read", "select": "context", "args": {"ancestorId": "<rootId>", "limit": 100, "fields": ["ancestors"]}}

1. Recent transitions (the "where did I leave off" signal). The history select has no ancestorId: with no itemId it covers every item the caller may see, so the line is whole-tree even inside a project.

{"tool": "items_read", "select": "history", "args": {"since": "<now minus 48h, ISO 8601>", "limit": 20}}

1. Ranked recommendations (the default limit is 1, so ask for 5). fields: ["ancestors"] supplies the Container column.

{"tool": "items_read", "select": "next", "args": {"limit": 5, "ancestorId": "<rootId>", "fields": ["ancestors"]}}

1. The canonical source for queue children. Group rows by parentId; page.total is the true queued count. Subtract rows whose type or tag is container or project (a fresh container sits in queue until its first advance and would inflate N queued). When page.truncated, the headline count is approximate.

{"tool": "items_read", "select": "list", "args": {"role": "queue", "limit": 200, "ancestorId": "<rootId>"}}

1. The true terminal count is data.page.total.

{"tool": "items_read", "select": "list", "args": {"role": "terminal", "limit": 1, "ancestorId": "<rootId>"}}

Headline counts come from these sources, never from the overview payload (it covers the roots set only and may be truncated).

Runs (only when runs exist)

Issue both reads in parallel and render the section only when either returns a run. A run is a bounded, budgeted pass over a set of items.

{"tool": "runs_read", "select": "list", "args": {"rootId": "<rootId>", "status": "open"}}

{"tool": "runs_read", "select": "list", "args": {"rootId": "<rootId>", "status": "paused"}}

For each run (cap 5, newest first) read its frontier:

{"tool": "runs_read", "select": "frontier", "args": {"runId": "<run UUID>"}}

data.counts is members by role, ready the members nothing holds back, inFlight the active seats (each with its own stalled flag), waiting the members held back, each {id, reason, decisionId?, blockers?} with a reason of manual, dependency, awaiting_decision or resource; decisionId is present whenever the member's block names a decision, and blockers (short ids) only for dependency. stalled is the coordinator's flag. A paused run's list entry carries pauseReason. Render one row per run: label or title, short run id, status, counts, ready, in flight (N silent, from the seats' stalled flags), waiting. The word "stalled" is kept for the health stalled items (open items missing notes); a run's seats and coordinator are "silent".

When the director connection's tools are present (report and runs_read decisions; skip the rest of this section silently otherwise), add per run the budget and open decisions from the rollup, and one decisions line for the root. Every call here is a director-profile call:

{"tool": "report", "select": "rollup", "args": {"runId": "<run UUID>"}, "profile": "director"}

data.budget is {used, limit?} and data.decisions.open the open decisions count. Both are run-only and a run rollup always carries both: decisions with open: 0 when nothing is open, budget with limit absent when the run has no token budget; an anchor rollup has neither. Render budget used/limit (used alone with no limit) and decisions open in the run's row.

{"tool": "runs_read", "select": "decisions", "args": {"rootId": "<rootId>", "limit": 50}, "profile": "director"}

Follow page.next (pass it as cursor) until it is absent. The select has no status filter: keep the summaries whose status is open or acknowledged, count them, and count those with overdue: true. Render Decisions waiting: N (k overdue) just above the Runs table and point at /task-orchestrator:director to answer them; omit the line when N is 0.

Blocked-item decisions

For each health blocked entry with blockType: "explicit" (cap 10), read the item's context. Its item.blockedReason repeats the block reason and decisions[] lists the decisions raised on it as {id, class, status, option?} (withdrawn ones left out). The question text is not in this view: it is a director-profile read (runs_read decision), so show the decision class and status instead. This read supplies decisions[] class and status only; whether the item is resumable comes from the blocked read below.

{"tool": "items_read", "select": "context", "args": {"itemId": "<blocked item id>"}}

When health blocked holds an awaiting_decision entry, read items_read blocked once:

{"tool": "items_read", "select": "blocked", "args": {"ancestorId": "<rootId>", "fields": ["ancestors"]}}

Each awaiting_decision entry carries a server-computed resumable (true when its blocking decision is no longer open or acknowledged). Answering a decision never resumes its item, so flag a resumable one and point at advance op transition with trigger: "resume".

Enrichment

• Containers are shelves, not work. Items with tag or type = container never count as active; exclude them from the In Flight list.
• Active = health active.items minus containers. Blocked / stalled = the health lists as they are. Items of a lifecycle: none schema have no role, so role-filtered lists and counts leave them out: the dashboard covers role-bearing work (config-reference.md, Lifecycle-free items).
• Workstreams = non-terminal roots with children. Progress = terminal / total from childCounts, rendered N/M terminal (not done: the terminal bucket includes cancelled items). "Next up" = the highest-priority queue row from step 5 whose parentId is that root.
• Standalone queue roots group by kind: the type if set; else the first tag not in {agent-observation, feature, container}; else "Uncategorized".
• Rollup threshold: a group of more than 5 renders as a count line by kind, listing items only when priority is medium or higher or tagged action-item.
• Hygiene candidates: empty non-terminal containers; evident test artifacts (probe/smoke titles, mtest-* tags).

Dashboard format

Render in this order; omit any section with no data.

## ◆ Work Summary
 
[One sentence: health and momentum.]
 
**N active · N blocked · N stalled · N queued · N terminal**
 
### ◉ In Flight
| ID | Item | Container | Status | Pri |
|----|------|-----------|--------|-----|
| `xxxxxxxx` | <title> | <parent title or —> | ◉ work | high |
 
↳ Recent: <up to 3 one-line transitions from history, newest first; omit if none in 48h>
 
### ⊘ Attention Required
| ID | Item | Container | Issue |
|----|------|-----------|-------|
| `xxxxxxxx` | <title> | <parent or —> | Blocked by: `<blocker-id>` <blocker-title> |
| `yyyyyyyy` | <title> | <parent or —> | Blocked (awaiting_decision): <class> <status>; resumable |
| `zzzzzzzz` | <title> | <parent or —> | Stalled: missing `<note-key>` |
 
### ▸ Recommended Next
| ID | Title | Container | Pri |
|----|-------|-----------|-----|
 
### ⟳ Runs
| Run | Status | Terminal / total | Ready | In flight | Waiting | Budget | Decisions open |
|-----|--------|------------------|-------|-----------|---------|--------|----------------|
 
### ○ Backlog
**Workstreams**
| ID | Workstream | Progress | Next up | Pri |
|----|-----------|----------|---------|-----|
 
**<Kind>** (N): `id` <title> (pri) · ...           ← groups of 5 or fewer
**<Kind>** (N): X bug · Y optimization — highest: `id` <title> (pri)   ← groups of more than 5