Chapter 26: Governance Machines Enforce¶
Policy as a File, Enforcement as a Gate¶
A path with a way back still depends on people remembering the rules; this chapter moves the rules into gates that cannot merge.
1. Policy That Cannot Merge¶
The three structures are governed by rules; a portfolio is governed by machines. Branch protection, required checks, review rules, merge strategy — each is a decision, and each is a setting somewhere. When those settings live in a console, they are remembered; when they live in a file, they are reconciled.
Reconciled is the operative word: the file is applied to the platform, and a drift check fails when the platform disagrees. A policy that is applied once and never checked is a policy that decays with every console click.
🎯 What You'll Learn¶
- Why policy must be declared and reconciled, not remembered
- The conformance check that makes codified standards real
- Agent identity, and why a shared credential ends accountability
Declared, Applied, Checked¶
| Step | What it does | If it is missing |
|---|---|---|
| declare | the policy is a file, reviewed | the rule lives in someone's memory |
| apply | a command reconciles the platform to it | the file and the platform diverge |
| check | drift fails a gate | the divergence is discovered by an incident |
flowchart LR
F["policy file"] --> A["apply — reconcile"]
A --> P["platform settings"]
P --> D{"drift check"}
D -->|"matches"| M["a merge that obeys the rule"]
D -->|"drifts"| X["fails before the incident"]
What this shows: the file is only policy if something applies it and something checks it.
✅ What to Check¶
- Is any governance setting applied only through a console? That is the drift waiting.
- Does a policy change go through review like code?
2. Codified Standards Across Repositories¶
Ten repositories with ten lint configs are ten dialects. The standard is one canonical configuration — lint, format, architecture tests — with thin per-repository adapters that declare only what genuinely differs.
| Layer | What it holds | Where it lives |
|---|---|---|
| canonical | the rules shared by every repository | one repository, versioned |
| adapter | the declared exception for this repository | in the repository, with a reason |
| conformance | the check that the adapter matches the canonical | the gate |
Conformance is per repository and reported, never assumed absent. A repository with no conformance check is not compliant — it is unknown, which is worse, because unknown reads as fine.
✅ What to Check¶
- How many lint dialects do you maintain? Each one is a standard.
- Does every repository report conformance, including the ones that pass?
3. Access Tiers and Agent Identity¶
Access tiers come from the manifest — the same file that names the owner and lifecycle names the role. Onboarding and offboarding become executable steps rather than a checklist someone remembers.
Agent identity is the part teams get wrong. An agent that acts with a human's credential destroys attribution: the audit shows a person, the action was a machine, and the review cannot tell whose intent it was.
| Rule | Why |
|---|---|
| one identity per agent | an audit that cannot attribute an action is not an audit |
| least privilege, per agent | the blast radius of a confused agent is its permissions |
| audited, with the decision | who acted, under whose approval |
| never a human's credential | attribution, and the end of the borrowed-author problem |
Runners and trust. Persistent runners execute trusted code only; fork and public pull-request code never touches them. This is not a preference about hardware — it is the boundary that keeps a stranger's code off a machine that holds credentials.
✅ What to Check¶
- Does every agent have its own identity, or does it borrow one?
- Can a fork pull request reach a persistent runner? That is the boundary.
4. The AI Delta¶
An agent inherits whatever the repository permits, silently and at once: policy drift is not a slow erosion when the actor is a machine.
A shared credential ends attribution — so an agent acting as a human cannot be held to account. And an audit that cannot attribute an action is not an audit; it is a list.
💰 Cost Check: a policy in a console costs the drift nobody sees until an incident. A shared agent credential costs the audit that cannot name the actor. A conformance check nobody runs costs a dialect nobody chose. Reconciling policy costs one command and one check per repository.
The Delegation Line¶
The agent applies policy from the manifest and reports conformance. The human approves the policy change and the agent's identity. The system refuses a merge that violates policy, and refuses an agent without its own identity.
5. Build the Delivery¶
Deliverables¶
| Artefact | Shape | Where it lives |
|---|---|---|
| policy manifests | branch rules, required checks, review rules, merge strategy | policy/*.yaml |
| conformance check | canonical vs adapter, per repository | the gate |
| access tiers | roles from the manifest | the manifest + the platform |
| agent identities | one per agent, least privilege, audited | the platform's identity store |
| runner trust statement | what may run where | the policy files |
Decisions¶
| Choice | Default | What changes if you choose otherwise |
|---|---|---|
| reconcile or drift-check | reconcile, and fail on drift | a platform that slowly disagrees with its file |
| one canonical config | yes, with declared exemptions | ten dialects, ten standards |
| agent credentials | one per agent | an audit that cannot attribute |
| runner access | trusted code only | a stranger's code on a credentialed machine |
✅ Gates¶
- A repository that violates policy cannot merge.
- A fork pull request cannot reach a persistent runner.
- A conformance failure names the deviation, per repository.
Runbook¶
- Write the policy manifests. Checkpoint: every setting is a file, not a console click.
- Build the reconcile and the drift check. Checkpoint: a planted drift fails.
- Wire conformance per repository. Checkpoint: every repository reports, including the passing ones.
- Issue agent identities. Checkpoint: no agent uses a human credential.
- Prove one violation is refused. Checkpoint: the refusal names the rule and the fix.
🎯 Proof¶
- A refused merge on a real violation.
- A drift report that predates an incident.
- An agent action attributable to that agent.
6. 🔑 Chapter Summary¶
Policy is a file, applied and checked; a violation cannot merge.
- Declare, apply, check — a policy that is not reconciled is a policy that decays.
- One canonical configuration, thin adapters with declared reasons, conformance reported per repository.
- Access tiers come from the manifest; onboarding and offboarding become commands.
- Agent identity is per agent, least privilege, audited — a shared credential ends accountability.
- Runners execute trusted code only; the boundary is the point, not the hardware.