mmintel/mintel.me
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases 1 Wiki Activity

feat: add /notes with two engineering write-ups and diagrams

Browse Source 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
mmintel
2026-10-03 19:21:00 +02:00
co-authored by Claude Sonnet 5.5
parent cc0d9bd9c2
commit 4eb663f42a
11 changed files with 992 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/web/src/content/notes/spec-first-gates.tsx
+142
View File
@@ -0,0 +1,142 @@
import * as React from "react";
import { GatePipelineDiagram } from "@/src/components/notes/GatePipelineDiagram";
import {
NoteCode,
NoteFigure,
NoteList,
NoteParagraph,
NoteSection,
} from "@/src/components/notes/NoteProse";
import type { Note } from "./types";
const Body: React.FC = () => (
<>
<NoteParagraph>
A workflow that depends on discipline lasts until the first deadline. In
my Rust systems the workflow is enforced by scripts instead: a change that
skips the spec, drops coverage or leaves a weak test does not get past the
gates, no matter who wrote it or how it was generated.
</NoteParagraph>
<NoteSection>The gates</NoteSection>
<NoteParagraph>
There are four, and each one answers a different question.
</NoteParagraph>
<NoteList>
<li>
<strong>TDD gate.</strong> Was the behavior specified as a test before
it was implemented? Skipping the spec fails the gate.
</li>
<li>
<strong>Functional-style gate.</strong> It forbids methods, traits,{" "}
<NoteCode>&amp;mut</NoteCode> and <NoteCode>unwrap</NoteCode> in the
domain code. Pure functions over immutable data are easier to test and
to mutate, so the style is a rule, not a preference. The gate is itself
covered by a self-test script, because a checker that silently stops
checking is worse than none.
</li>
<li>
<strong>Mutation gate.</strong> The tool changes the code in small ways
and the specs must notice. The policy is zero survivors. A surviving
mutant means either a weak assertion or dead code, and both get fixed.
</li>
<li>
<strong>Coverage ratchet.</strong> Coverage may rise but may not fall.
The gate fails when the number drops below the last recorded one.
</li>
</NoteList>
<NoteFigure caption="Four gates in sequence, run at three scopes.">
<GatePipelineDiagram />
</NoteFigure>
<NoteSection>Three speeds</NoteSection>
<NoteParagraph>
Mutation testing is slow, so the same gates run at three scopes. In the
dev loop they look only at changed lines, which keeps feedback fast enough
to use constantly. Before a merge they run on the changed crates. The
merge gate runs everything. Nothing is skipped on the way to main; a
cheaper check just runs earlier and more often.
</NoteParagraph>
<NoteParagraph>
The mutation gate also keeps a proof ledger. When the code bytes and the
toolchain are unchanged since a previous run, the mutants already caught
are carried over instead of being recomputed. That keeps a zero-survivor
policy affordable on a large codebase, and it stays honest because any
change to the code or the toolchain invalidates the entry.
</NoteParagraph>
<NoteSection>Claims drift, measurements do not</NoteSection>
<NoteParagraph>
The most useful lesson came from reading my own documentation. A README
and a Makefile said &quot;100% coverage at all times&quot;, while the
measured badge said 87.5%. Nobody lied; the sentence was true once and
then the code moved. Prose does not fail a build.
</NoteParagraph>
<NoteParagraph>
So I quote the measured number and enforce a ratchet instead of promising
an absolute. A ratchet is a claim the machine checks on every run: the
number may only go up. It is a weaker sentence than &quot;always
100%&quot; and a far more reliable one.
</NoteParagraph>
<NoteSection>A story from this website</NoteSection>
<NoteParagraph>
This site has a small domain core with the same setup: Vitest for the
specs and Stryker for mutation testing. At one point Stryker reported a
mutation score of 14%. That looked like terrible specs, but the specs were
fine. The mutation tool was silently running zero tests per mutant under
Vitest 5, so every mutant looked like it had survived.
</NoteParagraph>
<NoteParagraph>
The cause was a version mismatch between the Stryker Vitest runner and
Vitest itself. Pinning Vitest to 4.1.x fixed it. The first real run then
found 9 genuine gaps in the specs, the kind a green test suite had been
hiding. Rewriting one date check also removed redundant conditions that no
test could ever distinguish from the simpler version.
</NoteParagraph>
<NoteParagraph>
The pin is now written down in the project instructions, with the reason,
so the next dependency bump does not quietly undo it.
</NoteParagraph>
<NoteSection>What I take from it</NoteSection>
<NoteList>
<li>
<strong>Verify that your verification runs.</strong> A gate that
executes zero tests passes or fails for the wrong reasons. Treat &quot;0
tests ran&quot; as a failure, and look at a surprising score before
explaining it away.
</li>
<li>
<strong>Enforce, do not remind.</strong> If a rule matters, a script
should fail when it is broken. Rules that live in a README drift.
</li>
<li>
<strong>Quote measurements.</strong> Write the number the tool printed,
with the command that printed it, and let a ratchet protect it.
</li>
<li>
<strong>Make the cheap check run first.</strong> Three speeds let the
slow, thorough gates exist without slowing the loop that people use
every few minutes.
</li>
</NoteList>
<NoteParagraph>
None of this is specific to Rust. The same shape works for a TypeScript
project: a spec before the code, mutation testing on the changed files,
and a coverage number that is only allowed to go up.
</NoteParagraph>
</>
);
export const specFirstGates: Note = {
slug: "how-i-enforce-spec-first-mechanically",
title: "How I enforce spec-first mechanically",
summary:
"Four gates, three speeds, and one lesson: claims drift, so measure and ratchet instead of promising.",
publishedOn: "2026-10-03",
readingMinutes: 4,
tags: ["testing", "mutation testing", "process"],
Body,
};