# Working-time rules

Working-time rules are the boundary around every manual assignment, candidate suggestion, solved roster, and cover decision. Fivexer provides the rule engine and explanation format; **you provide the values that apply to your operation**.

## No hidden legal defaults

Rules differ across countries, sectors, collective agreements, contracts, age groups, and dates. Fivexer therefore does not silently install a jurisdiction’s limits. An omitted rule is not checked.

Before using compliance results in production:

1. identify the rules and agreements that apply;
2. configure their actual values;
3. record worker-specific terms and exceptions;
4. review citations and outputs with the responsible legal or HR owner.

The product helps apply your rules consistently. It is not legal advice and cannot determine which rules apply to you.

## Configure the planning clock

```
tsawait fivexer.roster.setSettings({
  timeZone: 'Europe/Tallinn',
  defaultTimeBudgetMs: 10_000,
  rules: {
    dailyRest: { minMinutes: 660 },
    weeklyRest: { minMinutes: 2_100, windowDays: 7 },
    workingTime: {
      maxPerDayMinutes: 600,
      rollingAverages: [{ maxMinutes: 2_880, windowDays: 7 }],
    },
    breaks: [
      { afterMinutes: 360, minMinutes: 30 },
      { afterMinutes: 540, minMinutes: 45 },
    ],
    consecutive: {
      maxWorkingDays: 6,
      forbiddenSuccessions: [{ fromTag: 'night', toTag: 'early' }],
    },
  },
});
```

Shift times are interpreted in `timeZone`, not in the browser’s zone. Overnight and daylight-saving transitions are resolved as real dated intervals before hours and rest are measured.

## What can be expressed

The scheduling engine supports rule families for:

- daily and weekly rest, including rolling windows and reductions;
- daily limits and rolling working-time averages;
- ordinary time, overtime caps, consent, and time off in lieu;
- night-work bands, duration limits, averages, and hazardous-work caps;
- paid and unpaid break requirements;
- consecutive workdays, consecutive nights, and forbidden shift successions;
- Sunday, holiday, and minimum-engagement rules;
- publication and cancellation notice;
- availability, preferences, time off, and external commitments;
- date-valid qualifications and required team composition;
- per-contract hour and day limits;
- fairness across nights, weekends, hours, and other declared dimensions.

Worker-specific rules override workspace rules where the model supports them. This is how individual opt-outs, protected categories, hazardous-work status, or contract-specific limits are represented without weakening the rule for everybody else.

## Severity and explanations

Validation returns structured issues:

| Severity | Meaning |
| --- | --- |
| `error` | A hard rule is broken or required cover is missing |
| `warning` | A configured medium constraint or publishing concern needs a decision |
| `info` | A preference or soft objective was not met |

Issues carry a stable rule code, plain-language message, affected worker or shift, measured `actual`, required bound, unit, and optional citation. Render those values; do not reduce a verdict to a red dot.

## Fairness and cost never overrule legality

The solver evaluates hard feasibility before soft objectives. Cost and fairness can choose between otherwise acceptable plans, but they cannot make a prohibited assignment legal or trade an unfilled mandatory slot for a saving.

The roster engine is also deliberately separate from task-routing learning. It does not consume acceptance history, predicted reliability, no-show risk, or behavioural scores. Candidate ranking uses declared planning facts and realised fairness counts only.

See [validate and publish](/docs/rostering/publish/) for how rules appear in the approval workflow.