Concept
How Zof decides
Updated
On this page
Zof gives every pull request one of four results. It checks the same things every time, lists every reason it finds, and the strictest reason wins. Missing information never counts as a pass.
What does Zof look at?
Zof decides about the pull request's latest commit. It reads five things:
| What Zof reads | Where it comes from |
|---|---|
| What changed, which services it touches, and their tier and owners | The System Graph |
| What your rules require for this change | Your company's live release policy |
| Test and review evidence for this exact commit | Verification |
| Approvals | Pull request reviews on GitHub, checked against Release approvers |
| Who wrote the change: a person or an agent | GitHub |
Zof decides again whenever one of these changes: a push, a review, new verification results, a new policy version, or a change to release approvers. You can also ask Zof to decide again.
Which result wins?
Zof doesn't stop at the first problem. It lists every reason, and the result is the strictest one:
| Result in Verification | Title on the check | When |
|---|---|---|
| Denied | "RELEASE DENIED" | At least one reason denies the change, for example a required check failed or an approver requested changes. |
| Needs evidence | "RELEASE BLOCKED: evidence missing" | Nothing denies it, but evidence is missing, not enough or out of date, or Zof couldn't read an input. |
| Awaiting approval | "AWAITING APPROVAL" | The evidence is in, but a required approval is missing. |
| Release authorized | "RELEASE AUTHORIZED" | No reason blocks the change. |
A rule marked Optional is reported on the check, but it never changes the result. Each reason is listed in Reason codes, and each result in Check results and statuses.
What if something is missing?
Zof fails closed. When it can't get or read something it needs, that becomes a reason of its own, and the change is blocked, usually as Needs evidence. For example:
- No policy has been published:
policy_not_published. The check asks for action with “No release policy yet” and links to Release policies. - The System Graph hasn't answered:
context_unavailable. - Verification didn't answer in time:
verification_unavailable. Zof retries on its own. - A verification capability timed out or failed to run:
capability_unavailable. - Zof couldn't evaluate the policy:
policy_unavailable. - Verification reported a status Zof doesn't recognise:
unrecognized_verification_status.
While Zof waits for verification, the check says "Evaluating: waiting for verification" and shows the time it fails if nothing arrives. An unknown tier counts as tier 0, the strictest.
What if no rule matches?
Every live policy has a baseline rule. It applies to every change and asks for at least one required check, and Zof refuses a policy without one. So there is no "nothing applies, so allow".
If the policy's answer for a change has no required check at all, Zof treats the answer as broken. The result is Needs evidence, with policy_result_invalid.
Which policy applies?
A new company has no policy until an admin publishes one. Your company then has one live policy at a time. Edits stay in a draft until an admin publishes them, and a new version is tested on recent pull requests first. Open pull requests are checked again once the new version is live.
Evidence must be checked against the live policy version. Evidence checked against another version doesn't count: evidence_criteria_mismatch.
Can AI change a result?
No. The result is worked out by fixed code from your policy, the evidence and the approvals. The same inputs always give the same result.
If your policy requires a code review as evidence, a failed review can only hold the change as Needs evidence. It never denies it. A Zof code review posted to a pull request adds a Zof / Review check, which is always neutral and never blocks a merge.
What this means for you
- To find the reason for a blocked pull request, see Find out why a pull request is blocked.
- To change what Zof requires, see Change your release policy.
- To change a service's tier or owner, see Change zof.yaml safely.
- To give the approval a change is waiting for, see Approve a change.