feat(attendance): add geofence monitoring and policy controls

docs/BACKEND/API_GUIDES/V2/README.md

@@ -21,10 +21,11 @@ What was validated live against the deployed stack:
 - client sign-in
 - staff auth bootstrap
 - client dashboard, billing, coverage, hubs, vendors, managers, team members, orders, and reports
-- client hub and order write flows
+- client coverage incident feed for geofence and override review
+- client hub, order, coverage review, and late-worker cancellation flows
 - client invoice approve and dispute
 - staff dashboard, availability, payments, shifts, profile sections, documents, certificates, attire, bank accounts, benefits, and time card
-- staff availability, profile, tax form, bank account, shift apply, shift accept, clock-in, clock-out, and swap request
+- staff availability, profile, tax form, bank account, shift apply, shift accept, clock-in, clock-out, location stream upload, and swap request
 - direct file upload helpers and verification job creation through the unified host
 - client and staff sign-out
 
@@ -76,7 +77,36 @@ All routes return the same error envelope:
 }
 ```
 
-## 4) Route model
+## 4) Attendance policy and monitoring
+
+V2 now supports an explicit attendance proof policy:
+
+- `NFC_REQUIRED`
+- `GEO_REQUIRED`
+- `EITHER`
+
+The effective policy is resolved as:
+
+1. shift override if present
+2. hub default if present
+3. fallback to `EITHER`
+
+For geofence-heavy staff flows, frontend should read the policy from:
+
+- `GET /staff/clock-in/shifts/today`
+- `GET /staff/shifts/:shiftId`
+- `GET /client/hubs`
+
+Important operational rules:
+
+- outside-geofence clock-ins can be accepted only when override is enabled and a written reason is provided
+- NFC mismatches are rejected and are not overrideable
+- background location streams are stored as raw batch payloads in the private v2 bucket and summarized in SQL for query speed
+- incident review lives on `GET /client/coverage/incidents`
+- confirmed late-worker recovery is exposed on `POST /client/coverage/late-workers/:assignmentId/cancel`
+- queued manager alerts are written to `notification_outbox`; this is durable notification orchestration, not a full push delivery worker yet
+
+## 5) Route model
 
 Frontend sees one base URL and one route shape:
 
@@ -94,7 +124,7 @@ Internally, the gateway still forwards to:
 | writes and workflow actions | `command-api-v2` |
 | reads and mobile read models | `query-api-v2` |
 
-## 5) Frontend integration rule
+## 6) Frontend integration rule
 
 Use the unified routes first.
 
@@ -106,7 +136,7 @@ Do not build new frontend work on:
 
 Those routes still exist for backend/internal compatibility, but mobile/frontend migration should target the unified surface documented in [Unified API](./unified-api.md).
 
-## 6) Docs
+## 7) Docs
 
 - [Unified API](./unified-api.md)
 - [Core API](./core-api.md)

docs/BACKEND/API_GUIDES/V2/mobile-api-gap-analysis.md

@@ -16,6 +16,7 @@ That includes:
 - staff dashboard, availability, payments, shifts, profile sections, documents, attire, certificates, bank accounts, benefits, privacy, and frequently asked questions
 - staff availability, tax forms, emergency contacts, bank account, shift decision, clock-in/out, and swap write flows
 - upload and verification flows for profile photo, government document, attire, and certificates
+- attendance policy enforcement, geofence incident review, background location-stream ingest, and queued manager alerts
 
 ## What was validated live
 
@@ -41,5 +42,6 @@ The remaining items are not blockers for current mobile frontend migration.
 They are follow-up items:
 
 - extend the same unified pattern to new screens added after the current mobile specification
-- add stronger observability and contract automation around the unified route surface
+- add stronger contract automation around the unified route surface
+- add a device-token registry and dispatch worker on top of `notification_outbox`
 - keep refining reporting and financial read models as product scope expands

docs/BACKEND/API_GUIDES/V2/unified-api.md

@@ -41,6 +41,7 @@ The gateway keeps backend services separate internally, but frontend should trea
 - `GET /client/coverage`
 - `GET /client/coverage/stats`
 - `GET /client/coverage/core-team`
+- `GET /client/coverage/incidents`
 - `GET /client/hubs`
 - `GET /client/cost-centers`
 - `GET /client/vendors`
@@ -114,6 +115,7 @@ The gateway keeps backend services separate internally, but frontend should trea
 - `POST /staff/profile/setup`
 - `POST /staff/clock-in`
 - `POST /staff/clock-out`
+- `POST /staff/location-streams`
 - `PUT /staff/availability`
 - `POST /staff/availability/quick-set`
 - `POST /staff/shifts/:shiftId/apply`
@@ -159,7 +161,87 @@ These are exposed as direct unified aliases even though they are backed by `core
 - `roleId` on `POST /staff/shifts/:shiftId/apply` is the concrete `shift_roles.id` for that shift, not the catalog role definition id.
 - `accountType` on `POST /staff/profile/bank-accounts` accepts either lowercase or uppercase and is normalized by the backend.
 - File upload routes return a storage path plus a signed URL. Frontend uploads the file directly to storage using that URL.
-- Verification routes are durable in the v2 backend and were validated live through document, attire, and certificate upload flows.
+- Verification upload and review routes are live and were validated through document, attire, and certificate flows. Do not rely on long-lived verification history durability until the dedicated persistence slice is landed in `core-api-v2`.
+- Attendance policy is explicit. Reads now expose `clockInMode` and `allowClockInOverride`.
+- `clockInMode` values are:
+  - `NFC_REQUIRED`
+  - `GEO_REQUIRED`
+  - `EITHER`
+- For `POST /staff/clock-in` and `POST /staff/clock-out`:
+  - send `nfcTagId` when clocking with NFC
+  - send `latitude`, `longitude`, and `accuracyMeters` when clocking with geolocation
+  - send `overrideReason` only when the worker is bypassing a geofence failure and the shift/hub allows overrides
+- `POST /staff/location-streams` is for the background tracking loop after a worker is already clocked in.
+- `GET /client/coverage/incidents` is the review feed for geofence breaches, missing-location batches, and clock-in overrides.
+- `POST /client/coverage/late-workers/:assignmentId/cancel` is the client-side recovery action when lateness is confirmed by incident evidence or elapsed grace time.
+- Raw location stream payloads are stored in the private v2 bucket; SQL only stores the summary and incident index.
+
+### Clock-in request example
+
+```json
+{
+  "shiftId": "uuid",
+  "sourceType": "GEO",
+  "deviceId": "iphone-15-pro",
+  "latitude": 37.4221,
+  "longitude": -122.0841,
+  "accuracyMeters": 12,
+  "overrideReason": "Parking garage entrance is outside the marked hub geofence",
+  "capturedAt": "2026-03-16T09:00:00.000Z"
+}
+```
+
+### Location-stream batch example
+
+```json
+{
+  "shiftId": "uuid",
+  "sourceType": "GEO",
+  "deviceId": "iphone-15-pro",
+  "points": [
+    {
+      "capturedAt": "2026-03-16T09:15:00.000Z",
+      "latitude": 37.4221,
+      "longitude": -122.0841,
+      "accuracyMeters": 12
+    },
+    {
+      "capturedAt": "2026-03-16T09:30:00.000Z",
+      "latitude": 37.4301,
+      "longitude": -122.0761,
+      "accuracyMeters": 20
+    }
+  ],
+  "metadata": {
+    "source": "background-workmanager"
+  }
+}
+```
+
+### Coverage incidents response shape
+
+```json
+{
+  "items": [
+    {
+      "incidentId": "uuid",
+      "assignmentId": "uuid",
+      "shiftId": "uuid",
+      "staffName": "Ana Barista",
+      "incidentType": "OUTSIDE_GEOFENCE",
+      "severity": "CRITICAL",
+      "status": "OPEN",
+      "clockInMode": "GEO_REQUIRED",
+      "overrideReason": null,
+      "message": "Worker drifted outside hub geofence during active monitoring",
+      "distanceToClockPointMeters": 910,
+      "withinGeofence": false,
+      "occurredAt": "2026-03-16T09:30:00.000Z"
+    }
+  ],
+  "requestId": "uuid"
+}
+```
 
 ## 6) Why this shape