Oko
Oko/Docs

Command reference

oko review harsh

The harsh-review queue: commit candidates no reviewer other than their author has read. The author queues its candidate (`tama reviews harsh request`, which calls enqueue); nobody is messaged and no session is started. A session asks for an entry: `oko work next --executor SESSION` hands it, before any other item, the waiting entry it did not stage whose item ranks first in the work queue (whose build-first pool, the critical path, comes first), then the oldest; `oko review harsh take --executor SESSION` does the same ranked by the local defect register alone (open defects, highest priority first), so it waits on no broker or database. That session reads it with `tama reviews harsh show --queue ID` and records its round with `tama reviews harsh record --queue ID`, which keeps the round where the author's next commit attempt reads it and marks the entry reviewed here.

Invocation#

Command
oko review harsh enqueue --repository PATH --parent COMMIT --tree TREE --message-file FILE --author SESSION [--item ID] [--within-minutes N] | list | show ID | done ID --reviewer SESSION --findings N | take --executor SESSION [--product P] [--json]

Inputs and options#

  • enqueue: the checkout, the commit the candidate follows, its staged tree, the message file the commit attempt carried and its author (a session, or operator); --item the task or defect the commit repairs, by which the entry is ranked; --within-minutes how long its author declares a round may take, a positive number. The parent must be a commit and the tree a tree of the checkout (`git cat-file -t`). Each entry carries its patch: `git patch-id --stable` of the tree's diff over its parent. The same patch with the same message is the same change, answered as the entry already queued with sameChange true: a waiting or held entry moves to the new parent and tree, a reviewed one keeps the tree its round read and lists the new one under restaged, which its round covers, so a rebase needs no new round. A changed patch or message is a new candidate, and an author has one open entry per checkout: while its entry waits or is held, a new candidate is refused naming it (`<author> already has harsh-review entry <id> open for <checkout> (tree <tree>, waiting for a reviewer | held by <session> for its round); a changed candidate is queued once that round is recorded, …`); once the round is recorded it is a new entry.
  • done: the reviewer session and how many findings its round made. take: the session asking, and with --product only entries whose checkout is that product (work next passes its own --product the same way). A session that holds an entry it has not reviewed is answered that entry again, unchanged, so it never holds two.

Output and state effect#

  • Each verb prints the entry, or {entries, measure} for list, each entry with its state (waiting until a session is handed it, assigned while that session has not recorded its round, reviewed after), waitedSeconds, from the request to now while it waits or to its round once reviewed, its patch, restaged and previousReviewers. measure is {reviewed, meanSecondsToRound, secondsToRound}: how long rounds took from request to round. `oko work next` and take hand an entry as a work item of kind harsh-review with a title, its product (the checkout's name), the reason it comes first and the command that reads it, and name that session the entry's reviewer; take with nothing free prints {taken: null, why}. An entry whose holder has held it longer than its declared minutes is handed to the next session that asks, never to its author or its holder again; the first holder is named under previousReviewers (session, movedAt, movedTo, told), and its next work next or take answers a work item of kind harsh-review-moved listing each such entry and who holds it now, once, so it stops reading. One round per entry, the first recorded: a round by a holder whose minutes passed still stands if it comes first, and done then answers moved {heldUntil, movedTo}. The queue is ~/Library/Application Support/Oko/harsh-review-queue.json; OKO_HARSH_REVIEW_QUEUE moves it; every change is made under its lock. Oko Desktop → Defects shows the same queue and measure through the native API (`review` domain, `harsh_list`). tests/review/harsh.rs and harsh_held.rs (`--test review-harsh`) run enqueue, list, show, done and take, restaging and moved holds, with their refusals, through the built CLI in a home of its own, over candidates staged in a git checkout of its own.

Refusals and safe exits#

  • A missing field refuses by name (`a harsh-review entry needs --tree`); an empty message file refuses; a parent or tree the checkout does not hold refuses (`--tree <tree> is no object of <checkout> (git cat-file -t found none), so no reviewer could read the candidate`), and one of the wrong type refuses naming it (`--tree <object> is a commit of <checkout>, not a tree, so no reviewer could read the candidate as its tree over its parent`); a patch git cannot read refuses with git's cause (`git patch-id of candidate tree <tree> over <parent> in <checkout> failed …`); a second open candidate of the author in one checkout refuses naming the first; --within-minutes that is not a whole number, or not positive, refuses by name; an unknown or ambiguous id refuses naming it; the author as reviewer of its own entry refuses (`<session> staged harsh-review entry <id> and cannot review it`); a second round on a reviewed entry refuses naming the first (`harsh-review entry <id> was reviewed by <session> at <time>; a changed candidate is a new entry`); a time in the queue that is not RFC 3339 refuses naming it.

CLI reference#