Status Progression

Status Progression — Current (v3)

Guides role transitions for a WorkItem: identify the item, check gate status, fill missing notes, and advance. Handles all triggers including block, resume, and cancel.

Step 1: Identify the Item

Resolve $ARGUMENTS to a UUID via query_items search (operation="search", query=$ARGUMENTS, limit=5); if ambiguous, present matches via AskUserQuestion. If $ARGUMENTS is empty, ask for a UUID or title fragment.

Step 2: Check Current State

Once you have the item ID, call:

get_context(itemId="<item-uuid>")

Parse the response and display a status card. Use this format:

◉ "Implement authentication module"
  Role:     work
  Gate:     ⊘ blocked — 2 required notes missing
  Missing:  implementation-notes (work, required)
            session-tracking (work, required)
  Guidance: "Describe what was implemented, which files changed, and why
             the approach was chosen..."

◉ "Design API schema"
  Role:     queue
  Gate:     ✓ open — all required notes filled (or no schema)
  Next:     advance_item(trigger="start") → work

Fields to surface from get_context response:

If the item has no schema (no tags matching a schema key), noteSchema will be empty and the gate is always open.

Step 3: Fill Missing Notes (if Gated)

If gateStatus.canAdvance = false, the item cannot advance until required notes are filled.

For each missing note, check whether its content can be inferred from the conversation context. If yes, fill it directly. If not, ask the user what to capture.

Use guidanceKey to prompt the user — resolve its guidance text via query_items(operation="schema", itemId=...). Only one guidanceKey is returned — for the first unfilled required note. See schema entries list for all unfilled notes.

Fill notes with:

manage_notes(
  operation="upsert",
  notes=[
    { itemId: "<uuid>", key: "implementation-notes", role: "work", body: "<content>" },
    { itemId: "<uuid>", key: "session-tracking", role: "work", body: "<content>" }
  ]
)

After filling, re-check gate status:

get_context(itemId="<uuid>")

Confirm gateStatus.canAdvance = true before proceeding to Step 4. If notes are still missing after the upsert, show the updated status card and repeat for any remaining gaps.

Step 4: Advance the Item

With the gate open, call advance_item with the appropriate trigger (trigger semantics are documented in the advance_item tool description):

advance_item(transitions=[{ itemId: "<uuid>", trigger: "start" }])

Parse the response and report the transition result:

✓ Advanced: queue → work
  ↳ Cascade: "Feature: Auth System" also moved queue → work
  ↳ Unblocked: "Write integration tests" (was waiting on this item)
  ↳ Next phase notes:
      implementation-notes (work, required)
      session-tracking (work, required)

Fields to check in the advance response:

If cascadeEvents is empty, omit the cascade line. If unblockedItems is empty, omit the unblocked line. If expectedNotes is empty or absent (no schema), omit the next phase notes line.

Troubleshooting

Problem: advance_item fails with "required notes not filled"

Cause: The current phase has required notes that have not been upserted yet. Gate enforcement runs before the transition executes.

Solution: The gate-failure error already lists the missing note keys. Fill each one with manage_notes(operation="upsert"), then retry advance_item. Call get_context only if you need broader item state.

Problem: Item cannot advance — it is blocked by a dependency

Cause: Another item has a BLOCKS edge pointing to this item, and that blocking item has not yet reached terminal role.

Solution: Find the blocker:

query_dependencies(operation="get", itemId="<uuid>", direction="incoming", includeItemInfo=true)

Identify the blocking item (role will be non-terminal). Advance the blocking item to terminal first. When it completes, the current item appears in unblockedItems.

Problem: Item is in BLOCKED role and start fails

Cause: The item is in the BLOCKED role (was explicitly blocked with trigger: "block"). The start trigger is not valid from BLOCKED — it is only valid from QUEUE, WORK, or REVIEW.

Solution: Use trigger: "resume" to return the item to its previous role:

advance_item(transitions=[{ itemId: "<uuid>", trigger: "resume" }])

After resuming, check get_context and then advance normally with start if the gate is open.

Problem: Want to skip the review phase and go directly to terminal

Cause: The item is in WORK role and has a review-phase schema, but verification is already done or not applicable.

Solution: Use trigger: "complete" instead of start. This jumps from any non-terminal role directly to TERMINAL, but it checks ALL required notes across all phases first:

advance_item(transitions=[{ itemId: "<uuid>", trigger: "complete" }])

If any required notes across queue, work, or review phases are unfilled, the gate will block this call and list the missing notes. Fill them, then retry.

Problem: advance_item fails with errorCode: "resource_unavailable"

Cause: The item declares a shared resource (via a resources: trait, mode: exclusive) that another item currently holds — a real resource-lease conflict, not a note-schema gate failure. errorKind is "transient", distinct from the gate-block/ownership/policy error codes above.

Do NOT treat this like a gate failure — do not "fill in more notes" and do not spin-retry the same advance_item call. The fix is to wait (retryAfterMs names a backoff hint) or work a different item; retrying immediately will almost always fail again since the response never discloses when — only that — the key is contended. contendedResources names the contended key(s) only; the current holder's identity is never included in this response by design.

Solution:

1. Report the contended key(s) to the user/operator rather than retrying silently.
2. To diagnose who holds it: get_context(itemId="<uuid>") → resourceLeases block (shows holderItemId/acquiredByActorId/expiresAt for the contended key), or the REST route GET /api/v1/resources/leases for a fleet-wide view (ADMIN capability needed to see the holder's actor identity).
3. If the holder is confirmed stale/crashed, an operator can force-release via DELETE /api/v1/resources/leases/{key} (ADMIN capability) rather than waiting out the TTL.
4. Otherwise, move on to a different item and revisit this one later.