> ## 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.

# Progress Notes & Session Documentation — Integration

> 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

**Feature ID:** CL-04\
**Status:** ✅ Implemented\
**Spec Reference:** [CL-04-progress-notes-session-documentation.md](../../../specs/cl/specs/CL-04-progress-notes-session-documentation.md)\
**Last Updated:** 2026-02-18\
**Last Verified:** 2026-02-18

***

## Table of Contents

* [Overview](#overview)
* [Quick Reference](#quick-reference)
* [Decision Trees](#decision-trees)
* [Pattern Library](#pattern-library)
* [Integration Points (from Spec)](#integration-points-from-spec)
* [API / Data Contracts](#api--data-contracts)
* [Code Examples](#code-examples)
* [Event Contracts](#event-contracts)
* [Security and RLS](#security-and-rls)
* [Common Mistakes](#common-mistakes)
* [Pre-Flight Checklist](#pre-flight-checklist)
* [Related Docs](#related-docs)

***

## 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

| Item              | Value                                                               |
| ----------------- | ------------------------------------------------------------------- |
| Core tables       | `cl_progress_notes`, `cl_note_treatment_goals`, `cl_note_templates` |
| Triggering event  | `clinical_note_finalized`                                           |
| Publish condition | Note transitions to `signed` or `cosigned`                          |
| Key consumers     | PM-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

| Pattern                    | Usage                                                                    |
| -------------------------- | ------------------------------------------------------------------------ |
| Event-based billing bridge | `clinical_note_finalized` links CL-04 completion to PM-07 charge capture |
| Goal progress coupling     | `cl_note_treatment_goals` maps note outcomes to CL-03 goal progress      |
| Defense-in-depth access    | App-level org filters + RLS helper checks in note reads/writes           |

***

## Integration Points (from Spec)

| Dependency                 | Pattern     | Purpose                                                                                                                                                                           |
| -------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PF-33 (Digital Signatures) | Direct      | Clinician electronic signatures with credentials                                                                                                                                  |
| PF-10 (Notifications)      | Direct      | Overdue note and co-signature alerts                                                                                                                                              |
| CL-01                      | Internal CL | Notes render within patient chart                                                                                                                                                 |
| CL-03                      | Internal CL | Notes link to treatment plan goals via `cl_note_treatment_goals`; goal progress\_pct updated when notes are saved                                                                 |
| PM-07                      | Event-based | Completed notes trigger charge capture via `clinical_note_finalized` when status is `signed` or `cosigned` — see [CL-PM-ENCOUNTER-TO-BILLING.md](./CL-PM-ENCOUNTER-TO-BILLING.md) |
| HR-19                      | Cross-core  | Co-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](./CL-PM-ENCOUNTER-TO-BILLING.md).

***

## Code Examples

### Example: `clinical_note_finalized` payload

```json theme={null}
{
  "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

```sql theme={null}
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](./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

| Mistake                                    | Impact                        | Fix                                                         |
| ------------------------------------------ | ----------------------------- | ----------------------------------------------------------- |
| Missing `organization_id` in event payload | Cross-tenant ambiguity        | Require tenant context in all published events              |
| Publishing before final sign-off           | Invalid charge capture timing | Publish only when status is `signed`/`cosigned`             |
| Trusting PM encounter FK at DB layer       | Core boundary violation       | Keep 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.

***

## Related Docs

* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)
* [CL-PM-ENCOUNTER-TO-BILLING.md](./CL-PM-ENCOUNTER-TO-BILLING.md)
* [CL-PM-TELEHEALTH.md](./CL-PM-TELEHEALTH.md)
* [CL-03-treatment-planning-INTEGRATION.md](./treatment-planning-integration.md) (if present)
* [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md)