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

feat: add /process page with tested delivery report model and sample

Browse Source 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
mmintel
2026-10-03 19:20:28 +02:00
co-authored by Claude Sonnet 5.5
parent c71916cf08
commit a9702dc3ff
7 changed files with 546 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/web/app/(site)/process/page.tsx
+151 -5
View File
@@ -1,8 +1,51 @@
import type { Metadata } from "next";
import { Container } from "@/src/components/site/Container";
import { SectionHeader } from "@/src/components/site/SectionHeader";
import {
ButtonLink,
Container,
SectionHeader,
TerminalCard,
} from "@/src/components/site";
import { ProcessStepCard } from "@/src/components/process/ProcessStepCard";
import { PROCESS_STEPS } from "@/src/components/process/processSteps";
import { SAMPLE_DELIVERY_REPORT } from "@/src/components/process/sampleDeliveryReport";
import { formatDeliveryReport } from "@/src/domain/deliveryReport";
export const metadata: Metadata = { title: "Process" };
const TITLE = "Process: AI speed, engineering proof";
const DESCRIPTION =
"How I ship AI-accelerated code that holds up: spec first, red, green, mutation check and a delivery report with exact commands and results on every pull request.";
export const metadata: Metadata = {
title: TITLE,
description: DESCRIPTION,
alternates: { canonical: "/process" },
openGraph: {
title: TITLE,
description: DESCRIPTION,
url: "/process",
type: "website",
},
};
const GUARDRAILS = [
{
title: "Pre-commit gate",
text: "Formatting and lint on staged files, then typecheck and the unit tests, run before a commit is created. Broken code does not enter history.",
},
{
title: "Pre-push gate",
text: "Coverage runs before a push leaves my machine, and the mutation check runs when the domain logic changed. The remote only receives green work.",
},
{
title: "CI gates the deploy",
text: "On client projects the same checks run again in CI, and a deploy only starts when they pass. My machine is not the only line of defense.",
},
{
title: "Tests are never weakened",
text: "If a test blocks a change, I do not skip, loosen or delete it to get green. If the test is wrong, I tell you why and the spec changes with your agreement.",
},
] as const;
const reportLines = formatDeliveryReport(SAMPLE_DELIVERY_REPORT);
export default function Page() {
return (
@@ -10,9 +53,112 @@ export default function Page() {
<SectionHeader
as="h1"
kicker="/process"
title="Process"
lead="This page is coming soon."
title="How I ship AI-accelerated code that holds up"
lead="AI makes code cheap to produce. What you pay for is code that is correct. Every change goes through the same five steps, and you get the evidence for each of them every week."
/>
<section aria-labelledby="steps" className="mt-16">
<h2 id="steps" className="sr-only">
The five steps
</h2>
<p className="!mb-6 max-w-2xl text-base text-muted">
One running example: parsing an availability, meaning a date and
weekly hours. The date 2026-02-30 must be rejected, 2028-02-29 must be
accepted, and 168 hours is the upper boundary of a week.
</p>
<ol className="list-none !p-0">
{PROCESS_STEPS.map((step, index) => (
<ProcessStepCard key={step.id} step={step} index={index} />
))}
</ol>
</section>
<section aria-labelledby="report" className="mt-16">
<SectionHeader
kicker="evidence"
title="A delivery report"
lead="This is what arrives with a pull request. The example below is illustrative: the numbers are made up for the availability parsing case and are not from a client project."
/>
<TerminalCard
title="delivery report (illustrative example)"
className="mt-8 max-w-3xl"
>
{reportLines.map((line) => (
<p key={line} className="!mb-0 whitespace-pre">
{line}
</p>
))}
</TerminalCard>
<p className="!mb-0 mt-4">
<a
href="/sample-delivery-report.md"
download
className="font-mono text-sm text-accent underline underline-offset-4"
>
Download the sample report (sample-delivery-report.md)
</a>
</p>
</section>
<section aria-labelledby="weak" className="mt-16 max-w-2xl">
<h2 id="weak" className="!mt-0 !text-2xl">
What I do when tests are weak or missing
</h2>
<p className="text-base leading-relaxed text-muted">
AI-built code often arrives with few tests, or with tests that only
repeat the implementation. I do not start by rewriting. I write the
expected behavior as cases for the parts that matter most, run them
against the existing code, and let the failures show what is really
broken. Then I add a mutation baseline so you can see which tests
would not notice a bug.
</p>
<h2 className="!text-2xl">Why mutation testing</h2>
<p className="text-base leading-relaxed text-muted">
Coverage tells you which lines ran during the tests. It does not tell
you whether the tests would notice a bug in those lines. Mutation
testing changes the code on purpose and checks that a test fails. That
is the question you care about. Coverage stays useful as a gap finder:
it points at code nothing exercises. It is not a goal, and a high
number alone proves little.
</p>
<p className="text-base leading-relaxed text-muted">
Two systems where I run this: a Rust and Solidity liquidation system
across 7 chains, with a zero-survivor mutation gate and a coverage
ratchet, and the domain core of this website, which has its own tests
and mutation gate.
</p>
</section>
<section aria-labelledby="guardrails" className="mt-16">
<SectionHeader
kicker="guardrails"
title="Gates that run without me"
lead="The process does not depend on my discipline on a good day."
/>
<ul className="mt-8 grid list-none gap-6 !p-0 md:grid-cols-2">
{GUARDRAILS.map((item) => (
<li
key={item.title}
className="rounded-lg border border-border bg-surface p-5"
>
<h3 className="!mb-2 !mt-0 text-lg font-semibold">
{item.title}
</h3>
<p className="!mb-0 text-base leading-relaxed text-muted">
{item.text}
</p>
</li>
))}
</ul>
</section>
<section className="mt-16 border-t border-border pt-10">
<h2 className="!mt-0 !text-2xl">Want this on your codebase?</h2>
<p className="mb-6 max-w-2xl text-base text-muted">
A 20-minute intro call is enough to see whether this fits your team.
</p>
<ButtonLink href="/book">Book a 20-minute intro call</ButtonLink>
</section>
</Container>
);
}
apps/web/public/sample-delivery-report.md
+41
View File
@@ -0,0 +1,41 @@
# Delivery report (illustrative example)
This is an illustrative example, not a report from a real client project.
It shows the shape of the evidence attached to every pull request.
Change: availability parsing (a date and weekly hours)
Rules: reject 2026-02-30, accept 2028-02-29, accept 0 to 168 hours per week, reject 169
## Gates
```
[pass] spec 9 cases written before code
[pass] red 9 failing for the right reason
[pass] green 9/9 pass
[pass] mutation 14 mutants, 14 caught, 0 survived
[pass] coverage changed lines 100% (23/23)
[pass] typecheck clean
[pass] lint clean
verdict: pass
```
## Commands
Every gate is a command you can run yourself:
```
pnpm test # spec, red, green
pnpm test:mutation # mutation check on the changed files
pnpm test:coverage # coverage on changed lines
pnpm typecheck
pnpm lint
```
## How to read it
- spec: behavior written as concrete cases before any implementation exists.
- red: the new cases fail because the behavior is missing, not because of an import or compile error.
- green: all cases pass with the simplest clean solution.
- mutation: the code is changed on purpose (for example `<=` becomes `<`); the tests must fail. A surviving mutant means a weak assertion or dead code.
- coverage: shows which changed lines ran. It is a gap finder, not a goal.
- verdict is pass only if every gate passes.
apps/web/src/components/process/ProcessStepCard.tsx
+30
View File
@@ -0,0 +1,30 @@
import * as React from "react";
import { TerminalCard } from "@/src/components/site";
import type { ProcessStep } from "./processSteps";
type ProcessStepCardProps = {
readonly step: ProcessStep;
readonly index: number;
};
export const ProcessStepCard: React.FC<ProcessStepCardProps> = ({
step,
index,
}) => (
<li className="grid gap-6 border-t border-border py-8 md:grid-cols-2 md:gap-10">
<div>
<p className="!mb-2 font-mono text-xs uppercase tracking-widest text-accent">
Step {index + 1}
</p>
<h3 className="!mb-3 !mt-0 text-xl font-semibold">{step.title}</h3>
<p className="!mb-0 text-base leading-relaxed text-muted">{step.rule}</p>
</div>
<TerminalCard title={step.exampleLabel}>
{step.example.map((line) => (
<p key={line} className="!mb-0 whitespace-pre">
{line}
</p>
))}
</TerminalCard>
</li>
);
apps/web/src/components/process/processSteps.ts
+68
View File
@@ -0,0 +1,68 @@
export type ProcessStep = {
readonly id: string;
readonly title: string;
readonly rule: string;
readonly exampleLabel: string;
readonly example: readonly string[];
};
export const PROCESS_STEPS: readonly ProcessStep[] = [
{
id: "spec",
title: "Spec first",
rule: "Behavior is written as concrete cases before any code: inputs, outputs, edge cases, error paths. Unclear business rules get one precise question to you, not a guess.",
exampleLabel: "Availability parsing: the cases",
example: [
'"2026-02-30" -> rejected, not a real date',
'"2028-02-29" -> accepted, leap day',
"168 h per week -> accepted, the boundary",
"169 h per week -> rejected",
"-1 h per week -> rejected",
],
},
{
id: "red",
title: "Red",
rule: "The cases run and fail for the right reason: the behavior is missing, not an import error or a typo. A bug fix starts with a failing test that reproduces the bug.",
exampleLabel: "Availability parsing: first run",
example: [
"FAIL parses a leap day",
" expected { ok: true }, received undefined",
"9 failing, all because parseAvailability does not exist yet",
],
},
{
id: "green",
title: "Green",
rule: "The simplest clean solution that makes the cases pass. Pure functions for the logic, side effects pushed to thin edges. Then refactor while the tests stay green.",
exampleLabel: "Availability parsing: second run",
example: [
"9/9 pass",
"date check: month length plus leap-year rule",
"hours check: whole number from 0 to 168",
],
},
{
id: "mutation",
title: "Mutation check",
rule: "A tool changes the code on purpose and reruns the tests. Every change must make a test fail. A surviving mutant means a weak assertion or dead code, and I fix one or the other.",
exampleLabel: "Availability parsing: mutants",
example: [
"hours <= 168 -> hours < 168",
" caught by the 168 h case",
"day <= daysInMonth -> day < daysInMonth",
" caught by the 2028-02-29 case",
],
},
{
id: "report",
title: "Delivery report",
rule: "Every pull request carries the exact commands and their results: case counts, mutation result, coverage on changed lines, typecheck and lint. You can rerun every line.",
exampleLabel: "Availability parsing: the report",
example: [
"spec 9 -> red 9 -> green 9/9",
"mutation 14 caught, 0 survived",
"see the full sample below",
],
},
];
apps/web/src/components/process/sampleDeliveryReport.ts
+16
View File
@@ -0,0 +1,16 @@
import type { DeliveryReport } from "@/src/domain/deliveryReport";
// Illustrative numbers for the availability parsing example. Not a real project.
export const SAMPLE_DELIVERY_REPORT: DeliveryReport = {
specCases: 9,
redFailing: 9,
greenPassing: 9,
greenTotal: 9,
mutantsTotal: 14,
mutantsCaught: 14,
mutantsSurvived: 0,
changedLinesCovered: 23,
changedLinesTotal: 23,
typecheckErrors: 0,
lintErrors: 0,
};
apps/web/src/domain/deliveryReport.spec.ts
+120
View File
@@ -0,0 +1,120 @@
import { describe, expect, it } from "vitest";
import {
formatDeliveryReport,
verdictOf,
type DeliveryReport,
} from "./deliveryReport";
const passing: DeliveryReport = {
specCases: 9,
redFailing: 9,
greenPassing: 9,
greenTotal: 9,
mutantsTotal: 14,
mutantsCaught: 14,
mutantsSurvived: 0,
changedLinesCovered: 23,
changedLinesTotal: 23,
typecheckErrors: 0,
lintErrors: 0,
};
describe("verdictOf", () => {
it("is pass when every gate passes", () => {
expect(verdictOf(passing)).toBe("pass");
});
it.each<[string, Partial<DeliveryReport>]>([
["no spec cases", { specCases: 0, redFailing: 0 }],
["red does not match the written cases", { redFailing: 8 }],
["a green test fails", { greenPassing: 8 }],
["no green tests ran", { greenPassing: 0, greenTotal: 0 }],
["a mutant survived", { mutantsCaught: 13, mutantsSurvived: 1 }],
["no mutants were generated", { mutantsTotal: 0, mutantsCaught: 0 }],
["caught plus survived does not add up", { mutantsCaught: 13 }],
[
"a survivor is reported although all mutants count as caught",
{ mutantsSurvived: 1 },
],
["a changed line is uncovered", { changedLinesCovered: 22 }],
[
"no changed lines measured",
{ changedLinesCovered: 0, changedLinesTotal: 0 },
],
["typecheck has errors", { typecheckErrors: 1 }],
["lint has errors", { lintErrors: 2 }],
])("is fail when %s", (_name, patch) => {
expect(verdictOf({ ...passing, ...patch })).toBe("fail");
});
});
describe("formatDeliveryReport", () => {
it("renders one line per gate and a verdict for a passing report", () => {
expect(formatDeliveryReport(passing)).toEqual([
"[pass] spec 9 cases written before code",
"[pass] red 9 failing for the right reason",
"[pass] green 9/9 pass",
"[pass] mutation 14 mutants, 14 caught, 0 survived",
"[pass] coverage changed lines 100% (23/23)",
"[pass] typecheck clean",
"[pass] lint clean",
"verdict: pass",
]);
});
it("marks failing gates with their numbers", () => {
const lines = formatDeliveryReport({
...passing,
redFailing: 8,
greenPassing: 8,
mutantsCaught: 13,
mutantsSurvived: 1,
changedLinesCovered: 22,
typecheckErrors: 3,
lintErrors: 1,
});
expect(lines).toEqual([
"[pass] spec 9 cases written before code",
"[fail] red 8 failing, expected 9",
"[fail] green 8/9 pass",
"[fail] mutation 14 mutants, 13 caught, 1 survived",
"[fail] coverage changed lines 95.6% (22/23)",
"[fail] typecheck 3 errors",
"[fail] lint 1 error",
"verdict: fail",
]);
});
it("never rounds a partial coverage up to 100", () => {
const lines = formatDeliveryReport({
...passing,
changedLinesCovered: 9999,
changedLinesTotal: 10000,
});
expect(lines).toContain(
"[fail] coverage changed lines 99.9% (9999/10000)",
);
});
it("reports empty measurements as failures", () => {
const lines = formatDeliveryReport({
...passing,
specCases: 0,
redFailing: 0,
greenPassing: 0,
greenTotal: 0,
mutantsTotal: 0,
mutantsCaught: 0,
changedLinesCovered: 0,
changedLinesTotal: 0,
});
expect(lines.slice(0, 5)).toEqual([
"[fail] spec no cases written",
"[fail] red no cases written",
"[fail] green 0/0 pass",
"[fail] mutation no mutants generated",
"[fail] coverage no changed lines measured",
]);
expect(lines.at(-1)).toBe("verdict: fail");
});
});
apps/web/src/domain/deliveryReport.ts
+120
View File
@@ -0,0 +1,120 @@
export type DeliveryReport = {
readonly specCases: number;
readonly redFailing: number;
readonly greenPassing: number;
readonly greenTotal: number;
readonly mutantsTotal: number;
readonly mutantsCaught: number;
readonly mutantsSurvived: number;
readonly changedLinesCovered: number;
readonly changedLinesTotal: number;
readonly typecheckErrors: number;
readonly lintErrors: number;
};
export type Verdict = "pass" | "fail";
type Gate = {
readonly name: string;
readonly pass: boolean;
readonly detail: string;
};
const NAME_COLUMN_WIDTH = 11;
const PERCENT_SCALE = 1000;
const PERCENT_DIVISOR = 10;
const plural = (count: number, singular: string): string =>
`${count} ${singular}${count === 1 ? "" : "s"}`;
// Floor, never round: 99.96% must not be shown as 100%.
const floorPercent = (part: number, whole: number): number =>
Math.floor((part / whole) * PERCENT_SCALE) / PERCENT_DIVISOR;
const specGate = (r: DeliveryReport): Gate =>
r.specCases > 0
? {
name: "spec",
pass: true,
detail: `${r.specCases} cases written before code`,
}
: { name: "spec", pass: false, detail: "no cases written" };
const redGate = (r: DeliveryReport): Gate => {
if (r.specCases === 0) {
return { name: "red", pass: false, detail: "no cases written" };
}
return r.redFailing === r.specCases
? {
name: "red",
pass: true,
detail: `${r.redFailing} failing for the right reason`,
}
: {
name: "red",
pass: false,
detail: `${r.redFailing} failing, expected ${r.specCases}`,
};
};
const greenGate = (r: DeliveryReport): Gate => ({
name: "green",
pass: r.greenTotal > 0 && r.greenPassing === r.greenTotal,
detail: `${r.greenPassing}/${r.greenTotal} pass`,
});
const mutationGate = (r: DeliveryReport): Gate => {
if (r.mutantsTotal === 0) {
return { name: "mutation", pass: false, detail: "no mutants generated" };
}
return {
name: "mutation",
pass: r.mutantsSurvived === 0 && r.mutantsCaught === r.mutantsTotal,
detail: `${r.mutantsTotal} mutants, ${r.mutantsCaught} caught, ${r.mutantsSurvived} survived`,
};
};
const coverageGate = (r: DeliveryReport): Gate => {
if (r.changedLinesTotal === 0) {
return {
name: "coverage",
pass: false,
detail: "no changed lines measured",
};
}
const percent = floorPercent(r.changedLinesCovered, r.changedLinesTotal);
return {
name: "coverage",
pass: r.changedLinesCovered === r.changedLinesTotal,
detail: `changed lines ${percent}% (${r.changedLinesCovered}/${r.changedLinesTotal})`,
};
};
const errorCountGate = (name: string, errors: number): Gate => ({
name,
pass: errors === 0,
detail: errors === 0 ? "clean" : plural(errors, "error"),
});
const gatesOf = (r: DeliveryReport): readonly Gate[] => [
specGate(r),
redGate(r),
greenGate(r),
mutationGate(r),
coverageGate(r),
errorCountGate("typecheck", r.typecheckErrors),
errorCountGate("lint", r.lintErrors),
];
export const verdictOf = (report: DeliveryReport): Verdict =>
gatesOf(report).every((gate) => gate.pass) ? "pass" : "fail";
export const formatDeliveryReport = (
report: DeliveryReport,
): readonly string[] => [
...gatesOf(report).map(
(gate) =>
`[${gate.pass ? "pass" : "fail"}] ${gate.name.padEnd(NAME_COLUMN_WIDTH)}${gate.detail}`,
),
`verdict: ${verdictOf(report)}`,
];