Oko
Oko/Docs

Command reference

oko work next

Answers the first open work item and why it leads: a defect of the build-first pool, then an orphaned task whose executor is observed stopped, then the rest of the ranked defect queue. `oko work queue` shows the entire order.

Invocation#

Command
oko work next [--executor ID] [--product P] [--json]

Inputs and options#

  • The build-first pool leads everything: open defects put in it with `oko defects category set <id> build-first … --attest TEXT --by SESSION`, whose author attested that their repair decides the quality of all other work (the delivery path, the rules agents work under) and changes no product behaviour. A category kept without an attestation does not lead. Within the pool the order below applies.
  • An open task whose leading executor is observed not alive with no process holding it comes next. Oko settles the task's current ledger status and claim; a live new claimant removes it from the orphaned set. `oko tasks claim <task-id> --by <executor>` transfers it and keeps the previous holder and transfer history. A missing process observation, transcript or database read refuses rather than presenting an incomplete queue.
  • The order, highest first: while the delivery path is down (`stado ci delivery` names a refused step, a step no pass holds, or a failing Stado unit), the defect that blocks it — the Oko defect Stado recorded for the refused step, or the open defect recorded with the shape `the delivery path is down` — since no repair of any product reaches a machine before it; then an item a release waits on, directly or through others (the delivery chain — an install or push refusal recorded with `oko blockers record --blocks release-<repository> --waits-on <defect>` puts that defect in it); then items whose own product's release does not itself wait on other work, since a repair that cannot reach a machine ranks below one that can; then how many open items wait on it in `oko blockers graph`; then how many operator rulings stand on it; then a class (whose mechanism repairs every instance) before an instance; then the item open longest. The reflection routine (`oko reflection run` and the standing routine) records that defect against Stado when the path is down and none is open, and reports under `delivery` what it read or why it could not.
  • Every item with no recorded repair comes before every item whose repair is claimed — recorded with `oko defects repaired`, or kept as a claim by the register's migration — and not verified by its completion measure. A claim on its author's word is still work: it is served after the unrepaired items, ordered among themselves the same way, with `claimed` naming the revision and a reason naming the verification it needs: compare the repair plan with the committed source, CLI, GUI, docs and test, search for remaining instances, and reopen it with what is missing (`oko defects reopen`). A defect whose completion measure passed is done work waiting for its release and is left out.
  • A defect whose repair claim holds in the claim register (`oko claims verify`: a real test, and for a build-first item an adversarial reviewer other than the author, each holding at the claimed revision) is no longer served; the reason of a claimed item names `oko claims list --subject <id>` and `oko claims verify` as where its verification is recorded.
  • --executor ID keeps the defects that session owns or that nobody owns, and orphaned tasks any executor may claim; --product P keeps that checkout's items.

Output and state effect#

  • Prints `<id> <product>: <title> (holder <session>)` and `why: <reason>` for each item, or `no open work waits`. A build-first item's reason starts with `build-first: it decides the quality of the other work (<attestation>)`. An orphaned task's reason names the observed stopped executor, open task and claim command. Defect reasons retain their delivery, release, dependency, ruling, class and age evidence.
  • --json prints one ordered array: task items carry {kind: task, id, task, title, product?, owner, sessionId, previousClaimedBy?, claimHistory?, reason}; defect items carry {kind: defect, id, defect, product, title, owner, buildFirst, blocksDelivery, claimed, releases, deliveryStands, unblocks, rulings, class, foundAt, reason}, where buildFirst is the attestation of a pool item and null otherwise. The native API's blockers/work_queue action and Oko Desktop → Blockers → Work queue show the same items in the same order, the attestation under `Build first`, and the claim lineage. Supervision's defect ranking serves the pool first too.

Refusals and safe exits#

  • A verb the command does not take is refused naming it (exit 2); a flag other than --executor, --product and --json is refused by name, and so is either of those without its value.
  • A failed agent inventory, process observation, task reading, transcript or database operation refuses naming it; so does an unreadable defect graph, claim register or `stado ci delivery` report. Oko will not call a missing observation an empty queue.

CLI reference#