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-014: GR-02 is the Canonical Training Substrate; HR-22 and HR-27 are HR-Side Overlays

Status: Proposed Date: 2026-04-19 Participants: Platform Architecture, GR core owner, HR core owner Supersedes: — Related: ADR-007 (multi-tenant RLS), ADR-010 (core / PF dependency boundary), ADR-012 (PF-96 jurisdiction profiles)
Renumber note (2026-04-20): The three follow-on training specs referenced in this ADR were renumbered to close the GR-18..GR-21 numbering gap: GR-22 → GR-18 (Competency Validation & Assessment Engine), GR-23 → GR-19 (Mandatory In-Service Training Compliance Monitor), GR-24 → GR-20 (External LMS Bridge). No semantic change to this ADR.

​
Context

Encore Health OS has three overlapping training-related specs that currently propose incompatible schemas for the same operational surface:
SpecStatusTablesScope
GR-02 Training & CEU Tracking✅ Completegr_training_courses, gr_training_enrollments, gr_training_completions, gr_ceu_credits, gr_training_assignments, gr_training_policy_links, gr_training_requirement_linksOrg-wide course catalog, CEU ledger, policy- and requirement-driven assignments, compliance dashboard
HR-22 Learning Management System📋 Specification (50%)hr_training_courses, hr_training_assignments, hr_training_completions (proposed)Mandatory training, supervision-hour aggregation, transcripts, optional external LMS sync
HR-27 Continuing Education Tracker📋 Specification (50%)hr_ce_requirements, hr_ce_activities, hr_ce_progress (proposed)Per-credential CE requirement library + deficit alerting + cycle progress
The 2026-04-19 cross-core training deep review (specs/cross-cutting/TRAINING-DEEP-REVIEW-2026-04-19.md) documents the full overlap analysis. Headline points:
  • HR-22 and HR-27 each propose duplicate *_training_* tables that would fork the catalog and the CEU ledger.
  • HR-22 has no consumer pattern documented for gr_training_completions; it would simply re-implement the same shape under hr_*.
  • HR-27 hardcodes Arizona AZBBHE rules in a per-org hr_ce_requirements table — the exact AHCCCS-only anti-pattern PF-96 jurisdiction profiles (ADR-012) was built to prevent.
  • Cross-core consumers (HR-02 credentialing, HR-13 skills, HR-19 supervision, RH-06 staff ops, CL-19 peer encounters) currently have no canonical platform layer to import from, which is the reason the duplicate tables keep being proposed: AGENTS.md § Architecture Rules forbids @/cores/gr/... imports from non-GR cores, so HR’s only options today are “duplicate the schema” or “violate the architecture rule.”
This ADR makes the ownership decision explicit so HR-22 and HR-27 can be reframed as consumer overlays and a @/platform/training integration layer (proposed in GR-02-EN-02) can land before either of them is implemented.

​
Options Considered

​
Option A: Parallel HR + GR cores own their own training data

  • How it works: GR-02 stays as written; HR-22 and HR-27 each create their own hr_* tables and HR-side compliance logic. Cross-core sync via events.
  • Pros: Each core owns its UX persona end-to-end; smaller blast radius per spec.
  • Cons: Schema fork (every column on gr_training_courses would need an analogue on hr_training_courses); CEU credits double-counted or out of sync between gr_ceu_credits and hr_ce_progress; downstream consumers (HR-02 renewal, RH-06 staff ops) must pick one source of truth and live with the lag of the other; ongoing migration cost for every new field.
  • Why not chosen: Violates constitution §1 (no parallel implementations of the same domain entity), violates constitution §5 (one canonical entity table per concept), and creates the exact PHI / metadata reconciliation problem ADR-007 (multi-tenant RLS) is supposed to make impossible.

​
Option B: Migrate GR-02 into HR core; deprecate GR-02 schema

  • How it works: Move the GR-02 tables into HR; HR-22 absorbs catalog + assignments + completions; HR-27 absorbs CE library; GR-03 (compliance) consumes HR.
  • Pros: All training in one core matches some external HRIS conventions (Workday Learning, ADP).
  • Cons: Training is not purely an HR concern — GR-02 was placed in GR specifically because policy- and requirement-driven assignments (GR-01 / GR-03) and CARF / Joint Commission survey readiness are governance functions, not workforce functions. Recovery housing (RH-06) staff training and clinical (CL-19) peer-cert prereqs are not HR domain. Migration touches ~7 production tables and breaks every ✅ Complete consumer wired today.
  • Why not chosen: High migration risk for low payoff; misaligns with constitution §7 (governance / compliance ownership of regulatory training); violates constitution §8.4 (deprecation policy — would deprecate a ✅ Complete spec to absorb it into a 📋 spec).

​
Option C: GR-02 canonical, HR-22 / HR-27 reframed as HR-side consumer overlays ✓

  • How it works:
    • GR-02 owns the substrate: course catalog, enrollments, completions, CEU credits ledger, policy/requirement evidence.
    • HR-22 keeps responsibility for: the HR-facing transcript UI, mandatory-training enforcement on hire, external LMS sync (deferred to GR-20), and the workforce persona — all consuming GR-02 via @/platform/training.
    • HR-27 keeps responsibility for: per-credential CE deficit alerting and HR-facing renewal-readiness dashboards — but its requirement / progress tables are renamed under gr_ce_* and moved into GR (per GR-02-EN-04 PF-96 jurisdiction-aware library). HR-27 hooks read via @/platform/training.
    • HR-19 (clinical supervision) continues to own supervision-session capture, but supervision-hour aggregation against GR-02 completions flows through @/platform/training.
  • Pros: Single canonical schema; no migration of existing GR-02 data; HR keeps the persona work; PF-96 jurisdiction model preserved (constitution §10); architecture-validator can mechanically enforce the boundary; cross-core consumers (HR-02, HR-13, HR-19, RH-06, CL-19) get a clean integration target.
  • Cons: HR core team gives up “ownership” of training tables; reframing HR-22 and HR-27 spec text and the 📋 Specification rows requires a coordinated PR.
  • Why chosen: Lowest risk (no schema move), highest architectural integrity, preserves all ✅ Complete work, and the cost is one ADR + two spec headers + one platform layer — landed before any HR-22 / HR-27 implementation has begun.

​
Decision

GR-02 is the canonical, single source of truth for the training course catalog, enrollments, completions, CEU credits, and policy/requirement evidence. HR-22 and HR-27 are reframed as HR-side consumer overlays that read GR-02 data through the @/platform/training integration layer (GR-02-EN-02). The two HR specs retain their persona-specific UX, business logic, and HR-side hooks; they do not own duplicate tables. Specific table rulings:
Originally proposedResolution
hr_training_courses (HR-22)Dropped. Use gr_training_courses via @/platform/training.
hr_training_assignments (HR-22)Dropped. Use gr_training_assignments + gr_training_enrollments.
hr_training_completions (HR-22)Dropped. Use gr_training_completions.
hr_ce_requirements (HR-27)Renamed and moved. Becomes gr_ce_requirements under PF-96 jurisdiction profiles (GR-02-EN-04).
hr_ce_activities (HR-27)Dropped. CE activity records are gr_training_completions rows with non-zero ceu_credits.
hr_ce_progress (HR-27)Dropped. Replaced by computed view gr_ce_progress_v over gr_ceu_credits joined to the active jurisdiction profile (GR-02-EN-04).
hr_ce_requirement_overrides (new)Accepted under GR. Created in GR-02-EN-04 to allow per-org overrides of jurisdiction defaults.

​
Consequences

​
Positive

  • One canonical training schema; one CEU ledger; one assignment surface.
  • HR-22 and HR-27 spec scope shrinks from “build parallel system” to “build HR persona overlay” — both become smaller and faster to ship.
  • @/platform/training becomes the canonical integration target for HR-02 (credential renewal), HR-13 (skill crediting), HR-19 (supervision-hour aggregation), RH-06 (NARR staff training), and CL-19 (peer-cert prereqs).
  • Architecture-validator can mechanically enforce that non-GR cores import only from @/platform/training (per AGENTS.md rule 7).
  • AZ AZBBHE rules ship under PF-96 (per ADR-012 and AGENTS.md rule 9), making other-state expansion configuration rather than schema work.
  • No data migration required; GR-02 already exists and is ✅ Complete.

​
Negative

  • HR core team loses on-paper “ownership” of training tables (mitigation: HR retains the persona work and HR-side hooks).
  • Two specs (HR-22 and HR-27) need a coordinated reframing PR before they begin implementation.
  • A new platform layer (@/platform/training) is required before R-2 (events) and R-13 (CL-19) can be implemented cleanly.

​
Mitigations

  • Phase 0 of TRAINING-CONSOLIDATION-IMPLEMENTATION-PLAN.md adds a ”🔁 Reframed by ADR-014” header block to HR-22 and HR-27 in the same PR that lands this ADR, so no implementer accidentally starts on the dropped tables.
  • GR-02-EN-02 (Phase 1 of the implementation plan) is the very next PR after this ADR, so the platform layer exists before any consumer needs it.
  • Per-table reconciliation row mappings are listed above and reproduced in the deep review (specs/cross-cutting/TRAINING-DEEP-REVIEW-2026-04-19.md § 3 R-1) so reviewers can audit any future PR against this ADR mechanically.
Constitution Reference: This ADR codifies the GR/HR ownership boundary for the training domain per constitution §1.3. It does not introduce a cross-core foreign key (no ADR-002-style exception). HR consumers read via @/platform/training (PIL pattern) and via training_completed events (GR-02-EN-01).