Deep dive — how the whole thing fits

The connective account: seven layers of refusal, why they’re deliberately redundant, the order they argue in when they disagree, and the holes the design admits to.

The overview shows the two halves — the rule books and the enforcement plane — and there is one reference page per box. This page is the join between them. It reads the same system as seven layers, walks one action all the way through, and ends with the gaps the design names out loud rather than hides.

The one lesson the whole design rests on

On 2026-05-23 an agent wrote a secret token to /etc/agent-vault/…, breaking three written policies at once. Every one of them was prose. None of them could stop anything. The conclusion was blunt: a rule that lives only in a document is a suggestion. So every load-bearing rule now ends in something that doesn’t read English and can’t be argued with — the kernel, a Git server, a CI robot, an exit code. The phrase used internally is turn prose into refusal. See HARD RULE 11.

Seven layers, on purpose redundant

The layers don’t trust each other. Each one re-checks from scratch, so if one is bypassed, misconfigured, or simply wrong, the next still catches the action. That redundancy is the point — no single checkpoint is load-bearing on its own.

  LAYER                          ENFORCED BY                       PAGE
  ─────                          ───────────                       ────
  1  one source of truth         AGENT_POLICY.yaml (machine-read)  agent-policy
  2  the gate                    exit 0 = allow / exit 2 = deny    the-gate
  3  the kernel wall             Landlock LSM (one-way, inherited)  landlock
  4  scopes + approvals          signed manifests + operator yes   scope-manifests
  5  the safety nets             post-hoc revert + violations log  post-hoc-sweep
  6  the merge wall              CODEOWNERS + branch rules + CI     codeowners
  7  the evals                   invariant fitness tests           architecture-invariants

1 · One source of truth

A single file, AGENT_POLICY.yaml, is the law in machine-readable form — scopes, protected paths, forbidden commands, what needs approval and for how long, and which code areas need a signed-off task before an agent may edit them. Everything downstream reads this one file, so a rule changes once and every checkpoint changes with it. Some protected paths carry required_scope: null — not “ask permission,” but “no permission can ever unlock this.” The file validates itself on load: every permission a rule names must exist, or the whole thing refuses to load.

2 · The gate

The gate is the bouncer every action passes before it runs. It answers one question — allow or deny — with an exit code: 0 allow, 2 deny. Not 1, because Claude Code treats exit 1 as “the hook errored, carry on,” which would wave everyone through; that scar dates to 2026-05-24. It is fail-closed where it counts (can’t load the law → deny everything) and denies anything it doesn’t recognise. Same program for every agent, so hardening it once covers them all.

3 · The kernel wall

Landlock is the layer you can’t argue with, because it’s in the Linux kernel, not the app. The process tells the kernel “I may only ever write inside these folders,” then makes a one-way switch that permanently drops the ability to write anywhere else. After that, even if the agent’s own code is tricked, even if it spawns other programs, the kernel refuses. Two honest limits, written down: it is write-only (it does not confine reads or network), and the Codex sandbox holds a documented wide-access exception.

4 · Scopes and approvals

By default an agent can do almost nothing. Permission arrives as a scope manifest — a signed, time-boxed record naming the task, the exact folder, the paths it may touch, and an expiry. It is readable by the agent but not writable, so an agent cannot widen its own grant. When something needs a human yes, the approval queue posts a request to the dashboard and waits, polling until a person approves, denies, or the request times out (treated as no). This is the layer a human actually stands in.

5 · The safety nets

Behind the gate sit two nets. The post-hoc sweep snapshots before, compares after, and undoes changes the agent shouldn’t have made — and it deliberately does not hide Git-ignored files, because a leaked .env is exactly what Git ignores and exactly what you most want caught. The audit log appends every block, revert, and approval to violations.jsonl — the flight recorder.

6 · The merge wall

Everything above guards the live machine. This layer guards the code that defines the rules, so an agent can’t quietly rewrite its own constitution and merge it. CODEOWNERS makes the sensitive files require the human’s review; branch protection (set on GitHub’s side) blocks anything that hasn’t passed the checks; and a CI workflow runs a battery of robots on every pull request — policy-consistency, “you didn’t delete an invariant,” “you didn’t secretly edit the security workflow,” a size cap, and the invariant fitness tests below.

7 · The evals

The architecture invariants are the properties that must always hold (INV-001…026). The eval machinery reads each invariant’s enforcement block and turns it into a real pass/fail CI test, via four simple scanner kinds (forbidden pattern, directory, compose service, env var). Two guardrail tests watch the watchers — “the file still parses” and “at least one invariant is still enforced” — so the suite can’t rot into an empty shell that passes by doing nothing.

The order they argue in

When two rules collide, the invariants are ranked, so the winner is never a judgement call. Highest authority first:

  secret safety · host boundaries · data integrity   ← beats everything
        ▲
        │   operator hard rules
        │   live-system correctness
        │   not breaking the user's work
        │   engineering standards
        ▼
  mere convenience                                    ← loses to everything

Secrets and host integrity sit at the top and beat every other consideration; convenience sits at the bottom and yields to all of them. That ordering is what lets a checkpoint refuse a “helpful” shortcut without it being a matter of taste.

One action, all the way through

Put it together for a single move an agent tries to make:

  agent tries to write a file / run a command
        │
        ▼  [2] the gate checks it against [1] the policy
        │       and the agent's [4] time-boxed scope
        │
        ├─ needs a human?  ─▶ [4] wait at the approval queue ─▶ yes / no
        │
        ▼  if it slips through and writes where it shouldn't…
        │
        ├─ [3] the kernel physically refuses the write, OR
        ├─ [5] the post-hoc sweep undoes it after the run,
        └─ and either way [5] the audit log records it.

  meanwhile, any attempt to weaken the rules themselves
  must pass [6] CODEOWNERS + branch protection + CI,
  and every machine-checkable rule is continuously [7] eval'd.

The honest gaps

A system worth trusting writes down what it does not cover. This one does, in the open:

• INV-026 (no AI attribution) has no automated check. It’s honoured because it’s written as a hard rule, not because a robot blocks it — a deliberately documented hole.
• Landlock is write-only. It stops bad writes; it does not confine reads or network access.
• The Codex sandbox holds a wide-access exception, with its residual risk (reads and network unconfined) formally accepted rather than papered over.
• Branch protection lives on GitHub, not in the repo, so it isn’t self-evident from the code alone — and it’s part of what a past rebrand knocked out and is being restored.

Why naming the gaps matters

The willingness to list its own holes is the strongest signal the system is real and not theatre. A checkpoint you’ve forgotten about is more dangerous than one you’ve written down as missing — the first hides; the second is on someone’s list.

See also

• Overview — the two-halves map and the one-policy-many-checkpoints idea.
• The gate — the exact write-time decision path, line by line.
• Architecture invariants — how a sentence becomes a CI test.
• Hard rules — the 15 non-negotiables behind the layers.