Gate your Backstage scorecards on the CAI

Who this is for: the platform team running Backstage with Soundcheck — or Cortex, or OpsLevel — who wants tech-health tracks to stand on measured code instead of self-declared checks. Your scorecards already grade services on portal facts: does it have an owner, is CI green, is there an on-call rotation. None of those facts read the code. This guide wires in the one that does.

The shape matters more than the tool: anything that can poll an HTTP endpoint and evaluate a JSON field — a portal fact collector, a CI dashboard, a weekly report script — consumes the same endpoint the same way.

Call GET /api/agent/verdict on the app host and you get the repository's current verdict, gate-shaped: no remediation plan, no prose to parse past — the numbers, pinned to their provenance.

• cai and band — the headline 0–100 and its word (Critical / Weak / Adequate / Strong / Exemplary).
• lenses — one row per measured lens: key, label, score, band.
• dimensions — only when you ask (add ?include=dimensions): id, name, score, band and the owning lens for every scored dimension.
• repository, commit, measuredAt — what was measured, exactly when.
• rubricVersion and rubricContentHash — the frozen ruler the numbers were produced under, by name and by published content digest.

Everything this endpoint serves is deterministic by construction. The advisory LLM reads are excluded from the scored rows at the source, so nothing a check can gate on carries a model's opinion — the same firewall that keeps the score reproducible keeps your certification honest.

In Watchdog, open the repository and go to Integrations — under "Portal scorecards read the verdict", the Access keys panel mints the key right where you are wiring it. Create a key and copy the value; it is shown once. Keys are per-repository, read-scoped, and revocable from the same page; give each external system its own key so revoking one never touches another. (Keys for the MCP fix loop are minted separately under Agents — the two doors keep separate lists over one revocation store, so your portal's key never masquerades as an agent's.)

Send it as the X-Watchdog-Agent-Key header (an Authorization: Bearer token also works). One key reads one repository — a scorecard covering fifty services uses fifty keys, which is exactly the blast-radius you want.

Soundcheck's generic HTTP fact collector is the whole integration: point it at the verdict endpoint with the key header, on whatever schedule suits your tracks — the numbers change on the repository's survey cadence, so polling more than daily buys nothing. Extract the fields your checks need (cai, a lens score, a dimension) as facts; the exact collector and check syntax is defined in Spotify's Soundcheck documentation. Cortex and OpsLevel follow the same pattern through their HTTP integrations.

• A floor on the headline — cai ≥ 70: every always-on lens Strong or better, no lens Critical. Decomposable, not opaque — which is why the next two exist.
• A floor on one lens — securityCompliance ≥ 75 for services handling customer data; productionReadiness ≥ 70 before a service enters the on-call rotation.
• No lens Critical — a single Critical-banded lens caps the headline, so this check catches the cause before the aggregate hides it.
• A dimension floor (with ?include=dimensions) — when one practice is the campaign: hold the specific dimension, not the whole lens.

And one check not to write: don't re-implement the roll-up by averaging lens scores in your portal. The published roll-up is weighted, critical-gated and versioned — gate on the numbers, never on your own arithmetic over them.

• Rubric bumps move numbers with unchanged code. Any scoring change ships as a new rubricVersion — record it beside the fact, so a track that dips on a rubric bump reads as "the ruler changed", not "the code got worse".
• rubricContentHash lets you verify the ruler itself: compare it with the digest published for that version on the open standard.
• A repository with no completed survey yet returns an empty verdict — surface it as "not measured", never as zero.
• Watchdog still never gates. Your portal's certification levels are your policy on Watchdog's measurement — the survey itself never blocks a merge, a deploy or a scan.