From 8528005bdb72c14072311a5d67248ad0f9b79727 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 19 Jun 2026 20:48:28 +0200 Subject: [PATCH] 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. --- .claude/rules/credential-routing.md | 50 ++++++++++++++++++ AGENTS.md | 52 +++++++++++++++++++ docs/pilots/mvp-pilot-report.md | 50 ++++++++++++++++++ src/feature_control_sdk/resolver.py | 3 +- tests/test_registry_resolver.py | 4 +- tests/test_sdk_wrapper.py | 13 +++++ ...EATURE-WP-0003-first-implementation-mvp.md | 10 +++- 7 files changed, 178 insertions(+), 4 deletions(-) create mode 100644 .claude/rules/credential-routing.md create mode 100644 docs/pilots/mvp-pilot-report.md diff --git a/.claude/rules/credential-routing.md b/.claude/rules/credential-routing.md new file mode 100644 index 0000000..fb69cbb --- /dev/null +++ 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 "" --json +warden route show --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` \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index f4457e4..79d5d76 100644 --- a/AGENTS.md +++ b/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 "" --json +warden route show --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 diff --git a/docs/pilots/mvp-pilot-report.md b/docs/pilots/mvp-pilot-report.md new file mode 100644 index 0000000..d504abc --- /dev/null +++ b/docs/pilots/mvp-pilot-report.md @@ -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 \ No newline at end of file diff --git a/src/feature_control_sdk/resolver.py b/src/feature_control_sdk/resolver.py index 73370e2..af4b416 100644 --- a/src/feature_control_sdk/resolver.py +++ b/src/feature_control_sdk/resolver.py @@ -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" diff --git a/tests/test_registry_resolver.py b/tests/test_registry_resolver.py index 9482917..cfba9d6 100644 --- a/tests/test_registry_resolver.py +++ b/tests/test_registry_resolver.py @@ -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"}) diff --git a/tests/test_sdk_wrapper.py b/tests/test_sdk_wrapper.py index cf40b80..ed6d0fd 100644 --- a/tests/test_sdk_wrapper.py +++ b/tests/test_sdk_wrapper.py @@ -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 diff --git a/workplans/FEATURE-WP-0003-first-implementation-mvp.md b/workplans/FEATURE-WP-0003-first-implementation-mvp.md index b0b324b..d692777 100644 --- a/workplans/FEATURE-WP-0003-first-implementation-mvp.md +++ b/workplans/FEATURE-WP-0003-first-implementation-mvp.md @@ -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).