Skip to content

Team PR review protocol

Five commands record the review of a pull request as typed facts on a team task, and one query reads whether the PR is ready at a head. This page is the lookup surface for them. For why a team would record review on a task, and what the chat is still for, see Team tasks. The CLI's side is team pr.

Ready is a recorded fact, not a merge gate

Nothing here merges a PR, checks CI, or makes a merge wait for readiness. pr.ready records that the current seats served one frozen head. Whether to merge is still the team's call.

The contract comes from hadron-server#3448, merged in hadron-server#3452 at 06f4b59c54a8e63b50c04d3f08c9d5d610acc25e. Every name below was read from the GraphQL schema and the protocol resolver at that revision. The rules are the platform specs cor:agt:050:08, :09, :21, :23 and :28, and cor:agt:110:01 to :03. This page cites them and does not restate them; where the two differ, the specs win.

The tasks

Task What it is
Build task The task that carries the PR. It needs a task reference of kind pull_request (AgentTask.references); without one, freezing is refused.
Seat task A direct child of the build task, one per review seat. A seat is bound to a slot at a head.

A slot is a name the build's owner chain puts in the schedule, such as a local review or a blind review. A seat is the child task that fills it.

The commands

GraphQL mutation Who may call it What it records
setReviewSchedule(taskRef, slots) The build task's owner chain; the assignee alone may not review.scheduled: the required slots. The latest event replaces the schedule.
freezePullRequestHead(taskRef, head) The build task's assignee pr.frozen: the head under review.
assignReviewSeat(taskRef, slot, head, supersedes) The seat task's owner chain review.seat.assigned: binds the seat to a slot at the frozen head.
recordReviewVerdict(taskRef, head, verdict, node, receipt) The seat task's assignee, while the seat is STARTED review.verdict. It does not finish the seat task.
recordReadyCall(taskRef, head) The build task's assignee pr.ready, only when the readiness rule holds.

Every command returns a PrProtocolResult: the task, and an action with the event code, a register state and, when mapped, the taskLoc and taskUrn (see the register). A caller without an Agent gets the code and the state WITHHELD only.

All five refuse a finished or cancelled task with TASK_ENDED, after checking authority. Writes are serialised on the App's task graph, so concurrent calls do not interleave.

Values

Value Shape
head A full 40-character hex SHA. Never inferred and never abbreviated. Stored lower-case.
slot id Colon-separated atoms, at most 64 characters in total. An atom starts and ends with a letter or digit and may hold _, . and - between. Slots in a schedule are unique and non-empty.
node, receipt Optional text, recorded and not fetched. Put no secrets in them.

The verdict enum

ReviewVerdict is APPROVE, CHANGES_REQUESTED, PASS, FAIL, CARRY or REFUSED. APPROVE, PASS and CARRY are positive. CHANGES_REQUESTED, FAIL and REFUSED are negative.

The frozen head

The build assignee freezes one head at a time. Seats are assigned at it, verdicts are recorded at it and readiness is read at it. A head that is not the latest frozen head is PR_HEAD_NOT_FROZEN on the readiness query and REVIEW_HEAD_MISMATCH when you assign a seat. A verdict is checked against the head its seat was assigned, not against the build's latest frozen head: a seat still STARTED after a newer freeze can record a verdict at its old head, and that verdict does not count at the newer head.

Freezing a head that already carries a negative verdict from any child seat is refused REVIEW_SEAT_NOT_SUPERSEDABLE, including a verdict from a superseded seat or a dropped slot. Going back to an old head cannot erase a finding. Answer it with a new head.

The seat rules

They apply in this order when you assign a seat.

  1. REVIEW_SEAT_NOT_SUPERSEDABLE. A current seat whose verdict at this head is negative cannot be replaced, with or without supersedes. A negative seat cannot move to another slot at the same head either. A schedule that drops a slot holding a negative verdict at the frozen head is refused for the same reason.
  2. REVIEW_SEAT_ALREADY_ASSIGNED. A seat task is assigned once. Use a new seat task to change anything.
  3. REVIEW_SEAT_SUPERSEDES_REQUIRED. A seat that replaces another in the same slot names the current one in supersedes.

supersedes that does not name the current sibling for the slot is REVIEW_SEAT_SUPERSEDE_INVALID.

A different actor cannot overwrite a negative verdict at the same head; only the actor who recorded it may re-rate it (REVIEW_SEAT_NOT_SUPERSEDABLE).

The readiness rule

The PR is ready at a head when, for every slot in the schedule, the current seat for that slot:

  • is FINISHED,
  • was assigned at that head and recorded its verdict at that head, in that slot,
  • has a verdict of APPROVE, PASS or CARRY, and
  • has a verdict whose actor is not the build's current assignee and not anyone who froze that exact head anywhere in the same App.

And one condition on the whole PR: no direct child's latest verdict at that head may be negative, including a child that is superseded or whose slot was dropped from the schedule. Such a verdict makes every slot not count, even when each current seat is positive.

Readiness is computed from event facts only. The pr.* and review.* properties never decide it (cor:agt:050:28).

recordReadyCall writes pr.ready only when this holds. Otherwise it is refused PR_NOT_READY, and the refusal carries the slots that do not count.

Reading readiness

query {
  pullRequestReadiness(taskRef: "AT0.12", head: "<40-hex head>") {
    ready
    head
    slots { slot currentTaskId state verdict head counts }
  }
}

slots has one row per scheduled slot. state is the seat task's status in upper case, or MISSING when no seat fills the slot. counts is true when the slot meets the rule above, including the whole-PR condition. A head that is not ready is a successful answer, not an error.

The read gate

pullRequestReadiness uses the same read gate as the task itself, including the App's own live key. It returns null for a task the caller cannot read, so an unreadable task looks the same as a missing one. An unfrozen head is PR_HEAD_NOT_FROZEN, and a build with no schedule is REVIEW_SCHEDULE_MISSING.

Refusal codes

Code When
TASK_NOT_FOUND The task, or a seat's build task, is not found or not readable.
TASK_NOT_OWNER The caller is not in the task's owner chain. The assignee alone has no standing.
TASK_NOT_ASSIGNEE The caller is not the task's assignee.
TASK_ENDED The task is finished or cancelled.
TASK_INVALID_TRANSITION A verdict on a seat that is not STARTED.
BAD_USER_INPUT A head, slot, schedule or verdict that is malformed.
PR_REFERENCE_MISSING Freeze on a build task with no pull_request reference.
PR_HEAD_NOT_FROZEN A readiness read at a head that is not frozen.
REVIEW_SCHEDULE_MISSING A build task with no schedule.
REVIEW_SLOT_UNKNOWN A seat names a slot that is not scheduled.
REVIEW_HEAD_MISMATCH A seat or verdict names a head other than the frozen or assigned one.
REVIEW_SEAT_UNASSIGNED The seat is not a child of a build task, or has no assigned seat.
REVIEW_SEAT_ALREADY_ASSIGNED See the seat rules.
REVIEW_SEAT_SUPERSEDES_REQUIRED See the seat rules.
REVIEW_SEAT_SUPERSEDE_INVALID supersedes is not the current sibling for the slot.
REVIEW_SEAT_NOT_SUPERSEDABLE See the seat rules.
PR_NOT_READY A ready call while a slot does not count. Carries slots.

The event codes

Each command appends one typed event, readable with hadron team events (see the CLI reference).

Event Written by
review.scheduled setReviewSchedule
pr.frozen freezePullRequestHead
review.seat.assigned assignReviewSeat
review.verdict recordReviewVerdict
pr.ready recordReadyCall

Each code is looked up in the register like any other, and the answer comes back as the command's action. The lookup runs after the write has committed and never fails it.