From 8740ac8d2f260c6fc60deab526bca6c5df8e9582 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 21 Jul 2026 01:23:39 +0000
Subject: [PATCH 1/3] Add page/button wiring guardrails and fix audited defects

A repo-wide wiring audit found the app well-wired, with a few real gaps.
This fixes the clear-cut defects and installs a prevention layer so the
class of bug (dead buttons, orphan routes) is caught by a gate instead of
by a user noticing a control that does nothing.

Fixes:
- Wire the dead "Language and region" globe button in the workflow header
  to the codebase's disabled "coming soon" placeholder convention
  (aria-disabled + sr-only note); it was styled and labelled but had no
  handler and was not disabled.
- Correct three stale doc claims: the /documents/source redirect target in
  the site-map generator (canonical /documents/[id], not the invalid-id
  /documents/search fallback the first-redirect regex captured), and, in
  codebase-index, /applications (a redirect, not a composer mode home) plus
  the missing dsm/specifiers mode-param redirects.

Prevention:
- New AGENTS.md `page-and-button-wiring` durable rule block.
- New local ESLint rule `require-button-wiring` flagging a
  `<button type="button">` with no handler / formAction / disabled state
  (the globe-button class); scoped to src/**, mockups exempt.
- New offline tests/route-reachability.test.ts asserting every static
  production page route has an inbound nav link (catches orphan routes such
  as /tools), with a documented allowlist.
- New docs/wiring-conventions.md reference, registered in docs/README and
  cross-linked from codebase-index.
- Record the judgment-call findings (#006-#010) in the /issues ledger.

Verified offline: lint, typecheck, sitemap:check, docs:check-index, knip,
and the full unit suite (both new gates included) pass. The unrelated,
pre-existing pdf-extraction-budget process-timing test fails on origin/main
too (tracked as ledger #002).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BFM6m7WAnLuo9kqh2ExPNh
---
 AGENTS.md                                     |  33 +++++
 docs/README.md                                |   1 +
 docs/codebase-index.md                        |   5 +-
 docs/outstanding-issues.md                    |  21 ++-
 docs/site-map.md                              |   2 +-
 docs/wiring-conventions.md                    | 100 +++++++++++++
 eslint-rules/require-button-wiring.mjs        |  80 ++++++++++
 eslint.config.mjs                             |  34 ++++-
 scripts/generate-site-map.ts                  |   5 +
 .../master-search-header.tsx                  |  11 +-
 tests/route-reachability.test.ts              | 137 ++++++++++++++++++
 tests/ui-tools.spec.ts                        |   4 +-
 12 files changed, 415 insertions(+), 18 deletions(-)
 create mode 100644 docs/wiring-conventions.md
 create mode 100644 eslint-rules/require-button-wiring.mjs
 create mode 100644 tests/route-reachability.test.ts

diff --git a/AGENTS.md b/AGENTS.md
index bc8c6e90a..84b5c4293 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -174,6 +174,39 @@ When a branch or PR review completes, record the reviewed branch/ref, HEAD SHA,
 
 <!-- END:process-hardening -->
 
+<!-- BEGIN:page-and-button-wiring -->
+
+# Page and button wiring
+
+Interactive controls and routes follow conventions the codebase already holds to. Before adding
+or moving a button, link, or route, read `docs/wiring-conventions.md`. A control that advertises an
+action must perform one; a page that ships must be reachable.
+
+- **Buttons.** Every interactive `<button>` must do something: an `onClick`, a `type="submit"`
+  inside a `<form onSubmit>`, or navigation (wrap it in a `<Link>` / call `router.push`). A control
+  whose feature is not yet built uses the explicit disabled-placeholder pattern — `disabled` or
+  `aria-disabled="true"` + `title="… — coming soon"` + an `sr-only` note wired via
+  `aria-describedby` (see `favourites-hub.tsx`). **Never** ship a styled, `aria-label`led button
+  with no handler and no disabled state — that was the "Language and region" defect fixed
+  2026-07-21.
+- **Navigation.** Internal navigation uses `<Link>`, `router.push`, or server `redirect()` — never
+  a raw `<a href="/…">` to an internal route. Build hrefs from the existing sources
+  (`src/lib/app-modes.ts`, `src/lib/tools-catalog.ts`, `src/lib/universal-search.ts`), not
+  hardcoded strings scattered across components.
+- **New-route checklist.** Add the page → link it from real nav (sidebar / launcher / mode home /
+  search) → `npm run sitemap:update` → document it in `docs/codebase-index.md` → add a
+  reachability/coverage assertion. A production page route with no inbound link is an orphan.
+- **Gates.** `eslint-rules/require-button-wiring.mjs` (in `npm run lint`) fails on an un-wired
+  `<button>`; `tests/route-reachability.test.ts` (in `npm run test`) fails when a production page
+  route has no inbound nav link unless it is consciously added to that test's documented
+  allowlist (redirect targets / legacy-compat routes). Both run in `verify:cheap` and CI. Mockups
+  (`src/app/mockups/**`, `*-mockups.tsx`) are design-scratch and exempt from both.
+- **Never** add a production page route without either an inbound link or a documented
+  reachability allowlist entry plus an `/issues` note, and never silence the button-wiring rule
+  with a blanket disable — wire the control or make it an explicit placeholder.
+
+<!-- END:page-and-button-wiring -->
+
 <!-- BEGIN:supabase-project-safety -->
 
 # Supabase project safety
diff --git a/docs/README.md b/docs/README.md
index 27bbd73d1..0b743e80c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -23,6 +23,7 @@ npm run docs:check-links
 ## Architecture
 
 - [frontend-architecture.md](frontend-architecture.md) — shell, routing, dashboard module structure
+- [wiring-conventions.md](wiring-conventions.md) — page/button wiring conventions and the dead-button / orphan-route gates
 - [deployment-architecture.md](deployment-architecture.md) — app/worker/Supabase deployment topology
 - [ingestion-state-machine.md](ingestion-state-machine.md) — ingestion job lifecycle and states
 - [design-system.md](design-system.md) — tokens, primitives, styling conventions
diff --git a/docs/codebase-index.md b/docs/codebase-index.md
index 35571a478..0ad69d458 100644
--- a/docs/codebase-index.md
+++ b/docs/codebase-index.md
@@ -299,11 +299,12 @@ sequenceDiagram
 
 One shared composer (`master-search-header.tsx`) serves every mode. Placement:
 
-- **Mode homes** (`/services`, `/forms`, `/favourites`, `/differentials`, `/formulation`, `/applications`, and dashboard homes): inline in the hero via the `mode-home-composer-slot` portal, on phone and tablet+ alike.
+- **Mode homes** (`/services`, `/forms`, `/favourites`, `/differentials`, `/formulation`, `/tools`, and dashboard homes): inline in the hero via the `mode-home-composer-slot` portal, on phone and tablet+ alike. (`/applications` is a redirect to `/tools`, not a composer surface.)
 - **Result and detail views**: fixed bottom dock on phone (compact variant on submitted searches), sticky top from `sm` up.
-- **Results routing**: standalone routes own their submitted searches via `?q=…&run=1` (`/services` → `ServicesNavigatorPage`, `/forms` → `FormsSearchResultsPage`, `/differentials` → `DifferentialsHome` results view, `/formulation` → local mechanism results, `/favourites` filters the command library in place). Answer, Documents, and Prescribing submitted searches render inside `ClinicalDashboard` — intentional, since they need retrieval/answer state. `/?mode=favourites` redirects to `/favourites`; `/?mode=differentials` redirects to `/differentials`; `/?mode=formulation` redirects to `/formulation`.
+- **Results routing**: standalone routes own their submitted searches via `?q=…&run=1` (`/services` → `ServicesNavigatorPage`, `/forms` → `FormsSearchResultsPage`, `/differentials` → `DifferentialsHome` results view, `/formulation` → local mechanism results, `/favourites` filters the command library in place). Answer, Documents, and Prescribing submitted searches render inside `ClinicalDashboard` — intentional, since they need retrieval/answer state. `/?mode=favourites` redirects to `/favourites`; `/?mode=differentials` redirects to `/differentials`; `/?mode=dsm` redirects to `/dsm`; `/?mode=specifiers` redirects to `/specifiers`; `/?mode=formulation` redirects to `/formulation`.
 - **Intentionally composer-free routes**: `/differentials/presentations/*` (comparison workflow owns its chrome), `/documents/[id]` viewer (has its own in-document ask composer), `/documents/source/*` (document flow owns mobile chrome). Do not re-flag these in search-consistency audits.
 - **Local filter fields** (sidebar "Search chats", document drawer "Find a document"/"Find a source PDF") are scoped filters, not global search; they share the `fieldControlWithIcon`/`fieldIcon` primitives.
+- **Wiring conventions** for buttons and route navigation (and the gates that enforce them — the dead-button ESLint rule and the orphan-route reachability test) live in `docs/wiring-conventions.md`.
 
 ---
 
diff --git a/docs/outstanding-issues.md b/docs/outstanding-issues.md
index 38620f445..d5328662e 100644
--- a/docs/outstanding-issues.md
+++ b/docs/outstanding-issues.md
@@ -27,17 +27,22 @@ Durable, cross-session memory of everything still outstanding for this repo: ope
 - Resolving an item moves its row to **Resolved / archive** with the date and a one-line outcome —
   rows are archived, not deleted, so the history stays auditable.
 
-<!-- issues:next-id=006 -->
+<!-- issues:next-id=011 -->
 
 ## Open items
 
-| ID   | Pri | Type | Summary                                          | Detail / next action                                                                                                                                                                                                                                                                                                  | Source                                                                                  | Added      |
-| ---- | --- | ---- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ---------- |
-| #001 | P2  | task | Semantic reranking still gated off               | `RAG_SEMANTIC_RERANK_ENABLED=false` from PR #901. Do not enable until the provider-backed 36/36 retrieval-quality gate **and** an ambiguity-focused canary are explicitly approved and recorded.                                                                                                                      | `docs/process-hardening.md` (Semantic reranking rollout debt); PR #901                  | 2026-07-21 |
-| #002 | P2  | task | Process-ownership fix not yet isolated on `main` | `scripts/run-eval-safe.mjs` still terminates residual repo processes broadly. Isolate the child-owned `terminateOwnedProcessTree(child.pid)` approach + the regression test proving unrelated Vitest/Playwright/Next processes survive; verify statically — do **not** start a provider-backed eval.                  | `docs/process-hardening.md` (High-priority local process ownership)                     | 2026-07-21 |
-| #003 | P2  | task | Staging tenancy release evidence outstanding     | The provider-backed A/B tenancy regression is intentionally outside local + PR gates. Run the standalone manual/nightly workflow and attach a recent green evidence artifact **before release**.                                                                                                                      | `docs/process-hardening.md`; `docs/staging-tenancy-release-evidence.md`                 | 2026-07-21 |
-| #004 | P3  | rec  | Rescope provider-gated RAG safety ideas          | If explicitly approved, rescope only the still-relevant preflight utilities/tests (answer-quality thresholds, cost-cap preflight, deep-health) against current `main`; keep live OpenAI/Supabase validation separate. Do **not** replay the stale 754-line retrieval migration/worktree wholesale.                    | `docs/process-hardening.md` (Provider-gated RAG safety ideas)                           | 2026-07-21 |
-| #005 | P3  | rec  | `finalScore` saturates at clamp ceiling          | Base + ~40 stacked boosts routinely exceed 1.0, so strong matches tie at 1.0 and order by an arbitrary `document_id` tiebreak. If ranking is ever revisited, break ties by the **pre-clamp** score rather than raising the `[0,1]` ceiling (downstream gates assume `[0,1]`). Not a defect on the current golden set. | `docs/rag-hybrid-findings-and-todo.md` P1 item 4; `src/lib/rag/clinical-search.ts:1362` | 2026-07-21 |
+| ID   | Pri | Type  | Summary                                                 | Detail / next action                                                                                                                                                                                                                                                                                                  | Source                                                                                       | Added      |
+| ---- | --- | ----- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------- |
+| #001 | P2  | task  | Semantic reranking still gated off                      | `RAG_SEMANTIC_RERANK_ENABLED=false` from PR #901. Do not enable until the provider-backed 36/36 retrieval-quality gate **and** an ambiguity-focused canary are explicitly approved and recorded.                                                                                                                      | `docs/process-hardening.md` (Semantic reranking rollout debt); PR #901                       | 2026-07-21 |
+| #002 | P2  | task  | Process-ownership fix not yet isolated on `main`        | `scripts/run-eval-safe.mjs` still terminates residual repo processes broadly. Isolate the child-owned `terminateOwnedProcessTree(child.pid)` approach + the regression test proving unrelated Vitest/Playwright/Next processes survive; verify statically — do **not** start a provider-backed eval.                  | `docs/process-hardening.md` (High-priority local process ownership)                          | 2026-07-21 |
+| #003 | P2  | task  | Staging tenancy release evidence outstanding            | The provider-backed A/B tenancy regression is intentionally outside local + PR gates. Run the standalone manual/nightly workflow and attach a recent green evidence artifact **before release**.                                                                                                                      | `docs/process-hardening.md`; `docs/staging-tenancy-release-evidence.md`                      | 2026-07-21 |
+| #004 | P3  | rec   | Rescope provider-gated RAG safety ideas                 | If explicitly approved, rescope only the still-relevant preflight utilities/tests (answer-quality thresholds, cost-cap preflight, deep-health) against current `main`; keep live OpenAI/Supabase validation separate. Do **not** replay the stale 754-line retrieval migration/worktree wholesale.                    | `docs/process-hardening.md` (Provider-gated RAG safety ideas)                                | 2026-07-21 |
+| #005 | P3  | rec   | `finalScore` saturates at clamp ceiling                 | Base + ~40 stacked boosts routinely exceed 1.0, so strong matches tie at 1.0 and order by an arbitrary `document_id` tiebreak. If ranking is ever revisited, break ties by the **pre-clamp** score rather than raising the `[0,1]` ceiling (downstream gates assume `[0,1]`). Not a defect on the current golden set. | `docs/rag-hybrid-findings-and-todo.md` P1 item 4; `src/lib/rag/clinical-search.ts:1362`      | 2026-07-21 |
+| #006 | P2  | issue | Globe "Language & region" button had no handler         | Fixed in this PR to the disabled "Coming soon" placeholder convention (`aria-disabled` + sr-only note). Wire to a real language/region settings screen when one exists, then drop the placeholder state.                                                                                                              | `src/components/clinical-dashboard/master-search-header.tsx:1829`; session 2026-07-21        | 2026-07-21 |
+| #007 | P3  | rec   | `/tools` vs `/?mode=tools` parallel Tools entry points  | `/tools` (standalone `ApplicationsLauncherPage`) has no inbound in-app link; the sidebar Tools item uses `/?mode=tools`. Decide the canonical entry point and wire nav consistently, or drop the standalone `/tools` page + `/applications` redirect. Currently allowlisted in `tests/route-reachability.test.ts`.    | `src/app/tools/page.tsx`; `src/app/applications/route.ts`                                    | 2026-07-21 |
+| #008 | P3  | rec   | Dead href builders in `document-flow-routes.ts`         | `documentReaderHref` / `documentEvidenceHref` (+ `*MockHref` variants) are exported but never called in `src`. Remove them, or start using them for the `/documents/source*` compatibility links.                                                                                                                     | `src/lib/document-flow-routes.ts`                                                            | 2026-07-21 |
+| #009 | P3  | rec   | Confirm `/api/jobs` is intentionally server/ops-only    | No client `fetch()` reaches `/api/jobs` (only tests import it). Confirm it is a deliberate ops/manual surface; if abandoned, remove it.                                                                                                                                                                               | `src/app/api/jobs/route.ts`                                                                  | 2026-07-21 |
+| #010 | P3  | task  | Un-built "Coming soon" controls across forms/favourites | ~10 disabled placeholders (forms refine/reset, favourites sort/add/new-set, move-to-set, remove-favourite). Correctly flagged (`aria-disabled` + "Coming soon"), not defects — wire when the underlying features land.                                                                                                | `forms-search-results-page.tsx`; `favourites-hub.tsx`; `favourites-command-library-page.tsx` | 2026-07-21 |
 
 ## Resolved / archive
 
diff --git a/docs/site-map.md b/docs/site-map.md
index 2e335f073..92210148a 100644
--- a/docs/site-map.md
+++ b/docs/site-map.md
@@ -1071,7 +1071,7 @@ This file is generated by `npm run sitemap:update`. Run `npm run sitemap:check`
 
 - `/applications` - Redirects to `/tools`. Source: `src/app/applications/route.ts`.
 - `/differentials/presentations` - Redirects to `/differentials/presentations/[workflow-slug]`. Source: `src/app/differentials/presentations/route.ts`.
-- `/documents/source` - Redirects to `/documents/search`. Source: `src/app/documents/source/page.tsx`.
+- `/documents/source` - Redirects to `/documents/[id]`. Source: `src/app/documents/source/page.tsx`.
 - `/medications` - Redirects to `/?mode=prescribing`. Source: `src/app/medications/route.ts`.
 - `/mockups/favourites-hub` - Redirects to `/favourites`. Source: `src/app/mockups/favourites-hub/page.tsx`.
 - `/mockups/medication-prescribing` - Redirects to `/medications/acamprosate`. Source: `src/app/mockups/medication-prescribing/page.tsx`.
diff --git a/docs/wiring-conventions.md b/docs/wiring-conventions.md
new file mode 100644
index 000000000..a4f36d735
--- /dev/null
+++ b/docs/wiring-conventions.md
@@ -0,0 +1,100 @@
+# Page and button wiring conventions
+
+How interactive controls and routes are wired in this app, and the gates that keep them wired.
+The root `AGENTS.md` (`page-and-button-wiring` block) is the short rule; this is the detail.
+
+A repo-wide audit (2026-07-21) found the app is well-wired — the conventions below are ones the
+codebase already holds to. The point of writing them down, plus the two gates, is to keep new work
+from regressing: a control that advertises an action must perform one, and a page that ships must be
+reachable.
+
+## Button wiring
+
+Every interactive `<button>` must resolve to a behaviour:
+
+- **Action** — `<button type="button" onClick={handler}>`. `type="button"` is used for every
+  non-submit button, so it does nothing on its own; it **must** carry an `onClick` (or another
+  handler).
+- **Form submit** — `<button type="submit">` inside a `<form onSubmit={handler}>`, where the handler
+  calls `event.preventDefault()`.
+- **Navigation** — wrap it in a Next `<Link>`, or call `router.push(...)` from an `onClick`. Do not
+  navigate by other side channels.
+- **Busy / async** — route through the shared busy-state contract in `src/components/ui-primitives.tsx`
+  (spinner + `disabled` + live-region announcement), not an ad-hoc disabled flag.
+
+For a feature that is **not yet built**, use the explicit disabled-placeholder pattern — never a fake
+or empty handler. The reference markup is `favourites-hub.tsx`:
+
+```tsx
+<button
+  type="button"
+  aria-disabled="true"
+  aria-describedby="thing-unavailable"
+  className="… cursor-not-allowed opacity-60 …"
+  title="Thing — coming soon"
+>
+  <Icon aria-hidden="true" />
+</button>
+<span id="thing-unavailable" className="sr-only">
+  Thing is coming soon.
+</span>
+```
+
+**Read-only indicators are not controls.** The shared `ToggleSwitch` (`ui-primitives.tsx`) renders an
+operable `role="switch"` only when an `onToggle` is passed; without it, it is a presentational
+indicator by design — a "switch" with no handler is intentional, not a dead control.
+
+**Never** ship a styled, `aria-label`led `<button type="button">` with no handler and no disabled
+state. That was the "Language and region" globe defect (`master-search-header.tsx`, fixed 2026-07-20)
+and is exactly what the ESLint gate below now catches.
+
+## Navigation and route wiring
+
+- **Internal navigation** uses `<Link>`, `router.push` / `router.replace`, or a server `redirect()` —
+  **never** a raw `<a href="/…">` to an internal route (raw anchors bypass client routing/prefetch).
+- **Build hrefs from the canonical sources**, not hardcoded strings scattered across components:
+  - `src/lib/app-modes.ts` (`appModeHomeHref`) — the per-mode home URL.
+  - `src/lib/tools-catalog.ts` — Tools launcher tile targets.
+  - `src/lib/universal-search.ts` — universal-search result hrefs.
+- **Self-contained route families** may own a local builder — e.g. Therapy Compass derives every screen
+  URL from `screenHref(screen)` in `src/components/therapy-compass/bindings.tsx`. Keep new destinations
+  in that builder so state stays a real URL.
+
+## Adding a new route (checklist)
+
+1. Create the `page.tsx`.
+2. **Link it from real navigation** — sidebar, a launcher tile, a mode home, search, or a `redirect()`.
+   A production page with no inbound link is an **orphan** (reachable only by typing the URL).
+3. Run `npm run sitemap:update` to regenerate `docs/site-map.md`.
+4. Document the route in `docs/codebase-index.md` (the product-pages table).
+5. The reachability gate then enforces step 2 automatically (see below).
+
+## Mockups are exempt
+
+Design-scratch mockups — `src/app/mockups/**` (404 in production), the `*-mockups/` component
+directories, and `*-mockups.tsx` singletons — have intentionally inert buttons and are not required to
+be linked. Production code may not import them (`no-restricted-imports` in `eslint.config.mjs`), and
+both wiring gates skip them.
+
+## The gates
+
+| Gate                                       | Catches                                                   | Runs in                             |
+| ------------------------------------------ | --------------------------------------------------------- | ----------------------------------- |
+| `eslint-rules/require-button-wiring.mjs`   | `<button type="button">` with no handler / disabled state | `npm run lint` → `verify:cheap`, CI |
+| `tests/route-reachability.test.ts`         | static production page routes with no inbound nav link    | `npm run test` → `verify:cheap`, CI |
+| `tests/site-map.test.ts` / `sitemap:check` | routes / nav hrefs missing from `docs/site-map.md`        | `npm run test`, `verify:cheap`, CI  |
+| `npm run check:knip`                       | dead exports / orphan modules (e.g. unused href builders) | `verify:cheap`, CI                  |
+
+Intentional exceptions are documented, not silenced:
+
+- An orphan route that is deliberately unlinked (a redirect target, a legacy-compat page, or a decision
+  still pending) goes in the `REACHABILITY_ALLOWLIST` in `tests/route-reachability.test.ts` **with a
+  reason**, and — if it is a decision to revisit — a row in `docs/outstanding-issues.md`.
+- Do not silence `require-button-wiring` with a blanket disable — wire the control, or make it an
+  explicit disabled placeholder.
+
+## Known wiring debts
+
+Tracked in `docs/outstanding-issues.md` (`/issues`): the `/tools` vs `/?mode=tools` duplicate Tools
+entry point, the unused `document-flow-routes.ts` href builders, the server-only `/api/jobs` endpoint,
+and the un-built "coming soon" placeholders across forms/favourites.
diff --git a/eslint-rules/require-button-wiring.mjs b/eslint-rules/require-button-wiring.mjs
new file mode 100644
index 000000000..c3e37f37b
--- /dev/null
+++ b/eslint-rules/require-button-wiring.mjs
@@ -0,0 +1,80 @@
+/**
+ * Local ESLint rule: an explicit `<button type="button">` must be wired to a
+ * behaviour — an event handler, a form action, or an explicit disabled state.
+ *
+ * `type="button"` opts a button out of form submission, so on its own it does
+ * *nothing* when clicked. Such a button that carries no `onClick` (or other
+ * `on*` handler), no `formAction`, and no `disabled`/`aria-disabled` state is a
+ * control that advertises an action it cannot perform — the "Language and
+ * region" globe defect (master-search-header.tsx, fixed 2026-07-20). This rule
+ * makes that class of dead button fail `npm run lint`.
+ *
+ * Deliberately narrow to keep false positives at zero:
+ *  - Only `<button>` elements whose `type` is the string literal `"button"` are
+ *    inspected. Submit/reset buttons and buttons with a dynamic/absent `type`
+ *    (which may default to submit inside a <form>) are left alone.
+ *  - Any spread ({...props}) skips the element, since a handler may arrive
+ *    dynamically (same escape hatch as require-lucide-icon-aria).
+ *  - An unbuilt feature is expressed the codebase's way — `disabled` or
+ *    `aria-disabled` (typically with a "coming soon" note) — and passes.
+ *
+ * There is no auto-fix: wiring a button requires knowing what it should do, so
+ * the fix is a human decision (add the handler, or make it an explicit
+ * disabled placeholder). Design-scratch mockups are exempt via eslint.config.mjs.
+ */
+
+/** Attribute names that mark a <button type="button"> as wired. */
+const EXPLICIT_WIRING_ATTRS = new Set(["disabled", "aria-disabled", "formAction"]);
+
+/** True when the JSX attribute is `type="button"` (string literal). */
+function isTypeButton(attr) {
+  if (attr.type !== "JSXAttribute") return false;
+  if (attr.name.type !== "JSXIdentifier" || attr.name.name !== "type") return false;
+  const { value } = attr;
+  if (!value) return false;
+  if (value.type === "Literal") return value.value === "button";
+  // `type={"button"}` — a literal wrapped in an expression container.
+  if (value.type === "JSXExpressionContainer" && value.expression.type === "Literal") {
+    return value.expression.value === "button";
+  }
+  return false;
+}
+
+/** True when the attribute wires behaviour: any `on*` handler or an explicit signal. */
+function isWiringAttr(attr) {
+  if (attr.type !== "JSXAttribute") return false;
+  if (attr.name.type !== "JSXIdentifier") return false;
+  const name = attr.name.name;
+  return name.startsWith("on") || EXPLICIT_WIRING_ATTRS.has(name);
+}
+
+/** @type {import("eslint").Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        'Require an explicit `<button type="button">` to carry an event handler, formAction, or an explicit disabled state.',
+    },
+    schema: [],
+    messages: {
+      unwired:
+        'This <button type="button"> has no onClick (or other handler), no formAction, and no disabled/aria-disabled state — it does nothing when clicked. Wire it, or make it an explicit disabled "coming soon" placeholder.',
+    },
+  },
+  create(context) {
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type !== "JSXIdentifier" || node.name.name !== "button") return;
+        // A spread may inject a handler dynamically — don't flag.
+        if (node.attributes.some((attr) => attr.type === "JSXSpreadAttribute")) return;
+        // Only inspect explicit type="button"; submit/reset/dynamic are out of scope.
+        if (!node.attributes.some((attr) => isTypeButton(attr))) return;
+        if (node.attributes.some((attr) => isWiringAttr(attr))) return;
+        context.report({ node, messageId: "unwired" });
+      },
+    };
+  },
+};
+
+export default rule;
diff --git a/eslint.config.mjs b/eslint.config.mjs
index cc53f9aa8..4861899ce 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -3,6 +3,22 @@ import nextVitals from "eslint-config-next/core-web-vitals";
 import nextTs from "eslint-config-next/typescript";
 
 import requireLucideIconAria from "./eslint-rules/require-lucide-icon-aria.mjs";
+import requireButtonWiring from "./eslint-rules/require-button-wiring.mjs";
+
+// Shared `local` plugin object. ESLint flat config requires every config block
+// that references a plugin namespace to point at the *same* object, so the two
+// local rules below — which want different mockup-ignore scopes — share this one.
+const localRulesPlugin = {
+  rules: {
+    "require-lucide-icon-aria": requireLucideIconAria,
+    "require-button-wiring": requireButtonWiring,
+  },
+};
+
+// Design-scratch mockups (404 in production) are exempt from the local rules.
+// This is the repo's full mockup surface: the `/mockups/*` routes, the
+// `*-mockups/` component directories, and the `*-mockups.tsx` singletons.
+const MOCKUP_IGNORES = ["**/*mockup*", "**/mockups/**", "**/*-mockups/**", "**/*-mockups.tsx"];
 
 const eslintConfig = defineConfig([
   ...nextVitals,
@@ -29,13 +45,25 @@ const eslintConfig = defineConfig([
   {
     files: ["**/*.{jsx,tsx}"],
     ignores: ["**/*mockup*", "**/mockups/**"],
-    plugins: {
-      local: { rules: { "require-lucide-icon-aria": requireLucideIconAria } },
-    },
+    plugins: { local: localRulesPlugin },
     rules: {
       "local/require-lucide-icon-aria": "error",
     },
   },
+  // A styled, labelled `<button type="button">` with no handler is a dead control
+  // (the "Language and region" globe class, fixed 2026-07-20). Require an explicit
+  // non-submit button to carry a handler/formAction or an explicit disabled state.
+  // Scoped to production source (`src/**`): this is a product-UX concern, so test
+  // fixtures that render a bare <button> to exercise a slot are out of scope. The
+  // full mockup-ignore set exempts the `*-mockups/` design-scratch previews.
+  {
+    files: ["src/**/*.{jsx,tsx}"],
+    ignores: MOCKUP_IGNORES,
+    plugins: { local: localRulesPlugin },
+    rules: {
+      "local/require-button-wiring": "error",
+    },
+  },
   // Import boundary: production source must not import design-scratch mockup
   // modules. Every legitimate mockup import lives under `src/app/mockups/**` (all
   // 404 in production) or inside the `*-mockups` component sources themselves;
diff --git a/scripts/generate-site-map.ts b/scripts/generate-site-map.ts
index b2110bdd5..e19b99537 100644
--- a/scripts/generate-site-map.ts
+++ b/scripts/generate-site-map.ts
@@ -43,6 +43,11 @@ const productRouteHandlerPaths = new Set(["/applications", "/differentials/prese
 const documentedRedirectTargets: Record<string, string> = {
   "/applications": "/tools",
   "/differentials/presentations": "/differentials/presentations/[workflow-slug]",
+  // The source page redirects a valid id to the canonical `/documents/[id]` viewer
+  // (page.tsx line 20) and only falls back to `/documents/search` for an invalid id
+  // (line 14). Pin the canonical target here so the generated map does not report the
+  // invalid-id fallback that its first-`redirect()` regex would otherwise capture.
+  "/documents/source": "/documents/[id]",
   "/medications": "/?mode=prescribing",
 };
 
diff --git a/src/components/clinical-dashboard/master-search-header.tsx b/src/components/clinical-dashboard/master-search-header.tsx
index a17b51dbd..1487bd43a 100644
--- a/src/components/clinical-dashboard/master-search-header.tsx
+++ b/src/components/clinical-dashboard/master-search-header.tsx
@@ -1828,12 +1828,17 @@ export function MasterSearchHeader({
               <>
                 <button
                   type="button"
-                  className="universal-header-icon-control grid h-tap w-tap shrink-0 place-items-center rounded-full text-[color:var(--text-muted)] transition hover:bg-[color:var(--surface-subtle)] hover:text-[color:var(--clinical-accent)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)]"
-                  aria-label="Open language and region settings"
-                  title="Language and region"
+                  aria-disabled="true"
+                  aria-describedby="workflow-language-region-unavailable"
+                  className="universal-header-icon-control grid h-tap w-tap shrink-0 cursor-not-allowed place-items-center rounded-full text-[color:var(--text-muted)] opacity-60 transition hover:bg-[color:var(--surface-subtle)] hover:text-[color:var(--clinical-accent)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--focus)]"
+                  aria-label="Language and region settings (coming soon)"
+                  title="Language and region — coming soon"
                 >
                   <Globe2 className="h-5 w-5" aria-hidden />
                 </button>
+                <span id="workflow-language-region-unavailable" className="sr-only">
+                  Language and region settings are coming soon.
+                </span>
                 <span className="hidden h-8 w-px bg-[color:var(--border)] sm:block" aria-hidden />
                 <button
                   type="button"
diff --git a/tests/route-reachability.test.ts b/tests/route-reachability.test.ts
new file mode 100644
index 000000000..e4e900fca
--- /dev/null
+++ b/tests/route-reachability.test.ts
@@ -0,0 +1,137 @@
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { appModeDefinitions, appModeHomeHref } from "@/lib/app-modes";
+import { tools } from "@/components/tools-page-mockups/tool-fixtures";
+import { collectSiteMapData } from "../scripts/generate-site-map";
+
+/**
+ * Orphan-route guard. `site-map.test.ts` proves every route is *documented*;
+ * this proves every static production page route is *reachable* — i.e. some
+ * in-app navigation actually links to it. A page you can only reach by typing
+ * its URL (the `/tools` class) is an orphan and must be either wired into nav
+ * or added, with a reason, to REACHABILITY_ALLOWLIST below.
+ *
+ * Scope: static page routes only. Dynamic `[slug]` detail routes are reached
+ * via href builders from live/seeded data (`universal-search.ts`, registry
+ * loaders); their targets are covered by `site-map.test.ts`'s documented-href
+ * assertions, and pattern-matching interpolated hrefs here would be brittle.
+ * Mockups (`src/app/mockups/**`, `*-mockups/**`) are design-scratch and 404 in
+ * production, so a link *from* a mockup does not count and mockup routes are
+ * not required to be linked.
+ */
+
+const repoRoot = process.cwd();
+const srcRoot = path.join(repoRoot, "src");
+
+/** Intentionally-unlinked static page routes, each with the reason it is exempt. */
+const REACHABILITY_ALLOWLIST = new Map<string, string>([
+  [
+    "/tools",
+    "Orphan parallel to /?mode=tools; nothing links to the standalone page. Tracked as issue #007 (decide the canonical Tools entry point). Reachable via URL and the /applications redirect.",
+  ],
+  [
+    "/documents/source",
+    "Legacy compatibility redirect target reached by external/legacy deep links, not in-app navigation (frontend-architecture.md).",
+  ],
+  [
+    "/documents/source/evidence",
+    "Legacy compatibility redirect target reached by external/legacy deep links, not in-app navigation (frontend-architecture.md).",
+  ],
+]);
+
+function isMockupPath(relPosix: string) {
+  return relPosix.toLowerCase().includes("mockup");
+}
+
+function pathOnly(href: string) {
+  return href.split(/[?#]/)[0] || "/";
+}
+
+function collectSourceFiles(dir: string): { rel: string; content: string }[] {
+  const out: { rel: string; content: string }[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...collectSourceFiles(abs));
+    } else if (/\.(ts|tsx)$/.test(entry.name)) {
+      const rel = path.relative(repoRoot, abs).split(path.sep).join("/");
+      if (!isMockupPath(rel)) out.push({ rel, content: readFileSync(abs, "utf8") });
+    }
+  }
+  return out;
+}
+
+const sourceFiles = collectSourceFiles(srcRoot);
+
+/** Route targets produced by the canonical nav builders (never bare string literals). */
+const builderTargets = new Set<string>();
+for (const mode of appModeDefinitions) {
+  const href = ("href" in mode ? mode.href : undefined) ?? appModeHomeHref(mode.id);
+  builderTargets.add(pathOnly(href));
+}
+for (const tool of tools) builderTargets.add(pathOnly(tool.href));
+
+// Therapy Compass owns a self-contained route family whose fixed screens are
+// navigated via a local `screenHref(screen)` builder (`go*()` → router.push),
+// so the sub-route paths never appear as literals a static scan could see. Read
+// the family's reserved segments straight from the source of truth so new screens
+// are picked up automatically. See src/components/therapy-compass/bindings.tsx.
+const tcBindingsSrc = readFileSync(path.join(srcRoot, "components/therapy-compass/bindings.tsx"), "utf8");
+const tcBase = tcBindingsSrc.match(/const BASE = "([^"]+)"/)?.[1] ?? "/therapy-compass";
+const tcReserved = tcBindingsSrc.match(/RESERVED_SEGMENTS = new Set\(\[([^\]]*)]\)/);
+for (const match of (tcReserved?.[1] ?? "").matchAll(/"([^"]+)"/g)) {
+  builderTargets.add(`${tcBase}/${match[1]}`);
+}
+
+/** A route is reachable if a builder emits it, or a non-mockup source file links to it. */
+function referenceRegExp(route: string) {
+  const escaped = route.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // Require a navigation context immediately before the path literal — an `href`
+  // attribute/prop or a router/redirect call — so that route-ownership checks
+  // (`pathname === "/tools"`), switch cases, and comment mentions do NOT count as
+  // a link. Left boundary is the opening quote/backtick; the right boundary
+  // forbids a path-continuation char so `/dsm/compare` does not match inside
+  // `/dsm/comparexyz` but does match `/dsm/compare"` or `/dsm/compare?q=…`.
+  const navLeadIn = "(?:href\\s*[=:]\\s*\\{?\\s*|(?:push|replace|prefetch|redirect|permanentRedirect)\\s*\\(\\s*)";
+  return new RegExp(navLeadIn + "[\"'`]" + escaped + "(?![A-Za-z0-9_\\-/])");
+}
+
+function isReachable(route: string, selfFile: string) {
+  if (builderTargets.has(route)) return true;
+  const re = referenceRegExp(route);
+  return sourceFiles.some((file) => file.rel !== selfFile && re.test(file.content));
+}
+
+const staticPageRoutes = collectSiteMapData()
+  .pageRoutes.map((route) => ({ route: route.route, file: route.file.split(path.sep).join("/") }))
+  .filter(
+    (entry) =>
+      entry.route !== "/" && // app root, trivially the entry point
+      !entry.route.includes("[") && // dynamic families reached via builders (see header)
+      !entry.route.startsWith("/mockups"),
+  );
+
+describe("route reachability", () => {
+  it("every static production page route is linked from in-app navigation", () => {
+    const orphans = staticPageRoutes
+      .filter((entry) => !REACHABILITY_ALLOWLIST.has(entry.route))
+      .filter((entry) => !isReachable(entry.route, entry.file))
+      .map((entry) => entry.route);
+
+    expect(
+      orphans,
+      `Orphan page route(s) with no inbound <Link>/router.push/redirect. Wire them into nav ` +
+        `(sidebar/launcher/mode home/search), or add to REACHABILITY_ALLOWLIST with a reason: ${orphans.join(", ")}`,
+    ).toEqual([]);
+  });
+
+  it("reachability allowlist has no stale entries", () => {
+    const routes = new Set(staticPageRoutes.map((entry) => entry.route));
+    for (const route of REACHABILITY_ALLOWLIST.keys()) {
+      expect(routes.has(route), `${route} is allowlisted but is no longer a static page route`).toBe(true);
+    }
+  });
+});
diff --git a/tests/ui-tools.spec.ts b/tests/ui-tools.spec.ts
index 38edf578b..a3fffd51c 100644
--- a/tests/ui-tools.spec.ts
+++ b/tests/ui-tools.spec.ts
@@ -1855,7 +1855,9 @@ test.describe("Clinical KB tools launcher", () => {
     await expect(mobileComparison.getByRole("button", { name: "Column filters unavailable" })).toBeDisabled();
     await expect(mobileComparison.getByText("Delirium", { exact: true }).first()).toBeVisible();
     await expect(mobileComparison.getByText("Substance intoxication", { exact: true }).first()).toBeVisible();
-    await expect(page.getByRole("button", { name: "Open language and region settings" })).toBeVisible();
+    const languageControl = page.getByRole("button", { name: "Language and region settings (coming soon)" });
+    await expect(languageControl).toBeVisible();
+    await expect(languageControl).toHaveAttribute("aria-disabled", "true");
     await expect(page.getByRole("button", { name: "Start a new comparison" })).toBeVisible();
     await expect(page.getByTestId("global-search-input")).toHaveCount(0);
     await expect(page.getByText("Service details")).toHaveCount(0);

From 564ea89ac37332eb6ac6103ee6bd41ddfd7df806 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 21 Jul 2026 03:01:44 +0000
Subject: [PATCH 2/3] refactor(wiring): tighten button-wiring rule +
 reachability guard per review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses the CodeRabbit review threads on the new wiring tooling:

- require-button-wiring: only onClick (not any on*) and disabled/aria-disabled
  count as wired; drop formAction (no submit effect on type=button). onFocus/
  onMouseEnter no longer mask a click that does nothing.
- eslint.config MOCKUP_IGNORES: replace the broad **/*mockup* substring (which
  would exempt arbitrary production files) with the precise documented surface
  (src/app/mockups/**, *-mockups/, *-mockup(s).tsx); widen the rule's file scope
  to src/**/*.{js,jsx,ts,tsx}.
- route-reachability test: scan .js/.jsx source too; also seed builderTargets
  with the query-bearing appModeHomeHref variant (document/namespaced-search
  routes); fail loudly if therapy-compass BASE/RESERVED_SEGMENTS can't be parsed
  instead of silently checking nothing.
- Align the globe-defect fix date to 2026-07-21 across the doc + rule + config.

Verified: npm run lint (0 problems — no button newly flagged), typecheck,
route-reachability (2/2), format:check.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013f523gDfoBXPYT4H9vXRkE
---
 docs/wiring-conventions.md             |  2 +-
 eslint-rules/require-button-wiring.mjs | 26 +++++++++++---------
 eslint.config.mjs                      | 14 ++++++-----
 tests/route-reachability.test.ts       | 33 +++++++++++++++++++++-----
 4 files changed, 51 insertions(+), 24 deletions(-)

diff --git a/docs/wiring-conventions.md b/docs/wiring-conventions.md
index a4f36d735..ac278f386 100644
--- a/docs/wiring-conventions.md
+++ b/docs/wiring-conventions.md
@@ -45,7 +45,7 @@ operable `role="switch"` only when an `onToggle` is passed; without it, it is a
 indicator by design — a "switch" with no handler is intentional, not a dead control.
 
 **Never** ship a styled, `aria-label`led `<button type="button">` with no handler and no disabled
-state. That was the "Language and region" globe defect (`master-search-header.tsx`, fixed 2026-07-20)
+state. That was the "Language and region" globe defect (`master-search-header.tsx`, fixed 2026-07-21)
 and is exactly what the ESLint gate below now catches.
 
 ## Navigation and route wiring
diff --git a/eslint-rules/require-button-wiring.mjs b/eslint-rules/require-button-wiring.mjs
index c3e37f37b..c5e2e060c 100644
--- a/eslint-rules/require-button-wiring.mjs
+++ b/eslint-rules/require-button-wiring.mjs
@@ -3,11 +3,11 @@
  * behaviour — an event handler, a form action, or an explicit disabled state.
  *
  * `type="button"` opts a button out of form submission, so on its own it does
- * *nothing* when clicked. Such a button that carries no `onClick` (or other
- * `on*` handler), no `formAction`, and no `disabled`/`aria-disabled` state is a
- * control that advertises an action it cannot perform — the "Language and
- * region" globe defect (master-search-header.tsx, fixed 2026-07-20). This rule
- * makes that class of dead button fail `npm run lint`.
+ * *nothing* when clicked. Such a button that carries no `onClick` and no
+ * `disabled`/`aria-disabled` state is a control that advertises an action it
+ * cannot perform — the "Language and region" globe defect
+ * (master-search-header.tsx, fixed 2026-07-21). This rule makes that class of
+ * dead button fail `npm run lint`.
  *
  * Deliberately narrow to keep false positives at zero:
  *  - Only `<button>` elements whose `type` is the string literal `"button"` are
@@ -23,8 +23,8 @@
  * disabled placeholder). Design-scratch mockups are exempt via eslint.config.mjs.
  */
 
-/** Attribute names that mark a <button type="button"> as wired. */
-const EXPLICIT_WIRING_ATTRS = new Set(["disabled", "aria-disabled", "formAction"]);
+/** Attribute names (besides `onClick`) that mark a <button type="button"> as wired. */
+const EXPLICIT_WIRING_ATTRS = new Set(["disabled", "aria-disabled"]);
 
 /** True when the JSX attribute is `type="button"` (string literal). */
 function isTypeButton(attr) {
@@ -40,12 +40,16 @@ function isTypeButton(attr) {
   return false;
 }
 
-/** True when the attribute wires behaviour: any `on*` handler or an explicit signal. */
+/**
+ * True when the attribute wires click behaviour. Only `onClick` counts as a
+ * handler: other `on*` events (onFocus/onMouseEnter) leave a click doing
+ * nothing, and `formAction` has no submit effect on a non-submit button.
+ */
 function isWiringAttr(attr) {
   if (attr.type !== "JSXAttribute") return false;
   if (attr.name.type !== "JSXIdentifier") return false;
   const name = attr.name.name;
-  return name.startsWith("on") || EXPLICIT_WIRING_ATTRS.has(name);
+  return name === "onClick" || EXPLICIT_WIRING_ATTRS.has(name);
 }
 
 /** @type {import("eslint").Rule.RuleModule} */
@@ -54,12 +58,12 @@ const rule = {
     type: "problem",
     docs: {
       description:
-        'Require an explicit `<button type="button">` to carry an event handler, formAction, or an explicit disabled state.',
+        'Require an explicit `<button type="button">` to carry an onClick handler or an explicit disabled state.',
     },
     schema: [],
     messages: {
       unwired:
-        'This <button type="button"> has no onClick (or other handler), no formAction, and no disabled/aria-disabled state — it does nothing when clicked. Wire it, or make it an explicit disabled "coming soon" placeholder.',
+        'This <button type="button"> has no onClick and no disabled/aria-disabled state — it does nothing when clicked. Wire it with onClick, or make it an explicit disabled "coming soon" placeholder.',
     },
   },
   create(context) {
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 4861899ce..0a67d4ed7 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -16,9 +16,11 @@ const localRulesPlugin = {
 };
 
 // Design-scratch mockups (404 in production) are exempt from the local rules.
-// This is the repo's full mockup surface: the `/mockups/*` routes, the
-// `*-mockups/` component directories, and the `*-mockups.tsx` singletons.
-const MOCKUP_IGNORES = ["**/*mockup*", "**/mockups/**", "**/*-mockups/**", "**/*-mockups.tsx"];
+// Match the repo's documented mockup surface precisely — the `/mockups/*`
+// routes, the `*-mockups/` component directories, and the `*-mockup(s).tsx`
+// singletons — instead of a broad `*mockup*` substring, which would also exempt
+// arbitrary production files whose name merely contains "mockup".
+const MOCKUP_IGNORES = ["src/app/mockups/**", "**/*-mockups/**", "**/*-mockups.tsx", "**/*-mockup.tsx"];
 
 const eslintConfig = defineConfig([
   ...nextVitals,
@@ -51,13 +53,13 @@ const eslintConfig = defineConfig([
     },
   },
   // A styled, labelled `<button type="button">` with no handler is a dead control
-  // (the "Language and region" globe class, fixed 2026-07-20). Require an explicit
-  // non-submit button to carry a handler/formAction or an explicit disabled state.
+  // (the "Language and region" globe class, fixed 2026-07-21). Require an explicit
+  // non-submit button to carry an onClick handler or an explicit disabled state.
   // Scoped to production source (`src/**`): this is a product-UX concern, so test
   // fixtures that render a bare <button> to exercise a slot are out of scope. The
   // full mockup-ignore set exempts the `*-mockups/` design-scratch previews.
   {
-    files: ["src/**/*.{jsx,tsx}"],
+    files: ["src/**/*.{js,jsx,ts,tsx}"],
     ignores: MOCKUP_IGNORES,
     plugins: { local: localRulesPlugin },
     rules: {
diff --git a/tests/route-reachability.test.ts b/tests/route-reachability.test.ts
index e4e900fca..d020f9a06 100644
--- a/tests/route-reachability.test.ts
+++ b/tests/route-reachability.test.ts
@@ -56,7 +56,7 @@ function collectSourceFiles(dir: string): { rel: string; content: string }[] {
     const abs = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       out.push(...collectSourceFiles(abs));
-    } else if (/\.(ts|tsx)$/.test(entry.name)) {
+    } else if (/\.(js|jsx|ts|tsx)$/.test(entry.name)) {
       const rel = path.relative(repoRoot, abs).split(path.sep).join("/");
       if (!isMockupPath(rel)) out.push({ rel, content: readFileSync(abs, "utf8") });
     }
@@ -69,8 +69,14 @@ const sourceFiles = collectSourceFiles(srcRoot);
 /** Route targets produced by the canonical nav builders (never bare string literals). */
 const builderTargets = new Set<string>();
 for (const mode of appModeDefinitions) {
-  const href = ("href" in mode ? mode.href : undefined) ?? appModeHomeHref(mode.id);
-  builderTargets.add(pathOnly(href));
+  // Record both the default home path and a query-bearing variant: appModeHomeHref
+  // can emit a different path when given a query (e.g. document / namespaced-search
+  // routes), and those are valid static targets that must not read as orphaned.
+  const hrefs = [
+    ("href" in mode ? mode.href : undefined) ?? appModeHomeHref(mode.id),
+    appModeHomeHref(mode.id, { query: "__reachability__" }),
+  ];
+  for (const href of hrefs) builderTargets.add(pathOnly(href));
 }
 for (const tool of tools) builderTargets.add(pathOnly(tool.href));
 
@@ -80,9 +86,24 @@ for (const tool of tools) builderTargets.add(pathOnly(tool.href));
 // the family's reserved segments straight from the source of truth so new screens
 // are picked up automatically. See src/components/therapy-compass/bindings.tsx.
 const tcBindingsSrc = readFileSync(path.join(srcRoot, "components/therapy-compass/bindings.tsx"), "utf8");
-const tcBase = tcBindingsSrc.match(/const BASE = "([^"]+)"/)?.[1] ?? "/therapy-compass";
-const tcReserved = tcBindingsSrc.match(/RESERVED_SEGMENTS = new Set\(\[([^\]]*)]\)/);
-for (const match of (tcReserved?.[1] ?? "").matchAll(/"([^"]+)"/g)) {
+const tcBaseMatch = tcBindingsSrc.match(/const BASE = "([^"]+)"/);
+const tcReservedMatch = tcBindingsSrc.match(/RESERVED_SEGMENTS = new Set\(\[([^\]]*)]\)/);
+// Fail loudly if the source shape changed: a silent `?? default` / empty fallback
+// would drop every reserved Therapy Compass route from the guard without notice.
+if (!tcBaseMatch || !tcReservedMatch) {
+  throw new Error(
+    "route-reachability: could not parse BASE / RESERVED_SEGMENTS from therapy-compass/bindings.tsx — " +
+      "update this parser to match the current source so reserved routes stay covered.",
+  );
+}
+const tcBase = tcBaseMatch[1];
+const tcReservedSegments = [...tcReservedMatch[1].matchAll(/"([^"]+)"/g)];
+if (tcReservedSegments.length === 0) {
+  throw new Error(
+    "route-reachability: RESERVED_SEGMENTS parsed to an empty set — Therapy Compass routes would be unchecked.",
+  );
+}
+for (const match of tcReservedSegments) {
   builderTargets.add(`${tcBase}/${match[1]}`);
 }
 

From 890f9d18631a7d7c943e40481f4521bf49b89f10 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 21 Jul 2026 03:08:19 +0000
Subject: [PATCH 3/3] fix(wiring): make button-wiring rule value-aware, not
 presence-only
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CodeRabbit re-review: disabled={false}, aria-disabled="false", and onClick={null}
satisfied the rule despite doing nothing. Add isStaticallyOff() so a statically-
known off value (literal false/null, string "false", identifier undefined — bare
or in an expression container) no longer counts as wiring/disabled, while dynamic
expressions and aria-disabled="true" stay valid. lint stays green (0 problems; no
existing button relies on those patterns).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013f523gDfoBXPYT4H9vXRkE
---
 eslint-rules/require-button-wiring.mjs | 31 ++++++++++++++++++++++----
 1 file changed, 27 insertions(+), 4 deletions(-)

diff --git a/eslint-rules/require-button-wiring.mjs b/eslint-rules/require-button-wiring.mjs
index c5e2e060c..05d5fb405 100644
--- a/eslint-rules/require-button-wiring.mjs
+++ b/eslint-rules/require-button-wiring.mjs
@@ -41,15 +41,38 @@ function isTypeButton(attr) {
 }
 
 /**
- * True when the attribute wires click behaviour. Only `onClick` counts as a
- * handler: other `on*` events (onFocus/onMouseEnter) leave a click doing
- * nothing, and `formAction` has no submit effect on a non-submit button.
+ * True when a JSX attribute value is a *statically-known* value that means "off":
+ * a literal `false`/`null`, the string `"false"`, or the identifier `undefined`
+ * (bare or inside an expression container). Anything dynamic — an identifier,
+ * call, arrow function, member access, ternary — is unknown at lint time and is
+ * NOT treated as off, so it keeps passing (same fail-open stance as the spread
+ * escape hatch). A bare boolean attribute (`disabled`, no value) is `true`.
+ */
+function isStaticallyOff(value) {
+  if (value == null) return false; // bare boolean attribute → `true`, not off
+  const nodeIsOff = (node) =>
+    node.type === "Literal"
+      ? node.value === false || node.value === null || node.value === "false"
+      : node.type === "Identifier" && node.name === "undefined";
+  if (value.type === "Literal") return nodeIsOff(value);
+  if (value.type === "JSXExpressionContainer") return nodeIsOff(value.expression);
+  return false;
+}
+
+/**
+ * True when the attribute actually wires click behaviour with a live value. Only
+ * `onClick` counts as a handler: other `on*` events (onFocus/onMouseEnter) leave
+ * a click doing nothing, and `formAction` has no submit effect on a non-submit
+ * button. A statically-known "off" value does not wire or disable the button —
+ * `onClick={null}`, `disabled={false}`, and `aria-disabled="false"` are treated
+ * as unwired, while dynamic values and `aria-disabled="true"` remain valid.
  */
 function isWiringAttr(attr) {
   if (attr.type !== "JSXAttribute") return false;
   if (attr.name.type !== "JSXIdentifier") return false;
   const name = attr.name.name;
-  return name === "onClick" || EXPLICIT_WIRING_ATTRS.has(name);
+  if (name !== "onClick" && !EXPLICIT_WIRING_ATTRS.has(name)) return false;
+  return !isStaticallyOff(attr.value);
 }
 
 /** @type {import("eslint").Rule.RuleModule} */