Track B Phase 3 (CR-2) — configured-vs-effective scope enforcement (cohort divergence)

2026-06-21

scope-enforcementgovernance-dashboardfeature-flags

LOCKSTEP TRACEABILITY MATRIX --- api_endpoints: ["GET /auth/governance/scope-enforcement"] sdk_methods_updated: ["none — dashboard JWT surface"] mcp_tools_updated: ["none"] ---

What We Built

GET /auth/governance/scope-enforcement returns, per scope source (api_key, br_scope, delegation), the configured mode, the effective mode, whether the tenant is in the rollout cohort, and a divergent flag. The effective-mode badge now surfaces the dangerous case in amber: _"effective: OFF for api_key — not in rollout cohort."_

This closes R6 — the single most dangerous lie a governance dashboard can tell. The scope-enforcement dial is gated behind a per-tenant rollout cohort (a feature flag): an operator can set api_key: enforce, but if the tenant isn't in the enforce_apikey_models cohort, resolveScopeMode returns off and nothing is actually enforced. Phase 1 honestly refused to claim "effective" for exactly this reason; CR-2 now computes and shows the truth.

Why It Matters

"Configured to enforce" and "actually enforcing" are different facts, and the gap between them is invisible in the dial alone. An operator who sets enforce, sees the dial say enforce, and assumes they're protected — while the cohort flag silently keeps it off — has a false sense of security that the evidence plane exists to destroy. CR-2 makes the divergence loud.

How It Works

The route calls the same resolveScopeMode(source, tenantId) the request path uses (cohort flag → operator dial → off fallback) for the _effective_ value, reads security.scopeEnforcement[source] for the _configured_ value, and checks the rollout flag directly for in_cohort. divergent = configured !== "off" && effective === "off". The badge fetches it after the kill-switch check (kill-switch HALT takes precedence) and renders any divergent sources.

The Numbers

1 new JWT route, reusing the production resolveScopeMode. 389 dashboard tests + the backend suite pass; pnpm check green.

Competitive Edge

Showing "you configured enforce, but it's effectively off because you're not in the rollout cohort" is a degree of operational honesty that only a platform treating governance as evidence — not marketing — will build. It's the opposite of a vanity dashboard.

Lockstep Checklist

[x] API Routes: GET /auth/governance/scope-enforcement.
[x] TS/Python SDK / MCP: none — dashboard JWT surface.
[x] Generated contract: docs/openapi.yaml + static-assets regenerated.

Track B complete

With CR-2 shipped, every Track B CR is live — Phases 1–4 and all of Phase 3 (CR-1 chain badge + ledger, CR-2 cohort divergence, CR-3 would-deny, CR-4 dry scope composition, CR-5 kill-switch effective-state, CR-7 governance events + live feed). The one explicitly-deferred item is the composer's principal-side source auto-resolution (a documented follow-up on top of the shipped CR-4 dry composition), not a CR.