Hospital Admin & Governance
This spec is superseded by
profile-non-doctor.md, which defines the five-level org admin hierarchy (Department Admin, Hospital Admin, Health Service Admin, Governing Body Admin, PPP Staff). The old "Hospital Super Admin" / "Executive Admin" two-tier model is being migrated out via issue #6669.
Feature Overview
PPP has three layers of administrative governance:
- PPP Super Admin — internal Rob/Matt-only role for system-wide tasks (provider merging, vetting, escalations)
- Executive Admin (
executive_admin) — hospital-wide administrator who manages settings, memberships, and reporting - Hospital Admin (
hospital_admin) — departmental/operational manager (ward manager, department head) with team visibility and join-request approval, but no hospital-settings access
This spec defines the data model, role hierarchy, permission matrix, and the workflows that depend on them.
Open Questions
| # | Question | Ref | Proposed answer |
|---|---|---|---|
| — | No open questions. |
Source
Rob & Matt call 13 Apr 2026, multiple sections (~00:34:20–00:43:53, ~00:55:16–00:56:36, ~01:01:04). Continuation of #4529 (existing hospital admin epic). Role split decision confirmed 13 Apr 2026 — Option B (implement hospital_admin as a subset of executive_admin with approve/reject capability).
Hospital Membership Role Hierarchy
executive_admin Full hospital management (settings, memberships, reporting)
└── hospital_admin Operational management (team visibility, join-request approval)
└── doctor Standard hospital memberPermission Matrix
| Capability | executive_admin | hospital_admin | doctor |
|---|---|---|---|
| Dashboard stats (member counts, CPD active-plan %) | Yes | Yes | No |
| CPD compliance distribution (aggregate bands only) | Yes | Yes | No |
| List team members (HR Passport level only) | Yes | Yes | No |
| View pending join requests | Yes | Yes | No |
| Approve join requests | Yes | Yes | No |
| Reject join requests | Yes | Yes | No |
| Update hospital settings (accepting members, contact email, description) | Yes | No | No |
Design Rationale
The hospital_admin role maps to a real-world ward manager or department head who needs:
- Visibility into team CPD compliance and staffing
- Ability to approve/reject doctors joining their department
- But should not control hospital-wide settings (toggling membership acceptance, contact details)
This keeps hospital-level configuration decisions with the executive admin while allowing operational managers to handle day-to-day membership workflows independently.
Data Isolation Rules
All admin roles enforce:
- Aggregate-only CPD data — no individual doctor CPD details exposed to admins
- HR Passport data only for team lists — name, role, status, joinedAt (no clinical data). (The PPP Staff Passport review queue,
/admin/passport-reviews, is Super Admin only and lives insuper-admin.md/ppp-passport.md; #12893.) - Hospital-scoped access — an admin for Hospital A cannot see Hospital B data
- Audit trail on all membership mutations (approve, reject)
Organisational Hierarchy
Hospital Health Service (e.g. Metro South Hospital and Health Service)
└── Hospital (e.g. Mater Adult Hospital)
└── Department / Specialty (canonical, nationally-consistent list)
└── Doctors (incl. consultants who form the approver pool)Key facts:
- Specialty list is nationally consistent across Australia and largely consistent in the UK — single canonical master-data table, no per-hospital department forks
- Not every hospital has every specialty — but the catalogue of possible specialties is fixed
- The hospital admin role sits at the (hospital, specialty) intersection — i.e. each specialty within each hospital has its own admins, not one admin per hospital
- One health service runs many hospitals; reporting roll-ups can use either level
Stored as:
hospital_health_service (id, name, country, ...)
hospital (id, healthServiceId FK, name, ...)
specialty (id, name, country)
hospital_admin (hospitalId FK, specialtyId FK, userId FK, status)Existing Implementation
The executive_admin role is already implemented in:
- Service:
api/backend-ppp/src/services/hospitalExecutiveAdminService/index.ts - Router:
api/backend-ppp/src/routers/procedures/hospitalExecutiveAdmin/index.ts - Schema:
packages-shared/ppp/src/schema-groups/pppHospitalMembership.ts— role stored as VARCHAR with values['executive_admin', 'hospital_admin', 'doctor'] - Auth guard:
assertIsExecutiveAdmin()— queries membership view, checks active status + role
Implementation Plan for hospital_admin (#4529)
- Create
assertIsHospitalAdminOrAbove()guard that accepts bothhospital_adminandexecutive_adminroles - Create a new
hospitalAdminRouterwith:- Read procedures: dashboard stats, CPD distribution, team list, pending join requests
- Mutation procedures: approve join request, reject join request
- Reuse the same service methods from
hospitalExecutiveAdminService— the data queries are identical, only the auth guard differs updateHospitalSettingsremains exclusive toexecutive_adminvia the existingassertIsExecutiveAdmin()guard
Enterprise Hospital Onboarding (#4507)
The ppp_hospital enterprise system (Epic #2869) is production-ready. Doctors pay for their own seats via their existing PPP personal subscription — there is no hospital-level charge, and the hospital account is free to create. The subscription_tier field (free, standard, premium) gates which admin-dashboard features unlock, not billing — no Stripe integration exists at the hospital level.
Feature tier matrix (enforced by assertHospitalTier(hospitalId, minTier, ctx) in hospitalManagementService/hospitalTierGuard.ts):
| Feature | free | standard | premium |
|---|---|---|---|
| Doctor roster (HR Passport view) | ✅ | ✅ | ✅ |
| CPD aggregate dashboard | ❌ | ✅ | ✅ |
| CPD distribution analytics | ❌ | ✅ | ✅ |
| Bulk / single invite | ❌ | ✅ | ✅ |
Acceptance Criteria — Enterprise Onboarding (#4507)
- ✅ Tier enforcement:
standard+ only features return403(FORBIDDEN) forfree-tier hospitals —getDashboardStats,getCpdDistribution, and invite creation guard viaassertHospitalTier(..., 'standard', ...) - ✅ Executive Admin can update hospital settings (
isAcceptingMembers,contactEmail,description) viaupdateHospitalSettings; the guard rejectshospital_admin/doctor - ✅ Hospital stats return real CPD data —
doctorsWithLockedPlanPercentageis computed from linked CPD plans (replacing the previously hardcoded0),nullwhen there are no active doctors - ✅
archiveHospitaltransitionsstatus → archivedandisAcceptingMembers → falseatomically; existing memberships are untouched and newrequestJoincalls receive an explicit archived error - ✅
hospital_adminrole is implemented (hospitalAdminService,hospitalAdminrouter) as a subset ofexecutive_adminwith approve/reject join-request capability but no settings access - ✅ End-to-end onboarding happy path: Super Admin creates hospital → Executive Admin invited and accepts → doctor invited → doctor accepts → doctor holds an active membership and appears on the hospital roster (BDD
@smoke @issue-4507)
PPP Super Admin
A caller is a super admin only when the PPP user linked to their login (pppUserId) has is_super_admin = true. adminProcedure and the adminUsers gate never identify the caller by login email. A login with no linked PPP user is never an admin (#12616, auth.identity.resolved-by-ppp-user-id).
Responsibilities
| Task | Tracked in |
|---|---|
| Approve / reject / merge CPD providers before verification email is sent | #4823, #4841 |
| Approve consultant requests to act as timesheet approvers (until hospital admin role is live) | #4822 |
| Vet new CPD providers submitted by users (de-dup miss path) | #4841 |
| Inspect audit logs across the platform | (separate observability work) |
Acceptance Criteria — Super Admin Screen
- ⏳ Single super-admin landing page lists pending queues by type
⏳ CPD provider queue — informational-only ABN/org-type/vetting checklist— superseded 2026-07-15, migrated intocpd-provider-recognition.mdas a real approve/condition/decline gate (Pathway B / recognition-application assessment), no longer informational-only (#6688)- ⏳ Approver queue — list of consultants requesting approver role with hospital + specialty context
- ✅ Merge providers action — multi-select then "merge into…" with full transactional reassignment of references (activities, approvals, plans)
- ⏳ All actions write audit-log entries
- ⏳ Authorisation gate:
role = pppSuperAdminonly - ⏳ Single super-admin landing page lists pending queues by type
⏳ CPD provider queue — see above, superseded by(#6688)cpd-provider-recognition.md- ⏳ Approver queue — list of consultants requesting approver role with hospital + specialty context
- ⏳ Merge providers action — multi-select then "merge into…" with full transactional reassignment of references (activities, approvals, plans) (#4823)
- ⏳ All actions write audit-log entries
- ⏳ Authorisation gate:
role = pppSuperAdminonly - ⏳ Hospital CSV bulk import is atomic — the entire batch inserts/updates succeed together, or none are applied; a mid-batch failure rolls back every partial row and the hospital list cache is not invalidated (#5052)
- ⏳ Hospital coordinates input preserves sign (#5053) — when adding or editing a hospital, negative latitude (Southern hemisphere) and negative longitude (Western hemisphere) values entered into the Latitude/Longitude fields must persist with their sign intact through React Hook Form validation and tRPC submission. Zero (
0) must also persist as a valid coordinate, not be coerced tonull - ⏳ When a super admin changes a user's type to Consultant and existing supervisor rows (professional supervisor and/or clinical supervisors) would be removed, the UI shows a confirmation dialog listing each affected relationship; Cancel aborts the mutation, Confirm proceeds with the update (#5070)
- ⏳ Each Settings sidebar sub-item route slug matches its human-readable label so that direct navigation (e.g.
/settings/clinical-locations) renders the expected page without redirecting away (#5017). Legacy slugs must redirect to the renamed slug to preserve bookmarks. - ✅ Speciality master data is deduplicated and canonical (#10775) — Settings → Specialties (and the Surgical Data "Add Surgery" picker) show exactly one row per specialty. Source: Matt's UAT WhatsApp feedback, 19 Jul 2026 ("not grouped per speciality… confusing… needs to be better segregated"). The speciality table carries
UNIQUE(name); migration 0215 merged every legacy seed variant (lookups.json '…Specialist'/ENT/Plastic/Maxillofacial names) into its canonical GMC/RACS name, re-pointing all nine referencing tables (users, user-speciality links, procedures, CPD plan templates/activities, HLSR requirements, classification reviews, department-scoped hospital admins and hospital approvers — the latter two ON DELETE CASCADE, so re-pointing before delete is what prevents silent loss) with fail-loud count assertions proving no data loss. Canonical names are the already-ratified set fromDEFAULT_SPECIALITIES/gmcLabelMap(#4613/#5404/#7464) — display-name preferences (e.g. "Otolaryngology (ENT)" vs "ENT (Otolaryngology)") remain a trivial one-row rename via the Settings UI and are tracked as an open question for Matt, non-blocking - ✅
admin.surgical-data.speciality-grouping— Settings → Surgical Data presents all five tabs (Surgeries, Principal Procedures, Treatment Acuities, Broad Areas, Specific Areas) as default-collapsed accordion sections keyed on the canonical (post-#10775) speciality name, replacing the flat, alphabetical, un-segmented lists. Surgeries group via the directprocedures.specialityIdFK; the four lookup tabs (which carry no speciality column) group via a derived join — a lookup value's speciality is inferred from the specialities of the procedures that reference it (single speciality → that group; zero or several → a single "Used across specialties / Unclassified" bucket). No schema change, no migration — the grouping is a read-path derivation (instances/ppp/src/modules/admin-org/settings/utils/deriveSpecialityGroups.ts) rendered through the sharedSpecialityGroupedAccordionson the design-systemCollapsibleSectionatom. The Surgeries tab groups by default with a one-toggle fallback to the flat, server-paginated table. Depends on the #10775 dedupe so the keys are clean. † (#10777) - ✅ HLSR Requirements console (#8729) — super-admin page at
/admin/cpd-hlsr-requirementsto view/add/edit/remove the per-specialty HLSR requirements list, each requirement carrying description, frequency (yearly / every N years), minimum duration, and evidence type; multi-year requirements use Option A ("Not yet due — next due 20XX", not counted as a gap, last-completed + next-due shown); a yearly banner prompts the SA to confirm the list is current for the CPD year and lets them mark it confirmed. See super-admin.md for the full spec. Notification prompt + existing-plan review-flag deferred to #8775
Hospital Admin (Ward Manager / Department Head)
Responsibilities
| Task | Notes |
|---|---|
| View aggregate dashboard stats for their hospital | Member counts, CPD active-plan %, pending request count |
| View CPD compliance distribution bands | Aggregate only — never individual doctor data |
| List team members (executive admins, hospital admins, doctors) | HR Passport level data only |
| View and action pending join requests | Approve or reject doctor membership requests |
| Approve consultant requests to be timesheet approvers within their (hospital, specialty) | Long-term replacement for super-admin gating |
| Escalate genuine issues to PPP support | Per the support model — see project memory |
Acceptance Criteria
- ⏳
hospital_adminrole value recognised by auth guards alongsideexecutive_admin - ⏳ New
assertIsHospitalAdminOrAbove()guard accepts both roles - ⏳ Hospital admin can view dashboard stats (same data as executive admin)
- ⏳ Hospital admin can view CPD compliance distribution (aggregate bands only)
- ⏳ Hospital admin can list team members (HR Passport level only)
- ⏳ Hospital admin can view pending join requests
- ⏳ Hospital admin can approve join requests (membership activated, audit trail recorded)
- ⏳ Hospital admin can reject join requests (membership rejected, audit trail recorded)
- ⏳ Hospital admin cannot access
updateHospitalSettings(returns FORBIDDEN) - ⏳ Hospital admin self-service screen shows their (hospital, specialty) departments with pending approvals
- ⏳ Audit log captures all admin actions
- ⏳ Update timesheets.md approver workflow to read from this table once ready
- ⏳ Update cpd.md provider queue to optionally route to hospital admin (vs super admin) for hospital-bound providers
- ⏳
hospital_adminrole value recognised by auth guards alongsideexecutive_admin - ⏳ New
assertIsHospitalAdminOrAbove()guard accepts both roles - ⏳ Hospital admin can view dashboard stats (same data as executive admin)
- ⏳ Hospital admin can view CPD compliance distribution (aggregate bands only)
- ⏳ Hospital admin can list team members (HR Passport level only)
- ⏳ Hospital admin can view pending join requests
- ⏳ Hospital admin can approve join requests (membership activated, audit trail recorded)
- ⏳ Hospital admin can reject join requests (membership rejected, audit trail recorded)
- ⏳ Hospital admin cannot access
updateHospitalSettings(returns FORBIDDEN) - ⏳ Hospital admin self-service screen shows their (hospital, specialty) departments with pending approvals
- ⏳ Audit log captures all admin actions
- ⏳ Removing a hospital assignment from a user (via the Manage Hospitals dialog in Admin Users Settings) MUST open a confirmation dialog before the remove mutation fires — a single mis-click on the chip's delete icon must never immediately revoke access. Cancel closes the dialog without calling the mutation; Confirm executes the removal (#5015)
- ⏳ Update timesheets.md approver workflow to read from this table once ready
- ⏳ Update cpd.md provider queue to optionally route to hospital admin (vs super admin) for hospital-bound providers
- ✅
admin.attendance.meeting-management-cross-ref— The Hospital Admin meeting-management screens underinstances/ppp/src/modules/HospitalAdmin/Meetings/**(QR meeting creation, attendee roster, the Attendance Report dialog with CSV + branded-PDF roster export shipped in #7879) are admin surfaces that live in the Hospital Admin area but are governed byattendance.md. The acceptance criteria for attendance capture, roster, and report export are maintained there — seeattendance.md § Tabular attendance report export. The on-screen report and attendee tables also show Check-in method and Check-out method columns, scrollable sideways on small screens (#12446, #12458). The Complete Meeting dialog states how many attendees will be credited, counting verified attendees plus everyone who checked in by QR or was ticked off (creditableAttendeeCountonmeetings.list), so it never says "No attendees" for a meeting that only has check-ins (#12462). Create/Edit meeting also set an End date & time (extendable via the Extend action), a location pin pre-filled from the hospital default, and Manage attendance invites individuals or a Profile-filtered group (#12450, #12449, #11773). The projected-QR dialog's behaviour — by default one QR per meeting shown as "Valid until the meeting is closed" with no refresh timer (#12471), or the optional strict-mode rotation countdown (#12443) — and its visible QR size are likewise specified inattendance.md § Anti-abuse Check-out. (#7879) - ✅
admin.org-dashboard.cpd-alignment-okr-cross-ref— The Hospital Executive Admin dashboard's CPD-alignment OKR card (CpdAlignmentSection.tsxunderinstances/ppp/src/modules/HospitalExecutiveAdmin/, wiring the CPD-alignment OKR v1 shipped in #7363) is an admin surface that lives in the Hospital Admin area but is governed byorganisational-dashboard.md. The acceptance criteria for the OKR framework, Key Result targets, and cohort anonymisation guard are maintained there — seeorganisational-dashboard.md § OKR framework. (#7363) - ✅
admin.profile-non-doctor.seat-usage-metering-cross-ref— The Hospital Executive Admin dashboard's "Doctor Seats Used" metering tile (Dashboard/index.tsxunderinstances/ppp/src/modules/HospitalExecutiveAdmin/, wiring the seat-usage meter shipped in #7877) is an admin surface that lives in the Hospital Admin area but is governed byprofile-non-doctor.md. The acceptance criteria for seat economics — admin tiers provision unlimited doctor seats with no cap, and doctor seat usage is metered for reporting only (seatLimitnull = Unlimited) — are maintained there — seeprofile-non-doctor.md § Seat economics. (#7877) - ✅
admin.hospital-admin.approver-crm— A hospital admin (or platform super admin) can centrally maintain the default timesheet approver for each(hospital, department)from a dedicated admin CRM screen at/hospital-admin/approvers(instances/ppp/src/modules/admin-org/hospital-admin/HospitalApproverAdmin/): they can view all existinghospital_approversrows for their hospital (department + approver), add a row, edit a row, and remove a row. Department is optional (blank = hospital-wide default); the approver is either an internal PPP user or an external contact (name + valid email). The form also exposes an optional second (surrogate/fallback) approver slot (#10632) — internal PPP user or external contact — persisted to thesurrogate_approver_*columns; this is the hospital's default fallback approver, whom a doctor can manually route a submission to (either the primary or the surrogate is an equally-valid signer). One row per hospital/department — this is the DEFAULT approver, not the per-user override, which still lives on the doctor's profile via the existingHospitalApproverTable(not touched by this screen). Backed by theppp.hospitalApprovers.*CRUD router, gated byhospitalAdminProcedure(a hospital admin may only read/write their own hospital's rows). Reads through thehospital_approvers_viewrelational query shipped by enabler #10650. † (#10652)
Executive Admin (Hospital-Wide)
Responsibilities
Retains all capabilities from the permission matrix above, including hospital settings management.
Acceptance Criteria
All existing executive_admin acceptance criteria remain unchanged. The only addition:
- ⏳
updateHospitalSettingsprocedure explicitly rejectshospital_adminrole with clear error message
CMO / B2B Anonymized Insights (#3632, on-hold)
Moved from dashboard.md on 2026-04-22 — this is an admin-tier surface, not the doctor's PPP Dashboard.
Anonymized high-level insights for Chief Medical Officers / Hospital Admins / Exec Admins / Super Admins. Shows aggregate cohort health, CPD compliance, wellness trends, WBA throughput across their doctors without exposing individual identities below a k-anonymity threshold.
Acceptance Criteria
- ⏸ View available to
hospital_admin,executive_admin,super_adminroles only (#3632) - ⏸ Aggregate KPIs: CPD-compliance %, WBA-completion %, wellness-submission %, timesheet-submission %
- ⏸ K-anonymity gate — panels hide when cohort < k (default k=5) to prevent re-identification
- ⏸ Drill-down filters: specialty, seniority, hospital department (no drill to individual doctor)
- ⏸ Export to CSV for executive reporting
Access
Sits under the Hospital Admin / Exec Admin / Super Admin screens (NOT the doctor's PPP Dashboard). Routes: /admin/insights (hospital + exec), /super-admin/insights (PPP staff).
Open issues on label:feature:admin — no open issues. Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.
AMC Review Checklist — Reference Integrity (#11108)
- ✅
admin.amc-review.reference-paths-resolve— Every file path in the Super Admin AMC yearly-review checklist resolves to a file that actually exists. All FOURREVIEW_FILESrows were checked, not just the RACS one: the RACS CPD Framework row pointed atdocs/compliance/RACS_CPD_FRAMEWORK.md(moved todocs/site/compliance/and renamed to kebab-case), and review of this PR found two more rows independently gone stale via the same ADR-0003 bounded-context move —packages-shared/ppp/src/schema-groups/specialty.ts(moved and respelled toschema-groups/identity-profile/speciality.ts) andapi/backend-ppp/src/services/dashboardService/cpd/index.ts(moved toservices/admin-and-org/dashboardService/cpd/index.ts) — all three sent a Super Admin to a missing file. All three corrected, and the published runbook (docs/site/runbooks/amc-yearly-review.md) updated to match so the app and the docs-site copy of the checklist agree. The RACS wording in the prompt is deliberately unchanged — it is a factual reference to a real college document, which Matt confirmed on 2026-07-29 (#11025) is fine; only proprietary product/feature naming is banned. An earlier pass on this issue genericised the prompt text as well, and that part was reverted. A regression scenario (super-admin.feature: "Every AMC yearly review reference file resolves on disk") now pins all four paths so a future rename that misses this checklist fails CI instead of shipping silently.†‡ (#11108)
System Settings Read Gate (#5013)
The systemSettings.get procedure returns the full system settings record (support email, configuration IDs, and any future sensitive fields). It is admin-only — non-admin authenticated users receive TRPCError({ code: 'FORBIDDEN' }).
For in-app surfaces that need only the public support email address, use the narrow systemSettings.getSupportEmail procedure which returns just the email string and nothing else. This keeps the blast radius of any future sensitive field added to system_settings contained to admin sessions.
Invariant: read procedures on admin configuration must enforce scope, not only writes. See also auth-zero-trust-routing.md.
Audit Trail Invariant (#5012)
Every admin-initiated mutation MUST write exactly one row to the audit_trail table. This is a compliance invariant for the regulated medical platform.
Procedures covered by this invariant (minimum-viable set; expand as follow-up):
adminUsers.setAdmin— togglingisSuperAdminon a useradminUsers.setHospitalRole— togglingisHospitalAdmin/isHospitalSuperAdminsettings.hospital.create/update/delete— hospital CRUD
The audit row MUST include: userId (actor), targetUserId (where applicable), action, entityType, entityId, and a metadata JSON object capturing the before/after values. For role mutations (adminUsers.setAdmin, adminUsers.setHospitalRole), metadata MUST include previousValue and newValue (or a diff map per flag) so the audit trail is self-describing for compliance review (#5016). Writes are fire-and-forget via insertAuditEntry — audit failures must not break the mutation, but must be logged.
The DB-trigger audit_log (#4776) continues to capture row-level change history on a separate allow-list of tables; the application-level audit_trail captures who-did-what.
Level of Involvement Reference Screen — Legacy Section Accuracy (#12707)
- ✅
admin.loi-reference.legacy-section-excludes-selectable-codes— the Super Admin Level of Involvement reference screen's (/admin/level-of-involvement) legacy-codes section lists only non-consultant codes genuinely dropped from the live selectable list — currently justPP("Partial Procedure").TaT("Training another Trainee") was re-added as a selectable option by #9200 (PR #10825) but this screen'sLEGACY_NON_CONSULTANT_CODESconstant was never updated, so it rendered twice: once correctly in the live non-consultant table and again mislabelled as dropped/historic-only here. Found live during the Task 4 Async Task Model audit (#11183).‡ (#12707)
Change Log
| Date | Change | PR/Issue | Reason |
|---|---|---|---|
| 2026-10-05 | The PPP Passport staff review queue at /admin/passport-reviews now spans every Passport domain (with a document viewer and an immunisation / Passport-document section), and the indemnity, indemnity-expired and training expiry notifications deep-link to /ppp-passport. See the ppp-passport spec change-log entry for the full set. | #12893, #12896, #11212 | Task 13 audit defects D2, D5 and D9 (5 Oct 2026); covered by @issue-12893 in ppp-passport.feature. |
| 2026-10-04 | Hospital-admin Meetings gains an End date & time, an Extend action, a location pin pre-filled from the hospital default, invites (individual and Profile-filtered group) in Manage attendance, and stacked cards at phone width. See the attendance spec for the ACs. | #0, #11773, #12450, #12449, #11216 | Rob's 4 Oct 2026 decisions on #12449/#12450 and Matt's 4 Aug brief (#11773). Task 14 lane, Refs #11216. |
| 2026-10-02 | Removed TaT ("Training another Trainee") from the Super Admin Level of Involvement reference screen's legacy-codes section — it duplicated the live non-consultant table, which already lists it as selectable. | #12707, #9200, #10825 | #9200 (PR #10825, 2026-07-21) re-added TaT as a selectable non-consultant LoI option, but LEGACY_NON_CONSULTANT_CODES in LevelOfInvolvementReference/index.tsx was never updated, so the admin reference screen kept showing TaT a second time, mislabelled as dropped/historic-only — directly contradicting the live dropdown. Found live during the Task 4 Async Task Model audit (#11183). Only PP ("Partial Procedure") remains legacy. |
| 2026-09-29 | The Admin Users management gate (adminUsers list / set-admin / reset) and adminProcedure now identify the caller by the linked pppUserId instead of the login email. No change to what a real super admin can do. | #12616 | Critical anonymous privilege escalation. An anonymous sign-up using an unlinked super admin's email passed both admin gates. See auth.identity.resolved-by-ppp-user-id. |
| 2026-09-25 | Attendance report/attendee tables and CSV/PDF export now label the columns "Check-in method" and "Check-out method", and the tables scroll sideways in a labelled, keyboard-focusable region with a visible hint on small screens. | #12468, #12458 | Design review of #12454 found the bare "Method" header ambiguous and the 5-column table unreachable at 375px with no scroll cue. |
| 2026-09-25 | Cross-reference AC admin.attendance.meeting-management-cross-ref now notes the on-screen report and attendee tables show a Check-out Method column. | #12454, #12446 | The Meetings attendance dialogs are Hospital Admin surfaces governed by attendance.md; the column was previously visible only in the CSV/PDF export. |
| 2026-07-28 | Fixed a stale file path in the Super Admin AMC yearly-review checklist — the RACS CPD Framework row pointed at docs/compliance/RACS_CPD_FRAMEWORK.md, which had not existed since the doc moved to docs/site/compliance/ and was renamed to kebab-case, so the row sent a Super Admin to a missing file. | #11112, #11108, #11025 | Found while sweeping for RACS naming outside instances/marketing/src after release #11107. The naming half of that sweep was descoped by Matt's 2026-07-29 ruling on #11025 — college references in activity content, docs and news are fine, and only proprietary product/feature naming (CAPE) is banned — so the genericised prompt wording was reverted. The broken path was a real defect independent of the ruling and is fixed here. |
| 2026-07-22 | Settings → Surgical Data tabs grouped by canonical speciality — all five tabs render as default-collapsed accordion sections (Surgeries via procedures.specialityId direct FK; the four lookup tabs via a derived join through the procedures that reference each value), with one 'Used across specialties / Unclassified' bucket for 0-or-many mappings. No schema change, no migration. | #10843, #10777 | Matt's UAT WhatsApp feedback (19 Jul 2026): Surgical Data 'not grouped per speciality… confusing… needs to be better segregated'. Rob (CTO) greenlit grouping all five tabs (2026-07-22), resolving the issue's for-discussion open question. Grouping keys are clean because #10775 (PR #10820) deduped the speciality taxonomy. Pure read-path derivation rendered through the shared SpecialityGroupedAccordions on the design-system CollapsibleSection atom — no new brand primitive. |
| 2026-07-22 | Speciality master data deduplicated to one canonical GMC/RACS row per specialty; UNIQUE(name) added (migration 0215); legacy lookups.json variants canonicalised; seed alias map now driven by shared LEGACY_SPECIALITY_TO_CANONICAL constant; settings CRUD returns friendly CONFLICT on duplicate names | #10820, #10775 | Matt's UAT WhatsApp feedback (19 Jul 2026): Settings specialty master data 'not grouped per speciality… confusing… needs to be better segregated' — the list was the un-reconciled union of two seed sources with duplicate, inconsistently-named rows; also the latent root cause of the #10776 critical-conditions backfill misses. Canonical names were already ratified (#4613/#5404/#7464), so the dedupe resolves the open question without a new naming decision; display-name tweaks remain a one-row rename. |
| 2026-07-15 | Added the hospital-approver admin CRM AC to the Hospital Admin screen — a central screen at /hospital-admin/approvers to view/add/edit/remove the default (hospital, department) timesheet approver, backed by the ppp.hospitalApprovers.* CRUD router | #10687, #10652 | Per Matt (dev session 2026-07-14) the default-approver mapping should live in the admin CRM so it can be centrally maintained; the new screen lives under modules/admin-org/hospital-admin and is a Hospital Admin surface. Child of epic #10631, depends on the hospital_approvers table/view from #10650. Deliberately disjoint from the per-user HospitalApproverTable (#10652) |
| 2026-06-29 | Rename "educational supervisor" → "professional supervisor" in admin AC description for supervisor removal. | #9718, #9703 | Vernacular change requested by Matt (#9703) — "Professional Supervisor" is the correct term for non-consultant profiles platform-wide. |
| 2026-06-17 | Added the HLSR Requirements console AC to the PPP Super Admin screen — per-specialty requirements list management with Option-A multi-year handling and a yearly confirmation banner | #8774, #8729 | The HLSR list-management page lives under modules/Admin and is part of the super-admin screen surface; full spec lives in super-admin.md (#8729) |
| 2026-06-01 | Documented that the Hospital Executive Admin dashboard's CPD-alignment OKR section (CpdAlignmentSection.tsx under instances/ppp/src/modules/HospitalExecutiveAdmin/) lives in the admin area but is governed by organisational-dashboard.md, via a cross-reference AC. | #7924, #7363 | The CPD-alignment OKR wiring (#7363) added CpdAlignmentSection.tsx under instances/ppp/src/modules/HospitalExecutiveAdmin/, which admin.md owns by code-path glob (instances/ppp/src//Admin/); the feature itself is spec'd in organisational-dashboard.md § OKR framework, so admin.md carries a cross-reference rather than duplicating the criteria. |
| 2026-06-01 | Documented that the Hospital Admin meeting-management screens (including the new Attendance Report dialog with CSV + branded-PDF roster export) live under the Hospital Admin area but are governed by attendance.md, via a cross-reference AC. | #7923, #7879 | The tabular attendance report export (#7879) added AttendanceReportDialog.tsx under instances/ppp/src/modules/HospitalAdmin/, which admin.md owns by code-path glob; the feature itself is spec'd in attendance.md, so admin.md carries a cross-reference rather than duplicating the criteria. |
| 2026-06-01 | Documented that the Hospital Executive Admin dashboard's "Doctor Seats Used" metering tile (Dashboard/index.tsx under instances/ppp/src/modules/HospitalExecutiveAdmin/) lives in the admin area but is governed by profile-non-doctor.md § Seat economics, via a cross-reference AC. | #7877 | The seat-usage metering wiring (#7877) edited Dashboard/index.tsx under instances/ppp/src/modules/HospitalExecutiveAdmin/, which admin.md owns by code-path glob (instances/ppp/src//Admin/); the seat-economics feature itself is spec'd in profile-non-doctor.md § Seat economics, so admin.md carries a cross-reference rather than duplicating the criteria. |
| 2026-05-19 | Added per-(hospital, specialty) governance data model — hospital_health_services table, hospitals.health_service_id FK, hospital_admins.specialty_id scope column, and a getDepartmentApproverPool join helper. | #6557, #4840 | Implements the long-term governance model agreed on the Rob & Matt call 13 Apr 2026 — the hospital-admin role is scoped per department within a hospital, surfacing timesheet to-do items to the right consultant pool. |
| 2026-05-19 | Document completed ppp_hospital enterprise onboarding — tier matrix, settings, archive, hospital_admin role — and add the end-to-end onboarding @smoke BDD scenario. | #6547, #4507 | #4507 captured the production-readiness gaps for the enterprise hospital system; all ACs were delivered across #4524/#4525/#4526/#4527/#4529 but lacked a single traced spec section and the end-to-end onboarding happy-path smoke scenario the issue's Test Requirements called for. |
| 2026-04-21 | Triage sweep — 18 open issues mapped to this spec | #5190, #5070, #5053, #5052, #5020, #5017, #5016, #5015, #5014, #5013, #4916, #4840, #4823, #4777, #4659, #4507, #2013, #1985 | Unblocks drift detection on the features index. |
| 2026-04-13 | Initial spec — hierarchy, super admin vs hospital admin responsibilities, schema | #4823, #4840, #4841 | Rob & Matt call 13 Apr 2026: governance model agreed end-to-end. Specialty list confirmed nationally consistent and reusable AU+UK. Per-(hospital, specialty) admin scope. |
| 2026-04-13 | Added role hierarchy, permission matrix, and implementation plan for hospital_admin role | #4529 | Product decision: Option B — implement hospital_admin as subset of executive_admin. Dashboard read access plus approve/reject join requests. No hospital settings access. Ward manager / department head use case. |
| 2026-04-21 | Added Audit Trail Invariant — admin mutations must write to audit_trail | #5012 | Compliance gap: the audit_trail table existed but nothing was writing to it. Minimum-viable wiring covers admin role changes and hospital CRUD; remaining settings mutations tracked as follow-up. |
| Date | Change | PR/Issue | Reason |
| ---------- | ------------------------------------------------------------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 2026-04-13 | Initial spec — hierarchy, super admin vs hospital admin responsibilities, schema | #4823, #4840, #4841 | Rob & Matt call 13 Apr 2026: governance model agreed end-to-end. Specialty list confirmed nationally consistent and reusable AU+UK. Per-(hospital, specialty) admin scope. |
| 2026-04-13 | Added role hierarchy, permission matrix, and implementation plan for hospital_admin role | #4529 | Product decision: Option B — implement hospital_admin as subset of executive_admin. Dashboard read access plus approve/reject join requests. No hospital settings access. Ward manager / department head use case. |
| 2026-04-21 | Added Audit Trail Invariant — admin mutations must write to audit_trail | #5012 | Compliance gap: the audit_trail table existed but nothing was writing to it. Minimum-viable wiring covers admin role changes and hospital CRUD; remaining settings mutations tracked as follow-up. |