Per-deliverable reports, the service catalogue, and one roster authority

.githooks/pre-commit

@@ -83,7 +83,12 @@ needs_typegen() {
     # Editing a route module's body does not change its generated types — those
     # infer from `typeof loader` when tsc runs. A route file APPEARING or
     # DISAPPEARING changes the tree, and that does.
-    echo "$STAGED_TREE" | grep -qE '^app/routes/'
+    #
+    # A colocated SPEC is not a route: `app/routes/foo.test.tsx` never enters
+    # routes.ts, so typegen's output cannot differ because one arrived. The Test
+    # Layout in CLAUDE.md REQUIRES frontend specs to sit beside what they test,
+    # so this fires on ordinary work — and typegen costs ~60s measured here.
+    echo "$STAGED_TREE" | grep -E '^app/routes/' | grep -qvE '\.(test|spec)\.(ts|tsx)$'
 }
 
 step "Type check"

.github/workflows/ci.yml

@@ -75,6 +75,17 @@ jobs:
           path: app/paraglide
           key: paraglide-${{ hashFiles('messages/**', 'project.inlang/**') }}
       - run: npm run i18n:compile:cached
+      # Same shape as the paraglide cache above, and for the same reason: the
+      # output is a pure function of the route TREE, so a key built from those
+      # inputs can only restore what they produced. Five jobs need these types
+      # and every one of them was paying the full ~60s generate — five runner
+      # minutes per CI run for identical output. Hashing the route file bodies
+      # over-invalidates (editing a loader cannot change the generated types)
+      # but never under-invalidates, which is the safe direction for a cache.
+      - uses: actions/cache@v4
+        with:
+          path: .react-router/types
+          key: rr-typegen-${{ hashFiles('app/routes.ts', 'app/routes/**', 'react-router.config.ts', 'package-lock.json') }}
       - run: npx react-router typegen
       - run: npm run type-check:app
 
@@ -114,6 +125,17 @@ jobs:
           path: app/paraglide
           key: paraglide-${{ hashFiles('messages/**', 'project.inlang/**') }}
       - run: npm run i18n:compile:cached
+      # Same shape as the paraglide cache above, and for the same reason: the
+      # output is a pure function of the route TREE, so a key built from those
+      # inputs can only restore what they produced. Five jobs need these types
+      # and every one of them was paying the full ~60s generate — five runner
+      # minutes per CI run for identical output. Hashing the route file bodies
+      # over-invalidates (editing a loader cannot change the generated types)
+      # but never under-invalidates, which is the safe direction for a cache.
+      - uses: actions/cache@v4
+        with:
+          path: .react-router/types
+          key: rr-typegen-${{ hashFiles('app/routes.ts', 'app/routes/**', 'react-router.config.ts', 'package-lock.json') }}
       - run: npx react-router typegen
       - run: npm run test:types
 
@@ -141,6 +163,17 @@ jobs:
           path: app/paraglide
           key: paraglide-${{ hashFiles('messages/**', 'project.inlang/**') }}
       - run: npm run i18n:compile:cached
+      # Same shape as the paraglide cache above, and for the same reason: the
+      # output is a pure function of the route TREE, so a key built from those
+      # inputs can only restore what they produced. Five jobs need these types
+      # and every one of them was paying the full ~60s generate — five runner
+      # minutes per CI run for identical output. Hashing the route file bodies
+      # over-invalidates (editing a loader cannot change the generated types)
+      # but never under-invalidates, which is the safe direction for a cache.
+      - uses: actions/cache@v4
+        with:
+          path: .react-router/types
+          key: rr-typegen-${{ hashFiles('app/routes.ts', 'app/routes/**', 'react-router.config.ts', 'package-lock.json') }}
       - run: npx react-router typegen
       - run: npm run lint:eslint
 
@@ -168,6 +201,17 @@ jobs:
       # the generated route types present or it reports the whole of app/routes
       # as unresolved. In the old serial job these existed only because
       # type-check had already run; nothing declared the dependency.
+      # Same shape as the paraglide cache above, and for the same reason: the
+      # output is a pure function of the route TREE, so a key built from those
+      # inputs can only restore what they produced. Five jobs need these types
+      # and every one of them was paying the full ~60s generate — five runner
+      # minutes per CI run for identical output. Hashing the route file bodies
+      # over-invalidates (editing a loader cannot change the generated types)
+      # but never under-invalidates, which is the safe direction for a cache.
+      - uses: actions/cache@v4
+        with:
+          path: .react-router/types
+          key: rr-typegen-${{ hashFiles('app/routes.ts', 'app/routes/**', 'react-router.config.ts', 'package-lock.json') }}
       - run: npx react-router typegen
       - run: npm run lint:gates-full
       - name: Migration drift gate (schema vs migrations)
@@ -220,6 +264,17 @@ jobs:
           path: app/paraglide
           key: paraglide-${{ hashFiles('messages/**', 'project.inlang/**') }}
       - run: npm run i18n:compile:cached
+      # Same shape as the paraglide cache above, and for the same reason: the
+      # output is a pure function of the route TREE, so a key built from those
+      # inputs can only restore what they produced. Five jobs need these types
+      # and every one of them was paying the full ~60s generate — five runner
+      # minutes per CI run for identical output. Hashing the route file bodies
+      # over-invalidates (editing a loader cannot change the generated types)
+      # but never under-invalidates, which is the safe direction for a cache.
+      - uses: actions/cache@v4
+        with:
+          path: .react-router/types
+          key: rr-typegen-${{ hashFiles('app/routes.ts', 'app/routes/**', 'react-router.config.ts', 'package-lock.json') }}
       - run: npx react-router typegen
       - run: npm run test:web
 
@@ -316,6 +371,17 @@ jobs:
       - name: Provision ephemeral E2E secrets
         run: node scripts/gen-e2e-dev-vars.mjs
 
+      # Keyed on the resolved Playwright version, because the browser build a
+      # given Playwright pins is a pure function of it — a hit can only ever
+      # restore the binary that version asked for. `--with-deps` still runs on a
+      # hit; it installs system libraries into /usr, which is outside the cached
+      # path and cheap once the download is skipped.
+      - name: Cache Playwright browser
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+
       - name: Install Playwright browser (chromium)
         run: npx playwright install --with-deps chromium
 

CLAUDE.md

@@ -61,25 +61,10 @@ applies the same config resolution to direct wrangler commands (db:migrate).
 
 ## Key Files & Directories
 
-| File/Dir | Purpose |
-|---|---|
-| `workers/app.ts` | Single-worker entry — Hono mounts the full API in-process + delegates page routes to React Router SSR |
-| `server/index.ts` | Hono API entry point and route configuration |
-| `server/api/` | API route handlers (Auth, Inspections, Bookings, etc.) |
-| `server/lib/db/` | Drizzle ORM schema (`server/lib/db/schema`) and database utilities |
-| `server/lib/middleware/` | Hono middleware (Authentication, RBAC, etc.) |
-| `server/lib/validations/` | Zod schemas per module |
-| `server/services/` | Business logic, DB queries (Drizzle) |
-| `migrations/` | D1 migration SQL (drizzle-kit schema-first: `0000_baseline.sql` + forward) |
-| `tests/` | See "Test Layout" below |
-| `app/routes/` | React Router v8 route files |
-| `app/components/` | React components |
-| `app/hooks/` | React hooks (useInspection, useFindings, useKeyboard, etc.) |
-| `app/lib/` | API client (hono/client over the in-process binding), session management, helpers |
-| `app/styles/tailwind.css` | Design System 0523 token layer (Tailwind v4) |
-| `public/` | Static assets (fonts, logo, service worker, widget) |
-| `packages/shared-ui/src/` | shared React components (Button, Pill, Card, etc.) |
-| `packages/api-types/` | CoreApiType re-export for hono/client |
+The layout is conventional and discoverable — `server/` (api, lib/db, lib/middleware,
+lib/validations, services), `app/` (routes, components, hooks, lib), `packages/`
+(shared-ui, api-types), `migrations/`, `public/`. `workers/app.ts` is the single
+worker entry; see Core Architecture below for what it does and why.
 
 ### Test Layout
 

app/components/AuthShell.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect } from 'vitest';
 import { render } from '@testing-library/react';
 import { AuthShell } from '~/components/AuthShell';

app/components/CommandPalette.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen, fireEvent } from '@testing-library/react';
 import { createRoutesStub } from 'react-router';
 import { CommandPalette } from './CommandPalette';

app/components/CostExportButtons.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen } from "@testing-library/react";
 import { CostExportButtons } from "./CostExportButtons";
 

app/components/LoadFailedNotice.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 /**
  * The sentence that keeps "this did not load" apart from "there is nothing
  * here" (IA-118).

app/components/MoneyInput.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen, fireEvent } from "@testing-library/react";
 import { vi } from "vitest";
 import { MoneyInput } from "./MoneyInput";

app/components/NewInspectionWizard.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 /**
  * Free-tier "at cap" gate — the New Inspection wizard should show the
  * upgrade panel IMMEDIATELY when it opens for a tenant already at the free

app/components/QuotaBanner.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect } from 'vitest';
 import { render } from '@testing-library/react';
 import { QuotaBanner } from '~/components/QuotaBanner';

app/components/Toast.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect, afterEach } from 'vitest';
 import { act, render, cleanup } from '@testing-library/react';
 import { ToastPortal } from '~/components/Toast';

app/components/address/AddressAutocomplete.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect, vi } from "vitest";
 import { useState } from "react";
 import { render, screen, fireEvent, waitFor } from "@testing-library/react";

app/components/address/GoogleMap.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { render } from "@testing-library/react";
 

app/components/agent/cross-portal-reuse.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 /**
  * The same entity must read the same in both portals.
  *

app/components/audit/EntityAuditTrail.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen, fireEvent } from '@testing-library/react';
 import { createRoutesStub } from 'react-router';
 import { EntityAuditTrail, type AuditEntry } from './EntityAuditTrail';

app/components/booking/HolidayAdvisoryBanner.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect } from "vitest";
 import { renderToStaticMarkup } from "react-dom/server";
 import { createMemoryRouter, RouterProvider } from "react-router";

app/components/calendar/CalendarDatePicker.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect, vi } from "vitest";
 import { createRef } from "react";
 import { render, fireEvent } from "@testing-library/react";

app/components/calendar/CalendarScopeToolbar.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, expect, it, vi } from "vitest";
 import { render } from "@testing-library/react";
 import { CalendarScopeToolbar } from "./CalendarScopeToolbar";

app/components/calendar/InspectorSyncBadge.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, expect, it } from "vitest";
 import { render } from "@testing-library/react";
 import { InspectorSyncBadge, syncBadgeState } from "./InspectorSyncBadge";

app/components/collab/version-compare.test.ts

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 // #181 PR-H (Task H2) — VersionCompare modal + VersionHistoryPanel compare flow.
 //
 // happy-dom + react-dom/client (no RTL in this repo). JSX avoided so the file

app/components/collab/version-history-panel.test.ts

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 // #181 Task 12a — VersionHistoryPanel UI behaviour.
 //
 // Renders the panel under happy-dom via react-dom/client (no RTL dep in this

app/components/comment-editor.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen } from '@testing-library/react';
 import { createRoutesStub } from 'react-router';
 import { CommentEditor } from './CommentEditor';

app/components/contacts/CapabilityMatrix.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 /**
  * Task 11 (two-layer role model) — the `?` capability matrix on the Roles page.
  * Five booleans with no explanation is how email_template_id became IA-93:

app/components/contacts/RoleProfileModal.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 /**
  * The modal auto-closes itself when a save succeeds, and the value it reads to
  * decide that — `fetcher.data` — outlives the submission that produced it.

app/components/contacts/RolesTable.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 /**
  * Admin Roles tab table (Plan 1B Task 4). Covers the behaviors the review
  * checks for: renders the role-profile list, flags isSystem rows with a

app/components/dashboard/DashboardInspectionRow.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 /**
  * The price on a dashboard row is integer CENTS and must be formatted as money.
  *

app/components/defect-category-editor.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen } from '@testing-library/react';
 import { createRoutesStub } from 'react-router';
 import { DefectCategoryEditor } from './DefectCategoryEditor';

app/components/editor-shared/InlineRename.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen, fireEvent } from "@testing-library/react";
 import { vi } from "vitest";
 import { InlineRename } from "~/components/editor-shared/InlineRename";

app/components/editor-shared/ItemList.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen } from '@testing-library/react';
 import { vi } from 'vitest';
 import { ItemList } from '~/components/editor-shared/ItemList';

app/components/editor-shared/RatingSegment.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect, afterEach } from "vitest";
 import { render, screen, cleanup, fireEvent } from "@testing-library/react";
 import { RatingSegment } from "./RatingSegment";

app/components/editor-shared/SectionRail.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen, fireEvent } from '@testing-library/react';
 import { vi } from 'vitest';
 import { SectionRail } from '~/components/editor-shared/SectionRail';

app/components/editor/BreadcrumbDropdown.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen, fireEvent } from "@testing-library/react";
 import { vi } from "vitest";
 import { BreadcrumbDropdown, type UnitScopeRow } from "~/components/editor/BreadcrumbDropdown";

app/components/editor/CommentLibraryList.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect, vi } from "vitest";
 import { render, screen, fireEvent } from "@testing-library/react";
 import { CommentLibraryList } from "../../../app/components/editor/CommentLibraryList";

app/components/editor/CommentTypeahead.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 // tests/web/unit/CommentTypeahead.spec.tsx
 import { describe, it, expect, vi } from "vitest";
 import { render, screen, fireEvent } from "@testing-library/react";

app/components/editor/CostItemsHost.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen, waitFor } from "@testing-library/react";
 import { vi, beforeEach, afterEach } from "vitest";
 import { CostItemsHost } from "./CostItemsHost";

app/components/editor/CostItemsPanel.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen, fireEvent, waitFor } from "@testing-library/react";
 import { vi, beforeEach, afterEach } from "vitest";
 import { CostItemsPanel } from "./CostItemsPanel";

app/components/editor/SideRail.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen } from '@testing-library/react';
 import { SideRail } from '~/components/editor/SideRail';
 

app/components/editor/UnitProgress.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen, fireEvent } from "@testing-library/react";
 import { vi } from "vitest";
 import { UnitProgress } from "~/components/editor/UnitProgress";

app/components/editor/UnitsManager.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, screen, fireEvent } from "@testing-library/react";
 import { vi, beforeEach, afterEach } from "vitest";
 import { UnitsManager, type UnitsManagerProps } from "~/components/editor/UnitsManager";

app/components/editor/batch-action-bar.test.ts

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect, vi } from 'vitest';
 import { renderToStaticMarkup } from 'react-dom/server';
 import React from 'react';

app/components/editor/item-editor-nonrich.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect, vi } from "vitest";
 import { render, screen, fireEvent } from "@testing-library/react";
 import { ItemEditor } from "../../../app/components/editor/ItemEditor";

app/components/editor/property-info-form.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { useState } from "react";
 import { render, fireEvent, screen, waitFor } from "@testing-library/react";
 import { createRoutesStub } from "react-router";

app/components/editor/side-rail-library-gate.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { SideRail } from "../../../app/components/editor/SideRail";

app/components/editor/structure-delete-modal.test.ts

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect } from 'vitest';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { createElement } from 'react';

app/components/inspection-edit/compliance-panel.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { render, fireEvent, waitFor } from "@testing-library/react";
 import { createRoutesStub, useLoaderData } from "react-router";
 import { CompliancePanel, type CompliancePanelData } from "~/components/inspection-edit/CompliancePanel";

app/components/inspection/AddPersonModal.access-notice.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 /**
  * IA-102 — adding a person to an inspection is an AUTHORIZATION act wearing
  * the clothes of a data-entry one. Naming someone on the inspection is what

app/components/inspection/LinkExpiryControl.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 /**
  * IA-36 ⑦ — one control, two places (Settings → Inspection, and the People
  * card). It expresses a DURATION, never a date: the value therefore cannot land

app/components/inspection/PeopleEditor.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 /**
  * Plan 1B Task 5 — editable People section on the inspection detail page.
  * Covers what the review checks for: renders people grouped by role kind

app/components/inspection/SendReportModal.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 /**
  * Spec 2 Task 7 — "Send report" modal. `SendReportModal` receives its
  * fetcher as a prop (independent per-mutation fetcher, B-17), so tests build

app/components/inspection/pca-narrative-panel.test.tsx

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect, vi } from "vitest";
 import { render, fireEvent } from "@testing-library/react";
 import { PcaNarrativePanel } from "~/components/inspection/PcaNarrativePanel";