---
name: healthcare-core
description: "Shared reference for the healthcare cluster: the three-layer data-protection contract (classify → access-control → audit), the patient-safety bias (alerts block, never silently pass), the alert-severity matrix, and the CRITICAL-vs-HIGH deploy-gate thresholds. USE WHEN handling PHI, designing clinical access control, wiring a CDSS alert, or configuring a safety gate — the interlocking rules every healthcare spoke shares."
cluster: healthcare
version: 1.0.0
---

# Healthcare Core

Shared model for the `healthcare` cluster. The privacy, EMR, CDSS, and eval spokes all depend on
these interlocking concepts — keep them consistent here so no spoke contradicts another.

## 1. The data-protection contract (this cluster's defining model)

Every healthcare app turns on one three-layer contract. Treat data as protected by default:

```
Classify (what is sensitive) ──> Access-control (who may see it) ──> Audit (who did see it)
```

- **Classify** — *PHI* is anything that identifies a patient **and** relates to health
  (name, DOB, address, national ID, MRN, diagnosis, meds, labs, imaging, claims, admissions).
  *PII* is non-patient sensitive data (staff details, doctor payouts, salaries, vendor payments).
  Tag PHI/PII columns at the schema level. → `healthcare-phi-compliance`
- **Access-control** — Row-Level Security scoped to facility/role; the **anon/publishable** key
  on the client, never `service_role`; minimum-necessary slice only. → `healthcare-phi-compliance`
- **Audit** — every PHI create/read/update/delete/print/export is logged to an **insert-only,
  tamper-proof** trail (no update, no delete). → `healthcare-phi-compliance`

**Rule:** grant the **narrowest** access that works; prefer opaque UUIDs over names/MRNs/IDs;
treat any new data path (vendor, LLM, analytics, export) as a privacy change worth stating.

## 2. The patient-safety bias (defaults fail safe)

Clinical software is patient-safety critical, so the safe default is **block, not pass**:

- A **critical** drug interaction **blocks** prescribing; the clinician must document an override
  reason (stored in the audit trail). → `healthcare-cdss-patterns`, `healthcare-emr-patterns`
- A mg/kg dose with **missing weight** returns invalid — it never silently passes.
- Critical alerts are **non-dismissable modals**, never toasts; abnormal values are always flagged.
- Signed encounters are **locked** — corrections are addenda (linked records), never edits.

## 3. Alert-severity matrix (shared by CDSS and EMR)

| Severity | UI behavior | Clinician action |
|---|---|---|
| Critical | Block action. Non-dismissable modal. Red. | Must document override reason to proceed |
| Major | Inline warning banner. Orange. | Must acknowledge before proceeding |
| Minor | Inline info note. Yellow. | Awareness only |

CDSS produces these; the EMR renders them; the eval harness asserts they never regress.

## 4. The deploy-gate thresholds (shared by eval + CI)

Five eval categories, two tiers. A single CRITICAL failure blocks the deploy.

| Category | Tier | Threshold | On failure |
|---|---|---|---|
| CDSS Accuracy | CRITICAL | 100% | **Block deploy** |
| PHI Exposure | CRITICAL | 100% | **Block deploy** |
| Data Integrity | CRITICAL | 100% | **Block deploy** |
| Clinical Workflow | HIGH | 95%+ | Warn, allow with review |
| Integration (HL7/FHIR) | HIGH | 95%+ | Warn, allow with review |

CRITICAL suites run with `--bail`; never lower a CRITICAL threshold to get green.
→ `healthcare-eval-harness`

## 5. Jurisdiction / standards matrix

| Concern | Standard(s) | Notes |
|---|---|---|
| Privacy regime | HIPAA (US), DISHA (India), GDPR (EU) | `healthcare-phi-compliance` covers all three; US adds BAAs / covered-entity gates |
| Diagnosis coding | ICD-10, SNOMED CT | Diagnosis search in the encounter flow → `healthcare-emr-patterns` |
| Clinical scoring | NEWS2 (RCP spec), qSOFA, APACHE, GCS | Tables must match the published spec exactly → `healthcare-cdss-patterns` |
| Interop | HL7 v2.x, FHIR | Integration-compliance eval gate → `healthcare-eval-harness` |
| Accessibility | WCAG AA (4.5:1), 44×44px targets | No color-only indicators; keyboard-first → `healthcare-emr-patterns` |

## 6. Conventions

- CDSS is a **pure, side-effect-free function library** — input clinical data, output alerts;
  fully testable, no `any` types, errors surface loudly (never silently caught).
- Interaction pairs are **bidirectional** (A↔B) and live in a maintainable data structure,
  not hardcoded inline.
- Test runner is illustrative (examples use Jest); thresholds and categories are
  framework-agnostic (Vitest, pytest, PHPUnit all fine).

## 7. Shared guardrails

- **Protect-by-default**: classify → restrict → audit; minimum-necessary; opaque UUIDs.
- **No PHI** in logs, error strings, URLs, browser storage, screenshots, or LLM prompts.
- **Fail safe**: critical alert blocks; missing weight blocks; signed encounter locks.
- Critical clinical alerts are non-dismissable — never toasts; override reasons are audited.
- Third-party SaaS / LLM / observability vendors are blocked-by-default until the data boundary
  (and a BAA, under HIPAA) is established.
- A single CRITICAL eval failure blocks the deploy; don't weaken the gate.