Review gate

Type: types/type-spec.md

Authoring Instructions

A review gate is a closed-ended, verdict-kind quality assay. Each gate is one markdown criterion telling a reviewer what failure to seek and how to choose the final decision: PASS, WARN or FAIL. A reviewer that cannot inspect the target returns no decision and reports that the pair cannot be judged. INFO may label a finding in the prose but is not a final decision. Report-kind assays are instructions, not review-gate artifacts. The catalog discovers gates at kb/instructions/review-gates/{lens}/{name}.md.

Frontmatter

  • gate_id: {lens}/{name} — matches the file path under kb/instructions/review-gates/.
  • name: {Human-Readable Name} — used in rendered reviews.
  • lens: {bundle} — the bundle this gate belongs to (accessibility, semantic, structural, complexity, prose, frontmatter, sentence).
  • watches: [title | description | body] — which parts of the target the gate inspects. Review freshness hashes only these parts of the note. Any other value, or no declaration, makes the gate watch the whole note.
  • staleness: changed — declares the only supported runtime policy: a stored result is stale after a change to a watched part of its note or to its criterion text. Gate resolution and schema validation reject missing or other values. This field is not a per-gate threshold or tuning surface.
  • description — the trigger condition: what kind of authoring problem this gate catches.
  • type: types/review-gate.md.
  • Optional requires_trait or requires_type — narrow the gate to a subset of artifacts that carry the given trait or type. A requires_type value is written like a type: value, such as types/definition.md.

Body

  • ## Failure mode — the failure the reviewer is looking for, stated as the concrete pattern that should not appear.
  • ## Test — the procedure for choosing PASS, WARN or FAIL. It may route INFO findings without changing a clean final decision. Name exceptions explicitly so the reviewer does not double-flag adjacent gates.
  • Optional ## Example (pass) and ## Example (fail) blocks make the test concrete. Most existing gates carry at least one of each — copy their shape rather than reinventing it.
  • The test must be self-contained. Review freshness hashes only note text and criterion text, so a test that leans on contract text living elsewhere (a type spec, a collection convention) carries a dependency that never invalidates acceptances. If the test needs contract language, quote it in the gate body — that converts the dependency into hashed criterion text, and editing the gate to track a moved contract fires criterion-changed through the normal path. Conformance to a type's contract as a whole is not a catalog gate's job: that is the type-conformance pair, whose criterion side is the type spec itself (ADR 038). A gate scoped by requires_type owns a sharper, named failure mode and should state its boundary with the conformance pair.

Force and warrant

A gate is automated problem-noticing, not reject-capable evaluation. Its verdict generates disposition work — fix, reject, or defer, decided downstream — and commit or merge is what retains a change; FAIL is an escalation signal, not an operative blocker. Author the test as a detector for the named failure mode, not as an acceptance authority.

  • Warrant boundary. The model-judged test is warranted only for the failure mode the gate names, and that warrant is currently uncalibrated. Do not raise a gate's enforcement force (making its verdicts blocking, or auto-acting on them without disposition) before it meets the acceptance criteria in the calibration proposal.
  • Judgment outside the freshness hash. Review freshness hashes the watched note parts and the criterion text only. Editing a gate's criterion text makes its results stale through the normal path — but a change that shifts judgment without touching either hashed side (prompt rendering, process scaffolding, judging configuration) leaves stored results silently fresh. Such a change owes a deliberate re-review of the affected corpus until freshness can represent that dependency.

Template

---
gate_id: {lens}/{name}
name: {Human-Readable Name}
description: '{What kind of authoring problem this gate catches.}'
type: types/review-gate.md
lens: {lens}
watches: [body]
staleness: changed
---

## Failure mode

{Concrete pattern that should not appear.}

## Test

{Procedure for choosing PASS, WARN or FAIL. INFO may appear only as a finding label. Name exceptions explicitly.}

## Example (fail)

{Minimal failing example.}

## Example (pass)

{Minimal passing example.}