On a Tuesday in July I sat down to write the fifth wire format for a system that had not yet executed a single line of production code.

I got about four hundred words in before I stopped, because I could not answer a question a reviewer would ask in the first minute: what does an implementer do when two of these five formats disagree about the same fact? I had five protocols — an authorisation envelope, an action receipt, an artifact-attestation record, a composite attestation profile, and a verification bundle — each with its own field names, its own canonicalisation rules, and its own conformance surface. Each was defensible alone. Together they were five separate opportunities for two implementations to be correct and incompatible at the same time.

That afternoon, four of them stopped being protocols. They became profiles of one envelope: five views onto a single signed object, sharing one canonicalisation, one signature, one conformance suite. The fifth survived, narrowed.

I want to be precise about what happened, because it is the entire argument of this piece. No code was deleted, because no code existed. The decision cost an afternoon of writing and a small amount of ego. Made nine months later, it would have cost five implementations, five test suites, five sets of downstream consumers, and a migration touching everything. The reason it was cheap is that the contract was frozen first, and a contract is a document, and documents are cheap to be wrong in.

This edition is about that discipline: writing the specification before the implementation, deliberately, on a system built substantially by AI coding agents. What the freeze caught, what it cost, where it nearly failed, and the one rule I would carry to a project with no agents on it at all.

The problem the freeze exists to solve

Start with the mechanics of building with a fleet rather than a team, because the failure mode is not the one people expect.

The expected failure is that the agents write bad code. In my experience that is not the binding constraint. On a well-specified task with a frozen interface, a current coding model produces code I am happy to review, and it produces it faster than I can specify the next task. The output is not the bottleneck.

The binding constraint is divergence. Point four agents at four components of the same system, give each one an interface description that is ninety percent settled, and every one of them will resolve the remaining ten percent locally, confidently, and differently. Agent one decides the digest is lowercase hex. Agent two carries the sha256: prefix. Agent three base64s it. Agent four writes a helper accepting all three and normalising — the worst of the four, because it works, so nobody finds it.

None of those agents is wrong. Each made a reasonable local decision in the absence of an authoritative statement. And each wrote tests that pass, because each tested its own interpretation.

That is the sentence I would put on a wall: an agent fleet building against an unfrozen contract produces conflicting implementations faster than one developer produces correct ones. Speed is not a virtue when the thing being accelerated is divergence. Four agents at four times human pace, all diverging, reach an unmergeable codebase in a week rather than a quarter. The AI made it worse, not better, and it made it worse because it was good.

What "frozen" actually means

There is a useless version of this idea, and I want to separate it out. The useless version is "write a design doc first." Everybody has written design docs. They rot, nobody reads them, and the code becomes the specification by default.

A freeze is a different object with four properties the design doc lacks.

It is normative, and says so. Every document in the pack carries a status line: FROZEN CANDIDATE or DRAFT SPEC. Frozen means implementations build against it, and a breaking change afterwards requires a new protocol version rather than an edit. Draft means the argument is settled but the fields are not, and no implementation should treat it as stable. That distinction sits at the top of the file, where an implementer — human or agent — reads it before anything else.

It carries conformance vectors, not prose. A specification that describes a format is a suggestion. A specification shipping a file of golden test vectors is a specification. The manifest spec ships its vectors; the receipt spec ships its JSON Schema. An implementation either reproduces them byte for byte or it does not conform, and there is no conversation to have about it.

It names what it does not cover. One document in the pack exists solely so that the system's central claim — that an agent cannot bypass it — is falsifiable rather than rhetorical. It defines three enforcement modes, requires every receipt to declare which one produced it, and permits only one of them to claim containment. That is a specification whose main function is constraining what the product may say about itself.

It has an owner and a version. Not a wiki page eleven people have edited. A file, in the repository, beside the code, that CI can check links out of and a reviewer can diff.

Sixteen such documents now define the contract. Six are the spine: the receipt, the notary interface, the enforcement-mode contract, the verdict function, the capability algebra, the delegation engine. Four are containment: root compromise, egress, containment conformance, the policy compiler. Four are assurance: evaluation receipts, the invariant attack corpus, the attack-to-policy loop, the conformance harness. One is exchange, contributed outward rather than kept. The sixteenth is the agent manifest.

None was written after the thing it describes.

The five protocols, in full

Let me walk the decision from the top of this piece properly, because the abstract version sounds obviously correct and the concrete version is where it hurts.

Each of the five candidates had a real job. The first carried authorisation: who asked, under what authority, bounded by what. The second carried the outcome: what happened, signed. The third carried artifact identity: which model weights, which tool version, which dataset digest served this action. The fourth carried composite attestation: hardware root, runtime measurement, workload identity, chained. The fifth carried verification: the bundle a third party needs to check any of the above without privileged access.

Five jobs, five documents. A reasonable person writes five protocols.

Here is what that reasonable person has actually built. Five canonicalisation algorithms, each of which must be deterministic and each a separate opportunity to be subtly non-deterministic. Five signature envelopes. Five schema-evolution stories. Five conformance suites. And critically, the interactions between them are unspecified. If the authorisation envelope and the outcome receipt disagree about which model digest served an action, which is authoritative? Nothing in five independent documents answers that, because the question lives inside none of them.

There is a strategic cost on top of the engineering one. The whole claim of a system like this is unification — that the authority decision and its cryptographic proof are the same object rather than two systems requiring reconciliation. Five wire formats argue against that claim directly. Every additional format multiplied the conformance burden while weakening the exact property that made the work worth doing.

So: one envelope, five profiles. One canonicalisation, one signature, one conformance suite. A profile is a view — a defined projection of the single object for one consumer — and because it is a projection rather than a translation, there is no lossy step and no disagreement available. The authorisation and the outcome cannot contradict each other about the model digest, because there is one field, in one object, signed once.

The cost was real. The single envelope is larger than any one of the five would have been, and a consumer wanting only artifact identity now parses an object carrying four things it does not need. I decided that was acceptable. A fatter object is a performance question with known answers. Five formats that can disagree is a correctness question with no answer at all.

Notice the timeline. That decision took an afternoon and touched five documents and zero implementations. The same decision after those five protocols had shipped is a year-long migration across every producer and consumer — and in practice, a decision nobody makes. You live with the five formats forever, and the incoherence becomes the architecture.

What the freeze caught that a code review would not have

Three things, different in kind.

A duplicate of something mature. Writing the notary specification forced me to state exactly what one verb did. Written plainly, it did what cosign already does, slightly worse, in a system with no business owning a signing implementation. The verb was retired before anything implemented it. That finding is nearly impossible in code review: by review time the code exists, it works, and "this duplicates a mature tool" reads as an opinion rather than a defect. In a specification, where "this component signs artifacts" sits four lines above "we consume Sigstore for artifact signing", the contradiction fits on one screen.

The broader pass removed a great deal. Of the components in the original portfolio, twenty-one were cut for re-implementing mature open source the system should call rather than rebuild. That number measures how much of the original design was accidental duplication — visible only because everything had been written down in one place, at one level of abstraction, at the same time.

A component load-bearing by implication and wired to nothing. One console module's own documentation referred to policies "compiled by the policy compiler" — a component that, at that moment, nothing in the repository invoked. The design depended on it. The code did not call it. That gap is invisible from inside either file and obvious when both contracts sit in the same pack.

A factual error that had propagated through the design. The containment conformance work is positioned against a specific piece of legislation, and that legislation was cited by the wrong bill number in the source material — copied onward into several documents. Writing a normative spec means writing the citation as a normative fact, which means checking it, which is how the error surfaced. A wrong bill number in a slide is embarrassing. A wrong bill number in a conformance suite claiming to test that bill's mandated capabilities is a product defect.

Where the freeze nearly failed, and the rule that saved it

I do not want to write a piece where a discipline works flawlessly, so here is the part that went wrong.

A frozen contract creates a temptation a fluid one does not: to treat the document as the truth. With sixteen normative specifications in a repository it becomes very easy to answer a question by reading the spec rather than running the code, and then to write that answer somewhere else as though it had been observed.

That happened. A document described a component accurately when written, stopped being accurate, and was then cited by a second document, which was cited by a third. Nothing was lying. Every sentence had been true when written. The freeze had made the documents authoritative, and authority without a re-verification step is a longer-lived error.

The countermeasure has one rule and it is boring: every claim in a status document carries how it was established. Three states, marked inline — observed running on this machine this session; established from the source but not executed; cannot be established from here. Not sophisticated. It works because it makes the cheap kind of claim visibly cheap. A sentence saying "verified" that cannot name the command which verified it is a sentence somebody must fix before it ships.

There is a second-order version of this failure that is the most interesting thing I found all month. While correcting a false claim in one document, I nearly introduced a different false claim into the correction — writing that something had never been built by CI, two days after CI had built it on four platforms. It felt like tightening the document. It would have made the document more wrong while making it read as more careful.

A document can be stale in the direction of understating itself and still be one nobody can trust. None of my countermeasures catch that. The only thing that caught it was checking the claim against a different document before committing.

The part that transfers to a codebase with no agents in it

I would keep this discipline on a solo project, and the reason is not about AI.

A frozen contract converts architectural decisions into documentary ones. Architectural decisions are expensive to reverse because they are embodied in code, tests, data, and the habits of everyone who has read the code. Documentary decisions are cheap to reverse because they are embodied in a paragraph. The freeze does not make you smarter. It moves the moment of decision to the point in the project where being wrong costs least, and it makes wrongness visible by forcing incompatible statements onto the same page.

Everything else follows. The five-to-one collapse, the retired verb, the twenty-one cuts, the wrong citation — none required unusual insight. They required the relevant facts to be adjacent, in prose, before anything had been built on top of them.

The agent fleet raises the stakes rather than changing the principle. With one developer, an unfrozen contract produces confusion at human speed, and humans are good at noticing they are confused. With a fleet it produces confident, tested, mutually incompatible implementations at four or ten times that speed, and no participant experiences any confusion at all. That is the specific hazard: divergence at scale does not feel like a problem from inside any single agent's context. It is visible only in the aggregate, and only if something authoritative exists to compare against.

Where this meets what supervisors are about to ask

One instrument is worth naming, and only one.

In January 2026 FINRA published observations addressing AI agents. Observations, not a rule — that distinction matters and I will not blur it. What the document does is describe the shape of the questions an examiner asks about an agentic workflow: what it was permitted to do, who permitted it, what record exists, and whether the firm can reconstruct a specific action afterwards.

Every one of those is a question about a contract. Not about model quality, not accuracy, not a benchmark. About whether an authoritative statement exists of what the system was allowed to do, and whether behaviour can be checked against it.

A firm whose agent behaviour is defined by whatever code happens to be running cannot answer except by reading the code, in which case the answer is an opinion. A firm with a frozen, versioned, vector-backed contract answers by pointing at a document and a conformance report.

I am not claiming the freeze is a compliance strategy. I am claiming the artefact the discipline produces — an authoritative, checkable statement of intended behaviour, dated and versioned — happens to be exactly the artefact those questions require. Not a coincidence. Both are asking the same thing: is anything here true independently of the implementation?

What to check on Monday

Five checks, in ascending order of discomfort.

One. Find an interface between two components that different people, or different agents, built. Ask each side separately what happens at one edge case: an empty list, a duplicate id, a value at the boundary. If the answers differ, you have found an unfrozen contract, and it is load-bearing right now.

Two. Take your most-referenced internal design document. For each factual claim, ask how it was established. If the answer is "somebody wrote it and it seemed right", that document is authority without verification, and it is being cited.

Three. Count your wire formats. Not services — formats: the distinct serialised objects crossing a boundary and getting validated. For each pair, ask what happens when they disagree about a fact they both carry. If no document answers, that is a specification gap, and it will surface as a production incident that looks like a data problem.

Four. Look for a component your documentation treats as load-bearing that nothing in your code calls. Grep the component name outside its own directory, in code rather than docs. Zero external references on something the design depends on is the exact defect shape described above.

Five. Ask whether any claim your system makes about itself is falsifiable. Not "do we have a security page" — whether a defined test exists whose failure would oblige you to withdraw a specific sentence. If not, the sentence is marketing, and it is somewhere a person will rely on it.

What I am not claiming

The freeze does not produce a correct design. It produces a design whose incoherences are visible early, which is a different and lesser thing. Several specifications in this pack will turn out to be wrong; the version discipline exists because I expect that.

It is also not free. It cost roughly three weeks of writing before the first component was implemented, and during those weeks a reasonable observer would have concluded nothing was happening. I cannot prove the three weeks were repaid, because I cannot run the counterfactual. What I can say is that the five-format collapse alone would have cost more than three weeks to undo later, and it was one of four such decisions.

The pack is unfinished. Some documents are frozen candidates; others are explicitly drafts, and the difference is marked, because an implementer treating a draft as frozen is the divergence problem in a new costume.

The invitation

The contract pack is sixteen documents, and its whole value proposition is that a stranger can find it wrong.

I am looking for reviewers — specifically, people who have implemented against a protocol specification and know where ambiguities hide. Not a general call for feedback. A specific one: read one document, find the sentence an implementer could read two ways, and tell me. The capability algebra and the conformance harness are the two I am least confident in, and the two where a divergence would cost most.

If you have shipped a protocol and lived with its ambiguities afterwards, you already know the sentence I am asking about.

Claims register

  • Sixteen normative documents define the contract pack · spec directory listing · verified — enumerated
  • Documents were written before implementation, deliberately · repository README, stated as design rationale · verified — in source
  • Five protocol formats were demoted to profiles of one envelope · portfolio re-cut, §2 · verified — in source
  • Twenty-one of fifty-four components were cut for duplicating mature OSS · portfolio re-cut, §1 and §3 · verified — counted
  • One signing verb was retired as a duplicate of cosign · portfolio re-cut, §5 · verified — in source
  • A component the design depends on was invoked by nothing · OSS-readiness pass, measured across 74 component directories · verified — measured
  • A cited bill number was wrong in the source material and corrected · portfolio re-cut, §6 · verified — in source
  • Documents carry FROZEN CANDIDATE / DRAFT SPEC status lines · spec file headers · verified — observed
  • Conformance vectors ship with the manifest specification · test-vector file present in repository · read — file exists; not executed by me this session
  • FINRA published observations addressing AI agents in January 2026 · FINRA publication · read — characterised as observations, never as a rule
  • Roughly three weeks of specification writing preceded implementation · my own record · read — estimate, not instrumented

What would falsify the central claim: if two independent implementations built against the frozen pack diverged on a fact the pack covers, the freeze did not do its job. The conformance harness is the instrument that would show it — and it reports a language absent from the run as absent rather than as a pass, so the check cannot be passed by not running it.