Skip to main content

Roles sign off on a task before a person reviews it

People want agents to check each other's work before it reaches them, so that what they review has already been looked at from every angle it needs, such as security or operations. We decided that a task can need sign-off from roles: each such role must sign off before a role may move the task to in review or done. A sign-off is not an approval. It says the work is ready for a person's review from that role's angle; what merges and what is done is still decided by people (ADR 0017), and in review is unchanged. A role signs off with sign_off, only on a task its own run works on and while the task is assigned to it, so a role is asked for its sign-off the way any work reaches it: the task is handed to it as todo, and it hands the task back, signed off or with what to change in its handoff.

Considered Options​

  • Agents as final approvers, whose approval lets a pull request merge: rejected for now. It would overturn ADR 0017, and an agent approval would have to stand in for a person's on the forge, where the token is often a person's own.
  • Reviewers and approvers as two kinds of reviewer: rejected; both look at the work and give a verdict, so the names could not be told apart. What differs is what the verdict lets happen next, so the role's verdict is named for that.
  • Role reviews as a step of their own while a task is in review: rejected; in review would no longer mean a person's review, and a task has one run at a time. Handing the task to each role as todo uses the workflow agents already follow.
  • Sign-offs that go stale on new commits, as approvals do: rejected for now. Asking each role again after every change costs more than it protects, while the final review still sits with a person. Real reviews often work the same way.
  • A "changes requested" state, or withdrawing a sign-off: left out. The handoff already carries what to change, and a sign-off that never goes stale gains little from a third state.

Consequences​

  • A sign-off holds until the role is removed, whatever changes after it. This is an accepted risk: sign-offs raise the floor, and the guarantee stays with the person who reviews.
  • The guard applies to roles, on in review and done. Done is guarded too, so an agent refused in review cannot finish the task instead, and so a change made without a pull request, such as to a running cluster, still waits for its sign-offs. Cancelled is not guarded. People are not held back: whoever moves a task themselves decides.
  • People and roles can add a role whose sign-off a task needs; only people can remove one. Adding raises the bar; removing lowers it, so it is a person's call, and is how one waives a sign-off on purpose.
  • A role may sign off on its own work when it is among those asked. Telling authors from signers is left to whoever chooses the roles, which only people can take back.
  • Who coordinates is the role that hands the task to each signer. A signer hands it back to whoever handed it over, so signers need not know about each other.
  • A change to the roles a task needs sign-off from is a comment on the task, by whoever made it, so people see it and the task's agent reads it with its next turn's news. It does not wake a run that waits for a reply.
  • A deleted role's sign-off is no longer needed, or its tasks could never reach review.