Timesheets & Geo-fence
Feature Overview
The timesheet module automates work-hours logging for doctors. The primary mechanism is geo-fencing: the mobile app detects when a doctor arrives at or departs a hospital, and automatically creates/prompts to complete a timesheet. Doctors can also create timesheets manually.
Timesheets feed into fatigue management alerts, pay claims, and eventually automated submission to payroll or administrative officers.
Open Questions
| # | Question | Source |
|---|---|---|
| Q1 | Time-at-Work colour bands — narrowed (#8531) then missed-lunch resolved (#8169): the five uncontested AU threshold rules from Matt's "AU_vs_UK_Timesheet_Parameters (1).docx" (Timesheet Notion page, 2026-05-03; confirmation table on #8169) are BUILT as jurisdiction-keyed config (#8531): overtime over 10h in a single shift, over 38 ordinary hrs/week, and work outside the ordinary span (Mon–Fri 06:00–18:00); fatigue rest under 10 consecutive hours between shifts, and a shift over the 12.5h QH absolute cap. GB / unknown jurisdictions keep current behaviour byte-for-byte. The missed-lunch meal rule is now resolved and built (#8169): Matt confirmed on 2026-06-15 ("row 4 is wrong - and should be 5 hrs") the Award figure of one 30-minute break for any shift over 5 hours, superseding the interim AU over-3h/20-min placeholder (#8172). Open remainder: (a) the within-shift meal-break TIMING nuance Matt raised on #8169 (break earned at the start vs end of the 5 hours) — a presentation detail, not modelled by the duration-based detector; (b) Time-at-Work colour band semantics (light/dark/darker) — Matt said the proposed mapping "seems ok"; UI implementation tracked separately. See the AU vs UK parameters appendix below | AU scope; Matt confirmed missed-lunch on #8169 |
| Q6 | Where should the geofence stream-silence / stuck-open-shift monitors (#10916) surface? The detection itself is built (server-side, scheduled — monitorGeofenceStreamSilence / monitorStuckOpenGeofenceShifts), logging a Log Analytics warn line on the existing scheduled-task cadence. Whether either signal should ALSO reach the affected doctor, a specific admin/ops inbox, or stay log-only is an open product decision — not blocked on, but worth Matt's view given the issue explicitly flagged it as open. See #10920 for the separate, already-scoped mobile-side "location inactive" indicator, which is the user-facing counterpart for the permission-loss trigger specifically (not the general server-side detection built here). | #10916 (open per the issue itself) |
Closed Questions (5) — click to expand
| # | Question | Source |
|---|---|---|
| Q2 | "Approved timesheet destination" — user-configurable per entry, or set once on Profile? Resolved 2026-04-28: configured on user_assigned_hospitals (per user × hospital) — see Approver Model below | Approver flow |
| Q3 | Missed-lunch detection threshold — how many minutes into a shift without a recorded break triggers the "missed lunch" flag? | AU Fair Work rules |
| Q4 | Approver session scope: transcript 2026-05-06 §ApproverAuthMethod (~00:18:06) says the approver "would only need to authenticate once per session". Is a single browser-session-wide auth required, or is the shipped per-action scope acceptable? | Transcript 2026-05-06 §ApproverAuthMethod (~00:18:06); cross-ref #7327 |
| Q5 | Should a magic-link approver additionally verify identity via Google/Apple SSO for a stronger audit trail? | Transcript 2026-05-06 §ApproverSSO |
| Q7 | Doctor attaches their own timesheet approver: does an admin need to confirm it? Matt's newest word (#11181 brief, 2026-07-29) lists "User attaching hospital, payroll number, payroll approver and Pay cycle day" as Stage 1 of the lifecycle. On 2026-07-14 he also agreed ("correct") that a doctor who isn't part of a hospital (B2B) setup "can add in the email address" themselves. Matt has not said whether a doctor who picks an internal PPP consultant as approver needs an admin confirmation step. Answered 2026-10-04 (Rob, #12678/#12801/#12821; Matt 2026-10-03 on #12802): no admin confirmation; the doctor self-nominates by name + email and an admin-set approver overrides it. Built name + email self-nomination (see timesheets.approver.user-attaches-approver). | #12678 (for-discussion); #11181; transcript 2026-07-14 (~00:31:54) |
Matt's 17 Apr 2026 Notion Brief — Requirements Update
Source: Timesheet Notion brief.
Matt's 17 Apr brief re-affirms the Smart Geotag flow and adds concrete UX rules around entering/exiting hospital behaviour.
Smart Geotag — UX rules
- Entering hospital: on-screen PPP toast "You have entered {Hospital}". Does not route to the bell — this is a passive acknowledgement, not a notification.
- Exiting hospital: on-screen PPP toast "You have exited {Hospital}. Complete your timesheet entry." The toast carries the quick-entry affordance: shift type, optional lunch break, notes.
- Fatigue trigger: if the completed entry satisfies fatigue criteria, an automatic fatigue trigger fires (see fatigue rules — AU and UK differ, Q1).
- Minimum-stay filter: if the user is in the tag zone for under 5 minutes, the log is automatically deleted (not saved as a draft) — prevents drive-by false positives.
Fortnightly submission
- Monday 6am fortnight-end → prompt user to complete the fortnight's Timesheet and submit to their Timesheet Approver.
- Where the reminder shows (Rob 4 Oct 2026; open question for Matt): the weekly / fortnightly timesheet submit reminder appears under Action Items → Platform Reminders only; it does not ring the notification bell. Whether it should also reach the bell is for Matt to decide; delivery is deliberately unchanged here (#12939).
- Approver approves → approved timesheet routes to the elected destination: Hospital Admin, a designated support-officer email, or direct to payroll (see Profile (Doctor) Timesheet Approver field).
Fatigue + HR rules — AU vs UK divergence
- Rules differ between AU and UK. Matt notes he originally relayed these to the Moreton Blue team; the reference docs live somewhere in the information deck or drive.
- Rob task: locate Matt's original fatigue/HR docs (AU + UK) and add to this spec as a reference appendix.
- 2026-05-06 update: AU is the build target. UK rules deferred. Matt to cross-check current platform thresholds against the research doc and confirm or correct (Q1 blocker).
Matt's 6 May 2026 Call — Requirements Update
Source: Rob & Matt call 2026-05-06 (transcript: "Catchup – 2026/05/06 06:39 BST"). Resolves several open UX questions and locks the approver experience.
Approver experience — magic-link only, no full PPP login
- Approver does not log into PPP. No username/password, no SSO sign-up flow. The magic link in the approval email IS the auth.
- Browser session persists: once an approver authenticates by clicking a magic link, subsequent approval clicks within the same browser session do not re-prompt.
- Optional, deferred: third-party identity validation (Google / Apple SSO) for stronger audit trail. Not in scope until Matt asks; magic link is sufficient.
- Magic-link landing page shows ALL pending authorisations for that approver, not just the one batch the link was generated for. One click → one screen → approve/reject/request-info on every pending timesheet from any of the approver's doctors.
Email link expiry — 14 days, regenerable, validity stated
- All emailed action links (timesheet approval, evidence review, any future approver flow) expire 14 days after issue. Updated from the previous 7-day token TTL in
generateTimesheetBatchApprovalToken. - Email body must explicitly state the validity window. Shipped wording (
utils/email/templates/timesheet-approval.ts): "expires 14 days from when this email was sent" (a relative period, not a calendar date); the original brief wording was "This link expires on {date}". A relative period is accepted as meeting the requirement; whether Matt wants a calendar date instead is a copy question for him, not a defect (spec-review 5 Oct 2026, #12939). - If the link has expired when consumed, the approver lands on a "Link expired — request a new link" page that triggers a re-issue back to the same approver email. The re-issue resolves the batch owner from the batch alone (the owner's stored email and user id), never from whoever happens to be signed in to the browser that follows the link (#12616).
- Super admin needs visibility (count sent, count expired, count consumed) — see admin.md.
Smart Geotag — entry/exit notification surfaces
- Hospital entry: mobile OS push notification on the lock screen (not just an in-app toast). Copy: "You have entered {Hospital}". Tapping the notification routes to the timesheet entry view (passive — no required action). Supersedes the 17 Apr "in-app toast only" wording above.
- Hospital exit: mobile OS push notification "You have exited {Hospital}. Complete your timesheet entry." Tapping routes the doctor directly to the timesheet entry form (existing form, or a stripped-down "light" web form for non-app users) — not the home screen.
- Dwell thresholds (reconciled):
- <5 min in zone → log auto-deleted (drive-by suppression). Unchanged.
- <15 min continuous dwell → entry notification suppressed (avoids notifying doctors who live near a hospital). New from this call.
- ≥15 min dwell → entry notification fires.
- Superseded 2026-08-11 (Matt, WhatsApp): "reduce geotag timeframe within radius to 5 mins. If less than 5 minutes it would be clocked as a pass by (in our back end log) but not displayed to user". The 15-min tier is gone. A stay of 5 min or more opens the shift and notifies the doctor. A stay under 5 min is a back-end-only pass-by. See
timesheets.geofence.min-arrival-stay(⚠️ drift, #12734).
- Hours recorded to the minute (entry timestamp, not bucketed).
Fortnightly submission destination
- Restated, no change: doctor submits → line manager / approver signs off → approved batch is forwarded to the elected destination on
user_assigned_hospitals(Hospital Admin, designated support-officer email, or direct payroll).
Single-fire submit (no duplicate records)
timesheets.submit.single-fire— saving a timesheet entry and submitting the fortnight for approval each disable the primary action and show a pending state until the mutation settles; a rapid double-tap fires the create/submit mutation at most once, so a mobile double-tap can no longer create a duplicate timesheet entry or a duplicate approval batch. Implemented via the sharedSubmitButtonprimitive (seedesign-system.md→design-system.submit-button.single-fire). † (#9323)
Widget data freshness
- Dashboard widget figures (time-at-work, missed-lunch %, overtime, fatigue, recall) must be computed from current entries, not the last approved fortnight cycle. Provides a fast feedback loop so the doctor sees the impact of today's shift without waiting for the cycle to close.
Working-year overview widget — NEW
timesheets.widget.year-overview— a physical/visual representation of total working hours, broken down month-by-month for the user's current working year. Sits on the timesheet landing surface. Doctor can scan a year of work at a glance.- ✅
timesheets.widget.submitted-stat-grid— the dashboard Timesheets Submitted widget (TimesheetsCompletedWidget) presents its three status counts (Approved / Submitted / Complete — renamed from "Saved", #11454) as a compact stat grid — one number-focused tile per status plus a total summary badge — rather than a donut. The presentation contract is owned by the dashboard spec (dashboard.timesheets-submitted.stat-gridindocs/features/dashboard.md); this timesheet-surface AC records that the widget deliberately sits outside the shared donut standard. Presentation-only: same data points, no timesheet data-model or backend change. † (#10585)
Scope & deferrals
- AU-only build for now. UK behaviour (NHS hospital data, UK fatigue rules, GMC-specific copy) is deferred. Avoid AU/UK forks in this surface until UK is reactivated.
- Base-rate input + financial audit facility — DEFERRED. Future enhancement. Not in current scope.
- Investor demo: B2C timesheet stays in the investor demo (and Queensland Health dry-run). Confirmed by Matt 2026-05-06. Resolves dashboard Q4 (#5455).
Original Vision
Geo-fence Detection (from Geofencing Requirements doc, Jan 2026)
The system must detect hospital arrivals and departures using GPS:
- Arrived trigger: user within 100m of a hospital coordinate (see radius note below)
- Departed trigger: user remains outside radius for >10 minutes (prevents jitter)
- Edge case: Doctor who lives within 100m of hospital — require minimum 5 min stay (was 15 until #12734; see
timesheets.geofence.min-arrival-stay)
Geo-fence radius — 100m (fixed, not user-configurable) The
GEOFENCE_RADIUS_Mconstant inmobile/ppp/lib/services/location-service.tsis set to 100 metres. This was increased from 50m (Apr 2026, #4660) because:
- AIHW hospital coordinates target building entrances; road frontage is typically 80–130m away.
- 50m never successfully triggered a
geo_fence_eventsrow in UAT (0 rows confirmed).- 100m covers the campus carparks and road frontage without overlapping co-located campus entries.
- 200m was considered but caused zone overlap between the 6 co-located Mater South Brisbane entries — confirmed via coordinate mapping in #4662.
- Configurability was removed to reduce complexity (confirmed Rob & Matt call 2026-04-07). If coordinate imprecision is reported for a specific hospital, verify the coordinate against the building entrance / road frontage and update the hospital record accordingly.
Geo-fences derive live from the hospital's single lat/lon — never a per-user copy (ADR-0005, #10178). Each hospital carries one canonical
hospitals.latitude/longitude; the detection radius is applied live in code (haversine overuser_assigned_hospitals ⋈ hospitals), not pre-calculated or copied per user.workplace_locationsno longer stores a copy of the hospital's name/lat/lon — a hospital-linked row is a coordinate-free marker recording only the per-user Smart Geo TagisActivetoggle. A hospital coordinate correction therefore takes effect for every already-attached doctor immediately, with no re-attach step and no stale copy — closing the drift class behind #10164 / #10168 / #10173. (Behaviour-preserving: the 100m detection intent above is unchanged.)
- Battery optimisation: "Significant Location Change" monitoring, increase precision only when within 1km buffer zone
- Background sync: Refresh hospital coordinate database every 30 days
Hospital Data Sources:
| Region | Source | API |
|---|---|---|
| Australia | MyHospitals API (AIHW) | GET https://myhospitalsapi.aihw.gov.au/api/v1/reporting-units |
| Australia | Digital Atlas (ArcGIS) | Public + private declared hospitals |
| UK (NHS) | NHS ODS (ORD API) | GET https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?PrimaryRoleId=RO197 |
| UK (Private) | CQC API | Requires API key — GET https://api.service.cqc.org.uk/v1/locations |
Auto-Timesheet Creation
- On geo-fence exit: push notification "Complete your timesheet"
- Auto-create draft timesheet with arrival/departure times
- User reviews and submits
Multiple Entries Per Day (Jan 2026 — resolved in #3616)
- On-call, recall, overtime on same date
- Multiple timesheet entries per day supported ✅
Approver Workflow
- Consultant acts as approver for non-consultant timesheets
- Approver receives email if not on the platform
- In-platform approver action item (#3618)
- Forward approved timesheet to administrative officer
Fatigue Management
- Fatigue shift flag when hours exceed safe limits
- Missed lunch detection
- Overtime tracking
Fortnightly Submission
- Prompt doctor to submit timesheets every two weeks (#3617)
Acceptance Criteria
Geo-fence (Mobile)
- ✅ App detects hospital entry within 100m radius (
GEOFENCE_RADIUS_M=100— see radius note above; the previous "150m" wording contradicted the spec's own 100m decision) - ✅
timesheets.geofence.shift-session-grace— App treats boundary crossings up to the shift-gap grace window apart as ONE continuous visit, firing exactly one "Entered {hospital}" push and one "Leaving work" push per real visit regardless of how many times GPS crosses the 100m boundary during it: on EXIT the timesheetendTimeis updated (⚠️ #11099 — no longer on every exit delivery; only on one that SETTLES the departure, seetimesheets.geofence.exit-settlementbelow. The audit trail is still written on every exit, unchanged) but the "Leaving work" push is deferred, persisting ahospitalId → PendingExit { exitedAt }state; the next ENTER for that hospital (or a periodic location-update tick while still outside) resolves it — within the window it is the SAME visit (pending exit cleared, nothing fires), once the window has lapsed the now-overdue "Leaving work" fires for the closed session before the new ENTER is handled as a genuine fresh arrival. A genuine split shift (leaves for longer than the window, returns later the same day) therefore still produces its own Entered/Leaving pair for the new segment — this is correct signal, not suppressed. Arrival responsiveness is unchanged: "Entered" still fires on the first real ENTER with no pending exit. #10621 — the grace window is now the single DB-configurablegeoFenceExitGracePeriodMinutes(geo_fence_preferences, default 5 min), the same value that governs the backend duplicate-exit suppression — no longer a separate hardcoded 30-minSHIFT_GAP_MS. Mobile syncs the value viasyncGeoFenceGracePeriod(called when geofences are armed) and reads it throughgetSyncedShiftGapMs, falling back to the 30-minSHIFT_GAP_MSconstant only when no synced preference is available (fresh install / offline); the read clamps to a 60-min ceiling mirroring the server upsert bound. #10717 — per-hospital overrides are now synced too.syncGeoFenceGracePeriodalso fetches the resolved grace value for every armed hospital in one self-scoped batch call (geoFencePreferences.resolvedGracePeriodsForAssignedHospitals— userId derived from context, never client-supplied) and persists each into a per-hospital key (geofence-exit-grace-ms:<hospitalId>), applying the same per-hospital → user-default → DEFAULTS precedence the backend'srecordExitdedup uses (getGeoFencePreferencesForUser).getSyncedShiftGapMs(hospitalId)and the shift-gap decision sites (isShiftGapExpired,resolveOverduePendingExits) pick the window for the hospital whose geofence fired: its per-hospital override if any, else the user-wide default, elseSHIFT_GAP_MS, with the 60-min clamp on every tier — so mobile's same-shift window and the backend's dedup window can no longer diverge even for a hospital carrying a per-hospital override (the drift class #10621 eliminated, now fully closed). ⚠️ With the current default of 5, the same-shift re-entry window is 5 minutes by default (previously 30) — leaving the geofence for more than 5 min then returning starts a NEW shift session; because the value is DB-configurable this is tunable without a mobile release. Supersedes (not a revert of) the prior 10-min debounce pair —shouldFireExitNotification/shouldFireEntryNotificationandEXIT_NOTIFICATION_DEBOUNCE_MS/ENTRY_NOTIFICATION_DEBOUNCE_MSwere deleted, replaced byisShiftGapExpired/getSyncedShiftGapMsand the persistedgetPendingExit/setPendingExit/clearPendingExit/resolveOverduePendingExitsstate machine inmobile/ppp/lib/services/location-service.ts† † (#10621, #10422, supersedes #10234, #10387) - ✅
timesheets.geofence.exit-settlement— A burst of geo-fence exits across ONE real departure settles the shift'sendTimeexactly once. The OS delivers many EXIT events per departure — UAT user 17 recorded 3 entries/16 exits (2026-07-22), 2/5 (07-23), 1/7 (07-24), 1/2 (07-27) — and mobile wroteendTime: nowon every one, so the draft kept being extended and never settled when the doctor actually left (#10422 called that write "idempotent and cheap"; it is not —nowdiffers on each delivery). The webrecordExitpath has suppressed clustered exits on a 30-min window since #3674, but #9257 split the mobile path ontologExit, which had no suppression at all.logExitnow returnssettlesShift, decided by the dependency-freeevaluateExitSettlement(geoFenceEventService/exitSettlementRules.ts). The rule is DISTANCE-CONFIRMED, not merely time-clustered, and that is the substantive change from this AC's first draft: a shift settles ONCE per departure, anchored at the FIRST exit whose recordeddistance_metersEXCEEDS the authoritative workplace fence radius (workplace_locations.radius_meters, resolved server-side by the same helper #11157 added for thewithin_geofencederivation — mobile's hardcoded 100 m is never used for this). The anchor is never re-anchored: every later exit is suppressed until anentryproves the doctor returned, which is what breaks a departure and lets genuine split shifts (#10170) each settle on their own anchor. Exit deliveries at or inside the radius are ignored for settlement as GPS jitter (#11100 recorded an 'exit' at 55 m inside a 200 m fence); deliveries carrying no distance (pre-#11124 clients) are treated conservatively and never anchor. Suppressed exits are still written togeo_fence_eventsso #10342'sinsideGeofencelatch clears.EXIT_CONFIRM_WINDOW_MS(5 min) classifies a suppressed delivery as a burst repeat vs. a far-field straggler for the audit log; it deliberately does not expire suppression, because #11100 recorded stragglers at ~68.5 km / +125 min that must still not move the end. Why the previous 30-min window was replaced: both review passes found the M1 freeze defect — the old window re-anchored on every exit including suppressed ones, so a trickle of deliveries could hold it open indefinitely. Against the instrumented evidence neither candidate survived: 3-min would have missed a real delivery observed at +4.2 min, and 30-min bought nothing once re-anchoring was removed. Replaying user 17's recorded 2026-07-31 burst (586 → 586 → 852 → 1040 → 3646 → 3761 m over 4.2 min) settles exactly once, at the first confirmed exit. A stale exit replayed late from mobile's offline queue arrives after the departure settled and is therefore suppressed — it can never drag a settled end backwards (#10925 anti-truncation), and neither can jitter, which never anchors at all. Mobile gates itstimesheets.updateclose-out onsettlesShift, failing OPEN if the call errors or the flag is absent (a blocked close-out would risk stranding the shift on its #10915 arrival placeholder — the worse failure #10917 exists to prevent); that fail-open is also what makes the conservative null-distance branch safe. ⚠️ Evidence base is thin and the constants are explicitly revisitable: the rule was derived from 12 events / 1 user / 3 days, with no exit→entry re-entry observed andaccuracy_meterspopulated on 0 of 12 events (#11100 stays open for that half). Enough to reject re-anchoring and set the default; not enough to tune per-hospital. #11100 recommends revisiting after ~2 weeks of multi-user data. ⚠️ The end-time half of this fix is client-gated: the server stops treating repeat exits as settling immediately on deploy, but theendTimewrite itself is made by the mobile app, so already-deployed builds keep writingendTimeon every exit delivery until users update to a build that gates onsettlesShift. Server-side suppression and the audit trail are correct from day one; the user-visible "shift stops being extended" improvement arrives per-device with the app update. † † (#11099, #11100) - ✅
timesheets.geofence.battery-significant-location-change— Background geo-fence service does not drain battery: the mobile location service runs a low-power significant-location-change profile far from any hospital and only engages high-precision GPS within the 1km buffer zone (selectLocationAccuracy/resolveTrackingAccuracyinmobile/ppp/lib/services/location-service.ts) † (#7497) - ✅
timesheets.geofence.dwell-notification-id-persisted— The #5862 dual-timer arms BOTH an in-processsetTimeoutand a persistent OS notification ({ date }trigger), relying oncancelPersistentDwellNotificationto cancel the OS one so the doctor never receives both. That cancel now resolves the notification id from a persisted per-hospital store (geofence-dwell-notification-id) before falling back to the in-memorydwellState. This is required, not defensive: an iOS geo-fence event is delivered to a fresh JS invocation whenever the app is backgrounded or killed — the normal case for a geo-fence wake — sodwellStateis empty on the next invocation, the in-memory-only lookup cancelled nothing, and a second OS notification was scheduled for the same absolute wall-clock time as the still-armed first, delivering two byte-identical "Entered {hospital}" pushes at the same timestamp. Note the scope boundary:timesheets.geofence.shift-session-grace(#10422) governs whether two separate transitions are one visit and is structurally unable to see this defect, which fires two pushes for one transition — which is why the #10387/#10421/#10422 lineage did not prevent the 2026-07-31 recurrence. The spec already recorded the premise intimesheets.geotag.arrival-placeholder-indicator(#10915 — "dwellStateis in-memory only and does not survive a JS-runtime restart"); this AC follows that fact through to the notification path. The id is cleared once the dwell resolves so a stale id can never be re-cancelled or read as in-flight. Related:wasNotifiedToday/markAsNotifiedis a persisted per-hospital per-day entry dedup that is exported and unit-tested but has never been called by any production path — it is not, and never was, a backstop for this class. † (#11349) - ✅
timesheets.geofence.min-arrival-stay— Edge case: minimum continuous stay before an "arrived" timesheet is confirmed; a drive-by shorter than the threshold never confirms an arrival (shouldTriggerArrival/MIN_ARRIVAL_DWELL_MS, reconciled with the existingevaluateDwellOnExitdwell-suppression logic). Requirement (spec refresh 2026-10-03, WhatsApp top-up): the threshold is 5 minutes within the radius. A stay of 5 min or more opens the shift. That confirms the arrival, fires the entry notification and shows the running-shift indicator. A stay under 5 min is a pass-by. It is kept in the back-end log (geo_fence_events) but never shown to the doctor: no draft entry, no notification, no indicator. † Fixed (#12734, 2026-10-03):MIN_DWELL_NOTIFY_MS(and soMIN_ARRIVAL_DWELL_MS) is now5 * 60_000, matchingMIN_DWELL_DELETE_MS, andSTUCK_SHIFT_MAX_PLAUSIBLE_MINUTESis 5. History (condensed in the 5 Oct 2026 spec review so the yardstick is unambiguous: the requirement is 5 minutes, above). The 15-min dwell figure came from the Jan 2026 Geofencing doc and the 2026-05-06 call (#5811); it was replaced by 5 min on Matt's 2026-07-29 / 2026-08-11 statements (the supersession chain is in the dated ledger below). The 2026-08-22 "correction" (PR #11702, which read the 29 Jul decision as being aboutradius_metersonly) is itself superseded. #11145 also closed a mobile-persistence gap in the same mechanism:dwellStatewas in-memory only, soevaluateDwellOnExitwas silently skipped whenever the JS runtime restarted between a hospital ENTER and its matching EXIT; the dwell-entry state (entryTime,timesheetId,notificationFired) is now persisted likePENDING_EXIT_KEY/DWELL_NOTIFICATION_ID_KEY, so the gate runs across a runtime restart. † (#7497, #11145) - ✅
timesheets.geofence.residency-default-fallback— Native tRPC stays on the default backend unless a regional residency host was configured at build time † (#8558) - ✅
timesheets.geofence.rearm-latch-tristate— The geofence re-arm latch sets only when arming actually succeeded; a skip or failure retries † (#8561) - ⏳ Hospital coordinate database syncs every 30 days — not built: no scheduled coordinate refresh job exists; AU coords sourcing now sequenced under #8444 (AIHW MyHospitals API)
- ✅ User can configure workplace locations
- ✅ User preferences for geo-fence triggers — built (
geo_fence_preferences, #3682). The preferences panel is reachable by the doctor as a Geo-fence Preferences accordion in My Profile (remounted in Task 3, #11181 D4: auto-create, push, default shift start, grace period, auto-submission email); it had been unmounted. The earlier "open - on-hold" wording is superseded. - ✅
timesheets.geofence.mobile-writes-audit-trail—backgroundLocationTaskHandlercallsgeoFenceEvent.recordEntryon hospital entry andgeoFenceEvent.logExiton exit, in addition to (not instead of) its existingtimesheets.source='geofence'draft-timesheet write —timesheets.source='geofence'remains the operational trigger signal,geo_fence_eventsis the audit/dwell trail alongside it. Both calls are best-effort/non-blocking: a failure never blocks timesheet creation or update.logExit(new) is a timesheet-free exit-event insert — distinct fromrecordExit, which already creates a draft timesheet internally — so the mobile caller (which owns the timesheet lifecycle via its owntimesheets.updatecall) never gets a duplicate timesheet. † (#9257) - ✅
timesheets.geofence.offline-queue-bounded— The offline timesheet-creation queue (timesheet-offline-queue.ts, reached from every geo-fence ENTER handled while the device is offline) and the geo-fence event queue (geofence-event-queue.ts) are capped atMAX_QUEUE_SIZE=200entries with FIFO eviction of the oldest entry once at capacity, rather than growing without limit. This is a deliberate, narrow divergence frommobile.md's#4893AC ("if the device is offline at geo-exit, the timesheet entry is persisted to device storage and flushed automatically on next network availability — silent drop is not acceptable"): reaching the 200-entry cap requires weeks of continuous offline geo-fence crossings (a device this persistently offline is already in a degraded state the user needs to address directly), and the alternative — unbounded growth — is the defensive fix's own precautionary target. † (#10431) - ✅
timesheets.geofence.verification-result-persisted— Mobile now posts the on-device DERIVED verification result (never the raw GPS fix — #10827's DPIA-4 minimisation, unchanged) alongsiderecordEntry/recordExit/logExit:distanceMeters(required when present, integer metres, measured against the workplace geofence centre with aBalanced-accuracy fix bounded by a 5s timeout, sogeo_fence_events.distance_metersnow populates for mobile-originated rows — previously 44 of 64 exit rows stored NULL because the tRPC wire schema silently stripped theverificationfield before the service (which already persisted it) ever saw it) andaccuracyMeters(optional, the SAME fix's OS-reported horizontal accuracy — no extra position request). The call runs AFTER the pay-affecting timesheet-close/-create write, never before it, since the position fix can take up to 5s and nothing may delay the write a doctor's shift record depends on.withinGeofenceis deliberately NOT sent by mobile: mobile judges against a hardcoded 100m (GEOFENCE_RADIUS_M) while the web Smart GeoTag path judges against the per-workplaceradius_meters(default 200m), so the same boundary crossing could record opposite verdicts depending on which client reported it. Resolved for the common case (#11157), with two residuals stated explicitly rather than silently: rather than leavingwithin_geofenceNULL for the majority (mobile) path,geoFenceEventServicederives it SERVER-SIDE when a caller suppliesdistanceMetersbut no verdict of its own — it resolves the authoritativeworkplace_locations.radius_metersfor the reporting user/hospital (the same valuesmartGeoTag.tsalready judges against) and compares. An explicit verdict from the web path always wins and never triggers the lookup, so web behaviour is unchanged.accuracy_meters(nullable integer, DPO sign-off obtained — same #10827 DPIA-4 posture asdistance_meters) is now persisted from both mobile and the web Smart GeoTag path (GeolocationCoordinates.accuracy), closing the second of #11100's two open acceptance criteria. Residual 1 (review finding):within_geofencestill resolves to NULL whenever no ACTIVEworkplace_locationsmarker exists for the reporting (user, hospital) — mobile arms its OS geofence regions from every assigned hospital with coordinates (getUserAssignedHospitals), independent ofworkplace_locations.isActive, so a doctor who has toggled a workplace's Smart Geo-Tag off, or whose attachment was auto-deactivated by its end-date (#5965), keeps firing mobile entry/exit events that derive no verdict. Residual 2 (trust boundary, unchanged from #11100/#11124): awithin_geofencevalue derived from a mobile-reporteddistanceMetersis still DEVICE-REPORTED, not independently server-verified — it must not be treated as stronger evidence than the diagnostic it always was for any pay-affecting decision (#11120). † † † (#11100, #11124, #11157)
Server-side Monitoring (Ops)
Two scheduled, read-only monitors close the gap reconcileMissingGeofences/monitorGeofencePreferences left: those watch whether geofences are ARMED/CONFIGURED, not whether events are ARRIVING or whether a created timesheet is CORRECT. A user can be perfectly configured and still silently produce nothing, or produce a wrong record nobody corrects — exactly what happened to Matt (#10912, #10925).
- ✅
timesheets.geofence.stream-silence-monitor—monitorGeofenceStreamSilence(scheduler-lambda daily cadence + admin-callablenotifications.monitorGeofenceStreamSilence) flags a user whose geofence event stream has gone silent beyondSILENCE_THRESHOLD_HOURS(72h/3 days) despite an active, geofence-enabled hospital attachment and an established recent history (≥1 event withinESTABLISHED_HISTORY_WINDOW_DAYS, 60 days) — proving they were genuinely using Smart GeoTag, not merely configured for it. Threshold basis: real UATgeo_fence_eventsdata (queried 2026-07-25) shows only one account with genuine continuous usage (userId 17); its confirmed incident gap (2026-07-17T07:18:38Z → 2026-07-22T06:51:28Z, 119.5h) sits only ~6.7h from its largest OTHER internal gap (112.8h) — too close to tune a threshold strictly between them at this sample size. The threshold is deliberately set well below both (72h) so detection fires ~2 days before the user would notice, accepted as a widened net rather than a precise line because the signal is ops/admin-facing only (logger.warn, never a notification to the doctor) — see Q6. Replayed against the real timestamps, the monitor fires (integration test). Known limitation: 3 QA seed accounts with active geofence-enabled attachments but no events since June currently also match and will appear as perpetually silent until they age out of the 60-day window or accumulate a fast-follow exclusion — disclosed, not hidden. † (#10916) - ✅
timesheets.geofence.stuck-open-shift-monitor—monitorStuckOpenGeofenceShifts(same cadence + admin-callablenotifications.monitorStuckOpenGeofenceShifts) flags asource='geofence'timesheet whose duration is belowSTUCK_SHIFT_MAX_PLAUSIBLE_MINUTESonce it is older thanSTUCK_SHIFT_MIN_AGE_MINUTES(a grace buffer) — the second, distinct silent-failure class (#10925): events flow normally, but a created timesheet is left at an implausible placeholder duration (#10915's quoted example: Start 14:13, End 14:14) and never corrected, so monthly hours silently total near zero.STUCK_SHIFT_MAX_PLAUSIBLE_MINUTEStracks the product's owntimesheets.geofence.min-arrival-stayinvariant (MIN_ARRIVAL_DWELL_MS, 5 minutes since #12734; it was 15 before — see that AC above) — a genuinely-confirmed geofence visit cannot be shorter than that under the app's own rules, so any saved geofence-sourced entry under the threshold is provably the placeholder defect, not a real short shift. Verified against live UAT data: all 7 currently-live geofence-sourced entries have real durations of 532-797 minutes (well above the threshold). A standing invariant (defense-in-depth against a regression of #10925's class), not a fix to the mobile ENTER/exit handlers themselves — those are owned by #10925/#10915. #11145 changes what this AC defends against, not the monitor itself. The monitor remains a scheduled, AFTER-THE-FACT sweep — it still runs on its own cadence and still catches a stuck row that slips past the client. But #11145 closed the mobile-side defect this AC was compensating for (the exit handler'sif (dwell)guard silently skippingevaluateDwellOnExit— and therefore the drive-by delete/suppress that would have caught a too-short "arrival" — whenever the JS runtime restarted between ENTER and EXIT, pertimesheets.geofence.min-arrival-stayabove). With dwell-entry state now persisted, the delete/suppress branches run correctly at CREATION TIME across a runtime restart, so the class of implausible-duration row this monitor exists to catch should now be PREVENTED at the source in the case #11145 covers, rather than only detected up to 30+ minutes later by this sweep. The monitor is retained unchanged — it still catches any other path to a stuck row (e.g. a genuinely dropped exit event) — but it is no longer the only backstop for the JS-runtime-restart class specifically. † † (#10916, #10925, #10915, #11145)
Notifications
- ✅ Push notification on geo-fence exit: "Complete your timesheet" †
- ✅ Reminder at end of shift if timesheet incomplete
- ✅
timesheets.batch.submission-notification— submitting a fortnight for approval confirms to the submitting doctor, not only the approver: the submit toast reads "Timesheets submitted for approval to {approver}! Total {H:MM} across {N} entries." and the doctor also receives a bell notification (timesheet_submission_confirmed, a receipt, not an action item) stating the same total, net of meal breaks, with the period. The approver'stimesheet_submittednotification and the doctor's later approved / returned notifications are unchanged. Matt's #11181 stage 6, "notification of Timesheet submission (total) and completion". Whether the approver's notification should also state the total is an open question for Matt (spec-review F8). † (#12932) - ✅ Submission History panel renders a "Resubmitted" chip for batches with
status='resubmitted'— never "Unknown" - ✅ Geo-fence preference check filters workplace locations by both
userIdAND the triggeringhospitalId(matched via hospital name), so multi-workplace users get deterministic notification behaviour - ✅
timesheets.geo-fence.correct-hospital-id—recordExitresolveshospitals.idfrom the mobileworkplaceIdbefore inserting the draft timesheet; if it does not resolve, the audit event is still recorded but no draft timesheet is created (no silent "your workplace" fallback) - ✅
timesheets.geo-fence.multi-hospital-preferences—getGeoFencePreferencesForUseris scoped per(userId, hospitalId): a hospital-specific preference row takes precedence, falling back to the user-wide default (hospital_id IS NULL) row, then hard-coded defaults — giving multi-hospital doctors deterministic behaviour (absorbs) - ✅ Hospital-entry notification arrives as an OS-level push on the device lock screen (not just an in-app toast) — see new "Smart Geotag — entry/exit notification surfaces" section † (#5810)
- ✅
timesheets.geofence.dwell-thresholds— Geo-fence dwell logic: <5 min auto-deletes log;<15 min suppresses entry notification; ≥15 min fires† (#5811). Superseded 2026-08-11: now two tiers, not three. Under 5 min is a pass-by: back-end log only, nothing shown. 5 min or more fires the entry notification and opens the shift. † Fixed (#12734): the middle tier is gone:MIN_DWELL_NOTIFY_MS=MIN_DWELL_DELETE_MS= 5 min, so a stay of 5 min or more notifies and under 5 min is a pass-by. - ✅
timesheets.geotag.exit-deeplink— the exit geo-fence timesheet review notification deep-links the doctor directly to the editable timesheet entry form (/timesheet?id=<id>&edit=1, edit mode) so they can complete it, not the read-only list/home view — applied in both the backend notificationmetadata.routeand the frontenduseNotificationNavigationhandler †. Drift on the native OS push path (spec refresh 2026-10-03, #12722): the in-app bell path meets this AC. The native push is what a doctor actually taps after leaving hospital, and it does not.NotificationContext.tsxroutestimesheet-auto-created/timesheet-exit-reminderto/edit-timesheet/[id], andEditTimesheetScreenrenders the WebView withmode="view". That builds/timesheet?app=1&view=1&id=<id>, which opens the entry read-only and makes the doctor press Edit. Matt reported exactly this on 2026-08-18. Fixed (#12722):EditTimesheetScreennow mounts the WebView withmode="edit", so the native push opens the editable entry (mobile.timesheet.edit-screen-edit-mode). † (#12722) - ⚠️
timesheets.entry.one-form— manual and geotag timesheet entries are completed in one entry form, with the same fields and the same downstream effects (Payroll ID inherited pertimesheets.entry.payroll-id-inherited; a completed entry feeds the heat map per the Entry status lifecycle). There is no separate "old" form behind the geotag notification. Drift: the native push opened a different, read-only presentation (seetimesheets.geotag.exit-deeplink); the read-only mode is fixed by #12722, the remaining one-form claims (payroll ID, heat map) are not re-verified on device and are tracked in #12815 (AC stays ⚠️ until verified on device). #12815 fixed the heat-map half in code: an explicit in-place Save of a geotagdraftnow storescomplete, as a manual add does. † (#12722, #12815) - ✅
timesheets.geotag.derive-live— geo-fence detection derives the hospital name/lat/lon live from the joinedhospitalsrow at match time; a hospital-linkedworkplace_locationsrow is a coordinate-free marker that stores only the per-user Smart Geo TagisActivetoggle, never a copy of the hospital's name/coordinates. A correction tohospitals.latitude/longitudetherefore takes effect for every already-attached doctor immediately, with no re-attach and no stale-copy drift (the #10164/#10168/#10173 class). Arming (ensureGeofenceForHospital) inserts no coordinate; re-activation flipsisActiveonly † (ADR-0005, #10178) - ✅
timesheets.geotag.hospital-link-destination— the Smart Geo Tag CTA links to My Profile → Hospital Linking (/my-profile#hospitals, expands the My Hospitals accordion); completing hospital linking activates Smart Geo Tag automated timesheet creation for that workplace, confirmed to the doctor via a success notification †. Activation includes enabling the per-hospitalgeo_fence_preferencesrow the exit path consults (auto-timesheet + notifications on), so a doctor who never opened settings still gets a draft timesheet on exit — never overriding an explicit user-wide opt-out (#8478). The user-wide opt-out is tri-state (#8642): only a deliberate opt-out (thegeo_fence_timesheet_opt_out_explicitmarker, set when the doctor turns the settings master toggle off) blocks attach-time activation — the incidentalgeo_fence_timesheet_enabled=falsethe settings UI persists when the master toggle merely happens to be off (e.g. to tune the grace period) no longer silently blocks self-added hospitals (the #8642 / #8376 retest bug). Doctors can also self-enable per hospital directly on My Hospitals via a Smart Geo Tag toggle wired to the hospital-scoped preference upsert, so a self-added hospital can be activated even when the user-wide row is off (#8642) - ✅
timesheets.geotag.web-clock-in-out— on the web the geo-fence entry/exit events that drive auto timesheet creation were never fired (only the mobile app posted them), so clock-in/out via geotag was non-functional. A "Smart GeoTag" button on the Timesheets action bar captures the browser location andtimesheets.smartGeoTagclocks the doctor IN (inside an active hospital-linked workplace fence with no open shift) or OUT (outside every fence with an open shift, auto-creating the draft timesheet), reusing the existingrecordEntry/recordExitdedup/grace-period/preference logic; permission-denied/unavailable/timeout/unsupported surface a clear message pointing to the manual End Shift fallback. A shift counts as open only while the latest entry is newer than both the last timesheet end and any later exit event, so an exit that created no timesheet still ends the shift (#12604). Web flow is on-demand (button press), not continuous background polling (#7384) - ✅
timesheets.geotag.auto-submit-destination— geo-fence preferences expose a user-settable auto-submission destination email; the field validates a real address and may be cleared † (#7914) - ✅
timesheets.geotag.auto-submit-fallback— auto-submission proceeds only when a destination is set AND the facility accepts direct submission; otherwise the timecard stays a manual-reviewcompleteentry (settled, but not auto-forwarded — renamed from the historical "draft" wording, #11454), never auto-sent and never silently dropped, and UI copy never over-promises on facilities that cannot receive it † (#7914)
Navigation (Attendance menu)
- ✅
timesheets.attendance.collapsed-default— Attendance is collapsed by default in the nav (no child sub-items); clicking the Attendance item routes directly to History (/attendance/history); the dropdown-expand icon is replaced with aCameraAltIconaction button whoseactionTois/attendance/scan, which mounts the QR scanner page immediately; the "Scan QR code" and "History" child-page sub-menu items are removed †
Timesheet Entry
- ✅ Multiple entries per day (on-call, recall, overtime) ✅
- ✅
timesheets.entry.hours-net-of-meal-break— every duration the doctor sees is net of the meal break: the entry list and its mobile cards, the batch totals, the approver email and approval portal, the signed report and PDF, the submit confirmation, and the Year Overview total. 06:00–10:00 with a 30 minute meal break reads 3:30, with the break kept visible beside it ("3:30 (30m break)" in the list; the Break column elsewhere). Rob's decision, 5 Oct 2026, after the Task 3 recording showed 4:00. Flagged for Matt: this answers the draft question on how breaks count and is Rob's call until Matt confirms. Not changed: Time at Work (time on site, so gross), and the overtime / fatigue thresholds, which keep their own jurisdiction rules (Q1, #12841). † (#12936) - ✅ Manual timesheet creation —
createmutation (api/backend-ppp/src/routers/procedures/timesheets/index.ts→createTimesheet) backs the entry forminstances/ppp/src/forms/TimesheetForm/CreateViewUpdateForm.tsx† - ✅
timesheets.entry.manual-no-geofence— a doctor can create a timesheet entry manually (date, start, end, hospital) without any geo-fence auto-detection or location permission; the form opens from both the Timesheets section and the fortnightly home widget (instances/ppp/src/modules/Development/components/TimesheetWidget.tsx→/timesheet?add=true) † (#7586) - ✅
timesheets.entry.source-discriminator— every entry carries asourcecolumn (manualvsgeofence, defaultmanual); manual entries are visibly marked "Manual" in the list (desktop grid + mobile list) and geo-fence auto-created entries are marked "Auto", but both aggregate identically into working-year totals and widgets; geo-fence inserts setgeofence— both the server-sidegeoFenceEventServicepath and the mobile geo-fence auto-create payload (mobile/ppp/lib/services/location-service.ts→backgroundLocationTaskHandler+ already-inside-zone setup), which previously omittedsourceso auto check-ins wrongly rendered the "Manual" chip (#8600) † (#7586, #8600) - ✅
timesheets.entry.overlap-rejected—createTimesheetrunsassertNoOverlappingTimesheetserver-side, rejecting a new entry whose half-open time range overlaps an existing entry for the same user with aCONFLICT; back-to-back shifts (end == next start) are allowed † (#7586) - ✅
timesheets.entry.payroll-id-inherited— an entry created without an explicit Payroll ID inherits the owning doctor's profilepayrollId, on every create path and not just the web form. Population was previously frontend-only (usePayrollIdAutoPopulation, add mode only), so the three paths that create an entry without that form —geoFenceEventService.recordExit(geo-fence auto-created draft),manualEndShift(End Shift close-out) and the mobile arrival auto-create payload, which omits the field entirely — all stored NULL; no read path fell back to the profile, so the blank propagated to the payroll export, which is where it costs the doctor. Resolution happens at write time, not read time: the payroll ID that applied when the shift happened is stamped onto the row and never recomputed, so a doctor who changes employer does not have historical entries silently re-labelled with a new number. An explicitly supplied value always wins — including one the user deliberately CLEARED (null/''), so the field stays clearable on the form; only an absent field inherits. A whitespace-only profile value is not inherited, and a doctor with no profile payroll ID still gets an entry. Payroll ID is required for full-platform users to complete their profile (Rob's #10594 decision, 2026-07-17; enforced by #12728), but a missing one never blocks a timesheet write. Inheritance is skipped when the row's owner is not the authenticated user, sinceenforceUserScopelets an admin create an entry for another doctor and the admin's own number must never be stamped on it. The rule lives in a dependency-free module (timesheetServices/payrollIdInheritance.ts) so the backend suite and the BDD scenarios execute the same code the services run, matchingexitSettlementRules.ts(#11099) andshiftCloseRules.ts(#10925). † (#11140) - ✅
timesheets.geotag.arrival-placeholder-indicator— a Smart-GeoTag draft created at geo-fence ENTRY carries a documented sentinelendTime - startTimedelta (GEOFENCE_ARRIVAL_PLACEHOLDER_DURATION_MS, 60s), not an arbitrary/undocumented value; the timesheet list (End Time + Total Time columns) and the entry form detect this exact delta viaisGeoFenceArrivalPlaceholderand render "In progress" / "Shift still running" instead of a concrete-but-wrong duration, until a real EXIT event correctsendTimeto the actual elapsed time.timesheets.endTimeis NOT NULL, so the ENTRY handler cannot leave the row genuinely open the way the web Smart GeoTag flow does (processSmartGeoTagcreates nothing until EXIT) — the draft is created at ENTRY specifically becausedwellStateis in-memory only and does not survive a JS-runtime restart across a multi-hour shift, so the DB row'sstartTimeis the durable anchor EXIT relies on † (#10915) - ✅
timesheets.geotag.close-ownership— geo-fence timesheet CLOSURE has one named owner and one durable fallback. The mobile EXIT handler owns the happy path (timesheet-freegeoFenceEvent.logExitfor the audit trail, then its owntimesheets.updateclose);manualEndShiftis the durable fallback for every case that close never lands — a client-side transport failure that never reaches the server (#10917), an EXIT the OS never delivers, or a JS runtime killed mid-shift. The fallback treats a still-open arrival placeholder (detected viaisGeoFenceArrivalPlaceholder) as the ACTIVE shift rather than as evidence one already completed, so the End Shift control is offered — not hidden — exactly when a shift is stuck open; it CLOSES that row in place (real elapsed hours, anchored to the durable rowstartTime, so clustered GPS-jitter entry events cannot truncate a long shift) instead of inserting a duplicate; and where no usable start time exists it writes NOTHING and says so, never rolling a timestamp back to manufacture a placeholder-length or zero-length shift † (#10925) - ✅
timesheets.entry.friendly-save-error— a timesheet create/update failure never surfaces a raw parser/transport error to the doctor (e.g. a technicalSyntaxError-style string);getFriendlyTimesheetSaveErrorpasses through known, already-human-readable backend validation messages (e.g. "End time must be after start time", the overlap-rejected message above) unchanged, and replaces anything unrecognised — including raw technical/transport errors — with one generic, actionable fallback message. The real error is still logged (console.error) for diagnosis; only the snackbar text is sanitised † (#10917) - ✅
timesheets.entry.shift-times-render-without-shared-formatter— the Start Time and End Time columns on the Timesheet list render the entry's real clock times, never the "-" placeholder, for an entry that has both times stored.safeFormat(instances/ppp/src/modules/timesheet-attendance/timesheet/config/helpers.ts) formats viaDateUtils.dateFormatter, which is anexport letpopulated only byDateUtils.initializeDateFormatter(); that initializer is called by the backend (api/backend-core/src/utils/local-context.ts) and by core-utils' own test setup, but by nothing ininstances/ppp— so in the browser it is permanentlyundefined, the call threw "DateUtils.dateFormatter is not a function", and safeFormat's barecatchswallowed that TypeError into a "-". The visible symptom was an entry showing a correct computed Total Time (the Date and Total Time columns use plainnew Date) beside "Start: - End: -" — the same user-facing shape as #10781, reached through the formatter's initialisation rather than its parse path, which is why that earlier fix did not prevent it.safeFormatnow falls back to date-fnsformatwhen the shared formatter was never initialised. Unit tests could not catch this class of bug because their setup callsinitializeDateFormatter, so the formatter exists under test and is missing only in the real application; the regression scenario therefore forces the un-initialised state explicitly rather than relying on ambient test setup † (#11181) - ✅
timesheets.entry.hospital-picker-displays-assigned— the Hospital picker on the timesheet entry form always displays a hospital the doctor is linked to (or the entry's already-saved hospital), resolving it from the unfiltered hospital list rather than the country-filtered one. A geofence auto-created entry whosehospitalIdis correctly set no longer shows a blank Hospital field or "No linked hospitals found" when the hospital'scountryis miscoded — or before the user's profile country has loaded — because the country filter only narrows the choose-a-new-hospital list, never hides an assigned/selected hospital (instances/ppp/src/hooks/useCountryFiltering.ts→allHospitals;instances/ppp/src/forms/TimesheetForm/CreateViewUpdateForm.tsxresolvesassignedHospitals+ the existing-hospital fallback fromallHospitals) † (#10379) - ✅ Fatigue shift detection —
identifyFatigueShifts/ fatigue rules inapi/backend-ppp/src/services/timesheetServices/fatigueShiftUtils.ts;isFatigueShiftflag surfaced on entries (api/backend-ppp/src/services/timesheetServices/index.ts); both the per-entry flag (#8566) and the dashboard aggregate (getFatigueShiftsData, #8531) resolve the rest-gap + shift-cap thresholds per shift from the shift's hospital jurisdiction viaresolveTimesheetThresholds(GB / unknown keep 10.5h rest, no cap; AU rest under 10h, shift over 12.5h), so the entry-list badge and the widget can no longer disagree (detection only — widget enrichment is #7494) † - ✅ Missed lunch / overtime flagging — overtime detection in
api/backend-ppp/src/services/dashboardService/timesheets/index.ts(variationType === 'Overtime'plus daily / weekly / outside-span rules); overtime, fatigue and missed-lunch thresholds all resolve per shift from the shift's hospital jurisdiction viaresolveTimesheetThresholds(GB / DEFAULT keep current behaviour; AU follows Matt's parameters doc — over 10h shift, over 38h week, outside-span, rest under 10h, over 12.5h shift) † (#6425, #8172, #8531) - ✅ PDF download available for timesheet batches in any status (approved, submitted, pending, rejected) — the only exclusion is an empty batch with zero entries
- ✅
timesheets.entry.pay-cycle-prompt— the pay cycle start date (set on Profile) determines the day/time of the fortnightly 6 a.m. submission prompt † (#6418) - ✅
timesheets.entry.default-day-not-null— the timesheet prompt must always have a default day/time (e.g. Monday 6 a.m.); a null/unset prompt value is not permitted † (#6419) - ✅
timesheets.entry.fortnight-grouping— the Current Timesheet Entries list groups entries into fortnight buckets (TimesheetCurrentGroupedList,instances/ppp/src/modules/timesheet-attendance/timesheet/utils/fortnightGrouping.ts) aligned to the user's configured Pay Cycle Start Day (users.payrollCycleStartDay), not a hardcoded Monday-start or calendar month — the same boundaryprocessTimesheetSubmissionReminders/isUserPayCycleDayprompt on. The current fortnight's group is expanded by default and labelled "Current fortnight"; earlier fortnights collapse, matching the collapse convention already used for the Pending/Approved working-year history (timesheets.entry.fortnight-groupingmirrorsTimesheetHistoryGroupedList, #5823). A doctor with unset Pay Cycle Start Day falls back to a Monday-anchored fortnight, matchingpayrollCycleStartDay's existing Monday default (useUserFormLogic.ts) † (#11127)
Entry status lifecycle
timesheets.status (packages-shared/ppp/src/constants/timesheet-status.ts, TIMESHEET_STATUSES) governs one individual timesheet entry, distinct from the batch-level TimesheetBatchStatusEnum used by fortnightly submission (Approver Model, below). This section was not previously documented — added additively per #11454, not correcting a prior claim.
- ✅
timesheets.entry.status-lifecycle— an entry'sstatus(TIMESHEET_STATUSES,packages-shared/ppp/src/constants/timesheet-status.ts) is one ofdraft(Smart-GeoTag ENTRY placeholder or an unfinished manual/geofence entry — seetimesheets.geotag.arrival-placeholder-indicatorabove),complete(the doctor has reviewed/confirmed the entry; renamed fromsaved, #11454),submitted(locked inside a fortnightly batch pending approver action — seetimesheets.entry.batch-submission-locks-editingbelow),approved,rejected, orrequest_info.TIMESHEET_STATUS_TRANSITIONSis the single source of truth for which transitions are valid (isValidTimesheetTransition/validateTimesheetTransition);TIMESHEET_EDITABLE_STATUSESandTIMESHEET_SUBMITTABLE_STATUSESare separately-maintained groupings consulted by UI filtering, so a future status addition must be checked against all three, not just the transitions table (#11454) - ✅
timesheets.entry.draft-vs-complete-not-a-bug-signal—draftvscompleteis a normal, expected entry-lifecycle state, not itself evidence of a defect: a Smart-GeoTag entry is createddraftat geo-fence ENTRY (before the shift is even known to have ended) and only becomes actionable once EXIT settles a realendTime— seetimesheets.geotag.arrival-placeholder-indicator. The historical #10915/#10925 defects were never about thedraftstatus value itself; they were the save-prompt handler (CreateViewUpdateForm.tsx'sonSaveRequestlistener, wired fromuseUnsavedChanges) force-writingstatus: 'saved'on ANY save — including a save that only touched an unrelated field like Comments and never reviewed the placeholder time — silently masking a still-open geofence shift as "complete" without the doctor ever seeing or correcting the placeholder duration. Fixed as of #11454: the listener now only advancesdraft→complete; any other existing status (complete,submitted,approved,rejected,request_info) is left unchanged by that save path, so an unrelated-field save can never regress an entry backward into looking freshly-drafted, nor silently launder a still-open placeholder into "complete" (#10915, #10925, #11454) - ✅
timesheets.entry.batch-submission-locks-editing— once an entry's status issubmitted(i.e. it has been rolled into a fortnightly batch), it drops out ofTIMESHEET_EDITABLE_STATUSES(draft,complete,rejected,request_info) and the entry form/list no longer offer Edit for it — no new code was needed for this:TIMESHEET_EDITABLE_STATUSEShas never includedsubmitted, so the lock was already correct behaviour prior to #11454; this AC exists to make that invariant explicit and spec-traceable rather than only implicit in the constant's contents (#11454)
Approver Model — where the approver is configured
Decision (Rob & Matt, 2026-04-28): the timesheet approver is per user × hospital, never per batch.
Why per user × hospital: one approver (e.g. a Head of Department) covers many doctors. Storing the approver on the batch (one batch = one doctor's timesheet cycle) would either duplicate the same approver across N doctors' batches or let a doctor pick a different approver each cycle — both wrong. Storing it once on user_assigned_hospitals means every batch a doctor submits at that hospital flows to the same approver automatically.
Centralized-with-fallback resolution (built, #10651 — enabler #10650): the default timesheet approver for a doctor now resolves through a centralized hospital_approvers table first, falling back to the legacy per-user columns where no centralized mapping exists — no forced big-bang migration.
Resolution order at batch-creation time (getApproverSnapshotForUserHospital in timesheetBatchHelpers.ts):
- Per-user override wins (admin-set or the doctor's own nomination; an admin-set one outranks the doctor's). If the doctor's
user_assigned_hospitalsrow carries an explicit approver (approverIdorexternalSupervisorEmail), it is used — unchanged from before, and since #12934 the doctor's own nomination also beats the central default. (Non-goal per the parent epic: this issue does not touch the per-user override capability, only where the default comes from.) - Centralized default. Otherwise, the
hospital_approversdefault for the doctor's hospital + department (hospital_approvers.department = users.speciality_id, with a hospital-widedepartment IS NULLfallback; the department-scoped row wins when both exist) is used. - Legacy fallback. Otherwise, the (empty) per-user row is returned unchanged — so a hospital that hasn't been onboarded onto
hospital_approversbehaves exactly as before.
isApproverAuthorizedForHospital mirrors this order: a batch's approver is authorized if it matches the per-user columns or the centralized default.
- ✅
timesheets.approver.user-attaches-approver— the doctor attaches their own timesheet approver to a hospital they are linked to, as part of the setup stage that also covers hospital, payroll number and pay-cycle day. Built (#12802, #12801, #12678, #12821): in My Hospitals each attached hospital has a "Set approver" / "Approver" action, and Submit for Approval, when no approver is set, shows the same nominate form in place of the old dead end and selects the new approver on save. The doctor chooses either a PPP user, found by searching all PPP users with directors (thetimesheetApprover/ Director flag or a "Director" job title) listed first, then consultants, then everyone else, not limited to consultants at the same hospital; or an approver who is not on PPP, by name + email (position optional). A PPP user is stored by id; an off-platform approver as the external slot; both withapprover_source = 'self'. Search results carry no email address. No admin confirmation (Q7, decided 2026-10-03/04). An approver an administrator set (approver_source = 'admin') cannot be replaced by the doctor and shows read-only as "Set by your administrator"; resolution order is per-user admin-set approver > the doctor's own nomination > centralhospital_approversdefault (Matt 3 Oct #12802 AC2: the doctor's choice wins over the central default pre-fill; Rob confirmed 5 Oct, #12934). The approver signs off through the magic link. The My Profile UI for this belongs toprofile-doctor.md§ Payroll & timesheet approver (handed off on #12720). Verified on a local stack by live BDD; not yet on UAT. † † † (#12802) - ✅
timesheets.approver.esignature-identity— approving through the magic link captures the approver's electronic signature identity alongside the drawn signature: work email and payroll number (both required to approve) and an AHPRA registration number (optional, since an approver outside Australia has none). A well-formed AHPRA number is checked against the public register;approver_ahpra_statusrecordsverified,format_only(register unreachable) ornot_provided, and the check never blocks an approval. The fields are validated before the single-use link is spent, stored on the batch (approver_work_email,approver_payroll_number,approver_ahpra_number,approver_ahpra_status) and stamped under the signature on the signed PDF. Requesting more information needs none of them. † (#12821) - ✅
timesheets.approver.post-approval-routing— after the approver approves: if the hospital has a linked hospital admin on PPP, the approved batch goes on to them in-platform (bell + email via the admin-officer forward) and no payroll email is sent; otherwise the approver chooses a destination email (e.g. payroll) on the approval form and the signed PDF is emailed there. The portal knows which route applies before the approver acts (hospitalAdminLinked); the outcome is stored on the batch (routed_to=hospital_admin|email,payroll_destination_email,approved_report_key). The send stays one-shot. The doctor's own Payroll Admin Email is only a fallback when the approver gives none. † (#12802, #12821) - ✅
timesheets.approver.verified-tick— a "verified" blue tick shows beside an approver (My Hospitals row, Submit picker) when the hospital has a PPP hospital admin who has linked them: the admin set the approver, the approver is in the admin's central hospital-approvers list, or the approver is a hospital admin of that hospital. It is a signal only and never gates self-election, submission or approval; a hospital with no PPP admin shows none. † (#12821)
Second approver — primary + fallback surrogate (built, #10632)
A doctor may have up to two approvers per hospital: a primary (line manager) and a fallback/surrogate (e.g. an associate director) who can act when the primary is unavailable. Either approver is an equally-valid signer.
Data model — stored symmetrically on BOTH layers (Rob, 2026-07-22), mirroring the single-approver resolution chain so the per-user override beats the central default for the surrogate exactly as it does for the primary:
- Central default (
hospital_approvers, admin-CRM-maintained):surrogate_approver_id(internal PPP user) orsurrogate_approver_name+surrogate_approver_email+surrogate_approver_position(off-platform). - Per-user override (
user_assigned_hospitals):surrogate_approver_id+surrogate_approver_typeorsurrogate_external_supervisor_name+_email+_position.
Semantics (Matt delegated to Rob, 2026-07-17/22; best-practice Workamajig/4castplus/NHS backs manual primary+backup with no auto-escalation):
- Manual routing, no auto-escalation. At submission the doctor picks the primary OR the surrogate; there is no timeout/escalation scheduler. The surrogate is surfaced as a second selectable option in the submit approver picker (
getHospitalsAndApproversByUserIdreturns it labelled "(Fallback approver)"). - Notify the selected approver only. The batch stores the single selected
approverEmail; only that address receives the magic-link approval email. - Either approver signs.
isApproverAuthorizedForHospitalaccepts the per-user primary/surrogate or the centralized primary/surrogate — any of the four is a valid signer. Resolution surfaces both viagetApproverSnapshotForUserHospital(primary) andgetSurrogateApproverSnapshotForUserHospital(surrogate, per-user-override-beats-central). - Admin CRM sets the hospital's default surrogate on the central
hospital_approversadmin screen (per Matt's "mapping should live in the admin CRM").
Other current implementation (built):
user_assigned_hospitals.approverType—'ppp_user'or'external'.users.timesheet_approverboolean flags users eligible to be picked as internal approvers.timesheetBatchEmail.tsresolves the approver viagetApproverNameByUserHospitalAndEmail(userId, hospitalId, approverEmail)at email-send time.- Magic-link approval flow for off-platform approvers:
generateTimesheetBatchApprovalToken(HMAC-SHA256, 14-day TTL) →/approve-timesheets/{token}route →ApproveTimesheets.tsxpage →tokenConsumedAtenforces single-use.
Deferred cleanup (tracked separately, #5544):
timesheetBatches.approverIdandtimesheetBatches.approverEmailexist as writable columns. They should be derived-only (snapshot at batch-creation time, never user-editable post-create) so a doctor can't override the per-hospital approver. Today's API/UI doesn't expose the override path, but the schema does — needs a guard.- ✅ Resolved (#10651). When the same off-platform approver covers many doctors at one hospital, their email was denormalised across N
user_assigned_hospitalsrows (updating it = N writes). Thehospital_approverstable (department-level default) now holds that default in one place, and service resolution reads it first with a fallback to the per-user columns — collapsing the N writes to 1. Backfill of existing per-user rows intohospital_approversis tracked separately (#10653).
Approver Workflow
- ✅ Approver role is restricted to consultants (department director / deputy director) — non-consultants cannot self-declare. Superseded for the doctor's own nomination (Matt 2026-10-03, #12802): a doctor may name any PPP user or an off-platform person; this restriction now only governs who may flag themselves a Timesheet Approver/Director in their profile. †
- ✅ Approver candidates surfaced from the consultant pool of the (hospital, specialty) department (#4840)
- ✅ Consultant declaring approver intent enters
approverPending(status='pending' onusers.timesheet_approver_status) → PPP super admin approves for demo phase via/admin/timesheet-approvers; eventually hospital admin owns this. No longer a gate on being chosen (Matt 2026-10-04, #12821): a flagged approver is discoverable by every doctor without super-admin approval; an admin link only adds the verified tick. † (closed ✅, #4840) - ✅ Audit-log entry (
audit_trailactiontimesheet_approver_approved/timesheet_approver_rejected) for every approver approval / rejection - ✅ Trainee's submitted timesheet auto-appears as a to-do for every approved approver in their department's pool †
- ✅ Non-platform approver receives email with review link
- ✅ External approver (off-platform) authenticates via the magic link in the approval email (this IS the isolation-code mechanism defined in auth.md — the link carries a time-limited token that substitutes for username/password; no separate code-entry step required) † (#4827)
- ✅
timesheets.approver.typed-name-identity— the off-platform approver types their full name beside the signature on every action (required; pre-filled from the name that email last typed, else the name the doctor entered; editable). Each batch stores a per-approval snapshot — typed name, the approver email the link went to, time, IP address and browser — plus the doctor-entered approver name and position copied at submission, the typed name is remembered per lower-cased email, and anaudit_trailrow is written withactor_type = 'external'. Since the #12529 follow-up (migration 0267) the approver also types and confirms their email and position on every action (Request More Information included), stored beside the name; the older "name-only" build is superseded. The issue's open question on whether Matt wants email and position confirmed at all is still unanswered (spec-review F6). † (#12529) ‡ - ✅
timesheets.batch.returned-batch-opens— the doctor's "more information requested" notification links to/timesheet?tab=1&batchId=<batch code>; the Timesheet page switches to Pending Approval, opens that batch and shows the approver's reason and the returned entries, with the Edit entries action (the same detail opens from the eye icon in Submission History). It does not open a blank single-entry dialog (#12891, #12930). † - ✅
timesheets.batch.edit-then-resubmit— Matt: a returned batch is edited first and only then resubmitted. Edit entries reopens the returned batch (statusreopened, owner only) so its entries are editable again; no new batch exists until the doctor chooses Resubmit afterwards, which creates the new linked batch, marks the earlier oneresubmittedand emails the approver. Resubmitting a batch that was not reopened is refused. A returned batch that has not been reopened stays locked to edits (#4913). † (#12931) - ✅
timesheets.approver.flag-pending-state— in My Profile, "Are you a Timesheet Approver/Director?" answered Yes is stored as a pending request until a PPP super admin verifies it. The field then reads "Yes - pending verification" (with a note) after a reload instead of reverting visually to No; the stored approver flag stays false until verified (#12937). - ✅
timesheets.approver.no-full-authn-ui— approvers who are not PPP/CPD users approve via the magic link, not the full authentication UI; no PPP login and no account creation is required, to remove onboarding roadblocks for non-PPP approvers † (delivered by the token-scoped public proceduresprocessBatchByToken/generateUploadUrlByToken/emailApprovedToPayrollByToken, #12442: each re-verifies the HMAC magic-link token server-side and only accepts batches that token covers — the same approver match asgetPendingBatchesByToken. Until #12442 this AC was marked ✅ but was NOT met: the list rendered, yet every action (signature upload, submit, payroll email) went through session-only procedures (processBatch,storage.generateUploadUrl,emailApprovedToPayroll) and the hidden payroll-PDF view called the protectedhospital.list, so a session-less approver was redirected to/login. The public page now makes zero session-protected calls — pinned by the@regression @issue-12442BDD module-graph check over every moduleApproveTimesheets.tsxrenders. Token actions are also scope-frozen (a link covers its own batch plus batches submitted at or before it was issued), refuse self-approval, and the payroll send is one-shot (payroll_sent_at). The #7327 / PR #7516 scoped-session flow is unwired scaffolding and is not this path — see Closed Question Q4) - ✅
timesheets.approver.session-persists— once an approver opens the magic link, the authenticated state effectively persists for that browser session so subsequent approval actions in the same session do not re-prompt for authentication † (delivered by the HMAC token flow:getPendingBatchesByToken#5808 surfaces every pending batch on one screen, and since #12442 every action on that screen is authorised by the same token (processBatchByToken/generateUploadUrlByToken/emailApprovedToPayrollByToken), so the approver never re-authenticates per batch. Before #12442 this was marked ✅ while the actions still required a PPP session. The generic isolation-code flow #7327 / PR #7516 scopes its cookie per action by design, but it is unwired scaffolding for future WBA / 360 reuse and is not the live timesheet path — see Closed Question Q4) - ✅ Magic-link approval portal lists all pending authorisations for the approver, not only the batch the link was generated against † (
getPendingBatchesByToken#5808 returns every pending batch for the approver, rendered byApproveTimesheets.tsx. Since #12442 a link lists — and can act on — its own batch plus the approver's batches submitted at or before the link was issued; a later submission arrives with its own, newer link, which lists everything pending up to that point. Recorded as an engineering security scope (old/forwarded links cannot act on later work), not a requirement change) - ✅ Approval token TTL = 14 days (uplift from current 7d in
generateTimesheetBatchApprovalToken; auth.md Q1 resolved here); email body states validity; expired-link landing page can re-issue (#5809) - ✅ In-platform approver sees action item
- ⚠️ Approved timesheet forwarded to admin officer — built and covered by tests (the payroll email carries the signed PDF as an attachment, asserted on the mailer arguments, #12935), but delivery to a real admin or payroll inbox has never been watched (stage 8). The tick is withheld until one UAT run with a real inbox is seen. See "Live lifecycle audit fixes" below.
- ✅ Fortnightly submission prompt: doctor submits every two weeks based on pay cycle; submission routes to approver for sign-off; once approved, batch is forwarded to the elected destination (hospital admin or designated payroll email) †
- ✅
timesheets.lite-web-form— when the timesheet approver is an off-platform external person, the approval email magic link routes to a lightweight hosted web form (no PPP login required) that: (a) lists all pending timesheets for that approver, (b) allows approve/reject with optional comment, (c) requires a drawn signature (canvas pad, web + mobile) as formal evidence of approval. The drawn signature SVG is stored against the batch approval record and is included in the forwarded payroll email †. (23 Apr 2026) - ✅
timesheets.batch.friendly-submit-error— a submit-for-approval or resubmit-batch failure never surfaces a raw parser/transport error, and never surfaces a backend message that interpolates an identifier (approver/caller email address,userId,hospitalId,batchId).getFriendlyTimesheetBatchErroris a deny-by-default rule table, separate from the create/update allowlist (timesheets.entry.friendly-save-error): identifier-free batch guards ("Self-approval is not permitted…", "Approver is not authorized for the selected hospital", the overlapping-submitted-batch guard) pass through verbatim; actionable-but-identifier-bearing ones (theuser_assigned_hospitals-citing "set your hospital's approver first" guard, the no-timesheets-in-range guard, the missing-approver-email guard, therequest_inforesubmit guard) are replaced by an equivalent identifier-free rewrite that preserves the actionable wording; everything else — includingsendTimesheetBatchApprovalEmail's "User not found for email<email>…", whose call site insubmitTimesheetsForApprovalis deliberately un-wrapped so it propagates to the client — collapses to one generic fallback. Sanitisation is applied in the mutation'sonErrorcallback as well as the handlercatch, becauseonErrorfires first. This keeps the #10627/#10622 approver guard reaching the doctor while closing the #10917-class leak on these paths † (#10953)
Department & Hospital Hierarchy
The data model used by approver workflows, hospital admin governance, and reporting:
Hospital Health Service
└── Hospital
└── Department (= specialty — nationally consistent across AU; largely consistent in UK)
└── Doctors (incl. consultants who form the approver pool)- Specialty list is canonical master data — see admin.md for the hospital admin role design
- Hospital admin role is per (hospital, specialty), not per hospital
- Source: Rob & Matt call 13 Apr 2026 (~00:34:20–00:43:53)
Live lifecycle audit fixes (Async Task 3, #11181 — Oct 2026)
Found and fixed during a full live walk of the 8-stage lifecycle (profile setup → geotag activate/deactivate → manual completion → dashboard → fortnight of entries → submission → approval → payroll forward):
- ✅
timesheets.approver.no-self-service-misdirect— the "no approver configured" warning on Submit for Approval no longer tells the doctor they can add an approver themselves in My Profile under My Hospitals (that screen has no approver field — only an admin can set one via/users); it now correctly directs them to ask their hospital/practice administrator (#12677) - ✅ Smart GeoTag and End Shift no longer visually overlap on the narrow-browser (non-app) Timesheet header during an open shift — the #11231 overlap fix had only been applied to the native-WebView header, not the plain mobile browser header (#12679)
- ✅ Submit for Approval's default Start/End Date now matches the pay-cycle-anchored "Current fortnight" the entries list above it labels and groups by (previously a naive "today + 13 days" window that could silently omit real entries and include not-yet-worked days) (#12682)
- ✅ The doctor's "your timesheet was approved / returned for more info" notification correctly names the approver — the lookup used to 403 on every real approval (resolving the wrong user's scope) and silently produced a subject-less sentence (#12685)
- Confirmed NOT reproducible: duplicate geo-fence draft timesheets from rapid/duplicate exit events (the #11101 concern) — verified live via both the web Smart GeoTag path and the mobile
geoFenceEvent.recordExitdedup path; both produce exactly one draft per real visit - ✅ Dashboard Timesheet widget deep links:
+ Entryopens/timesheet?new=1(the add-entry dialog) andSubmitopens/timesheet?submit=current(Submit for Approval); each param is consumed once acted on (#11181 D2). - ✅ Each fortnight group header on the Current tab shows its status and a Submit button that opens Submit for Approval preset to that fortnight (Rob 11 Aug, #11181 D3).
- ✅ The geo-fence preferences panel is mounted as a Geo-fence Preferences accordion in My Profile (it had been unmounted, #11181 D4); see
timesheets.geotag.auto-submit-destination. - ✅ Smart-GeoTag times are minute-precise: a draft saved 08:00 to 17:00 stores no seconds, so totals read 9:00, never 8:59 (#11181 D9).
- ✅ The Submit for Approval picker offers the hospital's central default approver and its "(Fallback approver)" surrogate when the doctor has none of their own (#11181 D10); with a doctor-nominated approver the doctor's own wins (see precedence above, #12934).
- ✅ The Default Working-Calendar Start is stored and read as a plain calendar date regardless of browser timezone, so choosing April saves 1 April, not 31 March (#12890). Rows already saved a day early are not repaired by this fix (follow-up).
- ✅ The My Profile Payroll Admin Email is available to every doctor, not only consultant approvers, and is prompted rather than required (#12892, #12924).
- ✅ The My Hospitals desktop table has an Added column (the date the hospital was added to the profile); the 375px card already showed it (#12938).
- ✅ The dashboard active-shift banner (
dashboard.active-shift-indicator) is not shown to admin-only users (!isAdmin): it is a doctor's own shift state. - ✅ The Timesheets Submitted tile labels a returned batch "Information requested", never the raw status
request_info(#12933). - Not built here and still open: the overtime rule for Roster-variation shifts needs Matt's decision (#12841); native OS push, lock-screen copy and background geofence entry/exit are mobile-only and cannot be shown in a browser recording.
- Notification copy: the shipped mobile pushes read "Entered {Hospital}", "Leaving work" and "Complete your PPP time sheet entry." (
geofence-config.ts), not the 17 Apr / 6 May wording above ("You have entered {Hospital}" / "You have exited {Hospital}. Complete your timesheet entry."). Which wording is wanted is a copy decision for Matt (spec-review E1); the shipped wording stands until he says. - Approver Workflow note: "restricted to consultants" below governs only who may flag themselves a Timesheet Approver/Director in their profile (super-admin verified); the doctor's own nomination of an approver is not restricted to consultants (#12802).
- Not yet verified: the forward of the approved, signed PDF to the admin or payroll inbox (stage 8).
Approved timesheet forwarded to admin officeris marked ✅, but the audit environment blocked watching the email arrive in a real inbox. This is a gap in verification, not a change to the requirement. Matt's newest statement (2026-07-14) still matches the AC: "whether it goes straight to payroll or goes to their admin person um, as a PD as a signed PDF". Needs one end-to-end UAT check with a real inbox before the Task 3 recording. †
Spec refresh — dated requirement ledger (2026-10-03)
The newest dated statement from Matt wins. The statements below are the ones this refresh found newer than the 6 May 2026 brief sections above, or ones that change how an AC reads:
| Date | Source | Matt said (verbatim excerpt) | Effect on this spec |
|---|---|---|---|
| 2026-05-06 | Timesheet Notion brief (last edited that day) | "For the lite version not part of a hospital then the user can configure the email address for the timesheet to be sent to…" | This is about where the approved timesheet goes, not the approver. It CONFIRMS timesheets.geotag.auto-submit-destination (#7914, built) |
| 2026-07-08 | transcript 2026-07-08 | "anytime you leave … the hospital it would trigger an end of a … time sheet entry but you can have multiple time sheet entries per day" | CONFIRMS multiple entries per day + timesheets.geofence.shift-session-grace (the later 2026-07-11 #10422 spam report set the grace window) |
| 2026-07-14 | transcript 2026-07-14 (~00:31:54) | "who I would submit in work and pay … That's fallen off"; "correct" (doctor can add the approver's email) | Approver attach, Q7 |
| 2026-07-14 | transcript 2026-07-14 (~00:33:05) | "my line manager … sometimes the associate director would surrogate in … you might potentially have two" | CONFIRMS second approver (#10632, built) |
| 2026-07-27 | #11101 comment | "Indicative display on PPP Dashboard that geotag time sheet is active"; "Time sheet entries could be grouped by fortnight" | Dashboard banner is owned by dashboard.active-shift-indicator; fortnight grouping built (#11127) |
| 2026-07-28 | WhatsApp, quoted in #11139 | "Once a timesheet entry in completed in should be complete and not draft … once submitted … it can't be edited … Heat map should appear once completed." | CONFIRMS Entry status lifecycle (#11454/#11444) |
| 2026-07-29 | #11181 issue body | "User attaching hospital, payroll number, payroll approver and Pay cycle day" | Newest word on approver attach → timesheets.approver.user-attaches-approver (✅ built, Q7 answered 2026-10-04) |
| 2026-08-11 | WhatsApp 2026-08-11 14:39 (answers on #11128) | "2. show status and let you end shift 3. … reduce geotag timeframe within radius to 5 mins. If less than 5 minutes it would be clocked as a pass by (in our back end log) but not displayed to user" | Item 2 CONFIRMS dashboard.active-shift-indicator (End Shift action). Item 3 SUPERSEDES the 15-min dwell (2026-05-06) → timesheets.geofence.min-arrival-stay + timesheets.geofence.dwell-thresholds marked ⚠️ drift (#12734) |
| 2026-08-18 | transcript 2026-08-18 (~00:27) | "when you click the notification it goes into the old form which is not … editable by clicking … For for all of them needs to be one." | Drift on the native push path → timesheets.geotag.exit-deeplink ⚠️, timesheets.entry.one-form ⚠️ (#12722) |
| 2026-09-24 | #12439 issue body | "is the leaving work notification accidentally set as an arriving to work notification" | Open feedback against the entry/exit notification copy; tracked on #12439 (bug), no AC change |
WhatsApp top-up (2026-10-03). This pass checked the Rob–Matt WhatsApp chat (30 Jun–28 Sep 2026) against the conclusions above. The 2026-08-11 row is the only new requirement it found. Everything else Matt said there is either already in this spec or is a bug report that is already tracked:
- Running-shift indicator and End Shift (07-08, 07-10). Already built (#10380, #11128).
- Duplicate entered/leaving notifications (07-09, 07-11). Tracked as #10234, #10387 and #10422.
- Payroll ID missing from geotag entries (07-28). See
timesheets.entry.payroll-id-inherited(#11140). - Entry state and heat map (07-28). See the Entry status lifecycle (#11139).
- Geotag needing re-enabling after an app update (07-22, 08-07). Owned by
mobile.md(mobile.geofence.update-rearm). - Auto-geotag not firing (07-20, 09-02 Winchester). Live failure reports with no new requirement.
WhatsApp has nothing about the timesheet approver (Q7 / #12678 unchanged), the native-push read-only form (#12722 rests on the 2026-08-18 transcript), payroll PDF forwarding, or #12439.
Two widgets, two denominators — not a contradiction. Matt's PPP Dashboard Notion brief (last edited 2026-04-29) says the dashboard Timesheet widget's "denominator [is] to increase as user is detected in the workplace by Smart GeoTag". That widget is the fortnight widget, and dashboard.md § Widget — Timesheet owns it. The Timesheet Notion brief, edited later (2026-05-06), says the Timesheets Submitted widget's "Denominator increases every time a fortnight ticks over". That is the widget timesheets.widget.timesheets-submitted covers. Each statement is about a different widget, so neither replaces the other, and the AC below stays as written.
Dashboard
- ✅ Total hours widget updates immediately when timesheet submitted — not deferred (on-hold)
Widgets — 28 Apr brief sweep (engineering-led, 5 May)
Resolves #5566. Widget set, copy, and click-through behaviour locked below; thresholds (Q1) remain Matt-blocked.
- ✅
timesheets.widget.fortnightly-home— Timesheet widget on the home screen shows entries completed for the current fortnight (defaulting to 10 entries) and includes a Submit button so the doctor can submit directly from the home screen † (#6421) - 🟡
timesheets.widget.time-at-work— auto-selects current month shipped (#6422); hover tooltip on each day cell shows total hours worked + date. Colour scheme bands TBD (blocked on Q1) †. (#6422) - ✅
timesheets.widget.timesheets-submitted— renamed from "Timesheets Completed". Counter starts at start of working year. The working-year anchor is now resolved per hospital — the earliestuser_assigned_hospitals.start_date(My Hospitals), falling back to the user-level Default Working-Calendar Start, then 1 Feb (AU) (#7950). The same anchor resolution intimesheet/utils/workingYear.ts(now withworkingYearDateRange) also sets the Retrospective page's default working year (#12771). Denominator increments every fortnight tick-over; numerator increments on submission †. (#6423) - ✅
timesheets.widget.overtime-shifts— shows total shifts AND total hours for the working year. Click → month-by-month breakdown †. (#6424) - 🟡
timesheets.widget.missed-lunch— percentage with hover detail (numerator + denominator) shipped (#6425); total hours for the working year + click → month-by-month breakdown still pending (tracked as follow-on backend work) †. (#6425) - ✅
timesheets.widget.missed-lunch-jurisdiction— each shift's missed-lunch rule is resolved from its hospital jurisdiction: UK >6h / 20-min break (Working Time Regs), AU >5h / 30-min break (Award meal-break rule, confirmed by Matt on #8169 — supersedes the interim #8172 over-3h / 20-min placeholder) †. (#8172, #8169) - ✅
timesheets.overtime.au-shift-over-10h— at an AU hospital a shift over 10h flags overtime †. (#8531) - ✅
timesheets.overtime.au-week-over-38h— at an AU hospital a week over 38h flags overtime †. (#8531) - ✅
timesheets.overtime.au-outside-span— AU work outside Mon–Fri 06:00–18:00 flags overtime, hospital timezone †. (#8531) - ✅
timesheets.overtime.au-outside-span-null-tz— span rule skipped, logged, never UTC, when hospital timezone unknown †. (#8569) - ✅
timesheets.fatigue.au-rest-under-10h— at an AU hospital rest under 10h flags fatigue †. (#8531) - ✅
timesheets.fatigue.au-shift-over-12-5h— at an AU hospital a shift over 12.5h flags fatigue †. (#8531) - ✅
timesheets.thresholds.gb-unchanged— GB and unknown jurisdictions keep 8h/40h/10.5h-rest, no shift cap †. (#8531) - ✅
timesheets.fatigue.entry-flag-jurisdiction— the per-entryisFatigueShiftbadge resolves its rule from the shift's hospital jurisdiction, like the dashboard †. (#8566) - ✅
timesheets.fatigue.entry-flag-gb-unchanged— for GB / unknown-jurisdiction entries the badge keeps the shipped 10.5h-rest, no shift-cap behaviour †. (#8566) - ✅
timesheets.widget.fatigue-shifts— percentage with hover detail (preserved); total fatigue hours for the working year. Click → month-by-month breakdown (each row: month fatigue-shift count + hours). Mirrors the shipped Overtime widget shape (#6424). (#7494) - ✅
timesheets.widget.fatigue-rest-caption— the fatigue widget's "rest between consecutive shifts" caption is rendered from the backend-resolved rest-gap threshold (fatigueRestHoursin thegetFatigueShiftsDatapayload), not a hardcoded frontend constant. Detection became per-shift jurisdiction in #8531, but the caption is a single user-level summary: the payload resolvesfatigueRestHoursonce at user level via the sameresolveTimesheetThresholdsresolver (default jurisdiction), so the figure can never re-drift from a constant. Per-shift variance across mixed UK/AU shifts is handled by the per-shift tooltips/detection (#8531); the caption follows the user's primary jurisdiction. Until the figure has loaded the number is omitted rather than flashing a wrong one †. (#8570) - ✅
timesheets.widget.recall-hours— NEW widget. Delineates physical recall vs digital recall as separate sub-totals. Total hours for working year. Click → month-by-month breakdown. No schema change: recall kind is stored intimesheets.variation_typeandTIMESHEET_VARIATION_TYPESalready carries bothRecall(physical) andDigital Recall(#7495). - ✅
timesheets.widget.year-overview— NEW physical/visual representation of total working hours, broken down month-by-month for the working year. Confirmed Matt call 2026-05-06 (#5812). - ✅ All widget figures computed from current entries, not last approved fortnight cycle. Confirmed Matt call 2026-05-06 † (#5813).
- ✅
timesheets.footer.add-entry-button— "Add timesheet entry" button rendered next to the existing "Submit timesheet" button in the page footer † (#5822). - ✅
timesheets.footer.history-grouped-by-year— Approved + Pending Timesheets sections group entries per working year (collapsible groups, current year expanded by default) † (#5823, #6426). - ✅
timesheets.header.submit-button— "Submit timesheet" + "Add timesheet entry" pair mirrored at the top of the page † (#5822). - ✅
timesheets.header.mobile-submit-for-approval— the mobile WebView header exposes Submit for Approval (alongside Smart GeoTag + Add Entry). #9885 removed the native floating Add button and deferred Submit for Approval to "the native shell", but the native shell never wired up an equivalent control — so doctors on mobile could not submit a fortnight for approval at all. The action bar now renders Submit for Approval in theisMobileAppheader branch, opening the same Submit-for-Approval dialog as the desktop/web control; the footer stays hidden in the WebView so the action is not duplicated † (#9880). - ✅
timesheets.mobile.time-at-work-responsive-grid— the Time at Work month heatmap shows all seven weekday columns (Mon–Sun) on narrow devices without any column being clipped off-screen. The grid previously used fixed 48px column tracks and 44px square cells, so inside the native WebView shell on an iPhone SE (~360px viewport, ~260px card content box) the 336px-wide week overflowed its container and pushed the Monday column off the left edge. The columns are now responsive (repeat(7, minmax(0, 1fr))) withaspectRatio: 1/1square cells capped at the 44px desktop size, so the seven days shrink to fit ≤375px while the desktop dashboard is unchanged † (#10090). - ✅
timesheets.header.mobile-actions-single-row— the mobile WebView header's three actions (Smart GeoTag, Submit for Approval, + Add Entry) render on one row, never wrapping "+ Add Timesheet Entry" onto its own right-aligned second row. GeoTag and the (active-shift-only) End Shift button keep their intrinsic width; Submit / Add Entry share the remaining row width evenly and may wrap their own label onto a second text line at the narrowest supported width rather than the row wrapping — no font size or 44px touch-target floor is reduced, and no new button variant is introduced (design-system.md). "+ Add Timesheet Entry" is shortened to "+ Add Entry" in this header only. Scope narrowed by #11231: the one-row guarantee applies when the header carries three actions (no shift running). With a shift running the header carries a fourth (End Shift, #10380) and the entry pair wraps as a unit — seetimesheets.header.mobile-actions-four-legiblebelow. † ‡ (#10923, #11231). - ✅
timesheets.header.mobile-actions-four-legible— while a shift is running, the mobile WebView header's four actions (Smart GeoTag, End Shift, Submit for Approval, + Add Entry) each stay fully legible, individually clickable and non-overlapping at the narrowest supported phone width. #10380 added End Shift to the row #10923 had pinned as non-wrapping for three actions; Smart GeoTag and End Shift are both intrinsic-width with a start icon, so the two flexible siblings were crushed to ~25px each — rendering "Submit / for / Approv…" and "+ / Add / Entry" one word per line with visibly overlapping outlines (Matt, 31 Jul). The row is now a two-tier layout: the shift controls form one non-shrinking group and the entry actions another, each flexing as a unit with a minimum legible width, so the entry pair wraps onto a second row together instead of every button being squeezed. The three-action case still resolves to a single row, and no font size, button variant or the 44px touch-target floor (#3109) is changed (design-system.md). † ‡ (#11231). - Note (#10920): the native Timesheet screen (mobile/ppp) now shows a passive "location inactive" banner when Smart-GeoTag authorisation is insufficient — the follow-up safety net to
timesheets.header.mobile-submit-for-approval's sibling launch prompt (mobile.geofence.reauthorization-after-update, #10913). Since it lives entirely undermobile/ppp/**, the authoritative AC ismobile.geofence.location-inactive-bannerinmobile.md— this note exists only so a reader of the Timesheet spec doesn't miss it.
Status
| Sub-feature | Status | Notes |
|---|---|---|
| Manual timesheet entry | ✅ Built | Works |
| Multiple entries per day | ✅ Built | |
| Fatigue / overtime detection | ✅ Built | Screenshots confirm |
| Geo-fence mobile detection | ✅ Built | |
| Workplace location config | ✅ Built | |
| Geo-fence exit notification | ✅ Built | |
| Backend geo-fence event handling | ✅ Built | #3674 closed |
| Geo-fence user preferences | ✅ Built | #3682 closed — geo_fence_preferences table + geoFencePreferences procedures shipped |
| End-of-shift reminder | ✅ Built | #3683 closed |
| Email approver for non-platform | ✅ Built | |
| In-platform approver action item | ✅ Built | #3618 closed |
| Forward to admin officer | ✅ Built | |
| Fortnightly submission prompt | ✅ Built | #3617 closed |
| Dashboard total hours deferred | ✅ Fixed | #3951 closed |
| Hospital DB sync (backend) | ❌ Not built — AC over-claims | No scheduled coordinate refresh job exists; AU coords sourcing sequenced under #8444 (AIHW MyHospitals API) |
| Web Smart GeoTag clock-in/out | ✅ Built | #7384 |
| Manual end-of-shift fallback | ✅ Built | #6785 |
| Geofence arming on hospital attach | ✅ Built | #8410/PR #8439 (self-serve); admin bulk path open #8440 |
| iPhone geofence end-to-end | ⚠️ Bug | #8376 retest failed 2026-06-10, under investigation |
| Native push → editable entry form | ⚠️ Drift | Push opens view=1 (read-only), not edit=1; one form for manual + geotag (Matt 2026-08-18) — #12722 |
| Doctor attaches own approver | ✅ Built | PPP-user search (directors first) or email; verified tick; e-signature; routing — #12802, #12821 (local BDD) |
| Returned batch: reason, entries, edit then resubmit | ✅ Built | #12930, #12931 (unit + source-level BDD; live flow needs a UAT run) |
| Payroll/admin PDF forward | ✅ Built, ⚠️ not verified live | Audit environment blocked watching the email arrive in an inbox — needs a UAT inbox check |
Open issues on label:feature:timesheets — issue data unavailable at build time.Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.
Change Log
| Date | Change | PR/Issue | Reason |
|---|---|---|---|
| 2026-10-05 | The Payroll Admin Email is prompted, not required. In the Submit-for-approval dialog, when the chosen hospital has no linked hospital admin and the doctor profile Payroll Admin Email is empty, a non-blocking inline notice says the payroll copy will not be sent and links to My Profile (Work & Pay). Submission is never blocked. Recipient precedence is unchanged: linked hospital admin, then approver-chosen email, then the profile fallback. | #0, #12924, #11181, #12892 | Rob decision 5 Oct 2026, answering the open question in the #12892 changelog fragment (#12924, #11181). |
| 2026-10-05 | Task 3 final pass. Approver precedence is now admin-set > the doctor''s own nomination > central hospital default (#12934). Hours are shown net of the meal break (#12936, flagged for Matt). A returned batch opens from its notification with the approver''s reason and entries, and is edited (reopened) before it is resubmitted (#12930, #12931). The submit toast and a doctor notification state the fortnight total (#12932). The Timesheets Submitted tile reads "Information requested" (#12933). The approver flag shows "Yes - pending verification" (#12937). A geotag draft opened from a deep link is saved as complete (#12815). The payroll email''s signed PDF attachment is asserted by a test (#12935). Year Overview axis and the desktop My Hospitals Added column fixed (#12938). Spec drift items from the 5 Oct review corrected (#12939). | #0, #11181, #12815, #12891, #12930, #12931, #12932, #12933, #12934, #12935, #12936, #12937, #12938, #12939 | Rob 5 Oct 2026 Task 3 spec review and take-2 recording review. Open for Matt: overtime for Roster shifts (#12841), net-of-break confirmation, approver notification total, entry/exit notification wording, bell delivery of the submit reminder. |
| 2026-10-05 | Task 3 fixes after the 5 Oct live audit. The dashboard Timesheet widget deep links now work: ?new=1 opens the add-entry dialog and ?submit=current opens the submit-for-approval dialog. Each fortnight group header on the Current list shows a status (Draft / Rejected / Needs info / Submitted / Approved) and a Submit button that opens the submit dialog for that fortnight (Rob, 11 Aug). The geo-fence preferences panel (auto-create entries, push, default shift start, grace period, destination email) is mounted in a My Profile accordion. Geofence-derived times are saved and totalled to the minute, so 08:00 to 17:00 reads 9:00, not 8:59. Totals are GROSS of the meal break (shown separately); netting is unchanged and open. The Submit picker now lists the hospital administrator central default approver and the "(Fallback approver)" surrogate when the doctor has no admin-set approver. | #0, #11181 | Rob 5 Oct 2026 live audit of Task 3 (#11181): D2, D3, D4, D9, D10. The Default Working-Calendar Start (D8) behaves as specified (earliest My Hospitals start date wins; the profile field is the fallback), so no behaviour change. |
| 2026-10-05 | Task 3 round 2 fixes. (1) The Default Working-Calendar Start is stored and read as a plain calendar date regardless of browser timezone, so choosing April saves 1 April, not 31 March (#12890). (2) The Request More Information notification link opens the Current Timesheets tab for the returned batch (?tab=0&batchId=...) instead of a blank Timesheet Entry Details dialog for a nonexistent timesheet id (#12891). (3) The Payroll Admin Email profile field is available to every doctor, not only consultant approvers, so a registrar can set the fallback payroll destination and an in-platform approval no longer ends "payroll email was not sent" (#12892). The fallback itself is unchanged (Rob, 5 Oct). | #0, #11181, #12890, #12891, #12892 | Rob 5 Oct 2026 Task 3 video recording (#11181). Open question for Rob: should the Payroll Admin Email also be required, or only prompted, for a doctor with no linked hospital admin? |
| 2026-10-04 | timesheet/utils/workingYear.ts gains workingYearDateRange(), the full date span of a working year for a given anchor. Timesheet behaviour is unchanged; the Retrospective page reuses the helper and the existing anchor resolution for its default working year. | #12771, #11209 | Matt, Notion Retrospective page 2026-05-19: 'Change this to a working year - not rolling period - Default to full current year'. Reusing the timesheet anchor keeps one working-year definition across the app. |
| 2026-10-04 | The off-platform (magic-link) timesheet approver types their full name beside the signature on every action; the field is required and pre-filled from the name that email last typed (external_approvers, lower-cased email), else the name the doctor entered. Each batch stores a per-approval snapshot - typed name, the approver email the link went to, time, IP address and browser - and, copied at submission, the doctor-entered approver name and position (timesheet_batches, migration 0262). The action is remembered per email and written to audit_trail as an external actor (timesheet_batch_external_decision). Built name-only: email and position are snapshot-only, not editable on the form. | #0, #12529 | Rob 2026-10-04 (#12528-#12531 sprint): external approvers become first-class audit actors and type their name on each approval. The open question on #12529 (should the approver also confirm email and position) is unanswered, so the form asks for the name only. |
| 2026-10-04 | The Reporting Period Summary value column no longer pushes the report past the viewport at 375px: the grid uses minmax(0, 1fr) tracks, a narrower label column on xs, and long values wrap. | #0, #12571 | Pre-existing 6px horizontal overflow found by the #12540 design review; no acceptance criterion changes. |
| 2026-10-04 | Magic-link approval portal polish: at 375px the page header stacks (title above report name) instead of wrapping both side by side; an entry with no variation type shows "-" instead of an empty outlined chip. The third reported item (raw "on_call" enum label) does not reproduce: variation types are stored and rendered as human labels ("Oncall", "Digital Recall"). | #0, #12589 | Pre-existing portal layout/empty-state defects found during #12540 design review; no acceptance criterion changes. |
| 2026-10-04 | Smart GeoTag no longer reports already clocked in after a geo-fence exit that created no timesheet. An exit event newer than the latest entry now closes the open shift, alongside the existing timesheet-end-time pairing rule (#10170). | #0, #12604 | An exit event can be recorded without a timesheet (exit-timesheet preference off, start not before exit, unresolved hospital), which left the entry permanently open. |
| 2026-10-04 | Saving or editing a timesheet entry, ending a shift, or a Smart GeoTag clock-out now refreshes every overview widget (Time at Work, Year Overview, Overtime, Fatigue, Missed breaks, Recall, Timesheets Submitted). Year Overview and Recall were previously missed, so they stayed at 0 until a page reload. The overtime-classification half of #12800 is not changed: the spec does not state a rule for roster-day overtime (split to #12841). | #0, #12800 | timesheets.md requires dashboard widget figures to be computed from current entries (#5813); two widgets were not invalidated on entry mutation. |
| 2026-10-04 | Built the full Matt scope for the doctor-nominated approver: (1) the nominate form can search ALL PPP users with directors first, or take an off-platform approver by name + email; (2) after approval the timesheet routes in-platform to a linked hospital admin, otherwise the approver chooses a destination email and the signed PDF is sent there (batch stores routed_to, payroll_destination_email, approved_report_key); (3) a verified blue tick on an approver a hospital admin has linked (signal only); (4) an e-signature step on the magic-link approval capturing work email, payroll number and an optional AHPRA check (batch stores the identity and an AHPRA status). Migration adds timesheet_batches columns. timesheets.approver.user-attaches-approver is now ✅; new ACs esignature-identity, post-approval-routing and verified-tick. The approver-pending super-admin gate is marked no longer a gate on being chosen. | #0, #12802, #12821, #12678, #12589 | Rob 2026-10-04 asked for the FULL Matt scope of #12802 (3 Oct) and #12821 (3 and 4 Oct); each behaviour is covered by a live BDD scenario run red then green. |
| 2026-10-04 | A doctor can now nominate their own timesheet approver by name + email: a "Set approver" action per attached hospital in My Hospitals, and an inline nominate form on Submit for Approval in place of the old "ask your administrator" dead end. Stored as an external approver on user_assigned_hospitals with a new approver_source column (admin | self, migration 0257). Resolution order is admin-set per-user approver > central hospital default > doctor self-nomination; an admin-set approver is read-only to the doctor. timesheets.approver.user-attaches-approver is now ⚠️ (not ⏳); Q7 answered. Still open: searching all PPP users as the approver, the verified blue tick, and consultant discoverability (#12821). | #0, #12802, #12801, #12678, #12821 | Rob 2026-10-04 approved building the self-nominated approver (#12678 decision: name + email, admin-set overrides) and Matt 2026-10-03 (#12802) ruled out any admin confirmation step. |
| 2026-10-04 | Saving a Smart GeoTag draft entry in the (single) timesheet entry form now completes it (draft -> complete), as a manual add does. The in-place Save previously round-tripped status "draft", so a geotag entry completed from the notification link never counted toward the Time at Work heat map. timesheets.entry.one-form stays ⚠️: the Payroll ID half is covered by payroll-id-inherited but neither half is verified on a physical device. | #0, #12815 | timesheets.entry.one-form requires manual and geotag entries to share the same fields and downstream effects; the divergence was found by reading the status the form wrote back after a live save. |
| 2026-10-03 | timesheets.entry.one-form stays marked drift (not met). The one-form claim (same fields incl. Payroll ID, heat map) moved from #12722 to the new issue #12815; #12722 covers only the editable-form push (timesheets.geotag.exit-deeplink). | #12807, #12722, #12815 | Review finding on PR #12807: Fixes #12722 must not imply AC2 is delivered. |
| 2026-10-03 | Corrected the stale "payroll ID is OPTIONAL platform-wide" note in timesheets.entry.payroll-id-inherited. Payroll ID is required for full-platform users to complete their profile; a missing one still never blocks a timesheet write. Inheritance behaviour is unchanged. | #12778, #12728 | Rob's #10594 decision of 2026-07-17 made Payroll ID required for full-platform users, and #12728 (PR #12778) enforces it in profile completion. The old wording contradicted both. |
| 2026-10-03 | timesheets.geotag.exit-deeplink flipped from drift to met. The native push path (EditTimesheetScreen) now opens the WebView in edit mode. timesheets.entry.one-form stays marked drift for the unverified payroll-ID and heat-map claims. | #12722 | Fix for #12722 (Matt, 2026-08-18). See mobile.timesheet.edit-screen-edit-mode. |
| 2026-10-03 | Geo-fence arrival dwell is now 5 minutes: MIN_DWELL_NOTIFY_MS (and so MIN_ARRIVAL_DWELL_MS) went from 15 to 5 minutes and STUCK_SHIFT_MAX_PLAUSIBLE_MINUTES from 15 to 5. The 5-15 minute silent audit-only tier no longer exists. timesheets.geofence.min-arrival-stay and timesheets.geofence.dwell-thresholds flipped from drift to met. | #12734 | Matt's WhatsApp 2026-08-11 (newest statement): reduce the geotag timeframe within the radius to 5 minutes; under 5 is a back-end-only pass-by. Existing 15-minute-tier tests were rewritten to the 5-minute requirement. |
| 2026-10-03 | WhatsApp top-up of the Task 3 spec refresh. On 2026-08-11 Matt said on WhatsApp "reduce geotag timeframe within radius to 5 mins. If less than 5 minutes it would be clocked as a pass by (in our back end log) but not displayed to user". That supersedes the 15-min dwell from the 2026-05-06 transcript and PR #11702's 2026-08-22 re-reading of the 29 Jul decision. timesheets.geofence.min-arrival-stay is now marked drift, and the unnamed dwell-logic AC gets the ID timesheets.geofence.dwell-thresholds and is also marked drift. Both are tracked in #12734 because the code still confirms an arrival and notifies only at 15 min. Added the 2026-08-11 ledger row and a WhatsApp top-up note. That note confirms the chat changes nothing on approver self-attach (Q7/#12678), the native-push read-only form (#12722), payroll PDF forwarding or #12439. | #11181, #12734 | Newest dated Matt statement wins. Phase A had refreshed this spec without Matt's WhatsApp messages. |
| 2026-10-03 | Task 3 spec refresh against a dated ledger of Matt's statements (GitHub, the Timesheet and PPP Dashboard Notion briefs, and meeting transcripts up to 2026-09-29). timesheets.geotag.exit-deeplink is now marked drift for the native OS push path, which opens the entry read-only (view=1), and a new drift AC timesheets.entry.one-form records the requirement for one form (both #12722, Matt 2026-08-18). Added pending AC timesheets.approver.user-attaches-approver (#12678, Matt's #11181 brief 2026-07-29 and transcript 2026-07-14) and Open Question Q7 on whether an admin must confirm a doctor's choice of approver. Recorded the payroll/admin PDF forward as built but not yet verified live. Explained that the dashboard fortnight widget denominator (Smart GeoTag detections) and the Timesheets Submitted denominator (fortnight tick-overs) belong to two different widgets, so the two briefs don't contradict each other. Added the dated ledger section. Status set to partial-drift. | #11181, #12722, #12678, #12439 | Async Task spec refresh. Newest dated Matt statement wins, so the spec can serve as the yardstick for the Task 3 recording. No AC was retired, and no AC rested only on a statement that has since been superseded. |
| 2026-10-01 | Live audit of the full 8-stage Timesheet lifecycle (Async Task 3, #11181) found and fixed four bugs — the no-approver warning misdirecting doctors to a self-service control that doesn't exist (#12677); Smart GeoTag/End Shift overlapping on the narrow-browser header during an open shift (#12679); Submit for Approval defaulting to the wrong 14-day window instead of the pay-cycle-anchored current fortnight (#12682); and the approval notification silently omitting the approver's name because the lookup 403'd on every real approval (#12685). Also re-verified the #11101 duplicate-draft concern is not reproducible on either the web Smart GeoTag or mobile geo-fence-event paths. | #12677, #12679, #12682, #12685, #11181 | Closes the live-audit pass requested for Async Task 3. Each fix has a live repro, a BDD @regression scenario demonstrated red-then-green, and (where feasible) a live before/after verification against the running app. |
| 2026-09-29 | Regenerating an expired approval link resolves the batch owner by an identity built only from the owner (their stored email and their user id), never by mixing a signed-in caller's identity with the owner's email. Behaviour for the doctor and approver is unchanged. | #12617, #12616 | Security (#12616, PR #12617 review): the caller's own identity lookup is now pinned to their linked user id, so a mixed identity would have resolved the signed-in caller instead of the batch owner. |
| 2026-09-28 | A session-less magic-link approver can now sign and action their batch at /approve-timesheets/:token with no PPP login — every action runs through token-scoped public procedures, and the page (including the hidden payroll-PDF view) makes no session-protected calls. Token actions only cover batches submitted at or before the link was issued, refuse self-approval, and send to payroll at most once (new timesheet_batches.payroll_sent_at, also stamped by the in-app send). A link covers only batches routed to the same approver email (never by approver id), and the stored payroll report must be a real PDF within 10 MB. At submit, a caller-supplied approverId is stored only when it is itself an assigned signer. | #12540, #12442, #11181 | The timesheets.approver.no-full-authn-ui and timesheets.approver.session-persists ACs were marked ✅ while the action path still needed a PPP session (401 → /login). This fix makes them true, and the status notes now say so. The link scope is an engineering security measure, so old or forwarded links cannot act on later submissions; each submission still emails a fresh link listing everything pending. It is not a requirement change. The email-only coverage closes a security gap found in review: a submitter-typed approverId let a link for one inbox act on other doctors' batches. |
| 2026-09-20 | Fixed the magic-link approval portal (/approve-timesheets/:token) redirecting genuinely unauthenticated approvers to /login — useApproveTimesheets.ts called the protected ppp.hospital.list procedure unconditionally as a display-name fallback, and any 401 from that unrelated call tripped the global session-expiry redirect before the approver ever saw their batch. | #12336, #12335, #11181 | Found while adversarially re-recording the #11181 Async Task Model Task 3 walkthrough video — the prior recording's own narration described this exact defect without a fix ever landing. Confirmed live via direct Playwright network inspection against a real unauthenticated browser context. No spec change: docs/features/timesheets.md already states timesheets.approver.no-full-authn-ui ("no PPP login... required"); this fix makes the code match the spec's already-correct AC. |
| 2026-09-20 | No behavioural or acceptance-criteria change to timesheets.geofence.*. Removed an eager JSON.stringify(data) from backgroundLocationTaskHandler's dev-only entry log in mobile/ppp/lib/services/location-service.ts, so the OS-delivered background payload is no longer serialised and discarded on every geo-fence/location tick in release builds. | #12318, #12312, #12269 | Allocation-hot-path audit (#12312) of the background geo-fence task, opened as a speculative frequency-reduction attempt for the iOS 26 Hermes Pointer-Authentication crash pattern root-caused in #12269 — an upstream Hermes VM bug with no available fix, not a PPP code defect. debugLog only strips the console.log call under __DEV__; its arguments are still evaluated in release builds, so the stringify ran on every background invocation in production. 3 of 4 crash logs in #12269 show Hades GC workers running at fault time, which is consistent with (but does not prove) GC pressure widening the race window — any crash-rate effect must be verified against before/after TestFlight data before being claimed. The audit deliberately changed nothing else: the pending-exit/dwell storage helpers, the per-tick resolveOverduePendingExits sweep, and the offline-queue replay were all examined and left alone, as their allocations are small, bounded, and not worth the behaviour-change risk on a headless background-location path. The 184 existing tests covering this handler pass unchanged. |
| 2026-08-22 | Corrected timesheets.geofence.min-arrival-stay and timesheets.geofence.stuck-open-shift-monitor prose — the arrival-gate dwell threshold remains MIN_ARRIVAL_DWELL_MS = 15 minutes / GEOFENCE_RADIUS_M = 100m (unchanged), not the "5-min/200m" figure a prior revision of this spec incorrectly attributed to Matt's 2026-07-29 decision. | #11702, #11145 | Governance re-check (Task 3 sub-issue triage) found the spec's own citation on timesheets.geofence.min-arrival-stay already stated the 15-min/100m constants were "the current source of truth," directly contradicting the same line's lead sentence claiming Matt's #11145 decision changed them to 5-min/200m. Traced the real 2026-07-29 decision to a different value (workplace radius_meters default) — the dwell constants were never changed. No code change; code (MIN_DWELL_NOTIFY_MS/MIN_ARRIVAL_DWELL_MS = 15 min) was already correct and is what the spec now matches. |
| 2026-08-20 | Added timesheets.entry.fortnight-grouping — the Current Timesheet Entries list now groups entries by fortnight, anchored on the user's configured Pay Cycle Start Day, instead of an undifferentiated flat list. | #11698, #11127 | Matt asked that timesheet entries be grouped by fortnight to match the fortnightly submission cycle already driven by Pay Cycle Start Day elsewhere in the system. |
| 2026-08-20 | Persisted mobile dwell-entry state (entryTime, timesheetId, notificationFired) so evaluateDwellOnExit runs correctly after a JS-runtime restart between a hospital ENTER and EXIT; updated timesheets.geofence.min-arrival-stay and timesheets.geofence.stuck-open-shift-monitor to reflect the current 5-min/200m arrival-gate values and the shift from after-the-fact monitor detection to preventive creation-time suppression for this defect class. | #11695, #11145 | dwellState is in-memory only, but each OS-delivered geo-fence event runs in a fresh JS invocation whenever the app is backgrounded/killed — the normal case for a geo-fence wake. The EXIT handler's if (dwell) guard silently found nothing on a restarted runtime and skipped evaluateDwellOnExit entirely, so the drive-by delete/suppress thresholds stopped applying and every exit fell through to the standard "already worked" flow regardless of actual dwell duration. /sge:governance-trace verdict MATCHES_EXISTING_MODIFIED on #11145 named both AC bullets as needing the update. |
| 2026-08-18 | Added timesheets.entry.payroll-id-inherited — an entry created without an explicit Payroll ID now inherits the owning doctor's profile payrollId on every create path, not just the web form. | #11650, #11140 | Matt (WhatsApp 2026-07-28) had Payroll ID 320498 on his profile while his geofence auto-created entry showed an empty Payroll ID. Not a regression in usePayrollIdAutoPopulation (#1173 tested it) — population was frontend-only, add mode on the web form, so the three paths that create an entry without that form all stored NULL: geoFenceEventService.recordExit (Matt's case), manualEndShift, and the mobile arrival auto-create payload. No read path fell back to the profile, so the blank reached the payroll export. Resolved at write time rather than read time so the payroll ID that applied when the shift happened is stamped on the row and never recomputed — a read-time fallback would leave the stored row empty and would silently re-label historical entries when a doctor changes employer. An explicitly supplied value always wins, including a deliberately cleared one, so only an absent field inherits; inheritance is skipped when the row's owner is not the authenticated user, since enforceUserScope lets an admin create an entry for another doctor. |
| 2026-08-12 | Added timesheets.geofence.dwell-notification-id-persisted — the #5862 persistent OS dwell notification's id is now persisted per hospital, so cancelPersistentDwellNotification can still cancel it on a JS invocation that starts after the runtime was killed. | #11540, #11349 | Matt's 2026-07-31 lock screen showed two byte-identical "Entered {hospital}" pushes at the same timestamp. Not a regression of the #10422 shift-session grace window (verified intact) — that AC governs whether two separate transitions are one visit and is structurally unable to see a defect that fires two pushes for ONE transition, which is why the #10387/#10421/#10422 lineage did not prevent the recurrence. The #5862 dual-timer resolved the OS notification id only from the in-memory dwellState, which is empty on the fresh JS invocation an iOS geo-fence wake runs in, so the cancel found nothing and a second notification was scheduled for the same absolute time as the still-armed first. The premise was already recorded in timesheets.geotag.arrival-placeholder-indicator (#10915) but its notification-side consequence had never been followed through. |
| 2026-08-11 | Renamed the TIMESHEET_STATUSES enum value 'saved' to 'complete'; fixed the CreateViewUpdateForm unsaved-changes save-prompt handler to only advance draft -> complete instead of force-overwriting status on any save; documented the entry status lifecycle (previously undocumented). | #11465, #11454, #10915 | The generic "saved" name was ambiguously overloaded between EndShiftButton's genuine shift-completion write and CreateViewUpdateForm's autosave-on-any-edit handler, which caused #10915 (a still-open Smart-GeoTag placeholder got silently marked complete by an unrelated field save, masking the real duration from the doctor). |
| 2026-08-02 | Landed review findings on #11228 that never made it into the merge (a monitor/daemon completed that PR''s merge-gate pipeline against an earlier branch snapshot, before the last review-fix commits had been pushed): a mobile GPS-accuracy guard now also rejects negative values (iOS''s documented invalid-fix sentinel) and drops the whole verification rather than a confidently-wrong distance derived from bad coordinates; both mobile and web accuracy guards gained an upper bound matching the wire schema; the geo-fence radius lookup is now deterministically ordered and scoped directly by user; and the web Smart GeoTag fence check now compares the same rounded distance it persists, so the stored verdict and distance can never disagree with each other. | #11331, #11157 | Two independent review passes (code-reviewer + security-auditor) found these issues on #11228 before it merged, but the merge race meant none of them landed. Re-derived and re-verified against current uat rather than assumed still correct, since 48 commits had landed on uat since the original review: one additional issue surfaced during that re-verification (mobile''s negative-accuracy guard needed to drop the whole verification, not just the accuracy field, since a negative CLLocation.horizontalAccuracy means the coordinates themselves are unreliable) and three of the original fixes were found to be mutation-unproven (the rounding fix, the tenant-isolation filter, and the recordEntryInput bound all had zero test coverage that would have caught a regression) — closed with dedicated, mutation-verified tests for each, per this repo''s own #11069 standard of proving a test catches its target by reverting the fix and confirming red. |
| 2026-08-02 | Review fixes on the geo-fence exit-settlement rule: the settlement anchor is now resolved independently of the incoming delivery's own timestamp (a stale offline-queue replay stamped before the anchor previously could not see it, settled the departure a second time, and re-inflated endTime with wall-clock now); geo-fence entry/exit timestamps are bounded at the wire boundary against implausibly future-dated device clocks; and the first departure of the day is no longer mislabelled as a return. | #11120, #11099 | Four findings from the review of the distance-confirmed rule. B1: the anchor query carried an lte(timestamp, exitAt) bound, which is wrong for a rule whose anchor is "the oldest confirmed exit since the last entry" — an offline replay arriving late but stamped EARLY made the anchor invisible, producing exactly the double-settle the issue exists to prevent. B2: exitTimestamp/entryTimestamp were unbounded z.coerce.date() from a device clock feeding a pay-affecting flow; a single future-dated row permanently wins recordExit''s gte(cutoff) ORDER BY timestamp DESC LIMIT 1 dedup lookup and suppresses draft-timesheet creation for that user/hospital indefinitely. A 5-minute allowance keeps ordinary clock skew working, since rejecting a legitimate exit loses the shift close entirely. M1: the returned-since-settled flag was true for the day''s FIRST departure (an entry exists, no anchor yet), so it is now derived from whether a confirmed exit precedes the latest entry. M3: the unit tests threaded the anchor in JS — a second implementation of the query semantics that agreed with the code right up until the code was wrong, which is why B1 stayed green; the recorded sequences now also run through the real logExit against a DB fake that interprets the actual filter sentinels. Every fix was proven by reverting it and confirming the suite goes red; the first M1 attempt was caught by that step passing green and was strengthened to assert the settlement reason rather than only the count. |
| 2026-08-02 | Geo-fence exits now settle a shift's end exactly once per departure, anchored at the first exit whose recorded distance EXCEEDS the authoritative workplace fence radius: logExit returns settlesShift (decided by the dependency-free evaluateExitSettlement), the anchor is never re-anchored by later deliveries, sub-radius exit deliveries are ignored as GPS jitter, deliveries carrying no distance never anchor, and every exit after the anchor is suppressed until an entry proves the doctor returned. Suppressed exits are still written to geo_fence_events so the #10342 insideGeofence latch clears, and mobile only writes the shift endTime when the exit actually settles the departure — failing OPEN whenever the flag is absent or the call errors. | #11120, #11099, #11100 | Matt reported his leaving-work geotag was slow to settle a shift draft. UAT user 17 was recording up to 16 exits per real departure and mobile wrote endTime: now on EVERY delivery, so the draft kept being extended — draft ts1020 was created 05:31:25 and still moving at 15:48:09. #9257 had split the mobile path onto logExit, which carried none of the clustered-exit suppression recordExit has had since #3674, and #10422 mistakenly treated the endTime write as idempotent. This PR''s FIRST attempt settled on the first exit of a time-clustered burst behind a 30-minute window; it was held (2026-08-01) rather than merged, because both review passes found the same M1 freeze defect — the window re-anchored on every exit including suppressed ones, so a trickle of deliveries could hold it open indefinitely. #11124 then landed distance persistence and #11100''s instrumented-era analysis replaced the guesswork: a real departure is a burst of repeated exits with monotonically increasing distance complete within ~4.2 min (586 → 3761 m), one "exit" was recorded at 55 m INSIDE a 200 m fence, two far-field stragglers arrived at ~68.5 km / +125 min, and there were zero exit→entry re-entries. Distance confirmation is what makes an anchor trustworthy and removing re-anchoring is what kills the freeze; the 5-minute constant classifies burst repeats vs. stragglers but deliberately does not expire suppression, since the stragglers must still not move the end. Neither original candidate window survived the evidence (3-min would have missed a real delivery at +4.2 min; 30-min bought nothing without re-anchoring). Evidence base is stated plainly as thin — 12 events / 1 user / 3 days, accuracy_meters populated on 0 of 12 — so the constants are documented as revisitable and #11100 stays open for the accuracy half. |
| 2026-08-01 | The mobile WebView Timesheet header no longer collides its actions while a shift is running. New AC timesheets.header.mobile-actions-four-legible: with four actions (Smart GeoTag, End Shift, Submit for Approval, + Add Entry) each stays fully legible, individually clickable and non-overlapping at the narrowest supported phone width. timesheets.header.mobile-actions-single-row (#10923) is narrowed to the three-action (no shift running) case it actually guarantees. | #11317, #11231 | Matt's WhatsApp screenshot (2026-07-31 06:59, iPhone) showed Submit for Approval and + Add Entry squashed into ~25px columns, wrapping one word per line ("Submit / for / Approv…", "+ / Add / Entry") with visibly overlapping outlines. #10923 pinned the isMobileApp header to flexWrap:'nowrap' for THREE controls; #10380 then added End Shift to that same row, but End Shift only renders during an open shift, so the row silently grew to FOUR controls in exactly that state — which is why the report shows a correctly-rendered shift-running banner directly above the broken row. Smart GeoTag and End Shift are both flexShrink:0 with a start icon and nowrap labels (~240px together at 320px), leaving the two flex:1 minWidth:0 siblings free to shrink to nothing. Fix restructures the row into two flex groups — shift controls (non-shrinking) and entry actions (flexing as a unit with an 88px legibility floor) — so the entry pair wraps onto a second row together rather than every button being squeezed; three controls still resolve to one row, preserving #10923. No font size, button variant, colour or the 44px touch target (#3109) is changed and no new visual primitive is introduced (design-system.md). |
| 2026-07-30 | Geo-fence events now persist OS-reported GPS fix accuracy (accuracy_meters, nullable integer, new column), and within_geofence is derived server-side against the authoritative per-workplace radius_meters whenever a caller (mobile) supplies a distance but no verdict of its own — closing the common case of the last two gaps left open by #11100/#11124, with two residuals stated explicitly (see reason). | #11228, #11157, #11100, #11124 | #11124 fixed the wire-schema bug so distanceMeters populates for mobile, but deliberately left two acceptance criteria open, tracked in #11157: OS-reported accuracy was not persisted at all (no column existed), and within_geofence stayed NULL for every mobile-originated row because mobile judges against a hardcoded 100m radius while the web Smart GeoTag path judges against the per-workplace radius_meters — a boolean meaning two different things depending on which client reported it. The fix: geoFenceEventService resolves the SAME workplace_locations.radius_meters the web path already judges against (via workplace_locations ⋈ user_assigned_hospitals) and derives the verdict from distanceMeters when the caller supplies none — an explicit web verdict always wins and never triggers the lookup, so web behaviour is unchanged. accuracy_meters was added with DPO sign-off (Rob Duncan, 2026-07-30): same #10827 DPIA-4 posture as distance_meters — a derived/measured scalar, never a raw coordinate — and mobile already fetches the OS-reported accuracy at the exact point it computes distance, so wiring it through required no extra position request. Two residuals, surfaced by review rather than left implicit: (1) within_geofence still resolves NULL when no ACTIVE workplace_locations marker exists for the reporting user/hospital — mobile arms its OS regions from every assigned hospital independent of that markers activity, so a doctor with Smart Geo-Tag toggled off for a workplace, or an auto-deactivated attachment (#5965), keeps producing undecided rows; (2) a mobile-derived verdict remains DEVICE-REPORTED, not independently server-verified, and must not be read as stronger evidence than that for any pay-affecting decision (#11120). |
| 2026-07-29 | The "Comments / UR Number" encryption seam (#10932) now fails CLOSED, not open, when the AES key or blind-index secret is missing. encryptTimesheetCommentsForStorage now calls the same shared assertPiiEncryptionWritable() gate the logbook identifiers use (default mode required) instead of branching on isPiiEncryptionEnabled() directly — a deployed environment missing the secrets now refuses the write with a clear error instead of silently persisting a plaintext UR number. Local dev keeps working unchanged by explicitly opting into optional mode. | #11171, #11111 | Found during the #11070 merge-gate review. The timesheet comments seam intentionally reuses the logbook''s isPiiEncryptionEnabled() gate rather than a parallel one — so it inherited the same fail-open defect: a missing key could not be distinguished from "deliberately unencrypted" local dev, and a UR number typed into "Comments / UR Number" was silently persisted in plaintext with no error or warning. Fixing both seams via the one shared gate (assertPiiEncryptionWritable) keeps them from ever diverging on this again, per the issue''s explicit scope note. |
| 2026-07-28 | Geo-fence exit and entry events now persist the derived distanceMeters reported by mobile (withinGeofence remains web-only — see reason). The columns and the service already existed and already wrote these fields — the only reason 44 of 64 exit rows stored NULL is that the tRPC input schema never listed verification, so z.object stripped it before the service could see it. Mobile derives the distance on-device at entry and exit (bounded best-effort: Balanced-accuracy fix — within 100m, matching the fence radius — 5s timeout, omitted entirely on failure so the event still logs) and posts the RESULT, never the fix, after the pay-affecting timesheet write completes. Raw coordinates remain unacceptable on every endpoint, now pinned by a test that fails if any coordinate field reappears on the wire. | #11100, #11120, #10827, #9257 | #11100. Without a distance on exit events, geo_fence_events cannot distinguish GPS jitter at the fence boundary from a genuine departure — which is exactly why the exit-flap settlement rule in #11120 was blocked: its own analysis showed '22m44s of flap removed' and '22m44s of real work deleted' are the same observation on the available data, and the one replay that appeared to validate it settled correctly only by luck. This is the measurement that converts that judgement call into a fact. Deliberately NOT a relaxation of #10827: DPIA-4 removed latitude/longitude and KEPT these two derived fields, describing them in the schema as 'the DERIVED verification result computed at event time' — so populating them is the design working as intended. The original framing of this issue assumed a new column, a migration and a privacy trade-off; none was needed. Once mobile supplies them the values are DEVICE-REPORTED, so they are diagnostics only and must not become evidence for a pay-affecting calculation without server-side verification. Review finding: withinGeofence is judged against a hardcoded 100m radius on mobile but the per-workplace radius_meters (default 200m) on web, so the same crossing could record opposite verdicts from the two clients under one column — mobile therefore sends distance only and omits the verdict; only the web Smart GeoTag path, which knows the authoritative radius, may still populate it. This PR does not persist the OS-reported horizontal-accuracy value #11100 also asked for, and within_geofence therefore still stays NULL on every mobile-originated row — tracked as a follow-up rather than closing #11100 outright (see the PR for the tracking issue). |
| 2026-07-27 | The Timesheet Entry Details "Comments / UR Number" free-text field is now AES-256-GCM encrypted at rest, its reads are access-audit-logged, and its value is redacted from error logs. The column widened from varchar(1000) to text (ciphertext does not fit 1000 chars) with the 1000-character limit preserved on the plaintext in the input schema; every read path decrypts at the service boundary — list, detail, batch, the unauthenticated magic-link approver portal, the multi-feature report, the batch PDF, and the create/update/delete .returning() echoes — with the cached per-user list decrypting AFTER the cache read so Redis stores ciphertext. | #11070, #10932 | The field''s own UI copy invites a patient Unit Record number into a Timesheet & Attendance row, but the column had none of the protection #10721 built for the logbook patient identifiers. Product decision (Rob, 2026-07-27) resolving the issue''s open question: keep the field inviting UR numbers and protect it properly, rather than stripping "UR Number" from the label. Reuses the existing #10721/#10730 seam (pii-crypto, isPiiEncryptionEnabled, looksLikeCiphertext, logPatientIdentifierAccess) rather than a parallel mechanism, with three differences forced by this being free text rather than a structured identifier: no blind index (nothing looks a timesheet up by comment text), mixed plaintext/ciphertext tolerated permanently rather than removed at a cutover (a not-yet-backfilled row must still render), and decrypt-verified rather than shape-only ciphertext detection (an ordinary comment like "Dr.A.Smith" matches the ciphertext envelope structurally, so only the GCM auth tag can settle it). Also closes a verified TRPC_ON_ERROR gap: before this, a failed timesheet mutation echoed the UR number verbatim into the error log — the #10896/#10907 residual-leak class. |
| 2026-07-26 | Submit-for-approval and resubmit-batch failures now route through a dedicated deny-by-default sanitiser (getFriendlyTimesheetBatchError) before reaching the snackbar, so neither a raw parser/transport error nor a backend message interpolating an email address, userId, hospitalId or batchId is shown verbatim — while the actionable approver guards still get through. | #10981, #10953 | #10948 (fixing #10917) sanitised only the create/update snackbar. The two batch handlers in the same hook still surfaced error.message verbatim, deliberately — #10627 kept the raw message there so the actionable #10622 "set your hospital approver first" guard could not be swallowed again, and the create/update allowlist covers none of the batch-workflow guards. Enumerating the throw surface reachable from submitTimesheetBatch and resubmitBatchMutation found the leak was wider than the #10917 raw-transport class: several batch throws interpolate identifiers into the doctor-visible message, most severely the timesheetBatchEmail.ts throw "User not found for email <email> when sending approval email for batch <id>", whose call site in submitTimesheetsForApproval is deliberately un-wrapped and therefore propagates a live email address to the client. The new rule table passes identifier-free guards through verbatim, rewrites actionable-but-identifier-bearing ones into identifier-free text that preserves the actionable wording, and collapses everything else to one generic fallback. Applied in the submitForApproval mutation onError callback as well as both handler catch blocks, because onError fires first. |
| 2026-07-26 | Geo-fence shift closure now completes — an open Smart GeoTag arrival placeholder is treated as the ACTIVE shift so the manual End Shift fallback is offered instead of hidden, and it closes that row in place with real elapsed hours rather than inserting a duplicate or fabricating a placeholder-length one. | #10974, #10925 | Matt's July 2026 UAT showed 28 logged geo-fence exits, 3 timesheet creations and a Total Hours in July 2026 figure of 0.0. The mobile EXIT handler owns the happy-path close, but it is a single best-effort client call; when it never lands the documented fallback (manualEndShift, #6785) was meant to take over and could not — its already-a-timesheet-today guard matched the open placeholder itself (created via timesheets.create, so sourceGeoFenceEventId is NULL), so the End Shift button hid exactly when a shift was stuck open. When it did run it anchored to the LATEST entry event (GPS jitter could truncate an 8-hour shift) and its start-before-exit fallback mutated a Date in place that could be the SAME instance as the exit timestamp, persisting a ZERO-duration shift. Closure is now anchored to the durable row startTime (jitter-proof), the create path anchors to the earliest entry of the day, and an unusable start declines rather than inventing hours. |
| 2026-07-25 | Added timesheets.header.mobile-actions-single-row (#10923, Matt UAT screenshots: Smart GeoTag + Submit for Approval sat on row one but "+ Add Timesheet Entry" wrapped onto its own right-aligned second row at phone width). The mobile-WebView header row is now flexWrap:''nowrap'' with alignItems:''flex-start''; Smart GeoTag / End Shift keep intrinsic width (flexShrink:0) while Submit / Add Entry share the remaining space evenly (flex:1, minWidth:0) and may wrap their own label onto a second text line at the narrowest supported width instead of the row wrapping. "+ Add Timesheet Entry" is shortened to "+ Add Entry" in this header only — no font size or 44px touch-target floor reduced, no new button variant. | #10958, #10923 | The issue explicitly ranked even-distribution first and label-shortening second as the acceptable fixes, and forbade a new visual primitive; the fix follows that order exactly rather than introducing an icon-only or compact-button pattern. |
| 2026-07-25 | Smart GeoTag's geofence-created draft (previously rendered as a literal 1-minute shift) now shows an "In progress"/"Shift still running" treatment until a real exit corrects it; raw parser/transport save errors are sanitised into a friendly message on the create/update timesheet form instead of reaching the doctor verbatim. | #10948, #10915, #10917 | Two related Matt UAT reports (2026-07-22). #10915 — the geofence ENTRY handler's placeholder endTime (an undocumented +60000 "satisfy validation" hack) rendered as a real, wrong duration; now a named sentinel the UI detects unambiguously. #10917 — a client-side, pre-network-request error ("The string did not match the expected pattern") reached the save snackbar verbatim; now routed through an allowlist that keeps known backend validation messages verbatim and replaces anything else with a generic, actionable fallback. |
| 2026-07-25 | Added two scheduled server-side monitors — monitorGeofenceStreamSilence (detects a user's geofence event stream going silent beyond 72h despite an active, enabled hospital attachment) and monitorStuckOpenGeofenceShifts (detects a geofence-sourced timesheet stuck at an implausible placeholder duration under 15 minutes). New ACs timesheets.geofence.stream-silence-monitor and timesheets.geofence.stuck-open-shift-monitor. New Open Question Q6 — whether either signal should reach the doctor, an admin/ops channel, or stay log-only is undecided. Also added the scheduled-monitor directory (services/notifications/scheduledNotificationService/) and scheduler-lambda.ts to this spec's code-paths — they governed geofence monitoring already (reconcileMissingGeofences, monitorGeofencePreferences) but were missing from the frontmatter list. | #10916, #10912, #10925, #10915 | Matt's account posted zero geofence entry/exit events for any hospital for ~5 days (2026-07-17 to 2026-07-22) — timesheet auto-generation is purely event-driven with no scheduled fallback, so the silence produced silent timesheet loss, only caught when Matt happened to notice and report it (#10912). The existing reconcileMissingGeofences/monitorGeofencePreferences monitors watch geofence configuration, not event arrival, and both ran clean throughout the blackout. A second, distinct silent-failure class was proven on the same subsystem while scoping this issue (#10925) — events flowing normally but a created timesheet left at a 1-minute placeholder duration and never corrected (#10915), driving a month's hours to silently total near zero. A pure stream-silence detector would not have caught that second class, so both are built together. |
| 2026-07-22 | A doctor may now have up to TWO timesheet approvers per hospital — a primary (line manager) and a fallback/surrogate (e.g. an associate director) — either of whom is an equally-valid signer. The surrogate is stored symmetrically on BOTH layers of the existing resolution chain (central hospital_approvers default + per-user user_assigned_hospitals override), each as an internal FK OR external name/email/position, with the per-user override beating the central default exactly as it does for the primary. Routing is manual at submission (the doctor picks primary OR surrogate — no auto-escalation), only the selected approver is notified, and isApproverAuthorizedForHospital accepts any of the four slots. New AC content in the "Approver Model → Second approver" section. | #10848, #10632 | Split from #10595 (deep-dive 2026-07-14): the one piece of Matt''s ask with no existing schema/UI/spec. Rob ratified the both-layers data model (2026-07-22) — store the surrogate symmetrically on hospital_approvers and user_assigned_hospitals, mirroring the single-approver chain now that the central home (#10631) shipped. Matt delegated the mechanics (2026-07-19 "assigning to you"): manual routing, notify the selected approver only, either approver valid — best-practice (Workamajig/4castplus/NHS) backs manual primary+backup with no auto-escalation. |
| 2026-07-16 | Synced per-hospital geoFenceExitGracePeriodMinutes overrides to mobile, closing the override case of the shift-gap drift #10621 eliminated. syncGeoFenceGracePeriod now also fetches the resolved grace value for every armed hospital in one self-scoped batch call and persists each into a per-hospital MMKV key; getSyncedShiftGapMs(hospitalId) and the shift-gap decision sites pick the window for the hospital whose geofence fired (per-hospital override → user-default → SHIFT_GAP_MS). | #10717, #10621 | PR #10712 (#10621) consolidated the mobile shift-gap window onto the DB-configurable geoFenceExitGracePeriodMinutes but synced only the user-wide default row, while the backend's recordExit dedup resolves the value per-hospital (getGeoFencePreferencesForUser, #4909/#8642). For a hospital carrying a per-hospital override, mobile's same-shift window and the backend's dedup window still diverged — the drift #10621 removed, narrowed to the override case. #10717 (the review gate's major finding on #10712) closes it so the two windows can no longer diverge for any hospital. |
| 2026-07-16 | Consolidated the two independent geo-fence re-entry timers into one DB-configurable value. The mobile shift-session grace window now reads the same geoFenceExitGracePeriodMinutes (geo_fence_preferences, default 5 min) that governs the backend duplicate-exit suppression, instead of a separate hardcoded 30-min SHIFT_GAP_MS. Mobile syncs the value when geofences are armed and falls back to the 30-min constant only when no synced preference is available. | #10621, #10605 | #10605 exposed that two unrelated timers (mobile SHIFT_GAP_MS = 30 min, backend geoFenceExitGracePeriodMinutes = 5 min) each answered 'is this still the same visit?' and had silently drifted apart — neither engineer recalling '10 min' or '5 min' was fully wrong, each was half-remembering a different one. One tunable source of truth removes the drift and lets the value change without a mobile release. Recorded assumption (Rob, 2026-07-16, #10621 comment, decision A): default stays 5, so the same-shift re-entry window shortens 30 -> 5 by default — a real behaviour change acknowledged in that comment; Matt veto window open until merge. |
| 2026-07-15 | Default timesheet approver now resolves through the centralized hospital_approvers table first, falling back to the per-user user_assigned_hospitals columns where no centralized mapping exists; a doctor's per-user override still wins. | #10686, #10651, #10631, #10650 | Collapses the N-writes-per-hospital denormalisation of the default approver (#5544 deferred cleanup) into a single centralized row, without a big-bang migration — the #10653 backfill can run independently without breaking resolution. |
| 2026-07-12 | Replaced the flat 10-minute exit/entry debounce maps with a single persisted per-hospital PendingExit state and a 30-minute shift-session grace window — exactly one "Entered {hospital}" push and one "Leaving work" push per continuous visit, regardless of how many times GPS crosses the 100m boundary, while a genuine split shift (departs >30 min, returns later the same day) still produces its own Entered/Leaving pair. | #10427, #10422 | Matt's 2026-07-11 screenshots (#10421) showed "Leaving work"/"Entered…" pairs spaced 20min-3h+ apart across a single working day — each individually legitimate under the 10-min debounce added by #10234/#10387, but experienced as notification spam for one continuous visit because the old debounce had no concept of "same shift". The new mechanism decides by what happens next (re-entry within 30 min vs. the window lapsing) rather than a flat timer, and fires the overdue "Leaving work" only once the window is confirmed closed — avoiding the immediate-then-retract race that the #10234 → #10387 → #10422 bug chain kept stemming from. shouldFireExitNotification/shouldFireEntryNotification and the 10-min debounce constants were deleted, not kept alongside the new state machine. |
| 2026-07-12 | Added AC timesheets.geofence.offline-queue-bounded — the offline timesheet-creation queue and geo-fence event queue are now capped at 200 entries with FIFO eviction, a deliberate narrow divergence from mobile.md's #4893 "silent drop is not acceptable" guarantee. | #10431 | Defensive fix for Sentry sentry-issue-119195945 (iOS WatchdogTermination / OS RAM kill, no stack trace). Source-level review found timesheet-offline-queue.ts (live, reached from every geo-fence ENTER while offline) had no upper bound on total queued entries. Not a confirmed root cause — PR uses Refs #10431, not Fixes. |
| 2026-07-11 | The timesheet Hospital picker now displays a hospital the doctor is already linked to (or the entry's already-saved hospital) even when that hospital's country is miscoded — resolving it from the unfiltered hospital list rather than the country-filtered one. | #10394, #10379 | Matt reported (WhatsApp 2026-07-09/10) that geofence auto-created timesheet entries showed an empty Hospital field and "No linked hospitals found" despite the hospitalId being correct at write time. Root cause was READ-side — the picker intersected the user's assigned hospitals (and the already-selected hospital) with the country-filtered list (hospital.country === userCountry), so a linked hospital with a miscoded country, or before the user's profile country loaded, was silently dropped. useCountryFilteredHospitals now also returns the unfiltered allHospitals list; CreateViewUpdateForm resolves assignedHospitals and the existing-hospital fallback from allHospitals. The country filter still only narrows the choose-a-new-hospital list, never hides an assigned/selected hospital. |
| 2026-07-11 | Geo-fence ENTER notifications are now debounced per hospital in a 10-min window, symmetric to the #10234/#10242 exit debounce — repeated boundary-jitter entries fire at most one "Entered hospital" push and create at most one auto-created timesheet draft. | #10389, #10387 | #10242 debounced only the EXIT push and treated ENTER events purely as a reset for the exit guard, so GPS jitter oscillating across the 100m boundary independently fired an entry push AND spawned a duplicate draft on every ENTER event — Matt received 18 stacked duplicates (2026-07-11). The ENTER handler now suppresses a boundary bounce within the window before any side effect (no push, no draft) and does not clear the exit guard for a suppressed bounce; a genuine EXIT clears the entry guard so a later real arrival notifies and creates a fresh draft again. Behaviour-preserving for genuine arrivals: the first entry per hospital per window is unchanged. |
| 2026-07-10 | Geo-fences now derive live from a hospital's single canonical lat/lon; workplace_locations no longer stores a per-user copy of the hospital's name/coordinates. | #10371, #10178 | ADR-0005 (Matt + Rob call 2026-07-08). ensureGeofenceForHospital copied hospitals.name/latitude/longitude onto each per-user workplace_locations row and refreshed it on re-attach, so a hospital coordinate correction with no re-attach event left every attached user's row silently stale — the root cause of #10164/#10168/#10173. Detection now joins user_assigned_hospitals ⋈ hospitals and reads the hospital's live coordinates; the workplace_locations row becomes a coordinate-free marker carrying only the per-user isActive toggle (name/latitude/longitude made nullable, migration 0194). A coordinate correction now applies to every attached doctor immediately with no re-attach and no stale copy. Behaviour-preserving: the 100m detection intent is unchanged. |
| 2026-07-09 | Geo-fence exit ("Leaving work") push is now debounced per hospital within a 10-minute window, finally enforcing the long-documented "Departed … remains outside radius for >10 minutes (prevents jitter)" rule. A genuine re-entry clears the guard so the next real departure still notifies. | #10242, #10234 | Matt received the "Leaving work" notification 6× while standing at a hospital edge (2026-07-09) — GPS jitter oscillated him across the 100m boundary, firing an EXIT event each time, and the handler pushed a notification on every one. The spec's 10-min exit debounce AC was documented but never implemented. The 100m GEOFENCE_RADIUS_M was left unchanged (locked in #4660/#4662; a radius change reverses a decision that already rejected 200m and needs Matt's sign-off — held as for-discussion). |
| 2026-07-07 | Auto-timesheet geo-fence activation now runs for un-geocoded hospital attachments too, not only when a geofence boundary can be armed. | #10166, #10162, #10152 | ensureGeofenceForHospital returned early on the un-geocoded-hospital branch (#8219) before activating the per-hospital geo_fence_preferences row, even though activation never reads coordinates. Un-geocoded active attachments were left without a preferences row, which the 0160/0168 backfill validators then caught as a forever-invariant violation and used to brick every subsequent backend deploy (#10152). Activation now runs on that branch; a top-up migration (0188) backfills the rows already missing. |
| 2026-07-06 | Expose "Submit for Approval" in the mobile WebView timesheet header (isMobileApp branch), alongside Smart GeoTag + Add Entry. | #10089, #9880 | #9885 removed the native floating Add button and deferred Submit for Approval to "the native shell", but the native shell never wired up an equivalent control (#9880), so doctors on mobile could not submit a fortnight for approval at all. The header now owns Submit for Approval too, opening the same Submit-for-Approval dialog; the footer stays hidden in the WebView so the action is not duplicated. |
| 2026-06-20 | Default Work Hours Overview widget to open on first visit; persist collapse choice per user in localStorage. | #8991, #8949 | UAT: mobile user (iPhone) found the widget collapsed by default with no indication content existed — #8949. WidgetSection now defaults to expanded on all viewports and remembers the user's explicit collapse/expand choice via localStorage keyed by sectionId + userId. |
| 2026-06-17 | Smart Geo Tag auto-timesheets now fire for self-added hospitals even when the geo-fence settings master toggle is off. The user-wide opt-out is now tri-state — a new nullable geo_fence_timesheet_opt_out_explicit marker distinguishes a deliberate opt-out (set when the doctor turns the settings master toggle off) from the incidental geo_fence_timesheet_enabled=false the settings UI persists whenever the toggle merely happens to be off (e.g. to tune the grace period). ensureGeoFenceActivationForHospital now blocks attach-time activation only on the explicit marker, so self-adding/attaching a hospital activates it. Added a per-hospital Smart Geo Tag self-enable toggle on My Hospitals (wired to the hospital-scoped geoFencePreferences.upsert + a new getForHospital query) so a doctor can self-enable a specific hospital even when the user-wide row is off. A one-time corrective backfill (0168) re-activates active attachments the old over-broad block wrongly skipped, gated on the tri-state marker so genuine opt-outs stay honoured. | #8803, #8642, #8376 | [UAT Bug] Matt's three self-added hospitals (RHCH / Winchester / Basingstoke) never auto-started a timesheet (#8642, consolidating the #8376 retest). Verified root cause: the settings UI writes a user-wide geo_fence_timesheet_enabled=false on any save with the master toggle off, and BOTH the live ensureGeoFenceActivationForHospital path and the #8491 backfill treated every user-wide false as an explicit opt-out — silently blocking activation of every self-added hospital and making recordExit return skippedByPreference. Owner-confirmed (relayed): self-added hospitals must let the doctor self-enable; a genuine explicit opt-out must still be honoured. Privacy-safe: existing rows stay non-explicit (NULL) so nothing is silently re-enabled beyond the doctor's own attached workplaces. |
| 2026-06-17 | AU missed-lunch threshold updated to the confirmed Award meal-break rule — a shift over 5 hours with under a 30-minute recorded break is flagged as a missed break (was the interim over-3h / 20-min placeholder from #8172). GB and unknown jurisdictions are unchanged (UK Working Time Regs over-6h / 20-min). The change is a one-line edit per value in the jurisdiction config (timesheet-thresholds-config.json); the resolver and all consumers (missed-lunch widget) pick it up automatically. | #8789, #8169 | Matt confirmed on #8169 (2026-06-15) that the missed-lunch rule should follow the Award figure of one 30-minute break for any shift over 5 hours — "row 4 is wrong - and should be 5 hrs" — resolving the conflict between the shipped #8172 placeholder and his AU vs UK Timesheet Parameters doc. Closes #8169 for the missed-lunch threshold; the within-shift break-timing nuance (start vs end of the 5 hours) and the Time-at-Work colour band UI remain follow-ups. |
| 2026-06-17 | Geo-fence auto-created timesheets now set source: 'geofence' on the mobile create payload, so they render the 'Auto' source chip instead of 'Manual'. | #8738, #8600 | The mobile geo-fence auto-create path (location-service.ts) never set source, so the DB column defaulted to 'manual' and doctors could not distinguish auto check-ins from hand-entered timesheets (regression against the #7586 Auto/Manual chip feature). |
| 2026-06-10 | Per-entry isFatigueShift badge now resolves its rule per shift from the hospital jurisdiction (identifyFatigueShifts), matching the #8531 dashboard: AU uses rest-under-10h plus the over-12.5h shift cap, GB/unknown keep the shipped 10.5h rest with no cap. The hospital (country, state) join was added to every identifyFatigueShifts call site so the entry list and the fatigue widget can no longer disagree near AU boundaries. | #8608, #8566, #8531 | Deferred by PR #8560 (#8531): the entry-list flag still used the global LEGACY_DEFAULTS (10.5h rest only) while the dashboard had moved to per-shift jurisdiction config, so an AU shift with 10.2h rest was flagged on the widget but not in the list. Resolving per shift from the same resolveTimesheetThresholds source of truth closes the discrepancy; GB stays byte-for-byte because the GB config rest value equals the legacy 10.5h and the DEFAULT fallback applies when no hospital resolves. |
| 2026-06-10 | Added code-paths for timesheet.ts, timesheet-status.ts, timesheet-batch-status.ts, timesheetThresholds.ts, timesheet-thresholds-config.json | #8606, #8485 | Drift gate now correctly fires for timesheets spec when timesheet constants (UK/AU jurisdiction thresholds etc.) are edited, per #8485 |
| 2026-06-10 | The AU outside-ordinary-span overtime rule (#8531) is now skipped — with a structured service-logger warn aggregated to one entry per hospital (hospitalId, skippedShiftCount, country, state, rule) — for any shift whose hospital.timezone is null or an unresolvable IANA string, instead of evaluating the Mon–Fri 06:00–18:00 span in UTC (which would mis-flag) or throwing an uncaught RangeError (junk timezone). The skip decision is shared config (shouldEvaluateOrdinarySpan in packages-shared/ppp/src/constants/timesheetThresholds.ts) so the backend service and the BDD scenario assert against one source of truth. The daily/weekly overtime rules still apply; non-AU jurisdictions (span disabled) are unaffected. | #8591, #8569 | hospitals.timezone is nullable (back-filled by super admin / on first edit, #6722/#8444). The span is a time-of-day window, so resolving a null timezone to UTC actively mis-flagged an in-span local shift — a Brisbane 06:00–18:00 shift is 20:00–08:00 UTC — as outside-span overtime. There is no safe jurisdiction default (Brisbane is wrong for WA/SA), so the rule degrades by skipping rather than guessing, mirroring the #6722 precondition. Found by the PR #8560 review. |
| 2026-06-10 | Refactored the Timesheet page from a 1236-line God-component into single-responsibility section components (TimesheetActionBar, TimesheetWidgetsRow, TimesheetTabsView, TimesheetTabPanel, TimesheetDialogs) and logic hooks (useTimesheetColumns, useWorkingYearGroups, useTimesheetSubmission, useTimesheetUrlState), reducing Timesheet/index.tsx to a 314-line thin orchestrator. Behaviour-locked — zero user-visible change; all 250 existing Timesheet unit/component tests pass unmodified. Adds a source-contract regression scenario that fails if the module regresses back into a God-component. | #8583, #8223 | Clean-code epic #8220 — applies the proven DRY/SOLID standard (PR #8200) to the Timesheet module so the page is maintainable and restyleable, with single-responsibility units under the max-lines threshold. |
| 2026-06-10 | Native geofence reliability — two fixes. (1) Data-residency routing (mobile/ppp/lib/services/data-residency.ts) now engages a regional tRPC endpoint ONLY when TRPC_URL_AU/UK was explicitly configured at build time; the hardcoded NXDOMAIN regional fallback (api-au/api-uk) is removed, so a country-set user reaches the default backend and a new data_residency telemetry event records the endpoint + reason. (2) The geofence re-arm path (geofence-rearm.ts + location-service.ts) now reports a tri-state outcome (armed / skipped(reason) / failed) and the per-token latch sets only on armed — a successful hospital fetch registering zero regions still counts as armed — so a skip (no hydrated user; background permission missing) or failure leaves the guard clear for the next launch/foreground trigger to retry. geofence_setup telemetry carries the outcome + reason. | #8573, #8558, #8561, #8376 | Found by the 2026-06-10 iOS simulator background-geofence proof (#8376 chain). The residency router substituted an unprovisioned NXDOMAIN regional host for every country-set user, killing all native tRPC (geofence arming, recordEntry, background timesheet creation) the moment the user hydrated; and the re-arm latched on startLocationTracking's bare true even when geofence setup was skipped, so the trigger that would actually have armed the device no-opped as already-armed and locationd held zero fences. Both block Matt's #8376 retest and need a new TestFlight build. |
| 2026-06-10 | The Fatigue Shifts widget's "rest between consecutive shifts" caption is now rendered from the backend-resolved threshold (a new fatigueRestHours field on the getFatigueShiftsData payload — the same value the fatigue detection actually applies) via a pure buildFatigueRestLabel helper, instead of the hardcoded frontend FATIGUE_THRESHOLD_HOURS = 10.5 constant. That constant is deleted; the heatmap colour-bucket boundary that also referenced it keeps its own literal. When the threshold has not yet loaded the figure is omitted rather than flashing a wrong number. | #8570 | Post-#8531 the backend computes AU fatigue at rest under 10h, so the hardcoded "under 10.5h" caption contradicted an AU doctor's detection rule. Sourcing the label from the payload means it tracks the resolved (and, once #8531 lands, jurisdiction-resolved) value automatically with no further frontend change. Found by the #8560 review. #8531 (PR #8560) is still open at time of writing — this change is decoupled and does not depend on its merge. |
| 2026-06-10 | Five AU jurisdiction threshold rules built as config (overtime over-10h-shift / over-38h-week / outside Mon-Fri 06:00-18:00 span; fatigue rest-under-10h / shift-over-12.5h), resolved per shift from the hospital's country; GB/DEFAULT preserved byte-for-byte (10.5h legacy rest, 8h/40h overtime, no span, no cap). Q1 narrowed to the two genuinely Matt-blocked items (missed-lunch meal rule conflict + Time-at-Work colour bands). | #8560, #8531, #8169 | Matt's 'AU vs UK Timesheet Parameters' doc (Notion, 2026-05-03) is the published source for these five rules; the #8169 confirmation table treats them as authoritative, so the build proceeded without holding on confirmation. Any value Matt amends becomes a one-line config change. |
| 2026-06-10 | One-time data migration backfills geo-fence auto-timesheet activation for every pre-existing active hospital attachment — inserting a hospital-scoped, enabled geo_fence_preferences row (at the service DEFAULTS) for users who linked their hospital before #8478 shipped. Idempotent (ON CONFLICT DO NOTHING; re-run is a no-op) and never overrides an explicit user-wide opt-out, mirroring ensureGeoFenceActivationForHospital. Ships with a sibling .validate.sql that RAISE EXCEPTIONs on any active non-opted-out attachment still missing its row. | #8499, #8491, #8376 | #8478 only activates the per-hospital preference recordExit consults when a hospital is attached/re-armed AFTER it shipped, so doctors whose hospitals were linked earlier — including Matt's UAT account — kept getting skippedByPreference:true on geo-fence exit and no draft timesheet. This backfill is the final prerequisite for Matt's #8376 retest. |
| 2026-06-10 | Hospital linking now activates the per-hospital geo_fence_preferences row the geofence exit path consults (auto-timesheet + notifications on), so a doctor who never opened settings gets a draft timesheet on geofence exit — never overriding an explicit user-wide opt-out. | #8489, #8478, #8376 | Closes #8478. recordExit gated on geoFenceTimesheetEnabled (DEFAULTS to false); arming the workplace_locations boundary on attach (#8439/#8410) never enabled it, so the timesheets.geotag.hospital-link-destination activation promise was unimplemented. Third and final blocker in Matt's #8376 field-test chain (after #8374 and #8472). |
| 2026-06-10 | Geofence regions are now idempotently re-armed on app launch, token acquisition, and foreground for already-onboarded doctors — previously startLocationTracking (the only path that registers OS geofence regions) ran solely from the one-time onboarding wizard, so geofences were never re-registered after relaunch. | #8472, #8376, #8341 | Closes #8376 (continuation of the #8341 token-bridge fix). Matt's 2026-06-10 UAT retest confirmed the token fix worked (token issued 10x, valid hospital coords) yet the backend saw zero getUserAssignedHospitals calls and zero geo_fence_events — because an already-onboarded device held an empty geofence set forever. Re-arm never prompts (#8406 owns prompting) and emits #8366 geofence_setup telemetry for field observability. Native code → requires a new TestFlight build before retest. |
| 2026-06-10 | Renamed the misleading geo_fence_events.workplace_id column (and the Drizzle workplace relation) to hospital_id / hospital, since it FKs hospitals.id — not the workplace_locations geofence-coordinate table. Data-preserving ALTER TABLE … RENAME COLUMN migration (0156_sticky_warbound) plus validator. Pure naming fix — FK target (hospitals.id) and onDelete: 'set null' unchanged; no behaviour change. | #8470, #8434 | Closes #8434 (surfaced during the #8410 geotag-model deep dive). The old name made any reader joining geo_fence_events assume it pointed at workplace_locations, producing wrong queries. The mobile recordExit/recordEntry wire input field stays workplaceId (unchanged contract); only the schema column/relation are renamed. |
| 2026-06-10 | SGD audit re-baseline: status table refreshed against live issue states, 150m->100m AC fix, coordinate-sync AC marked unbuilt, AU-vs-UK parameters appendix added (Q1 doc received) | #8469, #8169, #8376, #8444 | sgd-align sweep found stale statuses and over-claimed ACs; Matt's AU/UK research doc landed on Notion 2026-05-03 |
| 2026-06-09 | Corrects the spec<->code citations for the approver auth ACs. Re-points timesheets.approver.session-persists and the "lists all pending authorisations" AC at the production HMAC token flow (getPendingBatchesByToken #5808 / ApproveTimesheets.tsx) — a single magic link surfaces every pending batch on one screen with no per-link re-auth, which is what actually delivers Matt's "authenticate once per session" intent. Notes that the generic isolation-code flow (#7327 / PR #7516), previously credited for these ACs, is unwired scaffolding for future WBA / 360 reuse. Resolves Open Question Q4 (moved to Closed Questions). | #8415, #8173 | #8173 reported drift: the per-action scoped cookie in externalApproverCodeService appeared to contradict the "once per session" AC. Investigation found the isolation-code flow (#7327) has no production caller — timesheet emails link to /approve-timesheets/{token}, which already lists all pending batches for the approver and never re-prompts. So the user-facing intent was already met; the only defect was the spec crediting the wrong PR and leaving a stale Matt-action open question. Documentation-only fix, no behaviour change. |
| 2026-06-03 | Reconciles the missed-lunch threshold spec<->code drift. Moves the rule into jurisdiction-keyed config (timesheet-thresholds-config.json) resolved per shift from the shift's hospital (country, state): UK >6h shift / 20-min break (Working Time Regs), AU >3h shift / 20-min break (Q3), with a DEFAULT that preserves the prior UK behaviour. Adds AC timesheets.widget.missed-lunch-jurisdiction and a @regression BDD scenario covering both a UK and an AU shift. | #8298, #8172 | The SGD audit (#8172) found Q3 resolved the AU threshold to 3 hours while the shipped code used UK Working Time Regs (6h / 20-min). Both are correct for their jurisdiction and UK Prod relies on the 6h rule, so a blanket value swap would break UK correctness. A jurisdiction config (mirroring the immunisation matrix #7338) keeps both right. The AU value remains subject to Matt's confirmation against his fatigue/HR research doc (timesheets Q1). |
| 2026-06-02 | Removes the timesheets.approver.sso-identity-audit AC and its (hollow, mis-tagged @smoke) BDD scenario. Records the decision as Closed Question Q5. The off-platform approver authenticates via the magic link only — no Google/Apple SSO. | #8114, #8048 | Declined as won't-do in #7854 (no SSO for non-platform users; magic link is the sole approver auth mechanism). The transcript raised SSO as deferred/optional, but engineering decided against it. The SGD gap analysis only checks open issues, so closing #7854 re-raised the identical AC as #8048 — removing the spec AC breaks that loop so it is no longer surfaced as a gap. |
| 2026-06-01 | Geo-fence battery polish — mobile location service uses a low-power significant-location-change profile far from hospitals and only engages high-precision GPS within a 1km buffer; minimum 15-min continuous stay now required before an "arrived" timesheet is confirmed (drive-by suppression for doctors living near a hospital). | #7497, #7317 | Last two deferred geo-fence ACs from the #7317 timesheets audit. Battery drain and nuisance arrival triggers for near-hospital residents were the open mobile gaps; #7384 (Smart GeoTag) shipping unblocked this work. |
| 2026-06-01 | Geo auto-submission — added a user-settable destination email to geo-fence preferences and a per-facility "accepts direct submission" capability flag. Auto-submission proceeds only when a destination is set AND the facility accepts it; otherwise the timecard stays a manual-review draft (never auto-sent, never silently dropped). Settings copy makes the fallback explicit so the capability is not over-promised on facilities that cannot receive it. | #7914 | Surfaced in Kristin's demo-walkthrough feedback (29 May 2026, to Matt + Rob) — auto-submission of geo-tagged timecards depends on the receiving facility accepting direct submission, so the destination must be configurable and the no-direct-submission case handled gracefully and promoted carefully. |
| 2026-05-27 | Web Smart GeoTag clock-in/out — a "Smart GeoTag" button on the Timesheets action bar captures the browser location and the backend timesheets.smartGeoTag procedure clocks the doctor IN (inside an active workplace fence) or OUT (left the fence with an open shift, auto-creating the draft timesheet), reusing the existing mobile geo-fence dedup/grace-period/preference logic. Clear failure messaging on permission-denied/unavailable/timeout/unsupported points to the manual End Shift fallback. | #7658, #7384 | Closes #7384. The geo-fence entry/exit events were only ever fired by the mobile app, so clock-in/out via geotag was non-functional on the web (the demo-critical onboarding moment). Web flow is on-demand (button press) rather than continuous background polling — browsers cannot reliably geofence in the background. |
| 2026-05-26 | Manual timesheet creation without geo-fence — new source discriminator column (manual | geofence), server-side overlap rejection in createTimesheet, Manual/Auto badge in the list, and a home-widget entry point to the create form. | #7612, #7586 | Doctors without a geo-fence event (no app, denied location permission, off-site work, or a missed auto-detection) need a first-class manual entry path indistinguishable downstream from an auto-detected one (#7586, decomposed from #7317). |
| 2026-05-26 | Transcript-sourced approver-auth ACs — magic-link only (no full AuthN UI, no account) and per-session auth persistence; both built by the #7327 scoped-session flow. | #7542, #7302, #7327 | SGD audit of Dev Session 2026-05-06 §ApproverAuthMethod surfaced two untraced approver-auth requirements; the "once per session" vs per-action scope is left as Open Question Q4 for Matt. |
| 2026-05-26 | Doc-only AC-marker reconciliation in §Timesheet Entry — flipped Manual timesheet creation, Fatigue shift detection, and Missed lunch / overtime flagging from ⏳ to ✅ with code-path citations. Manual creation is the create mutation → createTimesheet + CreateViewUpdateForm.tsx; fatigue detection is identifyFatigueShifts in fatigueShiftUtils.ts with the isFatigueShift flag surfaced on entries and getFatigueShiftsData aggregation; overtime flagging is variationType === 'Overtime' in the dashboard timesheets service and missed-lunch is the #6425 widget (3-hour threshold per Q3). No code, schema, or .feature changes. | #7502, #7496, #7317 | Code verification confirmed these three ACs ship already (the Status table already marked them "✅ Built" and the .feature file already has the manual-creation + fatigue-alert scenarios). The ⏳ spec markers were stale. Fatigue widget enrichment (total hours / month breakdown) stays ⏳ under sibling #7494; approver-pool and other sibling-owned markers (#7493/#7495/#7497) are untouched. |
| 2026-05-26 | New Recall Hours dashboard widget — delineates physical recall (variation_type = 'Recall') vs digital recall ('Digital Recall') as separate sub-totals, shows total recall hours for the working year, and opens a month-by-month breakdown on click. Backed by a new dashboardTimesheets.getRecallHoursData procedure mirroring the Overtime widget shape. | #7495 | Doctors need recall hours surfaced distinctly from rostered/overtime time, split by physical vs digital recall, to claim pay and demonstrate working patterns (#7495, decomposed from #7317). No schema change required — TIMESHEET_VARIATION_TYPES already carries both recall types. |
| 2026-05-26 | Approver-pool work-queue to-do — a submitted timesheet batch now surfaces in the WorkQueue/to-do for EVERY approved consultant in the batch's (hospital, department) pool, not just the single named approverId. Flipped the "Trainee's submitted timesheet auto-appears as a to-do for every approved approver in their department's pool" AC from ⏳ to ✅. New helper getPoolVisibleBatchIds(userId, ctx) in timesheetBatchHelpers.ts resolves the submitted batches a user can see via their hospital_admins_view department scopes (matching batch.hospitalId + originator users.specialityId, with hospital-wide NULL-specialty admins falling into the pool — same fallback as getDepartmentApproverPool). Wired into both getWorkQueue and getUnifiedWork in workQueueService so the named approver OR any pool member sees the batch. | #7493, #7317 | The work-queue submitted-batch query filtered only eq(timesheetBatches.approverId, userId) (single approver). getDepartmentApproverPool existed (#4840) but was not wired into the to-do surfacing. Because the work-queue keys off status = 'submitted', once any pool member approves or requests info the batch drops out of every other pool member's to-do — no double-approval. |
| 2026-05-26 | Enriched the timesheets.widget.fatigue-shifts widget to parity with the shipped Overtime widget (#6424). getFatigueShiftsData now returns totalHours (sum of fatigue-shift durations for the working year) and a per-month monthly breakdown array ({ month, shifts, hours }). FatigueShiftsWidget.tsx surfaces the total fatigue hours and opens a click-through month-by-month breakdown dialog (each row: month fatigue-shift count + hours). Existing percentage + hover detail preserved; numeric fields null-guarded with ?? 0 (#6942). | #7494 | Closes #7494 (part of #7317). Brings fatigue widget to parity with Overtime. Detection logic unchanged — reuses the existing rest-gap rule only; new fatigue thresholds remain Matt-blocked (Q1). |
| 2026-05-22 | timesheets.manual-end-shift — "End Shift" button on Timesheets and PPP Dashboard; only visible when an active (un-exited) geo-fence shift is detected; creates a timesheet entry with endTime = now. | #6785 | Fallback for when the automatic geofence exit trigger doesn't fire (early finish, half-day, no geofence coverage). |
| 2026-05-21 | Mark timesheets.lite-web-form complete — off-platform approver lightweight web form with drawn-signature requirement is fully implemented. | #7163, #7023, #5979 | Implementation was complete in #5979 (SignatureModal canvas pad, pending-batch list, storageKey persisted, payroll PDF embed) but the spec AC was still marked ⏳. This PR adds the @smoke BDD scenario and closes the gap. |
| 2026-05-20 | Timesheet fortnightly submission prompt now exports explicit non-null defaults (Mon / 06:00 / Europe/London) from timeWindow.ts. Until the per-user pay-cycle override (#6418) lands, every user receives this default schedule — the prompt day/time can never be null/undefined. | #6642, #6419 | Matt's 23 Apr Dev Session locked the rule "the time sheet prompt must default to a set day of the week (e.g., Monday 6 a.m.) and not have an unset value". Formalising the defaults as exported constants (with a unit test asserting non-null) makes the AC timesheets.entry.default-day-not-null enforceable. |
| 2026-05-20 | The fortnightly 6 a.m. timesheet submission prompt is now gated per-user by the Pay Cycle Start Day set on Profile, not by a hardcoded Monday. processTimesheetSubmissionReminders keeps the global 06:00-06:29 instance-tz window check but moves the day-of-week gate inside the per-user loop using the new isUserPayCycleDay(today, tz, payrollCycleStartDay) helper. | #6418 | Closes #6418. Spec timesheets.entry.pay-cycle-prompt — "The pay cycle start date was added to determine the 6 a.m. prompt for submitting the fortnightly time sheet" (Dev Session 2026-04-23 §PayCycle ~00:31:34). Previously doctors whose pay cycle started on a non-Monday day never received the submission reminder. |
| 2026-05-20 | Verified deferred/optional AC timesheets.approver.sso-identity-audit is correctly marked ⏳ with transcript citation (Dev Session 2026-05-06 §ApproverSSO). No implementation required — magic link remains sufficient until Matt requests SSO audit trail. | #TBD, #6420 | SGD gap-analysis follow-up; confirms AC accurately reflects spec lines 87–89 ("Optional, deferred: third-party identity validation … Not in scope until Matt asks"). No code changes. |
| 2026-05-20 | Time-at-Work widget month selector now auto-selects the current calendar month on mount (clarified the stale "previous month" code comment). Each day-cell hover tooltip now labels the value as X.X hours alongside the date (day + month), satisfying the AC timesheets.widget.time-at-work for the auto-selection + hover-detail portion. Heatmap colour scheme bands remain TBD (Q1, Matt-blocked). | #TBD, #6422 | AC timesheets.widget.time-at-work (Dev Session 2026-05-06 §DashboardWidgets ~00:52:07) requires the widget to default to the current month and surface per-day hours + date on hover so the doctor sees their in-month workload at a glance. |
| 2026-05-20 | Widget renamed in UI from "Timesheets Completed" to "Timesheets Submitted". Backend default window for getTimesheetsCompletedData now anchors at the doctor's working-year start (Profile Job/Contract Start Date, fallback 1 Feb AU) when no explicit dateRange is supplied; denominator (numFortnights) ticks over every 14 days from that anchor. | #6423 | Implements AC timesheets.widget.timesheets-submitted. Source — Dev Session 2026-05-06 §DashboardWidgets (~00:53:12): "Time sheets submitted widget should track submissions from the start of the user's working year". |
| 2026-05-20 | Overtime Shifts widget now shows total overtime shifts AND total overtime hours accrued for the working year. Clicking the widget opens a month-by-month breakdown dialog listing overtime shifts and hours per month. Backend getOvertimeShiftsData now returns totalHours and a monthly array; existing total/totalShifts/breakdown shape is preserved. | #TBD, #6424 | Dev Session 2026-05-06 §DashboardWidgets (~00:54:36) — Matt requested the widget reflect both the number of overtime occurrences and the total hours accrued for the working year, with month-by-month drill-down on click. |
| 2026-05-20 | Missed-lunch widget now exposes the explicit numerator and denominator beneath the percentage as N / Total shifts, wrapped in a hover Tooltip that reads "N missed breaks out of D shifts (P%)". The Tooltip-discoverable hover detail satisfies the AC timesheets.widget.missed-lunch for the percentage + numerator + denominator portion. Total-hours-for-year and click → month-by-month breakdown remain pending backend work and stay tracked under #6425. | #TBD, #6425 | AC timesheets.widget.missed-lunch (Dev Session 2026-05-06 §DashboardWidgets ~00:55:42) requires the percentage to reveal the underlying ratio on hover so the doctor can sense-check the calculation at a glance. |
| 2026-05-20 | Verified timesheets.attendance.collapsed-default — Attendance nav is collapsed (no sub-items), Attendance row routes directly to /attendance/history, and the action icon next to it is a CameraAltIcon with actionTo: /attendance/scan that mounts the QR scanner page immediately. | #6662, #6417 | Closes the SGD gap AC from Dev Session 2026-03-25 §AttendanceRedesign. Implementation landed via sibling sidebar work (#6598); this verifies the AC against the live code, marks it ✅ in the spec, and adds a @smoke @issue-6417 BDD scenario covering the camera-icon → scanner flow. |
| 2026-05-19 | Verified timesheets.footer.history-grouped-by-year AC is satisfied — Approved + Pending Timesheets sections already group entries per working year via TimesheetHistoryGroupedList (collapsible groups, current year expanded by default). Flipped AC ⏳ → ✅ and re-tagged BDD scenarios with @issue-6426. | #6581, #6426 | Closes #6426. The grouping was implemented as part of #5823 (PR-issue-5823); this issue is the SGD audit follow-up that flips the spec marker and links the scenarios to the verification issue. |
| 2026-05-19 | Smart Geo Tag CTA → hospital linking destination is now closed end-to-end. The dashboard onboarding step "Use Smart GeoTag for first timesheet entry" already routed to /my-profile#hospitals (expands the My Hospitals accordion). This slice adds the missing completion feedback — when a doctor finishes hospital linking (self-add via addToMyProfile, or accepting a hospital-initiated invite), MyHospitals.tsx now fires a success notification confirming Smart Geo Tag automated timesheet creation is active for that workplace. | #6416 | Closes #6416. The AC requires the link to have a defined destination AND that completing hospital linking activates automated timesheet creation. The destination existed but there was no user-facing signal that the linking step satisfied the Smart Geo Tag onboarding goal, leaving the doctor unsure the dashboard CTA was complete. |
| 2026-05-19 | Fixed the geo-fence backend slice. recordExit now resolves and validates hospitals.id from the mobile workplaceId before inserting the draft timesheet (api/backend-ppp/src/services/geoFenceEventService/index.ts) — if the id does not resolve, the audit event is still recorded but no draft timesheet is created. Geo-fence preferences are now scoped per (userId, hospitalId): the geo_fence_preferences table gains a nullable hospital_id column and a composite NULLS NOT DISTINCT unique index (migration 0098_geo_fence_preferences_hospital_scope); getGeoFencePreferencesForUser(userId, ctx, hospitalId) prefers the hospital-specific row, falls back to the user-wide default (hospital_id IS NULL), then hard-coded defaults. | #4909, #4910 | Closes #4909 and absorbs #4910. The previous code inserted hospitalId: input.workplaceId blindly, so a dangling reference produced a silent "your workplace" fallback downstream; preference lookup ignored the hospital entirely, making multi-hospital doctors' geo-fence behaviour non-deterministic. Mobile-queue subscriber wiring (mobile/ppp) is tracked separately — no mobile build environment available in this slice. |
| 2026-05-19 | Exit geo-fence timesheet review notification now deep-links the doctor directly to the editable timesheet entry form (/timesheet?id=<id>&edit=1, edit mode) instead of the read-only list/home view. Applied in both the backend notification metadata.route and the frontend useNotificationNavigation handler. | #6415 | Closes #6415. Spec timesheets.geotag.exit-deeplink — "Upon exiting, the notification should take the doctor directly to the time sheet entry to complete the form" (Dev Session 2026-05-06 §SmartGeotagging ~00:42:00). |
| 2026-05-13 | Consolidated the approver decision mapping (approve → approved, request_info → request_info) into a single toBackendDecision() helper in instances/ppp/src/modules/Timesheet/utils/decisionMapping.ts. Both ApproveTimesheets and TimesheetBatchReviewDialog now route through the helper; the View's internal no-op remap is gone. | #6147, #6002 | Closes #6002. The previous two-step chain was a maintenance trap — adding a new UI decision value without updating every site would silently send the wrong status to the backend. Single point of conversion makes TypeScript catch the mismatch at compile time. |
| 2026-05-06 | 6 May call sweep — magic-link approver portal lists all pending; 14-day link TTL with regenerate; OS-level push on hospital entry; geo-fence dwell thresholds reconciled (under 5min delete, under 15min suppress, ≥15min fire); new month-by-month year-overview widget; live widget recompute; AU-only scope + base-rate/audit deferred; B2C timesheet confirmed in investor demo. | #5807, #5455, #5808, #5809, #5810, #5811, #5812, #5813, #5822, #5823 | Captures Matt + Rob 2026-05-06 catchup decisions and resolves dashboard Q4 (#5455). Sets up follow-on issues for build. |
| 2026-05-06 | Timesheet approver role restricted to consultants and gated behind PPP super admin verification for the demo phase. New users.timesheet_approver_status column tracks none | pending | approved | rejected; consultant self-declaration enters pending; super admin approves/rejects via /admin/timesheet-approvers; every decision writes an audit_trail row (timesheet_approver_approved / timesheet_approver_rejected). | #TBD, #4822 | Self-declared approver toggle is unsafe (Rob & Matt call 13 Apr 2026). Demo-phase gate keeps the workflow secure until the hospital admin role lands (#4529). |
| 2026-05-06 | Surface the existing batch.resubmit tRPC procedure in the Submission History panel — a Resubmit action now renders on request_info and rejected batches, fires the mutation behind a confirmation dialog, and refreshes the panel. | #TBD, #4908 | Closes #4908. Backend was wired but the UI exposed no path to resubmit a returned batch, so doctors fell back to the top-level Submit form which created an unlinked batch and broke the previousBatchId audit chain. Pairs with the #4913 mutability guard, which already pointed users at this resubmit pathway. |
| 2026-05-06 | Magic-link approver portal now lists every pending timesheet batch for the approver derived from the token, not just the one batch the link was generated against. Each row is independently actionable; approving or requesting more info on a row decrements the visible list while leaving remaining rows actionable in the same session. | #TBD, #5808 | One approver with five pending batches no longer needs five emails / five clicks. Closes #5808. Token shape unchanged (backward compatible); single-use enforcement still applies per batch via tokenConsumedAt. |
| 2026-05-06 | Hospital-entry geo-fence notification now ships as a lock-screen-grade OS push (Android high-importance geofence-events channel + iOS interruptionLevel: 'active') instead of an in-app-only toast. Tap routing to the timesheet entry view is unchanged. | #TBD, #5810 | Doctors are commonly on a locked device or in another app at the moment of hospital entry; an in-app toast was invisible. AC #5810 — supersedes the 17 Apr "in-app toast only" wording. |
| 2026-05-06 | Action-bar pair (Submit + Add Entry) mirrored in both Timesheet page header and footer; both pairs now render on mobile-web viewport. | #5822, #4919 | Closes #5822 and supersedes #4919 (mobile-hidden buttons). Gives the user reachable Submit and Add Entry actions at both ends of the page without scrolling. |
| 2026-05-06 | New timesheets.widget.year-overview widget — month-by-month physical/visual representation of total working hours for the doctor's current working year. Backend service getYearOverviewData returns 12 monthly buckets anchored on Profile → Job/Contract Start Date (1 Feb AU fallback). Live recompute — includes approved + submitted + saved + draft entries (#5813 pattern). | #5812 | Closes #5812. Confirmed Matt call 2026-05-06 — gives the doctor a "year of work at a glance" panel on the timesheet landing surface. |
| 2026-05-06 | Approved + Pending timesheet history now group entries per working year — collapsible groups with current year expanded by default, working-year boundary derived from Profile → Job/Contract Start Date (1 Feb fallback). | #5823 | Closes #5823. Implements timesheets.footer.history-grouped-by-year so long histories scan cleanly once doctors have several cycles on the platform. |
| 2026-05-06 | Widget figures (time-at-work, missed-lunch %, overtime, fatigue) now compute from all current timesheet entries — not only the last approved batch — so doctors see today's shift impact immediately. Frontend invalidates every dashboard timesheet widget on entry create/update. | #0, #5813 | Matt + Rob 2026-05-06 catchup. Frozen-between-approvals figures broke the fast-feedback loop the dashboard is meant to provide. |
| 2026-05-05 | Widget set sweep from Matt's 28 Apr brief — Time-at-Work, Timesheets Submitted (renamed from Completed), Overtime, Missed Lunch, Fatigue, NEW Recall Hours (physical vs digital), header + footer Submit/Add buttons, Approved/Pending grouped per working year. | #5566 | Closes #5566. Fatigue/Overtime/Missed-Lunch threshold values and Time-at-Work colour bands remain in Q1 — engineering needs to surface current platform thresholds for Matt to confirm. |
| 2026-04-21 | Triage sweep — 17 open issues mapped to this spec | #5101, #5032, #4978, #4919, #4918, #4915, #4914, #4913, #4912, #4911, #4910, #4909, #4908, #4907, #4906, #4893, #4822 | Unblocks drift detection on the features index. |
| Mar 2026 | Multiple entries per day implemented | #3616 | Doctors work on-call, recall, overtime same day |
| Mar 2026 | Approver email workflow implemented | #3619, #3933 | Administrative officers not on platform |
| Jan 2026 | Geofencing requirements documented | GDrive doc | Full technical spec written up |
| Apr 2026 | Geo-fence radius increased 50m → 100m | #4660, #4662 | AIHW coordinates target entrances not road; 50m never triggered in UAT; 200m caused zone overlap between co-located campus entries (#4662); configurability removed per Rob & Matt call 2026-04-07 |
| Apr 2026 | Geo-fence customisation deferred — 100m fixed for now | Call 13 Apr 2026 (~01:21:54) | Matt: "overcomplicated without any customers" — focus on log-in/log-out/timesheet-produced before tuning per-hospital |
| Apr 2026 | Approver role restricted to consultants; super admin verification gate added for demo | #4822, #4840 | Self-declared approvers are unsafe; long-term governance is hospital admin per (hospital, specialty) — see admin.md |
| Apr 2026 | Department/hospital hierarchy documented (HHS → Hospital → Department/Specialty → Doctor) | Call 13 Apr 2026 (~00:40:41–00:43:53) | Specialty list is nationally consistent; this is the join key for approver pools and admin roles |
| Apr 2026 | External approver auth uses isolation code, not username/password | #4827 | Existing email-link-only flow had security gaps; isolation code tightens this without forcing account creation |
Appendix — AU vs UK timesheet parameters (Matt, May 2026)
Source: "AU_vs_UK_Timesheet_Parameters (1).docx", uploaded by Matt to the Timesheet Notion page on 2026-05-03. This fulfils the "Rob task: locate Matt's original fatigue/HR docs and add to this spec as a reference appendix" item above. AU thresholds below are awaiting Matt's confirmation on #8169 (Q1).
| Parameter | Australia (Award / QH MOCA7) | UK (NHS England) |
|---|---|---|
| Standard hours | 38h full-time week, rostered as 80h/fortnight; ordinary span Mon–Fri 06:00–18:00 (QH SMOs 07:00–18:00) | 40h week with 48h WTR rolling average cap; plain-time span Mon–Fri 07:00–21:00 + Sat 07:00–17:00 (residents) |
| Max shift | 10h (overtime trigger above); 12.5h absolute (QH MOCA7) | 13h absolute; 72h max in any rolling 168h |
| Meal breaks | Shift over 5h → 1×30-min break, unpaid (Award) / paid (QH MOCA7); not time worked under Award cl. 14.3 | Shift over 5h → 1×30-min PAID; over 9h → 2×30-min; night over 12h → 3×30-min; all count as time worked |
| Rest between shifts | Min 10 consecutive hours; breach → DOUBLE rate until released plus paid absence until 10h elapsed | Min 11 consecutive hours; breach → TOIL within 24h; 8h or less → Guardian penalty payment |
| Overtime triggers | Over 10h in a single shift; over 38 ordinary hrs/week; outside ordinary span; un-pre-agreed ADO work | Over 40h/week (Additional Rostered Hours); no daily paid trigger (13h cap is absolute); exception reporting |
| Recall — physical | 3h minimum payment at 150% weekday / 200% weekend-PH, plus 1h min hourly rate for travel | No fixed minimum (local rota); counts toward 72h cap and weekly average |
| Recall — digital (remote/phone) | QH MOCA7: 30-min minimum at overtime rate per call/episode (cl. 11.17.10); digital escalating to physical within 30 min → 2.5h minimum | No dedicated provision — captured via exception reporting only |
| Fatigue protections | Under-10h break between shifts → paid fatigue leave (QH cl. 19.7); mandatory safe transport home if unsafe to drive (employer pays) | Hard caps prevent fatigue in advance (no paid fatigue leave); Guardian of Safe Working Hours fines breaches; rest space or taxi home |
| Compliance flags to surface | Shift over 10h (overtime); shift over 12.5h (QH absolute cap); under-10h inter-shift break (fatigue); missed/unpaid meal break; unclaimed unrostered overtime | Shift over 13h (HARD breach); over 72h in 168h (HARD breach); over 4 consecutive long shifts/nights; under-11h rest (TOIL); under-8h rest (Guardian fine); over 25% missed meal breaks |
Doc's key reading note: AU rules specify pay multipliers per hour (every hour must be classified by rate band: 150%/200%/250%); UK rules specify hard caps and rest minimums (the timesheet must surface breach flags). The two jurisdictions require structurally different data models.
Sources & Recordings
| Source | Notes |
|---|---|
| https://docs.google.com/document/d/1gz0DsJC4U3zhVEJTIJ1sBLjHgP3cJ0oHYA4WW3VT2MA | Hospital Geofencing Requirements (Jan 2026) — geo-fence triggers, radii, battery strategy, hospital data APIs |
| https://docs.google.com/document/d/1HSyLmmu2yHx9RPiA5jvDpvTbMOrgW7bMn4YkOh74sY4 | Hospital Data API Links (Jan 2026) — AIHW MyHospitals, Digital Atlas, NHS ODS, CQC endpoints |
| https://drive.google.com/file/d/1HDF4acVA0QKImQ29Wu0rp_kVIgb-VGFVg_XwcZnUV6E | Features Deck (Oct 2025) — original timesheet/geofence product framing |
| "AU_vs_UK_Timesheet_Parameters (1).docx" on the Timesheet Notion page | AU vs UK time parameters: hours, breaks, rest, overtime, recall, fatigue (uploaded by Matt 2026-05-03; answers Q1 pending confirmation #8169) |