SAFETY-07 review: defend the three wiring mutations that survived

The reviewer's finding was correct and the shape of it matters: everything the
first cut graded was in peakguard.py, and grading the module is not the same as
grading the guard. Three one-line changes to main.py's CALL SITE left all twelve
suites green while a default install parked at 0 W in the quarter that sets the
month's bill.

B2 was the serious one. My own comment described that defect - "that entity is
optional and empty on a default install, so until now the suspension could not
fire on the site that needed it" - and nothing could regress it. A comment that
documents a fix nobody can test is the same shape as a corrected comment nobody
tests, which this project has already been caught by once.

WHAT CHANGED

The suppression conjunction moved out of main.py and into
peakguard.shaping_suspended(), for the reason watchdog.loop_is_following() and
freeze.looks_frozen() live where they do: the check that grades a safety
predicate must assert on THE SHIPPED EXPRESSION, not on a transcription that can
drift apart from it in silence. Its docstring carries both terms and why neither
is sufficient alone. main.py's call site now says READ THAT FUNCTION FIRST, and
records that a reviewer mutated it back to its historical broken form with every
suite staying green.

test_peakguard.py part 7 gains a section that EXECUTES the three mutations
rather than describing them. Each one is put in place on the shipped module and
the REAL Controller.cycle() is driven with it, on the dangerous fixture: a
default install (no peak_forecast_entity, so peak_fc is None and peak_at_risk is
False forever) with maintenance in its CHARGE phase, so a P_MAINT_SHAPE `hi <= 0`
limit is live, and the guard genuinely engaged on the measurement. That the
mutations are monkeypatched onto the shipped module is itself load-bearing: if
main.py inlined either expression again the patch would do nothing and these
checks would pass vacuously.

    SHIPPED   suspended=True    loop -> 1498 W, limited by peak    +1497.8 W
    B1        suspended=False   CONTRADICTION between limits           0.0 W
    B2        suspended=False   CONTRADICTION between limits           0.0 W
    B2b (forecast term dropped instead) - caught by its own check

B3 is graded three ways, because the single-cycle form is only INFLATED and the
failure is what happens on the next cycle:

  * the value main.py actually hands decide() is recorded off the real call, with
    the measured battery at 0 W and the command standing at +3000 W;
  * the one-cycle difference is asserted to be exactly the standing command - the
    whole defect in one line, watts that were asked for and never arrived counted
    as if they had;
  * both forms are then run forward against the REAL controller's own projection
    with an inverter that never follows:

        intent-sized floor    4482 5000 5000 5000 ...  SATURATED at cycle 2
        delivered-power floor 1482 1482 1482 1482 ...  stationary

  * and the call site is graded on parsed syntax, so a rename cannot quietly
    reintroduce it: `decide(batt_w=...)` must unparse to `self.batt`.

SAFETY-24 is now named in peakguard.py, in its own section, with the number that
makes it real - 878 Wh of forced discharge on the 2026-08-20 replay - and the
statement that this must not go to a client install before that ticket lands. A
ticket nobody can find from the code is a ticket nobody reads before shipping.

RED AND GREEN

Fifteen mutations run against the shipped modules, each reverted after: the six
new wiring ones (B1, B2, B2b, B3, B3b, and deleting the SAFETY-24 pointer) and
the eight from the first round, re-run to confirm they still bite. All fifteen
turn test_peakguard.py red. Full suite green, test_price.py and TARIFF-03's
included.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015VXjA3LWccN1rJsk3okyPC

goodwe_controller/app/main.py

@@ -515,11 +515,17 @@ class Controller:
             # default install, so until now the suspension could not fire on the
             # site that needed it. `self.peak_guard` is measured from the meter
             # and is always there.
-            suspend = peak_at_risk(self.peak_fc,
-                                   float(self.o.get("peak_cap_w", 3500)))
-            if self.peak_guard is not None and self.peak_guard.engaged:
-                suspend = True
-            if suspend:
+            #
+            # ⚠️ THE CONJUNCTION LIVES IN peakguard.py, NOT HERE, and that is not
+            # tidiness. It was inline, and a reviewer mutated it back to its
+            # historical broken form - re-gated on `peak_forecast_entity` alone -
+            # and every suite in this repository stayed green while a default
+            # install parked at 0 W in the quarter that sets the month's bill.
+            # Read shaping_suspended() before touching this: both terms are
+            # there, and why neither is sufficient alone.
+            if peakguard.shaping_suspended(
+                    self.peak_guard, self.peak_fc,
+                    float(self.o.get("peak_cap_w", 3500))):
                 # Edge-logged: level-logging here would write one line per cycle
                 # for as long as the event lasts and flush the 40-line action log
                 # of the very context that explains it.

goodwe_controller/app/peakguard.py

@@ -245,6 +245,21 @@ validate.py are untouched by this ticket, exactly as TARIFF-01 left them, and
 14's `capacity_peak_limit_kw` stays declined - a kW key beside a W key is the
 mismatch trap 14's own warning box describes.
 
+------------------------------------------------------------------------------
+⚠️ WHAT THIS GUARD DOES NOT HAVE: AN ENERGY BACKSTOP. SEE SAFETY-24.
+
+The graded branch can FORCE DISCHARGE, and nothing in this file or in the loop
+below it consults the state of charge - `soc_floor` belongs to the maintenance
+cycle, and freeze.py already records that for the grid-following loop "the BMS
+is the sole energy backstop". On the 2026-08-20 replay the guard asks for 878 Wh
+in a day. Against a pack sitting near 9 % that is not nothing, and the guard will
+keep asking as long as the meter says the quarter is over the ceiling.
+
+That is deliberate for THIS card and it is filed as SAFETY-24. It is also the
+reason this must not go to a client install before SAFETY-24 lands: on the
+reference site the BMS is a known quantity and an operator is present, and on a
+client site neither is true.
+
 ------------------------------------------------------------------------------
 AND IT READS NO PER-PHASE QUANTITY, ON PURPOSE
 
@@ -258,6 +273,7 @@ not need re-testing. Nothing here indexes a phase.
 from dataclasses import dataclass
 
 from .arbiter import P_PEAK, Claim
+from .control import peak_at_risk
 from .tariff import QUARTER_S
 
 # Why the projection may not be graded. Reasons, not booleans: the status page
@@ -454,6 +470,40 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w,
                f"only give {ceil_top:.0f} W" if saturated else "")))
 
 
+def shaping_suspended(decision, peak_forecast_w, cap_w) -> bool:
+    """Must the maintenance charge-only shaping stand down this cycle?
+
+    THE ONE PLACE THIS CONJUNCTION IS WRITTEN, and it is public for the reason
+    `watchdog.loop_is_following()` and `freeze.looks_frozen()` are: the check
+    that grades it has to assert on THE SHIPPED EXPRESSION. A safety predicate
+    transcribed into its own test is one copy plus a future disagreement about
+    what the check means, and the copy that drifts is always the grading one.
+    It was inline in `main.py` and nothing could reach it; a reviewer mutated it
+    back to its historical broken form and all twelve suites stayed green.
+
+    ⚠️ WHY SUPPRESSION AND NOT PRIORITY. The shaping is a LIMIT (`hi <= 0`) and
+    the peak guard's claim is a LIMIT (`lo >= 0`). arbiter.py clause 2 applies
+    EVERY limit at or above the winner's priority and takes the MOST RESTRICTIVE,
+    with no notion of one limit outranking another - which is precisely what
+    makes the safety bounds unconditional and must not be changed. Two crossing
+    limits are therefore a CONTRADICTION, which resolves to 0 W: the battery
+    PARKED, in the one quarter of the month that sets the bill. P_PEAK 50 >
+    P_MAINT_SHAPE 40 does not save it and never could.
+
+    ⚠️ AND THE FIRST TERM IS NOT ENOUGH ON ITS OWN. `peak_forecast_entity` is
+    OPTIONAL and is empty on a default install, so `peak_forecast_w` is None
+    there and `peak_at_risk()` answers False forever. Before this card the
+    suspension therefore could not fire on the very site that needed it. The
+    second term is the MEASURED guard, which is always present wherever P1 is.
+    Deleting either term - or re-gating the whole thing on the forecast - parks
+    a default install at 0 W, silently, in the billed quarter. test_peakguard.py
+    part 7 drives the real cycle with each of those mutations in place.
+    """
+    if peak_at_risk(peak_forecast_w, float(cap_w)):
+        return True
+    return decision is not None and decision.engaged
+
+
 def claim(decision: PeakDecision) -> Claim | None:
     """The decision as one arbiter claim, or None when the guard is idle.