Reviewing a change

You can review a Kraft work item whenever you like — while it is running, while it is stopped for a human, or at a pending gate. Comments never interrupt an agent by themselves; only request-changes does, and only the node it targets.

Drafts and sending

kraft item comment --body "this leaks the connection" --file src/db.py --lines 40-46 --label must-fix
kraft view threads
kraft item review comment --summary "a few notes, nothing blocking"

kraft item comment files a draft. Drafts are invisible to every agent — and to kraft view threads output as anything but a draft — until you send them with kraft item review. That one command is one of three outcomes:

• comment queues your drafts for the next agent that runs. It never stops anything, and it works whether or not a gate is pending.
• approve needs a pending gate: it clears it, the same as kraft item approve.
• request-changes redoes work now — see below.

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-id> clears it; kraft item reopen puts it back if the fix did not hold up.

Commenting while it runs

Every agent dispatch — the next implementation run, every verify reviewer, every fix-loop round — carries the item's unanswered threads. A working agent (no review skill) is told to address each one and reply with kraft item reply; a reviewer agent is told to judge the change against them, and reports an unaddressed must-fix as a finding. A thread drops off the list the moment an agent replies or you resolve it.

Request changes

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

With no --node, the target is derived 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.

The review page shows where the work will restart, the nodes that run after it, and which rejection round this would be, before you submit. It reads the same target the submit acts on, so the two cannot differ.

• If the target is the node that is running, it stops and re-runs now, with your review as its note.
• If the target is an earlier node, nothing running is touched. The rewind is queued and takes effect the moment the running node finishes, or on your next kraft item resume or kraft item retry.
• On a needs_human item with nothing else running, it retries at the target immediately.
• On a paused item, only the rewind is queued — resuming a paused item is your call, so request-changes does not do it for you.

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

Gates don't ask twice

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, capped by the gate's own reject-loop limit so an agent that never answers cannot loop forever. A gate with only unanswered questions or nits opens as usual, with the reply agent already launched to answer them.

Comparing attempts

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

base, last_review and latest (the working tree) resolve at any time. attempt:N needs a pending gate. --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 human's job, or an assistant acting on a human's behalf from outside the item.