Graduation Report View

Objective & scope

Give Jes one place to see a graduating 1:1 client's outcome picture, review it, and close the file — replacing three manual habits with one system action.

In scope: a staff-facing Graduation Report section on the existing client detail screen (practitioner console); a single "Graduate" action that approves the report and closes the client file in one step; a client-facing page that appears only after approval, showing only the sections that have real data.

Out of scope: PDF export, print layout, a shareable public link, an all-clients graduation dashboard, any AI-generated narrative, any new symptom-trend visualization beyond a two-point intake-vs-graduation comparison. Each is addressed with a reason in Deliberately Left Out.

Capture-first requirements

This spec works backward from the report. Below is everything that has to be true — schema applied, a button that exists, a habit someone remembers — before a graduating client's report has real content instead of honest placeholders. Ordered by how badly its absence breaks the feature.

Role vocabulary — pick one, and it's this one

Two vocabularies coexist in the codebase today: the retired admin / coach / onboarding labels, and the ranked ladder owner (3) / practitioner (2) / sales (1) / none (0) that the 2026-09-02 role-ladder migration introduced and that every file written since uses exclusively. This spec is written against the ladder, and every new object it defines uses current_staff_rank()/current_staff_role() with the new labels only. No new SQL in this feature references 'admin', 'coach', or 'onboarding', full stop.

Access rule for everything new in this spec: current_staff_rank() >= 2, further scoped to assigned_coach = auth.uid() for rank-2 (practitioner) callers, unconditional for rank-3 (owner). This is the exact shape already used by client_practitioner_notes and (post-hotfix) coaching_sessions — nothing new is invented here.

Data sources per field

Every field the report shows, where it actually comes from, and its honest status. LIVE exists today and works. NEEDS-MIGRATION / NEEDS-BUILD the schema or a small piece of UI doesn't exist yet. CAPTURE GAP the schema exists but nothing makes the data get entered.

Explicitly not sourced — no honest data exists

The order is specific that these must not be invented. None have a live path into this database:

• Lab marker before/after values. Marker data never leaves the local Mac Mini pipeline; only a rendered PDF crosses the boundary. Not included.
• Food & Mood Journal insights. The app writes journal entries to device AsyncStorage only — never synced to Supabase. Matches the existing "awaiting the Food and Mood Journal" placeholder already shipped in practitioner.js.
• Structured action steps. No table for this exists anywhere in either repo.
• Per-symptom duration + severity trend. assessment_results gives at most two point-in-time snapshots (intake, graduation), never a time series. This report shows a two-point comparison, not a trend line, and does not manufacture one.

Data model changes

Deliberately small. No new tables. No RLS widening — every existing read policy on coaching_clients, client_forms, assessment_results, and coaching_sessions already exposes what this feature needs to whoever already had it; this spec only assembles it into one screen.

1. Two columns on coaching_clients

alter table public.coaching_clients
  add column if not exists graduation_report_approved_at timestamptz,
  add column if not exists graduation_report_approved_by uuid
    references public.staff_members(user_id);

No RLS change needed. "coaching_clients: client reads own" already exposes every column on her own row; the staff read policy (once item 1 above is confirmed correct) already exposes every column to rank-2+ staff.

2. One RPC: graduate_client(p_client_id uuid)

Does both jobs Jes currently does by hand — closes the file and approves the report — in one atomic call:

• Rejects if caller's current_staff_rank() < 2, or if rank = 2 (practitioner) and assigned_coach <> auth.uid().
• Rejects with a clear message if the client's current status is 'prospect' or 'withdrawn' — a mis-click cannot graduate someone who never got there.
• Sets status = 'completed', completed_at = coalesce(completed_at, now()) — never overwrites an existing completion date.
• Sets graduation_report_approved_at = now(), graduation_report_approved_by = auth.uid() — always overwrites, since re-approval after a correction is the intended second-call behavior.
• security definer, revoke all ... grant execute to authenticated — the real authorization boundary is the function body's rank check, same pattern as every other write RPC in this schema (create_coaching_session, assign_form_to_client).

3. One new RLS policy: course_lesson_progress: staff read

create policy "course_lesson_progress: staff read"
  on public.course_lesson_progress for select
  to authenticated
  using (
    current_staff_role() = 'owner'
    or (
      current_staff_role() = 'practitioner'
      and user_id in (
        select cc.user_id from public.coaching_clients cc
        where cc.assigned_coach = auth.uid()
      )
    )
  );

The only genuinely new read surface this spec introduces. It exposes completion percentages and timestamps only — no lesson content, no course answers, nothing beyond what "how far along is she" requires.

View states

Staff — Graduation Report section (client detail screen)

Visible when current_staff_rank() >= 2 for a client whose status is 'active' or 'completed'. Not shown for 'prospect' or 'withdrawn'. Five sections render independently — one section running short never blocks the other four.

Client-facing — "Your Graduation Report"

A single new page in the portal. Before approval, it does not exist for her — no locked state, no "coming soon," nothing to see, because she has no reason to expect it yet. After graduation_report_approved_at is set, the page renders warmly and plainly, showing only the sections that have complete data at the moment she opens it. An incomplete section is omitted entirely — never shown broken, never shown with a red placeholder tag. client_practitioner_notes is never read by this page under any state.

Sign-off flow

1. Near the end of the program, Jes opens the client's Graduation Report section and reviews what's there.
2. If the Reflection form hasn't been assigned yet, she clicks "Assign Reflection form" (item 4). She separately prompts the client, by message or on a call, to also retake her Symptom & Systems Assessment.
3. The client completes the Reflection form — and, ideally, retakes the assessment — herself, in the portal.
4. Jes returns to the section once submitted and reviews the full picture with the client on the final call.
5. Jes clicks "Graduate [Name]." This calls graduate_client(client_id), which sets status, stamps completion (first time only), and stamps approval — one transaction, one click.
6. The client's portal now shows "Your Graduation Report," rendering whatever has complete data at the moment she opens it.

Sign-off is never hard-blocked by missing data. If a section is in its "not enough data yet" state, clicking "Graduate" shows one inline line — "Some sections are still empty — graduate anyway?" — not a modal, not a separate review page. Confirming proceeds.

Edge cases

Acceptance criteria

• The coaching_clients: staff read policy is verified against the live database to use the current role vocabulary (owner/practitioner/sales) before this feature ships — confirmed by querying as Maria (practitioner) and as Izzy (sales), not by reading the policy text.
• intake_forms_repeatable_and_discretionary.sql is applied to production; a real client can submit the Reflection form, and its answers are reachable at client_forms.answers under the same field ids as the Onboarding Questionnaire.
• video_sessions_phase1c_role_ladder_hotfix.sql and video_sessions_phase2.sql are applied (or confirmed already live); a rank-2+ staff member can create a coaching_sessions row for an active client who has a signed Client Services Agreement.
• A new "Assign Reflection form" control in the practitioner console calls assign_form_to_client(client_id, 'reflection') and a new client_forms row appears with status 'assigned'.
• The new course_lesson_progress: staff read policy exists; a practitioner-rank query for an assigned client's user_id returns rows; the same query for a non-assigned client's user_id returns zero rows.
• coaching_clients gains graduation_report_approved_at/graduation_report_approved_by, both null by default on every existing row.
• graduate_client(p_client_id) exists, is callable only at rank ≥ 2 (scoped to assigned_coach at rank 2), sets status/completion/approval correctly on a first call, and is idempotent on a second call — does not clobber an existing completed_at, does refresh approved_at/approved_by.
• Calling graduate_client() against a 'prospect' or 'withdrawn' client raises an exception and changes no row.
• The staff Graduation Report section renders all five sections independently; a section with insufficient data shows its own labeled placeholder without blocking the other four from rendering.
• The symptom burden section correctly handles 0, 1, and 2+ assessment_results rows per the three states in View States, and never computes a delta from a single sitting.
• The quality-of-life section maps onboarding and reflection answers by their seven shared field ids and shows a directional indicator per pillar, only where both a start and end value exist.
• The client-facing "Your Graduation Report" page is unreachable for a client whose graduation_report_approved_at is null — verified by a direct navigation attempt as that client, not by hiding a nav link.
• Once approved, the client-facing page shows only sections with complete data at render time; an incomplete section is fully absent, never shown with a placeholder or partial state.
• The client-facing page never renders any value sourced from client_practitioner_notes, under any state.
• No SQL added by this feature references the role literals 'admin', 'coach', or 'onboarding'.

Deliberately left out

• PDF / print / share-link export. A real future need, but a materially different rendering surface (print CSS, a public unauthenticated token, or an attachment pipeline) that nothing in the order asked for. Cut; she reads it in her own portal, same access model as everything else there.
• Snapshotting the report at the moment of approval. Considered, matching the protocol_publish_events audit-table pattern already used elsewhere. Cut: this is a one-time celebratory recap, not a legal or clinical record — the cost of a new audit table and versioning logic isn't earned by the actual risk of a later correction quietly improving accuracy on something nobody re-opens. Revisit if this ever needs to become an exportable or legally-relevant artifact.
• Hard-blocking sign-off on missing data. Considered a validation gate that refuses "Graduate" until every section is complete. Cut: real clients will legitimately graduate with a gap (declined the assessment, withdrew from the course), and a hard block just trains staff to route around it.
• A cross-client graduation dashboard. Not asked for. The roster already exists (staff_list_active_clients()); this spec touches only the single-client detail view.
• Using calcom_bookings or intro_bookings as the session-count source. Both exist for different jobs — team calendar view, pre-program purchase tracking — and neither carries a reliable client_id link the way coaching_sessions does.
• Any AI-generated narrative. Nothing in the order calls for one, and generating one would add a whole review-and-edit obligation for zero benefit — every word this report shows a client is either her own submitted text or a plain computed number or date. Nothing to review because nothing is generated.
• Rewriting the 7-pillar scale's copy. Out of scope; Jes's own outstanding wording pass on that content is independent of this spec and doesn't block it.
• Per-symptom duration + severity trend. Excluded per the order; no honest source exists for it.
• Lab markers and Food & Mood Journal content. Excluded; neither lives in a database this report can query.

Open questions for the General

1. Does Jes's "1:1 success metric" spreadsheet get retired the moment this ships, or does it track an aggregate across all clients that this single-client view was never meant to replace? If it should retire, worth a short follow-up pointing her at this view instead; if not, worth saying so explicitly.
2. Confirm live: has coaching_clients: staff read actually been corrected off the old role literals, or is the roster genuinely dark for every staff member right now? Blocks this feature and the entire practitioner console.
3. Confirm live: are video_sessions_phase1c_role_ladder_hotfix.sql and video_sessions_phase2.sql applied? If not, decide whether to apply them as a prerequisite here or accept "0 sessions, always" as this report's interim state.
4. Should a withdrawn client ever get a lightweight version of this ("how far she got")? Assumed graduation-only for this pass — flagging in case there's a business reason (partial-refund conversations, win-back outreach) to want one for withdrawals too.