# Checks

Deterministic tests that reject a bad state, and the gates that order the work.

A check is a plain script that runs without AI and reads your spec, tokens or code. It passes or reports errors with a suggested fix. Together the checks keep sources, outputs and records in agreement. The full list is in the [check list](/reference/checks/).

## Run the checks

<figure class="illustration"><svg viewBox="0 0 720 240" role="img" aria-label="Many checks run and pass through one gate. The gate ends in one of three exits: 0 pass, 2 pass with overrides, or 1 fail.">
<defs><filter id="sketch-gate" x="-3%" y="-5%" width="106%" height="110%"><feTurbulence type="fractalNoise" baseFrequency="0.035" numOctaves="2" seed="3" result="n"/><feDisplacementMap in="SourceGraphic" in2="n" scale="2.4"/></filter><marker id="arrow-gate" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0 L10 5 L0 10 z" fill="currentColor"/></marker></defs>
<g filter="url(#sketch-gate)" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
<rect x="24" y="24" width="210" height="36" rx="6"/>
<rect x="24" y="78" width="210" height="36" rx="6"/>
<rect x="24" y="132" width="210" height="36" rx="6"/>
<rect x="24" y="186" width="210" height="36" rx="6"/>
<path d="M240 42 L300 120" marker-end="url(#arrow-gate)"/>
<path d="M240 96 L300 120" marker-end="url(#arrow-gate)"/>
<path d="M240 150 L300 120" marker-end="url(#arrow-gate)"/>
<path d="M240 204 L300 120" marker-end="url(#arrow-gate)"/>
<rect x="300" y="24" width="14" height="192" rx="3" fill="var(--sb-color-primary)" stroke="var(--sb-color-primary)"/>
<path d="M314 120 L400 120" marker-end="url(#arrow-gate)"/>
<path d="M400 120 L440 60 L560 60" marker-end="url(#arrow-gate)"/>
<path d="M400 120 L440 120 L560 120" marker-end="url(#arrow-gate)"/>
<path d="M400 120 L440 180 L560 180" marker-end="url(#arrow-gate)" stroke-dasharray="5 4"/>
</g>
<g font-family="inherit" font-size="14">
<text x="40" y="47" fill="var(--sb-color-foreground)">T1 <tspan fill="var(--sb-color-muted-foreground)">tokens are valid</tspan></text>
<text x="40" y="101" fill="var(--sb-color-foreground)">C3 <tspan fill="var(--sb-color-muted-foreground)">code matches its contract</tspan></text>
<text x="40" y="155" fill="var(--sb-color-foreground)">G1 <tspan fill="var(--sb-color-muted-foreground)">outputs match a fresh build</tspan></text>
<text x="40" y="209" fill="var(--sb-color-foreground)">D1 <tspan fill="var(--sb-color-muted-foreground)">design file in step</tspan></text>
<text x="572" y="65" fill="var(--sb-color-foreground)" font-weight="600">exit 0 <tspan font-weight="400" fill="var(--sb-color-muted-foreground)">pass</tspan></text>
<text x="572" y="125" fill="var(--sb-color-foreground)" font-weight="600">exit 2 <tspan font-weight="400" fill="var(--sb-color-muted-foreground)">pass, with overrides</tspan></text>
<text x="572" y="185" fill="var(--sb-color-primary)" font-weight="600">exit 1 <tspan font-weight="400" fill="var(--sb-color-muted-foreground)">fail</tspan></text>
</g>
</svg>
<figcaption>Every check runs; the exit code says whether the sources and outputs agree.</figcaption></figure>

```terminal
sketchbook check
sketchbook check --json
```

`--json` prints one JSON envelope for agents and CI. `--only <ids>` runs a subset and `--fix` rebuilds generated outputs first.

| Code | Meaning |
| --- | --- |
| 0 | Pass |
| 1 | At least one check failed |
| 2 | Pass, with flagged hand edits to generated tokens (overrides) |

## Git gates

When the folder is its own git repository, `sketchbook init` points `core.hooksPath` at `.githooks/` (elsewhere it warns). `pre-commit` runs `sketchbook check` and blocks the commit when any check fails (exit 1); exit 2, a pass with flagged overrides, is allowed. `pre-push` runs the same checks again, so a commit made with `--no-verify`, a merge or a rebase is still checked. In the Sketchbook source repo, `pre-push` also runs `check --maintainer`. `sketchbook doctor` reports whether the gate is active.

## Gates

Two gates apply to a new component. Both are set in `harness.config.json` and written as rules in `.claude/rules/`, so the Claude layer and review enforce them, not a check.

The planning gate (`features.planningGate`) puts the contract and `plan.md` first, then stops for approval before any code.

Test-first (`features.testFirst`) writes tests from the contract and sees them fail before the code exists.

> **Note** Both gates are walked through in [Contracts](/concepts/contracts/).

## Decision records

`spec/decisions/DECISIONS.md` records design-system decisions as `SB-NNNN` entries, and check X1 verifies they are complete. An accepted decision is read-only: add a new entry that supersedes it.

## Next steps

- [Check list](/reference/checks/)
- [Rules](/reference/rules/)
- [Claude layer](/concepts/claude-layer/)
