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-02
Status: ✅ Implemented
Spec Reference: CL-02-comprehensive-assessments.md
Last Updated: 2026-02-17
Last Verified: 2026-02-19

​
Table of Contents

​
Overview

CL-02 defines comprehensive assessments per AHCCCS AMPM 320-O: 18-element template, age-specific instruments (CALOCUS, ASAM, developmental, SU), 48-hour documentation window, annual expiration tracking, and electronic signatures. It depends on PF (organizations, RBAC, forms, digital signatures, notifications) and CL-01 (chart embedding). Cross-core: CL-03 (treatment planning), CL-07 (suicide risk screening).

​
Quick Reference

ItemValue
Core tablescl_assessments, cl_assessment_sections, cl_assessment_instruments
Critical timing rules48-hour completion expectation, annual expiration tracking
Signature modelClinician + optional co-sign via PF-33
Downstream consumersCL-03 (planning), CL-07 (risk workflows), PF-10 (notifications)

​
Decision Tree

  • Assessment flow: Initiate per CL-02 spec → 18-element template (AHCCCS AMPM 320-O) → age-specific instruments (CALOCUS, ASAM, developmental, SU) as applicable → complete sections → 48-hour documentation window → electronic signatures (PF-33) → annual expiration tracking; findings may drive CL-03 goals; risk screening links to CL-07.
  • Data source: CL-01 chart embedding; PF-08 form rendering; PF-02 RBAC for view/create/sign/cosign/manage.

​
Pattern Library

PatternUse
18-element assessment formPF-08 form rendering; CL owns section structure in cl_assessment_sections
48-hour documentationConfigurable window; completion deadline per spec
Electronic signaturesPF-33 (clinician and patient/HCDM); capture signedAt, signatureBlob
Expiration dashboardQuery by expires_at; PF-10 assessment_expiring event 30 days before due

​
Common Mistakes

SymptomCauseRemediation
Missing organization_id on eventsPayload omits tenant/audit fieldsInclude organization_id (uuid), timestamp (timestamptz) in all event payloads; use event_type (snake_case)
Signed assessment edited in placeUPDATE without amendment pathUse supersedes_id + new row; keep signed rows immutable
Part 2 SUD section visible without consentNo consent checkTag section_code/instrument metadata; enforce CL-11 consent before display/export
Expiration notification not firingNo cron/schedulerAdd pg_cron or dashboard job for PF-10 assessment_expiring 30 days before expires_at

​
Pre-Flight Checklist

  • Data: cl_assessments, cl_assessment_sections, cl_assessment_instruments created with RLS; deleted_at, site_id per Errata.
  • RBAC: Permission keys seeded (cl.assessment.view, create, sign, cosign, manage); RLS uses existing CL-01 helpers (cl_has_org_access, cl_has_chart_access, pf_is_org_admin). Role checks enforced at application layer via useHasPermission.
  • Digital signatures: PF-33 integration for clinician and patient/HCDM; signed rows immutable.
  • Notifications: PF-10 assessment_expiring event payload includes organization_id, timestamp, event_type; scheduler (pg_cron or dashboard) documented for 30-day-before expiry.
  • Annual expiration tracking: Dashboard/list filter on expires_at; event published per EVENT_CONTRACTS.

​
Integration Points (from Spec)

DependencyPatternPurpose
PF-01 (Organizations & Sites)DirectMulti-tenant isolation; payload includes organization_id, optional site_id
PF-02 (RBAC)DirectClinical assessment permissions (e.g. cl.assessment.view, cl.assessment.create, cl.assessment.sign, cl.assessment.cosign, cl.assessment.manage)
PF-08 (Forms)Platform / DirectAssessment form rendering; request formId, patientId, locale; response rendered form or JSON schema
PF-33 (Digital Signatures)DirectSignature capture (clinician and patient/HCDM); request signerId, documentId, payloadHash; response signedAt, signatureBlob
PF-10 (Notifications)EventExpiration alerts; event assessment_expiring with targetId (assessment_id), dueDate; notification to assessment clinician_id
CL-01 (Patient Chart)InternalAssessments render within patient chart; embedding assessmentId, patientId, chartLocation
CL-03 (Treatment Planning)EventAssessment findings drive treatment plan goals; event findings, severity, linkedGoals
CL-07 (Suicide Risk Screening)EventRisk screening linked to assessment; event score, flags, recommendedActions

​
API / Data Contracts

  • Assessment data: cl_assessments, cl_assessment_sections, cl_assessment_instruments; all scoped by organization_id; RLS via existing CL-01 SECURITY DEFINER helpers: cl_has_chart_access (SELECT), cl_has_org_access (INSERT/UPDATE), pf_is_org_admin (DELETE). Role-based access enforced at application layer via useHasPermission.
  • PF-08: Request { formId, patientId, locale? }; response { html?, schema }. CL owns 18-element structure and section content; PF-08 used for form rendering/validation only.
  • PF-33: Request { signerId, documentId, payloadHash }; response { signedAt, signatureBlob }. Used for clinician and patient/HCDM signature capture.
  • Amendment/version: New assessment row with supersedes_id FK; status amended/superseded; signed rows immutable.

​
Event Contracts

All event payloads must include organization_id (uuid, required) and timestamp (timestamptz); use canonical event_type (snake_case) key.
  • PF-10 (assessment_expiring): Published when assessment is expiring (e.g. 30 days before due). Consumer: notification to assigned clinician. Example: 
    {
  "event_type": "assessment_expiring",
  "organization_id": "org-uuid",
  "timestamp": "2026-02-19T00:00:00Z",
  "assessment_id": "assessment-uuid",
  "due_date": "2026-03-20T00:00:00Z",
  "clinician_id": "user-uuid"
}
  • CL-03 (findings): Assessment findings event for treatment plan linkage. Example: 
    {
  "event_type": "assessment_findings_available",
  "organization_id": "org-uuid",
  "timestamp": "2026-02-19T14:00:00Z",
  "assessment_id": "assessment-uuid",
  "chart_id": "chart-uuid",
  "findings": [{ "code": "F32.1", "severity": "moderate", "linked_goal_ids": [] }]
}
  • CL-07 (risk): Suicide risk screening event when linked to assessment. Example: 
    {
  "event_type": "risk_screening_linked",
  "organization_id": "org-uuid",
  "timestamp": "2026-02-19T15:00:00Z",
  "assessment_id": "assessment-uuid",
  "screening_id": "screening-uuid",
  "risk_level": "high",
  "recommended_actions": ["safety_plan_review", "supervisor_notification"]
}
Document in EVENT_CONTRACTS.md when event schemas are finalized.

​
Labeled Example

​
Example: CL-02 Assessment JSON

{
  "assessment_id": "assessment-uuid",
  "organization_id": "org-uuid",
  "assessment_type": "comprehensive",
  "status": "completed",
  "expires_at": "2027-02-17T00:00:00Z",
  "signed_at": "2026-02-17T14:00:00Z"
}

​
AI-Optimized Notes

  • Always treat signed/amended/superseded assessments as immutable.
  • expires_at drives all expiration dashboards and notifications.
  • Use organization_id in payloads, query keys, and mutation filters.
  • For expiresInDays, 0 is valid and must not be treated as falsy.

​
Security and RLS

  • RLS on cl_assessments, cl_assessment_sections, cl_assessment_instruments; ENABLE + FORCE ROW LEVEL SECURITY. Per-operation policies use existing CL-01 helpers: cl_has_chart_access (SELECT), cl_has_org_access (INSERT/UPDATE with WITH CHECK), pf_is_org_admin (DELETE). Signed assessment immutability enforced via BEFORE UPDATE trigger.
  • UPDATE policies include WITH CHECK; signed assessments not updatable except via amendment path (new row with supersedes_id).
  • Part 2 SUD assessment sections require explicit tagging (section_code or instrument metadata) and consent checks (CL-11).
  • PHI; full HIPAA audit logging; 6-year retention per errata (deleted_at soft-delete).