## Architecture

### Our rules are ADRs — `docs/adr/`

The decisions that govern this repo live in `docs/adr/` as addressable records,
not in wiki prose. Read `docs/adr/README.md` first; it explains the one
distinction that matters here.

| ADR | Rule |
| --- | --- |
| `ADR-0001` | The routing catalog is a pointer layer, never a second copy of an owner's procedure |
| `ADR-0002` | ops-warden is a transparent conduit, never a secret broker |
| `ADR-0003` | Cover gaps, but never silently own them |
| `ADR-0004` | High-risk lanes refuse raw value streaming to agent sessions |
| `ADR-0005` | Implement one lane narrowly, route everything else |
| `ADR-0006` | Enforcement is zone-scoped, never a global flag |
| `ADR-0007` | Build-stage permissiveness stops at credential disclosure; every lane carries an explicit `risk` grade |
| `ADR-0008` | A lane's risk grade covers every field its path discloses, not just the field it is named after |
| `ADR-0009` | Adopt security-zones v0.1 as a consumer; membership is compiled, never inferred |
| `ADR-0010` | ops-warden is Staff: it owns access lanes, never access rules; doctrine belongs to gate-house |

### Owned versus inherited — check `owner:` before changing anything

Every ADR carries `owner:` in its frontmatter, and it decides what you are allowed
to do with the rule:

- **`owner: ops-warden`** — ours. We are bound by it *and* we may change it. Changing
  one means writing a superseding ADR, not editing the decision in place.
- **any other owner** — inherited. We follow it; we do not own it. Dispute it through
  that owner's process; never amend it here.

Everything in `docs/adr/` today is `owner: ops-warden`. Rules we merely follow —
NetKingdom canon, the IAM profile, the credential-management standard — are cited,
never copied in. Copying them would recreate the second-source-of-truth failure
`ADR-0001` exists to prevent.

**Naming collision, worth knowing.** `ADR-001` (three digits) in
`workplan-convention.md` and `session-protocol.md` is **the-custodian's** ADR
establishing the workplan convention across the whole estate. It is inherited and
not ours to change. Our records are four-digit — `ADR-0001` … `ADR-0005` — and live
in this repo. When writing, say "the-custodian's ADR-001" if that is what you mean.

### Precedence

If a wiki page, playbook, or `.claude/rules/` file disagrees with an ADR, **the ADR
is right and the other file is a defect** — fix it rather than working around it.
The rule files are agent-facing operational instructions derived from these
decisions; they should cite an ADR rather than restate its reasoning.

### Publication

These ADRs are publishable through `policy-nexus` at `policy.coulomb.social`, which
requires `title`, `status` and `owner`, renders owner in the page header and in the
index, and records source repo, path and revision digest in its manifest. Ownership
survives the repo boundary. `policy-nexus` publishes and never writes back: the file
here is the source of truth.

## Quick Reference

`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference