Reviewing a change

Approve or reject the gate a Kraft work item waits at, and comment on its change, in the web UI or from the CLI. You can comment while the item runs, while it is stopped and waits for you, or at a pending gate, and your comments reach the next agent. Comments never interrupt an agent by themselves. Only request-changes does, and only the node it targets.

To approve or reject a gate:

For the screen's own parts, see The review page.

Before you start

• A work item to review. To approve or reject, it waits at a gate: the board shows it under Needs you.
• For the CLI, the ID of the work item. kraft view list shows it (add --all outside the repo's directory).
• For the CLI, to pass that ID to every verb below. Left out, a verb defaults to the work item whose worktree you are standing in, which a reviewer rarely is.

Approve or reject in the web UI

1. On the board, click Review to approve on the item's row. It opens the review page at the waiting gate: on the gate's document when the gate has one, and on the diff when it has none. Or open the item and select the waiting gate in its chain: the gate's panel has Read filename (the document, only when the gate has one), Review changes (the same review page), Approve and Reject….
2. Read the document and the diff.
3. Decide:
   • Approve on the gate's panel passes the gate at once. With a must-fix thread open it is not greyed out, but the click is refused with must-fix review threads are not resolved, shown beside the buttons.
   • Approve at the top of the review page, which a gate with a document has, also submits at once, and is greyed out while a must-fix thread is open.
   • At a gate with no document, the bottom bar offers Finish review, and Approve is an outcome in Finish your review. Once a review has been sent, the bar offers Approve directly, and with drafts pending it opens Finish your review first, so a new comment is never sent with an approval unseen.
   • Reject… on the gate's panel opens a note box under Reject gate · goes back to node. Write what is wrong, because the next agent reads it and Reject stays off until there is a note. Cancel closes the box.
   • Request changes on the review page is a rejection too: the dialog reads Reject gate · goes back to node, and its button reads Reject to node. Your threads and summary are the note.

Approving on the review page shows Approved · gate passed and returns you to the item's page.

Comment and finish a review in the web UI

The item's review page does everything the comment verbs below do: click Review changes on the item's page, or open /work-items/<id>/review. Each part of the page does what one CLI verb does:

A comment you add on the page is a draft, as with kraft item comment, until you finish the review. Viewed, which marks a file as read, has no CLI equivalent: it only tracks your own progress through the diff.

Approve or reject from the CLI

kraft item approve ID
kraft item reject ID --note "the plan skips migrations"

Each acts on the gate the item waits at, and prints what it did and where the item stands:

approved spec_approval on <id>; the item is now running

reject prints rejected <gate> on <id> in the same form. --gate names the gate you mean to decide, and is refused with 409 when that gate is not the one pending. reject needs a note, which the next agent reads, and --node sends the work back to a node other than the gate's default.

approve is refused while a must-fix thread is open, and when the gate is not the one pending. Item verbs has every flag. kraft item review makes the same decisions together with your drafted comments, as Comment and send a review shows.

Comment and send a review from the CLI

1. Comment on the lines you mean:

   kraft item comment ID --body "this leaks the connection" --file src/db.py --lines 40-46 --label must-fix
   

   
   It files a draft and prints where the thread sits, the lines it quotes, and what happens next:

   drafted thread <thread-id> on src/db.py:+40 to +46
       | <the quoted lines>
   it goes out with your next kraft item review
   

2. Read your drafts:

   kraft view threads ID
   

   
   Each thread is a line with its ID, where it sits and its tags, then its comments. A draft carries the tag draft and (draft) after its author:

   <thread-id>  src/db.py:+40 to +46  [must_fix open draft]
     you (draft): this leaks the connection
   

3. Send them with one outcome:

   kraft item review ID comment --summary "a few notes, nothing blocking"
   

   
   No agent sees a draft until you send it. The outcome is one of three:

   Outcome	What it does
   comment	Queues your drafts for the next agent that runs. It never stops anything, and it works whether or not a gate is pending. Agents answer questions in the thread, and at a gate the gate stays open.
   approve	Needs a pending gate: it clears it, the same as kraft item approve.
   request-changes	Redoes work now. See Request changes.

   
   For comment with no gate pending, the CLI prints the review's ID and outcome:

   review_id    <review-id>
   outcome      comment
   gate         -
   reply_agent  False
   

Block approval with a must-fix

A comment labeled --label must-fix blocks every gate approval on the item until it is resolved, no matter which gate it was filed at or whether one was pending at all. kraft item resolve THREAD clears it. kraft item reopen THREAD puts it back if the fix did not hold up.

Comment while it runs

Every agent dispatch carries the item's unanswered threads: the next implementation run, every verify reviewer, every fix-loop round.

• A working agent (no review skill) is told to address each thread and reply with kraft item reply.
• A reviewer agent is told to judge the change against the threads, and reports an unaddressed must-fix as a finding.

A thread drops off that list the moment an agent replies or you resolve it.

Request changes

kraft item review ID request-changes --summary "please address the must-fix"
kraft item review ID request-changes --node implementation --summary "redo this part"

Where the work restarts is --node when you give it. Without --node, at a pending gate it is the gate's reject target. With no gate pending, Kraft derives it from your threads: the earliest node, at or before the one now running, that wrote what a thread is about (a thread's own file_path, or the node it names). A whole-change comment falls back to the current working node.

What happens next depends on the item:

The response says which of these happened, and the CLI prints it: request-changes -> implementation (threads on src/db.py), rerun.

A gate with a must-fix does not open

Reaching a gate with an unanswered must-fix bounces it back to the reject target instead of opening, the same as if you had rejected it yourself. The gate's own reject-loop limit caps the bounces, so an agent that never answers cannot loop forever.

When one more bounce would pass that limit, the gate opens for you, and approving it still answers 409 until you resolve the must-fix. A gate with only unanswered questions or nits opens as usual, with the reply agent already launched to answer them.

Compare attempts

kraft view compare ID --from base --to latest
kraft view compare ID --from attempt:1 --to attempt:2 --stat

base and latest (the working tree) resolve at any time. last_review needs a review you have already submitted, and attempt:N needs a pending gate. latest can only be the --to end. --nodes a,b limits the diff to files those nodes touched.

For agents

A worker replies to a thread it was handed with kraft item reply <thread-id> --body "..." --claim fixed|answered|should_fix. Every other review verb above is refused from inside a worker's own worktree. Reviewing is a person's job, or an assistant acting on a person's behalf from outside the item.

Check it worked

• After an approval, the CLI prints approved <gate> on <id>. On the review page, Approved · gate passed shows. The item leaves Needs you and runs on, until it reaches the next gate or stops.
• After you send a review, run kraft view threads ID again. The sent threads no longer carry draft: [must_fix open].

Next steps

• The review page: the toolbar, the comment box and the bar along the bottom, part by part.
• Item verbs: every kraft item verb, including approve, reject, review, comment and reply.
• View verbs: view threads and view compare in full.
• Events: the events a review writes on the item's timeline.