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

# HR ↔ FW Cross-Core Integration Contract

> Version: 1.0.0 Status: 📝 Planned Created: 2026-03-21 Last Updated: 2026-03-21 Constitution Reference: Section 1.3 (Integration Patterns — Pattern 1: Platform…

**Version:** 1.0.0
**Status:** 📝 Planned
**Created:** 2026-03-21
**Last Updated:** 2026-03-21
**Constitution Reference:** Section 1.3 (Integration Patterns — Pattern 1: Platform Integration Layer, Pattern 2: Event-Based)

***

## Overview

This document defines the integration contract between the **HR (Human Resources)** core and the **FW (Forms & Workflow)** core. HR uses FW for dynamic forms, approval workflows, event-driven automations, and business rules across multiple HR features.

**Related Specifications:**

* HR-02: Credentialing & Compliance
* HR-03: Onboarding & Offboarding
* HR-06: PTO & Leave Management
* HR-10: Performance Management & Reviews
* HR-11: Benefits Administration
* HR-14: Employee Relations
* HR-15: Compensation Management

**FW Features Consumed:**

* FW-01/FW-05: Forms (single-page and multi-page)
* FW-03: Automation Engine (event triggers, actions)
* FW-15: Form Field Lookups (employee/department dropdowns)
* FW-16: Event-Based Workflow Triggers
* FW-34: Approval Workflows (multi-level with delegation)
* FW-45: Decision Tables (routing rules)

**Cross-cutting guide:** See [FW Cross-Core Integration Guide](../../../specs/cross-cutting/FW-CROSS-CORE-INTEGRATION-GUIDE.md) for shared patterns, platform layer imports, and testing requirements.

***

## Integration Pattern

**Primary Pattern:** Pattern 1 — Platform Integration Layer
**Secondary Pattern:** Pattern 2 — Event-Based Integration

HR accesses FW capabilities through:

* `@/platform/forms` — form rendering and submission
* `@/platform/approvals` — approval chain submission and inbox
* `@/platform/events` — publishing HR events for FW automation triggers
* `@/platform/data-lookup` — HR data as form field lookup sources
* `@/platform/calendar` — business day calculations for SLA deadlines

***

## Event Contracts (HR → FW)

Events published by HR that trigger FW automations and workflows.

### HR-03: Employee Lifecycle Events

#### Event: `hr_employee_hired`

**Event:** `hr_employee_hired`
**Channel:** `hr_events`
**Publisher:** HR (HR-03 Onboarding)
**Subscribers:** FW-03 (onboarding workflow trigger), PF-10 (notification)
**Status:** ✅ Implemented (registered in `KnownEventName`)

##### Purpose

Triggers the employee onboarding workflow when a new hire record is created.

##### Trigger Conditions

* **Trigger:** New employee record created with `status = 'active'` or onboarding instance started

##### Payload Schema

```typescript theme={null}
interface HrEmployeeHiredPayload {
  organization_id: string;  // UUID - tenant isolation
  employee_id: string;      // UUID - hr_employees.id
  department_id: string;    // UUID - pf_departments.id
  position_id: string;      // UUID - hr_positions.id
  site_id?: string;         // UUID - pf_sites.id
  manager_id?: string;      // UUID - hr_employees.id (reporting manager)
  start_date: string;       // ISO date - employment start date
  employment_type: string;  // 'full_time' | 'part_time' | 'contractor'
  timestamp: string;        // ISO timestamp
}
```

##### Consumer Actions

| Consumer           | Action                                                             | Status |
| ------------------ | ------------------------------------------------------------------ | ------ |
| FW-03 Automation   | Trigger onboarding workflow (parallel tasks to HR, IT, Facilities) | 📝     |
| PF-10 Notification | Notify HR admin and hiring manager                                 | 📝     |

##### Testing Requirements

* [ ] Event fires when new employee created
* [ ] Payload includes `organization_id`, `employee_id`, `department_id`
* [ ] No PII (name, SSN, DOB) in payload
* [ ] Onboarding workflow triggered within FW

***

#### Event: `hr_employee_terminated`

**Event:** `hr_employee_terminated`
**Channel:** `hr_events`
**Publisher:** HR (HR-03 Offboarding)
**Subscribers:** FW-03 (offboarding workflow trigger), PF-10 (notification)
**Status:** ✅ Implemented (registered in `KnownEventName`)

##### Purpose

Triggers the employee offboarding workflow when an employee is terminated or resigns.

##### Payload Schema

```typescript theme={null}
interface HrEmployeeTerminatedPayload {
  organization_id: string;
  employee_id: string;
  department_id: string;
  termination_type: string;    // 'voluntary' | 'involuntary' | 'retirement'
  last_working_date: string;   // ISO date
  timestamp: string;
}
```

##### Consumer Actions

| Consumer           | Action                                                                          | Status |
| ------------------ | ------------------------------------------------------------------------------- | ------ |
| FW-03 Automation   | Trigger offboarding checklist (IT deprovisioning, asset return, exit interview) | 📝     |
| PF-10 Notification | Notify HR admin, IT, facilities                                                 | 📝     |

***

### HR-02: Credential Management Events

#### Event: `hr_credential_expired`

**Event:** `hr_credential_expired`
**Channel:** `hr_events`
**Publisher:** HR (HR-02 Credentialing)
**Subscribers:** FW-03 (renewal reminder automation)
**Status:** ✅ Implemented (registered in `KnownEventName`)

##### Purpose

Triggers renewal reminder workflow when an employee credential expires or approaches expiry.

##### Payload Schema

```typescript theme={null}
interface HrCredentialExpiredPayload {
  organization_id: string;
  credential_id: string;        // UUID - hr_credentials.id
  employee_id: string;          // UUID - hr_employees.id
  credential_type: string;      // e.g., 'license', 'certification', 'cpr'
  expiration_date: string;      // ISO date
  days_until_expiry?: number;   // Negative if already expired
  timestamp: string;
}
```

##### Consumer Actions

| Consumer           | Action                                                          | Status |
| ------------------ | --------------------------------------------------------------- | ------ |
| FW-03 Automation   | Trigger credential reminder workflow (email at 90/60/30/7 days) | 📝     |
| FW-03 Automation   | Create renewal task for HR compliance team                      | 📝     |
| PF-10 Notification | Alert employee and compliance officer                           | 📝     |

***

#### Event: `hr_credential_verified`

**Event:** `hr_credential_verified`
**Channel:** `hr_events`
**Publisher:** HR (HR-02 Credentialing)
**Subscribers:** FW-03 (compliance status update)
**Status:** ✅ Implemented (registered in `KnownEventName`)

##### Purpose

Updates compliance tracking when a credential is verified or renewed.

##### Payload Schema

```typescript theme={null}
interface HrCredentialVerifiedPayload {
  organization_id: string;
  credential_id: string;
  employee_id: string;
  credential_type: string;
  new_expiration_date: string;
  verified_by: string;           // UUID - user who verified
  timestamp: string;
}
```

***

### HR-06: Leave Management Events

#### Event: `hr_leave_request_submitted`

**Event:** `hr_leave_request_submitted`
**Channel:** `hr_events`
**Publisher:** HR (HR-06 PTO & Leave Management)
**Subscribers:** FW-34 (approval workflow)
**Status:** ✅ Implemented (registered in `KnownEventName`)

##### Purpose

Triggers the leave request approval workflow when an employee submits a leave request.

##### Payload Schema

```typescript theme={null}
interface HrLeaveRequestSubmittedPayload {
  organization_id: string;
  leave_request_id: string;     // UUID - hr_leave_requests.id
  employee_id: string;          // UUID
  leave_type: string;           // 'vacation' | 'sick' | 'personal' | 'fmla' | 'bereavement'
  start_date: string;           // ISO date
  end_date: string;             // ISO date
  total_days: number;
  department_id: string;
  manager_id: string;           // UUID - direct manager
  timestamp: string;
}
```

##### Consumer Actions

| Consumer             | Action                                                   | Status |
| -------------------- | -------------------------------------------------------- | ------ |
| FW-34 Approval       | Route to approval chain based on leave type and duration | 📝     |
| FW-45 Decision Table | Determine approval chain (leave type × days → chain)     | 📝     |

***

### HR-10: Performance Management Events

#### Event: `hr_performance_review_due`

**Event:** `hr_performance_review_due`
**Channel:** `hr_events`
**Publisher:** HR (HR-10 Performance Management)
**Subscribers:** FW-03 (review cycle workflow)
**Status:** 📝 Planned (not yet in `KnownEventName`)

##### Purpose

Triggers the performance review cycle workflow when reviews are due for employees.

##### Payload Schema

```typescript theme={null}
interface HrPerformanceReviewDuePayload {
  organization_id: string;
  review_cycle_id: string;
  employee_id: string;
  reviewer_id: string;          // UUID - manager conducting review
  review_type: string;          // 'annual' | 'quarterly' | 'probationary' | 'project'
  due_date: string;
  timestamp: string;
}
```

***

#### Event: `hr_pip_initiated`

**Event:** `hr_pip_initiated`
**Channel:** `hr_events`
**Publisher:** HR (HR-10 Performance Management)
**Subscribers:** FW-03 (PIP tracking workflow)
**Status:** 📝 Planned (not yet in `KnownEventName`; related `hr_pip_terminated` is registered)

##### Purpose

Triggers PIP tracking workflow with milestone reminders and escalation deadlines.

##### Payload Schema

```typescript theme={null}
interface HrPipInitiatedPayload {
  organization_id: string;
  pip_id: string;
  employee_id: string;
  manager_id: string;
  start_date: string;
  end_date: string;              // PIP deadline
  review_milestones: string[];   // ISO dates for check-in milestones
  timestamp: string;
}
```

***

### HR-11: Benefits Events

#### Event: `hr_benefits_enrollment_approved`

**Event:** `hr_benefits_enrollment_approved`
**Channel:** `hr_events`
**Publisher:** HR (HR-11 Benefits Administration)
**Subscribers:** FW-03 (enrollment processing automation)
**Status:** ✅ Implemented (registered in `KnownEventName`)

##### Purpose

Triggers post-approval processing when a benefits enrollment is approved.

##### Payload Schema

```typescript theme={null}
interface HrBenefitsEnrollmentApprovedPayload {
  organization_id: string;
  enrollment_id: string;
  employee_id: string;
  plan_type: string;             // 'medical' | 'dental' | 'vision' | '401k'
  effective_date: string;
  timestamp: string;
}
```

***

### HR-14: Employee Relations Events

#### Event: `hr_disciplinary_action_termination`

**Event:** `hr_disciplinary_action_termination`
**Channel:** `hr_events`
**Publisher:** HR (HR-14 Employee Relations)
**Subscribers:** FW-03 (termination workflow), HR-03 (offboarding trigger)
**Status:** ✅ Implemented (registered in `KnownEventName`)

##### Purpose

Triggers termination workflow when a disciplinary action results in termination.

##### Payload Schema

```typescript theme={null}
interface HrDisciplinaryTerminationPayload {
  organization_id: string;
  disciplinary_action_id: string;
  employee_id: string;
  action_type: string;           // 'termination'
  effective_date: string;
  timestamp: string;
}
```

***

#### Event: `hr_incident_reported`

**Event:** `hr_incident_reported`
**Channel:** `hr_events`
**Publisher:** HR (HR-14 Employee Relations)
**Subscribers:** FW-03 (investigation workflow)
**Status:** ✅ Implemented (registered in `KnownEventName`)

##### Purpose

Triggers investigation workflow when an employee incident is reported.

##### Payload Schema

```typescript theme={null}
interface HrIncidentReportedPayload {
  organization_id: string;
  incident_id: string;
  reporter_id: string;          // UUID - employee who reported
  incident_type: string;        // 'harassment' | 'safety' | 'policy_violation' | 'other'
  severity: string;             // 'low' | 'medium' | 'high' | 'critical'
  site_id?: string;
  timestamp: string;
}
```

***

## Approval Chain Configurations

### Leave Request Approval

**Chain ID:** `hr-leave-request-approval`
**Entity Type:** `hr_leave_requests`
**Based On:** HR-06

| Step | Approver Type       | Condition              | Timeout | Escalation          |
| ---- | ------------------- | ---------------------- | ------- | ------------------- |
| 1    | `submitter_manager` | Always                 | 48h     | `department_head`   |
| 2    | `role: hr_manager`  | Leave > 5 days OR FMLA | 72h     | `role: hr_director` |

**Decision Table for Routing:**

| Leave Type  | Days | → Chain Steps                                     |
| ----------- | ---- | ------------------------------------------------- |
| Vacation    | ≤ 5  | Manager only                                      |
| Vacation    | > 5  | Manager → HR                                      |
| Sick        | Any  | Manager only (auto-approve if balance sufficient) |
| FMLA        | Any  | Manager → HR → Compliance                         |
| Bereavement | Any  | Manager only (auto-approve)                       |

***

### Credential Renewal Approval

**Chain ID:** `hr-credential-renewal-approval`
**Entity Type:** `hr_credentials`
**Based On:** HR-02

| Step | Approver Type              | Condition                 | Timeout | Escalation          |
| ---- | -------------------------- | ------------------------- | ------- | ------------------- |
| 1    | `role: compliance_officer` | Always                    | 72h     | `role: hr_director` |
| 2    | `role: hr_director`        | Critical credentials only | 48h     | —                   |

***

### Performance Review Approval

**Chain ID:** `hr-performance-review-approval`
**Entity Type:** `hr_performance_reviews`
**Based On:** HR-10

| Step | Approver Type                            | Condition                                          | Timeout         | Escalation          |
| ---- | ---------------------------------------- | -------------------------------------------------- | --------------- | ------------------- |
| 1    | `submitter_manager` (reviewer's manager) | Always                                             | 5 business days | `department_head`   |
| 2    | `department_head`                        | Rating: "exceeds expectations" or "unsatisfactory" | 3 business days | `role: hr_director` |

***

### Compensation Change Approval

**Chain ID:** `hr-compensation-change-approval`
**Entity Type:** `hr_compensation_changes`
**Based On:** HR-15

| Step | Approver Type           | Condition                            | Timeout | Escalation          |
| ---- | ----------------------- | ------------------------------------ | ------- | ------------------- |
| 1    | `submitter_manager`     | Always                               | 48h     | `department_head`   |
| 2    | `role: hr_manager`      | Always                               | 72h     | `role: hr_director` |
| 3    | `role: finance_manager` | Increase > 10% OR salary > threshold | 72h     | `role: cfo`         |

**Decision Table for Routing:**

| Increase % | Salary Level | → Approval Levels            |
| ---------- | ------------ | ---------------------------- |
| ≤ 5%       | Any          | Manager → HR                 |
| 5-10%      | Any          | Manager → HR → Finance       |
| > 10%      | Any          | Manager → HR → Finance → CFO |
| Any        | > \$150K     | Manager → HR → Finance → CFO |

***

## Form Templates

HR uses these FW form templates (specs in `specs/fw/templates/`):

| Template ID               | Type   | Spec Location                                           | Description                         |
| ------------------------- | ------ | ------------------------------------------------------- | ----------------------------------- |
| `hr-leave-request-form`   | Form   | `specs/fw/templates/forms/hr-leave-request-form.md`     | Leave request data capture          |
| `hr-employee-w4-form`     | Form   | `specs/fw/templates/forms/hr-employee-w4-form.md`       | Federal W-4 tax withholding         |
| `hr-employee-i9-form`     | Form   | `specs/fw/templates/forms/hr-employee-i9-form.md`       | Employment eligibility verification |
| `hr-leave-request-bundle` | Bundle | `specs/fw/templates/bundles/hr-leave-request-bundle.md` | Form + approval workflow            |

### Planned Form Templates (Not Yet Specced)

| Template ID                         | Type | Priority | Description                      |
| ----------------------------------- | ---- | -------- | -------------------------------- |
| `hr-performance-review-form`        | Form | P1       | Performance review data capture  |
| `hr-onboarding-checklist-form`      | Form | P1       | New hire checklist (multi-page)  |
| `hr-exit-interview-form`            | Form | P2       | Employee exit interview survey   |
| `hr-pip-tracking-form`              | Form | P2       | PIP progress documentation       |
| `hr-direct-deposit-form`            | Form | P2       | Banking information capture      |
| `hr-onboarding-acknowledgment-form` | Form | P2       | Policy acknowledgment signatures |

***

## Workflow Templates

| Template ID                 | Spec Location                                               | Description                                    |
| --------------------------- | ----------------------------------------------------------- | ---------------------------------------------- |
| `hr-leave-request-approval` | `specs/fw/templates/workflows/hr-leave-request-approval.md` | Leave request through approval chain           |
| `hr-credential-reminder`    | `specs/fw/templates/workflows/hr-credential-reminder.md`    | Credential expiry reminders at 90/60/30/7 days |

### Planned Workflow Templates (From Recommended Templates)

| Template ID                   | Priority | Description                                                                |
| ----------------------------- | -------- | -------------------------------------------------------------------------- |
| `hr-employee-onboarding`      | P0       | Multi-department parallel onboarding (HR, IT, Facilities, Manager)         |
| `hr-employee-offboarding`     | P0       | Offboarding checklist with IT deprovisioning, asset return                 |
| `hr-pip-tracking`             | P1       | PIP milestone reminders and escalation                                     |
| `hr-performance-review-cycle` | P1       | Annual/quarterly review cycle with self-assessment → manager → calibration |
| `hr-benefits-enrollment`      | P2       | Open enrollment workflow with deadline reminders                           |
| `hr-compensation-approval`    | P2       | Multi-level compensation change approval                                   |

***

## Form Field Lookups

HR exposes these data sources for FW form field lookups (FW-15):

| Lookup Source    | Table                 | Value Column | Label Column | Filter              | Used By                   |
| ---------------- | --------------------- | ------------ | ------------ | ------------------- | ------------------------- |
| Employees        | `hr_employees`        | `id`         | `full_name`  | `status = 'active'` | Leave forms, review forms |
| Departments      | `pf_departments`      | `id`         | `name`       | `organization_id`   | All HR forms              |
| Positions        | `hr_positions`        | `id`         | `title`      | `status = 'active'` | Onboarding, compensation  |
| Managers         | `hr_employees`        | `id`         | `full_name`  | `is_manager = true` | Review forms, leave forms |
| Leave Types      | `hr_leave_types`      | `id`         | `name`       | `is_active = true`  | Leave request form        |
| Credential Types | `hr_credential_types` | `id`         | `name`       | —                   | Credential forms          |

***

## Platform Layer Usage

### Hooks HR Components Import

```typescript theme={null}
// Forms
import { useFormTemplate, FormRenderer } from '@/platform/forms';

// Approvals
import { useSubmitApprovalRequest, useMyApprovalRequests } from '@/platform/approvals';

// Events
import { publishEvent } from '@/platform/events';
import type { KnownEventName } from '@/platform/events';

// Data lookups for form fields
import { useLookupOptions } from '@/platform/data-lookup';
```

***

## Testing Requirements

### Unit Tests

* [ ] HR event payloads match documented schemas
* [ ] Leave request decision table returns correct approval chain
* [ ] Compensation decision table returns correct approval levels
* [ ] No PII/PHI in event payloads

### Integration Tests

* [ ] `hr_employee_hired` event triggers onboarding workflow in FW
* [ ] `hr_leave_request_submitted` event routes to correct approval chain
* [ ] `hr_credential_expired` event triggers reminder automation
* [ ] Approval request status updates propagate back to HR entity
* [ ] Form field lookups return correct HR data

### E2E Tests

* [ ] Complete leave request flow: form submission → approval → balance update
* [ ] Complete onboarding flow: hire → workflow → parallel tasks → completion
* [ ] Credential expiry → reminder → renewal → verification flow

### RLS Tests

* [ ] HR events filtered by `organization_id`
* [ ] Approval requests scoped to submitter's organization
* [ ] Form submissions isolated per tenant

***

## Implementation Status

| Integration                    | Status     | Notes                                                                         |
| ------------------------------ | ---------- | ----------------------------------------------------------------------------- |
| HR events in `KnownEventName`  | ✅ Partial  | 12 events registered; `hr_performance_review_due`, `hr_pip_initiated` pending |
| Leave request approval chain   | 📝 Planned | Chain config needed; form + workflow templates ready                          |
| Onboarding workflow            | 📝 Planned | Template recommended in FW-28; not yet implemented                            |
| Credential reminder automation | 📝 Planned | Workflow template ready (`hr-credential-reminder`)                            |
| Performance review workflow    | 📝 Planned | Events and chain not yet registered                                           |
| Compensation approval chain    | 📝 Planned | Decision table needed for amount-based routing                                |
| Form field lookups             | 📝 Planned | HR table lookup configs not yet registered                                    |

***

## Related Documentation

* [FW Cross-Core Integration Guide](../../../specs/cross-cutting/FW-CROSS-CORE-INTEGRATION-GUIDE.md) — Shared patterns
* [Event Contracts](./EVENT_CONTRACTS.md) — HR event registry
* [Cross-Core Integration Matrix](./CROSS_CORE_INTEGRATIONS.md) — Platform-wide matrix
* [Recommended Workflow Templates](../../../specs/fw/recommendations/RECOMMENDED_WORKFLOW_TEMPLATES.md) — HR templates (8)
* [FW-28 HR/FA Template Plan](../../../specs/fw/archive/FW-28-HR-FA-WORKFLOW-TEMPLATES-PLAN.md) — Implementation roadmap