---
id: ops-warden-adr-0001
type: adr
title: "ADR-0001 — The routing catalog is a pointer layer, never a second copy"
domain: infotech
repo: ops-warden
status: accepted
version: "1.0"
revision: "1"
owner: ops-warden
binds: "ops-warden; every repo contributing a catalog entry"
created: "2026-06-20"
updated: "2026-08-18"
last_reviewed: "2026-08-18"
review_interval: 6m
enforced_by: tests/test_routing.py
supersedes: ""
successor: ""
---

# ADR-0001 — The routing catalog is a pointer layer, never a second copy

## Status

Accepted. Decided during WARDEN-WP-0010 (access routing charter), enforced in code
since WARDEN-WP-0011. Restated here because it binds repos other than ops-warden
and had, until now, no address they could cite.

## Context

`registry/routing/catalog.yaml` tells a worker which subsystem owns a credential
need and where the authoritative procedure lives. The obvious temptation, every
time someone uses it, is to add the procedure itself: the reader is already here,
the steps are short, and one more copy seems cheaper than a second lookup.

That temptation is the failure mode. A copied procedure is correct on the day it
is written and silently wrong afterwards, because the owner changes theirs without
knowing ours exists. The estate has already paid for this once, between an ADR and
its published page — fixed by generating the page from the markdown rather than
maintaining both.

The catalog is consulted precisely when someone is about to touch a credential.
Being confidently wrong there is worse than being absent.

## Decision

**For any subsystem ops-warden does not own, a catalog entry carries identifiers
and pointers only** — `owner_repo`, `subsystem`, `wiki_ref`, `canon_ref`,
`need_keywords`, and the secret-free handoff metadata `warden access` needs.

**Authored procedure is permitted only where `warden_executes: true`.** A `steps:`
block and a `cert_command:` may exist on the SSH certificate lane and nowhere else,
because that is the one lane ops-warden actually owns. Rotation `steps:` are the
narrow exception and describe what the *owner* does, recorded because rotation
guidance had no other home; they are still pointers in spirit and must not grow
into a runnable substitute for the owner's tooling.

**No secret material in this file, ever.**

This is enforced, not merely documented. `tests/test_routing.py` fails any non-SSH
entry carrying a `steps` block, and checks that every `wiki_ref` anchor resolves to
a real section. A rule that is only written down is a rule that erodes.

## Consequences

**Accepted cost.** Two lookups instead of one. A worker who wants the procedure
follows the pointer. We consider a correct second hop cheaper than a stale first
one.

**Anchors must resolve.** Because the entry is only a pointer, a broken pointer is
a total failure rather than a cosmetic one. Hence the anchor test — which has
already caught a real break (`ADHOC-2026-08-11-T01`, a stale
`rapp-qonto-keycape-client` anchor).

**Other repos are bound by this.** When another repo asks us to add or rename a
lane, we add the pointer and decline to absorb the procedure. That has been
exercised: on 2026-08-11 railiance-platform asked ops-warden to rename an active
lane, and the answer was to cross-reference the id from their CCR rather than have
this repo carry a second identity for the same thing.

**It constrains what this repo may usefully become.** ops-warden cannot grow into
a documentation site for other people's credential procedures, however often that
is asked for. The value of the catalog is that a reader knows it points at truth
rather than at a copy of truth.

## Related

- `registry/routing/catalog.yaml` — the file this governs, header comment
- `wiki/AccessRouting.md` — the issue-vs-route role and boundary
- `ADR-0005` — the narrower charter this follows from