About gates
A written rule gets broken under pressure, even by an honest agent. A gate turns that rule into a check a machine runs, so the rule holds without anyone watching.
Each gate reads facts it can verify (the diff, the pull request, the Issue, the forge) and answers pass or fail. It never judges quality and never decides how severe a finding is. Reviewers judge; the pinned review policy decides what blocks.
Vinaya ships 37 core checks:
- 17 implement generic gates. Every process must answer these questions, such as "is the evidence current?" or "is the review valid?". Vinaya answers them with its own checks.
- 20 are Vinaya-specific. They exist because of how Vinaya works: briefs, tranches, task branches, Issue grammar, writing rules.
How gates run
Gates run in three rings. Each ring catches what the one before it cannot reach.
- 1
Ring 0 · on your machine
At every commit and push, the installed hooks run the checks before anything leaves the machine. A refusal comes back in the author's own session with the exact error, so an agent fixes it where it happened.
- 2
Ring 1 · on the pull request
The same checks run again in CI, from the same code, so the hooks and CI cannot disagree. Pull-request checks and the review gate run here too, and merge is blocked while any is red. Validated Issue and pull-request writes are checked before they reach GitHub. This ring catches every writer the hooks cannot reach: the web interface, other tools, people.
- 3
Ring 2 · after merge
Audits run on every merge and once a day. They close finished work and report drift from any source, such as a push to a branch whose work is already done, or a push straight to
main.
All three rings are always on. A team cannot switch a ring off; see Configuration for the two narrow opt-outs.
The 37 checks
The checks are grouped by where they first run.
Ring 0 · commit checks
11 checks on the files you are committing
Ring 0 · push checks
14 checks across the repository at push
Ring 1 · pull request checks
7 checks on the pull request, including the review gate
Ring 1 · Issue checks
5 checks on every Issue before it is written
Gate mechanisms
Hooks, workflows and audits that gate outside the 37 checks
Run the checks yourself
The hooks and CI run the checks for you. You can also run them by hand.
Runs every check that can run locally.
vinaya check --all --localEach check either passes, or fails with one line per problem. A check can also report a wait rather than a defect, for example while a Principal test-plan item is still unticked.
Customize the checks
A team adapts the checks in vinaya.. Configuration selects and parameterizes checks; it never loads code.
Scaffold your own check, then register it under your own namespace.
vinaya new checkA check that declares validates: 'body' or validates: 'issue' joins the pull-request or Issue write path with no further wiring.
Configuration
| Key | What it sets |
|---|---|
checks | Which checks run, with what scope (diff or full), environment and timeout. Adds, replaces or silences checks. |
rings | The two opt-out flags below. |
prePush | Extra test files the push hook always runs. |
securityScan | The scanner the review loop runs before the security review. |
gateCutovers | Issue or pull-request numbers below which a newer rule does not apply. |
proseGates | Inputs for the writing checks, such as where reader-facing docs live. |
decisionRecords | Where decision records live, for the writing checks. |
The rings flags both default to true:
{
"rings": {
"ring1_forgeWriteInterception": true,
"ring2_asyncAudits": true
}
}What gets logged
Every check run writes to the Log:
| Event | When | Carries |
|---|---|---|
gate · summary | Once per run | How many checks ran, passed, failed and were skipped, and which failed |
gate · checked | Once per check that did not pass | The check, its outcome and a short reason code |
A passing check is counted, not logged one by one. The reason is a short code, never the check's message, so nothing from a pull-request body leaks into the Log. See Events for every field.