Configuration

Every setting the reviewer reads, its default, and what it changes (ADR-0013: nothing is hardcoded; secrets come from the environment only). The names and defaults below were read from the code on main on 22 October 2026 (internal/generator/settings.go, internal/guardrail/settings.go, internal/query/settings.go, internal/review/config.go, cmd/livecheck). A wrong value stops Proven before any work, and the refusal names the setting, the value and what is allowed. An empty secret does not: that service is down and the review names it, and an empty guardrail key refuses every model call unless PROVEN_GUARDRAIL_MODE is off.

The shell's own flags (proven scan …) are documented by the shell's track. Sample mode (--sample) reads none of the settings below except proven.yaml's timeout and the switches of the four Meterless engines (PROVEN_MARKOVIAN and its three tuning variables, PROVEN_HMEM, PROVEN_WORLD_MODEL; ADR-0053): see SAMPLE_MODE.md.

The network mode: air-gapped

In local mode every address in the tables below is checked when it loads, the guardrail's nvidia mode is refused, and the Prover's image is never pulled (ADR-0034). docs/AIR_GAPPED.md says what to run and how to check the mode holds.

The model generator: Meterless Nightshift or NVIDIA's hosted API

Which keys each mode needs (ADR-0031). nightshift (the default, ADR-0019): METERLESS_RUNTIME_TOKEN, issued by the operator of the Nightshift you run; nothing else is required. nvidia: PROVEN_GENERATOR_MODE=nvidia and PROVEN_GENERATOR_KEY, a free NVIDIA API key created at https://build.nvidia.com (sign in, open any model, choose Get API Key); the hosted API's address (PROVEN_NVIDIA_BASE_URL, https:// only) and the models have defaults, so the key is the only value needed. Each mode reads its own address: nightshift reads PROVEN_GENERATOR_BASE_URL, nvidia reads PROVEN_NVIDIA_BASE_URL and ignores the other, so the key is never sent to a Nightshift address. The guardrail has its own key in either mode (below). In nvidia mode the hosted API gives no signed receipt, so the trace says no receipt and the nvidia/* requirement is checked against the model field of its answer. A free key is rate limited; a review that meets the limit names it as a failed service. Sample mode reads none of these.

The second reviewer: any OpenAI-compatible model

The guardrail: NVIDIA Nemotron content safety

Every prompt and every answer is checked; an unsafe verdict, or a guardrail that does not answer, stops that step by name. An empty key is not off: every model call is refused and the review names the guardrail.

Evidence: the store, and Zetaris over REST

The store is zetaris unless PROVEN_EVIDENCE_STORE says local or couchdb. The local store is one file and opens no network (ADR-0034, ADR-0047), and a review that chooses it does not read the Zetaris variables. The couchdb store reads the PROVEN_COUCHDB variables and not the Zetaris ones. A live review passes the template request, and each store runs the form of its own language: sql on Zetaris and the local store, mango on CouchDB (ADR-0047, docs/ADAPTERS.md). Sample mode uses the local store on the fixture file and reads none of these, except that it reads PROVEN_COUCHDB_RECORDS and PROVEN_EVIDENCE_LINK_BASE_URL, and, when PROVEN_COUCHDB_RECORDS is set, also the other PROVEN_COUCHDB_* variables (URL, USER, PASSWORD, PREFIX, ROW_LIMIT, TIMEOUT, RECORDS_USER, RECORDS_PASSWORD) and GITHUB_REF, and the engine switches of ADR-0053 (PROVEN_MARKOVIAN, PROVEN_MARKOVIAN_THRESHOLD, PROVEN_MARKOVIAN_STEP_UNIT, PROVEN_MARKOVIAN_CARRY_TOKENS, PROVEN_HMEM, PROVEN_WORLD_MODEL), and nothing else besides OTEL_*, so the lab's review can write its records (docs/ADAPTERS.md).

The Prover's container

Each test runs with no network and no secret (ADR-0025). With no container runtime the Prover is off, and the review says so. Sample mode reads none of these.

Deterministic tools

Each tool runs in the Prover's container with no network and no secret (ADR-0025, ADR-0040). A tool that cannot run is named. Sample mode reads none of these.

Bounded steps: Meterless's Markovian engine

ADR-0053 (superseding the "off until measured" clause of ADR-0048): on by default, switched off with PROVEN_MARKOVIAN=off. Its benefit is UNMEASURED until the corpus recordings exist. Every review's trace says whether bounded steps ran, how many, and the carried state's size at each step. A wrong value stops the review before it starts. Sample mode reads these four, so the lab's pull-request review runs bounded steps on by default and switches them off the same way.

The two stores: Meterless's H-MEM and World Model

ADR-0053: both stores are on by default, each switched off by its own variable. A store switched off is not opened, read or written on any path: no directory is made for it, the Judge suppresses nothing from H-MEM, and with the World Model off there is no fold, so H-MEM learns nothing from the trace either. With only H-MEM off, the World Model still folds and records no refutation. Their benefit is UNMEASURED. A wrong value stops the review before it starts. Sample mode reads both, as it reads the Markovian switches.

One adapter call

Telemetry: OpenTelemetry (ADR-0045)

Telemetry is off unless an endpoint is set. It only observes: once a review has started it never changes what the review decides, and a collector that cannot be reached never fails a review (the export is bounded at 5 seconds, and the failure goes to stderr). The one refusal is at the start: a malformed OTEL_* setting stops Open by name, like any other setting. No secret is put in an attribute, an event or a span status: the same redactor that cleans the trace file cleans the span events and the text of every failed review and failed agent, so a status carries the redactor's marker where a configured secret stood. The headers, timeout and certificates of the exporter are the SDK's own variables (OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_CERTIFICATE), read from the process environment. Sample mode reads the OTEL_* variables and no other.

Reads of the repository under review

A read over its bound is refused by name before the review goes on; the refusal names the file and the bound, never its content. Sample mode reads none of these.

The organisation policy

A repository's proven.yaml may make a policy setting stricter, never weaker, and an exception without an owner or an expiry is refused on load (ADR-0036).

The evidence pack

The pack holds source excerpts and query rows, so keep it where the review itself may be read. The private key is never written into it (ADR-0035). See docs/EVIDENCE_PACK.md.

H-MEM: the memory store

H-MEM reads its whole state file at open and scans every record on each query, so it is built for a small store; see the scale section of docs/ARCHITECTURE.md. A state file over the cap is refused by name with its size and the cap. Sample mode reads none of these.

The trace

The default is the user cache directory, with proven/logs under it, created so only that user can read it. An existing configured directory is narrowed to 0700. A path that resolves inside the repository under review is refused when Proven loads, and the refusal names PROVEN_LOG_DIR and the target. The link count of each file written in that directory is read on every OS. Sample mode reads this setting.

Counting guardrail checks

The guardrail's settings are in the generated table above; this section is what its checks leave on the trace.

Each check is one kind: "guardrail" line in logs/trace.jsonl. Its guardrail object carries:

The line's text is unchanged: a check that could not be made still reads guardrail: <reason>, and an error outside the set keeps its text there only. The key is never written to the trace. A review with the guardrail off writes one no guardrail line and no checks.

guardcount reads one or more traces and counts the checks per UTC day, side, verdict and backend, with the median latency. A down check's verdict is down:<reason>. An older down line with no guardrail object counts as down:unstructured, and a field an older line lacks prints as -.

go run ./cmd/guardcount logs/trace.jsonl [more traces...]

Its output on the sample traces in cmd/guardcount/testdata (the golden file counts.golden, which the test compares byte for byte):

day         side    verdict            backend          count  median_ms
2026-10-24  answer  down:http-503      nvidia           1      220
2026-10-24  answer  safe               server           1      80
2026-10-24  answer  unsafe             server           1      95
2026-10-24  prompt  down:timeout       server           1      5000
2026-10-24  prompt  safe               nvidia           2      355
2026-10-24  prompt  safe               server           3      100
2026-10-25  -       down:unstructured  -                1      0
2026-10-25  answer  safe               sample           1      0
2026-10-25  prompt  down:no-key        absent           1      0
2026-10-25  prompt  safe               sample           1      0
2026-10-25  prompt  unsafe             sample-recorded  1      0

The sample traces are written for the test, not taken from a live review. A trace of a review with the guardrail off prints the header line only, and exits 0.

proven.yaml

proven.yaml is one flat mapping of scalar values. A missing file is the defaults below. An unknown key, a nested value, or a bad value is refused on load and proven exits 7. The refusal names the field and the allowed values. A key that is set replaces that setting. It does not merge with the default list.

Where the file is read:

• An explicit config path is that file. A missing path is refused.
• Otherwise, when the review names a baseline commit, the file is the baseline commit's proven.yaml. The change's copy is not read. If the change edits proven.yaml, the review prints the change edits proven.yaml.
• Otherwise there is no baseline (a sample fixture, or a review of the whole tree). The file in the target is used.

No environment variable sets these keys.

The Planner, the Prover, the Judge, the Writer and the Fixer have no query path, so they have no scope key. A template name is the only thing a scope names: it does not narrow the tables or views a template reads.

For example, an Investigator that may ask every KEV, EPSS and OSV template and a Skeptic that may ask only KEV:

investigator_templates: kev-by-cve, epss-by-cve, osv-by-package, osv-by-advisory
skeptic_templates: kev-by-cve

Default path rules

Each of these is class security:

**/auth/**, **/payment*/**, **/*secret*, **/migrations/**, go.mod, go.sum, package.json, package-lock.json, pnpm-lock.yaml, yarn.lock, Cargo.toml, Cargo.lock, requirements.txt, Pipfile.lock, poetry.lock, Gemfile.lock, composer.json, composer.lock, pom.xml, build.gradle, build.gradle.kts, libs.versions.toml, gradle.lockfile.

Each of these is class docs:

**/*.md, docs/**.

Anything else is the fallback class.

Check the live settings

go run ./cmd/livecheck

With nothing set, it reports every service not ready with the reason and exits 1. Its output never contains a secret.

The judges' lab

make reads these from lab/versions.env. A variable already set in the environment wins. Secrets are not in that file: copy lab/.env.example to lab/.env for make livecheck. lab/.env is not committed.

make livecheck reads these keys from lab/.env when the file exists, and ignores an empty value: METERLESS_RUNTIME_TOKEN, PROVEN_GUARDRAIL_KEY, ZETARIS_API_KEY, ZETARIS_REST_URL, ZETARIS_ORG_ID.