# Decision Record — Sharpen "steward" into "issue SSH, route the rest"

**Date:** 2026-06-18
**Author:** codex
**Status:** Accepted. Feeds WARDEN-WP-0010 T1.
**Supersedes:** the earlier "operations security coach" draft (rejected — see below).

---

## 1. The decision

Keep ops-warden's mission exactly as it is in production and sharpen only the
wording: **ops-warden issues short-lived SSH certificates and routes every other
credential need to the subsystem that owns it.** Add a small machine-readable
routing catalog and a `warden route` lookup CLI so agents stop re-deriving routing
from wiki prose.

This is **wording plus a thin lookup surface**, not a new security lane. SSH
issuance stays the only thing ops-warden executes.

| | Before | After |
| --- | --- | --- |
| Framing | "operational access steward / desk" | "issues SSH certs; routes the rest to its owner" |
| Non-SSH creds | document paths in wiki | same wiki + structured catalog pointing at it |
| Lookup | grep the wiki | `warden route find/show` |
| Foreign APIs | not owned | explicitly not proxied or restated |

Maturity moves **Availability A3 → A4** (structured lookup for agents). Completeness
and Reliability for the SSH lane are unchanged — nothing here ships new signing code.

---

## 2. Why not "coach"

An earlier draft framed this as an "operations security coach." Rejected:

- **Overpromises.** What is built is a routing directory — lookup, not pedagogy.
  "Coach" implies teaching and an ongoing relationship the CLI does not deliver,
  which feeds the "agent stops at the lookup and never learns the subsystem"
  failure mode.
- **Generic / collision-prone** across other custodian domains.
- **No new metaphor needed.** "Steward who issues SSH and routes the rest" is
  already accurate and harder to misread as a wrapping service.

Command verb is `warden route` (concrete), not `warden coach`.

---

## 3. The double-source-of-truth trap, and how we avoid it

A routing catalog risks becoming a hand-maintained fork of net-kingdom's
responsibility map. A stale-but-authoritative-looking catalog is **worse** than
wiki prose, because an agent trusts structured output and will not second-guess it.

**Rule (binding on WP-0010 T3 / enforced by WP-0011 T5):** the catalog is a
*pointer layer*. For any subsystem ops-warden does not own, an entry carries only
identifiers + `owner_repo` + `wiki_ref` (in-repo authoritative section) +
`canon_ref` (upstream net-kingdom doc) — **no restated procedure**. Procedure is
authored in exactly one place per need: the wiki section it points to. ops-warden
authors `steps` for exactly one lane — SSH issuance — because it owns it.

This is enforced structurally, not by process: a CI test fails any non-SSH entry
that carries a `steps` block, and checks every `wiki_ref` anchor resolves. We do
not rely on a quarterly human review to catch drift.

---

## 4. Other tightenings applied

- **Dropped `warden coach check`.** Highest scope-creep risk, thin value (`warden
  status` already covers SSH local preconditions). SSH precondition hints fold into
  `warden route show` instead.
- **No agent-visible stubs for unshipped paths.** Scenarios whose owning repo has
  not shipped a real path stay `status: draft` and are hidden from default
  lookup (WP-0012 anti-stale rule).

---

## 5. Guardrails (non-negotiable)

1. **One execution lane** — only SSH cert issuance in ops-warden code.
2. **No secret material** in catalog, CLI output, logs, or history.
3. **No foreign API wrappers** — beyond the existing opt-in SSH pre-sign gate.
4. **No restated procedure** for subsystems ops-warden does not own — pointers only.
5. **Canon supremacy** — wiki tracks net-kingdom; ops-warden never overrides it.

---

## 6. Failing signals (watch for these)

- Feature requests cluster on `warden secret` / `warden bao` / `warden login`.
- A catalog entry grows a `steps` block for a non-SSH subsystem.
- `wiki_ref` anchors rot without CI failure.
- Operators bypass OpenBao "because warden is easier" — but warden cannot help.

---

## 7. References

- `INTENT.md`, `SCOPE.md` — pre-update wording
- `workplans/WARDEN-WP-0010-access-routing-charter.md`
- `workplans/WARDEN-WP-0011-routing-guide-cli.md`
- `workplans/WARDEN-WP-0012-routing-scenario-playbooks.md`
- `history/2026-06-18-post-wp0008-intent-scope-reassessment.md` — prior gap analysis
- `wiki/CredentialRouting.md`, `wiki/NetKingdomSecurityMap.md`