HR & People Manager

Editing technical v0.1 — published

Tab to switch the tab. Save writes a vNEW-DRAFT.md alongside the published file.

Markdown source

# HR & People Manager – Technical Specification

## 1. Module Purpose & Scope (Authoritative)

HR & People Manager is Primoro's authoritative workforce operations system, managing the employee lifecycle, HR compliance, and workforce execution layer for dental practices. It provides a single source of truth for staff data, converts HR policy into executable workflows, and surfaces operational staffing visibility — without duplicating the scheduling authority of Rota Manager or the commercial analytics authority of Financial Insights.

It governs:

- Employee lifecycle management (onboarding through offboarding) and HR compliance
- Leave, attendance, and time-tracking as operational source data
- Policy-driven workflow execution (disciplinary, grievance, onboarding, and equivalent UK HR processes)
- Workforce staffing analytics (coverage, absence, workload balance — operational layer only)
- Payroll-readiness outputs (structured data export for external payroll processing)
- Compliance and mandatory training requirement definition and enforcement handoff to the Knowledge, Training & Learning module

It explicitly does not:

- Own scheduling logic or rota templates (Rota Manager owns scheduling and allocation)
- Perform financial modelling, labour cost analysis, or revenue-per-staff calculations (Financial Insights owns the commercial interpretation layer)
- Process payroll directly (payroll execution is out of scope; Primoro MUST NOT process payroll)
- Independently determine which training content is mandatory (Knowledge, Training & Learning owns delivery and evidence; HR owns the compliance definition)

---

## 2. Ownership & Responsibilities

### 2.1 HR & People Manager IS Responsible For

- Maintaining the authoritative record of all staff profiles, employment status, and HR activity
- Defining compliance and mandatory training obligations (per role, recurrence cadence, and consequence of non-completion) and publishing these in a structured, machine-readable form
- Executing HR workflows in a structured, auditable sequence — no ad-hoc HR actions outside governed workflows
- Validating leave requests against rota availability and detecting conflicts before approval
- Simulating downstream rota impact before leave is approved and classifying coverage risk
- Surfacing operational staffing metrics (coverage, absence concentration, overtime distribution, workload imbalance)
- Producing payroll-ready data outputs for each lockable pay period
- Emitting audit events for all state transitions, approvals, risk acknowledgements, and cross-module events
- Routing workflow tasks through Task Manager for human follow-up

### 2.2 HR & People Manager IS NOT Responsible For

- Scheduling logic, rota template creation, or shift allocation — Rota Manager owns these
- Commercial workforce intelligence (labour cost, revenue per staff, chair utilisation profitability) — Financial Insights owns these
- Training content delivery, scheduling, and completion tracking — Knowledge, Training & Learning owns these
- Appointment demand signals — Appointment Manager owns these (future integration surface; see §6.2)
- Identity, authentication, and role-based access enforcement infrastructure — Access Manager owns these

---

## 3. Core Objects (Normative)

### 3.1 StaffRecord (Canonical Artefact)

A StaffRecord is a governed digital artefact representing the authoritative employment record for a single member of staff within a Primoro practice.

Minimum required fields:

- StaffRecordID (UUID)
- PracticeID (FK to practice / tenant)
- StaffRecordState
- Role / StaffGroup
- CreatedBy (user / role)
- CreatedAt (timestamp)
- AuditTrail (immutable)

### 3.2 LeaveRequest (Canonical Artefact)

A LeaveRequest is a governed digital artefact representing a single leave application raised by or on behalf of a staff member, subject to conflict detection and coverage risk classification before approval.

Minimum required fields:

- LeaveRequestID (UUID)
- StaffRecordID (FK)
- LeaveType
- RequestedDateRange
- LeaveRequestState
- RiskClassification
- CreatedBy (user / role)
- CreatedAt (timestamp)
- AuditTrail (immutable)

**Relationship to Staff App Mode StaffRequest:** Staff App Mode enables staff members to submit structured requests — including leave and sickness — as tracked, auditable submissions via the StaffRequest artefact. A StaffRequest of type Leave or Sickness submitted through Staff App Mode MUST be converted into, or directly create, a LeaveRequest artefact in HR & People Manager. The LeaveRequest is the canonical, governed record; the StaffRequest is the submission mechanism. The two artefacts are not duplicates — StaffRequest captures the submission event and channel, whilst LeaveRequest owns the approval state machine, conflict detection, and audit trail. HR & People Manager MUST NOT maintain a parallel approval process for leave that bypasses the LeaveRequest state machine, regardless of submission channel.

### 3.3 LeaveRequest State Machine (Authoritative)

States:

- Draft — request initiated, not yet submitted
- Submitted — pending manager review; conflict detection and coverage simulation run at this point
- Risk Acknowledged — High Risk or Critical Risk impact shown; manager has explicitly acknowledged before proceeding
- Approved
- Rejected
- Cancelled

Rules:

- All state transitions are auditable and time-stamped.
- A LeaveRequest MUST NOT advance beyond Submitted to Approved while a High Risk or Critical Risk classification is outstanding without explicit manager acknowledgement (transition to Risk Acknowledged is mandatory).
- A Critical Risk classification MUST trigger an escalation task via Task Manager before approval can proceed.
- A Rejected or Cancelled request MUST NOT be re-opened; a new LeaveRequest MUST be raised.
- Conflict detection and coverage gap simulation MUST run before the request leaves Submitted state.

### 3.4 HRWorkflowInstance (Canonical Artefact)

An HRWorkflowInstance is a governed digital artefact representing a single execution of a policy-driven HR workflow (e.g. disciplinary, grievance, onboarding, probation review).

Minimum required fields:

- WorkflowInstanceID (UUID)
- StaffRecordID (FK)
- WorkflowType
- WorkflowInstanceState
- PolicyReference
- CreatedBy (user / role)
- CreatedAt (timestamp)
- AuditTrail (immutable)

### 3.5 HRWorkflowInstance State Machine (Authoritative)

States:

- Draft
- Active
- Pending Action (awaiting human step completion)
- Completed
- Cancelled

Rules:

- State transitions are auditable and time-stamped.
- A workflow step MUST NOT auto-complete without explicit human action where the step is designated as requiring human confirmation.
- Cancellation MUST record the reason and the actor.
- Completed instances MUST NOT be mutated; corrections require a new instance or an amendment record.

### 3.6 PayrollPeriod (Canonical Artefact)

A PayrollPeriod is a governed digital artefact representing a single locked pay period for which HR & People Manager has produced payroll-ready output data.

Minimum required fields:

- PayrollPeriodID (UUID)
- PracticeID (FK)
- PeriodStartDate
- PeriodEndDate
- PayrollPeriodState (Open / Locked)
- ExportedAt (nullable, timestamp)
- AuditTrail (immutable)

---

## 4. Core Capability Areas

### 4.1 Leave, Attendance & Time Tracking (Authoritative)

HR & People Manager is the system of record for leave, attendance, and time data. These data are operational source truth; Financial Insights MAY consume them for cost-layer analysis but MUST NOT mutate or duplicate them.

The module MUST:

- Record all leave requests as LeaveRequest artefacts with full audit trail
- Run conflict detection against Rota Manager RotaEntry records before a LeaveRequest advances beyond Submitted state
- Simulate rota coverage gaps and classify risk (Low / Medium / High / Critical) before approval
- Require explicit manager acknowledgement for High Risk classifications
- Require escalation via Task Manager for Critical Risk classifications
- Track attendance (clock-in / clock-out) and surface absence concentration by role, team, and time period
- Track TOIL balances and overtime frequency and distribution

The module MAY:

- Surface recommended alternative leave dates (via AI Aiden, subject to §7 boundaries)

The module MUST NOT:

- Mutate RotaEntry records in Rota Manager; any rota change necessitated by an approved absence MUST be applied within Rota Manager
- Consume raw Schedule Patterns from Rota Manager for conflict detection; it MUST use date-resolved RotaEntry records

### 4.2 Workforce Planning & Staffing Analytics (Authoritative)

HR & People Manager provides operational staffing visibility. It answers whether the practice is over- or understaffed, where workload imbalances exist, and where coverage or absence risks are forming. It does not perform financial modelling.

The module MUST surface:

- Staffing coverage vs required shifts
- Unfilled rota slots (consumed from Rota Manager)
- Overtime frequency and distribution
- Absence concentration by role, team, and time period
- Workload imbalance signals

The module MUST NOT calculate:

- Revenue efficiency
- Chair utilisation profitability
- Labour cost (Financial Insights owns these)

### 4.3 Policy-Driven Workflow Engine (Authoritative)

HR & People Manager converts HR policy into structured, executable workflows. Ad-hoc HR action outside a governed workflow is not permitted on policy-bound matters.

The module MUST:

- Provide UK HR policy templates (including disciplinary and grievance workflows as baseline)
- Allow policies to be attached to workflow types
- Enforce mandatory compliance steps within each workflow; steps designated as requiring human confirmation MUST NOT auto-complete
- Route tasks requiring human action to Task Manager

When routing tasks to Task Manager, HR & People Manager MUST emit a task-creation event containing at minimum: the WorkflowInstanceID, the StaffRecordID, the step type, the required action description, the responsible role or user, and the deadline (where applicable). This payload MUST conform to Task Manager's canonical task schema. Once a task has been created in Task Manager, Task Manager owns the task lifecycle (assignment, reminder, completion confirmation); HR & People Manager retains authority over the workflow step gate and MUST NOT consider a step complete until it has received a task-completion confirmation event from Task Manager for steps designated as requiring human confirmation.

The module MAY:

- Surface guided next-step recommendations for non-HR users (practice managers) to support adoption

### 4.4 Compliance & Mandatory Training Handoff

HR & People Manager is the authoritative owner of compliance and mandatory training requirements.

The module MUST:

- Define which training obligations are compliance-critical (e.g. safeguarding, infection control, GDC-required CPD categories) and publish these requirements in a structured, machine-readable form that Knowledge, Training & Learning can consume
- Specify per role or staff group the applicable mandatory training items, their recurrence cadence, and the consequence of non-completion (e.g. escalation, workflow block)
- Surface compliance status signals received back from Knowledge, Training & Learning within relevant HR workflows (e.g. onboarding completion, probation sign-off, disciplinary context)
- Trigger an escalation task via Task Manager when a compliance deadline is approaching or has been breached, closing the gap between Knowledge's tracking layer and HR's enforcement layer

The module MUST NOT:

- Independently determine which training content is mandatory — that determination is HR's authority, not Knowledge, Training & Learning's
- Own delivery, scheduling, or completion evidence for training — Knowledge, Training & Learning owns these

**Boundary with Knowledge, Training & Learning LMS layer:** Knowledge, Training & Learning owns the full LMS delivery layer, including course scheduling, external CPD integration, and completion evidence storage. HR & People Manager publishes compliance definitions (role, obligation, cadence, consequence) and receives structured compliance status signals in return. HR does not replicate evidence records; it surfaces compliance status within HR workflows only. The integration contract between these two modules MUST be versioned to account for schema changes in the structured requirement publication format (see Open Question 2).

**Boundary with Inventory & Compliance Manager:** Inventory & Compliance Manager manages its own compliance task scheduling, including equipment-related training renewals and practice-level regulatory obligations. Where a compliance task originates from Inventory & Compliance Manager (e.g. equipment-specific training renewals), that module owns the task schedule and tracks completion. HR & People Manager MUST NOT duplicate those records; however, HR MAY surface a summary of practice-level compliance posture within staff HR workflows where it is relevant to employment status or disciplinary context. Ownership boundaries: HR owns staff-bound mandatory training compliance definitions; Inventory & Compliance Manager owns equipment, CQC, and practice-level regulatory compliance tasks.

### 4.5 Payroll Readiness Layer (Authoritative)

Primoro MUST NOT process payroll. HR & People Manager MUST produce payroll-ready outputs for each locked pay period.

Required output data per PayrollPeriod:

- Total hours worked
- Approved overtime
- Leave adjustments
- Sickness flags
- TOIL balances

Output methods:

- CSV export (current)
- API (future)

Each PayrollPeriod MUST be lockable and MUST carry a full audit history.

### 4.6 Commercial Metrics & Operational Efficiency Tracking

HR & People Manager surfaces operational efficiency metrics only. Financial valuation is out of scope.

The module MUST surface:

- Approval speed (time from submission to decision)
- Overdue task count
- Onboarding duration
- Workflow throughput

These operational efficiency metrics (onboarding duration, workflow throughput, approval speed, overdue task count) MUST be emitted as consumable signals for Performance Dashboards. Each emitted metric MUST carry a freshness timestamp indicating when the underlying data was last updated, so that Performance Dashboards can correctly label data currency to operators. Emitted metrics are read-only signals; Performance Dashboards MUST NOT write back to HR & People Manager via this feed.

Time-saved estimates (where surfaced) MUST be clearly labelled as indicative only.

---

## 5. Delivery Surfaces & Access (Authoritative)

### 5.1 Web Portal

HR & People Manager appears in the Primoro staff web portal as the primary management surface. Practice managers and HR-role users access staff records, workflow instances, analytics dashboards, payroll export, and compliance status from this surface.

### 5.2 Tablet App

The tablet app surface supports guided, task-driven interactions for practice managers and senior staff — for example, approving leave requests, acknowledging risk classifications, and completing workflow steps. Full administrative configuration is not expected on tablet.

### 5.3 Patient Mobile App

Not applicable. HR & People Manager has no patient-facing surface.

### 5.4 Engagement Signals

The module emits staffing coverage and workforce risk signals for manager dashboards. Operational efficiency metrics (approval speed, overdue tasks, onboarding duration, workflow throughput) are surfaced as part of the operator experience layer to support high adoption with low training overhead. All emitted metric signals carry freshness timestamps for downstream consumer use.

---

## 6. Integration Contracts

### 6.1 Inbound (this module consumes from)

| From module | What | Contract |
| --- | --- | --- |
| Rota Manager | RotaEntry records (date-resolved shift data) for conflict detection and coverage gap simulation | Sync / read |
| Knowledge, Training & Learning | Compliance status signals (completion, breach, upcoming deadline) per staff member | Event / async |
| Task Manager | Task completion confirmations for workflow-step gating | Event / async |
| Access Manager | Role and permission data for access control enforcement | Sync / read |
| Staff App Mode | StaffRequest submissions of type Leave and Sickness, which are converted into LeaveRequest artefacts | Event / async |

### 6.2 Outbound (this module emits to)

| To module | What | Contract |
| --- | --- | --- |
| Rota Manager | Leave approval decisions (approved LeaveRequest events) so that Rota Manager can apply necessary RotaEntry overrides and mark the relevant slots as unavailable; Rota Manager owns the AbsenceChangeEvent and absence availability removal — HR emits the approval, Rota Manager consumes and re-publishes as an availability change | Event |
| Knowledge, Training & Learning | Structured mandatory training requirements (per role, cadence, consequence) in versioned, machine-readable form | Event / publish |
| Task Manager | Workflow step tasks, escalation tasks, Critical Risk approval tasks — each emitted with WorkflowInstanceID, StaffRecordID, step type, required action, responsible role/user, and deadline, conforming to Task Manager's canonical task schema | Event |
| Financial Insights | Operational source data (attendance, overtime, leave records) for labour cost calculations and overtime cost analysis; PayrollPeriod lock events and leave audit events for provider statement and payroll-readiness workflows; data is read-only for Financial Insights — this module MUST NOT accept mutations from Financial Insights | Read / data feed + Event |
| Performance Dashboards | Operational efficiency metrics (onboarding duration, workflow throughput, approval speed, overdue task count), each carrying a freshness timestamp; read-only signals | Event / data feed |
| Communication Hub | Notification triggers for state changes (approval, rejection, escalation, compliance breach) | Event |
| Audit & Compliance | Immutable audit events for all state transitions and cross-module events | Event |
| Appointment Manager | *(forward compatibility — HR surfaces workforce impact only; demand signals consumed from Appointment Manager in a future integration)* | TBD |

### 6.3 PMS Boundary

HR & People Manager does not integrate directly with the practice management system (PMS) for scheduling or clinical data. Staff profile data (role, employment status) is owned by HR & People Manager. Rota Manager owns scheduling; any PMS-originated scheduling data flows through Rota Manager, not directly into HR & People Manager.

---

## 7. AI Boundaries (Non-Negotiable)

The AI assistant (Aiden) is embedded in HR & People Manager surfaces for operational guidance only.

AI MAY:

- Highlight understaffed or overstaffed periods from operational data
- Suggest reviewing rota allocations where staffing risk signals are present
- Surface repeated absence or workload risk patterns for manager review
- Explain coverage risk classification in plain language
- Highlight key impacts shown at each risk level
- Suggest alternative leave dates for manager consideration

AI MAY NOT:

- Approve or reject leave requests or any workflow step
- Override risk classification controls or skip mandatory acknowledgement steps
- Make any commitment on behalf of the practice
- Optimise labour cost or make financial recommendations (Financial Insights boundary)
- Recommend automatic rota reassignment; final staffing decisions remain with the manager
- Bypass governance, audit, or access checks
- Replace required management or clinical judgement

Module does not embed AI surfaces for clinical decision-making.

---

## 8. Audit & Compliance

The system MUST log:

- All state transitions on LeaveRequest, HRWorkflowInstance, StaffRecord, and PayrollPeriod artefacts, with actor identity and timestamp
- All risk classifications assigned to LeaveRequests, including the coverage impact data shown at the time of classification
- All manager risk acknowledgements (High Risk) and escalation triggers (Critical Risk), with timestamp and actor
- All payroll period lock and export events
- All mandatory training requirement publications emitted to Knowledge, Training & Learning
- All compliance breach escalation tasks triggered
- All AI (Aiden) suggestions surfaced, and which were acted upon or dismissed by a human
- All cross-module events emitted or consumed (leave approval sent to Rota Manager, compliance status received from Knowledge, Training & Learning, tasks emitted to Task Manager)
- All read/write access to staff-bound personal and employment data

Audit logs MUST be immutable. Audit logs MUST be exportable for inspection (e.g. for CQC, Employment Tribunal, or GDPR subject access purposes).

Each PayrollPeriod MUST carry its own locked audit history that remains accessible after the period is closed.

---

## 9. Access Control

Access control is enforced via Access Manager roles. The following capabilities require role-based permission:

- **Create** a StaffRecord or initiate an HRWorkflowInstance: Practice Manager, HR Admin role
- **Read** staff records and workforce analytics: Practice Manager, HR Admin; limited read (own record only) for individual staff members
- **Update** StaffRecord fields: HR Admin; Practice Manager (within defined scope)
- **Approve / promote** LeaveRequest state transitions: Practice Manager, HR Admin
- **Acknowledge** High Risk coverage classifications: Practice Manager (explicit action required; MUST NOT be auto-completed)
- **Lock** a PayrollPeriod: Practice Manager, HR Admin
- **Export** payroll data: Practice Manager, HR Admin
- **Delete** a StaffRecord: Not permitted via UI; deactivation / offboarding workflow is the governed path. Hard deletion, if required for GDPR erasure, requires elevated privilege and generates a mandatory audit event.

MFA MUST be required for payroll period lock and export operations, and for any action that permanently alters a staff record's employment status.

---

## 10. Integration Summary

- **Rota Manager** — inbound RotaEntry consumption for conflict detection; outbound leave approval events so Rota Manager can apply RotaEntry overrides and emit AbsenceChangeEvents
- **Knowledge, Training & Learning** — outbound mandatory training requirement publications (versioned, machine-readable); inbound compliance status signals
- **Task Manager** — outbound workflow step tasks and escalation tasks (conforming to Task Manager's canonical task schema); inbound task completion confirmations for workflow gating
- **Financial Insights** — outbound operational source data (attendance, overtime, leave records) and PayrollPeriod lock events for cost-layer and payroll-readiness consumption; no inbound; Financial Insights MUST NOT mutate HR data
- **Performance Dashboards** — outbound operational efficiency metrics (onboarding duration, workflow throughput, approval speed, overdue task count) with freshness timestamps; read-only
- **Communication Hub** — outbound notification triggers for leave decisions, escalations, and compliance breaches
- **Access Manager** — inbound role and permission data; RBAC enforcement for all read/write/approve operations
- **Audit & Compliance** — outbound immutable event log for all state transitions and cross-module events
- **Staff App Mode** — inbound StaffRequest submissions (Leave, Sickness types) converted into LeaveRequest artefacts; HR owns the approval state machine
- **Inventory & Compliance Manager** — boundary only; equipment/practice-level compliance tasks owned by Inventory & Compliance Manager; HR surfaces staff-bound compliance posture within HR workflows only
- **Appointment Manager** — future inbound demand signals (forward compatibility only; HR surfaces workforce impact only)

---

## 11. Explicit Non-Goals

- **Payroll processing** — Primoro will not process payroll. Payroll-ready exports are the boundary. If payroll execution is added in future, it would require a dedicated Payroll module.
- **Rota scheduling and shift allocation** — Rota Manager owns scheduling logic. HR & People Manager MUST NOT replicate it.
- **Financial labour cost analysis and revenue-per-staff metrics** — Financial Insights owns the commercial interpretation layer.
- **Training content authoring and delivery** — Knowledge, Training & Learning owns training delivery and evidence. HR owns the compliance definition only.
- **Equipment and practice-level regulatory compliance task scheduling** — Inventory & Compliance Manager owns these.
- **Clinical decision support** — out of scope entirely; no clinical AI surfaces are embedded.
- **PMS replacement** — HR & People Manager augments, it does not replace, PMS staff data management.

---

## 12. Versioning & Governance

This specification is owned by: the Post-MVP module owner for HR & People Manager.

Changes to this spec require:

- Review by the Post-MVP module owner
- Impact analysis across declared related modules (Rota Manager, Financial Insights, Knowledge Training & Learning, Task Manager, Communication Hub, Access Manager, Audit & Compliance, Appointment Manager, Staff App Mode, Inventory & Compliance Manager, Performance Dashboards) via the /propose process
- Version bump (patch for clarifications, minor for capability additions, major for ownership boundary changes)

---

## 13. Build Contract (Engineering & QA)

### 13.1 Canonical Data Model

*(no exhaustive schema captured in original — needs definition by engineering)*

The following objects MUST be represented in the data model, each as a first-class persisted entity with the minimum fields declared in §3:

- `staff_records`
- `leave_requests`
- `hr_workflow_instances`
- `payroll_periods`

All tables MUST carry `created_at`, `updated_at`, `created_by`, and an immutable `audit_trail` reference. All foreign keys to staff or practice entities MUST be indexed.

### 13.2 Core Behaviour Rules

1. A LeaveRequest MUST NOT transition from Submitted to Approved while a High Risk or Critical Risk classification is unacknowledged.
2. A Critical Risk LeaveRequest MUST generate an escalation task in Task Manager before approval can proceed.
3. Conflict detection and coverage gap simulation MUST consume RotaEntry records from Rota Manager, not raw Schedule Patterns.
4. HR & People Manager MUST NOT write to or mutate RotaEntry records in Rota Manager; any override MUST be applied within Rota Manager.
5. A PayrollPeriod in Locked state MUST NOT be editable; corrections require a new period or an amendment record with audit trail.
6. All HRWorkflowInstance steps designated as requiring human confirmation MUST NOT auto-complete.
7. Mandatory training requirements published to Knowledge, Training & Learning MUST be in the structured, machine-readable form agreed with that module's integration contract.
8. When a compliance deadline is breached or approaching, an escalation task MUST be automatically created in Task Manager.
9. All AI (Aiden) suggestions MUST be logged, including whether the human acted on or dismissed each suggestion.
10. Payroll export (CSV) MUST include, per staff member: total hours, approved overtime, leave adjustments, sickness flags, and TOIL balances for the locked period.
11. Time-saved estimates surfaced in the operator experience layer MUST be labelled as indicative only.
12. Financial metrics (labour cost, revenue per staff, chair utilisation profitability) MUST NOT be computed or surfaced within this module.
13. Leave approval events emitted to Rota Manager MUST contain sufficient data (StaffRecordID, approved date range, LeaveRequestID) for Rota Manager to identify and override the affected RotaEntry records without requiring a further query back to HR & People Manager.
14. Task-creation events emitted to Task Manager MUST include: WorkflowInstanceID, StaffRecordID, step type, required action description, responsible role or user, and deadline (where applicable). HR & People Manager MUST await a task-completion confirmation from Task Manager before advancing a workflow step that is designated as requiring human confirmation.
15. A StaffRequest of type Leave or Sickness submitted via Staff App Mode MUST result in a LeaveRequest artefact being created in HR & People Manager. The LeaveRequest state machine is authoritative; the StaffRequest submission event MUST be recorded in the LeaveRequest audit trail as the originating event.
16. Operational efficiency metrics emitted for Performance Dashboards consumption MUST carry a `data_as_of` freshness timestamp. These signals are read-only; no write-back from Performance Dashboards is permitted.
17. PayrollPeriod lock events MUST be emitted as structured events consumable by Financial Insights, carrying PayrollPeriodID, PracticeID, PeriodStartDate, PeriodEndDate, and LockedAt timestamp.

### 13.3 Configuration Surfaces

- **Practice-level settings (Admin Control Plane):** UK HR policy templates enabled/disabled; workflow types active for the practice; payroll period cadence; coverage risk threshold overrides (if permitted)
- **Per-user preferences (Access Manager):** notification preferences for leave decisions and escalations
- **Per-workflow overrides (this module):** policy reference attached to a specific HRWorkflowInstance; mandatory step configuration per workflow type

### 13.4 Filtering & Views

The UI MUST support the following standard filters and saved views:

- Leave requests by status, date range, staff member, risk classification
- Workforce analytics by role, team, time period
- HRWorkflowInstances by type, status, staff member
- Payroll periods by status (Open / Locked), date range
- Compliance status by staff member, training type, deadline proximity
- Overdue tasks (surfaced from Task Manager integration)

### 13.5 Module Extension Map

- **Appointment Manager integration (future):** HR surfaces workforce impact only; when Appointment Manager demand signals become available, this module may consume them to enrich staffing coverage analysis without taking on scheduling authority.
- **Payroll API (future):** CSV export is the current boundary; a structured API output for payroll providers is a declared future extension and MUST be designed to be additive without breaking the PayrollPeriod lock contract.
- **Extended workflow types:** The policy-driven workflow engine is designed to accommodate additional UK HR workflow templates (e.g. redundancy, TUPE) without schema changes to the core HRWorkflowInstance object.
- **Performance Dashboards extended metrics (future):** As the operational efficiency metric set expands, additional signals MAY be added to the outbound feed without breaking existing consumers, provided freshness timestamps are maintained on all new fields.

### 13.6 Acceptance Criteria

The build of HR & People Manager is complete when:

- [ ] All canonical objects (StaffRecord, LeaveRequest, HRWorkflowInstance, PayrollPeriod) can be created, read, and updated through the API
- [ ] LeaveRequest state machine enforces all rules in §3.3, including mandatory risk acknowledgement and Critical Risk escalation
- [ ] HRWorkflowInstance state machine enforces human-confirmation gating; no auto-completion of designated manual steps
- [ ] Conflict detection consumes RotaEntry records from Rota Manager and correctly classifies Low / Medium / High / Critical risk
- [ ] HR MUST NOT write to Rota Manager data (negative test: attempted mutation is rejected)
- [ ] Leave approval events are emitted to Rota Manager with the required payload (StaffRecordID, approved date range, LeaveRequestID)
- [ ] StaffRequest submissions of type Leave or Sickness received from Staff App Mode result in a LeaveRequest artefact being created, with the submission event recorded in the audit trail
- [ ] Mandatory training requirements are published to Knowledge, Training & Learning in structured, versioned form; compliance status signals are consumed and surfaced in HR workflows
- [ ] Escalation tasks are automatically created in Task Manager on compliance deadline breach
- [ ] Task-creation events to Task Manager include all required payload fields; workflow steps awaiting human confirmation do not advance until Task Manager task-completion confirmation is received
- [ ] PayrollPeriod lock prevents edits; CSV export includes all required fields; PayrollPeriod lock events are emitted for Financial Insights consumption
- [ ] Operational source data (attendance, overtime, leave) is available to Financial Insights as a read-only feed; Financial Insights cannot mutate HR data (negative test passes)
- [ ] Operational efficiency metrics (onboarding duration, workflow throughput, approval speed, overdue task count) are emitted with `data_as_of` freshness timestamps for Performance Dashboards consumption
- [ ] All integrations in §6 are wired
- [ ] AI (Aiden) boundaries in §7 are enforced (negative tests: Aiden cannot approve, reject, or auto-reassign)
- [ ] Audit log captures every event in §8
- [ ] Access control is enforced per §9, including MFA for payroll lock and export
- [ ] Financial metrics are not computed or surfaced (negative test passes)
- [ ] All non-functional requirements in §14 are met

---

## 14. Non-Functional Requirements

- **Performance:** Leave conflict detection and coverage simulation MUST complete within 3 seconds of submission. Dashboard and analytics views MUST load within 2 seconds for a single-site practice. Payroll export generation MUST complete within 10 seconds for a standard monthly period.
- **Reliability:** The module MUST maintain 99.5% availability. Rota Manager integration failures MUST degrade gracefully — conflict detection should surface a warning to the approver rather than silently omitting it. Payroll lock operations MUST be idempotent.
- **Scalability:** The module MUST support multi-site, multi-tenant operation. Workforce analytics queries MUST perform within SLA for practices with up to 100 staff members per site.
- **Security:** All staff and employment data MUST be encrypted at rest and in transit. Payroll export files MUST be treated as sensitive and access-logged. Secrets and credentials for any integration MUST be managed via the platform's secrets management infrastructure and MUST NOT be stored in application config.
- **Privacy:** The module MUST honour GDPR data subject rights, including subject access requests (SAR) and the right to erasure. Hard deletion of StaffRecord data for GDPR erasure MUST be implemented as a governed, audited operation accessible only to elevated roles. Data retention periods for HR records MUST be configurable at practice level, subject to UK employment law minimums. Audit logs MUST be exportable to support CQC inspection, Employment Tribunal proceedings, and GDPR SAR responses.
- **Accessibility:** All web portal and tablet surfaces MUST meet WCAG 2.1 AA standards. Guided workflow flows for non-HR operators (practice managers) MUST be designed for low training overhead.
- **Observability:** The module MUST export structured logs, metrics, and traces compatible with the platform's observability stack. Key metrics to instrument include: leave request processing time, conflict detection latency, workflow step completion rate, compliance breach escalation rate, payroll export success/failure rate, AI suggestion acceptance rate, and outbound metric feed freshness lag.

---

## 15. Open Questions

1. **Rota Manager RotaEntry API contract:** The spec requires HR to consume RotaEntry records (not raw Schedule Patterns) for conflict detection. The exact API shape and sync mechanism between Rota Manager and HR & People Manager has not been defined. What is the agreed integration contract (polling, webhook, shared read model)?

2. **Knowledge, Training & Learning structured format:** HR must publish mandatory training requirements in a "structured, machine-readable form." The exact schema or format for this publication has not been specified. What format and versioning strategy will be used?

3. **Coverage risk threshold configuration:** The spec defines four risk levels (Low / Medium / High / Critical) but does not define the thresholds that trigger each classification (e.g. number of unfilled roles, percentage coverage drop). Are these thresholds fixed by Primoro, configurable per practice, or configurable per role type?

4. **Payroll period cadence:** The PayrollPeriod object requires a period start and end date, but the supported cadences (weekly, four-weekly, monthly) and whether these are practice-configurable have not been defined.

5. **Appointment Manager forward integration:** The spec notes "future integration with Appointment Manager (demand signals)" but does not define the trigger or timeline. Is this in scope for Post-MVP, or a later release?

6. **GDPR retention minimums:** The spec requires data retention periods to be configurable "subject to UK employment law minimums." The specific minimum retention periods for each HR data category (employment records, disciplinary records, payroll data) have not been enumerated. Which categories require explicit configuration controls and what are the floor values?

7. **Staff App Mode StaffRequest schema alignment:** The conversion of a StaffRequest (Staff App Mode) into a LeaveRequest (HR & People Manager) requires an agreed field mapping. The exact schema mapping and the handling of StaffRequest types not directly supported by the LeaveRequest model (e.g. shift swaps, expenses) have not been defined. What is the agreed conversion contract and which StaffRequest types are in scope for HR ownership?

8. **Task Manager canonical task schema:** The spec requires task-creation events to conform to Task Manager's canonical task schema, but that schema has not been reproduced here. What is the agreed payload contract, and how will schema versioning be managed across modules?

9. **Financial Insights data feed contract:** The outbound operational source data feed to Financial Insights (attendance, overtime, leave records) requires an agreed schema and delivery mechanism. What format, cadence, and versioning strategy will govern this feed?

10. **Inventory & Compliance Manager boundary for shared staff members:** Where a staff member is subject to both HR-owned mandatory training obligations and Inventory & Compliance Manager-owned equipment training renewals, the practice-level compliance posture surfaced in HR workflows may be incomplete without a cross-module compliance status aggregation layer. Is there a requirement for a unified compliance view, and if so, which module owns it?

Live preview