feat(projects): a band for what the scan result cannot say about itself

[haksungjang]

W17. A scan report says what is in the code. It cannot say whether the build gate would let it ship, whether a known-exploited finding is past its CISA deadline, whether someone is waiting on an approval, or which way the last few scans moved — those are decisions an organisation made, and a tool that runs once and prints has nowhere to keep them.

The band puts those five signals between the header and the tabs. All of them are reachable from a tab already; the point is that reading them costs no navigation, so the project's standing state is present while you work inside any one tab.

Composition, not measurement

GET /v1/projects/{id}/governance produces no new number. The risk score comes from the Overview tab's aggregation, the verdict from evaluate_gate itself, the KEV buckets and the approval count from the functions the action queue calls. A band that disagreed with the tab three pixels below it would be worse than no band.

Worth naming: this route calls evaluate_gate directly where the dashboard's action queue deliberately does not. The queue needs a verdict for every project at once and five to seven queries each does not scale, so it aggregates the gate's inputs and pays for the duplication with a parity test. Here there is one project, the real evaluator costs nothing, and there is nothing to keep in sync.

What the review found

Access control came back clean — the reviewer traced the order of operations and confirmed nothing is read before assert_team_access, and that removing the guard fails a test. It found the central claim false on one axis.

The score disagreed with the Overview tab. The band assembled it from the release-snapshot helpers, which start at license_findings; the tab starts at scan_components and LEFT JOINs. A component the scan saw but could not attribute a licence to is not absent from the licence distribution — it lands in unknown, which is a scored band. A project with no CVEs and two unlicensed components scored 8.7 on the tab and 0 in the band.

Fixed at the root: the Overview's aggregation is now distributions_for_scan, and both surfaces call it. The regression guard is a fixture where the licence axis decides the score — a security-dominant fixture proves nothing, since max() picks the other axis regardless. Verified by mutation.

The band ignored the snapshot pin. Opening a two-month-old release put every tab on that snapshot while the band described today's HEAD. Two of its tiles have no historical form, so the band is not rendered while a snapshot is pinned.

A gate blocked by EPSS alone read "0 critical · 0 forbidden licences" — every number true, the sentence useless. Only non-zero clauses appear now, and EPSS has one.

Three tests were added for states the first suite could not reach: one succeeded scan cannot prove an anchor, so a two-scan fixture pins that score, gate and KEV all describe the newest while the trend carries both in order; approvals are asserted against a second project's queue; and a 200 body is asserted at all.

Documented rather than changed

Both are deliberate and neither was written down. The trend counts the Overview donut's population including dismissed findings, so it holds its shape when a team triages a gate to pass. And the gate's forbidden-licence count honours the team's licence policy while the score's licence axis uses the category stored at scan time — the Overview tab has the same split; the band shows both at once.

Gates

Backend: 13 governance tests plus the full unit suite green (one known local-only failure documented in the handoff), ruff and mypy clean, OpenAPI contract updated. Frontend: 1571 unit tests green, tsc clean, token-lint holds at 130. Narrow-viewport and axe both pass on the two project-detail screens — five tiles in a row is the shape §3.6-(2) flagged, so the strip is a two-column grid below xl. EN/KO together, ko-style 0 findings, user guide updated in both.

Follow-ups this surfaced

The approvals tile links to the global /approvals, which has no project filter — the number is this project's, the destination is not. can_access_team treats the membership-derived role == "super_admin" as a bypass while team_scope_filter was narrowed to is_superuser alone by an earlier review; that is shared by every project route and wants its own look.