Clinical Reporting & Quality Measures — Integration

​

Cross-Core Integration Matrix

​

Overview

​

Quick Reference

​

Decision Tree

1. Need report output?
   Use CL definitions/runs with PF-12 execution pipeline.
2. Need compliance escalation from incident state-reporting transition?
   Publish cl_incident_reported with standard event envelope fields.
3. Need accreditation evidence?
   Use CL-15 generated reports as GR-08 evidence input.

​

Pattern Library

• Configurable report pattern: definitions + run records decoupled from execution engine.
• Event-driven compliance pattern: incident reported event fans out to GR compliance consumers.
• Tenant-safe reporting pattern: org-scoped RLS + permission keys for all report/incident tables.

​

Common Mistakes

​

Pre-Flight Checklist

• PF-12 integration path and report schemas validated.
• cl_incident_reported contract includes standard envelope fields.
• GR-03/GR-08 subscriber expectations verified.
• RLS + WITH CHECK + permission keys validated for release.

​

Integration Points (from Spec)

​

API / Data Contracts

• Report definitions: Stored in cl_report_definitions; consumed by PF-12 for generation; schedules and recipients configurable.
• Report runs: Stored in cl_report_runs; links to PF-12 and document storage; audit trail for all runs.
• Incidents: Stored in cl_incidents; AZDHS reporting timeframes (death 1h, serious injury 6h, abuse/neglect/elopement immediate); immutability once reported.

​

Event Contracts

interface ClIncidentReportedPayload {
  event_type: 'cl_incident_reported'; // required event schema field
  incident_id: string;              // UUID of the reported incident
  organization_id: string;          // UUID of the organization
  timestamp: string;                // ISO timestamp (event emission time)
  user_id: string;                  // user UUID initiating/reporting event
  correlation_id?: string;          // optional trace correlation
  chart_id: string | null;          // UUID of the patient chart, if applicable
  incident_type: string;            // 'death' | 'serious_injury' | 'abuse' | 'neglect' | 'elopement' | 'other'
  severity: string;                 // 'critical' | 'major' | 'moderate' | 'minor'
  reported_to_state_at: string;     // ISO timestamp
  reporting_deadline: string;       // ISO timestamp
  reported_by: string;              // user UUID (legacy compatibility)
  custom_fields: Record<string, unknown>;
}

• Safe: incident_id, organization_id, incident_type, severity, reported_by
• Log as flag only: chart_id (log has_chart_id: true/false)
• Prohibited: patient names, chart content
• custom_fields must be sanitized before logging

​

Security and RLS

• All three tables use ENABLE ROW LEVEL SECURITY and FORCE ROW LEVEL SECURITY (PHI tables per CL standard).
• RLS on cl_report_definitions, cl_report_runs, and cl_incidents via SECURITY DEFINER helpers (e.g. cl_has_org_access); no direct queries to RLS-protected tables in policies (constitution §5.7).
• UPDATE policies include WITH CHECK on organization_id (§5.2.4).
• DELETE policies restricted to pf_is_org_admin(auth.uid(), organization_id) (admin-only, consistent with CL-14).
• Permission keys: cl.report_definitions.view/create/delete, cl.report_runs.view/run, cl.incidents.view/create/update/delete (seed in migration per PF-30).

​

Related Docs

• Spec
• EVENT_CONTRACTS.md — cl_incident_reported
• PLATFORM_INTEGRATION_LAYERS.md (PF-12 Reports)
• CROSS_CORE_INTEGRATIONS.md

​

Phase 2 & 3 Addendum (2026-05-18)

​

Shipped

• Dual-track incident deadlines (T1, T3, T6) — cl_module_settings extended with incident_deadline_track (azdhs | ahcccs | dual, default azdhs), incident_business_day_config JSONB, and incident_sentinel_options JSONB. Client-side deadline math lives in src/cores/cl/utils/incidentDeadline.ts and mirrors the server-side AZDHS trigger. CL settings UI exposes the subsection in CLSettingsForm.tsx.
• clinical_audit report type (T1) — cl_report_definitions_report_type_check widened to include clinical_audit. UI renderer is not yet shipped (T5 pending).
• Portal Quality Measures (T8 + T-COMP-1 portal half) — read-only patient route /portal/clinical/quality renders cl_outcome_measures filtered by org-configurable cl_module_settings.portal_qm_config (instruments allow-list, measure types, SUD-consent flag). SUD-tagged instruments (audit, dast10) are filtered out via cl_check_sud_consent(chart_id, 'outcome_measure', user_id); fail-closed on RPC error. Patient-facing notice is generic (no PHI / no measure name leak).
• @/platform/governance read-only contract (T10 partial) — new platform layer at src/platform/governance/ exposes useCarfReadiness, computeReadinessScore, computeReadinessTier, and GR-08 row types so CL (and future cores) can read CARF accreditation data without importing from @/cores/gr. The CARF dashboard page itself (CarfReadinessPage.tsx) is still pending.

​

Pending

• T5 — clinical_audit report-type form/renderer with dimension checkboxes
• T7 — Deployment guide documenting dual-track deadline rationale
• T9 — Automated HEDIS QM calculation wired into report runs
• T10 — CarfReadinessPage.tsx + route + breadcrumb (contract is ready)
• T-COMP-2 — HEDIS measure conformance documentation
• T-COMP-3 — Audit logging on clinical_audit report generation/export and cl_module_settings dual-track field changes
• T-DOCS — User guide update

​

Blocked

• T2 — restraint_event_id migration on cl_incidents (waits on CL-13)
• T4 — Restraint/seclusion event picker in incident form (waits on T2)

​

Cross-core surface changes

• Added: @/platform/governance (read-only). Consumers: CL-15 (CARF dashboard, pending), potential JCAHO / COA dashboards. Mutations remain inside GR core.
• No new cl_* -> pm_* or cl_* -> gr_* FKs in this drop.