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

# ADR-006: Cross-Core Foreign Keys to hr_employees

> Status: Accepted Date: 2026-04-10 Decision Makers: Platform Architecture Team

# ADR-006: Cross-Core Foreign Keys to `hr_employees`

**Status:** Accepted\
**Date:** 2026-04-10\
**Decision Makers:** Platform Architecture Team

***

## Context

Workforce identity (`hr_employees.id`) is referenced outside HR for assignments, scheduling, credentialing overlays, and governance workflows. Constitution §5.2.7 defaults to UUID-only cross-core references unless an ADR authorizes a database FK.

Examples in the codebase directionally include:

* **GR** — audit team assignments, training enrollments tied to staff identity.
* **PM** — e.g. appointment match / provider linkage patterns referencing employees.

These are distinct from **ADR-002** (CL → `pm_encounters`) and **ADR-005** (`pm_patients`).

## Decision

1. **Database FKs to `hr_employees.id` are permitted** when a spec requires referential integrity between HR’s canonical employee row and another core’s assignment or attribution row, with **`ON DELETE RESTRICT`** so HR cannot delete an employee record that is still referenced without an explicit workflow.

2. **New references** should default to UUID + validation unless the spec documents FK need; any new FK must be reviewed for RLS coverage on both sides.

3. **No CASCADE** to HR from other cores — downstream cores must not trigger HR row deletion via FK.

## Rationale

* Employee identity is a stable internal key for permissions, scheduling, and compliance attribution; silent broken references create audit and payroll/compliance risk.
* **RESTRICT** aligns with workforce record retention and separation workflows.

## Migration Plan

Pre-existing foreign keys referencing `hr_employees.id` that use `ON DELETE CASCADE` or `ON DELETE SET NULL` must be remediated to comply with the `ON DELETE RESTRICT` policy:

1. **Exception Window:** 2026-04-10 through 2026-06-30 (Q2 2026)
2. **Responsible Team:** Platform Architecture Team (with support from owning core teams)
3. **Cutoff Date:** 2026-06-30 — all non-RESTRICT FKs must be remediated or documented exceptions approved before this date

### Remediation Steps

1. **Inventory (by 2026-05-01):**
   * Identify all foreign keys referencing `hr_employees.id` (query `pg_constraint` / `information_schema.referential_constraints`)
   * Document current `ON DELETE` behavior per FK

2. **Remediation (by 2026-06-15):**
   * **Preferred:** Alter FK to `ON DELETE RESTRICT` via migration where possible
   * **Exception Path:** If immediate change is impossible (e.g., production data dependencies), create a documented exception ticket with:
     * Justification (why RESTRICT cannot be applied immediately)
     * Mitigation plan (alternative safeguards)
     * Expiration date (must be \<= 2026-12-31)

3. **Audit Evidence (by 2026-06-30):**
   * Migration PRs merged for all altered FKs, or
   * Exception tickets created and approved for any deferred remediations
   * Enforcement script validates compliance against inventory

## Consequences

### Positive

* Clear authorization for documented HR↔GR/PM (etc.) integrity where specs require it.
* Migration plan ensures existing non-compliant FKs are remediated in a controlled timeframe.

### Negative

* Order-dependent migrations when `hr_employees` or dependent tables change.
* Reviewers must distinguish UUID-only references from FK-backed ones.
* Remediation work required for pre-existing non-RESTRICT FKs.

## Related Documents

* [ADR-002](./ADR-002-cl-pm-cross-core-foreign-keys.md) — CL → `pm_encounters`
* [ADR-005](./ADR-005-cross-core-fk-pm-patients.md) — `pm_patients`
* [Constitution §5.2.7](../../../constitution.md)