Glossary
Finding
A single failure surfaced by a gate. Has a stable fingerprint (sha1 over gate id + reason + target + source.file + source.jsonPath) so the same finding across runs collapses for diff mode. Every Finding carries a reason (machine-readable, e.g. route_not_found), a message (human-readable, one line), a target (the value being audited), and a source (file + optional jsonPath / line).
Fingerprint
A 16-character sha1 hash that uniquely identifies a Finding across runs. Powers diff mode (--since=<ref>) and allowlist matching. Two semantically-equivalent findings produce the same fingerprint; the gate's fingerprint() helper computes it.
Gate
A *.gate.ts file whose default export conforms to the Gate interface. Auto-discovered by the runner. Carries id, version, category, layer, mode, severity, description, optional dependsOn + slaMs + serial, and a run(ctx) => Promise<Finding[]> function.
Mode
Which layer of the pyramid the gate lives on. 19 values total: static, drift, unit, property, fuzz, mutation, integration, contract, visual, e2e, smoke, synthetic, eval, safety, red-team, prompt-regression, hallucination, llm-judge, determinism. See /testing/pyramid.
Layer
Which industry philosophy the gate serves. Three values: Stripe (contract sync), Vercel (measurable budgets), Anthropic (AI behavior).
Category
The runner's filter knob, broadly mapped to layer + a security cut-out. Eight values: contract, budget, eval, security, capability, safety, cost, latency.
Severity
How the runner treats a finding for exit-code purposes.
blocking— non-zero exit code on any unsuppressed findingwarning— exit code 0, but reported prominentlyinfo— exit code 0, reported quietlyshadow— exit code 0, reported only in telemetry. Used for new gates pre-promotion.
Allowlist
A JSON file (<gate-id>.allowlist.json) of suppression entries that the runner matches against findings before deciding exit code. Every entry MUST include a tracking_issue and expires_at (ISO date). Past-expiry entries become hard failures so allowlists shrink monotonically. Entries can match by full fingerprint or by key.
Quarantine
A JSON file (<gate-id>.quarantine.json) for temporal suppression — "this gate (or this finding) is flaky right now, mute it until we stabilise it." Per-entry expires_at enforced. Whole-gate quarantine: omit fingerprint. Specific-finding quarantine: include fingerprint.
Budget
A JSON file mapping metric names to numeric ceilings. The Budget primitive's check(gate, metric, value, source) emits a budget_exceeded Finding when the observed value exceeds the ceiling. Used for perf, a11y, bundle-size, cost, latency.
Eval
An AI-layer gate (mode: "eval") that runs captured cases through a subject (the AI emission under test) and grades each output with a grader. Cases live in a JSON file: { cases: [{ id, input, must_include?, must_not_include? }] }.
LLM-as-judge
A grading strategy where Claude evaluates a soft output against a rubric — voice, style, tone, alignment. The llm-judge primitive returns { verdict: "pass" | "fail", rationale, model }. Used when deterministic substring checks don't apply.
Red-team
An adversarial-input gate (mode: "red-team") that runs a signed corpus of prompt injection / jailbreak / data-extraction attempts against the subject. The corpus is versioned and hashed (red-team-corpus.digest) so a compromised corpus can't silently weaken the gate.
Hallucination check
A gate (mode: "hallucination") that grounds AI claims against an oracle — for Matter, @repo/jurisdictions, the OpenAPI spec, the MCP catalog. Each claim has a kind that routes to the right oracle.
Determinism
A gate (mode: "determinism") that repeats the subject N times with temperature 0 and asserts all outputs are equal (or comparator-equivalent). Used for structured-output flows that must be reproducible.
Cost meter
A primitive that records token usage per model call, multiplies by a price table, and emits a cost_budget_exceeded Finding when the total exceeds the budget. Used in category: "cost" gates.
Latency budget
A primitive that asserts per-call p50 and p95 latency ceilings over a sample. Distinct from the gate-level slaMs (which budgets the gate's own runtime); this measures per-call latency that downstream SLAs care about.
Telemetry span
The OpenTelemetry-shaped record the runner emits per gate run. Span name: gate.run. Attributes: gate.id, gate.version, gate.mode, findings.count, duration.ms, sla.exceeded, quarantine.applied. Sinks: OTLP if MATTER_OTEL_ENDPOINT set; otherwise .matter/telemetry/<run-id>.json.
Diff mode
bun run gates --since=<ref> returns only findings new vs. a git base ref. PR comments use this so they surface only what this PR introduced; pre-existing findings get a collapsed "already broken" section with an auto-suggested allowlist entry.
Shadow severity
A gate with severity: "shadow" runs in CI but never fails the build. Used for new gates pre-promotion. After N green runs (default 14 days or 30 runs), promote via bun run gates --promote=<id> which edits the gate file's severity.
Four audits
Per CLAUDE.md, every change passes Design / Security / Architecture / Testing before final build. This framework powers the Testing audit and supplies tooling (the dependency-audit + secret-scan gates) to the Security audit.