The documented check commands are a subset of the gate, and nothing says so

[JArmandoAnaya]

The check tables in AGENTS.md and CONTRIBUTING.md name uv run mypy src/visionset/kernel,
which reads 72 source files. scripts/check.sh runs uv run mypy src/visionset, which reads 171.
Somebody who runs the documented command and sees it pass has checked well under half of what the
gate checks, and has no signal that anything is missing.

This is not hypothetical. The batch pre-labeling work carried a real type error in
src/visionset/server/routes/batches.py — a Batch.schema_version typed int | None passed to
SchemaService.get, which requires int — through six tasks and eight reviews. Every one of
those runs reported the documented mypy command green, because the file the error lived in is not
in the kernel. It surfaced only when somebody ran scripts/check.sh for an unrelated reason.

The frontend half has the same shape. pnpm -r build && pnpm -r test && pnpm -r lint is the
natural reading of the frontend check rows, and it runs no Playwright at all, so a change can
leave an e2e assertion stale and still look complete. The same branch shipped a test asserting a
capability was unconsumed after making it consumed, and nothing caught it until the browser stages
ran.

The pattern is that every narrower command in the documentation is a subset of check.sh, and
nothing in the documentation says so. A reader reasonably treats the rows in a check table as the
checks.

Two directions, either of which fixes it, and the choice is a judgement about how the tables are
meant to be read:

• Make the documented commands match what the gate runs, so mypy src/visionset is what the
  tables say and the frontend rows name the browser stages.
• Keep the narrow commands as an explicitly-labelled inner loop, and state in both tables that
  bash scripts/check.sh is the gate and the rows above it are a subset.

The second is closer to what the commands are actually for — the narrow mypy is genuinely useful
while iterating on the kernel — but it only works if the subset relationship is stated where the
commands are, rather than inferred.

[JArmandoAnaya]

A second instance, sharper than the mypy one already described here, and worth recording because
the cost was different in kind.

The mypy case is a check that reads less than it appears to. This one is what happens when somebody
acts on the documented commands and treats CI as the backstop: pull request #673 stayed red on
annotator e2e (chromium) through several pushes while every other signal was green — the unit
suites, the type-checker, the import contracts and all four drift gates. The red was never seen,
because the local runs were the narrow ones the tables name and nobody read what CI answered.

The failure underneath was invisible to every narrow gate by construction. Two wire models gained
required fields; fourteen hand-built stubs in the browser specs stopped satisfying the generated
runtime checks; the app stopped rendering; and the suite reported missing elements and timeouts
across four spec files, naming neither field. Only chromium could see it, and the frontend rows in
the check tables do not run chromium.

Two things follow for whatever this issue settles.

The subset relationship needs stating per row, not once at the bottom. A reader scanning for
"how do I check the frontend" finds pnpm -r build && pnpm -r test && pnpm -r lint and has no way
to learn from that row that it runs no browser at all. The same holds for the mypy row and its
scope.

Some changes deserve the full gate and the tables could say which. A change that alters a
published wire model — a new required field, a new member of an enum a client switches on — makes
every hand-built stub in the repository a runtime failure that no unit suite can observe. That is a
narrow, nameable category, and a line saying "run the full gate when the wire changes shape" would
have caught both instances recorded here.

The stub-shape gap itself is filed separately (#682); this comment is about the documentation that
led away from finding it.

[JArmandoAnaya]

Decision (Armando, 2026-08-18): the second of the two directions this issue sets out is the one taken. The narrow commands stay in the check tables, because a kernel-scoped mypy is genuinely what you want while iterating on the kernel, but the tables are relabelled as an inner loop and bash scripts/check.sh is named in them as the gate. The subset relationship is stated per row rather than once at the foot of the table, so that a reader scanning for "how do I check the frontend" learns from that row itself that it runs no browser.

The same edit carries a change of policy about how often the gate runs, which is what makes it worth doing in one pass rather than two. During iteration, only the tests pertinent to the change at hand are run — the file's own suite, the module's suite, or a named test. The exhaustive gate is CI. A full local pass happens in exactly two cases: once, immediately before a pull request is opened, so that a CI failure does not burn a three-strike round-trip, or when it is explicitly asked for.

Two obligations come with that, and the second is new. Reading what CI answered is part of pushing, not an optional follow-up — the instance recorded above, where the annotator chromium suite stayed red across several pushes while every narrow signal was green, is the failure this policy would otherwise invite rather than prevent. And two named categories always earn the full gate regardless of how small the diff looks: anything touching state, gating or progress, which the real-server cycle run already covers and which has been the only detector four times over, and any change to the shape of a published wire model, since a new required field turns every hand-built stub in the browser specs into a runtime failure that no unit suite can observe. The stub-shape gap itself is tracked separately (#682) and this does not stand in for that work.

What does not change: red-before-green and deterministic reproduction for bug fixes, mutation verification, the rule that failures are reported verbatim and no check is claimed to have passed without being run, the two machine-enforced boundaries, and the disclosure clause on the saturated-machine fallback. A reduced run becoming the normal case makes saying which suites did not run more load-bearing, not less.

Corpus reduction is not re-run as part of this. The test-suite reduction program (#517) already answered that question with measurement: the gate went from 355 seconds to 132, one test was deleted to get there, and the entire ratified pruning catalog was worth under two tenths of a second against a corpus with a 63 ms mean and no fat tail. The slowness this issue is about is breadth and frequency of running, not the size of the suite.