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.

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

DependencyTypeDirectionStatus
CL-04 (cl_progress_notes)Data (schema extension)EN-66 → CL-04📝 Planned
PF-02 (User/Credential Management)Platform LayerEN-66 → PF-02📝 Planned
PF-30 (Permissions/RBAC)Platform LayerEN-66 → PF-30📝 Planned
PF-70 (Medical Terminology Code Libraries)Platform LayerEN-66 → PF-70 (ICD-10/DSM code match)📝 Planned
PF-10 (Notifications)Platform LayerEN-66 → PF-10 (break-glass alert)📝 Planned
CL-36 (AI-Assisted Clinical Documentation)Platform Layer / DelegationCL-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):
ColumnTypePurpose
note_940_validation_passedBOOLEAN NOT NULL (after backfill)Whether the note passed Policy 940 validation
note_940_validation_resultJSONB NOT NULL DEFAULT ''Structured pass/fail per element
note_940_override_reasonTEXTOverride reason when gate bypassed
note_940_override_byUUID REFERENCES auth.users(id)Actor who invoked override
note_940_validated_atTIMESTAMPTZ 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.
ColumnTypePurpose
idUUID PKAudit record identity
organization_idUUID NOT NULL FK organizationsTenant isolation
note_idUUID NOT NULL FK cl_progress_notes ON DELETE RESTRICTNote being overridden
override_byUUID NOT NULL FK auth.usersActor invoking override
override_reasonTEXT NOT NULLMandatory reason for override
override_atTIMESTAMPTZ NOT NULLEvent timestamp
validation_result_snapshotJSONB NOT NULLState of validation result at time of override
created_atTIMESTAMPTZ NOT NULLRow creation timestamp
created_byUUID NOT NULL FK auth.usersActor who created audit record

​
Permission Keys

Permission KeyScope
cl.note_940_validation.overrideOverride the validation gate (supervisor/compliance officer)
cl.compliance_settings.manageEdit 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 LayerUsage
@/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”).
ElementDetection MethodAcceptance CriteriaSample Data / Process
Actual begin/end timesRegex/heuristic — reject templated patterns (e.g. identical start/end, “0900–0950”)Start and end times present and non-templatedNote body or structured fields; encounter time range
Type of service(s)Required field/segment present; match to rendered serviceService type(s) documented and consistent with encounter/billingEncounter type, service code (PF-70), note segment
Service description/treatment linkageRequired field/segment present linking note to treatmentDescription of service and linkage to treatment plan/goalsNote segment, treatment plan reference, goal linkage
DSM diagnosis referencedCode match (PF-70) OR diagnosis text present in noteEncounter diagnosis or structured attestationPF-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/AAll 7 present or explicitly N/ANote MSE section or structured MSE fields
Member response to interventionRequired segment/field presentDocumented response to interventions deliveredNote segment, intervention response field
Progress toward objectivesGoal progress documented; link to treatment plan objectivesProgress toward treatment plan goals presentGoal IDs, progress text, treatment plan reference
Late-entry proceduresCompare note_created_at to encounter date; if > 24–48 h, require late-entry attestationNote within 48 h of encounter OR late-entry attestation presentnote_created_at, encounter date, attestation flag
Multi-staff documentation rulesMultiple staff documented per org policy; roles and contributions clearWhen multiple staff involved, each contribution and credential documentedStaff IDs, roles, signature with credentials per staff
Billing-support documentation per service codeDocumentation supports each billed service codeNote content supports each service code (e.g. time, type, linkage)Service codes (PF-70), note segments per code
Signature with credentialsPF-02 credential eligible for rendered service; signature and credentials presentSigning clinician credential eligible to bill; signature and credentials capturedPF-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 planService plan/safety plan referenced where required by policyPlan 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

RegulationRelevance
AHCCCS Policy 940Primary — this gate enforces Policy 940 note completeness
HIPAA Privacy RuleOverride reasons may contain PHI; INSERT-only audit with proper access controls
42 CFR Part 2Inherited 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