Chain file keys

What the final review approves

The head the approval of a chain_finalized gate pins, and what a later mr.merge task may merge once it is recorded.

Added in 2.3

Approving the chain's first chain_finalized gate records the branch tip it approves, in every checkout a merge could push: the item's own, and each workspace member not merged yet. Skipping that gate records the tips it passes the same way. They are on the gate_approved (or node_skipped) event, as tips.

The approval names the head you were shown. The item page serves it as review_head (kraft view show prints it as head), and kraft item approve --head, kraft item skip --head and kraft item review ... approve --head send it back. Without it the approval is refused with a 409, and so is one whose head is no longer the branch's: look again.

The web UI sends the head of the diff it showed.

Right before an mr.merge task asks the forge to merge, or to queue the merge request again after a merge train's own runners failed, it reads the tip it would push. When that isn't the approved one, it merges nothing and pushes nothing, records merge_refused_unreviewed, and the item stops for you:

  • On a node with on_merge_rejected, Kraft holds the item at restart_from, with the gates from there to the merge reopened.
  • On any other node, it holds the item at the chain_finalized gate, reopened.

A retry from there walks back through the final review, which sees the new code. This holds whatever changed the branch: an agent, an escalation, a commit of yours, or anything else.

The merge call names the head too (gh pr merge --match-head-commit, glab mr merge --sha), so the forge itself refuses any other head, however long after the call it would have merged. A commit that reaches the merge request on the forge is held the same way, with merge_refused_unreviewed.

If the commit landed before Kraft pushed, or the forge refuses the head, Kraft fetches it into the item's branch when that is a fast-forward and the worktree is clean (never for an in-place item). The reopened final review then shows it.

A merge still open when Kraft finds the forge's head moved is cancelled first. One that has already landed can't be undone: the item stops for you with merge_landed_unreviewed, and kraft item complete or kraft item skip on the merge node ends the stop.

Kraft's own changes to the approved head carry the approval over, recorded as reviewed_head_repinned: a rebase onto the base branch that needs no conflict resolved, with no agent involved (the merge's own forced rebase, an mr_rebase task, the rebase on approval, resume or retry), and a workspace root's commit that points it at its merged members. A rebase that needed a conflict resolved, or that rebased a head nobody approved, carries nothing over.

An item whose final gate was approved before this check existed, or whose chain has no chain_finalized gate, merges without it.

Copyright © 2026