Oko
Oko/Docs

Command reference

oko tasks review

The operator walks proposed decisions about his tasks on his own terminal and decides each himself: close, withdraw, keep or skip, one task at a time or a page at a time, with the proposal and the task's recorded evidence beside it.

Invocation#

Command
oko tasks review [--from PATH ...] [--class CLASS ...] [--product PRODUCT ...] [--page N] [--json]

Inputs and options#

  • --from names a review file or a directory of them (every `*.jsonl` file in it, in name order); repeat it for several. A review file is JSON Lines, one proposal per task: `{"id": "task-…", "class": "done", "product": …, "evidence": …, "quote": …, "needs": …, "duplicate_of": …}`; id and class are required, the rest may be null or left out. Without --from the walk is every task with a recorded evidence row that no verdict has answered since, oldest evidence first, each with the class `done`; an evidence row recorded before rows carried a task identity is not listed.
  • --class keeps the proposals of the named classes, --product those of the named products; repeat either for several. Each named value must be one the review holds.
  • --page N shows N tasks at once, numbered 1 to N; without it the tasks come one at a time.
  • At the prompt the operator types a line: the decision (`close`, `withdraw`, `keep` or `skip`), then on a page the task numbers it is for or `--all-shown` for every undecided task shown, then any words of his own. On a page of one, the decision alone is for the task shown. `next` leaves the page's undecided tasks and shows the next page; `quit`, or the end of the terminal's input, ends the review.
  • --json prints the closing summary as JSON.

Output and state effect#

  • Reads the proposals, the tasks' rows, their evidence rows and their verdict rows from the shared database, then shows each task: its identity, class, product, session and number, its words, the proposal's evidence, the operator's words it quotes, what it needs and what it duplicates, and the recorded evidence (commit, report, who recorded it and when) with the report's text when the report is a document on this machine; a JSON attestation, a JSON Lines record file or an unreadable report is named, not shown. A task whose newest verdict is the operator's own is left out as already decided, so a review taken up again starts where it stopped; a proposed task the shared database holds no task object for is left out and listed at the end.
  • Each typed decision is recorded at once as the operator's own verdict (`judged_by` `operator`) in `oko_task_verdicts`, its reason quoting the line he typed and the proposal he read: `the operator decided <decision> in oko tasks review, typing "<line>" on his terminal; the proposal he read: class <class> from <file>:<line>; <evidence>; …`. `close` records the completion claim `oko tasks close` records; source-bound qualification still decides the task's standing. `withdraw` records `withdrawn`: no work owed, by the operator, so no transcript quote is asked for. `keep` records `not done`, keeping the task open. `skip` records nothing. Every task's session is settled from its live transcript before its verdict is bound, the sessions of one decision side by side.
  • When the review ends it prints, per decision, how many tasks were decided and how many were recorded, each refused task with its refusal, how many were left undecided and how many were already decided. Oko Desktop's Tasks toolbar Review sheet reads the same walk and records the same verdicts through the native API.

Refusals and safe exits#

  • Run with no terminal — from a pipe, a hook or an agent’s tool call — it refuses before reading anything with “oko tasks review records the operator's own decision and is confirmed on the terminal it runs from; this process has no terminal (<error>), so nothing was recorded”.
  • Usage refusals exit 2: “oko tasks review does not take <flag>; it takes --class, --from, --product, --page, --json”; “oko tasks review takes only flags; it was given <word>, which it would not read”; “oko tasks review: every --from takes a value; write --from <text>” (and the same for --class and --product); “oko tasks review: --page takes a positive whole number, got <value>: <cause>”.
  • Review files: “the review file <path> cannot be read: <error>”; “the review directory <path> cannot be listed: <error>”; “the review directory <path> holds no .jsonl review file”; “<path>:<line> is not a review proposal (<error>); each line is a JSON object with id and class, and optionally product, evidence, quote, needs and duplicate_of”; “<path>:<line> proposes "<id>", which is not a task identity”; “task <id> is proposed twice, at <path>:<line> and at <path>:<line>; keep one proposal per task”.
  • Selection: “--class <values> matches no proposal of this review; the values it holds for --class are: <values>” (the same for --product); without --from, “--product selects a review file's proposals by their product, and tasks Oko lists by their recorded evidence carry none; name the review file with --from”. Nothing is shown or recorded on these refusals.
  • At the prompt, a line that decides nothing is answered and asked again: “<word> is not close, withdraw, keep or skip, nor next or quit”; “<n> is not a task of this page; its tasks are 1 to <count>”; “task <n> of this page is already decided”; “name the tasks of this page <decision> is for by their numbers, or write --all-shown”; “type close, withdraw, keep or skip, or next or quit”.
  • A task its decision cannot be recorded for is refused by itself and the review goes on: “no live transcript of session <session> on this machine; nothing was recorded”; “session <session> could not be settled for this decision (its cause is on standard error); nothing was recorded”; “cannot record against <id>: session <session>'s current ledger contains no task with that identity …”. A decision whose reads fail as a whole is answered “nothing was recorded for this line: <cause>” and its tasks stay undecided.

CLI reference#