Decisions are recorded, not remembered.

The ADR process

Architecture Decision Records are the project's institutional memory. When a choice is public-facing or hard to reverse, it does not live in a chat log or a maintainer's head — it becomes a file in the repository.

The path is deliberately ordinary: an issue raises the question, discussion works it out, a pull request adds adrs/NNNN-slug.md capturing the decision and its reasoning, and CODEOWNERS review approves it before it merges. The decision log records every such choice — from the plugin transformation (packaging, the Codex second runtime, score subject identity, and the authoring tier) through the epistemic core, the live-connector lanes, and the drift watcher — the receipts of every hard-to-reverse choice made so far.

Who guards the seams

Not every file carries the same weight. A few seams decide what EvalGlass is allowed to claim, and a change there can quietly turn an honest signal into false confidence. Those seams require maintainer review, enforced in code through CODEOWNERS:

• The Evaluation Core. The effect-free center where score meaning, contracts, and aggregation live.
• The Verdict Engine. The only place a run becomes pass, fail, blocked, or informational.
• The core-isolation gate. The check that keeps effects, SDKs, and optional lanes out of required paths.
• CI workflows and pyproject. The build, the gates, and the dependency surface that everything else trusts.

The ownership rules are verifiable, not asserted — read them in .github/CODEOWNERS →

What forces an ADR

A decision is recorded when undoing it later would be costly or would change what users can rely on. In practice, an ADR is required when a change involves:

• A new dependency. Anything added to the trusted surface the project ships.
• A public API, CLI, or report-schema change. The contracts other people build against.
• Verdict or authority mapping. Anything that touches how evidence becomes a claim.
• A port/adapter or host-layout change. The seams where EvalGlass meets your repository and your effects.

How the plugin governs what it scaffolds

The same discipline runs one level down. EvalGlass is delivered as a Claude Code plugin (with Codex as a second runtime), and its authoring tier — add-metric, add-judge, calibrate — helps you build your own measurement. The pressure to make a number pass is exactly where false confidence creeps in, so the plugin is governed so it cannot (ADRs 0025, 0038):

• Everything it scaffolds lands provisional. A new metric is proposed/informational; a new judge is uncalibrated. Neither can gate until you validate it. The plugin populates host-owned files; it never fills in authority.
• There is no gate, approve, or certify verb. Activating a gate is a host YAML edit you own (metric_status: gating, threshold_approval: approved), guided by the promoting-a-gate skill — the agent can type it at your direction; it can never grant the authority. The absence of the verb is the identity.
• Synthetic data stays proposed. No generator ships. If one is ever added, its import path forces proposed regardless of what the data claims — generated data can never enter as validated reference data.
• The live-tracing lane is deletable. connect --live is opt-in and isolated, ships no provider SDK, and no required path imports it — removing it changes no verdict.
• Host evaluators import only the core. A scorer you write imports the vendored _evalglass.core contracts — never the framework or the plugin — and represents a non-scored state as a diagnostic, never as 0.0.

Read the decisions in the ADR index →