ims/docs/superpowers/plans/2026-07-11-phase-5-6-usability-compliance-analytics.md

Phase 5 & 6 — Usability, Compliance Hardening, Analytics

Context

Phases 0–4 complete. Gap audit against PRD (docs/01_PRD_HSE_Incident_Management_System.md) found 10 specced features missing or partial. User approved all four gap groups: core usability, compliance hardening, evidence UX, and analytics. Split into Phase 5 (usability + compliance + evidence) and Phase 6 (analytics/AI), matching the existing phase-plan convention in docs/superpowers/plans/.

Verified current state (Explore audit, 2026-07-11):

• notifications_log table exists (supabase/migrations/20260709000006_notifications_audit.sql) — no UI
• app/(protected)/admin/page.tsx is a stub
• app/api/incidents/[id]/route.ts has no PATCH; no closure lock
• app/api/incidents/[id]/jkkp-pdf/route.ts supports jkkp6/jkkp7 only; lib/incidents/dosh.ts:45 already computes requires_jkkp8
• components/incidents/report-form.tsx branches only on injury_involved
• Investigation schema has alcohol_test_result, witness_statement_refs (migrations/...004:27-28) — no UI
• app/(protected)/hse/incidents/page.tsx:18 hard .limit(100), no pagination
• lib/supabase/storage.ts stores SHA-256 file_hash; no thumbnails
• Dashboard has type/site breakdown + zone heatmap; no time-series, no root-cause trend

Conventions to follow (established, do not deviate)

• Every DB mutation writes audit_log; RLS at DB level for all new tables/columns
• AI routes: claude-opus-4-8, thinking: {type:"adaptive"}, forced tool_choice, validate tool output, 503 on model failure; getApiKey(supabase, key) (lib/settings.ts) before client construction (lib/claude/client.ts)
• Notifications: reuse lib/notifications/email.ts, lib/notifications/whatsapp.ts
• i18n: add strings to lib/i18n/locales.ts (EN/MS/ZH)
• Client fetches prefixed /ims basePath
• TDD per repo practice; tests in tests/ mirroring lib paths (61 passing currently)

---

Phase 5 — Usability & Compliance Completion

Task 1: In-app notification bell + badge

• Migration: extend notifications_log if needed (add read_at TIMESTAMPTZ, index on recipient+read)
• app/api/notifications/route.ts — GET unread list (RLS: own rows), POST mark-read
• components/notifications/bell.tsx — badge count, dropdown list; mount in app/(protected)/layout.tsx
• Write in-app rows at the same points email/WhatsApp fire (new incident, CAPA assign/escalate, verification)

Task 2: Admin user + site/zone management

• Replace stub app/(protected)/admin/page.tsx
• User list: invite (Supabase admin API server-side), role assign, deactivate — admin-only RLS + server-side role check via lib/auth/roles.ts
• Site/zone CRUD against sites/zones tables (migration 001)
• All mutations audit-logged

Task 3: Incident closure lock + addenda

• Migration: incident_addenda table (incident_id, author, body, created_at) with RLS
• Add PATCH guard in app/api/incidents/[id]/route.ts and triage/investigation/capa routes: reject mutation when closed_at IS NOT NULL (DB trigger preferred — belt and braces)
• Addenda UI on components/incidents/incident-detail.tsx for closed incidents

Task 4: JKKP 8 annual register export

• lib/pdf/jkkp8.ts (or Excel via existing export route pattern app/api/dashboard/export/route.ts) — annual register of all reportable incidents for a chosen year
• app/api/reports/jkkp8/route.ts — HSE/admin only; reuse lib/incidents/dosh.ts flags
• Download button on HSE dashboard; reminder banner in January while register unsubmitted

Task 5: Type-specific intake forms

• Extend components/incidents/report-form.tsx: conditional field groups per type — environmental (spill volume/substance/containment), MHE/asset (equipment id, LOTO applied), security, fire; near-miss stays minimal by design
• Store in existing JSONB detail column if present, else migration adds one
• Validate in lib/incidents/validate.ts; translate new labels

Task 6: Witness statement + alcohol test UI

• Add fields to components/incidents/investigation-form.tsx wired to existing alcohol_test_result, witness_statement_refs columns
• Witness statement file uploads reuse components/incidents/file-upload.tsx with stage tag

Task 7: Incident list pagination

• Server-side range pagination in app/(protected)/hse/incidents/page.tsx + components/incidents/incident-list.tsx (searchParams page/pageSize, .range(), count)
• Same for supervisor incident list

Task 8: Evidence thumbnails

• Supabase Storage image transform (getPublicUrl with transform: {width}) for image types in components/incidents/evidence-gallery.tsx; icon fallback for video/pdf/doc
• No new infra if Supabase transform available on plan; else client-side next/image sizing of signed URL

Task 9: Housekeeping

• Delete stray duplicates lib/notifications/whatsapp 2.ts, tests/lib/notifications/whatsapp.test 2.ts (verify identical/stale vs canonical first)

---

Phase 6 — Analytics & Predictive Safety

Task 1: Dashboard time-series

• Extend app/api/dashboard/stats/route.ts: monthly incident counts by type (12 mo), leading vs lagging trend, CAPA on-time trend
• Chart components on app/(protected)/hse/dashboard/page.tsx (lightweight — no heavy chart lib unless one already present)

Task 2: Top root cause trended

• Aggregate root_cause_category (phase-2 RCA data) by month; top-5 table + trend on dashboard

Task 3: AI rising-risk heatmap

• app/api/dashboard/ai/risk-flags/route.ts — server-side Claude call per AI-route conventions; input: 90d near-miss + incident + zone aggregates; output: flagged zones/shifts with rationale (forced tool_use schema)
• Panel on management + HSE dashboards, clearly labelled as AI suggestion; log suggestion to audit_log per convention

---

Verification

• npm test — all existing 61 tests plus new unit tests per task (escalation-style pattern in tests/lib/)
• Manual: run app, walk lifecycle — report (each type) → triage → investigate (witness/alcohol) → CAPA → verify → close → confirm lock + addenda; bell badge increments; admin creates user + zone; JKKP 8 downloads; pagination past 100 rows (seed if needed)
• graphify update . after code changes
• Update docs/superpowers/plans/ with phase-5/6 plan docs and memory phases.md on completion

---

Completion Record (2026-07-12)

All Phase 5 and Phase 6 tasks implemented on branch phase-5-6. 112 tests passing (23 files), tsc --noEmit clean, next build clean.

Notable deviations/additions vs plan:

• Incident close endpoint did not exist at all — added POST /api/incidents/[id]/close (verification status + all CAPAs verified required) alongside the lock.
• In-app notification inserts go through create_in_app_notification SECURITY DEFINER RPC (reporters are not covered by the elevated INSERT policy).
• Fixed 9 pre-existing missing /ims basePath prefixes across fetch calls and download links (similar-incidents-panel, investigation-form ×3, triage-form ×2, verify-form, JKKP PDF links ×2, dashboard/management export links).
• New migrations: 20260712000016_in_app_notifications, 20260712000017_closure_lock_addenda, 20260712000018_type_details.