engsys 1.0.0

package/stacks/platform/web/skills/frontend-testing/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: frontend-testing
+description: Frontend test discipline for this repo — Vitest 4, Testing Library (RTL / React Testing Library), and Playwright E2E for React / Next.js apps. Use when writing or reviewing Vitest specs, vi.mock factories, fake-timer tests, RTL component tests, Radix portal tests, or Playwright E2E specs and their CI matrix wiring. Covers vi.hoisted mock-factory hoisting, keeping every vi.mock factory in sync, Vitest 4 pool config (fileParallelism), the fake-timers act() pattern, RTL accessible-query discipline, Radix-portal JSDOM limits, useLayoutEffect for test-observable accumulation, and Playwright spec-authoring footguns / CI-matrix registration / axe E2E.
+---
+
+# Frontend Testing (Vitest + Testing Library + Playwright)
+
+Applies to: unit/component specs (`*.spec.{ts,tsx}`) and Playwright E2E (`e2e/**/*.spec.ts`) in the repo's web frontends. Stack assumed: Vitest 4.x, `@testing-library/react`, the `testing-library` + `react-hooks` eslint plugins, Radix UI, Playwright in a CI matrix against booted services.
+
+> Naturalize: confirm the Vitest version, the eslint test config, and the Playwright CI job/matrix in `CLAUDE.md`. Paths below (`services/dashboard/...`, `.github/workflows/...`) are illustrative.
+
+This skill is the React/Vitest/Playwright-specific **mechanism**. The cross-project **principles** behind it — "a change isn't done until every surface is updated", "register checks or they're silent gaps", "shift correctness left and distrust false greens" — live in the engsys `lessons-library/`. Here we carry the concrete test-tooling shape.
+
+## Contents
+
+- [Vitest: mock factories](#vitest-mock-factories)
+- [Vitest 4: pool config and gated suites](#vitest-4-pool-config-and-gated-suites)
+- [Fake timers: the act() pattern](#fake-timers-the-act-pattern)
+- [RTL: accessible queries, not container traversal](#rtl-accessible-queries-not-container-traversal)
+- [RTL: double render and Radix portals](#rtl-double-render-and-radix-portals)
+- [RTL: useLayoutEffect for test-observable accumulation](#rtl-uselayouteffect-for-test-observable-accumulation)
+- [Playwright: register every spec in the CI matrix](#playwright-register-every-spec-in-the-ci-matrix)
+- [Playwright: migrate the local DB before E2E](#playwright-migrate-the-local-db-before-e2e)
+- [Playwright: assert containers for services not booted in CI](#playwright-assert-containers-for-services-not-booted-in-ci)
+- [Playwright: spec-authoring footguns](#playwright-spec-authoring-footguns)
+- [Playwright: strict mode and table rows](#playwright-strict-mode-and-table-rows)
+- [Playwright: whole-document axe finds real a11y](#playwright-whole-document-axe-finds-real-a11y)
+- [Playwright: copy / flow changes break E2E](#playwright-copy--flow-changes-break-e2e)
+- [Review checklist](#review-checklist)
+
+## Vitest: mock factories
+
+**`vi.mock` factories are hoisted above `const`/`let`.** A spy declared with `const mockFn = vi.fn()` *before* a `vi.mock` factory that references it throws `Cannot access 'mockFn' before initialization` at runtime — the factory is hoisted above the declaration. Linters don't catch it. Wrap such spies in `vi.hoisted()`:
+
+```ts
+// Wrong — ReferenceError at runtime
+const mockCreateJob = vi.fn();
+vi.mock("@/lib/api-client", () => ({ signalsExportApi: { createJob: mockCreateJob } }));
+
+// Right — vi.hoisted runs before the factory
+const { mockCreateJob } = vi.hoisted(() => ({ mockCreateJob: vi.fn() }));
+vi.mock("@/lib/api-client", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@/lib/api-client")>();
+  return { ...actual, signalsExportApi: { createJob: mockCreateJob } };
+});
+```
+
+**When you add an export to a mocked module, update EVERY `vi.mock` factory of it — in the same commit.** A factory replaces the whole module; a missing new export is `undefined` (or throws `No "X" export is defined on the mock`), and *pre-existing* specs go red in code you only added an export to. Use `importOriginal` and spread `...actual` so real exports survive and you only override what you need.
+
+```ts
+vi.mock("@app/database", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@app/database")>();
+  return { ...actual, prisma: prismaMock }; // keep the rest real
+});
+```
+
+Grep for mock factories of a path **before** running the suite, not after it fails:
+
+```bash
+grep -rl 'vi.mock("@/lib/access"' --include='*.spec.*' services/dashboard
+```
+
+When a new export reads a model the prisma mock doesn't define, add that model returning the "no override" row (`findUnique: vi.fn().mockResolvedValue(null)`) so pre-change behavior holds. Run **every** consuming service's full suite after a cross-cutting shared-package change — the break is in the OLD specs.
+
+## Vitest 4: pool config and gated suites
+
+`poolOptions.forks.singleFork` was **removed in Vitest 4** — it's replaced by the top-level `fileParallelism`. CodeRabbit may cite v2/v3 doc URLs that still list `singleFork`; trust the installed package's types, not the doc URL.
+
+```ts
+// Vitest 4 — correct: all files run sequentially in one pool process
+export default defineConfig({
+  test: { pool: "forks", fileParallelism: false },
+});
+```
+
+Use `fileParallelism: false` for E2E specs that depend on ordered external-service state and for suites that manage their own concurrency. Verify the option exists in your install:
+
+```bash
+grep -n "singleFork\|fileParallelism" node_modules/vitest/dist/chunks/*.d.ts
+```
+
+**Separate configs for gated suites.** When a suite needs external infra (live DB, LLM key, docker stack), give it its own config so plain `pnpm test` never triggers it: `vitest.config.ts` (unit), `vitest.e2e.config.ts`, `vitest.ai-regression.config.ts`, with matching `test:e2e` / `test:ai-regression` scripts. Put the env gate (`if (!process.env.INGESTION_E2E) return`) in the spec so `pnpm test` skips the whole file rather than silently passing.
+
+## Fake timers: the act() pattern
+
+Advancing fake timers fires `setTimeout` callbacks synchronously, which call `setState` inside the hook. Without `act`, React queues but doesn't flush the update and the assertion sees stale state. But `testing-library/no-unnecessary-act` (error) flags any `act()` wrapping an RTL utility.
+
+Resolution: import `act` from **`react`** (not `@testing-library/react`) and wrap **only** the `vi.advanceTimersByTime()` call — never an RTL utility in the same `act` scope.
+
+```ts
+import { act } from "react";                  // NOT @testing-library/react
+import { renderHook } from "@testing-library/react";
+
+function advanceTimers(ms: number) {
+  act(() => { vi.advanceTimersByTime(ms); }); // act wraps only the timer advance
+}
+
+it("debounce fires after quiet period", () => {
+  const { result, rerender } = renderHook(({ v }) => useDebouncedValue(v, 250), {
+    initialProps: { v: "" },
+  });
+  rerender({ v: "a" });
+  advanceTimers(250);
+  expect(result.current).toBe("a");
+});
+```
+
+Don't: `act(() => { rerender(...); vi.advanceTimersByTime(50); })` (lint error — rerender inside act), and don't advance timers without `act` (state not flushed).
+
+## RTL: accessible queries, not container traversal
+
+The `testing-library` eslint plugin (`no-container`, `no-node-access`, error) forbids `container.querySelector(...)` / `element.querySelectorAll(...)`. Use `screen.*` accessible queries:
+
+```tsx
+expect(screen.queryByTestId("my-element")).toBeNull();          // not container.querySelector
+expect(screen.getAllByTestId("row").length).toBeGreaterThan(0);  // not querySelectorAll
+expect(screen.queryAllByRole("button")).toHaveLength(0);         // not querySelectorAll("button,...")
+```
+
+Only exception: **security assertions** with no accessible query (checking no `<script>`/`iframe[srcdoc]` was injected by an XSS payload) — use `// eslint-disable-next-line testing-library/no-container, testing-library/no-node-access` with a rationale comment. (`container.innerHTML` is property access, not traversal, and is allowed.)
+
+## RTL: double render and Radix portals
+
+**Two `render()` calls in one `it()` accumulate DOM** — RTL appends, both renders coexist, and `getByTestId` throws "Found multiple elements". RTL runs `cleanup()` after each test (`afterEach`), not between renders within one. Split into separate `it()` blocks, or call `cleanup()` between renders.
+
+**Radix portal items are unreachable in JSDOM.** `DropdownMenu`/`Select`/`Popover`/`Tooltip`/`Dialog` content renders in a portal via pointer/popover APIs JSDOM doesn't implement — clicking the trigger never opens the content, so `getByTestId("the-item")` throws. Don't simulate the interaction; **test the invariant**:
+
+```ts
+// Wrong — portal item never mounts in JSDOM
+fireEvent.click(screen.getByTestId("sort-dropdown"));
+fireEvent.click(screen.getByTestId("sort-option-movers")); // throws
+
+// Right — assert the invariant (sort is client-side, never a query param)
+it("sort param is never passed to useThemeGrid", () => {
+  renderTable({ sort: "volume" });
+  for (const call of mockUseThemeGrid.mock.calls) {
+    expect(call[0]).not.toHaveProperty("sort");
+  }
+});
+```
+
+For "correct option selected", check the trigger's visible label / `aria-label`. The codebase pattern for unit-testing Radix Select is to mock the whole Select component. The real interaction is the job of Playwright E2E (real browser).
+
+## RTL: useLayoutEffect for test-observable accumulation
+
+When a component accumulates data across fetches (e.g. "Show more" appends rows), `useEffect` fires **asynchronously** and is not flushed by the `act()` that wraps `render()` — so `accumulated` stays empty and queries time out even though the mock data was synchronous. Use **`useLayoutEffect`** (fires synchronously inside RTL's `act`) with **`useReducer`** for correct multi-action sequencing:
+
+```tsx
+const [accumulated, dispatchAcc] = React.useReducer(accReducer, []);
+React.useLayoutEffect(() => {
+  if (data?.data) dispatchAcc({ type: "merge", items: data.data });
+}, [data?.data]);
+
+// Guard reset against the spurious initial-mount fire (ordering wipes page 1 otherwise):
+const prevIdRef = React.useRef(metricId);
+React.useLayoutEffect(() => {
+  if (prevIdRef.current !== metricId) { prevIdRef.current = metricId; dispatchAcc({ type: "reset" }); }
+}, [metricId]);
+```
+
+The ref-during-render alternative is `react-hooks/refs`-illegal; `useLayoutEffect + useReducer` is the lint-clean answer. Use it whenever an accumulating, RTL-tested component needs its accumulated state visible in assertions without `waitFor`.
+
+## Playwright: register every spec in the CI matrix
+
+A new Playwright spec that isn't in the CI matrix is theater — it passes locally forever and **never runs in CI**, a silent gap indistinguishable from coverage. Writing the spec **includes registering it in the matrix, in the same commit / AC**. Treat the matrix entry like an import: the spec doesn't exist until something runs it. Reviewers: any PR adding `e2e/*.spec.ts` must show a matching workflow/matrix diff (or a verified glob that picks it up).
+
+```bash
+ls services/dashboard/e2e/*.spec.ts | xargs -n1 basename
+grep -ni "playwright" .github/workflows/services-ci.yml
+```
+
+## Playwright: migrate the local DB before E2E
+
+After a migration-bearing phase merges, local Postgres lacks the new migrations — the next phase's E2E `beforeAll` seed throws Prisma `P2022` and the whole spec aborts (zero tests run), which looks like a flake but is an environment gap. Apply migrations locally first, and source env (`JWT_SECRET` etc.) before any local Playwright run:
+
+```bash
+pnpm db:migrate:local                                  # prod-safe, localhost-hardcoded
+set -a && source services/dashboard/.env.local && set +a
+cd services/dashboard && pnpm playwright test e2e/<spec>.spec.ts --project=chromium
+```
+
+A `PUSH_OVERRIDE`'d E2E is **not** verified — confirm the specific changed specs go green in CI (`gh pr checks <n> --watch`), not just the unit gate. An unverified E2E once hid a real Radix-Select feature bug because it was the only test exercising the flow.
+
+## Playwright: assert containers for services not booted in CI
+
+The CI Playwright stack boots only some services (e.g. api-gateway + dashboard, not Insights). For pages whose data is fetched client-side from a **not-booted** service, you can only assert the **container / loading state** that renders immediately on mount — **not** its data-dependent children, which spin forever.
+
+```ts
+await expect(page.getByTestId("all-themes-grid")).toBeVisible();  // container — renders immediately
+// NOT: await expect(page.getByTestId("theme-card")).toBeVisible(); // data from Insights — never loads in CI
+```
+
+Before asserting data content: trace the hook → API call → proxy controller; if the route proxies to a not-booted service, assert container only and document why. When the UX *depends* on that service's data (a strip that renders from an embedded projection field), the spec's `page.route()` interception must supply that service's **full data contract** for the branch under test — not just the fields you happen to need locally — or CI stubs an incomplete fixture and the UX silently doesn't render. "Passes locally" is never the gate.
+
+## Playwright: spec-authoring footguns
+
+- **No self-nested locators.** After `const panel = page.getByTestId("widget-config-panel")`, a `panel.getByTestId("widget-config-panel")` searches *inside* panel and finds nothing. Query a **child** testid/role instead.
+- **`domcontentloaded`, not `networkidle`, for routes with background retries.** Any route whose layout fires hooks to services that are down in CI never reaches `networkidle` (requests retry forever) and times out. Use `waitUntil: "domcontentloaded"`. Reserve `networkidle` for fully self-contained pages.
+- **One-time setup in `beforeAll`, not `beforeEach`.** A ~60s `seedScenario()` in `beforeEach` blows the per-test budget. Use `beforeAll` for read-only suites; `beforeEach` only when each test needs fresh state. Sanity: `setupCost × testCount` under ~80s.
+- **Hydrate before clicking.** A click on an SSR-rendered tab/control before React hydrates is a silent no-op (`toBeVisible`/`networkidle` don't prove hydration). Interact with a controlled input first (`fill`/`selectOption` auto-wait for actionability and double as a hydration gate), then click. Use `await expect(page).toHaveURL(/pattern/)` (auto-retries) — not synchronous `page.url()`, which reads before navigation commits.
+- **`forceMount` panels that own cross-tab effects/state.** A custom `TabsContent` that `return null`s inactive panels unmounts effects/state a panel must keep while another tab is active — a product bug, not just a test issue. Keep it mounted via `hidden={!isSelected}`.
+- **Stub the LANDING panel's on-mount fetches**, not only the panel under test — an unmocked background fetch on the initially-active panel can stall a later tab switch.
+- **Exact matchers in negative assertions.** Broad regexes in absence checks match unintended controls (false failures) or miss renamed ones (silent false passes). Anchor: `/^confirm kpi$/i` or testids. Establish the page surface first so "absent" can't mean "never rendered".
+
+## Playwright: strict mode and table rows
+
+`page.getByText("Acme Corp").click()` violates strict mode — `getByText` matches every element whose subtree contains the text (`<tr>`, `<td>`, `<div>`, `<p>`). With `workers: 1` it's a hard error, not a flake. Target the row by role or testid:
+
+```ts
+await page.getByRole("row", { name: /Acme Corp/i }).click(); // exactly one row
+```
+
+Related: Radix tooltips render **two** `role="tooltip"` nodes — bare `getByRole("tooltip")` violates strict mode; use `.first()` or an exact name.
+
+## Playwright: whole-document axe finds real a11y
+
+Component-level `jest-axe` (mounted in isolation, JSDOM) **structurally cannot** see real CSS-token contrast as rendered, focus order, dialog trapping, opacity-dimmed text, or Radix's portal/aria id plumbing. A **whole-document** axe E2E (wcag2a+2aa) against the running app catches real shipped violations component-axe misses — `Badge variant="success"` white-on-green at 2.3:1, `text-muted-foreground/60` opacity-dimmed text, a custom `id` on a Radix `Dialog.Title` that overrides Radix's `aria-labelledby` wiring, `<label>` with no `htmlFor`/`id` pairing.
+
+Treat a whole-document axe failure as a **real product bug** to fix at the source (design token / markup), not a reason to weaken the audit. Read the axe `fgColor`/`bgColor`/`message` and fix the **exact** element in the **state the seed renders** (it often flags a placeholder, not the snippet). Run the whole-page scan against the rebuilt bundle when introducing composite ARIA (treegrid/tablist/menu). When scoping a gate to a feature's subtree, exclude specific rule ids and file a tracking issue — don't drop whole rule categories. Never use `opacity-*` to soften text that must meet AA.
+
+## Playwright: copy / flow changes break E2E
+
+`pnpm test` runs **Vitest only** — E2E is a separate runner against the full stack. A green unit suite can sit alongside an E2E `getByRole('heading', { name: /old copy/i })` that times out. When a change touches headings/CTA labels/option names **or the interaction FLOW** (a new gating step, confirm dialog, required control, re-routed commit), grep the specs and update locators in the **same PR**:
+
+```bash
+grep -rnE "Welcome to <App>|Get started|<old label>" <app>/e2e/
+```
+
+Use substring regexes that dodge punctuation (`/set up your first workspace/i`). A renamed label is an API change to the test suite. Note derived strings reuse labels (a `${col.label} ${verb}` aria-label breaks too — grep every occurrence, not just the header). And remember separate Playwright surfaces run in their own CI job that the default precheck may NOT cover — grep them too.
+
+## Review checklist
+
+- [ ] Spies referenced in a `vi.mock` factory are wrapped in `vi.hoisted()`
+- [ ] Every `vi.mock` factory of a module updated when an export is added (same commit; `importOriginal` + spread)
+- [ ] Vitest 4 uses `fileParallelism: false` (not `poolOptions.forks.singleFork`); gated suites have their own config + spec-level env gate
+- [ ] Fake-timer tests wrap only `vi.advanceTimersByTime` in `act` from `react`
+- [ ] RTL uses `screen.*` queries; no `container.querySelector` (except justified security checks)
+- [ ] No double `render()` per test; Radix portal tests assert the invariant, not the interaction
+- [ ] Accumulate-across-fetches uses `useLayoutEffect` + `useReducer` to be test-observable
+- [ ] Every new Playwright spec registered in the CI matrix in the same commit
+- [ ] Local DB migrated + env sourced before local E2E; CI legs confirmed green (not just unit)
+- [ ] Data assertions only for services booted in CI; container/loading otherwise; interceptions supply the full contract
+- [ ] No self-nested locators; `domcontentloaded` for background-retry routes; `beforeAll` for read-only setup; hydrate before clicking; `forceMount` cross-tab panels
+- [ ] Table-row clicks use `getByRole('row')`/testid, not `getByText`
+- [ ] Whole-document axe run for new/changed UI; violations fixed at source
+- [ ] Copy/flow changes: specs grepped and locators updated in the same PR (all Playwright surfaces)

package/stacks/platform/web/skills/react-conventions/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: react-conventions
+description: React + Next.js client conventions for this repo (React 19 / Next.js 16, React Query / TanStack Query, Radix UI, shadcn-style cards/dialogs). Use when writing or reviewing React components, hooks, optimistic cache patches, data-fetching code, dialogs, Radix Select usage, JSX, interactive cards/rows, or Next.js Edge Runtime / middleware code. Covers optimistic-cache completeness, fetch error states, destructive-dialog error handling, the React 19 set-state-in-effect rule, a Radix Select form footgun, a JSX-ternary-comment parse error, composite-interactive a11y, the Edge-Runtime/Prisma import boundary, and the shared API-helper convention.
+---
+
+# React + Next.js Client Conventions
+
+Applies to: client components and hooks in the repo's web frontends. Stack assumed: React 19 / Next.js 16 (App Router), TanStack Query (React Query), Radix UI primitives, a shared `api` client helper, and a same-origin BFF/proxy. Test runner is Vitest + Testing Library (see the sibling `frontend-testing` skill).
+
+> Naturalize: confirm framework versions, the query-client setup, and the shared API helper path in `CLAUDE.md`. Paths below (`services/dashboard/lib/...`) are illustrative.
+
+These conventions are the React/Next.js-specific **mechanism**. The cross-project **principles** behind several of them — "a change isn't done until every surface is updated", "shift correctness left and distrust false greens" — live in the engsys `lessons-library/`. This skill carries the concrete React shape.
+
+## Contents
+
+- [Optimistic cache patches must be complete](#optimistic-cache-patches-must-be-complete)
+- [Derived parent fields: inherit the server's rule](#derived-parent-fields-inherit-the-servers-rule)
+- [Error states on data fetch](#error-states-on-data-fetch)
+- [Destructive dialogs own their error + pending state](#destructive-dialogs-own-their-error--pending-state)
+- [No setState inside useEffect (React 19)](#no-setstate-inside-useeffect-react-19)
+- [Radix Select inside a form: guard the empty reset](#radix-select-inside-a-form-guard-the-empty-reset)
+- [No JSX comment inside a ternary branch](#no-jsx-comment-inside-a-ternary-branch)
+- [Composite interactive a11y](#composite-interactive-a11y)
+- [Next.js Edge Runtime: no Node-only imports at module scope](#nextjs-edge-runtime-no-node-only-imports-at-module-scope)
+- [Data fetching goes through the shared API helper](#data-fetching-goes-through-the-shared-api-helper)
+- [Common mistakes](#common-mistakes)
+- [Review checklist](#review-checklist)
+
+## Optimistic cache patches must be complete
+
+An optimistic React Query patch is a hand-written mirror of the server's write. It is correct only when it touches **every** surface the mutation touches. Five recurring incompleteness shapes:
+
+1. **Update every projected/derived field.** For each field the server derives from child rows, mirror the exact server projection rule — ranking (`ACCEPTED` outranks `DECLINED`), last-pending checks, primary-vs-non-primary. Do not assume `result.status` is authoritative; check what the server would compute. A missed projection causes optimistic → server-returned flicker.
+2. **Re-sort when the mutation changes a sort key.** If the patch updates a field the list sorts by, re-sort before returning: `[...nodes].sort(sortFn)`. Guard with `'sortOrder' in node` to skip unrelated updates.
+3. **Refresh sibling derived caches.** Count/stats/rollup/badge caches that read the mutated collection go stale. Patch or invalidate them explicitly (e.g. pass `derivedKeys: [queryKeys.nodes.stats(scopeId)]`). Never assume an unrelated refetch will eventually fix it.
+4. **Reconcile placeholders by a stable id.** Generate an `optimisticId` at `onMutate` time and thread it through to `onSuccess`. Match/remove the placeholder by `node.id === optimisticId` only — never by `label`, `index`, or any user-controlled field, or two concurrent creates with the same label silently drop one.
+5. **Return new references — never mutate in place.** React Query uses reference equality to decide whether to notify subscribers. `arr.sort()` / `obj.field = x` mutate the cached object without notifying. Use `[...arr].sort(fn)` and `{ ...obj, field: x }`. When a mapper returns the original reference on a no-match, skip `setQueryData` entirely.
+
+```ts
+// Wrong — mutates the cached array, no sibling refresh, stale derived field
+const node = cache.find((n) => n.id === id);
+node.sortOrder = next;            // in-place mutation: no notify
+updated.sort(sortDepth1);         // mutates the cached array
+
+// Right — new references, re-sort a copy, refresh siblings
+const patched = cache.map((n) => (n.id === id ? { ...n, sortOrder: next } : n));
+const sorted = [...patched].sort(sortDepth1);
+queryClient.setQueryData(listKey, sorted);
+queryClient.invalidateQueries({ queryKey: queryKeys.nodes.stats(scopeId) });
+```
+
+**Cache-KEY completeness** is the same family: any new query parameter that changes the result set MUST be in the cache key, or two parameter values collide on one cached entry and serve wrong data. When adding a filter param, grep every queryKey/cache-key builder for that query's shape and add the param in the same commit.
+
+**The full statement:** a mutation (or a new query param) touches three cache surfaces — (1) the patched/invalidated entries, (2) every sibling family that *displays* the entity (list, detail, rollup, badge/count), and (3) the cache KEY itself. Enumerate all three before declaring the cache handling done.
+
+## Derived parent fields: inherit the server's rule
+
+When a mutation on a child rolls up into a parent summary field, **re-derive the parent field from the full updated state, not from the mutation result alone.** Inherit the server's calc/precedence rule exactly; fall back to `result` only when there is no better signal.
+
+```ts
+// Wrong — ignores an already-decided primary
+const newStatus = remainingPending.length > 0 ? "PENDING" : result.status;
+
+// Right — inherit the primary's decided status; fall back to result when none decided yet
+const primaryDecidedStatus = rec.themeImpactId
+  ? rec.decidedSuggestions?.find((s) => s.id === rec.themeImpactId)?.status
+  : undefined;
+const newStatus =
+  remainingPending.length > 0 ? "PENDING" : (primaryDecidedStatus ?? result.status);
+```
+
+Apply identical derived-state logic to **both** the list cache and the detail cache (separate `setQueryData` calls) — copy/paste divergence here makes the card and the detail panel disagree. Grep the owning server service for the projection rule (e.g. an `IMPACT_STATUS_RANK`) and confirm the patch matches every branch.
+
+## Error states on data fetch
+
+Never silently `return null` on a fetch error for primary content — the user gets a blank section with no signal. Handle `isError` with user-visible UI. `null` is acceptable only for decorative tiles where the page still renders meaningfully.
+
+```tsx
+const { data, isError } = useSubscriptionInvoices();
+
+// Decorative strip / tile — page still meaningful without it:
+if (isError || !data) return null;
+
+// Primary content card — show an error and a recovery hint:
+if (isError) {
+  return (
+    <Card>
+      <CardHeader><CardTitle>Invoices</CardTitle></CardHeader>
+      <CardContent>
+        <p className="text-sm text-muted-foreground">
+          Could not load invoices. Please refresh the page to try again.
+        </p>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+Anything user-actionable (invoices, past-due status, anything with a `refetch()`) gets the error card. Inline `text-destructive` error for action failures (e.g. a "Manage billing" portal-session failure).
+
+## Destructive dialogs own their error + pending state
+
+A confirm dialog for a destructive action (remove/suspend/delete) must own its own `isPending` and `error` state — not inherit them from the parent, and not route failures to a far-away toast that leaves the modal open with no explanation.
+
+Rules:
+1. Dialog owns local `isPending` + `error`.
+2. `onConfirm` is typed `() => Promise<void>` and **throws on failure**.
+3. Inside the dialog: `setError(null)`, `setPending(true)`, `await onConfirm()`; on success close, on catch `setError(msg)` and do **not** close; `setPending(false)` in `finally`.
+4. Render `error` inline; reset it when the dialog **closes** (`if (!next) setError(null)`).
+5. The page-level handler throws instead of toasting — the dialog catches and surfaces it.
+
+```tsx
+async function handleConfirm() {
+  setError(null);
+  setIsPending(true);
+  try {
+    await onConfirm();        // throws on failure
+    onOpenChange(false);      // success closes the dialog
+  } catch (err) {
+    setError(errorMessage(err)); // failure stays open, shows inline
+  } finally {
+    setIsPending(false);
+  }
+}
+```
+
+## No setState inside useEffect (React 19)
+
+The React 19 / Next.js 16 eslint config ratchets `react-hooks/set-state-in-effect` (and `react-hooks/cannot-access-refs-during-render`) to **error**. `useEffect(() => { if (!open) setForm(EMPTY) }, [open])` and the ref-reset-during-render workaround both fail and block the PR.
+
+- **Reset-on-close → push into the close callback.** Wrap the parent's `onOpenChange` in a local `handleOpenChange(next)` that calls `setForm(EMPTY)` before delegating, and wire it to every close path (Radix Root `onOpenChange`, Cancel button, close-on-success).
+- **Derived-from-prop → `useMemo` + controlled fallback** (`const effective = form.value || derivedDefault`) instead of writing state from an effect.
+- **Filter-linked resets that must run on dependency change** → wrap the write in `startTransition` so it is scheduled as a non-urgent update outside the synchronous commit:
+
+  ```tsx
+  import { startTransition, useEffect } from "react";
+  useEffect(() => {
+    startTransition(() => setShown(PAGE_SIZE));
+  }, [period, scopeId]);
+  ```
+- **When the reset legitimately fires mid-session** (e.g. on a `provider` change while still open) the close-callback can't cover it — use a targeted per-line `// eslint-disable-next-line react-hooks/set-state-in-effect` with a rationale comment. Every suppressed setter needs its own disable line.
+
+Paired obligation: whenever you set a `saving`/`pending` flag before an async call, reset it (`setSaving(false)`) in **both** the success path and the open-reset — otherwise the confirm button stays disabled when the dialog reopens.
+
+## Radix Select inside a form: guard the empty reset
+
+A controlled Radix `<Select value={x} onValueChange={setter}>` **inside a `<form>`** with an **empty initial value** resets to `""` after the user picks an option. Radix renders an aria-hidden native `<select>` for form participation; when the content closes it remounts with no `<option>`s and fires a spurious `onValueChange("")`. The trigger may still show the right label (it reads props) while the underlying state is empty and the submit stays disabled.
+
+```tsx
+// Fixed — ignore the spurious empty-reset (safe when no option has an empty value)
+<Select
+  value={form.unit}
+  onValueChange={(v) => {
+    if (v) patch({ unit: v }); // guard against Radix's empty remount event
+  }}
+>
+```
+
+Only triggers with all three: inside a `<form>`, controlled, empty initial value. Initializing to a derived non-empty value avoids it entirely.
+
+## No JSX comment inside a ternary branch
+
+`{/* ... */}` is itself a JSX expression node. A ternary branch expects a **single** expression, so a comment node before the element makes a second child and the parser errors (`Expected '</', got 'ident'`).
+
+```tsx
+// Wrong
+{kind === "chip" ? (
+  {/* comment */}
+  <JudgmentChip bucket={bucket!} />
+) : ...}
+
+// Right — comment outside the ternary, or wrap the branch in a fragment
+{kind === "chip" ? (
+  <>
+    {/* comment */}
+    <JudgmentChip bucket={bucket!} />
+  </>
+) : ...}
+```
+
+## Composite interactive a11y
+
+Making a whole card/row clickable, or adding expand/collapse controls with ARIA relationships:
+
+- **No nested interactives.** No `<a>`/`<button>` descendant of an `<a>`/`<button>` ancestor. If a card is a `<Link>`, inner CTAs become handler-based controls (`e.preventDefault(); e.stopPropagation(); router.push(...)`) — or restructure so the card link is an overlay sibling, not an ancestor.
+- **`stopPropagation` on nested control clicks** so activating an inner control does not also activate the clickable container. Verify with both Enter and Space.
+- **Gate ARIA relationships on the target's presence.** A trigger pointing `aria-controls` at a region that isn't rendered while collapsed dangles. Gate it: `aria-controls={expanded ? regionId : undefined}`. Every `aria-controls`/`aria-owns`/`aria-describedby` id must exist in the DOM while the attribute is present.
+
+`aria-required-parent`-family violations only fire when the elements actually render, so seeded states can mask them in unit tests — confirm with whole-document axe E2E (see `frontend-testing`).
+
+## Next.js Edge Runtime: no Node-only imports at module scope
+
+Next.js middleware runs in the **Edge Runtime**, which can't load Node-only modules (Prisma, `fs`, native crypto). A *top-level* `import { prisma } from './prisma'` in any module the middleware imports runs at module-load time and crashes — even if `prisma` is only used inside one function.
+
+```ts
+// Wrong — top-level import runs in Edge Runtime when middleware loads this module
+import { prisma } from "./prisma";
+export async function ensureSessionClaimed(id: string) {
+  return prisma.session.findUnique({ where: { id } });
+}
+
+// Right — lazy import inside the function, which only runs in the Node runtime
+export async function ensureSessionClaimed(id: string) {
+  const { getPrisma } = await import("./prisma"); // runs only when called from a Node route
+  const prisma = await getPrisma();
+  return prisma.session.findUnique({ where: { id } });
+}
+```
+
+Rule: any module reachable from `middleware.ts` must be Edge-safe at module scope — pure functions, constants, types only. Push Node-only access into lazy `await import(...)` calls inside functions that run only in the Node runtime (API routes).
+
+## Data fetching goes through the shared API helper
+
+Use the shared `api` helper (`api.get/post/put/delete`) for all client → gateway calls, never raw `fetch`. The helper provides 401 silent token-refresh + one retry, `X-Tenant-Id` injection, correlation-id forwarding, and centralized JSON error parsing. Raw `fetch` bypasses all of it and a 401 fails silently.
+
+```ts
+// Wrong — bypasses auth refresh + tenant headers
+const res = await fetch("/api/proxy/api/v1/signals/export", {
+  method: "POST", credentials: "include", body: JSON.stringify(payload),
+});
+
+// Right — the helper prepends /api/proxy and handles auth/headers/errors
+const result = await api.post<SignalExportResult>("/api/v1/signals/export", payload);
+```
+
+Exceptions: anchor-click downloads (browser-native `Content-Disposition` streaming) and `rawGet()` when you need the raw `Response` (e.g. inspecting a 404 before throwing).
+
+Use `async/await` for every new API-client method and React Query `queryFn` (`queryFn: async () => await api.get(...)`) — direct promise returns get flagged.
+
+**Param parity:** when you add a query param or response field to the client types/hooks, implement it at the **owning backend service**, not just in the client. A param the client sends but the service ignores makes the UI look wired while the backend silently drops it. Trace every client API change through the gateway/proxy to the owning service and add coverage there in the same change.
+
+## Common mistakes
+
+1. Optimistic patch updates the surface you were looking at but misses a sibling rollup/badge cache.
+2. Mutating a cached array/object in place (`arr.sort()`, `obj.x = y`) — no subscriber notify.
+3. A new filter param reaches the query but not the cache key — values collide and serve wrong data.
+4. Deriving a parent rollup from `result.status` instead of the server's precedence rule.
+5. `return null` on `isError` for primary content — silent blank section.
+6. Destructive dialog routes failures to a toast and stays open with no inline error.
+7. `setState` inside `useEffect` for reset-on-close instead of the close callback.
+8. Setting a `saving` flag without resetting it on the success path / open-reset.
+9. Unguarded `onValueChange` on a controlled empty-start Radix Select inside a `<form>`.
+10. `{/* comment */}` directly inside a JSX ternary branch.
+11. Nested anchors/buttons, or `aria-controls` pointing at a not-yet-rendered region.
+12. Top-level Prisma/Node import in a module the Edge middleware loads.
+13. Raw `fetch` instead of the `api` helper; or extending client types without the owning service.
+
+## Review checklist
+
+- [ ] Optimistic patch updates every derived field, re-sorts on sort-key change, refreshes sibling caches, reconciles by stable id, returns new references
+- [ ] New query param is in the cache KEY, not just the query
+- [ ] Parent rollup field re-derived with the server's precedence rule, on list AND detail caches
+- [ ] `isError` shows visible UI for primary content; `null` only for decorative tiles
+- [ ] Destructive dialog owns `isPending`+`error`; `onConfirm` throws; errors inline; reset on close
+- [ ] No `setState` in `useEffect` (close callback / `useMemo` / `startTransition` / justified suppression)
+- [ ] `saving` flags reset on success and on open-reset
+- [ ] Controlled empty-start Radix Select in a form guards `onValueChange` against `""`
+- [ ] No JSX comment inside a ternary branch
+- [ ] No nested interactives; `stopPropagation` on inner controls; `aria-controls` gated on presence
+- [ ] No Node-only imports at module scope in any Edge-middleware-reachable module
+- [ ] All gateway calls use the `api` helper with `async/await`; new params implemented at the owning service

package/stacks/platform/web/skills/web-platform-conventions/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: web-platform-conventions
+description: Web platform conventions for this repo — Content-Security-Policy discipline and (for Next.js 16+) the proxy.ts-not-middleware convention. Use when editing CSP headers, adding a third-party SDK / analytics / external API origin, touching request-edge code (middleware/proxy), or wiring auth/redirects/headers on a web frontend.
+---
+
+# Web Platform Conventions
+
+Applies to: the web frontend(s) in this repo. Mostly framework-agnostic; the proxy.ts section is Next.js-specific.
+
+> Naturalize: confirm the framework/version and where the CSP is built in `CLAUDE.md`. The defaults below assume a same-origin BFF/proxy architecture.
+
+## Content-Security-Policy is a security-critical surface
+
+Treat the CSP as code that gates every network origin the page may reach. **Any new XHR/fetch origin, script host, or asset host must be added explicitly.** Never relax a directive to a wildcard to "make it work."
+
+### `connect-src` policy
+
+- **Production: `'self'` only** — no `https:` wildcard, no `data:` / `blob:` / `javascript:`. Browser-initiated API calls should go through a same-origin BFF/proxy (e.g. `/api/proxy/*`), so `'self'` covers them.
+- Auth flows that navigate the browser to another origin (OAuth login/callback) use `window.location` navigations, which are governed by `form-action` / navigation directives, **not** `connect-src`.
+- Development may add `ws:` / `wss:` for the dev server's hot-reload.
+
+### Before adding a new third-party SDK / analytics / external API
+
+1. Add the **explicit origin** to `connect-src` (e.g. `https://browser.sentry-cdn.com`). Do NOT relax to `https:`.
+2. If the SDK loads a script, also add the script host to `script-src`.
+3. Add a test asserting both that the new origin is present **and** that the old strictness is preserved (no wildcard regression).
+4. Smoke-test in dev — open DevTools console and look for CSP violation reports on the affected path.
+
+### Sensible directive defaults
+
+| Directive         | Sources                                              | Notes                                                  |
+| ----------------- | --------------------------------------------------- | ------------------------------------------------------ |
+| `default-src`     | `'self'`                                             | Fallback for everything not listed.                    |
+| `connect-src`     | `'self'` (+ `ws:` `wss:` in dev)                    | All XHRs same-origin via BFF.                          |
+| `script-src`      | `'self'`, per-request nonce, `'strict-dynamic'`     | Add explicit CDN hosts; avoid `'unsafe-inline'` in prod. |
+| `style-src`       | `'self'`, `'unsafe-inline'` (if the CSS framework requires it) | Tailwind/Next often need inline styles. |
+| `img-src`         | `'self'`, `data:`, your asset/storage host          |                                                        |
+| `frame-ancestors` | `'none'`                                             | Plus `X-Frame-Options: DENY` belt-and-suspenders.      |
+| `object-src`      | `'none'`                                             | No Flash, no PDF embed.                                 |
+| `base-uri`        | `'self'`                                             | Blocks `<base>` injection.                              |
+| `form-action`     | `'self'`                                             | All forms post same-origin.                            |
+
+Prefer a per-request nonce + `'strict-dynamic'` over host allowlists for scripts where the framework supports it.
+
+## Next.js 16+: `proxy.ts`, not `middleware.ts`
+
+Next.js 16 **replaced `middleware.ts` with `proxy.ts`**. Having both present is a build error ("use ./proxy.ts only").
+
+**Rule:** on Next.js 16+, there is no `middleware.ts` anywhere in the service. Auth, redirects, headers, request rewriting, and the CSP header all go through `proxy.ts`.
+
+Background: <https://nextjs.org/docs/messages/middleware-to-proxy>.
+
+## Logging
+
+Use the project logger, not `console.*`, on web frontends — so logs are structured, domain-scoped, and routable. Check `CLAUDE.md` for the logger import and the domain/level conventions.

package/stacks/tooling/issue-tracker-github/claude.fragment.md

@@ -0,0 +1,10 @@
+## Issue tracking
+
+- **Active tracker: GitHub Issues + Projects.** Agents use the `issue-tracker-github`
+  skill for all issue and board operations (create/list/get/update/comment/close issue;
+  create/add-to/query board; set board field; link PR).
+- PRs and CI stay on GitHub via `gh`. A merged PR closes its work item through the
+  `Closes #<n>` convention (one keyword per line).
+
+<!-- naturalize: confirm the repo (<owner>/<repo>) and the GitHub Project number + owner
+(user/org) that hold the board, plus the Phase/Priority/Owner field option values. -->

package/stacks/tooling/issue-tracker-github/settings.fragment.json

@@ -0,0 +1,24 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh issue create:*)",
+      "Bash(gh issue list:*)",
+      "Bash(gh issue view:*)",
+      "Bash(gh issue edit:*)",
+      "Bash(gh issue comment:*)",
+      "Bash(gh issue close:*)",
+      "Bash(gh issue status:*)",
+      "Bash(gh project list:*)",
+      "Bash(gh project view:*)",
+      "Bash(gh project create:*)",
+      "Bash(gh project field-list:*)",
+      "Bash(gh project field-create:*)",
+      "Bash(gh project item-list:*)",
+      "Bash(gh project item-add:*)",
+      "Bash(gh project item-edit:*)",
+      "Bash(gh api graphql:*)",
+      "Bash(gh pr create:*)"
+    ]
+  },
+  "mcpServers": {}
+}