MAINT-20 part 2 r2: app/main.py comments, lines 2501-3000 (_peak_over_drain .. _read_unit)

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

goodwe_controller/app/main.py

@@ -2546,8 +2546,8 @@ class Controller:
     def _drain_over_reserve(self, claims, maint_results) -> None:
         """SAFETY-87, N>=2: while a battery is held at its peak reserve, a
         draining battery that may still give is raised from its drain rate
-        towards its rating for the peak floor, after the others.
-        (DECISIONS/MAIN-orchestration-archive.md)"""
+        towards its rating for the peak floor, after the others. A site stop
+        still decides alone. DECISIONS/SAFETY-87-guard-uses-able-batteries.md"""
         reserve = self._peak_reserve()
         floor = max((c.lo for c in claims if c.source == peakguard.SOURCE),
                     default=0.0)
@@ -2641,10 +2641,11 @@ class Controller:
 
     def _charge_headroom(self, floor: float, claims) -> float:
         """SAFETY-84: a cheap-window charge pulls no more than the quarter's
-        room under the peak aim (`charge_room_w()`), so it yields just
-        enough to the peak guard; at N>=2 nothing under a site stop (its 0 W
-        would need the other pack to give).
-        (DECISIONS/MAIN-orchestration-archive.md)"""
+        room under the peak aim (`charge_room_w()`), so it yields just enough
+        to the peak guard; at N>=2 nothing under a site stop (its 0 W would
+        need the other pack to give). SAFETY-125: at N=1 too; the stop rule
+        stays N>=2 only.
+        DECISIONS/SAFETY-125-grid-charge-under-the-month-peak.md"""
         if len(self.inverters) > 1 and any(
                 c.kind == SET and c.actuator == ACTUATOR_SITE
                 and c.priority > P_MAINT_SHAPE for c in claims):
@@ -2856,7 +2857,8 @@ class Controller:
         elif uses_chain(o):
             # PRICE-01. A provider with fallbacks gives the maintenance gate
             # its own prices: the current 15-minute price against today's
-            # average, as the Home Assistant pair did.
+            # average, as the Home Assistant pair did. No I/O here: the series
+            # is the one the background refresh stored.
             # (DECISIONS/MAIN-orchestration-archive.md)
             self._provider_gate(datetime.now(timezone.utc))
         else: