Shift Scheduling Rules

Source of truth. The scheduling engine must conform to this document. When a rule here conflicts with code, the rule wins — change the code. When tuning the app, edit this file first, then update coverage-requirements.yaml and the engine.

Scope

• Two hospitals: CVH and MRH
• Monthly schedule, generated one month at a time
• Single shared pool of physicians covers both hospitals
• Holidays are treated identically to weekend days

Assignment types

A physician's daily assignment is one of:

1. Ward — covering a specific ward at one hospital
2. ER — one of the emergency room shifts at one hospital
3. MUCC — outpatient clinic at MRH (weekdays only, never on holidays/weekends)
4. Off — no assignment

Ward coverage

Weekdays (Mon–Fri)

• MRH: 7 wards must be covered
• CVH: 8 wards must be covered
• Each ward is covered by one physician for the entire Mon–Fri block (same person all 5 days)

Weekends and holidays

• MRH: 4 wards must be covered
• CVH: 4 wards must be covered
• Each covered ward is staffed by one physician for the entire weekend/holiday block (Sat + Sun, or the full holiday run)

ER coverage

Weekdays (Mon–Fri), per hospital

Three shifts per day, at each hospital:

• Day: 08:00 – 18:00
• Evening: 17:00 – 23:00
• Night: 18:00 – 08:00 (next morning)

Weekends and holidays, per hospital

Two shifts per day, at each hospital:

• Day: 08:00 – 18:00
• Night: 18:00 – 08:00 (next morning)

MUCC (outpatient clinic)

• Location: MRH only
• Days: Mon–Fri, excluding holidays
• Staffing: 3 to 6 physicians per day

Hard constraints

These must never be violated by the generator. The engine applies them hardest → softest, mirroring the on-screen "How preferences and quotas work together" help guide on /doctors:

1. Time-off (calendar-anchored hard block) — rule #6 / #9.

2. Recurring blocks (perpetual day-of-week × shift hard block) — rule #10.

3. Quotas with min=max=0 (faceted category hard block) — rule #13.

4. Quotas with a max (faceted monthly cap) — rule #13.

5. Quotas with a min (soft floor — engine biases candidate selection, emits RULE_QUOTA_UNMET post-generation when the floor isn't met) — rule #13.

6. One assignment type per day. A physician cannot be assigned Ward + ER, Ward + MUCC, or ER + MUCC on the same day.

7. One hospital per day. A physician cannot be assigned to both CVH and MRH on the same day.

8. Post-night rest. A physician who works an ER night shift (18:00–08:00) receives no assignment the following calendar day.

9. No consecutive night ER. A physician cannot be assigned ER night shifts on two consecutive calendar days.

10. Holidays = weekends. On any holiday, use weekend coverage rules (ward counts, ER shift counts, no MUCC).

11. Approved time-off is a hard block. Any date range approved by an admin (vacation, leave, or one-off absence) must produce no assignment for that physician on those dates. The engine treats approved time-off identically to a pre-filled "off" assignment — it is not overrideable by the scheduler without first revoking the approval.

12. Recurring unavailability is a hard block. A recurring pattern approved by an admin (e.g. "every Wednesday afternoon for clinic") blocks the physician from being assigned to a conflicting shift on matching dates. Pattern granularity is day-of-week + optional half-day (AM/PM).

13. Shift-type eligibility. Each physician carries a canWork map gating which shift-type buckets they can be assigned: ward, er_day, er_evening, er_night, mucc. Missing keys default to true (eligible). Either the physician (via My Profile) or an admin can flip a key to false; the engine then refuses to place that physician in matching shifts.

14. Time-off blocks. Each physician carries a per-date timeOff map from their preferences. Keys are ISO dates (YYYY-MM-DD); values are arrays of shift-eligibility keys to block on that date, or the special all sentinel meaning the whole day is off. The engine refuses any matching shift on those dates. Distinct from rule #6 (approved time-off requests via admin workflow) — timeOff blocks are set directly through the Doctors preferences editor.

15. Day-of-week × shift blocks. Each physician carries a dayShiftBlocks list of perpetual block entries in the form "{dow}-{shiftKey}" (dow ∈ mon..sun, shiftKey ∈ ward, er_day, er_evening, er_night, mucc). The engine refuses a matching assignment whenever the candidate date's weekday lines up with a blocked entry — e.g. tue-er_night blocks every Tuesday's ER night for that doctor regardless of date.

16. Hospital scope. Each physician carries a hospitalsAllowed list. If non-empty, the engine refuses any assignment at a hospital not in the list. Empty / undefined = unrestricted (every hospital).

17. Max consecutive days. Each physician carries a limits.maxConsecutive cap. The engine refuses an assignment that would push the doctor's working-day streak over the cap.

18. Faceted assignment quotas. Each physician carries a quotas list. Each rule scopes a (assignmentType, shiftId, hospital, dayOfWeek, isWeekend) facet to an optional min and/or max count per calendar month. max is enforced at canAssign time (RULE_QUOTA_MAX); min drives candidate priority and emits RULE_QUOTA_UNMET post-generation if the floor isn't met. Filter fields combine with AND across fields and OR within dayOfWeek. Empty/missing fields match anything. Replaces the legacy min/maxNightsPerMonth fields — those are auto-migrated into an ER-night quota at load time so existing rosters keep their settings.

19. Must-work pre-placements. Each physician carries an optional mustWork map keyed by ISO date. Each entry pins the doctor to a specific assignment (ER shift, MUCC seat, or named ward) before regular coverage runs, so the slot isn't double-filled. Conflicts (same doctor pinned twice on a date, two doctors claiming the same slot, missing fields, unknown shift for the day-kind) emit RULE_MUST_WORK_CONFLICT and the entry is dropped.

Soft preferences

These are scored when the engine supports multi-objective optimisation. Until then they are logged but not enforced.

• Balance total shifts across physicians over the month.
• Balance weekend/holiday load across physicians over the month.
• Balance night-shift load — spread ER nights evenly; no physician should hold a disproportionate share.
• Shift-type preference — physicians may express a preference (day over night, no weekends, etc.). Honour where possible without violating hard constraints or fairness.
• Hospital preference — physicians may prefer CVH or MRH. Treated as a tiebreaker, never a hard block.

Fairness

The engine must track, per physician over a rolling 3-month window:

• Total assignments
• Weekend/holiday assignments
• Night-shift (ER night) assignments

These counts are surfaced in the Fairness Dashboard (scheduler + admin only) and used as tiebreakers during generation. A physician more than 20% above the group average in any category is deprioritised for that category in the next generation.

Conflict pre-check

When a scheduler manually overrides an assignment, the system must instantly evaluate all hard constraints against the proposed change and surface any violations before saving. The override is still allowed (scheduler discretion) but violations must be acknowledged.

Peer swap protocol

1. Doctor A proposes swapping shift X (their assignment) for shift Y (Doctor B's assignment).
2. Doctor B receives a notification and approves or rejects.
3. On approval, the swap enters pending-scheduler-review state.
4. Scheduler reviews the proposed swap against hard constraints and either rubber-stamps or rejects.
5. On scheduler approval, both assignments are updated with source: 'manual' and an audit log entry is written covering both sides of the swap.
6. Rejected at any step → no change, notification sent to initiating doctor.

Change log

• 2026-04-21: Initial version, captured from stakeholder description.
• 2026-04-23: Added hard constraints 6–7 (time-off, recurring unavailability). Added soft preferences detail, fairness rules, conflict pre-check, and peer swap protocol.

Roles and Permissions

Three roles. A user has exactly one role. All roles require authentication via Cognito.

admin

• Invite new users (any role) by email
• Deactivate users
• Edit doctor roster via the UI (add, deactivate, update)
• Edit holidays via the UI
• Approve or reject time-off requests and recurring unavailability patterns
• All scheduler permissions

scheduler

• Generate a monthly schedule
• Manually edit a generated schedule (override assignments, with conflict pre-check)
• Publish a schedule (makes it visible to doctors)
• Review and rubber-stamp peer swap requests
• View all doctors' calendars
• View the Fairness Dashboard
• All doctor permissions

doctor

• View the published schedule
• View their own assignments highlighted
• Download their .ics calendar feed or subscribe via signed URL
• Update their own profile (display name, contact email)
• Submit time-off requests (date range + reason)
• Submit recurring unavailability patterns (day-of-week + AM/PM)
• Set shift preferences (day/night preference, hospital preference, no-weekends flag)
• Propose peer swap requests

Invitation flow

1. Admin enters email + role on the Invite page.
2. System creates a Cognito user in FORCE_CHANGE_PASSWORD state and emails a signup link with a one-time token.
3. Invitee clicks link, sets password, lands on the app with their assigned role.
4. Tokens expire after 7 days. Admin can resend.

Audit

Every schedule publish, manual override, user invite, time-off approval, swap approval, and doctor/holiday update is logged with actor, timestamp, and before/after state.

Enhancements (later slices)

Time-off requests

• Doctor submits a date range + reason (vacation, leave, personal).
• Admin reviews and approves or rejects. Approved ranges become hard constraints for the next generation covering those dates.
• Scheduler can see all approved time-off when generating; the engine will not assign those physicians on blocked dates.

Recurring unavailability

• Doctor submits a day-of-week pattern (e.g. "every Wednesday PM — clinic obligation").
• Admin approves. Approved patterns are evaluated each generation and block the physician from conflicting shifts on matching dates.
• Patterns have an optional end date; they expire automatically if set.

Shift preferences

• Doctor sets soft preferences: day-shift preferred, no weekends if possible, hospital preference.
• Preferences feed into the engine's scoring phase (once multi-objective optimisation is implemented).
• Preferences are never hard blocks — coverage always wins.

Fairness Dashboard

• Scheduler and admin can view a rolling 3-month summary per physician: total shifts, weekend/holiday shifts, night shifts.
• Imbalances (>20% above group average) are highlighted.
• Accessible from the scheduler workspace; not visible to doctors.

Peer swap requests

• Doctor A proposes swapping one of their assignments for one of Doctor B's.
• Doctor B approves or rejects in the app.
• On B's approval, scheduler reviews against hard constraints and rubber-stamps or rejects.
• Approved swaps update both assignment records (source: manual) and write an audit log entry.
• See full protocol in scheduling-rules.md.

iCal feed per doctor

• Each doctor gets a personal signed URL (/api/calendar/[doctorId]?token=...) returning a .ics file with their published assignments.
• The URL auto-updates as new schedules are published.
• Token can be rotated by the doctor; old tokens immediately stop working.
• The CalendarFeedToken model is already deployed.