Human on the loop

Piyaz runs agents on a human-on-the-loop (HOTL) model. Agents do the work and record it; a human stays on the loop to approve the merge, rather than stepping into every action. 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. Composer's fix loop sends these back to the implementer and re-reviews, up to two rotations, before the result reaches you.
• 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.

Asking for a review

You trigger a review in plain language: name the task or the PR, and tell the agent to ground its read in the diff.

review MET-1. File-cited, do not rubber-stamp. Read the diff first, then reason
across security, performance, reliability, observability, and codebase standards.

Treat every finding as a claim to confirm, not a verdict to apply. Some may be deliberate choices already recorded on the task.

take each finding and reason it first. Some may be known decisions recorded on
MET-1. Confirm against the code before you change anything, then plan and fix.

For a security-sensitive change, push for a thorough sweep:

review this change for security. Read the diff line by line, check removed behavior,
cross-file effects, and the auth paths, and cite file and line for every finding.
Rank by severity and drop anything you cannot verify.

Why review never flips in_review to done

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. A request-changes is handled by composer's bounded fix loop, not by the reviewer, and an approve does not promote the task on its own. Promotion is a separate decision.

By default that decision is yours. Composer runs under a merge policy you choose once per session, and the default (never) keeps the merge and the in_review → done transition in your hands. If you set ask-each or auto-on-approve, composer makes the merge and writes done for you, but only on an approve verdict with green CI, and only because you authorized that policy. See The merge gate.

How the operator finalizes

Under the default policy the HOTL 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 for another fix rotation. After a task reaches done, run propagation so downstream tasks see the finished work.