docs: ADR-011 setpoint leases, spec F3 limits decided, roadmap M4

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/decisions/011-setpoint-leases.md

@@ -0,0 +1,34 @@
+# ADR-011: Setpoint changes are leases that the backend renews
+
+Status: accepted · 2026-10-24
+
+## Context
+
+ADR-006 restores a timed boost by itself, but a change "until changed" (away: CWU 10, CO 15)
+stays forever. If the backend, the tunnel or the Kraków server is lost for good, the house stays
+on those settings until someone notices. The requirement: a missing command at the gateway
+reverses the change.
+
+## Decision
+
+- Every applied change, timed or not, keeps a restore with a **lease** of 15 minutes
+  (`leaseUntil`). The restore runs at the earlier of its end time (`due`, null for "until
+  changed") and the end of the lease, through the existing path: conflict check, read-back,
+  backoff.
+- `POST /commands/renew` (token, same throttle as `/commands`) extends the lease to 15 minutes
+  from now for every restore that has not reached its run time. A lapsed, due or failing restore
+  is never revived.
+- The backend calls it every 5 minutes from its start while `GATEWAY_TOKEN` is set. A failed call
+  is logged and retried; two in a row may fail without effect.
+- A restore file entry without `leaseUntil` (older file) counts as lapsed and is restored on
+  start. `leaseUntil` is saved atomically like the rest.
+- Limits and presets stay as agreed: CWU at most 48 °C (code ceiling 50), CO 5–25, restores at
+  most 72 h.
+
+## Consequences
+
+- "Until changed" means "while the backend runs and reaches the gateway". The UI says so.
+- After a backend or tunnel outage longer than 15 minutes the house returns to the original
+  values; the user sets them again. That is the intended safe direction.
+- One extra small file write on the Pi every 5 minutes while a change is active.
+- A backend that is up but wrong about the world keeps changes alive; the gateway cannot tell.

docs/roadmap.md

@@ -39,7 +39,7 @@ their names and fields; new data goes into new measurements (ADR-005). The heat
 |---|---|---|
 | M2 Understand the controller | Timing (safe poll rate, response times), which pumps run in which state, open questions in `docs/frisko/` | `docs/frisko/` reviewed; F3 limits agreed |
 | M3 Backend and web UI, read-only | Backend in Docker in Kraków: history from Influx, snapshot from the gateway; F1, F2, F5, F7 with the schematic and charts after `research/ui/`; Traefik route, Krosno only and no login for now (ADR-009). Backend, frontend and their images are on master (ADR-008 proposed, ADR-010); open: `REGISTRY_TOKEN`, first release, the stack in homelab-compose (Arcane) | My father sees the heat pump and the energy on his phone |
-| M4 Setpoints | F3 through gateway commands with timed restore (ADR-006); CWU first, then CO; S1–S6. On master and wired, off until `commands.enabled` (gateway/README.md: Enabling commands): command service with restores, FC6, token-protected `/commands`, backend `/api/setpoints` and presets, UI tab Ustawienia | Father boosts hot water from his phone, value restored on time |
+| M4 Setpoints | F3 through gateway commands with timed restore (ADR-006) and 15 min leases the backend renews (ADR-011); CWU first, then CO; S1–S6. On master and wired, off until `commands.enabled` (gateway/README.md: Enabling commands): command service with restores, FC6, token-protected `/commands`, backend `/api/setpoints` and presets, UI tab Ustawienia | Father boosts hot water from his phone, value restored on time |
 | M5 Alarms | F4; decide the channel first (e.g. ntfy, Telegram) | Simulated alarm reaches the phone |
 | M6 Native app? | Decide: keep the web UI, WebView wrapper or React Native | Decision recorded |
 

docs/spec.md

@@ -78,11 +78,12 @@ Functional:
 - F2 History for the last 7 days.
 - F3 Change four setpoints: economy and comfort temperature of CWU (4143, 4144) and CO
   (4131, 4132). Any value within limits, or one tap on a named preset. Limits and presets live in
-  the backend config: CWU 5–50 °C (pump maximum per my father; 48 °C proposed for margin, to
-  decide in M2), CO 5–25 °C.
+  the backend config: CWU 5–48 °C (decided; the gateway's ceiling stays 50), CO 5–25 °C.
   - **Boost**: raise the economy temperature for a duration the user picks; the previous value
     is restored automatically.
   - **Away / not needed**: lower the comfort temperature (e.g. CWU 10 °C, CO 15 °C) until changed back.
+  - **Lease** (ADR-011): every change also needs the backend to renew it every 5 minutes; after
+    15 minutes without, the gateway restores the previous value.
 - F4 Alarms with notifications: heat pump alarm, controller link lost, grid outage (house on battery).
 - F5 Health of backend, device links and tunnel.
 - F6 Later, low priority: show the weekly program (reading needs selector writes).