> ## Documentation Index
> Fetch the complete documentation index at: https://system.muzemus.online/llms.txt
> Use this file to discover all available pages before exploring further.

# Replacement system

> How MUZE determines when employees are due for uniform replacement

MUZE implements a cycle-based replacement system. Each entitlement rule set defines a replacement cycle length (default 24 months). After the cycle elapses, the employee becomes eligible for a new allocation.

## Cycle anchoring

Cycles are anchored to a date, not to the individual employee's start date. The anchor is determined by:

1. **Store rollout anchor**: if the store has a `rolloutAnchorDate`, all employees in that store share cycle boundaries aligned to it
2. **Employment start date**: the fallback when no store anchor exists

This matches Boxer's policy, where replacements are scheduled store by store rather than employee by employee.

## Phase boundaries

`computeEntitlementPhase()` returns:

| Output                 | Meaning                                              |
| ---------------------- | ---------------------------------------------------- |
| `currentPhase`         | `INITIAL` or `REPLACEMENT`                           |
| `currentCycleStart`    | Start date of the current allocation cycle           |
| `firstReplacementDate` | When the employee first becomes replacement-eligible |
| `nextReplacementDate`  | Next upcoming cycle boundary                         |

### INITIAL phase

* Employee has not yet reached the first replacement boundary
* Receives the initial allocation quantities from rule items with phase `INITIAL` or `BOTH`

### REPLACEMENT phase

* Employee has passed the first boundary
* Receives quantities from rule items with phase `REPLACEMENT` or `BOTH`
* New boundaries occur every `replacementCycleMonths` after the anchor

## Calculation example

Given:

* Store rollout anchor: 2024-01-01
* Cycle length: 24 months
* Current date: 2025-06-15

```
Anchor:          2024-01-01
First boundary:  2024-01-01 + 24 months = 2026-01-01
Current date     (2025-06-15) < 2026-01-01
→ Phase: INITIAL
→ Next replacement: 2026-01-01
```

Given the same anchor and cycle, but a current date of 2026-06-15:

```
Anchor:          2024-01-01
First boundary:  2026-01-01
Current date     (2026-06-15) >= 2026-01-01
→ Phase: REPLACEMENT
→ Current cycle start: 2026-01-01
→ Next replacement: 2028-01-01
```

## Reporting integration

The replacement system feeds the Replacement Due report, which identifies:

* Employees approaching their replacement boundary
* Employees past their boundary (overdue)
* Store-level summary of replacement status

The report uses the same `computeEntitlementPhase()` function as the order-time engine, so both always agree on cycle timing. See [Reporting](/notifications-reports/reporting).