An estate of 240 internal HTTP services was built from a reference architecture over three years, and about 180 of them conform. The reference architecture now has to change - the standard timeout and retry behaviour was wrong and caused two incidents. Design the artefact set and mechanism that lets you revise the reference architecture and know, without asking anyone, which of the 180 have taken the revision.

Requirements that drive the structure

Three, and the third is the one that is usually missing.

• A team must be able to prove conformance in its own pipeline, with no human in the loop.
• The centre must be able to report conformance across the estate without a survey.
• Conformance must be versioned. A service that conformed to v2 is not conformant to v3, and the system has to be able to say so without anybody re-reviewing it. A reference architecture with no version is a one-time event, which is why most of them decay silently.

The design

Four artefacts, each with one job:

1. A generator that produces a working service: pipeline, telemetry, identity, ownership descriptor, and the retry and timeout defaults already set. This is how new services arrive conformant.
2. A conformance pack, published as a versioned library the service depends on - not a document. It contains executable checks: the service rejects a request past its deadline, it retries with jitter and a budget, it emits the required telemetry fields, it surfaces its ownership descriptor. The pack runs in the service's own pipeline against the running service, not against its source.
3. A declared conformance level in the service's descriptor - reference: http-service/v2 - committed alongside the code and read by the catalogue.
4. A drift report built by joining the catalogue's declared versions against the current published version. One query, no survey.

Revising the reference architecture then becomes: publish conformance pack v3, publish the changed defaults in the generator, and the drift report shows 180 services at v2 and 0 at v3 on day one. That number is the migration backlog, and it was free to produce.

The hard part

The checks have to assert behaviour, not structure. A check that the service imports the standard HTTP library is trivially satisfiable and catches nothing - including the defect in the stem, which was a wrong default inside a correctly imported library. A check that fires a request with a 100 ms deadline and asserts the service abandons it is harder to write and is the only kind that would have caught it.

The second hard part is the pack's own compatibility. v3 will fail services that were correct under v2. If the pack is a hard gate, publishing v3 breaks 180 pipelines on a Tuesday. So the pack reports two results: conformance against the version the service declares (a gate) and conformance against the current version (a warning plus a drift entry). Teams fail only on a promise they made.

What it costs

A permanently owned product. Roughly 1 to 2 engineers for the generator plus the pack, plus a deprecation process: how long v2 stays supported, who pays for the 180 migrations, what happens to a service that stays on v1. Reference architectures become cheap to publish and expensive to revise, and this design moves the cost to where it belongs - visible, budgeted, and attached to the revision rather than discovered two years later.

How it fails

• The declared version is set once and never updated, because nothing makes updating it necessary. Fix: the pack writes the version it ran as, so the declaration is an output rather than a claim.
• The pack becomes a style checker. Every rule anybody wants gets added, the pack takes four minutes per build, teams start skipping it. Cap it: a rule earns its place by naming the incident it prevents.
• Nobody funds the migrations, so the drift report shows 180 at v2 forever and becomes a number people stop reading.

When this is the wrong answer

Below roughly 20 or 30 services of the same shape, skip all of it. A generator and a versioned conformance pack cost more to build and maintain than hand-reviewing 20 services, and the drift report answers a question you can answer by reading a list. The mechanism earns its cost when the estate is large enough that "which services have taken the change" is genuinely unknown - and when the reference architecture is expected to be revised at all. A template for a problem that will be solved once needs no version, no pack and no drift report.