Chapter 22: The Control Plane as a Product¶
Validators, Audits, and the Golden Path¶
Once the facts live in files, something has to serve them: this chapter turns the control plane into a product whose second user is a machine.
1. A Platform Has Users¶
The three structures need a place to declare their state. That place is the control plane: one manifest, its registries, and the machinery that keeps them true. It becomes a product the moment it has users — and those users are humans and agents, with different tolerances.
A human tolerates a README and a console. An agent tolerates neither: it needs everything machine-readable, idempotent, and evidence-producing, or it will do something else.
🎯 What You'll Learn¶
- The difference between a validator and an audit, and why conflating them lies
- What a service catalog must be generated from
- The golden path as the platform's only reliable output
Validators and Audits¶
These are two different instruments, and using one where the other belongs is how a platform lies.
| Validator | Audit | |
|---|---|---|
| reads | the declared state | the live state |
| runs | in the gate, on every change | on demand, on a schedule |
| answers | is the declaration well-formed? | does the world match the declaration? |
| fails | the change | the drift |
| lies when | it is mistaken for an audit | it is mistaken for a validator |
A validator that passes tells you the file is coherent. It tells you nothing about production. An audit that passes today says nothing about the change you are about to merge.
✅ What to Check¶
- Is any "green" in your platform a validator being read as an audit?
- Does the audit run on a schedule, or only when someone remembers?
2. The Catalog Is Generated¶
A service catalog has five facts per service: owner, lifecycle, SLO, signal, runbook. Five facts across twenty services is a hundred chances to drift — and the catalog is the page everyone reads.
So it is generated from the manifest, never maintained beside it.
| Fact | The source |
|---|---|
| owner | the manifest |
| lifecycle | the manifest |
| SLO | the signal definitions |
| signal | the evidence layer |
| runbook | the repository's path |
A hand-maintained catalog is a second source of truth with a nice UI — which makes it more dangerous than a stale file, because it is more trusted.
flowchart LR
M["manifest"] --> C["catalog<br/>generated"]
S["signal definitions"] --> C
R["runbook paths"] --> C
C --> H["human reads it"]
C --> A["agent reads it"]
What this shows: the catalog has no independent input — every fact comes from the thing that owns it.
✅ What to Check¶
- Is any catalog row edited by hand? That row will be wrong first.
- If the catalog were deleted, could it be regenerated without a meeting?
3. The Golden Path¶
A golden path is the one command that creates a new service or repository with its gates already wired. Not a checklist, not a template repository, not a wiki page — a command that an agent can run twice without creating two services.
What a scaffold must produce:
- the repository, or the files in an existing one;
- its gates, wired and passing;
- its manifest row, added;
- its contract skeleton, in place;
- the runbook entry, generated.
Idempotent matters because an agent will run it again. A scaffold that creates a second service is a scaffold that teaches the agent to stop using it.
Scope discipline: the platform states what it governs. Mirrors, forks and vendored copies are not the organisation's content; a control plane that tries to govern them fails on the first fork and never recovers.
✅ What to Check¶
- Run the scaffold twice. Does it create one service or two?
- Does the platform state what it does not govern?
4. The AI Delta¶
The platform's second user is a machine: every operation must be idempotent, because an agent will run the scaffold twice, and machine-readable, because a console-only step is invisible to it.
The golden path becomes the agent's only reliable route to a correct change — which makes it the highest-leverage artefact in the book.
💰 Cost Check: a hand-maintained catalog costs a wrong row in every planning conversation; a non-idempotent scaffold costs a duplicate service and a cleanup nobody scheduled; a console-only path costs an agent that cannot follow it and invents its own. The platform's cost is a real day of work, and its return is every question it answers afterwards.
The Delegation Line¶
The agent scaffolds, audits and reports drift. The human approves the scope and the catalog. The system refuses a scaffold outside the manifest, and a second run that would create a second service.
5. Build the Delivery¶
Deliverables¶
| Artefact | Shape | Where it lives |
|---|---|---|
| control-plane skeleton | the manifest, the registries and the two runners | control-plane/ |
| service catalog | generated: owner · lifecycle · SLO · signal · runbook | generated output |
| scaffold command | one command, gates wired, idempotent | control-plane/scaffold |
| scope statement | what the platform governs, and what it does not | the platform's README |
Decisions¶
| Choice | Default | What changes if you choose otherwise |
|---|---|---|
| validators and audits | two commands | one command that conflates well-formed and true |
| the catalog | generated | a hand-maintained second truth |
| the scaffold | files in an existing repository | repositories per service, until the count justifies it |
| scope | stated, and enforced | a platform that governs forks and fails |
✅ Gates¶
- The validator runs on every change; the audit runs on demand, and its drift is reported.
- The catalog is regenerated, never edited.
- The scaffold run twice creates one service, and its gates pass.
Runbook¶
- Land the manifest and registries. Checkpoint: the validator passes on a planted bad row.
- Build the validator. Checkpoint: it fails on a malformed declaration, not on live drift.
- Build the audit against live state. Checkpoint: a planted drift is reported.
- Generate the catalog. Checkpoint: no hand edits survive a regeneration.
- Add one golden path and run it end to end. Checkpoint: run twice, one service.
🎯 Proof¶
- A new service scaffolded by one command that passes its gates.
- A drift report that names the change that caused it.
- A catalog that regenerates without a meeting.
6. 🔑 Chapter Summary¶
The platform is a product whose users include a machine; its only reliable output is the golden path.
- Validators check the declaration, audits check the world — conflating them is how a platform lies.
- The catalog is generated from the manifest and the signals, never maintained beside them.
- The golden path is one idempotent command that wires the gates — the agent's only reliable route.
- Scope is stated: mirrors and forks are not the organisation's content.
- The agent scaffolds and audits; the human owns scope; the system refuses duplicates.