docs/control.md

### Control Module — Overrides and Explainability

Directory: `scheduler/control/`

This package houses the manual control plane that allows judges or operators to override algorithmic decisions and to inspect the reasoning behind suggestions.

#### Files overview

- `overrides.py`
  - Purpose: Define override types, manage override drafts per cause list, validate changes, and collect judge preferences and audit trails.
  - Key elements:
    - `OverrideType` (Enum): categories like ripeness override, capacity change, add/remove case.
    - `Override`: a single change request with metadata; `to_dict()`, `to_readable_text()` helpers.
    - `JudgePreferences`: persistent preferences per judge; `to_dict()`.
    - `CauseListDraft`: a draft editable list for a given date/courtroom/judge; exposes `get_acceptance_rate()` and `get_modifications_summary()`.
    - `OverrideValidator`: validates requested changes; surface `get_errors()`; targeted validate methods for each override kind (ripeness, capacity, add/remove case).
    - `OverrideManager`: creates drafts, applies overrides, finalizes drafts, fetches preferences, produces statistics, and exports an audit trail.
  - Interactions: Consumed by `core/algorithm.py` to apply judge preferences and manual modifications before final allocation.

- `explainability.py`
  - Purpose: Human‑readable explanations for why cases were selected or not.
  - Typical content: utilities that convert ripeness/eligibility checks and policy scores into readable reasons for UI display and audit logs.
  - Interactions: Used by dashboard pages and potentially during `SchedulingAlgorithm.schedule_day` explanation generation.