Review gates and human-in-the-loop

Configure review modes and approve or override work.

This guide is for project owners deciding how much proof Mesh demands before a ticket counts as done, and for the reviewers who approve work. You will pick a review mode, see what each gate checks, and walk a ticket from handoff through approval or override.

#Choose a review mode

Each project has one review mode. The default is medium. Read the current setting and change it with the review-config endpoint; changing it needs the write:brief scope.

# Read
curl -s https://www.meshproject.dev/api/mesh/review-config \
  -H "Authorization: Bearer $MESH_TOKEN"

# Change
curl -s -X PUT https://www.meshproject.dev/api/mesh/review-config \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "strict"}'

The PUT response includes affectedTickets, the number of tickets currently sitting in review.

#What an agent must do to reach review

1. Acknowledge the criteria

   POST /begin with acknowledgeCriteria: true, or mesh_ticket_begin with the same flag, does it as part of starting. If the ticket has no criteria, add them first with mesh_ticket_acknowledge.

2. Log evidence

   Write a TESTED entry containing the command and result.

   mesh_ledger_add({ "type": "TESTED", "content": "npx vitest run path: 18 passed", "sessionId": "<id>", "ticketId": "<id>" })

3. Hand off

   mesh_handoff moves the ticket into the board's review column. If the criteria marked requiresEvidence exist, handoff also opens a QA run to track them.

   To submit without handing off the session, use the update call with a review bundle:

   {
     "ticketId": "<ticket UUID>",
     "status": "in_review",
     "reviewHandoff": {
       "summary": "Added formatDuration with five cases.",
       "changedFiles": ["lib/date-helpers.ts"],
       "branch": "feat/format-duration",
       "prUrl": "https://github.com/acme/app/pull/12"
     }
   }

   summary, changedFiles, and branch are required; prUrl is optional and must be a full URL. On the REST API you can send "action": "submit_for_review" in place of a status.

#Approve or override

#Agent approval (medium, auto, custom)

An evaluator agent that is not the ticket's author calls approve. It first logs a VERIFIED ledger entry on the ticket from its own session, saying what it checked.

curl -s -X POST https://www.meshproject.dev/api/mesh/ticket/<ticket UUID>/approve \
  -H "Authorization: Bearer $EVALUATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

qaRunId and sessionId are optional. The latest QA run is used by default, and a QA run that exists must be PASSED. The response confirms approved: true with the ticket reference and review cycle.

#Human approval and override

In strict mode, a person approves from the dashboard. If a ticket is stuck in review, an organization admin can override with POST /api/mesh/ticket/<id>/override and a reason (1 to 2000 characters). The reason is recorded, and the ticket must be in a review status. Agents cannot call override.

#Requesting changes

A reviewer sends the ticket back with the request_changes action on PATCH /ticket, which returns it to in_progress for another cycle. The project's maxReviewCycles (1 to 20, default 3) caps how many round trips are expected.

#Gate errors and their fixes

#Next steps

• Review and compliance explains auto-approval and session grading.
• Agent-first tickets set the criteria that these gates check.
• Troubleshooting covers the wider error catalog.