fix(a11y): include leftover-pair evidence in button names

.github/workflows/tests.yml

@@ -100,3 +100,11 @@ jobs:
       - name: Build Storybook
         working-directory: frontend
         run: pnpm run build-storybook
+
+      - name: Install Chromium for Storybook browser acceptance
+        working-directory: frontend
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Exercise Storybook interactions in Chromium
+        working-directory: frontend
+        run: pnpm run test:storybook:browser

docs/adr/0049-leftover-pair-report-ui.md

@@ -123,10 +123,22 @@ A hidden post never appears as a leftover pair.
 ## Consequences
 
 The authorized report payload carries `leftover_pairs` next to
-`members` and `selected_items`. Screen-reader names are
-`Open leftover closest pair: {title}` and
-`Open leftover farthest pair: {title}` so the control announces the
-next action, not only the distance.
+`members` and `selected_items`.
+
+The button's accessible name begins with the **exact localized label that is
+visibly rendered on that button**: `Closest leftover: {title} · {criterion}` or
+`Farthest leftover: {title} · {criterion}`. Localized next-action text follows
+that visible-label prefix, then only formatter-admitted persisted evidence that
+is actually available and finite. Missing or non-finite values are omitted from
+the accessible name; they are never announced as `R —`, `d NaN`, or another
+placeholder. This keeps the programmatic name aligned with the visible label
+required by WCAG 2.2 SC 2.5.3 while still exposing the same buyer evidence to
+screen-reader users. The accessible name does not derive, clamp, repair, or
+synthesize psychometric values.
+
+The historical `Open leftover closest/farthest pair: …` prefix is not the
+screen-reader contract. It may describe the action conceptually, but it must
+not replace the rendered label at the start of the accessible name.
 
 ## Related
 
@@ -136,3 +148,6 @@ coverage of the leftover map is [ADR 0168](0168-leftover-map-complete-case-cover
 
 [ADR 0003](0003-fast-mlsirm-report-integration.md). The grouping
 comparison strip reuses this leftover store ([ADR 0149](0149-leftover-pairs-on-comparison-strip.md)).
+
+Accessibility naming follows W3C, *Web Content Accessibility Guidelines (WCAG)
+2.2*, Success Criterion 2.5.3, Label in Name.

docs/product-requirements.md

@@ -526,7 +526,7 @@ current boundary until that repository adopts one.
 | `ContextualWisdomLab/keyverse` | `docs/PRD.md` | Production OIDC/JWKS/identity control plane; local demo Keycloak is not Keyverse |
 | `ContextualWisdomLab/RankWeave` | No standalone PRD; `README.md`, `ARCHITECTURE.md` | Store-agnostic ranking/fusion dependency; caller owns channels and authorization |
 | `ContextualWisdomLab/ThreadWeave` | `docs/PRD.md` | Deterministic reference-thread assembly dependency; LineageWeave owns records and persistence |
-| `ContextualWisdomLab/DiskSage` | No standalone PRD; `docs/superpowers/specs/2026-07-10-disksage-design.md` | Prospective storage-policy boundary; no current runtime integration |
+| `ContextualWisdomLab/disksage` | No standalone PRD; `docs/superpowers/specs/2026-07-10-disksage-design.md` | Prospective storage-policy boundary; no current runtime integration |
 | `ContextualWisdomLab/wardnet` | No standalone PRD; `README.md`, `docs/architecture.md` | Prospective gateway/network-policy boundary; no current runtime integration |
 | `ContextualWisdomLab/naruon` | Scoped `docs/topic-intelligence/PRD.md` only | Owns observed calendar/email projections; LineageWeave owns commitments and combined display |
 | `ContextualWisdomLab/LineageWeave` | This PRD, with ADRs normative | Evidence BI/orchestration, lineage, semantic projection, API, and UI owner |

frontend/package.json

@@ -11,7 +11,8 @@
     "test": "vitest run",
     "e2e": "playwright test",
     "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
+    "build-storybook": "storybook build",
+    "test:storybook:browser": "playwright test --config playwright.storybook.config.ts"
   },
   "dependencies": {
     "oidc-client-ts": "^3.5.0",

frontend/playwright.storybook.config.ts

@@ -0,0 +1,28 @@
+import { defineConfig, devices } from "@playwright/test";
+
+/** Browser acceptance for the already-built Storybook artifact. */
+export default defineConfig({
+  testDir: "./storybook-e2e",
+  testMatch: "**/*.pw.ts",
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 1 : 0,
+  workers: 1,
+  reporter: [["list"]],
+  use: {
+    baseURL: "http://127.0.0.1:6006",
+    trace: "retain-on-failure",
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"], hasTouch: true },
+    },
+  ],
+  webServer: {
+    command: "python3 -m http.server 6006 --directory storybook-static",
+    url: "http://127.0.0.1:6006",
+    reuseExistingServer: false,
+    timeout: 120_000,
+  },
+});

frontend/src/App.test.tsx

@@ -4203,9 +4203,9 @@ describe("App, authenticated", () => {
       "Leftover map dropped 0 incomplete criteria",
     );
     const coverageCaption = screen.getByLabelText("Leftover map coverage");
-    const closestPair = screen.getByRole("button", { name: /open leftover closest pair: public post/i });
+    const closestPair = screen.getByRole("button", { name: /^closest leftover: public post · sales-lead /i });
     const farthestPair = screen.getByRole("button", {
-      name: /open leftover farthest pair: specification revision requested/i,
+      name: /^farthest leftover: specification revision requested · negative /i,
     });
     expect(closestPair).toHaveTextContent("Closest leftover: Public post · sales-lead");
     // Leftover-map coordinates are present, so they name the next action
@@ -4223,7 +4223,7 @@ describe("App, authenticated", () => {
     expect(closestPair).toHaveTextContent("R̂ +0.25");
     expect(closestPair).toHaveTextContent("ξ (+0.50, +0.10) ζ (+0.50, −0.02)");
     expect(closestPair).toHaveTextContent("d 0.12");
-    expect(closestPair).toHaveAccessibleName("Open leftover closest pair: Public post · sales-lead");
+    expect(closestPair).toHaveAccessibleName(/^Closest leftover: Public post · sales-lead /);
     expect(farthestPair).toHaveTextContent("Farthest leftover: Specification revision requested · negative");
     expect(farthestPair).toHaveTextContent(
       "Leftover map places this post at ξ (+0.90, +0.80) and the criterion at ζ (−0.70, −0.40) after IRT main effects. Open this post to read negative.",
@@ -4438,7 +4438,7 @@ describe("App, authenticated", () => {
     render(<App showLabPanels />);
 
     await userEvent.click(
-      await screen.findByRole("button", { name: /open leftover closest pair: public post/i }),
+      await screen.findByRole("button", { name: /^closest leftover: public post · sales-lead /i }),
     );
     await waitFor(() => expect(screen.getByText("The full body text.")).toBeInTheDocument());
     expect(await screen.findByRole("heading", { name: "Post quality (IRT)" })).toHaveFocus();
@@ -4454,7 +4454,7 @@ describe("App, authenticated", () => {
     await userEvent.click(screen.getByRole("button", { name: "Close" }));
     await userEvent.click(
       await screen.findByRole("button", {
-        name: /open leftover farthest pair: specification revision requested/i,
+        name: /^farthest leftover: specification revision requested · negative /i,
       }),
     );
     await waitFor(() =>

frontend/src/components/LeftoverPairList.accessibleName.test.tsx

@@ -0,0 +1,246 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import type { LeftoverPair } from "../api";
+import { LeftoverPairList } from "./LeftoverPairList";
+
+const PAIR: LeftoverPair = {
+  pair_kind: "closest",
+  post_id: "post-demo-public",
+  post_title: "Public post",
+  criterion_code: "sales_lead_quality",
+  leftover_distance: 0.12,
+  leftover_residual: 0.4,
+  observed_response: 2.4,
+  expected_response: 2.0,
+  leftover_map_rank: 1,
+};
+
+const ACTION_EVIDENCE_CASES: Array<[string, Partial<LeftoverPair>, string]> = [
+  [
+    "rank-only",
+    { observed_response: null, expected_response: null, leftover_map_rank: 2 },
+    "rank 2",
+  ],
+  ["observed/expected", { leftover_map_rank: null }, "Y 2.40"],
+  ["unexplained", { leftover_map_unexplained: 0.05 }, "U +0.05"],
+  [
+    "reconstruction",
+    { leftover_map_unexplained: 0.05, leftover_map_reconstruction: 0.35 },
+    "R̂ +0.35",
+  ],
+  [
+    "cross share",
+    {
+      leftover_map_unexplained: 0.05,
+      leftover_map_reconstruction: 0.35,
+      leftover_map_cross_share: 0.13,
+    },
+    "0.13",
+  ],
+  [
+    "unexplained share",
+    {
+      leftover_map_unexplained: 0.05,
+      leftover_map_reconstruction: 0.35,
+      leftover_map_cross_share: 0.13,
+      leftover_map_unexplained_share: 0.23,
+    },
+    "0.23",
+  ],
+  [
+    "explained share",
+    {
+      leftover_map_unexplained: 0.05,
+      leftover_map_reconstruction: 0.35,
+      leftover_map_cross_share: 0.13,
+      leftover_map_unexplained_share: 0.23,
+      leftover_map_explained_share: 0.76,
+    },
+    "0.76",
+  ],
+  [
+    "coordinates",
+    {
+      leftover_map_unexplained: 0.05,
+      leftover_map_reconstruction: 0.35,
+      leftover_map_cross_share: 0.13,
+      leftover_map_unexplained_share: 0.23,
+      leftover_map_explained_share: 0.76,
+      leftover_map_person_axis_1: 0.5,
+      leftover_map_person_axis_2: 0.1,
+      leftover_map_item_axis_1: 0.5,
+      leftover_map_item_axis_2: -0.02,
+    },
+    "ξ (+0.50, +0.10)",
+  ],
+];
+
+function criterionLabel(code: string): string {
+  return code === "sales_lead_quality" ? "sales-lead" : code;
+}
+
+function occurrences(value: string, token: string): number {
+  return value.split(token).length - 1;
+}
+
+function accessibleNameFor(overrides: Partial<LeftoverPair> = {}): string {
+  render(
+    <LeftoverPairList
+      pairs={[{ ...PAIR, ...overrides }]}
+      criterionLabel={criterionLabel}
+      onSelectPost={vi.fn()}
+    />,
+  );
+  return (
+    screen
+      .getByRole("button", { name: /^Closest leftover: Public post · sales-lead / })
+      .getAttribute("aria-label") ?? ""
+  );
+}
+
+describe("LeftoverPairList accessible action name", () => {
+  it("starts with the rendered label and carries each finite evidence value once", async () => {
+    const onSelectPost = vi.fn();
+    render(
+      <LeftoverPairList
+        pairs={[PAIR]}
+        criterionLabel={criterionLabel}
+        onSelectPost={onSelectPost}
+      />,
+    );
+
+    const action = screen.getByRole("button", {
+      name: /^Closest leftover: Public post · sales-lead /,
+    });
+    expect(action).toHaveTextContent("Closest leftover: Public post · sales-lead");
+    expect(action).toHaveAccessibleName(/R \+0\.40/);
+    expect(action).toHaveAccessibleName(/Y 2\.40 · E 2\.00/);
+    expect(action).toHaveAccessibleName(/rank 1/);
+    expect(action).toHaveAccessibleName(/d 0\.12/);
+
+    const name = action.getAttribute("aria-label") ?? "";
+    expect(occurrences(name, "rank 1")).toBe(1);
+    expect(occurrences(name, "Y 2.40")).toBe(1);
+    expect(occurrences(name, "E 2.00")).toBe(1);
+    expect(occurrences(name, "R +0.40")).toBe(1);
+    expect(occurrences(name, "d 0.12")).toBe(1);
+
+    await userEvent.click(action);
+    expect(onSelectPost).toHaveBeenCalledWith(PAIR);
+  });
+
+  it("keeps residual guidance while announcing finite residual evidence once", () => {
+    const name = accessibleNameFor({
+      observed_response: null,
+      expected_response: null,
+      leftover_map_rank: null,
+    });
+
+    expect(name).toContain(
+      "Leftover residual R +0.40 after IRT main effects. Open this post to read sales-lead.",
+    );
+    expect(occurrences(name, "R +0.40")).toBe(1);
+    expect(occurrences(name, "d 0.12")).toBe(1);
+  });
+
+  it.each(ACTION_EVIDENCE_CASES)(
+    "announces %s action evidence once",
+    (_label, overrides, token) => {
+      const name = accessibleNameFor(overrides);
+      expect(occurrences(name, token)).toBe(1);
+    },
+  );
+
+  it("keeps every finite persisted pair-evidence badge in the same accessible name", () => {
+    render(
+      <LeftoverPairList
+        pairs={[
+          {
+            ...PAIR,
+            leftover_map_unexplained: 0.05,
+            leftover_map_reconstruction: 0.35,
+            leftover_map_cross_share: 0.12,
+            leftover_map_unexplained_share: 0.02,
+            leftover_map_explained_share: 0.76,
+            leftover_map_person_axis_1: 0.5,
+            leftover_map_person_axis_2: 0.1,
+            leftover_map_item_axis_1: 0.5,
+            leftover_map_item_axis_2: -0.02,
+          },
+        ]}
+        criterionLabel={criterionLabel}
+        onSelectPost={vi.fn()}
+      />,
+    );
+
+    const action = screen.getByRole("button", {
+      name: /^Closest leftover: Public post · sales-lead /,
+    });
+    expect(action).toHaveAccessibleName(/R \+0\.40/);
+    expect(action).toHaveAccessibleName(/Y 2\.40 · E 2\.00/);
+    expect(action).toHaveAccessibleName(/rank 1/);
+    expect(action).toHaveAccessibleName(/U \+0\.05/);
+    expect(action).toHaveAccessibleName(/U²\/R² 0\.02/);
+    expect(action).toHaveAccessibleName(/R̂²\/R² 0\.76/);
+    expect(action).toHaveAccessibleName(/2R̂U\/R² 0\.12/);
+    expect(action).toHaveAccessibleName(/R̂ \+0\.35/);
+    expect(action).toHaveAccessibleName(/ξ \(\+0\.50, \+0\.10\) ζ \(\+0\.50, −0\.02\)/);
+    expect(action).toHaveAccessibleName(/d 0\.12/);
+  });
+
+  it("keeps non-finite residual visual disclosure while omitting it and non-finite distance from the accessible name", () => {
+    render(
+      <LeftoverPairList
+        pairs={[
+          {
+            ...PAIR,
+            leftover_residual: Number.NaN,
+            leftover_distance: Number.NaN,
+          },
+        ]}
+        criterionLabel={criterionLabel}
+        onSelectPost={vi.fn()}
+      />,
+    );
+
+    const action = screen.getByRole("button", {
+      name: /^Closest leftover: Public post · sales-lead /,
+    });
+    expect(action).toHaveAccessibleName(/rank 1/);
+    expect(action).not.toHaveAccessibleName(/R —/);
+    expect(action).not.toHaveAccessibleName(/d NaN/);
+    expect(action).toHaveTextContent("R —");
+    expect(action).not.toHaveTextContent("d NaN");
+  });
+
+  it("falls back to the existing localized open action while preserving the visual non-finite residual marker", () => {
+    render(
+      <LeftoverPairList
+        pairs={[
+          {
+            ...PAIR,
+            leftover_residual: Number.NaN,
+            leftover_distance: Number.NaN,
+            observed_response: null,
+            expected_response: null,
+            leftover_map_rank: null,
+          },
+        ]}
+        criterionLabel={criterionLabel}
+        onSelectPost={vi.fn()}
+      />,
+    );
+
+    const action = screen.getByRole("button", {
+      name: /^Closest leftover: Public post · sales-lead /,
+    });
+    expect(action).toHaveTextContent(
+      "Open this post so the leftover criterion is current in Post quality.",
+    );
+    expect(action).not.toHaveAccessibleName(/R —/);
+    expect(action).not.toHaveAccessibleName(/d NaN/);
+    expect(action).toHaveTextContent("R —");
+    expect(action).not.toHaveTextContent("d NaN");
+  });
+});