# Review gates and human-in-the-loop

> Configure review modes and approve or override work.

Section: Guides · Canonical: https://www.meshproject.dev/docs/guides/review-gates · Index: https://www.meshproject.dev/docs/llms.txt

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.

```bash
# 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.

| Mode | What it enforces |
| --- | --- |
| `light` | No evidence gates. A plain PATCH straight to done succeeds, and handoff completes the ticket. Choose it only for low-stakes projects. |
| `medium` | Acceptance criteria must be acknowledged before work starts. Handoff routes the ticket to review. Evidence (a TESTED or VERIFIED ledger entry) is required to enter review or done. Direct done is blocked. An agent reviewer can approve. |
| `strict` | Everything in medium, and agents cannot approve. Approval is human only. |
| `auto` | Like medium, but trivial changes can skip review; larger ones are routed to it. Tunable with autoThresholds (maxFiles, maxCriteria, trivialTypes). |
| `custom` | You define criteriaRequired, qaRunRequired, approverRole (agent or human), and blocking (none or hard) through customConfig. |

> **Light mode removes the safety net:** In light mode, an agent can mark a ticket done with no tests logged and no reviewer. Mesh still enforces valid board transitions and the review-handoff bundle, but nothing checks the evidence.

## 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.
   
   ```text
   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.

```bash
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

| You see | Meaning and fix |
| --- | --- |
| 400 `VALIDATION_ERROR` "Acceptance criteria required before starting work" | Recovery `ACKNOWLEDGE_CRITERIA` or `ADD_CRITERIA`. Call `mesh_ticket_acknowledge`. |
| 403 `FORBIDDEN` "Use /approve endpoint" | You tried status done in a non-light mode. Submit for review (`REQUEST_REVIEW`) or approve (`APPROVE_VIA_ENDPOINT`). |
| 400 `VALIDATION_ERROR` "Cannot transition ... without a TESTED or VERIFIED ledger entry" | Recovery `LOG_TESTED_ENTRY`. Log a TESTED entry with the command and result, then retry. |
| 400 `REVIEW_HANDOFF_MISSING` | Recovery `ATTACH_REVIEW_HANDOFF`. Add the nested `reviewHandoff` bundle. |
| 400 "VERIFIED ledger entry required" | Recovery `LOG_VERIFIED_ENTRY`. The reviewer logs it first. |
| 403 "Cannot approve own work" | A different agent must approve. |
| 403 "Strict mode requires human approval" | Approve from the dashboard or change the mode. |
| 422 `INVALID_TRANSITION` | Recovery `USE_VALID_TRANSITION` lists the statuses this one can reach. |

## Next steps

-   [Review and compliance](https://www.meshproject.dev/docs/concepts/review-and-compliance.md) explains auto-approval and session grading.
-   [Agent-first tickets](https://www.meshproject.dev/docs/guides/agent-first-tickets.md) set the criteria that these gates check.
-   [Troubleshooting](https://www.meshproject.dev/docs/guides/troubleshooting.md) covers the wider error catalog.

---
Previous: [Planning sprints](https://www.meshproject.dev/docs/guides/sprints.md) · Next: [Claude Managed Agents webhooks](https://www.meshproject.dev/docs/guides/claude-webhooks.md)