Human in the loop

Agents do the work and record it. A human approves the merge. The in_review status is where those two responsibilities meet.

The in_review gate

When an agent finishes a task, its terminal write is in_review, not done. At that point the work is complete, the PR is open, tests and lint and typecheck are green, and the Completion Protocol payload is populated. The task is parked, waiting for a human to inspect the PR.

From in_review a task goes one of two ways: the operator approves and moves it to done, or the operator sends it back to in_progress for rework. Both transitions belong to the human.

The review agent's verdict

Before the human decides, a review agent can produce a structured verdict on the work. It reads the task at piyaz_context depth='review', which renders the implementation plan alongside the execution record, surfaces the PR, and computes plan-vs-files drift. It returns exactly one of three values:

• approve: the work meets the acceptance criteria, the lenses find nothing worth blocking, CI is green, the PR is mergeable.
• request-changes: at least one lens has a finding to fix, or an acceptance criterion is unmet, or there is unrecorded drift. The PR can land after one rotation back through in_progress.
• block: a structural problem the implementer cannot fix in one rotation: CI red and unresolvable, the diff ships a different task than scoped, or a security finding that makes the current diff unsafe to merge.

The verdict carries file-cited reasoning across five lenses (security, performance, reliability, observability, codebase standards), an acceptance-criteria evaluation against the diff, and a downstream-impact list. It picks one of the three, no hedging.

Why agents never flip in_review to done

The verdict is advisory. The review agent is read-only over Piyaz: it owns zero status transitions and does not touch the working tree. The verdict travels in its return message; it does not land on the task. Keeping promotion in human hands means a request-changes or block is not auto-retried and an approve is not auto-merged. The human reads the verdict, reviews the PR on GitHub, and makes the call.

How the operator finalizes

The operator inspects the PR, weighs the verdict, and either approves and merges the PR then moves the task in_review → done, or sends it back to in_progress so the implementer rotates once on the fix. After a task reaches done, run propagation so downstream tasks see the finished work.