fix(hosts): source Avg compliance KPI from /fleet/score so it matches /dashboard (#676)

The /dashboard and /hosts 'Avg compliance' tiles showed different numbers
because they used different denominators over the same host_rule_state data:
  - /dashboard (GET /api/v1/fleet/score): passing / (passing + failing)
  - /hosts (kpisFromHosts): passing / total, where total = COUNT(*) including
    skipped + error rows.
Kensa marks many rules not-applicable (skipped) per host, so the /hosts figure
read materially lower. passing/(passing+failing) is the canonical metric (it
also drives the scheduler bands via drift.ComplianceScore).

Source the /hosts headline KPI from the same /api/v1/fleet/score endpoint the
dashboard uses (shared queryKey ['fleet','score'], same round(passing_fraction
*100)) so the two surfaces are literally the same number and cannot drift. The
client-side kpisFromHosts aggregate remains a fallback until the score loads.

Spec frontend-hosts-list v1.8.0: new C-13 + AC-26 + source-inspection test.

Author: remyluslosius

frontend/src/pages/HostsListPage.tsx

@@ -242,7 +242,29 @@ export function HostsListPage() {
     refetchInterval: 60_000,
   });
 
+  // Avg-compliance KPI value: source the SAME fleet score the dashboard KPI
+  // uses (GET /api/v1/fleet/score = passing / (passing + failing), the
+  // canonical compliance metric that also drives the scheduler bands) so the
+  // two surfaces can never diverge. The client-side kpisFromHosts value (which
+  // divides by the all-status rule total) is only a fallback shown until this
+  // resolves. Shared queryKey with the dashboard widget, so it dedupes/caches.
+  // Spec frontend-hosts-list AC-26.
+  const fleetScoreQuery = useQuery({
+    queryKey: ['fleet', 'score'],
+    queryFn: async () => {
+      const { data, error, response } = await api.GET('/api/v1/fleet/score', {});
+      if (error || !response.ok) throw new Error(`HTTP ${response.status}`);
+      return data!;
+    },
+  });
+
   const kpis = kpisFromHosts(hosts);
+  // Authoritative fleet score wins over the client-side aggregate so the
+  // /hosts headline equals the /dashboard headline exactly (same endpoint,
+  // same integer rounding). Spec frontend-hosts-list AC-26.
+  if (fleetScoreQuery.data && fleetScoreQuery.data.total_evaluations > 0) {
+    kpis.avgCompliance.value = Math.round(fleetScoreQuery.data.passing_fraction * 100);
+  }
   if (scanQueueQuery.data) {
     const q = scanQueueQuery.data.queued;
     const r = scanQueueQuery.data.running;

frontend/tests/pages/hosts-list.test.ts

@@ -13,6 +13,7 @@
 //   AC-16  test('frontend-hosts-list/AC-16 — compliance_summary maps to real compliance with null honesty')
 //   AC-17  test('frontend-hosts-list/AC-17 — avg compliance KPI excludes never-scanned hosts')
 //   AC-18  test('frontend-hosts-list/AC-18 — critical issues KPI sums critical_failing with affected-hosts scope')
+//   AC-26  test('frontend-hosts-list/AC-26 — avg compliance KPI sourced from /fleet/score (matches dashboard)')
 
 import { describe, expect, test } from 'vitest';
 import { readFileSync } from 'node:fs';
@@ -125,6 +126,23 @@ test('frontend-hosts-list/AC-13 — per-host Scan buttons are live with idempote
   expect(btnSlice).not.toMatch(/setInterval/);
 });
 
+// @ac AC-26
+// AC-26: the Avg compliance KPI value is sourced from GET /api/v1/fleet/score
+// (the same fleet score, and the same round(passing_fraction*100) expression,
+// the dashboard KPI uses) so /hosts and /dashboard can never show a different
+// fleet-compliance number. The client-side kpisFromHosts aggregate (which
+// divides by the all-status rule total) is only a fallback.
+test('frontend-hosts-list/AC-26 — avg compliance KPI sourced from /fleet/score (matches dashboard)', () => {
+  // Shares the dashboard's query key + endpoint.
+  expect(PAGE_SRC).toContain("queryKey: ['fleet', 'score']");
+  expect(PAGE_SRC).toContain("api.GET('/api/v1/fleet/score'");
+  // The KPI value is overridden with the canonical fleet score, same rounding
+  // as the dashboard widget (Math.round(passing_fraction * 100)).
+  expect(PAGE_SRC).toMatch(/kpis\.avgCompliance\.value\s*=\s*Math\.round\(\s*fleetScoreQuery\.data\.passing_fraction\s*\*\s*100\s*\)/);
+  // Guarded so an empty fleet (no pass/fail evaluations) keeps the fallback.
+  expect(PAGE_SRC).toMatch(/fleetScoreQuery\.data\.total_evaluations\s*>\s*0/);
+});
+
 // @ac AC-14
 test('frontend-hosts-list/AC-14 — scan-queue KPI wired to /fleet/scan-queue', () => {
   expect(PAGE_SRC).toContain("queryKey: ['fleet', 'scan_queue']");

specs/frontend/hosts-list.spec.yaml

@@ -1,7 +1,7 @@
 spec:
   id: frontend-hosts-list
   title: Hosts list — fleet dashboard with search, filter, card/table views
-  version: "1.7.0"
+  version: "1.8.0"
   status: approved
   tier: 2
 
@@ -96,6 +96,18 @@ spec:
       description: 'v1.7.0 — the card/table view is chosen as: URL ?view= (table|cards) when present (so a link or refresh is stable), otherwise the user''s server-persisted default usePreferencesStore.hostsViewDefault (system-user-preferences). Toggling the view MUST both call setHostsViewDefault(v) (persisting the new per-user default) AND set ?view= for the session — so the choice "becomes the default until the user changes it"'
       type: technical
       enforcement: error
+    - id: C-13
+      description: >-
+        v1.8.0 — the headline Avg compliance KPI value MUST be sourced from the
+        same fleet score the dashboard KPI uses (GET /api/v1/fleet/score,
+        passing / (passing + failing) — the canonical compliance metric that
+        also drives the scheduler bands), so the /hosts and /dashboard surfaces
+        cannot show different fleet-compliance numbers. The client-side
+        kpisFromHosts average (which divides by the all-status rule total,
+        including skipped + error) is a fallback shown only until the fleet
+        score resolves, never the authoritative displayed value.
+      type: technical
+      enforcement: error
 
   acceptance_criteria:
     - id: AC-01
@@ -198,3 +210,18 @@ spec:
       description: "v1.7.0 source-inspection: the view resolves to search.view when it is 'table' or 'cards', otherwise usePreferencesStore.hostsViewDefault (not a hardcoded 'cards'). The ViewToggle onChange calls setHostsViewDefault(v) AND updateSearch({view:v}) so the toggle persists the per-user default and updates the URL together."
       priority: high
       references_constraints: [C-12]
+    - id: AC-26
+      description: >-
+        v1.8.0 — the Avg compliance KPI value is taken from GET
+        /api/v1/fleet/score (queryKey ['fleet','score'], shared with the
+        dashboard KPI): when the fleet score has loaded with total_evaluations
+        > 0, kpis.avgCompliance.value is round(passing_fraction * 100) — the
+        same number and rounding the dashboard shows — overriding the
+        client-side kpisFromHosts aggregate so /hosts and /dashboard agree.
+        Source-inspection of HostsListPage: a useQuery with queryKey
+        ['fleet','score'] hits GET /api/v1/fleet/score, and the avg-compliance
+        KPI value is set to round(passing_fraction * 100) from that query
+        (guarded on total_evaluations > 0), the same expression the dashboard
+        widget uses.
+      priority: high
+      references_constraints: [C-13]