ops-warden/docs/adr

ops-warden architecture decision records

This directory holds the rules ops-warden owns — the decisions this repo made, is bound by, and is responsible for changing.

Why these exist as ADRs rather than wiki prose

Until 2026-08-18 every rule in this list lived in wiki prose, a workplan, or a comment at the top of registry/routing/catalog.yaml. All of them were being followed. None of them was addressable: a reader outside ops-warden could not cite one, could not tell whether it was current, and could not tell whether it was ours to change or someone else's that we merely obey.

That distinction is the point of this directory. It matters in both directions:

• A rule we own, mistaken for inherited canon, never gets fixed. We wait for an owner who does not exist.
• Inherited canon, mistaken for ours, gets quietly bent. We change something we had no authority over, and the drift is invisible until it breaks a repo that trusted the canonical version.

Owned versus inherited

Every ADR here carries owner: in its frontmatter. It is the load-bearing field.

owner:	Meaning	How it changes
ops-warden	Ours. We decided it, we are bound by it, and we may change it	A new ADR that supersedes this one. Never an edit-in-place that rewrites a decision
anything else	Inherited. We follow it; we do not own it	Through that owner's process. We may dispute it — we may not amend it

Everything currently in this directory is owner: ops-warden. Rules we follow but do not own — NetKingdom canon, the IAM profile, the credential-management standard — are not copied here. They are cited. Copying inherited canon into our own ADR directory would recreate exactly the second-source-of-truth failure that ADR-0001 exists to prevent.

Superseding one of these

A decision here changed the behaviour of other repos, so retracting it silently is not available. Write a new ADR, set the old one's status: superseded and successor:, and leave it in place. Superseded is a lifecycle state; deletion is not. policy-nexus publishes the history, and a reader asking "what did this say when we made that decision" must be able to find out.

Relationship to .claude/rules/

.claude/rules/*.md are agent-facing operational instructions. They tell an agent what to do in a session. They are derived from these ADRs and should cite them rather than restate the reasoning. If the two disagree, the ADR is right and the rule file is a defect.

Publication

These are publishable through policy-nexus at policy.coulomb.social, which requires title, status and owner on every document and renders Owner as a column in its index. The ownership knowledge therefore survives publication rather than being a local convention that evaporates at the repo boundary.

policy-nexus publishes; it never writes back. The file in this directory is the source of truth. If the site and this directory disagree, this directory is right and the publication is a defect.

ADR	Rule	Binds
ADR-0001	The routing catalog is a pointer layer, never a second copy of an owner's procedure	ops-warden, and every repo contributing a catalog entry
ADR-0002	ops-warden is a transparent conduit, never a secret broker	ops-warden
ADR-0003	Cover gaps, but never silently own them	ops-warden
ADR-0004	High-risk lanes refuse raw value streaming to agent sessions	ops-warden, and any agent runtime calling warden access
ADR-0005	Implement one lane narrowly, route everything else	ops-warden
ADR-0006	Enforcement is zone-scoped, never a global flag (superseded by ADR-0009)	ops-warden
ADR-0007	Build-stage permissiveness stops at credential disclosure	ops-warden
ADR-0008	A lane's risk grade covers every field its path discloses	ops-warden
ADR-0009	Adopt security-zones v0.1; compile explicit membership and select PEP failure mode per zone	ops-warden