> ## Documentation Index > Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt > Use this file to discover all available pages before exploring further. # Clinical Reporting & Quality Measures — Integration > Feature ID: CL-15 Status: ✅ Implemented Spec Reference: CL-15-clinical-reporting-quality-measures.md Last Updated: 2026-02-23 **Feature ID:** CL-15\ **Status:** ✅ Implemented\ **Spec Reference:** [CL-15-clinical-reporting-quality-measures.md](../../../specs/cl/specs/CL-15-clinical-reporting-quality-measures.md)\ **Last Updated:** 2026-05-18 (Phase 2/3 partial) *** ## Cross-Core Integration Matrix | Core Area | Integration Owner | Dependencies | Impact | Status | | --------------------------------------------- | ----------------- | ------------------------------------ | ------------------------------------------------------------------------------------- | ------------- | | CL-15 (Clinical Reporting & Quality Measures) | CL | PF-12, CL-10, CL-01–04, GR-03, GR-08 | Report definitions, runs, incidents; PF-12 report engine; GR compliance/accreditation | ✅ Implemented | *** ## Overview CL-15 defines clinical reporting and quality measures: Joint Commission, CARF, NCQA/HEDIS, AHCCCS compliance dashboards and report definitions, configurable report builder, scheduled generation, export (PDF, CSV, Excel), and AZDHS incident reporting with mandated timeframes. It depends on PF (organizations, RBAC, reports), CL-01/02/03/04/10 (chart, assessments, treatment plan, progress notes, outcomes). Data flows to/from PF-12 (report engine) and CL-10 (outcome measures). GR-03 (Compliance Tracking) and GR-08 (Accreditation Management) are downstream consumers: `cl_incident_reported` events trigger compliance check updates, and CL-15 reports serve as accreditation evidence for Joint Commission and CARF. ## Quick Reference | I need to… | Pattern | Location | | -------------------------------------------------- | ------------------------------------------- | --------------------------------------------- | | Generate compliance reports | PF-12 report engine + CL report definitions | [API / Data Contracts](#api--data-contracts) | | Process incident-triggered compliance flow | `cl_incident_reported` event contract | [Event Contracts](#event-contracts) | | Validate release safety for reporting integrations | RLS + permission + contract checks | [Pre-Flight Checklist](#pre-flight-checklist) | ## 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 | Mistake | Impact | Fix | | ----------------------------------------------------- | ------------------------------------- | ------------------------------------------------------- | | Omitting event envelope metadata | Subscriber ambiguity and tracing gaps | Include event\_type/org/timestamp/user metadata fields | | Treating report tables as unrestricted analytics data | PHI exposure risk | Keep strict RLS and permission checks on report sources | | Skipping deadline-specific incident semantics | Compliance misses | Preserve explicit AZDHS timing metadata in contracts | ## 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) | Dependency | Pattern | Purpose | | -------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PF-01 (Organizations & Sites) | Direct | Multi-tenant isolation | | PF-02 (RBAC) | Direct | Permission keys; role-based access to reports and incidents | | PF-12 (Reports) | Platform | Report generation engine; scheduled and on-demand runs | | CL-10 (Outcomes) | Internal | Outcome measure data for HEDIS/CARF reporting | | CL-01, CL-02, CL-03, CL-04 | Internal | Clinical data aggregation for compliance reporting | | GR-03 (Compliance Tracking) | Event | `cl_incident_reported` triggers `gr-handle-incident-reported` edge function via `fw_domain_events` trigger; auto-creates `gr_compliance_checks` row with `result: fail`, `check_type: ad_hoc` | | GR-08 (Accreditation Management) | Data | CL-15 reports serve as accreditation evidence (Joint Commission, CARF) | *** ## 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 | Event Name | Category | Owning Core | Trigger | Subscribers | Payload | | ---------------------- | --------- | ----------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `cl_incident_reported` | lifecycle | CL | `reported_to_state_at` transitions from NULL to non-NULL | GR-03 (Compliance Tracking), GR-04 (Audit Management), GR-08 (Accreditation Management), PF-10 (Notifications) | See [EVENT\_CONTRACTS.md — cl\_incident\_reported](./EVENT_CONTRACTS.md#event-cl_incident_reported) | **Payload Schema:** ```typescript theme={null} 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; } ``` **PHI/PII Logging Guidelines:** * **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](../../../specs/cl/specs/CL-15-clinical-reporting-quality-measures.md) * [EVENT\_CONTRACTS.md — cl\_incident\_reported](./EVENT_CONTRACTS.md#event-cl_incident_reported) * [PLATFORM\_INTEGRATION\_LAYERS.md](PLATFORM_INTEGRATION_LAYERS.md) (PF-12 Reports) * [CROSS\_CORE\_INTEGRATIONS.md](CROSS_CORE_INTEGRATIONS.md) *** ## Phase 2 & 3 Addendum (2026-05-18) Tracks the partial shipment of [CL-15-PHASE-2-3-EXPANSION](../../../specs/cl/specs/CL-15-PHASE-2-3-EXPANSION.md). See `CL-15-PHASE-2-3-TASKS.md` for per-task status. ### 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.