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

# Comprehensive Assessments — Integration

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

**Feature ID:** CL-02\
**Status:** ✅ Implemented\
**Spec Reference:** [CL-02-comprehensive-assessments.md](../../../specs/cl/specs/CL-02-comprehensive-assessments.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)
* [AI-Optimized Notes](#ai-optimized-notes)
* [Event Contracts](#event-contracts)
* [Security and RLS](#security-and-rls)
* [Related Docs](#related-docs)

***

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

| Item                  | Value                                                                   |
| --------------------- | ----------------------------------------------------------------------- |
| Core tables           | `cl_assessments`, `cl_assessment_sections`, `cl_assessment_instruments` |
| Critical timing rules | 48-hour completion expectation, annual expiration tracking              |
| Signature model       | Clinician + optional co-sign via PF-33                                  |
| Downstream consumers  | CL-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

| Pattern                    | Use                                                                         |
| -------------------------- | --------------------------------------------------------------------------- |
| 18-element assessment form | PF-08 form rendering; CL owns section structure in `cl_assessment_sections` |
| 48-hour documentation      | Configurable window; completion deadline per spec                           |
| Electronic signatures      | PF-33 (clinician and patient/HCDM); capture signedAt, signatureBlob         |
| Expiration dashboard       | Query by `expires_at`; PF-10 `assessment_expiring` event 30 days before due |

***

## Common Mistakes

| Symptom                                    | Cause                             | Remediation                                                                                                       |
| ------------------------------------------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Missing organization\_id on events         | Payload omits tenant/audit fields | Include `organization_id` (uuid), `timestamp` (timestamptz) in all event payloads; use `event_type` (snake\_case) |
| Signed assessment edited in place          | UPDATE without amendment path     | Use supersedes\_id + new row; keep signed rows immutable                                                          |
| Part 2 SUD section visible without consent | No consent check                  | Tag section\_code/instrument metadata; enforce CL-11 consent before display/export                                |
| Expiration notification not firing         | No cron/scheduler                 | Add 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)

| Dependency                     | Pattern           | Purpose                                                                                                                                         |
| ------------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| PF-01 (Organizations & Sites)  | Direct            | Multi-tenant isolation; payload includes organization\_id, optional site\_id                                                                    |
| PF-02 (RBAC)                   | Direct            | Clinical assessment permissions (e.g. cl.assessment.view, cl.assessment.create, cl.assessment.sign, cl.assessment.cosign, cl.assessment.manage) |
| PF-08 (Forms)                  | Platform / Direct | Assessment form rendering; request formId, patientId, locale; response rendered form or JSON schema                                             |
| PF-33 (Digital Signatures)     | Direct            | Signature capture (clinician and patient/HCDM); request signerId, documentId, payloadHash; response signedAt, signatureBlob                     |
| PF-10 (Notifications)          | Event             | Expiration alerts; event assessment\_expiring with targetId (assessment\_id), dueDate; notification to assessment clinician\_id                 |
| CL-01 (Patient Chart)          | Internal          | Assessments render within patient chart; embedding assessmentId, patientId, chartLocation                                                       |
| CL-03 (Treatment Planning)     | Event             | Assessment findings drive treatment plan goals; event findings, severity, linkedGoals                                                           |
| CL-07 (Suicide Risk Screening) | Event             | Risk 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:

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

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

  ```json theme={null}
  {
    "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](./EVENT_CONTRACTS.md) when event schemas are finalized.

***

## Labeled Example

### Example: CL-02 Assessment JSON

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

***

## Related Docs

* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)
* [CL-01-patient-chart-clinical-summary-INTEGRATION.md](./patient-chart-clinical-summary-integration.md)
* [API\_CONTRACTS.md](./API_CONTRACTS.md)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)