Add credential routing instructions and WP-0003 workplan

Inline ops-warden credential routing guidance in AGENTS.md and mirror it for Claude Code under .claude/rules/. Add IDENTITY-WP-0003 to backfill the research corpus and refine the conceptual model against scenario tests.
2026-06-19 20:44:05 +02:00
parent c66bebc9c3
commit ca0c968387
3 changed files with 205 additions and 0 deletions
--- a/.claude/rules/credential-routing.md
+++ b/.claude/rules/credential-routing.md
@@ -0,0 +1,50 @@
+# Credential and access routing
+
+**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
+for inference. Run this check **before** requesting secrets, API keys, SSH access,
+login tokens, or database passwords — in any repo, not only `ops-warden`.
+
+ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
+other credential need belongs to another subsystem. **Do not** message
+`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
+
+### Lookup (do this first)
+
+```bash
+warden route find "<describe your need>" --json
+warden route show <catalog-id> --json
+```
+
+Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).
+
+| Agent runtime | How to orient |
+| --- | --- |
+| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=identity-canon` is for coordination, not secret vending |
+| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
+| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
+
+### Quick routing table
+
+| I need… | Owner | ops-warden executes? |
+| --- | --- | --- |
+| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
+| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
+| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
+| Authorization decision | flex-auth | No — route only |
+| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
+| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
+
+### Anti-patterns (do not do these)
+
+- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
+- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
+- Pasting secrets into Git, State Hub, workplans, logs, or chat
+
+### Other capabilities (reuse-surface)
+
+Non-credential capabilities are usually discovered through **reuse-surface** federation
+(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
+every repo's agent instructions because it is high-frequency, high-risk, and easy to
+get wrong.
+
+**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,6 +101,58 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \

 ---

+## Credential and access routing
+
+**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
+for inference. Run this check **before** requesting secrets, API keys, SSH access,
+login tokens, or database passwords — in any repo, not only `ops-warden`.
+
+ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
+other credential need belongs to another subsystem. **Do not** message
+`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
+
+### Lookup (do this first)
+
+```bash
+warden route find "<describe your need>" --json
+warden route show <catalog-id> --json
+```
+
+Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).
+
+| Agent runtime | How to orient |
+| --- | --- |
+| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=identity-canon` is for coordination, not secret vending |
+| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
+| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
+
+### Quick routing table
+
+| I need… | Owner | ops-warden executes? |
+| --- | --- | --- |
+| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
+| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
+| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
+| Authorization decision | flex-auth | No — route only |
+| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
+| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
+
+### Anti-patterns (do not do these)
+
+- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
+- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
+- Pasting secrets into Git, State Hub, workplans, logs, or chat
+
+### Other capabilities (reuse-surface)
+
+Non-credential capabilities are usually discovered through **reuse-surface** federation
+(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
+every repo's agent instructions because it is high-frequency, high-risk, and easy to
+get wrong.
+
+**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
+---
+
 ## Workplan Convention (ADR-001)

 Work items originate as files in this repo — not in the hub. The hub is a
--- a/workplans/IDENTITY-WP-0003-corpus-backfill-model-refinement.md
+++ b/workplans/IDENTITY-WP-0003-corpus-backfill-model-refinement.md
@@ -0,0 +1,103 @@
+---
+id: IDENTITY-WP-0003
+type: workplan
+title: "Research corpus backfill and model refinement"
+domain: canon
+repo: identity-canon
+status: ready
+owner: codex
+topic_slug: canon
+created: "2026-06-19"
+updated: "2026-06-19"
+---
+
+# Research corpus backfill and model refinement
+
+This workplan follows up on `ResearchProposal.md` Immediate Next Steps 4 and
+10. The seeded source notes under `research/` still contain `TODO` placeholders;
+the terminology, canon, model, and scenario artifacts from
+`IDENTITY-WP-0002` are candidate hypotheses until the corpus is backfilled.
+
+Priority order follows `OpenQuestions.md` corpus guidance: start with record and
+subject semantics (provisioning and federation), then authorization
+projections, then social graph, verifiable claims, and entity-resolution
+sources.
+
+## Backfill Provisioning And Federation Source Notes
+
+```task
+id: IDENTITY-WP-0003-T01
+status: todo
+priority: high
+```
+
+Backfill the nine source notes in `research/identity-provisioning/` and
+`research/authentication-federation/`. Replace template placeholders with
+source-backed terminology extracts, modeling assumptions, conflicts, candidate
+canonical mappings, and open questions. Use the structure defined in
+`research/CorpusIndex.md`.
+
+## Backfill Authorization And Social Graph Source Notes
+
+```task
+id: IDENTITY-WP-0003-T02
+status: todo
+priority: high
+```
+
+Backfill the eight source notes in `research/authorization-relationships/` and
+`research/social-community-graphs/`. Capture how each source models principals,
+subjects, actors, groups, organizations, tenants, and relationships without
+collapsing them into a single overloaded term.
+
+## Backfill Verifiable Claims And Entity-Resolution Source Notes
+
+```task
+id: IDENTITY-WP-0003-T03
+status: todo
+priority: medium
+```
+
+Backfill the six source notes in `research/verifiable-claims/` and
+`research/entity-resolution-privacy/`. Document synonymity, identifier,
+pseudonymity, and privacy semantics that affect canonical account-linking and
+relationship modeling.
+
+## Refresh Terminology Artifacts From Corpus
+
+```task
+id: IDENTITY-WP-0003-T04
+status: todo
+priority: high
+```
+
+Update `terminology/TerminologyInventory.md` and
+`terminology/TerminologyConflictMap.md` using extracted terminology from the
+backfilled source notes. Keep mappings marked as candidate until conflicts are
+reviewed against `canon/CanonicalGlossary.md`.
+
+## Refine Conceptual Model Against Scenario Tests
+
+```task
+id: IDENTITY-WP-0003-T05
+status: todo
+priority: high
+```
+
+Revise `model/ConceptualModel.md` so each scenario in
+`scenarios/ScenarioTests.md` has an explicit representation path. Record any
+scenario that the current model cannot satisfy without glossary or principle
+changes.
+
+## Reconcile Canon Surfaces And Open Questions
+
+```task
+id: IDENTITY-WP-0003-T06
+status: todo
+priority: medium
+```
+
+Update `canon/DesignPrinciples.md`, `canon/CanonicalGlossary.md`,
+`OpenQuestions.md`, and `DownstreamRecommendations.md` to reflect corpus
+findings. Resolve questions where the source evidence is sufficient; otherwise
+leave them open with citations to the relevant source notes.