Engineering principles
These are the rules. They show up in the diff and in code review, not on a poster. Each one costs something — more commits than a typical repo, longer scoping passes before any code moves. Each one was added after we paid for not having it.
The history is the artifact.
Every commit is SSH-signed and atomic; the linter rejects pushes that aren't. The history bisects clean — anything on the branch HEAD path builds and passes tests. This produces more commits and more revert noise than a typical workflow. The first time git bisect walks twelve commits and lands on the offending line in twenty minutes makes the trade obvious.
Closed enums for everything we alert on.
Failure modes are typed values from a closed set, with a snapshot test that fails the build when a value is added or removed. The catalog includes a single unknown bucket, and an alert pages on any non-zero rate of it. Growth happens when production hands over a failure mode that wasn't named, never because an engineer guessed in advance. Code review runs longer for new failure paths — every value gets an explicit add. Every alert that fires has a label a human chose.
Deferred work names its trigger condition.
"Later" is not a trigger. "When a job uses more than three concurrent vsock channels" is a trigger. Every deferral in the spec docs and the issue tracker carries an explicit condition for reopening: a metric crossing a threshold, or a class of inbound request that hasn't shown up yet. Decisions without trigger conditions become drift; the rule keeps the backlog honest.
New service endpoints bind to loopback.
A new HTTP listener binds to 127.0.0.1 unless someone names the cross-host use case that requires otherwise. Exposure is a decision, not a default. The boundary is the bind itself, not a per-endpoint auth check — a port that doesn't accept public requests can't have one to authenticate. Same-host scrapers and local diagnostics work as expected. Anything else is an explicit lift.
Loud failures.
A degraded path that doesn't page is a bug, regardless of how often it triggers. Silent fallbacks and swallowed errors get flagged in code review. Errors propagate or they page; there is no third option in production code. On-call alerts ring more often than at a team that hides failures. Regressions get caught before customers do.
Tests run against real hardware below the FSM tier.
Mocks earn their place; they don't get it by default. Unit tests at the FSM layer use in-memory transitions because the FSM is the contract being tested. Below that — anything that talks to a real kernel or a real hypervisor — tests run against real Linux on a dedicated server, including the integration suite that needs KVM and root. The test loop is slower than mock-based suites, and the build machine carries more operational burden. Most of the bugs caught at the integration tier are in our own assumptions, not in the libraries we depend on.
Specs precede plans. Plans precede commits.
For anything larger than a fix, the spec gets written first: the shape of the change, and what was rejected. Then the plan: which files change and in what order. Only then does code move. Days of writing happen before any commit lands. The writing surfaces the wrong-shape decisions while they're still cheap to walk back.