ops-warden-adr-0001 accepted · 1 ops-warden reviewed 2026-08-18generated from canonical source — do not edit

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

Source: ops-warden · docs/adr/ADR-0001-catalog-is-a-pointer-layer.md · 35aff380a33f51a512c1e1b42d52d1dc0d95930f

Review due: 2027-02-18

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 onlyowner_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.