Surgical Logbook
Feature Overview
The Surgical Logbook allows doctors to record every surgical procedure they perform or assist with. It maps to specialty curricula (RACS, ISCP/RCS) and tracks progression toward required procedure volumes. It supports import from established logbook systems (ISCP/eLogbook for UK, Australian formats) and OCR scanning of theatre lists and patient stickers.
Open Questions
| # | Question | Source | Answer |
|---|---|---|---|
| Q1 | Where does the dataset get built to — when are the master procedure lists considered "done"? Update 2026-06-10 (#8468 waves): built to the Orthopaedics PPP masterlist model from the ISCP curricula Matt provided — all 10 lists re-keyed (index groups + numbers, syllabus hierarchy) with per-specialty change/disagreement reports (rekey-reports/). "Done" = Matt's expert verification of those reports on #6684–#6705 (~12 named questions remain). | Questions section; Catchup 2026-06-09 | Open |
| Q8 | FHIR export shape — which resource types are exposed? (Use-case confirmed 2026-05-13: third-party data integration and platform feature licensing. Specific resource types and consumer onboarding process still TBD.) | Drift audit 2026-04-22; partial update 2026-05-13; #8814 | Answered (engineering/product default, 2026-06-30, #8814): Procedure only for now. The shipped OpenAPI surface exposes a single FHIR Procedure endpoint (api/backend-ppp/src/rest/fhir/openapi.json), and that is the agreed export shape for the current phase — it matches what is built (AC logbook.api.export-resource-shape). Additional resource types (e.g. Practitioner, DocumentReference) and the third-party consumer-onboarding process are deferred until a concrete licensing consumer requires them; expanding the set is a future decision, not a commitment to omit them permanently. |
| Q9 | Practical Logbook dataset — label variant is live (logbookVariant derived from job title); when does the physician procedure master list land? | Engineering audit 2026-05-12; #8815 (Rob 2026-07-16) | Resolved (Rob, 2026-07-16, #8815). The interim physician dataset lands NOW, seeded from the UK Internal Medicine Training (IMT) practical procedures list (JRCPTB / Federation of Royal Colleges of Physicians) rather than waiting for RACP — research established RACP's 2026 curricula are EPA/competency-based and do not publish a flat procedure list. ~17 procedures across two IMT tiers (Independent by end of IMT, Experience of) plus a Logbook extension set, keyed to a General Internal Medicine speciality and seeded via the same seedSettingsData.ts mechanism as the 10 surgical lists (#8468). Once seeded, a procedural-variant user whose specialty resolves to this list gets it instead of the #8890 External-Lookup-only empty-state. See AC logbook.variant.practical-dataset and src:issue-8815. Matt may redirect to a different physician source; same mechanism re-keys. |
| Q13 | Curated principal-index mapping — the derived tree (#7319) groups each procedure under its existing principalProcedure value; rows lacking one fall into an "Unclassified principal procedure" bucket. Matt said he subcategorised orthopaedics "because I kind of know how it's relevant" — the full per-specialty principal-index categorisation still needs Matt + surgical-colleague review and sign-off (e.g. orthopaedics first) before the tree is treated as clinically authoritative. Which specialties are confirmed, and what is the curated mapping for the unclassified rows? Update 2026-06-10: the per-specialty mapping is now applied from each curriculum's own index groups via dual-rater consensus (#8511); the remaining sign-off set is the per-specialty disagreement lists (~12 questions, on #6684–#6705). | Transcript 2026-05-13b §00:34:04; #7319; #8468 | Open |
| Q14 | NOT a Matt question — recorded for tracking. Orthopaedic Surgery has no curriculum-structures/*.curriculum.json file in this repo, so it has no entry in specialty-critical-conditions-config.json, curriculumTrainingDefaults.ts, or the SPECIALTY_PROCEDURE_CLASSIFICATIONS registry — every other seeded surgical speciality does. Matt already supplied the source PDF (Q19 GDrive link below, 2026-05-19); this is the same #8490-style mechanical extraction already done for the other 9 specialities, engineering work only. | src:issue-9123 gap list (2026-07-25); appraisals-wba.md Q19 (source PDF already supplied) | Resolved 2026-07-26 (#10945). orthopaedic-surgery.curriculum.json extracted from the ISCP/JCST Trauma and Orthopaedic Surgery Curriculum (Version 2 August 2024) — 14 critical conditions, 13 index-procedure groups (indicative numbers summing to the curriculum's own stated Total 365), 1800 overall indicative operations. All three consumers now carry an Orthopaedic Surgery entry. No Matt input was required. |
| Q-retrospective-control | Add-retrospective control — March (transcript 2026-03-11) asked for a single button with a roll-down (built #6392); June (transcript 2026-06-03, #8191) calls that a regression and asks for the options visible inline. These reverse each other. Confirm direction: (1) visible inline multi-select tick-boxes restoring the pre-#6392 control [planned]; (2) keep the button+dropdown and just ensure no option is missing; or (3) a single-choice radio (would drop the ability to link more than one retrospective per case). Also confirm "involvement options" means the retrospective options (Reflection/WBA/Feedback), not the separate Level-of-Involvement field. | Transcript 2026-06-03 §AddRetrospective; #8191 (reverses #6392) | Open |
| Q-group-flow-advance | Grouped Action Items stepped flow (#8101/#8496): when the surgeon SAVES a case but it stays a draft (not submitted), the flow pauses with Resume/Skip rather than auto-advancing — the to-do genuinely is not done. Confirm: (1) pause is correct [shipped]; or (2) Save-without-submit should also advance to the next case, leaving the saved draft in the list for later. | PR #8496 review 2026-06-10 | Open |
| Q-consultant-loi | Consultant Level of Involvement labels — #9187 shipped PPP's own NON-consultant vernacular (Observed, Assisting, Trainer (unscrubbed), Trainer (scrubbed), Primary). Matt confirmed the consultant list is DIFFERENT and listed separately, but the authoritative consultant labels live in the logbook design spreadsheet that is not yet in hand. What are the exact consultant LoI labels, and what is each one's Primary-vs-Secondary operator classification? Until confirmed, PPP_CONSULTANT_LOI is a clearly-marked PPP-default placeholder. Also confirm the provisional non-consultant code↔label mapping for the two Trainer levels (currently reusing the Supervised-Training codes). Wiring delivered (#10076): the WORDING was never a blocker on shipping the override MECHANISM — #10758 made the placeholder admin-editable in-app (loi_label_overrides), and Matt engaged with the placeholder set on #9200 (2026-07-21) without objecting, so #10076 (Rob, acting PO) wired the override-aware resolveConsultantLoiLabel resolver into every doctor-facing surface that previously rendered the raw code-derived involvementDisplayLabel instead: the add-case consultant dropdown, the consultant/non-consultant reviewer sections, the case table column, the case card and the CSV export. A super-admin override entered on /admin/level-of-involvement now shows up everywhere a doctor sees a consultant LoI, not only the admin reference screen. The exact wording remains Matt's to refine at any time via the in-app editor — that residual is a light-touch follow-up, not a blocker. | #9187 — Rob (2026-06-24 call); pending logbook design spreadsheet; #10076 — Rob (acting PO, 2026-07-22), display-layer wiring | Wiring resolved (#10076); wording refinement optional/open |
| Q-signature-audit | Digital-signature persistence — the prompt's copy says "recorded to this entry for audit purposes", but the confirmation is a UI gate for Verify only and is never persisted (true since the original add-form implementation; unchanged by the #8192 relocation to the review screen). Should verifying write a signature audit event (who/when, e.g. an audit-trail row or verifiedBy/verifiedAt columns) so the "recorded" claim is true? Schema + audit-trail decision for Matt. | Transcript 2026-06-03 ~00:51:58; #8192 engineering note | Open |
| Q-malt-alignment | RACS MALT alignment premise + Section B — the deep review (#9189) compared the logbook to the RACS MALT standard and surfaced Section B items beyond the recognised PPP model: structured complications + a Clavien-Dindo severity grade; a discrete MALT "Primary Surgeon = Yes/No" outcome flag with binding dual-primary de-duplication (PPP currently derives a primary-operator role and only warns on conflict); multiple coded procedures per patient encounter (PPP is one procedure per row); off-platform supervisor nomination for logbook sign-off (theme of #9168); and a nominated/alternate supervisor + bulk approve/reassign model. Full MALT code-set alignment also needs a formal RACS data agreement (#1740). Matt questioned the premise itself ("At this stage we won't be seeking RACS formal agreement… What was the decision to attempt to Align to MALT standards?") and the 24 Jun catch-up confirmed PPP will bridge from the UK system and build its own level-of-involvement / primary-secondary model (authoritative LoI lists in #9187) rather than aligning heavily to RACS MALT. Decision for Matt: which (if any) Section B items to build, and whether to record MALT non-alignment as a governed limitation. Section A engineering tidy-ups (assessor email on submit, involvement-code zod enum, assessor-vs-supervisor naming docs) shipped in #9189 independently of this premise. Matt answered all Section B items on the 2026-07-08 thread: (1) structured complications + Clavien-Dindo grade → BUILD, audit-tool-only ("we can add it clavien dindo classification system as an option for the user to enter") — shipped as logbook.audit-event.complication-grade, decoupled from CPD Home / HLSR, no MALT licence; (2) primary-surgeon dedup → already exists, couple to Level of Involvement (confirm, don't rebuild); (3) multiple procedures per case → already exists (confirm); (4) off-platform supervisor → already exists (confirm); (5) nominated/alternate + bulk → not needed; (6) MALT licence / RACS reference in-platform → not pursuing (marketing-site RACS references fine). MALT non-alignment is the governed position. | Deep RACS MALT review 2026-06-24; #9189; Catchup 2026-06-24; #9187; #9168; #1740 | Resolved (Matt 2026-07-08). Item 1 (Clavien-Dindo) built audit-tool-only; items 2-4 confirmed already-existing (verification, not rebuild); item 5 not needed; MALT licence not pursued. Section A tidy-ups shipped earlier (#9189). |
| Q-rc-profile-dimensions | Responsible-consultant profile summary (#10823) — MVP ships a header count + delineations (procedure category → index procedure) + a level-of-involvement secondary breakdown, with surgical outcomes deliberately excluded (ANZASM confidentiality) and no patient identifiers. "Delineations" is grounded by research as surgical scope of practice (src:research-2026-07-22-delineations-scope-of-practice), since Matt used the term loosely. Decision for Matt: confirm the exact breakdown dimensions if richer views are wanted later (e.g. by specialty/subspecialty, complexity/acuity, hospital, trauma vs elective, or a target-vs-actual scope-of-practice comparison), and whether the period selector should also offer CPD-year presets rather than the shared 3M/6M/1Y/All windows. | #10823 (Matt NBB 2026-07-21); research 2026-07-22 | Open |
| Q-ocr-procedure-match | Scan Operating List procedure classification (#11350). A real theatre list matched 0 of 5 procedures to the master list (theatre shorthand such as "IM nail", "ORIF", "hemiarthroplasty"). Options on #11350: (A) expand the procedure alias/synonym list, (B) fuzzy-match the procedure column at extraction time, (C) accept unclassified-on-import as normal UX for now. Matt (2026-08-11) asked about the pros and cons of A vs B, "would fuzzy search create and alias situation", and deferred it to a call. On WhatsApp he deferred it to a call again††. That call was cancelled on 2026-08-12. No later Matt statement found in GitHub, Notion, the meeting transcripts up to 2026-09-29, or WhatsApp up to 2026-09-28. Which option (or combination) is the near-term priority? | #11350 (Matt 2026-08-11); src:issue-11350 | Open — awaiting Matt |
| Q-signoff-cpd-double-credit | Consultant CPD credit when both sign-off and own-case credit apply. A consultant can earn supervising CPD for the same operation in two ways: by verifying the non-consultant's case (logbook.consultant-review.cpd-credit-on-sign-off) and by logging their own entry for it at a supervising LoI (cpd.multi-user.self-loi-credit). No Matt source says whether both should count. Should one operation credit the consultant once (and which path wins), or are these separate activities? | Task 4 spec refresh 2026-10-03; #12725; AC3 split to #12814 | Answered by Rob 4 Oct 2026 (#12814): credit once, the consultant's own log wins — built |
| Q-ocr-age-only-storage | Storing only age at surgery instead of DOB. Matt (2026-08-04): "Let's build for now, as I said, date of birth, hospital ID, and the patient's initial … with a view to then be probably refining to" keeping the hospital reference number and the age at time of surgery, storing nothing else ("I think that's probably where we will get to"). The current build stores DOB (encrypted) per logbook.case.patient-identifier-encryption-at-rest. When should the age-only refinement happen: before launch, after the GDPR/privacy policy review he mentioned, or later? | src:transcript-2026-08-04 (~00:36:45) | Open — direction stated, timing not |
| Q-import-window | How long is the historic-import window, and what happens when it closes? Matt (2026-09-22) wants historic import to feel like a limited-time step that pushes every new user to upload all their past cases, with no row cap (logbook.import.time-boxed-onboarding-window). On 2026-05-13 he also said "we can provide discretion to this maybe internally". Not yet stated: (1) how long the window is, and when it starts (sign-up, subscription start, or first login); (2) once it closes, is import hidden, or still allowed with a warning; (3) who can reopen it for a user (for example a super admin) and how; (4) whether the generic 5,000-row-per-import technical ceiling is acceptable, given that he said "everyone's going to have way more than" 500 and his own logbook is about 4,000 cases. | src:transcript-2026-09-22 (~00:37:31); src:transcript-2026-05-13a (~00:24:14); #12423 | Open |
| Q-import-notes-mapping | Should the import mapper drop the Notes, Broad Area and Specific Area targets? On #9829 (2026-06-30) Matt wrote "remove mapping to notes" under Category mapping, next to the instruction to categorise by matched operation and not by the sheet's own competency/category columns. The wizard still offers Notes (saved on the case) and Broad Area / Specific Area (accepted in the mapper but ignored by the import) as targets. Does "remove mapping to notes" mean (1) stop source category/competency columns being mapped into Notes, keeping a Notes target for genuine free-text notes; (2) remove the Notes target entirely; or (3) something else? And should the ignored Broad Area / Specific Area targets come out of the mapper? | src:issue-9829 (Matt 2026-06-30, item 3) | Open |
| Q-import-onboarding-effort | How much time should a user expect to spend completing imported cases? The Task 5 brief (#11186, 2026-07-29) asks to "determine estimate time user would need to commit to attribute to prompts for 'outstanding onboarding'". That is a measurement for the task review, not a stated product behaviour. Should the product also show the user an estimate (for example "about N minutes to complete your N imported cases") on the import result or in the Outstanding Onboarding prompts (Task 7, #11189), or is the estimate only for Matt's review? | src:issue-11186 (Matt 2026-07-29) | Open |
| Q-import-national-format | Reference for the national-standard logbook file format. On #9820 (2026-07-09) Matt asked: "Can we dig up the research/reference for the national-standard file format?" (this is the format behind the "Australian PPP" sheet option). The issue was closed on 2026-07-10 with a decision to keep the label as it is, and the reference was never given to him. Is there a national-standard Australian logbook export format that import should name and support explicitly, and is the "Australian PPP" label still right? | src:issue-9820 (Matt 2026-07-09) | Open |
Closed Questions (8) — click to expand
| # | Question | Source | Answer |
|---|---|---|---|
| Q3 | Favourites (consultants + operations) — where should they surface (top of list vs other representation)? | Additions section | Answered (transcript 2026-05-13 ~00:31:41): Top of list. Commonly selected operations and consultants should appear at the top of their respective selection lists. Refined 2026-06-30 (Matt, #8171) for the Responsible Consultant picker only: the doctor's Clinical Supervisor(s) sort above favourites (Clinical Supervisors → favourites → alphabetical). Favourites remain top-of-list for the operations picker. See logbook.entry.responsible-consultant-list-order. |
| Q4 | Stacking UI — one OCR source to multiple entries: what's the review/confirm shape? | Drift audit 2026-04-22 | Answered (transcript 2026-05-13 ~00:24:14–00:25:27): Scan daily list via OCR → auto-populate details → incomplete fields go to a to-do list → user completes to-dos end of day. WBA, reflection, and feedback can all be stacked as activations from a single log entry. Prescriptive — do not change existing flow without checking with Matt. |
| Q5 | Satisfaction capture — which scale, when prompted, mandatory or optional? | Drift audit 2026-04-22 | Answered (Rob, 2026-05-21): 1–5 stars, optional (surgeon may skip). Displayed as a star-rating input at end of case entry. Score stored as an insight — feeds PPP Pulse surgeon-load signal. Reconciled #8598: the shipped control was a 1-10 scale; corrected to 1-5 across both Add/Edit form variants and the review screen (logbook.entry.satisfaction-scale). The literal star-glyph rendering ("star-rating input") remains open — current control is the shared numbered RatingScale. |
| Q6 | Verification reject path — consultant verify is built (ReviewLogbookCaseForm → verified); what happens when a consultant declines? | Engineering audit 2026-05-12 | Answered (Rob, 2026-05-21): Entry stays in the non-consultant's logbook, flagged as unverified / declined. Non-consultant receives a notification. Entry counts toward totals but is visually distinguished (e.g. greyed, badge). No forced resubmission — non-consultant may choose to leave it unverified or contact the consultant directly. |
| Q7 | Case propagation — how do we match other participants (name, email, GMC)? | Drift audit 2026-04-22 | Answered (transcript 2026-05-13 ~00:20:29–00:21:42): Non-consultants enter independently and can select which other users were present. If a duplicate is detected (same time + patient details), the surgical entry collapses to one record for the consultant — but each non-consultant retains their individual involvement level, supervision time, competency data, and satisfaction rating. Consultant provides feedback and competency scoring for each non-consultant separately. |
| Q10 | Wheel/donut chart style — Matt suggested a wheel-style display "for certain data" during dashboard widget review, but did not specify which widget(s). Which widget(s) should use a donut/wheel chart? | Transcript 2026-05-13 §DashboardWidgets (~00:45:31) | Answered (transcript 2026-05-13 ~00:41:09): Primary vs secondary operations widget. Matt: "I wonder whether it's better as a wheel" for the primary/secondary breakdown, with hover detail showing per-category breakdown. |
| Q11 | Onboarding-import ring-fence — minimal version shipped (#6334): imported entries excluded from a 90-day active-engagement metric. What are the precise constraint rules — max legacy rows per onboarding window, a hard timing cut-off after which import is disabled, and what user-facing consequence (warning vs blocked) applies when exceeded? | Transcript 2026-05-13 §LegacyImport (~00:22:53); #6334 | Superseded (Rob, 2026-09-20, #12303): the 90-day window and 500-row cap answered below were removed entirely — "Remove the 90 day 500 row import limit." The Import Logbook entry point is now always available and unrestricted (still subject to the generic 5,000-row MAX_IMPORT_ROWS technical sanity ceiling that applies to every import). The #6334 active-engagement exclusion (imported entries don't count toward the 90-day engagement metric) is unaffected — that is a separate mechanism this decision did not touch. Original answer, preserved for history: Answered (Rob, 2026-05-21): 90-day window from account creation; max 500 legacy entries. After 90 days the import button is hidden. Exceeding 500 rows shows a warning and blocks further import until reviewed. Explore relaxing limits once real usage data exists. |
| Q12 | Logbook API token semantics — Matt's transcript only asked for "an API interface and token feature" (§APILicensing ~00:56:04). Should tokens be per-user or org-wide, what expiry/rotation policy applies, and is write access ever permitted for external consumers? | Transcript 2026-05-13 §APILicensing Next-steps (~00:56:04); #7299 audit; #8816 | Resolved (Rob, 2026-07-11). Per-user scope, read-only, confirmed as the official policy for the Logbook API token — no write access for external consumers, ever. The engineering default the team hardened into code (from the shipped #7017 behaviour) is now the confirmed product policy: per-user scope (a token exposes only its owner's logbook data; cross-user reads return 403), READ-ONLY (GET-only surface, non-GET → 405), optional expiry + immediate revocation with a 90-day default expiry applied at issuance when none is set, and atomic rotation (logbookApiTokens.rotate revokes the old token and issues a fresh one in a single DB transaction). Kept consistent with mcp-provider.md Q1–Q4. This was Rob's direct decision, not raised with Matt. |
Matt's 17 Apr 2026 Notion Brief — Requirements Update
Source: Logbook Notion brief.
Rename intent: Matt now frames this feature as just "Logbook" — rendered as "Surgical Logbook" for Surgeon users and "Practical Logbook" for Physician (non-Surgeon) users, driven by Job Description on Profile (Doctor). The filename surgical-logbook.md is retained for now to avoid breaking notion-map.json, BDD files, issue labels, and GDrive links; rename to logbook.md is scheduled for Wave 6 of the Notion sync.
Issues Matt wants solved (verbatim)
- Onerous data collection.
- No verified logbooks exist, creating an extra sign-off process that can be gamed.
- Competency score / micro-feedback not collected.
- Doctors present at the same case both have to enter the case to their personal logbook (duplication).
- Satisfaction not collected as an insight.
- Insights not mapped to Health Metrics or time-at-work (Pulse linkage).
- No way to create multiple entries from one source (stacking).
- Manual entry only.
- No FHIR-enabled logbook product exists — Matt explicitly calls this out as a differentiator for PPP.
Purpose
- Easy-to-use, verified logbook that enables CPD scoring and WBA activation, feedback collection, and competency tracking over time.
- FHIR-enabled product.
- Allow upload of prior records for immediate insights.
- One-user logbook entry propagates to the other users in the case (e.g. non-consultant enters case; consultant's log is also created) — preventing duplicate data entry across the team.
- Downloadable, portable insights for job tendering.
- Enable PPP Enterprise matching for certain roles.
Process (authoritative flow)
- OCR entry — single or multiple (stacking to-do's).
- Completion of entry against dataset or external-lookup function.
- Satisfaction capture.
- WBA activation (if desired).
- Submission for verification of the operation(s) + role, collection of competency score and feedback.
Surgical Case parent (multi-participant model)
Source: 13 May 2026 catchup transcript (00:20:29–00:21:42). Matt's directive: "do not change the code that exists" — the model below is purely additive.
One physical operation may involve multiple doctors (one consultant + N juniors). Each participant carries their own per-person data (role, level of involvement, supervision time, satisfaction, competency, WBA / Reflection / Feedback links). What the existing data model is missing is a parent grouping that ties their entries together as one surgery.
Model (additive — no changes to existing tables beyond one nullable FK):
surgical_case (NEW)
id — surrogate PK
reference — derived from patient_urn + surgery_date + primary_procedure_id
patient_urn
surgery_date
primary_procedure_id FK procedures
hospital_id FK hospitals — nullable until populated
trauma_or_elective — enum
patient_age_at_surgery (years) — for Adult vs Paediatric widget
created_by_user_id FK users — first user to enter
created_at, updated_at
activities (EXISTING, type='logbookCase')
+ surgical_case_id FK surgical_case — NEW nullable column
+ participant_role enum — NEW: 'primary' | 'assistant' | 'observer' | 'consultant'
...all existing per-user fields stay (user_id, supervision_time, satisfaction, competency,
named_consultant_id, ...) — unchanged ...Behaviour change (small, surgical):
duplicateDetection(URN + date + procedure)graduates from warn-only to auto-link: if another activity matches, both rows are pointed at the samesurgical_case_id(creating the parent if it doesn't yet exist).PrimaryOperatorConflictDialogsoftens: "you're not primary on this case — recording you as assistant" rather than a hard conflict, while keeping the explicitskipConflictCheckproceed-anyway path.- When a junior names a consultant, no phantom activity is created for the consultant. The consultant's logbook view queries
activities WHERE user_id = me OR named_consultant_id = megrouped bysurgical_case_id, so they see one card per surgery with each junior's child entry beneath it — eliminating the consultant-double-feedback problem (transcript 00:21:42). - WBA / Reflection / Feedback continue to link to a specific participant row (the junior who triggered them) via the existing
related_formstable — unchanged. Consultant feedback rides on the consultant's own participant row when they verify.
Why this respects "do not change": existing activity-row writes/reads keep working; new surgical_case_id and participant_role are nullable and back-fillable; only duplicateDetection graduates from warn → link. Migration is one ADD COLUMN + CREATE TABLE, fully reversible, accompanied by a .validate.sql per CLAUDE.md #4802.
WBA / Reflection / Feedback Activation Flow (audit only)
Source: 13 May 2026 catchup action "Check WBA Data Flow". Audit-only — no code change is proposed against any row in this table. Matt: please sanity-check.
| Step | Where | What happens |
|---|---|---|
1. User saves logbook entry with createWba / createReflection / createFeedback flags | instances/ppp/src/forms/LogbookCaseForm/shared/hooks/useLogbookFormMutations.ts | Three tRPC mutations fire from the form |
2. Entry persists as an activity (type='logbookCase') | api/backend-ppp/src/services/logbookService/index.ts → createLogbookEntry → activitiesService.createActivity | Polymorphic activity row created |
3. relatedFormService.LogbookHandler.process() runs | api/backend-ppp/src/services/relatedFormService/handlers/logbookHandler.ts | Reads the logbook row, decides per flag |
4. WBA created if createWba | LogbookHandler.createWbaFromLogbook → determineWbaType picks PBA / CBD / CEX from operation, builds an activity (type='wba') | Data drawn into WBA: operation name, patient URN, date, role, consultant ID |
5. Reflection created if createReflection | LogbookHandler.createReflectionFromLogbook → new activity (type='reflection') | Data drawn: operation, date, free-text seeded with logbook context |
6. Feedback created if createFeedback | LogbookHandler.createFeedbackFromLogbook | Data drawn: operation, date, named consultant, role |
| 7. Cross-links recorded | related_forms table | parent = logbookCase activity_id, child = wba / reflection / feedback activity_id |
| 8. Status tracker writes outcome | StatusTracker.setSuccess / setFailed | Surfaces in UI as success / failure toast |
Verify-time linkage: ReviewLogbookCaseForm.tsx reads the same logbook activity row + any feedback children. When the consultant adds feedback during verify, it goes through step 6 above against their participant row.
Consultant Review — Reject / Decline path (for demo)
Source: 13 May 2026 catchup. Net-new addition (resolves the open half of Closed Question Q6). Verify path stays untouched.
ReviewLogbookCaseFormgains a "Decline" button alongside "Verify".- Decline opens a small dialog: required
declineReason(textarea, 10–500 chars) + optional structureddeclineCategoryenum (incorrect-role,wasn't-present,wrong-patient,wrong-procedure,other). - New
logbook.consultantDeclinetRPC procedure → sets activitystatus='declined'; writesdeclineReason+declineCategory+declinedBy+declinedAt; emits an in-app notification to the submitting user via the existing notification pipeline. - Frontend (submitter side): a declined case shows a banner with the reason + a "Resubmit" CTA that pre-fills the form so they can correct and resubmit. Resubmit resets status to
pending; the previous decline metadata is preserved (not overwritten) so the verification audit trail is intact.
Placeholder for practical-logbook variant
- When a user's Job Description maps
logbookVariant = procedural, the UI/UX for this feature is presented as Practical / Procedural Logbook. The underlying data model is shared; variance is in labels, default procedure master list, and which dataset is looked up on external-lookup. - Dataset for the procedural variant — seeded (#8815, Rob 2026-07-16). The interim default physician list is the UK Internal Medicine Training (IMT) practical procedures list (JRCPTB / Federation of Royal Colleges of Physicians), keyed to a General Internal Medicine speciality via the same
seedSettingsData.tsmechanism as the surgical lists. See AClogbook.variant.practical-datasetand Open Question Q9 (resolved). RACP was not used because its 2026 curricula are EPA/competency-based (no flat procedure list); Matt may redirect to a different physician source and the same mechanism re-keys.
Logbook variant label — current implementation
logbookVariant is derived at runtime from deriveLogbookVariant(user.jobTitle) in userProfileService. The page title already switches between "Surgical Logbook" and "Procedural Logbook" via logbookVariant === 'surgical' in LogbookCase/index.tsx. However, many other surfaces still hard-code "Surgical Logbook": the sidebar nav (CoreAppContainerSidebarMenuList.tsx), PPP Dashboard V2 widget title, pppConstants.ts (CREATED_FROM/VIEW strings), the Notifications module, and the Plans & Pricing feature list (#5962).
Original Vision
From Features Deck (Oct 2025) and Walk-Through Notes (Jan 2026):
Core Logbook
- Record procedures with: date, hospital, procedure name, role (Performed/Supervised/Assisted), ASA grade, patient details, notes
- Map to SNOMED CT / FHIR procedure codes
- Filter and search by procedure, date, hospital, role
- Overview dashboard: total cases, breakdown by supervision role, by category, by hospital
Multi-feedback per Operation (Jan 2026)
"Surgical logbook needs to be able to handle more than one feedback for one operation. So a consultant can add feedback that..."
A single operation entry should support multiple feedback entries from different consultants — not just one-to-one feedback.
Index Procedures (Jan 2026)
"Surgical logbook - index procedures - these need a certain number to be done which is defined by the user in their plan"
Specialty curricula define a list of principal / index procedures (broad categories) with minimum required volumes. The logbook must track progress against these targets — e.g. for Orthopaedics the JCST/ISCP curriculum gives an indicative 80× Major joint arthroplasty (Appendix 4d), which encompasses the underlying procedure rows (knee replacements, hip replacements, shoulder arthroplasties, disc replacements, etc.) tagged with principalProcedure = 'Major Joint Arthroplasty' in the seed data. Counting is at the principal-procedure level, not the specific procedure name — a knee replacement, a hip replacement, and a reverse shoulder arthroplasty all increment the same Major Joint Arthroplasty target.
The procedures table has a principal_procedure_id FK pointing at the principal_procedures lookup table (packages-shared/ppp/src/schema-groups/procedures.ts), so each procedure row is normalised to its principal-procedure category rather than carrying a denormalised text column. The seed JSON (api/backend-ppp/scripts/seed-data/procedures.json) uses a string principalProcedure field per row purely as the human-readable lookup key — the seeder resolves it to the corresponding principalProcedures.id at insert time. When extracting curriculum data for other specialties (#6086–#6095), the same shape applies: each row gets its specific name, mapped to its principalProcedure category in the seed JSON, with target volumes attached to the principal-procedure level.
Multi-Consultant Retrospective (Jan 2026)
"New requirement - if 3 or more people are in a surgery then retrospective needs to go to all those who were in the surgery"
When a case has ≥3 participants, the retrospective/feedback should be shared with all participants, not just one-to-one. (Note: this overlaps with the Retrospective feature spec.)
Import
- UK: ISCP/eLogbook format (OperationsList.xlsx — 22 columns, 507 rows)
- Australian: PPP multi-sheet xlsx format (13 sheets including SNOMED mapping)
- OCR: Theatre list JPEG (UK) and Australian patient sticker JPEG → auto-populate entry
Dashboard Widgets
- Supervision Breakdown (Performed / Supervised / Assisted)
- Operations by Category (bar chart)
- Competency Levels (clickable to drill into cases)
- Primary Surgeon count
Acceptance Criteria
Logbook Variant Labelling
- ✅
logbook.variant.page-title— Logbook Cases page title reads "Surgical Logbook" whenlogbookVariant === 'surgical', "Procedural Logbook" otherwise (Engineering audit 2026-05-12)† - ✅
logbook.variant.nav-label— Sidebar nav item, PPP Dashboard widget title,pppConstantsstrings (CREATED_FROM/VIEW), Notifications copy, and Plans & Pricing feature list must all readlogbookVariantdynamically instead of hard-coding "Surgical Logbook" (#5962)
FHIR & Standards
- ✅
logbook.fhir.health-blueprint-alignment— the logbook is FHIR-enabled to align with the 2032 Australian Health Blueprint and uses SNOMED CT terminology for procedure coding, positioning PPP within the required national health infrastructure and enabling third-party data integration.† - ⏳
logbook.fhir.snomed-tree-structure— procedure data is organised as a three-level clinically-relevant tree: Category → Subcategory → Principal index procedure (procedure leaves carrying their SNOMED CT code). The tree is derived from the existing procedure dataset bybuildProcedureTreeand served by thelogbook.getProcedureTreequery — no clinical data is hand-curated or duplicated.† Remaining: NCTS-validated SNOMED codes on every leaf (#7320) and the in-app tree-navigable selector UI; curated principal-index mapping pending Matt's per-specialty sign-off (Open Q13).† (#7319) - ✅
logbook.fhir.snomed-data-cleanup— the procedure seed data has no concatenated parent-child SNOMED CT codes (two codes merged into one cell) and no duplicate procedure entries; all codes are single, valid SNOMED CT concepts confirmed against NCTS.† Mechanical data-hygiene done (#7322, #7850): a Verhoeff check-digit gate rejects any over-long concatenated code; the exact-duplicate-row gate removed the last byte-identical duplicate (general-surgery "Gastroenterostomy"); same-name+code rows that differ only by anatomical area are left for Matt's clinical review (#7366). NCTS-confirmed validity, previously deferred to #7320, is now delivered: #7320 (NCTS OAuth2 auth) closed 2026-07-14, unblocking #8876 (AU masterlist re-key) and #8877 (authoritative re-validate against the pinned AU edition) — both closed. Every masterlist row is re-resolved against the authoritative NCTS terminology server via the shared FHIR$validate-codegate (logbook.fhir.validate-code-gate); a code that fails to resolve or resolves as retired/inactive is never silently kept, it is routed to the review queue (snomedMatchStatus='needs_review', feeding #7366). This confirmation is a live-DB re-key, not a static-seed rewrite: the checked-in*-db-ready.jsonfixtures intentionally carry nosnomedEdition/snomedVersionprovenance columns — that provenance is written to theprocedurestable by the re-key, which the mechanical-hygiene test file also now asserts (snomedSeedIntegrity.test.ts) so the two halves of this AC (mechanical seed hygiene + NCTS-confirmed validity) don't drift apart again.† (#7320) (#11589) - ✅
logbook.fhir.curriculum-structures— every specialty carries a curriculum-structure reference file extracted VERBATIM from the ISCP curriculum documents Matt provided (index-procedure groups with their training numbers, critical-conditions/WBA lists, special-interest areas, certification-evidence rules, per-curriculum deviations in extractionNotes); every name/number/condition — and, since #10945, the level-4 PBA count eachinvolvementstates, whichparseRequiredLevel4PbaCountturns into a trainee-facing requirement — is machine-verified against the source text by the committed verifierverify-extractions.py. That verifier is a developer-run check, not a CI gate, and the spec should not be read as claiming one: the multi-MB page-text extracts are deliberately uncommitted, and fetching eleven third-party PDFs on every PR would turn an unrelated PR red whenever iscp.ac.uk is slow or re-publishes a document at the same URL. It is reproducible from a clean checkout in one command —python3 verify-extractions.py --fetch [slug], which re-downloads eachsource.publicIdenticalDocument, verifies the pinnedsha256where a curriculum records one, and reports per-slug rather than aborting on the first missing input. Thatsha256guarantee holds on every run, not only the first (#11135): a pinned slug always re-downloads, because honouring a cached<slug>.txtwould let a synthesised or stale extract — including one produced from the committed JSON itself — be reportedOKwithout the pin ever being checked, and re-runs are exactly where a developer citing anOKline in a PR description is.--no-cacheextends the forced re-download to unpinned slugs; a missingpypdfor an unreachable URL is a per-slug problem, never an early return that skips the pin. The level-4 PBA count eachinvolvementstates is asserted as an anchored phrase in both forms it appears in — theN x Level 4 PBAsmultiplier carries its own level-4 marker, while the plain form is anchored to the count's whole clause (the phase prefix), because a curriculum can state the same bareN PBAsunder several phases and only the prefix says which figure is meant. What gates merges is the in-repo drift test asserting the three committed copies of each extraction (curriculum JSON → config JSON →SPECIALTY_PROCEDURE_CLASSIFICATIONS) cannot diverge.†‡ (#8490) - ✅
logbook.fhir.masterlist-rekey-provenance— the 10 specialty review lists are re-keyed to their own curriculum's index groups (principalProcedure) and syllabus hierarchy (broadArea/specificArea) via dual independent raters with consensus-only application: vocabulary is locked to the curriculum structure (hard-fail otherwise), every applied cell carries evidence, and every disagreement or low-confidence proposal is nulled/kept-existing and listed per specialty for Matt's expert verification — never silently decided.†‡ (#8511, #8518) - ✅
logbook.fhir.congenital-flat-classification— Cardiothoracic Surgery (Congenital) is a phase-3 sub-specialty curriculum that defines no Principal Procedures and no Critical Conditions of its own (indexProcedures: [],criticalConditions: []) — both are inherited from the parent Cardiothoracic Surgery curriculum (#6705), and its only quantitative requirement is the indicative 100 major cases. Its syllabus is single-level (34 broadArea topic groups, no sub-category tier), sospecificAreais intentionallynullon all 140 rows andprincipalProcedureisnullon all 140 rows. The classification is derived, never invented: an empty curriculum list yields an empty classification with an explicit parent-curriculum pointer, and the same derivation guards against the "critical condition tagged against every row" bug ever appearing in this seed. This resolves Matt's 2026-07-07 flag (the empty specific-category column is a remove, single broadArea grouping is sufficient); the WBA/target delivery layer is tracked in #9123.†‡ (#6704) - ✅
logbook.fhir.specific-area-not-broad-area-duplicate— aspecificAreathat merely restates its ownbroadArea(the same clinical fact in two columns, no distinct anatomical sub-division) is collapsed to broad-area-only (blankspecificArea). For Plastic & Reconstructive Surgery this cleared 52 rows across six broad-area-only groups (Non-Surgical rejuvenation, Chest wall reconstruction, Complex wound, Craniomaxillofacial trauma, Vascular Anomalies, Sarcoma) — each of which carried exactly one specific value identical to its broad area. Groups with a genuine anatomical sub-division are left intact (e.g. Breast surgery keeps its distinct "surgery of the breast" specific value). The reviewedplastic-surgery-review.csvis the authoritative source andplastic-surgery-db-ready.json(the DB-load artefact) is re-synced positionally from it, so the loaded classification matches the reviewed one. This resolves Matt's 2026-07-07 flag on this thread ("breast surgery is a broad and specific area currently … maybe we just have a broad area only for the ones that double [up]"); the remaining per-Matt items (8 non-surgical rejuvenation filing, 4 blank-placement themes) stay open for in-app review. Neurosurgery carried the identical double-up in itsCranial Traumagroup (4 rows whosespecificAreamerely restated the broad area, alongside 8 sibling Cranial Trauma rows already broad-area-only); #10365 collapsed those 4 to broad-area-only the same way, re-syncedneurosurgery-db-ready.jsonpositionally (0 drift), and widened both guards to cover neurosurgery — completing this AC across both specialties. BlankspecificAreais the established broad-area-only form (140/140 congenital rows, 350/405 general-surgery, 62/62 maxillofacial).†‡ (#6699) (#10365) - ✅
logbook.fhir.ncts-api-auth— NCTS business verification is confirmed (account set up, per NCTS email received 4 June — Matt/Rob, transcript 2026-07-14 §00:40:40).† NCTS API credentials are stored in Doppler (NCTS_CLIENT_ID/NCTS_CLIENT_SECRET,uat+prdconfigs) and the backend implements the OAuth2 client-credentials grant against the NCTS token endpoint, caching the access token in-memory until expiry. When NCTS credentials are configured,searchSnomedProcedures/snomedValidateCodeattach the Bearer token and target the authoritative NCTS FHIR base URL (https://api.healthterminologies.gov.au/integration/R4/fhir) instead of the public CSIRO Ontoserver; when absent, requests fall back to the existing unauthenticated public-Ontoserver behaviour so unconfigured environments (local dev, environments without the Doppler secret) are unaffected — no regression. A token-fetch failure fails closed (empty results), it never silently falls back to the unauthenticated path once credentials are present. This unblocks theon-holdre-key/re-validate slices #8876 and #8877.‡ (#7320) - ✅
logbook.fhir.snomed-edition-config— the SNOMED edition + ValueSet are resolved per-instance frominstance_config(not hardcoded), so the backend auto-matcher and the frontend live picker target the same edition. A known procedure therefore resolves to the same SNOMED CT code from the live picker and from the stored masterlist under the configured edition. Wheninstance_configis absent the backend service falls back to the historic UK edition, so non-AU / unconfigured environments are unaffected (no regression). This is Slice A of #7883 and is build-ready on the public CSIRO Ontoserver — it does not depend on NCTS authoritative validation (#7320, tracked separately as #8876/#8877).‡ (#8875) - ✅
logbook.fhir.procedure-valueset-config— the procedure pick-list value set is resolved per-instance from a singleinstance_config.procedure_value_setkey (not hardcoded), so the frontend live picker and the backend SNOMED matcher are driven by one jurisdiction switch. The key takes either an edition-implicit binding (isa/71388002, the default = descendants-or-self of71388002 |Procedure|, the historic full-subtree behaviour) or an absolute ValueSet canonical URL (the national AU Coreprocedure-1set), and it defaults toisa/71388002so no regression ships before the constrained binding is validated. A spike against the current public CSIRO Ontoserver confirmed the AU Coreprocedure-1value set already expands there (e.g. "appendicectomy" returns only in-set AU surgical concepts), so flipping an AU instance to the constrained set is a single config-row change. This is the config-not-code slice of #7883; the live NCTS binding stays gated on #7320 (out of scope here, tracked as #7885) and the RACS MALT refset remains banned until a formal agreement exists (#1740, cpd.md:236).‡ (#7884) - ✅
logbook.fhir.au-instance-config— the Australianinstance_configis provisioned so the AU deployment resolves SNOMED CT-AU end-to-end. With the AUinstance_configactive the resolved config reports SNOMED edition32506021000036107(not the UK999000031000000106default) and the constrained national AU Coreprocedure-1value set (not the UKisa/71388002default), plus AUD /en-AUlocale. The AU row is seeded by migration (drizzle/0180_au_instance_config.sql) instance-gated on a customapp.ppp_instance_countryGUC so it is a deliberate no-op on the UK database (and on local dev) — it can never giveinstance_configtwo rows and break the single-row resolver. The backend service carries anAU_DEFAULT_CONFIGfallback alongsideUK_DEFAULT_CONFIG, selected byPPP_INSTANCE_COUNTRY, so a fresh AU instance auto-creates AU defaults while UK behaviour is byte-for-byte unchanged. This is Wave 2 of #7883; pinning the AU edition version and the authoritative NCTS swap stay gated on #7885 / #7320.‡ (#9548) - ⏳
logbook.fhir.validate-code-gate— every external-procedure write is gated by FHIR$validate-codeagainst the configured procedure value set, checking both the code and the display, before the row is stored. The write is rejected when the code does not exist / is not in the value set, or when the supplied display does not match the concept's preferred/FSN term; a valid-but-inactive (retired) concept is not silently stored — it is flaggedstatus='needs_review'. The SNOMED edition + version the code was validated against are persisted alongside it (snomed_edition/snomed_version) so each entry is reproducible. Validation runs against the currently-configured Ontoserver / value set (public CSIRO by default) and fails closed (a code that cannot be validated is rejected). This is the NCTS-independent portion of #7885 (Slices 1 + 2): the authoritative AU NCTS Ontoserver swap and corpus re-validation stay gated on #7320 (Slice 3, tracked under #7885, out of scope here).‡ (#7885) - ✅
logbook.fhir.au-edition-end-to-end— under an active AUinstance_config(snomed_edition = http://snomed.info/sct/32506021000036107) the frontend live picker$expandURL and the backend SNOMED matcher ValueSet both target the same AU-edition value set.../32506021000036107?fhir_vs=<au value set>, sourced frominstance_configrather than the hardcoded UK/default edition. This is the Wave-2 end-to-end proof that joinslogbook.fhir.snomed-edition-config(#8875, edition) andlogbook.fhir.procedure-valueset-config(#7884, value set) into a single AU-deployment guard. Proven by a@smokeBDD scenario that captures the real picker$expandURL (stubbed fetch over the livesearchConceptspath) and drives the sharedresolveProcedureValueSetUrlmirror both call sites use; it runs in standard CI (no live backend) and depends on the AUinstance_configprovisioning (Wave-2 item).‡ (#9549) - ✅
logbook.fhir.masterlist-au-rekey— the seeded procedures masterlist (originally matched against the UK edition) is re-keyed against the AU edition (32506021000036107), Slice B of #7883, unblocked by #7320 (NCTS auth confirmed 2026-07-14). Every masterlist row carrying asnomedCtis re-resolved via the existing FHIR$validate-codegate (logbook.fhir.validate-code-gate, #7885): a code that resolves and is active is re-keyed (snomedCt/snomedDisplay/snomedEdition/snomedVersionupdated,snomedMatchStatus='confirmed'), so the live picker and the stored masterlist resolve the same code under the AU edition. A code that does not resolve — or resolves but is retired/inactive — is never silently kept or deleted: it is routed to the review queue (snomedMatchStatus='needs_review') with its prior code preserved for triage, feeding #7366. Distinct from the read-onlylogbook.fhir.snomed-au-resolutionde-risk pass (#9550), which never mutates the masterlist.†‡ (#8876) - ✅
logbook.fhir.masterlist-au-revalidate— the AU SNOMED CT edition is pinned to the authoritative release20250630(SNOMED CT-AU, 30 June 2025) end-to-end, Slice C of #7883, unblocked by #7320 (NCTS OAuth2 auth). Slices A/B resolved the edition frominstance_configand re-keyed the masterlist but left the AU edition unpinned (snomed_version = null), so the matcher / picker / re-key resolved against "latest" — a new AU edition release could silently move a code's resolution out from under the stored masterlist. Now the AUinstance_configrow (seed migration0209_au_snomed_version_pin.sql, GUC-gated so it never touches the UK row) and theAU_DEFAULT_CONFIGfallback both carrysnomed_version = '20250630', soresolveFhirRequestemitssystem-version = http://snomed.info/sct|<edition>/version/20250630and the masterlist re-key (rekeyProcedureMasterlistToAuEdition) re-validates against the pinned authoritative edition, not "latest". When NCTS credentials are configured the same$validate-codecall targets the authoritative NCTS FHIR server (logbook.fhir.ncts-api-auth, #7320); the version pin is server-independent, so the resolved edition is reproducible whichever terminology server answers. Deltas continue to reconcile through the review queue (snomedMatchStatus='needs_review', feeds #7366), unchanged from Slice B — never silent retention. This is the final Slice of #7883's authoritative-terminology arc.†‡ (#8877)
Access Control
- ✅ Backend rejects logbook tRPC calls from CPD-only users
- ✅ Only
accountAccess ∈ { ppp, cpdppp }callers reach logbook endpoints - ✅
logbook.case.patient-identifier-encryption-at-rest— the patient identifiers the logbook persists (activities.dob_patient,activities.urn,activities.gender,surgical_case.patient_urn) are stored encrypted at rest with AES-256-GCM authenticated encryption (random IV per value, auth tag stored with the ciphertext), so a raw DB row shows ciphertext, never the URN/DOB/gender — meeting UK GDPR Art 32 / Australian APP 11 for special-category health data. The encryption key is sourced from an env secret (Azure Key Vault), resolved lazily following thetoken-helper.tspattern (neverapi/backend-core's@ts-nocheck, unauthenticatedcrypter.ts). Because a random IV makes the ciphertext non-deterministic, equality lookups use a separate indexed blind index columnurn_hash— an HMAC-SHA256 of the normalised URN — so duplicate detection, surgical-case auto-link, and import dedupe keep working without a decrypt.surgical_case.reference(the surgical-case dedupe key: URN + surgery day + procedure) is a SEPARATE blind index, noturn_hashitself:blindIndexCompositeHMACs the whole composite, sharingurn_hash's secret. This column was found storing that composite in the clear (a plaintext sibling of the encryptedpatient_urnon the same row) and re-keyed ontoblindIndexCompositeby #11188; rows written before #11188 carried the legacy plaintext composite until #11202's backfill re-hashed them ontoblindIndexComposite(idempotent — a row already matching the new hash format is a no-op, mirroring the #10734backfillPatientIdentifierEncryptionre-plan-is-no-op contract). Plaintext is exposed only at the service boundary for authorised reads, and each decrypt is access-audit-logged (Art 32 access logging). A data migration back-fills existing rows (encrypt + populateurn_hash), proven by a.first-apply.validate.sqlsibling. Delivered as a decomposition (parent #10721 → enabler #10730 + stories #10731/#10732/#10733 + backfill #10734): the enabler (#10730) landed thepii-cryptoprimitive (encryptPii/decryptPii/blindIndex), theurn_hashcolumns, and thedob_patienttimestamp→text column-widening; the write (#10731), read (#10732) and equality (#10733) conversions followed. The backfill + cutover (#10734) close it: because AES/HMAC need the Key Vault secret and cannot run in SQL, the back-fill of existing rows runs as an app job (backfillPatientIdentifierEncryption,scripts/backfillPatientIdentifierEncryption.ts) — idempotent, encrypting every legacy identifier + populatingurn_hash— anchored by drizzle migration0216_encrypt_existing_patient_identifierswhose.first-apply.validate.sqlasserts the integrity invariant (a ciphertext URN always carries itsurn_hash). Once the secrets are provisioned and the back-fill has run, the transitional plaintext-tolerant read fallbacks are removed so reads are encrypted-only: with the gate on, a stray un-backfilled plaintext value fails loud, and URN equality/search key on the blind index alone. Cutover order: provision secrets → run backfill → deploy the encrypted-only read code.surgical_case.reference's own legacy-composite backfill (#11202) closes the gap #11188 left, using the same idempotent-re-plan pattern againstblindIndexComposite, proven by a sibling.first-apply.validate.sql(migration0232_backfill_surgical_case_reference).††‡ (#10721, #10730, #10734, #11202)
Super Admin — Level of Involvement reference
A read-only Super Admin reference screen surfacing the hardcoded Level of Involvement (LoI) constants (
packages-shared/ppp/src/constants/logbook/involvement.ts) so the product owner can read the full lists in-app and annotate the vernacular. Matt asked for the consultant and non-consultant lists "side by side" on the 2026-07-14 catch-up so he could confirm the labels and which levels count as supervising/teaching for CPD credit. This screen only displays the constants — it does not resolve the open consultant-vernacular question (Q-consultant-loi / #10076); the consultant table shows the current PPP-default placeholder behind an awaiting-confirmation banner.
✅
logbook.admin.level-of-involvement-reference— a read-only Super Admin screen at/admin/level-of-involvementrenders the non-consultant and consultant Level-of-Involvement lists side by side (stacked on mobile), each row showing the stored involvement code, the PPP display label, the Primary/Secondary operator axis, and a "counts as supervised" flag. The non-consultant list is the Matt-confirmed PPP vernacular (PPP_NON_CONSULTANT_LOI, #9187); the consultant list is the PPP-default placeholder (PPP_CONSULTANT_LOI) and its table carries a prominent "placeholder — awaiting confirmation" banner, because the authoritative consultant labels are still pending the logbook design spreadsheet (Open Question Q-consultant-loi, #10076). The legacy back-compat non-consultant code still dropped from the selectable list — Partial Procedure (PP) — appears in a distinct "legacy — display only" section. (Oncelogbook.entry.partial-procedure-recordships, PP moves to the selectable non-consultant list on the Secondary operator axis.) (Training another Trainee (TaT) was re-added as a live, selectable non-consultant option by #9200 (PR #10825, 2026-07-21) and moved out of this legacy section — see #12707 Change Log 2026-10-02.) Data is sourced entirely from the hardcoded constants: no DB table, no editing, no mutation controls (making the vernacular editable is a separate decision once Matt confirms it). The route isAdminRoute-gated (a non-super-admin is redirected to/— the screen surfaces no logbook data on the server, so there is no new tRPC procedure to gate).††‡ (Read-only surfacing only — the consultant vernacular stays governed by Open Question Q-consultant-loi (#10076); this screen displays the placeholder so Matt can annotate it, it does not confirm it. Cross-referenced fromsuper-admin.md(the console it lives in). Unblocks #10076 and decisions 1–2 of #9200. The consultant table gained an inline edit affordance in #10758 — seelogbook.admin.level-of-involvement-label-override; the non-consultant and legacy sections remain read-only.) (#10752)✅
logbook.admin.level-of-involvement-label-override— on the Super Admin LoI reference screen (/admin/level-of-involvement,logbook.admin.level-of-involvement-reference), each consultant row gains an inline edit affordance (edit icon → text field → save) so a super-admin can type a preferred display label for that consultant Level-of-Involvement code. A saved override persists and survives reload; a per-row "placeholder" chip is shown while a row carries no override and clears once one exists. Overrides are stored in a smallloi_label_overridestable (codetext PK = the stored involvement code string,labeltext,updated_at) — display wording only: the stored involvement codes (attributes.userLevelInvolvement/verifiedInvolvement), the classification arrays, the dashboard bucketing and every logged case row are untouched (this is not a data migration). Writes go through superAdmin-gatedsuperAdmin.loiLabelOverrides.list/upsertprocedures; the upsert validates thatcodeis one of the recognised consultant codes (CONSULTANT_USER_INVOLVEMENT_OPTIONS) and thatlabelis a non-empty, trimmed, length-capped string, so a non-consultant or unknown code can never be overridden. The consultant label helper (resolveConsultantLoiLabel) resolves override → else the PPP-default placeholder (PPP_CONSULTANT_LOI); overrides are exposed to the (non-super-admin) display layer via a protectedlogbook.consultantLoiLabelOverrides.listquery so any consultant-LoI label surface — the reference screen today, and the add-case dropdown / dashboard widget once those are wired toPPP_CONSULTANT_LOI— resolves the same override. Non-consultant labels stay constant-only (already Matt-confirmed, #9187) and the legacy (PP/TaT) section stays read-only. The override mechanism is how Matt supplies the answer to Q-consultant-loi (#10076): the wording itself remains his decision, so #10076 stays open until he enters it in-app.††‡ (Editing surfaces only the DISPLAY label — the consultant vernacular decision stays governed by Q-consultant-loi (#10076); this screen now lets Matt enter it directly. Builds onlogbook.admin.level-of-involvement-reference(#10752) and the Form Prompts overridable-strings precedent (#2283). Supports decisions 1–2 of #9200.) (#10758)✅
logbook.entry.consultant-loi-doctor-facing-wiring— the override-awareresolveConsultantLoiLabelresolver is wired into every doctor-facing surface that renders a consultant Level-of-Involvement label, not only the admin reference screen: the add-case consultant LoI dropdown, the consultant review screen's own-involvement field and the non-consultant reviewer section's read-only display of the consultant's involvement, the logbook case table's "Level of Involvement" column, the logbook case card's role-badge tooltip and its list-view row equivalent, and the CSV export. A newresolveLoiDisplayLabeldispatcher (routes a consultant code throughresolveConsultantLoiLabel; every other code keeps the existinginvolvementDisplayLabelbucket vernacular, #8473) covers the surfaces that render whichever code happens to be on the record without knowing in advance whether it is a consultant or non-consultant code. Every surface reads the override table through the same doctor-facinglogbook.consultantLoiLabelOverridesquery #10758 shipped for exactly this purpose (via a newuseConsultantLoiOverrideshook), so a super-admin override entered on/admin/level-of-involvementshows up everywhere a doctor sees a consultant LoI within one refetch — never only on the admin screen. While the overrides query is loading or returns none, every surface falls back to the PPP-default placeholder (PPP_CONSULTANT_LOI) — never a blank label. Stored involvement codes are untouched; this is display wording only. This is also how #10076 (Q-consultant-loi) closes as an engineering item: the wording remains Matt's to refine at any time via the in-app editor, but the mechanism delivering that wording to doctors is complete.†‡ (Display wording only — stored involvement codes and logged case data are untouched. Builds onlogbook.admin.level-of-involvement-label-override(#10758), which shipped the override table and the doctor-facing read query ahead of this wiring. Closes the engineering-mechanism side of Q-consultant-loi (#10076); the exact wording stays Matt's open call.) (#10076)
Audit Events — complication grade
The Audit feature (Audit Events) records case outcomes/complications separately from the logbook case itself. Item 1 of the #9189 RACS MALT deep-review (structured complications + severity grade) is built here as an audit-tool-only optional field. Explicitly not RACS MALT alignment and not tied to CPD Home or HLSR — Matt on #9189 (2026-07-08): "We have complications in our Audit feature list; we can add it clavien dindo classification system as an option for the user to enter."
- ✅
logbook.audit-event.complication-grade— an Audit Event exposes an optional Clavien-Dindo severity grade for a complication, sourced from the fixed 7-grade ordinal scale (I / II / IIIa / IIIb / IVa / IVb / V) and persisted in the activityattributesJSONB ascomplicationGrade(no migration). The field is optional (a complication may be recorded ungraded) and is decoupled from CPD Home / HLSR — it carries no RACS MALT alignment or licence (dropped on #9189 / #1740).†‡ (#9189)
Core Entry
- ✅ Fields persist when returning to a saved entry — including treatment acuity and principal procedure fields†
- ✅
logbook.entry.imported-unmatched-procedure-surfaced— an imported case whose procedure did not match a master-list procedure (stored with noprocedureId) surfaces its captured best-guess procedure detail (importNotes.procedureMatch.*Name, falling back to the captured operation description for Principal Procedure) into the read-only Principal Procedure / Treatment Acuity / Broad Area / Specific Area fields instead of leaving them blank, and shows an inline prompt guiding the surgeon to select a matching surgery to confirm and complete the case. Previously these required fields were blank for unmatched imports, so the case failed required-field validation and could not be saved from the app.†‡ (#8649) - ✅
logbook.entry.matched-procedure-detail-survives-edit— re-opening a saved logbook case matched to a master-list procedure and switching it into edit mode keeps its read-only Principal Procedure / Treatment Acuity / Broad Area / Specific Area detail populated, so the case still saves. The Consultant form's bareform.reset()on entering edit mode resetsprocedureRefFieldto its empty-string defaults, and the surgeriesList-based restore only re-derived the fields when the matched procedure was present in the specialty-scoped picker — so a case whose procedure sits in another specialty (or whose picker had not loaded) re-blanked its four required fields and failed to upload. The fields are now re-derived directly from the hydratedprocedurerelation on the record, independent of the picker list.†‡ (#8649) - ✅
logbook.entry.sticky-save-mobile— on a phone, the logbook case form's Save / Submit action bar stays pinned and reachable above the on-screen keyboard while editing the last fields, so a surgeon can always submit a case from a mobile device. The case Add/Edit and Review dialogs open withscroll="paper"(bounded scroll container) and the form'sFormActionsSectionaction row is sticky. Implements the shareddesign-system.form-actions.sticky-mobilebehaviour for the logbook — this was the worst-case form, where the Save control previously scrolled away / sat behind the keyboard.†‡ (#9324) - ✅ Visual distinction between own and received cases in list
- ✅ Default list filter = user's own cases
- ✅
logbook.entry.involvement-code-enum— the persisted level-of-involvement code (attributes.userLevelInvolvement/verifiedInvolvement) is constrained to the recognised PPP involvement-code set (the consultant + non-consultant user options) via a shared zod enum (involvementCodeSchema) and anactivitiescreate-path write guard, so a new case can no longer be created with an unrecognised value (it was previously a loosez.string()). Enforcement lives only on the create/insert input — not on the shared read schema and not on the update path — so legacy records carrying historical involvement values are never rejected on read, nor when an assessor verifies or a doctor edits a pre-existing case (both re-send the stored value verbatim).conConsultantInvolvement(which round-trips legacy/vernacular values verbatim, #8473) is left unconstrained for the same reason. This is the PPP-derived involvement set, not the RACS MALT code set — full MALT alignment is licence-gated (#1740) and deferred (see Open Question Q-malt-alignment).†‡ (#9189) - ✅
logbook.entry.add-retrospective-dropdown— the "Add retrospective" button on a logbook case entry presents an inline dropdown of the retrospective options (Reflection / WBA / Feedback) directly from the button, without navigating to an intermediate screen.† (Implemented options are the linkable case-entry retrospective forms — Reflection, WBA, Feedback; the transcript paraphrase said "audit event" but WBA is the case-entry equivalent — see Change Log 2026-05-19.) (#6392) — SUPERSEDED 2026-06-03 bylogbook.entry.retrospective-options-inline(#8191): Matt's 2026-06-03 review reversed the March decision, asking for the options to be visible inline on the form rather than hidden behind a button. See Open Question Q-retrospective-control and Change Log 2026-06-03. - ✅
logbook.entry.retrospective-options-inline— the case-entry retrospective options (Reflection / WBA / Feedback for a trainee case; Reflection only for a consultant's own case) are shown as visible inline multi-select tick-boxes on the logbook case form, not hidden behind an "Add retrospective" button; an option already linked to the case is omitted so it cannot be added twice.†‡ (Reverseslogbook.entry.add-retrospective-dropdown(#6392), restoring the pre-#6392 inline checkbox control that writes the samecompleteReflection/completeWBA/completeFeedbackform fields. The 2026-06-03 transcript said "radio"; built as multi-select tick-boxes to preserve linking more than one retrospective per case (#7460). Built per Rob (acting PO); Matt to confirm the March→June reversal — see Open Question Q-retrospective-control.) (#8191) - ✅
logbook.entry.involvement-vernacular— Consultant Level of Involvement option labels lead with the widget's Primary/Secondary × Independent/Supervised buckets; stored involvement codes unchanged.†‡ (Display labels only — the stored value stays the original code string keyed by the widget bucketing, chart palette and UK eLOGBOOK import mapping (#8099); legacy/unknown stored values display verbatim.) (#8473) — SUPERSEDED for NON-CONSULTANTS 2026-06-29 bylogbook.entry.ppp-involvement-vernacular(#9187): Rob confirmed off the 2026-06-24 call that PPP bridges from the UK system (not RACS), so the non-consultant list uses PPP's OWN plain-language vernacular. — SUPERSEDED for CONSULTANTS 2026-07-22 bylogbook.entry.consultant-loi-doctor-facing-wiring(#10076): the add-case consultant dropdown (and every other consultant-LoI display surface) now resolves each label viaresolveConsultantLoiLabel(super-admin override, #10758 → else the PPP-default placeholder,PPP_CONSULTANT_LOI) instead of the Primary/Secondary × Independent/Supervised bucket vernacular this AC originally specified for consultants. The bucket vernacular remains live for every OTHER (non-consultant/legacy) code viainvolvementDisplayLabel/resolveLoiDisplayLabel. - ✅
logbook.entry.ppp-involvement-vernacular— the non-consultant Add Case "Level of Involvement" dropdown uses PPP's OWN vernacular — exactly Observed, Assisting, Trainer (unscrubbed), Trainer (scrubbed), Primary — led by a distinct Primary vs Secondary operator axis (NOT the RACS supervised/independent matrix). The Primary/Secondary operator flag is the cross-network common denominator that drives the surgical cadence meter and the surgical goals (total operations + primary operations); granular LoI is the deep-dive layer, and for imported/unverified cases (where granular LoI may be missing) primary-vs-secondary is still derivable. The stored value stays the original involvement code string so the dashboard bucketing, chart palette, short role chip and UK eLOGBOOK import mapping (#8099) are untouched. The legacy "Partial Procedure" (PP) code is dropped from the selectable non-consultant list to match Matt's confirmed vernacular; cases already stored against it still display via the back-compat label path. (PP dropout superseded 2026-08-02: Matt chose to bring PP back as a recorded-for-skill option. Seelogbook.entry.partial-procedure-record.)†‡ (Non-consultant only — the consultant LoI labels are pending the logbook design spreadsheet, see Open Question Q-consultant-loi, and stay on their existing labels for now. Case-card chip/tooltip and CSV export still render the back-compat label path; aligning those to PPP's own vernacular is a follow-up.) (#9187) — REVISED 2026-07-21 by #9200 (PR #10825): "Training another Trainee" (TaT) is RE-ADDED as a selectable Primary-operator option — it is the sole non-consultant LoI that earns supervising/teaching CPD credit for the logging doctor (Matt, #9200: "TaT needs to be added back"). Only PP stays dropped/legacy. See Change Log 2026-10-02. - ⚠️
logbook.entry.partial-procedure-record— a non-consultant can log a case as Partial Procedure (PP) when they did only part of the operation, and say which part they did in a free-text box ("Which part did you perform?"). A PP case is kept for skill experience. It never counts as a primary operation (it sits on the Secondary operator axis) but it does count toward total operations. This is option 2 from #10822, which Matt chose as the testing version. A later version will let the surgeon pick the part from a list of standard stages instead (option 3, on hold until after launch, #12744). Supersession: 2026-06-24 five-option vernacular dropped PP (#9187) → 2026-07-21 PP on hold pending the early user test (#9200) → 2026-08-02 go with option 2, count toward total, go forward (#10822).† Drift: not built. PP is still left out of the selectable list (packages-shared/ppp/src/constants/logbook/involvement.ts) and there is no "which part" field. Tracked on #10822. (#10822, #11186) - ✅
logbook.entry.specialty-scoped-surgery-picker— the Add Case surgery picker defaults to the user's OWN specialty masterlist; the "Other Specialties" toggle widens it to the full master list (internal and user-added external procedures); External Lookup (SHRIMP/SNOMED CT) stays as the third tier. A surgical-variant user with no specialty — or a specialty with no procedures — gets the full master list, never an empty picker; favourites-first ordering applies to whichever list is shown. (For a procedural-variant user with no matching procedures the full-list fallback is suppressed — seelogbook.entry.procedural-no-dataset-external-only(#8815).) Ticking "Other Specialties" widens the picker to the full master list for a procedural-variant user too — it is not the "no specialty" case and must not fall back to the practical default list (#12793).†‡ (#8190) - ✅
logbook.entry.procedural-no-dataset-external-only— interim guard while the physician (Practical) procedure dataset is pending. The "Practical Logbook" label ships for non-surgeon doctors (logbookVariant === 'procedural', derived from job title inderiveLogbookVariant), but no physician procedure dataset exists yet — only the 10 surgical lists. For a procedural-variant user whose specialty resolves to NO matching procedures (no specialty, or a specialty with no procedures), the Add Case surgery picker does NOT fall back to the full all-surgical master list — that would show a physician surgical procedures (heart transplant etc.) that are wrong for them. Instead the form presents External Lookup only with a short, friendly empty-state ("Your procedure list is coming soon — search for a procedure below to add it") and defaults the doctor to the External Lookup search, so they reach SNOMED/external search rather than surgical procedures. Surgeons, and procedural-variant users WHOSE specialty does resolve to procedures, are unchanged. NARROWED 2026-07-16 bylogbook.variant.practical-dataset(#8815): now that the physician IMT dataset is seeded and surfaced viaprocedure.listPracticalDefault, a procedural user with an empty scoped list is served the IMT practical list — this External-Lookup-only empty-state fires ONLY when the practical default is ALSO empty (i.e. the seed has not been applied to the environment). It remains the correct safety floor; it is no longer the primary path for physicians.†‡ (#8815) - ✅
logbook.variant.practical-dataset— the physician (Practical / Procedural Logbook) procedure master list is seeded so alogbookVariant === 'procedural'user gets a real, relevant procedure list instead of the #8890 External-Lookup-only empty-state. Data source: the UK Internal Medicine Training (IMT) practical procedures list (JRCPTB / Federation of Royal Colleges of Physicians) — chosen over RACP because RACP's 2026 curricula are EPA/competency-based and do not publish a flat, enumerable procedure list (Rob's decision, 2026-07-16). Structure — two IMT curriculum tiers plus a logbook extension set (~17 procedures), carried on thebroadAreacolumn exactly as the surgical lists carry their curriculum hierarchy:Independent by end of IMT(advanced CPR incl. external pacing; ascitic tap; diagnostic lumbar puncture; NG tube placement & confirmation; pleural aspiration; intercostal drain for pneumothorax),Experience of(US-guided central venous cannulation; DC cardioversion; Seldinger intercostal drain), andLogbook extension(portable echo; ascitic drain; joint aspiration; joint injection; ABG/arterial access; urinary catheterisation; Argyll/pigtail pleural drain; pleural decompression). Professions/job-titles: any non-surgeon doctor whose job title yields the procedural variant (e.g.Physician;deriveLogbookVariantreturnsproceduralwhen the title contains neither "surgeon" nor "surgical"). Via the runtime surfacing below they receive the list whether or not their own profile speciality resolves to procedures — they do NOT need to select the General Internal Medicine speciality themselves. Seeding mechanism (identical to the surgical lists, #8468): the source-of-record isapi/backend-ppp/scripts/seed-data/specialty-procedures/internal-medicine-imt-db-ready.json, aggregated intoscripts/seed-data/procedures.json(the fileseedSettingsData.tsloads) andscripts/seed-data/lookups.json(adds theGeneral Internal Medicinespeciality and the three tierbroadArearows);seedReferenceData.ts→seedSettingsData.tsseeds it idempotently to UAT on deploy (prod does not seed — seecd.yml). Runtime surfacing: because physicians select from broad "Specialist" buckets or set no specialty at all, keying to a single speciality is not enough on its own —procedure.listBySpeciality(userSpecialtyId)would still resolve to nothing for most of them. So a dedicatedprocedure.listPracticalDefaultquery returns the General Internal Medicine list (resolved BY NAME server-side, never a hard-coded id), and the surgery-picker data hook (useLogbookFormData) serves it to ANY procedural user whose own scoped list is empty (no specialty, or a specialty with no procedures) — instead of the all-surgical fallback or the empty-state. The #8890 empty-state now fires only when the practical default is itself empty (seed not applied). Surgeons are unchanged. Procedure names are recorded as facts attributed to JRCPTB/Federation; the canonical curriculum PDF is to be pulled by product/legal before any store-front claim. This is the interim default — Matt may redirect to a different physician source and the same mechanism re-keys.†‡ (#8815) (Resolves Open Question Q9; supersedes the interimlogbook.entry.procedural-no-dataset-external-onlyempty-state for any procedural user with an empty scoped list once the IMT dataset is seeded; the empty-state remains only as the seed-not-applied safety floor.) - ✅
logbook.entry.surgery-picker-redis-cache— the specialty-scoped procedure query is Redis-cached per scope (ppp:settings:procedures:bySpeciality:<id|all>, settings TTL) so opening the Add Case form does not freeze loading values; every procedure write path (create/update/delete/external-create) invalidates the full-list key and all per-specialty keys.†‡ (#8190) - ✅
logbook.entry.hospital-pre-list— opening the Add Case Hospital dropdown without typing pre-lists the doctor's hospitals (attached hospitals pinned first); live registry search still takes over at 2+ typed characters, and the pre-filled selected hospital's label never acts as a filter. A hospital picked from the search results stays shown in the field after it loses focus (#12797).†‡ (#8480) - ✅
logbook.entry.hospital-sticky-default— the Add Case Hospital field defaults to the hospital the doctor last saved a case with (per-user, device-local preference), falling back to the first assigned hospital (#8339) when none is stored.†‡ (#8480) - ✅
logbook.entry.sticky-action-bar— on a long logbook-case form the action row (Edit / Save / Discard) is pinned to the bottom of the form's scroll container so the controls stay reachable without scrolling to find them; short forms keep the inline action row. The sharedFormLayout.Actionsrow gained an opt-instickyprop, and the logbookFormActionsSectionopts in for both consultant and non-consultant case forms.†‡ (#8787) - ✅
logbook.entry.responsible-consultant-clinical-supervisor-default— when the Add Case form opens for a NEW case, the Responsible Consultant field defaults to the doctor's own Clinical Supervisor. If the doctor has more than one Clinical Supervisor, the first is used as the default and all sort to the top of the selectable list (seelogbook.entry.responsible-consultant-list-order). A doctor with no Clinical Supervisor gets no default (empty field), never an error. Editing an existing case never overrides its stored consultant (the default runs in Add mode only, and only whenassessorIdis unset).†‡ (#8171) - ✅
logbook.entry.responsible-consultant-sticky-default— within a login session the Responsible Consultant field defaults to the last-entered consultant (the one saved on the doctor's previous case this session), taking priority over the Clinical-Supervisor default; the remembered value is cleared on logout (session-scopedsessionStorage, not device-locallocalStoragelike the hospital sticky default). Mirrors thelogbook.entry.hospital-sticky-defaultpattern but session-scoped per Matt's "until log out".†‡ (#8171) - ✅
logbook.entry.responsible-consultant-list-order— the Responsible Consultant dropdown orders options: the doctor's Clinical Supervisor(s) first, then favourites (star-pinned), then the remaining consultants alphabetically. This REVISES the earlier favourites-first ordering (closed Q3) per Matt's #8171 refinement placing Clinical Supervisors above favourites. Full profile search remains available. Favourites keep their star-toggle (unchanged fromuseConsultantFavourites).†‡ (#8171) - ✅
logbook.entry.responsible-consultant-smart-list— the Responsible Consultant query supports an optional "smart list" scoping to consultants at a given hospital and/or department/speciality.getConsultantUsers(GetConsultantUsersOptions) now acceptshospitalId(filters via theuser_assigned_hospitalsjunction) andspecialityId(filters onusers.speciality_id); both are optional and independent (either, both, or neither), composing with the existingsearch/limit/excludeUserIdpredicates. Theusers.getConsultantUserstRPC procedure exposes both as optional inputs. The backend query is delivered here (#10373, deferred from #8171-C per Matt's #8171 priority); the picker's tiered surfacing (smart-list tier below Clinical-Supervisor + favourites) rides on this query.†‡ (#8171, #10373) - ✅
logbook.entry.satisfaction-primary-operator-only— the "How Satisfied were you with your performance?" rating is shown on the Add/Edit case form only when the selected Level of Involvement is a primary-operator value (consultant PA/PCC/PPT; non-consultant P), and a previously-entered satisfaction value is cleared when the user changes involvement away from primary (an already-non-primary case is not altered on open).†‡ (Reuses the sharedisPrimaryOperatorInvolvement()helper — the same primary-operator gate the consultant review screen uses for competency scoring. Strict reading per the 2026-06-10 deep-dive (Option 1); whether supervised-trainee involvement should also self-rate is an open question with Matt — see Change Log 2026-06-10.) (#8542) - ✅
logbook.entry.satisfaction-scale— the "How Satisfied were you with your performance?" rating is captured on a 1-5 scale (optional; the surgeon may skip it), per the closed Q5 decision; the score is stored as an insight feeding the PPP Pulse surgeon-load signal. The control originally shipped as a 1-10 scale, contradicting the recorded decision; #8598 reconciles the control to 1-5 across both Add/Edit case form variants and the consultant review screen. The literal star-glyph rendering noted in Q5 ("star-rating input") is a presentation detail still open — the established control is the shared numberedRatingScale, and only the 1-5 range is corrected here.†‡ (#8598) - ✅
logbook.entry.server-side-validation—validateLogbookEntryutility exists (validates URN, date, procedure, non-negative operative time/job duration) but is not called inside thecreatemutation — the server currently accepts entries without enforcing required fields at the tRPC layer (#4880) - ✅ Min/max validation on numeric fields e.g. operative time (#4884)
- ✅ Metrics refresh reactively after case create without reload —
invalidateLogbookWidgetQueriescovers all 7 SPO widget queries;logbook.getStatshas no frontend consumers - ✅
logbook.entry.incomplete-todo-guidance— an incomplete (draft) logbook case surfaces in Action Items with guidance naming the clinical detail fields still to complete (acuity, role, patient category, operative time), or a "finish and submit" prompt when all are present — not a bare "Surgical Logbook" type row.†‡ (#8100) - ✅
logbook.entry.todo-deep-link-complete— opening a draft case from its Action Items to-do opens it ready to complete (editable) rather than read-only, so an imported case can be finished in one step.†‡ (#8100) - ✅
logbook.entry.todo-grouped-stepped-flow— similar draft logbook to-dos collapse into ONE Action Items row ("Complete N Surgical Logbook drafts", surfacing the first case's completion guidance) that starts a stepped flow: the first case opens ready to complete, each save rolls to the next automatically, each item is individually skippable, and the row shows progress ("x of n done").†‡ (#8101) — REVISED 2026-08-04 (seelogbook.entry.todo-group-individual-oversight): Matt kept grouping but said the single tile gives "no oversight" to pick a specific case. The stepped flow stays as the bulk path. - ✅
logbook.entry.todo-group-individual-oversight— a grouped logbook-draft to-do can be expanded (a drop-down under its topic) to show each draft case individually. From there the surgeon can open any one draft directly, or delete a draft created in error, as well as using the stepped flow.†† Built (#12724):GroupedTodoItemCardhas a "Show N cases" toggle listing each draft by its operation text and case date, with Open (opens that case ready to complete) and Delete (after a confirm; draft logbook cases only) per row; clicking the row itself still starts the stepped flow. (#11183) - ✅
logbook.entry.todo-group-title-distinguishes-status— a grouped to-do row's title names the status its members share, so two groups of the SAME record type that differ only by status (e.g.timesheet:draftandtimesheet:complete) never render as two visually identical cards, and a group of completed records is not labelled "drafts". Grouping already keys ontype:wbaType:status; the title previously used only the type.†‡ (#11217) - ✅
logbook.entry.todo-count-vs-bell— the notification-bell count and the Action Items count are deliberately distinct: the bell groups similar events while Action Items lists (or groups) all outstanding work — no forced alignment.† (#8101) - ✅
logbook.case.draft-persisted— an in-progress NEW case entry's non-identifiable form structure is preserved if the app is backgrounded or the WebView is evicted mid-entry (a surgeon answering a call), and is restored on reopen; it is cleared once the case is successfully submitted and on an explicit discard/close. The form keeps all entry state in memory, and the unsaved-changes guard only fires on an explicit close, so a backgrounding tear-down silently lost the whole form. A reusableuseFormDrafthook debounce-persists the dirty form to per-user, per-form device-local storage off the existingformState.isDirty, restores it on remount, and clears it on submit; the logbook case form (consultant and non-consultant Add mode) is the first adopter, with CPD activity / WBA able to adopt the same primitive later. PII — primary compliance control: patient name and DOB are confirmed special-category data and must NOT sit in plain device storage, so the on-device draft is an allowlist (#9798, hardening the original #9328 denylist): it persists ONLY known-safe structural keys (procedure, area, hospital, ASA, involvement, patient category, satisfaction, operative time, date, ids/foreign keys) and drops everything else by default — including any field added to the form later, which is excluded automatically rather than leaked until someone remembers to denylist it. On restore the excluded fields are empty and the surgeon re-enters patient identity. Defence-in-depth: the draft is also cleared on explicit discard/close (a background eviction never callsonClose, so an interrupted entry is preserved while a deliberately-abandoned one drops at once) and self-expires via a 24h TTL (a draft older than the TTL is treated as absent and purged on read). (The #9371 DPO decisions are now made (Rob, 2026-07-16): the DPIA + RoPA + Art 9(2)(h) lawful basis for storing identifiable patient clinical data is documented indocs/site/compliance/compliance-assessment.md§8–§9 (#10722); encryption-at-rest for the persisted identifiers (AES-256-GCM + URN blind index) is approved and tracked as #10721; and the fuller encrypted server-side draft — full recovery including patient identity — is approved and tracked as #10723. The no-PII-on-device default lands now.)††‡ (#9328, #9798) - ✅
logbook.case.draft-persisted-encrypted-server-side— the source of truth for the in-progress case draft is now an encrypted server-side draft holding the FULL form incl. patient identity (URN + DOB), so crash-recovery is complete and no patient PII sits on the device at all — the gold-standard option Rob approved in the #9371 DPO decision (item 4, "yes full encrypted server side", Rob 2026-07-16). One in-progress draft per user per logbook form (logbook_case_drafts, unique on(user_id, form_key)); the whole draft body is JSON-serialised by the client and stored as one AES-256-GCM ciphertext blob (payload_ciphertext) using the samepii-cryptoprimitive as the encryption-at-rest work (#10730/#10721) — a raw DB row shows only ciphertext. tRPClogbook.upsertCaseDraft/getCaseDraft/clearCaseDraftare owner-scoped from the caller's identity ONLY (no client-supplieduserId;getSelfUserId(ctx)), so a user can only ever reach their own draft — a cross-user fetch is refused withFORBIDDEN(403). The draft self-expires via a 30-day TTL (expires_at, refreshed on every upsert; read-time expiry is the shipped enforcement — an expired row reads as absent — with a physical sweep tracked as a follow-up in #10749), and is cleared eagerly on submit and explicit discard. Availability gate: because this store persists ciphertext only, it cannot pass through in plaintext like the encryption-at-rest stories (#10731/#10732) do before cutover — so until thepii-cryptosecrets are provisioned the procedures no-op cleanly (upsertCaseDraft→{ persisted: false },getCaseDraft→null) and the client falls back to the sanitised on-device draft rather than 500-ing on every form open. On reopen the full form incl. patient identity is restored from the server — no re-entry. The on-device allowlist draft (logbook.case.draft-persisted) is retained only as an offline fallback: it still persists just the non-identifiable structure, so a fully offline surgeon recovers the bulk of the form and no patient identity is ever written to device storage; when online the server's full draft takes precedence on restore.†‡ (#10723)
Multi-feedback
- ✅
logbook.multi-feedback.per-operation— multiple consultants can add separate feedback entries against a single operation/surgical_case; each is a distinctfeedbackactivity linked viarelated_forms, keyed by a per-author trackingId so a second consultant's feedback no longer overwrites the first (#7505) - ✅
logbook.multi-feedback.independent-retrospective-visibility— each feedback entry is a separaterelated_formschild, so every consultant's feedback is independently visible in the Retrospective Feedback tab (rendering owned by #7307) (#7505)
Index Procedures
- ✅
logbook.index-procedures.user-target-volumes— users can define target volumes per principal/index procedure in their plan (e.g. 20× Major Joint Arthroplasty); targets persist in thecadenceTrackerJSONB underindexProcedureTarget:{principalProcedureId}keys and are settable via thedashboardLogbook.setIndexProcedureTargetmutation.† (#7504) - ✅
logbook.index-procedures.dashboard-progress— the Principal Procedures widget shows progress toward each index-procedure target; counting is at theprincipal_procedurelevel (a knee/hip/shoulder arthroplasty all increment Major Joint Arthroplasty) and derives from theprocedures.principal_procedure_idFK rather than denormalised text.† (#7504) - ✅
logbook.entry.user-case-targets— users can set their own personalised targets for total cases and primary surgeon cases within their profile; these targets are used to drive progress display on the logbook dashboard.† - ✅
logbook.entry.training-total-target— the case target the doctor enters is the whole-of-training total (total cases and primary-surgeon cases), not a per-year figure; PPP derives the per-year and per-3-month pace by dividing the remaining total across the time to the doctor's expected completion (CCT) date. This refines the meaning of the figures stored incadenceTracker.totalCasesTarget/cadenceTracker.primarySurgeonTarget(whichgetThreeMonthGoalpreviously treated as an annual target divided by 4). Default reference totals are PROPOSED, gated on Matt — see onboarding.md Open Question Q5. The CCT-date capture and years-remaining divisor shipped in #8045; #8042 re-defined the stored target as a whole-of-training total and re-pacedgetThreeMonthGoalto remaining ÷ years-to-CCT ÷ 4 (a null goal, not a negative/Infinity one, when there is no usable CCT date), and added a one-time prompt for existing users to re-confirm their stored total.†† (#7344, #8045, #8042;code:api/backend-ppp/src/services/dashboardService/logbook/threeMonthGoalPace.tsderiveQuarterlyPace,code:api/backend-ppp/src/services/dashboardService/logbook/threeMonthGoal.ts,code:api/backend-ppp/src/services/cadenceTargetService/index.ts) - ✅
logbook.training-totals.curriculum-default— a per-specialty default whole-of-training case total prefills the profile cadence target from the ISCP/JCST curriculum structures (#8490, theoverallIndicativeOperations.totalfield), so an in-training surgeon gets a sensible goal (and therefore the #8195 pace monitor) without researching their own curriculum number. The prefill is clearly marked as a curriculum default and is user-overridable; the storedcadenceTracker.totalCasesTargetstays the single source of truth (prefill, not a hidden fallback), so the #8195 "coaching only when a target is set" rule stays meaningful. Every number traces to a curriculum JSON field — engineering never invents a figure — so a specialty whose curriculum states no overall total (General Surgery, Maxillofacial, Urology, Vascular — alltotal: null) gracefully has no default rather than a made-up one. The cadence helper text names the source (e.g. "JCST Neurosurgery indicative operations").† (#8552, #8490;code:packages-shared/ppp/src/curriculum/curriculumTrainingDefaults.tsgetCurriculumTrainingDefault,code:api/backend-ppp/src/services/settingsServices/speciality.tsgetAllSpecialities,code:instances/ppp/src/modules/MyProfile/UserForm/sections/SurgicalCadenceSection.tsx) - ✅
logbook.training-totals.critical-conditions-wba— each surgical specialty surfaces, in the trainee logbook dashboard, (1) the critical conditions required as WBAs and (2) the numbers required for completion of training (index-procedure indicative case numbers), both sourced verbatim from the ISCP/JCST curriculum documents (#8468/#8490curriculum-structures/<slug>.curriculum.jsoncriticalConditions/indexProcedures, machine-verified byverify-extractions.py) — not hand-entered by Matt. The critical-conditions list is backfilled into the existing (previously empty-seeded)speciality.criticalConditionscolumn, lighting up the already-built WBA critical-conditions widget (per-condition WBA counts + the level-4 target); the index-procedure completion numbers are surfaced read-only in a "Numbers Required for Completion" dashboard widget alongside the user-defined index-procedure targets (#7504), each with a curriculum source citation. Every condition and number traces to a curriculum JSON field — engineering never invents a figure — so the 9 curricula that carry this data are populated (Paediatric 94 conditions / 37 index procedures down to Vascular 3 / 11) and Cardiothoracic Surgery (Congenital) lists none (it defines no critical conditions or index procedures of its own, inheriting the parent Cardiothoracic curriculum, #6704). Originally filed as Matt-gated clinical data; Rob decided (2026-07-11) to build directly from the already-sourced, cited official curriculum data rather than wait for Matt to retype numbers that are already extracted and verified — the clinical authority (the curriculum documents Matt provided under #8468) is unchanged.†† (#9123, #8490, #8468;code:packages-shared/ppp/src/curriculum/specialtyCriticalConditions.tsgetSpecialtyCurriculumRequirements/getSpecialtyCriticalConditions,code:packages-shared/ppp/drizzle/0196_speciality_critical_conditions_backfill.sql,code:api/backend-ppp/src/services/admin-and-org/settingsServices/speciality.tsgetSpecialityById,code:instances/ppp/src/components/widgets/SurgicalLogbookWidgets/CurriculumTargetsWidget.tsx,code:instances/ppp/src/components/widgets/WBAWidgets/CriticalConditionsWidget.tsx) - ✅
logbook.training-totals.principal-procedure-classification— answers Matt's 2026-06-28 review-thread follow-up in full, per specialty: (1) the Principal Procedures (curriculum index procedures) with their level-4 PBA sign-off rule (an explicit count where the curriculum states one, e.g. Urology — an indicative 9 PBAs; a level requirement with no fixed count where it does not, e.g. Cardiothoracic Surgery — "no requirement for a certain number of PBAs"), and (2) the Critical Conditions requiring a WBA for level-4 sign-off, with the curriculum's own certification wording (criticalConditionCertification/indexProcedureCertification, verbatim).SPECIALTY_PROCEDURE_CLASSIFICATIONS(previously registering only the intentionally-empty Cardiothoracic Surgery (Congenital) entry from #6704) now registers every speciality whose curriculum is extracted in this repo, each traced to its curriculum-structure JSON by the existingderiveSpecialtyProcedureClassification— no new data shape, no invented figure. Fixed two latent parsing bugs inparseRequiredLevel4PbaCountthat would have reported a fabricated count: reading the "4" in "level 4 PBA" (a competency level) as a required count of 4 (Plastic Surgery), and reading Vascular Surgery's "10 PBAs" total as the level-4-specific count when the curriculum states only "four" of the ten must be at level 4. Orthopaedic Surgery was the sole seeded surgical speciality absent from the registry at the time; that extraction gap is now closed — seelogbook.training-totals.orthopaedic-curriculumbelow.† (#9123, #10945, #8490, #6704;code:packages-shared/ppp/src/curriculum/specialtyProcedureClassification.tsderiveSpecialtyProcedureClassification/parseRequiredLevel4PbaCount/SPECIALTY_PROCEDURE_CLASSIFICATIONS,code:packages-shared/ppp/src/curriculum/specialtyCriticalConditions.tsgetSpecialtyCriticalConditionCertification/getSpecialtyIndexProcedureCertification,code:packages-shared/ppp/src/curriculum/specialty-critical-conditions-config.json) - ✅
logbook.training-totals.orthopaedic-curriculum— Orthopaedic Surgery, the sole seeded surgical speciality that the #8490 extraction wave never covered, now has a curriculum-structure JSON like its nine siblings, so its trainees get the same critical-conditions widget, "Numbers Required for Completion" widget and whole-of-training cadence prefill everyone else already had — on existing databases as well as fresh ones. The curriculum JSON alone only reaches a fresh DB:speciality.critical_conditionshas two writers, andseedSpecialitiesIfEmptyruns underif (result.length === 0), so UAT/prod (whoseOrthopaedic Surgeryrow long predates this extraction) are populated only by the name-matched backfill migrations — 0196/0213, neither of which names Orthopaedic. Backfill migration 0222 closes that second path with the same normalised, variant-tolerant name match 0213 uses, writing only rows still empty so an admin edit is never clobbered, and carrying a first-apply-only validator (#10172) that proves the effect once rather than re-asserting a data invariant on every deploy forever. Extracted the same mechanical, machine-verified way (mirroringverify-extractions.py) from the ISCP/JCST Trauma and Orthopaedic Surgery Curriculum, Version 2 August 2024 — the source document Matt supplied on 2026-05-19 (appraisals-wba.md Q19), so no Matt input was required: 14 critical conditions (Appendix 3), 13 index-procedure groups with their indicative numbers (Appendix 4 — which sum to the curriculum table's own stated Total 365, an arithmetic proof the name-to-number pairing survived extraction), an overall indicative 1800 total operations / 1260 as first surgeon (Appendix 4a/4b), the eight main clinical areas (section 2.3) and the verbatim Table 3 certification wording. The new file is consumed by exactly the same helpers as its siblings with no special-casing:specialty-critical-conditions-config.jsongains a 10th entry,curriculumTrainingDefaults.tsgains its 1800 prefill, andSPECIALTY_PROCEDURE_CLASSIFICATIONSgains itsderiveSpecialtyProcedureClassification-derived entry. T&O is not the first extracted curriculum to state an explicit level-4 PBA count — Urology already states an indicative 9 (see the bullet above;UROLOGY_CLASSIFICATIONhas carriedrequiredLevel4PbaCount: 9on all six of its principal procedures since #9123). What is new is the form: T&O is the first to state its count as anN x Level 4 PBAsmultiplier ("3 x Level 4 PBAs in each specific operation group … by two or more trainers", Appendix 4d; 1 x PBA level 4 for its two named exceptions — supracondylar fracture and external fixator application, Appendix 4e), which is precisely the formparseRequiredLevel4PbaCountcould not read — Urology's plain "N PBAs … level 4" wording it already handled. It therefore gained a reader for the multiplier form only, while both #9123 anti-fabrication traps stay green. Corroborated against data Matt has already signed off: the 1800/1260 figures match the Orthopaedics defaults ingap-sheets/audit-summary.md, and 12 of the 13 Appendix 4 groups are already represented among theprincipalProcedurevalues on the 567 Orthopaedic rows inprocedures.json(all but "Tension band wire for fracture or arthrodesis") — a concept correspondence, not string equality: only 4 match verbatim, 3 differ only in capitalisation and 5 appear there solely in abbreviated form, so the two datasets must never be joined on the name. Provenance caveat, recorded in the committed file'sextractionNotes(clause 5) and repeated here so the spec does not read stronger than the data: Matt's Drive copy of the curriculum is access-controlled, so — unlike the other nine, whose Drive filenames matched the public documents exactly — byte-identity with his copy could not be confirmed; the extraction was run against the current ISCP-published document, whosesha256is pinned in the sameextractionNotesclause (the only one of the eleven curricula to pin one, which is what makes this extraction independently re-derivable).† (#10945, #9123, #8490, #8468;code:api/backend-ppp/scripts/seed-data/specialty-procedures/curriculum-structures/orthopaedic-surgery.curriculum.json,code:packages-shared/ppp/src/curriculum/specialtyProcedureClassification.tsORTHOPAEDIC_SURGERY_CLASSIFICATION/parseRequiredLevel4PbaCount,code:packages-shared/ppp/src/curriculum/curriculumTrainingDefaults.ts,code:packages-shared/ppp/src/curriculum/specialty-critical-conditions-config.json,code:packages-shared/ppp/drizzle/0222_orthopaedic_critical_conditions_backfill.sql)
Import
✅ UK ISCP/eLogbook format imports correctly
✅ Importer handles multi-sheet spreadsheets — user selects which sheet to import from†
✅
logbook.import.strip-empty-columns— Importer does not read infinite columns; the parse step strips columns with no data (blank/auto-generated header AND all-empty cells, or any header with all-empty cells) before the Map Columns step, while keeping any column that contains data (even if unlabelled) and preserving header/sample-data alignment, so only columns containing data are shown in the column mapper.† (#7740)✅
logbook.import.column-flexible-matching— import column auto-matching uses flexible (fuzzy/semantic) matching rather than exact string equality, so minor differences in column header names do not block import.† (#6394)✅
logbook.import.map-columns-sample-tooltip— on the Map Columns step, each source column's sample values are shown via a hover tooltip on the Source chip (not as a separate column), keeping the Map-To dropdown full-width and readable.†‡ (#7821)✅
logbook.import.dialog-on-brand— the import dialog and wizard use the shared compact, token-driven look (brand title, condensed stepper, design-token spacing/colour) with no hardcoded hex/px, so the flow is on-brand and easy to use.†‡ (#7821)✅
logbook.import.back-button— import wizard provides a back button at each step and does not require the user to re-select the file when navigating backwards through the wizard.† (#6395)✅ Missing URN blocks import with ERROR severity
✅ OCR via Azure OpenAI GPT-4o-mini Vision on web and mobile
✅ OCR handles UK theatre list JPEGs (verified 2026-04-12)
✅ OCR handles Australian patient stickers 19/19 (verified 2026-04-12)
✅ Upload enforces file-size guard before reading file (#4886)
✅ Frontend enforces 5,000-row import cap pre-submission (#4879)
✅ Import action button reappears after import completes (#4876)
✅ Navigation guard warns when leaving wizard mid-import (#4877)
✅ Imported cases included in Surgical Performance Overview (totals; per-breakdown population depends on the captured clinical fields below)
✅
logbook.import.capture-clinical-fields— when the surgeon maps them, import captures the clinical detail columns the breakdown charts read: Patient Category →activities.patientCategory(Adult vs Paediatric), ASA Grade →attributes.asaGrade(ASA distribution), and Supervision/Responsibility →attributes.userLevelInvolvement(Primary vs Secondary, via the sanctioned UK eLOGBOOK mapping plus a conservative plain-English fallback for unambiguous AU terms); Case Acuity is stored onactivities.caseAcuity. Unmapped/unrecognised fields are left for the completion to-do flow. Note: the Trauma vs Elective chart groups by the matched procedure's treatment acuity (procedures.treatmentAcuityId), notactivities.caseAcuity.†‡ (#8099)✅
logbook.import.dob-category-fallback— extends the #9846 DOB-derived patient category path: when a mapped Date of Birth cell is absent (no DOB column mapped, or blank for that row) or unparseable, the row falls back to the existing Patient Category column value (already normalised perlogbook.import.capture-clinical-fields) instead of being left blank for manual entry whenever that column has a usable value. The DOB-derived category still takes precedence whenever the DOB is present and parseable. A row whose DOB is unparseable still raises a non-blocking preview warning, worded to reflect whether the fallback produced a usable category or the row genuinely still needs manual entry.†‡ (#9900)✅ patientName mapped in wizard persists on saved case (#4885)
✅ autoCreateProcedures flag creates unmatched procedure entries (#4647)
✅ OCR adopts zodResponseFormat Structured Outputs (#5184)
✅ OCR date-of-birth extraction reliable (#4825); ✅ hospital names detected by OCR are matched against the user's linked hospitals (
logbook.ocr.hospital-matching) — confident match auto-selects, otherwise the user is prompted to confirm/select an unknown hospital before the entry is saved (logbook.ocr.unknown-hospital-confirm), with no silent free-text (#4838, #7506)†✅
logbook.ocr.scan-reachable-on-mobile-app— the multi-add "Scan Operating List" entry point (theatre-list OCR that bulk-creates one case per patient) stays reachable on the mobile app, where the full logbook toolbar is otherwise suppressed for native chrome; without it a phone user photographing a theatre list falls back to the single Patient Sticker OCR and gets a single misread.†‡ (#8337)✅
logbook.ocr.sticker-list-detection-redirect— the single Patient Sticker OCR detects when the uploaded image is a multi-patient operating/theatre list (the model returns anisOperatingListflag) and, instead of fabricating one misread case, returns no patient fields and the form directs the user to the multi-add Scan Operating List flow; a genuine single sticker still auto-fills as before.†‡ (#8378)✅
logbook.ocr.trust-id-preference— sticker OCR extracts the NHS number and the local hospital/trust ID as separate fields; the Pt Hospital Number / URN field carries the trust ID, falling back to the NHS number only when no trust ID is readable, and digit-free / over-long OCR junk is rejected rather than pulled through.†‡ (#8480)✅
logbook.ocr.single-sticker-hospital-autofill— the single Patient Sticker OCR path (LogbookImageUploader→analyzeImage.analyze) now also extracts a hospital/trust name from the sticker and resolves it to the doctor's linked hospitals, reusing the sameHospitalMatchingServicecascade (exact → fuzzy → partial → acronym-expansion) the bulk import path already relies on — no duplicated matching logic. A confident match returns ahospitalId(never the raw free-text name, which is stripped from the response) and the Add Logbook Case form autofills the Hospital field from it; no match, no name read, or no linked hospitals leaves the field for the surgeon to pick, same as before. The resulting draft is unconditionally markedcreationSource: 'ocr'/isImported: true, extendinglogbook.origin.three-way/logbook.origin.ocr-distinctandlogbook.origin.scanned-details-headingto the single-sticker flow — previously only the bulkOperatingListScannerpath set these, so a sticker-scanned case did not reliably badge/label as "Scanned".†‡ (#10629)✅
logbook.ocr.operating-list-dob— Scan Operating List extracts each patient's date of birth (as well as the hospital ID and the patient's initials), so the draft case it creates carries the DOB that adding a case needs. An illegible DOB is left blank and never guessed.††† Built (#12723): the operating-list prompt and Structured Outputs schema (imageService/index.tsOperatingListStructuredOutputCaseSchema) ask for each row'sdob(DD/MM/YYYY day-first,nullwhen not legible — never guessed); the scanner's Review step shows an editable DOB column; the import sendsDate of BirthandPatient Name, and forcreationSource: 'ocr'persists the DOB through the encrypteddob_patientpath, while the name is reduced to initials (logbook.import.patient-name-initials-only). Spreadsheet imports still use a DOB column only to derive the patient category. A DB-storedoperating_listsystem-prompt override, if one exists in an environment, does not mentiondob; the strict schema still requires the key. The later age-at-surgery-only refinement is Q-ocr-age-only-storage. (#11183)✅
logbook.ocr.take-photo-first— on the scan upload step, "Take Photo" is the first option and "Choose Image" second, because taking a photo is the usual action.† Built in bothOperatingListScanner/sections/UploadStep.tsxand the patient-stickerLogbookImageUploader/sections/UploadDropzone.tsx, wherever a camera is available; Choose Image stays as the second option. Take Photo is the contained primary button and Choose Image the outlined neutral one (design-system.button.variant-emphasis) (#12727). (#11183)✅
logbook.import.onboarding-ring-fence— legacy data imported during onboarding is ring-fenced: imported entries are flagged (isImported = true) and excluded from the active-engagement metric (getActiveEngagementMetric, rolling 90-day window counting platform-created entries only), so a bulk historical upload cannot substitute for ongoing daily platform use. Minimal version per #6334. The 90-day/500-row gate built for Q11 was removed (logbook.import.onboarding-window-and-row-cap); Matt's current word on timing islogbook.import.time-boxed-onboarding-windowbelow.†❌
logbook.import.onboarding-window-and-row-cap— Removed (#12303, Rob's explicit product decision, 2026-09-20): "Remove the 90 day 500 row import limit." This entry previously enforced the precise Q11 gate: the Import Logbook entry point (LogbookCaseToolbar) was hidden once the account was more than 90 days old,executeWizardImportrejected the whole import server-side as a hard backstop, and within the window a single legacy import was further capped at 500 rows cumulatively (#11804, atomic per-user viapg_advisory_lock, #11965 security review). None of that remains — the entry point is now always available and unrestricted, subject only to the generic 5,000-rowMAX_IMPORT_ROWStechnical sanity ceiling that still applies to every import forever.LOGBOOK_IMPORT_ONBOARDING_WINDOW_DAYS,LOGBOOK_IMPORT_LEGACY_ROW_CAPandisLogbookImportWindowOpenwere deleted frompackages-shared/ppp/src/constants/logbook/formConfig.ts; theUploadSteprow-count guard now enforcesMAX_IMPORT_ROWSdirectly. Kept here (rather than deleted outright) so the spec history shows this was built (#11774, #11804, #11965) and then removed (#12303), not silently erased.† (#11774, #11804, #11965, #12303)⚠️
logbook.import.time-boxed-onboarding-window— importing historic records is presented as a limited-time onboarding opportunity, so every new user is under some pressure to upload all their past cases at the start. There is no row-count cap on what they can upload in that window. This keeps the 2026-05-13 intent (ring-fence historic upload to the start of a user's time with PPP, with possible internal discretion) and Matt's 2026-09-22 correction (a time limit, but "not 500 because everyone's going to have way more than that"). Supersession: 2026-05-13 ring-fence → #11774/#11804 built 90 days + 500 rows → Rob removed both on 2026-09-20 (#12303) → Matt, 2026-09-22: the row cap goes, the time limit stays. The window length, what happens once it closes, and how internal discretion works are not stated; see Q-import-window.††† Drift: since #12324 (2026-09-20) the Import Logbook entry point has no time limit at all, and nothing tells the user that import is a limited-time onboarding step (#12423). (#11186, #12423)✅
logbook.import.dob-derived-patient-category— when a Date of Birth column is mapped, import works out the patient's age at surgery (date of surgery minus DOB) and sets the patient category: under 16 is Paediatric, 16 or over is Adult. A source column that already says Adult or Paediatric is the second measure, used only when the DOB is missing or unreadable (logbook.import.dob-category-fallback).††‡ (#9846)✅
logbook.import.categorise-from-matched-operation— an imported row is categorised by matching its operation to an operation in PPP's master dataset; the matched procedure then sets the principal procedure, treatment acuity, broad area and specific area. Import does not try to match the source sheet's own category, subcategory or competency columns (for example a JCST competency column) onto PPP's tree. Demographic columns are still mapped as usual. Source category/subcategory columns are not used to categorise the case: the wizard still lists Broad Area / Specific Area as mapping targets, but the import ignores them. Whether those targets and the Notes target should be removed from the mapper is Q-import-notes-mapping.††‡ (#9829)✅
logbook.import.imperfect-data-no-fail— import never fails wholesale: valid rows import; rows with errors are returned (not dropped) for the user to fix or skip.†† (#7766)✅
logbook.import.preserve-multi-procedure-rows— multiple procedure/competency lines for one operation are preserved; only fully-identical rows are de-duplicated.† (#7766)✅
logbook.import.fix-invalid-rows-inline— invalid rows are shown editable on the import preview so the surgeon corrects or skips them and re-validates without re-uploading.†‡ (#8054)✅
logbook.import.needs-attention-surfacing— after an import, incomplete cases are self-evident: the list shows a per-case amber needs-attention indicator whose hover/accessible label names the exact missing clinical fields (Pt DOB, Pt Gender, ASA Grade, Level of Involvement, Operative time, Responsible Consultant for non-consultants, Surgery not mapped / Confirm matched procedure); a "N need attention" count chip on the Logbook Cases header toggles a Needs-attention filter that narrows the list to those cases, worst-first.†‡ (#8443)✅
logbook.import.unconfirmed-match-gate— an imported case whose procedure match is anything but exact (fuzzy / partial / abbreviation / similarity / auto-created / failed — an allow-list ofexact, so new matcher tiers can never silently count) is NOT counted in any performance chart until the surgeon confirms the procedure and submits the case (status leaves draft); the import result warns "N procedures were not matched exactly", and the case's Action Items guidance leads withConfirm the matched procedure ("<description>"). Refines the #4878 imported-drafts-count rule: only exact (or legacy unrecorded) matches count while still in draft.†‡ (#8443)✅
logbook.import.procedure-abbreviation-recall— the deterministic procedure matcher's abbreviation tier expands a curated table of unambiguous surgical shorthand common on OCR'd / hospital-export operating lists (e.g. MUA, OGD/EGD, WLE, LSCS, FESS, ERPC, EMR, VATS, PCNL — alongside the pre-existing lap/ORIF/TURP/etc.) so a scanned case whose operation is written in shorthand resolves to a known procedure instead of falling through to "needs classification". Each entry maps 1:1 to a single procedure phrase, so recall improves with no ambiguous expansion, and the result is still only amatchType: 'abbreviation'suggestion (confidence 0.8) the surgeon confirms in the Confirm-procedures panel — never an auto-accept and never upgraded toexactexcept via a surgeon-chosen id (resolveConfirmedProcedureMatch), preserving thelogbook.import.confirm-matches-in-wizardsafeguard.†‡ (#10391)✅
logbook.import.confirm-matches-in-wizard— the import preview lists every non-exact procedure match in a "Confirm procedures" panel: source text → best-guess match (+ confidence) → a specialty-scoped procedure picker (the add-case surgery search) to confirm or correct. A confirmed row is re-keyed SERVER-side to the chosen procedure id and upgraded to matchType exact (never a client-claimed exact), so it counts in performance charts immediately; unconfirmed rows still import as gated drafts (#8466) — the import is never blocked. The result summary separates "confirmed during import" from "left for Action Items".†‡ (#8467)✅
logbook.import.no-confirm-rejected-procedure— import resolution must never confirm a case against an admin-REJECTED procedure (a procedure whosestatusisrejected). The specialty-scoped surgery picker hides rejected procedures (the same query feeds the manual add-case picker), and the SERVER-side confirm path (resolveConfirmedProcedureMatch) returns null for a rejected id — so even a tampered client that smuggles a rejected procedure id through theconfirmedMatchespayload falls back to a gated draft rather than counting as an exact match. External (user-added) procedures stay selectable — rejection is an explicit admin decision; an external addition is not (option 2, not 3).†‡ (#8582)✅
logbook.import.unmatched-hospital-no-block— a typed-but-unmatched hospital never blocks its row (only an empty hospital cell still errors). The case imports withhospital_idNULL and the free-text hospital captured inimportNotes.originalData.hospital, flagged for later resolution; the import preview offers a per-row hospital picker (the same DB-backedhospital.listsearch the manual add-case form uses) so the surgeon can correct it to a real hospital before importing. A confirmed hospital id is validated SERVER-side against the canonical hospitals table before the case is keyed to it (never a client-supplied id), and no row is ever invented in the hospitals reference table (#8444 — the DB is the source of truth). The result summary separates "matched during import" from "imported with an unmatched hospital". A file whose hospitals are all unknown still imports every row.†‡ (#8648)✅
logbook.import.whole-file-hospital-fallback— when NO source column can be mapped to Hospital (the file has no hospital column at all, e.g. a single-hospital sheet named after the site), the Map Columns step offers a single DB-backed hospital dropdown — the samehospital.listsearch / pre-listed attached hospitals the manual add-case form uses — to pick one hospital for the entire file, and that selection satisfies the otherwise-required Hospital field so the wizard can advance. The chosenhospitalIdis validated SERVER-side against the canonical hospitals table (only a real, selectable hospital resolves; an unresolvable/tampered id is ignored) and applied to every imported row that has no hospital text of its own — never a client-supplied id keyed blindly, and no row is invented in the hospitals reference table (same safeguard as #8648). The per-row unmatched-hospital picker (logbook.import.unmatched-hospital-no-block, #8648) is unchanged when a hospital column IS present; the whole-file picker appears only when no hospital column is mapped, and a per-row typed hospital always wins over the whole-file default.†‡ (#10683)✅
logbook.import.bulk-hospital-assignment— when many imported rows reference a hospital that is not in the system (the real case: a whole file sourced to an HHS/Trust that is not itself a selectable site), the surgeon can pick ONE hospital from a search in the import preview's "Confirm hospitals" panel and apply it to EVERY unmatched-hospital row in a single action, instead of correcting each row through the per-row picker (logbook.import.unmatched-hospital-no-block, #8648), which is unworkable at that volume (the per-row list is capped at 50 rendered rows). Each bulk assignment is recorded as a normalconfirmedHospitalsentry and rides the confirm import, so the chosenhospitalIdis validated SERVER-side against the canonical hospitals table (same safeguard as #8648/#10683 — never a client-supplied id keyed blindly, no invented hospital row) and any single row can still be overridden afterwards. Distinct from the whole-file picker (#10683), which handles a file with NO hospital column at all; this handles a file whose hospital value simply does not match a selectable site.†‡ (#10680)✅
logbook.import.scale-verification— an on-demand (workflow_dispatch-only, not per-commit) test drives the real import pipeline over an anonymised fixture from Matt's ~4,000-case logbook, asserting every row is accounted for, a match-rate breakdown, the chart gate, and list/widget latency at scale.†‡ (#8602)✅
logbook.import.live-progress-and-observability— a large import is observable, legible, and resilient. The import publishes per-batch progress to an in-process registry keyed by a client-suppliedimportJobId, exposed via thegetImportProgressquery the wizard polls to render a live "X / N rows" count instead of a static "Validating… 25%". Structuredctx.loggeroutput reports row count, per-batch progress, the imported/skipped/invalid/duplicate/failed breakdown, peak RSS/heap memory, and an explicit failure cause with timing — so a net::ERR_FAILED has a matching server trace instead of silence. A batch insert that throws falls back to per-row inserts so one bad row only loses itself (recorded infailedEntrieswith its cause) rather than sinking the whole batch; the import still returns a summary of imported vs skipped/failed rows. Progress is best-effort (in-process, not DB/Redis) — the authoritative result is the mutation return value, and a poll that lands on another replica returns null so the wizard falls back to indeterminate progress, never worse than before.†‡ (#9133)✅
logbook.import.auto-split-large-file— a file too large to import in a single request (the Azure ingress kills any request past ~60s, reached at a few hundred rows) is automatically split by the app into sequential sub-requests that each stay under the timeout, imported in order — the surgeon never pre-splits the file. The confirm import chunks the payload atIMPORT_CHUNK_ROWS(250); a payload under the threshold is a single chunk, so a small import is unchanged. The row-keyed in-wizard confirmations (logbook.import.confirm-matches-in-wizard#8467,logbook.import.unmatched-hospital-no-block#8648) are re-based into the chunk that owns each row before sending. Progress shows one aggregate "X / N rows" across the whole file (the live registry count offset by rows already imported), not a per-chunk reset. Chunk seams are safe by construction:logbook.import.repeatable-with-dedupe(#10013) dedupes across separate requests and the per-user advisory lock serialises them, so no row is ever double-imported or double-counted; and per the honest-failure rule (#9998) a single failed chunk fails the whole import rather than silently importing a partial file. The former "split into smaller batches (under 300 rows)" error instruction is removed — auto-split handles it.†‡ (#10682)✅
logbook.import.preview-auto-split-and-visible-progress— extendslogbook.import.auto-split-large-file(#10682) to the preview/validation request, and hardenslogbook.import.live-progress-and-observability(#9133) for the multi-replica deployment. Previously only the confirm import chunked; the preview (confirm: false) sent the whole file in ONE request, so a large file (Matt's 2,000+ rows) hit the Azure ingress ~60s timeout during validation and the surgeon never reached the confirm step — observed as no feedback then a timeout. The preview now auto-splits atIMPORT_CHUNK_ROWS(250) exactly like the confirm path and folds the per-chunk results (invalid rows, unmatched-hospital and unconfirmed-procedure lists, match-stats summary) into one whole-file preview viaaggregateImportResults, so the review step reflects the whole file, not just chunk 0. Becauseppp-uk-uat/ppp-uk-prodrun the backend at up to 2 replicas and the progress registry is in-process, agetImportProgresspoll can land on the replica NOT running the import and return null; so the coarse percentage now advances per completed chunk on the client (independent of the poll), guaranteeing visible movement even when a poll misses. A single-chunk (small) import is unchanged. The fold includesvalidatedEntries, so validated + invalid + duplicate + skipped rows add up to the file's row count (#12789), and the "Procedure matches" line on the validation and success summaries lists every category (exact, fuzzy, abbreviation, partial, similar, auto-created, unmatched) so it sums to the rows considered (#12789).†‡ (#10680)✅
logbook.import.progress-poll-never-signs-out— a 401 from the best-effortgetImportProgressprogress poll must NEVER trigger the global session-expired redirect (logbook/app-wide 401 interceptor, #5044). During a long import the backend replica can recycle under load and drop an in-flight poll with a 401 (observed on ppp-uat: the poll 401'd during replica churn and the interceptor redirected to/login?reason=session-expiredmid-import, destroying the wizard and all its state — 0 rows imported). The interceptor now ignores 401s from a small allowlist of best-effort background polls (currentlygetImportProgress) so a garnish progress poll can never sign the user out, while every other query and mutation still triggers the session-expired redirect exactly as before — if the session genuinely expired, the next real call surfaces it. Defensive: an unexpected query-key shape falls through to "not best-effort" so a real 401 is never accidentally suppressed.†‡ (#10680)✅
logbook.import.patient-name-initials-only— supersedeslogbook.import.patient-name-privacy-notice's "skip entirely" behaviour. When a source column is mapped to "Patient Name", the backend (importSurgicalLogbook.ts) derives only the first+last initial (e.g. "John Smith" → "JS") and persists it asimportNotes.originalData.patientInitials— the full name is never referenced again after that reduction, and is never persisted, logged, or displayed anywhere. The Map Columns step shows an informational, non-blocking (info severity) alert reflecting this: the full name is never imported, only the initials are captured as a secondary identifier for disambiguation when Date of Birth (#9846) is absent from the source sheet. Imported-case detail views (ImportedCaseDetails,ImportedCaseDetailsSection) surface the initials under a "Patient Initials" label, never a full name.†‡ (#9897, supersedes #9845)✅
logbook.import.reset-flow-for-new-file— after an import completes, the surgeon can start importing a different file straight from the success screen without a full page refresh. The import runs as a two-dialog pipeline (the upload/map wizard hands off to the preview→confirm→success dialog); previously the success screen's only exit was Close, so importing another file meant re-opening the wizard from the toolbar or reloading the page. An "Import another file" control on the success screen now clears the finished import — selected file, parsed rows, column/hospital mappings, preview, result, and progress — and re-opens the upload wizard at the file-select step in place, so no stale state from the previous file is ever carried into the next one.†‡ (#10681)✅
logbook.import.repeatable-with-dedupe— a surgeon can import their logbook as many times as they need (an updated spreadsheet later in the year, one file per hospital/rotation). The single-import-per-user guard (which rejected any second confirmed import with "You already have imported logbook data. To import again, please contact support.") is removed. Duplicates are handled gracefully instead: each incoming row is deduped against the user's existing imported cases on URN + operation calendar day + operation description (the same key the in-batch dedupe and the wizard import path use), skipped when it matches, and counted induplicateEntriesso the "N duplicates skipped" figure shows on both the preview and the confirmed result. Re-importing the exact same file is a clean no-op (0 imported, N duplicates skipped) reported honestly as success — not a false failure (perlogbook.import.honest-failure, #9998/#10007); importing an updated file imports only the genuinely new rows. The #9998 per-user advisory lock is retained: it now serialises the cross-import dedupe read-then-insert so two concurrent confirmed imports of the same file can never both persist the case.†‡ (#10013)✅
logbook.import.single-scroll-region— the import wizard modal is a fixed-height flex column (max-height: 85vh,display: flex; flex-direction: column; overflow: hidden) with exactly ONE scrollable viewport: the header/stepper, the fixed privacy banner, and the footer navigation areflex-shrink: 0and never scroll away; only the content body isflex: 1; overflow-y: auto. This replaces the former dual-scrollbar layout where the modal paper AND the inner mapping table both scrolled ("scrollbar inception"), so the Back/Continue buttons stay visible without scrolling the modal at any step or viewport size. The preview→confirm dialog (the second dialog in the two-dialog pipeline) follows the same contract.†‡ (#10705)✅
logbook.import.step-label-honesty— the Map Columns step's primary action reads "Continue to Review", never "Finish". That click only advances the wizard to the Review step; it does not run the import, so "Finish"/"Import" is reserved for the final import step. (Previously it read "Finish", implying the import ran on that click.)†‡ (#10705)✅
logbook.import.auto-map-summary-collapse— when every source column is mapped with high confidence (nothing needs manual attention), the fully-mapped rows collapse behind a one-line success summary ("N of N fields automatically mapped") with an expander; only rows still needing review (unmapped or low-confidence) stay expanded by default, so the surgeon is not made to scroll a wall of already-correct rows. Expanding the summary reveals the individual auto-mapped rows.†‡ (#10705)✅
logbook.ocr.upload-size-limit-consistency— refines the numeric value behind the existing "Upload enforces file-size guard before reading file" AC (#4886): the Scan Operating List/Patient Sticker OCR upload size ceiling is ONE shared value (MAX_IMAGE_FILE_SIZE_BYTES, 10MB) imported by the client-side validation, the advertised "Max size" label, the blob-upload gate (storage.generateUploadUrl), and the OCR image-fetch gate (imageService.fetchImageFromStorage) — so the four can never numerically disagree again. Previously the OCR-fetch gate still enforced a stale 5MB ceiling (set in #990/issue #80 for an AWS Lambda memory constraint that no longer applies under Azure Container Apps) while the other three had independently moved to 10MB, so a doctor's phone photo between 5MB and 10MB passed upload and was then rejected with an error that contradicted the on-screen "Max size: 10MB" copy.†‡ (#10918)✅
logbook.import.dedupe-decrypt-resilient— the cross-import duplicate-detection scan (importSurgicalLogbook.ts— OCR scanner and legacy spreadsheet callers — andimportExecutionService/index.ts— the wizard) tolerates an existing case whose stored patient identifier fails to decrypt (a legacy/un-backfilled row post-#10734 encryption cutover): that ONE row is excluded from dedupe matching (logged server-side with the activity id, never the raw value) instead of the decrypt failure aborting the ENTIRE import. Because excluding a row from dedupe matching means a genuine duplicate of it could import undetected — a clinical data-integrity concern, not a cosmetic one, since inflated case counts feed revalidation/training-progression evidence — the import result carries a plain-language warning ("We couldn't check N of your existing cases for duplicates...") whenever this happens; the warning never names decryption/ciphertext internals. The underlying question of how a stored identifier became undecryptable is tracked separately, unresolved (#10937) — this AC covers only that the import must never silently corrupt or wholesale fail because of it.†‡ (#10919)✅
logbook.ocr.epr-screen-photo-input— Scan Operating List accepts BOTH a printed/photocopied theatre list AND a photograph of the list displayed on an EPR monitor; both are what a surgeon realistically photographs, so neither is a second-class input. The operating-list OCR prompt names the monitor-photograph case explicitly and instructs for the artifacts specific to it — glare, reflection, moire banding and perspective skew — and to ignore the surrounding application chrome (window title bars, menus, toolbars, ribbons, navigation panes, tabs, status bars, ward filters), since a toolbar button or column header is never a patient, procedure or case. EPR column headers are mapped by MEANING rather than exact label text ("Patient"/"Name", "NHS No"/"Hospital No"/"MRN"/"UR", "Procedure"/"Operation"/"Planned Procedure"), and a row whose individual field is hidden by glare returns that field as null rather than dropping the whole row. The model must never invent a value glare or blur has hidden, and must return an emptycasesarray for a genuinely illegible image rather than fabricating plausible-looking rows. The pre-existing #8724 prohibition on extracting the operating surgeon, level of involvement and time slot is unchanged.†‡ (#11484)✅
logbook.ocr.unreadable-image-honesty— a Scan Operating List OCR call that SUCCEEDS but reads zero cases is its own outcome, distinct from both a successful extraction and a technical failure, and the surgeon is told so at the point of scanning. The scanner does not advance to the Review step, never fires a success message reporting the extracted count, and never runs the classification preview; instead the upload step explains that no patient rows were legible and names the causes the surgeon can act on — blur, and the glare or reflection that comes of photographing a monitor — with retake advice specific to the screen-photo case and a control to try another photo. Previously a zero-case read fell straight through to Review under a success-variant "Extracted 0 cases from operating list" snackbar, presenting an empty table with a live Import button, so the surgeon met only a generic "Import Failed" after clicking it, naming nothing actionable. A THROWN OCR error keeps its existing error treatment and is never relabelled as an unreadable image, which would send the surgeon chasing an image problem that does not exist. Server-side, a zero-case extraction and a refusal/content-filter stop are logged distinctly so a blank scan is diagnosable rather than invisible; neither log line carries patient data.†‡ (#11484)
Case Origin
- ✅
logbook.origin.three-way— every case records its origin — imported (spreadsheet), scanned (OCR), or manual — inactivities.creationSource.†† (#7766) - ✅
logbook.origin.badge— the logbook list and card show a distinct badge per origin (Imported / Scanned / Manual) using colour + icon (WCAG 2.1 AA).† (#7766) - ✅
logbook.origin.ocr-distinct— OCR-scanned cases no longer share the imported flag with spreadsheet imports; new OCR writes setcreationSource='ocr'. Pre-existing OCR cases backfill to'import'(historically indistinguishable).‡ (#7766) - ✅
logbook.origin.no-rescan-prompt-on-existing-case— the single Patient Sticker OCR uploader appears only while composing a NEW case (add mode). A case that was already created by scanning a sticker (or by spreadsheet import) does not re-show the scan-sticker upload prompt when it is re-opened for view/edit — the item is already scanned, so re-prompting is confusing.†‡ (#10598) - ✅
logbook.origin.scanned-details-heading— a case whose origin is a sticker scan (creationSource='ocr') heads its captured-detail section "Scanned Case Details", to match the actual source; a spreadsheet import keeps "Imported Logbook Case Details". Resolved via the sharedresolveCaseOriginhelper, so the wording follows the same three-way origin vocabulary as the list/card badges (logbook.origin.badge).†‡ (#10598)
Dashboard
- ✅ Supervision Breakdown widget boxes not truncated
- ✅ ASA Grade surfaced in Surgical Performance Overview
- ✅ Competency Levels widget is clickable
- ✅ Sort label and x-axis title not clipped
- ✅ View Cases button visible when drilling Trauma/Elective
- ✅ Dashboard stats default to user's own cases
- ✅ Primary Surgeon count not inflated by received cases
- ✅ Cog on the pace-monitor strip opens the case-targets modal (absorbed the two per-card cogs; #8195)
- ✅ Auto-generated review feedback visible in Retrospective
- ✅ TotalOperationsWidget drill level 2 navigates to cases
- ✅
logbook.dashboard.level-of-involvement-label— the Supervision Breakdown widget is labelled "Level of Involvement breakdown"; consultant and non-consultant data sets are displayed within it.† - ✅
logbook.dashboard.trauma-elective-position— Trauma vs Elective widget appears at dashboard position 2 (immediately after Total Operations).† - ✅
logbook.dashboard.paediatric-widget— dashboard includes an Adult vs Paediatric case breakdown widget at position 3; patient age < 16 years classifies a case as paediatric.† - ✅
logbook.dashboard.jcst-case-source-removed— the JCST Competency widget and the Case Source Breakdown widget are not present on the logbook dashboard (removed as redundant).† - ✅
logbook.dashboard.principal-procedures-show-all— the Principal Procedures widget shows all procedures for the user's specialty even when the primary-operation count is zero; zero-count procedures render as empty bars with distinct styling.† - ✅
logbook.dashboard.target-progress-replaced— the Logbook Target Progress widget is replaced by the 3-Month Rolling Goal widget showing case count, quarterly goal, and percentage progress gauge.† - ✅
logbook.dashboard.pace-monitor— one compact top strip consolidates total cases, primary surgeon, training goal, done, remaining and pace status. Each stat's number is horizontally centred under its heading, and the strip shares one row with the Hospital filter / Customise controls (#8723) rather than stacking as a separate row above them, cutting the header's vertical footprint by roughly one row on desktop.†‡ (#8195, #9982) - ✅
logbook.dashboard.pace-monitor-coaching— pace status reads Ahead of/On/Behind pace with one encouraging line citing the quarterly goal.†‡ (#8195) - ✅
logbook.dashboard.pace-monitor-visibility— coaching renders only with a stored training target; others see plain totals. An expected completion date is not required: without one the quarterly goal is paced over the 5-year default (DEFAULT_TRAINING_YEARS, same as the profile read-out, #12736); an elapsed completion date still yields no goal and no coaching.†‡ (#8195) With no CCT date the pace divides by the doctor's own Years to complete (pre-filled with 5, stored ascadenceTracker.yearsToComplete, #12813) and falls back to the labelled 5-year default only when none is entered. - ✅
logbook.dashboard.customise-widgets— a discoverable "Customise" button toggles a reorder-only edit mode: a banner explains the interaction, each widget card gains a reorder affordance, and "Done" exits; outside edit mode the dashboard shows no extra chrome. Widgets are NOT deletable (#8671) — no remove/− control. The reorder affordance differs by breakpoint (#8671): desktop/pointer shows a single grab handle (drag-to-reorder, no arrows); mobile/touch shows up/down arrows (no grab handle). Same shared framework as the PPP dashboard.††‡ (#8241, #8671) - ⛔️
— Superseded by #8671 (2026-06-17). Widgets are no longer deletable on the surgical logbook either, so the per-widget remove badge and the "Add widgets" tray were removed along with the sharedlogbook.dashboard.customise-add-removeAddWidgetTraycomponent and theremoveWidget/addWidget/hiddenWidgetshook API. The customisable set is now exactly the default widget set, reorder-only.† (#8241, superseded by #8671) - ✅
logbook.dashboard.customise-persistence— customisation choices persist per user, per dashboard, across devices via adashboardLayoutsJSONB map on the user profile; a doctor who never customises sees the default set + order, unknown widget ids in a saved layout are skipped, and newly shipped widgets append visible at the end. The persistedhiddenarray is always written empty (#8671 — reorder-only) and any legacyhiddenentries are ignored on read.†‡ (#8241, #8671) - ✅
logbook.dashboard.range-filter-parity-on-load— on first load of/logbook-case, the "Logbook Cases" list opens on the same window and filter state as the "Surgical Performance Overview", so the top-of-page total and the list count do not silently diverge. The case-list date range defaults to the same 1-year window the overview opens on (startOfDay(subYears(now, 1))→endOfDay(now), the exact start/end thePillDateRangeFilter1Y preset detection expects, so the "1 Year" pill renders selected rather than "Custom"), and the Source filter defaults to'all'(no silent "Source: Submitted" filter that would hide received cases the overview total counts — option (a) of the issue spec). The Source control stays available so users can narrow explicitly; any non-default selection still surfaces as a visible, removable chip. "Clear filters" resets to these same defaults. Engineering default (Rob acting-PO) superseding the prior 3-month /'submitted'case-list defaults; not a Matt-authored requirement.†‡ (#9185) - ✅
logbook.dashboard.verified-unverified-states— logbook dashboard widgets (as well as the case list) show verified and unverified cases differently, while still counting both in totals.† Built (#12726): the Level of Involvement widget (SupervisionBreakdownWidget, on the logbook dashboard) and the Primary vs Secondary widget (logbook report) each show a "N verified · M unverified" line (VerificationSplit) that partitions the widget's existing total — unverified (pending or declined) cases still count toward the total.getSupervisionBreakdownnow returnsverified/unverifiedper category. (#11183)
Responsible-Consultant Profile Summary
"Delineations" is grounded in best-in-class surgical-credentialing research (adversarially verified 2026-07-22) as surgical scope of practice / delineation of clinical privileges — named procedure categories each containing individual index procedures, NOT a flat count — mapping onto RACS MALT (per-case supervision level + primary-surgeon flag) and the ISCP/JCST eLogbook trainer supervision codes (incl. "Under my care"). Matt used the term loosely in the #10823 NBB, so per the SGD audit protocol it is grounded by citation rather than inferred. See
src:research-2026-07-22-delineations-scope-of-practice.
- ✅
logbook.profile.responsible-consultant-count— the consultant's own profile shows a header count of surgical logbook cases where they are the responsible consultant (the caseassessorId, distinct fromcpdSupervisorId), for a selectable period (reuses the sharedPillDateRangeFilter3M/6M/1Y/All presets). OnlyassessorId = selfcases are counted — not cases the consultant merely submitted. Server-sideenforceUserScoperestricts a non-admin to their own responsible-consultant caseload.†‡ (#10823) - ✅
logbook.profile.responsible-consultant-delineations— the primary breakdown ("delineations") groups those responsible-consultant cases by procedure category → individual index procedure (the scope-of-practice structure), using the existing procedure taxonomy (procedurebroadArea= category,principalProcedure= index procedure). Infrequently-performed procedures are NOT hidden — the full scope is shown, including single-case index procedures (RACS surgical-audit requirement to reflect the whole scope).†‡ (#10823) - ✅
logbook.profile.responsible-consultant-involvement— the secondary breakdown groups the same cases by the consultant's level/role of involvement, mapped to the existing consultant LoI codes (S-S Supervising scrubbed, S-U Supervising in theatre, S-H Supervising in hospital, UC Under my care, PA/PCC/PPT, O, AC), preferringconConsultantInvolvementand falling back touserLevelInvolvement.†‡ (#10823) - ✅
logbook.profile.responsible-consultant-outcomes-excluded— surgical outcomes (mortality, complications, return-to-theatre) are DELIBERATELY EXCLUDED from this profile view. This is a governance decision: ANZASM-style confidentiality forbids surgeon-identifying mortality attribution, and case volume is only weakly/non-deterministically tied to outcome; outcomes belong to a separate, opt-in, de-identified peer-review audit surface, never a per-consultant profile count.† (#10823) - ✅
logbook.profile.responsible-consultant-de-identified— the view shows counts and groupings only — no patient identifiers. The aggregation reads only case taxonomy + involvement codes and never selects or decrypts the encrypted patient identifiers (dob/gender/URN, #10721); patient de-identification is respected end to end.†‡ (#10823)
Display
- ✅
logbook.display.list-tile-toggle— users can toggle the logbook cases list between tile/card view and line/list view; the selected view persists across sessions.† - ✅
logbook.display.imported-vs-manual-hatch— visually distinguishes imported logbook entries from manually entered entries using a hatching pattern (or equivalent accessible visual treatment); distinction must meet WCAG colour contrast requirements.† - ✅
logbook.display.case-type-button-colour— the three logbook case-type buttons (Scan Operating List / Import Logbook / + Add Logbook Case) all use the on-brandcolor="primary"blue and never a differential blue scale that varies between buttons. They are arranged as a clear action hierarchy: + Add Logbook Case is the solid primary CTA (variant="contained"); Scan Operating List and Import Logbook are brand-blue outlined secondaries (variant="outlined") — the same one-primary/two-secondary pattern as the wellness dashboard action row, so the primary action stands out without any off-brand colour.††‡ - ✅
logbook.display.case-type-buttons-compact-mobile— on a narrow mobile viewport (below thesmbreakpoint) the three logbook case-type buttons (Scan Operating List / Import Logbook / Add Logbook Case) render as one tidy equal-width row of compact buttons with short labels (Scan/Import/Add Case) instead of wrapping into a chunky full-width 3-row vertical stack that pushed the fold down by ~180px. The desktop layout (full labels,size="small", the one-primary/two-secondary colour hierarchy) is unchanged. Touch targets stay ≥44px (WCAG 2.5.5); the full label rides on the buttontitleso the accessible name still matches the visible short text and noaria-labeldiverges from it (#7773). The?help control's placement (adjacent-right of the heading rather than a standalone row) is owned by the sharedPageHeaderand was fixed for all pages by #9887 — this AC covers only the action-row compaction.†‡ (#9891) - ✅
logbook.display.on-brand-page— the /logbook-case page uses the shared compact look & feel (PageHeader title row, bordered SectionCard panel, ~13px text, tight token-driven spacing) matching the rest of the app; all colours/spacing come from design tokens with no hardcoded hex/px on the page.†‡ (#7821) - ✅
logbook.display.thin-ring-calibration— logbook doughnut widgets use the shared compact thin ring (slim ~30px desktop / ~26px mobile), not a heavy block.†‡ (#8003) - ✅
logbook.display.filters-popover-close— the logbook cases Filters popover carries an explicit, discoverable dismiss affordance: a semantic closeIconButton(accessible name "Close filters") in the popover header next to "Clear all", plus a "Done" button at its foot — both wired to the same dismiss handler. On a phone viewport the popover fills almost the whole screen (width: 92vw,maxHeight: 80vh), and previously the only way out was tapping the near-invisible backdrop; the close control and Done button make exiting obvious on both mobile and desktop. Both are real MUI controls per the semantic-control a11y rule (#7773); the close control's visible icon carries the accessible name viaaria-label.†‡ (#8943)
Consultant Review
- ✅
logbook.consultant-review.verify—ReviewLogbookCaseForm(forms/LogbookCaseForm/Consultant/) lets a consultant review a non-consultant's entry and set status toverified. A transition toverifiedis authorised server-side: the caller must be the case owner, the assignedassessorId/supervisorId, or a super-admin, and the verifier id is derived from the authenticated session — never from client input. Theactivities.updateprocedure enforces this guard for logbook cases (FORBIDDEN otherwise, status unchanged on a partial write); thelogbook.updateprocedure additionally scopes non-admins to their own entries viaenforceUserScope. This mirrors the symmetric non-assessor guard on the decline path (logbook.consultant-review.decline-required-reason). (Engineering audit 2026-05-12; guard shipped in #6239, confirmed present #9188) - ✅
logbook.consultant-review.status-visible— verified status visible on the entry (Engineering audit 2026-05-12) - ✅
logbook.consultant-review.verify-notifies-submitter— when a consultant verifies a non-consultant's logbook entry, an in-applogbook_case_reviewednotification ("has verified your logbook case") is emitted server-side inlogbookService.updateLogbookEntryon the transition intoverifiedstatus (covering all review surfaces incl. the Work Queue dialog); self-verification is suppressed.† (#6335) - ✅
logbook.consultant-review.decline-required-reason— "Decline" button onReviewLogbookCaseFormopens a dialog requiringdeclineReason(10–500 chars) + optionaldeclineCategoryenum; submitting the dialog sets activitystatus='declined'via thelogbook.consultantDeclinetRPC procedure (non-assessor guard added in #6239) (#6085, #6239) - ✅
logbook.consultant-review.decline-notifies-submitter— on decline, an in-applogbook_case_declinednotification is emitted to the submitting user via the existing notification pipeline, carrying the reason (#6085) - ✅
logbook.consultant-review.resubmit-after-decline— declined cases show a banner with the reason + a "Resubmit" CTA that pre-fills the form;resubmitDeclinedresets status topendingwhile preserving the prior decline metadata (audit trail intact) (#6085) - ✅
logbook.consultant-review.signature-on-review— the digital-signature confirmation ("Check this as your digital signature…") appears only on the consultant review/confirm screen, gating Verify; it is not shown on the add/submit case forms — saving/submitting implies it.†‡ (UI gate only — the confirmation is not persisted; recording a signature audit event is an open product decision, see Open Questions.) (#8192) - ✅
logbook.consultant-review.competency-feedback-capture— the review screen captures the submitter's level of involvement (accept/modify), the consultant's own involvement, a competency score (Global Summary), and short-form feedback; the verified values render back on the submitter's case form (Reviewer's Section).†‡ (#8192) - ✅
logbook.consultant-review.dual-profile-visibility— a submitted case is visible on both profiles individually: the submitter's logbook (owner) and the reviewing consultant's logbook (received-as-assessor query merged into the case list), plus the consultant's Action Items / Work Queue while pending.†‡ (#8192) - ✅
logbook.review.assessor-email-on-submit— when a logbook case is submitted for sign-off (status →pendingwith an assignedassessorId), the responsible consultant is sent a branded email (in addition to the existing in-app notification + generic daily push digest), mirroring the WBA assessor email (#5026). Best-effort: a send failure is logged and never blocks the submit. Fires fromactivitiesCrudon both the create and the submit-transition paths vianotifyAssessorOnLogbookSubmission.†‡ (#9189) - ✅
logbook.data-model.assessor-vs-supervisor— theactivities.assessorId(approval / sign-off "Responsible Consultant" — drives review, the work-queue and submit/decline notifications) andactivities.supervisorId(CPD-credit field, co-accruing credit for the same operation; unrelated to approval) columns are documented in the Drizzle schema to prevent the naming trap of keying approval logic on the wrong column. A physical column rename was considered but deferred as a higher-risk, separately-reviewed refactor given its ~200-reference blast radius across the approval workflow.†‡ (#9189) - ✅
logbook.consultant-review.cpd-credit-on-sign-off— when a consultant verifies a non-consultant's case (checking level of involvement and competency score, and optionally giving feedback), the consultant earns CPD automatically. Supervising/training credit goes to Supervision of Surgical Trainees or Teaching to Trainees/Undergraduates (lowest bucket), and feedback credit to peer review with feedback. The consultant doesn't log anything separately. One operation credits the consultant once (#12814, Rob 4 Oct 2026): if the consultant also logged their own entry for the same operation (same surgical-case parent), their own log wins and the sign-off adds no extra CPD.†††‡ The trigger is built, and (#12725) it now qualifies off the adminearns_cpd_creditflag (seeded PPT/S-S/S-U; S-H no) and credits per operative hour with minute banking in the assessing consultant's pooled credit viasyncSignOffSupervisionCredit. Still open (#12725 AC3, moved to #12814): no double credit when the same consultant also logs the same operation at a supervising LoI. That is blocked on Q-signoff-cpd-double-credit and is not built: today both are credited. The same mechanism is still to be built for WBA sign-off (#12712). Built in #12725. (#11183) - ⏳
logbook.lifecycle.attached-forms-cpd-both-users— forms activated from a logbook case (WBA, Reflection, Feedback) go to the consultant's profile and back to the doctor. When each form completes, CPD triggers where appropriate for both the doctor and the consultant.† Partly built: completing a Reflection credits its owner, and giving Feedback credits its author (cpdUserActivityHandlerREFLECTION/FEEDBACK branches;cpd-automations.md). The consultant's credit for completing a CBD/CEX/PBA/SSA WBA from the case isn't built yet (#12712; hours/category are WBA Q27). (#11183)
Multi-participant Surgical Case
- ✅
logbook.case.parent-link— entries that match onURN + date + primary_procedureare auto-linked to a sharedsurgical_caseparent row; existingduplicateDetectiongraduates from warn-only to auto-link (see Process → Surgical Case parent)† - ✅
logbook.case.consultant-roll-up— consultant logbook view groups bysurgical_case_id, showing one card per surgery with each junior's child entry beneath; no phantom activity is created for the consultant† - ✅
logbook.case.participant-role— each activity carries aparticipant_roleenum (primary/assistant/observer/consultant); per-participant fields (supervision time, satisfaction, competency) remain on the child activity row, unchanged†
Entry — Duplicate Detection
- ✅
logbook.entry.duplicate-warning— on create/update, if another entry with matching URN+date+procedure exists for the same user, the service returns aduplicateWarningobject; frontend showsDuplicateWarningDialogbefore proceeding (Engineering audit 2026-05-12) - ✅
logbook.entry.primary-operator-conflict— if another user has already claimed primary operator for the same case (same URN+date+procedure), the backend throws aCONFLICTtRPC error; frontend showsPrimaryOperatorConflictDialoggiving the user the option to proceed withskipConflictCheck(Engineering audit 2026-05-12). The CONFLICT message is a static, non-identifying string — it names neither the patient URN (#10888) nor the conflicting clinician (#10936), sinceerror.messagereaches the requesting user, the structured log sink, and the live Discord webhook unredacted, and person names have no reliable regex pattern foronError.tsto scrub. The conflicting clinician's name is not merely omitted from the message but never fetched:checkPrimaryOperatorConflictis an existence probe overactivitiesalone and returns{ hasConflict }only, so no clinician identity is ever resident on an object a future log statement could serialise (#10949).
Reports / Export
- ✅
logbook.export.csv— Export button on the Logbook Cases page generates a client-side CSV of the current filtered case list (utils/export.ts → exportToCSV) (Engineering audit 2026-05-12) - ✅
logbook.export.identifiers-decrypted-once— the logbook CSV and PDF exports and the Multi-Feature Report's logbook rows take patient identifiers (URN, date of birth, gender) fromgetActivitiesByFilter, which has already decrypted them, and only convert the date of birth to a Date and write the access-audit entry. They never decrypt a second time, which threwmalformed ciphertextwith encryption on. (#12600) - ✅
logbook.export.pdf— Export button also supports client-side PDF generation via@pdfme/generator(utils/export.ts → exportToPDF) (Engineering audit 2026-05-12) - ✅
logbook.export.pdf-server-side— backendlogbook.exportToPdftRPC procedure is registered but never called from the frontend — dead code path that should be wired up or removed (#5031) - ✅
logbook.export.report-builder— a Logbook Report page allows global date-range selection, per-widget/insight selection, and ASA grade filtering; the full audit log output is presented in line-by-line format.†
API & Data Licensing
- ✅
logbook.api.interface-spec— an API interface specification is defined as a dedicated specification artifact (not just docs) to enable third-party data integration and platform feature licensing, leveraging the FHIR architecture.† Built #7017: OpenAPI 3.0 artifact atapi/backend-ppp/src/rest/fhir/openapi.json. (#6336) (#7299) - ✅
logbook.api.token-access— a token-based access mechanism (the "token feature") accompanies the API interface specification, allowing a third-party consumer to access logbook data for licensing/integration.† Built #7017:logbook_api_tokenstable (migration 0113) + long-lived Bearer-token auth path on the FHIR Procedure endpoint. Token policy — confirmed product policy (Rob, 2026-07-11, #8816, Open Question Q12 CLOSED): the shipped #7017 behaviour hardened into code is now the official policy — per-user scope, read-only, no write access for external consumers, ever. This token is the third-party API-licensing mechanism. Per-user scope — a token exposes only its owner's logbook data (cross-user reads return 403). READ-ONLY — external consumers never write: the public FHIR surface is GET-only and the token path opens an unauthenticated inner context bound to the token owner, so no write procedure is reachable. Optional expiry with immediate revocation (a non-nullrevokedAtinvalidates instantly), with a 90-day default expiry applied at issuance when the issuer sets none, and supported rotation (logbookApiTokens.rotateissues a fresh token and revokes the old one atomically in a single DB transaction, so a crash mid-rotation cannot strand the owner with a revoked token and no replacement). The public FHIR endpoint is GET-only and rejects any write verb with 405 (Allow: GET), making the read-only contract explicit. Kept consistent withmcp-provider.mdQ1–Q4 (v1 read-only, doctor-scoped, 90-day expiry, doctor-revocable). This was Rob's direct decision, not raised with Matt.†‡ (#7299) (#8816) - ✅
logbook.api.export-resource-shape— the FHIR export surface exposes theProcedureresource type only for the current phase: the shipped OpenAPI 3.0 artifact (api/backend-ppp/src/rest/fhir/openapi.json) defines a singleProcedureendpoint, and that is the confirmed export shape (engineering/product default, 2026-06-30). Additional FHIR resource types (e.g.Practitioner,DocumentReference) and the third-party consumer-onboarding process are deferred until a concrete licensing consumer requires them — expanding the set is a future decision, not a commitment to omit them permanently.† (#8814)
Cross-feature
- ✅ Reflection keeps logbookContext when linked case deleted (#5051 — see retrospective.md)
- ✅
logbook.reflection.searchable-reminder-fields— when a reflection is linked to a surgical logbook entry, the reflection form displays the operation name and hospital number (Pt URN) as read-only reminder fields; reflections are searchable by hospital number, clinical area, and user-defined title. After a case is submitted the reminder shows the decrypted URN taken from thelogbook.getByIdre-read, never the stored ciphertext from the create response, and no URN until that read resolves (#12599).† (See alsoretrospective.mdReflections section.) (#6398) - ✅
logbook.reflection.tag-to-surgical-entry— users can tag reflection entries (learning tidbits) directly to a specific surgical logbook entry, creating a traceable link between the reflection and the case.† (#6399)
Status
| Sub-feature | Status | Notes |
|---|---|---|
| Logbook variant label (page title) | ✅ Built | Switches surgical/procedural — LogbookCase/index.tsx |
| Logbook variant label (other surfaces) | ⚠️ Bug | Nav, dashboard, constants, notifications hardcoded — #5962 |
| Core case entry | ✅ Built | All listed entry bugs closed (#3949, #3974, #3975) |
| Entry validation hardening | ⚠️ Bug | Server-side + numeric min/max gaps — #4880, #4884 |
| Entry reactivity | ✅ Built | All 7 SPO queries invalidated on create/update — closed |
| Dashboard overview | ✅ Built | All listed display bugs closed (#3966, #3967, #3977–#3979) |
| Stats accuracy | ✅ Built | |
| Widget drill-downs | ✅ Built | closed |
| Cog icons (Total + Primary) | ✅ Built | |
| UK import (ISCP) | ✅ Built | |
| Multi-sheet / infinite columns | ✅ Built | |
| Import wizard UX guards | ⚠️ Bugs | #4876, #4877, #4879, #4886 |
| Import metrics integration | ✅ Built | closed |
| Import field fidelity | ⚠️ Bug | patientName hidden in importNotes — #4885 |
| OCR engine | ✅ Built | Azure OpenAI GPT-4o-mini Vision — #4637 |
| OCR enhancements | 📋 Specified | Structured Outputs #5184, DOB reliability #4825 |
| autoCreateProcedures | 📋 Specified | #4647 |
| Duplicate detection | ✅ Built | DuplicateWarningDialog + PrimaryOperatorConflictDialog |
| CSV / PDF export (client-side) | ✅ Built | ExportButton → utils/export.ts |
| Logbook PDF export (server-side) | ⚠️ Bug | Dead code path — #5031 |
| Multi-feedback per operation | 📋 Specified | From Matt Jan 2026 + Apr 2026 briefs |
| Index procedures tracking | ✅ Built | Targets + widget (#7504); per-specialty index groups AND training numbers now sourced from the curricula (#8490) |
| Specialty masterlist re-key (10 lists) | ✅ Eng done | Curriculum structures (#8490) + PP re-key (#8511) + area re-home (#8518); Matt verification pending on #6684–#6705 |
| Multi-consultant retrospective | 📋 Specified | Overlaps retrospective.md |
| Consultant review + sign-off | ✅ Built | Verify + decline/resubmit paths shipped; assessor guard enforced (#6085, #6239) |
| Consultant CPD on sign-off | ✅ Built | Follows earns_cpd_credit (PPT/S-S/S-U) with per-hour minute banking (#12725); no double credit — the consultant's own log wins (#12814) |
| OCR list DOB / Take Photo first | ✅ Built | List OCR reads each row's DOB into the draft (#12723); Take Photo offered first (#12727) |
| Grouped draft to-dos oversight | ✅ Built | Group expands to list each draft with Open / Delete; stepped flow kept (#12724) |
| Widgets verified vs unverified | ⚠️ Drift | Backend split exists, widgets don't render it (Notion demo brief) — #12726 |
| Historic import time-boxed window | ⚠️ Drift | Matt 2026-09-22: limited-time upload, no row cap; no time limit since #12324 — #12423 |
| Partial Procedure (option 2) | ⚠️ Drift | Matt 2026-08-02 go-ahead on #10822; not built (option 3 on hold, #12744) |
| Multi-participant surgical case parent | ✅ Built | New surgical_case parent table + surgical_case_id on activity |
| WBA / Reflection / Feedback flow audit | ✅ Documented | Audit-only table in Process — relatedFormService.LogbookHandler |
| Reflection-logbook link on delete | ⚠️ Bug | #5051 — shared with retrospective.md |
| Auto-review feedback visible | ✅ Built | |
| Matt Apr 2026 product expansions | 🟡 Blocked | 3 open questions (Q1, Q8, Q12) — Q3–Q7, Q9, Q10, Q11 answered; Q9 physician dataset seeded from UK IMT list (#8815); token semantics → Q12 |
| FHIR / 2032 Health Blueprint | ✅ Built | FHIR R4 Procedure export + SNOMED CT coding in place; |
| Dashboard: Level of Involvement label | 📋 Specified | AC added 2026-05-13; #6100 |
| Dashboard: Trauma vs Elective pos 2 | 📋 Specified | AC added 2026-05-13; #6098 |
| Dashboard: Adult vs Paediatric (<16) | 📋 Specified | AC added 2026-05-13; #6102 |
| Dashboard: JCST + Case Source removed | 📋 Specified | AC added 2026-05-13; #6101 |
| Dashboard: Principal Procedures all | 📋 Specified | AC added 2026-05-13; #6214 |
| Dashboard: Target Progress → 3M Goal | ✅ Built | merged PR #6237 |
| Display: list/tile toggle | 📋 Specified | AC added 2026-05-13; #6106 |
| Export: report builder | ✅ Built | merged PR #6222 |
| Legacy import onboarding ring-fence | 🟡 Partial | #6334 excludes imported entries from active-engagement (still built, unaffected); Q11's precise 90-day/500-row gate (built by #11774) was removed entirely by #12303 |
| API interface specification + token | ✅ Built | #7017: openapi.json artifact + logbook_api_tokens (0113) + Bearer auth; token semantics → Q12 |
| Add-retrospective control | ✅ Built | #6392 built the button+dropdown; #8191 (2026-06-03) reversed it back to visible inline multi-select tick-boxes — Matt to confirm |
| User case targets (profile setting) | 📋 Specified | AC added 2026-03-18; profile-level target config |
| Import: flexible column matching | ✅ Implemented | Levenshtein + alias fuzzy match in columnMappingEngine.ts (#6394) |
| Import: back button / no re-select | ✅ Implemented | Back button at each step; parsed file persists (#3320, #6395) |
| Display: imported vs manual hatch | ✅ Done | #6396; 45° diagonal hatch on imported case cards + list cells |
| Display: case-type button colour | 📋 Specified | AC added 2026-03-25; consistent on-brand colour |
| Reflection: searchable reminder fields | ✅ Built | #6398; operation name + hospital number read-only reminder fields |
| Reflection: tag to surgical entry | 📋 Specified | AC added 2026-05-19; tidbits linked to surgical entries |
| SA LoI reference screen | ✅ Built | Read-only side-by-side LoI reference at /admin/level-of-involvement; consultant placeholder banner + legacy section (#10752) |
Test Files
See Surgical Test Artifacts Reference for test file locations.
| File | Format | Location |
|---|---|---|
| OperationsList.xlsx | UK ISCP/eLogbook | GDrive: Import Test Files/UK |
| 2UKOperationFrequency_8054206_M_Randell_20Oct25.pdf | UK frequency report | GDrive: Import Test Files/UK |
| PPP - Logbook Cases (Combined).xlsx | Australian (13 sheets) | GDrive: Import Test Files/Australian |
| OCR_Operative_List_sample.jpeg | OCR (UK theatre list) | api/backend-ppp/src/services/imageService/__test-images__/ |
| OCR_Patient_Sticker_01..19.jpeg | OCR (AUS sticker x19) | api/backend-ppp/src/services/imageService/__test-images__/ |
Open issues on label:feature:logbook (15)
| # | Title |
|---|---|
| #6684 | review(logbook): ENT / Otolaryngology procedure list — ready for Matt sign-off |
| #6697 | review(logbook): Vascular Surgery procedure list — ready for Matt sign-off |
| #6698 | review(logbook): Urology procedure list — ready for Matt sign-off |
| #6699 | review(logbook): Plastic and Reconstructive Surgery procedure list — ready for Matt sign-off |
| #6700 | review(logbook): Paediatric Surgery procedure list — ready for Matt sign-off |
| #6701 | review(logbook): Neurosurgery procedure list — ready for Matt sign-off |
| #6702 | review(logbook): Oral and Maxillofacial Surgery procedure list — ready for Matt sign-off |
| #6703 | review(logbook): General Surgery procedure list — ready for Matt sign-off |
| #6704 | review(logbook): Cardiothoracic Surgery (Congenital) procedure list — ready for Matt sign-off |
| #6705 | review(logbook): Cardiothoracic Surgery procedure list — ready for Matt sign-off |
| #11350 | logbook: Scan Operating List cases import without procedure classification — 0/5 matched on a real theatre list (Matt WhatsApp 2 Aug) |
| #12628 | feat(logbook): procedure data is organised as a three-level clinically-rele… |
| #12744 | logbook: Partial Procedure option 3 — pick the part performed from standard stages (post-launch, on hold) |
| #12828 | fix(logbook): follow-ups from #12827 review (OCR-only DOB test, numeric DOB parse, row button titles) |
| #12843 | Logbook import: keep Review and Import inside the 4-step wizard (remainder of #12789) |
Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.
Closed Questions (2) — click to expand
| # | Question | Resolution |
|---|---|---|
| Q2 | External lookup function — which source, and what's the post-lookup process to prevent duplication? | Resolved (engineering, 2026-05-12): Source is SNOMED CT via Ontoserver (ExternalSurgeryLookup component → services/fhirApi.searchConcepts). Post-lookup, procedure.createExternal creates a procedure record storing the SNOMED code and display name. Deduplication: if a procedure with the same SNOMED CT code already exists as an external entry (isExternal = true), the existing record is returned — no duplicate is created. If that record has status = 'rejected', an error is thrown to block reuse. Code: api/backend-ppp/src/services/settingsServices/procedures.ts → createExternalProcedure. |
| Q6 | Verification flow — who signs off (consultant present? hospital record?); what happens on reject? | Partially resolved (engineering, 2026-05-12): A consultant signs off via ReviewLogbookCaseForm (forms/LogbookCaseForm/Consultant/), which sets case status to verified. The verify path is built. The reject/decline path is not yet specified or built — see Open Questions Q6 for the remaining sub-question. |
Change Log
| Date | Change | PR/Issue | Reason |
|---|---|---|---|
| 2026-10-04 | The logbook CSV and PDF exports no longer decrypt patient identifiers a second time. getActivitiesByFilter already returns them decrypted, so with encryption on the second pass threw and the export failed. | #12846, #12600 | Found while fixing the Multi-Feature Report logbook count (#12600), which shared the same double decrypt. Both exports now use the same single-decrypt seam as the report. |
| 2026-10-04 | When no expected completion date is set, the logbook pace strip now adds a note under the coaching line ("Paced over a default of 5 years. Add your expected completion date in My Profile to change it."). The pace-status tooltip says the goal uses the 5-year default, and it describes the chip instead of replacing its visible label as the accessible name. The My Profile 5-year caption is shortened to "Based on a default of 5 years. Add your expected completion date to change it." | #12778, #12736 | Design review of PR #12778 (round 1 FAIL). A red "Behind pace" status built on an assumed 5-year plan gave no visible cue that it rested on a default, and the tooltip still credited the "expected completion date". The caption wrapped to three lines at 375px. |
| 2026-10-04 | The full-platform dashboard's Outstanding Onboarding checklist now shows the "Partially complete — N imported cases still need a procedure/hospital match reviewed" note beside the "Import your logbook" step. Before, only the CPD-only checklist rendered it, and CPD-only users never get the import step, so nobody saw it. Both checklists now take the text from one helper. | #0, #10130, #11186 | Matt (#10130, 2026-07-07) asked for a "partially complete" note with the number left to resolve after an import. The count was computed by the backend but dropped by the dashboard section (Task 5 #11186 checklist T5-28). |
| 2026-10-04 | The post-case Personal Reflection reminder takes its URN only from the decrypted logbook.getById re-read, never from the activities.create insert row, which carries the stored (ciphertext) URN once PII encryption is on. The reminder shows no URN until the re-read resolves. No AC wording changes (logbook.reflection.searchable-reminder-fields already requires the real URN). | #12599 | Found on UAT during the #10561 walkthrough: the dialog showed the ciphertext URN. The create response is the raw insert row; only the read path decrypts at the API boundary. |
| 2026-10-04 | Import validation counts now reconcile for large files. The multi-chunk preview summed duplicates, invalid and skipped rows but not validated rows, so the headline showed the first chunk only (validated and duplicate counts did not add up to the file's rows). The procedure match breakdown on the validation and success summaries now lists every category (abbreviation, similar and auto-created were missing, so the totals did not add up to the rows considered). | #12789 | UAT practice run (3 Oct 2026) with a large workbook. The wizard still hands off from Review to the older import dialog (the documented two-dialog pipeline, #10599); moving Review and Import inside the 4-step wizard is not done here. |
| 2026-10-04 | The procedure matcher's similarity tier no longer offers a best guess that names a different procedure. A candidate is rejected when the description and candidate disagree on side (left vs right), or when each holds a distinguishing word the other lacks (a different joint or bone, DISTAL vs PROXIMAL). One side merely adding detail still matches. Applies to both the cached and database matching paths. Rejected rows fall to an unmatched warning for manual pick. | #12790 | UAT practice run (3 Oct 2026) offered a best guess for a different anatomical region at 72% because the abbreviation expansion of ORIF shares four tokens with every fixation procedure. The score itself is unchanged (no token weighting), so a surviving suggestion can still show a confidence inflated by shared words. |
| 2026-10-04 | Import preview shows Excel date cells as dd/mm/yyyy instead of serial numbers. Date-formatted cells are converted on read (workbook now read with number formats), and a bare serial in a Date-named column is shown as a date in the Upload preview. Stored dates were already correct (the importer parses both dd/mm/yyyy and serials); a unit test now asserts the previewed text and the raw serial import as the same calendar day. | #12791 | UAT practice run (3 Oct 2026) showed the preview Date column as serial numbers for real Excel date cells. A serial number in a column that is not named like a date still previews as a number; the Map Columns sample tooltip is unchanged. |
| 2026-10-04 | The import wizard now masks patient identifiers on screen. The Upload preview shows a Patient Name column as initials and a Date of Birth column as dots, and the Map Columns source-chip sample tooltip masks them the same way. This matches the banner promise in logbook.import.patient-name-initials-only that only initials are imported. | #0, #12792, #11186 | The Upload preview and the sample tooltip printed raw full names and dates of birth, contradicting the on-screen privacy banner (Task 5 #11186 recording checklist T5-07). |
| 2026-10-04 | logbook.entry.specialty-scoped-surgery-picker: ticking Other Specialties now really widens the picker for a procedural (non-surgeon) doctor. Before, clearing the specialty scope was mistaken for "user has no specialty" and the picker fell back to the 17-item practical default list. AC wording unchanged. The second issue AC (resolving out-of-specialty imports without changing specialty) rests on the same toggle; the persona seeding the issue suggests is not built here. | #12793 | SMAN demo practice run on UAT (3 Oct 2026), IMT physician persona: Other Specialties still returned No options for "knee". Live BDD before the fix: the picker stayed at 17 options after the toggle. |
| 2026-10-04 | The Add / Edit Logbook Case Hospital field keeps the name of a hospital picked from the live search results after the field loses focus. The saved hospital id was always correct; the box went blank because the picked option was only resolved from the preloaded hospital list. No AC wording changes. The ASA half of the issue does not reproduce: the ASA picker maps option 2 to the stored and displayed value 2 (constants/asa-grade.ts). | #12797 | SMAN demo practice run on UAT (3 Oct 2026): the Hospital input read back empty after choosing a hospital. Live BDD run before the fix reproduced it (expected the picked hospital name, received an empty string). |
| 2026-10-04 | The logbook quarterly goal (three-month pace) now divides by the doctor's own "years to complete" when there is no CCT date, falling back to the labelled 5-year default only when none is entered. | #12813, #11144 | Rob, 4 Oct 2026 on #12813: "use the CCT date when one exists; otherwise show an editable 'years to complete' field, pre-filled with 5". The profile pace, the logbook quarterly goal and the Roadmap surgical milestone must agree. |
| 2026-10-04 | A consultant who signs off a trainee's case and also logged their own entry for the same operation (same surgical-case parent) is now credited once. Their own log wins and the sign-off adds no extra supervising CPD. | #12814 | Rob, 4 Oct 2026 on #12814 answered Q-signoff-cpd-double-credit - credit once, the consultant's own log wins. Both cases used to enter the minute-banking pool and the operation was credited twice. |
| 2026-10-04 | logbook.ocr.operating-list-dob: an OCR-read DOB is parsed strictly as DD/MM/YYYY or ISO (YYYY-MM-DD); anything else, including a numeric-only value such as 1971 (previously read as an Excel serial date), stores no DOB. Spreadsheet imports still store no DOB. Both rules now have integration tests. No AC wording changes. | #12828, #12827, #12723 | Review findings on #12827: the OCR-only guard was untested and a numeric DOB was silently stored as 1905-05-23. |
| 2026-10-03 | The logbook pace monitor no longer needs an expected completion date. With a stored training target and no date, the quarterly goal is paced over the 5-year default, matching the profile read-out. An elapsed date still shows no goal. logbook.dashboard.pace-monitor-visibility updated. | #12778, #12736 | Matt (#11144, 2026-09-21) - "Default to 5 years". The backend gauge and the profile read-out disagreed (blank gauge vs a 5-year pace). The constant is now shared (DEFAULT_TRAINING_YEARS). |
| 2026-10-03 | logbook.entry.todo-group-individual-oversight flipped from drift to built — a grouped draft to-do expands to list each draft (operation text and case date, from new procedureLabel/caseDate work-queue fields) with per-case Open and Delete; the stepped flow is unchanged as the bulk path. | #12724, #11183 | Matt, 2026-08-04 catch-up (~00:32:57): the grouped tile only opened "the next in line" with "no oversight to be able to select exactly the one that you want"; he asked for a drop-down showing each case so it can be actioned or deleted "if it''s an error". Also 2026-07-14 (~00:08:18). Overlaps Task 15 (Action Items, #11217): the grouped row''s existing behaviour is kept, only the expand is added. |
| 2026-10-03 | logbook.consultant-review.cpd-credit-on-sign-off drift closed. Sign-off supervising credit now qualifies off the admin earns_cpd_credit flag (seeded PPT/S-S/S-U, so S-H no longer earns credit) and is computed from operative minutes with per-hour minute banking, pooled with the consultant's own-case credit by syncSignOffSupervisionCredit. A recompute also removes the consultant's pre-#12725 sign-off rows so each case is credited once, and editing or deleting a signed-off case re-banks the assessor's year. Issue AC3 (no double credit when the consultant also logs the operation) is split to #12814, blocked on Q-signoff-cpd-double-credit, which remains open. | #12725 | Matt's #9200 rulings (2026-07-21 LoI set, 2026-06-24 per-hour rule) were only applied to the self-LoI path; the sign-off handler still used the hard-coded S-S/S-U/S-H list and rounded hours. |
| 2026-10-03 | logbook.ocr.operating-list-dob flipped from drift to built — the operating-list OCR schema and prompt ask for each row's DOB (null when not legible, never guessed); the scanner shows an editable DOB column and sends DOB and patient name to the import; OCR-created drafts persist the DOB through the encrypted dob_patient path and keep only the patient's initials. | #12723, #11183 | Matt, #8652 (2026-06-24): "It doesn''t appear to extract dob which is required for adding a case"; 2026-07-14 and 2026-08-04 catch-ups: DOB still not coming through — "Let''s build for now … date of birth, hospital ID, and the patient''s initial". DOB persistence is scoped to OCR imports; spreadsheet imports are unchanged. Age-at-surgery-only storage remains Q-ocr-age-only-storage. |
| 2026-10-03 | Task 4 spec refresh against Matt's latest dated statements. Added ACs: consultant CPD on sign-off (built, drift #12725), attached-forms CPD for both users (partial, WBA leg #12712), operating-list DOB (drift #12723), Take Photo first (drift #12727), grouped draft to-dos individual oversight (drift #12724; revises todo-grouped-stepped-flow), widgets verified vs unverified (drift #12726). Open Questions Q-ocr-procedure-match, Q-signoff-cpd-double-credit, Q-ocr-age-only-storage. | #11183, #12723, #12724, #12725, #12726, #12727, #12712, #11350 | Async Task spec refresh (#11183). Newest dated Matt statement wins: 2026-06-03 stepped flow (#8101) superseded by 2026-07-14/2026-08-04 "no oversight… see the individual… action it or delete it"; OCR DOB restated 2026-06-24 (#8652) → 2026-07-14 → 2026-08-04 ("build for now DOB, hospital ID, initials"); consultant sign-off CPD from the Notion PPP and CPD Demo brief + #11183, constrained by #9200 (2026-06-24 per-hour; 2026-07-21 PPT/S-S/S-U, S-H NO). Spec-only, no BDD (scenario requirement is on each fix issue). |
| 2026-10-03 | Task 5 spec refresh (historic logbook import) against Matt's latest dated statements. Added ACs: time-boxed onboarding import window with no row cap (drift #12423), DOB-derived patient category <16 Paediatric (built, #9846), categorise from matched operation not source category columns (built, #9829), Partial Procedure option 2 recorded for skill, not primary, counts toward total (drift #10822; option 3 on hold #12744). Marked PP drop-out in ppp-involvement-vernacular and the LoI admin reference as superseded. Added Matt #365 citations to imperfect-data-no-fail and origin.three-way. Open Questions Q-import-window, Q-import-notes-mapping, Q-import-onboarding-effort, Q-import-national-format. | #11186, #10822, #12423, #12744, #9829, #9846 | Async Task spec refresh (#11186). Newest dated Matt statement wins: import ring-fence 2026-05-13 → 90d/500-row build (#11774/#11804) → Rob removed both 2026-09-20 (#12303) → Matt 2026-09-22 "limited time … but not 500" (row cap stays removed, time box restored as a requirement). PP: dropped 2026-06-24 (#9187) → on hold 2026-07-21 (#9200) → option 2 go 2026-08-02 (#10822). Spec-only, no BDD (scenario requirement is on each fix issue). |
| 2026-10-03 | logbook.ocr.take-photo-first flipped from drift to built — Scan Operating List and the patient-sticker uploader now offer "Take Photo" before "Choose Image" (Choose Image still available). Take Photo is the contained primary action and Choose Image the outlined neutral one (design-system.button.variant-emphasis); with no camera, Choose Image stays primary. | #12727, #11183 | Matt, 2026-07-14 catch-up (~00:06:55): "I wanted to switch take photo and choose image because often we''ll take photo will be the first option." Both upload surfaces rendered Choose Image first. |
| 2026-10-03 | logbook.dashboard.verified-unverified-states flipped from drift to built — the Level of Involvement and Primary vs Secondary widgets show a verified / unverified count line that partitions their existing total; getSupervisionBreakdown now returns verified/unverified per category. | #12726, #11183 | Notion "PPP and CPD Demo" brief (2026-04-21), Logbook step 7: "observe states of unverified and verified log in logbook on widgets and in log". Closed Q6 (Rob, 2026-05-21): unverified/declined entries count toward totals but are visually distinguished. The backend split existed for Primary vs Secondary but no widget rendered it. |
| 2026-10-03 | WhatsApp top-up for the Task 4 spec refresh (OCR operating list and logbook entry lifecycle). Q-ocr-procedure-match now cites Matt's 2026-08-11 and 2026-08-12 WhatsApp messages, where he again deferred #11350 to a call, and says that call was cancelled. Its "no later statement" claim now covers WhatsApp too. No AC changed. The 2026-07-24 WhatsApp OCR screenshots are already the sources behind logbook.ocr.upload-size-limit-consistency (#10918), logbook.import.dedupe-decrypt-resilient (#10919) and logbook.ocr.epr-screen-photo-input (#11484). | #11183, #11350 | Async Task spec refresh. Phase A ran without Matt's WhatsApp messages. This top-up checked them, and no WhatsApp statement adds or supersedes a logbook requirement. |
| 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 (it earns supervising/teaching CPD credit), 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-20 | Removed the Import Logbook onboarding ring-fence entirely: the 90-day account-age window and the 500-row cumulative cap built by #11774/#11804 (Q11) are gone. The Import Logbook entry point is now always visible; the generic 5,000-row MAX_IMPORT_ROWS technical sanity ceiling is unchanged and is now the only row-count guard on this flow. | #12324, #12303 | Rob's explicit, direct product decision — 'Remove the 90 day 500 row import limit' — stated verbatim in the session that produced #12303. Not inferred or second-guessed. |
| 2026-08-30 | A grouped to-do row's title now names the status its members share, refining the "Complete N <type> drafts" row introduced by the grouped stepped flow (#8101) so that two groups of the same record type differing only by status are distinguishable, and a group of completed records is not called "drafts". | #12089, #11217 | The grouped-row title built by buildGroupTitle is shared by every record type that groups, logbook cases included. Grouping keys on type:wbaType:status, but the title used only the type — surfaced on live UAT during the #11217 walkthrough as two identical "Complete 2 Timesheet drafts" cards. |
| 2026-08-29 | Closed two genuine bypasses of the #11804 cumulative legacy-import row cap found in review: (1) a TOCTOU race — concurrent executeWizardImport calls all read previouslyImportedCount before any insert committed, so N parallel calls could each pass the cap check and import N × 500 rows; fixed with a per-user pg_advisory_lock (same namespace as importSurgicalLogbook.ts's #9998 lock) serialising the count-then-insert. (2) The cap counted live activities rows only, so a user could hard-delete their own imported rows via activities.delete (ownership-only guard, no isImported exclusion) to reset the counter and re-consume the cap indefinitely; recorded as an accepted, explicit product trade-off (resettable-by-design) rather than solved with an append-only ledger, pending a follow-up decision. | #11973, #11804 | security-auditor review of #11804 found both DB-race findings were genuine bypasses of the cap the issue exists to enforce, reachable by any authenticated user with no special access — not advisory/minor as first triaged. |
| 2026-08-25 | Built Q11's precise onboarding-import ring-fence: the Import Logbook entry point is hidden once the account is more than 90 days old (server-side backstop in executeWizardImport even against a direct call), and a legacy import within the window is capped at 500 rows — distinct from and well under the generic 5,000-row MAX_IMPORT_ROWS technical ceiling. Added logbook.import.onboarding-window-and-row-cap AC. | #11774 | discovered as a gap during the Async Task Model Task 5 (#11186) click-through review of the Historic Logbook Import flow — Q11 had been answered (Rob, 2026-05-21) but only the active-engagement-metric exclusion half (#6334) was ever built; the button-visibility and row-cap gate were never implemented. |
| 2026-08-22 | Backfills surgical_case.reference for rows written before #11188, re-hashing the legacy plaintext URN+day+procedure composite onto blindIndexComposite so no row in the table still carries a plaintext dedupe key (logbook.case.patient-identifier-encryption-at-rest). | #11716, #11202 | #11188 fixed new writes but explicitly left existing rows unremediated — the spec's own AC named #11202 as the pending follow-up. This closes that gap: idempotent backfill (a row already matching the new hash format is a no-op, mirroring #10734's re-plan-is-no-op contract), proven by a .first-apply.validate.sql sibling per the data-only-backfill convention (#10172). |
| 2026-08-16 | Flipped logbook.fhir.snomed-data-cleanup ⏳ → ✅. The AC text still cited "NCTS-confirmed validity is deferred to #7320" from when the test file was first written; #7320 (NCTS auth), #8876 (AU masterlist re-key) and #8877 (authoritative re-validate against the pinned AU edition) have all since shipped and closed, so the deferral no longer holds. Added a regression test asserting the NCTS-confirmation mechanism (isNctsConfigured, classifyAuRekeyResult) is wired, and a companion test confirming the static *-db-ready.json seed fixtures deliberately carry no snomedEdition/snomedVersion provenance — that provenance is written by the re-key to the live procedures table, not the checked-in seed JSON, so the spec text is explicit about which artefact "confirmed" applies to. | #11594, #11589 | re-derived the AC status against current HEAD before building anything (per CLAUDE.md "Verify Epic Scope Before Building") — issue #11589 (a sgd-gap-analysis re-file) asked to implement NCTS-confirmed validity, but that work was already delivered by the #7320/#8876/#8877 chain; the spec line was simply left stale at ⏳ after those PRs merged without updating this AC. |
| 2026-08-15 | Scan Operating List now treats a photograph of an EPR monitor as a first-class input alongside a printed theatre list (logbook.ocr.epr-screen-photo-input), and a scan that succeeds while reading zero cases is reported honestly instead of as a success followed by a generic import failure (logbook.ocr.unreadable-image-honesty). | #11578, #11484 | #10919 shipped the printed-theatre-list layout and explicitly deprioritised the EPR-screen case as 'a harder secondary case worth a lower bar of support', so its ACs only require the printed layout to extract. Rob's 2026-08-11 decision on #11141 put both input types in scope. |
| 2026-07-31 | verify-extractions.py --fetch now verifies a pinned sha256 on EVERY run, not only a slug's first. The cache short-circuit ran before the download, so a re-run honoured whatever bytes sat in TXT_DIR — including an extract synthesised from the committed JSON itself — and reported OK having checked no hash. A pinned slug always re-downloads; --no-cache extends that to unpinned slugs. Separately, the plain-form level-4 PBA assertion is now anchored to the count's CLAUSE rather than the bare N PBAs phrase, so an extraction naming the wrong phase's figure is rejected. | #11259, #11135 | The logbook.fhir.curriculum-structures AC states the verifier re-downloads each source.publicIdenticalDocument, verifies the pinned sha256 where a curriculum records one. That was literally true only from a clean checkout: on any re-run the pin was never checked. The AC's claim now holds unconditionally. |
| 2026-07-29 | surgical_case.reference (the surgical-case dedupe key) no longer stores the patient URN in the clear. deriveSurgicalCaseReference now HMACs the urn|isoDay|procedureId composite via a new blindIndexComposite primitive (pii-crypto.ts), sharing the same blind-index secret patient_urn's urn_hash already uses, gated by assertPiiEncryptionWritable() so it fails CLOSED (not silently plaintext) exactly like #11111. findOrCreateSurgicalCase's existing-row lookup now checks both the new HMAC form and the legacy plaintext composite (dual-read, mirrors the urnStorageMatch/#10734 cutover pattern) so a participant joining an already-existing pre-#11188 case still links to it. | #11203, #11188 | Found during the #11171 merge-gate review (tracked as #11188): surgical_case.reference (varchar(512) NOT NULL UNIQUE, indexed) was persisting ${urn.trim().toLowerCase()}|${isoDay}|${procedureId} verbatim in plaintext, on the SAME row where patient_urn is AES-256-GCM encrypted — a plaintext sibling column defeating that row's own encryption-at-rest for anyone with raw DB read access (a DB dump, backup theft, or read-only analytics access). |
| 2026-07-29 | Patient-identifier encryption (urn/gender/dob_patient, surgical_case.patient_urn) now fails CLOSED, not open, when the AES key or blind-index secret is missing. A new PPP_PII_ENCRYPTION_MODE=required|optional switch (default required) drives a shared write-path gate (assertPiiEncryptionWritable) that every logbook identifier write seam now calls instead of branching on isPiiEncryptionEnabled() directly — a deployed environment missing the secrets now refuses the write with a clear error instead of silently persisting plaintext PII. Local dev keeps working unchanged by explicitly opting into optional mode. | #11171, #11111 | Found during the #11070 merge-gate review (inherited #10730 design, not introduced by #11070). isPiiEncryptionEnabled() is a pure presence check, so it could not distinguish "deliberately unencrypted" (local dev) from "supposed to be encrypted, key just missing" (a deployed environment with an absent/misconfigured secret) — both produced the same false, so a missing key in a deployed environment silently wrote plaintext patient identifiers with no error, no warning. A key that is present but malformed already failed loud; only a missing key failed silently, in the worst direction for PII. |
| 2026-07-28 | Corrected a false novelty claim repeated in seven places (spec AC, the ORTHOPAEDIC_SURGERY_CLASSIFICATION doc comment, the parser doc comment, the backend unit test, the BDD scenario comment, the source fragment, the curriculum JSON's extractionNotes) that T&O was the first extracted curriculum to state an explicit level-4 PBA count. Urology already does — UROLOGY_CLASSIFICATION has carried requiredLevel4PbaCount: 9 on all six of its principal procedures since #9123, and the immediately preceding AC bullet in this same spec says so. What is actually new is the FORM: T&O states its count as an N x Level 4 PBAs multiplier, which is the wording parseRequiredLevel4PbaCount could not read. The backend test now asserts Urology's 9 alongside T&O's 3/1 so the distinction is enforced rather than narrated. Also extended verify-extractions.py to check the level-4 PBA count each involvement states against the source text (an adjacency check on the matched phrase, not a bare-number tripwire), replaced its hardcoded personal default path with a repo-relative one, added --fetch and per-slug reporting so it is reproducible from a clean checkout, and de-overstated logbook.md's claim that it gates anything; added the curriculum paths to logbook.md's code-paths: so the spec-drift gate can see them; added a zero-match RAISE NOTICE and an acknowledged LIKE 'orthop%' under-match note to migration 0222; and made stripSqlComments strip comments inside a DO $$ … $$ body, closing a hole that let a migration step satisfy a substring assertion on prose instead of SQL. | #10999, #10945, #9123 | Raised by the #10999 merge-gate review, which withheld the gate on the self-contradiction. Two adjacent acceptance criteria asserting incompatible things about which curricula state an explicit count is exactly the defect this PR withheld its own gate for one commit earlier, and the false claim sat in a production doc comment 600 lines above the UROLOGY_CLASSIFICATION that contradicts it — the failure path being an engineer who reads it, concludes a non-null requiredLevel4PbaCount is Orthopaedics-only, and branches on it. The verifier changes close the other half: involvement is the field #10945 made load-bearing (its digit becomes a trainee-facing requirement) and it sat outside the fidelity check that logbook.md cited as covering every figure, run from a path that existed on one machine. |
| 2026-07-28 | Corrected the Index Procedures example in logbook.md, which attributed "20× Major Joint Arthroplasty cases" to the Orthopaedic specialty curriculum. The curriculum extraction delivered by this same PR gives an indicative 80 for Major joint arthroplasty (ISCP/JCST Trauma and Orthopaedic Surgery Curriculum v2, Appendix 4d), so the spec asserted two different curriculum-attributed figures for the same procedure — in the very file the PR edits to de-stale its Orthopaedic claims. The sentence now cites 80 and names Appendix 4d as the source. The separate mention at logbook.index-procedures.user-target-volumes is deliberately left at 20: that one illustrates a target a USER sets in their own plan, which is not a curriculum claim and is not contradicted. The unverifiable "60 underlying procedure rows" in the same sentence was dropped rather than restated, since nothing in this PR establishes that count. | #10999, #10945 | Caught by the #10999 merge-gate review, which withheld the gate for it. A spec that states two different curriculum figures for one procedure is worse than one that is silently stale: a reader has no way to tell which is authoritative, and this file is the engineering translation other work is built from. The corrected figure is not inferred — it is the indicativeNumber in the curriculum JSON this PR adds, whose source PDF the reviewer verified byte-for-byte by sha256 against the cited ISCP document. |
| 2026-07-26 | Added logbook.training-totals.orthopaedic-curriculum — Orthopaedic Surgery, the sole seeded surgical speciality the #8490/#8468 extraction wave never covered, now has a curriculum-structures/orthopaedic-surgery.curriculum.json like its nine siblings, so its trainees get the same critical-conditions widget, "Numbers Required for Completion" widget and whole-of-training cadence prefill everyone else already had. Extracted from the ISCP/JCST Trauma and Orthopaedic Surgery Curriculum v2 (August 2024, the document Matt supplied on 2026-05-19) and verified by the committed verify-extractions.py: 14 critical conditions (Appendix 3), 13 index-procedure groups whose indicative numbers sum to the curriculum's own stated Total 365 (Appendix 4), an indicative 1800 total operations / 1260 as first surgeon, the eight clinical areas (section 2.3) and the verbatim Table 3 certification wording. Consumed by exactly the same helpers as its siblings, with no special-casing. parseRequiredLevel4PbaCount gained a reader for the N x Level 4 PBAs multiplier form T&O states its counts in (3 per operation group; 1 for the two Appendix 4e exceptions) — a new FORM, not a new kind of claim: Urology has reported an explicit count of 9 since #9123. Both #9123 anti-fabrication traps stay green. Because speciality.critical_conditions has two write paths and seedSpecialitiesIfEmpty only populates a FRESH database, backfill migration 0222_orthopaedic_critical_conditions_backfill carries the same array to existing rows on UAT/prod (the shipped-once gap 0213 was raised to fix, #10776), writing only rows still empty so an admin edit is never clobbered. Resolves logbook.md Q14. | #10999, #10945, #9123, #8490, #8468 | #10945 — Orthopaedic Surgery was the only seeded surgical speciality absent from specialty-critical-conditions-config.json, curriculumTrainingDefaults.ts and the SPECIALTY_PROCEDURE_CLASSIFICATIONS registry, so orthopaedic trainees silently lost three curriculum-driven surfaces that every other speciality had. This was a genuine engineering extraction gap, explicitly NOT a question for Matt (he had already supplied the source PDF), and closing it needed no new data shape — the same mechanical extract-and-verify pass already run nine times. Nothing was invented: the extraction is verified three independent ways (verify-extractions.py against the source text; the 13 indicative numbers summing to the curriculum's own stated Total 365; and two corroborations against data Matt has already signed off — the 1800/1260 figures matching gap-sheets/audit-summary.md, and 12 of the 13 Appendix 4 groups already being represented among the principalProcedure values on the 567 Orthopaedic rows in procedures.json, the masterlist Matt froze as the model for every other speciality — a concept correspondence rather than string equality, since only 4 match verbatim, 3 differ only in capitalisation and 5 appear there solely in abbreviated form). The one caveat is recorded in the file's extractionNotes: Matt's Drive copy is access-controlled, so — unlike the other nine, whose Drive filenames matched the public documents exactly — byte-identity with his copy could not be confirmed, and the current ISCP-published document was used instead. |
| 2026-07-26 | Bulk backend-only curriculum reference data moves from packages-shared/ppp/src/constants/ to packages-shared/ppp/src/curriculum/, behind a new @ppp-org/ppp/curriculum package export. Affects the code: citation paths for logbook.training-totals.curriculum-default, logbook.training-totals.critical-conditions-wba, logbook.training-totals.principal-procedure-classification and logbook.fhir.congenital-flat-classification. No acceptance criterion changes. | #10984, #10962 | Issue #10962: the four modules holding this data (specialtyProcedureClassification.ts, specialtyCriticalConditions.ts + its 45 KB JSON asset, curriculumTrainingDefaults.ts, competencyTargets.ts) were exported from the shared @ppp-org/ppp/constants barrel, which instances/ppp imports from ~120 modules. A single module-level side effect anywhere in that chain — a top-level new Map(...), new Set(...), Object.freeze(...) or sort — is a side effect Rollup must retain, and retaining it retains the entire data chain behind it, re-pinning ~125 KB of curriculum source into the frontend EAGER bundle that no UI path consumes. That is not hypothetical: #9123 / PR #10950 took the eager payload from 706 KB to 720 KB gzip against a 722 KB budget. Memoising each index fixed that instance but was local and re-breakable. Splitting the data behind its own package export makes the leak structurally impossible instead of review-dependent. Measured with the repo bundle-budget gate: reintroducing BOTH module-level new Maps costs +14 KB before the split (706 -> 720 KB) and 0 KB after it (705 -> 705 KB), with no curriculum marker present in any eager chunk. |
| 2026-07-26 | Logbook now formally owns the surgical-logbook import wizard services (importExecutionService, importWizardService) in its code-paths, moving them off Exportable Reports' broad directory glob. | #10980, #10975 | Both services are Logbook concerns — one batch-inserts logbook case activities, the other validates surgical logbook import rows — but they sit under services/reports-and-export/ by directory accident, so the spec-drift gate demanded an Exportable Reports update for import changes. That spec has no mention of import, dedupe, or import warnings; Logbook already documents them. |
| 2026-07-26 | checkPrimaryOperatorConflict no longer fetches the conflicting clinician's name at all — the users innerJoin and the firstName/lastName selects are dropped, the query is now an existence probe over activities alone, and PrimaryOperatorConflictResult is reduced to { hasConflict: boolean }. | #10972, #10949 | Follow-up to #10936 raised by the #10941 merge-gate review. #10936 made the CONFLICT message static, but the name was still read from the DB and left resident on the returned object purely to be discarded — so the guarantee rested on the message-construction path plus a doc-comment MUST-NOT rather than on the data flow, and one future logger.debug({ conflict }) would have re-leaked it to the structured log sink and the Discord webhook. Row matching is unchanged: activities.userId is a FK with ON DELETE SET NULL and the existing ne(userId, currentUserId) condition already drops NULL-user rows, so the removed join excluded nothing. |
| 2026-07-26 | Three security-review follow-ups to the #10919 import-dedupe resilience fix. (1) readStoredUrnLenient now takes the existing row's id and returns a per-row sentinel __UNDECRYPTABLE_ROW__<rowId> on decrypt failure instead of null. (2) Both cross-import dedupe paths (importSurgicalLogbook.ts, importExecutionService/index.ts) emit an error-level *_IMPORT_DEDUPE_SYSTEMIC_DECRYPT_FAILURE log when every existing case fails to decrypt, gated on a 3-row minimum so a tiny cohort cannot false-trigger it. (3) A new shared predicate isDedupeIncompleteWarning (@ppp-org/ppp/constants) scopes the persistent-warning treatment (a persist: true snackbar plus the standing Alert on the results screen) to the dedupe-incomplete warning alone, instead of applying it to the whole backend warnings array. | #10969, #10968, #10919 | #10919 made a decrypt-failed row fall back to null so one bad legacy row could no longer abort a whole import. But caseKey folds a null/absent urn to '', and a genuinely blank-URN existing row already collapses to that same '' key — so a decrypt-failed row silently collided with any unrelated blank-URN row (or another decrypt-failed row) sharing the same day + operation text, and was treated as a duplicate of it: excluding a row from dedupe had turned into inventing a false match. The sentinel's uppercase-underscore prefix cannot be produced by real URN normalisation (sanitizeOcrPatientNumber et al.), so it only ever matches itself. Separately, one failing row is the ordinary case #10919 targets, but every row failing at once is a systemic signal (a rotated or misconfigured PPP_PII_ENCRYPTION_KEY) and degrading an entire cohort to duplicate-blind in silence is the exact 'loud failure becomes silent corruption' outcome that fix existed to prevent. Finally, #10919's persistent warning display was applied to the whole warnings array, which is general-purpose and includes the pre-existing #9846 date-of-birth parse warning that echoes a RAW PATIENT DOB — pinning that on screen indefinitely would have created a new PII-exposure surface, so persistence is now scoped to the one warning that needs it. |
| 2026-07-25 | Made MAX_IMAGE_FILE_SIZE_BYTES the single 10MB source of truth across the frontend upload validation, the blob-upload gate, and the OCR image-fetch gate (previously the fetch gate alone still enforced a stale 5MB Lambda-era limit); and made the logbook import's cross-import dedupe scan tolerate an existing case whose stored patient identifier fails to decrypt, excluding just that row instead of aborting the whole import, with a plain-language warning when it happens. | #10943, #10918, #10919 | Matt UAT (2026-07-24): "Scan failed: Image exceeds maximum allowed size of 5MB" rendered directly above the feature''s own "Max size: 10MB" copy (#10918); and "Import Failed - No cases were imported" after an OCR extraction that production logs proved had already succeeded (casesExtracted:6) - the real failure was a decrypt crash on an unrelated existing row inside the dedupe-key-building loop, aborting the entire import (#10919). Confirmed via Log Analytics that the two bugs are independent, not cause-and-effect. |
| 2026-07-25 | The primary-operator CONFLICT message no longer names the conflicting clinician — both the create and update throws in activitiesCrud.ts now use a static, non-identifying string ("Another clinician is already recorded as the primary operator for this case...") instead of interpolating Dr. ${firstName} ${surname}. | #10941, #10936 | Found by the #10927 merge-gate review (DPIA-4 chain): the interpolated name reached the requesting user's dialog verbatim, the structured log sink, and the live Discord webhook unredacted — person names have no reliable regex pattern, so onError.ts's #10907 pattern-scrub structurally cannot catch this. Fixed by construction at the source rather than by redacting downstream. |
| 2026-07-25 | Populated SPECIALTY_PROCEDURE_CLASSIFICATIONS for all 9 specialities with an extracted curriculum (Principal Procedures, level-4 PBA sign-off, Critical Conditions requiring a WBA), added verbatim criticalConditionCertification/indexProcedureCertification per specialty, and fixed two latent parseRequiredLevel4PbaCount bugs that would have fabricated a level-4 PBA count from a competency-level digit or an ambiguous cross-level total. | #9123, #10945 | Matt's 2026-06-28 review comment asked engineering to list, per specialty, the critical conditions required as WBAs (confirming the level-4 single-assessment rule) and all index procedures with the level-4 PBA count required for certification. The data was already extracted and verified under #8490/#8468 but never wired into the SPECIALTY_PROCEDURE_CLASSIFICATIONS registry the #6704 Cardiothoracic (Congenital) entry was designed for — only that one entry existed. Orthopaedic Surgery remains a genuine, tracked extraction gap (#10945): no curriculum-structure JSON exists for it in this repo, so it is correctly absent rather than fabricated. |
| 2026-07-22 | Added a Responsible-Consultant Cases section to the consultant's own profile — a header count of cases where they are the responsible consultant (assessorId), plus scope-of-practice "delineations" (procedure category → index procedure) and a level-of-involvement secondary breakdown, for a selectable period. Surgical outcomes are deliberately excluded and no patient identifiers are shown. | #10846, #10823 | Matt''s NBB on #9200 (2026-07-21): collect in the consultant profile the number of cases and delineations for cases where they are listed as the responsible consultant. "Responsible consultant" = assessorId (distinct from cpdSupervisorId). "Delineations" grounded by best-in-class credentialing research (RACS/ISCP/ACS/ANZASM) as surgical scope of practice / delineation of clinical privileges, not inferred (SGD audit protocol). |
| 2026-07-22 | Added logbook.entry.consultant-loi-doctor-facing-wiring — the override-aware resolveConsultantLoiLabel resolver (#10758) is now wired into every doctor-facing consultant Level-of-Involvement surface, not only the admin reference screen: the add-case dropdown, the consultant/non-consultant reviewer sections, the case table column, the case card + list-view tooltip, and the CSV export, via a new resolveLoiDisplayLabel dispatcher and useConsultantLoiOverrides hook reading the pre-existing doctor-facing logbook.consultantLoiLabelOverrides query. Updated logbook.entry.involvement-vernacular (#8473) to record that the consultant Primary/Secondary bucket vernacular is now superseded for consultants (the add-case dropdown shows the override-aware PPP label instead). | #10837, #10076 | resolveConsultantLoiLabel was only ever consumed by the admin reference screen — every doctor-facing surface still rendered the raw code-derived involvementDisplayLabel and never consulted loi_label_overrides, so a super-admin's label override was invisible to doctors. This closes the engineering-mechanism side of the Q-consultant-loi for-discussion item without a fresh Matt reply: the labels are admin-editable in-app (#10758) and Matt engaged with the PPP_CONSULTANT_LOI placeholder set on #9200 (2026-07-21) without objecting — the residual was unfinished wiring, not an open product decision. |
| 2026-07-22 | Delivered the final child of the #10721 patient-identifier encryption-at-rest epic — logbook.case.patient-identifier-encryption-at-rest is now marked delivered. A runtime backfill job (backfillPatientIdentifierEncryption + scripts/backfillPatientIdentifierEncryption.ts) encrypts existing plaintext activities.urn/gender/dob_patient + surgical_case.patient_urn in place and populates urn_hash; drizzle migration 0216_encrypt_existing_patient_identifiers anchors it with a .first-apply.validate.sql asserting the ciphertext-implies-urn_hash integrity invariant. The transitional plaintext-tolerant read fallbacks were removed so reads are encrypted-only when the gate is on (readStoredUrn/maybeDecryptIdentifier decrypt unconditionally and fail loud on a stray plaintext value; urnStorageMatch/urnSearchMatch key on the blind index alone). | #10819, #10734 | AES-256-GCM + HMAC-SHA256 need the Key Vault secret and cannot run in raw SQL, so the backfill runs as an app job (following the backfillMissingGeofences pattern) rather than a pure-SQL migration; the validator is .first-apply.validate.sql (#10172) so it can't brick a future deploy on new runtime data. The cutover removes the dual-read fallbacks the sibling stories added transitionally, per the #10721 cutover-readiness audit — with the master isPiiEncryptionEnabled() gate retained so pre-cutover/dev envs still store and read plaintext. |
| 2026-07-21 | The searchSurgicalEntriesByUrn search endpoint (activitiesService/activitiesQuery.ts) now routes its fetched rows through decryptActivityIdentifiersForApiRead(rows, 'activity_list', ctx) before returning, instead of returning the raw findMany result. The URN-match/query conditions are unchanged. | #10814, #10813 | Post-#10797 this search endpoint was the one activity read path in the file still returning rows without the read-boundary decrypt seam its siblings (getActivitiesByFilter, getAllActivities, getActivitiesByType) use, so once #10721 PII encryption-at-rest is on it surfaced ciphertext for urn/dob_patient. This aligns it with the #10797 read-decrypt contract and fires the access-audit via the same seam. Latent (no active frontend caller today) but bites the moment the endpoint is used post-cutover. |
| 2026-07-21 | The UR Number search field now fires the surgical-entry lookup once the user SUBMITS the full URN — on Enter or on blur — instead of a debounced tRPC query after 3 characters on every keystroke. A new submittedTerm state gates the query (enabled: submittedTerm.length >= 3); typing no longer searches, so there is no wasted round-trip per keystroke and no "No surgical entries found" flicker while a valid URN is still being typed (results appear only after submit). Loading/empty states, the #10801 exact-match helper text, and the component's props/contract are unchanged; a "Press Enter to search" hint is added to the existing helper text to surface the interaction. | #10810, #10808 | Under the exact-full-URN search shipped in #10801, only a complete URN matches (the encrypted blind index supports equality only), so searching per-keystroke returned "no entries" until the last character was typed and cost a wasted query on every keystroke. Firing once on submit removes the flicker and the per-keystroke round-trips. |
| 2026-07-21 | The activities.searchSurgicalEntriesByUrn tRPC procedure now scopes its result to the caller. Previously it was a protectedProcedure with no user scoping, so any authenticated user could look up another clinician's logbook case (URN, patient identifiers) by exact URN. It now applies enforceUserScope (own cases; super-admin unscoped), adding a userId predicate to the URN search — mirroring how getByFilter scopes. | #10809, #10806 | P2 broken object-level authorization on patient data, surfaced during the #10801/#10804 encryption-at-rest review. searchSurgicalEntriesByUrn has no assessor use-case and no active frontend caller, so own + super-admin is the correct minimal fix (an assessor-visibility path would be dead code). The scope mirrors the sibling getByFilter procedure so the two stay consistent. |
| 2026-07-21 | The surgical-case patientAgeAtSurgery derivation now decrypts dob_patient (via maybeDecryptDob) before the age math. Previously surgicalCaseService.autoLinkActivityToSurgicalCase selected the DOB raw and parsed it without decrypting, so once encryption was on new Date(ciphertext) gave an Invalid Date → null age. computePatientAge is exported for regression coverage. | #10807, #10800 | #10721 stores dob_patient encrypted, so every derivation doing date math on it must decrypt first. The update-path patient-category derivation was already covered once #10797 made getLogbookEntryById decrypt at the read boundary; this closes the one remaining raw-ciphertext derivation (the surgical-case age). |
| 2026-07-21 | Derived supervisor-credit rows (multi-clinician CPD credit) now copy the source case's urn_hash blind index alongside its (encrypted) urn value, so the two never drift. Previously the raw-write snapshot copied urn but not urn_hash, leaving derived rows with a ciphertext URN and a null blind index — invisible to every blind-index equality path. | #10805, #10799 | #10721 stores the patient URN encrypted with a urn_hash blind index for equality. The derived-credit sync writes with a raw drizzle insert/update (bypassing the encrypt seam), so it must copy both value and index verbatim to keep them consistent. Product decision (Rob, #10799 — keep & fix): keep the derived row's URN matchable and fix the consistency, rather than dropping the identifier. |
| 2026-07-21 | URN search now matches the FULL patient URN, case-insensitively, instead of a partial substring — routing getActivitiesByFilter, searchSurgicalEntriesByUrn, and the paginated getLogbookEntries filter through a new urnSearchMatch helper (the urn_hash blind index when encrypted, a case-insensitive-exact ilike on the plaintext column when not — so behaviour is consistent in every regime, including pre-cutover and legacy un-backfilled rows). Substring ilike('%…%') is dropped (it can't match encrypted ciphertext) but case-insensitivity is preserved. The UrnSearchField gains exact-match helper text. The logbook list urn sort option is removed (from the sort-field enum and sortColumnMap) — a global URN ordering is impossible under encryption (ciphertext / urn_hash ordering ≠ URN ordering). | #10804, #10801 | #10721 stores the patient URN encrypted, so a blind index supports exact equality only — substring search returned zero rows against ciphertext and ORDER BY urn was meaningless, both silently. Product decision (Rob, #10801): full-URN exact search (case-insensitive, all regimes) + drop the URN sort. urnSearchMatch is kept separate from the dedupe/auto-link equality helper urnStorageMatch (which needs a case-sensitive eq), so the search's plaintext branch stays a case-insensitive ilike rather than regressing to case-sensitive matching pre-cutover. |
| 2026-07-20 | The general detail/list/edit read paths now decrypt patient identifiers at the API boundary instead of returning stored rows verbatim — getActivityById and __getActivityWithUserDataById (activitiesService/activitiesCrud.ts), getAllActivities, getActivitiesByFilter and getActivitiesByType (activitiesService/activitiesQuery.ts), getLogbookEntryById and getLogbookEntries (logbookService/crud.ts), and sourceLogbookUrn (cpdUserActivities/crud.ts). A new seam decryptActivityIdentifiersForApiRead / decryptActivityIdentifierRowForApiRead (logbookService/patientIdentifierReadDecrypt.ts) decrypts urn/gender/dob_patient and fires ONE patient_identifier_decrypt access-audit entry per read via logPatientIdentifierAccess. Unlike the export seam it keeps dob_patient a string, not a Date, so the existing wire contract is unchanged — plaintext instead of ciphertext, nothing else. Read contracts are preserved exactly: getLogbookEntryById still returns null when absent, the getById helpers still return undefined, identifier keys are never fabricated on rows that did not select them, and the audit only logs rows that actually carried an identifier. For getActivitiesByFilter the decrypt happens after the read-through cache, so the cache stores ciphertext and a cache hit still emits its own audit entry. | #10802, #10797 | #10732 (Story B) wired the decrypt seam into only the export/report surfaces (CSV, PDF, surgical-case, multi-feature report), and there is no tRPC output-layer decrypt middleware — so once #10721 encryption-at-rest was enabled, every general detail/list/edit read returned raw ciphertext for urn/dob_patient/gender. The frontend edit forms round-trip those fields through logbook.getById/activities.getById, so this broke editing outright and showed encrypted blobs in list views. #10797 was the largest cutover-blocking surface of the epic. Recorded retrospectively by #10966: PR #10802 shipped without its Change Log fragment while every sibling in the read-decrypt family (#10804/#10805/#10807/#10809/#10810/#10814/#10819) shipped one, leaving the compliance audit trail without an entry for the change that brought the general read paths under the Art 32 decrypt boundary. |
| 2026-07-17 | Wired the expired-server-draft TTL sweep into a daily Azure Container Apps Job (logbook-draft-sweep-<env>, cron 0 21 * * *, UAT). The job physically hard-deletes logbook_case_drafts rows past their expires_at horizon via purgeExpiredLogbookCaseDrafts, replacing the "physical sweep tracked as a follow-up in #10749" note on AC logbook.case.draft-persisted-encrypted-server-side. Read-time expiry (an expired row already reads as absent) remains the shipped enforcement; the sweep is defence-in-depth storage hygiene that bounds ciphertext-row accumulation. Also reconciled isDraftEncryptionAvailable() to a straight re-export of the shared isPiiEncryptionEnabled() helper, closing the TODO(#10749) seam left by #10723. | #10768, #10749, #10723 | #10723 shipped the encrypted server-side draft store with read-time TTL expiry but deferred the physical row sweep to #10749 so ciphertext does not accumulate indefinitely. The sweep never decrypts (delete-by-expires_at only), so its job container needs only DATABASE_URL — not the PII encryption secrets — mirroring the resource-link-check / storage-cleanup sibling job pattern. The gate reconcile is a pure de-duplication (both checks were the identical two-env-var presence test), giving the two encrypted-storage surfaces a single source of truth on availability so they can never disagree at cutover. |
| 2026-07-17 | Added logbook.admin.level-of-involvement-label-override — the Super Admin LoI reference screen (#10752) gains an inline per-row edit affordance on the consultant table so a super-admin can type a display-label override per consultant Level-of-Involvement code. Overrides are stored in a new loi_label_overrides table (display wording only — stored involvement codes and logged case data are untouched), exposed via superAdmin-gated list/upsert tRPC procedures plus a protected list query for the display layer; the consultant label helper resolves override → else the PPP-default placeholder. Non-consultant and legacy sections stay read-only. | #10758 | Product direction (Rob, 2026-07-17): Matt's LoI wording decision should be captured inside the PPP UX, not on a GitHub thread. The override mechanism is how Matt supplies the answer to the open consultant-vernacular question (Q-consultant-loi, #10076) — the wording itself stays his decision, so #10076 remains open until he enters it. Follows the DB-overridable-strings precedent from Form Prompts (#2283). |
| 2026-07-17 | Added logbook.admin.level-of-involvement-reference — a read-only Super Admin screen at /admin/level-of-involvement rendering the non-consultant (confirmed #9187) and consultant (placeholder) Level-of-Involvement lists side by side, with the consultant awaiting-confirmation banner and a distinct legacy (TaT/PP) section. | #10753, #10752 | Matt asked on the 2026-07-14 catch-up to see the LoI lists "side by side" for consultants and non-consultants so he could annotate the vernacular and confirm which levels count as supervising/teaching — an in-app reference beats a GitHub-comment table. Surfaces the hardcoded constants only (no DB table, no editing); consultant labels stay governed by Q-consultant-loi (#10076). |
| 2026-07-17 | Add the parent AC5 @regression BDD scenario for the PII encryption-at-rest family (#10721 Story C) — a source-inspection guard proving that duplicate detection, the primary-operator conflict check, surgical-case auto-link, surgical_case.reference derivation, and cross-import dedupe all key on the deterministic urn_hash blind index (via urnStorageMatch) once patient identifiers are AES-256-GCM-encrypted at rest, never comparing plaintext to the non-deterministic ciphertext column. The equality-path repointing itself shipped in Story A (#10731 / PR #10746); this closes the AC5 test gap. | #10750, #10733, #10721 | Story C of the #10721 decomposition scoped both the equality-path repointing and its @regression coverage. A verify-first audit against origin/uat confirmed the repointing (urnStorageMatch seam, detectLogbookDuplicates / checkPrimaryOperatorConflict / autoLinkActivityToSurgicalCase, deriveSurgicalCaseReference fed the readStoredUrn-recovered plaintext for cutover-stable references, import dedupe) already merged in Story A (#10746), leaving the parent AC5 scenario as the sole residual. The parent spec AC logbook.case.patient-identifier-encryption-at-rest stays ⏳ pending the backfill/cutover story (#10734, still open). |
| 2026-07-16 | Added the encrypted server-side logbook case draft (new AC logbook.case.draft-persisted-encrypted-server-side). The source of truth for the in-progress case draft is now an encrypted server-side draft holding the FULL form incl. patient identity (URN + DOB), so crash-recovery is complete AND no patient PII sits on the device at all. New logbook_case_drafts table (migration 0210, unique on (user_id, form_key)) stores the whole JSON-serialised draft body as ONE AES-256-GCM ciphertext blob (payload_ciphertext) reusing the #10730/#10721 pii-crypto primitive — a raw DB row shows only ciphertext. tRPC logbook.upsertCaseDraft/getCaseDraft/clearCaseDraft are owner-scoped from the caller's identity ONLY (getSelfUserId, no client-supplied userId), so a cross-user fetch is refused with FORBIDDEN (403). The draft self-expires via a 30-day TTL: read-time expiry (an expired row reads as absent) is the shipped enforcement; a physical sweep of expired rows is tracked as a follow-up in #10749. Cleared on submit and explicit discard. On reopen the full form incl. patient identity is restored from the server — no re-entry. Availability gate: because the store is ciphertext-only it cannot pass through in plaintext, so until the pii-crypto secrets are provisioned the procedures no-op cleanly (upsert → { persisted: false }, get → null) and the client falls back to the on-device draft instead of 500-ing. The frontend useLogbookCaseDraft hook is rewired so the server draft is the source of truth, with the on-device allowlist draft (#9328/#9798) retained only as an offline fallback (structure only, no identity written to device storage). | #10747, #10723, #9371, #10730 | Parent #9371 DPO decision item 4 (Rob, 2026-07-16): 'yes full encrypted server side' — the gold-standard option Rob approved for the in-progress logbook case draft. The shipped on-device draft (#9328/#9798) deliberately persists only non-identifiable structure, so on restore the surgeon re-enters patient name/DOB. Rob's decision: instead persist the FULL draft (incl. identity) encrypted server-side, so recovery is complete and no patient PII sits on the device at all. AC approved by Rob 2026-07-16 (recorded as a comment on #10723). Reuses the already-merged #10730 pii-crypto primitive rather than inventing new crypto. Migration numbered 0210 to avoid the in-flight 0208 (#10741) / 0209 (#10740) collision (re-verified against origin/uat at PR time; latest merged was 0207). |
| 2026-07-16 | Encrypted the logbook's patient identifiers on every WRITE path (Story A of the #10721 decomposition, AC logbook.case.patient-identifier-encryption-at-rest, ⏳ — completes across sibling stories). Every write of activities.dob_patient / urn / gender and surgical_case.patient_urn now routes through the single patientIdentifierStorage seam, which AES-256-GCM-encrypts the value and populates the HMAC-SHA256 urn_hash blind index from the URN. Covered write paths: activitiesCrud create/update (partial-update-safe, urn/urn_hash kept in lock-step), surgicalCaseService.findOrCreateSurgicalCase (the reference dedupe key stays plaintext-derived), and the two direct-insert import writers (importSurgicalLogbook, importExecutionService). The four URN-equality reads that would otherwise compare a plaintext URN to the non-deterministic ciphertext column — detectLogbookDuplicates, checkPrimaryOperatorConflict, notifyParticipantsOnAuditEventCreation, autoLinkActivityToSurgicalCase — were migrated to match on the urn_hash blind index (urnStorageMatch), respecting each caller's URN provenance (plaintext form input used directly; stored ciphertext decrypted via an internal, server-only readStoredUrn before hashing — including the updateActivity fallback to the existing row's URN). Import cross-import dedupe decrypts existing rows / prefilters on urn_hash so plaintext-vs-ciphertext keys stay symmetric. | #10746, #10731, #10721 | Story A of the #10721 encryption-at-rest decomposition (parent DPO decision #9371 item 2, Rob 2026-07-16: always encrypt the identifiable patient clinical data at rest — UK GDPR Art 32 / Australian APP 11, special-category health data). The write conversion is gated behind isPiiEncryptionEnabled() (both PPP_PII_ENCRYPTION_KEY and PPP_URN_BLIND_INDEX_SECRET present); neither secret is wired in any environment yet, so this merges as a pure plaintext pass-through with zero behaviour change — ciphertext appears only once Key Vault is wired after the #10734 backfill cutover, which is what lets each decomposition story merge independently. The four equality reads had to move in this same PR because there is no dual-read tolerance for URN equality: once the column holds a non-deterministic AES-GCM ciphertext, an eq(urn, plaintext) match returns zero rows, so a secrets-on deploy would silently break duplicate detection, the primary-operator conflict check, surgical-case auto-link, and audit-event participant notification. Reads that surface identifiers to a caller (decrypt-at-boundary + access-audit-log) are Story B #10732; the AC5 @regression scenario is Story C #10733. The internal re-derivation read (readStoredUrn) is mixed-state tolerant: it structurally shape-detects the ciphertext envelope (looksLikeCiphertext — the single shared definition both stories key on) and only decrypts a value that looks encrypted, so a legacy plaintext row that has not yet been backfilled passes through unchanged instead of throwing. This is what makes the cutover flip safe while encrypted and plaintext rows coexist until #10734 completes the backfill. |
| 2026-07-16 | Story B of the logbook patient-identifier encryption work (AC logbook.case.patient-identifier-encryption-at-rest, ⏳ — still completing across siblings): the READ side. Patient identifiers (activities.urn/dob_patient/gender, surgical_case.patient_urn) are now decrypted ONLY at the service boundary on authorised read paths — the logbook CSV export, the logbook PDF export, the multi-feature report (and the FHIR structured JSON export that reuses it), and the consultant surgical-case roll-up. A new dual-read seam tolerates BOTH storage states during the migration: a legacy plaintext row (pre-backfill #10734) passes through unchanged, and a #10731 ciphertext row is decrypted, detected structurally by the iv.tag.ciphertext envelope. Every decrypt read writes a single access-audit entry (new action patient_identifier_decrypt) via the existing auditLogService.insertAuditEntry — one entry per export/report request listing the entity scope (surface + case count + a bounded id sample), never a plaintext identifier, and never blocking the read (fire-and-forget). | #10745, #10732, #10721 | Parent #9371 DPO decision item 2 + the #10721 scheme (Rob, 2026-07-16): decrypt only at the service boundary and access-audit-log every decrypt (UK GDPR Art 32 access logging). Story B of the #10721 decomposition (enabler #10730 + stories #10731/#10732/#10733 + backfill #10734). Batched one-audit-row-per-request rather than per-row: a single export is one access event, and per-row auditing would multiply a 1000-case export into 1000 audit inserts with no compliance benefit (the AC asks for a row per decrypt event, and an export is one event). Dual-read tolerance is required because Story A (#10731, encrypt-on-write) and the backfill (#10734) run in parallel/after, so at any moment a row may be plaintext or ciphertext; the read must never assume one. The report/structured-export path was in scope because multiFeatureReportService.fetchLogbookSection spreads the raw logbook row (including urn/dob/gender) into the report payload — its redactUserFields only strips nested user objects — so without this it would have emitted ciphertext post-#10731. |
| 2026-07-16 | Added the encryption-at-rest foundation for the logbook's patient identifiers (AC logbook.case.patient-identifier-encryption-at-rest, ⏳ — completes across sibling stories). The four persisted identifiers (activities.dob_patient, activities.urn, activities.gender, surgical_case.patient_urn) will be stored AES-256-GCM-encrypted with a HMAC-SHA256 urn_hash blind index so equality paths (dedupe, surgical-case auto-link, surgical_case.reference, import dedupe) still work without a decrypt; decrypt happens only at the service boundary and is access-audit-logged. This enabler PR (#10730) lands the pii-crypto primitive (encryptPii/decryptPii/blindIndex, key from a lazily-resolved Key Vault secret via the token-helper.ts pattern — not backend-core's @ts-nocheck crypter.ts), the urn_hash columns + indexes on both tables, and the dob_patient timestamp → text column widening (migration 0207) with its Date → string type cascade resolved via a single patientIdentifierStorage serialize/parse seam. The write/read/equality conversions and the existing-row backfill follow in siblings #10731/#10732/#10733/#10734. | #10739, #10730, #10721, #9371 | Parent #9371 DPO decision item 2 (Rob, 2026-07-16): 'always encrypt at rest and in transit' for the identifiable patient clinical data the logbook persists (UK GDPR Art 32 / Australian APP 11, special-category health data). Scheme decided on #10721 (Rob, 2026-07-16): AES-256-GCM via a Key Vault secret resolved lazily following token-helper.ts; a HMAC-SHA256 urn_hash blind index preserving dedupe/auto-link/reference/import-dedupe (a random IV makes the ciphertext non-deterministic, so equality cannot key on it); decrypt only at the service boundary + access-audit-logged; a backfill proven by a .first-apply.validate.sql sibling. #10721 was sized Large (~48, ~30 backend files reference the four columns) and decomposed with team-lead approval into enabler #10730 + stories #10731/#10732/#10733 + backfill #10734; the SGD doc trail lands with the enabler per Rob so the trace is complete from the first child. dob_patient had to be widened from timestamp to text because ciphertext is a string a timestamp column cannot hold; the migration's USING clause converts existing DOBs to ISO-8601 text so pre-backfill reads behave identically. |
| 2026-07-16 | Seeded the physician (Practical / Procedural Logbook) procedure master list from the UK IMT practical procedures list (JRCPTB), keyed to a General Internal Medicine speciality, AND surfaced it at runtime — a new procedure.listPracticalDefault query wired into the surgery-picker hook (useLogbookFormData) replaces the External-Lookup-only empty-state for procedural users with an empty scoped list — resolves Open Question Q9. | #10738, #8815 | The procedural label variant shipped but no physician procedure dataset existed (only the 10 surgical lists), so a physician hit the #8890 External-Lookup-only guard. RACP was not used because its 2026 curricula are EPA/competency-based with no flat procedure list (Rob decision 2026-07-16); the UK IMT list is the published, enumerable interim default. Seeded via the same seedSettingsData.ts mechanism as the surgical lists (#8468); no schema change, so no migration. Seeding alone was invisible (physicians carry broad "Specialist" buckets or no speciality, so listBySpeciality returned nothing) — Rob approved (2026-07-16) adding the runtime surfacing on the same PR. Interim default — Matt may redirect to a different source. |
| 2026-07-16 | Document the DPIA, RoPA (Art 30) entry, and Art 9(2)(h) lawful basis for storing identifiable patient clinical data in the surgical logbook. The logbook.case.draft-persisted clause is updated — the #9371 DPO items are now decided (Rob, 2026-07-16)- DPIA/RoPA/lawful-basis documented in compliance-assessment.md §8–§9, encryption-at-rest approved (#10721), encrypted server-side draft approved (#10723). | #10724, #10722, #9371 | Item 3 of the #9371 patient-PII DPO decision — Rob approved documenting the DPIA + RoPA + Art 9(2)(h) lawful basis for identifiable patient clinical data. This discharges the documentation half; the two engineering items (encryption-at-rest #10721, encrypted server-side draft #10723) are filed as separate children. The spec's PII clause previously recorded these as parked "policy/DPO decisions on #9371"; that deferral is now resolved. |
| 2026-07-16 | Fixed a regression from #10710: the chunked import preview reported row numbers 1-based LOCAL to each chunk, so a second chunk's rows collided with the first. useImportLogbook now rebases each preview chunk's row-keyed lists (invalidEntriesList, unconfirmedMatchesList, unmatchedHospitalsList) by chunk.rowsBefore to whole-file numbers before aggregateImportResults folds them, so a hospital or procedure correction the surgeon makes keys the correct physical case on confirm. | #10720, #10716, #10680 | #10710 chunked the preview but the backend numbers each row 1-based against the csvData it receives; the aggregator only concatenated the row lists without rebasing. For any file over the 250-row chunk cap, chunk 2's row 1 collided with chunk 1's row 1, and because the confirm path (planImportChunks.rebase) expects whole-file row numbers, a bulk or per-row hospital assignment (or a procedure confirmation) on a colliding row keyed the WRONG physical CSV case — corrupting exactly the at-volume flow the chunking exists to fix. The aggregation unit test masked it by mocking both chunks with identical row numbers and asserting only list length; it now asserts the exact rebased, globally-unique row set (proven to fail against the pre-fix hook). |
| 2026-07-16 | Refactored the logbook import wizard modal to a single-scroll-region layout and added three ACs. (1) logbook.import.single-scroll-region — the wizard (and the preview→confirm dialog) is now a fixed-height flex column (max-height: 85vh, overflow: hidden) whose header/stepper, privacy banner and footer are flex-shrink: 0 and never scroll; only the content body is flex: 1; overflow-y: auto, killing the former dual-scrollbar 'inception'. (2) logbook.import.step-label-honesty — the Map Columns primary action reads 'Continue to Review', never 'Finish' (that click only advances to Review). (3) logbook.import.auto-map-summary-collapse — fully auto-mapped rows collapse behind a one-line 'N of N fields automatically mapped' summary with an expander; only rows needing review stay expanded. The logbook.import.patient-name-initials-only (#9897) privacy notice moved out of the scrollable Map Columns body into the wizard shell as a fixed banner below the stepper so it never scrolls out of view — behaviour and copy unchanged, location only. | #10705, #10680 | Rob (Dev Session 2026-07-16, #10705): the import modal suffered 'scrollbar inception' — the outer modal paper AND the inner mapping table both scrolled, making the data-dense Map Columns step feel cramped. He asked for a sticky header/footer architecture with exactly one scrollable viewport, an honest button label ('Finish' on the mapping step was misleading since it only advances to Review), and an auto-map summary that collapses already-correct rows. The privacy-banner move is a structural change to logbook.import.patient-name-initials-only (#9897): the notice's content and trigger are unchanged, but it now renders from the wizard shell (fixed) rather than the scrollable step body, for compliance visibility. Landed after #10680 (same ImportDialog.tsx) merged to avoid conflicts. MUI + existing tokens only — no new brand primitives. |
| 2026-07-16 | Restored live import progress at volume and added bulk hospital assignment. (1) logbook.import.preview-auto-split-and-visible-progress — the preview/validation request now auto-splits at IMPORT_CHUNK_ROWS (250) exactly like the confirm path (#10682), folding per-chunk results into one whole-file preview, so a large file no longer hits the ~60s Azure ingress timeout during validation; the coarse progress percentage advances per completed chunk on the client so movement is visible even when a getImportProgress poll lands on the other replica (up to 2) and returns null. (2) logbook.import.progress-poll-never-signs-out — a 401 from the best-effort getImportProgress poll no longer triggers the global session-expired redirect (#5044), so backend replica churn under import load can never sign the user out mid-import; every other query/mutation still redirects on 401 as before. (3) logbook.import.bulk-hospital-assignment — the preview's Confirm hospitals panel lets the surgeon pick one hospital from a search and apply it to EVERY unmatched-hospital row in a single action, validated server-side like the per-row #8648 correction, with any row still overridable afterwards. | #10680, #10599 | Split from #10599 (Rob's self-testing, Dev Session 2026-07-14, problem 1): a large import showed no live progress and ended in a ~60s timeout completion email. Root cause was two-fold — the PREVIEW request was never chunked (only the confirm path was, #10682), so validation of Matt's 2,000+ rows timed out before the confirm step was ever reached; and the in-process progress registry is replica-local, so on the 2-replica UAT/prod deployment roughly half the polls returned null and the X/N label never moved. Rob (2026-07-16) additionally asked that a record referencing a hospital not in the system offer a search to bulk-assign one hospital to all affected records, rather than the per-row picker (#8648) which is unworkable when thousands of rows share one unknown hospital. |
| 2026-07-16 | Authoritative AU masterlist re-validation (Slice C of #7883): the AU SNOMED CT edition is now PINNED to the authoritative release 20250630 end-to-end — the AU instance_config row (seed migration 0209) and the AU_DEFAULT_CONFIG fallback both carry snomed_version = 20250630, so the matcher, the live picker, and the masterlist re-key resolve against a specific, reproducible edition version rather than "latest". With NCTS credentials configured the same calls target the authoritative NCTS FHIR server (wired by #7320); deltas continue to reconcile through the existing review queue (#7366). | #8877 | Slice C of #7883, unblocked by #7320 (NCTS OAuth2 auth, merged). Slices A/B resolved the edition from instance_config and re-keyed the masterlist but left the AU edition UNPINNED (snomed_version = null), so a new AU edition release could silently move a code's resolution out from under the stored masterlist. Pinning the authoritative version makes the re-validation reproducible and server-independent. |
| 2026-07-15 | Added logbook.import.reset-flow-for-new-file — after a completed import, an 'Import another file' control on the success screen clears the finished import and re-opens the upload wizard at the file-select step in place, so a surgeon can import a different file without a full page refresh. | #10684, #10681, #10599 | Split from #10599 (Rob's self-testing, Dev Session 2026-07-14, problem 3): the import runs as a two-dialog pipeline (upload/map wizard -> preview/confirm/success ImportDialog) and the success screen's only exit was Close, so importing a different file required re-opening the wizard from the toolbar or reloading. Rob flagged it explicitly as 'obviously not a good user experience.' |
| 2026-07-15 | Added logbook.import.whole-file-hospital-fallback — when no source column can be mapped to Hospital, the Map Columns step offers a single DB-backed hospital dropdown to pick one hospital for the whole file; the chosen hospitalId is validated server-side against the canonical hospitals table and applied to every imported row. The per-row unmatched-hospital picker (#8648) is unchanged when a hospital column is present. | #10683, #10599 | Split from #10599 (Rob's self-testing, Dev Session 2026-07-14, problem 4): a source spreadsheet with no hospital column (all rows implicitly one hospital, e.g. a sheet named after the site) cannot map the hospital source step, so #8648's per-row picker — which assumes a hospital column exists — has nothing to work with. The whole-file 'no hospital column at all -> one dropdown applied to the whole file' case was uncovered. |
| 2026-07-15 | Single-sticker Patient Sticker OCR now extracts a hospital name, matches it to the user's linked hospitals (reusing HospitalMatchingService via new resolveStickerHospital.ts), and autofills hospitalId on the Add Logbook Case form; the scanned draft persists creationSource: 'ocr' / isImported: true so logbook.origin.scanned-details-heading and the origin badges render correctly for the single-sticker path, not just the bulk OperatingListScanner. Added new AC logbook.ocr.single-sticker-hospital-autofill documenting this behaviour. | #10655, #10629 | Split from #10598 (deep-dive 2026-07-14) — genuinely new behaviour: the single-sticker OCR flow (LogbookImageUploader -> analyzeImage.analyze) previously had no hospital field in its contract at all and never set creationSource/isImported, so hospital-name extraction + matching + the origin-flag writes on this path did not exist before this PR (only the separate bulk OperatingListScanner path delivered equivalent behaviour). The required Spec-drift gate flagged the useLogbookCaseFormShell.ts change with no matching docs/features/ update; per explicit product direction this is recorded as a new AC (logbook.ocr.single-sticker-hospital-autofill), not a spec-unchanged bypass. |
| 2026-07-14 | NCTS OAuth2 client-credentials authentication wired for live SNOMED CT lookups — Doppler-sourced credentials, token client with in-memory caching, Bearer-token attachment to Ontoserver FHIR requests, fail-closed on auth failure, unauthenticated public-Ontoserver fallback preserved when unconfigured. | #7320 | NCTS business verification confirmed complete (account set up 4 June, per Dev Session transcript 2026-07-14) — unblocks the authoritative AU masterlist re-key/re-validate slices (#8876, #8877) that were on-hold pending this. |
| 2026-07-14 | Procedures masterlist re-key against the AU SNOMED edition (32506021000036107) — every masterlist code carrying a SNOMED CT value is re-resolved via the existing FHIR $validate-code gate; a resolvable, active code is re-keyed to the AU edition (snomedCt/snomedDisplay/snomedEdition/snomedVersion updated, snomedMatchStatus=confirmed); an unresolvable or retired/inactive code is routed to the review queue (snomedMatchStatus=needs_review) with its prior code preserved, never silently kept or deleted. | #8876 | Slice B of #7883 — the seeded procedures masterlist was originally matched against the UK edition. #7320 (NCTS OAuth2 auth) unblocked authoritative AU terminology-server access, so this issue performs the actual re-key. Distinct from the read-only #9550 resolution report (validate-snomed-codes.mjs --resolve), which never mutates the masterlist and was always documented as a de-risk pass ahead of this issue. |
| 2026-07-12 | Internal refactor: split the 1063-line logbookService/index.ts into responsibility-focused sibling modules behind a re-export barrel — no behaviour or acceptance-criteria change. | #10498 | index.ts had grown to a god-module mixing entry CRUD, stats/reporting, validation, and the consultant decline/resubmit workflow. Behaviour-preserving decomposition surfaced by a repo-wide /sgd:refactor smell pass (verified genuine per triage). |
| 2026-07-12 | Internal refactor of the surgical logbook Add/View/Update case forms — no behaviour or acceptance-criteria change. The Consultant and NonConsultant CreateViewUpdateForm components were near-duplicate god components (~500-line bodies) that each independently reimplemented the same form initialisation, backgrounding-draft autosave, satisfaction-visibility gate, external-procedure creation, submit/update wrappers and hospital/consultant auto-population. That shared logic now lives once in a shared useLogbookCaseFormShell hook; each form supplies only its variant, two divergence options and its own JSX (SurgerySection variant, reviewer/declined banners, involvement options). All existing behaviour is preserved, including the #8649 edit-mode form-reset that re-derives procedureRefField for the Consultant and the #8542 primary-operator satisfaction gate. Guarded by a new @regression source-inspection scenario (#10469). | #10469 | Removes a duplicated form shell so the two logbook case-entry variants cannot silently drift apart on future edits (part of the forms-DRY epic #8111). Behaviour-preserving cleanup surfaced by a repo-wide /sgd:refactor smell pass; no product-owner sign-off required as no acceptance criteria change. |
| 2026-07-11 | Collapsed the 4 Neurosurgery "Cranial Trauma" seed rows whose specificArea ("cranial trauma") merely restated their broadArea ("Cranial Trauma") to broad-area-only (blank specificArea), completing the specific-area/broad-area de-duplication across both affected specialties (Plastic & Reconstructive Surgery landed the other half in #10407/#6699). Edited neurosurgery-review.csv (the reviewed source) and re-synced neurosurgery-db-ready.json positionally via sync-dbready-from-review.mjs (4 rows synced, 0 drift, 384/384 row parity). Widened the vitest guard (Specialty specificArea does not duplicate broadArea (#6699)) and the @regression @issue-6699 BDD scenario to also cover neurosurgery, and updated the logbook.fhir.specific-area-not-broad-area-duplicate AC scope note. | #10413, #10365 | The identical double-up Matt flagged for Plastic Surgery (#6699) also existed in Neurosurgery's Cranial Trauma group. The 4 offending procedures (wound exploration/debridement, ICP monitor insertion, craniotomy for acute haematomas, decompressive craniectomy) are heterogeneous with no single genuine anatomical sub-area to derive, and the other 8 Cranial Trauma rows were already broad-area-only — so blanking to broad-area-only matches both the #10407 plastics precedent and the existing neurosurgery pattern. #7365, previously thought to own this half, is closed and was an unrelated Notion-clarification deliverable; the neurosurgery half was simply unclaimed and buildable, confirmed by Rob. |
| 2026-07-11 | Collapsed 52 Plastic & Reconstructive Surgery seed rows whose specificArea merely restated their broadArea to broad-area-only (blank specificArea), across six groups (Non-Surgical rejuvenation, Chest wall reconstruction, Complex wound, Craniomaxillofacial trauma, Vascular Anomalies, Sarcoma). Edited plastic-surgery-review.csv (the reviewed source) and re-synced plastic-surgery-db-ready.json positionally via sync-dbready-from-review.mjs. Added logbook.fhir.specific-area-not-broad-area-duplicate AC, a scoped vitest guard (Specialty specificArea does not duplicate broadArea (#6699)) and a @regression @issue-6699 BDD scenario. | #10407, #6699 | Matt 2026-07-07 on #6699: 'breast surgery is a broad and specific area currently ... or maybe we just have a broad area only for the ones that double [up] with that same or similar in broad and specific'. Each of the six affected groups has exactly one specific value identical to its broad area (no distinct anatomical sub-division), so broad-area-only is the correct form — matching the established blank-specificArea convention (congenital 140/140, general-surgery 350/405). Groups with a genuine sub-area (e.g. Breast surgery / surgery of the breast) are preserved. The 8 non-surgical rejuvenation lines and 4 blank-placement themes remain open per Matt (in-app review, #10339); the PP/PBA/WBA numbers ask is centralised in #9123 (out of scope). |
| 2026-07-11 | Confirmed the Logbook API token policy as official product policy — per-user scope, read-only, no write access for external consumers, ever. Moved Open Question Q12 to Closed Questions and updated the logbook.api.token-access acceptance criterion from "engineering default, pending Matt's confirmation" to confirmed policy. The shipped #7017 behaviour (per-user scope, GET-only/405-on-write, optional expiry with 90-day default at issuance, immediate revocation, atomic rotation) is unchanged in code — only its governance status changes from provisional to confirmed. | #10406, #8816 | Q12 tracked the gap between the shipped #7017 engineering default and confirmed product policy. Rob confirmed the shipped default (per-user, read-only) as the official policy on 2026-07-11 — his direct decision, not raised with Matt. Pure documentation change; the code already matched the now-confirmed policy. |
| 2026-07-11 | Added a regression guard closing out #6698 (Urology procedure list). Matt's only residual data-quality flag was "only double is emergency urology" — the raw curriculum extraction's "Emergency Urology" category restated acuity (Emergency) in the classification area/principal dimension, the same acuity/area double-up as #6684 but outside the specificArea column the #6684 guard pins. The #8511/#8518 human re-key already dissolved it in the loaded urology-db-ready.json (the 9 emergency operations load with treatmentAcuity="Emergency" and broadArea="General Urology", verified clean on uat). This PR adds a specialtyClassificationSync.test.ts guard (no loaded urology broadArea/principalProcedure is a "<acuity> Urology" label; the 9 emergency ops keep acuity in treatmentAcuity alone) plus a @regression @issue-6698 BDD scenario. Data content unchanged. | #10405, #6698 | Matt (2026-07-07) confirmed the Urology list otherwise "looks quite good"; the only concrete residual was the emergency double-up, now guarded so a future re-extraction cannot silently reintroduce it. PBA/WBA numbers and critical-conditions-as-WBAs from the same thread are intentionally excluded (trainee-facing targets tracked in #9123). Clinical sign-off moved to the in-app Specialty Procedure Classification Review screen (#10339). |
| 2026-07-11 | Widened the deterministic procedure matcher's abbreviation table (SURGICAL_ABBREVIATIONS) with a curated set of unambiguous surgical shorthand common on OCR'd / hospital-export operating lists — MUA, OGD/EGD, WLE, FESS, LSCS, ERPC, EMR, VATS, PCNL — so those scanned cases resolve via the existing abbreviation tier instead of falling through to "needs classification". Added new AC logbook.import.procedure-abbreviation-recall plus backend unit tests and a @regression BDD scenario. Each abbreviation maps 1:1 to a single procedure phrase; the match remains a matchType 'abbreviation' suggestion (confidence 0.8) the surgeon confirms in the wizard — the confirm-inline safeguard is untouched. | #10404, #10391 | Q2-only "cheaper win" slice of #10391 (follow-up to #10381). #10391 poses two questions for Matt — Q1 (whether/where to add a new Gemini auto-suggestion step) is a clinical-safety product decision and remains open; Q2 asks whether strengthening the existing server-side matchProcedure() tiers is the cheaper win. This ships Q2 only: a precision-safe recall improvement to already-shipped deterministic matching, with no new AI step and no change to what the surgeon confirms. #10391 stays open pending Matt's Q1 call. |
| 2026-07-11 | Added logbook.training-totals.critical-conditions-wba — each surgical specialty now surfaces its critical conditions required as WBAs and its "numbers required for completion of training" (index-procedure indicative case numbers) in the trainee logbook dashboard, sourced VERBATIM from the ISCP/JCST curriculum documents (#8468/#8490 curriculum-structures JSON, machine-verified by verify-extractions.py) — not hand-entered by Matt. The critical-conditions list is backfilled into the existing (previously empty-seeded) speciality.criticalConditions column via a data-only migration (0196, with a first-apply-only validator per #10172), lighting up the already-built WBA CriticalConditionsWidget; the index-procedure completion numbers are surfaced read-only in a new "Numbers Required for Completion" dashboard widget alongside the user-defined index-procedure targets (#7504), each with a curriculum source citation. New verbatim constant SPECIALTY_CURRICULUM_REQUIREMENTS (specialtyCriticalConditions.ts, mirroring the #8552 curriculumTrainingDefaults pattern), the speciality service enriched to carry curriculumIndexProcedures, plus a @smoke @issue-9123 BDD scenario exercising the real helpers. 9 of 10 specialties are populated; Cardiothoracic Surgery (Congenital) lists none (inherits the parent Cardiothoracic curriculum, #6704). | #9123, #8490, #8468 | Issue #9123 (from Matt's #6684/#6697-#6705/#7365 sign-off ask) was originally filed as Matt-gated clinical data. Rob determined (2026-07-11) the exact requested data — critical conditions requiring WBA + numbers required for completion — is ALREADY extracted, sourced (each curriculum file cites its ISCP/JCST PDF), and machine-verified in the existing curriculum JSON from the #8468 rekey wave. Building directly from the already-cited official curriculum data (rather than waiting for Matt to retype numbers that are already extracted and verified) delivers the WBA/target layer that #6704 and the congenital classification explicitly deferred to #9123, without re-gating on Matt. The clinical authority (the curriculum documents Matt provided) is unchanged; the issue stays open + for-discussion for Matt's UX review of the surfacing. |
| 2026-07-11 | General Surgery specialty seed — the "Trauma" curriculum module now carries an anatomical specificArea sub-group on every one of its rows (thoracic injury · abdominal injury · neck injury · head injury · limb and soft tissue injury · vascular trauma · trauma principles), derived mechanically from the curriculum's own trauma-chapter ordering. Previously all 59 Trauma-module rows had a blank specificArea while carrying both broadArea="Trauma" and treatmentAcuity="Trauma", so the Trauma-vs-Elective dashboard widget (buckets by acuity, then breaks each bucket down by broadArea) collapsed the whole module into a single self-referential "Trauma / Trauma" slice with no drill-down. broadArea="Trauma" is a legitimate curriculum syllabus module and is kept; treatmentAcuity="Trauma" (a first-class app-wide acuity value the widget reads) is untouched. Data-only, no schema/migration; general-surgery-db-ready.json re-synced from the reviewed CSV via sync-dbready-from-review.mjs so the pair stays row-for-row equal. | #6703 | Matt flagged (#6703, 2026-07-07) that "Trauma (which is a double up from acuity)" needed review/delineation. Investigation against the curriculum's own orthoModelMapping (curriculum-structures/general-surgery.curriculum.json) confirmed the genuine redundancy was the missing specificArea sub-tier, not the module heading — matching Matt's own 2026-06-10 suggestion to "make the Breast / Trauma chapter headings sub-areas". Scoped narrowly to this mechanical, non-clinical sub-grouping. The remaining flags Matt raised (the ~400-row specificArea categorisation method, the legitimately-empty specificArea rows for modules with no curriculum sub-section — the accepted #6704 precedent, the "Elective/Emergency General Surgery" section-name question, and the childhood inguinal-hernia principalProcedure Open Question from 2026-06-10) are deliberately left for Matt's Super Admin Specialty Procedure Classification Review screen (#10339). The WBA/numbers-required layer stays out of scope in #9123. |
| 2026-07-10 | Delivered the deferred department/speciality half of the Responsible Consultant smart-list (logbook.entry.responsible-consultant-smart-list flipped to shipped). getConsultantUsers / GetConsultantUsersOptions now accept optional hospitalId (filters via the user_assigned_hospitals junction) and specialityId (filters on users.speciality_id); both optional and independent, composing with the existing search/limit/excludeUserId predicates. The users.getConsultantUsers tRPC procedure exposes both as optional inputs. Added integration tests for the new scoping and a @smoke @issue-10373 source-inspection BDD scenario. | #10373, #8171 | Follow-up to #8171-C (PR #10369), which shipped the hospital half's picker default/ordering but deferred the backend query extension for hospital+dept/speciality scoping rather than half-building it. Matt's #8171 decision (2026-06-30): "Smart list option previously talked about would be to show consultants of hospital and department/speciality." Backend query delivered here so the picker's smart-list tier has data to scope on. |
| 2026-07-10 | Added an optional Clavien-Dindo complication-severity grade to the Audit feature (Audit Events). New AC logbook.audit-event.complication-grade — a fixed 7-grade ordinal scale (I/II/IIIa/IIIb/IVa/IVb/V) in the shared logbook constants (CLAVIEN_DINDO_GRADES + isKnownClavienDindoGrade), an optional complicationGrade field on activityAttributesSchema (attributes JSONB, no migration), and an optional Autocomplete on the Audit Event narrative section. Resolved the Q-malt-alignment Open Question with Matt's 2026-07-08 answers (item 1 built audit-tool-only; items 2-4 confirmed already-existing; item 5 not needed; no MALT licence). | #10370, #9189, #9899 | Item 1 of the #9189 RACS MALT deep-review, confirmed by Matt on 2026-07-08 ("we can add it clavien dindo classification system as an option for the user to enter"). Scoped strictly to the internal audit tool — decoupled from CPD Home and HLSR, and carrying no RACS MALT alignment or licence (dropped on #9189 / #1740). Supersedes the Clavien-Dindo half of #9899. |
| 2026-07-10 | Logbook Responsible Consultant picker enhancements (#8171) — a NEW case defaults the consultant to the doctor's Clinical Supervisor; the last-entered consultant is remembered for the session (sessionStorage, cleared on logout) and takes priority; the dropdown sorts Clinical Supervisor(s) → favourites → alphabetical (revising the favourites-first Q3 ordering for this picker). Shipped logbook.entry.responsible-consultant-clinical-supervisor-default, -sticky-default, -list-order. The optional hospital+dept/speciality "smart list" (-smart-list) is deferred to a backend follow-up because getConsultantUsers exposes no hospital/speciality scoping yet. | #10369, #8171 | Matt confirmed the picker behaviour on #8171 (2026-06-30): "defaults to clinical supervisor … remember last entered consultant … until log out; Clinical supervisor/s to default to top … favourite list … below clinical supervisor/s". The default + session-sticky mirror the existing hospital-sticky-default pattern; smart-list needs a getConsultantUsers query extension so it is split out rather than bundled. |
| 2026-07-06 | Reconciled the spec frontmatter github-label from the stale feature:surgical-logbook (0 open issues) to the live canonical feature:logbook (all 22 open issues + recent closures), completing the Wave 6 label rename for this spec. | #9889 | The feature:logbook rename landed but the frontmatter still pointed at feature:surgical-logbook, so _ac-index.json / AC-search tooling associated this spec with an empty label. Flagged by the 2026-07-06 drift audit (.drift-audits/logbook.md). Note the BDD @github-label:surgical-logbook / @feature:surgical-logbook tags remain on the older identifier and are tracked separately (feature-graph rename, not a one-line change). |
| 2026-07-05 | Import date parser now accepts DD-Mon-YYYY textual-month dates (e.g. "07-Feb-2023"), in addition to Excel serial, ISO, and slash-separated formats. | #10049 | Discovered while proving out #9903 against a client's real hospital export (TPCH.xlsx) — every row failed import validation because parseDate() didn't recognise that hospital's native date format. |
| 2026-07-04 | A mapped "Patient Name" column is no longer dropped entirely (#9845) — the backend now captures only the first+last initial (e.g. "John Smith" -> "JS") as a privacy-safe secondary identifier, stored in importNotes.originalData.patientInitials. The full name is never persisted, logged, or displayed. The Map Columns privacy notice copy, the imported-case detail display (ImportedCaseDetails/ImportedCaseDetailsSection), and the (currently unwired) frontend dataTransformService.ts pipeline were all updated to match; three latent privacy edge cases in that frontend pipeline (a BOM/case-mismatched header leaving the full name in rawData, a duplicate column mapping stripping only the last one, and inline-edit revalidation reintroducing the raw row) were fixed alongside it. | #10033, #9897, #9845 | Matt Randell (product owner, a doctor) identified on a 2026-07-01 call that #9845's "skip entirely" rule left no reliable secondary identifier when a source sheet lacks Date of Birth (#9846) — patients with the same or missing hospital number cannot be disambiguated. Matt explicitly authorised first+last initial capture as a privacy-safe middle ground, superseding the "skip entirely" AC. |
| 2026-07-03 | Surgeons can now import their logbook repeatedly instead of being locked out after the first import. The single-import-per-user guard (which rejected any second confirmed import with "You already have imported logbook data. To import again, please contact support.") is removed and replaced with cross-import duplicate detection — each incoming row is deduped against the user's existing imported cases on Patient ID + operation date + operation description (the same key the in-batch dedupe and the wizard import path use). Re-importing the exact same file is a clean no-op (0 imported, N duplicates skipped, reported honestly as success); importing an updated file imports only the genuinely new rows. The #9998 per-user advisory lock is retained and now serialises the cross-import dedupe read-then-insert so two concurrent confirmed imports of the same file can never both persist the case. | #10016, #10013 | A user could only ever import their logbook once — any subsequent confirmed import was hard-blocked, so a surgeon could not import an updated spreadsheet later in the year or one file per hospital/rotation, and any prior (even partial) import permanently locked the account out of importing. Rob, 2026-07-03: "They need to be able to import as many times as they need to! We have to handle duplicates gracefully." |
| 2026-07-03 | Compact mobile action row on the surgical logbook toolbar — short-label equal-width buttons below the sm breakpoint instead of a full-width 3-row stack. | #10015, #9891 | On a 375px viewport the three header actions (Scan / Import / Add) rendered at desktop width and wrapped into a chunky ~180px vertical stack above the fold. Desktop layout and the ≥44px touch target are preserved; the full label rides on the button title so the accessible name still matches the visible text (#7773). The ? adjacent-to-heading half of #9891 already shipped via the shared PageHeader (#9887). |
| 2026-07-03 | Three logbook-import reliability fixes found during live UAT testing. (1) A confirmed import whose rows all fail to persist (e.g. a database-level constraint violation) now honestly reports success:false instead of a bare success:true, importedCount:0 that silently masked a total persistence failure as a success toast. (2) The "already imported" duplicate-import guard is now enforced under a per-user Postgres advisory lock, closing a check-then-act race where two near-simultaneous confirmed imports for the same account (a double-fired "Proceed Import" click) could both pass the guard and both persist. (3) The preview/validation step now polls the same server-side per-batch progress registry the confirm-import step already used, so the "Validating your import…" caption shows a live "processed / total rows" count instead of a fake 5%/95% jump — the progress bar itself remains animated/indeterminate throughout validation (unchanged from #9822), since a large file's validation call can still take 30-120s. | #9998 | Live UAT testing (#9903) found a 500-row logbook import silently reported success while inserting zero rows, and separately observed a double-fired "Proceed Import" click racing past the duplicate-import guard. Reproduced and fixed as three independent, individually-testable changes rather than one large patch; an async/job-based import redesign was considered and deliberately deferred as a follow-up (tracked as an Open Question) since the root causes here were correctness bugs, not a volume/timeout problem. |
| 2026-07-02 | logbook.dashboard.pace-monitor: Total Cases / Primary Surgeon numbers are now horizontally centred under their headings (were left-aligned), and the pace monitor strip shares one row with the Hospital filter / Customise controls (#8723) instead of stacking as a separate row above them. Also fixes a bug in this spec''s own code-paths frontmatter: several entries had literal backslash-escaped globs (\*\* instead of **) that silently broke spec-drift attribution for files under LogbookCaseForm/, SurgicalLogbookWidgets/, and three backend service paths — tracked more broadly for other specs in #9989. | #9990, #9982 | PO request (Rob, 2026-07-02): the KPI header strip consumed two rows with dead vertical space between them, pushing the charts further down the page than necessary. |
| 2026-07-02 | The import wizard's DOB-derived patient category path (#9846) now falls back to the mapped Patient Category column value whenever a row's Date of Birth is absent (no DOB column mapped, or blank for that row) or unparseable — instead of leaving the row blank for manual entry whenever a usable category was already available. The DOB-derived category still takes precedence when the DOB is present and parseable. The non-blocking preview warning for an unparseable DOB now distinguishes "used the Patient Category column value instead" from "left for manual entry" depending on whether the fallback actually produced a category. | #9900 | Same-day follow-up to #9846, confirmed directly by Matt Randell on the 2026-07-01 call — his real-world source spreadsheet does not always have a Date of Birth column, but does have an existing Adult/Paediatric column already populated by whoever compiled the sheet. Reading that column instead of leaving rows blank removes unnecessary manual data entry. |
| 2026-06-30 | Map Columns step shows an informational notice when a source column is mapped to Patient Name, warning that it will be skipped on import. | #9848, #9845 | The backend silently drops Patient Name on import for privacy reasons; surgeons had no visibility that the column they mapped would not appear in their logbook. |
| 2026-06-30 | Add executable BDD coverage (four @regression @issue-9800 scenarios with implemented step defs) for the consultant-review ACs signature-on-review, competency-feedback-capture, dual-profile-visibility (work-queue facet) and decline-notify (Closed Q6), which were previously asserted only in prose. | #9828, #9800 | From the #9189 RACS MALT review — these four consultant-review ACs had no standard-CI BDD scenarios. Each new scenario locks a facet distinct from the #8192 placement scenarios via source inspection, so the behaviour is regression-guarded in standard CI. |
| 2026-06-30 | Fragment-split the 1932-line surgical-logbook.feature monolith into 18 per-area BDD fragment files under e2e/bdd/features/logbook/ (entry, clinical, surgery picker, case list, dashboard, widgets, import flow/validation, OCR, review, work-queue, access, cadence, FHIR/SNOMED, SNOMED write-gate, API, reports, drafts), following the #6229 fragment convention used by cpd/ and wellness/. | #9810, #9801 | A single 1932-line .feature file is a merge-conflict hotspot across concurrent PRs (every PR adding a scenario edited the same file). Splitting into focused per-area fragments — each near/under ~200 lines — lets parallel logbook work land without colliding, the same way #6229 did for cpd and wellness. |
| 2026-06-30 | Invert the on-device logbook case-draft patient-PII control (stripPatientPii) from a denylist to an allowlist. The persisted draft now keeps ONLY explicitly-listed known-safe structural keys (procedure, area, hospital, ASA, involvement, patient category, satisfaction, operative time, date, ids/foreign keys) and drops everything else by default — any field added to the form later is excluded automatically rather than persisted until someone remembers to denylist it. localStorage-only write path, 24h TTL, and clear-on-submit/clear-on-discard are unchanged. AC logbook.case.draft-persisted updated. | #9809, #9798, #9371 | The original denylist (#9328 Option B) stripped known patient-identifying keys before each device write and relied on "remember to add new PII fields here as the form grows", so a newly-added field would leak to plain device storage until someone updated the denylist. Patient name + DOB are confirmed special-category data (DPO decision #9371 item 1, the engineering-recommended next safe default), so an allowlist — exclude by default, opt structural keys in — is the safer posture. The allowlist stays in the React-free shared util typed <T extends Record<string, unknown>> so it remains importable from the playwright-bdd step path without dragging the heavy form type into the step type-check program (the TS2742 / step-tsc baseline trap). Backend encryption-at-rest, DPIA/RoPA, and the encrypted server-side draft remain policy/DPO decisions on #9371. |
| 2026-06-30 | Fixed a demo-blocking dead end on the import wizard's Map Columns step. The step gates the Finish button on every required target field being mapped, but the warning showed only a count ("1 required field(s) unmapped"); because the table is source-column centric, an unmapped required target had no row of its own, so the surgeon could neither see which field was missing nor reach a control to set it. The unmapped-required summary is now an always-visible Alert above the (already scrollable) mapping table that NAMES each missing required field and offers a semantic per-field "Map" button which scrolls to and focuses the first unmapped source column, making every unmapped required field both visible and reachable. Unit tests assert each missing field renders as a semantic button and that clicking it focuses the first unmapped source column; a @regression @issue-9786 BDD scenario clears the Patient ID mapping and proves the field is named with a reachable Map affordance. | #9790, #9786 | Hit during UAT demo prep — a logbook file whose auto-suggest left a required column unmapped left the import permanently stuck with no way to discover or fix the offending field. No spec AC was removed or added as a Matt-confirmed requirement; this is a defect fix to the existing logbook.import.map-columns-* behaviour, recorded here for traceability. |
| 2026-06-30 | Answered logbook Open Question Q8 (FHIR export shape) — the FHIR export exposes the Procedure resource type only for the current phase, matching the shipped single-Procedure OpenAPI surface; added AC logbook.api.export-resource-shape. Additional resource types and third-party consumer onboarding are deferred until a licensing consumer requires them. | #8814 | The FHIR API interface + token feature shipped (#7017) with a single Procedure endpoint, but which resource types the export should ultimately expose — and the consumer-onboarding process — were an unresolved Open Question (Q8) with no tracking decision. Recorded the engineering/product default (Procedure-only for now) so the export shape is governed rather than implicit, with expansion left as an explicit future decision. |
| 2026-06-30 | The import wizard's Map Columns step now offers "Date of Birth" as a mappable target field. When a DOB column is mapped, the backend derives each row's age at surgery (age = floor((surgery_date - dob) / 365.25)) and auto-classifies the patient category — under 16 at surgery is Paediatric, otherwise Adult — taking precedence over any Patient Category column. A DOB that cannot be parsed for a row is non-blocking: that row still imports with its patient category left for the existing Patient Category column / manual entry, and a preview warning names the affected row. A blank or unmapped DOB column leaves behaviour unchanged. | #9846 | Part of the #9829 UAT-session follow-up — surgeons often have DOB in their source spreadsheet but no pre-computed age or category, so deriving it on import removes manual data entry and avoids classification errors. The under-16 Paediatric cut-off is the threshold stated in issue #9846 and applies only to the new DOB-derived path; it is intentionally distinct from the 17-year cut-off the pre-categorised Patient Category / Patient Age column path uses (#8099). That divergence is an engineering default recorded here for traceability, not a Matt-confirmed clinical requirement — flagged for-discussion so the single canonical paediatric threshold can be confirmed. |
| 2026-06-29 | Implemented the premise-independent Section A engineering tidy-ups from the RACS MALT deep review. Added a canonical involvement-code set (ALL_USER_INVOLVEMENT_OPTIONS / isKnownInvolvementCode) and a proper zod enum (involvementCodeSchema), enforced only on the activities create/insert input so a new case cannot be created with an unrecognised userLevelInvolvement / verifiedInvolvement (clean 400). Enforcement is deliberately NOT on the update path: the assessor-review submit and the doctor's own edit re-send the stored involvement value verbatim, so a pre-existing record carrying a legacy/vernacular value must still be verifiable/editable (the shared read schema also stays lenient; conConsultantInvolvement stays unconstrained for the same round-trip reason, #8473). Added notifyAssessorOnLogbookSubmission so the responsible consultant (assessorId) is emailed when a logbook case is submitted for sign-off, mirroring the WBA assessor email (#5026), via a new email/templates/logbook-assessor.ts template wired into activitiesCrud. Documented the assessorId (approval/sign-off) vs supervisorId (CPD-credit) distinction in the Drizzle schema. New ACs logbook.entry.involvement-code-enum, logbook.review.assessor-email-on-submit, logbook.data-model.assessor-vs-supervisor, and email.template.logbook-assessor; two @regression @issue-9189 BDD scenarios. | #9781, #9189 | The RACS MALT review (#9189) split findings into Section A (engineering tidy-ups, not licence-gated) and Section B (MALT-standard model decisions). Matt questioned the MALT-alignment premise itself and the 24 Jun catch-up confirmed PPP will bridge from the UK system and build its own level-of-involvement model rather than aligning to RACS MALT, so Section B (structured complications + Clavien-Dindo grade, a discrete Primary-Surgeon outcome flag with binding de-dup, multi-procedure-per-case, off-platform/alternate supervisors, formal RACS MALT licensing #1740) is deferred to Matt and recorded as Open Question Q-malt-alignment. Only the premise-independent Section A items were built; a physical assessorId/supervisorId column rename was deferred as a higher-risk separate refactor (~200-reference blast radius). |
| 2026-06-29 | Non-consultant Add Case "Level of Involvement" dropdown now uses PPP's own vernacular — Observed, Assisting, Trainer (unscrubbed), Trainer (scrubbed), Primary — led by a distinct Primary vs Secondary operator axis, instead of the RACS-derived Primary/Secondary × Independent/Supervised matrix (#8473). Adds OPERATOR_AXIS / pppOperatorAxis / PPP_NON_CONSULTANT_LOI to the shared constants. Stored involvement codes are unchanged; the legacy Partial Procedure (PP) and Training another Trainee (TaT) codes are dropped from the selectable non-consultant list to match Matt's confirmed five-option list. | #9780, #9187 | Matt's 2026-06-24 call (recorded on #9187), confirmed by Rob — PPP bridges from the UK logbook system, not RACS, so the LoI must use PPP's own vernacular and not align heavily to RACS/MALT. Supersedes the non-consultant half of logbook.entry.involvement-vernacular (#8473). The consultant LoI labels are confirmed different and pending the logbook design spreadsheet, so they are left as a clearly-marked PPP-default placeholder (PPP_CONSULTANT_LOI) and the consultant dropdown is unchanged — see Open Question Q-consultant-loi. |
| 2026-06-29 | Role chip hover tooltip on logbook case cards now shows the Primary/Secondary × Independent/Supervised vernacular label instead of the raw involvement code string. | #9730, #8944, #8473 | UAT reported Level of Involvement display inconsistency (#8944). The add-case form dropdown was already corrected by #8473; this closes the remaining gap where the card hover tooltip still exposed the raw stored code. |
| 2026-06-27 | Added an end-to-end @smoke BDD scenario (logbook.fhir.au-edition-end-to-end) proving that under an active AU instance_config (snomed_edition = .../32506021000036107) BOTH the frontend live picker $expand URL and the backend SNOMED matcher ValueSet target the same AU-edition value set .../32506021000036107?fhir_vs=<au value set>, sourced from instance_config. The picker URL is captured for real via a stubbed fetch over searchConcepts; backend parity is proven via the shared resolveProcedureValueSetUrl mirror plus source inspection of the matcher's $expand wiring. | #9601, #9549, #7883 | Wave 2 of #7883 — joins the edition slice (#8875) and the value-set slice (#7884) into a single AU-deployment guard so a regression in either de-hardcoding (picker reverting to the UK/default edition, or the matcher diverging from the picker) is caught end-to-end. Runs in standard CI with no live backend; depends on the AU instance_config provisioning (Wave-2 item). |
| 2026-06-27 | Provision the Australian instance_config so the AU deployment resolves SNOMED CT-AU end-to-end — AU SNOMED edition 32506021000036107 (not the UK 999000031000000106 default), the constrained national AU Core procedure-1 value set (not the UK isa/71388002 default), and AUD/en-AU locale. The AU row is seeded by migration 0180_au_instance_config.sql, instance-gated on a custom app.ppp_instance_country GUC so it is a deliberate no-op on the UK database (and local dev) and can never give instance_config two rows. The backend service gains an AU_DEFAULT_CONFIG fallback alongside UK_DEFAULT_CONFIG, selected by PPP_INSTANCE_COUNTRY, so a fresh AU instance auto-creates AU defaults while UK behaviour is byte-for-byte unchanged. New AC logbook.fhir.au-instance-config. | #9597, #9548, #7883 | Epic #7883 moves the AU deployment onto SNOMED CT-AU as the system of record — the existing logbook.fhir.snomed-edition-config / procedure-valueset-config ACs read the edition + value set from instance_config, but only the UK was ever provisioned (the service auto-created a UK default). Wave 2 provisions the AU row so AU-namespace concepts (…1000036107) resolve and the picker is constrained to the national AU surgical set, without risking the live UK instance — the GUC gate guarantees the shared migration is a no-op everywhere except a genuinely-AU database. Pinning the AU edition version and the authoritative NCTS swap stay gated on #7885 / #7320. |
| 2026-06-25 | Add a reusable useFormDraft hook that debounce-persists an in-progress form to per-user/-form device-local storage (off formState.isDirty), restores it on remount, and clears it on submit AND on explicit discard/close; wire it into the logbook case form (consultant + non-consultant Add mode) via useLogbookCaseDraft. The on-device draft EXCLUDES all patient-identifying fields (urn, dobPatient, gender, and free-text summary/feedback/comments) via stripPatientPii — only non-identifiable form structure is persisted. Defence-in-depth: 24h TTL + purge-on-stale-read. New AC logbook.case.draft-persisted. | #9328, #9320 | The logbook case form held all entry state in memory and the unsaved-changes guard only fired on explicit close, so a surgeon whose phone backgrounded/evicted the WebView mid-entry lost the entire form (mobile best-practice epic #9320). Patient name + DOB are confirmed special-category data (Rob's DPO decision), so the PRIMARY compliance control is to never write patient-identifying fields to plain device storage — the draft persists only non-identifiable structure for crash recovery, and the surgeon re-enters patient identity on restore. A fuller encrypted server-side draft is the gold-standard follow-up if the DPO wants full recovery; the broader policy carries for-discussion. The hook is kept pure so CPD activity / WBA can adopt the same primitive later. |
| 2026-06-24 | Add Redis read-through cache to activities.getActivitiesByFilter keyed by userId+type+filterHash (TTL_DASHBOARD, ~2 min); cache is invalidated on create/update/delete mutations. | #9228 | Repeated identical filter queries from the logbook list view hit Postgres on every page load; caching at the service layer reduces DB load and improves dashboard response times (perf epic #9227). |
| 2026-06-24 | Align the Surgical Logbook case-list default date range with the Performance Overview (both now open on the same 1-year window) and drop the silent default "Source: Submitted" filter (Source now defaults to "All"), so the top-of-page total and the case-list count no longer disagree on first load. | #9217, #9185 | The "Surgical Performance Overview" defaulted to 1Y (e.g. Total 13) while the "Logbook Cases" list defaulted to 3 months plus a hidden "Source: Submitted" filter (e.g. 2 cases), so the two counts silently diverged on load with no visible reason (found in demo rehearsal). |
| 2026-06-24 | Fix the "Scan Operating List" OCR scanner so scanned cases actually persist as drafts — the import now sends confirm: true (it previously ran in dry-run mode and saved zero rows), success is reported from the server's real importedCount (not the client-selected count), and the CTA reads "Add N draft cases". | #9212, #8652 | Scanned cases never reached the Logbook or the grouped "Complete N Surgical Logbook drafts" To-Do because the scanner called importSurgicalLogbook without confirm: true, so the import previewed and persisted nothing while the UI falsely reported success. |
| 2026-06-24 | Documented the server-side authorisation guard on the logbook verify (sign-off) path in AC logbook.consultant-review.verify — a transition to verified requires the caller to be the case owner, assigned assessor/supervisor, or a super-admin, with the verifier id derived from the authenticated session. No code change: this guard already shipped with #6239 (PR #6277); #9188 was an investigation confirming it is present and complete. | #9188, #6239 | Issue #9188 (RACS MALT deep review, 2026-06-24) suspected the verify path lacked the assessor guard that the decline path enforces. Step 1 of the issue — confirm whether a higher-level procedure guard already restricts who can set status:'verified' before adding a duplicate — was honoured. Investigation found the guard is already enforced at the procedure layer: activities.update (api/backend-ppp/src/routers/procedures/activities/index.ts) rejects non-owner/assessor/supervisor/super-admin callers with FORBIDDEN for logbook cases, and logbook.update scopes non-admins to their own entries via enforceUserScope. The @regression @issue-6239 scenario "Non-assessor cannot verify a logbook case via the activities update API" (surgical-logbook.feature) exists, but its step definitions require a cross-user seeded case (caller must not be the case owner or assigned assessor) — this needs multi-user E2E fixture infrastructure not yet available (#9188). The guard is proven at the service-unit level. The issue's evidence only inspected the service layer (logbookService/index.ts) and missed the procedure-layer guard. Closed as not-a-bug; the spec AC is made explicit so the authorisation contract is no longer implicit. |
| 2026-06-23 | Made a large surgical-logbook import observable, legible, and resilient. The importSurgicalLogbook procedure now publishes per-batch progress to an in-process registry keyed by a client-supplied importJobId, exposed via a new getImportProgress query the wizard polls to render a live "X / N rows" count instead of a static "Validating… 25%". Structured ctx.logger output now reports row count, per-batch progress, imported/skipped/invalid/duplicate/failed breakdown, peak RSS/heap memory, and an explicit failure cause with timing — so a net::ERR_FAILED has a matching server trace. A batch insert that throws now falls back to per-row inserts so one bad row only loses itself (recorded in failedEntries with its cause) rather than sinking the whole batch; the import still returns success with a summary of imported vs skipped/failed rows. | #9133 | Importing a full-career 2,000+ row logbook is a real user scenario. After the #9132 perf fix stopped the validation timeout, the import was still opaque (no progress, no server trace on failure) and fragile (a single insert error aborted the whole batch). This PR closes the companion observability/resilience ask: live progress via polling, structured logging incl. peak memory + explicit failure cause, and graceful partial-failure reporting. The progress registry is deliberately in-process best-effort (not a DB/Redis table) — the authoritative result is still the mutation return value; a poll that lands on another replica simply returns null and the wizard falls back to indeterminate progress, never worse than before. |
| 2026-06-22 | Adopted the shipped #7017 logbook API token behaviour as a safe least-privilege ENGINEERING DEFAULT, pending Matt's product confirmation (Open Q12 stays OPEN) — per-user scope, READ-ONLY for external consumers, optional expiry + immediate revocation, 90-day default expiry at issuance, and atomic rotation. Hardened the service to apply the 90-day default, added logbookApiTokens.rotate (revoke + reissue in a single DB transaction), and made the public FHIR endpoint reject non-GET verbs with 405. Flagged for-discussion for Matt's sign-off. | #9144, #8816, #7299 | The #7017 token feature shipped with engineering-default semantics Matt never confirmed (Open Q12). Matt's thread question (whether an on-sold third-party FHIR-logbook API is issued as a 90-day token) is still open and his "token" may instead be the enterprise-subscription discount concept — so this is NOT a settled product decision. The team ratified the shipped behaviour in code as the safe default (least-privilege, consistent with mcp-provider.md Q1–Q4) while keeping Q12 open for Matt. Rotation was additionally hardened to be transaction-atomic (a crash between revoke and issue could otherwise strand the owner with a revoked token and no replacement) and the read-only guarantee made explicit via a 405 method guard. |
| 2026-06-20 | Default Surgical Performance Overview widget to open on first visit; persist collapse choice per user in localStorage. | #8991, #8949 | UAT: mobile user (iPhone) found the widget collapsed by default with no indication content existed — #8949. WidgetSection now defaults to expanded on all viewports and remembers the user's explicit collapse/expand choice via localStorage keyed by sectionId + userId. |
| 2026-06-20 | Gated the master-surgery bulk import path (importMasterSurgeries) with a SOFT FHIR $validate-code check against the configured procedure value set — invalid codes do NOT abort the import; they are collected into snomedValidationWarnings in the result summary for admin triage. A valid-but-inactive (retired) concept is flagged needs_review instead of being silently stored approved, matching the createExternalProcedure pattern. The validated snomed_edition + snomed_version are stored alongside each coded row for reproducibility (using the existing columns from migration 0173). $validate-code calls are batched with a concurrency cap of 5 to avoid overwhelming the terminology server on large lists. | #8984, #7885 | The spec AC for #7885 says "gate every stored SNOMED code" — this PR implements the remaining ungated write path after createExternalProcedure was gated in #8900. The soft-gate design (warn+flag, not hard reject) diverges from the spec AC wording "rejects" because bulk admin imports must never fail-stop on a single bad code in a spreadsheet of hundreds of rows — the admin needs to see which codes need remediation and continue the import. This divergence is recorded here per the #5273 convention. |
| 2026-06-20 | Added logbook.display.filters-popover-close — the logbook Filters popover now exposes an explicit close IconButton ("Close filters") and a "Done" button, both wired to the existing dismiss handler. | #8955, #8943 | On a phone viewport the filters popover fills the screen (92vw / 80vh) with no discoverable dismiss control; Matt's UAT report (#8943) — "took me a while to work out where to click to get out." |
| 2026-06-19 | Gated every external-procedure write with FHIR $validate-code (code + display) against the configured procedure value set — a write is rejected when the code does not exist / is not in the value set or the display does not match the SNOMED concept, and a valid-but-inactive (retired) concept is flagged needs_review instead of being silently stored. Added snomed_edition + snomed_version provenance columns so each entry is reproducible (migration 0173). | #8900, #7885 | createExternalProcedure previously stored whatever code-and-display pair it was handed with no server-side check that the code exists, is active, or matches the concept — the control that makes 100% SNOMED linkage accuracy enforceable. NCTS-independent slices (1 + 2) of #7885; runs against the public CSIRO Ontoserver. The authoritative AU NCTS server swap + corpus re-validation (Slice 3) stay gated on #7320, so #7885 remains open. |
| 2026-06-19 | Interim guard — a procedural (non-surgeon) user with no matching procedures gets External Lookup only with a friendly empty-state, never the all-surgical master list. | #8890, #8815 | The Practical/Procedural Logbook label ships for non-surgeon doctors (logbookVariant === 'procedural'), but no physician procedure dataset exists yet — only the 10 surgical lists. The #8190 never-empty fallback was serving a physician surgical procedures (heart transplant etc.). This suppresses that fallback for the guarded user and steers them to SNOMED/external search. The real RACP dataset lands later — #8815 stays open (logbook Open Q9). |
| 2026-06-19 | Lifted the hardcoded isa/71388002 full-Procedure-subtree value set out of BOTH the frontend live picker and the backend SNOMED matcher into a single instance_config.procedure_value_set switch, read by both via a mirrored resolveProcedureValueSetUrl. Defaults to isa/71388002 (no regression); an AU instance can point it at the national AU Core procedure-1 value set in one config row. | #8889, #7884, #7883 | The full-subtree binding was duplicated in two call sites, and string-matching the whole Procedure tree produced clinically wrong codes. A spike confirmed AU Core procedure-1 already expands on the public CSIRO Ontoserver (constrains to in-set AU surgical concepts), so the constraint is build-ready now; the authenticated NCTS binding stays gated on #7320 (#7885) and the RACS MALT refset remains banned until a formal agreement (#1740). |
| 2026-06-18 | De-hardcoded the SNOMED edition — the backend auto-matcher + seed-extraction scripts now resolve the edition + ValueSet from instance_config (same source as the frontend picker), so picker and matcher agree on a procedure's code. | #8886, #8875, #7883 | The frontend picker already read the edition from instance_config, but the backend hardcoded the UK edition, so a procedure could resolve to different SNOMED codes in the picker vs the stored masterlist. Slice A of #7883; build-ready on the public CSIRO Ontoserver, independent of NCTS (#7320). Falls back to the historic UK edition when instance_config is absent (no regression). |
| 2026-06-18 | Added AC logbook.entry.sticky-action-bar: the logbook-case form action row (Edit / Save / Discard) is now pinned to the bottom of the form's scroll container so the controls stay reachable without scrolling. Implemented as an opt-in sticky prop on the shared FormLayout.Actions row; the logbook FormActionsSection opts in for both consultant and non-consultant case forms. | #8843, #8787 | Split from #8654 — Matt asked to edit a long form without scrolling to the top/bottom to find the Edit button (enhancement, not crucial). MyProfile already carried its own sticky edit bar (#7383); this completes the logbook side as a shared form-layout affordance rather than a one-off. |
| 2026-06-18 | Import resolution can no longer confirm a case against an admin-rejected procedure: the specialty-scoped surgery picker hides rejected procedures and the server-side confirm path (resolveConfirmedProcedureMatch) returns null for a rejected id, so a smuggled rejected id falls back to a gated draft. External (user-added) procedures stay selectable. Adds logbook.import.no-confirm-rejected-procedure. | #8841, #8582 | Found during PR #8572 review (#8467): the import resolution picker offered every procedure including admin-rejected ones, and confirming against one made the case count as a confirmed match on the dashboards. Matt chose option 2 ('2 - Hide rejected procedures', 2026-06-16) — rejection is an explicit admin decision and import resolution shouldn't bypass it; external additions are legitimate and stay (option 2, not 3). |
| 2026-06-17 | Built the in-app tree-navigable procedure selector UI for AC logbook.fhir.snomed-tree-structure — a Category → Subcategory → Principal index → Procedure navigator in the Add/Edit Case surgery picker (new ProcedureTreeNavigator, "Browse Tree" mode in SurgerySection), consuming the existing logbook.getProcedureTree query (#7319) alongside the flat search. | #8825, #8813 | AC logbook.fhir.snomed-tree-structure listed the selector UI as remaining work; the tree query existed server-side (#7319) but had no frontend consumer. This adds the consumer as the smallest correct slice. NCTS-validated SNOMED codes per leaf (#7320) and the curated principal-index mapping (Open Q13) remain separately tracked. |
| 2026-06-17 | A saved logbook case matched to a master-list procedure keeps its Principal Procedure / Treatment Acuity / Broad Area / Specific Area detail when re-opened and switched into edit mode, so the case still uploads. The detail is now re-derived directly from the hydrated procedure relation on the record, independent of the specialty-scoped surgery picker. | #8785, #8649 | Matt's UAT reopen of #8649 — "the logbook data was added... Then when reclicking the logbook entry the principal procedure and following details had been erased". The Consultant form's bare form.reset() on entering edit mode reset procedureRefField to empty-string defaults, and the picker-based restore only re-derived the fields when the matched procedure was in the specialty-scoped list, so a case whose procedure sits in another specialty re-blanked its four required fields and failed required-field validation on save. |
| 2026-06-17 | Patient demographics fields renamed to clinical standard — "Date of Birth" (was "Pt DOB") and "Sex" with options Male/Female/Not stated (was "Pt Gender" with M/F/Other/Prefer not to say). Legacy stored values are normalised for backward compatibility. Completeness prompts and export column headers updated to match. | #8749, #8725 | Matt's UAT feedback — "where is DOB male female etc?" — the logbook already stored these fields as dobPatient and gender columns; the labels and option vocabulary needed to reflect clinical recording standards (Sex, not Gender; full words not abbreviations). |
| 2026-06-17 | OCR scan (Scan Operating List) no longer pre-populates Time or Level of Involvement — surgeon-supplied fields excluded from the ExtractedCase mapping and csvData import payload. | #8748, #8724, #8644 | Time on a printed operating list is an admin artefact, not the actual operative time; Level of Involvement must be set by the surgeon completing the form. Matt's explicit feedback was that these should never pull through from an OCR scan. The review table columns Role and Time are replaced by Notes (a reliable extractable field). All other fields (procedure, hospital, date, patient ID, notes) continue to extract. |
| 2026-06-17 | Reconciled the logbook performance-satisfaction control from a 1-10 scale to 1-5, matching the closed Q5 decision. Changed maxValue 10→5 in both Add/Edit case form variants (Consultant, NonConsultant) and the consultant review screen; added the logbook.entry.satisfaction-scale AC and a decision source for Q5. | #8739, #8598 | The shipped control was 1-10 but docs/features/logbook.md Q5 (closed, Rob acting-PO 2026-05-21) records the decision as 1-5; the control contradicted the recorded decision. Verified the Q5 citation is a firm dated decision (authoritative), so the control was corrected rather than the spec. The literal star-glyph rendering noted in Q5 stays an open question — only the 1-5 range is corrected here. |
| 2026-06-17 | Surgical logbook customise-widgets edit mode is now reorder-only — widgets are NOT deletable (the per-widget remove badge and the Add-widgets tray are removed, along with the shared AddWidgetTray component and the removeWidget/addWidget/hiddenWidgets hook API). Desktop reorders via a drag grab handle; mobile reorders via up/down arrows. Inherited from the shared customise framework change. | #8671 | The surgical logbook shares the dashboard-agnostic customise framework with the PPP dashboard, so the #8671 reorder-only / not-deletable decision and the desktop-handle/mobile-arrows breakpoint split apply here too. Supersedes logbook.dashboard.customise-add-remove; updates logbook.dashboard.customise-widgets and logbook.dashboard.customise-persistence. (#8671) |
| 2026-06-16 | An imported logbook case whose procedure did not match a master-list procedure (stored with no procedureId) now surfaces its captured best-guess procedure detail into the read-only Principal Procedure / Treatment Acuity / Broad Area / Specific Area fields (new AC logbook.entry.imported-unmatched-procedure-surfaced), and shows an inline prompt guiding the surgeon to select a matching surgery to confirm and complete the case. | #8695, #8649 | Matt's UAT bug #8649 ("failing to upload from app"): an imported case opened on the app showed four blank required procedure fields, so the case failed required-field validation and could not be saved. Root cause: imported cases whose procedure did not match exactly are stored with procedureId NULL (importSurgicalLogbook.ts), and useLogbookFormInitialization only populated those read-only fields when procedureId !== null. The import already stored best-guess detail in importNotes.procedureMatch.*Name + originalData.operationDescription but never surfaced it. resolveImportedProcedureRefFields now pulls that detail into the fields for unmatched imports, and SurgerySection prompts the surgeon to confirm a matching surgery. Distinct from the unmatched-hospital import block fixed in #8661. Covered by resolveImportedProcedureRefFields unit tests and a @regression @issue-8649 BDD scenario. |
| 2026-06-16 | Unmatched hospital no longer blocks the surgical-logbook import (new AC logbook.import.unmatched-hospital-no-block). A typed-but-unmatched hospital is non-blocking: the case imports with hospital_id NULL and the free-text hospital captured for later resolution, and the import preview offers a per-row hospital picker (the DB-backed hospital.list search) so the surgeon can correct it before importing. Confirmed hospital ids are validated server-side; no canonical hospital row is ever invented. | #8661, #8648, #8649 | Matt's UAT bug #8648 (and #8649) found imported cases were "not found / not directed where they are" and uploads "failing from app". Root cause: any hospital that did not match the canonical hospitals table pushed a blocking validation error (importSurgicalLogbook.ts:521), excluding the row; when every row's hospital was unmatched the preview reported "0 valid entries", disabled Proceed Import, and nothing imported. Real-world driver: Matt's ~4,000-case export sources every case to "Metro North", an HHS (not a selectable hospital), so it can never match. Fix mirrors the in-wizard procedure match-confirmation pattern (#8467) for hospitals and honours the #8444 decision that the DB is the source of truth (no invented hospitals). A @regression @issue-8648 BDD scenario asserts an all-unknown-hospital workbook still imports and offers per-row correction. |
| 2026-06-10 | Add an on-demand at-scale logbook import test: a workflow_dispatch-only backend test (importSurgicalLogbook.scale.test.ts) that drives the real import pipeline over an anonymised fixture derived from Matt's actual ~4,000-case surgical record, asserts every row ingests (#7766), reports a procedure/hospital match-rate breakdown, confirms non-exact matches are gated out of the performance charts (#8466), and measures the logbook list + dashboard-widget aggregation latency at scale. A new logbook-import-scale-test.yml workflow (workflow_dispatch only) runs it against a Postgres service container and uploads the match-rate + timings report as an artifact. Adds logbook.import.scale-verification. | #8618, #8602 | Per #8602: before the Tue 16 Jun demo press (and Matt's weekend testing) we must be able to prove import + display at ~4k scale on demand. A 4k-row import is too heavy for every CI run, so the test is workflow_dispatch only (precedent: load-test.yml) and excluded from the default vitest include. The fixture is anonymised — patient names/URNs synthesised, dates uniformly shifted, surgeon-name annotations scrubbed — while procedure-name strings, source hospitals, involvement and acuity values are preserved verbatim so matching behaviour is representative; the raw file stays in Google Drive only. |
| 2026-06-10 | Gate the Add Logbook Case "How Satisfied were you with your performance?" rating to primary-operator involvement only: the question renders only when the selected Level of Involvement is a primary-operator value (consultant Performed roles PA/PCC/PPT; non-consultant Principal Operator P), and a previously-entered satisfiedPerformance value is cleared when the question hides. Adds logbook.entry.satisfaction-primary-operator-only. | #8617, #8542 | Matt''s UAT bug report #8542 ("Satisfaction question should only be when level of involvement is the primary operator") supplied a previously-unspecified conditionality. The satisfaction question had always rendered unconditionally, and both the spec (Q5 settled only scale/optionality) and the BDD codified always-shown behaviour. Deep-dive decision (2026-06-10): strict primary-operator gate (Option 1), reusing the existing shared isPrimaryOperatorInvolvement() helper — the same gate the consultant review screen already uses for competency scoring. The supervised-trainee widening question is pending with Matt (a one-line constant change to Option 2 if he says yes). |
| 2026-06-10 | Profile Surgical Cadence prefills a per-specialty whole-of-training case default from the ISCP/JCST curriculum structures — adds logbook.training-totals.curriculum-default. | #8616, #8552 | Issue #8552: in-training surgeons needed to research their own curriculum number before the #8195 pace monitor could coach them. Each default is the verbatim overallIndicativeOperations.total from the matching curriculum-structures JSON (#8490): Cardiothoracic 250, Neurosurgery 1200, Otolaryngology 2000, Paediatric 1990, Plastic & Reconstructive 2100, Congenital Cardiac 100. Per Matt''s frozen rule (carried from #8490) engineering extracts numbers from the curricula and never invents one, so a specialty whose curriculum states no overall total (General Surgery, Maxillofacial, Urology, Vascular — all total: null) gracefully gets no default. The prefill is user-overridable and the stored cadenceTracker.totalCasesTarget remains the single source of truth (prefill, not a hidden fallback), keeping the #8195 "coaching only when a target is set" rule meaningful. |
| 2026-06-10 | Replace the removed Surgical Logbook widget reorder arrows with an iOS-home-screen-style "Customise" edit mode: a discoverable Customise/Done toggle, a banner, per-widget remove badges + drag/move controls, drag-reorderable cards, and a bottom "Add widgets" tray for hidden widgets. Choices persist per user, per dashboard, across devices via a dashboardLayouts JSONB map on the user profile. Built as a dashboard-agnostic shared framework. Adds logbook.dashboard.customise-widgets, logbook.dashboard.customise-add-remove, logbook.dashboard.customise-persistence. | #8609, #8241 | Rob (acting PO, 2026-06-10) approved the Option A mockup for #8241 — the old hover reorder arrows were clunky and offered no way to hide widgets. Built under components/widgets/dashboard/customise as a dashboard-agnostic framework (useDashboardCustomisation hook + CustomisableDashboardGrid + edit-mode chrome) so the cascade to other dashboards (#8592) reuses it. Persistence follows the cadence-targets path (#3329): a layout map is unstructured config, so a dashboardLayouts JSONB column (migration 0161) is the right shape; the proc + UserFormData validate it against the shared dashboardLayoutsSchema. Accessibility per #7773 (real buttons, visible-label = accessible name), 44x44 touch targets (#3700), tokens only (#7525); edit mode works at 390px (tray scrolls horizontally, up/down move controls are the drag fallback). |
| 2026-06-10 | Added code-paths for logbook.ts | #8606, #8485 | Logbook constants belong to the surgical logbook spec; drift gate now fires correctly when logbook constants change, per #8485 |
| 2026-06-10 | Fix the auto-opened reflection dialog so the linked-case reminder shows the real operation name and hospital from the just-created surgical case (conforms to logbook.reflection.searchable-reminder-fields; no AC text change). | #8604, #8556 | Matt's UAT bug report #8556 (2026-06-10) found the reflection reminder panel showed "Operation: N/A" / "Hospital: N/A" after a case was logged on /logbook-case. The dialog was fed the bare activities.create insert row, which has no nested procedure.principalProcedure / hospital relations (those only exist on logbook read queries via LOGBOOK_WITH_CLAUSE), and the hospital name was resolved through the country-filtered list which dropped on a null hospitalId or country mismatch. The AC was already correct — the create→reflection flow was violating it. Fixed frontend-only via a one-shot logbook.getById re-read; backend create-response shape unchanged. The hospital-search list pathology itself overlaps #8585 and is owned by that track. See retrospective.md for the sibling reminder-fields AC and the same fix entry. |
| 2026-06-10 | Resolve guessed procedure matches inside the import wizard: the import preview lists every non-exact match in a "Confirm procedures" panel (source text → best-guess + confidence → specialty-scoped procedure picker); confirmed rows are re-keyed server-side to the chosen procedure as matchType exact so they count in performance charts immediately; unconfirmed rows still import as gated drafts. Adds logbook.import.confirm-matches-in-wizard. | #8572, #8467 | In-wizard half of Rob''s 2026-06-10 walkthrough steer on #8443 ("the UX makes these easy to see and does not accept the data until these are matched"). #8466 shipped the post-import half (chart gate, needs-attention pipeline, Action Items guidance); #8467 asked for the surgeon to be able to resolve guesses before the import completes — without ever blocking the import (#7766/Q4). Per the #8466 review security note, the matchType upgrade happens server-side via resolveConfirmedProcedureMatch keyed off the chosen procedure id; a client can never claim exact directly. |
| 2026-06-10 | Consolidated cadence/pace monitor at the top of the surgical logbook — one compact strip (goal · done · remaining · pace status) absorbs the two TOTAL CASES / PRIMARY SURGEON header cards and adds three-state pace coaching (Ahead of / On / Behind pace) with one encouraging line per state referencing the quarterly goal. Adds logbook.dashboard.pace-monitor, logbook.dashboard.pace-monitor-coaching and logbook.dashboard.pace-monitor-visibility; collapses the two per-card cog ACs into a single strip-cog AC. | #8571, #8195 | Dev Session 2026-06-03: the profile cadence settings feed a 3-month pace but there was no cadence/pace monitor on the surgical logbook — add one at the top (goal, remaining, how they are tracking, coaching element). Engineering defaults agreed with Rob 2026-06-10: absorb the duplicate header cards rather than adding a third surface with the same numbers (the 3-Month Rolling Goal widget in the Logbook Report stays as the drill-down); derive the three coaching states from the existing deriveQuarterlyPace backend maths (#8042/#8045) with no new maths; show coaching only for in-training users with a training target + expected completion date (Matt 06-04/06-09 steer) — everyone else keeps a plain totals strip. Per-specialty curriculum-default training totals are follow-up #8552. |
| 2026-06-10 | Add Case hospital UX + sticker OCR identifier preference: the Hospital dropdown pre-lists the doctor's attached hospitals on open (typed search unchanged at 2+ chars); the default hospital is the last one a case was saved with (per-user, device-local), falling back to the first assigned (#8339); sticker OCR extracts the NHS number and hospital/trust ID separately, prefers the trust ID for the Pt Hospital Number / URN field, and rejects letter-dominant/over-long OCR junk. | #8568, #8480 | Matt's UAT report (mobile Add Logbook Case): dropdown should show pre options of attached hospitals rather than having to search; selected hospital should be remembered for next entries; NHS stickers should bring through the trust ID as the pt number, not the NHS number, and number pull-through had brought through text incorrectly. |
| 2026-06-10 | The Add Case surgery picker now defaults to the user's OWN specialty masterlist; the "Other Specialties" toggle widens it to the full master list (internal and user-added external procedures); External Lookup (SHRIMP/SNOMED CT) stays as the third tier. A user with no specialty — or a specialty with no procedures — gets the full master list, never an empty picker. The specialty-scoped procedure query is Redis-cached per scope and flushed on every procedure write. Adds logbook.entry.specialty-scoped-surgery-picker and logbook.entry.surgery-picker-redis-cache. | #8567, #8190 | Matt (Dev Session 2026-06-03, verbatim) — "this needs to be pulling from our FHIR enabled master list... it will tie to the specialty for the user... select other specialties... then external lookup". The picker showed wrong data (e.g. heart transplant for an orthopaedic surgeon) and froze loading every procedure on each form open (#8190). |
| 2026-06-10 | Similar draft logbook to-dos in Action Items now collapse into a single grouped row ("Complete N Surgical Logbook drafts") that starts a stepped completion flow — the first case opens ready to complete, each save rolls to the next automatically, every item is individually skippable (Resume / Skip / Exit flow bar), and the row shows "x of n done" progress. The notification-bell count and the Action Items count remain deliberately distinct per Matt's decision. | #8496, #8101 | After importing 15 incomplete cases, Action Items showed 15 separate identical rows. Matt (Dev Session 2026-06-03) asked to itemise so it reads as "one type of thing but there's 15 within it", with clicking "tak[ing] you through step by step each one … automatically rolls through them"; the bell-vs-Action-Items count mismatch was decided acceptable (#8101). |
| 2026-06-10 | Level of Involvement option labels now lead with the Primary/Secondary × Independent/Supervised vernacular the widget shows — adds logbook.entry.involvement-vernacular. | #8492, #8473 | Matt (Catchup 2026-06-10, verbatim): "level of involvement this is old vernacular. This isn''t like the primary independent primary supervised secondary independent secondary supervised." Display labels only — the stored value remains the original involvement code string, which exact-match keys the widget bucketing (supervisionMetrics.ts), the chart palette, toShortRoleLabel and the UK eLOGBOOK import mapping (#8099), so no data migration and no classification change. Labels are derived from the same classification arrays the widget buckets by, so the dropdown vernacular cannot drift from the widget; unknown/legacy stored values display verbatim. |
| 2026-06-10 | Import needs-attention pipeline: per-case missing-field indicator, "N need attention" chip + filter, unconfirmed procedure-match gate (partial/fuzzy/failed matches excluded from performance charts until confirmed), import-result warning, and confirm-then-complete Action Items guidance. Also: "Import Logbook" rename, stray-0 import-result fix, first-person involvement label + help-text cleanup on the add-case form, Principal Procedures competency hover restored, dead AddRetrospectiveButton removed. | #8466, #8443, #8442, #8451, #8193, #8305, #8281 | Rob's 2026-06-10 walkthrough: after a bulk import the doctor could not see which cases needed attention or what was missing, and partially-matched procedures were silently accepted into the charts — 'the UX makes these easy to see and does not accept the data until these are matched', with 'clear action items that intuitively explain what needs to be complete'. |
| 2026-06-10 | Relocate the digital-signature confirmation ("Check this as your digital signature…") from the Add Logbook Case screen to the consultant review/confirm screen, where it gates Verify — adds logbook.consultant-review.signature-on-review, logbook.consultant-review.competency-feedback-capture, and logbook.consultant-review.dual-profile-visibility, plus Open Question Q-signature-audit. | #8192 | Matt (Dev Session transcript 2026-06-03 ~00:51:58) read the prompt on the Add Case screen and called it "an error that''s been carried through onto this screen… this is already then they''re saving submitting it… this prompt I believe is for the consultant user once they''re going through that second screen of confirming." The same session asked engineering to step through the non-consultant→consultant workflow (action item, level-of-involvement check, competency score + feedback, dual-profile logging) — those paths were verified in code and pinned with ACs/tests rather than changed. The confirmation remains a UI-only gate (never persisted); whether Verify should write a signature audit event is raised as Q-signature-audit for Matt. |
| 2026-06-03 | Reverse the Add-retrospective control back to visible inline multi-select tick-boxes — adds logbook.entry.retrospective-options-inline and supersedes logbook.entry.add-retrospective-dropdown (#6392). | #8191, #6392 | Matt''s 2026-06-03 Dev Session called the button+dropdown built in #6392 a regression and asked for the options to be visible inline again ("restore from the previous code"). This directly reverses his own 2026-03-11 request (the source of the #6392 dropdown AC), so it is logged as a deliberate reversal, not a silent removal. We propose multi-select tick-boxes (restoring the pre-#6392 control) rather than the literal "radio" Matt mentioned, to preserve linking more than one retrospective per case (#7460); the March→June direction and the radio-vs-tick-box choice are held as Open Question Q-retrospective-control pending Matt''s confirmation. |
| 2026-06-02 | Logbook import now captures the clinical detail columns the Surgical Performance Overview breakdown charts read — Patient Category (Adult vs Paediatric), ASA Grade (ASA distribution) and Supervision/Responsibility (Primary vs Secondary, via the sanctioned UK eLOGBOOK mapping plus a conservative plain-English fallback for unambiguous AU terms), plus Case Acuity on the case — instead of dropping them. | #8160, #8099 | Import persisted only hospital/date/patient ID/operation/notes/responsibility and hardcoded attributes={}, so imported cases were invisible to the Adult vs Paediatric, ASA and Primary vs Secondary charts (drift against 'Imported cases included in Surgical Performance Overview'). Captures what is present; the completion to-do flow (#8100) covers the rest (#8099). |
| 2026-06-02 | Incomplete (draft) logbook cases are now clearly actionable in Action Items — the to-do names the clinical detail fields still to complete (acuity, role, patient category, operative time), or prompts to finish and submit when all are present, and opening it from Action Items opens the case ready to complete (editable) rather than read-only. | #8159, #8100 | Imported/scanned cases land as drafts and surface as Action Items per spec Q4, but read as a generic "Surgical Logbook" row with no guidance, so it wasn't obvious what to do or that completing them is what makes them count in the Performance Overview (#8100). |
| 2026-06-02 | Flips logbook.entry.training-total-target ⏳ → ✅. The stored cadence target (cadenceTracker.totalCasesTarget / primarySurgeonTarget) is now interpreted as a whole-of-training total, and getThreeMonthGoal derives the rolling 3-month goal from (cases remaining ÷ years to the expected-completion CCT date) ÷ 4 — re-pacing as cases are logged — instead of the old annualTarget / 4. With no usable CCT date there is no derived goal (null, never negative/Infinity) and the TargetGauge widget prompts the doctor to add a completion date. Existing users with a stored total are prompted once to re-confirm it via a new users.cadence_targets_confirmed_at column (migration 0153) + cadenceTarget tRPC router + CadenceTargetConfirmBanner. | #8107, #8042 | Deep-dive resolution on #7344 (Rob, acting PO, 2026-06-02), completing the cadence model #8083 (#8045) deferred. Pace basis = remaining ÷ years-to-CCT (re-pace); no-CCT → hidden gauge; confirmation persisted in a typed column rather than the cadenceTracker JSONB (queryable, typed, consistent with the sibling expectedCompletionDate column). Default reference totals remain PROPOSED, gated on Matt (onboarding Q5, tracked on #8047). |
| 2026-06-02 | Add the CCT-date-derived years-remaining divisor helper (SurgicalLogbookWidgets/cadencePace.ts derivePace/yearsRemaining) that feeds the per-year and per-3-month surgical pace read-out. Cited from logbook.entry.training-total-target. | #8083, #8045 | #8045 captures the doctor's expected-completion (CCT) date and derives the pace divisor from it. The helper lives under SurgicalLogbookWidgets, so the logbook spec records the new code path. The stored-target re-definition and the getThreeMonthGoal annual÷4 change remain out of scope under #8042. |
| 2026-06-02 | Logbook doughnut widgets adopt the calibrated compact thin ring (shared THIN_DOUGHNUT_CONFIG innerRadius raised to desktop 90 / mobile 64), slimming the heavy 45/35px ring to a light ~30/26px ring matching the /ppp-dashboard standard. | #8065, #8003 | Rob's direction to elevate the CPD dashboard to a 2026 compact standard and DRY-cascade that look across the site; the surgical logbook charts read as "too thick" versus the dashboard. Calibrating the single shared config fixes every doughnut consumer (CPD, logbook, appraisals, retrospective, timesheets) at once. |
| 2026-06-02 | Updated logbook.display.case-type-button-colour AC: the three case-type buttons keep a single on-brand primary blue (no differential blue scale) but are now arranged as a hierarchy — + Add Logbook Case solid (primary CTA), Scan Operating List / Import Logbook Case outlined-blue (secondary) — matching the wellness dashboard action row. | #8102 | During the 2026-06-02 UX review Rob chose to keep the new one-primary/two-secondary button hierarchy on /logbook-case (clearer primary action, consistent with wellness) and adjust the spec to match, rather than revert to three identical solid buttons. The original AC only forbade a differential scale of blues; an outlined-vs-solid variant hierarchy in the same primary blue satisfies that intent while giving the + Add action visual priority. Relies on the outlined-primary theme variant added the same session so outlined buttons render brand blue, not grey. |
| 2026-06-02 | Logbook import accepts imperfect data (valid rows import, invalid rows are fixable not fatal), preserves multi-procedure/competency rows, and records each case's origin (imported / scanned / manual) with a distinct badge. | #7766 | Proving Matt's real 2,204-row surgical record imports seamlessly surfaced two gaps — multi-competency lines were silently de-duplicated and OCR-scanned cases were indistinguishable from spreadsheet imports (both set isImported=true). Rob's direction: import imperfect data and let the user fix it; show imported data as imported, separate from OCR/manual. |
| 2026-06-02 | Invalid rows on the logbook import preview are now editable inline — the surgeon corrects the highlighted field(s) or skips a row and re-validates, importing the corrected data without re-uploading the file. | #8054 | Carved out of #7766. The backend already imported valid rows and returned the invalid ones; the remaining fix-not-fail gap was the UX. Rob's direction: allow import of imperfect data and let the user fix it instead of failing to import. |
| 2026-06-01 | Surgical case target reframed as a whole-of-training total (logbook.entry.training-total-target) — PPP derives per-year and per-3-month pace from the doctor's expected completion (CCT) date, refining the meaning of cadenceTracker.totalCasesTarget/primarySurgeonTarget. | #8005, #7344 | Matt (#7344) — the doctor should enter the total cases to achieve across their whole training, from which PPP works out the per-year and per-3-month pace; the current "per year" framing (and getThreeMonthGoal dividing an annual target by 4) is misleading. |
| 2026-06-01 | Mechanical data-hygiene pass over the specialty-procedures seed datasets for AC logbook.fhir.snomed-data-cleanup. A directory-wide scan confirmed there are no concatenated parent-child SNOMED CT codes left to split in any *-db-ready.json / *-review.csv / raw *-procedures.json file. Removed the one remaining byte-identical exact-duplicate procedure row (general-surgery "Gastroenterostomy", SNOMED 18692006, childhood-GI area) at its raw source and in sync across the db-ready JSON and review CSV (406→405 rows). Added an exact-full-row-duplicate hard gate to validate-snomed-codes.mjs (findExactRowDuplicates), a snomedSeedIntegrity.test.ts unit test asserting no concatenated codes and no exact duplicate rows across all 10 db-ready datasets, and an @regression @issue-7850 BDD scenario. | #8002, #7850 | Matt flagged the dirty RACS curriculum export in the 2026-05-13 Dev Session — merged SNOMED cells and duplicate rows. This delivers the safe mechanical half for the specialty datasets without any clinical judgement: same-name+code rows that differ only by anatomical area (e.g. the other three Gastroenterostomy placements; the plastic-surgery lesion-biopsy pair) are PRESERVED for Matt's clinical review (#7366), not auto-collapsed. NCTS-confirmed code validity remains deferred to #7320 (live Ontoserver cross-check is blocked on manual NCTS business verification). |
| 2026-06-01 | Added a clinically-relevant SNOMED CT procedure tree derivation (Category → Subcategory → Principal index procedure → Procedure) via buildProcedureTree and the logbook.getProcedureTree query. | #7867, #7319 | The logbook procedure selector needs a tree-navigable view. The tree is derived from the existing procedure dataset rather than hand-curating new clinical data; curated per-specialty principal-index mapping remains pending Matt's sign-off (Open Q13). |
| 2026-05-28 | Filter bars now consume the shared PillDateRangeFilter; doughnut widgets share the THIN_DOUGHNUT_CONFIG from the canonical ThinDoughnutChart component. | DRY refactor — eliminate duplicated chip-preset and chart-radius logic so a single source of truth governs the date-range pill and thin-doughnut look across the app. | |
| 2026-05-27 | Brought /logbook-case onto the shared compact look & feel and polished the Surgical Logbook import flow. Added logbook.display.on-brand-page, logbook.import.map-columns-sample-tooltip, and logbook.import.dialog-on-brand. | #7821 | Demo polish (28 May). The page header row and the Logbook Cases panel were hand-rolled; they now use the shared PageHeader and the compact SectionCard primitive (thin 1px border, ~13px text, tight spacing) matching /cpd-dashboard. The import dialog title, wizard stepper, and Map Columns step were tokenised (SEMANTIC_COLORS / SPACING / FONT_SIZE) so there are no hardcoded hex/px and a rebrand is one-touch. Map Columns sample data is surfaced via a hover tooltip on the Source chip (#7771) so the Map-To dropdown stays full-width and readable; the two unit tests that still asserted sample data as visible text/column were updated to assert the tooltip. |
| 2026-05-27 | Mark logbook.import.strip-empty-columns as built; the import parse step now strips empty columns before the Map Columns screen. | #7745, #7740 | Excel sheets carry thousands of trailing/empty columns that cluttered the Map Columns step and blocked scrolling to the Accept button (re-raise of #3945). A pure stripEmptyColumns(headers, rows) helper now drops columns with no data (blank/auto-generated header or any header with all-empty cells) before headers+rows reach MapColumnsStep, while keeping any column that contains data even if unlabelled and preserving header/sample-data alignment. |
| 2026-05-27 | Multi-consultant feedback — N consultants can each add separate feedback to one operation, with independent per-consultant Retrospective visibility. Both Multi-feedback ACs flipped from ⏳ to ✅. | #7709, #7505 | The related_forms plumbing already supported N feedback children, but the create path blocked a second consultant (blanket "feedback type exists" guard) and the StatusTracker upserted on (type, input_record_id) so a second consultant's feedback overwrote the first. Each feedback child is now keyed by a per-author trackingId (feedback:author:<id>), and the authoring consultant is resolved from the caller identity, so N distinct consultants' feedback persist as separate related_forms rows. Retrospective Feedback-tab rendering remains owned by #7307; this issue aligns the data contract only. |
| 2026-05-27 | Mark OCR hospital-name matching against linked hospitals + unknown-hospital confirm prompt as built; add logbook.ocr.hospital-matching and logbook.ocr.unknown-hospital-confirm AC IDs. | #7686, #7506 | OCR-detected hospital names are matched against the user's linked hospitals (confident match auto-selects) and unknown hospitals are confirmed before save — no silent free-text. Implementation landed under #4838; this issue formalises the AC IDs, spec wording, and @smoke BDD coverage. |
| 2026-05-26 | Split the conflated logbook.api.interface-spec AC into interface-spec + token-access, marked both ✅ Built (#7017), and added Open Question Q12 for unspecified token policy. | #7545, #7299, #7017 | SGD transcript audit of #7299. The §APILicensing passage (~00:56:04) supports the API interface spec; the Next-steps action item ("an API interface and token feature") supports the token mechanism. Implementation already shipped under #7017 (openapi.json, logbook_api_tokens migration 0113, Bearer auth). Token semantics (scope/expiry/read-only) were never Matt-stated, so they are surfaced as Q12 rather than asserted as ACs. |
| 2026-05-26 | Reconcile three stale ⏳ markers in the Consultant review section to ✅ — logbook.consultant-review.decline-required-reason, logbook.consultant-review.decline-notifies-submitter, and logbook.consultant-review.resubmit-after-decline — and flip the "Consultant review + sign-off" Status row from ⚠️ Partial to ✅ Built. No code or BDD change: the decline/resubmit flow (consultantDecline procedure + dialog, logbook_case_declined notification, resubmitDeclined preserving audit metadata, DeclinedBanner resubmit CTA) shipped under #6085 and the non-assessor guard under #6239; scenarios already exist at surgical-logbook.feature:353–372. | #7509, #7501, #6085, #6239 | Code-verification during the #7325 decomposition found the consultant review decline flow was already fully implemented and tested, but the spec markers still read ⏳. Doc-only reconciliation to make the spec reflect shipped reality. |
| 2026-05-26 | Index Procedures — implement per-index-procedure target volumes. Users can define a target volume per principal/index procedure in their plan (persisted in cadenceTracker JSONB under indexProcedureTarget:{principalProcedureId} keys, settable via the new dashboardLogbook.setIndexProcedureTarget mutation). The Principal Procedures dashboard widget now shows a Target Volumes progress section per index procedure, counted at the principal_procedure level via the procedures.principal_procedure_id FK. Flips the two Index Procedures ⏳ markers to ✅ (logbook.index-procedures.user-target-volumes, logbook.index-procedures.dashboard-progress). | #7504 | Outstanding per-index-procedure target tracking distinct from the already-shipped total/primary-surgeon case targets. No schema change required — targets reuse the existing users.cadenceTracker JSONB column, so no migration. Counting derives from the principal_procedure_id FK (not denormalised text) per the spec Index Procedures section. |
| 2026-05-26 | Add a Verhoeff SNOMED CT check-digit validator (api/backend-ppp/scripts/validate-snomed-codes.mjs, wired as pnpm validate:snomed and a green CI gate) that scans the confirmed db-ready procedure datasets and rejects any code whose check digit fails — the structural signature of Excel-mangled concatenated parent-child codes. Removed the 3 duplicate procedure rows (same name + SNOMED code) from procedures.json. Emitted a flag-don't-fix review CSV (scripts/seed-data/snomed-invalid-codes-review.csv) cataloguing the 79 known-bad legacy Orthopedics codes plus 4 low-confidence needs-review matches. Added an @regression BDD scenario asserting the confirmed db-ready datasets contain no invalid SNOMED CT code. | #7322, #7367 | Matt flagged in the 2026-05-13 Dev Session that the RACS export is a "dirty system" — some cells contain two concatenated SNOMED CT codes (parent + child merged by Excel) and there are duplicate rows. This PR delivers the deterministic, safe half: a structural validator + dedup + a flagging CSV. The 79 mangled Orthopedics codes are NOT auto-corrected — they need Matt''s clinical sign-off and route through the #7366 review-sheet flow. Live NCTS cross-check remains blocked on #7320 (the --ncts flag is a soft stub). #7367 is the same defect (a duplicate symptom) and is covered by this validator. |
| 2026-05-22 | SGD audit 2026-05-13 (evening): add 3 new ACs — SNOMED CT clinically-relevant tree structure, dirty data cleanup, NCTS API authentication prerequisite. | #0, #7319, #7320, #7322 | Transcript audit of May 13 evening session. Matt explicitly described the need for a category→subcategory→principal-index tree, flagged dirty/concatenated SNOMED codes, and confirmed NCTS registration is awaiting manual business verification. |
| 2026-05-21 | Mark logbook.fhir.health-blueprint-alignment as built; verify FHIR R4 Procedure export + SNOMED CT coding satisfy the 2032 Australian Health Blueprint AC. | #7147, #7016 | AC was ⏳ despite the implementation being complete — FHIR R4 Procedure endpoint (GET /fhir/r4/Procedure/{id}) and SNOMED CT code storage on the procedures table were already in place from prior work. This PR closes the spec gap, adds @issue-7016 to the BDD smoke scenario, and adds a second scenario verifying the export endpoint shape. |
| 2026-05-21 | logbook.api.interface-spec: dedicated OpenAPI 3.0 spec artifact (src/rest/fhir/openapi.json) + logbook_api_tokens table + Bearer token auth on FHIR R4 Procedure endpoint — enables third-party data integration and platform feature licensing. | #7017, #6336 | Matt and Rob agreed in the 2026-05-13 catchup (§APILicensing ~00:56:04) that a formal API spec and token-based access mechanism is needed to position the platform for external data integration. The spec artifact makes the interface machine-readable and contractual; the token mechanism allows integrators to authenticate without SSO credentials. |
| 2026-05-20 | Verified deferred AC logbook.api.interface-spec is correctly marked ⏳ with transcript citation (Dev Session 2026-05-13 AM §APILicensing ~00:56:04). No implementation required — the AC calls for a dedicated specification artifact (not docs) defining a third-party API interface and token-based access mechanism leveraging the FHIR architecture for platform feature licensing. Remains deferred until Matt prioritises external-data-licensing work. | #TBD, #6336 | SGD gap-analysis follow-up; confirms AC accurately captures the discussion (Rob Duncan / Matt Randell) about Runkeeper-style API for third-party integration and FHIR-based licensing. No code or spec text changes — the ⏳ marker, citation, and (#6336) link are already in place at docs/features/logbook.md line 323. |
| 2026-05-20 | Verify flexible (fuzzy/semantic) import column auto-matching — flip logbook.import.column-flexible-matching ⏳ → ✅. | #6394 | columnMappingEngine.ts already implements alias normalization, substring containment, and Levenshtein-distance matching with confidence scoring, so the AC from Dev Session 2026-03-18 §ColumnMatching is satisfied. |
| 2026-05-19 | Implements logbook.reflection.tag-to-surgical-entry — standalone reflection form now exposes a "Tag to surgical logbook entry" Autocomplete picker that writes the selected entry id to attributes.logbookId, creating a traceable link between a learning tidbit and a specific case. Hidden when the form is auto-triggered from a freshly saved logbook entry (link is implicit). Picker reuses ppp.logbook.list, which is already server-side scoped to the caller via enforceUserScope. | #6586, #6399 | Matt directive in Dev Session 2026-05-19 §ReflectionTagging (~00:45:53): "Reflections allow users to tag learning tidbits to surgical entries". Flips the AC from ⏳ to ✅. |
| 2026-05-19 | logbook.reflection.searchable-reminder-fields flipped ⏳ → ✅. When a reflection is linked to a surgical logbook entry, the reflection form now surfaces the operation name and patient hospital number / URN as read-only reminder fields. The reminder block ("Linked Logbook Entry:") renders whenever logbook context is present — the auto-triggered create flow OR an already-linked reflection opened in view mode — not only during auto-trigger. operationName is resolved from the linked logbook record's nested principalProcedure relation. @regression @issue-6398 BDD scenario added to surgical-logbook.feature. | #6559, #6398 | Dev Session 2026-03-25 §ReflectionFields (~00:28:31) — "operation and hospital number as reminder fields; searchable by hospital number, clinical area, and user-defined title". Prior to this the form only showed a context block during the auto-trigger flow and never surfaced the operation name; the change is additive (optional field + broader render condition) and does not alter reflection persistence. |
| 2026-05-19 | logbook.consultant-review.verify-notifies-submitter flipped ✅. When a consultant verifies a non-consultant's logbook entry, an in-app logbook_case_reviewed notification ("has verified your logbook case") is now emitted authoritatively server-side in logbookService.updateLogbookEntry on the transition into the verified status. The Work Queue review dialog previously hard-coded isReview: false and sent NO notification on verify — the server-side emit closes that gap and covers every review surface. The redundant client-side notifyLogbookCaseReviewed helper is now a no-op to prevent a duplicate notification; self-verification (verifier === submitter) is suppressed. | #6544, #6335 | Transcript 2026-05-13a §EntryVerification (~00:26:39): "a notification sent back to the non-consultant user once verified". The AC was tracked but unimplemented for the Work Queue review path; moving the emit server-side makes it robust across all review entry points and immune to client-side race conditions. |
| 2026-05-19 | Implemented the minimal onboarding-import ring-fence (#6334): legacy logbook data imported during onboarding is flagged (isImported = true) and excluded from a new active-engagement metric. getActiveEngagementMetric (api/backend-ppp dashboardService/logbook/timeAnalytics) computes ongoing platform use over a rolling 90-day window counting only platform-created (non-imported) logbook cases; imported entries are tracked for transparency but never satisfy isActivelyEngaged. Exposed via the dashboard.logbook.getActiveEngagementMetric tRPC procedure with server-side user-scope enforcement. AC logbook.import.onboarding-ring-fence flipped to ✅ (minimal version) and Open Question Q11 added for the precise timing/quota rules. @wip BDD scenario replaced with an executable @regression @requires-backend @issue-6334 scenario. | #6518, #6334 | §LegacyImport (~00:22:53): Matt and Rob agreed bulk historical upload must not substitute for ongoing daily platform use. The exact timing/quota constraint rules were left TBD; this ships the agreed sensible minimal version (imported data ring-fenced out of active-engagement measurement) and surfaces the remaining decisions as Open Question Q11 rather than inferring requirements. |
| 2026-05-19 | Imported logbook entries are visually distinguished from manually entered ones with a 45° diagonal hatching pattern (case cards + list Origin cells). | #6491, #6396 | AC logbook.display.imported-vs-manual-hatch (src:transcript-2026-03-25 §ImportedVsManual ~00:12:07 — "hatching pattern differentiates imported vs manually entered data for WCAG compliance"). The prior treatment used colour + chip only; this adds a true repeating-linear-gradient hatch so the distinction is perceivable without relying on colour alone (WCAG 2.1 AA SC 1.4.1). Flips the AC from ⏳ to ✅. |
| 2026-05-19 | Verify and lock in logbook.import.back-button — the import wizard already provides a Back button at each step and preserves the selected spreadsheet file across step navigation (no re-selection required). AC flipped ⏳ → ✅; @regression BDD scenario added. | #6489, #6395 | SGD gap audit (#6395) flagged this AC as unverified. Investigation confirmed the feature is already implemented — ImportWizard renders a Back button whenever activeStep > 0 and the UploadStep is hidden via display:none (not unmounted) so parsed-file state survives going back (#3320). Locked in with a @regression scenario to prevent future drift. |
| 2026-05-19 | The three logbook case-type toolbar buttons (Scan Operating List / Import Logbook Case / + Add Logbook Case) now all use color="primary" so they render in one consistent on-brand colour instead of a differential blue scale. | #6485, #6397 | Matt flagged a differential scale of blue across the three case buttons in the 2026-03-25 Dev Session (§LogbookColour ~00:10:08); colours must be consistent and on-brand. |
| 2026-05-19 | The "Add retrospective" entry point on a logbook case is now a single button that opens an inline dropdown of the retrospective options (Reflection / WBA / Feedback) directly from the button — replacing the previous separate per-type checkboxes. No intermediate navigation screen; selecting an option flags the matching retrospective to be created and linked on case save. | #6392 | Implements AC logbook.entry.add-retrospective-dropdown — transcript-2026-03-11 §AddRetrospective (~00:32:25): "three options appear as roll-down from the button; no intermediate navigation screen". Saves a tap by removing the intermediate screen. |
| 2026-05-19 | Introduce the surgical_case parent entity linking multiple logbook activities for one multi-participant operation. New surgical_case table + nullable surgical_case_id FK and participant_role enum on activities; duplicateDetection(URN + date + procedure) graduates from warn-only to auto-link; consultant logbook roll-up groups by surgical_case_id. ACs logbook.case.parent-link, logbook.case.consultant-roll-up, logbook.case.participant-role flipped ⏳ → ✅; @smoke BDD scenarios un-@wip'd. | #6084 | 13 May 2026 catchup (transcript 00:20:29–00:21:42) — one physical operation may involve N juniors + a consultant each entering their own row, producing consultant double-feedback and no single-surgery view. The parent grouping is purely additive (nullable, back-fillable columns; only duplicateDetection semantics change warn → link), honouring Matt's "do not change the code that exists" constraint. |
| 2026-05-13 | Deep-dive after 13 May catchup with Matt — adds three additive sections to the spec without changing any existing AC: (1) Surgical Case parent model for multi-participant entries (one row per participant linked by surgical_case_id; converts duplicateDetection from warn-only to auto-link; respects "do not change" by keeping per-user activity rows intact); (2) WBA / Reflection / Feedback Activation Flow — audit-only table documenting today''s relatedFormService.LogbookHandler pipeline so Matt can validate the data drawn into each child form; (3) Reject/Decline path on Consultant review — net-new addition (declineReason + declineCategory + declinedBy + declinedAt on the activity, in-app notification to submitter, resubmit flow). Plus new index-aligned bullet on Practical (non-surgical) Logbook test data loading (gdrive xlsx, post-demo). | Captures the design landed against the 13 May catchup. Matt''s repeated constraint "do not change the code that exists" is honoured throughout — the parent model is one nullable column on activities plus a new surgical_case table; the WBA/Reflection section is read-only documentation; reject/decline is purely additive (new procedure, new dialog, new banner). No existing behaviour or schema column changes. | |
| 2026-05-13 | Transcript audit 2026-05-13 (evening, 18:13 BST) — all passages CONFIRM or C (context/operational). Zero new ACs. Session was primarily operational: burnout/workload, 31 logbook issues created, UAT paused for 40-PR sprint, grant research, team expansion (Kristen), Ireland company move, May 28 demo milestone, security vulnerabilities (tracked by CI), SNOMED CT data quality (logbook Q1/Q9), NCTS API authentication (operational dependency). | #~ | §EmailBranding (~00:06:07): "adjust header sizes and resolution for professional quality, AMC-comparable" — F (feedback), CONFIRM (CPD provider email branding already in cpd.md/timesheets.md from 2026-05-06). §SecurityVulnerabilities (~00:22:18): "5 critical vulnerabilities, wide-area security framework needed" — F, already tracked by security-scan CI workflow; not a new AC. §DataMapping (~00:34:04): "dirty data, need logical tree structure for SNOMED CT operations" — F/Q, CONFIRM as logbook Q1/Q9 (specialty datasets, data quality). §NCTSAuth (~00:34:56): "awaiting manual authentication to connect to NCTS API" — C (operational dependency). All other paragraphs are C (personal well-being, financials, startup pressures, team expansion, grants, company structure, demo prep) — no product requirements. |
| 2026-05-13 | Pin favourite operations to top of surgery selector — star toggle persists to localStorage per user. | #6225, #6108 | Matt requested a favourites affordance on the procedure selector (Notion Logbook brief) so frequently-used operations are instantly reachable without scrolling. |
| 2026-05-13 | Correct the Index Procedures example in the spec — counting target volumes is at the principal-procedure level (e.g. "Major Joint Arthroplasty"), not at the specific procedure name (e.g. "total knee replacement"). The procedures seed has a dedicated principalProcedure column; for Orthopaedics, 60 underlying rows roll up into Major Joint Arthroplasty. Adds a forward-reference to that data shape so the same convention is applied when each specialty curriculum is extracted (#6086–#6095). | Matt flagged the error in Notion comment 2026-05-13 after reviewing my earlier comment: "I think some errors in the analysis, for example the comments reference total knee replacements as principal/index procedures whereas I know this is listed as Major Joint Arthroplasty for principle/index procedure. NB a total knee replacement is one of the Major Joint Arthroplasty''s. In our data set these have all been mapped per principal/index procedure (dedicated column) so you''ll be able to see where it''s gone wrong." Confirmed in seed data: 2,815 ortho rows, 60 mapped to principalProcedure = "Major Joint Arthroplasty". Fixing now so the same mistake doesn''t propagate into the per-specialty extraction issues. | |
| 2026-05-13 | Transcript audit 2026-05-13 (morning, 06:29 BST) — 10 new ACs added across new sections (FHIR & Standards, Display, API & Data Licensing); 7 existing BDD scenarios back-filled with corresponding spec ACs (dashboard widget refinements already built and in BDD but missing from spec); Q8 updated with partial context (third-party licensing as use-case confirmed); Q10 added (wheel/donut chart widget ambiguity); 3 @wip BDD scenarios added (FHIR alignment, onboarding ring-fence, API interface spec); Status table updated with 13 new rows. CI/CD pipeline paused for demo (C — no AC). Multi-user model, WBA activation, OCR, consultant verification, and exportable report already in spec — CONFIRM. | #~ | §FHIRAlignment (~00:19:04): Matt confirmed the logbook will be FHIR-enabled to align with the 2032 Australian Health Blueprint using SNOMED CT — no explicit AC existed despite being in the feature description. §LegacyImport (~00:22:53): timing and ring-fencing constraints on bulk historical import are NEW (the basic import capability was already specified; the constraint is new). §DashboardWidgets (~00:41:09/00:45:31/00:49:35/00:50:55): Level of Involvement label, Trauma vs Elective position 2, Adult vs Paediatric (under 16) at position 3, JCST/Case Source removal, and Principal Procedures show-all were all in BDD as implemented scenarios (#6098, #6100, #6101, #6102, #6214) but had no corresponding spec ACs. §LargeDataset (~00:53:11): list/tile toggle already in BDD (#6106) but missing from spec. §ExportableReports (~00:55:04): report builder with date/widget/ASA selection already built (#6109/#6222) but no spec AC. §APILicensing (~00:56:04): API interface specification for third-party data licensing is NEW. Q10 added for wheel/donut chart ambiguity (~00:45:31). Multi-participant model, WBA flow, OCR, consultant verification, and SNOMED CT external lookup all CONFIRM (already in spec from earlier sessions). |
| 2026-05-12 | Engineering audit — close Q2 (external lookup: SNOMED CT/Ontoserver + dedup confirmed in code), partially close Q6 (consultant verify path built; reject path still open), fix two stale status rows (#4882 and #4878 both closed), flip Consultant review from Specified to Partial, close #4883 (SPO metrics do refresh reactively — invalidateLogbookWidgetQueries covers all 7 dashboardLogbook.* queries; logbook.getStats has no frontend consumers). | Code inspection against logbook.md revealed Q2 was fully answered by the existing ExternalSurgeryLookup + createExternalProcedure implementation, Q6 verify path was built (ReviewLogbookCaseForm sets verified status), the status table still showed #4882 and #4878 as open bugs despite both issues being closed, and grep confirmed logbook.getStats has zero frontend usages so the #4883 invalidation concern was moot. | |
| 2026-04-21 | Triage sweep — 15 open issues mapped to this spec | #5184, #5051, #5031, #4886, #4885, #4884, #4883, #4882, #4880, #4879, #4878, #4877, #4876, #4825, #4647 | Unblocks drift detection on the features index. |
| Jan 2026 | Multi-feedback per operation identified as gap | Walk-through notes | Single feedback insufficient for multi-consultant cases |
| Jan 2026 | Index procedures tracking identified | Walk-through notes | Curriculum requires volume tracking per procedure |
| Jan 2026 | Multi-consultant retrospective identified | Walk-through notes | ≥3 surgeons requires shared retrospective |
| Mar 2026 | Test artifact reference doc created | Surgical Test Artifacts doc | Centralised test file catalogue |
| Apr 2026 | OCR engine migrated from Google Gemini to Azure OpenAI GPT-4o-mini Vision | Epic #4637, PRs #4633, #4754 | Eliminate Gemini free-tier reliability risk, consolidate on existing Azure credits, pave the way for Structured Outputs |
| Apr 2026 | Added backend account-type guard (requirePppAccessProcedure) on all logbook tRPC procedures, plus activities.executeWizardImport, activities.importSurgicalLogbook, and activities.validateImportRows | #4881 | Prior to this, only UI-level redirects gated the logbook; a CPD-only subscriber could call the tRPC endpoints directly with a valid session. Fix enforces accountAccess ∈ { 'ppp', 'cpdppp' } on the server (super admins and internal calls bypass). |
| Apr 2026 | Import wizard: missing URN/Patient ID promoted from warning to error severity | #4920 | Frontend severity now matches backend validation so users can no longer advance a row that the backend will reject |
| 2026-04-22 | Drift re-baseline — 17 closed issues removed from Open Issues table, 15 new ACs added for live open issues, 6 new Matt product questions (Q4–Q9) raised. Status kept partial-drift pending Matt Q1–Q9. | #5345, #4647, #4825, #4876, #4877, #4878, #4879, #4880, #4882, #4883, #4884, #4885, #4886, #5031, #5051, #5184 | Spec was silently tracking closed bugs as open and had not translated Matt's 17 Apr brief into ACs. Audit at .drift-audits/logbook.md. Engineering label drift (feature:surgical-logbook vs feature:logbook) noted for Wave 6 rename. |
Sources & Recordings
| Source | Notes |
|---|---|
| https://drive.google.com/file/d/1HDF4acVA0QKImQ29Wu0rp_kVIgb-VGFVg_XwcZnUV6E | Description pending SGD audit |
| https://docs.google.com/document/d/1YhgQSFL9iOlQLoTrQYSwxRNXH4Dg4wefkItcwljQZmo | Description pending SGD audit |
| https://docs.google.com/document/d/1BTLAuAM1IMITJwCjK8cQV7S11ktl3HMWUjN8LpZniTg | Description pending SGD audit |