Tests and the gate

bun test           # everything
bun run test:gate  # everything, plus the coverage gate
bun run lint       # biome
bun run typecheck  # tsc

The gate

src/core/** must be 100% covered. Not the whole project — core specifically, and the gate is a script rather than a coverage threshold because a project-wide percentage lets a large, well-tested core hide an untested adapter.

Core is pure, so full coverage costs little: no containers, no fixtures on disk, no mocking. If a line is hard to cover, that is usually a sign it belongs in an adapter.

Adapters are covered by contract tests that drive the real thing — the compiled binary over stdio for the MCP server, real backends for the environment ports.

What a test is for

A test here is expected to say why it exists. The ones worth reading name the failure:

prepare-test survives, because it is the one that decides the design — a suite run without it fails against an unmigrated database, and that is a false failure somebody then reports as a broken test.

That habit pays when a test fails two years later and nobody remembers what it was protecting.

Guards

Some tests are not about behaviour but about a class of mistake:

• The www/ guard — no file outside a small allow-list may assume a project's code sits under www/. Written after the same wrong assumption appeared in four places, none of which failed loudly.
• The client-name guard — no page of this documentation site may name a client. The list lives in one place, and the build fails rather than the deploy succeeding.
• Never-exposed tools — no MCP tool name may resolve to a destructive command at any flag.

Each exists because the mistake is silent and a human re-reading a few thousand lines misses one.

Walking it for real

Unit tests do not catch everything, and the plan records what the walks found: a stack that started before its database was ready, a certificate that did not cover a new domain, a copy that copied nothing and exited 0. Every one of those passed the test suite.

So a change to something that touches the machine gets walked on a real project before it is called done.