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.

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