Decisions
docs/adr/
A note on the owner's English (2026-10-19). The owner asked us to correct the grammar of his own English in this repository. Where he wrote in English, his quoted words have been lightly corrected for grammar only; nothing was added to their meaning. Where he wrote in Polish, the quotes are translations, as each one says.
This folder holds two kinds of decision, and both are the owner's:
- Design decisions,
ADR-<number>-<slug>.md: how proven is built and why. One file per decision, written when the decision is taken. - Decisions on a change,
DECISION_<slug>_r<n>.md: the owner's ruling on one change, after its review.
Design decisions (ADRs)
| ADR | decision | status |
|---|---|---|
| 0001 | proven is written in Go, and every outside service sits behind an adapter | accepted, 2026-10-17 |
| 0002 | a finding counts only with evidence: a test, or a query through Zetaris with the rows it returned | accepted, 2026-10-17 |
| 0003 | the reviewer's memory and state are Meterless's H-MEM and World Model, built in Go | accepted, 2026-10-17 |
| 0004 | the first evidence sources: OSV, CISA KEV, FIRST EPSS, the repository's own history | accepted, 2026-10-17 |
| 0005 | a guardrail on every prompt and answer by default, local or hosted, with a switch to turn it off | accepted, 2026-10-18 |
| 0006 | every finding faces a Skeptic from another model family, NVIDIA Nemotron; the evidence settles it, never a vote | accepted, 2026-10-18; extended by ADR-0019 (Amendment 1, 2026-10-22: reached through Nightshift) |
| 0007 | no exploit code; a vulnerability finding is proved by a query and its rows | accepted, 2026-10-18 |
| 0008 | the reviewer's model is chosen against the author's model stated in the change; NVIDIA by default; some reviews doubled | accepted, 2026-10-19 |
| 0009 | two reviewer models; a doubled review may use the author's own model as a fresh second reviewer; A writes, NVIDIA reviews, B for special cases is best | accepted, 2026-10-19 |
| 0010 | every reviewer model is configurable, NVIDIA's included; NVIDIA is only the default; no setup is blocked | accepted, 2026-10-19 |
| 0011 | a change names its model in an Assisted-by: trailer by default; sources, keys and the family table are configurable | accepted, 2026-10-19 |
| 0012 | Saphan Studio's review classes: security, backend, user interface, mobile, docs; security doubled by default | accepted, 2026-10-19 |
| 0013 | no setting is hardcoded; every value has a documented default; rules are not settings | accepted, 2026-10-19 |
| 0014 | a change's review class is chosen by configured path rules, not a model; the highest-risk class wins | accepted, 2026-10-19 |
| 0015 | the Zetaris adapter speaks REST, not JDBC; proven carries no Java | accepted, 2026-10-20 |
| 0016 | a drop-in replacement for Semgrep and Opengrep in a pipeline: their flags, exit codes and text, JSON and SARIF outputs | accepted, 2026-10-20 |
| 0017 | a Docker Compose lab with Gitea and Gitea Actions, configured, for the judges; Jenkins only if time is left | accepted, 2026-10-20 |
| 0018 | H-MEM and World Model at their minimum, one injected generator, JSONL in logs/; Markovian only if time is left | accepted, 2026-10-21 |
| 0019 | Meterless Nightshift is the primary AI provider; NVIDIA's models through it by default; other routes stay settings | accepted, 2026-10-21 |
| 0020 | the exact command line, GitHub Action inputs and outputs, and exit codes, taken from Semgrep and the Opengrep action; self-hosted runners first; one summary comment per pull request | accepted, 2026-10-21 |
| 0021 | a demo with a self-hosted GitHub runner in Docker; one script connects it to a judge's repository from its name and a token | accepted, 2026-10-21 |
| 0022 | Gitea on the team's own premises is a scenario equal to GitHub; the judges' lab is that scenario, packaged | accepted, 2026-10-21 |
| 0023 | evidence sources are Zetaris REST tables an administrator registers and Proven's own key reads live; OSV by package needs another path | accepted, 2026-10-21 |
| 0024 | every coding session of a Cursor agent on Proven is recorded, and the recording is published here, blacked out | accepted, 2026-10-21 |
| 0025 | the Prover runs the change's code in a container with no network and no secret; with no container runtime it runs no code | accepted, 2026-10-21 |
| 0026 | one Makefile: help by default; builds natively, through a Go image, or prints how to install Go; minimal images scanned by Docker Scout before a push; builds and pushes saphan/proven:latest; starts, checks, logs and stops the Gitea lab (Docker in Docker); make e2e is the judge's rehearsal | accepted, 2026-10-23 |
| 0027 | the code is written to be read by the judges: package and doc comments, why-comments, the ADR a step carries out, what each test proves; the masters comment the code already written themselves | accepted, 2026-10-23 |
| 0028 | the code is security-reviewed as a whole in nine pieces, each a trust boundary; two reviews per piece; a weakness becomes a fix with a failing test and is published only after it is merged; SECURITY.md and SECURITY_REVIEW.md at the root | accepted, 2026-10-23 |
| 0029 | a security piece is reviewed at one commit of main, and only once its code is on main; Docker Scout runs in the lab piece | proposed, 2026-10-23 |
| 0030 | the product and the hackathon live apart: the build's record moves to hackathon/, the design decisions to docs/adr/; moved before the day-2 push with a permanent link check | accepted, 2026-10-23 |
| 0031 | the generator can also call NVIDIA's hosted API (Nightshift stays the default); proven scan runs live; the lab turns live on from one NVIDIA key | accepted, 2026-10-23 |
| 0032 | a model picks a query template and its values; Proven validates each value and builds the SQL; a read-only Zetaris key only if measured | accepted, 2026-10-23 |
| 0033 | the text review is written for a person: a summary, one separated block per problem, "how we know" in plain words; the machine detail moves to --verbose, JSON and SARIF; Markdown and HTML for people | accepted, 2026-10-23 |
| 0034 | Proven runs air-gapped: one setting keeps every call on the organisation's network, and a test proves it | accepted, 2026-10-23 |
| 0035 | every review can leave a signed evidence pack; proven verify checks it for an auditor | accepted, 2026-10-23 |
| 0036 | one organisation policy for every repository; a risk is accepted only with an owner and an expiry | accepted, 2026-10-23 |
| 0037 | bring your own second reviewer: any OpenAI-compatible model; with it connected every change is reviewed by two, and their disagreement is shown | accepted, 2026-10-23 |
| 0038 | a language is one small adapter behind a public interface; PHP, Java, C#, Rust and Ruby join Go, JavaScript and Python | accepted, 2026-10-23 |
| 0039 | more evidence sources through Zetaris: malicious packages, project health, CVSS, licences | accepted, 2026-10-23 |
| 0040 | a deterministic tool's run is evidence, through a tool adapter: race detector, fuzzing, static analysis, coverage | accepted, 2026-10-23 |
| 0041 | what two models agree on without proof is shown apart, labelled as an opinion, never as proven | accepted, 2026-10-23 |
| 0042 | a proposed fix is proved by the same test that proved the problem; a person applies it | accepted, 2026-10-23 |
| 0043 | a vulnerable dependency is checked for reachability (govulncheck for Go): reached, imported but not reached, or not measured | accepted, 2026-10-23 |
| 0044 | every finding names its level of proof first: by a test, by a tool, by data, or agreed by two models | accepted, 2026-10-23 |
| 0045 | a review is observable through OpenTelemetry (standard OTEL_*, off unless set), plugs into any monitoring; the lab shows it live on a provisioned Grafana dashboard | accepted, 2026-10-23 |
| 0046 | a data source is one adapter: it loads into Zetaris, offers query templates and a rule that turns a row into a finding; an organisation adds its own sources the same way | accepted, 2026-10-24 |
| 0047 | the evidence store is an adapter: Zetaris or a local one-file store, chosen by one setting; the same templates return the same rows on both | accepted, 2026-10-24 |
| 0048 | a large change is reviewed in bounded steps with Meterless's Markovian engine; kept only if it holds the findings and cuts the cost | accepted, 2026-10-24 |
| 0049 | Meterless's Scout Intent plans each review before a model runs; never lowers a configured rule; kept only if measured worth it | accepted, 2026-10-24 |
| 0050 | after a review, one automated fix attempt for all proved findings, judged only by the same deterministic evidence; then fixed or rejected; Proven never commits to the author's branch | accepted, 2026-10-25 |
| 0051 | a judge's lab reaches our Nightshift and our Zetaris through one gateway behind a Cloudflare tunnel and Access, with the judge's own expiring token; evidence by query template only; every call limited and logged | accepted, 2026-10-26 |
| 0053 | all four Meterless engines are on by default and each is switched off by its setting; the benefit of Markovian and Scout Intent stays unmeasured; Scout never lightens a change that is not verified prose | accepted, 2026-10-26 |
Rules for an ADR
- The decision is the owner's, and the ADR quotes his words. An agent may write it down; it cannot decide it.
- One decision per file, numbered in order. A number is never reused.
- An ADR is not rewritten when the decision changes. A new ADR supersedes it, and the old one's status says
superseded by ADR-<number>. - What is not known yet is said so, under Consequences.
Template
Decisions on a change
A decision is the owner's. No agent can merge, and no agent's "yes" counts: a reviewer's accept is advice the owner reads, not a decision.
Rules every decision follows
- One of four outcomes:
accept,accept-with-conditions,rejectorclose-without-shipping. - The reason is written by the person who decides. The owner writes it himself, in his own words. A decision without a reason is not published.
- Conditions are named. If the owner accepts with conditions, each one says what closes it and in which later change.
- Every decision states how the change went, over all its rounds: who built it on which model, how many repair rounds it took, and how many BLOCKING and OWED conditions the reviews found. From 25 October it states no cost. The same line goes into
../LEDGER.md. - A rejected change keeps its documents. The order, the status report and the review of every round stay in this repository, including the ones that were sent back.
Template