# ROADMAP.md — Heating MPC

> **Planning document, 2026-10-26.** Architecture and scope are discussed in ChatGPT; implementation happens in Codex. Priorities may change based on data collected in Home Assistant. Check code/tests before marking an item complete.

## Goal

Deliver a **fully local Home Assistant custom integration** for HAOS on Raspberry Pi 5. The integration learns how each room warms and cools, uses selectable indoor/outdoor sensors, forecasts temperatures and — **only after validation and explicit opt-in** — can safely control one existing ON/OFF boiler relay through an exclusive-control architecture.

Success means predictable comfort, understandable decisions, safe operation and maintainability. Lower gas consumption is a *hypothesis to measure*, not a promised result.

## Current baseline — v0.2.1

**Implemented (experimental):**

- [x] Native Home Assistant integration with UI-based Config Flow and Options Flow.
- [x] Multiple room temperature sensors and independent room comfort weights.
- [x] Ranked, swappable HA weather sensor sources with normalization/fallback and diagnostics.
- [x] Read-only reference to existing Generic Thermostat and ON/OFF relay.
- [x] Per-room online linear thermal learner, 5-minute sampling and persistent parameters.
- [x] Simple radiator-heat-lag approximation and hypothetical finite-horizon binary MPC plan.
- [x] Integration shown as `service` (not `helper`); configuration entry deletion cleans up saved model data.
- [x] Status, weighted temperature, outside temperature, individual +60-minute forecast entities, and proposed-heat diagnostic binary sensor.
- [x] Baseline pure-Python tests.

**Not yet implemented or validated:**

- [ ] End-to-end HAOS tests across restart, reconfiguration and deletion.
- [ ] Backfill of indoor sensors and relay history from Home Assistant Recorder.
- [ ] Proper held-out, multi-horizon forecast evaluation; plotted predictive trajectories.
- [ ] Explicit sensor freshness policies and full degradation/recovery semantics.
- [ ] Weather forecast inputs, learned effects from wind/clouds or sunshine.
- [ ] Identification of inter-room heat transfer and radiator dynamics beyond the present proxy.
- [ ] Real boiler-burner detection or direct gas-use measurement.
- [ ] **Any live actuation** (intentionally excluded from v0.2.1).

Current behavior: **shadow mode only**. `generic_thermostat` remains the one and only controller of the physical switch.

## Milestone 0 — Audit and reliability (v0.2.x) — FIRST

**Objective:** Make the existing observer trustworthy before extending it.

- [x] Perform a source audit of v0.2.1: pure model, optimizer, config/options, coordinator update timing, persistent model and entity lifecycle.
- [ ] Add Home Assistant test harness coverage for initial setup, update, restart/reload, options changes, missing sensors, `heat/off`, target changes, teardown and uninstall.
- [ ] Verify that **zero physical-device service calls** occur in observation mode, including restart and failed update cases.
- [ ] Establish deterministic handling of 5-minute transitions, polling jitter, timestamp discontinuities, missing data and real switch transitions between samples.
- [x] Add input freshness thresholds and diagnostics that identify exactly which source is missing/stale/invalid.
- [ ] Verify that source switching, entity renaming, adding/removing rooms and replacing the relay do not silently reuse incompatible fitted coefficients.
- [ ] Version persisted model schema; test corrupted/older state and migration/rollback behavior.
- [ ] Verify calculated sample totals and successful/failed fitting counters; expose reasons why training/prediction is unavailable.
- [ ] Add CI, linting, tests and packaging validation (including HACS metadata/translations).
- [ ] Update installation/release documentation and remove packaged `__pycache__`/`.pyc` files if present.

**Exit criteria:** No control writes; reproducible tests covering HA lifecycle; clean upgrade/removal; clear status during outages; no significant model-data loss or silent corruption on restart.

### Audit update — 2026-10-26

See [AUDIT.md](AUDIT.md). The source audit and focused repairs are complete;
Milestone 0 acceptance is **not** complete. Offline boundary doubles cover setup,
reload/unload, migration, removal, corrupt storage, missing inputs and manual off.
They are not a full HA test harness. Per-room accepted ON/OFF counts, additive
payload schema v2, conservative relay-transition rejection, jitter normalization,
Fahrenheit targets and forecast input-change guards are implemented.

Configurable room/weather report-age limits and per-source quality diagnostics
are now implemented with offline coverage. Sensor alignment remains open.
Next implement a supported HA test harness/CI. Then improve event-based sampling and identity/persistence
migration tests. Only after those reliability checks proceed to Milestone 1's
recorded forecasts and walk-forward evaluation. Live control remains unauthorized.

## Milestone 1 — Explainable forecasts and dashboards (target v0.3.0)

**Objective:** Users can verify what the model predicts and whether it is actually accurate.

- [ ] Expose trajectories for each room at 5–15-minute resolution for 2–3 hours, with forecast generation timestamp, horizon and input provenance.
- [ ] Expose predicted +15/+30/+60/+120 minute temperatures and full proposed ON/OFF schedule.
- [ ] Provide an HA dashboard example using native cards or a clearly documented optional chart card (do not bundle a heavyweight frontend unnecessarily).
- [ ] Make clear that the **MPC plan forecast is counterfactual** while Generic Thermostat is controlling the relay; add a separate actual-policy forecast/evaluation pathway.
- [ ] Store a bounded history of predictions with snapshots of inputs, proposed plan and eventually observed outcome.
- [ ] Implement out-of-sample/walk-forward MAE and bias at 15, 30, 60 and 120 minutes; include sample counts and confidence/quality labels.
- [ ] Compare against simple benchmarks such as current-temperature persistence and a fixed thermal baseline.
- [ ] Add inspectable explanations: expected heat loss, expected heating response, target, room weights and reason for the next proposed action.

**Candidate quality gate:** Sustain **about 0.3–0.4°C or better 60-minute MAE** on representative held-out data *under comparable known relay input sequences*, without systematic room bias. This is a starting engineering goal to validate, not a guarantee or an arbitrary gate to waive. Compare to baselines.

## Milestone 2 — Better thermal identification (target v0.4.0)

**Objective:** Improve forecasts with genuinely useful features, not just more inputs.

- [ ] Compare existing per-room linear model with a multi-zone RC model including inter-room heat exchange.
- [ ] Address multiple sensors within a single physical room; configurable room grouping, aggregation and comfort priorities.
- [ ] Distinguish air/room thermal mass and radiator lag where observable; avoid overfitting unidentifiable parameters.
- [ ] Add optional Recorder history import/backfill for **indoor sensor + physical relay** history; do not assume old HA Recorder data still exists.
- [ ] Add outdoor forecast data with future timestamps (forecast provider selectable) and compare forecast-based versus constant-outdoor assumptions.
- [ ] Experiment with wind/cloud cover as optional covariates; retain them only if held-out forecast error improves. Solar gains may require orientation/irradiance or a useful proxy.
- [ ] Expose source reliability and provider comparison: normalized units, update age, outages and sensor offsets.
- [ ] Handle shifts in room usage, opened windows, sensor relocation and season changes without unstable feedback.
- [ ] Benchmark RAM, CPU and event-loop latency on Raspberry Pi 5. Prefer standard-library/small scientific dependencies and avoid heavy inference runtimes.

**Exit criteria:** Model complexity justified by reproducible forecast improvements over v0.3.0; stable fitting and manageable HAOS resource usage. Retain the simpler model as fallback where it performs better.

## Milestone 3 — Safety design for optional control (target v0.5.0; NOT AUTHORIZED YET)

**Objective:** Design, simulate and review live actuation **before** any real actuator writes are enabled.

- [ ] Specify a formal **single-owner** strategy for `switch.central_heating_switch`: no simultaneous Generic Thermostat and MPC writers.
- [ ] Design explicit user-selectable controller modes: `Observe` (default), `Advisory`, `MPC Active` (separate opt-in), `Fallback`/manual.
- [ ] Make manual `off` authoritative; never auto-enable heat. Preserve targets/presets (Comfort 22°C / Away 19°C / Sleep 21°C in current household; all configurable).
- [ ] Define watchdog, heartbeat, max-command age, minimum ON/OFF time, bounds, restart rules and an unambiguous safe behavior on invalid data.
- [ ] Test handover to/from Generic Thermostat with no overlap, stuck state, or unexpected ON request. Handover itself must be user-visible and reversible.
- [ ] Add pure simulation / hardware-in-the-loop-style tests for sensor dropouts, rapid changes, relay availability, HA restart, config reload and network loss.
- [ ] Perform dry-run comparison of live decisions versus the existing thermostat using recorded traces.
- [ ] Provide a rollback playbook and explicit separate approval step to begin live experiments.

**Hard gate:** Do **not** add, enable or invoke real actuation merely because this milestone is on the roadmap. Get explicit user approval after the safety design and tests are reviewed. This includes indirect actuations via automations.

## Milestone 4 — Controlled evaluation (future v0.6.x)

Only after the Milestone 3 gate has been satisfied:

- [ ] Conduct short, supervised and reversible trials with one active controller at a time.
- [ ] Compare comfort: time outside user-defined comfort band, degree-minutes of discomfort, overshoot and temperature variability **per room**.
- [ ] Compare actuator commands: total commanded ON time, restart count and cycle lengths.
- [ ] Where available, compare **measured burner operation and gas-meter data** normalized for outdoor weather. Relay ON time alone is not gas consumption.
- [ ] Measure manual overrides, watchdog/fallback activations and recovery behavior.
- [ ] Define clear criteria to return to the existing Generic Thermostat if predicted performance or safety degrades.

## Milestone 5 — Stable release / HACS (future v1.0.0)

- [ ] Document user-facing installation, config, sensor selection, tuning, compatibility, backup and uninstall.
- [ ] Provide robust migration from old config entries and stored model data.
- [ ] Stable entity IDs, diagnostics downloads where safe, translations and troubleshooting.
- [ ] CI, meaningful automated HA integration tests and supported HA version policy.
- [ ] Clean HACS repository metadata, release tags and changelog.
- [ ] Clearly document the difference between a thermostat demand command and burner/gas consumption.
- [ ] Publish only after real HAOS testing and acceptance criteria are met.

## Non-goals (unless separately approved)

- Replacing the boiler or modifying gas-side operation, burner modulation, flow-temperature electronics, wiring or safety circuitry.
- Adding cloud AI/LLMs for thermostat decisions.
- Creating a direct InfluxDB integration: weather data already exists as Home Assistant sensors.
- Controlling individual radiators without individually addressable actuators.
- Guaranteeing a fuel saving based solely on relay-state history.
- Auto-switching the user's HVAC mode between `off` and `heat`.

## Priority backlog for the next Codex session

1. Confirm the imported repository contents match v0.2.1; run existing tests and write an honest baseline audit.
2. Review HA lifecycle, polling/sample timing, options reload, storage/cleanup and failure handling; fix P0 problems before features.
3. Add a test harness (HA fixtures/mocks) and a shadow-only invariant test prohibiting all actuator service calls.
4. Add forecast recording and held-out evaluation, then expose a trajectory usable by an HA dashboard.
5. Only then consider richer weather inputs and the live-control **design**; do not implement live control without separate authorization.

## Definition of done for each milestone

- Documented requirements and behaviors, backward-compatibility notes and any schema changes.
- Tests for nominal, edge and failure paths, with actual commands/results stated in the PR/commit summary.
- No regressions to sensor configurability, preset behavior or manual mode control.
- Observability sufficient to explain predictions and diagnose invalid inputs.
- HAOS verification clearly differentiated from unit tests; no unsupported performance claims.
- Release notes and installation/rollback instructions updated when appropriate.

**Guiding principle:** a reliable, locally explainable thermostat model is more valuable than a sophisticated optimizer whose predictions cannot be validated or whose failure behavior is unclear.