Mobile App
Feature Overview
The PPP mobile app is a first-class surface of the platform, not a responsive fallback. It is built with Expo / React Native and lives in mobile/ppp/. It ships through TestFlight (iOS) and Google Play Internal Testing (Android).
The mobile app exists so doctors can:
- Get automatic timesheets via background geo-fencing on arrival at / departure from assigned hospitals — this is only possible from a native app, not the web SPA
- Receive push notifications (WBA feedback, CPD deficits, plan reminders) through Expo push
- Complete short interactions quickly on the go — logbook entries, timesheet approvals, wellness prompts
The web SPA (instances/ppp/) remains the canonical surface for long-form work (CPD plan authoring, appraisals, admin). The mobile app is a thin, authenticated wrapper that shares the web routes via the same tRPC backend, with native-only surfaces (bottom navigation, location, push) layered on top.
Open Questions
| # | Question | Ref | Proposed answer |
|---|---|---|---|
| 1 | Apple Watch — which notification categories mirror to the Watch? Matt: "Are you suggesting only wellness notifications go through to Apple Watch or other select notifications?" (#9198). Awaiting Matt's confirmation. | #9198 | Default: mirror ALL categories (wellness, CPD, timesheet, feedback, system) with a user filter to opt down — Matt asked for "option to limit notifications", so on-by-default-with-a-toggle is the safest engineering default pending his answer. Modelled in mobile/ppp/lib/config/appleWatch.ts. |
| 2 | Biometric sign-in — how long should a session live before re-prompting for Face ID / fingerprint? Engineering-initiated (#10014), no Matt transcript on this specific point — surfaced as an open question rather than inferred. | #10014 | Biometric prompt on every cold app open; no re-prompt on quick app switches — implemented as: the gate only runs when there is no valid in-memory session (showPasswordFlow init check), so backgrounding/foregrounding within the same process lifetime never re-prompts, while a fresh process start always does. |
| 3 | Biometric sign-in — should enrolment be offered at first login by default, or only in Settings? Engineering-initiated (#10014), no Matt transcript on this specific point. | #10014 | Offer at first successful login (one-tap "Enable"/"Not now"), with a permanent Settings toggle as the alternate path — matches the issue's proposed flow; a declined offer is remembered so it does not nag on every subsequent login. |
| 4 | Crash-free-session target — should a numeric crash-free-session percentage gate releases, and at what threshold? Engineering-initiated (#10828/#10833): Sentry release health now reports a crash-free-session rate per build (enableAutoSessionTracking, #10773), but no target has been set by Matt — a threshold that blocks a TestFlight/App Store release is a product decision, not an engineering default. | #10828 | Track the rate per release in Sentry and review it in rollout health; adopt no numeric release-blocking threshold until Matt sets one — the engineering gates stay structural (lint gate #10829, dSYM gate #10831, release-config crash-scan #10830) rather than statistical. |
| 5 | Passive location-inactive indicator — in scope for #10913 or a separate follow-up? Matt's #10913 design notes said this was "also worth surfacing" (softer than the issue's 4-item Acceptance list, which does not include it) — a persistent on-screen indicator so a doctor who dismisses the launch prompt still sees why timesheets are missing. | #10913 | Ship the launch-time re-prompt now (#10913's stated Acceptance); track the passive indicator as its own follow-up (#10920) — different surface (timesheet screen vs. a launch dialog), its own design/placement decision, and not listed in #10913's Acceptance section. |
Original Vision
From the walk-through notes and investor materials (Oct 2025 – Mar 2026):
"The mobile app is the key unlock for automatic timesheets — doctors carry their phone into every hospital shift, so the phone is the sensor." "Notifications must feel the same on mobile and web — a single nudge engine driving both surfaces." "Think: Whoop for the Workplace — always-on background tracking of the doctor's workplace footprint, not 'open the app to check in'."
The investor pitch is explicit that background tracking is the core differentiator. A foreground-only app is a non-starter because doctors will not reliably open the app at every hospital arrival.
Core Design Decisions
Background vs foreground tracking — background is required
Decision (2026-04-14, Matt): The app must support background location tracking so geo-fencing works when the user is not actively using the app. This is already configured in mobile/ppp/app.config.js:
UIBackgroundModes: ['location', 'fetch'];and the iOS permission strings request locationAlwaysPermission (see app.config.js lines 122–126).
Privacy stance — the app uses Apple's significant-location-change / region-monitoring APIs, not continuous GPS polling, so battery drain is bounded and location is only sampled at hospital zone entry/exit. The permission copy shown to the doctor must state this explicitly (already done).
What runs in foreground only — everything else. Push token registration, in-app notification fetch, analytics pings, config refresh, and tRPC queries are all opened on app launch or resume. There is no "analytics uploader" running in the background.
Observability — dual-stack (Sentry + App Insights)
Decision (2026-05-20, CTO): Mobile telemetry uses a dual-stack approach. Sentry handles crash reporting and JS error tracking with symbolicated stack traces. Azure Application Insights handles operational telemetry — lifecycle events, push token registration, geo-fence events, auth events, config fetch, and OTA events — giving Matt an Azure Portal rollout health dashboard filterable by appVersion. See #6753.
Prior decision (2026-04-23, Matt): Sentry chosen as the primary telemetry stack, replacing the original App Insights-only plan (2026-04-14). Sentry's crash grouping + source-map upload is retained for crashes and JS errors.
Current state: Sentry wired for crashes + JS errors. App Insights wired for all 6 operational event categories (#6753). Source-map verification pending (#5180).
Sentry covers:
- Native crashes (iOS + Android) and unhandled JS errors with symbolicated stack traces
App Insights covers (via direct REST ingest — no native bridge):
- App lifecycle: launch, foreground/background transitions
- Push token registration outcomes (success, permission denial, Expo API errors)
- OTA update events (available, downloaded, error)
- Geo-fence region entry/exit events (hospital id + event type only — never raw coordinates)
- Auth events (login, logout)
- Config fetch events (which env config was loaded, which channel, which build)
Config & version reporting
Every mobile build must surface its own identity in three places:
- To the user — Settings → About screen shows: app version, build number, EAS runtime version, update id, active config file, bundle id
- To telemetry — every App Insights event is auto-tagged with
appVersion,buildNumber,updateRuntimeVersion,updateId,platform(ios/android) — seelogEventinmobile/ppp/lib/services/app-insights-service.ts - To Matt — an admin-visible dashboard in Azure Portal (Application Insights) filtered by
appVersionso rollout health can be tracked per release
OTA update strategy — removed
Decision (#5158): expo-updates / EAS Update was removed from the project. The mobile-ota-update.yml CI workflow was deleted and OTA channel management is no longer part of the mobile release process. Store builds (TestFlight / Play Store Internal Testing) are the only distribution mechanism.
Auth — session cookie, no WebView remount
Session tokens are read from the auth cookie set by Azure AD B2C on login. The login WebView is mounted once and stays mounted across the auth flow — see the fix in #5085 (PR merged 2026-04-11). Any future auth rework must preserve this behaviour or the spec and BDD scenarios must be updated first.
Dependency management — tar stays on the security floor, the interop is patched
@expo/cli (used for expo prebuild, the prerequisite for all native iOS and Android builds) calls _tar().default.extract, which relies on tar v6's CJS default export. tar v7 removed it, so raising the major does crash expo prebuild with TypeError: Cannot read properties of undefined (reading 'extract') (#9723).
The remedy is to fix the interop, NOT to hold tar on v6. The pnpm.overrides block in mobile/ppp/package.json keeps a blanket floor:
"tar": ">=7.5.21"and mobile/ppp/scripts/fix-tar-cjs-interop.mjs, run from postinstall, restores exports.default on tar's minified CommonJS bundle. Version-independent by construction, so a future security bump cannot silently re-break prebuild.
The previously-documented scoped form is UNSAFE and must not be reintroduced (#11096):
"tar@<6.2.1": ">=6.2.1" // ❌ resolves @expo/cli to tar 6.2.1GHSA-r292-9mhp-454m has no lower bound — vulnerable_version_range: "<= 7.5.20" — so 6.2.1 is itself vulnerable, and 6.2.1 is the final 6.x release, with no backport to fall back on. This spec previously prescribed that scoped form as "the correct form", which made the written requirement an instruction to reintroduce the advisory. #9724 scoped to v6 to unblock prebuild; #10877 restored the floor for the CVE; a first attempt at #11096 scoped back to v6 again and wrongly claimed CVE coverage was retained. Correcting the spec is what breaks that loop — leaving it stale would have had the next person reintroduce it while following the documented rule.
Enforced rather than trusted to review attention: .github/scripts/check-override-rationale.mjs fails CI when a compatibility-critical override is removed or weakened below its documented min-floor, and mobile/ppp/__tests__/pnpm-override-resolution.test.mjs asserts both that tar.default.extract is callable from @expo/cli's resolution and that the installed tar is outside the vulnerable range — so neither half can regress alone.
Dependency management — an override floor pinned to "the current patched version" goes stale the moment a new advisory targets it
The weekly Mobile Dependency Audit (#12226, 2026-09-14) found 0 critical / 18 high / 5 moderate / 1 low advisories via pnpm audit --ignore-workspace in mobile/ppp. Most were newly-published advisories against transitive packages with no existing override (decode-uri-component, postcss-selector-parser, browserslist, baseline-browser-mapping) — routine, fixed by adding a floor. But three existing overrides (fast-uri, js-yaml, svgo) had their floor set to exactly the version that was patched-at-the-time; a newer advisory has since been published with a vulnerable range that includes that same pinned version, so the override stopped protecting anything the day the new advisory landed, while check-override-rationale.mjs kept passing (it only checks an override is present and at/above its documented floor, not that the floor is still ahead of the advisory database). @xmldom/xmldom had the same failure mode via a tilde range (~0.8.13), which npm semver resolves to >=0.8.13 <0.8.14 — i.e. it floated nowhere and pinned the package at the exact vulnerable patch release.
The lesson: a version-pinned override is not "fixed and done" — it is a floor that must be re-verified against pnpm audit on every scheduled run, not just present. All four are now floored at their current patched versions (fast-uri >=3.1.6, js-yaml >=4.3.2, svgo >=3.3.5, @xmldom/xmldom >=0.8.15 <0.9) plus the four new package overrides. Re-running pnpm audit --ignore-workspace afterwards returns 0 advisories; the only remaining "high" count is the pre-existing, already risk-accepted image-size finding (//auditConfig-comment above this block, #12107 — no upstream fix exists), which pnpm itself reports as (N ignored) rather than an open advisory.
Local native-build defaults — TRPC_URL, cleartext, WebView origin
expo run:ios / expo run:android must work against a local dev backend with no explicit env vars set. Three gaps discovered during native verification of #9890/#10045 blocked this:
app.config.jsdev fallbacks (#10054):TRPC_URL/WEB_URLhad no fallback, so an unset env var producedundefinedand native tRPC calls 404'd.app.config.jsnow falls back tohttp://localhost:4000/trpc/http://localhost:3000when the env vars are unset — production/EAS builds still require the real env vars and are unaffected since those are always set in that pipeline.- Android cleartext exception (#10055): Android's default Network Security Config blocks cleartext (
http://) traffic, so the native app could not reach a local dev server.withCertificatePinning.jsadds a scoped<domain-config cleartextTrafficPermitted="true">for10.0.2.2(Android emulator's host-loopback address),localhost, and127.0.0.1only — these addresses are unreachable from a production device, so this does not weaken release cleartext protection for any real host. - WebView origin/CSP port mismatch (#10056):
getWebHostname()stripped the port before building the WebView'soriginWhitelistand CSP directives, sohttp://localhost:3000was whitelisted ashttp://localhost(port 80) —react-native-webviewtreats port as part of the origin, so the whitelist never matched and the WebView rendered blank after the WelcomeGate.webview-security.tsnow resolves the full origin (scheme + host + port) viagetWebOrigin()/getApiOrigin()for both the whitelist and CSP. - Login WebView
onShouldStartLoadWithRequestblockedhttp://(#10056 follow-up): the origin/CSP port fix above was necessary but not sufficient — the login WebView (app/index.tsx) has its ownonShouldStartLoadWithRequestguard (kept so third-party SDK URLs cannot punch out to Safari) that returnedtrueonly forhttps:///about:, so a localhttp://dev WEB_URL's very first navigation was still blocked outright and the screen stayed blank (only the native Privacy-Policy footer visible) on a fresh install. The guard is now the pure, unit-testedshouldAllowWebViewNavigation(url, __DEV__)inwebview-security.ts— it also allowshttp://in__DEV__only, so local dev builds load while production release builds stayhttps-only. The reusableWebView.tsxhas no such guard (it relies onoriginWhitelist), so only the login screen was affected. - TokenService "All refresh attempts failed" dev toast on a fresh install (#10056): on a signed-out / fresh-install state (
accessToken === null) any native tRPC request'sheaders()callsensureValidToken()→refreshAccessToken(); the retry loop treatedperformTokenRefresh()'s "no token"falsereturn identically to a network failure, burning allMAX_RETRY_ATTEMPTSand emitting an error-level[TokenService] All refresh attempts failed…log that RN LogBox surfaced as a persistent dev error toast re-firing everyRESYNC_FAILURE_COOLDOWN_MS(~30s).refreshAccessToken()now short-circuits tofalsebefore the retry loop when there is no access token — a normal signed-out state is not a failure, so no error log, no retries, and no cooldown are armed. A genuine session still resyncs/validates normally once a token is present.
Acceptance Criteria
Navigation / Menu
- ✅ Bottom navigation renders at all viewports ≤599px with a reachable hamburger or drawer
- ⏳ Every primary web route is reachable from the mobile menu (Dashboard, CPD, Surgical Logbook, Wellness, Profile) — see
mobile-nav.feature:17-26 - ⏳
mobile.nav.bottom-tab-bar— Mobile bottom navigation uses a thumb-reachable tab bar with a maximum of five visible items (4 main tabs + "More"); any additional routes appear under the "More" sheet listed in the same order as the desktop menu, except the CPD sub-items (Plans, Activities, Report, Support, Resource Library, User Guide), which collapse behind a single expandable "CPD" row (starting collapsed) instead of always rendering expanded (#10623) — this keeps the desktop-order guarantee for every other item while preventing the CPD section's 6 rows from pushing Action Items (order: 12) below the fold on common device heights. Verified natively via Maestro (mobile/ppp/.maestro/bottom-tab-bar.yaml) for the tab-bar contract; the CPD collapse/expand behaviour is a native component with no Maestro/Playwright coverage yet, guarded instead by the Jest suitemobile/ppp/lib/components/__tests__/MoreSheet.test.tsxand a source-inspection BDD scenario (mobile-nav.feature@issue-10623).†† (#7738, #10623) - ⏳
mobile.nav.action-items-menu-label— The native "More" sheet entry for the Action Items surface reads "Action Items" (not "Action"/"Actions"), matching the web page header. Canonical AC:action-items.label.native-menu-renamed. The source label was renamed in PR #8607 and is now guarded against silent regression by amenu-itemsunit test plus a source-inspection BDD regression scenario (mobile-nav.feature@issue-8630 @issue-8631). Stays ⏳ until a fresh Expo/TestFlight build ships the rename to devices (#8651) — a web-repo PR cannot rebuild the native app. Re-confirmed by #8755 (sgd-gap re-raise after the 16 Jun 2026 UAT); the source rename + executable guards satisfy the code side, the remaining gap is the native build.† (#8590, #8630, #8631, #8651, #8755) - ⏳ No controls are hidden behind the web-only central button layout (#4919 — timesheet buttons regression)
- ⏳ All touch targets meet the 44×44 minimum (#3700) — top-bar controls (hamburger, notification bell, avatar) and primary dashboard action buttons enforced via the theme
MuiIconButtonminimum +button.heightMobileraised to 44px; verified on the mobile engines (mobile-touch-targets.feature). Form controls (radios, checkboxes, control-row labels,size="small"buttons, rating-scale chips) are now covered bymobile.forms.touch-target-floor(#9320); remaining surfaces (chips, data-grid actions) still to be audited. - ✅
mobile.forms.touch-target-floor— On mobile (below thesmbreakpoint) the form-control surfaces meet the WCAG 2.5.5 / Apple HIG 44×44 minimum tap area that the existingMuiIconButton/button.heightMobilefloors (#3700) did not reach: the theme floorsMuiRadioandMuiCheckboxcontrols to 44×44, raises the wrappingMuiFormControlLabelrow to 44px tall with a 16px label, and stopssize="small"MuiButtons collapsing below 44px; the bespoke WHO-5 / MCR / WBARatingScalechips (previously 26px circles) hold a 44×44 tappable area while keeping a compact visible circle via an inner element. Desktop (md+) keeps its dense footprint unchanged. Clears the touch-target findings across WHO-5, MSF, MCR, WBA, Reflection, Feedback and settings toggles. Regression scenarios inmobile-touch-targets.feature(@issue-9320); theme floors unit-tested ininstances/ppp/src/themes/touch-target.test.tsandinstances/ppp/src/components/RatingScale.test.tsx.†‡ (#9320) - ✅
mobile.auth.no-ios-zoom— The login / auth inputs render at ≥16px (the email + password fields) so iOS never focus-zooms the first screen a user taps out of frame (#9330). The sharedINPUT_STYLES.authLogintoken (instances/ppp/src/themes/tokens.ts) pins the auth-field text to 16px (FONT_SIZE.md);EmailFieldandPasswordFieldapply it. Scoped to the auth path only — the generalINPUT_STYLES.outlinedtoken keeps its 14px sizing so non-auth outlined inputs are unchanged (no broad regression). Complementsmobile.forms.no-focus-zoom(#8338) which holds inputs at 16px below thesmbreakpoint app-wide; this guarantees the login fields specifically, which are bespoke auth atoms.†‡ (#9330) - ✅
mobile.forms.no-focus-zoom— Text inputs render at 16px below thesmbreakpoint so iOS never focus-zooms a tapped field out of frame. Verified 2026-06-10: shipped in PR #8370 —instances/ppp/src/themes/index.tsxholdsMuiOutlinedInput.inputat 16px belowsmplus a globalMuiCssBaselinefloor oninput, select, textareafor native/bespoke inputs; regression scenario inmobile-touch-targets.feature(@issue-8338).† (#8338) - ✅
mobile.auth.crash-relaunch-session-validity— After a crash + relaunch, the native tab layout gates the authenticated shell on session validity, not just token presence. The mobile session token is zustand-persisted, so a crash leaves it in storage; the pre-fixTabLayoutgatedgetCurrentUseron!!accessTokenalone, so a clock-expired persisted token was still presented as "logged in" until a stale-bearer API call happened to fail — the ambiguous "looks logged in but isn't" state Matt reported after a geofence-boundary crash (the Smart Geo Tag manual override still worked, which is why the automatic geofence-driven path was the part left stale).TabLayoutnow readsuseSessionStore().isSessionValid()(a locally-authoritative clock check — the same signal theapp/_layout.tsxOAuth-callback guard uses) and, when a persisted token is definitively past itssessionExpiresAt, clears the dead token androuter.replace('/')s to the login/relogin flow instead of rendering the dashboard, withgetCurrentUserdisabled (enabled: isSessionValid()) so no stale-bearer request is issued. Crucially this only fires on a clock-authoritative expiry: a token with no explicit expiry (the WebView-bridge sign-in path, which relies on the proactive-refresh scheduler + 401-retry) is treated as valid and is never wiped on launch — respecting the#10019/#10044rule that a session is only cleared on an authoritative signal, never a network blip. Does not alter the "session cookie, no WebView remount" auth flow (the WebView is untouched); it adds a mount-time validity gate on top. Native-only: guarded bymobile/ppp/app/(tabs)/__tests__/_layout.test.tsx("crash-relaunch session-validity guard"); device visibility ships with the next Expo/TestFlight build (#8651-class).†‡ (#10235) - ⏳ Topbar stays visible when scrolling (
mobile-nav.feature:43-48) - ✅
mobile.timesheet.edit-screen-edit-mode— The nativeEditTimesheetScreen(/edit-timesheet/[id], the route the OS geo-fence push and the in-app notification handler open fortimesheet-auto-created/timesheet-exit-reminder) mounts the WebView inmode="edit", so the timesheet entry opens as the editable form (edit=1), not the read-only view that made the doctor press Edit first. Jest:app/__tests__/special-screens.test.tsx. BDD:timesheets.feature@smoke @issue-12722 (acceptance only — its steps cannot observe the screen mode; the Jest test is the regression guard). Seetimesheets.geotag.exit-deeplink. (#12722) - ✅
mobile.nav.app-hamburger— In?app=1browser context (no native shell) the topbar shows an "Open navigation menu" hamburger button that opens a temporary drawer containing the sidebar menu items, so that surface always has working menu navigation. Also carriesdata-tour="sidebar-toggle"(#12674) as a Guided Tour fallback target — on a handheld viewport the sidebar drawer is closed by default and renders no DOM content until opened, so the tour's first step needs this button, not the drawer contents, to anchor to.† (#7533, #7635, #12674) - ✅
mobile.nav.app-drawer-navigates— Selecting a nav item in the app-context drawer navigates to the route and closes the drawer.† (#7533) - ✅
mobile.nav.desktop-permanent— On desktop web the sidebar remains a permanent (non-temporary) drawer; the handheld hamburger is not shown. The sidebar highlights Attendance, not Timesheet, on/timesheet-attendance/attendance/*(#12523).† (#7533) - ✅
mobile.nav.native-shell-single-nav— Inside the bundled React Native webview (detected viawindow.ReactNativeWebView) the web sidebar/hamburger is suppressed; the native bottom tab bar plus the "More" sheet remain the single navigation pattern, so the App never shows two competing navigation patterns. The web compact top toolbar (Search + avatar + notifications) renders inside the native shell as the single top chrome — the native blue DynamicHeader is removed (restoring Search and Profile on mobile), with one notification bell and logout owned by the web avatar menu (no duplicate). The web hamburger must still NOT render on Profile or any tabs screen. Native WebView sub-screens (add/edit/notifications) follow the same rule — no native blue header; the web toolbar inside the WebView is their single top chrome too. This headerless rule is enforced as the root Stack navigator default (the root StackscreenOptionssetheaderShownto false), so every top-level WebView sub-screen is headerless at the source — relying on each sub-screen's per-screen override alone let the blue native header re-appear on device. Exception: the fully-native Health screen (no WebView, so no web header) keeps its native header.††††‡ (#7635, #7982, #8259, #8477, #8863) - ✅
mobile.nav.native-shell-topbar-logo— Inside the native webview shell, the Topbar's blank leading space (the area left empty once the hamburger is hidden in-shell, permobile.nav.native-shell-single-nav) renders the approved PPP horizontal wordmark (design-system.brand.logo-wordmark-nunito,ppp-full-black-text-v1.svg— the black variant, matching the Topbar's lightbackground.paper), so the top of the screen reads as branded rather than empty. Sized at 18px tall (the asset's native 572×97 viewBox, ~5.9:1 — distinct from the unrelated 290×106design-system.brand.logo-side-lockupcanvas) so it does not crowd the topbar's other controls within the 48pxstickyTopbarHeight. Gated on a dedicatedisNativeShellprop, NOTisHandheld(corrected by #12349 —isHandheldis false both in the real native shell AND on an ordinary desktop browser with the sidebar expanded, which are not the same context; gating on it made the wordmark render unconditionally on desktop too, duplicating the SidebarDrawer's own PPP logo lockup). The wordmark renders ONLY inside the real native shell (isNativeShelltrue) — the one context where the SidebarDrawer is suppressed entirely (mobile.nav.native-shell-single-nav) and nothing else on screen carries the PPP logo. It is absent everywhere else: ordinary desktop (permanent sidebar already shows the logo) and the?app=1handheld browser context (the sidebar drawer the hamburger opens carries the logo once expanded).isHandheldandisNativeShellare mutually exclusive by construction (useAppContainerState.ts), so the previoussm-breakpoint responsive-hide for the?app=1case no longer applies — the real native shell has no hamburger competing for space. No new logo asset, font, or color is introduced. Verified via@smoke(native shell shows it) and@regression(desktop does not duplicate it, #12349) BDD scenarios, plus aTopbar.test.tsxunit regression.††‡ (#11617, #12349) - ✅ Handheld web and the native shell lead the top bar with the PPP logo circle as the Action Items control (To-do-only red marker, drop-down headed "Action Items"), followed by the wordmark at 24px tall; the bell stays top-right for Notifications (#12141,
action-items.header.logo-control). Desktop is unchanged. - ✅
mobile.nav.tier-gated-tabs— The native bottom tab bar is gated by the user's account access tier: a CPD-only user (accountAccess === 'cpd') sees no Wellness or Logbook tab, mirroring thehideForCpdOnlyfilter the "More" sheet already applies; full-PPP users see both tabs. Admin-only tabs stay gated to super admins. (#7837) - ⏳
mobile.nav.cpd-only-menu-matches-web— The native menu (bottom tab bar + "More" sheet) shows a CPD-only user (accountAccess === 'cpd') the same role-appropriate set the web sidebar shows that tier, so the mobile app never presents a menu that does not match the user type. A CPD-only user sees Reports and Action Items (visible on web viaCPD_ONLY_CLUSTERS+ the bottom utilities inCoreAppContainerSidebarMenuList), while full-PPP-only surfaces (Wellness, Logbook, WBAs, Appraisals, Timesheet) stay hidden. Previously the native config markedreportsandactionshideForCpdOnly: true, hiding them from CPD-only users and diverging from the web menu for the same tier. Source-inspection regression onmobile/ppp/lib/config/menu-items.tsplus themenu-itemsJest unit test; device visibility ships with the next Expo/TestFlight build.†‡ (#8189) - ✅
mobile.nav.native-shell-tab-sync— Inside the native shell, a "go to feature" navigation from within a tab's WebView (e.g. tapping the dashboard Wellness widget) switches the matching native bottom tab via thenavigateToTabsbridge instead of drifting the current tab's WebView. This stops the Home (PPP Dashboard) tab getting stuck on another feature after the user opens it from a dashboard widget. Deep-intent links carrying an action query (?new=1,?add=1) or an in-page#hashnavigate normally so the intent is not dropped. On web (and the?app=1browser context) navigation stays react-router. This covers every dashboard "go to feature" affordance — the Wellness pulse card, the generic clickable widget cards, and the CPD Progress widget (including its whole-card link) — and the same shared helper backs the avatar-menu (My Profile / Billing) and What's-Next banner navigations, so there is one web→native tab map.††‡ (#8335, #8373) - ✅
mobile.nav.cpd-add-switches-native-tab— Tapping the "Add CPD" action on the PPP Dashboard CPD Progress widget inside the native shell switches the native CPD Dashboard tab (which has its own Add FAB) via thenavigateToTabsbridge, instead of drifting the Home (PPP Dashboard) tab's WebView into the/cpd/addweb flow and locking the Home tab on CPD content until app restart. Same drift class asmobile.nav.native-shell-tab-sync(#8335/#8373):/cpd/addwas absent fromWEB_ROUTE_TO_NATIVE_TAB, souseShellNavigate/handleNativeTabLinkClickfell back to react-routernavigateand drifted the current tab; it is now listed explicitly in the map (resolving to/(tabs)/cpd-dashboard) so the bridge message switches the native tab. The nativeCPDDashboardScreenalso adopts the canonicalpath="cpd-dashboard"(not thedashboardback-compat redirect) so a tab re-press /resetToHome()no longer routes through the/dashboardto/cpd-dashboardReact-Router redirect. On web (and the?app=1browser context) navigation stays react-router to/cpd/add(unchanged). Guarded byinstances/ppp/src/utils/nativeTabNavigation.test.ts(the/cpd/addmap entry plus the native-shell intercept that postsnavigateToTabs) and@regression @issue-9084scenarios inmobile-nav.feature; native device visibility ships with the next Expo/TestFlight build.†‡ (#9084) - ✅
mobile.nav.tab-repress-returns-to-root— Tapping any feature's bottom tab / More-sheet item while already inside one of its sub-pages (e.g./wellness/settingsor a deep CPD activities screen in the embedded WebView) resets that feature's WebView back to its Home screen, regardless of how deep the user had client-side-navigated. This covers both cases: switching tabs into a feature (useFocusEffectfires) and re-tapping the tab you are already on (the React NavigationtabPressevent fires becauseuseFocusEffectdoes not re-fire when the tab is already focused). Fix: aWebViewflaggedisFeatureHomedrives the embedded SPA to its canonical Homepath(derived by the pureresolveHomePath) viahistory.pushState+popstatedispatch through the existingnavigateToimperative — no full reload, no Reactkeyswap (so the iOS WKWebView WebContent process is preserved, the #5073 contract), andFOREGROUND_REFRESH_JSis re-injected afterwards so focus-gated queries stay fresh (#8334). Originally Wellness-only (#8636); generalised in #8867 so the reset lives inside theWebViewcomponent itself and every feature Home gets it from one place rather than per-screentabPresswiring.††‡ (#8636, #8867) - ✅
mobile.nav.attendance-menu-routes-correctly— The native "More" sheet entry labelled "Attendance" routes to the dedicated/(tabs)/attendancescreen (wrapping/attendance/historyvia WebView), not to the Timesheet tab. Prior to #8951 the entry pointed at/(tabs)/timesheetas a stopgap (TODO #4720) while no dedicated Attendance screen existed. A nativeAttendanceScreenWebView was added, the TabTrigger registered in_layout.tsx, and the route corrected inmenu-items.ts. Guarded by a Jest regression test (menu-items.test.ts"Attendance menu route (#8951)") and a BDD@regression @issue-8951scenario inmobile-nav.feature.†‡ (#8951) - ✅
mobile.nav.ppp-passport-menu-routes-correctly— The native "More" sheet entry labelled "PPP Passport" routes to the dedicated/(tabs)/ppp-passportscreen (wrapping/ppp-passportvia WebView), not to the Appraisals tab. Prior to #8950 the entry pointed at/(tabs)/appraisalsas a stopgap (TODO #4720) while no dedicated PPP Passport screen existed. A nativePppPassportScreenWebView was added, the TabTrigger registered, and the route corrected. Guarded by a Jest regression test (menu-items.test.ts"PPP Passport menu route (#8950)") and a BDD@regression @issue-8950scenario inmobile-nav.feature.†‡ (#8950) - ✅
mobile.nav.health-more-menu-entry— The native "More" sheet exposes a discoverable "Health Data" entry routing to the fully-native/(tabs)/healthApple Health screen (#9231). Before this, after onboarding the Health screen was only reachable via the#9285web Data Sources Connect button or a deep link — there was no persistent native menu entry, so a user could not return to it. The entry is gatedhideForCpdOnly: true(mirroring Wellness — health data is not part of the CPD-only tier) and uses ahearticon. It is added to the "More" sheet only, not the bottom tab bar; the existing hiddenhealth/indexTabTrigger keeps the route resolvable. The#9285web Connect-button deep link still reaches the same screen (additive native nav, no change there). Source-inspection regression onmobile/ppp/lib/config/menu-items.tsplus themenu-itemsJest unit test; device visibility ships with the next Expo/TestFlight build.†‡ (#9231, #8977) - ✅
mobile.nav.sidebar-badges— the web sidebar renders menu badges supplied aslabel.ParentNode(Action Items To-do pill, CPD Home dot, Pending Accounts count): around the label when expanded, around the icon on the collapsed rail (#11217 B1, 2026-10-05). - ✅
mobile.nav.bottom-runner-current-feature— When the user is viewing a feature only reachable via the More sheet (e.g. Timesheet, Reports, WBAs, CPD Activities), the far-right bottom tab button shows that feature's icon and label instead of the plain "More" dots, so the user always sees where they are. A small 3-dots badge is overlaid on the icon to signal that tapping still opens the full More sheet. On a default tab (Home / Wellness / CPD / Logbook) the button reverts to the standard "More" dots + label. Tapping either variant always opens the More sheet.†‡ (#8952) - ✅
mobile.webview.focus-event-on-foreground— the native WebView shell dispatches a focus event on app foreground so the web SPA refetches focus-bound queries (e.g. wellness data-source connection status) that iOS WKWebView would otherwise serve stale (#8334) †‡ (#8334) - ✅
mobile.webview.native-shell-pinch-lock— Inside the bundled native WebView a two-finger pinch is locked to scale 1 so it can no longer escape the web content and zoom the whole native shell (a UAT-reported timesheet glitch, but the WebView is shared so the fix covers every embedded page).getViewportLockScriptoverrides the viewport meta (width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no) viainjectedJavaScript— run after content load so it wins over the page's own viewport meta — plus an iOSgesturestartpreventDefaultguard. This lives in the native shell only: it is injected into the app's WebView, not the shipped webindex.html, so real browsers keep pinch-to-zoom and the web a11y stance ofmobile.forms.no-focus-zoom(#8338) /mobile.auth.no-ios-zoom(#9330) is untouched — WKWebView (unlike mobile Safari) honoursuser-scalable=no, which is why the lock is effective in-app without a web-viewport change. Native-shell only, verified by source inspection + Jest (a real pinch gesture cannot be driven by remote automation — on-device confirmation is a manual/interactive follow-up). Part of #10090; the other three items (off-screen day squares, vanishing More menu, add-form back-affordance) remain open pending an interactive on-device session.†‡ (#10090) - ✅
mobile.nav.ios-webview-back-affordance— On iOS, a standard on-screen "Back" affordance is shown for in-WebView SPA navigation: a floatingWebViewBackButtonconsumesHeaderBackButtonContextand renders only when the embedded WebView reports it can go back (and a back handler is published), invoking that handler on tap. Android keeps its hardware/gesture back viaWebView.tsx'sBackHandler, so the on-screen control is iOS-only. Follow-up to #8259, which removed the nativeDynamicHeader— the only previous consumer ofHeaderBackButtonContext— leaving iOS with no on-screen back control for deep client-side WebView navigation. A non-throwinguseOptionalHeaderBackButtonlets the presentational button degrade to nothing outside the provider rather than crash a host screen rendered in isolation. Because the button isposition: absolute, itstopis measured from the container's border box rather than the host chrome's padded (safe-area) content box, so it offsetstopby the top safe-area inset (useSafeAreaInsets().top + 4) to sit inside the header band instead of floating up into the status bar / notch — a hardcodedtopis a regression (#10597). Gating + press logic guarded by a Jest unit suite; device-level on-screen assertion via Maestro (ships with the next Expo/TestFlight build, #8651-class).††‡ (#8259, #8261, #10597) - ✅
mobile.nav.branded-not-found— An unmatched route never strands the user on a bare dark 404 with no menu (#9330). The Expo Routerapp/+not-found.tsxfallback (rendered automatically for any path with no matching screen) is a light, on-brand screen usingBRANDtokens: a brand-blue icon chip, a "Page not found" heading, a one-line explanation, a primary "Go to dashboard"BrandButtonthatrouter.replaces to/(tabs)/dashboard(replace, not push, so a hardware/gesture back does not return to the dead-end), and a secondary "Go back" that pops one history entry, falling back to the dashboard whencanGoBack()is false (e.g. a stale cold-launch deep link). Relates to #9314/#9317 (stranded-screen first impressions). Unit-tested inapp/__tests__/not-found.test.tsx.†‡ (#9330) - ✅
mobile.nav.add-forms-dismissible-modal— Engineering DEFAULT pending Matt's UX-architecture confirmation (#9317 is a for-discussion item). Theadd-*form routes (Add CPD, Add Wellness Entry, Add Logbook, Add Timesheet, and the 19 add-_ routes total) live outside theapp/(tabs)/group, so when pushed onto the root Stack they covered the tab navigator full-screen and the bottom menu disappeared — users reported "losing the menu" with only the small floatingWebViewBackButtonas a way back (a dead-end first impression). The add-_ routes are now registered on the root Stack withpresentation: 'formSheet'(a dismissible iOS modal that visibly overlays the tabbed screen and dismisses straight back to it, so the bottom menu returns the instant the form closes),gestureEnabledfor native swipe-down-to-dismiss, plus an explicit in-content "Cancel" control rendered byWebSubScreenwhen itsdismissibleprop is set, so the user is never stranded. The native blue header stays suppressed (#8259/#8863) — the Cancel control is the dismiss affordance, not a re-introduced native header. The form's own Save/submit is unchanged; on Cancel the modal pops viarouter.back(), falling back to/(tabs)/dashboardwhen there is no history to pop (e.g. a cold-launch deep link straight into the form). This is the recommended engineering default, not a settled UX decision — Matt's confirmation of modal-with-Cancel vs alternatives (always-visible header Close, keep the tab bar visible during entry) is pending. Source-inspection regression inmobile-nav.featureplus unit coverage of the route registration, modal options, and Cancel control (lib/navigation/__tests__/addScreenModalOptions.test.ts,WebSubScreen.test.tsx,app/__tests__/add-screens.test.tsx); device behaviour ships with the next Expo/TestFlight build.†‡ (#9317) - ✅
mobile.nav.no-dead-notifications-route— The native shell has no dead/notificationsroute: the removed header bell (#8259) was the only nav to the native/notificationsWebView screen and itsNotificationBingicon, so the route,NotificationScreenandNotificationBingwere removed as unreachable dead code. The web header's ownNotificationMenu(rendered in-shell since #8259) is the live notifications UI. The dead native logout menu plumbing (isLogoutfield + theMoreSheetlogout branch) was also removed — sign-out is owned by the web avatar menu (logoutCompletebridge, #8259/#8270). Guarded by a source-inspection BDD regression scenario.†‡ (#8259, #8261) - ✅
mobile.nav.timesheet-add-entry-via-web-header— The Timesheet tab's native shell renders only the WebView (<WebView path="timesheet" isFeatureHome />); there is no native floating action button (FAB) overlay. The webTimesheetActionBarexposes a "+ Add Timesheet Entry" button in itsisMobileApp=trueheader branch (alongside the Smart GeoTag button), so the Add Entry affordance is fully accessible inside the WebView — no native FAB needed. The previously-blue FAB (FloatingActionButton) that duplicated the Add Entry action and navigated to the native/add-timesheetroute was removed (#9885). Guarded by source-inspection BDD regression scenarios intimesheets.feature(@regression @issue-9885).†‡ (#9813, #9885) - ✅
mobile.nav.single-canonical-retrospective-route— There is exactly one canonical Retrospective route:/(tabs)/reviews(theReviewsScreen, with the feedback/reflection tab tracking + Add-feedback/Add-reflection FAB). The orphanapp/(tabs)/retrospective/index.tsxroute and its sole-importRetrospectiveScreen(a bare duplicateWebView path="retrospective") were unreachable dead/duplicate code — theretrospectivemenu id inmenu-items.tsmaps to/(tabs)/reviews, and_layout.tsxregistered no TabTrigger forretrospective, so nothing ever navigated to it — and were removed. Theretrospective"More" menu entry (label "Retrospective", routing to/(tabs)/reviews) is unchanged, so the user-facing Retrospective surface is preserved. Separately, the dev-only/(tabs)/developmentscreen stays correctly__DEV__-gated (itrouter.replaces to the dashboard in production builds), so it is a guarded dev tool, not an orphan. Guarded by a source-inspection BDD regression scenario.†‡ (#9313)
Config & version
- ✅ Settings → About screen shows app version, build number, EAS runtime version, update id, active config, bundle id
- ✅ Every App Insights event is auto-tagged with the 5 identifiers above (appVersion, buildNumber, updateRuntimeVersion, updateId, platform) — see
logEventhelper (#6753) - ✅ A "Copy diagnostic info" button on the About screen copies a JSON blob for support
- ✅
mobile.version.gate— App checks a backend version floor on launch/resume; soft nudge below latest, hard "update required" block below floor. The hard gate is enabled with a floor of1.0.1(#10410) — every build below it reports1.0.0and predates the #8389/#8343 wellness.readiness sync fix, so those builds are shown the non-dismissible "Update required" screen (AppUpdateGate) with a store-listing button. Rolls out UAT-first via theuatbranch; prod only on the next promotion.† (#8399, #10410)
Settings — permissions & preferences
- ⏳ The app provides an in-app settings screen where users can view and adjust their location services permission and health monitoring preferences, so that a user who selected incorrectly during onboarding can correct their choices without navigating to the device system settings.†
Health data (native)
✅
mobile.health.apple-health-screen-useful— The iOS Health screen always presents a clear primary action matched to state (#9255): (a) Not connected → prominent "Connect Apple Health" + one-line explanation. (b) Connected, no data yet (from the first empty sync, not after a threshold) → "Sync now" + "Open Apple Health Settings" with non-circular guidance (check Health app data, sync Watch). (c) Connected, data present → health metrics + last-sync time + a discoverable labelled "Sync now" inline control (replacing the hidden floating FAB). A one-line purpose statement "Your phone's health data powers your wellness scores" is always visible. Unit-tested across all three states inHealthScreen.test.tsx.†‡ (#9255)✅
mobile.health.apple-health-sync-truthful— WhenmetricsWritten === 0after a sync the app shows "Connected, but no data read yet" with actionable tips (open Health app, sync Watch, 30-day window) instead of plain "Success". A sync that writes metrics confirms the count and offers "View Wellness". Unit-tested inHealthScreen.test.tsxtruthful-success suite. Satisfieswellness.data.apple-health-connect-truthful(set by #9242).†‡ (#9255, #8977)✅
mobile.health.apple-health-backfill-30d— First-run backfill window is 30 days (up from 7); when all days return empty, falls back to the most recent day with samples so sparse-recent-data users always get at least one data point. App Insightsapple_health_syncevent ({ metricsRead, metricsWritten, pushed }) fires on every sync attempt, mirroring the geofence telemetry pattern.†‡ (#9255, #9265)✅
mobile.health.apple-health-permission-strings— The iOS HealthKit usage strings in thereact-native-healthplugin config (mobile/ppp/app.config.js) name the actual data types PPP reads and the concrete benefit, not generic boilerplate (#10433 item 7).healthSharePermissionwas the circular "We need access to your health data to track your health."; it is rewritten to enumerate exactly whatinitHealthKitreads (HealthContext.ios.tsx: sleep, heart rate, heart-rate variability, resting heart rate, respiratory rate, blood oxygen, steps, workouts, active energy, mindful minutes) and why (calculate the wellness readiness score + personalise coaching prompts), and states "PPP never writes to Apple Health."healthUpdatePermission(the write-usage key) is deliberately KEPT, not dropped — this corrects the issue's own "drop it" suggestion: App Store Connect rejects a read-only app that omitsNSHealthUpdateUsageDescriptionwhen a linked SDK references the HealthKit write APIs, andreact-native-healthdoes, so removing it would risk bricking the TestFlight/App Store upload; the key stays present with an honest "PPP does not write any data to Apple Health; this permission is requested only by the health library and is never used." Becauseapp.config.jsonly reaches devices via a fresh Expo/TestFlight build, correctness is guarded by source-inspection BDD (standard CI, no device) and the mobile Jestapp-config.test.ts(both strings name a concrete data type / keep the write key / are not the old boilerplate). Rob (CTO) authorised shipping item 7 (App-Review copy fix); items 4/5 (legal sign-off) of #10433 remain open. Update (#12376):app.config.js's adjacent New Architecture comment previously (and inaccurately) describedreact-native-healthas "simulator-guarded" — corrected; seemobile.health.turbomodule-native-healthkitbelow for the audit and the reader's migration off that legacy bridge module. This AC's own permission-string claims are unaffected —healthSharePermission/healthUpdatePermissiondid not change.†‡ (#10433)⏳
mobile.health.turbomodule-native-healthkit— Unproven hypothesis test, not a confirmed fix (#12376). Auditedreact-native-health's New Architecture interop status per#12269's recurring SIGSEGV/EXC_BAD_ACCESScrash investigation (30+ occurrences, 2 devices/testers): confirmed on-device it ships nocodegenConfigand no TurboModule spec files anywhere in the package (pinned^1.19.0), the same architectural class asreact-native-fs, which caused an identical crash signature fixed by removal in#7759/PR #7778.healthKitReader.ios.ts's 9 read methods andHealthContext.ios.tsx's init/authorization path are migrated to@kingstinct/react-native-healthkit(Nitro Modules, genuine New-Architecture native support, no legacy-bridge interop shim), scoped to the exact read types PPP uses (sleep, HR, HRV, resting HR, respiratory rate, SpO2, steps, workouts, active energy, mindful minutes — the same list ashealthSharePermission). The#11555breadcrumb instrumentation (logHealthKitCallBreadcrumb) is preserved unchanged across the migration.#12269's own investigation concluded the crashes are "most consistent with" an upstream Hermes/iOS 26 Pointer-Authentication bug — this migration exists only because that conclusion did not rule out an interop-corruption alternative, and does NOT confirm one. Verification requires a TestFlight soak period against App Store Connect Organizer crash data (Sentry does not see this crash class); the AC stays ⏳ until that soak completes and Matt/Rob agree the crash class has genuinely stopped recurring. Scope limitation:HealthScreen.ios.tsx(a separate livereact-native-healthcall site rendering the on-screen metric tiles) was not migrated in#12376— out of that issue's explicitly named scope — soreact-native-healthremains installed pending a follow-up.††‡ (#12376, #12269, #7759, #8264, #11555)✅
mobile.health.platform-aware-sources— The Health screen only offers sources the current platform can use: iOS surfaces Apple Health only; Android surfaces Health Connect / Samsung Health only. Cross-platform wearable OAuth sources (WHOOP, Garmin, Oura) remain available on both. The.ios/.androidscreen split already enforces this — verified no cross-platform leakage in code review (#9255).† (#9255)✅
mobile.health.apple-health-screen-display— The iOS Health screen renders its metric tiles truthfully and legibly (#9231), verified live on-device: (a) Steps are rounded and thousands-formatted (Math.round+toLocaleString), so a raw HealthKit float like1710.4187…shows as "1,710", never the raw decimal. (b) Sleep shows a sensible "last night" duration computed by merging the union of overlapping asleep intervals (ASLEEP/CORE/DEEP/REM, falling back to INBED only when no asleep stage is present) scoped to the most recent sleep session — not a cumulative sum of every overlapping InBed + Asleep + multi-source sample, which previously produced impossible figures like "20.8 hours". The on-screen sleep query now passes an explicitendDateand a bounded ~36h window instead of an open-endedstartOfDay(today)query. The session window is anchored to a fixed cutoff (18h before the latest sample end) so a chain of naps can't extend it past one night, oversize INBED-only fallback samples (>14h, i.e. a corrupt "in bed" interval) are dropped, and the final figure is clamped to ≤16h so a malformed sample can never surface an impossible duration. A single night reads ~4–10h, never 20h+ (and never ~33h from a corrupt 33h INBED interval). (c) Absent or zero optional metrics (HRV, resting HR, respiratory rate, SpO2) render an em dash "—", never a misleading "0 ms"/"0 bpm". The pure display helpers (formatStepCount,formatMetricValue,computeLastNightSleepHours,hasLiveHealthData) live inhealthCalculations.tsand are unit-tested.†‡ (#9231, #8977)✅
mobile.health.apple-health-screen-onbrand-noscroll— The iOS Health screen is on-brand, fits one viewport without scrolling, and follows atomic design (#9231, Rob design direction). (a) On-brand: colours and fonts come from the centralBRAND/FONTStokens (mobile/ppp/lib/theme/brand.ts) — brand blue#117be5, the brand greyscale, the soft-blueprimarySofticon-chip wash, Nunito font family — replacing the prior off-brand Tailwindtext-blue-500/bg-gray-800classes and baretext-2xl; CTAs use the sharedBrandButton. (b) No scroll: theScrollViewis removed; the metric grid is laid out as a 3-across primary row (Steps, Sleep, Heart Rate) plus a 2×2 compact grid of the secondary metrics (HRV, Resting HR, Respiratory, SpO2), so the connect/last-sync state, the metric grid and the sync action are all visible at once on an iPhone-class viewport. (c) Atomic design: a single reusable presentational atomHealthMetricTile(props:label,value,unit, optionalicon,variantprimary|compact) renders every metric and owns the brand styling, so a rebrand changes one component (#8201 pattern); the grid composes seven instances of it rather than per-metric one-off styled Views. The atom is pure (takes already-formatted strings) and unit-tested inHealthMetricTile.test.tsx; the no-scroll grid composition is covered inHealthStats.test.tsx.†‡ (#9231, #8977, #8201)✅
mobile.health.apple-health-header-trusts-live-read— The iOS Health screen header derives its "connected with data" state from the live on-screen HealthKit read, not solely from a possibly-staleconsecutiveEmptySyncs(#9231). When the live read returns any samples (steps > 0 or any of heart rate / sleep / HRV / resting HR / respiratory rate / SpO2 non-empty) the screen treats itself as connected-with-data and does not show the contradictory "Apple Health is connected, but no data has been read yet" CTA while real data is rendered in the tiles below. The truthful-empty CTA (#9255/#9022) only shows when the live read genuinely returned nothing, so the screen stays truthful in both directions. Unit-tested inHealthScreen.test.tsxlive-read header suite.†‡ (#9231, #8977)✅
mobile.health.android-health-connect-reader— On Android, the native Health Connect reader is wired to the on-device platform SDK (react-native-health-connect), making Health Connect the primary cross-vendor health path (Pixel / OnePlus / Xiaomi / etc., not just Samsung).checkAvailability()callsgetSdkStatusand returns available only when Health Connect reportsSDK_AVAILABLE, so the native Health screen surfaces the Health Connect connect card (instead of "Coming soon") on devices where it is installed.requestPermissions()initializes the SDK and requests read access to the same metric set the iOS HealthKit reader uses — sleep stages, resting HR, HRV, respiratory rate, SpO2, steps, active energy, and workouts — and eachgetXxx()reads the matching record type viareadRecords, aggregating into the shapeshealthConnectMapper.tsemits so the Android device-push payload stays identical to the Apple Health / Samsung contract (#9012). The native enabler is delivered by thereact-native-health-connectExpo config plugin plus awithHealthConnectplugin that adds theandroid.permission.health.READ_*manifest permissions, the<queries>block declaring the Health Connect provider package, and the permissions-rationale intent-filter (minSdkVersionraised to 26, Health Connect's floor). The reader is unit-tested against a mocked SDK; the real on-device read is verified on a physical Android phone with Health Connect data and is covered by the Maestro Samsung/Android device-smoke follow-up (#9016). Supersedes the stub scaffolded by #9029.†‡ (#9023, #9029)✅
mobile.health.apple-health-device-harness— A physical-device proof harness (mobile/ppp/e2e/run-device-health-harness.sh+mobile/ppp/.maestro/apple-health-device.yaml) drives a wired iPhone through the full connect→sync path and asserts that HealthKit metric tiles (Steps, Heart Rate) render after sync, provingsource='apple_health'data reached the backend (#9546, deferred split from #9014). The harness uses a go-ios userspace tunnel (no root / usbmuxd required) plus ago-ios wdaproxyWebDriverAgent session, letting Maestro ≥ 1.39 target a real device without an Xcode build step. Run:TEST_EMAIL="..." TEST_PASSWORD="..." bash mobile/ppp/e2e/run-device-health-harness.sh. The Maestro flow is tagged@device-only @manualand excluded from the unattended simulator CI batch.Human-only boundary (cannot be automated): iOS Settings → Privacy & Security → Health → PPP → Turn All Categories On must be performed manually on the test device before the first harness run. This is the iOS Health Data-Access category toggle — a second-layer permission control inside Settings.app that no on-device automation tool can reliably drive (it is not reachable via
Linking.openURLand the Settings.app UI hierarchy is not exposed to Maestro / XCTest in a stable way). The initial in-app HealthKit permission sheet (presented byHKHealthStore.requestAuthorization) IS automated by the flow. The category toggle is a one-time manual step; once granted it persists until the app is deleted or the permission is revoked.†‡ (#9546, #9014)⏳
mobile.health.android-health-device-smoke— A Maestro Android health smoke flow (mobile/ppp/.maestro/samsung-health-connect.yaml) drives the Android on-device connect → permission → sync-trigger UX, replacing the manual QA noted in #4678 for the Android path. The flow covers two platform paths from a single file viawhen: visible:conditionals: Path A — Health Connect (primary Android path on Android 14+ / API-34 emulators, #9023) taps "Connect Health Connect", handles the Health Connect permission screen, and asserts sync-triggered state. Path B — Samsung Health (Samsung-device path) taps "Connect Samsung Health" once the Samsung Health SDK partner approval is obtained (currentlycheckAvailability()returnsavailable: falsepending thereact-native-samsung-healthintegration insamsungHealthReader.android.ts). Tagged@smoke @manual @android-health @samsung-health— excluded from the unattended Google API emulator CI batch via@manualuntil the Health Connect emulator path is confirmed stable; runnable withFLOW=samsung-health-connect.yaml bash mobile/ppp/e2e/run-maestro-flows.sh.†‡ (#9016, #9023, #4678)✅
mobile.health.apple-health-sim-e2e— An unattended iOS Simulator Maestro flow (mobile/ppp/.maestro/apple-health-connect.yaml) drives the full Apple Health connect path: launch PPP → Health tab → tap "Connect Apple Health" → accept the in-app HealthKit disclosure ("I Understand & Continue") → grant the iOS permission sheet (suppressed/auto-approved via Maestro'slaunchApp: permissions: { health: allow }) → tap "Sync now" → assert the post-sync state. On a seeded simulator (mobile/ppp/scripts/seed-healthkit-sim.shpre-run) the flow asserts HealthStats metric tiles (Steps, Heart Rate), provingsyncAppleHealthAndScorewrotesource='apple_health'data. On an unseeded simulator (CI default) the flow asserts the truthful-empty "no data has been read yet" state, proving the sync completed without crashing (#9255). The human-only boundary (iOS Settings Data-Access category toggle) is absent on the simulator: Maestro's sandbox-level permission grant replaces it, making the entire flow fully unattended. Wired into theios-e2eCI gate (mobile-e2e.yml): the "Seed HealthKit data (iOS Simulator)" step compiles and runsseed-healthkit-sim.swiftviaxcrun simctl spawnbefore the Maestro batch. The seed script documents the human-only boundary for the physical-device path and exits non-zero gracefully so CI falls back to the truthful-empty assertion if the SDK is unavailable. Tagged@smoke @apple-health @simulator @issue-9014; excludes@device-onlyand@manualso it runs in the standard CI batch.†‡ (#9014)
Observability
- ✅ Sentry SDK wired into
mobile/ppp/and initialised on app launch - ✅ Sentry crash reports tagged by environment — TestFlight builds report
environment: 'uat'; App Store builds reportenvironment: 'production'; local dev reportsenvironment: 'development'(#9835) - ⏳ Crash reporting captures native crashes (iOS + Android) and unhandled JS errors with symbolicated stack traces
- ⏳ Source-map upload verified — Sentry stack traces are human-readable (#5180)
- ✅ App Insights SDK (direct REST ingest) initialised on app launch — no-op when
EXPO_PUBLIC_APP_INSIGHTS_CONN_STRINGabsent - ✅ App lifecycle events (launch, foreground, background) flow to App Insights
- ✅ Push token registration outcomes flow to App Insights (success / denied / error)
- ✅ OTA update events (available, downloaded, error) flow to App Insights
- ✅ Geo-fence region events flow to App Insights (hospital id + event type — not raw coordinates)
- ✅ Auth events (login, logout) flow to App Insights
- ✅ Config and channel details included in the
app_launchevent - ✅ Every App Insights event carries the 5 required identifiers (appVersion, buildNumber, updateRuntimeVersion, updateId, platform)
- ✅ UAT and prod use separate App Insights resources (separate Pulumi stacks)
- ✅ console.log of sensitive tokens removed
- ✅
mobile.observability.testflight-feedback-autofile— TestFlight crash feedback (betaFeedbackCrashSubmissions) and shake-to-report screenshot feedback (betaFeedbackScreenshotSubmissions) are pulled hourly from the App Store Connect API and auto-filed as GH issues (bug,mobile,testflight-feedback) tagged with device, OS, app version + build, and the crash excerpt / tester comment. Duplicate crash signatures comment on the existing tracker instead of filing a new one, keyed by a two-generation marker (#10773): v2 — a crash log is available, so the key is device + OS + a stack signature (exception type + top symbolicated frames, addresses normalised) and the match is VERIFIED, may be posted as another occurrence, and may reopen a closed tracker; v1 — no crash log is returned by the API (the only case observed live), so the key falls back to device + OS (+ comment prefix), byte-compatible with pre-#10773 trackers, and the match is UNVERIFIED — labelled as such in body and comment, never claimed as another occurrence, and never reopening a closed tracker. Re-running the workflow is idempotent (marker-based dedup, no persisted cursor needed), including across a v1↔v2 marker flip on the same submission: because the two generations never cross-match, a submission whose crash log the API returns inconsistently between runs would otherwise be re-filed as a duplicate, so a per-submission seen-marker sweep (testflight-crash-seen-<id>, marker-generation-independent) runs over crash trackers — open and closed, bodies and comments, memoised and scan-capped — before any issue is created (#10893). A fetch failure is not automatically a PPP defect: the App Store Connect call retries transient upstream faults — 5xx, 429 and status-less network errors — with bounded exponential backoff honouringRetry-After(each wait capped at 30s, so a server-supplied delay of hours cannot park the job; worst case is 3 x 30s per request), while every other 4xx still throws on the first response so a 401/403 credential or permission failure stays exactly as loud and as fast as it was, and a status-less error is only retried when the fetch call itself threw — a status-less throw from PPP code is a defect and fails on the first attempt rather than being retried and blamed on Apple. A fault surviving every retry still files an issue — going silent would reopen the #10625 gap this reporting exists to close — but it is labelledupstream-outage(distinct fromplatform-api-drift: drift means we must change code, an outage means we must not) and worded as an Apple-side fault, and the first successful run comments and closes it so a transient outage leaves no board debris. Three guards keep that self-closing path from swallowing real defects: the upstream-outage verdict is reached from the run's terminal outcome only (the::error::annotation lines), so a fault that was retried and RECOVERED can never make a later PPP failure read as Apple's, while API-drift is still matched against the whole log; and anygh issue close/reopentarget is re-read and required to carry this workflow's marker literally, because GitHub's tokenized issue search returns issues containing none of it; and the upstream-outage verdict cannot be MINTED by untrusted input — a TestFlight tester's free-text comment reaches the failure annotation throughgh's argv (Command failed: gh … --body <issue body>), so every message the filer did not itself compose is flattened to a single line before interpolation, keyed to the full set of characters a line-anchored match treats as a line start (LF, CR, U+2028, U+2029) rather than LF alone (#10963). Because the App Store Connect API has never once returned a crash log on this app (0 of 60 live submissions), the UNVERIFIED path above is the only one production exercises, and a device+OS bucket alone is not actionable from inside GitHub — so each no-log submission is additionally correlated against Sentry, which does hold the real symbolicated stack (#10816/#10834). The query keys on Sentry'sdevicetag (which carries the sameiPhone15,3shape App Store Connect'sdeviceModelreturns) within a bounded window around the submission'screatedDate, with the OS version applied as a client-side post-filter against the event'scontexts.os.version:device.familyholds the OS platform (iOS) rather than the hardware model despite being documented as a model name, and no indexedos.versionsearch key exists, so keying on either would have matched zero events forever while appearing to work. Matches are written into the body and occurrence comment as explicit links labelled candidate correlation, not confirmation — the join is device + OS + time, which cannot prove two records describe the same crash. Four outcomes are distinguished rather than two: exactly one candidate, several candidates, device-only (Sentry saw this device but not this OS version), and a true zero-match, which is stated as its own finding because a TestFlight crash Sentry never saw is itself evidence (pre-init, native fatal, or SDK not running). Sentry being unreachable, misconfigured or erroring degrades to the pre-existing output and never aborts the batch, and is never rendered as the meaningful zero-match. Each no-log body and occurrence comment also carries a direct App Store Connect TestFlight link so classification is one click rather than a hunt — the link shape (.../teams/<team id>/apps/<app id>/testflight/crashes) was verified live against an authenticated ASC session (#11431); anASC_TEAM_IDsecret is required for the correct shape, and its absence degrades to a known-wrong app-scoped fallback (loudWARN, never a silent bad link) rather than failing the run — no build- or submission-scoped deep link exists in ASC's UI, so the link is necessarily app-scoped, and no-log bucket titles carry the accrued report count ([testflight-crash] <device> · <os> · <N> reports (unverified)) instead of naming a single build — a bucket keeps absorbing occurrences from every later build, so naming the first build it ever saw made triage dismiss a still-live bucket as predating the fix; a VERIFIED tracker is one real crash signature and keeps its build. Accrual on a closed tracker is logged explicitly, since an unverified bucket never reopens and the comment would otherwise land unseen. Every Sentry-supplied field rendered into an issue is treated as untrusted input on the same footing as the Sentry sweep'ssanitize_crash_field(#11164): events reach the project through the publicEXPO_PUBLIC_SENTRY_DSN, so a crafted issue title could otherwise forge an invisible<!-- testflight-crash-seen-… -->marker (HTML comments do not render) and join a real crash's dedup set, or break out of its markdown link label — so comment markers and square brackets are neutralised and the text is flattened to a single line, while a candidate's permalink is rendered only when it parses as anhttps:URL onsentry.io, never ajavascript:URI or an attacker-chosen host (#10988).†††‡ (#10175, #10773, #10893, #10963) - ✅
mobile.observability.shake-report-launch-race-guard— The shake-to-report gesture (BugReportProvider/useShakeDetector, enabled in all builds since #3496) never issues a native screenshot capture (react-native-view-shot'scaptureScreen/captureRef) during the firstLAUNCH_SETTLE_MS(2s) after the detector (re)subscribes, and never issues one whileAppState.currentStateis'background'/'inactive'— re-checked before each native call in a capture (not just once at entry), sincecaptureScreenshotmakes two sequential native calls per code path and the app can background in theawaitgap between them.†‡ (#10237) - ✅
mobile.observability.dsym-symbolication-verified— Native-crash symbolication is verified loud on release builds, and release health is tracked per build, so a broken symbolication upload can no longer silently produce zero-frame crash reports. Themobile-build-native.ymldSYM upload wascontinue-on-errorandsentry-cli debug-files uploadcan exit 0 having uploaded stripped/empty dSYMs (ExportOptions setsstripSwiftSymbols), invisibly recreating the #10251/#10418/#10428/#10563 "native crash in Sentry with zero stack frames" failure. A post-upload verification step now checks each*.dSYMcarries a debug ID (sentry-cli debug-files check) and, on a stripped/absent dSYM, emits a::error::annotation + step-summary warning instead of a swallowed continue-on-error — still non-blocking, so a Sentry hiccup never blocks a TestFlight submission. Separately,Sentry.initsetsenableAutoSessionTracking: trueexplicitly so Sentry reports a crash-free-session rate per release (the metric that shows whether a containment change like #10385 moved the needle);release/distare deliberately left to SDK auto-detect — an explicit value mismatching the build-time source-map/dSYM upload would break symbolication. Advances the pendingsymbolicated stack traces(above) andsource-map upload verified(#5180) items.†‡ (#10773) - ✅
mobile.observability.dsym-release-gate— Release-bound iOS builds hard-fail if native crashes could not be symbolicated — a build that cannot be symbolicated does not ship.mobile-build-native.yml'sbuild-iosjob now runs three dSYM steps, all gated oninputs.submit == trueand all withoutcontinue-on-error: (1)Upload iOS dSYMs to Sentryfails when the archive carries nodSYMs/directory orsentry-cli debug-files uploaderrors; (2)Verify iOS dSYMs are symbolicatablerunssentry-cli debug-files checkagainst each DWARF binary inside each local.dSYMbundle — never the bundle directory itself, which sentry-cli 3.x refuses and which false-negatived every real gate run until #10857 — failing when any DWARF binary lacks a debug ID or a bundle contains no DWARF binaries, with sentry-cli output left visible in the job log; and (3) a new post-upload symbolication smoke-check extracts each dSYM's debug-info UUID viadwarfdump --uuidand confirms it is actually resolvable through the live Sentry API (GET /projects/{org}/{project}/files/dsyms/, filtered by debug id and polled to tolerate upload-to-index lag), not merely that the upload command exited 0. Any failure fails thebuild-iosjob and blocks the later TestFlight/App Store submission steps, so no un-symbolicatable build ships. Hardens the prior softmobile.observability.dsym-symbolication-verified(#10773) check — which only emitted a warning — into a release blocker, closing the blind spot that let the #10251/#10418/#10428/#10563/#10649 zero-frame crash lineage re-file ~10 times and reach production.†‡ (#10831) - ✅
mobile.observability.symbol-artifact-retention— Native crash reports are symbolicatable by anyone with repo access, with no Sentry auth token.mobile-build-native.yml'sbuild-iosjob publishes anios-dsyms-<profile>artifact (30-day retention, exceedingios-ipa-*'s 7 days) carrying every.dSYMfrom the archive — app and frameworks, so the Hermes/React bundles that hold the #10964 SIGSEGV are included — plus adsym-uuids.txtUUID→bundle manifest and aREADME.txtwith theatosrecipe. The artifact is proved to match what shipped: the step unzips the exported IPA, reads its main executable'sLC_UUIDs withdwarfdump -u, and fails the job before the TestFlight submit if any is absent from the archived dSYMs. Android publishes the equivalentandroid-symbols-<profile>(unstripped.solibraries frommerged_native_libs, a GNU build-ID manifest, and R8mapping/when minification is enabled — currently off by default, so release Java frames are already unobfuscated); the Android collector is deliberately advisory (warns loudly, never fails the build) because its Gradle intermediate paths shift between AGP versions and it has no #10831-equivalent gate to sit behind. Strictly additive — the Sentry upload and both #10831 release gates are unchanged and still blocking; Sentry stays the primary automatic symbolication path and the artifact is the manual path for someone holding a.ips.†‡ (#11000) - ✅
mobile.observability.floating-promise-lint-gate— The #10649 crash class — a fire-and-forget promise whose rejection floats into the RN New Architecture + Hermes microtask drain and aborts the process natively — is un-lintable: the blocking Mobile CI lint gate (pnpm lint, Tier 1 inmobile-ci.yml) fails on any floating promise, includingvoid asyncCall()(@typescript-eslint/no-floating-promiseswithignoreVoid: false—voidsatisfied the default rule config but still floated the rejection, the exact hole #10649 entered through) and on any async function wired where a void-returning callback is expected (@typescript-eslint/no-misused-promiseswithchecksVoidReturn— the lifecycle-handler half: an asyncAppState/effect/event handler rejects inside RN internals where no caller can.catchit). Scope isapp/**+lib/**TS/TSX excluding tests (a jest rejection cannot abort the app and suites legitimately build rejected-promise fixtures). The sanctioned replacement for genuinely fire-and-forget work islib/utils/fireAndForget.ts—fireAndForget(task, site)guarantees the rejection is caught, categorised into the bounded #8372 enum (unauthorized/network/timeout/error/unknown) and reported to Sentry with{source: 'fireAndForget', site, category}tags (siteis a static literal naming the call site; the full Error object goes only to the exception sink, per the #10385 backstop convention); the helper itself never throws at the call site, even handed a non-promise at runtime. All 46 pre-existing violations across 21 files were swept in the same PR (awaited,.catch-chained, or routed throughfireAndForget; async JSX/event handlers wrapped in synchronous dispatchers) with zeroeslint-disableescapes. Pairs with the #10835 native containment patch (defense in depth): lint removes the trigger, the patch degrades gracefully if one slips through.†‡ (#10829) - ✅
mobile.observability.keychain-signing-guard— TheSet up CI keychain and signingstep inmobile-build-native.ymlcannot report success with an unusable keychain: the cert + private-key import and partition-list sequence runs in a bounded retry loop (3 attempts — the private-key import fails transiently withSecKeychainItemImport: Unknown format in import.; run 29987098335 hit it while run 29951786477 imported the identical key on the same runner image the previous day), the identity count is parsed from plainsecurity find-identity -v— the line that discriminated the good run (1 valid identities found) from the failed one, with-p codesigningdeliberately not used because the macOS 26 beta codesigning policy validator can report 0 for a usable identity even after the partition list is set — and the step hard-fails with an actionable::error::naming the real cause when the keychain still holds 0 valid identities after all attempts, instead of printing ✅ and lettingArchive iOS appdie ~80s later with the misleadingNo signing certificate "iOS Distribution" found. All existing keychain diagnostics are kept (they made the #10854 triage possible), and decoded cert/key material (CERT_TMP/WWDR_TMP/CERT_PEM/CERT_KEY) is removed on every step exit path via an EXIT trap, including the new fail-loud exit.†‡ (#10854) - ✅
mobile.observability.release-gate-scripts-pr-ci— Every release-gate script suite undermobile/ppp/scripts/**(the dSYM-gate and keychain-signing workflow-extraction suites, Sentry symbolication smoke-check, TestFlight feedback autofile, platform-API canary —node --test "scripts/**/*.test.mjs") runs on every PR via a dependency-freescripts-testsjob inmobile-ci.yml(plainnode --testonubuntu-latest; no pnpm install — the suites import onlynode:builtins and local.mjsmodules, andsetup-noderuns withpackage-manager-cache: falsesince there is nothing to cache and no pnpm on PATH), and the workflow'spull_request.pathsfilter covers.github/workflows/mobile-*.ymlso edits to the workflows whoserun:blocks the extraction suites execute re-run them pre-merge — closing the gap where a release gate's first real execution was a production deploy. Additionally, single-platformmobile-build-native.ymldispatches auto-close their open failure issues on success: theclose-successjob's guard is an explicit needs-result expression (at least one platformsuccess, neitherfailure, run not cancelled) instead ofif: success(), which evaluated false whenever one platform's build was skipped and left failure issues open (#10856).†‡ (#10859) - ✅
mobile.observability.sim-build-parallel-job— The iOS Simulator build (the unsigned.appE2E artifact consumed bymobile-e2e.ymlandmobile-ios-launch-smoke.yml) runs in its own parallelbuild-ios-simjob inmobile-build-native.yml, sharing onlyneeds: [preflight]with the signed-archivebuild-iosjob rather than running asbuild-ios's last serial steps. The sim build has no data dependency on the signed archive/export/TestFlight-submission path — it only needs the same expo-prebuild output (workspace/scheme/build number)build-iosalso produces — so serialising it behind the signed archive, three #10831 dSYM release gates, and Sentry symbolication added ~26 minutes to the TestFlight-submission critical path on every automatic uat push for no correctness benefit (#10947, follow-up to #10933/#10940's decision to build the sim artifact on everypreview-profile push). The split is strictly additive to existing behaviour:build-ios-simpublishes the identical ios-app-sim-${{ inputs.profile }} artifact (unchanged name, 7-day retention,if-no-files-found: error) under the identicalif: inputs.profile == 'development' || inputs.profile == 'preview'gating —download-artifactresolves by run id, so the artifact only has to exist somewhere on the run, not specifically insidebuild-ios.close-successandreport-failureboth addbuild-ios-simto theirneeds:/if:guard expressions alongsidebuild-ios/build-android, so a sim-build failure is neither silently ignored (auto-closing an open failure issue while the sim build is actually broken) nor blocks issue-closing when the sim job legitimately skips (platform=androiddispatch, orprofile=production, which the sim build never runs for). Caveat — runner-capacity risk flagged at review, not yet resolved as of this AC:build-iosandbuild-ios-simboth declareruns-on: [self-hosted, mac-mini], and the org has exactly one runner carrying that label — so the two jobs may serialise on the same physical machine rather than genuinely overlap, which would not deliver the stated wall-clock saving. Tracked as an open/sge:pr-reviewblocker on PR #11924 pending either a secondmac-mini-labelled runner or a corrected claim.†‡ (#10947, #10933, #10940) - ✅
mobile.observability.healthkit-call-attribution— Every Apple HealthKit native read (mobile/ppp/lib/modules/health/services/healthKitReader.ios.ts) is preceded by a Sentry breadcrumb (category: 'healthkit.native_call') naming the exact HealthKit method about to be invoked. Sentry 122620667 (C++ Exception: N8facebook3jsi7JSErrorE) re-filed a sixth time (#10385 → #10563 → #10774 → #10964 → #11470 → #11555) on build 1786542780, an ancestor of #11498's fix commit, withapp_start_timeover 10 minutes before the crash timestamp andin_foreground: true— provably not the launch/bundle-evaluation window every prior fix in this lineage (#10397/#10835/#10855/#10990/#11498) targeted. Live Sentry API inspection of all 5 events on that build found every native thread fully symbolicated (dSYM upload is not the gap:has_debug_info/has_symbolsbothtrue) but no thread flaggedcrashed: trueand the exception's ownthreadIdnot resolving to any thread in the dump — a crash-attribution gap in the mechanism itself, not something a client-side JS/RuntimeScheduler patch can fix (there is nobeforeSendstripping data — none is registered inapp/_layout.tsx). The circumstantial (never proven) lead across the 5 events was a HealthKit native read live at the moment of the OS thread-dump, but a different HealthKit method each time, so it could not be promoted to a root cause without shipping a 7th blind guess. This AC is the instrumentation that turns the next occurrence, if any, into a provable answer instead of another guess.†‡ (#11555, #10385, #11470, #11498) - ✅
mobile.observability.ci-jobs-are-time-bounded— Every job in the mobile-relevant GitHub Actions workflows (mobile-cd.yml,mobile-build-native.yml,crash-reports.yml,crash-resolve.yml,code-quality.yml) carries an explicit job-leveltimeout-minutes, sized from that job’s observed successful runtime (skipped jobs excluded) with headroom — never a blanket value, because a timeout below a job’s normal runtime converts a cost problem into a reliability problem. Without one a job inherits GitHub’s 360-minute default, so a wedged run bills up to $2.16 on its own and holds a concurrency slot for six hours; the weeklycode-quality.ymlreport and the hourly crash-report autofile are exactly the unattended jobs where such a hang would go unnoticed. (#12038) - ✅
mobile.observability.quality-baseline-never-silent-zero— Every duplication (jscpd) and dead-code (knip) metric incode-quality.yml— in both themobile-code-qualityjob (#11029) and the rootcode-qualityjob (#11130) — and every circular-dependency (madge) metric in themobile-code-qualityjob reportsn/aplus a::warning::when the tool did not run, never0. Each step is gated on a measured "the tool ran" marker: madge on^Processedon stdout (present in both the cycles and the no-cycles case, absent on failure — an empty-stdout test is NOT sufficient, because a missing-path failure writes 174 bytes of error text to stdout); jscpd on the existence of its report file; knip on either a section headerWords (N)or exit 0 with no output at all — neither half works alone, becausepnpm dlxfailing to fetch exits 1, the same code as a findings run, while a genuinely spotless knip run prints nothing. The knip marker matches any section header rather than theUnused files|exportspair hardcoded inscripts/knip-reconcile-regression.mjs(which can hardcode it only because it passes--include files,exports); narrowing it would report "did not run" for a real run that found only unused dependencies, discarding a true count exactly when the files/exports backlog has been cleared. The two pre-existing root madge steps deliberately keep a numeric output (theircountfeedstotal=$((…))and a-gt 5report comparison, both of which break on a non-integer) and instead emit a per-side::warning::naming the total as a lower bound — a stated, accepted residual gap, not an oversight. The rootcode-qualityjob's jscpd and knip steps carry the same two gates as their mobile counterparts (#11130): jscpd on its report file existing plus an unparseable-report branch, knip on a section header or exit 0 with no output. Root jscpd mattered more than the mobile one because itspctis the only one of these metrics that feeds a threshold: the tech-debt report's>10/>5duplication cell piped the value throughbc, which coerces a non-numeric string to a passing✅ OK, so a jscpd that never ran rendered a green duplication gate. That cell now tests for then/asentinel before anybccall and renders⚠️ Unknown; the knip summary-table fallbacks likewise becomen/arather than0. Root madge keeps its numeric-0residual unchanged — the accepted gap above is unaffected by #11130. Becausecode-quality.ymlruns weekly and is therefore never exercised at PR time, the markers are guarded by PR-time tests that extract each step's realrun:script from the workflow YAML and execute it against stubbed tools.†‡ (#11029, #11010, #11130)
Stability & release gates (#10828)
Engineering-derived stability requirements from the #10649 JSI/Hermes launch-crash lineage (epic #10828: make the JSI-crash class un-shippable). Four legs of the epic are already specified above under Observability and are not re-minted here: the symbolication release gate mobile.observability.dsym-release-gate (#10831), the floating-promise lint gate mobile.observability.floating-promise-lint-gate (#10829), the release-gate-script PR CI coverage mobile.observability.release-gate-scripts-pr-ci (#10859/#10872), and the keychain fail-loud guard mobile.observability.keychain-signing-guard (#10854). No crash-free-session percentage target is claimed anywhere in this section: Sentry release health reports the rate per build (enableAutoSessionTracking, #10773), but a numeric threshold is a product decision — see Open Question 4.
- ✅
mobile.stability.launch-lifecycle-contained— Cold launch → foreground → background → foreground of an authenticated session must not crash the app. The #10649 class — an uncaught async rejection in the launch/foreground burst that RN 0.76.9 + New Architecture + Hermes escalates to a nativeSIGABRT(cpp_exception,handled:false, zero JS frames, below the JS-handler layer so the #10397 ErrorUtils backstop structurally cannot fire) — is contained by the two shipped #10835 layers. Layer 1 (root cause): every async site reachable on launch/foreground guards its rejections —rearmGeofencesIfReadycan never reject (top-level try/catch reporting a Sentry stack + a bounded App Insights category per the #8372 pattern, returning a safe{ armed: false }), and the formerlyvoid-floated call sites (app/(tabs)/_layout.tsxlaunch + foreground re-arms — the primary defect, sincevoiddoes not catch rejections — plusAppUpdateGateevaluate, the OAuth deep-link handlers, and theuseLocationTrackingAppState listener) carry call-site.catch/top-level guards. Layer 2 (containment):patches/react-native+0.76.9.patchbackports RN 0.77's RuntimeScheduler error-propagation hardening — a non-JSErrorC++ exception inexecuteTask/performMicrotaskCheckpointis caught and reported, andJsErrorHandlerreports non-fatally on the runtime-ready path, so an uncaught async error is reported-and-survived with a JS stack instead of aborting the process. Layer 2b (#11470) — the pre-runtime-ready window:_isRuntimeReadyis false untilReactInstance::loadScriptfinishes evaluating the JS bundle, so Layer 2's runtime-ready branch does not cover module-scope bundle evaluation or the microtasks it schedules; an uncaught rejection from that window fell through to the fatal C++ pipeline (parseErrorStack(error, /*isFatal=*/true, …)→ParsedError.isFatal→RCTInstance.mm _handleJSError→ abort) and still aborted. That fallback now passesisFatal=false, so the launch window reports-and-survives like the ready path;hasHandledFatalError()is still set unconditionally, so theReactInstance.cppdrop-work guard still stops further JS work on a genuinely broken bundle. Both halves are pinned as required markers in.github/scripts/verify-native-patches.mjs— either alone leaves half the launch fatal. The class stays un-shippable via the@typescript-eslint/no-floating-promises(ignoreVoid: false) lint gate — seemobile.observability.floating-promise-lint-gate(#10829) above for the full gate contract.†‡ (#10649, #10835, #10829) - ✅
mobile.stability.launch-burst-gate— A CI job (release-crash-scaninmobile-ios-launch-smoke.yml) reuses the Release-config, New-Architecture iOS Simulator artifactmobile-build-native.ymlalready builds (xcodebuild -configuration Release -sdk iphonesimulator;app.config.jssetsnewArchEnabled: true) — no second build. It signs in as the seeded e2e account, which the backend seeder links to the geofence test hospital so the assigned-hospitals launch fetch (the #10649 dup-storm surface) actually fires, then drives the authenticated launch-burst Maestro flow (e2e/launch-burst.yaml):login.yamlentry, then 3× (background → authenticated cold-launch, noclearState→ppp://deep-link foreground re-entry), then a final relaunch — every cycle asserts the authenticated dashboard and that the login form does not reappear, so a signed-out relaunch cannot pass. The run is wrapped in the existing.ipscrash-scan harness (e2e/maestro-crash-scan.ts, #10416):classifyMaestroResultgives a new attributable crash report precedence over Maestro's own exit code, so the job fails on any new attributable.ipseven when Maestro itself reports success. The gate's ability to go red is proven by a negative-control suite (release-crash-scan-gate-workflow.test.mjs) that extracts this exact workflow step and executes it end-to-end against a stubmaestrobinary that drops a synthetic.ipsmid-run — wired into PR CI via thescripts-testsjob (mobile.observability.release-gate-scripts-pr-ci, #10859) so a regression here is caught pre-merge. The BDD scenario for this AC (mobile-stability.feature) is un-skipped with real source-contract assertions. Caveat — first real run is still outstanding: the simulator job cannot execute in PR CI (it needs the mac-mini runner + auatbuild artifact), so this AC is verified by source-contract + negative-control tests only; the gate's first genuine execution — build succeeds, the authenticated flow runs, zero attributable.ips— is an explicit post-merge dispatch obligation tracked on #10828/#10833 (gh workflow run mobile-ios-launch-smoke.yml --ref uat, jobrelease-crash-scan). Resolver hardening (#12310): bothlaunch-smokeandrelease-crash-scanresolve their target build viaresolve-ios-smoke-run.sh/resolve-mobile-build-run.shrather than treating "no successful run has a live artifact" as one undifferentiated failure.mobile-cd.yml'sNative Build + Submitjob is legitimatelyskipped(notfailure) on every automatic uat run where nomobile/ppp/**change has landed since the last build (#11149's once-daily schedule); the old inline resolver could not tell that apart from a build that genuinely ran and failed to produce an artifact, so it fired::error::red on essentially every no-change day.resolve-ios-smoke-run.shinstead inspects theNative Build + Submitjob's own conclusion via the Jobs API across recent runs: all-skippedresolves to a cleanstatus=skip(both jobs exit 0 with nothing to test, via askipjob output threaded through every downstream step'sif:), while a genuinely failed build job, or asuccessbuild job that still left no live artifact (an upload-step failure), still fails the gate loudly, naming the run.†‡ (#10830, #10828, #12310) - ✅
mobile.stability.crash-triage-dedup— The crash-feedback triage loop is idempotent and dedup-aware end-to-end, so a crash surfaces as one actionable GH tracker, not an unbounded stream of duplicates: (1) TestFlight crash/screenshot feedback auto-files with marker-based create-or-comment dedup (seemobile.observability.testflight-feedback-autofile, #10175); (2) the Sentry sweep (crash-reports.yml) dedups with fix-date awareness across open and closed trackers — a crash whose occurrence (Math.maxof its own build identity,dist, when available — see below — and Sentry'slastSeen, falling back tolastSeenalone wheneverdistis absent or unparseable, and toregressedwheneverlastSeenitself is absent or unparseable (distraises the occurrence time, it never substitutes for a missing one, #11245)) predatesfixMergedAtis treated as fixed and not re-filed, while an occurrence strictly afterfixMergedAt— or a closed tracker with no traceablefixMergedAtat all (unknown fails toward visibility, #11004) — re-files as a regression (#10539, closing the #10445 indefinite-re-file loop).fixMergedAtis resolved from an explicit<!-- crash-fixed-by: #NNNN -->marker a human adds to a closed tracker's body, naming the PR that actually fixes the crash — never inferred. Two prior designs both inferred it and both were wrong on live data: the tracker's ownclosedAt(#10539 — an administrative timestamp, not evidence fixed code shipped) and, after #11095's first correction, GitHub'sclosedByPullRequestsReferences(which PR's merge triggered the tracker's auto-close — a keyword-matching fact, not a causal one). Both silently classified the still-live iOS JSI launch crash (Sentry 122620667) "fixed" while it kept recurring 80 hours after the real fix (#10835) had already merged:closedAtbecause tracker #10964 happened to be closed 87 minutes after that later occurrence, andclosedByPullRequestsReferencesbecause #10964 was actually closed by an unrelated PR (#10991, a CI change, merged one second before that sameclosedAt) — re-deriving the live GitHub data during #11164's review found the two signals landed within the same window and produced the same wrong answer. The redesign (#11164, correcting #11095's own first attempt) requires the explicit marker instead, and folds the crash occurrence's own build identity (dist— this repo's epoch-seconds mobile build number, shared by iOSIOS_BUILD_NUMBERand AndroidVERSION_CODE, #4721/#9950) into the occurrence side asMath.max(dist, lastSeen)— a specific build's identity is stronger evidence of "which code this binary contained" than Sentry's ingestion wall-clock, butdistis Sentry-supplied and therefore attacker-influenceable through the same public-DSN ingestion pathsanitize_crash_fielddefends, so it may only push the verdict towardregressed(visible), never towardfixed(silent);lastSeenis a hard floor (#11196).distnow reaches the classifier on live data (#11252) — until then it did not, and the distinction is the point:classifyDedupStatushad accepted adistargument since #11164, butcrash-reports.ymlnever supplied one, because the Sentry latest-event fetch (the only response carryingdist) ran after the dedup decision and only for issues already destined to be filed. The branch was exercised by unit tests and never once by production data — a well-tested function wired to nothing, which no amount of testing that function could reveal. The fetch now runs before the decision (it only populates variables; every consumer still runs after it, so anopen/fixedissue still exits without filing),distis sanitized like every other Sentry-supplied field, and a literal"null"string is normalised to empty at the source. A workflow-extraction suite (crash-sweep-dist-wiring.test.mjs) executes the step's realrun:script under bash with stubbedcurl/gh/nodeand asserts on the payload the shipped shell actually builds, so the caller is gated and not only the classifier; and (3) closing acrash-labelled tracker triggerscrash-resolve.yml, which marks the underlying Sentry issue resolved so the sweep drops it from theis:unresolvedquery entirely (#10542; the resolve step no-ops with a clear message until theSENTRY_RESOLVE_TOKENwrite-scope secret is provisioned — it never fails the run). The same close event also posts an adoption nudge for the marker the whole loop depends on: acrash-labelled tracker closing with no<!-- crash-fixed-by: #NNNN -->marker in its body draws a comment asking for one, landing while a human is already looking at the ticket rather than only in the auto-filed footer at filing time (#11195). The nudge is fail-soft — aghfailure warns and exits 0 so the Sentry resolve above still runs — and idempotent across reopen/reclose cycles (#11260):issues: closedre-fires on every close, so the body-marker condition alone would post one duplicate nudge per cycle, unbounded. Every nudge therefore embeds a hidden<!-- crash-fixed-by-nudge -->marker and the step sweeps the issue’s existing comments for it before posting. The guard is structural, not prose-matched — rewording the nudge text cannot silently disable it, and an ordinary human comment quoting thecrash-fixed-by:convention (which is exactly what people write on these trackers) cannot suppress a real nudge. It is deliberately not keyed offgithub.event.issue.state_reason, which says why this close happened and cannot distinguish a first close from an Nth. The body-marker check still runs first, so an already-marked tracker costs no extra API call; the onegh issue view --json commentsis paid only on trackers that were going to be nudged. On a failed comment read the step posts anyway with a::warning::— a read failure proves a prior nudge neither absent nor present, and skipping on an unproven negative would lose the nudge entirely on a tracker’s only close, whereas the cost of guessing wrong the other way is one duplicate advisory comment. The sweep's degradation is observable on every path, not only the ones keyed on HTTP status (#11020): an HTTP 200 whose latest-event bodyjqcannot parse (an upstream HTML error page, a truncated response, an empty body) is warned about before it is normalised to{}, because that path otherwise produced exactly the blank report a failed fetch produces — App versionunknown,(stack trace unavailable),environment:unknown— with zero signal in the run log, indistinguishable from "no crashes". The warning is guarded by the samejq -etest that does the normalising, so a healthy 200 never trips it and the instrument does not cry wolf.††††††‡ (#10445, #10539, #10542, #11020, #11095, #11195, #11196, #11260)
Background tracking & geo-fencing
- ⏳
UIBackgroundModes: ['location', 'fetch']remains set inapp.config.js - ⏳
expo-locationlocationAlwaysPermissionremains requested with accurate copy - ⏳ Region-monitoring (not continuous GPS) is used so battery drain stays bounded — see
timesheets.md§§ background policy - ✅
mobile.geofence.always-location-nudge— When onboarding grants foreground but not background location, a non-blocking "Always" nudge offers Open Settings or Not now.†‡ (#8406) - ✅
mobile.onboarding.permission-button-pending— During each acceptance-onboarding permission step, the primary action button shows a spinner and is disabled while the async OS permission prompt is in flight, so a double-tap cannot re-prompt or skip past the step before the first request resolves (#9330).AcceptanceOnboardingtracks a singlependingPermissionstate across the location / health / notifications handlers (each guarded against re-entry and wrapped intry/finally), passed toOnboardingStepaspending; the button swaps its label for anActivityIndicator, setsaccessibilityStatedisabled+busy, and disables the Skip link too. The same step also raises the Skip link to a ≥44pt touch target (min-height 48 +hitSlop) and makes the inline Privacy Policy link a realPressablecontrol (#7773) instead of a bareonPresson inlineText. Unit-tested inAcceptanceOnboarding.test.tsx(pending-state suite — spinner shows, button disabled, double-tap fires the request once).†‡ (#9330) - ⏳ On Android, the "all the time" permission prompt is triggered after core onboarding, not on first launch (avoids rejection)
- ⏳ Background geo-fence events reach the backend even when the app has been force-quit by iOS / killed by Android battery optimiser — this is the critical success criterion Matt cares about
- ⏳ 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 (#4893). Narrow exception (#10431): the persisted queue is capped at
MAX_QUEUE_SIZE=200entries with FIFO eviction of the oldest entry once at capacity — a defensive bound against unbounded RAM growth, not a general relaxation of the "no silent drop" guarantee. Reaching the cap requires weeks of continuous offline geo-fence crossings; seetimesheets.geofence.offline-queue-boundedfor the full AC.† - ✅
mobile.geofence.auto-timesheet-native-test— Entering an assigned-hospital geo-fence triggers auto-timesheet creation, verified unattended via Maestro (mobile/ppp/e2e/native/geofence-auto-timesheet.yaml) against a deterministically seeded geo-fence hospital (mobile/ppp/e2e/native/seed-hospital.json) — no per-environment coordinate secret (#7669) - ✅
mobile.geofence.smart-geotag-button-native-test— The separate manual button-tap path (SmartGeoTagButton/useSmartGeoTag/processSmartGeoTag) — distinct from the passive background geofence path above — is verified unattended via Maestro (mobile/ppp/e2e/native/smart-geotag-button-tap.yaml) against the same seeded hospital, asserting the on-device app never regresses to the false "Add a workplace location in My Profile" warning that Matt and the QA seed accounts hit on UAT. RequiresWebView.tsx'sgeolocationEnabledprop (Android-only; without itnavigator.geolocationinside the embedded SPA always rejects, which would make the assertion pass vacuously — caught by PR review) and asserts a positive terminal outcome before checking the false-positive is absent, so a silently-broken tap fails loudly instead of proving nothing (#10124, #10115, #10125) - ✅
mobile.geofence.trpc-client-path-chain— The module-leveltrpcClientsingleton (used bysetupHospitalGeofences,resolveTrackingAccuracy, andbackgroundLocationTaskHandlerinlocation-service.ts) correctly preserves the full tRPC path chain so calls such astrpcClient.ppp.getUserAssignedHospitals.query({userId})andtrpcClient.ppp.timesheets.create.mutate({...})resolve without throwing "Cannot read property 'query' of undefined".†‡ (#9722) - ✅
mobile.geofence.audit-trail-write—backgroundLocationTaskHandlerwrites ageo_fence_eventsaudit row (geoFenceEvent.recordEntryon entry,geoFenceEvent.logExiton exit) alongside its existingtimesheets.source='geofence'draft-timesheet write —geo_fence_eventswas previously never written by the shipped mobile client despite the backend procedures existing, leaving the audit/dwell trail permanently empty. Both calls are best-effort: caught and logged, never blocking the timesheet write. Seetimesheets.geofence.mobile-writes-audit-trailfor the full backend contract. † (#9257) - ✅
mobile.geofence.events-coordinate-free— Mobile geo-fence events are coordinate-free on the wire:backgroundLocationTaskHandlersendsworkplaceId, entry/exit timestamp, and (since #11100) an optional derivedverification.distanceMeters— never a coordinate, and neverwithinGeofence(mobile omits the verdict; seetimesheets.geofence.verification-result-persisted) — and the backend input schemas (recordEntryInput/recordExitInput) accept no latitude/longitude fields at any nesting level — raw GPS coordinates are never persisted server-side on any geo-fence path. Server-side,geo_fence_events.latitude/longitudewere dropped and existing values purged (including theaudit_logJSONB row-snapshot copies) by #10880, with derived verification data (distance from the geofence centre, and — web-only — within-geofence status) replacing them. This is the DPIA-4 data-minimisation posture: the published privacy notices say coordinates are not stored, and the system now matches them. Restates and hardens the existing App Insights telemetry rule above (hospital id + event type only, never raw coordinates) at the persistence layer.†‡ (#10827, #10880, #11100, #11124) - ✅
mobile.geofence.reauthorization-after-update— On app launch (once a user + completed acceptance onboarding are present, and the app is in the foreground — a geofence background relaunch defers the check to the first 'active' viauseForegroundReady, while the geofence re-arm still runs in the background, #12520), the app re-evaluates location authorisation and, whenever it is insufficient for Smart-GeoTag (foreground denied, Android precise-location toggled off, or iOS downgraded from "Always" to "While Using") and not already dismissed for the current app version, shows a native prompt naming the affected feature and offering "Open Settings" (deep-links viaLinking.openSettings) or "Not now". Sufficient authorisation never prompts and clears any stale dismissal. A "Not now" dismissal is scoped to the current app version only. The very first check ever on a device (fresh install, just-completed onboarding, or the first launch of the build that ships this fix for an existing user) is a one-launch grace that never prompts; every check after that re-prompts on every launch where the gap persists and is undismissed — not gated on detecting an actual version change. That design choice is deliberate, not an oversight:getCurrentAppVersion()reads the marketing app version (app.config.js'sversion, release-please-bumped), whichmobile-build-native.ymlbumps "only for a real app release" — the per-build identity Apple/Google actually use to distinguish TestFlight/Internal-Testing builds (CFBundleVersion/versionCode, derived from epoch seconds) is not exposed throughexpo-constants. A version-change-gated design (the first draft of this AC, caught in PR review before merge) would almost never arm across the exact TestFlight update cadence Matt reported against — re-introducing the silent-inertness bug this AC exists to fix, one layer deeper. Reading the real per-build identity instead requires promotingexpo-applicationto a direct dependency (a lockfile change) — done by #11150, which promoted it and keys its own post-update re-arm onApplication.nativeBuildVersion(seemobile.geofence.update-rearm). This AC's own dismissal scoping still uses the marketing version and is unchanged; re-keying it onto the build identity is now unblocked but deliberately out of scope for #11150 (one PR per concern). Deliberately separate frommobile.geofence.always-location-nudge(#8406) above, which is onboarding-time-only and never prompts after first setup; this is the missing after-update prompt owner, ref-guarded inapp/(tabs)/_layout.tsxto fire at most once per mounted session so it cannot spam the Alert on unrelated re-renders.†‡ (#10913) - ✅
mobile.geofence.location-inactive-banner— the native Timesheet screen renders a persistent, passiveLocationInactiveBannerabove its WebView whenever location authorisation is insufficient for Smart-GeoTag, so a doctor who dismissed themobile.geofence.reauthorization-after-updatelaunch prompt still has a visible, on-screen reason when an expected automatic timesheet never appears — Matt's device sent zero geofence events for five days (17–22 Jul) before he noticed by chance (#10912). The banner reusesevaluateLocationAuthorizationGap/getCurrentLocationAuthorizationGapand the existing gap-specific copy fromgetLocationReauthorizationCopy(both #10913) rather than inventing new wording, so it can never overclaim: it renders only when the gap is genuinely non-'none'and is silent whenever authorisation is sufficient. It links to OS Settings viaLinking.openSettings(), matching theLocationAlwaysStep(#8406) precedent. Dismissing it is component-local React state only — never persisted to storage — so the dismissal is session-scoped and clears itself on the next app launch (never permanently hideable), deliberately separate from the launch prompt's version-scoped persisted dismissal, which is a different concern. The banner makes no claim that timesheets ARE working when authorisation is sufficient — the server-side "shifts open and never close" defect (timesheets.geofence.*, tracked under #10925) is an orthogonal failure mode this banner is silent about. Mirrors the established in-progress-state banner language of the webShiftRunningIndicator(timesheets.dashboard.shift-running-indicator, #10205), translated to the mobileBRANDtokens — no new colour, font, or icon primitive introduced. †‡ (#10920) - ✅
mobile.geofence.update-rearm— After an app update, background geo-fence monitoring re-arms on the first launch of the new build, with no user re-engagement — the doctor does not have to walk the intro screens or re-accept anything for arrival/exit detection to work again. Root cause: an update replaces the binary, so the OS drops the geo-fence regions the previous build registered, and every pre-existing re-arm trigger requiredapp/(tabs)/_layout.tsxto be mounted ('launch'and'foreground'are its own effects;'token'fires only on a fresh sign-in, which an already-signed-in doctor never hits) — so nothing re-armed until the doctor opened the app, leaving the whole update-to-next-open window unmonitored. The onboarding flags were not the cause:hasCompletedOnboardingandhasCompletedAcceptanceOnboardingboth persist in MMKV and survive an update untouched; walking the intro merely happened to be what got the doctor as far as the tabs layout. The re-arm is keyed on the native build identity (Application.nativeBuildVersionfrom expo-application —CFBundleVersion/versionCode, whichmobile-build-native.ymlderives from epoch seconds and patches into the native project for every build), not the rarely-bumped marketing version — this closes the follow-upmobile.geofence.reauthorization-after-update(#10913) left open, by promotingexpo-applicationto a direct dependency (pinned~6.0.2, the version pnpm had already resolved transitively viaexpo-notificationsandexpo-router, so the lockfile gains only the direct-dependency entry and no version resolution changes). An earlier draft of this AC read the identity fromConstants.nativeBuildVersionto avoid that lockfile change; that field does not exist — expo-constants removed it in favour of expo-application — andexpoConfig.ios.buildNumberis equally empty because CI patches the native project, neverapp.config.js. Both resolve toundefinedon a real device, so the identity was permanentlynull: the fail-safe held and the guard still re-armed, but on every launch and background wake, making the hospital fetch unconditional and every telemetry reason reportfirst-run. Nor may expo-application be imported as a phantom hoisted dependency just becausenode-linker=hoistedmakes that resolve — that is the #10883 / #10921 failure class. It delegates throughrearmGeofencesIfReady('foreground')deliberately: that service's per-session latch keys on the access token, which an update does not change, so the'launch'/'token'triggers would be suppressed asalready-armedin precisely this scenario. Only a genuinearmedresult records the build, mirroring the #8561 do-not-latch-a-skip discipline — recording a build whose regions were never installed would make the next check skip it assame-buildand silently reinstate the dormancy. A second, opportunistic path registers anexpo-background-taskworker that may re-arm while the app is still closed, narrowing the window further; iOS decides whether it ever runs, so it supplements the launch re-arm and never replaces it. Notification handling is covered by the same fix —NotificationProvidermounts inside the same tabs layout, so it was dormant for the same reason. In-flight timesheet continuity needed no change: the open entry is held server-side as adraftand re-read via tRPC, so it has no client state to lose across an update once geo-fences are re-armed. Scope is #11150 only — this never authenticates and never prompts, leaving #11427's combined post-update login/Face-ID/geotag friction untouched.†‡ (#11150)
Push notifications
✅ When the persistent OS dwell notification fires while the app is alive,
NotificationContextcallsmarkDwellNotificationFired— exactly onetimesheet-auto-creatednotification is delivered per dwell event, not two⏳ Expo push token registers on launch and on login
✅ All in-app notifications also fire as push notifications (see
notifications.md)⏳ Notification tap deep-links to the correct in-app route
✅ Push token registration failures are logged to App Insights, not silently swallowed
✅
mobile.notifications.push-token-persisted— the Expo push token obtained on the device is sent to the backend and stored, so server-side pushes have somewhere to deliver to. Persisted viauserNotificationToken.save(an authenticated, user-scoped procedure) once the token, a valid session, and a resolved user id are all available — those arrive independently and in either order, so whichever lands last triggers the save; an unchanged token is not re-sent on re-render, and the backend write is an idempotent upsert on(userId, platform). The save is dispatched throughfireAndForget, never as a floating promise: under RN New Architecture + Hermes an unhandled rejection escalates to a native process abort (#10649/#10829), so a failed token save must never crash the app. Before this the token was fetched and held in React state and nothing else —saveNotificationTokenhad zero production callers,user_notificationsstayed empty, and every server-side send short-circuited on "No notification tokens found": UAT logs over the full 30-day retention show 247 send attempts, 247 missing-token misses, 0 delivered, across 30 distinct users and every notification type, with no successful send ever recorded. Note this is a distinct failure from the ✅ AC directly above — token acquisition failures were correctly logged; the token was acquired successfully and then simply never transmitted, which is why the outage was invisible to that telemetry. Guarded by Jest (NotificationContext.test.tsx§"#11491 push token persistence", which drives the real provider and asserts the mutation payload) and a BDD@regressionscenario that executes those tests rather than inspecting source text — source inspection could not have caught this, since every individual piece was present and green and only the call between them was missing.†‡ (#11491, refs #11426)✅
mobile.notifications.push-token-single-owner— a device push token belongs to exactly one user at a time. An Expo push token identifies an installation, not a person: the same device reissues the same token to whoever logs in next, and logout is local-only (nothing is deregistered server-side).saveNotificationTokentherefore releases the token from any other user before binding it to the caller, anduserNotificationToken.saveresolves the caller's own id viagetSelfUserIdrather thanenforceUserScope, ignoring the client-supplieduserIdentirely. Both defects were reachable only once the client→backend wire in the AC above existed (saveNotificationTokenhad zero production callers before it). Without the release, the unique index on(user_id, platform, token)— three columns — lets(A, ios, T)and(B, ios, T)coexist, andsendPushNotificationselects every row for auserIdwith no cross-user check, so user A's notifications (carrying timesheet and hospital identifiers) would render on user B's lock screen indefinitely. Without thegetSelfUserIdswap,enforceUserScopereturns the client-supplieduserIdunchanged for super-admin callers, letting an admin bind a token to another user's account; registering a device is purely self-referential and has no legitimate admin use case. Token input is bounded to thevarchar(500)column width. Guarded by a real-database integration suite (sharedDeviceTokenScope.integration.test.ts) rather than a mocked one — the collision is a property of what the real three-column index permits, and a Drizzle mock chain has no index — plus a BDD@regressionscenario that executes that suite. Verified by mutation: reverting the release makes the suite report 2 rows for one token and user A still holding a route to the device. This suite runs in CI:.github/workflows/integration-tests.ymlexecutes the full*.integration.test.tsset (including this one) on every push touat, nightly, and on dispatch — a workflow-name grep for thetest:integrationscript had missed it (that workflow invokes vitest directly), which produced and then #11527 corrected a false "runs only locally" claim. Only the boundedintegration-smokesubset gates the PR itself pre-merge; this suite's protection lands post-merge.†‡ (#11491, refs #11507)✅
mobile.notifications.push-token-released-on-sign-out— signing out releases this device, so the signed-out user stops being reachable on it. The AC above self-heals a shared device on the next sign-in (the save releases the token from any other user), which is what closes the cross-user disclosure; it does nothing in the window where a user signs out and nobody logs in after them. In that window the backend still holds a live row for them andsendPushNotificationkeeps fanning their clinical content to a handset sitting on the login screen. That is a hygiene/least-privilege gap rather than disclosure — the device is with its own prior owner — which is why it is a separate AC rather than a correction of the one above. The release is scoped to(userId, token):userIdis the caller, resolved from the session by aderegisterprocedure that accepts no client-supplied id at all, so nobody can deregister another user's device;tokenkeys on the single device signing out, so a doctor signing out on a ward tablet keeps push working on their own phone. Dispatched throughfireAndForgetfor the same Hermes reason as the save (#10649/#10829) — sign-out must never be blocked or crashed by it. Best-effort by design: the call needs the session being torn down so it can lose that race, and an offline sign-out cannot reach the server at all; both are accepted because the save-path release remains the backstop. Guarded by the same real-database integration suite plus Jest tests driving the real provider, and a BDD@regressionscenario that executes them. Verified by mutation, not inspection: widening the release totokenalone (dropping theuserIdpredicate) turns the cross-user guard red — that is the dangerous mutation, since it would let one user's sign-out knock another user off push, and no mocked assertion can see it; removing the mobile effect turns 3 of the 5 new Jest tests red. Note the pre-existing suite was proven blind first — with #11491's cross-user release removed entirely, the mockedindex.test.tsstayed 7/7 green, so the behavioural assertions deliberately live in the integration suite.†‡ (#11507)⏳
mobile.notifications.apple-watch-mirror— Apple Watch direction (feasibility spike, #9198). Matt chose option 2 — notifications PLUS a glanceable wellness/readiness complication — "with a user option to limit notifications". The engineering default is to mirror ALL PPP notifications to the Watch with a user-controlled filter that can narrow the stream. The current iOS build ships no watch target, so this AC stays ⏳: Phase 0 (this spike) lands an inert, dependency-free notification-mirror config scaffold —mobile/ppp/lib/config/appleWatch.tspins theWatchNotificationCategory/WatchNotificationPreferencecontract, themirror-alldefault (DEFAULT_WATCH_NOTIFICATION_PREFERENCE), and the pureshouldMirrorNotificationToWatch/matchesWatchFilterdecision (gated byAPPLE_WATCH_ENABLED = false, so the shipping app routes nothing to a non-existent watch app). The full feasibility assessment, phased plan and PLA constraints live indocs/site/mobile/apple-watch-feasibility.md: Phase 1 (Watch notification filter UI + phone-side category routing) needs no PLA and is the recommended first slice; Phases 2–3 (native watchOS app + WidgetKit readiness complication) require a native target reintroduced via an Expo config plugin and are blocked on Apple PLA acceptance (the same gate as HealthKit / the bare-"PPP" name, #9199). The Phase 1 preparatory slice has landed (#10068): a persistedWatchNotificationPreference(mobile/ppp/lib/services/watchNotificationPreferenceStore.ts, defaultmirror-all), a phone-sidenotificationType → WatchNotificationCategorymapping (categoriseWatchNotification), and a Settings "limit to Watch" control — all still inert, gated hidden behindAPPLE_WATCH_ENABLED = false(the same "never offer a control the OS can't honour" rule as the biometric toggle, #10014), so the shipping app is byte-for-byte unchanged (noapp.config.js/native/dependency/build change). The AC stays ⏳ because on-wrist delivery still needs a real watch target (flip the kill-switch + callshouldMirrorTypeToWatchfrom the notification path). On-wrist delivery is verified manually on physical hardware; the mirror-filter decision is Jest-guarded (mobile/ppp/lib/config/__tests__/appleWatch.test.ts,mobile/ppp/lib/services/__tests__/watchNotificationPreferenceStore.test.ts,mobile/ppp/lib/modules/settings/screens/__tests__/SettingsScreen.test.tsx) and source-inspection-guarded in BDD.†‡ (#9198, #10068)
Security / access control
- ✅ Development tab (
app/(tabs)/development) and itsAddAuditEventsub-route are gated on__DEV__— they render nothing and redirect to the dashboard in production builds - ✅
react-native-fsis mocked inmobile/ppp/jest.setup.tsso theDevelopmentScreengate test (and any other test transitively importingreact-native-webview) does not crash onNativeEventEmitterwith a null argument - ⏳ Replace the hardcoded-email admin gate on Settings (
user.email === 'admin@professionalperformanceportfolio.com') with a proper role flag shared with the backend (#4891) — current gate is an anti-pattern and blocks extending the same check to Development
Auth
- ✅ Session token is read from the auth cookie, not re-derived from WebView state
- ✅
mobile.auth.native-token-bridge— Inside the native shell, once the web SPA confirms the session it mints a mobile token and hands it to the native shell via thesessionTokenbridge on every authenticated load, so the native geofence/timesheet client can authenticate on iOS.†‡ (#8341) - ✅ Login WebView is not remounted mid-flow
- ✅
mobile.auth.in-app-registration— New users can register from the mobile app: the first-install onboarding ends on a "Create my account" screen that opens the responsive web sign-up flow (/signup-process) inside the login WebView, the same adaptive screens as desktop. The app no longer directs users to register on a computer.†‡ (#8318) - ✅
mobile.auth.logout-bridge— The web avatar menu's Sign Out is the single logout path (the native blue-header logout was dropped in #8259/#8260). Tapping Sign Out posts alogoutCompletebridge message so the native shell clears its session immediately — no ghost session remains. Verified by Maestromobile/ppp/e2e/native/logout-bridge.yaml.†‡ (#8270) - ✅
mobile.auth.session-resync— The native session's cached expiry is resynced against the server via the real, already-workinggetMobileTokenprocedure (Bearer-authenticated with the current access token), and the session store is cleared only when the server authoritatively confirms the token is invalid (a genuine tRPC/Better-AuthUNAUTHORIZEDrejection — not merely a bare HTTP 401) — never on a resync attempt that merely could not be completed (no access token to resync, network error, 5xx, rate limit, or an unconfirmed 401). Root-cause fix (#10019):ppp.auth.refreshMobileTokenhas never existed on the backend and the mobile session store'srefreshTokenfield is alwaysnull(confirmed independently by #10032), so every previous proactive (5-min-before-expiry timer) and reactive (any-401-triggers-refresh) token-refresh attempt was guaranteed to fail — and on exhausting its 3 retries unconditionally wiped the entire session (accessToken/refreshToken/sessionExpiresAt/user), presenting to the user as an unexplained forced re-login with no explicit sign-out. Rate-limited under sustained failure (#10042): becausescheduleProactiveRefresh()only re-arms on a successful resync, a prolonged run of non-authoritative failures (5xx/network error, never a clean 401) leftisTokenExpiredOrExpiring()true indefinitely, so every subsequent tRPC call'sheaders()re-ran the full 3-attempt backoff viaensureValidToken()— up to ~7s of added latency per request. A 30s cooldown after a non-authoritative failure now short-circuits repeated resync attempts made within that window — but only the precautionary ones (the proactive timer andensureValidToken()'s pre-flight check before every tRPC call): a reactive refresh triggered bytrpcClient.ts's 401-retry handler, which fires only after a real business API call has already come back with a genuine 401, bypasses the cooldown (refreshAccessToken(true)), since an observed 401 is itself evidence the attempt is not precautionary. Gating that path too would mean an unrelated transient blip could suppress a refresh for a live, currently-failing user request — worse than pre-#10042 behaviour, which always tried. The remaining, deliberate tradeoff is narrower: a precautionary resync during the cooldown window won't itself notice a session has gone invalid until the cooldown elapses or a real 401 is hit on an actual request. Hardened (#10044): a non-401 resync failure no longer logs the response body (status code only — an auth endpoint's error payload has no reason to land in device logs/crash reporters), and a bare HTTP 401 is no longer trusted on its own:isGenuineAuthRejectionverifies the response body carries a real tRPCUNAUTHORIZEDerror code before the session is cleared, since an edge/proxy layer (Cloudflare/WAF/gateway) in front of the tRPC backend could in principle also respond 401, and trusting that unconditionally would reintroduce #10019's session-wiping bug in a narrower, edge-originated case.†††‡ (#10019, #10042, #10044) - ⏳ Logout clears the cookie and all local caches
- ✅
mobile.auth.biometric-unlock— After opting in, a returning doctor unlocks the app with Face ID / Touch ID (iOS) or BiometricPrompt (Android) instead of typing a password: the OS biometric read (SecureStore.getItemAsyncwithrequireAuthentication: true) IS the gate — a resolved stored session token means the prompt just succeeded, so no separate confirmation prompt double-fires it. On success that session token (the same mobile session token Better Auth already issues viagetMobileToken/the sign-in interceptor — long-lived, rolling, default 7-day expiry) is restored directly as the access token and the app opens straight to the dashboard, never showing the password form. Corrected mid-review (#10032): the original design gated this on a "refresh token" (data.refreshToken) that this codebase never actually issues — norefreshMobileTokenbackend endpoint exists, and the primary WebView login path hardcodesrefreshToken: null— so the feature could not activate in production despite passing tests (tests injected a synthetic value). Re-scoped to gate on the session token that genuinely exists instead, with no backend change required. A cancelled/failed prompt or a missing credential falls back cleanly to the existing passwordLoginWebView— never a dead end; a restored token that has actually expired/been revoked server-side is caught by the app's existing 401-retry and tab auth-guard handling, same as any other stale persisted session.††‡ (#10014, #10032) - ✅
mobile.auth.biometric-enrolment— After a successful password login, opted-out and first-ever-login users are offered a one-tap "Use Face ID / [Touch ID / Biometrics] to sign in next time?" prompt (never shown when already enabled, previously declined this install, or the device has no biometric hardware enrolled). Choosing "Enable" requires an explicit biometric confirmation (authenticateWithBiometrics) before the credential is ever persisted; "Not now" is remembered so the prompt does not nag on every future login. Gated on the session token (data.token), not the nonexistent refresh token — seemobile.auth.biometric-unlock. Engineering default pending Matt's answer to the open question on whether enrolment should be offered at first login (as implemented) vs. buried in Settings only — the Settings toggle (below) covers the latter regardless.†‡ (#10014) - ✅
mobile.auth.biometric-credential-storage— The session token used to re-establish a session after biometric unlock is written only toexpo-secure-storewithrequireAuthentication: true(iOS KeychainbiometryCurrentSet/ Android KeystoresetUserAuthenticationRequired,keychainAccessible: WHEN_UNLOCKED_THIS_DEVICE_ONLY) — never to AsyncStorage, a plain file, or the general encrypted-MMKV session persistence used elsewhere (stores/sessionStore.ts), which is gated only by device-unlock, not a fresh biometric check. This is deliberately a separate, narrower-scoped store for this one special-category credential. The non-secret "enabled"/"declined" UX flags live in the ordinary encrypted MMKV store since they carry no credential material.app.config.jsadds theexpo-local-authenticationandexpo-secure-storeconfig plugins (NSFaceIDUsageDescription, AndroidUSE_BIOMETRIC/USE_FINGERPRINT, SecureStore Android auto-backup exclusion) required outside Expo Go.†‡ (#10014) - ✅
mobile.auth.biometric-logout-wipe— Logout (logoutCompletebridge message), disabling the Settings biometric toggle, and GDPR Article 17 account erasure (performAccountErasure) all wipe the stored biometric credential — a signed-out doctor must re-enable biometric sign-in on their next password login rather than silently unlocking whoever's account was last active on the device.†‡ (#10014) - ✅
mobile.auth.dead-web-session-native-login— When the embedded web SPA inside an authenticated tab bounces to its standalone/loginpage (dead cookie session — the web 401 interceptor's full-pagewindow.location.assign('/login?reason=session-expired…')per#5044, or a client-sidenavigate('/login')), the per-tab WebView detects it and returns the user to the full-screen native login route via the existing logout pathway (/?logout=1) — the web login form must never render inside the tab shell (bottom tab bar visible, no privacy link — Matt's shake-report). Detection runs through two channels decided by one pure predicate (isWebLoginUrl, path-segment match only so a/loginburied in a?redirect=query can't false-positive): the nativeonNavigationStateChangeevent for full-page redirects, plus an injected URL-change watcher (MutationObserver +popstate, same technique as the login WebView) postingwebNavigationbridge messages for client-side redirects that fire no native navigation event on iOS WKWebView — the reported URL is untrusted WebView content and is only ever string-matched, never navigated to or evaluated. A once-per-instance guard stops the redirect re-firing while the tab shell unwinds. Crucially, arriving at the login route with?logout=1now skips the biometric fast-path (mobile.auth.biometric-unlock) — without that, the gate would restore the just-invalidated session token and bounce straight back to the tab shell in an endless Face ID → dashboard → login-redirect loop (this also fixes the pre-existing gap where a web avatar-menu sign-out could be undone by the biometric gate); the login route's existing logout handling then clears the native token and wipes the stored biometric credential per themobile.auth.biometric-logout-wipecontract. Inside a tab this signal is authoritative: the standalone/loginroute is unreachable for an authenticated user (safeInternalRedirect.tsforbids it as a redirect target), so its appearance always means the web session died.†‡ (#10862) - ✅
mobile.auth.session-survives-app-update— A doctor holding a still-valid stored session is signed straight back in on launch — including the launch that follows an app update — instead of being shown the credential form. The reported symptom was "an app update logs me out and loses Face ID enrolment", but no storage is lost across an update: the session token, the biometric-enabled flag and the onboarding flags all live in the one encrypted-MMKV store (mobile/ppp/lib/utils/storage.ts) behind a device-bound Keychain key, and#11475established the onboarding flags survive an update untouched — so the key is readable and the token is still present. The defect was that nothing read it:showPasswordFlowinitialised fromlogout === '1' || !isBiometricSignInEnabled()and never consultedisSessionValid(), while the mount-timecheckExistingSession()effect did call it and then onlydebugLog()ged the answer. A doctor who had never enrolled Face ID therefore met the login form on every cold start; an update is simply the next cold start, which is why it presented as update-triggered. The launch predicate now also restores a valid session, and the restore completes the same way the biometric path does (scheduleProactiveRefresh()+router.replace('/(tabs)/dashboard')) rather than leaving the user on the loading indicator. Precedence is unchanged:logout === '1'still beats both restore paths, permobile.auth.dead-web-session-native-login(#10862) — a logout signal means the token is dead, and restoring it would loop back through the tab shell. An expired token still falls through to the password form and is never navigated into the tab shell, where the auth guard would only bounce it out again.†‡ (#11230) - ⏳
mobile.auth.biometric-device-validation— The issue's "Works on physical iPhone (Face ID) and Android (fingerprint) — validated on the device rig" AC is not yet exercised on real hardware. The logic above is proven at the Jest level (mockedexpo-local-authentication/expo-secure-store); the actual OS Face ID/fingerprint prompt and Keychain/Keystore behaviour still need a pass on the iOS/Android device rig (go-ios/Appium/WDA — see the physical-device automation notes elsewhere in this repo) before this AC can move to ✅. (#10014) - ✅
mobile.auth.sso-system-browser— Native SSO sign-in (Google, Microsoft) runs the OAuth round-trip in the system browser —ASWebAuthenticationSessionon iOS / Chrome Custom Tabs on Android, viaexpo-web-browser'sopenAuthSessionAsync— never the embedded WebView. This is the whole point of the feature: Google and most providers reject OAuth inside an embedded WebView withdisallowed_useragentto prevent phishing, so the web SSO buttons (which callauthClient.signIn.social(), a full-page WebView redirect) would dead-end for mobile users. The native launcher (lib/services/nativeSsoSignIn.ts) builds the Better Auth/api/auth/sign-in/socialstart URL withcallbackURL=ppp://auth/sso/callbackandmobile=1, presents it in the system browser, and awaits the redirect. Apple SSO is out of scope (Developer PLA/credentials blocker) and is never offered natively — tracked separately.†‡ (#10212) - ✅
mobile.auth.sso-callback-deep-link— The OAuth callback deep-links back into the app via the registeredppp://custom URL scheme atppp://auth/sso/callback?code=<one-time-code>&provider=<p>, following the same established deep-link pattern as the Whoop/Garmin wellness OAuth callbacks (ppp://wellness/<provider>/callback).lib/utils/ssoDeepLink.ts(parseSsoCallbackUrl) parses it into a typed descriptor — a callback with no code yields anerrordescriptor rather than being silently dropped. The native SSO button normally receives the callback URL directly fromopenAuthSessionAsync's return value; a belt-and-bracesLinking-level handler in_layout.tsxalso parses the SSO callback for the cold-launch / foreground re-delivery case, exactly as the wellness OAuth handler does. Payload (the load-bearing design decision, hardened by #10233): the deep link carries a single-use, short-TTL exchange code — never the live bearer token — because on Android a customppp://scheme is hijackable by any app registering the same scheme, so a long-lived credential on the deep link is a materially higher-value exposure than a code that is worthless without a direct TLS exchange call. The native app immediately exchanges the code for the bearer token viappp.auth.exchangeNativeSsoCode(seemobile.auth.sso-code-exchange); the bearer token is the same valueppp.auth.getMobileTokenreturns, accepted onAuthorization: Bearer. The backend redirect that mints the code is implemented by a thin Express bridge in front of Better Auth: aGET /api/auth/sign-in/socialhandler intercepts only requests carryingmobile=1(the markerbuildSsoStartUrlsets), asks Better Auth for the provider authorize URL with our own backend return URL ascallbackURL(a trusted origin — never theppp://scheme, which Better Auth'strustedOriginsvalidation would reject), and after the OAuth exchange sets the session cookie, aGET /api/auth/sso/mobile-returnhandler reads that session, mints a one-time exchange code bound tosession.session.token(stored server-side keyed by the code's SHA-256 hash), and 302s toppp://auth/sso/callback?code=…&provider=…. Any request withoutmobile=1passes straight through to Better Auth, so the web OAuth flow (#10195) is untouched.††‡ (#10212, #10233) - ✅
mobile.auth.sso-code-exchange— The native SSO deep link carries a single-use, short-TTL one-time code, not the live bearer token, and the app exchanges it for the bearer over a direct TLS POST before establishing the session (#10233). The exchange endpointppp.auth.exchangeNativeSsoCodeis a rate-limited public tRPC mutation (it runs before any session exists — the code itself is the credential, mirroring an OAuth authorization-code exchange). The code is a 256-bit CSPRNG value, stored server-side only as a SHA-256 hash (a DB read alone cannot mint a session), with a 60-second TTL, and is invalidated on first use:consumeSsoExchangeCodedoes an atomicDELETE … RETURNINGso a replayed or intercepted code can never be exchanged twice even under a concurrent race, and a unique index oncode_hash(native_sso_exchange_codetable, migration0189_eminent_dazzler) enforces the single-use invariant at the DB layer. An expired-but-present row is deleted and reported asexpiredrather than honoured. Both cold-launch/foreground (handleSsoDeepLink.ts) and direct-return (NativeSsoButtons.tsx) paths perform the exchange; neither the raw code nor the bearer token is ever logged. Apple SSO remains out of scope (PLA blocker).†‡ (#10233) - ✅
mobile.auth.sso-return-flow-gate— The backend return legGET /api/auth/sso/mobile-returnis bound to the native OAuth flow it belongs to and rate-limited, so it cannot be driven as a standalone exchange-code oracle by any request that merely happens to carry a valid session cookie (#10232). Flow binding: the start handler (mobileSsoStartHandler) mints a short-lived, HMAC-signed flow nonce (ppp_sso_flowcookie —HttpOnly,SameSite=Lax,Secure, path/api/auth, 10-minute TTL) before redirecting to the provider; the browser carries that cookie through the whole OAuth redirect chain back to/mobile-return. The return handler rejects any request whose nonce is missing, malformed, tampered, expired, or signed under a different secret — redirecting toppp://auth/sso/callback?error=invalid_flowbefore any session lookup or code mint — and clears the nonce cookie on success (client-side only; the stateless nonce is not invalidated server-side, so a captured nonce can be replayed within its TTL but only up to the rate-limit cap below — the true single-use guarantee is per exchange code, at the DB layer,mobile.auth.sso-code-exchange). The nonce is self-contained (<random>.<expiryMs>.<HMAC-SHA256>signed withBETTER_AUTH_SECRET), so the check is stateless across container replicas and needs no DB; signing is fail-closed — with no secret, minting throws (the start handler falls to itssso_start_failederror path rather than proceeding un-gated) and verification returnsfalse. Rate limit: the return handler applies the samegetMobileToken-equivalent cap (thedefaulttier — 120 requests/minute), enforced with the Redis-backed (global-across-replicas) limiter and keyed on the verified nonce's random component — a stable, unguessable per-flow identifier a client cannot spoof (unlike anX-Forwarded-ForIP undertrust proxy: true), so an attacker can neither rotate the key for a fresh bucket nor pin a victim's key to starve their in-flight sign-in. The cheap in-process nonce verify runs first, so a nonce-less/forged flood is turned away (error=invalid_flow) before touching Redis or the DB; a valid-but-replayed nonce is bounded by the cap (error=rate_limited). Access-log / APM exposure finding (AC3, confirmed against the IaC): in this deployment the code-in-URL /Location-header exposure is theoretical, not realized — no repo-provisioned sink records/api/auth/sso/*query strings or response headers. There is no Express access-logger (nomorgan/pino-http; the SSO handlers log only{ provider }); Azure Container Apps forwards only container stdout/stderr to Log Analytics (appLogsConfiguration→ContainerAppConsoleLogs_CL) with no ingress access-log DiagnosticSetting; no Cloudflare Logpush is provisioned; and no APM SDK (App Insights/OpenTelemetry) is instrumented inapi/backend-ppp(the sole App Insights component is mobile-only and its connection string is never injected into the backend container). Residual real-world surfaces are limited to client-side browser/OS history and any Azure-internal ingress log the platform may retain outside this IaC.†‡ (#10232) - ✅
mobile.auth.sso-session-reuse— Establishing the Better Auth session from the SSO callback reuses the existing bearer-token mobile session path — it does not invent a new session mechanism. The shared helperlib/services/establishMobileSession.tswas extracted from the WebView bridge'ssessionTokenhandler so both the WebView sign-in path and the native SSO callback path run the identical side-effect bundle:setAccessToken,scheduleProactiveRefresh, geofence re-arm (rearmGeofencesIfReady('token')), data-residency logging (GDPR Article 32), acquisition telemetry (logEvent('mobile_token', { event: 'acquired', source }), discriminatedwebview_bridgevsnative_sso), and the optional biometric-enrolment offer — never duplicated inline across the two call sites. The WebViewsessionTokenhandler was refactored to call this helper with zero behavioural change (its full Jest suite passes unmodified).†‡ (#10212) - ✅
mobile.auth.sso-web-buttons-hidden-in-webview— Inside the bundled native WebView wrapper the web SSO buttons are not rendered.instances/ppp/src/components/SsoButtons.tsxnow early-returnsnullwhenisReactNativeWebView()(the'ReactNativeWebView' in windowsignal fromutils/export-utils) is true — before any provider query fires — so the buttons that callauthClient.signIn.social()(which would dead-end indisallowed_useragent) can never be clicked from within the wrapper. This is the correctness baseline the issue explicitly offers ("hide the web SSO buttons in the mobile wrapper until the native flow is wired"); native SSO is offered by the separate nativeNativeSsoButtonsaffordance on the login screen so the OAuth flow runs in the system browser, not anything WebView-adjacent. A plain browser?app=1session (no native shell, noReactNativeWebView) still shows the web buttons.†‡ (#10212) - ⏳
mobile.auth.sso-device-validation— The native SSO round-trip is proven at the Jest/Vitest level end to end: mockedexpo-web-browser, URL parsing, session establishment, web-button hiding (mobile side) and the backend bridge's decide/build helpers + deep-link shape (nativeSsoBridge.test.ts, which reconstructs the mobile parser's expectations so a redirect-shape drift fails CI). The backend redirect that mints and carries the bearer token is now wired (seemobile.auth.sso-callback-deep-link). What remains is exercising the actual system-browser OAuth flow — real Google/Microsoft consent screen andppp://auth/sso/callbackdeep-link delivery — on real hardware against a deployed UAT backend. Needs a pass on the iOS/Android device rig before this AC can move to ✅. (#10212)
Data refresh
- ✅
mobile.webview.pull-to-refresh— Native app data screens support the platform-standard pull-to-refresh gesture: pulling down from the top of a screen reloads the embedded WebView so the SPA re-fetches that screen's data, then the refresh indicator dismisses. Wired once in the sharedWebViewcomponent so every view-mode screen (Dashboard, Wellness, CPD, Logbook, Timesheet, and the rest) gets it from one place — iOS uses react-native-webview's nativepullToRefreshEnabledprop, Android (which the prop does not support in v13.x) wraps the WebView in aScrollViewplusRefreshControlthat engages only while the page is scrolled to the top, so in-page scrolling is preserved. The gesture defaults OFF onadd/editform screens so an accidental pull-down reload never discards unsaved input (an explicitpullToRefreshEnabledprop overrides the heuristic). The refresh indicator always dismisses on every terminal load outcome — success (onLoadEnd) and a failed reload (onError/onHttpError, e.g. offline, DNS, server 5xx) — so a pull-to-refresh while offline never leaves the user stuck on an infinite spinner they cannot dismiss. Matt (UAT, 2026-06-23) reported pull-to-refresh did nothing because the shared WebView had no refresh control wired up.††‡ (#9134, #9225)
Store presence
- ✅ Single app record per store on the PPP accounts — one bundle id / package
com.professionalperformanceportfolio.pppfor every build;appVariantselects only the backend (preview→UAT, production→prod), not the identity. On-device name is "PPP" (reverted from "PPP & CPD", #9135); the App Store Connect listing name is "PPP: CPD & Logbook for Doctors". (#7982, #9135) † - ✅
mobile.store.on-device-name-ppp— The on-device home-screen label (CFBundleDisplayName/ Androidandroid:label) is exactly "PPP" — never "PPP & CPD" / "PPP and CPD". It is config-driven fromgetAppName()inapp.config.jsand locked by a Jest guard so it can never silently re-drift to a "& CPD" descriptor. When Matt re-reported "PPP & CPD" on device (#9199, 24 Jun catch-up) the shipped build already carried "PPP" — the device was on a stale build (TestFlight internal testers were stuck on build 1 from 9 Jun; build 44 shipsCFBundleDisplayName = "PPP"), so the home-screen label corrects on the next build with no code change.†‡ (#9199) - ⏳
mobile.store.bare-ppp-name-blocked— The bare "PPP" App Store Connect / Play listing name (vs the current longer-but-unique "PPP: CPD & Logbook for Doctors") is blocked on a coordination task, not a code change: App Store names must be globally unique and the name "PPP" is held by the Moreton Blue Software Pty Ltd team. That team is PLA-frozen — Apple requires its Account Holder, Sean Kelly, to (a) accept the latest Program License Agreement and (b) delete or rename the conflicting "PPP" app before we can claim it. Until then the listing keeps the longer unique name while the home-screen label stays "PPP".† (#9199) - ✅
mobile.store.listing-copy— Store listing and onboarding tagline use "By Doctors, For Doctors" branding and "living, lifelong CV" positioning across App Store, Play Store, and in-app onboarding copy.†‡ (#8316) - ✅
mobile.store.subtitle-no-repeat— The App Store subtitle is "Your living, lifelong CV", not a repeat of the listing-name descriptor. After the #7982 consolidation the listing name became "PPP: CPD & Logbook for Doctors", which left the old subtitle "CPD & Logbook for Doctors" duplicating the title word-for-word (and repeating "PPP"/the descriptor against the title). The subtitle now carries only Matt's approved differentiating positioning (#8316) and adds no brand/descriptor already present in the title.†‡ (#8445) - ⏳ iOS build distributable via TestFlight (Apple Developer account provisioned —, #5078) — the TestFlight upload runs through fastlane pilot (
bundle exec fastlane ios upload_testflight,upload_to_testflight), which forwards the explicit numeric App Store Connect app id as pilot'sapple_idto bypass the bundle-id lookup that silently skipped the upload (#7982). This replaces the earlierxcrun altool --upload-packagestep, whose legacy--apple-idflag syntax Xcode 26 no longer supports (#9945). The uploaded IPA'sCFBundleVersionis derived from epoch seconds (date -u +%s) instead of an App-Store-Connectlatest + 1query (#9950): the earlier sequential scheme (#8197) fixed the build number at archive time, ~50 min before upload, so two overlapping runs (a previewmobile-cdbuild and adevelopmentworkflow_dispatchbuild) both read the same "latest" and computed the same next number, and Apple rejected the second upload with "The bundle version must be higher than the previously uploaded version" (run 28576016381 — both computed 72). Epoch seconds only ever move forward and never collide across concurrent runs or re-runs, mirroring the AndroidversionCodeepoch scheme (#4721) - ✅
mobile.store.testflight-internal-group-auto-assign— After each successful iOS upload to TestFlight, the new build is automatically added to the PPP Internal beta group (5bcbd1c8-5fad-44f0-947c-24d91e1a6a80, app6775512026) via the App Store Connect API, so internal testers always receive the latest build without manual action. App Store Connect offers no automatic-distribution toggle for internal groups (external-only), so each uploaded build must be explicitly assigned — previously the fastlanenotify_internal_testersstep timed out before Apple finished processing, leaving the PPP Internal group stuck on build 1 across builds 35–44 (#8977). Themobile-build-native.ymlstep polls the ASC API until the build appears, then POSTs the assignment directly to/v1/builds/{id}/relationships/betaGroups— with no GET pre-check. Apple's API rejectsGETon that relationship outright (403: "Allowed operations are: CREATE, DELETE"), so the original idempotency pre-check (isAlreadyAssigned()) threw before the real POST ever ran — meaning this step never once succeeded from #9204 (24 Jun) through #10150 (6 Jul), the first of the two independent root causes behind internal testers never receiving builds past build 47 (the second beingmobile.store.beta-app-description-auto-ensurebelow). A repeat POST to an already-linked group is itself an Apple-documented no-op, and any/already/i-matching error is treated as a successful idempotent no-op. Failure surfacing distinguishes terminal from transient failures (#10165): a terminal failure — a revoked/expired ASC key (401/403), a build that never reachesprocessingState=VALIDwithin the poll window, or an assignment POST that fails after its retry budget — sets aterminal_failurestep output, writes a::error::annotation plus a job-summary marker, and exits 2 (shown as a failed-but-continued step); a downstreamFlag terminal beta-group assignment failurestep then files/updates a dedicated alert issue. A transient blip (a status-less network hiccup that outlasted retries) keeps the original #9204 non-fatal::warning::+ exit 0 so a one-off ASC wobble never fails a build. The assign step stayscontinue-on-errorso the build itself never fails (testers still receive the build via the fastlane notify step); a genuine success emitsassigned=true, which a downstream step uses to auto-close the alert issue.†††‡ (#9204, #10150, #10165) - ✅
mobile.store.beta-app-description-auto-ensure— Before each submission, ASC's TestFlight "Test Information" (Beta App Description + feedback email) is auto-populated via the App Store Connect API if not already set, so fastlane'snotify_internal_testersbeta-review submission never rejects with "Beta App Description is missing". This was the second of two independent root causes (alongsidemobile.store.testflight-internal-group-auto-assignabove) behind internal testers never receiving builds past 1.0.1 (build 47) despite uploads succeeding — masked bycontinue-on-error: trueon the notify step. The newmobile-build-native.ymlstep (ensure-beta-app-description.mjs) checks the app's existingbetaAppLocalizationsforen-USand only creates/patches it if missing or empty; non-fatal, same convention as the beta-group-assign step. The existence lookup queries the top-level/v1/betaAppLocalizations?filter[app]=…&filter[locale]=en-UScollection — the only ASC variant that accepts both filters; the/v1/apps/{id}/betaAppLocalizationsrelationship endpoint the first cut used rejectsfilter[locale]with400 PARAMETER_ERROR.ILLEGAL, so the step warned non-fatally and exited green while the description was never set andnotify_internal_testersstill failed with the very error this AC prevents (#10171, run 28887672072).†‡ (#10150, #10171) - ⏳ Android build distributable via Play Store Internal Testing (#4761, #4954)
- ⏳ Xcode 26 / iOS 26 SDK upgrade landed before Apple's deadline (#5078)
- ⏳ SHA-256 SPKI cert pins regenerated before first production release (#5110)
- ✅ Mobile PRs are gated for lint, type-check, and tests: lint + type-check run once in
ci.yml'smobile-lintjob (self-hosted),mobile-ci.ymlruns Jest coverage plus release-gate script tests (#12252 —mobile-ci.ymlpreviously duplicated the same lint+typecheck pass on a billableubuntu-latestrunner; removed, no coverage loss) - ✅
mobile.a11y.native-lint— The nativemobile/pppapp enforceseslint-plugin-react-native-a11ystructural accessibility rules at error in its.eslintrc.json(run by bothmobile-ci.ymland themobile-lintjob inci.yml): everyPressable/Touchablemust carry a validaccessibilityRole/accessibilityState/accessibilityValue(has-valid-accessibility-descriptors/-role/-state/-value), anaccessiblecontainer must not nest touchables (no-nested-touchables), and inverted images opt out viaaccessibilityIgnoresInvertColors. The noisyhas-accessibility-hintrule is OFF — a hint is optional supplementary UX, not a defect. This is the native half of the cross-platform mobile-a11y enforcement that locks in the touch-target/semantic-control floors (web half:design-system.a11y.mobile-gate). The 14 violations the rules surfaced on existing screens (privacy-policy links, the bug-report modal, onboarding logos, the HealthKit/location disclosure modals) were fixed in the same change.†‡ (#9332) - ✅
mobile.store.backend-preflight— A native build cannot ship an app pointed at a backend that does not exist. A cheappreflightjob (ubuntu, ~15s) resolves the profile'sWEB_URL/TRPC_URLfrom a single source of truth (.github/scripts/resolve-mobile-backend.mjs) and probes both before anything is built;build-iosandbuild-androiddeclare it inneeds:, so an unreachable backend means no runner is provisioned, no prebuild runs, and the store-submission step is structurally unreachable — stronger than guarding submission alone, which would still burn ~40 minutes and leave a signed artifact aimed at a void. The probe is deliberately permissive about 4xx (the tRPC root has no route, so a healthy UAT answers 404) and fatal on DNS failure, connection refusal and timeout; the Cloudflare origin-error family (520-527 and 530, whose usual 1016 sub-code is an origin DNS failure — #11463) and plain 5xx are both retried 3× — bothapi-uatandapiare Cloudflare-proxied, so a Container App cold start or revision swap surfaces as 52x, not just 5xx — so neither can red-herring a legitimate build, whileENOTFOUNDfails on the first attempt. It tests reachability, not the environment name, so it passes on its own the day a production backend is deployed — no stale ban to remember to remove. Until then aprofile=productiondispatch fails fast with a message naming the unreachable host and pointing atprofile=preview. The same job also removed the five duplicated copies of the variant→URL ternary that made a one-site fix silently miss four. Because the probe fetches withredirect: 'follow', a fourth calibration rule closes a follow-on gap (#11158): the final, post-redirect URL's host is compared against the requested host before any status-based branch, so a Cloudflare redirect rule silently landing a probe on a different origin (a holding page, a different Cloudflare Pages project, an apex/host-canonicalization rule) is caught even on an otherwise-healthy 2xx/4xx — a cross-host landing is fatal and non-retried (a redirect misconfiguration is a config error, not a cold start), while a same-host path redirect, or a same-hosthttp→httpsupgrade (ordinary canonicalisation), is unaffected and stays reachable. A same-hosthttps→httpdowngrade is fatal (#11205): every probed target ishttps, so a downgrade is the only same-host scheme change this gate can observe, and iOS ATS / Android cleartext defaults both reject the resulting plaintext endpoint at runtime — calling it reachable would green-light a build against an endpoint the app cannot use. The direction matters: rejecting the upgrade direction too would red a healthy build. Where the probe supplied a requested URL but the post-redirect URL came back empty or unparseable, the guard could not run; the verdict is deliberately unchanged (treating “unverifiable” as “reject” is the standing-invariant trap of #10152) but the per-hostdetailnow says so, rather than a green tick that silently means “we could not see anything”. The operator-facing failure report no longer asserts that the production hostnames are “DNS records with nothing behind them” unless a failure actually looks origin-less — under a redirect failure an origin did answer, just the wrong one.††‡ (#11106, #11158, #11205, #11463) - ✅
mobile.e2e.artifact-freshness— The Mobile E2E suite cannot silently test against a stale binary.resolve-mobile-build-run.shpreviously treated GitHub'sexpiredflag as a freshness signal, but it is a retention flag — only flipped at the END of the window (30 days forandroid-apk-*, 7 forios-app-sim-*) — so every artifact inside its window looked identical to the resolver however old it was. The resolver now measures the age of the artifact it actually selects: it warns (still resolving) at/pastWARN_ARTIFACT_AGE_DAYS(default 3) naming the age in the log and the Actions Summary, refuses outright pastMAX_ARTIFACT_AGE_DAYS(default 14), and reports an unreadablecreated_atasage UNKNOWNrather than assuming fresh — a silent assume-fresh would recreate the exact blind spot this closes. Same failure-state-collapse class as the live-vs-expired split (#11011) and the absent-vs-API-failed split (#11185), one level up the stack. Two constraints are load-bearing: the ceiling is escapable (MAX_ARTIFACT_AGE_DAYS=0) because a genuinely quiet mobile codebase legitimately has no new build for weeks and must not have its E2E suite bricked for a non-defect (the standing-invariant trap of #10152), and age is evaluated only for the selected artifact, never for skipped candidates, so an old run deeper in the scan cannot fail a run over a binary it was never going to use. Note the staleness itself is not a resolver defect:mobile-cd.ymlonly builds on amobile/ppp/**change, and a run whose build is skipped still concludessuccessand publishes nothing, so the resolver legitimately walks back to the last run that did — the defect was doing so silently. Applies to both platform jobs, which share this one resolver.‡ (#11516) - ✅
mobile.e2e.baseline-requires-shipped-artifact— Themobile-cd.ymldiff-detection baseline only advances onto a run that actually published an APK, closing the upstream half of the accumulation loop thatmobile.e2e.artifact-freshness(above) catches only downstream, at consumption. A GitHub run whoseNative Build + Submitjob is SKIPPED (nomobile/ppp/**change that day) still concludessuccess— skipped is not a failing conclusion — anddetect-changes-baseline.mjspreviously trusted anysuccessrun as the next baseline. That let a no-change day's green, artifact-less run become tomorrow's baseline, so the diff window silently meant "since yesterday" instead of "since we last actually shipped a build." Measured onuat, 2026-08-04 → 08-10: six consecutive green, build-skipped runs advanced the baseline on every one of them while 24 commits touchinginstances/ppp/accumulated unbuilt — each individual day's verdict was correct (0 changed mobile files that day), which is exactly why it ran unnoticed and leftmobile-e2etesting an 8-day-old APK (#11516).resolveBaselineSha()gained an opt-inoptions.requireArtifactparameter: when set, a candidate run only qualifies as baseline iflistWorkflowRunArtifactsshows it published an artifact of that name —mobile-cd.ymlpasses'android-apk-preview', matching theandroid-apk-<profile>artifactmobile-build-native.ymluploads (name templated from the run'sinputs.profile) for thepreviewprofile everyuatrun resolves to. Per-platform since #12512/#12516:mobile-cd.ymlnow resolves one baseline per platform viaoptions.requireJob('iOS Build (preview)'/'Android Build (preview)') instead ofrequireArtifact— a run qualifies as a platform's baseline only if that platform's own build + store-submit job concludedsuccess(latest attempt), whatever the run's overall conclusion. A build-skipped run has no successful build job, so it still never advances either baseline (this AC's guarantee is unchanged); an artifact is no longer the signal becausemobile-build-native.ymluploads its IPA/APK artifacts underif: always(), so an artifact does not prove a submit. Each platform is diffed by its ownpaths-filteragainst its own baseline, and the schedule builds only the platforms that changed (all/ios/android/none);workflow_dispatchis unchanged. Opt-in and provably non-regressing:cd.yml's call site is unchanged (3-arg call, no options), pinned by a test asserting the artifacts API is never even queried when the option is omitted. An artifacts-API failure aborts resolution (returnsnull, unknown) rather than skipping past the run (false, absent) — advancing past an unknown would silently narrow the window on a transient 5xx, the same failure-state-collapse class asmobile.e2e.artifact-freshness/#11185 one level up the stack; the caller then treats mobile as changed and builds, which over-builds (safe) rather than under-builds (silent). No usable baseline means build, never a non-SHA diff (#12505):mobile-cd.ymlonly handspaths-filtera 40-hex SHA verified present in the checkout; with none it sets that platform's<platform>_force=true, skips that platform's filter and treats it as changed. Both earlier fallbacks were non-SHAs thatpaths-filtertreats as branch names —uatdiffed only the last commit on a schedule event (no iOS build 2026-08-26 → 09-19), andHEAD~1failedgit fetchwithinvalid refspec(09-20 → 09-26). A failing Android build neither blocks nor forces iOS: iOS diffs against its own last successful upload, so a night with no mobile change uploads nothing to TestFlight however Android is doing (#12512 — the mid-test updates #11149 removed), and a green Android-only dispatch never becomes iOS's baseline (#12516). The baseline step is wrapped in try/catch: an unexpected error forces a build of both platforms rather than failing Detect Changes, which would skip the build (#12516). Artifactexpiredstatus is deliberately not consulted — this asks "did the run BUILD it," not "can we still download it today"; retention aging the window would make it silently widen, and downloadability isresolve-mobile-build-run.sh's question to answer (#11011, #11528), not this one's. Complementary to, not a duplicate of,mobile.e2e.artifact-freshness: that AC stops the E2E suite testing a stale binary it already resolved (consumption-time); this AC stops the resolver's own baseline going stale unnoticed in the first place (source-time). Both layers are wanted together.‡ (#11493, #11516, #11528, #11185, #11011, #12505, #12512, #12516)
Non-Goals (v1)
Explicitly NOT part of this spec:
- Offline-first / local-first sync — the mobile app requires network for every tRPC call. Offline is a v2 question.
- Native-only features that don't exist on web — the mobile app is a native wrapper around the web routes plus geo-fence/push. If a feature exists on mobile but not web, it must be added to web first or explicitly justified in this spec.
- Tablet-optimised layouts — iPad/tablet use the phone layout in v1.
- Wear OS companion app — out of scope.
- Apple Watch companion — no longer a flat non-goal (#9198). Scoped as a feasibility spike: Matt chose option 2 (notifications + a glanceable wellness complication) with a user filter. Notification mirroring (Phase 1) is a near-term candidate; a native watchOS app + readiness complication (Phases 2–3) stay out of scope until the Apple PLA is accepted. See
mobile.notifications.apple-watch-mirroranddocs/site/mobile/apple-watch-feasibility.md.
Status
| Area | Status | Notes |
|---|---|---|
| Navigation & menu | ⚠️ Broken | #4887 critical — no mobile nav ≤599px |
| Background geo-fencing | 🔄 In progress | UIBackgroundModes configured; backend event handling still open per timesheets.md |
| Observability (dual-stack) | 🔄 In progress | Sentry: crashes/JS errors wired (#5126). App Insights: all 6 operational categories wired (#6753). Source-map verification pending (#5180). |
| Config / version reporting | ✅ Built (admin-only) | About screen at /(tabs)/about, super-admin only, 11 diagnostic fields + Copy button |
| Push notifications | ⚠️ Partial | Works but token logged in prod (#4981) |
| Auth cookie flow | ✅ Built | Fixed in #5085 |
| OTA updates | ⚠️ Partial drift | EAS Update failures unalerted (#4933) |
| Store presence | ⚠️ Blocked | Play Store perms (#4761, #4954), Xcode 26 deadline (#5078) |
| mobile-ci.yml gates | ✅ Built | #4889 — Jest coverage + release-gate script tests on mobile/ppp/** PRs; lint+typecheck run in ci.yml's mobile-lint job instead (#12252) |
Open issues on label:feature:mobile (3)
| # | Title |
|---|---|
| #12689 | feat(mobile): The native "More" sheet entry for the Action Items surface r… |
| #12690 | feat(mobile): The native menu (bottom tab bar + "More" sheet) shows a CPD-… |
| #12735 | feat(mobile): A Maestro Android health smoke flow (`mobile/ppp/.maestr… |
Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.
Open Issues
| Issue | Title | Type |
|---|---|---|
| #4848 | Empty-path tRPC call crashes WebView app on launch | bug (for-discussion) |
| #4807 | Mobile Build (native): all builds failed (preview) | bug |
| #4761 | Google Play service account lacks upload permission | bug (manual, on-hold) |
| #4919 | Timesheet buttons hidden in mobile-app view with no replacement | bug |
| #4891 | Settings tab gated on hardcoded admin email — not role-based | bug |
| #4893 | No offline queue for geo-fence timesheet creation — entries silently dropped | bug |
| #4954 | Android Play Store service account upload perms (AAB builds but not deployed) | bug (manual, on-hold) |
| #5078 | Upgrade to Xcode 26 / iOS 26 SDK before April 28 deadline | enhancement |
| #5110 | Regenerate real SHA-256 SPKI pins before first production release | enhancement |
| #5126 | Wire Sentry SDK into mobile/ppp — crash reporting + source-map upload | enhancement |
| #5127 | Settings → About screen with version / build / config diagnostics | enhancement |
| #5180 | Verify Sentry source-map visibility + run live-event smoke test | enhancement (chore) |
| #3700 | Mobile-specific UI polish and touch-target compliance | enhancement (on-hold) |
| #4209 | Set up Apple Developer Program account for App Store distribution | enhancement (on-hold) |
Change Log
| Date | Author | Change |
|---|---|---|
| 2026-10-05 | The sidebar menu item renderer now honours label.ParentNode, so the Action Items To-do pill, the CPD Home dot and the Pending Accounts count render on the expanded sidebar (wrapping the label) and on the collapsed rail (wrapping the icon). | #11217 — Task 15 audit B1: the badges were produced by useSidebarMenuClusters but the renderer only read label.value, so none ever showed. |
| 2026-10-04 | Mobile top bar: handheld web and the native shell lead with the PPP logo circle as the Action Items control (To-do-only red marker, drop-down headed Action Items) followed by the wordmark, now 24px tall (was 18px, native shell only). The bell stays top-right for Notifications. | #12141 — Matt 2026-09-20 on #12234 ('what would be neat would be if it was the logo') and the 2026-09-01 call; #12141. |
| 2026-10-04 | The sidebar highlights Attendance (not Timesheet) on the scan page, and CPD-only users in an enterprise organisation get an Attendance item. No change to the mobile app itself. | #0, #12523, #12777, #11216 — #12523 item 5 and #12777. Task 14 lane, Refs #11216. |
| 2026-10-03 | Added mobile.timesheet.edit-screen-edit-mode. The native EditTimesheetScreen now mounts the WebView in edit mode, so tapping the geo-fence push opens the editable timesheet entry instead of the read-only view. | #12722 — Matt (2026-08-18): after tapping the geotag notification the entry opened read-only and he still had to press Edit. The screen hard-coded mode="view". Jest regression in special-screens.test.tsx. |
| 2026-10-01 | The app-context hamburger button (mobile.nav.app-hamburger) now carries data-tour="sidebar-toggle", used as a Guided Tour fallback target on handheld viewports. | #12674 — Found during a full Task 7 re-audit: on a 375px viewport the sidebar drawer is closed by default and renders no DOM content until opened, so the Guided Tour's step 1 selectors never resolved there and the step silently skipped. The hamburger button is already the thing a mobile user actually sees at that point. |
| 2026-09-27 | mobile-cd Detect Changes now diffs only against a verified 40-hex baseline SHA (present per git cat-file -e); with no valid baseline it forces a build (over-build, never under-build), so iOS builds ship again. | #12514, #12505, #12269 — No iOS build had shipped since 2026-08-26 — a non-SHA base (uat, later HEAD~1) made dorny/paths-filter diff only the last commit or fail with an invalid refspec. A failed Android build no longer becomes a baseline, so it cannot suppress the next iOS build. |
| 2026-09-27 | iOS background launches (geofence / location wake-ups) no longer run foreground-only work | HealthKit launch init + sync, the embedded-SPA WebView (and every tRPC query it fires), the login WebView + its SSO-provider query and the Face ID prompt now wait for the first 'active' via a shared useForegroundReady hook. Geofence task handlers, the tabs-layout geofence re-arm, the getCurrentUser query it depends on, the re-arm task registration and notification listeners still run in the background. | #12514, #12507, #12269 — Engineering record #12269 (2026-09-27, "No headless path") — a background relaunch mounted the full tree, multiplying exposure to the #12269 crash class; crash timestamps cluster at hospital arrival/departure. Detection is AppState.currentState at mount ('background' for a location relaunch); anything else, including an 'inactive' user-tap cold start or an unrecognised value, fails open so a doctor never sees a blank screen. react-native-health removal (the rest of #12507's acceptance) is tracked on #12376 and not part of this change. Shipped in sprint PR #12514 (sprint/mobile-crashes-2026-09-27). |
| 2026-09-27 | The MMKV encryption key is stored AFTER_FIRST_UNLOCK (new alias, legacy key migrated, never regenerated on a failed read); a locked-launch key failure defers the MMKV open instead of crashing every importer; Sentry initialises before the import graph. Persisted stores that could not hydrate while locked drop their writes (with a warning) until they rehydrate, and rehydrate as soon as storage opens (first access or next foreground); the launch screen re-checks the session after a late hydration. | #12514, #12508, #12269 — A geofence relaunch on a locked phone threw out of storage.ts's module body before Sentry was up, taking down the background task handler unreported. The review of #12514 found the first deferral left the session / onboarding / health-consent stores on defaults and let the first write after unlock overwrite the stored data; writes are now dropped rather than queued because a queued write would carry those defaults. |
| 2026-09-27 | Hospital geofencing and continuous location updates use separate background task names (hospital-geofence-task, continuous-location-task); the legacy shared background-location-task registration is unregistered before any new registration, and geofences are not armed on a pass where that migration cannot be confirmed (retried on the next trigger). | #12514, #12509, #12269 — On iOS registering one name for a different consumer type replaces the old consumer; the dropped geofence consumer stopped monitoring every region and each new one re-fired "Entered" (#11150 / #11349). Arming past a failed migration would let a later unregister disarm the new geofences. |
| 2026-09-27 | mobile-cd Detect Changes now keeps a separate baseline per platform — the head SHA of the last run whose own iOS Build (preview) / Android Build (preview) job (build + store submit) succeeded — diffs each platform against its own baseline, and the schedule builds only the platforms that changed. An unexpected error in baseline resolution forces a build of both platforms instead of failing the job. | #12512, #12516, #12505, #11149 — With one baseline tied to a green run that published android-apk-preview, a failing Android build left iOS with no baseline, so iOS was built and uploaded to TestFlight every night even with no mobile change — the mid-test updates #11149 removed (#12512). A green Android-only dispatch also became the baseline for code never built for iOS, so the next quiet night skipped iOS (#12516). |
| 2026-09-27 | The launch location re-authorisation prompt (mobile.geofence.reauthorization-after-update) now waits for the app to be in the foreground — a geofence background relaunch defers the check (and its once-per-session guard) to the first 'active' via the #12507 useForegroundReady hook. The launch, post-update and foreground geofence re-arms in the same tabs layout stay ungated and still run in the background. | #12520, #12507, #12269 — Found in the #12507 lane and the review of #12514 — the native Alert could be raised during an iOS background launch with no visible UI. Covered by a tabs-layout Jest case (red on uat, green after) and @regression @issue-12520 in mobile-stability.feature. |
| 2026-09-27 | When encrypted storage fails to open while the app is in the foreground, the root layout replaces the held splash with a recovery screen. For a retryable failure (keychain / Keystore refused the key, or any other open error; storage status 'pending') it shows "We can't open your data" with "Try again", which re-attempts the open, and reports once per launch to Sentry tagged storage_open_failure = key-unavailable | open-failed. For a lost key (#12515, status 'key-lost') it shows "Please sign in again" with "Sign in again", which calls resetStorageAfterKeyLoss() only on that tap and starts the app signed out; that kind is reported once by storage.ts, not again. The locked background launch (#12508) is unchanged — no recovery screen and no report while backgrounded. | #12521, #12508, #12515 — Raised in the delta review of #12514 — after the #12508 storage-ready gate, a foreground open failure left the user on the splash indefinitely with no Retry and nothing in Sentry. Covered by locked-launch-startup Jest cases (red before the change, green after) and @regression @issue-12521 in mobile-stability.feature. |
| 2026-09-21 | Replaced react-native-health (legacy bridge module, no TurboModule/codegen support) with @kingstinct/react-native-healthkit (Nitro Modules, native New-Architecture support) in the iOS HealthKit reader | corrected app.config.js's inaccurate "simulator-guarded" comment about react-native-health. | #12382, #12376, #12269, #7759, #8264, #11555 — Audited react-native-health per #12376 and confirmed it is architecturally identical to react-native-fs, the legacy bridge module that caused the #7759 EXC_BAD_ACCESS crash (fixed by removal, PR #7778) — no codegenConfig, no TurboModule spec files, riding RN 0.76's New-Architecture interop shim on every real device build. This migration is an UNPROVEN HYPOTHESIS test for the #12269 recurring SIGSEGV/EXC_BAD_ACCESS crash class, not a confirmed fix — #12269's own investigation found the crashes "most consistent with" an upstream Hermes/iOS 26 Pointer-Authentication bug, and this issue exists only because that conclusion didn't rule out an interop-corruption alternative. Verification requires a TestFlight soak period against App Store Connect Organizer crash data (Sentry does not see this crash class); this PR alone cannot prove or disprove the hypothesis. The breadcrumb instrumentation added for #11555 (logHealthKitCallBreadcrumb) is preserved unchanged across the migration. NOTE: HealthScreen.ios.tsx (a separate live call site) still imports react-native-health directly and was NOT migrated in this PR — out of the issue's explicitly named scope (healthKitReader.ios.ts + HealthContext.ios.tsx only) and left as a follow-up, so react-native-health remains installed and linked pending that follow-up. |
| 2026-09-20 | Fixed the topbar PPP wordmark (#11617) duplicating the sidebar's own logo on ordinary desktop browsers. | #12357, #12349 — The wordmark was gated on isHandheld, which is false both in the real native webview shell (its intended target) and on desktop with the sidebar expanded — not the same condition. Re-gated on a dedicated isNativeShell prop. |
| 2026-09-20 | iOS Launch Smoke's build-run resolver now distinguishes a skipped mobile-cd.yml build (no mobile/ppp/** change landed) from a genuine build failure | no-change days skip cleanly instead of failing the gate red. | #12325, #12310 — mobile-cd.yml's "Native Build + Submit" job only runs when detect-changes finds a mobile/ppp/** change (#11149's once-daily schedule), so most automatic uat runs leave it legitimately skipped. The old resolver treated "no successful run has a live artifact" as one undifferentiated failure and fired ::error:: red on essentially every no-change day, even though nothing was actually broken. |
| 2026-09-16 | Removed mobile-ci.yml's duplicate lint+typecheck job | Jest coverage and release-gate script tests remain, lint+typecheck now run once in ci.yml's mobile-lint job. | #12252 — mobile-ci.yml's lint job was byte-for-byte identical to ci.yml's own mobile-lint job (same install/tsc/eslint steps, same trigger paths), except ci.yml's runs on the self-hosted fleet (free, per #11921/#11360) while mobile-ci.yml's ran on billable ubuntu-latest — every mobile PR paid for the same check twice. |
| 2026-09-15 | Raised the pnpm override floors for fast-uri, js-yaml, svgo and @xmldom/xmldom in mobile/ppp/package.json past newly-published advisories that targeted the exact version each was previously pinned to, and added missing overrides for decode-uri-component, postcss-selector-parser, browserslist and baseline-browser-mapping. | #12226 — Weekly Mobile Dependency Audit (run 34839739597, 2026-09-14) reported 0 critical / 16 high / 5 moderate advisories in mobile/ppp; re-running pnpm audit --ignore-workspace locally after the dependency graph moved further showed 0 critical / 18 high / 5 moderate / 1 low. Four of the flagged packages already had an override, but three (fast-uri, js-yaml, svgo) were pinned exactly at the version a later advisory covers, and @xmldom/xmldom used a tilde range (~0.8.13) that resolves to >=0.8.13 <0.8.14 — i.e. it never floated forward at all. After the fix, pnpm audit --ignore-workspace returns 0 advisories; the only remaining "high" count is the pre-existing, already risk-accepted image-size finding (#12107), which pnpm reports as ignored rather than open. |
| 2026-08-30 | Adds a job-level timeout-minutes to every previously-unbounded job in the mobile-relevant workflows — mobile-cd.yml (detect-changes), mobile-build-native.yml (close-success, report-failure), crash-reports.yml (fetch-and-file), crash-resolve.yml (resolve-sentry) and code-quality.yml (create-issue) — each sized from that job's observed successful runtime with headroom. Records the rule as the new mobile.observability.ci-jobs-are-time-bounded acceptance criterion. Part of a repo-wide sweep that bounds all 65 unbounded jobs across 16 workflows. | #12038 — A job with no timeout-minutes inherits GitHub's 360-minute default, so a hang (network stall, wedged worker, runner hiccup) bills up to $2.16 on its own and occupies a concurrency slot for six hours. Measured ~1,200 wasted job-minutes (~$7) on 2026-08-29 alone from cancelled/hung runs. The mobile workflows here are unattended (weekly quality report, hourly crash autofile), which is precisely where such a hang goes unnoticed. No change to any mobile app behaviour or to the quality-baseline-never-silent-zero tool-ran markers — this is workflow scheduling configuration only. |
| 2026-08-29 | code-quality.yml's "Run npm audit" step now persists pnpm audit --json to /tmp/audit.json (in addition to its existing high/critical count), and the "Generate tech debt report" step adds a capped (25-row) Markdown table of high/critical npm-audit advisories under "Critical Issues Requiring Immediate Attention" — module, severity, advisory link, and top affected dependency path — following the same pattern already used for the report's CORS-wildcard and SSL-bypass detail blocks. | #11953, #11628 — The advisory JSON was previously discarded after computing the count, so the report's vulnerability detail section rendered empty every week even though the summary table flagged findings 🔴 CRITICAL and the "Recommendations" section told readers to address them — the underlying issue (#11628) was re-filed weekly with the same scary-title-empty-body report. No change to mobile.observability.quality-baseline-never-silent-zero's duplication/dead-code/madge "tool ran" markers, which this PR does not touch — this is a separate, additive detail block for npm-audit findings. |
| 2026-08-28 | Added mobile.observability.sim-build-parallel-job AC — the iOS Simulator E2E-artifact build moved out of build-ios's serial tail into a parallel build-ios-sim job sharing only needs: [preflight]. | #11924, #10947 — #10947 (follow-up to #10933/#10940): running the sim build serially inside build-ios after the signed archive, three dSYM release gates, and Sentry symbolication added ~26 minutes to the TestFlight-submission critical path on every automatic uat push, for a step with no data dependency on that path. Splitting it into a parallel sibling job removes that serial tax while preserving the identical artifact name, retention, and profile gating. Caveat noted in the AC: /sge:pr-review flagged that both jobs declare runs-on: [self-hosted, mac-mini] and the org has exactly one runner with that label, so the two jobs may still serialise rather than overlap — tracked as an open review blocker on this PR pending a second runner or a corrected claim, not yet resolved by this changelog entry. |
| 2026-08-23 | Added mobile.nav.native-shell-topbar-logo AC — the PPP horizontal wordmark now renders in the native webview shell Topbar's blank leading space. | #11723, #11617 — #11617 reported a large blank white area with no branding at the top of the mobile app screen. Root cause: the native webview shell's Topbar (single top chrome since #8259) hides the hamburger in-shell, leaving its leading space empty. Fixed by rendering the already-approved PPP horizontal wordmark (design-system.brand.logo-wordmark-nunito, ppp-full-black-text-v1.svg) there — no new brand asset introduced. Governance-trace verdict: MATCHES_EXISTING (capability CAP-01 Platform Shell, matched spec docs/features/mobile.md) — purely additive, no existing AC required changing. |
| 2026-08-22 | Bumped mobile/ppp/package.json pnpm override for fast-uri from >=3.1.4 <4 to >=3.1.5 <4 to cover GHSA-7p8r-x3mc-p8w7 (host confusion via backslash authority introducer). | #11714, #11708 — Dependency-security patch — fast-uri is a build-time-only transitive dependency (webpack > schema-utils > ajv via @sentry/bundler-plugins), never imported by app code. No app behaviour changes; verified by the new @issue-11708 regression scenario in ci-ops-mobile-ci.feature. The remaining image-size high findings (Metro-transitive, no patched version upstream) are unchanged from #11669's assessment. |
| 2026-08-20 | Bumped mobile/ppp/package.json pnpm overrides to the patched minimum floors for brace-expansion (1.1.18/2.1.4/5.0.9), nanoid (3.3.18), js-yaml (4.3.1), and undici (8.9.0) after new security advisories were published against the previous pins. | #11669, #11623 — Dependency-security patch — the prior override floors were below newly-reported vulnerable versions. No app behaviour changes; verified by the existing @issue-11623 regression scenarios in ci-ops-mobile-ci.feature asserting the new floors are present in package.json. |
| 2026-08-18 | Added max-lines (2803) and complexity (32) as warn-level ESLint ratchets for mobile/ppp, pinned at the current worst offender (lib/services/location-service.ts) rather than below it. max-lines is off for test files. Re-verified that type-aware linting, no-floating-promises and no-misused-promises were already enabled by #10829. | #11643, #11005 — Caps the largest source file in the repo — the one behind the #10964 iOS crash, registering 9 of the app's TaskManager handlers — so it cannot grow further while new files start clean. Pinned at the worst value, not below, because a lower threshold fails the build today on the very file being capped, which is the separate deliberate cleanup this issue scopes out. Extends the structural engineering lint gate line already recorded against Open Question 4. |
| 2026-08-15 | Unhung the TabLayout Jest suite's afterEach cleanup — removed the file-wide fake timers that made @testing-library/react-native's auto cleanup never converge when unmounting the tabs-visible branch, and restored AppState.addEventListener's subscription-shaped mock implementation after a spy is restored. | #11576, #11573 — Test-infrastructure fix only — no mobile app behaviour or acceptance criterion changed. mobile.md lists this file via its mobile/ppp/** code-path because the suite guards several of its ACs; the value of the change is that those existing guards now actually execute instead of dying in cleanup. |
| 2026-08-15 | Made the two clauses of isOriginlessHostSymptom (.github/scripts/resolve-mobile-backend.mjs) independently testable. PR #11487 widened the predicate two ways at once — adding 530 to the numeric alternation AND the literal phrase "could not reach the origin" to the message-phrase alternation — and the new 530 table entry''s own message contains that exact phrase, so the phrase clause already matched every 530 the script can construct. Three unit tests added that pin each clause, and each individual alternative within both clauses, against a fixture the OTHER clause provably cannot match. The production regex is unchanged; the diff is additive (tests, a BDD scenario, and a doc comment recording why both clauses exist). | #11575, #11497 — Follow-up raised by #11487's independent review and filed as #11497. The redundancy was proven by mutation rather than inspection: against the pre-fix suite, reverting the numeric widening alone left all 61 tests green, reverting the phrase alternative alone left them green, and deleting the ENTIRE phrase clause also left them green — only deleting the entire numeric clause went red. Each clause was covering for the other, so either could have been silently deleted with CI green and the regression test written for #11487 pinned neither. |
| 2026-08-13 | Fixed a path-separator normalization bug in code-quality-tool-ran-markers.test.mjs (backslash vs forward-slash mismatch on Windows self-hosted runners). | #11560, #11555 — CI-tooling-only fix as part of the docker-machine-linux runner migration (issue #11555) — the test itself asserts CI tooling behavior, not mobile app behavior, and the test-anchor change is required for the test to pass on the new Windows-based self-hosted runner. |
| 2026-08-13 | Added crash-attribution breadcrumbs (category: healthkit.native_call) immediately before every HealthKit native invocation in healthKitReader.ios.ts, after live Sentry API inspection of Sentry 122620667's sixth re-filing (#11555) found the crash occurs 10+ minutes post-launch, in the foregrounded app — provably not the launch/bundle-evaluation window every prior fix in this lineage (#10397/#10835/#10855/#10990/#11498) targeted — and that no thread in any of the 5 crash events is flagged crashed: true, so the actual aborting call has never been provable from this build's crash data alone. | #11559, #11555 — Sentry 122620667 has now re-filed SIX times across five shipped "fix" PRs, each believing it had contained the crash. Rather than ship a 6th speculative containment patch on unproven correlation (a HealthKit read was live in 2 of 5 thread-dumps, but a different method each time), this PR ships the instrumentation needed to make the NEXT occurrence a provable root cause instead of another guess. |
| 2026-08-12 | Adds mobile.notifications.push-token-released-on-sign-out — the app releases this device's push token on the sign-out transition, so a signed-out user stops being reachable on it. Also corrects the stale residual clause on mobile.notifications.push-token-single-owner, which still pointed at #11507 as an open gap. | #11546, #11507 — The #11491 release self-heals a shared device on the NEXT sign-in, which is what closes the cross-user disclosure; it does nothing where a user signs out and nobody logs in after them. In that window the backend still holds a live row and keeps fanning their clinical content to a handset sitting on the login screen — a hygiene/least-privilege gap rather than disclosure, since the device is with its own prior owner. |
| 2026-08-12 | mobile-cd.ymls diff-detection baseline only advances onto a run that actually PUBLISHED an APK. A GitHub run whose Native Build + Submit job is SKIPPED (no mobile/ppp/** change that day) still concludes success — skipped is not a failing conclusion — and detect-changes-baseline.mjs previously trusted any success run as the next baseline. resolveBaselineSha() gained an opt-in options.requireArtifact parameter: when set, a candidate run only qualifies if listWorkflowRunArtifacts shows it published an artifact of that name; mobile-cd.yml passes requireArtifact: android-apk-preview, matching the android-apk-<profile> artifact mobile-build-native.yml uploads (name templated from the runs inputs.profile) for the preview profile every uat run resolves to. | #11543, #11493, #11516, #11528, #11185, #11011 — Measured on uat, 2026-08-04 -> 2026-08-10: six consecutive green mobile-cd runs had Native Build + Submit skipped, and the baseline head_sha advanced on every one of them, while 24 commits touching instances/ppp/ accumulated unbuilt. Every individual days verdict was correct (0 changed mobile files that day) -- which is exactly why it ran six days unnoticed and left mobile-e2e testing an 8-day-old APK (#11516). This is the UPSTREAM half of that incident: #11528 (the sibling fragment above) stops the E2E suite testing a stale binary it already resolved, at consumption time; this stops the build going stale unnoticed in the first place, at the source. |
| 2026-08-12 | Mobile E2E no longer silently tests against a stale build artifact. resolve-mobile-build-run.sh treated GitHubs expired flag as a freshness signal, but it is a RETENTION flag — only flipped at the END of the window (30 days for android-apk-*) — so every artifact inside its window looked identical however old it was. The resolver now measures the age of the artifact it actually SELECTS: it warns (still resolving) at/past WARN_ARTIFACT_AGE_DAYS (default 3) naming the age, refuses past MAX_ARTIFACT_AGE_DAYS (default 14), and reports an unreadable created_at as age UNKNOWN rather than assuming fresh. | #11528, #11516 — Run 31590335898 failed all 26 Maestro flows, every one on the FIRST assertion of its flow (".I have an account." never visible), and mobile-e2e.yml auto-filed "Mobile E2E: tests failing" (#11516) against the tests. The tests were correct — the BINARY was stale: an APK from run 30948342251 (commit f961f5f, 2026-08-04), 8 days behind uat, predating three merged launch-path fixes (#11230, #11470, #11493). A uniform first-assertion failure across every flow is the signature of "the app never rendered", not of 26 independent test regressions. |
| 2026-08-12 | Adds AC mobile.notifications.push-token-single-owner — a device push token is bound to exactly one user. saveNotificationToken now releases the token from any other user before binding it to the caller, and userNotificationToken.save resolves the caller's own id via getSelfUserId instead of enforceUserScope, ignoring the client-supplied userId entirely. Token input is also bounded to the varchar(500) column width. | #11500, #11491 — Two defects reachable only once the client-to-backend wire in this same PR existed (saveNotificationToken had zero production callers before it). (1) Cross-user collision — an Expo push token identifies an INSTALLATION, not a person, and logout is local-only, so on a shared device the same token is reissued to the next user. The unique index is (user_id, platform, token) — three columns — so (A, ios, T) and (B, ios, T) do not collide and coexist; sendPushNotification selects every row for a userId with no cross-user check, so user A's notifications (carrying timesheet and hospital identifiers) would render on user B's lock screen indefinitely. (2) enforceUserScope returns the client-supplied userId unchanged for super-admin callers, so an admin could bind a push token to another user's account; registering a device is purely self-referential and has no legitimate admin use case. |
| 2026-08-12 | Adds AC mobile.notifications.push-token-persisted — the Expo push token obtained on the device is now sent to the backend and stored via userNotificationToken.save, so server-side pushes have somewhere to deliver to. Persisted once the token, a valid session and a resolved user id are all present (they arrive independently and in either order, so whichever lands last triggers the save), dispatched through fireAndForget so a failed save can never abort the process under Hermes, with an unchanged token not re-sent on re-render. | #11500, #11491, #11426 — The token was fetched and held in React state and nothing else — saveNotificationToken had zero production callers, so user_notifications stayed empty and every server-side send short-circuited on "No notification tokens found". UAT logs over the full 30-day retention: 247 send attempts, 247 missing-token misses, 0 delivered, across 30 distinct users and every notification type, with no successful send ever recorded. No push notification had ever been delivered to anyone. |
| 2026-08-12 | Closed the pre-runtime-ready half of the iOS JSI launch abort. #10835's Layer 2 made JsErrorHandler::handleFatalError non-fatal only inside its if (_isRuntimeReady) branch, but that flag is initialised false and set by ReactInstance::loadScript only AFTER runtime.evaluateJavaScript() returns — so the whole bundle-evaluation window (every module-scope side effect and the microtasks it schedules) fell through to the fatal C++ pipeline and still aborted. The fallback now passes isFatal=false, and BOTH halves are pinned as required markers in .github/scripts/verify-native-patches.mjs. | #11498, #11470 — Sentry 122620667 re-filed a fifth time (#10385 → #10563 → #10774 → #10964 → #11470) after four shipped containment PRs. Verified as genuine survival rather than a stale cumulative counter: the reported build 1785875745 is epoch seconds = 2026-08-04, nine days after the last fix (#10990, 2026-07-26); occurrences rose 62 → 78 and lastSeen advanced to 2026-08-07, three days after that build. |
| 2026-08-12 | Added mobile.auth.session-survives-app-update — a doctor holding a still-valid stored session is signed straight back in on launch (including the launch after an app update) instead of being shown the credential form. The launch predicate in app/index.tsx now consults isSessionValid() alongside the existing logout === "1" and biometric checks, and a new mount-only effect completes the restore the same way the biometric path does (scheduleProactiveRefresh() + router.replace("/(tabs)/dashboard")), guarded on !isBiometricSignInEnabled() so it cannot race the biometric gate. | #11489, #11230 — Matt reported that updating the mobile app signs him out — session and Face ID enrolment lost, full re-login required (#11230). No storage is actually lost across an update: the session token, the biometric-enabled flag and the onboarding flags share ONE encrypted-MMKV store behind a device-bound Keychain key, and PR #11475 established the onboarding flags survive an update untouched. The defect was that nothing READ the surviving token — showPasswordFlow initialised from logout === "1" || !isBiometricSignInEnabled() and never consulted isSessionValid(), while the mount-time checkExistingSession() effect called it and only debugLog()ged the answer. Any doctor who had not enrolled Face ID therefore met the login form on every cold start; an update is simply the next cold start. |
| 2026-08-12 | Gated the Maestro E2E suite (mobile-e2e.yml) on backend reachability. A new preflight job probes the profile's frontend and tRPC API before any emulator is provisioned, reusing .github/scripts/resolve-mobile-backend.mjs — the same single source of truth mobile-build-native.yml already uses (#11106) — so the URL mapping and probe classification cannot drift between the build and E2E gates. Both platform jobs declare it in needs:. Also hardened Report Results: a blocked preflight is now its own state that fails the run loudly, rather than being absorbed by the existing 'a skipped platform job counts as OK' rule. | #11488, #11473 — Run 31570095744 failed all 26 flows and auto-filed #11473 against the tests. The cause was not the tests: the UAT tRPC origin was returning HTTP 530 (Cloudflare origin down) — the same outage that had already blocked the native build ~10h earlier through its own preflight (#11463). Every flow authenticates through a WebView served by the profile's frontend, so an unreachable backend fails all of them uniformly, as a wall of assertion timeouts indistinguishable from a suite-wide regression. |
| 2026-08-12 | Added HTTP 530 to CLOUDFLARE_ORIGIN_ERRORS in the mobile build''s backend preflight (.github/scripts/resolve-mobile-backend.mjs), and widened isOriginlessHostSymptom to recognise it. 530 is a Cloudflare origin error (usually sub-code 1016, "Origin DNS error") but sat outside the 520-527 table, so it fell through to the generic status >= 500 branch and reported "the origin did not serve the request" — wording that points at the Container App and never names the Cloudflare edge as the layer raising the fault. Retry/transient behaviour is unchanged: both branches are transient: true, so this alters the diagnostic message, not whether any build passes. | #11487, #11463 — Issue #11463 was filed by the failure auto-filer when the 2026-08-11 preview build (run 31532000142) was blocked by a 530 from api-uat on all three probe attempts. Root cause was a real, since-resolved UAT backend outage — re-probing returns HTTP 404 at the tRPC root (the correct healthy response) and 200 for the web host — so the gate behaved correctly and no build defect existed. The fixable defect was the misleading diagnosis handed to the operator. |
| 2026-08-12 | Added mobile.geofence.update-rearm — after an app update, background geo-fence monitoring (and, via the same tabs-layout mount, notification handling) re-arms on the first launch of the new build with no user re-engagement. Keyed on the native build identity (Application.nativeBuildVersion from expo-application — CFBundleVersion/versionCode, epoch-derived and bumped by CI for every build) rather than the rarely-bumped marketing version, and delegated through rearmGeofencesIfReady('foreground') because the per-session latch keys on the access token, which an update does not change. A second, opportunistic expo-background-task worker may re-arm while the app is still closed. Promotes expo-application to a direct dependency of mobile/ppp (pinned ~6.0.2 — the version pnpm had already resolved transitively, so the lockfile gains only the direct-dependency entry). | #11475, #11150 — Matt, 2026-07-29 Dev Session: after a TestFlight update, exits produced no prompt until he reopened the app and walked the intro. Root cause is that all three pre-existing re-arm triggers require the tabs layout to be mounted, so the whole update-to-next-open window was unmonitored. Also closes the follow-up that mobile.geofence.reauthorization-after-update (#10913) left open — reading the real per-build identity — which needed the expo-application promotion this PR makes. |
| 2026-08-11 | Corrected ascFeedbackUrl() (crash auto-filer) to the real, live-verified App Store Connect route: /teams/<team id>/apps/<app id>/testflight/crashes. The prior /apps/<app id>/testflight/ios shape was wrong on two counts, not one — it omitted the required teams/<team id>/ prefix, and its leaf path resolves to the builds list rather than the crash-feedback view, so it would not have landed a click away from the right page as previously assumed. ASC_TEAM_ID is a new optional env var / repo secret; its absence degrades to the old (still-wrong) app-scoped shape with a loud WARN, never a silent bad link. | #11435, #11431 — Closes the follow-up #10988 (PR #11429) deliberately left open: App Store Connect redirects every unauthenticated path — real or bogus — to /login with the path echoed back, so the original AC (verify the URL shape live before implementing) could not be satisfied without ASC access. Verified 2026-08-11 against a real authenticated ASC session. |
| 2026-08-11 | The TestFlight crash auto-filer now correlates each no-log crash submission against Sentry (bounded window around the submission, keyed on the device tag with the OS version post-filtered client-side against contexts.os.version) and renders any matches as explicitly-labelled candidate correlations. No-log issue bodies and occurrence comments carry a direct App Store Connect TestFlight link; unverified bucket titles now read [testflight-crash] <device> · <os> · <N> reports (unverified) instead of naming a single build; and accrual on a closed tracker is logged rather than left silent. A Sentry outage, network error, or absent credentials degrades to the previous output and never aborts the batch. | #11429, #10988 — Extends the shipped mobile.observability.testflight-feedback-autofile AC rather than changing it (governance-trace: MATCHES_EXISTING) — the UNVERIFIED classification and the #10893 seen-marker sweep both stay exactly as specified. ASC has never returned a crash log on this app (0 of 60 live submissions), so every tracker collapsed to a device/OS bucket that could not be actioned from inside GitHub; #10773 absorbed 10 submissions across 5 builds and four rounds of manual triage without reaching a verdict. Sentry already holds the real symbolicated stack (#10816/#10834) and nothing joined the two. |
| 2026-08-04 | mobile-cd.yml now deploys to TestFlight/Play Store once daily (schedule, cron: '0 20 * * *' = 21:00 BST/UTC+1) instead of on every push to uat, with workflow_dispatch kept as a manual override for urgent fixes and a detect-changes gate (mirroring cd.yml's pattern) that skips a scheduled run when nothing changed since the last successful deploy. | #11353, #11149 — Matt reported (2026-07-29 Dev Session) that multiple TestFlight builds a day — one per mobile PR merge — were invalidating his in-flight manual testing on the timesheet feature: an update landing mid-test looks identical to a glitch. He repeated the same specific ask, "single deployment of updates per day at 9pm", twice over WhatsApp (2026-08-02, 2026-08-03) and confirmed it on a call 2026-08-04. |
| 2026-08-02 | crash-resolve.yml's adoption nudge is now idempotent across reopen/reclose cycles. Every nudge carries a hidden <!-- crash-fixed-by-nudge --> marker, and the step sweeps the issue's existing comments for that marker before posting. A tracker reopened and re-closed while still lacking a crash-fixed-by: marker is nudged exactly once, not once per close. | #11335, #11260 — Closes the known limitation #11250 shipped with and recorded as #11260: on: issues: types: [closed] re-fires on every close, and the step's only condition was whether the issue BODY carried a marker — nothing looked at whether a nudge had already been posted, so duplicates accumulated unbounded, one per close cycle. |
| 2026-08-01 | The mobile.store.backend-preflight code: citation's BDD reference now points at instances/ppp/e2e/bdd/features/ci-ops/ci-ops-mobile-ci.feature instead of the flat ci-ops.feature. No acceptance criterion changed — the scenarios it cites were moved, not edited. | #11327, #11302 — #11302 fragmented ci-ops.feature (892 lines / 66 scenarios at merge) into per-area files under ci-ops/, following the cpd/wellness precedent from #6229. A citation naming a path that no longer exists is the same class of silent failure as a dead code-paths: glob (#11030) — it reads as a live trace while pointing at nothing. |
| 2026-07-31 | crash-reports.yml now supplies the crash''s own build identity (dist) to the dedup classifier on the live path. The Sentry latest-event fetch — the only response carrying dist — moved above the dedup decision; previously it ran after it, and only for issues already destined to be filed, so classifyDedupStatus''s dist branch was exercised by unit tests and never once by production data. dist is also sanitized like every other Sentry-supplied field, and a literal "null" string is normalised to empty at the source. | #11280, #11252 — The mobile.stability.crash-triage-dedup AC described Math.max(dist, lastSeen) as applying 'once wired into the live payload' — a conditional this change discharges. Both prerequisites landed first: #11196 (the occurrence is a max, not a dist override, so a Sentry-supplied dist can only push toward regressed) and #11245 (that max only has a floor when lastSeen itself parses). |
| 2026-07-31 | Three refinements to the backend-preflight cross-host redirect guard (.github/scripts/resolve-mobile-backend.mjs), all deferred out of #11199 as decisions rather than mechanical fixes. (1) A same-host https→http downgrade is now fatal, where before only .host was compared and a downgrade classified reachable. The check is DIRECTIONAL: an http→https upgrade is ordinary canonicalisation and stays reachable, so a blanket .origin comparison would have been wrong. It is ordered after the host comparison, so a redirect that is both cross-host and downgraded still reports the more fundamental host mismatch. (2) When the probe supplied a requested URL but the post-redirect URL came back empty or unparseable, the guard silently disabled itself; the verdict is deliberately unchanged but detail now carries "(redirect target unverifiable)", threaded through every status branch rather than only the mismatch branch. (3) formatFailureReport no longer asserts the production hostnames are "DNS records with nothing behind them" unless a failure actually looks origin-less. | #11278, #11205 — Each closes a "green tick that proves nothing" gap of the class CLAUDE.md tracks under #11030. Every BACKEND_TARGETS entry is https, so a downgrade is the ONLY same-host scheme change this gate can observe in practice — and iOS ATS and Android''s cleartext default both reject the resulting plaintext endpoint at runtime, so a downgraded origin answering 200 would green-light a build against an endpoint the app cannot use. The unverifiable marker is observability, NOT fail-closed: per the #10152 incident, a standing invariant that treats "unverifiable" as "reject" eventually reds a legitimate build on an unrelated transient. The report wording asserted a specific cause (origin-less DNS) that is wrong under a redirect failure, where an origin did answer — just the wrong one — sending the operator to check DNS for a problem living in a redirect rule. |
| 2026-07-31 | The extractStepRunScript() workflow-step extractor used by the mobile workflow regression suites is now a single shared module (mobile/ppp/scripts/__tests__/helpers/workflow-extract.mjs) instead of five per-file copies, and binds steps job-scoped: a step name occurring in more than one job now throws unless a { job } option disambiguates, rather than silently taking the first match. | #11275, #11224 — Follow-up from the #11198 review. The extractor bound a step by name alone, and .github/workflows/mobile-build-native.yml has NINE step names duplicated across jobs — including Set build variables, whose build-ios (2322 bytes) and build-android (1742 bytes) bodies genuinely differ. secret-env-routing-workflow.test.mjs asserted against the iOS one purely because build-ios is declared first, so a job reorder would have silently swapped the script under test with no failure. With the logic copied five times, any fix had to land five times to be correct anywhere. |
| 2026-07-31 | crash-resolve.yml now posts an adoption nudge when a crash-labelled tracker is closed without a <!-- crash-fixed-by: #NNNN --> marker in its body, prompting for the marker at the moment a human is already looking at the ticket. The nudge is fail-soft: a gh issue comment failure warns and exits 0 so the pre-existing Sentry-resolve step still runs. | #11250, #11195 — Closes the #11195 gap raised during the #11164 re-review: the marker convention crash-sweep-dedup.mjs depends on had no adoption nudge at tracker-close time — the only prompt was prose in the auto-filed issue footer, and HTML comments do not render. Live data confirms the problem: all 35 closed crash-labelled trackers sampled carry no marker, so every one of them currently classifies as regressed rather than fixed if Sentry sees the crash again. |
| 2026-07-31 | Closes the one branch #11196''s Math.max(dist, lastSeen) hardening did not reach. dist now RAISES the crash occurrence time and never SUBSTITUTES for it: when lastSeen is absent or unparseable there is no floor to raise, so the comparison stays NaN and falls through to the existing regressed guard — the same verdict that input already produced with no dist at all. Previously the inner fallback took the dist-derived build time alone. Adds three boundary tests (a fix-predating dist with an unparseable lastSeen; the oldest accepted dist against the literal "null" string jq -r emits; and the end-to-end classifySentryIssue path) and corrects all four docblocks, which described the pre-fix behaviour. | #11245 — Found during PR #11243''s merge-gate review by the security-audit lane, filed as #11245, and confirmed reachable rather than theoretical: crash-reports.yml extracts the field with jq -r ''.lastSeen'', which emits the literal string "null" when Sentry omits it, and Date.parse(''null'') is NaN. Substituting dist on that branch was strictly worse than having no dist: every value parseDistBuildEpochMs accepts is at or after 2000-01-01, decades before any real fixMergedAt, so ANY well-formed dist would classify such a crash fixed and suppress it permanently. That is the exact fail-toward-silence primitive #11004 and #11196 exist to prevent, reached through the one branch a max() cannot guard — and it contradicted the SECURITY NOTE #11243 had just added, which claimed lastSeen was a hard floor. Fixed on uat before #11252 wires dist into the live DEDUP_PAYLOAD and makes the branch reachable from attacker-influenceable data. |
| 2026-07-31 | The crash sweep''s build-identity (dist) comparison in classifyDedupStatus is hardened from "prefer dist entirely over lastSeen" to Math.max(dist-derived build time, lastSeen). A dist value can now only push the fixed-vs-regressed verdict toward regressed (visible), never toward fixed (silent); Sentry''s own lastSeen is a hard floor. The docblock, the top-of-file build-identity note, and the four tests that asserted override semantics were updated to match, and two boundary tests added (dist newer and after the fix agrees with lastSeen; dist and lastSeen both predating the fix agree on fixed). dist remains not wired into the live DEDUP_PAYLOAD — this hardening is the documented prerequisite for that follow-up wiring, not the wiring itself. | #11243, #11196 — Raised as a security finding during PR #11164's merge-gate re-review and filed as #11196. dist is dormant today because crash-reports.yml does not yet include it in DEDUP_PAYLOAD, but the moment it is wired in it becomes Sentry-supplied data reachable through the same public-DSN ingestion path sanitize_crash_field already defends against marker forgery. Under override semantics, one crafted, stale, or simply wrong dist value would permanently suppress a crash that is genuinely still recurring on current builds — the same fail-toward-silence shape #11004 exists to prevent, reached via a different field than the one #11095/#11164 closed. Hardening the comparison before the wiring lands means the dangerous configuration never exists in a deployed state. |
| 2026-07-31 | AC mobile.observability.quality-baseline-never-silent-zero widened from the mobile-code-quality job to both jobs in code-quality.yml. The root code-quality job's jscpd and knip steps now carry the same two gates as their mobile counterparts: jscpd on its report file existing (plus an unparseable-report branch), knip on a section header \| exit 0 with no output. The tech-debt report's >10/>5 duplication cell tests for the n/a sentinel before any bc call and renders ⚠️ Unknown; the knip summary-table fallbacks become n/a rather than 0. Root madge's numeric-0 residual is unchanged and still accepted. Guarded-step count 4 → 6, suite 19 → 31 tests. | #11239, #11130 — #11075 closed the silent-zero class for the mobile job only; two paths in the same file still published a false clean baseline. Root jscpd was the more consequential of the two because its pct is the only one of these metrics that feeds a threshold — the tech-debt report piped it through bc, which coerces a non-numeric string to 0, so a jscpd that never ran rendered a passing ✅ OK duplication gate rather than an obviously-missing one. Root knip's extract()-with-:-0-default turned a rejected config or a pnpm dlx fetch failure into a pristine 0 unused files / 0 unused exports / 0 unused deps baseline on a green job. Both were verified by extracting each step's real run: block from the workflow YAML and executing it under bash -e against stubbed tools, including the two cases where the obvious single signal is wrong: a pnpm dlx fetch failure exits 1, the same code as a findings run, and a genuinely spotless knip run prints nothing at all. |
| 2026-07-29 | The mobile-build backend preflight now rejects a cross-host redirect: classifyProbe compares the final, post-redirect URL'"'"'s host against the requested host before any status-based branch, so a Cloudflare redirect rule silently landing the probe on a different origin is caught even on an otherwise-healthy 2xx/4xx, instead of being reported reachable. | #11199, #11158 — Follow-up from the #11116 review (#11106). probeUrl fetches with redirect: '"'"'follow'"'"' and classifyProbe decided reachability purely from the final HTTP status, never checking whether that status came from the host actually probed. A Cloudflare redirect rule on a probed hostname (a holding page, a different Cloudflare Pages project, an apex/host-canonicalization rule) could return a plausible 2xx/4xx from a completely different origin, and the gate would report the original hostname reachable while the real backend stayed down. |
| 2026-07-29 | The crash-reports sweep now decides "fixed vs. regressed" off an explicit <!-- crash-fixed-by: #NNNN --> marker a human adds to a closed tracker's body naming the actual fixing PR — never inferred from the tracker's closedAt or from GitHub's closedByPullRequestsReferences (which PR's merge triggered the auto-close, not which PR fixed the crash — both were tried and both proved wrong on live data). Once a fix PR is confirmed, the crash's own build identity (dist, this repo's epoch-seconds mobile build number) is preferred over lastSeen for the occurrence-vs-fix comparison when available. A closed tracker with no traceable fix is treated as regressed, never fixed. Logic lives in .github/scripts/crash-sweep-dedup.mjs, unit-tested independently of the scheduled workflow; the job now also grants pull-requests: read (needed for the PR lookup) and caps + live-rechecks new issue filing per run. Second re-review round (security): every Sentry-supplied field that lands in an auto-filed tracker body (title, culprit, error type/value, stack preview, device info, app version) is now sanitized against HTML-comment injection before the body is built — without this, a crafted Sentry event (submitted via the public, write-only EXPO_PUBLIC_SENTRY_DSN shipped in the mobile app bundle) could forge a crash-fixed-by marker and a sentry-issue-N cross-reference invisibly (HTML comments do not render), joining a real crash's dedup set and forcing a false "fixed" classification — the same failure class this PR exists to eliminate, via ingestion instead of tracker-closing behaviour. The dedup match itself was also tightened from a bare contains("sentry-issue-N") substring to the exact <!-- sentry-issue-N --> marker. The per-run cap now applies before the live re-check (not after), and FILED/NEW_ISSUES_FILED only increment on a confirmed gh issue create success (previously incremented on attempts, masking failures behind a healthy-looking count). The PR number a marker names is bounded to 7 digits. | #11164, #11095 — The original closedAt comparison silently classified the still-live iOS JSI launch crash (Sentry 122620667) as fixed (fix #10835 merged 2026-07-23T07:04Z, crash recurred 2026-07-26T15:11:38Z — 80h later, a genuine regression — tracker #10964 closed 87 minutes after that). The first attempt at a fix (this PR's initial commit) replaced closedAt with fixMergedAt sourced from GitHub's closedByPullRequestsReferences — but this PR's own merge-gate review re-derived the live GraphQL data for the same incident and found tracker #10964 was actually closed by PR #10991 (an unrelated CI change, merged one second before #10964's own closedAt), not PR #10835 (the real fix, merged 3 days earlier). closedByPullRequestsReferences answers "which PR's merge triggered this issue's auto-close", not "which PR fixed the crash" — a keyword-matching fact, not a causal one — and fed the real data, the shipped classifier still returned "fixed": the same wrong answer as the original bug, because in this repo an issue typically auto-closes 1-2 seconds after whichever PR closes it, so the two signals converge almost everywhere. Corrected by requiring an explicit, deliberately-set marker instead of any further inference, and by layering in build/release identity (this repo's mobile build numbers are confirmed epoch-seconds timestamps, #4721/#9950) per the review's direction, since a specific build's identity is stronger evidence of which code a crashing binary contained than Sentry's ingestion wall-clock. |
| 2026-07-29 | Corrected mobile.geofence.events-coordinate-free: it stated mobile geo-fence events send workplaceId + timestamp only, which #11100/#11124 made false — mobile now also sends an optional derived verification.distanceMeters (never a coordinate, and never withinGeofence, which mobile deliberately omits). The DPIA-4 no-coordinate guarantee is unchanged and still holds at every nesting level; only the 'timestamp only' framing was stale. | #11124, #11100, #10827 — #11124 review. This is the same class of staleness the PR's own commit 1 rationale calls out fixing elsewhere ('the class of stale comment that later reads as an instruction, which is exactly what #11097 had to fix in mobile.md') — left uncorrected in this AC by the original PR. CLAUDE.md requires the spec to stay in sync with the acceptance criteria it governs; the mechanical Spec drift check did not catch it because docs/features/timesheets.md's exact-path code-paths entry outranks mobile.md's broader mobile/ppp/** glob for this file (features-data.mjs's narrowest-glob-owns rule, #8036), so only timesheets.md was required — this fragment is a voluntary correction, not a gate requirement. |
| 2026-07-28 | A native mobile build now proves its selected backend is reachable before anything is built: a new preflight job resolves WEB_URL/TRPC_URL from one source and probes them, and both build jobs declare it in needs:, so an unreachable backend makes store submission structurally unreachable rather than merely discouraged. | #11116, #11106 — A profile=production dispatch (run 30289616194) built an app pointed at a Cloudflare record with no origin (HTTP 522) and an API hostname with no DNS record at all, auto-submitted it to TestFlight, and reported success — the product owner opened it the next morning and got a full-screen Cloudflare Host Error while Azure health, Cloudflare status and CI were all green. The build verified the artifact, never that the artifact could reach a server. |
| 2026-07-28 | Corrected the "Dependency management" section of mobile.md, which prescribed the scoped override "tar@<6.2.1": ">=6.2.1" as "the correct form". That form resolves @expo/cli to tar 6.2.1, and GHSA-r292-9mhp-454m has NO lower bound (vulnerable_version_range: "<= 7.5.20"), so 6.2.1 is itself vulnerable and is the final 6.x release with no backport. The written requirement was therefore an instruction to reintroduce the advisory. The section now documents the shipped approach — a blanket "tar": ">=7.5.21" floor, with mobile/ppp/scripts/fix-tar-cjs-interop.mjs restoring exports.default on tar's CommonJS bundle at postinstall so expo prebuild keeps working — and records the scoped form explicitly as unsafe, with the #9724 → #10877 → #11096 history that produced it. Also adds mobile/ppp/pnpm-lock.yaml, scripts/** and __tests__/** to the mobile CI path filter: the lockfile is what actually decides installed versions and can move without package.json, which is exactly the #11096 shape (package.json declared the right floor while the lockfile still resolved 6.2.1). | #11097, #11096, #10877, #9724, #9723 — Caught by the #11097 merge-gate re-review, which withheld the gate for it and was right to. Every other part of this PR fixes the code; leaving the spec prescribing the vulnerable form would have had the next person reintroduce the advisory while correctly following the documented rule — the same loop that produced #9724 (scoped to v6 to unblock prebuild), #10877 (restored the floor for the CVE) and a first attempt at #11096 (scoped back to v6, wrongly claiming CVE coverage was retained). A spec that instructs the defect is worse than a stale one, because it makes the mistake the compliant choice. |
| 2026-07-27 | New AC mobile.observability.quality-baseline-never-silent-zero. Every mobile code-quality metric in code-quality.yml's mobile-code-quality job now reports n/a plus a ::warning:: when the tool did not run, never 0: madge gates on ^Processed on stdout, jscpd on its report file existing (plus a second branch for a report that exists but will not parse), knip on either a Words (N) section header or exit 0 with no output at all. The two pre-existing root madge steps keep a numeric count (it feeds total=$((…)) and a -gt 5 report comparison) and instead emit a per-side ::warning:: naming the total as a lower bound. npx madge is pinned to madge@8 at both root call sites, extract() moves from grep -oE '[0-9]+' | head -1 to a sed capture group at both call sites, and the mobile report table's fallbacks become n/a rather than 0. | #11075, #11029, #11010 — #11010 added the mobile analysis steps and, in the same PR, fixed a real silent-zero bug — then all three of its new steps reintroduced the same class one layer up. A tool that fails to run produced exactly the value a clean result produces (0) on a green continue-on-error step, so the step summary and the 90-day artifact asserted a pristine mobile baseline. Reproduced with a deliberately broken knip config: ERROR: Invalid input (unrecognized_keys: entryPointsTypo) reported unused files=0, unused deps=0 against real figures of 17/13/159/25/1. That undermines #11010's own deliverable — a baseline trustworthy enough to calibrate a future blocking gate. Every marker was measured against the real binaries rather than assumed, including two cases where the obvious single signal is wrong: a pnpm dlx fetch failure exits 1, the same code as a knip findings run, and a genuinely spotless knip run prints nothing at all. |
| 2026-07-27 | Crash sweep: an HTTP 200 whose latest-event body jq cannot parse now emits a :⚠️: before normalising to {}, instead of degrading to a blank report with no signal in the run log. | #11073, #11020 — #10991 keyed its new fetch warning on HTTP status alone, so an unparseable 200 still produced App version "unknown", "(stack trace unavailable)" and environment:unknown with zero warnings — indistinguishable from "no crashes", which is the exact failure mode #10991 exists to eliminate (30 trackers shipped empty and nobody noticed for months). |
| 2026-07-26 | The mobile lint rules declared in mobile/ppp/.eslintrc.json now actually run outside CI. ESLint 8.57 resolves a flat config by walking UP from cwd, so a plain eslint . in mobile/ppp found the monorepo-root eslint.config.mjs and discarded mobile's entire eslintrc — 8 plugins and 124 rules collapsed to 2 and 4. A new dependency-free wrapper mobile/ppp/scripts/eslint.mjs pins eslintrc resolution and is wired into the package lint/lint:fix scripts, mobile's lint-staged block, the root .lintstagedrc.mjs routing and both CI workflows; the root flat config now ignores mobile/ppp/** so a bypassing invocation fails loudly (exit 2) instead of silently linting against the wrong config. react-hooks/exhaustive-deps moves warn → error (measured: 0 violations across 357 files). The code: citation on mobile.observability.floating-promise-lint-gate is corrected from pnpm eslint . --max-warnings=0 to pnpm lint --max-warnings=0, the command that now actually enforces it. | #11012, #11002 — CI was already immune — both ci.yml and mobile-ci.yml already set ESLINT_USE_FLAT_CONFIG=false on their ESLint steps — so the gap was only ever the local loop (pnpm lint, lint-staged pre-commit, a bare npx eslint). That split meant developers and the pre-commit hook ran a near-empty config while CI ran the real one. The silent drop was never react-hooks-specific: the react-native-a11y enforcement (#9332), the brand-token no-restricted-syntax guard (#8205) and the no-floating-promises rules (#10829) were all disarmed locally by the same mechanism, so three shipped ACs were only half-enforced. A jest guard (mobile/ppp/__tests__/eslint-rule-registration.test.ts) spawns the real wrapper and asserts the plugin is registered and both hook rules fire on a fixture; removing the env pin from the wrapper fails all 7 of its assertions, so the guard is genuinely falsifiable rather than tautological. |
| 2026-07-26 | Every mobile build now retains its debug symbols as a downloadable CI artifact — a new mobile.observability.symbol-artifact-retention AC. mobile-build-native.yml publishes ios-dsyms-<profile> (30-day retention) carrying every archived .dSYM plus a UUID manifest and atos recipe, and hard-fails the job — before the TestFlight submit — if the exported IPA's dwarfdump -u LC_UUIDs are not all present among those dSYMs. Android publishes the equivalent android-symbols-<profile> (unstripped .so libraries, GNU build-ID manifest, R8 mapping when enabled), advisory rather than blocking. Strictly additive: the Sentry upload and both #10831 release gates are unchanged and still blocking. | #11008, #11000, #10964, #10831, #10828 — The #10831 gate proved Sentry could symbolicate, but the dSYMs were never retained anywhere else — so symbolicating a crash required a SENTRY_AUTH_TOKEN and no such token exists outside CI. Anyone holding a .ips pulled off a device was permanently blind: the shipped IPA is stripped (~105 text symbols, nearest-symbol offsets 344KB-663KB away), so atos against the binary alone yields nothing trustworthy. That is the blindness behind 30 auto-filed crash issues with 0 usable stack frames, and it blocked triage of the live #10964 Hermes SIGSEGV, whose responsible native module cannot be named without symbolicated app frames. An artifact that does not match the shipped binary is worse than none because it looks like coverage, hence the blocking UUID cross-check on iOS. |
| 2026-07-26 | Extended mobile.observability.testflight-feedback-autofile to state what happens when the App Store Connect fetch fails, which the AC had never covered. The call now retries transient upstream faults only — 5xx, 429 and status-less network errors — with bounded exponential backoff honouring Retry-After and each wait capped at 30s so a server-supplied delay of hours cannot park the job (worst case 3 x 30s per request), while every other 4xx still throws on the first response so a 401/403 stays as loud and as fast as before, and a status-less error is retried only when the fetch call itself threw so a PPP-side defect is never retried and blamed on Apple. A fault surviving every retry still files an issue, now labelled upstream-outage (distinct from platform-api-drift) and worded as an Apple-side fault, and the first successful run comments and closes it. Added the src:issue-10963 source fragment and refreshed the code: citation to name withAscRetry(), isRetriableAscError(), computeRetryDelayMs(), parseRetryAfterMs(), formatRunFailureError(), the classifier's new isUpstreamTransient axis, the two new node --test files, and the @issue-10963 BDD scenarios in mobile-stability.feature. The merge-gate review of this PR closed one blocker and four majors before merge: the transient verdict is now reached from the run's terminal ::error:: outcome only (a retried-and-RECOVERED fault could otherwise make a later PPP failure read as Apple's and get auto-closed) with the retry notice moved to stdout as a second layer; gh issue close/reopen targets are re-read and required to carry the marker literally, because GitHub's tokenized issue search returns issues containing none of it; a failed reopen falls through to filing a fresh issue instead of commenting on a still-closed one; and the two transient signatures that were not host-anchored, contrary to the file's own comment, are anchored. The delta re-review then found one more, in the same class and closed here: because gh runs via execFileSync, a failure's err.message carries the whole argv including --body, which embeds a TestFlight tester's free-text comment — so a line break in that comment started a new line inside the ::error:: annotation and the new ^::error::ASC_UPSTREAM_TRANSIENT anchor read it as the caller's own terminal verdict, letting a tester mint upstream-outage ("no action is needed here") for a genuine PPP failure and have the recovery step close it unattended. Both branches of formatRunFailureError now flatten the interpolated message through a shared toSingleLine(), keyed to the full ECMAScript LineTerminator set (LF, CR, U+2028, U+2029) rather than the sibling scripts' /\\r?\\n/ idiom — which, verified by mutation, would have closed the LF vector while opening the other three by moving untrusted text onto the one line the terminal-outcome extractor always retains — and extractTerminalFailureText now reconciles its own line model with the anchor's as a second, caller-independent layer. | #10997, #10963, #10625, #10175 — Issue #10963 was auto-filed by this workflow against itself: Apple returned HTTP 500 UNEXPECTED_ERROR on run 30171606341 and the filer threw on the first non-2xx, so a transient upstream fault failed the run, put a bug on the board classified as a generic failure, and — with no recovery path in the workflow — left it open after the next hourly run had already succeeded. The AC previously described only the happy path, so nothing recorded which failures are ours to fix and which are Apple's to fix. The retry boundary is stated explicitly in the AC because it is the load-bearing distinction: broadening it to any 4xx would silently swallow the #10626 auth/permission drift class that the #10625 failure reporting exists to surface. |
| 2026-07-26 | No acceptance criteria changed. Recorded for traceability: mobile/ppp/patches/expo-notifications+0.29.14.patch adds the .catch() that upstream omits on the module-scope getRegistrationInfoAsync().then(...) call in expo-notifications' DevicePushTokenAutoRegistration.fx, plus mobile/ppp/__tests__/expo-notifications-keychain-rejection.test.ts as the red/green regression guard, and a .gitignore negation for mobile/ppp/patches/*.patch so a patch-package patch can no longer be silently left uncommitted (and therefore unapplied in CI/EAS). | #10990, #10965, #10385 — Sentry 136572655 ("Could not fetch registration information from keychain.", platform javascript, production, 2 occurrences / 2 users) was auto-filed as a crash by the crash-reports sweep, but is neither a crash nor app code: it is an unhandled promise rejection inside expo-notifications. DevicePushTokenAutoRegistration.fx is a side-effect module re-exported by the package index, so importing expo-notifications at all runs a module-scope getRegistrationInfoAsync().then(...) with no .catch(); on iOS EXServerRegistrationModule.m rejects with ERR_NOTIFICATIONS_KEYCHAIN_ACCESS whenever SecItemCopyMatching returns anything other than noErr/errSecItemNotFound — in practice errSecInteractionNotAllowed (-25308) when iOS relaunches the app in the background (UIBackgroundModes location+fetch, startGeofencingAsync) after a reboot but before the first unlock. It surfaced in Sentry only because the #10385 global error handler forwards every unhandled rejection with allRejections: true, which also explains the empty stack and empty culprit. User-visible impact is nil — the app never calls setAutoServerRegistrationEnabledAsync, so the keychain item is never written and the auto-registration path is a no-op even on success, and push tokens go through getInstallationIdAsync, which swallows keychain errors and cannot reject — so the fix is deliberately confined to handling the rejection rather than inventing retry logic. Note that the console.warn inside the new handler is dev/test-only: mobile/ppp/babel.config.js applies transform-remove-console under env.production with no exclude, and Metro runs the project babel config over node_modules, so a release build emits .catch((e) => {}). Catching is the entire fix and it holds in every environment, but production behaviour is a deliberate silent, handled no-op with no telemetry — acceptable only because the path is already inert for this app. The kSecAttrAccessible hypothesis was ruled out explicitly: writes already use kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly, the most permissive attribute iOS still supports, so no attribute change can make a pre-first-unlock read succeed. |
| 2026-07-26 | Rewrote the mobile.observability.testflight-feedback-autofile dedup wording, which still described the pre-#10773 key as "(device + OS + comment prefix)". It now documents the two-generation marker scheme (v2 = device + OS + stack signature when a crash log is available, VERIFIED, may reopen a closed tracker; v1 = device + OS (+ comment prefix) when the API returns no crash log, byte-compatible with pre-#10773 trackers, UNVERIFIED, never claimed as another occurrence and never reopening) and the #10893 seen-marker sweep that makes the run idempotent across a v1↔v2 marker flip on the same submission — a per-submission testflight-crash-seen-<id> search over crash trackers, open and closed, bodies and comments, memoised and scan-capped, run before any issue is created. Added the src:issue-10893 source fragment and refreshed the code: citation to name crashDedup(), resolveCrashTarget(), findRecordedSubmissionIssue(), createCommentLoader() and the new @issue-10893 BDD source-contract scenario in mobile-stability.feature. | #10983, #10893, #10773, #10175 — Carries the second follow-up from the PR #10887 merge-gate review, sequenced after PR #10889 merged (2026-07-25) to avoid a shared-line collision on docs/features/mobile.md. The AC text had drifted a full generation behind the implementation: it still promised a comment-prefix dedup key that #10773 had already replaced, and said nothing about the verified/unverified distinction that governs whether a match may be posted as a recurrence or reopen a closed tracker — the exact semantics whose absence manufactured the false "fix failed" signal on #10773. The #10893 sweep wording is added in the same pass because the idempotency claim in the old text ("re-running the workflow is idempotent") was only true within a marker generation. |
| 2026-07-25 | Added mobile.geofence.location-inactive-banner (#10920, follow-up to #10913 / PR #10922). The native Timesheet screen now renders a persistent LocationInactiveBanner above its WebView whenever getCurrentLocationAuthorizationGap (a new no-persistence, no-telemetry reader added alongside the existing launch-prompt check in locationReauthorization.ts) reports the gap is not "none", reusing the existing getLocationReauthorizationCopy wording rather than inventing new copy. Dismissing it is component-local React state only (never persisted), so it is session-scoped, not permanently hideable. | #10958, #10920 — Matt asked for this passively-surfaced indicator specifically because the #10913 launch prompt is easy to decline and forget — his device sent zero geofence events for five days before he noticed by chance. Implemented natively (not a web/tRPC round-trip) since OS location authorisation is device state only the native app can read. |
| 2026-07-25 | Added mobile.geofence.reauthorization-after-update (#10913, Matt UAT: location silently lost after an app update, only found via manual Geotag press). On every eligible launch the app re-evaluates location authorisation and prompts (Open Settings / Not now) whenever it is insufficient and not already dismissed for the current app version, via new locationReauthorization.ts wired into app/(tabs)/_layout.tsx. Deliberately not gated on detecting an actual version change — an earlier version-gated draft was caught in PR review as a blocker: getCurrentAppVersion() reads the release-please marketing version, which is bumped "only for a real app release" and does not change across the TestFlight build cadence Matt is on, so a version-change gate would almost never arm. New Open Question 5 (passive on-screen indicator, deferred to follow-up #10920, outside #10913s stated Acceptance list). | #10922, #10913, #10920 — Matts design notes asked for a re-prompt "after any update"; the shipped design re-checks every launch instead of gating on a version-change signal that is unreliable in this codebase without a new native dependency (expo-application, which would need a lockfile change) — documented as an explicit, reviewed trade-off rather than a silent divergence from the issue text. |
| 2026-07-25 | Mobile brought under SGD / feature-graph governance (#10833): new "Stability & release gates (#10828)" spec section with mobile.stability.launch-lifecycle-contained (✅ — the #10649 JSI/Hermes launch-crash class contained by #10835 Layer 1 call-site rejection guards + Layer 2 RN 0.76.9 RuntimeScheduler patch, kept un-shippable by the #10829 lint gate), mobile.stability.launch-burst-gate (⏳ pending #10830), mobile.stability.crash-triage-dedup (✅ — #10539 fix-date dedup + #10542 Sentry auto-resolve on tracker close), and mobile.geofence.events-coordinate-free (✅ — workplaceId + timestamp only on the wire, DPIA-4 #10827/#10880). New @feature:mobile-stability BDD node with five passing source-contract scenarios plus a @wip @known-issue-10830 launch-burst placeholder; AC-id traceability comments added to the e2e harnesses and release-gate script suites. New Open Question 4: crash-free-session percentage target (product decision for Matt). | #10889, #10833, #10828, #10649, #10830, #10445, #10827 — Epic #10828 (make the JSI-crash class un-shippable): mobile stability requirements previously had no spec home, no feature-graph node, and no AC traceability, so a requirement like "the app must not crash on the authenticated launch burst" could silently regress. Per the 2026-07-24 re-scope on #10833 this extends the existing docs/features/mobile.md rather than creating a spec; already-shipped epic legs (#10831 dSYM gate, #10829 lint gate, #10859 scripts CI, #10854 keychain guard) are cross-referenced, not re-minted. AC-3 (launch-burst CI gate) stays pending #10830 — the @wip scenario un-skips when it lands. |
| 2026-07-25 | Un-skipped the mobile.stability.launch-burst-gate BDD scenario (mobile-stability.feature) now that PR #10890 shipped the release-crash-scan job in mobile-ios-launch-smoke.yml. Replaced the placeholder no-op steps in mobile-stability.steps.ts with real source-contract assertions: the gate job reuses the Release-config New-Arch iOS Simulator artifact (mobile-build-native.yml -configuration Release -sdk iphonesimulator; app.config.js newArchEnabled: true), the authenticated launch-burst Maestro flow (e2e/launch-burst.yaml), the .ips crash-scan wrapper with crash-takes-precedence semantics (e2e/maestro-crash-scan.ts classifyMaestroResult), and the negative-control proof that the gate can go red (scripts/__tests__/release-crash-scan-gate-workflow.test.mjs, wired into PR CI via mobile-ci.yml's scripts-tests job). Tags flipped from @wip @known-issue-10830 to @regression (kept @issue-10833 @issue-10830). Flipped mobile.stability.launch-burst-gate from ⏳ to ✅ in docs/features/mobile.md, rewritten to describe the shipped gate with an explicit caveat that the gate's first real simulator execution is a post-merge dispatch obligation (mac-mini + uat artifact, cannot run in PR CI). Corrected #10828's epic checklist to tick #10830 and #10833. | #10828, #10830, #10833 — Child issue #10830 (release-config crash-scan CI gate) merged via PR #10890, but its BDD steps were deliberately registered as no-ops so the scenario could not vacuously pass on a bare tag change (per #10833's traceability mandate) — removing only @wip without real assertions would have shipped a scenario that always passes regardless of whether the gate exists. This closes out the epic #10828 stability-hardening work: #10833's only remaining scope was this un-skip, so it closes alongside this change. The gate's own first live simulator run stays an explicit open item (tracked on #10828/#10833) since it needs the self-hosted mac-mini runner and a uat build artifact that cannot be produced in standard PR CI. |
| 2026-07-24 | The Set up CI keychain and signing step in mobile-build-native.yml now retries the cert + private-key import (3 attempts) and hard-fails with an actionable ::error:: if the keychain still holds 0 valid signing identities — instead of printing ✅ and letting Archive iOS app die ~80s later with the misleading ''No signing certificate "iOS Distribution" found''; decoded cert/key tmp files are removed on every exit path via an EXIT trap. The release-gate script suites (node --test "scripts/**/*.test.mjs", 65 tests) now run on every PR via a dependency-free scripts-tests job in mobile-ci.yml (setup-node with package-manager-cache: false — no pnpm on PATH by design), with pull_request.paths widened to .github/workflows/mobile-*.yml. The close-success auto-close job''s if: success() is replaced with an explicit needs-result guard so single-platform dispatches auto-close their failure issues while cancelled or fully-skipped runs never do. New regression suite keychain-signing-guard-workflow.test.mjs (the #10858 extraction pattern) executes the step''s actual run: block: clean import, transient recovery on retry, persistent failure exits 1. | #10872, #10854, #10859, #10856 — Run 29987098335 (the #10649 crash-fix deploy) failed at archive with a misleading signing error 80s after the keychain step reported success despite a transiently failed private-key import ('SecKeychainItemImport: Unknown format in import.', 0 valid identities) — run 29951786477 imported the identical key fine on the same runner image the previous day, so a retry would likely have saved the run (#10854, fail-loud over silent fallback per the prod-reliability playbook). The release-gate scripts had zero PR CI coverage: the #10857 dSYM-gate false-negative's first real execution was a production deploy and the #10834 gate had 3 consecutive production failures before its first green run (#10859). if: success() on close-success evaluated false on single-platform dispatches (one build job skipped), so open failure issues like #10856 never auto-closed after a successful rebuild. |
| 2026-07-24 | The per-tab WebView now detects the embedded web SPA bouncing to its standalone /login page (dead cookie session) — via the native onNavigationStateChange event for full-page 401 redirects plus an injected URL-change watcher for client-side ones, both decided by the pure isWebLoginUrl predicate — and routes through the native logout pathway (/?logout=1) to the full-screen native login route. Arriving with ?logout=1 now skips the biometric fast-path in app/index.tsx. New AC: mobile.auth.dead-web-session-native-login. | #10865, #10862 — Matt''s shake-report #10862 ("The login screen needs to have the privacy link and no menu"): the web SPA''s login form rendered INSIDE the authenticated tab shell — bottom tab bar visible, no Privacy Policy link — because the native shell gates on its own bearer token while the embedded SPA authenticates by cookie, and nothing told the native side when the cookie session died. The biometric-gate skip is load-bearing: without it, the gate restored the just-invalidated session token and bounced straight back to the tab shell in an endless Face ID → dashboard → login-redirect loop (it also fixed the pre-existing gap where a web avatar-menu sign-out could be silently undone by the biometric fast-path). |
| 2026-07-23 | The Verify iOS dSYMs are symbolicatable (#10773) release-gate step now runs sentry-cli debug-files check against each DWARF binary inside each .dSYM bundle instead of the bundle directory itself, hard-fails a bundle containing no DWARF binaries, and no longer suppresses sentry-cli output. A new node:test suite (verify-dsym-gate-workflow.test.mjs) extracts the step's actual run: block from the workflow and exercises it against a fixture archive built from the real failing run. | #10858, #10857, #10831, #10649 — The gate false-negatived on every real execution (runs 29949665735/29951786477/29987930688), blocking all iOS TestFlight deploys including the #10649 crash-containment build: sentry-cli 3.x refuses directory paths ("This command can only check individual debug files"), so checking the .dSYM bundle directory always exited 1 — and >/dev/null 2>&1 hid that self-explanatory error behind a misleading "stripped, or missing debug ID" verdict. Verified against the real sentry-cli 3.6.2 binary: the same dSYM checks Usable: yes when its inner DWARF binary is passed; an ID-less binary still fails, so true-positive detection is preserved (#10857). |
| 2026-07-23 | The #10649 floating-promise crash class is un-lintable — a new mobile.observability.floating-promise-lint-gate AC. mobile/ppp/.eslintrc.json enables @typescript-eslint/no-floating-promises with ignoreVoid: false (a bare void asyncCall() no longer passes) plus no-misused-promises (checksVoidReturn) for app/** + lib/** inside the blocking Mobile CI lint step, and lib/utils/fireAndForget.ts is the sanctioned fire-and-forget pattern: rejections are contained, categorised into the bounded #8372 enum and reported to Sentry with static {source, site, category} tags. All 46 pre-existing violations across 21 files were swept in the same PR with zero eslint-disable escapes. | #10855, #10829, #10828, #10649 — The #10649 crash entered through void rearmGeofencesIfReady('launch') — void satisfies no-floating-promises' default config but does NOT catch a rejection, and under RN New Architecture + Hermes the floating rejection escalated to a native process abort (Sentry 122620667). #10829 (epic #10828: make the JSI-crash class un-shippable) closes that exact hole in lint, pairing with the #10835 native containment patch as defense in depth: lint removes the trigger, the patch degrades gracefully if one slips through. A jest regression fixture asserts a lifecycle handler whose inner call rejects produces no unhandled rejection. |
| 2026-07-22 | Release iOS builds hard-fail if dSYM upload fails or the uploaded binary UUIDs are not resolvable in Sentry — a new mobile.observability.dsym-release-gate AC. mobile-build-native.yml drops continue-on-error from the dSYM upload + local-check steps and adds a post-upload smoke-check (verify-sentry-symbolication.mjs) that confirms each dwarfdump-extracted UUID actually landed in the live Sentry API, so no un-symbolicatable build ships. | #10834, #10831, #10828, #10649 — The #10649 JSI/Hermes crash lineage went ~10 re-files with zero stack frames and reached production because release builds shipped without their dSYMs ever landing in Sentry. #10589 added the upload step and #10816 added a local validity check, but both were continue-on-error — soft warnings that never blocked a TestFlight submission. #10831 (epic #10828: make the JSI-crash class un-shippable) turns both into hard gates and adds a server-side smoke-check, plus docs/site/mobile/symbolication-runbook.md documenting the gate and the P1-incident policy on a zero-frame prod/TestFlight crash. |
| 2026-07-15 | The native "More" sheet collapses its 6 CPD sub-items (Plans, Activities, Report, Support, Resource Library, User Guide) behind a single expandable "CPD" row, starting collapsed, instead of always rendering them expanded. | #10675, #10623 — Rob's follow-up from the #10600 deep-dive: the always-expanded CPD sub-items added ~5 rows that pushed Action Items (order: 12) below the fold on common device heights. /sgd:deep-dive on #10623 recorded Option B (collapse behind a single expandable row) as the narrowest amendment to the mobile.nav.bottom-tab-bar invariant (#7738) of the three directions considered — desktop-menu item order is preserved for every other item; only the CPD section gains expand/collapse behaviour. |
| 2026-07-14 | Fixed the iOS in-WebView floating back affordance (WebViewBackButton, #8261) floating up into the status bar / notch — it now offsets its top by the top safe-area inset instead of a hardcoded top: 4. No acceptance-criteria change; restores the documented placement of the existing back affordance. | #10639, #10597 — Reported by Matt (Dev Session 2026-07-14): "the back button is still hanging around out of place at the top of the screen." The #8261 button is position: absolute, so its top is measured from its container border box, not the host chrome''s padded safe-area content box; top: 4 therefore ignored the inset. The prior fix shipped with no placement regression test (the #8261 scenario asserts only visibility/tappability), so it regressed silently — a @regression @issue-10597 guard is added alongside the fix. |
| 2026-07-12 | Internal refactor of the three mobile health-sync services (Apple HealthKit, Android Health Connect, Samsung Health) behind a shared createHealthSyncService orchestrator — no behaviour or acceptance-criteria change. | #10470 — The three provider services each reimplemented an identical end-to-end sync flow (availability check, read+map, backend push, last-synced tracking, single-day retry, first-connection backfill, foreground routing, persisted failed-sync queue, YYYY-MM-DD formatting). Behaviour-preserving cleanup surfaced by a repo-wide /sgd:refactor smell pass. |
| 2026-07-12 | Bounded the offline timesheet-creation queue (timesheet-offline-queue.ts) and the (currently dead-code) geo-fence event queue to a 200-entry cap with FIFO eviction of the oldest entry once at capacity — previously both grew without limit. | #10431 — Sentry crash sentry-issue-119195945 — iOS WatchdogTermination (OS RAM kill), 6 occurrences / 2 users, no stack trace available (typical for a watchdog kill). Source-level review of the mobile background-task machinery found no confirmed unbounded in-memory growth in the live background-location path; this is a DEFENSIVE fix on the one live structure with an unbounded-append pattern reachable from the background geo-fence handler, not a confirmed root cause. Note this is a deliberate, narrow divergence from the #4893 AC's 'silent drop is not acceptable' guarantee: at the 200-entry cap (which requires weeks of continuous offline geo-fence crossings to reach — far beyond any real shift) the oldest queued entry is now evicted rather than kept forever, trading an already-pathological edge case for a bounded memory footprint. |
| 2026-07-11 | Enabled the minimum-supported-app-version hard gate with a floor of 1.0.1. Builds below the floor (all report 1.0.0 and predate the #8389 wellness.readiness sync fix) now see the non-dismissible "Update required" screen with a store-listing button on launch/foreground; 1.0.1+ builds operate normally. The gate previously shipped disabled (hardGateEnabled false, floor 1.0.0) so nothing was ever forced to update. | #10411, #10410, #8399, #8388 — With the hard gate off no installed build could be forced to update, which blocked safely retiring backend back-compat shims — starting with the wellness.v2 alias (#8388) — since old builds might still depend on them. Rob approved enabling the gate (#10410). The 1.0.1 floor is the first app version carrying the #8389/#8343 fix (#8351 bumped 1.0.0 -> 1.0.1 at 06:38 on 2026-06-09; #8389 merged the same day at 16:05), so it excludes the entire pre-fix 1.0.0 population. |
| 2026-07-10 | Added .github/workflows/mobile-feedback.yml — hourly (+ manual dispatch) pull of TestFlight crash and shake-to-report screenshot feedback from the App Store Connect API, auto-filed as GH issues (bug, mobile, testflight-feedback) tagged with device/OS/app version/build, deduped by crash signature via a marker-based comment-on-existing-issue pattern. | #10175 — Matt's crash reports and TestFlight feedback previously reached the team only when he screenshotted them into WhatsApp (e.g. the #9816 repeated-crash weekend). Apple already exposes this via the App Store Connect API, and the repo already holds an ASC API key in secrets (mobile-cd.yml uses it for TestFlight uploads/distribution) — reused here rather than provisioning new credentials. Mirrors the existing crash-reports.yml/e2e.yml auto-create/auto-close pattern per the issue's explicit ask, so the dedup/labeling conventions stay consistent across the repo's automated issue-filing workflows. |
| 2026-07-09 | Added a cold-launch settle window and an AppState guard around the shake-to-report native screenshot capture, so a shake fired immediately after launch or while the app is transitioning in/out of the foreground can never issue a captureScreen/captureRef call. | #10304, #10237 — Matt reported (WhatsApp, 2026-07-09) the app repeatedly crashes after an update unless he is actively screen-recording via iOS Control Center, at which point it stabilizes. Leading hypothesis from codebase investigation: BugReportProvider's shake detector subscribes to the accelerometer unconditionally on mount and, once triggered, calls react-native-view-shot's captureScreen — a native view-snapshot API that can race the view hierarchy while it is still mid-layout/mid-transition just after cold launch, or while the app is transitioning in/out of the foreground (e.g. the Control Center overlay itself). Starting a screen recording takes ~1-2s of Control Center interaction, plausibly enough for either race window to have closed. Sentry telemetry to confirm the exact native mechanism is currently blocked (SENTRY_AUTH_TOKEN lacks event:read scope, tracked separately) so this ships as a defensive guard on the theorised race windows rather than a byte-for-byte confirmed root-cause fix. |
| 2026-07-09 | The native WebView''s onOpenWindow handler now routes a window.open target (e.g. the embedded SPA''s target="_blank" public-policy links) through a new guarded openInSystemBrowser helper (canOpenURL check + handled Sentry fallback) instead of calling Linking.openURL directly, so a device with no resolvable https handler no longer throws "Unable to open URL". | #10281, #10276 — Sentry issue 112230799 (77 occurrences / 8 users): the embedded SPA''s Privacy Policy link (PublicPoliciesContent.tsx, rendered target="_blank") fired the WebView''s onOpenWindow, which called raw Linking.openURL(target).catch(console.error). On a device with no resolvable https handler that rejected with "Unable to open URL". This handler ALSO carries the wearable OAuth (WHOOP/Garmin/Oura) window.open hand-off, whose ppp:// deep-link return (#8635/#9814) requires the system browser — so the fix keeps the system-browser path (not openExternalUrl, which prefers an in-app browser) but adds a canOpenURL guard and a handled Sentry fallback. Sibling of #10253, which fixed the login-screen call site (app/index.tsx) for the same Sentry issue. |
| 2026-07-09 | Resolving the battery-efficient tracking accuracy no longer crashes the app when a GPS fix fails. resolveTrackingAccuracy() now attaches the failure handler to the position-fix promise itself before racing it against the 4s timeout, so a location fix that rejects after the timeout has already won degrades to the low-power accuracy profile and reports a handled Sentry warning instead of surfacing an unhandled promise rejection. | #10264, #10246 — Sentry issue 126794133 (11 occurrences / 3 users, production): Location.getCurrentPositionAsync can reject with the recoverable kCLErrorDomain error 0 ("cannot obtain current location" — poor signal, indoors, airplane-mode toggling) after the 4s timeout already won the bare Promise.race([resolve(), timeout]). The still-pending position promise then rejected with no handler attached, crashing the app. Attaching the catch to resolve() guarantees the rejection is always handled, win or lose the race. |
| 2026-07-09 | Added an ESLint no-restricted-syntax rule in mobile/ppp/.eslintrc.json that fails the build on any unguarded Linking.openURL(...) call (one not chained to .catch(...)) in app/**/lib/**, so the #10245-class "Unable to open URL" crash cannot be reintroduced. The openExternalUrl helper is the one allowed home for a raw fallback and is excluded. | #10261, #10254, #10245 — #10245 crashed in production (Sentry 112230799 / 122620667-class, 122+ occurrences, 12+ users) because Linking.openURL(PRIVACY_POLICY_URL) was called with no canOpenURL pre-check and no .catch, so a device with no resolvable https handler threw an unhandled rejection that crashed the app. A write-time lint rule catches the pattern in CI (Mobile Lint & Type Check) instead of relying on a Sentry report + WhatsApp escalation to surface it again in production. The rule enforces the guard shape #10245/#7359 standardised (route https links through openExternalUrl; chain .catch for custom-scheme links). |
| 2026-07-09 | The login-screen "Privacy Policy" link now routes through the shared openExternalUrl helper (in-app browser → system-browser fallback → handled Sentry warning) instead of calling Linking.openURL directly, so a device with no resolvable https handler no longer crashes the app. | #10253, #10245 — Sentry issue 112230799 (77 occurrences / 8 users): Linking.openURL(PRIVACY_POLICY_URL) on app/index.tsx had no canOpenURL guard and no catch, throwing an unhandled "Unable to open URL" error. The other three privacy-policy link call sites were already fixed in #7359 to use openExternalUrl; this one was missed. This PR routes the remaining call site through the same helper. |
| 2026-07-09 | Native SSO deep link now carries a single-use, short-TTL one-time code instead of the live Better Auth bearer token; the app exchanges the code for the bearer over a direct TLS POST (ppp.auth.exchangeNativeSsoCode) before establishing the session. New mobile.auth.sso-code-exchange AC; mobile.auth.sso-callback-deep-link updated to the code payload. | #10239, #10233 — On Android, custom ppp:// URL schemes are hijackable by any app registering the same scheme, so carrying a live bearer token on the deep link exposed a high-value, long-lived secret. Swapping it for a single-use, SHA-256-hashed, 60s-TTL code (invalidated on first use via an atomic DELETE … RETURNING + a unique index on code_hash enforcing single-use at the DB layer) closes the hijack-value gap without native manifest/App Links work (deferred as layerable defense-in-depth). Mirrors the already-reviewed Whoop/Garmin deep-link OAuth precedent. |
| 2026-07-09 | Gate and rate-limit the native SSO backend return leg GET /api/auth/sso/mobile-return. New mobile.auth.sso-return-flow-gate AC — the start handler sets a short-lived HMAC-signed flow-nonce cookie (ppp_sso_flow) and the return handler rejects any request without a valid nonce (error=invalid_flow) plus applies the getMobileToken-equivalent (default-tier) rate limit (error=rate_limited), Redis-backed and keyed on the verified nonce's random component (spoof-proof, not the client-controllable XFF IP). | #10232 — The return handler minted a one-time exchange code (#10233) for ANY request carrying a valid session cookie, with no proof it came from the legitimate native OAuth start and no rate limiting — unlike ppp.auth.getMobileToken (a rateLimitedProtectedProcedure). Binding the return leg to a start-issued signed nonce prevents a forged mobile-return (even one presenting a stolen session cookie) from harvesting an exchange code; the rate limit bounds abuse. Chosen the signed-nonce cookie over the trivially-forgeable ?mobile=1 marker as the security-meaningful option. |
| 2026-07-09 | Crash-relaunch session-validity guard — the native tab layout now gates the authenticated shell on session VALIDITY (isSessionValid()), not just token presence. A crash-relaunched, clock-expired persisted token is cleared and the user is returned to the login flow instead of a stale "logged in"-looking dashboard. | #10235 — After a crash + relaunch near a hospital geofence boundary (Matt, 2026-07-09), the app showed an ambiguous/stale login state — it appeared logged out yet the Smart Geo Tag manual override worked. Root cause: TabLayout gated getCurrentUser on !!accessToken (presence) rather than validity, so a zustand-persisted but clock-expired token was presented as authenticated until a stale-bearer API call failed. The guard reads isSessionValid() (the same clock check the OAuth-callback guard uses) and, on an authoritative clock expiry, clears the dead token and router.replace('/')s to login; a null-expiry WebView-bridge session (proactive refresh + 401-retry) is never wiped on launch (respects #10019/#10044). |
| 2026-07-08 | assign-build-to-beta-group.mjs now differentiates terminal from transient assignment failures (isRetryable + classifyFailure pure functions). A terminal failure — revoked/expired ASC key (401/403), a build that never reaches processingState=VALID within the poll window, or an assignment POST that fails after its retry budget — emits a ::error:: annotation, a job-summary marker, a terminal_failure step output, and exits 2; a new mobile-build-native.yml "Flag terminal beta-group assignment failure" step files/updates a dedicated alert issue, while a "Clear beta-group assignment alert on success" step auto-closes it on the next clean assignment. A transient blip keeps the #9204 non-fatal :⚠️: + exit 0. Updates the mobile.store.testflight-internal-group-auto-assign AC accordingly. | #10180, #10165, #10150, #9204 — After #10153 fixed the specific always-failing cause, the masking around it survived doubled — continue-on-error on the workflow step plus the script's main().catch converting every error to a :⚠️: + exit 0. A future terminal failure (revoked key, ASC 5xx after retries, build never VALID) would have left the CD run green with no alert — the same silent-break class that hid #8977 for ~10 builds. The build itself stays green (testers still receive the build via the fastlane notify step); the goal is detectability of a persistent break, not failing CD on every ASC blip. |
| 2026-07-08 | ensure-beta-app-description.mjs now looks up the existing Beta App Localization via the top-level ASC collection GET /v1/betaAppLocalizations?filter[app]={appId}&filter[locale]=en-US instead of the /v1/apps/{appId}/betaAppLocalizations relationship endpoint, which rejects filter[locale] with 400 PARAMETER_ERROR.ILLEGAL. The URL construction is extracted into an exported buildLocalizationLookupPath() helper and guarded by a node --test unit test; the create (POST) and update (PATCH) paths already targeted the correct top-level endpoints and are unchanged. | #10177, #10171, #10150, #10156 — The #10156 fix (mobile.store.beta-app-description-auto-ensure) never worked: its very first ASC call used filter[locale] on the app relationship endpoint, which Apple rejects with 400 (The parameter 'filter[locale]' can not be used with this request, proven in run 28887672072). The script warned non-fatally and exited 0, so the Beta App Description was never set and the downstream notify_internal_testers fastlane lane still failed with the exact Beta App Description is missing error #10156 was meant to prevent — both masked green (#10165 masking pattern). |
| 2026-07-08 | Native mobile SSO (Google/Microsoft) via the system browser — OAuth runs in ASWebAuthenticationSession/Custom Tabs (never the embedded WebView), deep-links back via ppp://auth/sso/callback, and establishes the session through the shared bearer-token path; web SSO buttons are hidden inside the native WebView wrapper. | #10212, #10195 — #10195 enabled web SSO (authClient.signIn.social() full-page redirect), but Google/most providers block OAuth inside embedded WebViews (disallowed_useragent), so the web buttons dead-ended for mobile users. Native SSO runs the round-trip in the system browser and reuses the existing getMobileToken bearer-token session path; the web buttons are hidden in the wrapper as the correctness baseline. |
| 2026-07-07 | assign-build-to-beta-group.mjs now POSTs the beta-group assignment directly to /v1/builds/{id}/relationships/betaGroups instead of running an isAlreadyAssigned() GET pre-check first — Apple's App Store Connect API rejects that GET outright (403, Allowed operations are CREATE/DELETE), so the pre-check threw before the real POST ever ran. Any already-assigned error from the direct POST is now treated as a successful idempotent no-op. Updates the mobile.store.testflight-internal-group-auto-assign AC accordingly. | #10153, #10150, #9204 — Every mobile-cd run since #9204 shipped (24 Jun) had silently failed to add builds to the PPP Internal group — the idempotency pre-check GET 403s before the real POST runs, and the failure was masked by a warning-level log plus continue-on-error, so nobody noticed testers were stuck on an old build until #10150 (6 Jul). This is root cause 1 of #10150 (internal testers never receiving new builds); root cause 2 (missing Beta App Description on the notify step) was fixed independently by #10156 (mobile.store.beta-app-description-auto-ensure). |
| 2026-07-06 | Apple Watch notification filter — Phase 1 (preparatory slice). Added categoriseWatchNotification (notificationType → WatchNotificationCategory, prefix-matched with a system fallback) to lib/config/appleWatch.ts; a new MMKV-persisted WatchNotificationPreference store (lib/services/watchNotificationPreferenceStore.ts, default mirror-all, corrupt/invalid-safe) with a shouldMirrorTypeToWatch convenience; and a "Mirror notifications to Apple Watch" Settings control that is hidden entirely while APPLE_WATCH_ENABLED is false. | #10088, #10068 — Phase 1 of the #9198 feasibility spike delivers the phone-side, PLA-free parts of the notification filter so the wiring is in place before a watch target exists. Everything stays inert behind the APPLE_WATCH_ENABLED = false kill-switch (no app.config.js / native / dependency / build change) — the same 'never offer a control the OS can't honour' rule as the biometric toggle (#10014). The remaining Phase 1 step (flip the kill-switch + call shouldMirrorTypeToWatch from the notification path) and the native watchOS app (Phases 2–3) are blocked on Apple PLA acceptance. |
| 2026-07-06 | Login WebView's onShouldStartLoadWithRequest guard now allows http:// navigation in DEV (via a new pure shouldAllowWebViewNavigation helper), and TokenService's refreshAccessToken short-circuits to false before the retry loop when there is no access token to refresh. | #10056 — #10058's origin/CSP port fix was necessary but not sufficient: the login WebView (app/index.tsx) has its own onShouldStartLoadWithRequest guard, kept so third-party SDK URLs can't punch out to Safari, that only returned true for https://\about: — so a local http:// dev WEB_URL's first navigation was still blocked outright and the screen stayed blank on a fresh install. Separately, a signed-out/fresh-install state (accessToken === null) hit the same retry-and-cooldown path as a genuine network failure, burning MAX_RETRY_ATTEMPTS and surfacing a persistent 'All refresh attempts failed' dev toast for a state that isn't a failure at all. |
| 2026-07-05 | Fix three native-build blockers: TRPC_URL /trpc fallback, Android cleartext exception, and blank WebView originWhitelist port mismatch. | #10058, #10054, #10055, #10056 — All three bugs were blocking local dev builds (expo run:ios/expo run:android) and Maestro E2E testing. #10054 killed native tRPC calls with 404s. #10055 blocked cleartext HTTP to the dev server on Android. #10056 caused a blank WebView after WelcomeGate due to react-native-webview's originWhitelist treating ports as part of the origin. |
| 2026-07-05 | tokenService.ts's performTokenRefresh no longer logs the response body on a non-401 resync failure (status code only), and no longer treats a bare HTTP 401 as authoritative session-invalid confirmation — it now verifies the response body carries a genuine tRPC/Better-Auth UNAUTHORIZED error envelope before clearing the session, falling back to the existing non-authoritative path otherwise. | #10044 — Found during the security-auditor's post-merge review of #10043 (the #10019 fix). The response-body log could leak an auth endpoint's error payload into device logs/crash reporters. The bare-401 trust gap meant an edge/proxy-originated 401 (Cloudflare/WAF/gateway) could reintroduce #10019's session-wiping bug in a narrower case, undermining the whole point of that fix. Neither was a regression (pre-#10043 any failure wiped the session), but both were worth closing before they mattered in production. |
| 2026-07-04 | Added Face ID (iOS) / BiometricPrompt (Android) sign-in — after opting in on a successful password login, a returning doctor unlocks the app with a biometric prompt instead of typing a password; falls back cleanly to the password form on cancel/failure/no-credential, and a Settings toggle plus logout/GDPR-erasure all wipe the stored credential. | #10014 — A surgeon between cases has ~10 seconds and gloves half-off; being dropped at the password screen on session expiry meant the case often never got logged (#10014). No SGD spec id on the issue — routed via the no-spec lane; two open UX questions (session lifetime before re-prompt, enrolment placement) are recorded in Open Questions pending Matt's confirmation rather than inferred. |
| 2026-07-04 | Corrected the #10014 biometric sign-in design mid-review — the credential is now gated on the mobile session token Better Auth already issues (long-lived, rolling), not a "refresh token" that this codebase never actually issues. | #10014, #10032 — A second-pass PR review of #10031 found the original design non-functional end-to-end in production (no refreshMobileToken backend endpoint exists; getMobileToken never returns one; the WebView interceptor hardcodes refreshToken: null) despite passing Jest tests, which injected a synthetic value. Filed as #10032. Re-scoping to the session token requires no backend change and keeps the same security properties (SecureStore requireAuthentication, wipe-on-logout/toggle/erasure). |
| 2026-07-04 | Added a 30s cooldown to tokenService.ts's session-resync so a run of non-authoritative resync failures (network error/5xx, never a clean 401) under sustained backend failure no longer forces every subsequent tRPC call to pay the full 3-attempt exponential backoff (~7s) via ensureValidToken(). | #10042 — Found during independent review of #10019's fix — scheduleProactiveRefresh() only re-arms on a successful resync, so isTokenExpiredOrExpiring() stayed true indefinitely under prolonged backend flakiness. Not a correctness bug (the #10019 session-survives-a-non-authoritative-failure behaviour is unchanged), but a latency tradeoff worth closing before it hits users during a real backend outage. |
| 2026-07-03 | Consolidated the native/web back-button affordance — HeaderBackButtonContext is now scoped per native route instead of one app-wide flat boolean, closing a cross-tab leak where a WebView on one tab (e.g. Wellness) left canGoBack=true visible to every other tab, including the native Health screen (which mounts no WebView at all). | #10000, #9902 — Root-caused via /deep-dive on #9902 rather than patching another screen — #9837's fix for #9817 removed a PageHeader wrapper with no back-navigation logic, so the actual duplicate-back-button mechanism was never touched, and the symptom resurfaced on the Apple Health screen (#9815 symptom 3). Decision recorded at https://github.com/Professional-Performance-Portfolio/ppp/issues/9902#issuecomment-4873474006. |
| 2026-07-02 | TestFlight upload switched from xcrun altool --upload-package to fastlane pilot (upload_to_testflight), forwarding the numeric App Store Connect app id as pilot's apple_id to preserve the #7982 bundle-id-lookup bypass. | #9946, #9945 — Xcode 26 dropped support for altool's legacy --upload-package/--apple-id flag syntax, breaking the iOS TestFlight upload step; pilot uploads through the actively-maintained App Store Connect API. |
| 2026-07-02 | iOS CFBundleVersion now derives from epoch seconds (date -u +%s) instead of the fastlane latest_testflight_build_number + 1 query, making the TestFlight build number collision-proof across concurrent runs and re-runs. | #9950 — The latest + 1 scheme (#8197) fixed the build number at archive time, ~50 min before upload, so two overlapping builds computed the same number and Apple rejected the second upload with 'The bundle version must be higher than the previously uploaded version' (run 28576016381 — a preview mobile-cd build and a development workflow_dispatch build both computed 72). Epoch seconds only ever move forward, matching the Android versionCode scheme (#4721). |
| 2026-07-01 | Remove floating action button (FAB) from TimesheetScreen; restore Add Entry button in the mobile WebView header. | #9908, #9885 — The blue FAB duplicated the Add Timesheet Entry affordance and used native code rather than the shared web component. The web TimesheetActionBar now exposes SmartGeoTag + Add Entry in mobile WebView mode (isMobileApp=true), so the FAB overlay is no longer needed. |
| 2026-07-01 | Fix native app crash on WHOOP reconnect — the embedded WebView now hands the OAuth window.open off to the external browser instead of react-native-webview's default multiple-windows path. | #9814 — PR #9841 fixed the web-only "unmatched route" symptom but the native app still hard-crashed the instant the OAuth page opened. The embedded wellness SPA launches wearable OAuth via window.open, which react-native-webview serviced through its multiple-windows code path — that crashes on iOS under the New Architecture. An onOpenWindow handler now opens the provider page in the system browser (matching the #8635 return-via-ppp://wellness design). |
| 2026-07-01 | "Open Apple Health Settings" now opens iOS Settings (Linking.openSettings) instead of the Apple Health app, so users can actually re-grant HealthKit read access. | #9815 — The button labelled "…Settings" deep-linked to x-apple-health:// (the Health app), leaving users with no way to grant the read categories PPP needs (initHealthKit only shows the OS permission sheet once per install). Split into a Settings-recovery path and a separate "Open Apple Health" browse-your-data path used by the post-sync guidance. |
| 2026-06-30 | Sentry environment tagging: derive sentryEnv from EXPO_PUBLIC_APP_VARIANT so TestFlight builds report environment:uat and App Store builds report environment:production. | #9840, #9835 — Both build profiles previously reported environment:production to Sentry, making /crash-reports unable to distinguish TestFlight testers from live App Store users. |
| 2026-06-29 | Fix Home tab locking on CPD content after Add CPD tap: map /cpd/add to native CPD tab in bridge; use canonical path="cpd-dashboard" in CPDDashboardScreen. | #9739, #9084 — UAT regression: Add CPD button on PPP Dashboard drifted Home tab WebView to /cpd/add SPA flow (absent from WEB_ROUTE_TO_NATIVE_TAB), leaving Home tab locked on CPD content until app restart. |
| 2026-06-29 | Apple Watch feasibility spike. Recorded the direction — option 2 (notifications + glanceable wellness complication) with a user filter, defaulting to mirror ALL PPP notifications to the Watch. Added AC mobile.notifications.apple-watch-mirror, an Open Question for Matt's category scoping, flipped the Non-Goals "Apple Watch — out of scope" line to spike-scoped, and landed an inert notification-mirror config scaffold (mobile/ppp/lib/config/appleWatch.ts) + Jest guard + a feasibility doc. | #9198 — From the 24 Jun catch-up Matt asked to explore Apple Watch support so doctors get notifications (and a wellness glance) on the wrist; he picked option 2 "with user option to limit notifications". The spike answers feasibility/effort without destabilising the native build — no app.config.js / native / dependency change. Feasibility assessment in docs/site/mobile/apple-watch-feasibility.md. |
| 2026-06-29 | Scope tar pnpm override to tar@<6.2.1 so @expo/cli can resolve tar v6 — unblocks expo prebuild on iOS and Android. | #9723 — Blanket "tar":">=7.5.16" override forced the entire tree to tar v7, crashing expo prebuild with "Cannot read properties of undefined (reading 'extract')" because @expo/cli relies on tar v6's CJS default export (removed in v7). Scoped override patches only vulnerable 6.x versions, leaving @expo/cli's tar 6.x resolution intact. |
| 2026-06-27 | Documented and guarded the on-device app display name as "PPP". Added mobile.store.on-device-name-ppp (home-screen CFBundleDisplayName / Android label locked to "PPP", never "PPP & CPD") and mobile.store.bare-ppp-name-blocked (bare "PPP" App Store name blocked on Moreton Blue / Sean Kelly, PLA-frozen — coordination task, not a build change). | #9624, #9199 — Matt re-reported "PPP & CPD" on device (#9199, 24 Jun catch-up). The on-device name was already "PPP" via getAppName() — Matt was on a stale TestFlight build (build 1); build 44 ships "PPP". Hardened the Jest guard so the on-device name can never silently re-drift to a "& CPD" descriptor, and recorded that the bare-"PPP" store title is blocked on Apple coordination, not code. |
| 2026-06-26 | Present the mobile add-* form routes as dismissible iOS modals (formSheet) with an explicit Cancel control, so the bottom tab menu returns when the form closes and the user is never stranded. | #9363, #9317 — On-device QA (#9317): the add-* form screens live outside app/(tabs)/, so pushing them onto the root Stack covered the tab navigator full-screen and the bottom menu disappeared ("losing the menu") — the only way back was the small floating WebViewBackButton. Engineering DEFAULT pending Matt UX-architecture confirmation. |
| 2026-06-26 | Remove the orphan native /(tabs)/retrospective route and its sole-import RetrospectiveScreen — an unreachable duplicate of reviews — establishing a single canonical Retrospective route. | #9359, #9313 — Found via the mobile nav audit (on-device QA sweep): app/(tabs)/retrospective/index.tsx existed but nothing navigated to it — the retrospective menu id maps to /(tabs)/reviews and _layout.tsx had no TabTrigger for retrospective, so the route + its duplicate WebView screen were dead code. |
| 2026-06-25 | Harden computeLastNightSleepHours against malformed Apple Health samples — fixed-anchor session cutoff, drop oversize INBED fallback, clamp result ≤16h. | #9348, #9231, #8977 — Reviewer follow-up to #9319/#9338: the ~36h on-screen sleep query window permits a malformed 33h INBED interval, and the prior INBED fallback returned it verbatim (computeLastNightSleepHours([INBED 33h]) === 33), defeating the "never 20h+" sleep AC. |
| 2026-06-25 | Mobile 44pt touch-target floor for form controls: radios, checkboxes, control-row labels, size="small" buttons, and the WHO-5/MCR/WBA rating-scale chips. | #9342, #9320, #8977 — Epic #9320 P0 audit found radios/checkboxes/Likert rows, size="small" buttons and the WHO-5 rating circles below the WCAG 2.5.5 / Apple HIG 44px minimum on mobile; no theme override existed for radios/checkboxes and the bespoke RatingScale hard-set 26px circles. |
| 2026-06-25 | On-brand, single-viewport, atomic-design redesign of the iOS Apple Health screen — reusable HealthMetricTile atom, no ScrollView, BRAND/FONTS tokens. | #9338, #9231, #8977, #8201 — Rob design direction (25 Jun 2026), follow-up to #9319: the Health screen must match the rest of PPP (BRAND tokens, not raw hex/Tailwind), fit one viewport with no scrolling, and follow atomic design with a reusable metric-tile atom rather than inline one-off cards. |
| 2026-06-25 | Auth/shell polish: a branded light app/+not-found.tsx fallback with a primary "Go to dashboard" route home, login/auth inputs raised to ≥16px to kill iOS focus-zoom on the first screen, and onboarding permission buttons gain a loading/disabled state (spinner + disabled, ≥44pt Skip, Privacy Policy as a real Pressable). | #9330 — Child of #9320 — native-shell + auth first-impression fixes. An unmatched route stranded the user on Expo Router's bare dark 404 with no menu (relates #9314/#9317); the 14px login fields focus-zoomed on iOS on the very first screen; and onboarding permission buttons had no in-flight state, so a double-tap could re-prompt or skip the step mid-request. |
| 2026-06-25 | Apple Health screen display fixes (rounded steps, deduped last-night sleep, live-read-truthful header, em-dash absent metrics, compact grid) + discoverable Health Data entry in the native More menu. | #9319, #9231, #8977 — Matt on-device report (#8977): data flows live but the iOS Health screen showed unrounded steps (1710.4187… steps), an impossible 20.8h summed-overlap sleep figure, a contradictory "no data shared" header while real tiles rendered, "0 ms" for absent HRV, and was unreachable from the menu after onboarding. |
| 2026-06-24 | Apple Health screen: truthful sync status, state-driven CTAs, 30-day backfill, platform-aware sources, App Insights telemetry. | #9255, #8977 — Matt UAT (Build 47, 24 Jun 2026): all HealthKit read scopes granted but app showed "Success" and nothing reached the backend; screen had no clickable affordance once ever connected; guidance looped circularly. |
| 2026-06-24 | Add mobile.store.testflight-internal-group-auto-assign — after each successful iOS upload, mobile-build-native.yml automatically assigns the new build to the PPP Internal beta group (id 5bcbd1c8-5fad-44f0-947c-24d91e1a6a80) via the ASC API, so internal testers always receive the latest build without manual action. Polling + idempotency guard; non-fatal on ASC errors. | #9236, #9204 — Investigation (24 Jun 2026) found PPP Internal had no build assigned across builds 35-44 — the fastlane notify_internal_testers step timed out before Apple processing completed, silently leaving testers on build 1. App Store Connect offers no automatic-distribution toggle for internal groups; explicit assignment is required after every upload. |
| 2026-06-24 | Wire cross-platform pull-to-refresh on native app data screens — pulling down from the top of a view-mode WebView reloads it so the SPA re-fetches the screen's data (iOS native pullToRefreshEnabled; Android RefreshControl wrapper gated to scroll-top). Defaults OFF on add/edit form screens to protect unsaved input. | #9218, #9134 — Matt (UAT 2026-06-23 demo) reported the standard pull-down-to-reload gesture did nothing in the native app; the shared WebView component had no refresh control wired up. |
| 2026-06-24 | Wire the Android Health Connect native reader (react-native-health-connect SDK). Add the dependency, the Expo config plugin + withHealthConnect manifest plugin (android.permission.health.READ_* permissions, the <queries> provider-package block, and the permissions-rationale intent-filter, minSdkVersion 26), and the real reader implementation (checkAvailability -> getSdkStatus, requestPermissions -> initialize + requestPermission, each getXxx -> readRecords for the iOS metric set), mapped into the device-push contract (#9012). Unit-tested against a mocked SDK. | #9214, #9023, #9029 — #9029 scaffolded the reader/mapper/sync/connect-UI but left healthConnectReader.android.ts a stub (checkAvailability hardcoded false), so non-Samsung Android devices had no path to connect. #9023 lands the device-gated native enabler so Health Connect becomes the primary cross-vendor Android health path. Functional/compiling/unit-tested; real on-device read proven on a physical Android phone via the Maestro device-smoke follow-up #9016. |
| 2026-06-24 | Added backfill-fallback regression tests for healthKitSync.backfillHistoricalData — one asserting it retries lastDayWithReadableData when every day's push wrote 0 metrics but at least one day had readable data (metricsRead > 0), one asserting it does NOT retry when every day's metricsRead === 0. No behaviour change; documents the #9255 fallback path. | #9265, #9255 — The #9255 backfill-fallback retry logic merged (PR #9260) without dedicated regression coverage for the retry-vs-no-retry branches — gap identified in PR review, missed in the merge race. These tests lock the branch behaviour in. |
| 2026-06-23 | Remediate 6 HIGH + 11 MODERATE dependency vulnerabilities in mobile/ppp via pnpm.overrides (tar, vite, undici, dompurify, protobufjs, @grpc/grpc-js, form-data, react-router, http-proxy-middleware, js-yaml, uuid). | #9138, #9105 — Security audit #9105 flagged GDPR technical-measure exposure in a medical-data app. All fixable advisories resolved via pnpm.overrides pinning; @opentelemetry/core (1.x->2.x major bump via @pulumi/pulumi) documented as unfixable without breaking infra tooling. |
| 2026-06-22 | iOS WebView back affordance re-added (floating WebViewBackButton); dead native /notifications route, NotificationScreen, NotificationBing and isLogout menu plumbing removed. | #9130, #8261 — Follow-up to #8259 — removing the native DynamicHeader left iOS with no on-screen back control for in-WebView SPA navigation and orphaned the bell-only /notifications route and logout plumbing. PPP team decision (2026-06-22): add the standard iOS back affordance and remove/cleanly route the dead nav entries. |
| 2026-06-18 | Removed the residual blue native header from the "Add Logbook Case" mobile screen (and every other top-level WebView sub-screen) by setting headerShown:false as the root Stack navigator default. The web app's own toolbar inside the WebView stays the single top chrome. | #8872, #8863 — #8863: the blue native header was still present on 'Add Logbook Case'. The root <Stack> in mobile/ppp/app/_layout.tsx set no default screenOptions, so every top-level route except index/(tabs) fell back to React Navigation's headerShown:true; the per-screen WebSubScreen override from #8477/#8532 was not reliable on device. Enforcing headerShown:false at the navigator default suppresses it for all top-level sub-screens at the source. (tabs) and the Health native header are unaffected. |
| 2026-06-17 | Aligned the native mobile menu with the web sidebar for the CPD-only tier — Reports and Action Items now appear in the native "More" sheet for CPD-only users (they always showed on web), while full-PPP-only surfaces (Wellness, Logbook, WBAs, Appraisals, Timesheet) stay hidden. | #8818, #8189 — #8189 (b): the native menu did not match the user type — menu-items.ts marked reports + actions hideForCpdOnly:true, hiding items the web shows CPD-only users (CPD_ONLY_CLUSTERS + bottomUtilityItems, #7911), so the native and web menus diverged for the same tier. |
| 2026-06-17 | Added a Maestro E2E flow for the mobile logout bridge — verifies the web avatar menu's Sign Out posts logoutComplete and the native session is cleared (no ghost session). | #8719, #8270 — After #8259/#8260 the web avatar menu's Sign Out is the only logout path; a silent break leaves a ghost native session and adb taps can't reach WebView web-content, so there was no automated regression guard on the single logout path. |
| 2026-06-17 | Locked the native "More" sheet Action Items label as "Action Items" with an executable guard — menu-items unit test + a source-inspection BDD regression scenario (mobile-nav.feature @issue-8630 @issue-8631) that reads mobile/ppp/lib/config/menu-items.ts. | #8630, #8631 — PR #8607 renamed the source label, but a web-repo PR cannot rebuild the separate Expo app so the rename still awaits a native build (#8651). This adds the missing executable AC trace so the rename cannot silently regress in source. No code change — the label was already correct on uat. |
| 2026-06-10 | Added code-paths for appVersionGate.ts and app-version-config.json | #8606, #8485 — Version gate config belongs to the mobile spec; drift gate now fires correctly when the minimum-app-version floor changes, per #8485 |
| 2026-06-10 | Onboarding tagline updated to "By Doctors, For Doctors" (dropped "Designed"); onboarding headline updated to "Build a living, lifelong CV and more"; App Store and Play Store listings updated with "living, lifelong CV" positioning copy. | #8550, #8316 — Matt: "Designed makes it sound like we've got a doctor in to design it and now not involved." Updated wording better reflects ongoing doctor involvement in the product. Approved in #8316. |
| 2026-06-10 | Native add/edit sub-screens (all 19 add-* screens, Edit Timesheet, Notifications) no longer draw their own blue native header — the web app's compact top toolbar inside the WebView is their single top chrome, matching the main tab screens. The fully-native Health screen (no WebView) keeps its native header. | #8532, #8477, #8259 — Matt's UAT report (#8477) — the blue banner reappeared on "add logbook case". PR #8260 (#8259) removed the native blue header from the tab screens only, deliberately leaving sub-screens with native chrome; since the web toolbar now renders inside the WebView everywhere, that header became a duplicate. New shared mobile/ppp/lib/components/WebSubScreen.tsx applies the same headerless treatment (top safe-area inset, dark status-bar icons, native testID for Maestro) to every WebView sub-screen; Maestro entry flows re-anchored on the testID with platform-conditional back. |
| 2026-06-09 | Minimum-supported-app-version gate — the native app checks a backend version floor on launch and foreground, shows a dismissible soft "Update available" nudge below the latest published build, and a hard "Update required" block below the floor when enabled. The hard gate ships OFF so a misconfigured floor cannot lock anyone out. | #8411, #8399 — There was no mechanism to enforce a minimum supported app version (#8399), which blocked safely retiring backend back-compat shims such as the wellness.v2 alias (#8388) while old installed builds might still depend on them. Bumping the floor and enabling the hard gate is now the deliberate, PR-reviewed step that unblocks shim removal. |
| 2026-06-09 | Background-location "Always" onboarding nudge — when the doctor grants foreground location but not background ("Always"), the location step now holds and shows a LocationAlwaysStep nudge (Open Settings deep-link / Not now) instead of silently advancing, so closed-app auto-timesheets are no longer quietly inactive. | #8407, #8406 — On iOS the onboarding Location prompt only offers Allow Once / Allow While Using App / Don''t Allow — Apple never shows "Always Allow" on the first prompt (iOS 13+ policy), and background geofencing requires "Always". handleLocationAllow previously ignored the requestBackgroundPermission() result and advanced regardless, so a doctor who tapped Allow landed on "While Using" and the background automation never ran with no indication why (#8406). The nudge is non-blocking (manual timesheets always work) and advances directly with no nudge when background is granted. |
| 2026-06-09 | New users can now register from the mobile app. The first-install onboarding "Register via Website" screen (which blocked mobile sign-up and emailed a desktop link) is replaced by a "Create my account" button that opens the responsive web sign-up flow inside the app. | #8401, #8318 — Matt reported you cannot sign up from the app — "We need to allow this to be register from a mobile". The block was added in #1823/#2091 but is no longer wanted; the web /signup-process flow is already mobile-responsive, so the app now surfaces it instead of blocking it. |
| 2026-06-09 | Extend native-shell tab sync to the CPD Progress widget and consolidate the avatar menu and What's-Next banner onto one shared web-to-native tab map, so every in-shell "go to feature" navigation switches the native bottom tab instead of drifting the current tab's WebView. | #8379, #8373 — Follow-up to #8335/#8371. The CPD Progress widget drifted the Home tab the same way the Wellness widget did (its whole-card RouterLink to /cpd-dashboard + view-activities action); it now switches the native CPD tab. CoreAppUserAvatarMenu (#4704) and WhatNextBanner (#7374) each carried a bespoke web-to-native route map — both now resolve via the single shared WEB_ROUTE_TO_NATIVE_TAB / postNavigateToTabs helper. |
| 2026-06-09 | Native iOS auth bridge — the authenticated web SPA now mints a mobile session token and hands it to the native shell on every authenticated load, so the native geofence/timesheet client can authenticate on iOS (where the app's own getMobileToken fetch fails). | #8374, #8341 — Matt bug report (#8341) — 'geotag didn't work driving to Basingstoke'. getMobileToken is a protectedProcedure relying on the better-auth session cookie, which the in-app injected WKWebView fetch does not carry on iOS, so the native tRPC client never got a bearer token and geofencing silently no-opped. The web SPA's own fetch carries the cookie, so the SPA mints the token after session confirmation and posts it over the existing sessionToken bridge. |
| 2026-06-09 | Native shell tab sync — inside the bundled app a "go to feature" navigation from within a tab's WebView (e.g. the dashboard Wellness widget) switches the matching native bottom tab instead of drifting the current tab's WebView, so the Home (PPP Dashboard) tab no longer gets stuck on another feature. | #8371, #8335 — Matt bug report (#8335) — 'Home button goes to wellness not ppp dashboard'. Each native tab hosts its own persistent WebView; a dashboard widget calling react-router navigate('/wellness') drifted the Home tab and autoReloadOnFocus made the drift sticky. Fix posts a navigateToTabs bridge message in the native shell, mirroring CoreAppUserAvatarMenu (#4704) and WhatNextBanner (#7374). |
| 2026-06-03 | The native shell now renders the web app's compact top toolbar (Search + avatar + notifications) as its single top chrome instead of a native blue header — restoring Search and Profile on mobile, with one notification bell and no duplicate logout. The native DynamicHeader is removed; the bottom tab bar + More sheet remain the only primary navigation (the web hamburger stays suppressed). | #8260, #8259, #7635, #7982 — Product decision (#8259) reversing the toolbar-suppression part of #7635/#7982. PppAppContainer drops the {!isNativeShell} gate on the compact top toolbar and the !isNativeApp gate on NotificationMenu (hamburger stays gated on isHandheld, false in the shell, so the single-nav guard holds); mobile/ppp removes DynamicHeader from (tabs)/_layout, adds the top safe-area inset and dark status-bar icons, and removes the duplicate Logout from the More sheet. AC mobile.nav.native-shell-single-nav updated to reflect the new top chrome; BDD scenario inverted to @issue-8259 in mobile-nav.feature. |
| 2026-06-03 | Fix iOS launch crash on the simulator — expo-secure-store now degrades gracefully when the keychain is unavailable (simulator only), and the unsigned sim build no longer carries the keychain entitlement that the simulator's launchd rejected (errno 163). | #8256, #7815, #7820 — The keychain entitlement is required at runtime, but adding it to an adhoc/post-hoc-signed sim binary made the simulator refuse to launch (errno 163 "Security policy issue"); without it the app crashed on boot (KeyChainException). On a real device a keychain failure is now re-thrown (fail-loud) so signed builds never silently weaken at-rest encryption. Reverts the #8040 ad-hoc re-sign. |
| 2026-06-03 | Wire the geo-fence auto-timesheet native-shell Maestro flow to run unattended via a deterministically seeded geo-fence hospital + shared coordinate fixture (no per-environment secret). | #8227, #7669, #8219 — The flow could never pass — the e2e seeder linked the test account to a coordinate-less AU hospital, so location-service registered zero geo-fence regions. Fixed at the source instead of adding the planned SEED_HOSPITAL_LAT/LON secret. The underlying AU-hospitals-have-no-coordinates product gap is tracked in #8219. |
| 2026-06-02 | Mobile: derive the iOS xcodebuild scheme from the generated workspace (unbreaks the archive after the app display name changed to "PPP & CPD" -> PPPCPD); fix the #7815 simulator launch crash by embedding the keychain-access-groups entitlement via a post-build ad-hoc deep re-sign; and suppress the web compact top toolbar (search + avatar) inside the native webview shell so the app no longer shows a duplicate header row. | #8040, #7815, #7635, #7982 — 2026-06-02 Dev Session — Rob: "so we don't have two menus" and "Fix app (#7815 launch + two-menus + adaptive)". The single-app consolidation (#8012) renamed the iOS scheme, which broke the distribution archive; #7815's keychain crash blocked all on-simulator testing; and the web top toolbar was the remaining duplicate after the #7635 hamburger fix. |
| 2026-06-02 | Consolidated the mobile app to a single store record per platform (one bundle id com.professionalperformanceportfolio.ppp); on-device name PPP & CPD, App Store listing PPP: CPD & Logbook for Doctors. Fixed the silently-skipped iOS TestFlight upload. | #8012, #7982 — The repo was configured for a two-app dev/prod split; iOS TestFlight uploads exited 0 but never landed because altool's bundle-id lookup failed for this account. One record per store is simpler for a small team and unblocks #7982. |
| 2026-06-01 | Gate the native bottom tab bar by account access tier — CPD-only users no longer see Wellness or Logbook tabs, mirroring the existing hideForCpdOnly filter used by the More sheet. | #7987, #7837 — CPD-only users (accountAccess === 'cpd') were shown Wellness and Logbook tabs in the native bottom navigation even though those features are not part of the CPD product, leading to empty or 403 screens. The More menu already hid them via hideForCpdOnly; the bottom-tab renderer iterated the hardcoded BOTTOM_TAB_ITEMS array without applying the same filter. Added a getBottomTabItems({ isCpdOnly, isSuperAdmin }) helper and had the tab layout consume it. |
| 2026-05-28 | Revert #7799 (react-native-fs -> expo-file-system migration). The migration changed WebView.tsx (loaded at app boot) and caused iOS to crash on launch in the resulting build. Restores react-native-fs and the previous Android download path; the proper migration is tracked under #7777 with a build + sim launch verification gate before next attempt. | #7832 — iOS launch-crash regression in production. MMKV downgrade (#7793) cannot be reverted (v3 requires the New Architecture, disabled by #7778). Reverting #7799 is the smallest restoration of known-good behaviour for the demo. |
| 2026-05-27 | Touch-target compliance slice of mobile UI polish. Enforce the WCAG 2.5.5 / Apple HIG 44x44 CSS px minimum on the always-present mobile controls: added a COMPONENT.touchTarget.minSize (44) token and applied minWidth/minHeight: 44 to the theme MuiIconButton root (the size="small" nav hamburger rendered ~34px), and raised COMPONENT.button.heightMobile from 36 to 44 so primary action buttons clear the floor on small viewports. New mobile-touch-targets.feature measures getBoundingClientRect on the hamburger, notification bell, avatar, and dashboard primary buttons and asserts >= 44px on the Tier-1 mobile engines. | #7818, #3700 — docs/features/mobile.md already carried the pending AC "All touch targets meet the 44x44 minimum (#3700)". A size="small" MUI IconButton renders ~34px and the MUI mobile button override capped minHeight at 36px — both below the 44px minimum once the web UI runs inside the mobile WebView, where these are the controls users tap on device. Fixed at the theme level (no hardcoded values) so the floor applies app-wide. #3700 stays open for the remaining UI-polish surfaces (chips, form controls, data-grid actions, bottom nav, night-shift mode). |
| 2026-05-27 | Add Maestro flow for native bottom tab bar contract (mobile/ppp/.maestro/bottom-tab-bar.yaml). Asserts: 4 tab items (Home, Wellness, CPD, Logbook) + "More" = 5 total visible controls; "More" sheet lists routes in desktop sidebar order. Drop @wip/@known-issue-7738 from the BDD scenario; promote to @maestro @regression @issue-7738 (native-only; not @mobile, so it does not run on the web mobile BDD engines). AC refined with mobile.nav.bottom-tab-bar identifier and Maestro flow reference. | #7756, #7738 — Transcript 2026-04-13 §Mobile-nav (~01:37:04): Matt described "a significant change to the mobile navigation, which now uses a thumb-based design at the bottom with no more than five items and a more option that reveals the menu in the same order as the desktop version." The native bottom tab bar exists only in the Expo app — the web layer uses a hamburger+drawer and has no tab bar. The BDD scenario was re-tagged @wip because it could not run on the web mobile BDD engines (#7738). This PR provides the correct Maestro-native flow and re-activates the scenario as a properly-tagged @maestro scenario. Known dependency: iOS flows fail at the login step until #7717 is resolved. |
| 2026-05-27 | Native webview shell no longer renders a duplicate web hamburger. After #7533/#7539 made PppAppContainer treat the native app as "handheld", the web hamburger + drawer rendered inside the native WebView on top of the native bottom tab bar — Profile (and every tabs screen) showed two competing navigation patterns. Add isReactNativeWebView() (true only when window.ReactNativeWebView is present) and exclude the native shell from isHandheld, suppressing the web sidebar/hamburger/drawer entirely in the native app. Refined the app-hamburger AC and added mobile.nav.native-shell-single-nav, plus one @regression scenario. | #7659, #7635 — In the 2026-05-27 catchup bug review Rob flagged that the hamburger menu and the bottom nav both render on the Profile page (duplicate navigation), appearing after navigating to Profile. The native shell already owns navigation via its bottom tab bar + More sheet, so the web hamburger added by #7533 was redundant there. window.ReactNativeWebView is injected only by the real RN webview and is absent in a plain ?app=1 browser session, so it cleanly separates "native shell owns navigation" (suppress web hamburger) from the #7533 browser case (keep it). Desktop web and phone web are unchanged. |
| 2026-05-27 | Remove the mobile-launch-smoke.yml workflow. The XCUITest variant broke iOS pod install (#7784/#7802) and the simctl variant was environment-flaky on the hosted macos-15 runner (the dev .app stays alive on the mac-mini simulator but exits on the hosted simulator). | #7800 — Net-negative gate. Crash-on-launch is already caught by the Maestro E2E login flow (mobile-e2e.yml), which fails if the app does not launch. A reliable launch gate on the mac-mini runner is tracked as a follow-up. |
| 2026-05-26 | Native App had no menu navigation — PppAppContainer hid both the sidebar drawer and the hamburger in app context (isMobileApp). Treat the native app as "handheld" so it always renders the hamburger + temporary drawer. Three new ACs under Navigation/Menu and one @regression BDD scenario. | #7539, #7533 — In the 2026-05-26 Dev Session bug review Rob flagged that "the App doesn't have a menu navigation": the #3495 assumption that native bottom tabs handle navigation was wrong — there are no working bottom tabs on these screens, so the App was left with zero navigation. The fix introduces isHandheld = isMobile || isNativeApp and routes both phone web and the native webview through the hamburger-driven temporary drawer. Desktop web is unchanged (permanent sidebar). Does NOT address separate mobile render/overflow issues on /cpd-dashboard. |
| 2026-05-20 | Wire OS notification handler to call markDwellNotificationFired() — prevents duplicate dwell notifications when OS notification fires while app is alive. | #6779, #5931 — Race window identified in #5931 — near-simultaneous OS+JS timer fire could deliver two timesheet-auto-created notifications for the same dwell event. NotificationContext.addNotificationReceivedListener now calls markDwellNotificationFired(hospitalId) which sets the idempotence flag and clears the pending JS timer. |
| 2026-05-20 | Removed stale OTA/EAS Update acceptance criteria — expo-updates was removed in #5158 and OTA channel management is no longer part of the release process. | #6764, #6745, #5128, #5158 — Issue #5128 was closed as superseded. The decision in #5158 removed expo-updates from package.json and deleted mobile-ota-update.yml. The spec still contained ⏳ OTA criteria that will never be implemented, causing drift-detection noise. Status table OTA row updated to 🚫 Removed. |
| 2026-05-20 | App Insights dual-stack integration: lifecycle, push token, OTA, geo-fence, auth, and config events now route to Azure Application Insights via direct REST ingest. | #6753 — CTO decision: Sentry covers crashes + JS errors (symbolicated stack traces, error grouping); App Insights covers operational telemetry and provides the rollout health dashboard filterable by appVersion that Matt needs. |
| 2026-05-20 | Flip Android package ID to com.professionalperformanceportfolio.ppp; fix GOOGLE_PLAY_JSON_KEY secret reference in Fastlane workflows. | #6616, #4761 — PPP Google Play account is now active. Fastlane workflows referenced a non-existent secret GOOGLE_PLAY_JSON_KEY instead of GOOGLE_PLAY_SERVICE_ACCOUNT_KEY. iOS remains on Moreton Blue pending #4209. |
| 2026-04-14 | Sentry chosen over App Insights for crash + unhandled JS error reporting. | #5154, #5167, #6752 — No first-party Expo/RN SDK for App Insights; Sentry integrates cleanly with Expo managed workflow and provides crash grouping, source-map upload, and a dashboard out of the box. Scope limited to native crashes + unhandled JS errors — the 6 non-crash categories (lifecycle, push token, OTA, geo-fence, auth, config) are addressed separately in #5126. |
| 2026-04-14 | Transcript audit 2026-04-14 — §Mobile-settings classified R (requirement); 1 new AC added under new "Settings — permissions & preferences" section; 1 @wip BDD scenario added. | #~ — §Mobile-settings (~00:37:01) of the 2026-04-14 Dev Session transcript ("Security failures, dashboard fidelity, PPP Docs portal introduced") identified that the app must provide an in-app screen for users to view and adjust location services permission and health monitoring preferences. Without this, users who selected incorrectly during onboarding have no way to correct choices without going into device system settings. All other paragraphs were classified C or F (security cascade context, CPD home drift already tracked, process agreements). |
| 2026-04-13 | Transcript audit 2026-04-13 — §Mobile-nav classified R (requirement); 1 new AC added under Navigation/Menu section; 1 @wip BDD scenario added. | #~ — §Mobile-nav (~01:37:04) of the 2026-04-13 Dev Session transcript ("Dev environment strategy, timesheet governance, OCR, enterprise pricing") announced a redesign of the mobile navigation to a thumb-reachable bottom tab bar with at most five visible items and a "More" option revealing additional routes in the same order as the desktop menu. The existing ✅ hamburger/drawer AC (#4887) documents the prior design; this AC captures the new thumb-based design agreed with Matt. |
| 2026-04-23 | Rob / Matt | Added AC for offline geo-fence queue (#4893): device-storage persistence on geo-exit, flush on next network available (Option A — minimal queue, no UI). Updated Open Issues table to reflect current open issues (removed closed #4887, #4933, #4981, #4889, #4704; added 8 missing open issues). Observability stack changed from Azure Application Insights to Sentry. Sentry is already installed in mobile/ppp/; #5126 updated to track full SDK wiring, #5180 tracks source-map verification. Wellness wearable issues (#4890, #4677, #4646, #4678) moved off feature:mobile — they belong under feature:wellness. |
| 2026-04-21 | Rob | Triage sweep — 21 open issues under feature:mobile mapped to this spec (#5180, #5158, #5128, #5127, #5126, #5110, #5078, #4954, #4919, #4893, #4891, #4890, #4889, #4848, #4807, #4761, #4678, #4677, #4646, #4209, #3700). Reason: unblocks drift detection on the features index. |
| 2026-04-14 | Rob / Claude | Initial spec. Matt decided (this session): background tracking required for geo-fencing; Azure Application Insights is the observability stack. Cross-referenced all 12 open mobile issues. Resolves #5112. |
| 2026-04-21 | Rob / Claude | Added Security / access control section. DevelopmentScreen and AddAuditEventScreen now gated on __DEV__ so production builds cannot reach dev tooling or create audit events (#4892). Follow-up #4891 tracks replacing the Settings hardcoded-email admin gate with a proper role flag; once that lands the Development gate should tighten to admin-only in dev AND prod. |
Sources & Recordings
| Source | Notes |
|---|---|
| https://drive.google.com/drive/u/0/folders/0AKMcHQJ2RC3IUk9PVA | Description pending SGD audit |
| https://drive.google.com/file/d/1HDF4acVA0QKImQ29Wu0rp_kVIgb-VGFVg_XwcZnUV6E | Description pending SGD audit |
| https://docs.google.com/document/d/1YhgQSFL9iOlQLoTrQYSwxRNXH4Dg4wefkItcwljQZmo | Description pending SGD audit |
| https://docs.google.com/document/d/1gz0DsJC4U3zhVEJTIJ1sBLjHgP3cJ0oHYA4WW3VT2MA | Description pending SGD audit |