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: PM-64
Status: 📋 Specification (pre-implementation)
Spec: PM-64 AI Coding Assistant v1.3
Companion: PM-64-CONTEXT.md
Compliance gate: PM-64-COMPLIANCE-SIGNOFF.md (CONDITIONAL PASS — see signoff for outstanding items)
Last Updated: 2026-05-04
Overview
PM-64 turns a finalized clinical note into suggested ICD-10 / CPT / HCPCS codes, modifiers, and E&M level for a coder to accept, edit, or reject. All AI calls go through an edge function, follow the canonical RAG / no-PHI-to-LLM pattern (GR-06-EN-01), and respect jurisdiction-specific rules from PF-96. Suggest-not-execute: the coder makes every coding decision; AI never writes a charge directly.
Integration Points
| Dependency | Type | Purpose |
|---|
| CL-04 (Clinical Notes) | Event consumer | Triggers suggestion on cl_note_finalized; note text is read inside the edge function via a service-role Supabase client and PHI-redacted before any LLM call (no frontend @/platform/clinical dependency) |
| PM-07 (Charge Capture) | Downstream consumer | Accepted codes flow to charges; PM-64 never writes pm_charges directly |
| PM-50 (Denial Risk Prediction) | Downstream consumer | Scores denial risk on AI-coded charges; consumes pm.ai_coding_decision_recorded for retraining signal |
| PM-50-EN-01 | Downstream consumer | Per-protected-class fairness drift monitor; reuses pattern for AI coding decisions |
| PF-70 (Medical Terminology) | Platform reference data | Canonical code library for RAG corpus and validation |
| PF-96 (Jurisdiction Profiles) | Platform configuration | Coding rules (timed-code thresholds, modifier requirements, payer policy) per state — never hardcoded |
| GR-06-EN-01 | Pattern reference | Canonical RAG / no-PHI / state-aware AI compliance pattern |
| PHI redaction utility | Platform dependency (does not exist yet) | Hard prerequisite for FR-002 fail-closed redaction; scope as PF spec before Phase 1 task generation |
| LLM vendor (Anthropic Claude via AWS Bedrock) | External | BAA required (SC-005); adapter pattern allows vendor switch |
Event Contracts
| Event | Direction | Payload | Detail |
|---|
cl_note_finalized | consumed | { encounter_id, note_id, organization_id, finalized_at, finalized_by, note_type, sud_flag } | EVENT_CONTRACTS.md § PM-64 |
pm.ai_coding_suggestion_created | published | { suggestion_id, encounter_id, note_id, organization_id, vendor, model_version, confidence_score, suggestion_counts } | EVENT_CONTRACTS.md § PM-64 |
pm.ai_coding_decision_recorded | published | { audit_id, suggestion_id, encounter_id, coder_id, organization_id, decided_at, decision, rejection_reason_code?, edit_summary? } | EVENT_CONTRACTS.md § PM-64 |
Edge Functions
| Function | Purpose | Auth | Notes |
|---|
pm-ai-coding-suggest | Consumes cl_note_finalized → PHI-redact → RAG (PF-70 + PF-96 + CMS/AMPM) → LLM → persist to pm_ai_coding_suggestions → publish pm.ai_coding_suggestion_created | verifyOrgAccess() from _shared/auth.ts; permission pm.ai_coding.suggest | Fail-closed: if redaction throws or confidence < threshold, no LLM call is made and no suggestion is created |
pm-ai-coding-record-decision | Coder accept / edit / reject → write pm_ai_coding_suggestion_audits (immutable) → publish pm.ai_coding_decision_recorded | verifyOrgAccess(); permission pm.ai_coding.review | DELETE forbidden on suggestions and audits at the RLS layer |
pm-ai-coding-audit-monitor | Daily cron — fairness drift detection (PM-50-EN-01 patterns); cost-cap enforcement | createCronHandler() | Alerts on > 2σ drift in per-protected-class accept/reject rates |
Cross-Core Boundary Rules
- No direct CL imports from frontend. Note context is fetched inside the edge function via a service-role Supabase client and PHI-redacted before LLM use; no
@/platform/clinical dependency is required.
- No direct PM-07 writes from PM-64. Coder accept action invokes the standard PM-07 charge mutation.
- Cross-core columns (
encounter_id → pm_encounters.id, note_id → cl_clinical_notes.id) are UUID-only with column comments per ADR-002; no database FK.
- 42 CFR Part 2: When
sud_flag=true on the consumed event, PM-64 enforces the stricter redaction profile and verifies CL-11 consent permits AI processing before any LLM call.
- Jurisdiction: All coding rules read from
pf_resolve_jurisdiction_profile() — no Arizona/AHCCCS hardcoding (PF-96).
Security & PHI Boundary
- PHI redaction is fail-closed. If the redaction utility throws, returns low confidence, or is unavailable, the LLM call is skipped and no suggestion is produced (FR-002).
- Audit trail is immutable. RLS forbids DELETE on both
pm_ai_coding_suggestions and pm_ai_coding_suggestion_audits (NFR-004 7-year retention; HIPAA Security Rule §164.316).
- Suggest-not-execute at every layer — DB, edge function, UI, and event payload (no auto-accept fields).
- Vendor BAA required before any production traffic (SC-005); enforced by feature flag.
- Cost cap per tenant in
pm_module_settings (default $0.05/suggestion); circuit breaker on overrun.
Open Items / Blockers
- ☐ Compliance signoff (0/20 items signed) — Wave 5 hard gate
- ☐ Platform PHI redaction utility (does not exist in
src/platform/) — recommend new PF spec
- ☐ LLM vendor BAA procurement (Anthropic via AWS Bedrock recommended in CONTEXT.md)
References
