generated from coulomb/repo-seed
tegwick
dcfcc4b20a
Drop the "operational access desk" framing (and the rejected "coach" metaphor) for plain language: ops-warden issues short-lived SSH certs and routes every other credential need to its owner. SSH is the only lane it executes. Adds WARDEN-WP-0010/0011/0012 with a pointer-layer routing catalog that points at owner docs rather than restating them, enforced structurally (non-SSH entries carrying a steps block fail CI). Drops the scope-creep-prone `check` command; hides unshipped-path scenarios as draft. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
151 lines
4.5 KiB
Markdown
151 lines
4.5 KiB
Markdown
---
|
|
id: WARDEN-WP-0011
|
|
type: workplan
|
|
title: "Routing Lookup CLI"
|
|
domain: custodian
|
|
repo: ops-warden
|
|
status: ready
|
|
owner: codex
|
|
topic_slug: custodian
|
|
planning_priority: high
|
|
planning_order: 11
|
|
created: "2026-06-18"
|
|
updated: "2026-06-18"
|
|
---
|
|
|
|
# WARDEN-WP-0011 — Routing Lookup CLI
|
|
|
|
**Scope:** A `warden route` command group that reads the pointer catalog and tells
|
|
a worker which subsystem owns a need, what the prerequisites are, and which
|
|
wiki/canon doc to follow **on that system**. ops-warden does not call OpenBao,
|
|
flex-auth, or key-cape on the worker's behalf.
|
|
|
|
**Out of scope:** HTTP API; live probes against any subsystem; secret generation or
|
|
retrieval; a separate health/precondition command (see "Dropped" below); replacing
|
|
subsystem CLIs.
|
|
|
|
**Depends on:** WARDEN-WP-0010 T3 (catalog schema + seed).
|
|
|
|
**Unlocks:** Agents run `warden route show <id> --json` instead of re-deriving
|
|
routing from wiki prose each session.
|
|
|
|
---
|
|
|
|
## Target CLI
|
|
|
|
```text
|
|
warden route list [--json] [--tag <tag>]
|
|
warden route show <id> [--json]
|
|
warden route find <query> [--json] # keyword match against need_keywords
|
|
```
|
|
|
|
`list`/`find` show only `status: active` entries by default (`--all` includes draft).
|
|
|
|
### Behaviour
|
|
|
|
| Command | Does | Does not |
|
|
| --- | --- | --- |
|
|
| `list` / `show` | Return owner, wiki/canon pointers, `warden_executes`, anti-patterns | Return secret material |
|
|
| `find` | Rank scenarios by keyword overlap | Invoke any external API |
|
|
|
|
When `warden_executes: true` (SSH), `show` appends the catalog's authored `steps`
|
|
and the `warden sign` / `cert_command` pattern, plus a local precondition hint
|
|
("actor in inventory? backend configured? run `warden status`"). For all other
|
|
scenarios `show` ends with **"next action on `<owner_repo>` — see `<wiki_ref>`"**
|
|
and never implies warden performed anything.
|
|
|
|
### Dropped: separate `check` command
|
|
|
|
The earlier draft had `warden coach check`. Cut. For SSH, `warden status` already
|
|
covers local preconditions; duplicating it invites scope creep toward probing
|
|
foreign subsystems. SSH precondition hints live inside `show` instead.
|
|
|
|
---
|
|
|
|
## Tasks
|
|
|
|
### T1 — Catalog loader and models
|
|
|
|
```task
|
|
id: WARDEN-WP-0011-T01
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
- [ ] Add `src/warden/routing/` package: `models.py`, `catalog.py`.
|
|
- [ ] Load and validate `registry/routing/catalog.yaml`.
|
|
- [ ] Enforce the no-double-source rule: non-SSH entries with a `steps` block are a
|
|
validation error. Clear errors for missing file, schema violations, dup `id`.
|
|
|
|
### T2 — `warden route list` and `show`
|
|
|
|
```task
|
|
id: WARDEN-WP-0011-T02
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
- [ ] Register `route` Typer sub-app on the main CLI.
|
|
- [ ] `list` — Rich table + `--json` array of summaries; active-only unless `--all`.
|
|
- [ ] `show` — owner, prerequisites, pointers (`wiki_ref`, `canon_ref`),
|
|
`warden_executes`, anti-patterns; SSH entries also append `steps` + cert pattern.
|
|
- [ ] Exit 1 with a `find` hint when `show` id is unknown.
|
|
|
|
### T3 — `warden route find`
|
|
|
|
```task
|
|
id: WARDEN-WP-0011-T03
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
- [ ] Tokenize query; match against `need_keywords`, `title`, `id`.
|
|
- [ ] Rank, show top matches (default 5); `--json` for agents.
|
|
- [ ] Fixtures: "issue core api key", "ssh tunnel", "openrouter key".
|
|
|
|
### T4 — Tests
|
|
|
|
```task
|
|
id: WARDEN-WP-0011-T04
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
- [ ] `tests/test_routing.py` — catalog load, no-double-source validation rejects a
|
|
non-SSH `steps` block, find ranking, show JSON shape, SSH `show` includes cert
|
|
pattern.
|
|
- [ ] No integration test requires a live subsystem.
|
|
|
|
### T5 — Doc consistency + drift guard
|
|
|
|
```task
|
|
id: WARDEN-WP-0011-T05
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
- [ ] CI/test: every `wiki_ref` anchor resolves to an existing in-repo wiki section;
|
|
every entry has a `reviewed` date.
|
|
- [ ] `wiki/AccessRouting.md` — CLI section with agent-oriented examples.
|
|
- [ ] README — `warden route --help` quick reference.
|
|
- [ ] Bump SCOPE availability note A3 → A4 on ship.
|
|
|
|
---
|
|
|
|
## Acceptance
|
|
|
|
- `uv run warden route find "issue core api key"` returns the draft scenario only
|
|
with `--all`, and never a generated key.
|
|
- `uv run warden route show ssh-cert-host-access --json` includes
|
|
`warden_executes: true` and the cert_command pattern.
|
|
- A non-SSH catalog entry carrying a `steps` block fails `test_routing.py`.
|
|
- `uv run pytest tests/test_routing.py` passes with no live-subsystem dependency.
|
|
|
|
---
|
|
|
|
## See also
|
|
|
|
- `WARDEN-WP-0010` — charter and catalog schema
|
|
- `WARDEN-WP-0012` — expanded per-scenario playbooks
|
|
- `history/2026-06-17-intent-scope-assessment.md` — prior `warden guide` proposal (P4)
|