hullcheck

Every repo has a rules file

Ours is called RULES.md and it is long. It says the palette is exactly four hexes. It says there is one spaceship and you do not draw a second one. It says every piece of art records where it came from. It says nobody deploys without a go.

Nice rules. Firm tone. Here is the question nobody asks about a rules file: what actually runs when one of them gets broken? For most rules in most repos the honest answer is nothing. The rule sits there in bold, looking sealed, and the first hard signal that it failed is the one you can't act on anymore.

So we built a tool that asks the question for you, pointed it at our own studio, and open-sourced it. The tool's first real customer was us, and we did not pass.

Why the studio needed it

Spaceship Alpha 9 is a two-person studio that runs like a small fleet: books, audio dramas, a daily news show, an album, a merch shop and a dozen websites in one monorepo, with dozens of branches open at once and master moving several times a day. A lot of that work gets drafted at machine speed.

Machine speed removed the rate limiter on writing code. It did not remove the need to check it. A rule that only lives in prose is a rule that gets skipped the first busy Tuesday. Our own essay, The Living Codebase, put it in one line: a rule that cannot execute is a wish. hullcheck is that sentence, compiled.

Reading one: 47%, and “never” on every rule

The first reading, on 6 September, said 47% gate coverage. The real finding was the Time-to-Truth column: never, for every single rule. The repo had 201 checker scripts and every one was manual. There was no CI in the studio repo at all.

Even the 47% was generous. The matcher credited a gate to a rule on one shared word, including words in the gate's file path, and in a monorepo a path is a bag of topics. Our voice-ID rule scored HOLD against every brand checker in the tree on the word “brand”. Nothing checked voice IDs.

Five hundred files that never belonged in git

A merged pull request landed more than five hundred files of a Python virtual environment on master. .venv/ was in .gitignore the whole time; the rule said keep build junk out of git; nothing ran on it. It went from BREACH to HOLD the same day, and check_git_hygiene.py now blocks the whole class.

94 artworks, one receipt

Our rules say every asset records its provenance: a small sidecar beside it saying what made it, from what prompt, under what licence. The provenance audit went looking. The merch folder held 94 master artworks and exactly one sidecar. The pipeline had been shipping art without receipts, and nobody knew, because nothing counted.

The CI we added never ran a single step

So we added the studio's first ever workflow. It died at zero seconds, every time, and each cause hid the next. The @v1 it pointed at had never been tagged. Fixed, the ratchet would still have failed every PR: it unpacks the base revision with git archive under a 60-second timeout, and our 3.47 GB tree took 169 seconds. A .gitattributes that skips media for git archive took it to 60 MB and 4 seconds. Under both sat an account billing lock, which on a private repo looks exactly like a broken workflow file.

A gate that has never run is a BREACH wearing a HOLD costume. The tool caught it in its own wiring.

Nine defects, filed against ourselves, fixed in one night

A 7,000-file creative monorepo is a stress test no toy repo gives you. We filed every place hullcheck lied to us as an issue upstream: nine of them. Directories no longer count as evidence. A clause is judged by its whole block, so rules written as declarative headlines stop being invisible (it had seen 2 of the 12 rules in our operations section). Rules are addressed by document and ID, so one entry can't flip a second studio's rule. Verify mode's scratch copy is gitignore-aware and refuses when it's too big, instead of trying to copy 241 GB per rule.

All nine landed on 7 September, between half two and four in the morning.

Wishes became gates

Within eight days, rules that had been wishes got something that runs: build junk out of git, deploys only from origin/master, no giant media forced past .gitignore, the cast only on registered voices, every render updating its operator doc, and provenance as a ratchet so the backlog only shrinks. Git hooks put the gates before the commit, so Time-to-Truth went from never to seconds.

On 14 September the studio cut its first release, studio-v1.0.0. The first release check refused to tag: it had found a real canon defect in one of the books.

Today's reading finds 83 rules where the old build found 38, and coverage still went up, to 64%. The tool learned to read, the denominator more than doubled, and the studio holds more of it. The 30 breaches left are a list with names on it. You can't fix a wish you can't see.