Encore OS — Documentation

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:

{
  "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
CL-36 overlap decision resolved (Clarification #4) — EN-66 is canonical; CL-36 delegates
Policy 940 element count finalized (Clarification #5) — Phase 1 = 6 elements; Phase 2 = 12
EN-66 confirmed as single canonical validator; CL-36 delegates to shared validatePolicy940
Enforcement mode aligned (Clarification #6) — EN-66 owns block|warn|disabled; CL-36 Phase 2 may add draft-warn-final-block
AHCCCS-contracted detection resolved (Clarification #7) — pf_organizations.ahcccs_contracted column
CROSS_CORE_INTEGRATIONS.md entry added
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/
Compliance Tracker: docs/compliance/REGULATORY_COMPLIANCE_TRACKER.md
Cross-Core Integrations: docs/architecture/integrations/CROSS_CORE_INTEGRATIONS.md

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

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

Purpose

Integration Points

CL-04 Schema Extension

New Table: `cl_note_940_override_audit`

Permission Keys

Platform Layer Usage

Validation Logic (Policy 940 Elements)

Configuration

CL-36 Overlap Resolution (Resolved)

Regulatory Compliance

Contract Validation Checklist

References

​Purpose

​Integration Points

​CL-04 Schema Extension

​New Table: cl_note_940_override_audit

​Permission Keys

​Platform Layer Usage

​Validation Logic (Policy 940 Elements)

​Configuration

​CL-36 Overlap Resolution (Resolved)

​Regulatory Compliance

​Contract Validation Checklist

​References

Purpose

Integration Points

CL-04 Schema Extension

New Table: `cl_note_940_override_audit`

Permission Keys

Platform Layer Usage

Validation Logic (Policy 940 Elements)

Configuration

CL-36 Overlap Resolution (Resolved)

Regulatory Compliance

Contract Validation Checklist

References