Feature ID: CL-22Documentation Index
Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
Use this file to discover all available pages before exploring further.
Status: ✅ Implemented
Spec: CL-22-vital-signs-biometric-tracking.md
Last Updated: 2026-02-23
Last Verified: 2026-02-23
Overview
CL-22 provides vital signs and biometric tracking for behavioral health: standardized capture, longitudinal trending, metabolic monitoring, and CDS/FHIR integration. Integration is within CL (chart, CDS, lab, outcomes, FHIR, consent) and Platform Foundation; no cross-core dependencies outside PF.Quick Reference
| I need to… | Pattern | Location |
|---|---|---|
| Load chart vitals safely | org + chart scoped query with RLS | Vitals/Biometrics CRUD |
| Trigger CDS from thresholds | CL-08 threshold evaluation contract | CL-08 CDS Contract |
| Enforce consent for sensitive contexts | CL-11 helper checks where applicable | PHI Consent Enforcement by Data Type (CL-11) |
| Validate policy requirements before rollout | RLS + WITH CHECK + PHI handling | Security and RLS |
Decision Tree
- Is the operation standard vitals/biometrics read/write under TPO?
- Yes → apply org/chart RLS and permission checks.
- Is the record tied to SUD/sensitive behavioral-health context?
- Yes → enforce CL-11 consent helper before access.
- Is downstream alerting required?
- For MVP: compute status on read.
- Post-MVP: publish event contracts once defined.
Pattern Library
- Tenant-scoped CRUD pattern: always include
organization_id+ chart scoping in mutations/queries. - Consent-conditional RLS pattern: apply CL-11 helper for sensitive monitoring contexts.
- Contract-driven integration pattern: document CL-08/CL-10/CL-16 consumption paths before implementation.
Common Mistakes
| Pitfall | Impact | Fix |
|---|---|---|
| Querying by chart only without org scope | Tenant isolation risk | Include organization_id filter in mutation/query paths |
| Treating all vitals contexts identically | Missing consent gates for sensitive scenarios | Apply CL-11 checks where behavioral-health sensitivity applies |
| Publishing undocumented events in MVP | Contract drift | Keep MVP event-free and document post-MVP events first |
Pre-Flight Checklist
- CRUD paths enforce org + chart scoping.
- RLS policies include SECURITY DEFINER helper usage and UPDATE WITH CHECK.
- Consent enforcement paths reviewed for sensitive monitoring data.
- CL-08/CL-10/CL-16 integration assumptions documented and validated.
Integration Points (from Spec)
| Dependency | Pattern | Purpose |
|---|---|---|
| CL-01 (Patient Chart) | Data / UI | Chart-level display and trending of vitals/biometrics |
| CL-08 (Clinical Decision Support) | API / Data | Threshold-based CDS alerts from vitals/biometric values |
| CL-09 (Lab Orders/Results) | API / Data | Optional linkage to lab result workflows |
| CL-10 (Outcomes Tracking) | API / Data | Outcomes/quality metrics inputs |
| CL-16 (FHIR Interoperability) | API / Data | FHIR Observation mapping for vitals |
| CL-11 (Consent / Part 2) | RLS / API | Consent and sensitive-access enforcement where applicable |
| PF-01, PF-02, PF-10, PF-70 | Platform | Organizations, RBAC, notifications, terminology as applicable |
API Contracts
Vitals/Biometrics CRUD
Organization- and chart-scoped CRUD via Supabase client with RLS enforcement. No public REST API for MVP.| Operation | Table | Permission Key | Defense-in-Depth |
|---|---|---|---|
| List vitals by chart | cl_vital_signs | cl.vitals.view | .eq('organization_id', orgId).eq('chart_id', chartId) |
| Create vital sign | cl_vital_signs | cl.vitals.create | .insert({ organization_id, chart_id, ... }) |
| Update vital sign | cl_vital_signs | cl.vitals.update | .eq('id', id).eq('organization_id', orgId) |
| List biometrics by chart | cl_biometrics | cl.biometrics.view | .eq('organization_id', orgId).eq('chart_id', chartId) |
| Create/update biometrics | cl_biometrics | cl.biometrics.manage | .eq('organization_id', orgId) |
| List metabolic events | cl_metabolic_monitoring_events | cl.metabolic_monitoring.view | .eq('organization_id', orgId).eq('chart_id', chartId) |
| Create/update metabolic event | cl_metabolic_monitoring_events | cl.metabolic_monitoring.manage | .eq('organization_id', orgId) |
CL-08 CDS Contract
CL-22 exposes a threshold evaluation service that CL-08 may consume:- Input: Vital sign type (e.g.,
systolic_bp), value,chart_id,captured_at - Output: Out-of-range flag with severity (e.g.,
critical,warning,normal) - Pattern: CL-08 subscribes to vitals writes or calls threshold evaluation on chart load
- Implementation: Deferred to Phase 4 (T13); CL-08 extension pattern must be verified
CL-16 FHIR Observation Mapping
Contract for mappingcl_vital_signs / cl_biometrics to FHIR Observation resources. Documentation-only for MVP (CL-16 is “Not Started”). To be expanded in CL-16 integration doc when implemented.
CL-10 Outcomes Inputs
CL-22 provides consumable aggregates for CL-10 quality metrics:- Vitals summary by chart/period
- Metabolic monitoring completion rate
- Documentation-only for MVP (CL-10 is “Not Started”)
PHI Consent Enforcement by Data Type (CL-11)
- Standard vital signs (e.g. blood pressure, heart rate, temperature, weight, height) are generally covered by Treatment, Payment, and Health Care Operations (TPO) and do not require separate CL-11 consent for read/write via the vitals/biometrics CRUD endpoints.
- Sensitive / behavioral health data in
cl_vital_signs,cl_biometrics, andcl_metabolic_monitoring_eventsthat relate to behavioral health (e.g. SUD, psych medication metabolic monitoring) or sensitive conditions (e.g. HIV, hepatitis) must enforce 42 CFR Part 2 / explicit consent per CL-11 before access. Examples: metabolic monitoring events tied to antipsychotic or MAT regimens; biometrics or vitals linked to SUD or HIV/hepatitis context. RLS policies must call the CL-11 consent enforcement mechanism (e.g.cl_check_sud_consentor equivalent SECURITY DEFINER helper) for those rows or contexts; API layer must not bypass consent checks. See CL-11 Consent Integration. - Example for implementers: Behavioral-health context that triggers CL-11 checks includes vitals captured during a SUD counseling visit, or metabolic monitoring in
cl_metabolic_monitoring_eventslinked to a MAT/antipsychotic prescription; for such rows, enforce access viacl_check_sud_consent(or equivalent) before any read/write oncl_vital_signs,cl_biometrics, orcl_metabolic_monitoring_events.
cl_metabolic_monitoring_events SELECT policy MUST include cl_check_sud_consent(chart_id, 'metabolic_monitoring', auth.uid()). Standard vitals and biometrics SELECT policies use cl_has_org_access only (TPO-covered).
Event Contracts
MVP Strategy: No events are published for CL-22 MVP. Metabolic monitoring overdue/due status is computed on read (query-time) rather than via cron or event publishing. This aligns with CL-21’s deferred event strategy. Future (post-MVP): If CL-22 publishes events (e.g.,cl_vital_sign_out_of_range, cl_metabolic_monitoring_overdue), they will be documented in EVENT_CONTRACTS.md.
Platform Integration Layer Usage
- CL-22 is owned by CL core; no direct imports from other cores. All integration with CL-01, CL-08, CL-09, CL-10, CL-16, CL-11 is within CL or via existing platform/CL contracts.
Security and RLS
- Protected tables:
cl_vital_signs,cl_biometrics,cl_metabolic_monitoring_events; all contain PHI. - RLS: Organization and chart access enforced via SECURITY DEFINER helpers.
- WITH CHECK: UPDATE policies must include WITH CHECK per constitution §5.2.4.
- PHI: All data in these tables is PHI; handle accordingly.
- CL-11 consent: Standard vitals (TPO) do not require separate Part 2 consent;
cl_metabolic_monitoring_eventsSELECT policy requirescl_check_sud_consentfor behavioral health / SUD / sensitive-condition metabolic monitoring events—see PHI Consent Enforcement section above. - Soft delete: Intentionally omitted; clinical measurements are immutable once captured (see spec Soft Delete Decision).