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.

Version: 1.0.0 Last Updated: 2026-02-17 Constitution Reference: Section 1.2 (Core Independence), Section 1.3 (Integration Patterns) Source: CL-PM-SPEC-REVIEW Findings 1.3, 3.4

​
Overview

Group sessions involve both scheduling (PM-04) and clinical documentation (CL-14). This contract defines which core owns which data to prevent duplication and divergence.

​
Ownership Boundaries

ConcernOwnerSpecTable
Group definition/templatePM-04pm_group_definitionsName, type, capacity, facilitator
Group schedulingPM-04pm_group_scheduleDate, time, location, status
Clinical session documentationCL-14cl_group_sessionsTopic, curriculum, session notes
Attendance trackingCL-14cl_group_attendancePer-patient attendance, participation
Individual clinical responseCL-14cl_group_attendanceindividual_response, goal_progress
Billing/charge capturePM-07pm_chargesCPT, HQ modifier, units
Key Principle: PM-04 is the source of truth for scheduling. CL-14 is the source of truth for clinical documentation (actual service times, actual facilitator, actual location). When schedule_id is set, CL-14 columns may be pre-populated from PM-04 but are authoritative for documentation and billing purposes. Billing data (CPT codes, modifiers) is determined by PM-07 at charge capture time, NOT stored in CL-14.

​
Data Linkage

CL-14 cl_group_sessions links to PM-04 scheduling via Platform Integration Layer: 
-- CL-14 adds this column to cl_group_sessions
schedule_id UUID  -- References pm_group_schedule.id via Platform Integration Layer
                  -- NOT a direct FK (would violate core independence)
                  -- Validated at application layer

​
Field Deduplication

Fields that currently exist in both specs must be consolidated:
FieldPM-04 pm_group_scheduleCL-14 cl_group_sessionsResolution
session_date✅ Authoritative (scheduled)✅ Keep — authoritative for clinical documentationBoth keep — CL stores actual date; when schedule_id is set, pre-populated from PM-04
actual_start_time❌ Not present✅ Keep (renamed from start_time)CL-14 owns actual service times per AHCCCS Policy 940
actual_end_time❌ Not present✅ Keep (renamed from end_time)CL-14 owns actual service times
facilitator_id✅ Authoritative (scheduled)✅ Keep — authoritative for clinical documentationBoth keep — CL stores actual facilitator; when schedule_id is set, pre-populated from PM-04
co_facilitator_id❌ Not present✅ KeepCL-14 owns clinical staffing
location✅ Authoritative (scheduled)✅ Keep — authoritative for clinical documentationBoth keep — CL stores actual location; standalone sessions have no PM-04 link
statusScheduling statusClinical doc statusBoth keep — different lifecycles
topic❌ Not present✅ KeepCL-14 owns clinical content
individual_response❌ Not present✅ KeepCL-14 owns clinical content

​
Billing Integration (Finding 3.4 Resolution)

Remove billing_code from cl_group_attendance. The HQ modifier and CPT code are determined by PM-07 at charge capture time based on:
  1. Participant count from cl_group_attendance (≥2 for HQ modifier)
  2. Session duration from cl_group_sessions.actual_start_time / actual_end_time
  3. Service type from pm_group_definitions.group_type
  4. AHCCCS timed code rules from PM-07 fee schedule

​
Event: cl_group_session_documented

Publisher: CL-14 Subscribers: PM-07 Channel: cl_events 
interface ClGroupSessionDocumented {
  event: 'cl_group_session_documented';
  publisher: 'CL';
  subscriber: ['PM'];
  payload: {
    session_id: uuid;
    schedule_id: uuid;       // Links to pm_group_schedule
    session_date: string;
    actual_start_time: string;
    actual_end_time: string;
    duration_minutes: number;
    facilitator_id: uuid;
    attendees: Array<{
      chart_id: uuid;
      patient_id: uuid;
      attendance_status: string;
      participation_level: string;
    }>;
    participant_count: number;  // Count of 'present' attendees
  };
  metadata: {
    organization_id: uuid;
    user_id: uuid;
    timestamp: string;
    correlation_id: uuid;
  };
}
PM-07 creates one charge per present attendee with:
  • HQ modifier (if participant_count ≥ 2)
  • AHCCCS timed units from duration
  • CPT from group type mapping

​
IOP/PHP Compliance Tracking

IOP (9+ hrs/week, 3+ days) and PHP (20+ hrs/week, daily) compliance requires aggregating group attendance across a week. This is a PM reporting concern (PM-11) that reads from CL-14 attendance data via a Platform Integration Layer query or materialized view. 
-- Platform Integration Layer view for IOP/PHP compliance
CREATE VIEW platform_iop_php_compliance AS
SELECT
  ga.organization_id,
  c.patient_id,
  date_trunc('week', gs.session_date) AS week_start,
  COUNT(DISTINCT gs.session_date) AS days_attended,
  SUM(gs.duration_minutes) / 60.0 AS hours_attended
FROM cl_group_attendance ga
JOIN cl_group_sessions gs ON ga.session_id = gs.id
JOIN cl_patient_charts c ON ga.chart_id = c.id
WHERE ga.attendance_status = 'present'
GROUP BY ga.organization_id, c.patient_id, date_trunc('week', gs.session_date);

​
Cross-Reference

SpecResponsibility
PM-04Group definition, scheduling, capacity
CL-14Clinical documentation, attendance, individual response
PM-07Charge capture with HQ modifier
PM-11IOP/PHP compliance reporting