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

# Treatment Planning — Integration

> Feature ID: CL-03 Status: ✅ Implemented Spec Reference: CL-03-treatment-planning.md Last Updated: 2026-02-17 Last Verified: 2026-02-19

**Feature ID:** CL-03\
**Status:** ✅ Implemented\
**Spec Reference:** [CL-03-treatment-planning.md](../../../specs/cl/specs/CL-03-treatment-planning.md)\
**Last Updated:** 2026-02-17\
**Last Verified:** 2026-02-19

***

## Table of Contents

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

***

## Overview

CL-03 defines treatment planning per AHCCCS AMPM 320-O: measurable goals (patient's own words, frequency, duration, target date), service line-specific timeframes, patient/HCDM signature with agreement/disagreement and appeal rights, multi-disciplinary team sign-off, annual and event-triggered review. It depends on PF (organizations, RBAC, digital signatures, notifications) and CL-01 (chart), CL-02 (assessment findings), CL-04 (progress notes → goal progress).

***

## Quick Reference

| Item                | Value                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| Core tables         | `cl_treatment_plans`, `cl_treatment_goals`, `cl_treatment_interventions`, `cl_treatment_plan_signatures` |
| Signature flow      | Patient/HCDM + clinician + optional co-sign with attestation                                             |
| Review triggers     | `treatment_plan_review_scheduled`, `treatment_plan_event_triggered`                                      |
| Key downstream link | CL-04 progress notes update goal progress                                                                |

***

## Decision Tree

* **Goal-setting and review flow:** Create plan (CL-01 chart context) → add measurable goals (patient wording, frequency, duration, target date) → optional linkage to CL-02 assessment findings → patient/HCDM signature (PF-33) with agreement/disagreement and appeal rights → multidisciplinary sign-off → annual review (trigger: `treatment_plan_review_scheduled` 30 days before `review_due_date`) and event-triggered review (trigger: `treatment_plan_event_triggered` on life events); goal progress updated from CL-04 when progress notes are saved.
* **Triggers:** CL-02 (findings → optional goal-to-finding link); CL-04 (progress note → progress\_pct); PF-10 (review-due and event-triggered notifications).

***

## Pattern Library

| Pattern                    | Use                                                                                                                                  |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Goal templates             | Canonical measurable-goal structure (patient wording, frequency, duration, target date); service line-specific timeframes            |
| Signature / consent        | PF-33 for patient/HCDM and clinician; agreement/disagreement; appeal rights attestation (custom\_fields or dedicated columns)        |
| Multidisciplinary sign-off | Team sign-off on plan; store in `cl_treatment_plan_signatures` (Errata E-1)                                                          |
| Review triggers            | Annual: pg\_cron or scheduler → `treatment_plan_review_scheduled`; event: user records life event → `treatment_plan_event_triggered` |

***

## Common Mistakes

| Symptom                                | Cause                                                   | Remediation                                                                                     |
| -------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Goals not measurable                   | Vague wording or missing frequency/duration/target date | Require patient's own words, frequency, duration, target date per spec                          |
| Missing patient signature              | PF-33 not invoked or disagreement path skipped          | Capture signature; on disagreement, complete appeal-rights attestation and store                |
| user\_id omitted on life-event trigger | Event payload missing audit field                       | For user-initiated triggers, include `user_id` (required per EVENT\_CONTRACTS) for auditability |
| Signed plan updated in place           | UPDATE without amendment path                           | Create new version with previous\_plan\_id; signed rows immutable                               |

***

## Pre-Flight Checklist

* [ ] Measurable-goal fields: patient wording, frequency, duration, target date present and validated.
* [ ] Required signatures: patient/HCDM and clinician via PF-33; agreement/disagreement and appeal rights path implemented.
* [ ] RBAC: Treatment plan permissions (create, sign, review) per PF-30; RLS via `cl_has_org_access` / `cl_has_chart_access` (CL-01 helpers).
* [ ] Digital signature and notification hooks: PF-33 integration; PF-10 subscription for `treatment_plan_review_scheduled` and `treatment_plan_event_triggered`.
* [ ] Annual and event-trigger review: Scheduler for review-due (30 days before `review_due_date`); life-event recording publishes `treatment_plan_event_triggered` with `user_id` when user-initiated.

***

## Integration Points (from Spec)

| Dependency                    | Pattern      | Purpose                                                                                                                |
| ----------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| PF-01 (Organizations & Sites) | Direct       | Multi-tenant isolation; all tables scoped by organization\_id                                                          |
| PF-02 (RBAC)                  | Direct       | Clinical treatment plan permissions (create, sign, review); recommend keys per PF-30                                   |
| PF-33 (Digital Signatures)    | Direct       | Patient/HCDM and clinician signature capture; agreement/disagreement; appeal rights attestation                        |
| PF-10 (Notifications)         | Event        | Review-due alerts (30 days before annual); event-triggered update alerts (48h from event recorded)                     |
| CL-01 (Patient Chart)         | Internal     | Plans render within patient chart; plan list and detail in chart context                                               |
| CL-02 (Assessments)           | Event / Data | Assessment findings inform goal development; optional FK goal → finding; event payload: findings, linkedGoals          |
| CL-04 (Progress Notes)        | Data / Event | Progress notes link to goals; goal progress\_pct updated from CL-04 (push when note saved); aggregation rules in CL-04 |

***

## API / Data Contracts

* **Plan data:** `cl_treatment_plans`, `cl_treatment_goals`, `cl_treatment_interventions`, `cl_treatment_plan_signatures` (Errata E-1); all scoped by `organization_id`; RLS via CL-01 SECURITY DEFINER helpers (`cl_has_org_access`, `cl_has_chart_access`, `pf_is_org_admin`).
* **PF-33:** Request `{ signerId, documentId, payloadHash }`; response `{ signedAt, signatureBlob }`. Used for patient/HCDM and clinician signatures; disagreement triggers appeal-rights step (attestation + date; store in custom\_fields or dedicated columns).
* **Signed plans:** Immutable; updates create new version with `previous_plan_id`; amendment/supersede path only for UPDATE on signed rows.
* **Service line:** User-selected at plan creation; constrained by chart/enrollment when available; drives FR-2 timeframe rules.

***

## Event Contracts

Payload schemas are defined in [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md) (Planned Events CL/PM):

* **treatment\_plan\_review\_scheduled:** Published when plan review is due (e.g. 30 days before annual `review_due_date`). Payload: `event_type`, `organization_id`, `timestamp`, `treatment_plan_id`, `chart_id`, `review_due_date` (see EVENT\_CONTRACTS). Consumer: PF-10 → notification to assigned clinician/care coordinator.
* **treatment\_plan\_event\_triggered:** Published when a life event is recorded that triggers plan update (hospitalization, move, LOC change, incarceration). Payload: `event_type`, `organization_id`, `timestamp`, `chart_id`, `event_recorded_at`, optional `life_event_type`, `treatment_plan_id` (see EVENT\_CONTRACTS). Phase 1: manual event entry only; future ADT integration. Success metric: alert within 48h of event recorded.
* **CL-02 → CL-03:** Assessment findings event (from CL-02) may include `linkedGoals?: UUID[]` for goal linkage. CL-03 consumes for optional goal-to-finding FK or narrative link.
* **CL-04 → CL-03:** When a progress note linked to a goal is saved, CL-04 (or platform layer) updates `cl_treatment_goals.progress_pct`; aggregation rules defined in CL-04.

***

## Labeled Example

### Example: `treatment_plan_review_scheduled` payload

```json theme={null}
{
  "event_type": "treatment_plan_review_scheduled",
  "organization_id": "org-uuid",
  "treatment_plan_id": "plan-uuid",
  "chart_id": "chart-uuid",
  "review_due_date": "2026-12-01",
  "timestamp": "2026-11-01T00:00:00Z"
}
```

***

## Security and RLS

* RLS on all four tables with FORCE ROW LEVEL SECURITY; per-operation policies use CL-01 helpers (`cl_has_chart_access` for SELECT, `cl_has_org_access` for INSERT/UPDATE, `pf_is_org_admin` for DELETE); no direct queries to RLS-protected tables (constitution §5.7).
* UPDATE policies include WITH CHECK; signed-plan immutability enforced via `cl_prevent_signed_plan_update()` BEFORE UPDATE trigger (not in RLS clauses).
* Patient signature and appeal-rights data require secure storage; PHI.
* **42 CFR Part 2 (SUD):** Treatment plans that reference or expose SUD-related problems or goals must enforce CL-11 consent before display or export. Apply `cl_has_sud_consent()` (or equivalent) where plan/goal data is surfaced when linked to Part 2–covered diagnoses.

***

## Related Docs

* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)
* [CL-02-comprehensive-assessments-INTEGRATION.md](./comprehensive-assessments-integration.md) (assessment findings → goals)
* [API\_CONTRACTS.md](./API_CONTRACTS.md)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)