Treatment Planning — Integration

​

Table of Contents

• Overview
• Quick Reference
• Decision Tree
• Pattern Library
• Common Mistakes
• Pre-Flight Checklist
• Integration Points (from Spec)
• API / Data Contracts
• Labeled Example
• Event Contracts
• Security and RLS
• Related Docs

​

Overview

​

Quick Reference

​

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

​

Common Mistakes

​

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)

​

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

• 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

{
  "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
• CL-02-comprehensive-assessments-INTEGRATION.md (assessment findings → goals)
• API_CONTRACTS.md
• EVENT_CONTRACTS.md

​

CL-03-EN-02 — person-centered plan block + regulatory gates (CL-75, shipped 2026-07-01)