Design: vcflow eCOA Slice 1 — Clinician eCOA Per-Participant View (v2 — review feedback incorporated)

Generated by /office-hours on 2026-05-22 Branch: main Repo: validcare/vcflow Status: APPROVED (2026-05-22, Scott — /office-hours feedback-incorporation session) Mode: Startup (intrapreneurship) Supersedes: scott-main-design-20260521-230737.md

What this revision is. v1 (the file above) produced the strawman + four-fixture mockup. Scott reviewed it on 2026-05-22 and returned 8 feedback points as the final input for the wireframe phase — the wireframes are reworked once against this doc, then spec authoring begins; there is no further wireframe re-review. This v2 carries v1 forward unchanged where v1 was not contested, and reworks the layout, zones, and edge states against the 8 points. The new content is concentrated in §Review Feedback Incorporation, the reworked §Recommended Approach, and §Wireframe Rework Checklist.

Naming note (carried from v1). The handoff calls this the "Participant Dashboard," which is ambiguous — it can read as the participant's own dashboard (ePRO). This surface is the clinician's dashboard about one participant (eCOA). The spec should be titled "Clinician eCOA — Per-Participant View."

Review Feedback Incorporation

Scott's triage instruction: every one of the 8 points gets an explicit "Slice 1 / Slice 2+" call with recorded rationale — no point silently dropped.

Triage table

The resolved decisions (this session)

• D1 — Action bar. Banner + button in Forms zone. The Now banner stops being a second executor. It becomes a pointer: it names the recommended action and the "why now," and highlights / scrolls to the zone that owns that action. Every zone owns exactly one button for its action. (See §Recommended Approach → Zone 1.)
• D2 — ePRO scope. Slice 1 zone, affirmation form deferred. Slice 1 designs and mocks a read-only ePRO-summary zone. The Part 11 clinician-affirmation form is Slice 2+, gated on work-vcflow-epro shipping real data.
• D3 — Out-of-window handling (reworked with Scott, this session). Journey-config-driven; the protocol dictates the path. A missed or overdue visit never blocks the journey — the participant continues to subsequent visits. The journey config declares, per visit, a window policy (soft / hard). A soft-window missed visit stays collectable — its data can be captured out of window, recording a protocol deviation + a clinician-entered reason. A hard-window missed visit is non-collectable once its window closes — the system flags it "Missed" and the clinician records the deviation reason. The dashboard records the deviation + reason; it never judges exclusion — whether a deviation is exclusionary is a later judgment by the PI / medical monitor / sponsor on a separate surface. Slice 1 because the overdue state is already a Slice 1 deliverable (fixture 4); shipping the overdue display with no way to collect the late data ships a dead-end.
• D4 — CRA in-context query. Slice 1 designs the in-context raise. The role-aware surface gives the monitor a raise-query affordance that auto-captures the field + value — no separate re-entry form.
• D8 — Deviation reason capture. In Slice 1. When data is collected out of window, or a visit is flagged missed, the clinician captures a structured reason (picklist + free-text) at that moment. The reason is the load-bearing input to the downstream exclusion judgment — a deviation record without it is near-useless.

Triage rationale for the points NOT made into D-questions

• Point 3 (dates). Resolved directly; OQ4 investigated and closed (see Open Questions). vcflow has no scheduled/appointment-date concept — visits carry only relative windows (an anchor such as enrollment + a minDays/maxDays offset, defined in dateRange guards). Slice 1 call: rail rows and the step summary show the computed window as a calendar date range with a countdown to window close (the compliance deadline). No scheduled-date headline — it does not exist and is not in Slice 1 scope to build. A visit with no window guard shows no date. Spec dependency: the aggregate API must compute each visit's window from context.anchors + the dateRange config (see Dependencies #1).
• Point 4 (PI fast summary). Scott's wording — "summary of the actions / participants awaiting signature" — is cross-participant. This dashboard is one participant by definition; a cross-participant PI summary is the /signing inbox (Slice 3 Task 17), a different surface. Call: deferred — recorded as input to /signing, not built here. Slice 1's per-participant signature zone (Zone 7) still stands and stays glanceable for when a PI does land on this surface.
• Point 5 (lab results). Split. Slice 1 designs the display zone and the attach-to-participant-journey model. The PDF intake/upload mechanism is Slice 2+ — it is the umbrella's interim path until Lab Connect integration ships and should be scoped with that work.
• Point 7 (pre-submit confirmation). Split. Field-level confirm-before-submit lives in the SurveyJS forms renderer, not this dashboard — separate work. The dashboard does own visit-level transitions, so Slice 1 adds a confirmation pattern to the three dashboard actions that write an immutable audit or deviation event: route-a-visit-to-signature, collect-data-out-of-window, record-missed-visit-reason.

Problem Statement

Design (not implement) Slice 1 of the vcflow clinician eCOA surface: the per-participant view a study coordinator opens to see where one enrolled participant is in their trial journey and what to do next with them. The deliverable is a strawman narrative + an interactive mockup for internal review. Implementation follows in a later slice, gated on mockup approval.

Today this surface (/participants/:id, apps/staff/src/app/features/participants/participant-detail.component.ts, ~285 lines) is a tabbed flat table of form responses ("Visit Matrix" / "Timeline" tabs). It makes the coordinator choose a view rather than see the next task.

Demand Evidence

Demand for the capability is committed, not speculative: the eCOA umbrella tracker (work-vcflow-ecoa.md) classifies it as "Day-1-required clinical capability — the clinician-side data-collection backbone," targeted for the first commercial study. The open question is not whether to build a clinician per-participant surface but what shape it takes. The 2026 industry direction corroborates the chosen shape: clinical dashboards are moving from static data displays to predictive prioritization — classify into urgency tiers, clinicians act rather than sort.

Status Quo

Validcare's legacy platform is a two-system split:

• Jotform — form-based data collection; the system of record.
• vcpi — the eCOA workflow / journey-state layer. Receives Jotform submissions via webhooks and mirrors completion state. It has no journey engine of its own — it is a webhook-fed status cache, which is why its screens show every visit and step regardless of where the participant is.

The wedge is to collapse the two-system split. vcflow natively owns forms, data, the XState journey engine, and the eCOA workflow in one platform. The dashboard's authoritative, live, journey-driven state is a correctness + trust argument vcpi structurally cannot make.

Target User & Narrowest Wedge

Primary persona: the study coordinator. Highest-frequency user; minutes per participant, not hours; does visit execution and clinician-completed eCOA data capture across a caseload. The default layout is optimized for the coordinator.

Secondary persona, now first-class on this surface: the monitor / CRA. v1 treated the surface as coordinator-only. Point 8 pulls the CRA in — not as a separate screen but as a role-scoped view of the same surface: the monitor gains a raise-query affordance and loses the coordinator's data-capture buttons (see Zone 3 and Open Question 8). PI/investigator e-signature remains secondary — surfaced, not centered.

Narrowest wedge: one participant, one screen, one glanceable next action — a journey-engine-driven view that ranks rather than lists.

Constraints

• Design only this round. No production Angular. Strawman narrative + clickable mockup.
• Scope is the clinician's view of ONE participant's eCOA — not the cross-participant grid (/casebook), not the participant's own ePRO app.
• Angular 21 (signals, standalone, OnPush, zoneless); Part 11 regulated (audit trail visible, e-signature, soft deletes); no PHI beyond study ID on screen.
• Quality over the date: proper implementation and meaningful functionality take precedence over hitting a specific date (Scott).
• A dedicated UX-polish pass on libs/shared-ui primitives is a separate later task, out of scope here.

Premises (carried from v1, unchanged)

• P1 — Scope. The clinician's dashboard view of one participant's eCOA. Not /casebook. Not the ePRO participant app. (Point 2 surfaces ePRO data here; it does not pull in the ePRO app.)
• P2 — Replaces a real, weak surface. Redesign of the existing tabbed flat table at /participants/:id. Existing behavior is carried forward or deliberately replaced, never silently dropped.
• P3 — Compose where it fits, build where it doesn't. Reuse libs/shared-ui primitives when they genuinely suit; build net-new when they don't.
• P4 — Journey-driven prioritization, tiered. Render a three-tier Now / Soon / Done view: Now prominent, Soon a peek, Done collapsed but expandable.

Tier-derivation rule (carried from v1, reworked for D3)

The rail separates two things v1 had fused: journey position (the single moving frontier — the state machine) and per-visit data completion (tracked independently). That split is what lets a missed visit's data be collected late without two concurrent journey states.

• A visit = a group of XState states sharing a meta.visitRef (the engine models one form per state; a multi-form visit is a chain of states — see §Journey-config-driven behavior). The rail tiers operate on visits; the XState frontier is a single state within the Now visit.
• Now — the visit containing the participant's current journey-frontier state. Always exactly one row. (Branching lives in Soon.)
• Soon — the immediate successor visits per the journey config (next 1–3), reached by following transitions from the current state.
• Done — past visits the journey frontier has moved beyond. A Done row is in one of three states: Complete; Data outstanding (a soft-window visit missed/overdue, still collectable — amber, actionable); or Missed (a hard-window visit whose window closed — amber, read-only). The "Done" label is provisional; the wireframe rework may rename the tier since it now holds not-yet-complete rows.
• Far-future states beyond the immediate successors are not rendered in Slice 1.

Journey-config-driven behavior

The journey config (study.json + the XState machine) is the single source of truth for override and sequencing — the dashboard reads and renders, it does not bake journey logic into the UI. OQ5 was investigated against the real engine (machine.factory.ts, guard.registry.ts, types.ts); the resolved model:

• A "visit" is a meta.visitRef group. The XState machine models one form per state; a multi-form visit is a chain of states sharing a meta.visitRef ("visit-1", "visit-2"). The dashboard groups states by visitRef to render a visit and its forms. No engine change needed — visitRef already exists.
• Window policy — soft today, hard is net-new. Today every window is soft: a dateRange guard failure fires a recordWindowDeviation action and the transition still proceeds. That is the soft-window behavior — Slice 1 ships against it with zero engine change. A hard window (block the transition once the window closes) does not exist; it is a small net-new per-state flag, windowPolicy: 'hard' | 'soft', default 'soft'.
• Sequencing — the engine chains forms; the dashboard is order-agnostic. The engine expresses only sequential chains (plus guarded branching between visits); there is no "unordered set of tasks" construct, and the dashboard does not need one. Because it is "recommend, don't gate" and form completion is tracked independently of journey state, it presents all of a visit's forms as co-equal, all actionable, whatever order the engine chains them. The chain drives only the banner's recommendation (the first incomplete form), never a gate. A clinician fills forms in any order; each FormResponse saves independently; the journey's FORM_COMPLETED chain catches up. So an explicit "unordered set" config, if the engine ever gains one, changes nothing here — the dashboard already never gated.

The only hard gates on this surface are data integrity (an open query blocks visit signature) and hard-window non-collectability. Everything else the banner recommends.

Data completion is already separate from journey state — confirmed in the engine: FormResponse rows persist on form save, independent of the XState machine; a form for a past visit can be filled after the frontier has advanced, and nothing blocks it. D3's core bet (collect late data without two concurrent journey states) needs no new separation — it is how the platform already works. The dashboard computes a visit's completeness from its FormResponse rows (all forms in the visitRef group present), not from journey state — that computation drives the Done-tier "Data outstanding → Complete" flip.

Cross-Model Perspective

From the v1 session (not re-run for this feedback-incorporation pass — the v2 decisions are feedback-driven, not premise-driven). Two independent cold reads validated the journey-engine wedge and the two-pane structure. Key v1 contributions still load-bearing here:

• The Now/Soon/Done tiering came from a subagent challenge to an over-narrow "current state only" premise.
• Codex flagged that the rail is net-new (vc-journey-timeline is a chronological audit component, the wrong base), that query-list is too heavy for in-step open items, and that pi-sig-banner composes but must be wrapped for coordinator-first copy. All still hold.

Approaches Considered (decided in v1 — not reopened)

• Approach A — Hero + Stack (single-column action cockpit). S–M effort.
• Approach B — Timeline Rail + Work Surface (two-pane). L effort. Chosen.
• Approach C — Priority Feed (urgency-tiered card stream). M effort.

Approach B was selected by Scott in v1 for its long-term scaling to Slice 2+ panels. This revision does not reopen the approach choice — the 8 points are all within Approach B.

Recommended Approach — reworked layout (Approach B)

A persistent participant identity header spans the top (study ID, arm, site, enrollment state — no PHI beyond study ID). Below it, two panes in a fixed 304px 1fr grid.

Left — Journey Rail (fixed 304px, net-new ParticipantJourneyRail)

Three tiers per the Tier-derivation rule. Date semantics (point 3, OQ4 resolved): there is no scheduled-appointment date in vcflow — each rail row shows the computed visit window as a calendar date range and a countdown to window close. A visit with no window guard shows just its name.

• Now — selected by default, visually loud. Window range as the date line; countdown to close, shading to amber as it shrinks; overdue = bold amber "Overdue." A non-date-gated visit shows no countdown.
• Soon — next 1–3 visits, dimmed, hollow dot, window range + "Opens [date]."
• Done — collapsed by default (count + chevron); expands to the past-visit list. Each Done row is Complete, Data outstanding (soft-window missed/overdue — amber, forms still actionable), or Missed (hard-window — amber, read-only). Selecting any Done row drives the work surface; a Complete or Data-outstanding row opens that visit's forms (preserves P2 behavior).

Right — Work Surface

All zones are step-scoped — they render the rail-selected step (default: the Now step). There are eight zones, numbered 1–8. v2 inserts Zone 6 (Lab Results) and renumbers the v1 Signature and Audit zones to 7 and 8; v1's zone order is otherwise preserved.

Zone 1 — Now recommendation banner (reworked, D1). The banner is a pointer, not an executor. It carries the "Next action" tag, a plain-language headline, and a one-line "why now." It has no primary button of its own. Its mechanic is fixed: the banner draws a static highlight border on the zone that owns the recommended action, and clicking the banner scrolls that zone into view. There is no scroll-on-load — the banner sits at the top and the owning zone is already near it.

• Recommended action is a form → banner highlights the matching Forms row.
• Recommended action is resolving a query → banner highlights Open Items.
• Recommended action is a signature reminder → banner highlights Signature.
• This satisfies "recommend, don't gate": the banner recommends; the clinician is free to act on any zone in any order (form/test sequencing is often driven by machine availability — that is fine and changes nothing about protocol integrity). The engine chains a visit's forms in sequence; the banner recommends the first incomplete form in that chain, but every other form in the visit is equally actionable — the banner recommends, it never gates.
• Persistence + pointer behavior on non-current steps (carried from v1, clarified): the banner always reflects the journey engine's current Now step. But when a Done/Soon step is selected, the work-surface zones render the selected step — so the banner cannot point at them without ambiguity. In that state the banner drops its highlight/scroll target and shows only the persistent recommendation text, and a dashed context strip appears above the step detail ("Viewing [step] — Back to current step"). The pointer mechanic is live only when the current step is the one on screen.
• Ghost state (carried from v1): when there is no coordinator action (visit complete, awaiting PI signature), the banner keeps the tag and a status headline, no recommendation target.

Zone 2 — Step summary. Visit/step name, window range (computed from the anchor + offset), window status, one-line plain-language summary.

Zone 3 — Open Items. Queries + edit-check failures + signature blockers for the selected step, must-resolve-first order. Compact list (net-new; reuses query types/badges only). Quiet empty state when clear.

• CRA in-context query (D4 / point 8). The surface is role-aware. For the monitor role, a "Raise query" affordance appears on each Forms row and on data shown in Open Items. Activating it opens an in-context query composer prefilled with the form + field reference + current value — the CRA never re-types old/new values into a separate form. The raised query then appears in Open Items for the coordinator (the existing resolve flow). Design boundary: Slice 1 designs the dashboard-side affordance and the no-re-entry principle; the in-form field picker (for value-level queries) depends on forms gaining a monitor-review mode (Open Question 6).
• The monitor view is not just an added affordance. A CRA must not execute clinical data capture — so the monitor role hides or disables the coordinator action buttons (Start / Continue, Route-to-signature, the override actions) in every zone. The per-zone monitor permission map is Open Question 8.

Zone 4 — ePRO since last visit (new, D2 / point 2). A read-only summary of participant-reported ePRO entries (e.g. "3 ePRO responses since last visit · last May 18 · Review"). "Review" opens the ePRO detail. Collapses to a one-line summary; quiet empty state when the participant has entered nothing. When a Done step is selected, the zone shows the ePRO entries that fell within that visit's window — the "since last visit" framing is relative to the current visit only; for a Soon step the zone is empty. The Part 11 clinician-affirmation form ("I reviewed this participant's ePRO data") is Slice 2+ — designed later, gated on work-vcflow-epro shipping real data. The zone is laid out now so ePRO is a planned surface, not a later bolt-on.

Zone 5 — Forms for this visit. Compact rows, status dot, one button per row — Start / Continue / View. This is the single executor for form actions (D1); the recommended row is highlighted by Zone 1 but is otherwise an ordinary row. The visit's forms (the visitRef group's states) render in the engine's chain order; all rows stay actionable regardless of order (recommend, don't gate). When a Done-tier "Data outstanding" visit is selected, its form rows stay actionable so the late data can be collected. Monitor role: each row carries the Zone-3 "Raise query" affordance and the Start / Continue button is hidden (see the Zone 3 design boundary).

Zone 6 — Lab Results (new, point 5). External lab results attached to this visit / the participant journey. Display only in Slice 1: result rows, source label, collected date, and a link to the source document (e.g. the lab PDF). When a Done step is selected, shows that visit's labs; empty for Soon steps. The display + journey-attachment model is Slice 1; the PDF upload/intake mechanism is Slice 2+ (the umbrella's interim path before Lab Connect). Quiet empty state when no external labs exist for the visit.

Zone 7 — Investigator signature. Wrapped pi-sig-banner; renders not-ready / pending-PI states with coordinator-first copy. Routing a completed visit to signature triggers the pre-submit confirmation (point 7) — see below.

Zone 8 — Audit trail. Step-scoped who-did-what-when, collapsed by default, present on the page (UX principle 5). "View full participant history" link opens the complete participant-wide audit (a separate view).

v1's "Coordinator job list" table (the 8-task → zone mapping) is superseded by the per-zone descriptions above and §Success Criteria's "every panel maps to a task" assertion — deliberately folded in, not silently dropped (P2).

Out-of-window handling (D3 / D8 / point 6)

A missed or overdue visit never blocks the journey — the next visit opens on its own window schedule; the dashboard does not gate it on the prior visit being complete. The prior visit drops into the Done tier, and what the clinician can do with it is dictated by the journey config's window policy:

• Soft-window visit, missed/overdue — "Data outstanding." The visit stays collectable. Selecting it from the Done tier shows its Forms zone with the rows still actionable. Capturing data out of window opens the pre-submit confirmation with deviation-reason capture (D8) — a structured reason (picklist + free-text) for why the visit is late. On confirm the deviation + reason is recorded; the row stays amber "Data outstanding" until all its forms are collected, then becomes "Complete — collected out of window."
• Hard-window visit, window closed with no data — "Missed." The system flags the visit Missed automatically once the hard window closes — the protocol already made that decision, the clinician does not. The clinician's one action is to record the deviation reason; the visit is otherwise read-only.
• In both cases the dashboard records, it does not judge — no exclusionary verdict appears here. A Done row may show "Deviation recorded — pending review"; the exclusion judgment is a separate downstream surface (out of scope — see §Out of Scope for Slice 1).

The pre-submit / pre-commit confirmation pattern (point 7)

A single consistent confirmation pattern applied to the three dashboard transitions that each write an immutable audit or deviation event — the confirmation is a genuine last check before a permanent write, not a courtesy, and its copy says so. Each shows a summary of what is about to happen and a confirm button — and for the two deviation actions it captures a structured reason (D8):

1. Route a completed visit to PI signature (Zone 7) — summary = forms + key values.
2. Collect a soft-window visit's data out of window — summary + deviation-reason capture.
3. Record the deviation reason for a hard-window missed visit.

Per-form, field-level confirm-before-submit is not in this pattern — it belongs to the SurveyJS forms renderer and is separate work.

The 9 strawman decisions (v1 table, amended)

Design decisions carried from v1 (unchanged)

• Window status communicated by text label + amber, never red. Amber carries all attention on this surface; red is reserved (Slice 1 has no destructive/error state). Consistent with the healthcare convention that warm/red tints read as bodily/infectious — cool blues carry clinical trust.
• Cool-blue palette, amber for genuine attention only.
• Tablet: desktop-first; two-pane → single-pane collapse deferred to the spec, co-designed with the Now banner.

Degraded & edge states (v1 table, amended)

Wireframe Rework Checklist

The single concrete punch list for the wireframe-rework session. Rework once against this, then author the spec.

Final fixture roster (v1 had 4; v2 reworks all 4 and adds 2): (1) newly-enrolled · (2) visit-in-progress · (3) awaiting-PI-signature · (4) visit-overdue · (5) out-of-window handling — a soft-window "Data outstanding" visit in the Done tier (collect-late + deviation-reason capture) and a hard-window "Missed" visit · (6) monitor-role view (CRA raise-query). Fixtures 5 and 6 may be interactive states layered on an existing fixture rather than standalone frames, at the rework session's discretion — but both must be walkable.

1. Zone 1 — Now banner: remove the primary button from all fixtures; convert to a pointer — static highlight border on the owning zone + click-to-scroll. Verify the Forms-zone row is the sole executor.
2. Rail + Zone 2 dates: replace "Due [date]" with the computed window range + countdown-to-close (OQ4 resolved — there is no scheduled-appointment date in vcflow; do not mock one). A non-date-gated visit shows just its name.
3. Zone 4 — ePRO: add the read-only ePRO-summary zone; populate it in fixtures 2 and 3; quiet empty state in fixtures 1, 4, 5, and 6.
4. Zone 6 — Lab Results: add the lab-results display zone; populate it in at least one fixture (a visit that has external labs).
5. Out-of-window handling (D3 / D8): build fixture 5 — a soft-window visit in the Done tier flagged "Data outstanding" with its forms still actionable and the collect-late deviation-reason confirmation, plus a hard-window "Missed" visit (read-only, reason recorded). Show the Done tier holding all three row-states (Complete / Data outstanding / Missed) — and decide whether to rename the "Done" tier label, since it now holds not-yet-complete rows (see §Tier-derivation rule).
6. Pre-submit confirmation: add the confirmation dialog for route-to-signature and the two deviation actions (collect-out-of-window, record-missed-reason), with reason capture.
7. CRA query (D4): build fixture 6 — the monitor-role view showing the "Raise query" affordance, the prefilled in-context composer, and the coordinator action buttons hidden.
8. Triage record: keep §Review Feedback Incorporation visible in the strawman narrative so the review can see every point was explicitly placed.

Open Questions & Resolutions (spec/plan inputs)

1. Tier-derivation compute location — client-side from the journey config, or API-served pre-classified.
2. Per-step aggregate API — the largest implementation cost (see Dependencies).
3. "Start first visit" flow — the highest-risk dependency (see Dependencies).
4. [RESOLVED — OQ4] Scheduled-appointment date. Investigated 2026-05-22 against the codebase: vcflow has no scheduled/appointment-date concept. Visits carry only relative windows (dateRange guards: an anchor + minDays/maxDays); anchors (enrollment, firstTreatment) are per-participant ISO dates in context.anchors; windows are computed at runtime in guards and are not exposed by any API today. Resolution: point 3 shows the computed window range + countdown-to-close, no scheduled-date headline. The aggregate API must compute the window per visit (Dependencies #1). Key file refs: apps/api/src/modules/journey/registry/types.ts:33-47 (JourneyContext.anchors), types.ts:59-65 (DateRangeGuardConfig), apps/api/src/modules/journey/registry/guard.registry.ts:107-143 (the dateRange window computation), studies/PILOT-001/study.json:191-208 (example dateRange guards — isInV2Window, isInV3Window), apps/api/src/modules/forms/entities/form-response.entity.ts:47 (visitRef column — string only, no date field).
5. [RESOLVED — OQ5] Journey-config schema for D3. Investigated 2026-05-22 against machine.factory.ts, guard.registry.ts, types.ts. Findings: (a) window policy — soft is exactly today's behavior (a dateRange guard failure records a deviation and the transition proceeds); hard is a small net-new per-state flag windowPolicy: 'hard' | 'soft' (default 'soft'). (b) next-step structure — the engine models one form per state, chains forms sequentially, and groups them into a visit by meta.visitRef; there is no unordered-set construct, and the dashboard does not need one (order-agnostic by design — see §Journey-config-driven behavior). (c) data-completion separation — already real: FormResponse rows persist independently of the XState machine; a past visit's form can be filled after the frontier advances. Resolution: the only net-new config is the windowPolicy flag; everything else D3 needs already exists. Key file refs: apps/api/src/modules/journey/registry/machine.factory.ts:88-149 (createJourneyMachine), machine.factory.ts:42-75 (transformStates), machine.factory.ts:22-32 + :62-65 (TransitionConfig + array-transitions for guarded branching), apps/api/src/modules/journey/registry/types.ts:162-178 (StateMeta / StateDefinition — no windowPolicy today; this is where the field gets added), apps/api/src/modules/journey/registry/guard.registry.ts:107-143 + :149 (dateRange + formCompleted guards), apps/api/src/modules/journey/entities/journey-state.entity.ts:40-44 (currentState + snapshot), apps/api/src/modules/journey/activities/journey.activities.ts:69 (getPersistedSnapshot), apps/api/src/modules/forms/entities/form-response.entity.ts:16-103 (FormResponse — independent of journey), apps/api/src/modules/forms/services/form-journey-bridge.service.ts:87-93 (onFormCompleted → signal journey), apps/api/src/modules/journey/services/participant-timeline.service.ts:108-120 (form responses + state history merged separately in the timeline), studies/EXAMPLE-001/study.json:76-135 and studies/PILOT-001/study.json (visit/state definitions, meta.visitRef grouping, transition arrays with recordWindowDeviation fallthrough).
6. CRA query attach point — value-level queries need a field reference; designing the in-form field picker depends on forms gaining a monitor-review mode. Slice 1 designs the dashboard-side affordance only.
7. Tablet collapse — responsive two-pane → single-pane, co-designed with the Now banner.
8. Monitor-role zone-level permissions — the CRA view is not just an added affordance; a monitor must not execute clinical data capture. Which buttons and actions each zone hides or disables for the monitor role needs an explicit per-zone permission map. Spec input.

Success Criteria

• A coordinator opening a participant identifies the single next action in under 2 seconds, without scrolling or reading microcopy.
• The surface never shows a future visit with the same visual weight as the current one, and never hides past/future entirely.
• An overdue visit is unmistakable at a glance; a soft-window overdue visit stays collectable out of window and a hard-window one is clearly marked missed, both recording a deviation + reason (D3 / D8).
• Every panel maps to a coordinator (or monitor) task; none is decoration.
• No action on the surface has two executors (D1).
• Every one of the 8 review points is explicitly placed (Slice 1 or Slice 2+) and visible in the strawman narrative.
• Mockup approved at the wireframe-rework checkpoint; on approval, a Rule-A spec is authored at docs/superpowers/specs/2026-05-2X-clinician-ecoa-per-participant-view-design.md (implementation_project: vcflow), then a plan, then implementation targeting Demo #2 (2026-06-06).

Distribution Plan

Not applicable — the deliverable is a route inside the already-deployed apps/staff Angular app (Cloudflare Pages), covered by the existing CD pipeline.

Dependencies

Implementation prerequisites, ordered by magnitude — spec/plan inputs, not Slice 1 design work:

1. Per-step aggregate API — the largest single implementation cost. All work-surface zones key off visit/step; v2 adds ePRO and lab-result data to that aggregate. No endpoint today serves forms + queries + edit-check failures
   • signatures + audit + ePRO + labs keyed by step. Scope as its own backend task. Because ePRO and lab data have independent backend readiness (#4, #5), the aggregate must degrade per-domain — a missing or not-yet-shipped domain returns an empty result, never fails the whole response. The aggregate also owns three computations the codebase does not expose today (surfaced by OQ4/OQ5): (a) group journey states into visits by meta.visitRef; (b) compute each visit's calendar window from context.anchors + the visit's dateRange config (today that config lives inside guard definitions and the visit→window mapping is implicit — the API needs an explicit mapping); (c) compute each visit's completeness from its FormResponse rows (drives the Done-tier "Data outstanding → Complete" flip). Starting points: apps/api/src/modules/journey/services/participant-timeline.service.ts:48-196 (current timeline shape — incomplete for the aggregate); apps/staff/src/app/features/participants/participant-detail.component.ts:260-275 (current dashboard fetch — two endpoints today).
2. "Start first visit" flow — the highest-risk dependency. Current form navigation requires an existing formResponseId (participant-detail.component.ts:282); a freshly-enrolled participant has none. First-form creation is net-new client + backend work.
3. D3 — windowPolicy flag + deviation recording. Reduced after OQ5: the only net-new journey-config is a per-state windowPolicy: 'hard' | 'soft' flag (default 'soft' = current behavior), plus hard-window enforcement (block the transition when a hard window has closed). Recording a protocol deviation + structured reason on out-of-window collection or a missed visit is also net-new; the deviation-reason picklist taxonomy needs a source (protocol-defined or a standard deviation-reason list). Per-visit data-completion tracking is not net-new — FormResponse already persists independently of the journey (OQ5c). Starting points: apps/api/src/modules/journey/registry/guard.registry.ts:107-143 (current soft-window behavior — the place to extend with hard-window enforcement); studies/PILOT-001/study.json:191-208 + transition arrays (the recordWindowDeviation fallthrough pattern — the place to wire the windowPolicy: 'hard' branch); apps/api/src/modules/journey/registry/types.ts:162-178 (StateMeta / StateDefinition — where the windowPolicy field gets added).
4. ePRO data source (D2). Zone 4 depends on work-vcflow-epro exposing queryable participant ePRO entries. If ePRO data does not exist when Slice 1 ships, Zone 4 renders its empty state.
5. External lab data model (point 5). Zone 6 depends on a model for lab results attached to a participant/visit, plus document storage for the source PDF. The intake/upload path is Slice 2+.
6. Monitor-role query-raise (D4). The query backend already exists (2026-05-06-queries-and-soft-checks); the net-new work is the in-context raise affordance + prefilled composer, and (Open Question 6) a forms monitor-review mode for value-level queries.
7. Net-new components: ParticipantJourneyRail, a compact open-items list, an ePRO-summary zone, a lab-results zone, a coordinator-first pi-sig-banner wrapper, and the confirmation-dialog pattern.

Adjacent surfaces that must not collide: /casebook (visit-matrix.component), /signing + /signing/:id (point 4 feeds this), /dashboard.

The eventual spec must be authored on a feature branch (per ~/code/ branching policy).

Out of Scope for Slice 1

Tools panel, Reports panel, Unscheduled-Visit catch-all, per-test status grid — all Slice 2+. Cross-participant triage stays in /casebook. The cross-participant PI sign-off summary is /signing (point 4). The ePRO clinician-affirmation form, the lab-PDF intake mechanism, and per-form field-level pre-submit confirmation are all Slice 2+ / separate work. The deviation exclusion-review surface — where the PI / medical monitor / sponsor judges whether a recorded deviation is exclusionary — is a separate downstream surface, not this dashboard. libs/shared-ui polish is a separate task.

The Assignment

Take the reworked mockup to the wireframe-rework checkpoint and walk it against the §Wireframe Rework Checklist — confirm each of the 8 points landed where this doc says. The state-to-state shape change (newly-enrolled → in-progress → awaiting-signature → overdue → out-of-window handling → monitor-role) is what sells the journey-engine wedge; a static frame does not. On approval, the next concrete action is authoring the Rule-A spec on a feature branch.

What I noticed about how you think

• Your triage instruction — "for each point, make an explicit call, do not silently drop a point because it looks like Slice 2" — is the move that keeps scope honest. The easy failure here is to quietly let points 4 and 7 evaporate because they straddle a boundary. You pre-empted it.
• "Highlight the next recommended action rather than forcing it... the design must recommend, not gate" turned out to be a single unifying principle, not one point. It resolved point 1 (banner), shaped point 6 (override, not a block), and is the reason machine-availability sequencing is a non-issue. You gave the rework its spine in one sentence.
• "Machine availability, not protocol prescription — and that is fine, it makes no difference to protocol integrity" — that is domain knowledge a designer guessing from the vcpi screenshot could not have. It is the difference between a dashboard that fights the clinic and one that fits it.