Land the unlanded Ward Flow Phase 3 work and reconcile the branch with main

docs/design-system/adoption-manifest.json

@@ -1564,7 +1564,8 @@
  "tests/ui-formulation.spec.ts",
  "tests/ui-smoke.spec.ts",
  "tests/ui-v2-components.dom.test.tsx",
- "tests/ui-ward-coordinator.spec.ts"
+ "tests/ui-ward-coordinator.spec.ts",
+ "tests/ui-ward-roles.spec.ts"
  ],
  "baseline": {
  "targetLayer": "v2",

src/components/ward-management/coordinator/coordinator-screen.tsx

@@ -36,10 +36,13 @@ const PHONE_DIAGRAM_MEDIA_QUERY = "(max-width: 48rem)";
 export function CoordinatorScreen() {
  // Task 5: the screen's props stop being derived from the frozen `wardMovements` fixture and
  // `NOW_ANCHOR` constant and start coming from the shared provider (`WardFlowProvider`, already
- // wrapping every `/ward-management` route via `src/app/ward-management/layout.tsx`). `units`
- // is not destructured here — nothing this screen renders yet reads live unit state, and an
- // unused destructured value would be dead weight rather than real wiring.
- const { movements, rejections, now, dispatch, focusMovementId, setFocusMovementId } = useWardFlow();
+ // wrapping every `/ward-management` route via `src/app/ward-management/layout.tsx`).
+ //
+ // Whole-branch review Critical 1: `units` IS now destructured and threaded into `FlowDiagram`
+ // and `ShortlistPanel` below. It was deliberately left out here on the original claim that
+ // "nothing this screen renders yet reads live unit state" — false: both child components read
+ // unit capacity, and both were doing it from the frozen `ward-sites.ts` fixture instead.
+ const { movements, units, rejections, now, dispatch, focusMovementId, setFocusMovementId } = useWardFlow();
  // Task 12: seeded from the shared `focusMovementId` (not always `undefined`) so a coordinator
  // who switched away to answer a referral as another role and switches back finds the same
  // patient still selected — this screen remounts on every route change (it is a route
@@ -189,6 +192,7 @@ export function CoordinatorScreen() {
  <FlowDiagram
  movement={selectedMovement}
  now={now}
+ units={units}
  selectedUnitId={selectedUnitId}
  onSelectUnit={(unitId) => setSelectedUnitId((current) => (current === unitId ? undefined : unitId))}
  />
@@ -203,6 +207,7 @@ export function CoordinatorScreen() {
  <ShortlistPanel
  movement={selectedMovement}
  now={now}
+ units={units}
  selectedUnitId={selectedUnitId}
  onSelectUnit={(unitId) => setSelectedUnitId((current) => (current === unitId ? undefined : unitId))}
  dispatch={dispatch}

src/components/ward-management/coordinator/coordinator.module.css

@@ -547,7 +547,7 @@
 }
 
 /*
- * `eligibleCandidates` sorts eligible-first but never filters, so a shortlisted unit can still
+ * `eligibleCandidatesAmong` sorts eligible-first but never filters, so a shortlisted unit can still
  * fail a gate (Critical 1 — already declined, wrong security tier, stale capacity, ...). This
  * line must never look like the eligible route above: dashed, and danger-toned rather than
  * accent-toned, so the arrow itself does not read as an endorsement of a route the data denies.
@@ -1453,6 +1453,25 @@
  line-height: var(--co-leading-body);
 }
 
+/*
+ * Whole-branch review I2: a recorded escalation is a real, persistent fact — the network really
+ * was exhausted for this movement at this instant — never a success message, so it deliberately
+ * does not reuse `.shortlistConfirmationRecord`'s success tokens above. `--warning-*`, not
+ * `--danger-*`: an escalation is a recorded operational fact a coordinator is expected to act on
+ * next, not a refusal or an error state.
+ */
+.shortlistEscalationRecord {
+ margin: 0 0 var(--co-space-8);
+ border: 0.0625rem solid var(--warning-border);
+ border-radius: var(--radius-md);
+ background: var(--warning-bg);
+ padding: var(--co-space-8) var(--co-space-10);
+ color: var(--warning-text);
+ font-size: var(--text-2xs);
+ font-weight: 650;
+ line-height: var(--co-leading-body);
+}
+
 .shortlistActionRow {
  display: flex;
  flex-wrap: wrap;
@@ -1596,6 +1615,30 @@
  font-weight: 700;
 }
 
+/*
+ * Whole-branch review I4: a separate, danger-toned badge for refused transitions — never merged
+ * into `.exceptionsToggleCount` above, which is `items.length`, a different fact (the action
+ * inbox). Rendered only while `rejections.length > 0` (see exception-drawer.tsx), so the trigger
+ * carries no extra chrome until the first refusal and then never goes quiet again — the same
+ * "present the moment the fact is real" rule `.refusalsSection` already applies to the panel
+ * beneath it. Danger tokens, not the neutral accent above: a refusal is the reducer stating an
+ * action did NOT happen, which is a sharper fact than an open work-list item.
+ */
+.exceptionsToggleRefusalCount {
+ display: inline-flex;
+ min-height: var(--co-space-20);
+ align-items: center;
+ gap: var(--co-space-6);
+ border: 0.0625rem solid var(--danger-border);
+ border-radius: var(--radius-pill, 9999px);
+ background: var(--danger-bg);
+ padding: 0 var(--co-space-8);
+ color: var(--danger-text);
+ font-size: var(--text-3xs);
+ font-weight: 700;
+ white-space: nowrap;
+}
+
 .exceptionsDrawer[data-open="true"] .placeholder {
  margin-top: var(--co-space-8);
 }

src/components/ward-management/coordinator/exception-drawer.tsx

@@ -47,7 +47,30 @@ export function ExceptionDrawer({ items, rejections, open, onToggle, onSelectMov
  <button type="button" className={styles.exceptionsToggle} aria-expanded={open} onClick={onToggle}>
  {open ? <ChevronDown aria-hidden="true" /> : <ChevronUp aria-hidden="true" />}
  <span>Exceptions</span>
- <span className={styles.exceptionsToggleCount}>{items.length}</span>
+ <span className={styles.exceptionsToggleCount} data-testid="ward-exceptions-toggle-count">
+ {items.length}
+ </span>
+ {/* Whole-branch review I4: the count above is `items.length` — the action inbox only —
+ so a refused transition (HOLD_BED on a ward with zero allocatable beds, in the
+ review's own Proof 2) was invisible on a closed drawer: nothing about the collapsed
+ trigger changed when a refusal was filed. Spec §7.4 calls the refusals surface
+ PERSISTENT, "not a toast that vanishes" — a badge that only appears once the count is
+ genuinely non-zero, and that stays wherever this drawer is rendered (never inside the
+ `open` branch below), is the smallest honest fix: it renders nothing extra until the
+ first refusal, then never goes silent again. A second, distinctly toned badge rather
+ than folding this into the count above — an action-inbox item and a refusal are
+ different facts a coordinator responds to differently, and merging their counts would
+ recreate exactly the "one number, two meanings" defect Ruling 3's own comment on
+ `exceptionsToggleCount` was written to prevent. */}
+ {rejections.length > 0 ? (
+ <span
+ className={styles.exceptionsToggleRefusalCount}
+ data-testid="ward-exceptions-toggle-refusal-count"
+ title={`${rejections.length} refused action${rejections.length === 1 ? "" : "s"}`}
+ >
+ {rejections.length} refused
+ </span>
+ ) : null}
  </button>
  {open ? (
  <section className={styles.exceptionsPanel} aria-label="Exceptions">

src/components/ward-management/coordinator/flow-diagram.tsx

@@ -6,27 +6,27 @@ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } fr
 import type { Instant } from "@/components/ward-management/ward-clock";
 import {
  candidateReason,
-eligibleCandidates,
+eligibleCandidatesAmong,
  restrictionNotice,
  unitCapacity,
  wardServiceOrder,
 } from "@/components/ward-management/ward-derivations";
-import { useWardFlow } from "@/components/ward-management/ward-flow-provider";
 import { PARALLEL_REFERRAL_CAP, type Movement, type Unit } from "@/components/ward-management/ward-model";
 import { edPressure } from "@/components/ward-management/ward-pressure";
-import { allUnits, siteByCode, unitById } from "@/components/ward-management/ward-sites";
+import { siteByCode } from "@/components/ward-management/ward-sites";
 
 import styles from "./coordinator.module.css";
 
 type FlowDiagramProps = {
  movement: Movement | undefined;
  now: Instant;
+ units: Unit[];
  selectedUnitId: string | undefined;
  onSelectUnit: (unitId: string) => void;
 };
 
 type Point = { x: number; y: number };
-type ShortlistCandidate = ReturnType<typeof eligibleCandidates>[number];
+type ShortlistCandidate = ReturnType<typeof eligibleCandidatesAmong>[number];
 type Connector =
  | { id: string; path: string; kind: "demand" }
  | { id: string; path: string; kind: "route"; eligible: boolean }
@@ -66,16 +66,20 @@ function recordedDestinationIds(movement: Movement | undefined): Set<string> {
  *
  * Two further corrections from the whole-branch review:
  *
- * Critical 1 -- the word "nearest" is gone. `eligibleCandidates` ranks cohort-matching units
+ * Critical 1 -- the word "nearest" is gone. `eligibleCandidatesAmong` ranks cohort-matching units
  * eligible-first and breaks ties on array order; the model holds no distance data at all, so a
  * proximity claim here was simply false.
  *
  * Important 3 -- a movement that ALREADY has a recorded destination is not looking for three of
  * them. WF-004 sits at stage `bed_held` with a bed held at BTY Adult Secure, and this line read
  * "WF-004 -- 3 eligible destinations". The recorded fact now leads; the candidate count follows
  * as secondary context, because a coordinator may still be considering alternatives.
+ *
+ * Whole-branch review Critical 1: `units` is the caller's live provider `units`, never
+ * `ward-sites.ts`'s `unitById`/`allUnits` — a name lookup here still must reflect a unit that
+ * exists in the live world the same as any capacity figure would.
  */
-function hubStatusText(movement: Movement | undefined, shortlist: ShortlistCandidate[]) {
+function hubStatusText(movement: Movement | undefined, shortlist: ShortlistCandidate[], units: Unit[]) {
  if (!movement) return "Select a movement from the priority queue to route it";
 
  // "Other" means other than the units already recorded against this movement -- a candidate that
@@ -85,14 +89,14 @@ function hubStatusText(movement: Movement | undefined, shortlist: ShortlistCandi
  const candidateTail = otherCount === 0 ? "" : `; ${otherCount} other candidate${otherCount === 1 ? "" : "s"} shown`;
 
  if (movement.acceptedUnitId) {
- const accepted = unitById(movement.acceptedUnitId);
+ const accepted = units.find((unit) => unit.id === movement.acceptedUnitId);
  return accepted
  ? `${movement.id} — accepted destination: ${accepted.name}${candidateTail}`
  : `${movement.id} — an accepted destination is recorded but could not be resolved`;
  }
  if (movement.referredUnitIds.length > 0) {
  const names = movement.referredUnitIds
- .map((id) => unitById(id)?.name)
+ .map((id) => units.find((unit) => unit.id === id)?.name)
  .filter((name): name is string => Boolean(name));
  return names.length === movement.referredUnitIds.length && names.length > 0
  ? `${movement.id} — outstanding referral${names.length === 1 ? "" : "s"}: ${names.join(", ")}${candidateTail}`
@@ -120,7 +124,7 @@ function hubStatusText(movement: Movement | undefined, shortlist: ShortlistCandi
  * is already recorded against; with nothing selected, this renders the network with nothing routed
  * rather than a guessed selection (ruling: display less rather than something plausible).
  *
- * `eligibleCandidates` sorts eligible-first but never filters -- it can and does return units
+ * `eligibleCandidatesAmong` sorts eligible-first but never filters -- it can and does return units
  * that fail a gate (already declined the movement, wrong security tier, stale capacity, ...).
  * Every shortlisted node therefore carries its own verdict (`data-eligible`, plus
  * `candidateReason` rendered as real text) and an ineligible route is drawn visually distinct
@@ -133,12 +137,11 @@ function hubStatusText(movement: Movement | undefined, shortlist: ShortlistCandi
  * and reruns on a `ResizeObserver` plus a window resize listener, so the diagram survives a
  * resize rather than only ever being screenshotted once.
  */
-export function FlowDiagram({ movement, now, selectedUnitId, onSelectUnit }: FlowDiagramProps) {
- const { units } = useWardFlow();
+export function FlowDiagram({ movement, now, units, selectedUnitId, onSelectUnit }: FlowDiagramProps) {
  const pressure = useMemo(() => edPressure(now), [now]);
  const shortlist = useMemo(
- () => (movement ? eligibleCandidates(movement, now, PARALLEL_REFERRAL_CAP, units) : []),
- [movement, now, units],
+ () => (movement ? eligibleCandidatesAmong(movement, units, now, PARALLEL_REFERRAL_CAP) : []),
+ [movement, units, now],
  );
  const shortlistByUnitId = useMemo(
  () => new Map(shortlist.map((candidate) => [candidate.unit.id, candidate])),
@@ -151,20 +154,24 @@ export function FlowDiagram({ movement, now, selectedUnitId, onSelectUnit }: Flo
  // group rather than guessing one -- conservative failure, not a crash. `unplacedUnits` below
  // catches exactly that case so the unit still renders (as an explicit anomaly) rather than
  // silently vanishing from the board (review Minor 6).
+ //
+ // Whole-branch review Critical 1: grouped from the caller's live `units`, never `allUnits()` —
+ // every unit NODE on this board (its bed grid, via `unitCapacity` in `UnitNode` below) must
+ // move the instant a ward confirms new capacity, not only at first paint.
  const serviceGroups = useMemo(
  () =>
  wardServiceOrder
  .map((service) => ({
  service,
- units: allUnits().filter((unit) => siteByCode(unit.siteCode)?.service === service),
+ units: units.filter((unit) => siteByCode(unit.siteCode)?.service === service),
  }))
  .filter((group) => group.units.length > 0),
- [],
+ [units],
  );
  const unplacedUnits = useMemo(() => {
  const grouped = new Set(serviceGroups.flatMap((group) => group.units.map((unit) => unit.id)));
- return allUnits().filter((unit) => !grouped.has(unit.id));
- }, [serviceGroups]);
+ return units.filter((unit) => !grouped.has(unit.id));
+ }, [serviceGroups, units]);
 
  const canvasRef = useRef<HTMLDivElement | null>(null);
  const hubRef = useRef<HTMLDivElement | null>(null);
@@ -380,7 +387,7 @@ export function FlowDiagram({ movement, now, selectedUnitId, onSelectUnit }: Flo
  <div className={styles.diagramHub} ref={hubRef}>
  <Network aria-hidden="true" />
  <strong>Statewide flow hub</strong>
- <span>{hubStatusText(movement, shortlist)}</span>
+ <span>{hubStatusText(movement, shortlist, units)}</span>
  </div>
 
  <div className={styles.diagramUnitsColumn}>

src/components/ward-management/coordinator/priority-queue.tsx

@@ -81,8 +81,12 @@ export function PriorityQueue({ movements, now, selectedId, onSelect, filterEdId
  // breached" — the factor list is scoped to Task 7's expandable shortlist, not this
  // row, but a breached statutory deadline is the one thing this row must never let a
  // coordinator miss, so it always renders here regardless of what Task 7 later shows.
- // A form with no `dueAt` (Task 6A: a Form 3B honestly carries none) is never breached —
- // `undefined` must never reach `clockState`'s arithmetic.
+ // A form with no `dueAt` is never breached — `undefined` must never reach
+ // `clockState`'s arithmetic. As of the 2026-08-23 product-owner correction, neither a
+ // Form 1A nor a Form 3B carries one any longer (Task 6A first established this for 3B;
+ // see `LegalForm`'s doc comment in ward-model.ts) — only the transport/transfer forms
+ // (4A/4C) still do, and none of those are due in the past on today's fixture, so
+ // `legalBreached` below is false today.
  const legalDueAt = movement.legalForm?.dueAt;
  const legalBreached = legalDueAt !== undefined && clockState(legalDueAt, now) === "breached";
  const legalFactor = factors.find((factor) => factor.label === "Statutory timing");