Skip to content
View in Notion

PPP Passport ​

Feature Overview ​

The PPP Passport (originally called "HR Passport" in Matt's brief; the code and route were renamed in #7810) is a portable, verified record of every piece of compliance documentation a doctor needs to start work at a new hospital. It replaces the current reality where every new hospital reproduces the same checks from scratch, re-verifies the same documents, and even re-mandates training the doctor has already completed recently elsewhere.

The commercial unlock is the Compliance Blue Tick: if a user carries a valid PPP Passport, the hospital accepts the tick in lieu of running its own process. Saves doctors time and saves hospitals the cost of running redundant admin.

📌 Matt flags this as the biggest single scope in his 17 Apr brief — six compliance domains, each with its own verification pathway, expiries, and jurisdiction variance. Build-out is multi-PR; this spec is the destination, not the first sprint.

Open Questions ​

#QuestionSourceOwnerStatus
Q2Rob review of Recruiter-supplied proof docs — what's the actual bar for acceptable immunisation evidence?Functions § ImmunisationsRob (then Matt confirm)Open — Rob research task.
Q3Hospital mandatory-training APIs — which hospitals publish, and can we pilot one?Functions § Mandatory TrainingsRob researchOpen — Rob research task. Matt named Green Brain as the example system: "the hospital system that we use at the moment is called green brain" (transcript 2026-05-12 ~00:56:04), and his Notion brief says "UK uses Green Brain ... is there an Aus equivalent?" (refreshed 2026-10-03; the earlier "used by Queensland Health" wording had no source). Engineering's proposed answer: assume no public API in MVP; build manual upload + verification flow first; add API ingestion as a per-tenant integration when a Q-Health-style customer offers credentials.
Q4Right-to-work digital API — which exists in UK, what's the AU equivalent (if any)?Functions § VisasRob researchOpen — Rob research task. Engineering's proposed answer: AU-first per project_au_first_uk_later — use VEVO (Visa Entitlement Verification Online, Home Affairs); UK Home Office Right-to-Work API deferred to UK launch phase.
Q5Immunisation titre evidence — which vaccinations are evidenced by a blood-test titre, and what is the below-threshold re-immunisation rule (value + unit, per jurisdiction)?Functions § ImmunisationsMattOpen — Matt input. Matt (2 Jun 2026, #7338): "often for items like Hep B and Hep C a blood test [shows] the required titre to remain immune … if it falls below a certain number then immunisation is required." The jurisdiction-driven required list + per-item records/dates evidence ships first (#7338 core); the titre-value + below-threshold "re-immunisation required" evidence type layers in once Matt confirms the affected vaccinations and thresholds. TODO(#7338) hook left on ImmunisationRequirement.
Q7Where does a doctor export their PPP Passport from? (a) an Export button on the PPP Passport page itself, or (b) a PPP Passport option in Reports.Matt, transcript 2026-07-14 ~01:13:02MattOpen — Matt: "either we make them exportable from their feature or we make them exportable from the ... reports". Rob was to propose options; nothing has been decided since. Blocks #12811.
Q8When one Passport item expires, what happens to the compliance tick? (a) it drops straight away, or (b) it shows "expired, renewing" for a grace period (engineering proposed 30 days) and then drops.Closed Q5 below was engineering-led, not MattMattOpen — refreshed 2026-10-03. The 30-day amber grace period was an engineering default (5 May); no Matt statement in the corpus mentions a grace period. Today the tick is a server boolean and the banner's amber means "incomplete", not "in grace".
Q9The Passport page shows the six domain cards at the top and the document tabs (Registration, Indemnity, Mandatory Training ...) below. Should (a) the domain cards be the only place to add and verify each item (remove the duplicate document tabs), or (b) both stay, with the tabs as a plain document store?Matt, transcript 2026-07-14 ~01:14:17MattOpen — Matt: "We just need to work out what these documents are doing like the top and bottom. I think that was a double up". Rob had no issue for it. Related: #12808 (the domain cards currently jump to the tabs).
Closed Questions (3) — click to expand
#QuestionSourceOwnerStatus
Q1Immunisation multi-vaccine OCR — worth the cost, or defer indefinitely?Functions § ImmunisationsMattResolved 1 Jun 2026 (Rob, #7941): BUILD IT. Reverses the prior "defer indefinitely" recommendation. A doctor scans one statement (AIR Immunisation History Statement / equivalent); Gemini-class Vision OCR extracts each vaccination, maps it to the jurisdiction-required rows, and pre-fills them as pending for the doctor to review — a PPP reviewer still verifies every row (OCR never auto-verifies). See [[hr-passport.immunisation.ocr-multivaccine]]. Image-only in MVP; PDF rasterisation is a follow-up.
Q5Blue Tick revocation — if one domain expires, Tick flips to false; is there a grace period, or instant?Engineering-raisedMattReopened as Q8 (2026-10-03) — Matt never confirmed this. Resolved 5 May (engineering-led): 30-day amber grace period. Tick goes green → amber → red. Amber for 30 days post-expiry with daily Platform Reminders nudging the user to renew; red after 30 days. Recruiters see amber as "expired but doctor is renewing"; red as "compliance failed".
Q6Recruiter-facing attestation URL — time-limited expiry default (24h? 7d?), and does it require the recruiter to authenticate?Engineering-raised (export)MattResolved 5 May (engineering-led): 7-day expiry, no recruiter login required — token in URL is signed JWT carrying the doctor's userId + scope. Recruiter scans QR or visits link, sees a public attestation page (no PII beyond what the doctor exports), one-time-use audit logged. Doctor can revoke any active attestation URL from their Passport screen.
Matt's Requirements (from Notion brief) ​

Issue ​

  • Every time a doctor starts at a new hospital they reproduce the same documents, redo the same processes, and often re-complete recent mandatory training.
  • The re-work is not because the docs are out of date — it's because there is no trusted global system.
  • Annoying for the doctor. Expensive for every hospital staffing the redundant admin.

Purpose ​

  • If a user has the PPP Compliance Blue Tick, the hospital agrees to trust it in lieu of running its own process.

Value ​

  • Saves time (doctor) and money (hospital).

Functions ​

  • Verification / Compliance tracking with expiry dates and renewal dates per document.
  • Reminders when an item is approaching expiry, has expired, or is otherwise non-compliant.
  • Blue Tick — a single roll-up status representing the user's overall compliance state.
  • Optional future capability: user uploads docs and the platform OCR-extracts relevant fields (Matt marks this as "maybe overkill for now" — parking it as a v2 enhancement). Update (#7808): the lightweight single-document field-autofill version of this is now built — see [[hr-passport.document.ocr-autofill]]. Update (#7941): the heavier multi-vaccine immunisation OCR is now built too — see [[hr-passport.immunisation.ocr-multivaccine]] (reverses the prior "defer indefinitely" on Q1).

The six compliance domains ​

1. Medical Registration ​

  • Jurisdictions: AHPRA (AU), local jurisdiction equivalents.
  • Verified via the PPP sign-up process (see onboarding.md).
  • Supports multiple jurisdictions per user (e.g. AHPRA + GMC for a doctor working across AU and UK — Matt's own case).

2. Medical Degree ​

Acceptable verification paths:

  • My eQuals (AU) — graduation verification service.
  • EPIC (Electronic Portfolio of International Credentials).
  • PPP Verification process — à la CPD Home's external-verification model (request → provider confirms → PPP stores the confirmation).

3. Indemnity ​

  • PPP Verification process to external indemnity provider (same pattern as CPD Home).
  • Expiries recorded and surfaced in reminders.

4. Immunisations ​

Likely multiple vaccinations recorded on one certificate.

  • Potential OCR multi-vaccine e-reader — similar pattern to the operations-list OCR used in Logbook. Matt flags this with a ? and notes "?associated cost" — so cost vs value is TBD.
  • Core vaccinations to cover:
    • Hepatitis B
    • Hepatitis C
    • Tetanus
    • Whooping Cough
    • TB — noting multiple acceptable proof types (e.g. IGRA, Mantoux, chest X-ray).
  • Rob task: review the documents emailed by the Recruiter to determine the extent of proof typically accepted, and use the same bar as PPP's default.
  • Expiries and renewal reminders per vaccination.

5. Mandatory Trainings ​

  • PPP Verification process for each training certificate.
  • Future capability: API calls to various hospital training systems to auto-verify completion.
  • Expiries + renewal reminders.
  • Jurisdiction-change handling: when a user switches jurisdictions, previously-required trainings may no longer be relevant. Surface a "no longer relevant" option at reminder time so users can acknowledge the change without being nagged forever.

6. Visas / Passport / Right to Work ​

Two paths depending on nationality + jurisdiction:

  • PPP Internal Review Process for docs — different expectations for local citizens (auto right-to-work) vs overseas employees (visas, sponsorship).
  • Local digital API checks where available. Matt notes these exist in the UK; not sure about AU — TBD.

Screenshots Comparison / Commentary ​

Matt's brief references the current moreton-vs-uat HR Passport journey at docs.professionalperformanceportfolio.com/journeys/moreton-vs-uat.html#_3-7-hr-passport-verification.

Required corrections:

  • Needs further work — confirm above-spec fidelity in the live feature.
  • Registration verified through our internal process — currently the screen doesn't make this clear.
  • Overall summary screen showing the user's complete compliance state at a glance (this is what the Blue Tick rolls up from).
  • Exportable function — user can export their PPP Passport as a single deliverable (for sharing with a new employer during recruitment). Not built yet: #12811, Q7.

Acceptance Criteria ​

Core — Passport data model ​

  • ⏳ Passport is a single entity per user with six sub-records (one per compliance domain).
  • ⏳ Each sub-record carries: status (pending | verified | expired | not_relevant), verified-at timestamp, expires-at timestamp (where applicable), verification pathway identifier, verifier identity, raw-document attachment (blob storage).
  • ⏳ Blue Tick computed server-side with three states: green (all required domains verified + not expired), amber (one or more expired but within 30-day grace period per Q5), red (expired beyond grace). Client never computes this locally.
  • ✅ Profile citizenship / residency status determines required-vs-optional per domain: AU citizens and AU permanent residents do NOT need right_to_work for Blue Tick; overseas doctors do (#5639).
  • ⏳ Full three-state Blue Tick (green / amber / red) with 30-day grace period on expiry (currently boolean true/false; three-state model is a future increment).
  • ✅ hr-passport.encryption-at-rest-and-in-transit — Hosting note (ADR-0006, 2026-08-05): the backend now runs on the NAS with the filesystem storage provider and HMAC-signed /storage/signed/:token URLs (15-minute read ceiling kept); the Azure Blob / Pulumi posture below describes the soak-period Azure estate, and the NAS at-rest posture is not yet documented (open). All Passport document blobs (Azure Blob Storage) are encrypted at rest using Azure Storage Service Encryption (AES-256, Microsoft-managed keys; customer-managed keys via Key Vault are a future hardening step). The encryption posture is pinned in Pulumi state on the storage account (encryption.keySource: 'Microsoft.Storage', encryption.services.blob.enabled: true, encryption.services.file.enabled: true) so a portal/CLI change cannot silently disable it. All Passport document transfers use TLS 1.2+ end-to-end (browser → API → blob storage), enforced by the storage account properties enableHttpsTrafficOnly: true and minimumTlsVersion: 'TLS1_2'. Anonymous blob access is disabled (allowBlobPublicAccess: false); reads are only available through signed short-expiry SAS URLs with a hard 15-minute (900s) ceiling enforced in getPublicUrl for any blob key matching a Passport path (medical_passport/, hr-passport/, ppp-passport/, etc.); never permanent public links. Upload SAS expiry remains ≤ 5 minutes. A security review gate must be completed and recorded before any production deploy of the HR Passport feature; once met, it is surfaced on the PPP website as a trust signal (12 May 2026). (#5943, #6170) † (#6383)
  • ✅ hr-passport.security.encryption-at-rest-in-transit — (Azure wording below; see the NAS hosting note on the companion AC.) passport documents are encrypted at rest (Azure Storage Service Encryption, AES-256, Microsoft-managed keys; pinned in Pulumi state with encryption.keySource: 'Microsoft.Storage') and in transit (TLS 1.2+ end-to-end via enableHttpsTrafficOnly: true + minimumTlsVersion: 'TLS1_2' on the storage account). Anonymous blob access is disabled; reads use short-expiry SAS URLs (15-minute ceiling for Passport paths, 5-minute upload ceiling). Trust-signal surfacing on the marketing website is tracked separately. See companion AC hr-passport.encryption-at-rest-and-in-transit above for the full posture. (#5943, #6170, #6383, #6560) † (#6384)

Medical Registration ​

  • ⏳ Primary registration captured at sign-up (see onboarding.md); verification status reflected in Passport immediately.
  • ⏳ Second jurisdiction can be added post-sign-up via Passport page (AHPRA + GMC dual-jurisdiction support).
  • ⏳ Expiry tracking tied to the registration body's renewal cadence.
  • ⏳ hr-passport.registration.internal-review — the "PPP Verification process" path for Medical Registration (used when My eQuals/EPIC are not applicable) follows the same internal-review pattern as CPD Home external-activity verification: user uploads document → PPP Staff member reviews and approves/rejects → status updated on Passport record. The review screen for PPP Staff is accessible from Super Admin. (21 Apr 2026) (#5985)

Medical Degree ​

  • ✅ hr-passport.verification.medical-reg-and-degree — the Passport verifies medical registration (AHPRA for AU via validateAhpraNumber, GMC for UK via fetchGmcRegistrant + licence-status gate) and medical degree; accepted degree verification paths are My eQuals, EPIC, or the internal PPP verification process — all three implemented in passportRegistrationService (#5610) and pppPassportMedicalDegreeService (#5611). † (19 May 2026, #6385)
  • ⚠️ User selects verification path: My eQuals | EPIC | PPP Verification (13 May 2026, #5611). Drift: the picker lives in MedicalDegreeCard, and nothing on /ppp-passport renders that card, so a doctor can't reach it (#12808).
  • ⏳ My eQuals / EPIC integrations return a confirmation artefact stored against the sub-record. (Integration stubbed pending API access; falls back to PPP Verification — #5611.)
  • ✅ PPP Verification path mirrors the CPD Home external-verification flow — request sent, provider approves via the existing pppPassportReviewService (#5985) review queue, PPP records (13 May 2026, #5611).
  • ✅ External fetch failures automatically route the submission to PPP Verification so the doctor's domain still progresses (#5611).

Indemnity ​

  • ✅ External verification request flow (CPD-Home pattern) — hrPassport.submitIndemnityVerification captures provider, policy number, expiry date, and the uploaded indemnity certificate; status becomes pending awaiting PPP Staff confirmation. (Certificate upload made required as step 1 of the two-step process — see hr-passport.verification.indemnity #6386.) (13 May 2026, #5612; updated 19 May 2026, #6386) Fixed 4 Oct 2026 (#12808): the Indemnity domain card on /ppp-passport now opens IndemnityCard inline, and the certificate is a real file picked by the doctor and uploaded under an owner-scoped key (ppp-passport/indemnity/{pppUserId}/…, usePassportEvidenceUpload) before submitIndemnityVerification is called. The free-text blob path field is gone.†
  • ⚠️ Expiry date captured from provider confirmation; 30-day advance reminder (passport_indemnity_expiry_reminder); re-verification flow at renewal — processExpiredIndemnityDomains auto-flips verified rows to expired past expires_at, and the IndemnityCard Re-verify CTA opens the same submission form. (13 May 2026, #5612) Drift (3 Oct 2026): the reminder and the auto-expire sweep now run daily at 21:30 UTC on the NAS backend (PASSPORT_DOMAIN_EXPIRY_TICK in entrypoints/api-container.ts, #12810). The Re-verify CTA is reachable since IndemnityCard was mounted (4 Oct 2026, #12808).††
  • 🅼 hr-passport.indemnity.no-screen-scraping — screen-scraping AU PI provider member portals (Avant, MIPS, MIGA) is out of scope on ToS, Privacy-Act, and reputational grounds. (#5948, 13 May 2026)
    • MVP: manual CoC upload + CPD-Home-pattern provider verification
    • Long-term: formal API partnership with the top three insurers (commercial track, not engineering)
    • Research: docs/features/research/hr-passport-pi-scraping-2026-05-13.md
  • ✅ hr-passport.indemnity-country-rules — Indemnity is required for Blue Tick in AU (doctors must hold their own medical indemnity cover). In UK NHS employment indemnity is generally provided by the employer (NHS Indemnity Scheme) and is therefore treated as optional for the Blue Tick for UK NHS personas. Country context is derived from Profile (country field) and an NHS-employer flag on the passport. The UI makes this rule transparent — a contextual note explains why the field is optional for UK NHS doctors (12 May 2026). (#5947) †
  • ⚠️ hr-passport.verification.indemnity — Drift (3 Oct 2026): the expiry reminder and auto-expire sweep now run daily on the NAS backend (#12810). The doctor-facing step 1 was unreachable, with a free-text blob path for the certificate; fixed 4 Oct 2026 (#12808), the Indemnity card opens IndemnityCard on /ppp-passport with a real file upload. Indemnity verification follows a two-step process: step 1 the doctor uploads their indemnity certificate (the documentBlobPath is now required on hrPassport.submitIndemnityVerification — submitIndemnityVerificationInputSchema rejects an empty path, and the IndemnityCard blocks submission until a certificate is attached); step 2 PPP Staff verify the uploaded certificate via the existing pppPassportReviewService queue, which flips the row to verified. The expiry date is recorded at submission and drives the 30-day compliance reminder (passport_indemnity_expiry_reminder) and auto-expire sweep. Whether a verified indemnity is required for the Blue Tick is governed by hr-passport.indemnity-country-rules (#5947): required in Australia, optional for UK NHS employees whose employer provides coverage. (19 May 2026, #6386) †

Immunisations ​

  • ✅ hr-passport.immunisations.jurisdiction-matrix — the required vaccination set is jurisdiction-driven: it is resolved from the doctor's hospital (country, state) via resolveRequiredImmunisations, not a fixed list. The rules themselves are configuration, not code — authored in immunisation-requirements-config.json (keyed by country / country-state), loaded and Zod-validated at module load by immunisationRequirements.ts, so a new jurisdiction or changed directive is a data edit. AU/NSW requires MMR, Hep B (+serology), Varicella, Diphtheria, Tetanus, Whooping Cough, annual Influenza, and TB screening; other AU states fall back to the AU national baseline until their directive is entered; GB carries the UK set. Hepatitis C is never a requirement (no vaccine exists). Onboarding captures the hospital (which resolves the jurisdiction) and ImmunisationsCard renders the resolved set; the Immunisations domain rolls up against it. The same mechanism serves the UK Prod deployment (the GB rows). Supersedes the prior fixed five-vaccination list (#5613). (1 Jun 2026, #7338; config-extracted 3 Jun 2026, #7968) ‡
  • ✅ hr-passport.immunisations.optional-influenza — a requirement may be marked optional in the config: it is offered for the doctor to record but is excluded from the domain roll-up / Blue Tick. Influenza is optional in the AU national baseline (Matt: not mandated nationally) and required in AU/NSW (mandated by NSW OASV PD2024_015). ImmunisationsCard shows optional rows with an "Optional" chip and the header reports "X of Y required verified" rather than a single blanket tick, giving per-item visibility. (3 Jun 2026, #7968) †
  • ✅ hr-passport.immunisations.titre-evidence-deferred — for vaccinations evidenced by a blood-test titre (e.g. Hep B), a below-threshold titre means re-immunisation is required. This titre-value + threshold evidence type is deferred pending Matt's confirmation of the affected vaccinations and per-jurisdiction thresholds (Open Question Q5); the records/dates evidence path ships first. A TODO(#7338) hook on ImmunisationRequirement marks the layering point. (2 Jun 2026, #7338) ‡
  • ✅ hr-passport.verification.immunisations — immunisation verification follows a two-step process mirroring the indemnity flow (#6386) and the CPD activity submission pattern: step 1 the doctor uploads supporting evidence per vaccination (documentBlobPath is now required on hrPassport.upsertImmunisation — upsertImmunisationInputSchema rejects empty / blank paths, and ImmunisationsCard only invokes the mutation after a successful blob upload); step 2 a PPP Staff reviewer / recruiter manually confirms each row via setImmunisationStatus, which flips the row to verified. The system defines the extent of proof required per vaccination type — non-TB vaccinations accept a single uploaded record; TB additionally requires a proofType selector (IGRA, Mantoux, CXR, or historical record) before evidence can be uploaded. Per-row expiresAt is captured at upload and rolls up to the earliest expiry on the Immunisations domain, driving renewal reminders. (20 May 2026, #6387) †
  • ✅ hr-passport.immunisations.administered-date-column — the date a vaccination was administered / given is stored as a typed administeredAt column on ppp_passport_immunisation (#8274), not encoded as prose inside notes. Both the multi-vaccine OCR review dialog's "Date given" field and manual entry write the reviewed date to this column via hrPassport.upsertImmunisation (administeredAt accepts an ISO date, coerced to a timestamp; re-uploads that omit it never wipe a previously-recorded date). ImmunisationsCard surfaces the date back on each vaccination row. A typed column means the date can be sorted, rendered as a date field, and drive annual-cadence expiresAt derivation — none of which a free-text note allows. (17 Jun 2026, #8274) †
  • ✅ hr-passport.immunisations.cadence-status — hrPassport.listImmunisations surfaces a date/cadence-aware per-item status on every record — current | due | expired — derived (never stored) from the row's administeredAt, the requirement's renewal cadence (annual vs once), and any explicit expiresAt. expired wins for any cadence when expiresAt is at or before now; due flags an annual item administered more than 365 days ago (or an annual item with no administered date and no future expiry); current otherwise. This is distinct from the stored verification status (pending/verified/expired) — a verified annual record can still fall due, which is precisely the oversight signal: admins and reviewers (and review exports) see which immunisations are up to date rather than a single blanket verified tick. The derivation is pure and clock-deterministic (deriveCadenceStatus, unit-covered with a mocked clock). Builds on the typed administeredAt column ([[hr-passport.immunisations.administered-date-column]], #8274) and the optional/required de-blanket ([[hr-passport.immunisations.optional-influenza]], #7968). (18 Jun 2026, #8244) †
  • ✅ Per-vaccination sub-status, one ppp_passport_immunisation row per (user × vaccination). The vaccination catalog is the superset across jurisdictions (Hep B, MMR, Varicella, Diphtheria, Tetanus, Whooping Cough, Influenza, TB); the required SUBSET is jurisdiction-resolved ([[hr-passport.immunisations.jurisdiction-matrix]]). Domain immunisations rolls up to verified only when every required vaccination for the doctor's jurisdiction is individually verified — vaccinations marked optional in the config (e.g. influenza outside NSW) are excluded from the roll-up ([[hr-passport.immunisations.optional-influenza]]). (#5613, #7338, #7968)
  • ✅ TB accepts multiple proof types (IGRA | Mantoux | CXR | historical record). TB row carries a proof_type column; the UI proof-type selector gates the upload CTA. (#5613)
  • ⏳ Expiry + renewal reminders per vaccination — domain expiresAt rolls up to the earliest non-null per-row expiry; per-row reminder cadence still to be wired (follow-on issue).
  • ✅ Base path is upload-doc + manual-confirm. Doctor upserts each vaccination via trpc.ppp.hrPassport.upsertImmunisation; a reviewer/recruiter sets status='verified' via setImmunisationStatus. Multi-vaccine OCR ([[hr-passport.immunisation.ocr-multivaccine]]) is a convenience layer on top of this same path — it pre-fills rows, it does not replace manual verification. (#5613, #7941)
  • ✅ hr-passport.immunisations.evidence-key-user-scoped — immunisation evidence blob keys are scoped to the uploader: ImmunisationsCard builds ppp-passport/immunisations/{pppUserId}/{vaccination}/{ts}-{name}, and storage.generateUploadUrl rejects any ppp-passport/ WRITE key whose owner segment is not the caller's pppUserId. Stops a user obtaining a SAS WRITE token for another doctor's evidence blob. Mirrors the ppp/medical_passport/{pppUserId}/ convention (#5062). (2 Jun 2026, #7967) ‡
  • 🗑️ hr-passport.hospital.registry-source-enum — removed (#8459): this hardened the source enum on hospital.addToMyProfileFromRegistry, but the whole doctor registry-self-add path (procedure + selfAssignRegistryHospital service) was deleted when DB-only doctor search (#8444) made it permanently unreachable, so there is no longer a registry-source input to constrain. Originally added 2 Jun 2026, #7967. ‡
  • ✅ hr-passport.immunisations.medicare-account-link — AU doctors can link their personal Medicare account from the Immunisations domain so the Passport can later surface government-verified immunisation history (including the annual influenza vaccination recorded against AIR) instead of manual per-vaccination entry. ImmunisationsCard shows a "Link Medicare account" affordance only when the doctor's resolved jurisdiction is AU (Medicare / AIR is an Australian government service); hrPassport.linkMedicareAccount captures + shape-validates the Medicare provider number (isValidMedicareProviderNumber — 6 stem digits + location + check char, normalised upper-case) and stores it on the ppp_passport row (medicare_provider_number, medicare_linked_at, migration 0170). The mutation rejects a non-AU jurisdiction server-side. This slice captures the linkage; the automated AIR / My Health Record fetch that uses the stored reference is a separate commercial / compliance decision (data-access + consent path, in the spirit of #7681) and is NOT performed here — the card signposts the verified-history feature as coming once that connection is available. Spun off from #7968 (Matt, 2 Jun 2026). (18 Jun 2026, #8240) †
  • ✅ hr-passport.immunisation.ocr-multivaccine — a doctor can scan one immunisation statement (an AIR Immunisation History Statement or equivalent record listing many vaccinations) and have the matching passport rows pre-filled for review. ImmunisationsCard uploads the statement image (JPG/PNG/WebP/HEIC — the doctor's own evidence, retained, not deleted) and calls analyzeImage.analyzeImmunisationStatement, which runs Azure OpenAI Vision OCR (same integration as the CPD operating-list / medical-sticker / passport-document OCR) and returns one entry per readable vaccination (name as printed + most-recent dose date). The client maps each free-text name to catalog vaccination value(s) via mapExtractedVaccineName (combination vaccines expand — dTpa → diphtheria + tetanus + whooping cough, MMRV → MMR + varicella), keeps only those required for the doctor's jurisdiction ([[hr-passport.immunisations.jurisdiction-matrix]]), and shows a review dialog where the doctor confirms/edits each row + date before pre-filling. Every pre-filled row is written as status='pending' via upsertImmunisation sharing the one statement blob path, with the dose date written to the typed administeredAt column ([[hr-passport.immunisations.administered-date-column]], #8274) — OCR never auto-verifies; a PPP reviewer still confirms each row via setImmunisationStatus ([[hr-passport.verification.immunisations]]). TB is excluded from auto-prefill (its evidence is a proof-typed blood test/CXR, recorded manually). OCR failure or empty extraction degrades gracefully to manual per-vaccination upload with a non-blocking notice. PDF statements are now auto-scanned too (#8272): a PDF upload is rasterised page-by-page to images server-side (pdfRasteriser — lazy-loaded pdfjs-dist + @napi-rs/canvas, capped at the first 5 pages) before the same Vision OCR runs over each page, and the per-page entries are merged (de-duped by name, first dose date kept) so multi-page statements extract vaccinations from every relevant page; ImmunisationsCard accepts application/pdf in the scan picker and the old "PDFs aren't scanned" notice is gone. A corrupt/unreadable PDF degrades to manual entry like any other OCR failure. Reverses the prior hr-passport.immunisation.ocr-deferred "defer indefinitely" decision (Q1). (3 Jun 2026, #7941; PDF rasterisation 18 Jun 2026, #8272) †

Mandatory Trainings ​

  • ⚠️ Training records list with per-item verification + expiry (19 May 2026, #5614). Drift (3 Oct 2026): the list lives in MandatoryTrainingsCard, which has never been mounted (#12808). The 30-day passport_training_expiry_reminder (processTrainingExpiryReminders) now runs daily at 21:30 UTC on the NAS backend (#12810).
  • ⚠️ "No longer relevant" action on a training record — user-triggered, requires reason, records actor + timestamp. Hides the item from reminders without deleting the record (19 May 2026, #5614). Drift (3 Oct 2026): the action is on the unmounted MandatoryTrainingsCard, so a doctor can't reach it (#12808).
  • ✅ hr-passport.mandatory-training.seed-data — the platform ships with a seeded list of common mandatory training items pre-populated per jurisdiction: AU (12 items — Fire Safety, Manual Handling, BLS, Infection Control, etc.) and GB (12 NHS CSTF core subjects — Fire Safety, Moving and Handling People, Basic Life Support, Infection Prevention and Control, Information Governance and Cyber Security, Equality/Diversity/Human Rights, Conflict Resolution, Safeguarding Adults, Safeguarding Children, Preventing Radicalisation, Health/Safety/Welfare, Learning Disability and Autism Awareness). Person-named training items (e.g. "Oliver McGowan") are excluded by design — the canonical subject title is used instead. Super Admin can add, edit, or deactivate items from the seed list. New users' Mandatory Training section is pre-populated from the applicable seed list based on their Hospital + Jurisdiction. (21 Apr 2026, extended GB 19 May 2026) (#5983, #6163)
  • ⚠️ hr-passport.mandatory-training.magic-link-batch — Verification email to a mandatory training provider carries a time-limited magic link (14-day TTL aligned with the timesheet approver window; single-use — non-reusable after provider submits) to a single PPP-hosted page listing all outstanding training items selected in the batch for that user for the provider to confirm in one visit. Only one email is sent per user-per-batch (no duplicate per-item emails). The page shows the evidence the doctor provided. The doctor enters the expiry date when submitting, and the provider confirms it (or corrects it) along with a completion status per item, on the same page and without re-authentication. Refreshed 2026-10-03: this used to say the provider sets the expiry. Matt's wording is that the provider confirms the date the doctor entered.†† Drift (3 Oct 2026), partly fixed 4 Oct 2026 (#12850): MandatoryTrainingsCard is now mounted on /ppp-passport; the doctor adds a training with a certificate file and their expiry date and sends the provider request from a "Request verification" row action, and VerifyTrainingPage pre-fills the doctor's expiry for confirmation. Still open: the page shows the doctor's evidence as a raw blob path, not a viewable file. Provider submission is atomically persisted — all per-item updates and the batch status flip happen in a single Drizzle transaction (partial saves are not allowed; missing or duplicate per-item decisions are rejected before the transaction opens). Prevents email overload from individual per-item messages (12 May 2026, verified ✅ 20 May 2026). (#5944, #6388) †
  • ✅ hr-passport.verification.mandatory-training-magic-link — mandatory training verification sends a single email to the training provider with a magic link to a page listing all pending items; the provider approves each item and confirms expiry dates in one visit without needing to re-authenticate. Duplicate phrasing of the canonical hr-passport.mandatory-training.magic-link-batch AC above — same source transcript paragraph, same implementation in api/backend-ppp/src/services/passport/passportTrainingService/ (requestVerification sends exactly one email per user-per-batch; submitVerification accepts every per-item decision + expiry on a single POST and no provider re-auth is required because the magic-link token IS the credential). Verified by the same evidence used for #6388 — see the @issue-6388 regression scenarios in hr-passport.feature plus the new @issue-6389 smoke scenario below. (verified ✅ 20 May 2026, #6389) †
  • ⏳ Blocked on Q3: API integrations with hospital training systems — identify which hospitals publish an API, sequence engineering work accordingly. Green Brain is the named candidate for the first pilot integration. Matt's Notion brief describes it as the system the UK uses, and asks whether there is an AU equivalent. Matt supplied mandatory-training title examples from his Green Brain profile (Notion comment, 12 May 2026), and those are reflected in the seed list. Refreshed 2026-10-03: this AC previously said Green Brain is "used by Queensland Health and other AU hospital networks", which no source supports.††

Visa / Passport / Right to Work ​

  • ⚠️ Internal review workflow for uploaded docs — local citizens (AU citizen / AU permanent resident) are auto-seeded as verified from the passport's citizenshipStatus; overseas doctors submit a visa / passport / right-to-work bundle via hrPassport.submitRightToWorkDocuments and the submission enters the PPP Staff review queue parameterised by domain (12 May 2026). (#5615) Drift (3 Oct 2026): the overseas submission UI (VisaCard) lost its only mount in the passport consolidation (#8807) and asks for a typed blob path, not a file (#12808). The Right to Work domain card opened the CV tab; fixed 4 Oct 2026, it now opens Recruiter Compliance (#12809).
  • ⏳ Blocked on Q4: UK digital API lookup exists — engineering to identify the endpoint; AU — investigate whether one exists.
  • ⚠️ hr-passport.verification.rights-to-work — Drift (3 Oct 2026): Tier 1 (the server-side auto-verify) is built. The Tier 2 doctor submission UI is unreachable (#12808). Right-to-work verification uses a tiered approach: Tier 1 (automatic approval) — local citizens (AU citizen / AU permanent resident, mirroring passport country of work) are auto-seeded as verified from pppPassport.citizenshipStatus with synthetic verifier identity ("AU Citizen — auto-verified"); Tier 2 (documentation check) — overseas doctors submit a visa / passport / right-to-work bundle via hrPassport.submitRightToWorkDocuments and the submission enters the PPP Staff manual-review queue. Pathway is decided server-side by getRightToWorkPathway (api/backend-ppp/src/services/passport/visaService/index.ts) — the client never picks the pathway. UK Home Office share-code API and AU VEVO digital API integrations remain Q4-blocked and tracked as a future enhancement on top of the manual-review Tier 2 baseline. † (#6390)

Reminders & lifecycle ​

  • ✅ Expiry reminders appear in the Platform Reminders tab (built: PlatformRemindersTab, passport types mapped to /ppp-passport). Immunisation, training reminders now follow the 30/14/7/0 day cadence; indemnity, registration and document sweeps still use their fixed windows.
  • ⏳ Reminder cadence by domain (30/14/7/0 days before expiry by default; tunable per reminder type).
  • ⏳ Expired sub-records move Blue Tick to amber (30-day grace, per Q5) then red; emit an event the Organisational Dashboard can surface. (Immediate false flip described in earlier drafts is superseded by the three-state model.) Refreshed 2026-10-03: the grace period is an engineering default that Matt has never confirmed. It is reopened as Q8.
  • ⚠️ hr-passport.reminders.domain-expiry-sweeps-scheduled — the doctor is prompted when any Passport item (registration, indemnity, immunisation, mandatory training) is about to expire or has expired. Every domain expiry sweep runs on the daily scheduler. Drift (3 Oct 2026): the generic document sweep (processPassportExpiryNotifications, 30/60 days, in the shared daily bundle) and, since #12810, the indemnity reminder, the indemnity auto-expire and the training reminder (PASSPORT_DOMAIN_EXPIRY_TICK, 21:30 UTC, entrypoints/api-container.ts) all run daily. Per-immunisation reminders aren't built (see the Immunisations ⏳ AC), so this stays ⚠️ until they are.††

Export ​

  • ⏳ hr-passport.export.single-deliverable — User can export their PPP Passport as a single PDF bundle with every verified sub-record, raw-doc attachments, verification provenance, and an overall Blue Tick summary page. Not built: today the only outward path is the recruiter share link. Tracked by #12811. Where the export lives (the Passport page or Reports) is Q7.††††
  • ⏳ Exported PDF carries a QR code linking to a public, time-limited attestation URL a hospital recruiter can scan to verify authenticity.
  • ✅ hr-passport.share-link.doctor-ui — the doctor creates a recruiter share link (7-day expiry, no recruiter login, Q6) and revokes any active link from a "Share with a recruiter" section on /ppp-passport; staff mark documents verified from /admin/passport-reviews (#12895, 5 Oct 2026).
  • ✅ hr-passport.share-link.document-verification — each medical passport document on the recruiter-facing share-link profile carries a real verification state, not a hardcoded false (replaces the #2903 stub). Verification is admin-managed: a Super Admin / PPP Staff member sets a document's verified state via medicalPassport.setDocumentVerification (gated by requireSuperAdmin), which records the reviewer identity and timestamp; un-verifying clears them. medicalPassport.listPendingVerification provides the internal review queue. The public share-link profile renders a "Verified by PPP" badge on verified documents and an "Unverified" badge otherwise — mirroring the internal-review pattern of pppPassportReviewService (#5985). (19 May 2026) (#4645)

Summary screen ​

  • ✅ hr-passport.summary-screen — Single Passport page at /ppp-passport shows all six domains as cards, a Blue Tick status banner, and an upcoming-expiries list (next 30 days). Doctor personas only. (13 May 2026) (#5609) Refreshed 2026-10-03: the server computes a boolean Blue Tick. The banner's three looks are derived from it in computeBannerState: verified, "expired" (any domain expired) and "pending" (amber, meaning incomplete rather than a grace period). The three-state server model is the ⏳ AC above and Q8.
  • ✅ hr-passport.status.on-passport-page — the PPP Passport compliance status (the Blue Tick banner and the per-domain completion cards) is shown at the top of the PPP Passport page, the single home for Passport work. It is not shown on the Doctor Profile. Supersedes hr-passport.profile-widget. Matt's statements, oldest to newest: 26 May 2026, the profile widget was "all or nothing rather than showing which ones are complete" → 28 May 2026, the Passport is "represented in the profile as just a tick box" → 3 Jun 2026, Rob proposed moving the status onto the Passport page "as a drop down at the top" and Matt agreed ("Yeah. Okay."), built in #8184.††‡
  • ⚠️ hr-passport.domain-cards.open-domain-flow — each of the six domain cards on /ppp-passport takes the doctor to that domain's upload-and-verify flow (registration, medical degree path, indemnity, immunisations, mandatory training, right to work), so the doctor can become compliant in every domain from the Passport page. Drift (3 Oct 2026): the cards jump to generic document-upload tabs. The Medical Degree, Mandatory Training and Right to Work flows aren't mounted anywhere (#12808). Indemnity fixed 4 Oct 2026 (#12808): its card opens the indemnity flow inline below the grid (DOMAIN_FLOWS in PassportOverview). Fixed 4 Oct 2026 (#12809): cards now resolve their tab by stable key (DOMAIN_TAB_KEY → PASSPORT_TABS[].key), so Right to Work opens Recruiter Compliance, not the CV tab, and inserting a tab can't re-point a card. Fixed 4 Oct 2026 (#12831): a card that opens a document tab (Medical Registration, and any domain without a mounted flow) now scrolls the tabs into view, so the CTA no longer looks like a dead click. Whether the document tabs should stay alongside the cards is Q9.†
  • ✅ hr-passport.purpose.hospital-compliance-tick — the PPP Passport's primary goal is to be accepted by hospitals as a trusted compliance verification, eliminating the need for doctors to resubmit the same documents at each new hospital and saving time and cost for both the user and the enterprise. † (#6391)

Route ​

  • ✅ hr-passport.route.canonical — the passport module is served at the canonical route /ppp-passport (renamed from the legacy /hr-passport to match the product name shown across the UI). The public share page is /ppp-passport/share/:token.†‡ (1 Jun 2026, #7810)
  • ✅ hr-passport.route.legacy-redirect — the legacy /hr-passport path and its /hr-passport/share/:token sub-path permanently redirect to /ppp-passport, preserving any sub-path, share token, query string, and hash so existing links, notifications, and roadmap milestones keep working.†‡ (1 Jun 2026, #7810)
  • ✅ hr-passport.route.in-app-nav — in-app navigation (sidebar, universal search, notification deep-links, roadmap milestone routes) and newly generated share URLs point at /ppp-passport; the breadcrumb/page title remains "PPP Passport".†‡ (1 Jun 2026, #7810)
  • ✅ hr-passport.nav.workforce-group — in the full-platform sidebar, PPP Passport sits under the Workforce header, after Timesheet and before Attendance. Supersedes Matt's 2 Jun 2026 grouping (#7911), which put PPP Passport with Reports. On 8 Jul 2026 Matt said "I thought we could bring that up into workforce... if someone was going to the workforce department in a hospital, that's that's basically what they call HR. That would be the compliance", and agreed ("Sounds good") to "after time sheet and before attendance". Built in #10187.††‡

Page look & feel ​

  • ✅ hr-passport.display.on-brand-page — the /ppp-passport document page uses the shared compact look & feel (PageHeader title row, bordered SectionCard panel wrapping the tabs, ~13px text, tight token-driven spacing) matching the rest of the app; all colours/spacing come from design tokens with no hardcoded hex/px.†‡ (#7826)
  • ✅ hr-passport.overview.workflow-summary-layout — the status-first overview (PassportOverview) reads as workflow → summary: the six actionable compliance domain cards (verify / re-verify) form the workflow section at the top, and the "Upcoming expiries" list is the summary section below; the server-computed Blue Tick banner stays at the very top. Each domain card is rendered with the shared approved SectionCard primitive (token-driven border/radius/surface/shadow) rather than a hand-rolled bordered Box, so it restyles with the rest of the app. Immunisations is de-prioritised into a single collapsed-by-default expandable group — the jurisdiction-driven ImmunisationsCard is wrapped in the shared CollapsibleSection primitive and expands on click, so it no longer dominates the page inline. This AC covers the structural slice only; the "more engaging card" visual treatment (icons, status-colour accents, hover elevation, etc.) is a separate for-discussion decision pending Matt's sign-off and introduces no new brand primitive here. (10 Jul 2026, #10194) †‡

Document OCR autofill ​

  • ✅ hr-passport.document.ocr-autofill — when a doctor uploads an image document (.jpg/.jpeg, .png, .webp, .heic/.heif) in the PPP Passport Add/Edit Document form, the platform runs Gemini OCR (reusing the same Azure OpenAI Vision integration as the CPD medical-sticker / operating-list OCR — imageService.analyzePassportDocument via analyzeImage.analyzePassportDocument) and pre-fills five form fields with best-effort suggestions: Issuer Name, Document Type (constrained to the form's own selector values), Issued Date, Expiry Date, Notes. The suggestions are always user-editable before saving — OCR is a convenience autofill, never an authoritative overwrite; the doctor can clear or change any field. Dates are normalised to ISO YYYY-MM-DD (day-first source interpretation, never US-style) so the date inputs accept them; an unreadable date is left blank rather than guessed. OCR failure or an empty extraction degrades gracefully to manual entry with a non-blocking notice (no error dialog). PDF/DOC/DOCX uploads are stored as before but are not auto-read (image-only OCR). The uploaded document is the doctor's own credential and is retained (unlike the PII medical-sticker flow which deletes the image post-extraction). No document image or extracted field value is logged — only the names of the fields that were populated are recorded for audit. (2 Jun 2026, #7808) ‡

Profile widget ​

  • 🗑️ hr-passport.profile-widget — Retired 2026-10-03, superseded by hr-passport.status.on-passport-page. Matt and Rob agreed on 3 Jun 2026 to move the status off the profile, and #8184 shipped that. The profile no longer shows any Passport content. Original AC, kept for history: the Doctor Profile page displays a PPP Passport summary widget showing: overall Blue Tick status (green/amber/red), count of verified domains out of six, and next expiry date. When expanded, the widget shows a per-domain completion breakdown — each of the six compliance domains is listed with a "Complete" / "Outstanding" indicator rather than a single all-or-nothing control, so the doctor can see exactly which domains are done and which still need action. The widget links to the full PPP Passport page. The widget is collapsed by default and expands on click. Non-doctor personas (Hospital Admin, PPP Staff) do not see the widget. (23 Apr 2026; per-domain breakdown + "PPP Passport" rename 26 May 2026) (#5986, #7385)
  • ✅ hr-passport.document-gallery.view-toggle — the Medical Passport page (/ppp-passport) carries a List ⇄ Gallery view toggle in the page header. Selecting Gallery renders the current tab's documents as image thumbnails; selecting List restores the original card layout. Default view is List; the toggle applies to all standard document-type tabs (the Recruiter Compliance tab keeps its own layout). (28 May 2026, #7809)
  • ✅ hr-passport.document-gallery.image-thumbnails — in Gallery view each document with an uploaded image (.png, .jpg/.jpeg, .webp, .gif, .heic, .heif, .avif, .bmp) renders an inline thumbnail at the top of its tile, captioned with the document title and expiry status badge so the doctor can recognise documents at a glance. Each thumbnail is fetched via the existing owner-scoped signed read URL (storageClient.get), inheriting the 15-minute SAS expiry ceiling from hr-passport.encryption-at-rest-and-in-transit. (28 May 2026, #7809)
  • ✅ hr-passport.document-gallery.non-image-placeholder — documents whose file is not a renderable image (e.g. PDF, DOCX) show a typed-file placeholder displaying the uppercase extension (e.g. "PDF") inside the tile frame, not a broken image. Clicking the tile reuses the existing list-view file-open handler that opens the signed URL in a new tab. (28 May 2026, #7809)
  • ✅ hr-passport.document-gallery.missing-file-placeholder — documents with no uploaded file show a clearly-labelled "No image attached" placeholder in their tile, so users immediately spot gaps in their Passport rather than seeing an empty frame. (28 May 2026, #7809)
  • ✅ hr-passport.document-gallery.lightbox — clicking an image tile opens a modal lightbox showing the enlarged image with zoom-in, zoom-out, and reset controls and Escape-to-close. (28 May 2026, #7809)
  • ✅ hr-passport.document-gallery.permission-scope — the gallery is owner-only on /ppp-passport; it reuses the existing owner-scoped medicalPassport.list query and therefore inherits the same authentication and per-user filtering as the list view. The public recruiter share page (HrPassportSharePage) is not affected — its existing getShareableProfile query does not expose document fileKeys. (28 May 2026, #7809)
  • ✅ hr-passport.document-gallery.accessibility — every image carries a meaningful alt of the form <document title> — issued by <issuer>; the view toggle, each tile button, and each lightbox control carry an aria-label; the lightbox dialog is keyboard-closable. (28 May 2026, #7809)
Downstream References ​
FeatureLinkage
OnboardingSign-up captures Primary Registration → seeds the Medical Registration sub-record
Profile (Doctor)Country + jurisdiction drive which domains are required vs optional
Profile (Non Doctor)Hospital Admin persona does not carry a Passport; PPP Staff do not either
Action ItemsPlatform Reminders tab surfaces expiry + non-compliance alerts
Organisational DashboardAnonymised cohort insights on Blue Tick rates (compliance fraction per department)
CPDSimilar verification pattern — PPP Verification flow is shared infrastructure with CPD external-activity verification
Status ​

Rebuilt 2026-10-03 for the Task 13 spec refresh (#11212), from read-only code checks on the Phase C sprint branch. The Passport entity, the six domain records and the server-computed boolean Blue Tick exist. The /ppp-passport page shows the domain cards, the Immunisations flow and the document tabs. Most per-domain verification UIs are built, but they aren't mounted.

Sub-featureStatusNotes
Passport entity + boolean Blue Tick✅ BuiltThree-state model with grace period not built; grace period is Q8
Summary page + status at top✅ BuiltStatus moved off the profile (#8184); nav under Workforce (#10187)
Domain cards → domain flows⚠️ DriftCards open generic document tabs (#12808); RTW→CV tab fixed by key lookup (#12809); tabs vs cards is Q9
Medical Registration⚠️ PartialSign-up registration feeds the domain; internal-review path and second jurisdiction ⏳
Medical Degree verification⚠️ DriftBackend paths built (#5611); MedicalDegreeCard path picker not mounted (#12808); My eQuals / EPIC still stubbed
Indemnity⚠️ DriftBackend built (#5612, #6386); IndemnityCard mounted with a real file upload (#12808); reminder and auto-expire scheduled daily (#12810)
Immunisations✅ BuiltJurisdiction set, OCR, Medicare link, cadence status; per-vaccination reminders ⏳
Mandatory Trainings⚠️ DriftCard mounted with certificate, expiry and "Request verification" (#12850); provider page pre-fills the expiry; provider cannot open the evidence file; training reminder scheduled daily (#12810); API integration blocked on Q3
Visas / Right to Work⚠️ DriftTier 1 auto-verify built; Tier 2 VisaCard not mounted (#12808, #12809); digital API blocked on Q4
Reminder integration⚠️ DriftGeneric document sweep and domain sweeps scheduled (#12810); per-immunisation reminders ⏳
Export PDF + recruiter QR❌ Not started#12811; export location is Q7. Recruiter share link with per-document verification is built

Open issues on label:feature:hr-passport — issue data unavailable at build time.Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.

Change Log ​
DateChangePR/IssueReason
2026-10-06Wave 2 wiring on /ppp-passport. The Immunisations domain card now expands and scrolls to the real Immunisations card. Right to Work gains a citizenship selector that saves through hrPassport.updatePassportContext. Medical Registration rows show the register they were checked against (AHPRA or GMC). The List/Gallery toggle mounts DocumentGallery on the standard document tabs. Staff review can record an expiry date when approving a registration, indemnity or Right to Work submission. Training reminders deep-link to the "no longer relevant" prompt. A per-immunisation expiry sweep was added and training and immunisation reminders follow the 30/14/7/0 day cadence (indemnity, registration and document sweeps keep fixed windows). api-dev now serves /storage/signed/:token. Spec status corrected: the Platform Reminders tab is built, CV import is built (#12876), and the encryption ACs describe the Azure estate while the backend is on the NAS (ADR-0006). The export scenario is parked as @wip until the export is built (L, Q7).#12974, #12975, #12976, #12977, #12978, #12979, #11212Found in the 5 Oct 2026 Task 13 reachability check. No migration. Covered by @issue-12974, @issue-12975 and @issue-12976 scenarios in ppp-passport.feature.
2026-10-05The PPP Staff review queue (/admin/passport-reviews) now lists submissions from every Passport domain with a Domain column and a "View document" button (signed read URL), not only medical_registration; listPending takes an optional domain and a new listPendingImmunisations plus a Verify action cover per-vaccination evidence (reusing setImmunisationStatus). The queue page also lists Passport documents awaiting verification with "Mark verified" (medicalPassport.setDocumentVerification). The Medical Registration card's Verify now opens its own flow (MedicalRegistrationCard) that uploads proof of registration through hrPassport.submitMedicalRegistrationEvidence (domain stays pending on the PPP Verification path, which is what queues it for staff) and lets the doctor add a second AHPRA / GMC registration. /ppp-passport gains a "Share with a recruiter" section to create a 7-day public link and revoke active links (generateShareLink / listShareLinks / revokeShareLink). The indemnity, indemnity-expired and training expiry notifications now deep-link to /ppp-passport, and the provider magic-link page opens the doctor's evidence through a signed URL instead of showing a raw path. The api-container entry is documented and started by scripts/cloud-stack-up.sh (pnpm start:container) because api-dev does not serve /storage/signed/:token. A single idempotent seed, api/backend-ppp/scripts/seedTask13Recording.ts, adds verified, expired, expiring, NSW, GB NHS, citizen and pending-review personas. No migration. The AC set stays as is: Q8, Q9, Q7 and the export (#12811) are still open.#12893, #12831, #12895, #12896, #12894, #11212Found in the 5 Oct 2026 Task 13 audit (defects D1, D2, D3, D5, D7, D8, D9, D11, D6). The Task 13 video must show step 2 of each two-step flow and every Passport look. Q6 (resolved 5 May) fixes the 7-day expiry and the doctor's right to revoke from their Passport screen. Covered by @regression @issue-12893, @issue-12831 and @issue-12895 scenarios in ppp-passport.feature.
2026-10-04The Indemnity domain card on /ppp-passport now opens the indemnity verification flow (IndemnityCard) inline below the domain grid, through a DOMAIN_FLOWS registry in PassportOverview. Domains without a mounted flow still open their document tab. The certificate is now a real file chosen by the doctor. It is validated against the shared passport upload allow-list (10 MB limit), uploaded under an owner-scoped key ppp-passport/indemnity/{pppUserId}/… by the new usePassportEvidenceUpload hook, and that key is sent as documentBlobPath. The free-text blob path field is removed. IndemnityCard now uses the shared SectionCard and status chip mapping, and its buttons share the focusRingSx focus ring, moved from ScanSourceButtons into themes/focusRing.ts. The indemnity "External verification request flow" AC is now ✅. hr-passport.verification.indemnity and hr-passport.domain-cards.open-domain-flow stay ⚠️: the reminder and auto-expire sweeps are still unscheduled (#12810), and the Medical Degree, Mandatory Training and Right to Work flows are still unmounted (#12808).#12808, #11212Bug #12808, Indemnity slice. IndemnityCard was never mounted (#6178), and its certificate field asked for a typed blob path, so a doctor could not upload a certificate. Matt (12 May transcript, ~00:49:42) said indemnity is "upload your certificate ... and we go through the same two-step verification process". Covered by the @regression @issue-12808 scenario in ppp-passport.feature.
2026-10-04The overview's domain cards now resolve their document tab by a stable key instead of a hard-coded index. PASSPORT_TABS entries carry a key, PassportOverview maps each domain to a key (DOMAIN_TAB_KEY), and passportTabIndex() looks the index up. The Right to Work card now opens Recruiter Compliance instead of the CV tab. hr-passport.domain-cards.open-domain-flow stays ⚠️ because the Medical Degree, Indemnity, Mandatory Training and Right to Work flows are still unmounted (#12808).#12809, #11212Bug #12809. The CV tab was inserted at index 6 (#9196, PR #9776), the index the Right to Work card targeted, and the map was never updated. Looking up by key means adding a tab can no longer silently re-point a card. Covered by the @regression @issue-12809 scenario in ppp-passport.feature.
2026-10-04The indemnity 30-day reminder, the indemnity auto-expire and the mandatory-training expiry reminder now run daily at 21:30 UTC on the NAS backend (registerScheduledJob(PASSPORT_DOMAIN_EXPIRY_TICK, …) in api-container.ts). The generic document sweep already ran in the shared daily bundle and is not registered twice.#12810Issue #12810: the three domain sweeps had only an admin tRPC caller (indemnity) or none (training), so a lapsed indemnity never moved to expired, the Blue Tick stayed green and the doctor was never prompted. Per-immunisation reminders are still unbuilt, so hr-passport.reminders.domain-expiry-sweeps-scheduled stays at drift.
2026-10-04A domain card's CTA that opens a document tab (Medical Registration, and every domain whose own flow is not yet mounted) now scrolls the document tabs into view. PassportPage bumps a scroll request on each card open and scrolls the tab-bar anchor, even when the target tab is already selected. hr-passport.domain-cards.open-domain-flow stays ⚠️ because the Medical Degree, Mandatory Training and Right to Work flows are still unmounted (#12850).#12831, #11212Bug #12831. The Verify button on the Medical Registration card switched the tabs far below the six cards and left the viewport where it was, so the click looked dead. Spec hr-passport.domain-cards.open-domain-flow says each card takes the doctor to that domain's flow. Covered by the @regression @issue-12831 scenario in ppp-passport.feature.
2026-10-04The Medical Degree, Mandatory Training and Right to Work domain cards now open their own flow inline on /ppp-passport (the DOMAIN_FLOWS registry in PassportOverview). Medical Degree (PPP Verification path) and Right to Work take a real file under an owner-scoped key via usePassportEvidenceUpload, and the Right to Work blob-path text field is gone (new RightToWorkFlow wraps VisaCard). Adding a mandatory training now captures the certificate file and the doctor's expiry date, and each pending training has a "Request verification" action that emails the provider. The provider's magic-link page pre-fills the doctor's expiry for confirmation (createTrainingItem accepts expiresAt; validateTrainingVerificationToken returns it; no migration, the existing expires_at column is reused). Immunisation rows also no longer show "Up to date" without an evidence file, and an empty file is rejected (#12830). hr-passport.domain-cards.open-domain-flow, hr-passport.verification.rights-to-work and the Mandatory Training ACs stay ⚠️ because the PPP Staff review queue still lists only medical_registration submissions and nothing in the UI sets citizenshipStatus.#12850, #12830, #11212Bug #12850 (split from #12808) and #12830. Matt's Task 13 brief asks the video to show a doctor uploading information for each aspect of the passport; three of the six domains were unreachable. Matt (transcript 2026-05-12, ~00:57:27) said the provider confirms the expiry date the doctor enters at submission. Covered by @regression @issue-12850 and @issue-12830 scenarios in ppp-passport.feature. The Right to Work card no longer lands on Recruiter Compliance (that tab stays reachable); the @issue-12809 scenario now asserts it never opens the CV tab.
2026-10-03The PPP Passport spec was refreshed for Async Task 13 (#11212) against Matt's 29 Jul 2026 task brief, his Notion PPP Passport page (last edited 12 May), and the 12 May, 26 May, 28 May, 2 Jun, 3 Jun, 8 Jul and 14 Jul 2026 transcripts. Read-only code checks found that the doctor-facing verification cards for Medical Degree, Indemnity, Mandatory Training and Right to Work (MedicalDegreeCard, IndemnityCard, MandatoryTrainingsCard, VisaCard) are not mounted on any page, so ACs marked ✅ were unreachable. Those ACs are now marked drift and filed as #12808. The Right to Work domain card opens the CV tab (#12809). The indemnity reminder, the indemnity auto-expire and the training expiry reminder are never scheduled (#12810). Three new ACs are added. hr-passport.status.on-passport-page (✅) supersedes and retires hr-passport.profile-widget. hr-passport.nav.workforce-group (✅, #10187) is new. hr-passport.domain-cards.open-domain-flow (⚠️) and hr-passport.reminders.domain-expiry-sweeps-scheduled (⚠️) are new drift ACs. The export AC is now hr-passport.export.single-deliverable, cited and tracked by the new enhancement #12811. The mandatory-training magic-link AC now says the doctor enters the expiry date and the provider confirms it (Matt's wording). The Green Brain AC drops the unsourced "used by Queensland Health" claim. The summary-screen AC now describes the boolean server Blue Tick accurately. New Open Questions: Q7 (where to export from), Q8 (whether expiry has a grace period; closed Q5 reopened because it was engineering-led) and Q9 (domain cards vs document tabs). The Status table is rebuilt. notion-last-synced: is now 2026-10-03. PassportOverview.tsx is added to code-paths:.#11212, #12808, #12809, #12810, #12811Async Task spec refresh, Task 13 (#11212). The newest dated statement from Matt wins. Drift was confirmed by read-only code checks against real call sites. No &lt;IndemnityCard, &lt;VisaCard, &lt;MandatoryTrainingsCard or &lt;MedicalDegreeCard mount exists under instances/ppp/src. DOMAIN_TAB_INDEX.right_to_work = 6 is the CV tab since #9776. api/backend-ppp/entrypoints/scheduler-lambda.ts calls only processPassportExpiryNotifications. No BDD scenarios were added, per the spec-refresh rule (Rob, 2026-10-03). The @regression requirements sit on #12808, #12809 and #12810.
2026-07-12Corrected two stale service-path citations in AC bodies and added both service files to the front-matter code-paths: list. hr-passport.verification.mandatory-training-magic-link now cites api/backend-ppp/src/services/passport/passportTrainingService/ (was api/backend-ppp/src/services/passportTrainingService/); hr-passport.verification.rights-to-work now cites api/backend-ppp/src/services/passport/visaService/index.ts (was api/backend-ppp/src/services/visaService/index.ts).#10518, #10489SGD C13 drift — both services were moved one directory level deeper under a shared passport/ service group during a prior reorg; the spec AC bodies still pointed at the old paths. Functional behaviour is unchanged — only the cited paths were stale.
2026-07-10The PPP Passport status-first overview (PassportOverview) now reads as workflow → summary — the six actionable compliance domain cards form the workflow section at the top and the "Upcoming expiries" list is the summary section below, with the server-computed Blue Tick banner remaining on top. Each domain card is rendered with the shared approved SectionCard primitive instead of a hand-rolled bordered Box, and Immunisations is de-prioritised into a single collapsed-by-default expandable group using the shared CollapsibleSection primitive (new bare prop on ImmunisationsCard avoids a card-in-card border). Adds AC hr-passport.overview.workflow-summary-layout.#10330, #10194Structural (non-visual-redesign) slice of #10194 (Rob + Matt, 2026-07-08 call). Matt found the current passport flat/blocked and wanted it to flow as a workflow at the top and a summary below, with immunisations under one group that expands on click rather than dominating inline. The "more engaging card" visual treatment is deliberately deferred as a for-discussion decision pending Matt's sign-off, so this PR reuses existing design-system primitives only and introduces no new brand primitive.
2026-06-18Added a date/cadence-aware per-item immunisation status — current / due / expired — derived (never stored) on every hrPassport.listImmunisations record from administeredAt, the requirement's renewal cadence (annual/once) and any explicit expiresAt, via the new pure clock-deterministic deriveCadenceStatus helper. cadenceStatus is threaded onto every record and rendered as a per-row chip on ImmunisationsCard. Added AC hr-passport.immunisations.cadence-status.#8837, #8244Closes #8244 (C2, split from #7968). Matt (2 Jun, #7968) — "explicitly show which immunisations are up to date rather than a blanket verified tick so that admin users can have oversight or if this is being exported for review." Distinct from the stored verification status — a verified annual record can still fall due. No DB change (derived status); builds on the typed administeredAt column (#8274, migration 0169).
2026-06-18PDF immunisation statements are now auto-scanned. A PDF upload to the multi-vaccine statement scan is rasterised page-by-page to PNG images server-side (new pdfRasteriser — lazy-loaded pdfjs-dist + @napi-rs/canvas, capped at the first 5 pages) before the existing Azure OpenAI Vision OCR runs over each page; per-page entries are merged (de-duped by name, first dose date kept) so multi-page statements extract from every relevant page. analyzeImage.analyzeImmunisationStatement accepts application/pdf, and ImmunisationsCard accepts .pdf in the scan picker with the old "PDFs aren't scanned" notice removed. Extends AC hr-passport.immunisation.ocr-multivaccine.#8272Closes #8272 (follow-up to #7941). AIR Immunisation History Statements are most commonly downloaded as PDF, which Azure OpenAI Vision cannot read inline — the #7941 MVP landed image-only, so the highest-value real-world input was not auto-scanned. Rasterising server-side feeds PDFs through the same scan → review → pre-fill flow as images. Graceful degradation preserved (corrupt/unreadable PDF → manual entry, non-blocking).
2026-06-17Added a typed administeredAt (timestamp, nullable) column to ppp_passport_immunisation (migration 0169). Both the multi-vaccine OCR review dialog's "Date given" field and manual entry now write the reviewed administered date to this typed column via hrPassport.upsertImmunisation (was previously preserved only as prose inside notes). ImmunisationsCard surfaces the date back on each vaccination row. Added hr-passport.immunisations.administered-date-column and updated hr-passport.immunisation.ocr-multivaccine to reference the typed column.#8274Closes #8274. Surfaced in the #8271 (#7941) PR review — the administered date was stored only in notes prose, so it could not be sorted, rendered as a typed field, or drive expiresAt / annual-cadence logic. Enabler for date-aware per-item status (#8244).
2026-06-10Added code-paths for immunisationRequirements.ts, immunisation-requirements-config.json, immunisation-values.ts, immunisationOcrMapping.ts#8606, #8485Immunisation jurisdiction matrix (#7338/#7941) belongs to PPP Passport; drift gate now fires correctly when these constants change, per #8485
2026-06-10Retires the hr-passport.hospital.registry-source-enum AC (✅ → 🗑️ removed). This AC (added by #7967) hardened the client-supplied source field on hospital.addToMyProfileFromRegistry to the registry-emitted enum (local | NHS_ODS | AIHW). That whole doctor registry-self-add procedure was removed in #8459, so there is no longer a client-supplied source to validate; the @regression @issue-7967 BDD scenario ("Adding a registry hospital rejects an unrecognised source value") is removed with it.#8589, #8459, #7967Consequence of removing the doctor registry-self-add path (#8459). With the addToMyProfileFromRegistry procedure deleted there is no doctor-side persist of a registry hospital and therefore no untrusted client-supplied source string to constrain. The Super-Admin curation path (#8444 PR2) sets source server-side from the registry API response, not from client input, so the hardening this AC described no longer has a surface to apply to.
2026-06-03Influenza is optional in the AU baseline (offered to record, excluded from the Immunisations domain roll-up / Blue Tick) and required for NSW; the verified tick is de-blanketed into a per-item "X of Y required verified" summary with an Optional chip per optional row. The jurisdiction rules are extracted to immunisation-requirements-config.json (config, not code), Zod-validated at module load.#8255, #7968Matt (2 Jun 2026, #7968) — influenza is not mandated nationally; make it an option to add but not a requirement, and explicitly show which immunisations are up to date rather than a blanket verified tick. Config extraction makes adding a jurisdiction or reflecting a changed directive a data edit.
2026-06-03Multi-vaccine immunisation OCR — a doctor can scan one immunisation statement image (AIR Immunisation History Statement or equivalent) and have the matching jurisdiction-required passport rows pre-filled for review. analyzeImage.analyzeImmunisationStatement runs Azure OpenAI Vision OCR and returns each vaccination as printed plus its most-recent dose date; the client maps free-text names to catalog values (combination vaccines expand, e.g. dTpa → diphtheria + tetanus + whooping cough), keeps only required rows (TB excluded), and the doctor confirms each row + date in a review dialog before rows are written as pending. A PPP reviewer still verifies every row — OCR never auto-verifies. Image-only (PDF not auto-scanned). Reverses the prior hr-passport.immunisation.ocr-deferred decision.#7941Rob (1 Jun 2026, #7941) — doctors frequently hold one document listing many vaccinations; reading it via automation and pre-filling saves re-keying while keeping mandatory human verification. Reverses the earlier defer-indefinitely recommendation (Q1).
2026-06-02Implemented the previously-missing @issue-7338 jurisdiction BDD step definitions so the region-aware required-immunisation scenarios (NSW set, GB set, Hep C absent, no-hospital signpost) now run as real assertions instead of being silently skipped. Added a TODO(#7338) hook plus Open Question Q5 and AC hr-passport.immunisations.titre-evidence-deferred for the deferred titre / below-threshold re-immunisation evidence type.#8092, #7338The #7338 core (jurisdiction-driven required set, data-driven ImmunisationsCard, hospital-resolved jurisdiction, card mounting) shipped in #7957/#8049, but the four @issue-7338 scenarios #7957 added referenced step definitions that were never written — missingSteps:'skip-scenario' skipped them, so the acceptance criteria had no executable backing. They now mock hrPassport.listImmunisations with the exact set resolveRequiredImmunisations produces and assert the card's rendered rows / serology + annual chips / Hep C absence / no-hospital signpost. Matt (2 Jun) flagged that some items (Hep B/C) are evidenced by a blood-test titre with a below-threshold re-immunisation rule; that titre evidence type is deferred pending his confirmation of affected vaccinations + thresholds and is intentionally not built here.
2026-06-02Relocated immunisation evidence upload file-validation BDD coverage from the removed Setup Wizard onto the PPP Passport ImmunisationsCard.#8073, #8050, #7922PR #8049 (#8027) removed the Phase 2 Setup Wizard, deleting the wizard-bound immunisation upload validation scenarios first added in #7922. The validation moved with its surface to the PPP Passport ImmunisationsCard, so the @regression reject paths (disallowed type / over 10MB on the Hepatitis B row) now live on the passport and assert the exact inline Alert text. The image-type accept path is already covered by #7339.
2026-06-02Document OCR autofill — uploading an image document to the Add Document form runs Gemini OCR (existing Azure OpenAI Vision integration) and pre-fills Issuer, Type, Issued date, Expiry date, and Notes; suggestions are editable and OCR failure degrades gracefully to manual entry. Document is retained; no image or extracted value is logged.#8071, #7808Manual entry of certificate/document metadata is slow and error-prone; reusing the CPD sticker/operating-list OCR capability removes typing for passport documents and improves expiry-date data quality.
2026-06-02User-scoped the immunisation evidence blob keys and added a backend prefix guard. ImmunisationsCard now builds the upload key as ppp-passport/immunisations/{pppUserId}/{vaccination}/{ts}-{name}, and storage.generateUploadUrl rejects any ppp-passport/ WRITE key whose owner segment is not the authenticated caller's pppUserId — mirroring the existing ppp/medical_passport/{pppUserId}/ convention from #5062. Also constrained hospital.addToMyProfileFromRegistry's source input from free-text (z.string().max(50)) to the exact enum the registry search emits (local | NHS_ODS | AIHW). Added ACs hr-passport.immunisations.evidence-key-user-scoped and hr-passport.hospital.registry-source-enum plus @regression @issue-7967 BDD scenarios.#8014, #7967The immunisation evidence upload key did not include the uploader's pppUserId, and the generateUploadUrl guard only enforced per-user scoping for the ppp/medical_passport/ prefix — for any ppp-passport/ key it ran the traversal + key-regex checks but never validated the path belonged to the caller. An authenticated user could therefore obtain a valid SAS WRITE token for an arbitrary ppp-passport/immunisations/... key and clobber another user's evidence blob (integrity/IDOR-write). The free-text registry source similarly let a crafted client persist an arbitrary authoritative-looking provenance string (issue #7967, security).
2026-06-01Renamed the passport route from /hr-passport to /ppp-passport so the URL matches the "PPP Passport" product name shown across the UI, and renamed the spec slug docs/features/hr-passport.md → docs/features/ppp-passport.md (and the BDD feature/steps files) for full naming consistency. The legacy /hr-passport path and its /hr-passport/share/:token sub-path now permanently redirect to /ppp-passport, preserving sub-path, share token, query string, and hash. In-app navigation (sidebar, universal search, notification deep-links, roadmap milestone routes) and newly generated share URLs point at /ppp-passport; the breadcrumb/page title remains "PPP Passport". Added ACs hr-passport.route.canonical, hr-passport.route.legacy-redirect, hr-passport.route.in-app-nav plus @smoke/@regression @issue-7810 BDD scenarios.#7979, #7810The route still used the legacy "HR Passport" naming while the feature was rebranded "PPP Passport" everywhere user-facing; the URL should match the product name for consistency and shareable links (issue #7810; Rob deep-dive 1 Jun 2026 ratified renaming the spec slug as well, not just recording the route). The @feature: tag and spec slug move to ppp-passport; the @github-label tag intentionally stays feature:hr-passport so existing issue labels keep tracking this spec.
2026-06-01Immunisation required set is now jurisdiction-driven — resolved from the doctor's hospital (country, state) via a (country, state) → requirements matrix (resolveRequiredImmunisations) instead of a fixed five-vaccination list. Expanded the vaccination catalog (MMR, Varicella, Diphtheria, Influenza); Hepatitis C removed from all requirements (no vaccine exists). hrPassport.listImmunisations returns the resolved requirements + jurisdiction; the domain roll-up verifies against the jurisdiction set. ImmunisationsCard renders the resolved set and is mounted on the PPP Passport page and the onboarding step, which now prompts for the doctor's hospital. Added AC hr-passport.immunisations.jurisdiction-matrix.#7957, #7338Matt asked (#7338) to "guide users on what immunisations they require". AU healthcare-worker immunisation is state-mandated (NSW OASV PD2024_015, etc.), so the required set must be derived from the hospital's jurisdiction — the same mechanism serves the UK Prod deployment (the GB rows). Multi-vaccine OCR extraction is tracked separately (#7941).
2026-05-28Added Gallery view to Medical Passport page — image thumbnails per document with lightbox zoom, typed-file placeholder for non-images, and "No image attached" placeholder for missing files.#7809Lets doctors and recruiters recognise and verify documents at a glance, mirroring how a physical credential wallet is browsed (#7809).
2026-05-27Brought the /hr-passport document page on-brand with the shared page template — replaced the hand-rolled title/header row with the shared PageHeader and wrapped the tabbed content in the compact, token-driven SectionCard (thin 1px border, ~13px text, tight spacing) matching /cpd-dashboard and /logbook-case. Replaced the remaining hardcoded hex on the Certificates "Submitted" chip with SEMANTIC_COLORS.status tokens. Added AC hr-passport.display.on-brand-page and a @regression @issue-7826 BDD scenario.#7826The page used a bespoke header and bare tab strip with hardcoded colours, so it looked off-brand next to the rest of the app ahead of the investor/legal demo (session-2026-05-27 — Rob: bring /hr-passport on-brand). Layout/brand pass only — no functional change.
2026-05-26Renamed all remaining user-facing "HR Passport" labels to "PPP Passport" (sidebar nav, route titles, universal search, roadmap milestone, hospital-admin roster tab/header/empty-state, and the shared-credentials page header). Replaced the all-or-nothing profile passport presentation with a per-domain completion breakdown — the PPP Passport summary widget now lists each of the six compliance domains with a Complete / Outstanding indicator when expanded. Updated AC hr-passport.profile-widget and added a @regression @issue-7385 BDD scenario.#7427, #7385The passport was still branded "HR Passport" in several surfaces and the Doctor Profile presented only a single all-or-nothing control, so doctors could not see which compliance domains were done versus outstanding (catchup review, 26 May 2026). The per-domain breakdown reuses the canonical PASSPORT_DOMAIN_VALUES and DOMAIN_LABELS so it never drifts from the full PPP Passport page.
2026-05-20Verify hr-passport.verification.mandatory-training-magic-link AC ✅ — duplicate phrasing of the canonical hr-passport.mandatory-training.magic-link-batch AC (#6388) sourced from the same transcript paragraph. Same implementation in api/backend-ppp/src/services/passportTrainingService/ already satisfies it end-to-end (single email per batch via requestVerification; magic-link page lists every pending item; submitVerification accepts all per-item decisions + expiries on one POST with no re-auth because the token IS the credential). Flipped ⏳ → ✅, cross-linked to #6388 to make the duplication explicit, and added a fresh @issue-6389 @smoke scenario covering the one-email-no-re-auth-all-items-in-one-visit happy path.#6664, #6389SGD gap sweep — duplicate AC text resolved against the existing implementation, no behaviour change.
2026-05-20Verify hr-passport.mandatory-training.magic-link-batch AC ✅ — implementation in passportTrainingService already satisfies the spec (single email per user-per-batch, magic-link page listing every selected item, per-item confirm/expiry without re-auth, all per-item updates plus batch status flip wrapped in a single Drizzle transaction, missing/duplicate decisions rejected up-front). Flipped ⏳ → ✅, aligned the AC time-limit wording to the implemented 14-day TTL (matching the timesheet approver window from #5944) — the original 24h figure was not in the source transcript. Added @issue-6388 regression scenarios covering single-email-per-batch and atomic-rejection-of-partial-decisions.#6661, #6388SGD gap sweep — implementation predated the AC text; spec confirmed in sync.
2026-05-20Verified hr-passport.verification.rights-to-work — tiered RtW pathway already implemented via getRightToWorkPathway / submitRightToWorkDocuments (Tier 1 auto-verifies AU citizens / PRs; Tier 2 routes overseas doctors to PPP Staff manual review). Flipped AC ⏳ → ✅. Added @smoke BDD scenarios for both tiers. Automated digital API integrations (UK share code, AU VEVO) remain Q4-blocked as a future enhancement on top of the manual-review Tier 2 baseline.#6390SGD gap traceable to Dev Session 2026-05-12 §RightsToWork. Implementation already satisfies the tiered approach AC (delivered under #5615) — this PR verifies and documents that.
2026-05-20Immunisation verification two-step process — supporting evidence upload (step 1) now required on hrPassport.upsertImmunisation; PPP Staff verification (step 2) continues to flow through setImmunisationStatus. upsertImmunisationInputSchema rejects empty / blank documentBlobPath, and the per-row extent of proof per vaccination type is defined (Hep B / Hep C / Tetanus / Whooping Cough = single uploaded record; TB additionally requires a proofType selector). Flipped hr-passport.verification.immunisations from ⏳ to ✅; mirrors the indemnity pattern (#6386).#6387Closes SGD gap from Dev Session 2026-05-12 §Immunisations (~00:51:53) — Matt's transcript explicitly requires users to upload evidence with system-defined proof extent per vaccination type and expiry tracking, mirroring the CPD activity submission pattern.
2026-05-20Indemnity verification two-step process — certificate upload (step 1) now required on hrPassport.submitIndemnityVerification; PPP Staff verification (step 2) flows through the existing review queue. Schema, IndemnityCard, and BDD scenarios updated. Flipped hr-passport.verification.indemnity from ⏳ to ✅.#6386Closes SGD gap from Dev Session 2026-05-12 §IndemnityVerification (~00:49:42) — Matt's transcript explicitly requires two-step verification with mandatory upload + staff confirmation + expiry tracking.
2026-05-20Verified hr-passport.security.encryption-at-rest-in-transit AC as ✅ — duplicate of the existing hr-passport.encryption-at-rest-and-in-transit AC, satisfied by Azure Storage Service Encryption (AES-256) at rest and TLS 1.2+ in transit (pinned in Pulumi).#6384SGD gap-analysis surfaced a duplicate AC for the same encryption requirement; the underlying posture was already implemented in PRs #5943, #6170, #6383, #6560. Marked ✅ with spec-unchanged so the SGD gap board reconciles.
2026-05-19Flipped framing AC hr-passport.purpose.hospital-compliance-tick to ✅ — the PPP Passport's primary goal of being accepted by hospitals as a trusted compliance verification (eliminating repeat document submission and saving time/cost for doctor and enterprise) is now confirmed as the canonical product purpose, already embodied by the existing Compliance Blue Tick architecture documented in ## Overview and ### Purpose of this spec.#6583, #6391SGD gap analysis surfaced this as an uncited purpose statement from Dev Session 2026-05-12 §HRPassportPurpose (~00:43:35 — "The goal of the PPP Passport is to create a system where a PPP compliance tick is accepted by hospitals, saving time and money by eliminating administrative annoyance"). Pure framing AC — no code change required; the Compliance Blue Tick (### Purpose, pppPassportComplianceService, passport.summary-screen) already implements this goal. No BDD scenario added — framing AC is a product purpose statement, not behavioural.
2026-05-19Flipped AC hr-passport.verification.medical-reg-and-degree to ✅ — the Passport already verifies medical registration (AHPRA for AU via validateAhpraNumber format + PCA live lookup; GMC for UK via fetchGmcRegistrant + isAcceptableGmcLicenceStatus licence-status gate, dual-jurisdiction) and offers all three accepted medical-degree verification paths (My eQuals, EPIC, internal PPP verification, with external→PPP fallback). Added @regression @issue-6385 BDD coverage (GMC sign-up seed + Scenario Outline over all three degree pathways) that fails if any jurisdiction or pathway is silently removed.#6566, #6385, #5610, #5611The verification requirement (Dev Session 2026-05-12 §VerificationRequirements ~00:48:24 — "medical registration (AHPRA, GMC) and medical degree verification; options: MyEquals, Epic, or internal automated process") was already fully implemented under passportRegistrationService (#5610) and pppPassportMedicalDegreeService (#5611); #6385 closes the spec-drift by marking the AC complete and regression-locking the end-to-end contract. No production code changed.
2026-05-19Implemented real medical passport document verification, replacing the hardcoded isVerified: false stub on the recruiter share-link profile (#2903). Added is_verified, verified_at, verified_by columns to medical_passport_documents (migration 0098). Added two Super-Admin-gated tRPC procedures — medicalPassport.setDocumentVerification (sets/clears verified state, recording reviewer identity + timestamp) and medicalPassport.listPendingVerification (internal review queue). The public share-link profile (HrPassportSharePage) now renders a "Verified by PPP" badge on verified documents and an "Unverified" badge otherwise.#6531, #4645, #2903The recruiter-shareable HR Passport profile showed isVerified: false for every document, undermining the platform's credential-verification value proposition. The chosen approach is admin-managed verification (option 1 from the issue), mirroring the established internal-review pattern used by pppPassportReviewService (#5985) — the lowest-risk MVP path consistent with the hr-passport spec. New spec entry hr-passport.share-link.document-verification added under § Export.
2026-05-19Verified and pinned the HR Passport blob security posture end-to-end — Azure Storage Service Encryption (AES-256, Microsoft-managed keys) for blob + file services, enableHttpsTrafficOnly: true, minimumTlsVersion: 'TLS1_2' and allowBlobPublicAccess: false all pinned in Pulumi state; the getPublicUrl procedure hard-caps any Passport-scoped read SAS URL at 900s. Flipped AC hr-passport.encryption-at-rest-and-in-transit to ✅ and added end-to-end @regression BDD coverage.#6383, #5943, #6170The encryption-at-rest-and-in-transit security gate (Dev Session 2026-05-12 §DocumentSecurity — "encryption at rest and in transit should be implemented before moving to production") must be demonstrably satisfied and regression-locked before the HR Passport feature can move to production. The Pulumi posture (#5943) and the 15-minute Passport SAS ceiling (#6170) were already implemented; #6383 closes the spec-drift by marking the AC complete and adding regression scenarios that fail if the posture is ever weakened.
2026-05-19Added GB (NHS CSTF) mandatory training seed list — 12 core subjects grounded in Matt's NHS hospital training profile (Notion 2026-05-12). Person-named items excluded by design.#6285, #6163, #5983Matt's screenshot was from a UK NHS trust; GB jurisdiction existed in schema with zero rows. NHS CSTF is the public standard across all NHS trusts.
2026-05-19Mandatory Trainings domain — PPP verification card UI, 'no longer relevant' action (requires reason, records actor + timestamp), 30-day expiry reminder cron, and three new schema columns (not_relevant_reason, not_relevant_at, not_relevant_by).#5614Core AC for the Mandatory Trainings domain; allows doctors to manage jurisdiction changes without being nagged by reminders for training that is no longer applicable to their role.
2026-05-13Decided NOT to screen-scrape AU PI provider member portals (Avant / MIPS / MIGA). MVP path for HR Passport Indemnity stays as manual CoC upload + CPD-Home-pattern provider verification. Long-term path is formal API partnership outreach with the top three insurers (commercial track, not engineering). Investigation artefact added at docs/features/research/hr-passport-pi-scraping-2026-05-13.md.#6198, #5948All three top providers' ToS explicitly prohibit automated access. The OAIC has recommended a screen-scraping prohibition and Treasury is working on a statutory ban. Credential-handling liability and reputational risk against a Doctors-trust product are incompatible with the brand. No compliant scraping configuration exists.
2026-05-13Medical Degree domain — three verification paths (My eQuals, EPIC, PPP Verification). New ppp_passport_medical_degree side table (migration 0080) storing pathway, institution, qualification, graduation year, external credential ID, and external-fetch outcome. New pppPassportMedicalDegreeService (submitMedicalDegree, getMedicalDegreeRecord) on the hrPassport tRPC router. New MedicalDegreeCard MUI component for the future unified PPP Passport page. External-fetch failures automatically fall back to PPP Verification so the doctor's domain still progresses.#6190, #5611AC for the Medical Degree section of the HR Passport required three distinct verification paths plus a graceful fallback when the My eQuals / EPIC APIs are unavailable (live API integrations remain a separate spike). Reuses the existing pppPassportReviewService review queue from #5985 so PPP Staff can approve degree submissions through the same console as registrations.
2026-05-13Tightened the default read-SAS expiry for Passport blobs from 1 hour to 15 minutes (900s) in the storage.getPublicUrl tRPC procedure. Any read URL whose resolved blob key matches a Passport path fragment (medical_passport/, medical-passport/, hr_passport/, hr-passport/, ppp_passport/, ppp-passport/) is now hard-capped at 900s — even if the caller requests longer. Non-Passport reads (CPD evidence, bug-report attachments, certificate downloads, mailer-helper links) are unchanged.#6170, #5943Honours the original #5943 acceptance criterion ("signed URLs ≤ 15 minutes") which had been negotiated to "≤ 1 hour" because the existing AzureBlobProvider.getSignedReadUrl default is 3600s and the 24h-capped email-mailer flow shares the same primitive. Per-call-site clamping in getPublicUrl keeps the wider storage primitive intact while restoring the stricter posture specifically for Passport document access. Spec entry hr-passport.encryption-at-rest-and-in-transit updated.
2026-05-13Pinned the PPP Azure Storage account encryption posture in Pulumi so Passport documents are guaranteed encrypted at rest (Azure SSE, AES-256, Microsoft-managed keys) and reachable only over TLS 1.2+ (enableHttpsTrafficOnly: true, minimumTlsVersion: 'TLS1_2', encryption.services.blob/file explicitly enabled, allowBlobPublicAccess: false). Tightened the hr-passport.encryption-at-rest-and-in-transit AC to enumerate the exact storage-account properties the security review gate verifies, and added three @smoke BDD scenarios (@issue-5943) covering TLS, encryption pinning, and SAS short-expiry.#6168, #5943Production-readiness blocker for HR Passport — sensitive identity, registration, indemnity, immunisation and training documents must be encrypted at rest and in transit before any prod deploy. Encoding the controls in Pulumi state makes them a CI-enforced contract instead of relying on Azure defaults that a portal/CLI change could regress silently.
2026-05-13Auto-derive ppp_passport.country from the user's Profile country field. On Profile country change, propagate the mapped ISO value to ppp_passport. On first passport creation, seed country from the Profile row. Profile values AU / GB map to passport enum AU / UK via a shared mapProfileCountryToPassportCountry helper.#6130The hr-passport spec calls for "country context derived from Profile" — previously this required an explicit updatePassportContext mutation, which left the two fields drifting whenever a doctor updated their Profile country. Auto-sync keeps the country-specific indemnity rules (#5947) consistent with the canonical Profile value.
2026-05-13PPP Passport summary widget added to the Doctor Profile page. The widget shows the overall Blue Tick traffic-light status (green/amber/red), verified-domains count out of six, the next upcoming expiry date, and a link to the full HR Passport page. Collapsed by default; hidden for non-doctor personas (admin-only). Consumes the existing hrPassport.getPassport tRPC procedure — no new server endpoints.#5986Closes AC hr-passport.profile-widget so doctors see Blue Tick status at a glance from their Profile page without navigating to the full passport editor.
2026-05-13PPP internal review path for Medical Registration — Super Admin reviewers can now approve / reject / request-more-info on documents uploaded via the PPP Verification path. New superAdmin.passportReview tRPC namespace, new /admin/passport-reviews console page, and reviewer decision columns on ppp_passport_domain (review_decision, reviewed_at, reviewer_user_id, review_notes, migration 0078).#5985AC hr-passport.registration.internal-review required an internal review queue accessible from Super Admin to mirror the CPD Home external-activity verification pattern. MVP scope is Medical Registration; the same queue is parameterised by domain so the other compliance domains plug in later.
2026-05-13Seed roster of mandatory training items shipped — new ppp_mandatory_training_seed table + Super Admin tRPC namespace (superAdmin.mandatoryTrainingSeed.list/create/update/deactivate). Migration 0080 also adds seed_id to ppp_passport_training for traceability and inserts the initial AU roster (Fire Safety, Manual Handling, BLS, Infection Control, Hand Hygiene, WHS, Aggression Minimisation, Child Protection, Code of Conduct, Privacy & Confidentiality, Open Disclosure, Blood Transfusion Safety). New users' Mandatory Training section is now auto-populated from applicable seeds based on Hospital + Jurisdiction.#5983AC hr-passport.mandatory-training.seed-data shipped — the platform now ships with the agreed AU seed roster and Super Admin can add/edit/deactivate items, with new doctors' passports pre-populated based on their country and assigned hospitals.
2026-05-13Country-specific indemnity rules — Blue Tick now treats indemnity as REQUIRED for AU doctors and OPTIONAL for UK NHS doctors (NHS Indemnity Scheme provides cover). Added country + nhsEmployer columns to ppp_passport; passport response now includes a domainRequirements block with a contextual NHS Indemnity Scheme note for the UI to surface.#5947Indemnity-cover semantics differ by country and employer — AU doctors must hold personal cover; UK NHS employees are covered by their employer under the NHS Indemnity Scheme. Treating indemnity as universally required produced false-negatives for UK NHS personas.
2026-05-13Mandatory-training verification now uses a single magic-link email to the training provider with a bulk approve page that captures per-item expiry dates — replaces any per-item email model.#5944Providers verifying multiple certificates for one doctor should receive one email, not one per item; expiry capture moves the source-of-truth for training expiry onto the provider rather than the doctor's self-attestation.
2026-05-13Visa / Passport / Right to Work domain — two pathway-driven flows decided server-side from ppp_passport.citizenshipStatus. Local citizens (au_citizen / au_permanent_resident) have right_to_work auto-seeded as verified with the internal_review pathway and a synthetic verifier identity on first passport access — no upload required. Overseas doctors use a new hrPassport.submitRightToWorkDocuments mutation that accepts a document blob path and a future-dated visa expiry, persists both on the ppp_passport_domain row, and enters the existing PPP Staff review queue parameterised by domain. New hrPassport.getRightToWorkPathway query resolves the pathway server-side so the client never picks. New VisaCard UI component renders the matching pathway (local-citizen verified state vs overseas upload form) plus a nationality-missing gate. Visa expiry reminders are handled by the existing processPassportExpiryNotifications job (works on any domain row with an expiresAt).#5615AC Visa / Passport / Right to Work required the internal review workflow for uploaded documents with the local-citizen vs overseas split. Digital API lookups (UK / AU VEVO) remain blocked on Q4 research and are out of scope for this PR — covered by future work.
2026-05-13Immunisations domain — manual upload + confirm path shipped for the five required vaccinations (Hep B, Hep C, Tetanus, Whooping Cough, TB). New ppp_passport_immunisation table with one row per (user × vaccination); TB rows carry a proof_type (igra | mantoux | cxr | historical_record); Immunisations domain rolls up to verified only when all five rows are verified. Frontend ImmunisationsCard renders the five sub-statuses with a TB proof-type selector that gates the upload CTA.#5613Closes the v1 Immunisations work that was previously blocked on Q1 (multi-vaccine OCR cost/value) — OCR is deferred indefinitely per the spec, so manual upload + reviewer-confirm becomes the default verification path. Per-vaccination sub-records mirror the way hospitals actually audit immunisation evidence and let renewal reminders fire per-vaccination instead of treating the whole certificate as one expiring blob.
2026-05-13Indemnity domain — added external verification flow (hrPassport.submitIndemnityVerification) capturing provider, policy number, expiry date, and optional document upload. Added daily cron jobs processIndemnityExpiryReminders (30-day advance reminder) and processExpiredIndemnityDomains (auto-flip verified → expired past expires_at). New policy_number column on ppp_passport_domain carries the external policy reference. Frontend IndemnityCard renders the four states (unverified / pending / verified / expired) with a Re-verify CTA enabled within 30 days of expiry.#5612Indemnity acceptance criteria called out external-provider verification + expiry reminders + re-verification flow. Verification is operationally manual (PPP Staff confirms with the provider) so the data model needs to carry provider + policy + expiry so Staff can do the lookup without a separate ticket system. The 30-day reminder and auto-expire sweeps mirror the ppp_passport.indemnity-country-rules requirement that expiries are surfaced as reminders.
2026-05-13Medical Registration domain wired into PPP Passport — sign-up now seeds the medical_registration sub-record on ppp_passport_domain with verification_pathway = 'ahpra' or 'gmc' and stamps the passport country (AU/UK). New hrPassport.listMedicalRegistrations and hrPassport.addMedicalRegistration tRPC procedures support dual-jurisdiction (e.g. an AHPRA-registered doctor adding GMC). Per-jurisdiction registrations live on the new ppp_passport_registration table (migration 9610). Re-uses existing AHPRA (validateAhpraNumber) and GMC (fetchGmcRegistrant) verification helpers.#5610Closes ACs "Primary registration captured at sign-up" and "Second jurisdiction can be added post-sign-up via Passport page" — without this wiring, sign-up verification was discarded and the Passport never reflected the user's medical registration state.
2026-05-13Added the PPP Passport summary screen at /passport — renders all six compliance domains as cards plus a server-driven Blue Tick banner (verified / pending / expired) and an upcoming-expiries list for the next 30 days.#5609Doctors had no single place to see their overall compliance state; per-domain pages were already in flight (#6178, #6188, #6190, #6194, #6175, #6200) but lacked a roll-up. The summary screen makes the Blue Tick visible at a glance and is the destination the recruiter-facing export and Profile widget both link to.
2026-05-06Blue Tick required-domain set is now jurisdiction-aware — AU citizens and AU permanent residents do not need right_to_work; overseas doctors continue to require it (safe default for null/unknown).#5639Overseas right_to_work semantics differ from local-citizen semantics; treating all users as overseas produced false-negatives for AU citizens who had all other five domains verified.
2026-05-05Awaiting-Matt sweep — Q1 multi-vaccine OCR deferred indefinitely; Q3 hospital training APIs assumed-none in MVP; Q4 right-to-work API uses VEVO for AU (AU-first); Q5 Blue Tick green→amber 30-day grace→red; Q6 recruiter attestation URL 7-day expiry, no-login signed JWT, doctor-revocable. All five resolved engineering-led, Matt to ratify.Engineering-led answers using project_au_first_uk_later memory; recruiter-URL pattern mirrors existing hr-passport export contract.
2026-04-21Spec created from Matt's 17 Apr 2026 Notion briefthis PRWave 4 — largest single new spec; establishes Passport entity + six compliance domains + Blue Tick roll-up + recruiter export

Internal documentation — org members only