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

# Integration: CL-04-EN-66 — Note Quality Pre-Submission Validation

> Spec: specs/cl/specs/CL-04-EN-66-note-quality-pre-submission-validation.md Core: CL (Clinical & EHR) Status: ✅ Complete Last Updated: 2026-04-03 Version: 1.0 (…

**Spec:** `specs/cl/specs/CL-04-EN-66-note-quality-pre-submission-validation.md`\
**Core:** CL (Clinical & EHR)\
**Status:** ✅ Complete\
**Last Updated:** 2026-04-03\
**Version:** 1.0 (Clarifications #4–7 resolved)

> **Resolved (Clarification #4):** EN-66 is the **canonical** Policy 940 validator. CL-36 Phase 2 **delegates** to EN-66's `validatePolicy940` service. Single org config source (`org_config_940_validation`). See spec Clarifications #4–7 for full resolution.

***

## Purpose

CL-04-EN-66 adds a pre-submission validation gate to the note finalize/sign workflow in CL-04. It checks Policy 940 required elements before a progress note is finalized and provides a configurable enforcement path (block | warn | override).

***

## Integration Points

| Dependency                                 | Type                        | Direction                             | Status     |
| ------------------------------------------ | --------------------------- | ------------------------------------- | ---------- |
| CL-04 (`cl_progress_notes`)                | Data (schema extension)     | EN-66 → CL-04                         | 📝 Planned |
| PF-02 (User/Credential Management)         | Platform Layer              | EN-66 → PF-02                         | 📝 Planned |
| PF-30 (Permissions/RBAC)                   | Platform Layer              | EN-66 → PF-30                         | 📝 Planned |
| PF-70 (Medical Terminology Code Libraries) | Platform Layer              | EN-66 → PF-70 (ICD-10/DSM code match) | 📝 Planned |
| PF-10 (Notifications)                      | Platform Layer              | EN-66 → PF-10 (break-glass alert)     | 📝 Planned |
| CL-36 (AI-Assisted Clinical Documentation) | Platform Layer / Delegation | CL-36 → EN-66 (canonical validator)   | 📝 Planned |

***

## CL-04 Schema Extension

EN-66 adds the following columns to `cl_progress_notes` (multi-step backfill migration required):

| Column                       | Type                                  | Purpose                                       |
| ---------------------------- | ------------------------------------- | --------------------------------------------- |
| `note_940_validation_passed` | BOOLEAN NOT NULL (after backfill)     | Whether the note passed Policy 940 validation |
| `note_940_validation_result` | JSONB NOT NULL DEFAULT '{}'           | Structured pass/fail per element              |
| `note_940_override_reason`   | TEXT                                  | Override reason when gate bypassed            |
| `note_940_override_by`       | UUID REFERENCES auth.users(id)        | Actor who invoked override                    |
| `note_940_validated_at`      | TIMESTAMPTZ NOT NULL (after backfill) | Timestamp of last validation run              |

***

## New Table: `cl_note_940_override_audit`

INSERT-only immutable audit table for override events. Org-scoped with RLS.

| Column                       | Type                                                    | Purpose                                        |
| ---------------------------- | ------------------------------------------------------- | ---------------------------------------------- |
| `id`                         | UUID PK                                                 | Audit record identity                          |
| `organization_id`            | UUID NOT NULL FK organizations                          | Tenant isolation                               |
| `note_id`                    | UUID NOT NULL FK cl\_progress\_notes ON DELETE RESTRICT | Note being overridden                          |
| `override_by`                | UUID NOT NULL FK auth.users                             | Actor invoking override                        |
| `override_reason`            | TEXT NOT NULL                                           | Mandatory reason for override                  |
| `override_at`                | TIMESTAMPTZ NOT NULL                                    | Event timestamp                                |
| `validation_result_snapshot` | JSONB NOT NULL                                          | State of validation result at time of override |
| `created_at`                 | TIMESTAMPTZ NOT NULL                                    | Row creation timestamp                         |
| `created_by`                 | UUID NOT NULL FK auth.users                             | Actor who created audit record                 |

***

## Permission Keys

| Permission Key                    | Scope                                                        |
| --------------------------------- | ------------------------------------------------------------ |
| `cl.note_940_validation.override` | Override the validation gate (supervisor/compliance officer) |
| `cl.compliance_settings.manage`   | Edit `org_config_940_validation` in Admin > Compliance       |

**Seed locations:** `src/platform/permissions/constants.ts`, migration seeding `pf_module_permissions` and `pf_role_permissions`.

***

## Platform Layer Usage

| Platform Layer                           | Usage                                                                                                  |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `@/platform/credentials` (PF-02)         | Signature with credentials: is the signing clinician credential eligible to bill the rendered service? |
| `@/platform/permissions` (PF-30)         | `useHasPermission('cl.note_940_validation.override')` guard for override UI                            |
| `@/platform/medical-terminology` (PF-70) | ICD-10/DSM code match for diagnosis element validation                                                 |
| `@/platform/notifications` (PF-10)       | Break-glass `DISABLE_940_VALIDATION` toggle notifies compliance team                                   |

***

## Validation Logic (Policy 940 Elements)

EN-66 **Phase 1** implements 6 high-risk elements; **Phase 2** expands to all 12 required categories per AHCCCS AMPM Policy 940 and CL-36 FR-4. The table below is the authoritative checklist for the canonical validator; use a config flag for phased rollout. Terminology aligned with CL-36 (e.g. "service description/treatment linkage" not "presenting problem"; "signature with credentials" not "clinician credential eligibility").

| Element                                                       | Detection Method                                                                                                                    | Acceptance Criteria                                                               | Sample Data / Process                                  |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------ |
| Actual begin/end times                                        | Regex/heuristic — reject templated patterns (e.g. identical start/end, "0900–0950")                                                 | Start and end times present and non-templated                                     | Note body or structured fields; encounter time range   |
| Type of service(s)                                            | Required field/segment present; match to rendered service                                                                           | Service type(s) documented and consistent with encounter/billing                  | Encounter type, service code (PF-70), note segment     |
| Service description/treatment linkage                         | Required field/segment present linking note to treatment                                                                            | Description of service and linkage to treatment plan/goals                        | Note segment, treatment plan reference, goal linkage   |
| DSM diagnosis referenced                                      | Code match (PF-70) OR diagnosis text present in note                                                                                | Encounter diagnosis or structured attestation                                     | PF-70 code match; diagnosis\_referenced attestation    |
| Mental status elements (MSE)                                  | 7 required fields: appearance, behavior, mood, affect, thought process, thought content, cognition — each present or explicitly N/A | All 7 present or explicitly N/A                                                   | Note MSE section or structured MSE fields              |
| Member response to intervention                               | Required segment/field present                                                                                                      | Documented response to interventions delivered                                    | Note segment, intervention response field              |
| Progress toward objectives                                    | Goal progress documented; link to treatment plan objectives                                                                         | Progress toward treatment plan goals present                                      | Goal IDs, progress text, treatment plan reference      |
| Late-entry procedures                                         | Compare note\_created\_at to encounter date; if > 24–48 h, require late-entry attestation                                           | Note within 48 h of encounter OR late-entry attestation present                   | note\_created\_at, encounter date, attestation flag    |
| Multi-staff documentation rules                               | Multiple staff documented per org policy; roles and contributions clear                                                             | When multiple staff involved, each contribution and credential documented         | Staff IDs, roles, signature with credentials per staff |
| Billing-support documentation per service code                | Documentation supports each billed service code                                                                                     | Note content supports each service code (e.g. time, type, linkage)                | Service codes (PF-70), note segments per code          |
| Signature with credentials                                    | PF-02 credential eligible for rendered service; signature and credentials present                                                   | Signing clinician credential eligible to bill; signature and credentials captured | PF-02 credential check; signed\_at, credential display |
| Current service plan / safety plan reference (per AMPM 320-O) | When applicable, reference to current service plan or safety plan                                                                   | Service plan/safety plan referenced where required by policy                      | Plan reference field, link to CL-03 or safety plan     |

**Resolved:** EN-66 is the single canonical Policy 940 validator. CL-36 Phase 2 delegates to EN-66's `validatePolicy940` service (Clarification #4). No duplicate validation logic.

***

## Configuration

Stored in `public.org_compliance_configs` with `config_key = 'org_config_940_validation'` and `config_value` JSON:

```json theme={null}
{
  "enabled": true,
  "enforcement_mode": "block",
  "allow_override": false,
  "override_roles": [],
  "require_override_reason": true
}
```

> **Resolved (Clarification #6):** Phase 1 uses `block | warn | disabled`. EN-66 owns this enum. If CL-36 Phase 2 needs `draft-warn-final-block`, it will be added as a fourth value via Phase 2 migration. No duplicate enums.
>
> **Config key:** Use `org_config_940_validation` as the `config_key` value consistently across spec, tasks, and integration doc (per Clarification #11). Do not use the shorter `940_validation` key.

***

## CL-36 Overlap Resolution (Resolved)

**Decision: Option A** — EN-66 is the canonical standalone Policy 940 validator. CL-36 Phase 2 delegates to EN-66's `validatePolicy940` service (or a shared function called by EN-66). Resolution details:

* **Single config source:** `org_config_940_validation` in `org_compliance_configs` (owned by EN-66); CL-36 reads enforcement mode from the same config.
* **Enforcement mode enum:** EN-66 owns `block | warn | disabled`. CL-36 Phase 2 may request `draft-warn-final-block` as a fourth value; if so, a Phase 2 migration adds it to the shared enum. No duplicate enums.
* **AHCCCS-contracted flag:** Single `pf_organizations.ahcccs_contracted` column used by both EN-66 and CL-36.
* **Phase scope:** EN-66 Phase 1 = 6 elements; Phase 2 = 12 elements; CL-36 consumes the same validator at each phase.

See spec Clarifications #4, #5, #6, #7.

***

## Regulatory Compliance

| Regulation         | Relevance                                                                       |
| ------------------ | ------------------------------------------------------------------------------- |
| AHCCCS Policy 940  | Primary — this gate enforces Policy 940 note completeness                       |
| HIPAA Privacy Rule | Override reasons may contain PHI; INSERT-only audit with proper access controls |
| 42 CFR Part 2      | Inherited from CL-04/CL-11; no new disclosure paths added by EN-66              |

***

## Contract Validation Checklist

* [ ] Platform layer exports for PF-02, PF-30, PF-70, PF-10 documented in `PLATFORM_INTEGRATION_LAYERS.md`
* [x] CL-36 overlap decision resolved (Clarification #4) — EN-66 is canonical; CL-36 delegates
* [x] Policy 940 element count finalized (Clarification #5) — Phase 1 = 6 elements; Phase 2 = 12
* [x] EN-66 confirmed as single canonical validator; CL-36 delegates to shared `validatePolicy940`
* [x] Enforcement mode aligned (Clarification #6) — EN-66 owns `block|warn|disabled`; CL-36 Phase 2 may add `draft-warn-final-block`
* [x] AHCCCS-contracted detection resolved (Clarification #7) — `pf_organizations.ahcccs_contracted` column
* [x] `CROSS_CORE_INTEGRATIONS.md` entry added
* [x] `REGULATORY_COMPLIANCE_TRACKER.md` AHCCCS row updated

***

## References

* **Spec:** `specs/cl/specs/CL-04-EN-66-note-quality-pre-submission-validation.md`
* **CL-36 spec:** `specs/cl/specs/CL-36-ai-assisted-clinical-documentation.md`
* **Parent spec:** `specs/cl/specs/CL-04-progress-notes-session-documentation.md`
* **AHCCCS AMPM:** [https://azahcccs.gov/shared/MedicalPolicyManual/](https://azahcccs.gov/shared/MedicalPolicyManual/)
* **Compliance Tracker:** `docs/compliance/REGULATORY_COMPLIANCE_TRACKER.md`
* **Cross-Core Integrations:** `docs/architecture/integrations/CROSS_CORE_INTEGRATIONS.md`