Gate your Backstage scorecards on the CAI

Wire the verdict endpoint into Soundcheck's HTTP fact collector, so your tracks can check how the code itself measures, next to the facts your portal already collects. Assert and developer portals ·

Who this is for: the platform team running Backstage with Soundcheck, Cortex or OpsLevel, who wants a measurement of the code itself among the facts its tech-health tracks check. Your scorecards already grade services on facts such as whether a service has an owner, whether its pipeline passes and whether someone is on call. This guide adds the Assert score and grades as facts, measured by published rules that are the same for every team.

The shape matters more than the tool: anything that can poll an HTTP endpoint and evaluate a JSON field, whether a portal fact collector, a CI dashboard or 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 and no prose to parse past, just 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, with key, label, score and band.
• dimensions: only when you ask, by adding ?include=dimensions, giving 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 repeatable keeps your certification honest.

In Assert, 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, because it is shown once. Keys are per-repository, read-scoped, and revocable from the same page, so give each external system its own key and revoking one never touches another. Keys for the MCP fix loop are minted separately under Agents, and the two doors keep separate lists over one revocation store, so your portal's key never masquerades as an agent's.

Send it as an Authorization: Bearer token. One key reads one repository, so 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, such as cai, a lens score or a dimension, as facts. The exact collector and check syntax is defined in Spotify's Soundcheck documentation, and Cortex and OpsLevel follow the same pattern through their HTTP integrations.

• A floor on the headline. cai ≥ 70 rules out a Critical lens, because the weakest lens carries the most weight in the headline, but it does not mean every lens is Strong. Decomposable rather than opaque, which is why the next two exist.
• A floor on one lens. securityCompliance ≥ 75 for services handling customer data, or 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), for when one practice is the campaign: hold the specific dimension rather than 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, so gate on the numbers rather than on your own arithmetic over them.

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