Profile (Doctor)
Feature Overview
The Doctor Profile is the unified store of user attributes that drive every personalised platform behaviour — which logbook appears, what their CPD compliance target is, which geofence triggers the timesheet, whose cohort insights they feed into, and what roadmap the dashboard prefills. Profile fields are referenced by most other features: when we say "PGY drives roadmap" in the Dashboard spec, or "Job Description drives logbook type" in the Logbook spec, the field lives here.
📌 Terminology anchor — this spec is the definitive source for field names, allowed values, and downstream consequences. Other specs that reference Profile fields (Dashboard, Logbook, Timesheet, CPD, Wellness, Organisational Dashboard, Attendance) should link here rather than redefining.
Open Questions
| # | Question | Owner |
|---|---|---|
| Q10 | Personal-email sign-up warning — confirm the final wording. Matt 2026-05-19 chose Option 1 (prominent warning) and asked to "show me the prompt to confirm language"; shipping copy is currently a placeholder pending that sign-off (#7852). | Matt |
| Q11 | Supervisor / appraiser selection model (#9168) — confirm: (a) "Add your hospital" + "Nominate your appraiser" become Outstanding-Onboarding nudges rather than hard-required fields; (b) resolved, #12870 — the supervisor picklist shows consultants at the doctor's hospital(s) + matching speciality first, with the full pool still searchable; (c) resolved — consultant-only (Matt, #9168); (d) off-platform appraisers can be added by name/email/title/contact for WBA/feedback messaging, and which data model (user-level external fields vs reuse per-hospital external approver). Drives the five profile.supervisor.* / profile.onboarding.add-hospital-step ⏳ ACs. | Matt |
Closed Questions (10) — click to expand
| # | Question | Resolution |
|---|---|---|
| Q1 | UK region field — ?Wessex or other determinant | Matt 2026-05-27 — the Organisation/State field is State in AU and County in the UK. |
| Q2 | Non-PPP Timesheet Approver — full walkthrough (email, signature, forward) | Resolved (Engineering) — branded approval email + /approve-timesheets/{token} page + rejection + admin-forward all built; drawn signature shipped. |
| Q3 | Enterprise-cadence website-comms update — engineering-automated or ops? | Matt 2026-05-27 — owned by the Hospital admin (an ops action, not an engineering/CI trigger). |
| Q4 | PGY computation — UK academic-year equivalent (AU resolved: Feb) | Matt 2026-05-27 — UK uses the same annual-year basis as AU. |
| Q5 | Registered-specialist flag — on Profile or on the Sign-up record? | Resolved (Engineering) — lives on Profile, sourced at sign-up; with Speciality it drives the CPD high-level requirement set. |
| Q6 | AMC reciprocal API — connect to AMC approved-CPD-homes list? | Deferred — out of scope until AMC accreditation lands; revisit post-approval. |
| Q7 | Enterprise access — how do Hospital / Super / Executive Admins sign in? | Matt 2026-05-27 — admins have a non-doctor sign-up and sign in the same way doctors do. |
| Q8 | My Hospitals Remove — "entered in error?" prompt, or audit-log only? | Resolved — built a confirm-gated Remove plus a full add/remove/update audit log; the confirm dialog satisfies the prompt ask. |
| Q9 | AU/UK field parity — one shared schema? | Matt 2026-05-27 — one shared schema; separate AU and UK prod deployments, data resides in one country, with a migration tool designed later. |
| Q11 | Job-role / grade controlled value set — fixed pick-list or free text? (#7913) | Resolved — Option A (#7913): the job-role / grade control is a fixed, Super-Admin-editable pick-list reusing the existing Job Titles list from sign-up (trpc.ppp.jobTitles.publicList / job_titles table) — not free text. Confirmed by Matt's Notion brief (Job Description is a fixed SA-editable list), the existing code, and Matt's comment ("Don't we already have a job roles list from the sign up?"). No new value-set / migration; pre-existing free-text grades stay displayable but the next change must be chosen from the list. |
Acceptance Criteria
Core — profile data model
- ⏳ One Profile entity persists every field — no split across tables for presentation only.
- ✅
profile.edit.single-page— profile is editable from a single page; edits apply without re-onboarding. ‡ - ⏳ Every field has one authoritative Zod validator shared between frontend and backend.
Account types and billing
- ⏳ Four account types exist: CPD-only; CPD+PPP; CPD+PPP+Hospital; Hospital-only. †
- ⏳ Payment history leaves the profile view; a Billing section holds history, invoices, and an upgrade CTA. †
- ⏳ Currency follows the deployment instance (AU=AUD, UK=GBP); no per-user currency field. †
Professional identity
- ⏳ Job Description is a closed enum (incl. Consultant/Non-Consultant Other); no "registrar", no free-text. †
- ⏳ Job Description maps deterministically to
logbookVariant(surgical/practical); Logbook reads the flag. - ⏳ PGY is derived server-side from
graduationYear; users edit the year, not PGY. - ⏳ PGY uses an annual-year basis (AU from February; UK confirmed the same).
- ⏳ PGY 1 is the first academic year AFTER graduation; the graduation year itself is PGY 0 (so a 2014 graduate is PGY 12 in 2026, not 13). †
- ✅
profile.pgy.prevocational-pathway— PGY collected for all doctors, shown only on non-consultant profiles; PGY1/PGY2 get the National Prevocational Pathway as the Roadmap pre-fill. † ‡ - ⏳ Speciality/Department supports one primary plus an optional secondary department.
- ⏳ Registered-specialist flag + Speciality drives the CPD high-level requirement set.
- ✅
profile.specialty-change.hlsr-refresh— changing Speciality refreshes the HLSR set, clears prior ticks, and warns before clearing an existing attestation. † ‡ - ✅
profile.logbook-variant.user-guide-dynamic— user-guide and nav text say "Surgical" or "Procedural" Logbook bylogbookVariant; no hard-coded "Surgical" strings. † ‡
Job Role / Grade history
- ✅
profile.job-role.history— job-role/grade changes are recorded as history (effective date, prior → new grade); adding a change closes the prior open entry and syncs the current grade; My Profile shows the current role plus a viewable change history. Tracks job role only — PGY (graduation-derived) and consultant-status (registration-driven) are out of scope. † † ‡ - ✅
profile.job-role.grade-picklist— the "New job role / grade" control is a controlled, Super-Admin-editable pick-list (the existing Job Titles list reused from sign-up,trpc.ppp.jobTitles.publicList/job_titlestable), not free text; the selected title persists intoppp_job_role_history.gradeand syncspppHrPassport.grade. No new value-set or migration; pre-existing free-text grade values remain displayable but the next recorded change must be chosen from the list. (Q11 → Option A) † ‡ - ✅
profile.job-role.evidence-verification— a role change can carry an optional offer-letter upload (attachable after the fact) and routes through the existing PPP verification (super-admin / hospital-admin attestation, reusing the Passport pending→verified pattern); verified vs unverified is clearly indicated and doctors cannot self-verify. † ‡
Consultant status (User Type)
- ✅
profile.user-type.registration-derived— User Type (Consultant / Non-Consultant) is derived from the doctor's AHPRA/GMC registration and is editable only by a Super Admin; the field carries explainer text so a read-only "Non-Consultant" value is not mistaken for a bug. † ‡
Supervisors
✅
profile.supervisor.distinct-roles— a doctor's Clinical Supervisor cannot also be their Professional Supervisor; enforced identically on both sides of the wire — the frontend form hard-blocks save with a clear inline message (My Profile edit + onboarding Road Map) and the backendupdateUserProfileprocedure rejects a conflicting direct API call withBAD_REQUEST(#10225), so a raw tRPC/script/mobile call cannot bypass the governance rule. † ‡✅
profile.supervisor.picklist-hospital-speciality-scoped— Built in #12870 (Matt 2026-06-30 on #8171, restated by Rob 2026-07-10: "smart list option... consultants of hospital and department/speciality"; "profiles searchable for user"). The Professional Supervisor, Clinical Supervisor(s) and Colleague Appraiser pickers list consultants at any of the doctor's linked hospitals who share the doctor's speciality first, under an "At your hospital" group; the rest of the consultant pool follows under "Other consultants" and typing still searches all of it. A doctor with no linked hospital (or with no consultant match) sees the plain full list. Hospital-only scoping applies when the doctor has no speciality. Backend:getConsultantUserstakes an optionalhospitalIdsarray (the singlehospitalIdlogbook input is unchanged). The doctor↔hospital link (userAssignedHospitals) and the speciality-scoped admin pattern (hospitalAdminsView.specialtyId, already used for timesheet-approval routing) already exist — this AC leverages them for the picklist rather than building new hierarchy. Current state: the picklist is platform-wide consultants only (users.getConsultantUsers), un-scoped by hospital or speciality. † ‡✅
profile.supervisor.eligibility-level— Confirmed consultant-only (Matt 2026-06-23 on #9168: for a non-consultant the supervisor is "of more seniority"; Rob's 2026-06-24 call note: "the supervisor is more senior (a consultant)"). PGY1/PGY2 and all non-consultants are excluded. † ‡⚠️
profile.supervisor.off-platform-nomination— Decided on #9168 (Matt 2026-06-24: off-platform by email allowed, "Option A"; Rob 2026-06-30 confirms the confirmation handshake). Partly built (#12872): a consultant's Colleague Appraiser can be an off-platform nominee with name, email and an optional title (helper text: a same-grade colleague, not a supervisor); a non-consultant's Professional Supervisor can be an off-platform nominee (name, email required, title optional,externalEducationalSupervisor*columns) and Clinical Supervisor(s) can include off-platform nominees alongside PPP users (externalClinicalSupervisorsJSONB). An off-platform nominee counts as a supervisor for "Complete your profile" and the Nominate-your-appraiser step. Emails are format-checked on both client and server and a nominee needs both name and email. Not built (still drift): the confirmation handshake with Pending / Confirmed / Declined status and tokenised email invites with the join-PPP upsell (AC5/AC6), and choosing the off-platform nominee as the recipient of a WBA / appraisal / feedback request (AC7, todayactivity.assessorIdis PPP-user-only).✅
profile.supervisor.appraiser-nudge-not-hard-required— Colleague Appraiser is surfaced as an Outstanding Onboarding checklist item ("Nominate your appraiser") rather than a hard-required profile field; the misleadingrequiredasterisk (the field isnullishand never enforced) has been removed. Consultants only (non-consultants' Educational/Clinical Supervisors are already required via "Complete your profile"). † ‡✅
profile.onboarding.add-hospital-step— "Add your hospital" is its own Outstanding Onboarding step (full-platform doctors), the prerequisite that unlocks Smart GeoTag, timesheet-approver suggestions and the (proposed) hospital-scoped supervisor picklist. Ticks once any hospital is linked. Previously hospital linking was only bundled inside the "Use Smart GeoTag to enter first timesheet entry" step. † ‡
Profile picture / avatar
- ✅
profile.avatar.display-resolution— profile picture renders external URLs and public-asset paths directly; only blob keys are signed. ‡ - ✅
profile.avatar.persona-comic-seed— seeded test accounts display their registry persona's Pixar-style comic avatar. † ‡ - ✅
profile.avatar.upload-persists— uploading a new profile picture persists it to the user's profile record immediately on upload success, so it survives reload and re-login. My Profile autosaves on blur (no Submit button, #7741) and an avatar upload never blurs a field, so the upload must trigger the save itself rather than wait for a blur that never comes. † ‡ - ✅
profile.avatar.click-to-enlarge— clicking/tapping the small profile picture opens an enlarged view of the same image. On the Profile page the avatar click enlarges when a photo exists (the camera badge keeps uploading); from the header the avatar click opens the user menu (primary nav) and enlarging is not offered there — the redundant "View photo" menu item was removed (#10129) because the Profile-page click-to-enlarge plus the camera badge's change/upload already cover viewing and changing the photo. Scoped strictly to enlarge: no upload-options-on-click, no CV/Passport surfacing (that is #9913). † ‡
Medical registration
- ✅
profile.registration.pca-api— AU registration verification targets PCA (Provider Connect Australia) for format/existence checks. † ‡ - ✅
profile.registration.pca-automated-check— AHPRA verified automatically; first check cached on the user record, refreshed on the annual recheck. † ‡ - ✅
profile.registration.multiple-bodies— a profile can hold multiple registrations (e.g. AHPRA + GMC), each rechecked independently; the profile shows the primary prominently with a subtle "Add another registration" affordance that reveals the secondary list after onboarding. † † ‡ - ⏳ AHPRA validation on save checks format only — no live API call per save. †
- ✅
profile.registration.annual-recheck— an annual job re-validates each registration; lapses raise a profile alert + in-app notification; AHPRA results cached between runs. † † ‡ - ✅
profile.registration.annual-validity-check— the annual check runs for every user regardless of registration type. † ‡ - ✅
profile.registration.recheck-persists-status— the annual re-check persists each registration's status and last-checked date, shown on the profile. † ‡ - ✅
profile.registration.no-live-recheck-on-load— the primary registration card shows stored verification on load and re-verifies live only when edited. † ‡ - ✅
profile.registration.no-user-verify-button— the additional-registrations table exposes no per-row "Verify against live register" button; verification status comes from the yearly system refresh only. The auto-verify-on-add path (system-initiated, not user-facing) is preserved. † ‡ - ⏳ GMC verification functions for UK users (carried over from Morton Blue). †
- ⏳ The setup flow has no emergency-contact field — removed entirely. †
Authentication & linked accounts
- ✅
profile.auth.personal-email-recommended— sign-up shows a prominent, screen-reader-announced warning to use a personal email so a deactivated hospital email never locks the user out. Final copy pending Matt (see Open Questions). † ‡ - ✅
profile.auth.hospital-email-link-personal— a hospital-email user can link a personal email/SSO; address changes are held pending until the verification link is clicked. † ‡ - ⏳ "Linked Hospital Accounts" + "Linked Accounts" merge into one "Linked Emails" entity; unique backend ID, no mandatory primary email. †
Hospital / org hierarchy
- ⏳ User can attach one or more Hospitals. †
- ⏳ Each Hospital resolves upward to HHS/Trust → Organisation/State → Country in one lookup.
- ✅
profile.hospitals.hhs-trust-from-health-service— the Work & pay "HHS / Trust" field resolves from the hospital's linked Health Service, never the state code, and hides when none is linked. † ‡ - ✅
profile.hospital.attachment-activates-geofence— attaching a Hospital that has coordinates auto-creates an active, system-controlled geofence at the hospital's location, linked to that attachment; a doctor with two hospitals gets two boundaries. Idempotent — re-attaching reactivates the existing boundary. † † ‡ - ✅
profile.hospital.admin-bulk-assign-geofence— the admin/profile-form bulk hospital save arms one boundary per newly assigned hospital with coordinates and deactivates a removed hospital's boundary, leaving no orphaned active rows. † ‡ - ⏳ Detaching a Hospital deactivates its geofence and enter/exit toasts.
- ⏳ Users cannot set their own geo-fence; coordinates are system-controlled only. †
- ✅
profile.hospital.end-date-deactivates-geofence— an end-date on a Hospital attachment deactivates its geofence from that date; the record is retained for audit. † ‡ - ✅
profile.hospitals.remove-action— My Hospitals exposes a Remove button beside Edit for self-added rows (admin rows omit it). † ‡ - ✅
profile.hospitals.add-dialog-feedback— the Add Hospital dialog labels the start date "Start Date" with a single required asterisk, shows the required error only after the user has interacted with the field (never on open), and while "Add to Profile" is in flight shows a progress indicator with a status message, disables both actions, and cannot be dismissed. The backend attach runs its follow-up writes (audit entry, geotag arming; boundary marker, auto-timesheet activation) concurrently rather than as four serial commits. † ‡ (#12552) - ✅
profile.hospitals.loading-skeleton— while its memberships are loading, My Hospitals reserves one skeleton row per attached workplace (count from the cached current user; two rows on a cold cache) in place of a centred spinner — table-row blocks under a header bar from md up, card-sized blocks with no header below md, where workplaces render as stacked cards — so the table lands without moving the accordions below it; thehospitalMembership.getMyMembershipsquery is sent on its own (skipBatch) rather than in the profile page's request batch. † ‡ (#12554) - ✅
profile.hospitals.audit-log— every add/remove/update on My Hospitals is written to the audit log with actor, timestamp, and record. † ‡ - ✅
profile.hospitals.auto-refresh— adding a hospital refreshes the list with no page reload and persists across reloads. † ‡ - 🗑️
profile.hospitals.registry-self-add— removed (#8459): #8444 Option A made doctor search DB-only, so search never surfacedid:nullregistry rows and this self-add path was permanently unreachable. The Super-Admin curation tool (#8444 PR2, #8495/#8510) is now the sanctioned route for registry rows to enter the DB, so the doctor-side path was deleted rather than repurposed. † ‡ - ✅
profile.hospitals.search-db-only— doctor hospital search queries the DB only; the live NHS ODS / AIHW registry is never called on the doctor path. † ‡ - ✅
profile.hospitals.search-country-scoped— hospital reference data is scoped to the instance country (prod one of AU/GB, UAT both) by config, not hardcoded. † ‡ - 🗑️
profile.hospitals.search-local-first— superseded byprofile.hospitals.search-db-only(#8444): the registry fallback is removed entirely from the doctor path, so search is now DB-only rather than registry-when-local-empty. † ‡ - ✅
profile.hospitals.add-mobile-keyboard-safe— Find-a-Hospital search opens as a fullScreen-on-mobile dialog with the input above the results so the keyboard never hides them. † ‡ - ✅
profile.hospitals.curation-refresh— a Super Admin refreshes the hospital list from the registry APIs, upserting by source and never deleting. † ‡ - ✅
profile.hospitals.legacy-reconciliation— a refresh adopts a matching legacy source-less row in place (backfilling provenance) instead of duplicating it, and a Super-Admin pass classifies legacy NHS Trust / AU HHS parents non-selectable without deleting them. † ‡ - ✅
profile.hospitals.curation-hierarchy— curation marks NHS Trust/HHS parents non-selectable and sentence-cases names; only sites are pickable. † ‡ - ✅
profile.hospitals.curation-ui— a Super Admin previews a registry refresh, sees the diff counts and disappeared-ratio warning, then applies behind a confirmation; apply is gated until a preview runs. † ‡ - ✅
profile.hospitals.au-coordinates— every Australian hospital in the reference data carries valid latitude/longitude inside Australia's bounding box, so the mobile geofence auto-timesheet registers regions for AU users (closes the AU gap in #8219). † ‡ - ✅
profile.hospitals.location-attributes— the seed and one-click import carry the registry'sstateandsuburbthrough to the database (state→state, suburb→region) instead of dropping them, so AU sites are searchable by area, not just by name. † ‡
Open Question — legacy source-less hospital rows: ~2,959 existing rows have no
source/sourceId, so an AU refresh can insert AIHW sites alongside stale legacy abbreviations (duplicates) and legacy parents like "Metro North" stay selectable. Reconciliation (dedup-by-name on refresh, one-time source backfill, legacy parent classification, manual-edit precedence flag) tracked in #8498.
- ✅
profile.hospitals.name-sentence-case— hospital names render sentence-cased with acronyms preserved across doctor-facing web surfaces (admin curation views show stored values). † ‡ - ✅
profile.hospitals.admin-row-edit-leave— a doctor can Edit dates and "Leave" an admin-assigned hospital (Leave sets an end-date → geofence off, record kept); never a hard delete of the admin's assignment. Actions are always visible, not hover-only. † ‡ - ✅
profile.hospitals.workplaces-not-memberships— the My Hospitals section labels a doctor's linked hospitals "Workplaces", never "memberships". † ‡ - ✅
profile.panels.profile-always-expanded— Profile Details is always expanded (never collapsible) so the user can always see and edit their profile. † ‡ - ✅
profile.panels.secondary-collapsed-by-default— the secondary panels (Linked Emails, My Hospitals, PPP Passport Status, Wellness Data Sources) render collapsed on each page load. † ‡ - ✅
profile.panels.single-expand— opening a secondary panel collapses any other open secondary panel; Profile Details stays open. † ‡
Logbook case targets
- ✅
profile.logbook.case-target— settable total-cases and primary-surgeon-cases targets, used as logbook-widget denominators. † ‡
Payroll & timesheet approver
- ⏳
payrollIdandpayCycleStartDateare captured and editable. - ✅
profile.contract.completion-gate-required— Default Working-Calendar Start (jobContractStartDate) is a base requirement for the "Complete your profile" onboarding step, gated alongside regulatory body and registration number on every profile-completion surface. The My Profile form pre-populates the picker with 1 February (AU default) rather than leaving it blank, so the field always shows a real value once the form loads. That February is a pending change, not just a display default: it is sent with the next save/autosave, and re-picking it also saves (#12786). The pre-filled value is only persisted once the form is saved (on blur out of the form), not on page load alone. Payroll ID is also required for full-platform doctors. That rule is owned by onboarding-checklist.mdonboarding-checklist.profile-payroll-id-required, and it was built in #12728. This replaces the earlier wording here, "payrollIdstays OPTIONAL", which rested on a misquote of Rob's 2026-07-17 #10594 decision. That decision reads "incl. payroll ID", and Matt said on 2026-07-14 that the profile shouldn't be complete without it. † † ‡ - ✅
profile.contract.start-date-picker— the job/contract start date sets the default date-picker range for timesheet and CPD selectors. † ‡ - ✅
profile.contract.start-date-per-hospital— contract start dates are delineated per hospital in My Hospitals; the working year anchors on the earliest per-hospital start date with a user-level fallback then 1 Feb (AU). The Profile field is relabelled "Default Working-Calendar Start" and demoted to a fallback. † ‡ - ✅
profile.contract.working-calendar-month-only— the Default Working-Calendar Start picker collects a month only, not a year. † ‡ - ⚠️
profile.timesheet-approver.doctor-self-attach— drift (#12678, for-discussion). On My Profile, the doctor can attach their own timesheet approver, as well as their hospital, payroll number and pay-cycle day. The approver picker has two modes: a PPP user (scoped to Hospital + Department) or an external person entered by email, for a doctor who is not covered by a hospital (B2B) setup. Shipped: the two-mode picker exists (HospitalApproverTable, with external approver fields from #10632), but My Profile hides it (hideAssignedHospitals), and the unified My Hospitals card has no approver control. A doctor therefore cannot attach their own approver. Whether an admin must confirm the doctor's choice is open: timesheets.md Q7, mirrored intimesheets.approver.user-attaches-approver. † † ‡ (#12678) - ⏳ External-email approver flow emits an approval email with a signed magic link returning decision + signature.
- ⏳ Approved external timesheets forward to the user's admin/payroll destination automatically.
- ✅
profile.timesheet-approver.drawn-signature-required— the external approval page requires a drawn signature (not typed); it is stored and forwarded to payroll. † ‡ - ⏳ Open — needs Matt (
@matt-review-requested): exact contents, branding, and signature rules of the external approver email.
Cadence Meter
- ⏳ Cadence Meter is user-set or pre-filled from the user's Enterprise Agreement.
- ⏳ Enterprise pre-fill precedence: Enterprise default → user override (cannot escape a mandated minimum).
- ⏳ Cadence Meter values drive the Dashboard Roadmap widget's prefilled requirements.
- 🗑️
profile.cadence-meter.non-consultant-only— superseded byprofile.cadence-meter.consultant-msf-360(#12806): the Cadence Meter is no longer hidden wholesale for consultants. (Was: shows only for non-consultant roles; hidden for all consultant Job Descriptions, #4581.) † - ✅
profile.cadence-meter.consultant-msf-360— the Cadence Meter shows for every role (hidden only for admin-only profiles). A consultant sees only the Multi Source Feedback (MSF) and 360 Review rows; Case Based Discussion / Clinical Evaluation Exercise / Procedure Based Assessment / Surgical Skills Assessment (role grid) and the Multi Consultant Report (non-consultant only, #12754) stay non-consultant only (#12806). † ‡ - ⏳ Open — needs Matt: when an Enterprise cadence is preloaded, who owns the marketing-copy update trigger — engineering CI or an ops runbook?
HR Passport widget in profile
- ✅
profile.hr-passport.completion-indicator— the PPP Passport status (completion + the 6-domain Blue Tick checklist) is surfaced on the Passport page (/ppp-passport), not on the Doctor Profile; the Profile shows no inline passport content. (Earlier the Profile carried a completion chip (#6411); Matt 2026-06-03 moved the status onto the Passport page entirely.) † † ‡ - ✅
profile.hr-passport.ppp-plan-gated— the HR Passport widget is gated behind a PPP plan: it is hidden for CPD-only doctors (the HR Passport is a full-platform feature) and shown for CPD+PPP and above. † ‡
Edit & audit
- ✅
profile.edit.sticky-affordance— the Edit/Save/Discard header bar is sticky, so editing can start from anywhere on the page; the explicit-Edit and unsaved-changes guards remain. † ‡ - ⏳ Field changes that affect other features emit an event downstream features can subscribe to.
- ⏳ Profile edits are logged in an audit trail with before/after values, actor, timestamp.
- ✅
profile.security.no-mass-assignment— a profile save can only write user-editable profile fields. Privilege, billing, verification and lifecycle columns (super-admin / hospital-admin flags, verification status, persona / tier, account status, onboarding completion, payment and downgrade state, enterprise SSO binding, audit ids) cannot be set throughupdateUserProfile— a direct API call carrying one is rejectedBAD_REQUEST. A doctor cannot change their own account tier (accountAccess); only a super admin can, from the admin Users page (#12592). † ‡
Admin Hierarchy (23 Apr)
Used for permission gating on cohort insights:
- Hospital Admin — department / small-business-unit secretary or admin officer
- Hospital Super Admin — full hospital view
- Executive Admin — PPP-internal; group-anonymised cohort insights across hospitals, health services, organisations (renamed from "PPP Super Admin" per 23 Apr)
Higher tiers (Hospital Health Service / Organisation / e.g. Queensland Health) grant broader read-only views on anonymised cohorts. Not fully formed — depends on Matt's enterprise access story.
Downstream References
Features whose specs depend on Profile fields. When those specs are rebased, they should link here rather than duplicate field definitions.
| Feature | Profile field used | Consequence |
|---|---|---|
| Logbook | Job Description | Determines surgical vs practical variant |
| Dashboard → Roadmap | PGY, Cadence Meter | Pre-fills roadmap requirements |
| Timesheet | Hospital(s), Timesheet Approver, Payroll ID | Geofence + approval flow + payroll forwarding |
| CPD | Speciality, registered-specialist flag, Country | High-level requirement set + AMC CPD Home eligibility |
| Wellness (PPP Pulse) | Speciality, PGY (aggregation only) | Cohort aggregation; no personalisation driver today |
| Organisational Dashboard | Job Description, Speciality, Department, Hospital, HHS/Trust, Organisation, Country, PGY | Anonymised cohort grouping dimensions |
| Attendance | Hospital, Department | Group-invite filtering by Profile-matched cohort |
Status
Many fields and flows ship today (registration verification + annual recheck, My Hospitals add/remove/audit, case targets, contract-date anchoring, HR Passport widget, sticky edit). The unified Profile entity and the multi-registration UI are the main outstanding pieces.
| Sub-feature | Status | Notes |
|---|---|---|
| Unified Profile entity | 📋 Specified | Fields persist; not yet one consolidated entity |
| Registration verify + recheck | ✅ Built | AHPRA/GMC, annual scheduled job |
| My Hospitals (add/remove/audit) | ✅ Built | Auto-refresh-on-add bug still open |
| Multiple registrations (UI) | ⚠️ Partial | Schema landed; wizard + profile UI to follow |
| External-email Timesheet Approver | ✅ Built | Drawn-signature approval page in place |
| Cadence Meter (Enterprise) | ⚠️ Partial | Non-consultant gating built; Enterprise prefill TBD |
Open issues on label:feature:profile-doctor — issue data unavailable at build time.Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.
Closed Issues (33) — click to expand
| # | Delivered | State |
|---|---|---|
| #5564 | Notion brief deltas — fields, roles, hospitals, Passport widget | closed |
| #5619 | My Hospitals — Actions column buttons | closed |
| #5621 | Added profile fields (PGY, HHS/Trust, Org/State, Country, etc.) | closed |
| #5622 | My Hospitals — start/end dates, edit/remove, audit | closed |
| #5645 | Verify AHPRA yearly automated check | closed |
| #5917 | Annual AHPRA/GMC re-verification job | closed |
| #5959 | profile.specialty-change.hlsr-refresh | closed |
| #5962 | profile.logbook-variant.user-guide-dynamic | closed |
| #5965 | profile.hospital.end-date-deactivates-geofence | closed |
| #5971 | profile.timesheet-approver.drawn-signature-required | closed |
| #5976 | profile.cadence-meter.non-consultant-only | closed |
| #5986 | PPP Passport summary widget | closed |
| #6306 | AHPRA public-register scrape client | closed |
| #6349 | Annual re-verification job (PR for #5917) | merged |
| #6400 | profile.pgy.prevocational-pathway (design) | closed |
| #6401 | profile.registration.pca-api | closed |
| #6402 | profile.registration.pca-automated-check | closed |
| #6403 | profile.registration.multiple-bodies (initial) | closed |
| #6404 | profile.registration.annual-validity-check | closed |
| #6405 | profile.auth.personal-email-recommended (initial) | closed |
| #6406 | profile.auth.hospital-email-link-personal | closed |
| #6407 | profile.hospitals.remove-action | closed |
| #6408 | profile.hospitals.audit-log | closed |
| #6409 | profile.logbook.case-target | closed |
| #6410 | profile.contract.start-date-picker | closed |
| #6411 | profile.hr-passport.completion-indicator | closed |
| #6655 | Schema — userRegistrations multi-body support | closed |
| #7018 | profile.pgy.prevocational-pathway (build) | closed |
| #7020 | profile.registration.annual-recheck | closed |
| #7300 | profile.registration.multiple-bodies (follow-up) | closed |
| #7301 | profile.auth.personal-email-recommended (follow-up) | closed |
| #7383 | profile.edit.sticky-affordance | closed |
| #4581 | Hide WBA cadence tracker for Consultants | closed |
Change Log
| Date | Change | PR/Issue | Reason |
|---|---|---|---|
| 2026-10-04 | The February shown in Default Working-Calendar Start for a user with none saved is now a real pending change: the form baseline is the saved value (null), so the default is sent on the next save/autosave and re-picking February also saves. | #12786, #11189 | The default was only the form baseline, so it was never dirty: nothing was sent and the checklist item stayed open; re-picking February did nothing for the same reason. The Submit toast AC of #12786 is not built. |
| 2026-10-04 | The Cadence Tracker now renders for consultants with only the Multi Source Feedback (MSF) and 360 Review rows. profile.cadence-meter.non-consultant-only is superseded by profile.cadence-meter.consultant-msf-360. | #12806, #4581, #5976 | Rob's 4 Oct 2026 decision on #12806 (newest statement wins over the #4581 hide) is that MSF and 360 apply to every role, but the tracker was still hidden for consultants, so their MSF/360 default could never be shown or confirmed. CBD/CEX/PBA/SSA (role grid) and MCR (#12754) stay non-consultant only. |
| 2026-10-04 | The Professional Supervisor, Clinical Supervisor(s) and Colleague Appraiser pickers list consultants at the doctor's linked hospitals who share the doctor's speciality first ("At your hospital"), with the full consultant pool still searchable. Consultant-only seniority bar confirmed. | #12870, #11189 | Matt (#8171, 2026-06-30; #9168, 2026-06-23) asked for a hospital + speciality smart list on top of a searchable full list, and for supervisors to be more senior than the doctor. |
| 2026-10-04 | Off-platform nominees. A consultant's appraiser can carry a title; a non-consultant's Professional Supervisor and Clinical Supervisor(s) can be off-platform nominees (name, email, optional title). Nominees count for profile completion. The confirmation handshake and sending WBA requests to a nominee stay open. | #12872, #11189 | Decided on #9168 (Matt 2026-06-24, Rob 2026-06-30) and approved for build by Rob 2026-10-04 (migration 0257 adds the columns and rebuilds users_view). |
| 2026-10-03 | profile.contract.completion-gate-required no longer says payroll ID stays optional. It now points to onboarding-checklist.profile-payroll-id-required (drift, #12728). The pending "Approver picker supports two modes" AC is rewritten as profile.timesheet-approver.doctor-self-attach and marked drift (#12678). The picker exists, but My Profile hides it, so a doctor cannot attach their own approver. | #11189, #12728, #12678, #11181 | Task 3 handoffs on #12720, folded in by the Task 7 spec refresh. Sources are Matt 2026-07-14 (transcript), Rob's written 2026-07-17 decision on #10594, and Matt's #11181 brief (2026-07-29). |
| 2026-09-29 | updateUserProfile refuses with 409 CONFLICT an email address that another user already holds (case-insensitive). Changing to an unused address is unchanged. | #12617, #12616 | Security (#12616, PR #12617 review): the caller's identity email is their stored users.email, so taking a super admin's address made the email-keyed scope checks resolve that admin. |
| 2026-09-29 | Below md, the My Hospitals loading skeleton reserves card-sized blocks with no table-header bar, matching the stacked-card layout workplaces render in on phones and tablets. | #12554 | Live measurement at 375px on PR #12580 — the table-row skeleton reserved 245px against ~610px of stacked cards, so the accordions below jumped ~364px when memberships landed (now 61px at 375, -40px at 768). |
| 2026-09-28 | Add Hospital dialog - single asterisk on "Start Date", the required error waits until the field has been touched, and the save shows a progress indicator with a status message (actions disabled, not dismissable) while in flight. The backend attach runs its follow-up writes concurrently (audit entry + geotag arming; boundary marker + auto-timesheet activation) instead of four serial commits. | #12552 | 'Add to Profile' took ~25 s on UAT with no feedback (Async Task walkthrough 2026-09-28, Task 7, #11189 at 1:17). Measured on UAT at 26.9 s and 44.2 s while every other call was 150-400 ms; pg_stat_activity showed each commit of the attach waiting seconds on IO:WALSync (the NAS Postgres volume), so the serial chain of four commits was the cost. Running the independent writes together shares the flush; the dialog now shows progress for whatever time remains. The literal "Start Date *" label plus required produced MUI's second asterisk, and the error was bound to "value is empty" rather than to user interaction. |
| 2026-09-28 | My Hospitals reserves one skeleton row per attached workplace (from the cached current user; two rows on a cold cache) while memberships load, instead of a centred spinner, and its hospitalMembership.getMyMemberships query opts out of the profile page's request batch (skipBatch). | #12554 | My Hospitals showed a spinner for about 6 s (Async Task walkthrough 2026-09-28, Task 7, #11189 at 1:11). Measured on UAT the memberships query sat inside a 14-procedure, 2 MB profile-page batch (the full hospital list, consultant users, specialities...) and a tRPC batch resolves only when its slowest member has; the spinner also collapsed to the table's height on load, shifting the accordions below. |
| 2026-09-28 | updateUserProfile input is now an explicit .strict() allowlist of user-editable profile columns (derived from what the profile form, profile-picture save and dashboard target/layout saves actually send). Any other users column — isSuperAdmin, isHospitalAdmin/isHospitalSuperAdmin, isVerified, userPersona, tierLevel, accountStatus, timesheetApproverStatus, onboardingCompletedAt, payment*, pendingDowngradeAt, enterprise SSO binding, id/createdAt — is rejected BAD_REQUEST. accountAccess is dropped unless the caller is a super admin. New AC profile.security.no-mass-assignment. | #TBD, #12592 | Security (#12592): the input spread every users column, so a signed-in doctor could make themselves super admin or unlock the paid tier by calling the procedure directly on their own row (confirmed with a live-DB integration test). |
| 2026-07-17 | Default Working-Calendar Start (jobContractStartDate) becomes a base requirement gating the "Complete your profile" onboarding step; the My Profile picker now pre-populates 1 February (AU default) instead of showing blank. | #10594 | Matt's profile showed a completed-profile tick while the working-year-start picker was blank with no default populated. Rob asked for a defined, spec'd checklist of required fields. Payroll ID stays optional per Rob's 2026-07-17 decision. |
| 2026-07-09 | The #7342 supervisor-role-conflict rule (a doctor's Clinical Supervisor cannot also be their Professional Supervisor) is now enforced server-side too. The predicate hasSupervisorRoleConflict + SUPERVISOR_ROLE_CONFLICT_MESSAGE moved to packages-shared/ppp/src/constants/supervisor.ts as a single source of truth; the updateUserProfile procedure adds a cross-field .refine rejecting a conflicting direct API call with BAD_REQUEST. Frontend resolver re-exports and consumes the shared predicate (no duplicated logic). | #TBD, #10225 | Closes the backend enforcement gap in AC profile.supervisor.distinct-roles — the rule was frontend-only, so a raw tRPC/script/mobile call could write a conflicting pair straight past the "hard block, no exceptions" governance rule (same failure class as #10203). |
| 2026-07-08 | Fix: uploading a profile picture on the always-editable My Profile now persists ONLY the picture via a targeted update, instead of re-submitting the whole form. Previously the avatar persist sent every field to updateUserProfile, which re-validated fields the user never touched server-side. Updates the profile.avatar.upload-persists code pointer accordingly (AC behaviour is unchanged — the picture still persists immediately on upload). | #~, #10203 | Matt (user 17), on mobile 2026-07-08, uploaded a profile photo and saw the green "Profile picture uploaded successfully." toast together with a red "Failed to update profile" toast; the picture did not stick. The UAT backend log for his request showed updateUserProfile rejecting his cadenceTracker assessment targets (CBD/CEX/MCR/MSF/PBA/SSA/REVIEW_360) stored as 0 — the server rule is z.number().int().min(1) (#4897) while the client resolver allows min(0), so a trainee's legitimately-zero targets pass on the client but fail on the server. #10126's persist sent the whole raw form, so those 0s reached the server on a plain photo upload. Persisting only the picture means a photo upload never carries — nor re-validates — unrelated fields, removing this and the whole class of "raw form field the backend rejects" failures (e.g. dob as a Date). |
| 2026-07-08 | Removed the redundant "View photo" item from the persona/header user menu; enlarging now lives solely on the profile picture (click-to-enlarge) with the camera badge handling change/upload. | #10176, #10129 | Rob (Dev Session 2026-07-07) — the separate menu item is redundant now that the profile-page click-to-enlarge (#9901/#9920) shows a large version and the camera badge covers change/upload. |
| 2026-07-07 | Fix: uploading a profile picture on the always-editable My Profile no longer raises a "please fix the highlighted fields before saving" banner. The avatar persist now runs through a dedicated handler (handleProfilePicturePersist) that bypasses the whole-form Zod validation gate + invalid banner while still persisting the picture. Clarifies the profile.avatar.upload-persists code pointer accordingly (behaviour of the AC is unchanged — the picture still persists immediately on upload). | #~, #10126 | Matt (Dev Session 2026-07-07) reported that uploading a profile photo popped an orange "please fix the highlighted fields before saving" banner, yet no field was highlighted and there was no Save button. Root cause: the avatar persist was wired to the validation-gated submit (form.handleSubmit(handleSubmit, handleInvalid)), so an unrelated incomplete required field fired the invalid handler — and its banner pointed at fields hidden inside collapsed sections on the #7741 always-editable surface, which by design has no Save button. A photo upload is a discrete, already-valid action and must not be blocked by unrelated incomplete fields, so it now persists without the save-blocking banner. |
| 2026-07-01 | Add AC profile.avatar.click-to-enlarge — clicking/tapping the small profile picture opens an enlarged view of the same image (Profile-page avatar click enlarges; header adds a "View photo" menu item). | #9920, #9901 | Requested on the 2026-07-01 Dev Session (Rob/Matt) — enlarge the profile picture on click, as many apps do. Scoped strictly to enlarge (no upload-options-on-click, no CV/Passport #9913). Header interaction is an engineering default pending Matt (for-discussion). |
| 2026-07-01 | Add AC profile.avatar.upload-persists — an uploaded profile picture is persisted to the user's profile record immediately on upload success, so it survives reload and re-login. | #9915, #9791 | Uploaded profile photos were lost (#9791). My Profile autosaves on blur (no Submit button, #7741) and an avatar upload never blurs a field, so the whole-form save never fired and the storage key was never written to the users row. The AC codifies that the upload itself must trigger the save. |
| 2026-06-29 | Specialist wording + adjacency: registered-specialist status is verification-sourced (read-only, labeled "Registered specialist"), speciality picker moved adjacent to it, multi-speciality model added (user_specialities junction table + additional specialities UI), surgeon toggle decoupled from cadence (#8902). | #9775, #8181 | Matt direction — separate cadence from specialist/surgeon question; collect registered-specialist status from AHPRA/GMC verification; speciality selected by all users with multi-speciality support for rare edge cases; speciality drives logbook default subset. |
| 2026-06-29 | Rename "Educational Supervisor" → "Professional Supervisor" in AC profile.supervisor.distinct-roles description. | #9718, #9703 | Vernacular change requested by Matt (#9703) — "Professional Supervisor" is the correct term for non-consultant profiles platform-wide. |
| 2026-06-25 | My Profile Personal-details inputs now surface the correct mobile keyboard — Email uses type=email + inputMode=email and Phone uses type=tel + inputMode=tel, both with autoCapitalize=none autoCorrect=off. Added AC profile.form.mobile-keyboard (built). | #TBD, #9329 | Child of the #9320 mobile sweep. The Email/Phone fields in PersonalDetailsSection forwarded no type, so the wrong (text) keyboard appeared on mobile. ControlledTextField/PERSONAL_FIELDS already supported a type/inputProps; this just forwards the right hints. |
| 2026-06-24 | Removed the CV upload/view/replace control from My Profile (ACs profile.cv-upload + profile.cv-upload-validation marked removed). A CV is captured at sign-up and is managed in the PPP Passport (passport-cv.md, #9196); a settings page is the wrong home for a portable, shareable record. Onboarding specs updated to stop listing My Profile as a CV location. | #9205, #9202, #9194, #9196 | Rob (acting PO, 2026-06-24) — having a CV upload on the profile makes no sense when it is asked for at sign-up and lives in the PPP Passport. Removed the control from My Profile; the now-unused UpdateCV component was deleted. Sign-up CV privacy (public-blob) + robust orphan cleanup remain backend follow-ups under #9194. |
| 2026-06-23 | Specified the supervisor / Colleague-Appraiser selection model on the doctor profile (5 proposed ACs, pending Matt confirmation in #9168) — a hospital + speciality-scoped consultant picklist, an explicit seniority bar (consultant-level today), off-platform appraiser/supervisor nomination by name/email/title/contact for downstream WBA/feedback messaging, an Outstanding-Onboarding nudge for "Nominate your appraiser" instead of a cosmetic-required field, and a standalone "Add your hospital" onboarding step. Traces to Matt's Profile (Doctor) Notion brief. | #9174, #9173, #9168 | Sprint review of the doctor profile found the Colleague-Appraiser field shows a required asterisk that is never enforced, the picklist lists every platform consultant (not the doctor's hospital + speciality), and off-platform appraisers cannot be nominated on the profile — yet Matt's Notion brief already specifies the hospital/speciality smart list and the off-platform-by-email approver. The data hierarchy exists (userAssignedHospitals, hospitalAdminsView.specialtyId) but is not leveraged for the picklist. Captured as spec + #9168 so Matt can confirm before build. |
| 2026-06-19 | The My Profile "New job role / grade" control is now a controlled, Super-Admin-editable pick-list (the existing Job Titles list reused from sign-up, trpc.ppp.jobTitles.publicList) instead of free text. The chosen title persists into ppp_job_role_history.grade and pppHrPassport.grade. Resolves Q11 as Option A. | #8923, #7913 | Q11 resolved as Option A across three converging sources — Matt's Notion "Profile (Doctor)" brief (Job Description is a fixed Super-Admin-editable list), the existing code (DEFAULT_JOB_TITLES / job_titles table / jobTitles.publicList already used at sign-up), and Matt's resolving comment on #7913 ("Don't we already have a job roles list from the sign up?"). Reuses the existing job_titles value-set — no new value-set and no migration. The #8086/#8087/#8088 history, offer-letter evidence, verification and CV surfacing already shipped in #8200 on the free-text field; this change only swaps the input control to the pick-list. One-time tolerance: pre-existing free-text grade values stay displayable but the next recorded change must be chosen from the list. |
| 2026-06-18 | Doctors can now reorder their workplaces in My Hospitals (Move up/down controls + drag), and that order drives the Add Logbook Case hospital dropdown order and its default selection. | #8873, #8864 | Closes ask #1 of #8864 — Matt asked that the Add Case hospital list follow his own workplace order. Persisted per-user on a new user_assigned_hospitals.displayOrder column (migration 0171); the dropdown + default already consume assignment order via utils/logbookHospitalSelection, so they inherit it. Asks #2/#3 already shipped in #8480 and were not rebuilt. |
| 2026-06-18 | The bundled AU hospital dataset now seeds the Hospital and Health Service (HHS) parent→site hierarchy directly. The 15 curated Queensland HHS administrative parents (Metro North, Metro South, …) are present in the dataset flagged is_selectable_site=false, so a fresh seed establishes the parent→site model without depending on a later Super-Admin reconcile run. Adds a single authority module (auHhsHierarchy.ts) kept aligned with hospitalCuration AU_HHS_PARENT_NAMES, carries is_selectable_site/parent_name through reseedHospitals.ts, and teaches refresh-bundled-hospitals.ts to source per-site parent_name from the AIHW LocalHospitalNetworkName (never name-matching). Extends the BundledHospital type with optional parentName/isSelectableSite. Strengthens the profile.hospitals.au-coordinates CI guard so no AU HHS parent name is ever exposed as a selectable site. | #8838, #8782, #8444 | Sub-issue of #8444: a correct AU parent→site model requires administrative parents (HHS) to be non-selectable — a doctor must never pick "Metro North" as a workplace. The reconcile pass (#8517) already flips known HHS parents to non-selectable, but only when an operator runs it after a seed; a fresh seed left the parents absent. This seeds the hierarchy into the bundled dataset so it holds from the first seed. Per-site parent_name (owning HHS) is sourced authoritatively from the AIHW LocalHospitalNetworkName at refresh time and the existing reconcile pass — never name-guessed, which would mis-assign Victorian/Tasmanian sites that share an HHS area word. No schema change — the hospitals.is_selectable_site / parent_name columns already exist (#8444). |
| 2026-06-17 | AU hospital reference data now carries geofence-ready coordinates and location attributes end-to-end. Adds acceptance criteria profile.hospitals.au-coordinates (every AU hospital in the bundled dataset has valid latitude/longitude inside Australia's bounding box, closing the AU geofence gap in #8219) and profile.hospitals.location-attributes (the seed and one-click import carry the registry's state and suburb through to the DB — state→state, suburb→region — instead of dropping them, so AU sites are searchable by area). Extends the BundledHospital type with optional state/suburb/source; importBundledHospitals and scripts/reseedHospitals.ts now persist those attributes (previously hard-coded to null). Hardens the bundled-data CI guard with per-country bounding-box checks and an AU state-code validity check. | #8780, #8444, #8219 | #8444 is the chain-head for the geofence track (#8219 → #8440 → #8376 all depend on AU hospitals having coordinates). The reference-data foundation — DB-only doctor search, country scoping, sentence-case names, Super-Admin registry curation, and the curated v3.0.0 bundled dataset — landed across #8456/#8471/#8495/#8510/#8517. This PR closes the remaining geofence-unblocking slice: it regression-locks the guarantee that every AU site has valid, in-country coordinates (the #8219 unblocker), and stops the seed/import path dropping the AIHW state/suburb so AU location search works. No schema change — the hospitals coordinate/state/region columns already exist. Broader scope from the deep dive (UK private/CQC sourcing, live HHS hierarchy seeding from AIHW, timezone backfill) is deferred to follow-up sub-issues. |
| 2026-06-17 | Removed the user-facing "Verify against live register" button from the additional-registrations table on My Profile. Verification is now a system responsibility on a yearly cadence only (annual January job, #8327/#8413). The auto-verify-on-add path and the "View on register" link are unaffected. | #8446 | Matt raised this in the 10 Jun dev session — live-register verification is a system job, not a user-initiated action. Exposes the doctor to confusing transient register errors and creates false expectations about real-time status. Sibling to #8413 (stop auto-recheck on every page load). |
| 2026-06-10 | Removes the dormant doctor registry-self-add path. Retires the profile.hospitals.registry-self-add AC (💤 dormant → 🗑️ removed) and deletes its implementation — the hospital.addToMyProfileFromRegistry tRPC procedure + addToMyProfileFromRegistrySchema, the selfAssignRegistryHospital service function, and the MyHospitals handleConfirmAdd id===null branch + addFromRegistryMutation wiring. The @wip @known-issue-8459 BDD scenario ("A doctor can add a registry-only hospital from My Hospitals") and its orphaned step are removed with it. | #8589, #8459, #8444, #8456, #8495, #8510, #8517 | Deep-dive decision on #8459: remove (not repurpose) the dormant path. #8444 Option A (DB-only doctor search, PR #8456) made search never return id:null registry rows, so this self-add path was permanently unreachable for doctors (#8456 review MAJOR-2 — the AC was marked dormant). The Super-Admin curation tool (#8444 PR2, PRs #8495/#8510) is now the sanctioned route for registry rows to enter the DB, and #8517 adoption-on-refresh preserves legacy attachments — removing the last conceivable need for a doctor-side registry add. Reversible via git history if a future PR wants to re-surface it. |
| 2026-06-10 | Repairs the mobile add-hospital flow in My Hospitals. The Find-a-Hospital search was an inline panel rendered at the very bottom of the My Hospitals card — far below the fold on a phone — so tapping "Find a Hospital" in the native app appeared to do nothing (Matt's UAT video), and on phone web the on-screen keyboard occluded the results list that rendered beneath the input. The search is re-housed as a responsive Dialog (fullScreen on mobile, the house pattern shared with the Workplace Locations picker) that opens immediately on tap as an overlay, with the search input anchored at the top of the dialog and the matched hospitals in the scrollable content area beneath it — so the keyboard pushes the results, not the input, and both stay reachable on ~390px viewports. The "Find a Hospital" button now opens (rather than toggles) the dialog, and closing it clears the query so the next open starts fresh. Adds acceptance criterion profile.hospitals.add-mobile-keyboard-safe. | #8563, #8332 | Matt reported (#8332) that he could not add a hospital from the native app; his video shows the inline search panel never scrolling into view on tap, and his screenshots show the results spinner/list hidden behind the iOS keyboard on phone web. Both are the same root cause: the search lived inline at the bottom of a long card with the results rendered below the input. A fullScreen-on-mobile Dialog with a top-anchored input is the established keyboard-safe pattern in the app (WorkplaceLocations) and fixes the unresponsive-on-tap failure and the keyboard occlusion together. SCOPE SPLIT: the separate search-fidelity symptom ("basing" not matching Basingstoke while "north h" does) is a DATA problem — the legacy seed row carries the old Trust/parent name — and is addressed by the #8444 curation refresh (the DB becomes the curated single source of truth), not by fuzzy matching here. The dormant registry (id:null) self-add branch (#8456, tracked under #8459) is left intact pending that decision. |
| 2026-06-10 | Reconciles the ~2,959 legacy source-less hospital rows so the Super-Admin curation refresh cannot duplicate them and legacy administrative parents stop being selectable. The refresh diff now ADOPTS a matching legacy (source-less) row instead of inserting a duplicate — a registry row with no (source, sourceId) match tries a robust legacy match (exact name+country, a normalised variant that strips punctuation and collapses whitespace and is compared via the shared sentence-case formatter's lowercased output, and a known AU abbreviation map QCH/TPCH) and on a hit backfills source/sourceId/coords/parent/casing onto the legacy row's id, so user FKs keep pointing at the adopted row. When a legacy row is adopted its name is upgraded to the canonical registry name by design — the registry is the upstream source of truth for the hospital's name, so adoption renames the row (e.g. a drifted "MATER HOSPITAL - BRISBANE" becomes the AIHW "Mater Hospital Brisbane"). Adoption is also collision-safe: if two distinct legacy rows normalise to the same match key the key is treated as ambiguous and the registry row inserts a fresh row rather than guessing which legacy row to adopt, leaving both legacy rows untouched. A separate Super-Admin-triggerable reconcileLegacyHospitals service + tRPC procedure classifies legacy administrative parents as is_selectable_site=false with parent_name set, so they drop out of doctor search — for GB a Trust/Foundation-Trust-named row is flipped ONLY when the DB already records it as a parent_name on at least one other (child) row (so genuine single-site institutions styled as a Trust — Alder Hey, The Christie, The Royal Marsden — stay selectable); for AU a known HHS name like Metro North driven by the AU_HHS_PARENT_NAMES const. It returns the full list of every row it reclassified for operator review, and never deletes or deactivates legacy rows since doctors are attached to them. Adds acceptance criterion profile.hospitals.legacy-reconciliation. No schema change — the is_selectable_site / parent_name / is_active columns from migration 0159 (#8444) suffice. | #8517, #8498, #8444, #8219 | Follow-up to the curation service (#8444, PR #8495). The (source, sourceId) durable key with a nameCountryKey fallback matched most UK Trusts but NOT AU sites — AIHW returns full names while legacy AU rows are abbreviations (QCH, TPCH, Metro North), so an AU refresh inserted the AIHW site alongside the stale legacy row (duplicates in doctor search) and legacy parents like Metro North (an HHS, not a hospital) stayed selectable. Dedup-by-name adoption on refresh backfills provenance onto the legacy row in place rather than inserting a duplicate (advancing #8219 — AU coordinates land on the adopted row); the one-time classification pass flips known administrative parents non-selectable. Legacy rows are never deleted/deactivated wholesale because doctors are attached to them. The do-not-overwrite / manually-curated precedence flag from the #8495 review remains future work. |
| 2026-06-10 | Adds the Super-Admin hospital registry curation UI (PR3) for the curation service shipped in PR2 (#8495). A new RegistryRefreshDialog (reached from a super-admin-only "Curate registry" button in Settings → Hospitals, beside the existing Refresh action) drives the preview/apply refresh flow. Step 1 — the admin picks a country scope (All / UK NHS ODS / Australia AIHW) and clicks Preview refresh, which calls previewRegistryRefresh on demand (a dry-run that writes nothing) and renders the new / changed / disappeared / unchanged counts. When the registry no longer returns rows for a source, the per-source disappeared ratio is surfaced as an amber warning — or a red "refresh blocked" callout when it would trip the backend mass-deactivation guard. Step 2 — Apply refresh is disabled until a preview has run for the current scope and is never enabled when the guard would trip; clicking it opens a confirmation that states exactly what will happen (X inserted, Y updated, Z flagged inactive — never deleted) before calling applyRegistryRefresh and showing the realised counts. The backend's mass-deactivation-floor refusal is rendered clearly in an error alert telling the Super Admin to re-preview. Adds acceptance criterion profile.hospitals.curation-ui. | #8510, #8444, #8219 | PR2 (#8495) shipped the Super-Admin curation service (previewRegistryRefresh / applyRegistryRefresh on adminProcedure) but explicitly deferred the UI to PR3. This PR is that UI. It keeps the DB as the single source of truth for doctor search (Option A, #8444) while giving the Super Admin a safe, review-before- commit way to refresh the curated list from the NHS ODS + AIHW registries: preview the diff, see how much of each source would be deactivated (surfacing the same mass-deactivation signal the backend guard enforces), then apply behind a confirmation. The floor refusal (a deliberate safety stop when a partial/erroring registry response would mass-deactivate a source) is rendered as a clear, actionable error rather than a silent failure. A UAT refresh run via this UI is what closes #8219 (AU coordinates land via AIHW then) — not this PR. Stacked on #8495; merge after it. |
| 2026-06-10 | Adds the Super-Admin hospital registry curation service. New hospitalCuration.ts validates/refreshes the hospital list from the NHS ODS + AIHW registries and persists a curated, normalised list into the DB. previewRegistryRefresh is a dry-run that returns a diff summary (new / changed / disappeared / unchanged counts, plus a per-source disappeared ratio so the admin sees pre-apply how much of each source would deactivate); applyRegistryRefresh performs the upsert by (source, sourceId) — never blind-deleting — COALESCE-enriches coordinates/state/address, sentence-cases names via the existing toTitleCase formatter, and flags registry rows that have disappeared upstream isActive=false rather than deleting them (user FKs point at hospitals). A mass-deactivation guard refuses the whole apply if any single source would deactivate more than 20% (floor 5 rows) of its active hospitals — protecting doctor search from a partial/erroring registry response. On write it derives the parent→site hierarchy: UK NHS Trust / Foundation Trust (RO197/RO209) parents are marked non-selectable with their parentName recorded, while RO198 sites and all AIHW hospitals stay selectable. Both procedures are super-admin-gated tRPC (ppp.hospital.previewRegistryRefresh / applyRegistryRefresh) and country-scoped (AU / GB / all). Doctor/admin search now excludes non-selectable parents and inactive rows. Adds acceptance criteria profile.hospitals.curation-refresh and profile.hospitals.curation-hierarchy. Schema migration 0158 adds hospitals.is_selectable_site, parent_name and is_active. | #8495, #8444, #8219 | #8444 deep-dive decision = Option A: the DB is the single source of truth for doctor-facing hospital search, and the live NHS ODS + AIHW registry clients become a Super-Admin curation tool that validates/refreshes against the upstream APIs and persists a refined hospital list into the DB. PR1 (#8456) delivered the DB-only doctor search + country scoping spine; this PR (PR2) builds the curation service on the existing syncHospitalsFromApi seam: refresh = fetch → diff (new / changed / disappeared) → upsert by (source, sourceId), never blind-delete. Disappeared rows are flagged inactive so historical attachments survive. Normalise-on-write fixes the hierarchy bug (Metro North is an HHS, not a hospital) by marking administrative parents non-selectable, and applies sentence case via the shared toTitleCase util (hardened separately under #8447). This advances #8219 — AU coordinates arrive via AIHW when a refresh runs on UAT (it closes when that refresh actually runs, not here). The Super-Admin curation UI is PR3. Reconciliation of the ~2,959 legacy source-less rows (dedup-by-name on refresh, one-time source backfill, legacy parent classification, and a manual-edit precedence flag) is deferred to #8498. |
| 2026-06-10 | The admin/profile-form bulk hospital save now arms a per-hospital smart geotag boundary for each newly assigned hospital with coordinates and deactivates a removed hospital's boundary before deleting its attachment — no orphaned active workplace_locations rows. Adds acceptance criterion profile.hospital.admin-bulk-assign-geofence. | #8484, #8440 | Follow-up of #8410 / #8439 (Option A — hospital attachment owns the geotag link). #8439 armed the smart geotag only on the self-service attach paths; the legacy admin/profile-form bulk-assign path (updateUserProfile) saved hospitals by delete-all-then-reinsert, so admin-assigned hospitals never got a boundary and the set-null FK (workplace_locations.userAssignedHospitalId) stranded active, unlinked boundaries on every save. The bulk save now diffs incoming vs stored attachments: removed → deactivateGeofenceForAttachment before delete, added → ensureGeofenceForHospital (best-effort, mirroring #8439), surviving → update in place so the attachment id and its boundary persist. A partial unique index (workplace_locations_user_assigned_hospital_uidx) enforces the one-boundary-per-attachment invariant in the DB, not just app code. AU hospitals with null coordinates (#8219) attach without arming a boundary. |
| 2026-06-10 | Hospital names now render sentence-cased with acronyms preserved (NHS, A&E, ICU, ENT, GP, HHS, QCH, TPCH, UCLH, Roman numerals) across the doctor-facing web surfaces — My Hospitals table and search, the surgical-logbook case location (HospitalCell + LogbookCaseCard), the surgical-logbook widgets hospital filter, the multi-consultant report, the fortnightly timesheet PDF export, the accept-invite welcome/banner copy, the imported-case detail/section views, and the UR-number search and procedure-information panels. Admin/Settings curation views deliberately keep the stored value so the Super-Admin sees exactly what is persisted. Acronyms wrapped in punctuation ((NHS)/(A&E)/(QEII)/(ICU)) and / separators (Royal/General) are now handled, conjunctions (and/of/the/for) are lowercased mid-name, and St/Mc/O', possessive (St Mary's, King's, Guy's and St Thomas') and hyphenated British place names (Stoke-on-Trent) are cased correctly. Adds acceptance criterion profile.hospitals.name-sentence-case. | #8471, #8447 | Child of anchor #8444 (Option A — the DB is the source of truth). Hospital records arrive ALL-CAPS from the local DB, NHS ODS and AIHW seed dumps, and the former MyHospitals helper force-uppercased them, so names rendered as raw caps across the doctor surfaces. The sentence-case + acronym formatter is hardened into a single shared implementation (packages-shared/ppp formatHospitalName) with a maintainable, extensible acronym allow-list and exhaustive unit tests on the tricky cases. PR review (#8471) found two gaps: a punctuation-adjacent acronym never matched the allow-list (so "(NHS)"/"(A&E)"/"(QEII)" lower-cased), and several doctor-facing surfaces still rendered raw names — both are now fixed, and the scope wording is tightened to "doctor-facing web surfaces" because the Admin/Settings curation views intentionally show stored values. It is applied format-on-read only via one shared helper import (DRY) — stored data is untouched, so search, dedupe and backend matching are unaffected. The backend toTitleCase re-exports the same formatter, so the Super-Admin curation service (#8444 PR2) reuses it for normalise-on-write. No DB writes in this PR. Mobile/ppp is a separate lane and is tracked as a follow-up. |
| 2026-06-10 | Doctor-facing hospital search is now DB-only and country-scoped. searchHospitalsWithFallback queries the local DB only and never calls the live NHS ODS / AIHW registry on the doctor path; results are filtered to the instance's configured country/countries (prod one of AU/GB, UAT both, via the HOSPITAL_SEARCH_COUNTRIES env override over instance_config.country_code). Adds acceptance criteria profile.hospitals.search-db-only and profile.hospitals.search-country-scoped, and retires profile.hospitals.search-local-first (superseded). Marks profile.hospitals.registry-self-add dormant: DB-only search never returns id:null registry rows, so the self-add path can no longer trigger; it stays dormant (BDD scenario @wip @known-issue-8459) until the Super-Admin curation tool (PR2) decides remove vs repurpose (#8459). | #8456, #8444 | #8444 deep-dive decision = Option A: the DB is the single source of truth for doctor-facing hospital search — fast, deterministic, offline-safe — and the live registry clients (NHS ODS ukService.ts / AIHW ausService.ts) become a future Super-Admin-only curation tool, not the live backend for doctor search. This PR delivers the two architecture-spine changes: (1) the searchWithFallback live-registry fallback is removed from the doctor path (the hospitalLookup clients stay intact for the curation path via syncHospitalsFromApi), and (2) hospital reference data is scoped to the instance country — single-country in prod, both in UAT, by config rather than hardcoded. No schema change: the hospitals.country column already exists. The Super-Admin curation service (refresh from NHS ODS RO197/RO198 + AIHW and upsert normalised sites) and its frontend are follow-up PRs; casing is split to #8447. The #8340 local-first-with-registry-fallback behaviour is replaced by strict DB-only. |
| 2026-06-10 | Attaching a Hospital that has coordinates now auto-creates an active, system-controlled smart-geotag boundary (a workplace_locations row at the hospital location, linked to that attachment). A doctor with multiple hospital attachments gets one geofence boundary per hospital. Idempotent — re-attaching reactivates the existing boundary; a coordinate-less hospital attaches without arming a geofence. Adds acceptance criterion profile.hospital.attachment-activates-geofence. | #8439, #8410 | #8410 resolved the hospital / jobs-log / geotag overlap to Option A: the hospital attachment owns the geotag link, so a doctor working at more than one hospital gets one geofence boundary per hospital. The deactivation half of the pair already existed (#5965) but nothing armed the boundary on attach, so the "geofence is system-controlled, derived from the hospital" model was never realised end-to-end. New ensureGeofenceForHospital is wired best-effort into selfAssignHospital and updateSelfAssignedHospital. No schema change — workplace_locations.userAssignedHospitalId already exists. The legacy admin bulk-assign path (userProfileService) is deferred to a follow-up. |
| 2026-06-10 | The My Profile primary registration card no longer re-verifies against the live GMC/AHPRA register on every page load — it seeds the "Verified" affordance from stored state and re-verifies live only when the doctor edits the registration number. | #8437, #8413 | useGmcVerification fired a debounced live lookup whenever the form-reset populated the stored number on mount, triggering a rate-limited gmc-uk.org scrape per visit that re-derived the badge live and persisted nothing. Per the #8327 decision the annual January job is the source of truth and the UI reads stored state on load. Signup's verify-on-change behaviour is unchanged. |
| 2026-06-09 | Fixed the Post-Graduate Year off-by-one — PGY 1 is now the first academic year after graduation (the graduation year is PGY 0), so a 2014 graduate reads PGY 12 in 2026 instead of 13. | #~, #8328 | Matt reported his profile showed the wrong PGY ("I'm PGY 12; my PGY 1 year was 2015 because I graduated 2014"). computePgy (api/backend-ppp/src/services/userProfileService/index.ts) used academicYear - graduationYear + 1, treating the graduation year itself as PGY 1. Dropped the + 1; the graduation academic year is now PGY 0 → null (no PGY yet), and PGY 1 begins the following academic year. Display-only change — no business logic gates off PGY today. computePgy.test.ts expectations updated to the new convention with an explicit 2014-grad → PGY 12 regression case; profile.feature @issue-8328 @regression scenario asserts the displayed PGY equals the academic years elapsed since graduation. The computePgy function (and the original + 1) was added by us in PR #5916 (#5621), not inherited. |
| 2026-06-09 | Added AC profile.user-type.registration-derived — User Type is derived from AHPRA/GMC registration, Super-Admin-only editable, and now carries explainer text on the field so a read-only "Non-Consultant" value is not mistaken for a bug. | #~, #8330 | Matt UAT (#8330): the specialist/consultant determination "still isn't right". The deep dive found the User Type value never evaluated in UAT (the AHPRA detail scrape was held off) and the field gave no explanation of where its value comes from, so a correct "Non-Consultant" read as broken. This adds the explainer; the AHPRA enablement is recorded against medical-registration- verification. The "Specialist" vs "Speciality" label and "Are you a surgeon?" wording are deferred to #8181 (Matt decision) — the profile label was deliberately set to "Specialist" at Matt's request in #4612, so re-labelling it here would reverse his own prior instruction. |
| 2026-06-09 | The Work & pay "HHS / Trust" field now resolves from the hospital's linked Health Service (hospital_health_services), and "Organisation / State" from the linked Organisation, instead of mislabelling the hospital state code as the HHS/Trust. Both hide when no Health Service / Organisation is linked. Adds acceptance criterion profile.hospitals.hhs-trust-from-health-service. | #8429, #8409 | Matt UAT feedback (#8331): "HHS/trust is locked... mater isn't Queensland Health, Queensland Health isn't a HHS, and currently that box says QLD which doesn't fit." The field resolved from hospitals.state, so a state code rendered under an "HHS / Trust" label. The governance hierarchy already exists in the schema (hospitals.healthServiceId -> hospital_health_services #4840; organisationId -> organisations #6739) but the UI bypassed it. getUserInfoByEmail now hydrates healthService + organisation through to the profile, and WorkPaySection reads them, hiding each field when unlinked (no state fallback). Split from #8331 (A2). The AU catalogue seeding that distinguishes Mater (private) from Queensland Health from a specific HHS remains a product/data decision for Matt. |
| 2026-06-09 | The Work & pay working-calendar anchor field now uses a month-only picker (views=['month'], openTo='month') instead of month+year, and is relabelled from "Working year start" to "Default Working-Calendar Start". Adds acceptance criterion profile.contract.working-calendar-month-only. | #8414, #8408 | Matt UAT feedback (#8331): "I think this just needs to be a month. Choosing year, why?" Only the anchor month is meaningful — the working-year resolver (workingYear.ts) reads the anchor month/day and ignores the stored year — so collecting a year was noise. The relabel completes the #7950 rename that the implementation missed: the spec and the existing @requires-backend BDD scenarios already said "Default Working-Calendar Start", but the rendered control still said "Working year start". Because those scenarios are skipped in standard CI, the drift went unnoticed; this PR also adds a CI-runnable WorkPaySection component test that locks both the label and the month-only picker config. |
| 2026-06-09 | Annual registration re-check now persists each registration's status and last-checked date back to the row; My Profile shows when each registration was last checked and reads a never-checked/inconclusive row as "Not checked". | #8412, #8327 | A secondary GMC registration showed a static "Unverified" chip because the once-a-year job only sent notifications and never wrote last_verified_status/at back, so an inconclusive lookup stayed unverified forever. The January job is now the source of truth. |
| 2026-06-09 | Hospital search now consults the live NHS ODS / AIHW registry only when the local DB returns no results for the query (local is the source of truth — the full registry dataset is seeded locally). Adds acceptance criterion profile.hospitals.search-local-first. | #8367, #8340 | #7355 made the registry fallback fire whenever local results did not fill the page. That flooded the list when the hospital was already held locally — Matt could not find "Basingstoke and North Hampshire Hospital" (buried under ~20 NHS ODS rows) and the selected row would not save because it was an id:null registry duplicate. UAT logs confirmed the hospital was in the DB and local search returned it (country:'all', localCount:1), so the fix is to skip the registry whenever local returns anything. A name-substring heuristic was considered and rejected in review (it would drift from how searchHospitals matches across name/address/region, #4666). The registry still fires for genuinely-absent hospitals, preserving the #7355 win. |
| 2026-06-03 | Added Job Role / Grade history to the Doctor Profile (Role & specialty section) — role changes are recorded over time (effective date, prior → new grade) with an optional offer-letter evidence upload and PPP verification, and verified history surfaces on the exportable CV report. | #8200, #8086, #8087, #8088, #7913 | Re-scoped from #7913 after Matt's 2026-06-02 reframe — job role / seniority is the real thing to track "for overall CV reporting", decoupled from PGY (graduation-derived, display-only) and consultant-status (registration-driven); no PGY→Reg→Consultant ladder. Ships on the existing free-text pppHrPassport.grade field. New ppp_job_role_history table (migration 0154_hard_pandemic + .validate.sql); jobRoleHistoryService (addJobRoleChange closes the prior open entry, captures previousGrade, syncs the HR Passport grade; setJobRoleEvidence; verifyJobRoleChange is super-admin-gated so doctors cannot self-verify, reusing the Passport pending→verified pattern with verification_pathway = 'ppp_verification'). New JobRoleHistory.tsx rendered on the Doctor Profile (Role & specialty section) shows the current role plus a viewable change history with verified/pending/rejected chips and an optional offer-letter upload + view link. The CV report (reportPdfService) renders a Career History section on the title page distinguishing verified from unverified entries (#8088). The controlled-value-set decision (fixed pick-list vs free text) stays open with Matt (Q11 / #7913) — the history, evidence, verification and CV work are independent of it. ACs profile.job-role.history + profile.job-role.evidence-verification (profile-doctor) and exportable-reports.career-history (exportable-reports) added, each with @issue-808x source-contract scenarios in profile.feature. |
| 2026-06-03 | Moved the PPP Passport status (completion + 6-domain Blue Tick checklist) off the Doctor Profile onto the Passport page (/ppp-passport); the profile now shows no inline passport content, and the redundant "View full PPP Passport" link is hidden when the status renders on the Passport page itself. | #8200, #8184, #6411 | Matt (2026-06-03 live review) — the PPP Passport status section felt out of place on the profile; it belongs on the Passport page where the passport content lives. Supersedes the earlier behaviour from #6411 (profile showed a completion-status widget). PppPassportStatus is removed from MyProfile/index.tsx and rendered in MedicalPassportPage.tsx with hideViewFullLink. AC profile.hr-passport.completion-indicator updated to reflect the move; the profile.feature scenario was re-pointed to assert the status renders on the Passport page, not the profile (@issue-8184); MyProfile.test.tsx #6411 updated to assert the profile renders neither the widget nor the legacy inline accordion. |
| 2026-06-03 | Consolidated the profile registration UI into a single primary-first area — the primary registration shows prominently and a subtle "Add another registration" link reveals the multi-body list only when a second body is added. | #TBD, #7771 | Before #7771 the primary registration fields (on the users columns) and the standalone MedicalRegistrations table overlapped — the table's empty state even read "stored in the profile form above" — which was confusing, so the multi-body section was hidden behind a SHOW_MEDICAL_REGISTRATIONS_SECTION = false flag. MedicalRegistrations.tsx is now a secondary-only surface (no heading/empty-state alert, "Additional registrations" label when rows exist) rendered via the UserForm registrationsSlot beneath RegistrationFields in the Registration SectionCard. The primary regulatory body is excluded from the add options so it cannot be duplicated. ~95% of doctors hold one registration, so single-registration doctors see only the quiet add link, no table chrome. Data model unchanged — the cutover to make user_registrations authoritative stays on #7698. Added a @smoke scenario (single-registration doctor sees the primary-first block and can reveal + add a second body) and a @regression scenario (no duplicated registration surfaces) to profile.feature, and updated the #7352 regression to assert the renamed "Add another registration" affordance. |
| 2026-06-02 | Contract/start dates are delineated per hospital. The timesheet working year now anchors on the earliest per-hospital start date (My Hospitals), with the user-level field demoted to a fallback and relabelled "Default Working-Calendar Start". | #8080, #7950 | A doctor with multiple hospital posts has a different contract start per hospital, so a single user-level Profile field was wrong. Matt confirmed on the 2026-06-02 call that there is no longer a single generic start date; per-hospital dates already live in My Hospitals (#5622). New AC profile.contract.start-date-per-hospital; @smoke @issue-7950 BDD scenario; resolver unit tests on both backend and frontend. |
| 2026-06-02 | Relocated CV upload file-validation BDD coverage from the removed Setup Wizard onto My Profile, and added the profile.cv-upload-validation acceptance criterion. | #8073, #8050, #7922 | PR #8049 (#8027) removed the Phase 2 Setup Wizard, deleting the wizard-bound CV upload validation scenarios first added in #7922. The validation moved with its surface to the My Profile UpdateCV dialog, so the @regression coverage (reject disallowed type / over 10MB / empty) now lives on My Profile and asserts the messages UpdateCV.tsx actually renders. |
| 2026-06-01 | Marked profile.specialty-change.hlsr-refresh complete — added the code-citation tooltip and flipped the AC and frontmatter status from contracted to complete. Added an @issue-7851 @regression BDD scenario asserting the warning dialog is shown before HLSR attestations are cleared and that cancelling preserves the existing ticks. | #~, #7851 | SGD gap analysis re-surfaced this AC (#7851) because the spec bullet still carried only a source citation and no code citation, so the traceability matrix flagged it as unverified. The behaviour was already shipped end-to-end under #5959: the profile UserForm pauses on a specialityId delta and opens a warning dialog before save (clearing on confirm, reverting on cancel), the backend wipes cpdPlans.highLevelRequirements in the same transaction on a real specialityId change, and CPDHomeV2's HlsrBlock re-queries the requirement set by specialityId. This change closes the traceability gap (code citation + status flip) and adds an explicit warn-before-clear regression scenario that the prior #5959 scenarios did not isolate. |
| 2026-06-01 | My Hospitals can now add a registry-only hospital (NHS ODS / AIHW) — registry results render an Add button and persist on-select instead of a dead "Registry Only" chip. | #8008, #7965 | A doctor whose workplace had not been synced into the local DB could not add it from their profile; selecting a registry result (id:null) bailed with "This hospital isn't in the PPP database yet". Closes the My-Profile half of the registry self-add gap (the onboarding half landed in #7957). |
| 2026-06-01 | Block selecting the same person as both Educational and Clinical Supervisor (hard block, both My Profile and onboarding). | #7953, #7342 | Governance/safety rule — a doctor's Clinical Supervisor must not also be their Educational Supervisor. |
| 2026-06-01 | Sign-up personal-email warning is now an accessible MUI Alert (severity=warning, role=alert) using theme warning palette instead of a hardcoded-hex Box; AC profile.auth.personal-email-recommended marked satisfied. | #7852 | Make the prominent personal-email recommendation screen-reader-announced and remove hardcoded brand values (#7525); final copy still pending Matt sign-off (Open Question Q10). |
| 2026-05-27 | Fixed hospital search ("Hospitals not found") — added relevance ranking (exact → prefix → contains → other, then name ASC) so the wanted hospital lands inside the result cap, and changed the registry fallback to run whenever local results do not fill the requested limit instead of skipping at a fixed 5-row threshold. | #7788, #7355 | Results were ordered by name ASC then truncated to LIMIT, so an exact/prefix match sorting late alphabetically fell off the page; and a fixed LOCAL_THRESHOLD of 5 hid registry-only hospitals behind empty slots when the default limit is 20. |
| 2026-05-27 | Seeded test accounts now display their registry persona's Pixar-style comic avatar in the header. | #7760 | Bring the persona registry to life for the demo; also fixed the header avatar resolver to render asset-path / external-URL profile pictures directly instead of always signing them as blob keys. |
| 2026-05-27 | Self-joining a hospital (Find a Hospital → Add to Profile) now appears immediately in My Hospitals and persists across reloads. selfAssignHospital invalidates the user-profile cache keys (ppp:user:<id>:profile, ppp:users:all:profiles, and the email identity key) after the insert, mirroring removeSelfAssignedHospital. | #7734 | The insert never invalidated the cache, so getUserProfile kept serving stale assignedHospitals from ppp:user:<id>:profile and the added hospital never showed — even after a full page reload. |
| 2026-05-27 | My Hospitals Add/Edit/Remove/Leave buttons now expose their visible word as the accessible name (hospital conveyed via aria-describedby), so they are reachable by role and name. | #7796 | The descriptive aria-label overrode the accessible name, so the buttons could not be reached by getByRole with their visible label despite being visually rendered. |
| 2026-05-27 | Spec brought up to date and made concise — verified AC statuses against code, moved all implementation detail into machine-readable ‡ code hovers, removed inline issue numbers, collapsed closed issues into a Closed Issues table, and deleted the duplicated "Matt's Requirements" and "22-Apr Brief Sweep" sections (Notion link + ACs are the requirements). | Verbose specs put Matt off reading them. Applies the new spec maintenance protocol (_spec-maintenance-protocol.md): visible layer = clean skimmable contract; † source + ‡ code hovers + collapsed issue/question history preserve full auditability and the SGD gates. | |
| 2026-05-26 | Marked profile.edit.sticky-affordance as ✅ — the profile header bar carrying the Edit / Save / Discard controls is now sticky, so editing can be initiated without scrolling back to the top of the page. | #TBD, #7383 | Matt flagged (26 May catchup) that the Edit affordance required scrolling back up after the user had scrolled down to the field they wanted to change — an awkward flow. The header Box in instances/ppp/src/modules/MyProfile/index.tsx is now position: sticky (top: 0, zIndex: appBar, background matched to COLORS.ppp.backgroundWhite). The accidental-edit guard is preserved: editing still requires an explicit Edit click and unsaved changes are still confirmed on exit. Added @regression @issue-7383 scenario in profile.feature and a component regression test asserting the Edit control lives inside a sticky header bar. |
| 2026-05-26 | Added a CV upload control to the doctor profile — always available, accepts PDF/DOC/DOCX, stored against the user and retrievable later (new AC profile.cv-upload). | #7603, #7388 | Follow-up gap from the 26 May 2026 catchup: doctors need to upload a CV on their profile for later use (part of the Sign up (doctor) information set). The profile already wired an Update CV dialog, but the upload control only rendered once a CV already existed — so a doctor with no CV could never add one. The control is now always shown ("Upload CV" with none stored, "Update CV" otherwise). |
| 2026-05-26 | Each medical registration is now verified independently against its own live register (AHPRA predictions API for AHPRA, GMC HTML scrape for GMC). Adding a secondary body runs the verify flow per number and a per-row "Verify" action re-checks a single body on demand, persisting the outcome to that row. | #7434, #7300 | A dual-jurisdiction doctor holding AHPRA + GMC simultaneously must have each registration validated on its own — the annual re-check already iterates per row; this completes the on-demand path so the profile page can confirm a newly added secondary registration immediately. |
| 2026-05-21 | Wire processRegistrationReCheckNotifications into an Azure Container Apps Job firing 1 Jan 22:00 UTC — marks profile.registration.annual-recheck complete. | #7162, #7020 | The service existed from #5917 but had no scheduler; this PR closes the gap by adding the Pulumi Container Apps Job resource and the compiled entry-point script. |
| 2026-05-21 | Gate Graduation Year and PGY display fields on profile to non-consultant users only (spec profile.pgy.prevocational-pathway). | #7018 | PGY is collected on registration for all doctor types but is only relevant and should be displayed in the profile for non-consultant profiles. Consultant profiles no longer show the Graduation Year editable field or the computed PGY read-only field. |
| 2026-05-20 | Documented the schema gap for profile.registration.multiple-bodies — today users holds a single primary registration via regulatoryBody / registrationNumber / ahpraNumber / ukNumber columns, so simultaneous AHPRA + GMC registrations cannot be stored. Filed sub-issue #6655 for the new user_registrations table + backfill; AC remains ⏳ and now links the schema-work issue alongside the original #6403. | #TBD, #6403, #6655 | Surface the implementation gap against docs/features/profile-doctor.md so the orchestrator can sequence the schema work (DAG dependency) before the wizard/profile UI work. Annotating the AC inline (rather than silently inferring multi-body support exists) keeps the spec honest and unblocks #5917's annual recheck once the per-body row model lands. |
| 2026-05-20 | Marked profile.registration.pca-api as ✅ — PCA (Provider Connect Australia) FHIR client is the documented integration target for Australian doctor registration verification. | #TBD, #6401 | api/backend-ppp/src/services/ahpraRegistrantService/pcaClient.ts implements the PCA FHIR R4 Practitioner lookup against the System of Record Agent API and is covered by pcaClient.test.ts. Added @issue-6401 smoke scenario tying the AC to the PCA integration. The on-demand validation path currently uses the public-register scrape client; PCA is preserved in the AhpraValidationResult.source union as the documented target for AU verification. |
| 2026-05-20 | Marked profile.registration.pca-automated-check as ✅ — AHPRA verification is automated via ahpraScrapeClient.lookupPractitionerByAhpraScrape, the first check is cached on the user record, and the annual recheck cadence (processRegistrationReCheckNotifications, #5917) triggers a fresh call. | #TBD, #6402 | The AC's three requirements — automated lookup, cached first result, annual recheck — are all in production today. Storage is on the user row (users.ahpraNumber + the practitioner name/source from the scrape result). The annual scheduled job is processRegistrationReCheckNotifications.ts (idempotent per registration_recheck:{userId}:AHPRA:{year} key). Matt's transcript proposed PIA at AUD $1/check; the live implementation delivers the same contract at $0/check via the public-register JSON API (#6306). Added @issue-6402 smoke scenario tying the AC to the cache + annual-recheck implementation. |
| 2026-05-20 | Marked profile.hospitals.audit-log as ✅ — add, update, and remove actions on My Hospitals all write audit_trail entries via insertAuditEntry. | #TBD, #6408 | api/backend-ppp/src/services/settingsServices/hospitals.ts already logs every self-add (create), self-remove (delete), and date-edit (update) on the user's hospital attachments — each row captures the actor (userId), entityType: 'hospital', entityId (hospital id), automatic timestamp, and a metadata payload tagging the source tRPC procedure plus start/end dates. Added @issue-6408 smoke scenario in profile.feature covering the create + delete audit rows. |
| 2026-05-20 | Implement profile.logbook.case-target — settable numeric Total Cases and Primary Surgeon Cases targets on the profile form for surgeons, stored on cadenceTracker JSONB (totalCasesTarget / primarySurgeonTarget) and consumed by logbook overall-summary widgets as denominators. | #TBD, #6409 | Closes #6409 SGD gap from Dev Session 2026-03-18 §CaseTarget — Matt asked for a profile function to set the primary-surgeon case total used by logbook progress widgets. |
| 2026-05-20 | Marked profile.contract.start-date-picker as ✅ — the Profile field jobContractStartDate now drives the working-year anchor used by the Timesheet history grouping and dashboard year-overview widgets. | #TBD, #6410 | instances/ppp/src/modules/Timesheet/index.tsx previously hard-coded the anchor to undefined with a TODO. The Profile schema field (#5621) is now wired through user?.jobContractStartDate and consumed by workingYear.ts (workingYearForDate, currentWorkingYear, groupByWorkingYear) and useYearOverviewData. Fallback remains 1 Feb (AU default) when the user has not yet set the field. Added @issue-6410 @smoke scenario. |
| 2026-05-20 | Add ppp_user_registrations table with AHPRA/GMC/other backfill; update annual recheck to iterate per-body rows (profile.registration.multiple-bodies schema phase). | #6655, #6403 | Flat user columns support only one registration at a time; dual-jurisdiction doctors (AHPRA + GMC) require a normalised table with one row per body so the annual recheck can validate each independently. |
| 2026-05-19 | Added aria-label to the global SearchBar TextField input (and the MyHospitals search input) via slotProps.htmlInput so every form input on /my-profile has an accessible name. Fixes the authenticated-pages a11y test (profile form inputs have associated labels). | #TBD, #6519 | TextField rendered with only a placeholder produced an unlabelled <input> on every authenticated page. The SearchBar is mounted in PppAppContainer so it appeared on the profile page and failed axe-core / the e2e a11y assertion. |
| 2026-05-19 | AHPRA registration badge now reflects the real verification source. A format-only check (ahpra-format) renders a neutral grey/info "Format valid — not yet verified" label instead of the misleading green "Verified with AHPRA" success badge. Live-register-confirmed checks (ahpra-scrape/ahpra-pca) keep the genuine green "Verified with AHPRA" badge and the practitioner name added in #6346. Adds @regression @issue-4813 BDD scenarios in profile.feature. | #TBD, #4813 | The green "Verified" badge appeared as soon as the format regex (3 letters + 10 digits) passed, which doctors reasonably read as "checked against the AHPRA register" — a correctness bug, since no register lookup occurs for the format-only path. This brings the UI in line with the documented "format validated only (no live lookup on every request)" behaviour and removes the false verification signal until the real verification pipeline (#4630) lands. |
| 2026-05-19 | Flipped AC profile.hospitals.remove-action from ⏳ specified to ✅ built. The My Hospitals Actions column already exposes a confirm-gated Remove button alongside Edit for self-added hospitals — implemented in instances/ppp/src/modules/MyProfile/components/MyHospitals.tsx under #5619 (desktop hover-reveal column + mobile card layout); admin-assigned rows deliberately omit Remove. Added a @regression @issue-6407 BDD scenario in profile.feature asserting both Edit and Remove are present for a self-added row and Remove is absent for an admin-assigned row, plus a new step definition for the Edit-button assertion. | #TBD, #6407 | Spec-drift correction (no code change). The acceptance criterion was tracked as outstanding (#6407) but the functionality shipped earlier under #5619. Updating the spec to match reality keeps the engineering spec authoritative and prevents redundant re-implementation, while the new regression scenario locks in the now-built behaviour. |
| 2026-05-19 | HR Passport widget on Doctor Profile shows only the completion-status indicator (Blue Tick chip + n/6 verified-domain count + next-expiry date + "View full PPP Passport" link). Inline HR Passport editor accordion removed from the profile page; full content remains at /hr-passport. | #6583, #6411 | Implements AC profile.hr-passport.completion-indicator — Matt: "HR Passport in profile feels strange; should show only a completion-status indicator" (Dev Session 2026-04-13 §HRPassportIndicator). |
| 2026-05-19 | Mark profile.registration.annual-validity-check AC as satisfied. The annual regulatory-body registration check is already implemented by processRegistrationReCheckNotifications — the scheduled job delivered in #5917 (PR #6349) — which re-validates every user's stored AHPRA/GMC registration once per calendar year regardless of registration type, with an idempotent registration_recheck:{userId}:{body}:{year} scheduledKey. Adds a registration-type-agnostic @regression BDD Scenario Outline (AHPRA + GMC) tagged @issue-6404 in profile.feature. | #6565, #6404 | Closes #6404. SPEC-DRIFT — the annual validity-check requirement was satisfied when #5917 merged; this PR closes the documentation/traceability gap only, with no production code change. |
| 2026-05-19 | Mark profile.auth.hospital-email-link-personal AC as satisfied. Account linking already existed (Linked Emails section); this adds the missing email-change verification step — Better Auth changeEmail is enabled with a sendChangeEmailVerification callback that emails a branded confirmation link to the user's current address, holding the change pending until confirmed. Adds the buildChangeEmailVerificationEmail template and two @regression BDD scenarios in auth.feature. | #6558, #6406 | Closes #6406. A doctor who signed up with a hospital email can now safely switch to a personal email — the change cannot take effect from a typo'd or hijacked address because verification is sent to the current account. |
| 2026-05-19 | SGD transcript audit — 16 new ACs + src: citations from transcripts 2026-03-11, 2026-03-18, 2026-04-01, 2026-04-13, 2026-04-23, 2026-05-06. Adds billing section, currency-by-instance, PCA/PIA AHPRA verification, personal-email recommendation, hospital-email link, logbook case targets, emergency-contact removal, AHPRA format-only validation, annual recheck caching, HR Passport completion indicator, linked accounts merge, multiple registrations, job role global vernacular, PGY prevocational pathway, contract start date picker, My Hospitals remove action + audit log. | #~ | Backfill src: citations from six Dev Session transcripts (E1–E25) to make every AC traceable per the SGD audit protocol. |
| 2026-05-12 | My Hospitals — start date is now required on the self-add (addToMyProfile) flow. The "Find a Hospital" Add button opens a dialog that captures a required start date (plus optional end date) before saving, and the backend tRPC schema rejects an empty/missing startDate with Start date is required. | #TBD, #5926 | The spec under My Hospitals (23 Apr) states "Add Start and End dates per hospital attachment (for exportable-report job history)." The original self-add flow accepted startDate as nullable/optional, allowing start_date = NULL rows that broke job-history exports. Closing the backend enforcement gap matches the edit-flow behaviour shipped in #5622 and ensures every new self-added hospital row has a usable start date. |
| 2026-05-12 | User Guide content now reads logbookVariant dynamically — procedural-role doctors see "Procedural Logbook" wording throughout the guide; surgical-role doctors see "Surgical Logbook". Sidebar nav label also reads logbookVariant. | #TBD, #5962 | Satisfies AC profile.logbook-variant.user-guide-dynamic from the 23 Apr 2026 transcript — no hard-coded "Surgical Logbook" strings render to non-surgical viewers. |
| 2026-05-12 | Hospital end-date now deactivates the linked Smart Geo Tag geofence — added nullable FK workplaceLocations.userAssignedHospitalId, immediate deactivation on save inside updateSelfAssignedHospital, and a daily scheduled sweep (processGeofenceDeactivation) to catch date-boundary crossings overnight. Historical attachment row is retained for audit. | #TBD, #5965 | Doctors leaving a hospital should not continue to receive enter/exit toasts for that site; deactivating on the end-date is the agreed source-of-truth signal (23 Apr 2026 transcript, deep-dive 12 May 2026). |
| 2026-05-12 | Mark profile.cadence-meter.non-consultant-only AC as satisfied — Cadence Meter (Cadence Tracker section in MyProfile/UserForm) is hidden for consultant users and visible for non-consultants. Adds two @smoke BDD scenarios in profile.feature formalising the AC and a data-testid="cadence-tracker" anchor on the CadenceTracker widget for stable persona-level visibility assertions. | #TBD, #5976 | Behaviour was implemented end-to-end by #4581 — this change formalises the spec acceptance criterion, anchors the assertion with a stable test id, and closes #5976. |
| 2026-05-06 | Tag Q6 (AMC reciprocal API) as out of scope for Investor Demo 14 May 2026; defer Matt's answer until AMC approval lands. | #TBD | Demo scope clarification — the question can stay open without blocking demo delivery; reframing as post-demo prevents it from sitting in our pre-demo question list. |
| 2026-05-06 | Transcript audit 2026-05-06 — §AHPRAProvider classified R (requirement); 1 AC modified (profile.registration.annual-recheck — PIA replaces PCA as AHPRA AU verification provider); BDD scenario updated to reference PIA. All other 2026-05-06 R passages CONFIRM (already captured in cpd.md, timesheets.md, or super-admin.md from prior sessions). | #~, #5917 | §AHPRAProvider (~00:19:45) of the 2026-05-06 Dev Session transcript ("Security link expiry, CPD provider, timesheet deep dive, AHPRA verification") confirmed that the initial PCA integration was the wrong AHPRA verification provider. PIA was identified as the correct automated lookup service for AU AHPRA at AUD $1 per check. The existing AC profile.registration.annual-recheck referenced PCA (via the status table and BDD scenario); both have been updated. Cost treated as per-unit budget cost. All other R passages (link expiry, evidence proxy, provider email branding, activity list, timesheet items, widget definitions, B2C demo inclusion) were already fully captured in the respective specs. |
| 2026-05-05 | Brief-sweep status table — every #5564 delta cross-checked against the current spec. AU working-year default = Feb (UK = Aug/Sep). Light-email approval signature = drawn on hosted token page, not typed. | #5564 | Closes #5564. Fields, role-aware appraisers, Surgeon/Physician toggle (#5620), My Hospitals dates+actions+audit, PPP Passport rename and collapsed widgets are all already in the spec — confirms no further drift. |
| 2026-04-23 | Transcript audit 2026-04-23 — §Registrations classified R (requirement); 1 new AC added for multiple concurrent registrations; 1 @wip BDD scenario added. | #~ | §Registrations (~00:12:52) of the 2026-04-23 Dev Session transcript ("Doctor Profile & CPD Home specification — PGY, AHPRA escalation, dynamic logbook vernacular") identified that the profile must support multiple simultaneous registration bodies (e.g. both AHPRA and GMC for a dual-jurisdiction doctor). The transcript flagged this as "an immediate discovery" — the current system only holds one registration. All other 2026-04-23 session items (log-book vernacular, PGY, pay cycle, signature approver, appraiser roles, cadence meter, My Hospitals, linked emails, admin hierarchy) were already captured in the 22-Apr brief sweep and are CONFIRM. |
| 2026-04-21 | Spec created from Matt's 17 Apr 2026 Notion brief | — | Wave 1 foundation — multiple other specs reference Profile fields |
| 2026-04-23 | Enriched from 23 Apr catchup: Consultant/Non-Consultant Other roles, log-book word-find rule, Country hidden, AMC calendar clash, pay-cycle Monday 6am default, drawn-signature approver, My Hospitals bugs + audit, PPP Passport rename, collapsed widgets, admin hierarchy, Q6–Q8 added | this PR | 23 Apr deep-dive captured Matt's full profile walkthrough |
Sources & Recordings
| Source | Notes |
|---|---|
| https://docs.google.com/document/d/1YhgQSFL9iOlQLoTrQYSwxRNXH4Dg4wefkItcwljQZmo | Description pending SGD audit |
| https://docs.google.com/document/d/15CIxBAS7ssOJR-wJfrOsItFiSr95j03Z1GTYjS6xy2U | Description pending SGD audit |
| https://docs.google.com/document/d/1kwSrcoJzrwVIyOYdmyxB9KIFXoqFLWi3Ex6KWrJjg_c | Description pending SGD audit |