Review gates

A review gate is a check on a run's plan or its final change. Each gate ends with a result such as passed or failed. A run that changed files cannot finish until every required gate is green for its current plan and change.

Gates only read. They never commit, push, merge or open a pull request. Syndai does those steps after the gates are green.

The gates

gate	looks at	what it checks
planning_review	the plan the agent writes before it builds	that the agent sent in a plan for this work
security_review	the final change	secrets in code, routes that skip sign-in checks, injection, open debug or admin routes, and server requests to a URL a user controls
preflight	the final change, its check results and the security review	that the checks ran and none that block are red, that security_review is green for this same change, and a scan of the diff for secrets, unsafe database rules and risky files
adversarial_review	the final change	a second, tougher review pass; runs only if you ask for it

planning_review, security_review and preflight are always required. You cannot turn them off.

Syndai also runs its own reviews on the final change, like code_review and simplify. You may see them in a run's gate list. You cannot add or remove them in policy.

Add a gate

You can require more gates on top of the three. Today the one you can add is adversarial_review.

Set it in policy_config on a run:

{
  "policy_config": {
    "reviews": { "required_gates": ["adversarial_review"] }
  }
}

You can also set it in your saved policy defaults or in your repo's syndai.yaml. See Policy and syndai.yaml.

The three required gates are always added back, so you never need to list them. A gate name Syndai does not know is refused with 400. So is a name of a step that changes the repo, like merge or push.

When a gate holds a run

Gates are checked once, when the run is ready to finish. A gate that is not green holds the run there. Syndai tells the agent which gate holds it and why. The agent fixes what the review found, or sends in its plan for planning_review. The run goes on once every required gate is green.

A gate holds the run if it is:

• not run yet;
• failed or blocked;
• still pending or running;
• green, but for an older plan or change.

Bound to what it saw

planning_review is tied to the exact plan it looked at. If the agent changes the plan, it sends the new plan in again.

Every other gate is tied to the exact change it looked at. It keeps the commit (reviewed_head_sha) and a hash of the diff (reviewed_diff_sha256). If the change moves, the old result no longer counts. A new commit or a rebase onto a newer base both move it. The gate must run again on the new change.

Read gate results

GET /runs/{id} returns a review_gates list. There is one row for each gate that has a result.

field	what it is
id	the gate row's ID
gate_name	the gate, like security_review
status	pending, running, passed, failed, waived, blocked or cancelled
iteration	which pass of the run this result is from
blocking	whether a failure here holds the run
findings	what the review found
artifact_refs	links to files the review made
reviewed_head_sha	the commit it reviewed
reviewed_diff_sha256	the hash of the diff it reviewed
created_at, updated_at	when the row was made and last changed

Secrets in the message and file of each finding are masked before they are stored.

Gate webhooks

When a gate records passed, failed or waived, Syndai sends coding.review_gate.completed. The event's payload.payload looks like this:

{
  "gate_name": "security_review",
  "status": "passed",
  "iteration": 0,
  "head_sha": "4f2bbe04ba1c0d3e5f6a7b8c9d0e1f2a3b4c5d6e",
  "diff_fingerprint": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
  "blocking": true
}

head_sha and diff_fingerprint match reviewed_head_sha and reviewed_diff_sha256 on the gate row. See Webhooks for the full delivery body and how to check its signature.