generated from coulomb/repo-seed
Complete WP-0003 T06 pilot validation and sync credential routing docs
Close the dangling MVP pilots task with H1 provider-switch test, pilot validation report, and resolver tenant-override fix. Add credential routing guidance to AGENTS.md and Claude rules.
This commit is contained in:
50
.claude/rules/credential-routing.md
Normal file
50
.claude/rules/credential-routing.md
Normal file
@@ -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=feature-control` 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`
|
||||
52
AGENTS.md
52
AGENTS.md
@@ -122,6 +122,58 @@ This repository started as documentation- and planning-focused but now includes
|
||||
|
||||
No full build/run yet (MVP phase). Extend this section as implementation grows.
|
||||
|
||||
---
|
||||
|
||||
## 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=feature-control` 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
|
||||
|
||||
50
docs/pilots/mvp-pilot-report.md
Normal file
50
docs/pilots/mvp-pilot-report.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# MVP Pilot Validation Report (FEATURE-WP-0003-T06)
|
||||
|
||||
**Date:** 2026-06-19
|
||||
**Pilot:** `docs/pilots/mvp_pilot.py`
|
||||
**Tests:** `tests/test_registry_resolver.py`, `tests/test_sdk_wrapper.py` (incl. UC-H1)
|
||||
|
||||
## Scope
|
||||
|
||||
End-to-end validation of the WP-0003 MVP against the scored UseCaseCatalog MVP selection.
|
||||
|
||||
## Use cases exercised
|
||||
|
||||
| UC | Description | Result |
|
||||
|----|-------------|--------|
|
||||
| UC-G1 | Register with lifecycle | Pass — registry validates owner, temp review_date |
|
||||
| UC-A1/A2 | Adopt with wrapper + local provider | Pass — thin client + LocalProvider, no backend |
|
||||
| UC-C1 | Tenant enable | Pass — `tenant.preview` scoped to `acme` vs `globex` |
|
||||
| UC-D3 | Agent capability | Pass — `agent.extract` evaluated with agent context |
|
||||
| UC-E1 | Compute disable per tenant | Pass — `compute.heavy_ocr` disabled for tenant |
|
||||
| UC-E4 | Emergency kill switch | Pass — kill signal overrides tenant/default at runtime |
|
||||
| UC-G3 | Explain decision | Pass — `client.explain()` returns reason/source/scope |
|
||||
| UC-H1 | Provider switch | Pass — `test_h1_provider_switch_without_business_code_change` |
|
||||
|
||||
## Observations
|
||||
|
||||
- **Adoption effort:** Single-script pilot; a consuming repo can integrate in one small task using the SDK + LocalProvider pattern (aligns with UC-A1 scoring).
|
||||
- **Explainability:** Decisions include `reason`, `source`, `scope` — sufficient for MVP governance (UC-G3).
|
||||
- **Runtime control:** Kill switch and tenant overrides applied without redeploy (local values mutated in-process).
|
||||
- **Compute savings:** Pilot demonstrates disable path; real savings measurement deferred to production adapter work.
|
||||
- **Canon alignment:** Evaluation uses tenant/agent context dimensions consistent with `docs/canon-mapping.md` (EvaluationScope).
|
||||
|
||||
## Fit vs scored catalog
|
||||
|
||||
The MVP UCs selected in WP-0003 (A1, C1, D3, E1, E4, G1, G3, H1) are all demonstrated. Deferred items from the catalog remain appropriate for follow-on work:
|
||||
|
||||
- Full tenant self-service (higher cost/risk)
|
||||
- Experimentation analytics
|
||||
- Complex approval workflows
|
||||
- Production backend adapters (Unleash/Flagsmith/flagd)
|
||||
|
||||
No catalog adjustments required for the MVP boundary.
|
||||
|
||||
## Ready for next workplan
|
||||
|
||||
Pilot and automated tests satisfy T06 acceptance. Recommended follow-ons (per WP-0004 Production Hardening section):
|
||||
|
||||
1. Real OpenFeature provider adapters
|
||||
2. Entitlement signal integration depth
|
||||
3. SDK packaging (PyPI) and multi-language examples
|
||||
4. Adoption validation in a real consuming repository
|
||||
@@ -81,8 +81,9 @@ class Resolver:
|
||||
reason = "entitlement_missing"
|
||||
source = "entitlement_rule"
|
||||
value = definition.safe_fallback
|
||||
elif tenant and self.values.get(f"tenant:{tenant}:{key}") is not None:
|
||||
elif tenant and f"tenant:{tenant}:{key}" in self.values:
|
||||
# tenant override
|
||||
value = self.values[f"tenant:{tenant}:{key}"]
|
||||
state = "enabled" if value else "disabled"
|
||||
reason = "tenant_policy"
|
||||
source = "tenant_rule"
|
||||
|
||||
@@ -69,6 +69,7 @@ def test_resolver_precedence_and_decision():
|
||||
owner="o",
|
||||
default_value=True,
|
||||
safe_fallback=False,
|
||||
expected_lifetime="long_lived",
|
||||
)
|
||||
)
|
||||
reg.register(
|
||||
@@ -78,6 +79,7 @@ def test_resolver_precedence_and_decision():
|
||||
"...",
|
||||
owner="o",
|
||||
default_value=False,
|
||||
expected_lifetime="long_lived",
|
||||
)
|
||||
)
|
||||
|
||||
@@ -87,7 +89,7 @@ def test_resolver_precedence_and_decision():
|
||||
"tenant:acme:tenant.test": True,
|
||||
}
|
||||
)
|
||||
resolver = Resolver(reg, provider.values)
|
||||
resolver = Resolver(reg, provider._values)
|
||||
|
||||
# Kill wins
|
||||
d = resolver.evaluate("kill.test", True, {"tenant_id": "acme"})
|
||||
|
||||
@@ -62,3 +62,16 @@ def test_safe_default_on_missing():
|
||||
|
||||
assert client.get_boolean_value("no.such", False) is False
|
||||
assert client.get_string_value("no.such", "def") == "def"
|
||||
|
||||
|
||||
def test_h1_provider_switch_without_business_code_change():
|
||||
"""UC-H1: swap provider backends without changing evaluation call sites."""
|
||||
client = FeatureControlClient()
|
||||
context = {"tenant_id": "acme", "actor_type": "human"}
|
||||
|
||||
client.set_provider(LocalProvider({"tenant.preview": True}))
|
||||
assert client.get_boolean_value("tenant.preview", False, context) is True
|
||||
|
||||
# Simulate migration to a different backend with the same OpenFeature contract
|
||||
client.set_provider(LocalProvider({"tenant.preview": False}))
|
||||
assert client.get_boolean_value("tenant.preview", True, context) is False
|
||||
|
||||
@@ -8,7 +8,7 @@ status: done
|
||||
owner: codex
|
||||
topic_slug: helix-forge
|
||||
created: "2026-06-14"
|
||||
updated: "2026-06-14"
|
||||
updated: "2026-06-19"
|
||||
state_hub_workstream_id: "d261227d-9f2a-406e-88c3-80428ea33f23"
|
||||
---
|
||||
|
||||
@@ -138,7 +138,7 @@ Satisfies UC-G1, G3, G4. T05 complete.
|
||||
|
||||
```task
|
||||
id: FEATURE-WP-0003-T06
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "78ddfd70-9d47-41c9-926a-8a555d1beb0f"
|
||||
```
|
||||
@@ -151,6 +151,12 @@ Acceptance:
|
||||
- Brief report on fit vs scored catalog; adjust if needed.
|
||||
- Ready for next workplan (full adapter contracts, production backends).
|
||||
|
||||
**Done 2026-06-19:**
|
||||
- Pilot script `docs/pilots/mvp_pilot.py` exercises G1, A1/A2, C1, D3, E1, E4, G3 end-to-end.
|
||||
- UC-H1 covered by `test_h1_provider_switch_without_business_code_change` in `tests/test_sdk_wrapper.py`.
|
||||
- Validation report: `docs/pilots/mvp-pilot-report.md`.
|
||||
- All pytest tests pass. MVP UCs fit scored catalog; no catalog adjustments needed.
|
||||
|
||||
## Non-functional and boundaries
|
||||
|
||||
- Reliability: caching, fallbacks (NFR-1).
|
||||
|
||||
Reference in New Issue
Block a user