jpicklyk/task-orchestrator/status-progression

Status Progression

Guides role transitions for a work item: identify it, read its gate status, fill missing notes, advance, and recover from a blocked or failed transition. Shapes are in `_generated/call-shapes.md` (advance transition); semantics are in current/docs/api-reference.md ("advance" and "items_read"). Ids below are 8-hex shorts and any id field also takes the full UUID. Read every answer through the envelope: ok, then data.results[0] (ok or error) and data.summary {ok, failed}. When a write element fails, the call-level error is only partial_failure (no detail, no fix): read code, kind (retry class), detail and fix from data.results[0].error. A read (select) call reports its failure in the call-level error.

Director mode

Director mode is the session state entered by /task-orchestrator:director (or by running as the hardened director agent). Here the director-safe reads are items_read get and blocked (they show the role, the block reason, a decisionId and whether the item is resumable). Never run advance, notes_write or items_read context in director mode. Answering an open decision goes through /task-orchestrator:director. Every transition, a resume once the item is resumable included, is delegated: SendMessage the run's coordinator when the item is a member of an open or paused run, otherwise dispatch ONE background Agent (run_in_background: true, model set) that runs the steps below. The agent reports the item id, the role before and after, and one line on any gate or block, never note bodies. A background agent dispatched by a director is not in director mode: it runs the steps below.

Step 1: Identify the item

Resolve $ARGUMENTS to an id with a search; if several match, show them via AskUserQuestion. With no argument, ask for an id or a title fragment.

{"tool": "items_read", "select": "search", "args": {"query": "OAuth login", "kinds": ["item"], "limit": 5}}

Step 2: Read the state

{"tool": "items_read", "select": "context", "args": {"itemId": "4b7d0e19"}}

Render a status card from the answer:

* "Implement authentication module"
  Role:     work
  Gate:     BLOCKED - 2 required notes missing
  Missing:  implementation-notes (work), session-tracking (work)
  Guidance: "Describe what was implemented, which files changed and why..."
  Next:     start -> review

A schema-free item has an open gate: the schema read answers {schemaFree: true}.

Step 3: Fill missing notes

If canAdvance is false because of notes, fill them from the conversation; ask the user when the content cannot be inferred. Send them in one call, an upsert element per note:

{"tool": "notes_write", "op": "upsert", "args": {"itemId": "4b7d0e19", "key": "implementation-notes", "role": "work", "body": "Added the retry policy in client.kt; tests cover 503 and timeout."}}

Re-read context and confirm canAdvance is true. Only one guidanceKey is returned at a time (the first unfilled required note); schema[] lists all of them.

Step 4: Advance

{"tool": "advance", "op": "transition", "args": {"itemId": "4b7d0e19", "trigger": "start", "summary": "Implementation finished"}}

Report from data.results[0]:

OK queue -> work
  Cascade: "Feature: Auth System" also moved queue -> work
  Unblocked: "Write integration tests"
  Next phase notes: implementation-notes (work), session-tracking (work)

Omit a line when its field is empty.

Triggers

Blocked items

block and hold take an optional reason: awaiting_decision, dependency, resource or manual (default). reason: awaiting_decision requires a decisionId naming an open or acknowledged decision on that item. Get one by raising with block: true (runs_write raise), which raises and blocks in one unit; do not send a bare block for a decision (see references/decisions.md). A decisionId with any other reason, or reason/decisionId on a trigger other than block/hold, is invalid_request:

{"tool": "advance", "op": "transition", "args": {"itemId": "4b7d0e19", "trigger": "block", "reason": "awaiting_decision", "decisionId": "7c9e6679"}}

• items_read get and context show blockedReason and decisionId for a blocked item.
• items_read blocked lists blocked items: each entry has blockType (explicit or dependency) and blockers[] (threshold, satisfied); an explicit entry also has reason, and an awaiting_decision entry adds decisionId and resumable (true once the decision is answered, withdrawn or missing).
• Answering a decision never resumes the item. Resume only when the entry is resumable: true (or context decisions[] shows the decisionId answered, or no longer lists it: withdrawn decisions are left out); while the decision is open or acknowledged, the next step is to have it answered (the director board), not a resume. resume clears the reason. The full rule, and how to carry the ruling to the next dispatch, is in references/decisions.md.
• Decisions are listed on the item in context decisions[]; runs_read decisions is director-only.
• Errors to recognize (on data.results[0].error): invalid_request with detail.fields[].field /decisionId (required with awaiting_decision, names no decision, belongs to another item, or is already answered or withdrawn). decision_closed is a runs_write ack/answer/withdraw error (director profile), never an advance error. invalid_transition with detail.fromRole: none (a lifecycle-free item takes no trigger).

Troubleshooting

`gate_blocked`. data.results[0].error.detail.missing[] lists the notes. Fill them (Step 3) and retry. Also read detail.violations[].gate: missing and violations may both be present, and a review-pending or independence violation is not cleared by filling notes.

`seat_forbidden`. The item is a member of an open or paused run whose schema declares seats, and the caller may not send that trigger. detail.allowedSeats names who may (it always starts with coordinator). The run's coordinator resends with its coordinator token as top-level seatToken; otherwise leave the transition to the run, and never retry it token-less. This also covers resume of a decision-blocked run member: the coordinator sends it with its token, and a member seat may resume only if its seat transitions: list resume. Or close the run first.

`run_paused`. A start under a token of a run paused on its budget or attempt limit. Read detail.pauseReason and detail.pauseDecisionId; the answer comes through the director board. Do not retry.

Blocked by a dependency (`dependency_unmet`). Find the blockers; advance them first, then this item appears in their unblocked:

{"tool": "items_read", "select": "blocked", "args": {"ancestorId": "98d452e9"}}

Use /dependency-manager to view or change the edges.

Item is in the blocked role and `start` fails. start is not valid from blocked. Read blockedReason first. A pending decision (awaiting_decision, not resumable) must be answered, not resumed. Otherwise send resume (see Triggers), re-read context, then start.

Skip the review phase. complete jumps from work straight to terminal but checks every phase's required notes; fill what is missing or use cancel.

`resource_unavailable` (kind transient). A shared resource the item declares through a trait is held by another item. This is not a note gate: do not fill notes and do not spin-retry. Report data.results[0].error.detail.resources[] and data.results[0].error.retryAfterMs, work a different item, and retry later. To see the holder, read context resourceLeases (holderItemId, expiresAt); an operator can clear a stuck lease with DELETE /api/v1/resources/leases/{key} (admin). See Workflow Guide, Resource Leasing.

A parent cascaded unexpectedly. Cascades are by design: the first child starting moves a queued parent to work; the last child reaching terminal moves the parent to terminal. The cascades list shows each parent and why. A parent in review is never moved by that cascade (applied: false, review-pending): it needs its own explicit complete (or its review, then start).

`invalid_transition`. Read data.results[0].error.detail.fromRole and .allowed. A terminal item allows only reopen; a lifecycle-free item (fromRole: none) allows nothing.

Item is terminal and should be worked again. Send reopen; it returns to queue and its terminal parent returns to work.

What next? The next ready item, ranked by priority (limit defaults to 1):

{"tool": "items_read", "select": "next", "args": {"role": "queue", "limit": 3}}

An empty answer with a reason (claim_held, dependency_unmet) means wait; no reason means nothing matches.

For work inside an open run, the run's frontier is the authoritative ready list (ready, with inFlight and waiting beside it):

{"tool": "runs_read", "select": "frontier", "args": {"runId": "7c41e0a2"}}

Example: gated flow

1. context shows role: queue, canAdvance: false, missing: ["feature-summary"].
2. Resolve its guidance, draft the note from the conversation, notes_write upsert it with role: "queue".
3. context again: canAdvance: true.
4. advance transition start answers newRole: work and expectedNotes for the work phase. Fill those as work proceeds, then return control; the orchestrator advances to review or terminal.

Quick decision guide