Skip to main content

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.

Feature ID: CL-04
Status: ✅ Implemented
Spec Reference: CL-04-progress-notes-session-documentation.md
Last Updated: 2026-02-18
Last Verified: 2026-02-18

​
Table of Contents

​
Overview

CL-04 provides progress notes and session documentation per AHCCCS Policy 940, with actual begin/end times, co-signature workflow (HR-19), electronic signatures (PF-33), and encounter-to-billing integration via events (PM-07). It depends on PF for tenancy, RBAC, notifications, and digital signatures; on CL-01/CL-03 for chart and treatment-plan context; and on PM-07 for charge capture when notes are finalized.

​
Quick Reference

ItemValue
Core tablescl_progress_notes, cl_note_treatment_goals, cl_note_templates
Triggering eventclinical_note_finalized
Publish conditionNote transitions to signed or cosigned
Key consumersPM-07 charge capture, PF-10 notifications

​
Decision Trees

​
Note finalization flow

  1. Draft note is authored in chart context.
  2. Clinician signs (or supervisor co-signs) note.
  3. If final status is signed/cosigned, publish clinical_note_finalized.
  4. PM-07 consumes event for charge capture workflow.

​
Co-signature flow

  1. Determine whether author role requires supervisory co-sign (HR-19).
  2. If required, enforce co-sign due window and PF-10 alerts.
  3. Block billing event publication until required co-sign state is satisfied.

​
Pattern Library

PatternUsage
Event-based billing bridgeclinical_note_finalized links CL-04 completion to PM-07 charge capture
Goal progress couplingcl_note_treatment_goals maps note outcomes to CL-03 goal progress
Defense-in-depth accessApp-level org filters + RLS helper checks in note reads/writes

​
Integration Points (from Spec)

DependencyPatternPurpose
PF-33 (Digital Signatures)DirectClinician electronic signatures with credentials
PF-10 (Notifications)DirectOverdue note and co-signature alerts
CL-01Internal CLNotes render within patient chart
CL-03Internal CLNotes link to treatment plan goals via cl_note_treatment_goals; goal progress_pct updated when notes are saved
PM-07Event-basedCompleted notes trigger charge capture via clinical_note_finalized when status is signed or cosigned — see CL-PM-ENCOUNTER-TO-BILLING.md
HR-19Cross-coreCo-signature requirements per clinical oversight rules (BHT/BHPP notes require BHP co-sign within 14 days)

​
API / Data Contracts

  • Progress notes: Tables cl_progress_notes, cl_note_treatment_goals, cl_note_templates; all scoped by organization_id; RLS via SECURITY DEFINER helpers (e.g. cl_fn_check_org_membership). No direct FK to pm_encounters; encounter_id validated at application layer (core independence).
  • Event: clinical_note_finalized — published when note status transitions to signed or cosigned; payload must include organization_id, clinical_note_id, encounter_id, patient_id, finalized_at. See CL-PM-ENCOUNTER-TO-BILLING.md.

​
Code Examples

​
Example: clinical_note_finalized payload

{
  "event_type": "clinical_note_finalized",
  "organization_id": "org-uuid",
  "clinical_note_id": "note-uuid",
  "encounter_id": "encounter-uuid",
  "patient_id": "patient-uuid",
  "status": "signed",
  "finalized_at": "2026-02-17T18:30:00Z",
  "actor_id": "clinician-uuid"
}

​
Example: org access guard pattern

USING (cl_fn_check_org_membership(organization_id, auth.uid()))

​
Event Contracts

  • clinical_note_finalized: CL publishes when a progress note is signed or cosigned; PM-07 (charge capture) subscribes. Payload schema and subscription details in CL-PM-ENCOUNTER-TO-BILLING.md.

​
Security and RLS

  • RLS on cl_progress_notes, cl_note_treatment_goals, cl_note_templates; USING and WITH CHECK use SECURITY DEFINER helpers; no direct queries to RLS-protected tables (constitution §5.7).
  • UPDATE policies include WITH CHECK for organization_id (constitution §5.2.4).
  • Part 2 SUD: restrict via consent check (e.g. cl_has_sud_consent() SECURITY DEFINER) per CL-11; access logged per HIPAA.

​
Common Mistakes

MistakeImpactFix
Missing organization_id in event payloadCross-tenant ambiguityRequire tenant context in all published events
Publishing before final sign-offInvalid charge capture timingPublish only when status is signed/cosigned
Trusting PM encounter FK at DB layerCore boundary violationKeep encounter validation in app/platform integration layer

​
Pre-Flight Checklist

  • RLS + FORCE RLS enabled on all CL-04 tables.
  • clinical_note_finalized payload contract documented and validated.
  • Co-signature requirements mapped to HR-19 role rules.
  • Error messages sanitized for all UI-facing failures.
  • Integration tests cover note finalization → PM-07 handoff.