The file and its keys

An example

A config that spells out several documented defaults:

{
  "dispatch": {
    "agent": "claude",
    "timeoutMs": 14400000,
    "reviewerTimeoutMs": 1200000,
    "killGraceMs": 5000
  },
  "reviewPolicy": {
    "codeReviewThreshold": "BLOCKER",
    "securityThreshold": "HIGH",
    "maxRounds": 3,
    "maxTaskMinutes": 180
  },
  "planning": { "collisionThreshold": 3 },
  "rings": {
    "ring1_forgeWriteInterception": true,
    "ring2_asyncAudits": true
  },
  "checks": {},
  "report": { "commandTimeoutMs": 900000 }
}

vinaya init seeds a starter: rings (both true), an empty checks, a starter briefSchema, then managed. See Setup commands.

All keys at a glance

General rules

• An unknown top-level key is dropped. logPublish is the one removed key kept, as a loud refusal.
• decisionRecords.path may not sit inside proseGates.doctrineRoot.
• In reviewPolicy, an unknown or invalid value refuses; it never falls back to a default. Three of its values are typed loosely on purpose, so a typo refuses that one setting instead of voiding the whole config.

Harness keys

logs

Where events are delivered, live, one at a time. Set exactly one of folder or url.

When absent, events go to a folder under the per-repository runtime directory. A CI job never falls back to a folder. For unattended runs, the destination must match the default branch; see Trust.

runtimeDir

The one directory that holds every file a run writes: the driver lock, control records and agent output. It is not the telemetry outbox.

• Must be an absolute path. A value inside the repository falls back to the default.
• Ignored in the global file.
• For unattended runs, honoured only when the default branch declares the same value.

dispatch

principals

An array of GitHub logins, at least one. These logins are trusted to author review verdicts and to apply the waiver labels vinaya/waiver:docs and vinaya/waiver:review. Read from the default branch. Ignored in the global file.

releaseActor

The GitHub login expected to author the Changesets release pull request (changeset-release/main). It decides the release exemption on the body-bare-digits check. Read from the default branch. Ignored in the global file.

managed

The ownership manifest. init writes it and eject reads it. You do not edit it by hand.

ci

{ setup }: a shell command added, word for word, as a step in the generated workflows that run vinaya check. Read when workflows are generated (init, upgrade, doctor), and only from the file at the repository root.

tokens

{ collect }: exactly "<interpreter> <repo-relative-script-path>", for a host other than Claude Code. The script prints { inputTokens, outputTokens, cacheCreationInputTokens, cacheReadInputTokens, model }.

vinaya tokens refuses to run the script until you approve it with vinaya tokens --trust-collect. Approval is per declaration, repository and machine, and pins the script's blob hash. Ignored in the global file.

Vinaya keys

roles

A map of role key → { contract }, where contract is a path containing /, resolved relative to the config file. An entry overrides a core role or adds a new one, and the contract is validated. Ignored in the global file.

briefSchema

The sections a body must carry.

• pr, issue, milestone: each { sections: [...] }. A section is one of { builtin }, { heading, name? }, { field, name? } or { phrase, name? }. Absent for a kind means no sections are required.
• ack: builtins you dropped on purpose. This only silences doctor's divergence report.
• init seeds a starter; upgrade never rewrites it.

reviewPolicy

An unknown or invalid value refuses; it never falls back. Read from the default branch.

planning

{ collisionThreshold }: how many files two open tasks may share before the new one must declare Conflicts-with. Default 3. 0 turns the refusal off and leaves a warning only.

projects

An array of { name, description?, path? }. Display metadata only; no gate reads it. vinaya init product <name> appends one, alongside a row in .vinaya/projects.md.

blastRadius

{ extraDomains: [paths] }: collision domains beyond the ones derived from package.json workspaces and the built-in set (lockfile, monorepo config, CI, git hooks).

checks

A map of check name → entry. An entry has the same shape as a core check, with no privileged field. There are no conditionals (if or unless). Ignored in the global file. init seeds {}.

See Gates for adding, replacing and silencing checks.

rings

{ ring1_forgeWriteInterception, ring2_asyncAudits }. Both are booleans, and both are required when the block is present.

• true or absent runs the slice.
• false opts out of brief-schema validation on the write path (ring 1) or dead-branch-push bookkeeping (ring 2).
• It never disables a ring or the detection of a direct push to main.

prePush

{ alwaysRun: [globs] }: test files that run on every push, whether or not the import graph reaches them. Additive only.

securityScan

{ command: [argv] }: a scanner run once per round before the security pass. It runs only when the pull request touches .claude/**, .mcp.json or .agents/**, on the head-verified candidate copy, with no forge credential.

When absent, the security pass is told no scanner is configured; it never pauses. Read from the default branch.

gateCutovers

Non-negative integers: objectivesSinceIssue, briefSectionsSinceIssue, documentationSinceIssue, briefRulesSincePr, agentBoxesRefusedSincePr. Below the number, that gate passes unconditionally. Read from the working tree, not the default branch.

proseGates

Inputs of the reader-resolvable-prose and retired-vocabulary checks, read when the check runs.

decisionRecords

{ path }: a repository-relative folder, outside the repository root and the doctrine tree. Setting it:

• turns on vinaya new adr,
• adds the folder to the spec scope,
• enables the decision-record-citation rule.

When absent, none of that happens.

report

{ commandTimeoutMs }: the time budget per [agent] Test Plan command in vinaya pr report. Default 900 000 (15 min); maximum 3 600 000.

Removed

logPublish

Removed: telemetry is never posted to a tracker or code host. If present, validation fails and names logs as the replacement.

What's next