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

# AI Coding Assistant — Integration

> Feature ID: PM-64 Status: \U0001F4CB Specification (pre-implementation) AI Coding Assistant v1.3 Companion: PM-64-CONTEXT.md Compliance gate: PM-64-COMPLIA…

**Feature ID:** PM-64
**Status:** 📋 Specification (pre-implementation)
**Spec:** [PM-64 AI Coding Assistant](../../../specs/pm/specs/PM-64-ai-coding-assistant.md) v1.3
**Companion:** [PM-64-CONTEXT.md](../../../specs/pm/specs/PM-64-CONTEXT.md)
**Compliance gate:** [PM-64-COMPLIANCE-SIGNOFF.md](../../../specs/pm/reviews/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](./EVENT_CONTRACTS.md#cl-04-note-finalized-consumed-by-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](./EVENT_CONTRACTS.md#pm-64-ai-coding-suggestion-created)     |
| `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](./EVENT_CONTRACTS.md#pm-64-ai-coding-decision-recorded)      |

**PHI rule:** Zero free-text narrative in any payload. IDs and structured metadata only. Subscribers needing note context must read via a service-role Supabase client inside their edge function and PHI-redact before any LLM call.

***

## 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](../decisions/ADR-002-cl-pm-cross-core-foreign-keys.md); 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

1. **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).
2. **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).
3. **Suggest-not-execute** at every layer — DB, edge function, UI, and event payload (no auto-accept fields).
4. **Vendor BAA required** before any production traffic (SC-005); enforced by feature flag.
5. **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

* [PM-64 spec](../../../specs/pm/specs/PM-64-ai-coding-assistant.md)
* [PM-64 CONTEXT](../../../specs/pm/specs/PM-64-CONTEXT.md)
* [PM-64 PLAN](../../../specs/pm/plans/PM-64-ai-coding-assistant-PLAN.md)
* [PM-64 TASKS](../../../specs/pm/tasks/PM-64-TASKS.md)
* [PM-64 compliance signoff](../../../specs/pm/reviews/PM-64-COMPLIANCE-SIGNOFF.md)
* [PM AGENTS § AI Integration Patterns](../../../src/cores/pm/AGENTS.md)
* [GR-06-EN-01](../../../specs/gr/specs/GR-06-EN-01-ai-state-compliance-checking.md) — canonical RAG / no-PHI pattern
* [ADR-002 CL/PM cross-core FKs](../decisions/ADR-002-cl-pm-cross-core-foreign-keys.md)
* [CROSS\_CORE\_INTEGRATIONS.md § PM Wave](./CROSS_CORE_INTEGRATIONS.md#pm--practice-management-wave-pm)
* [EVENT\_CONTRACTS.md § PM-64](./EVENT_CONTRACTS.md#planned-events-pm-64-ai-coding-assistant)