SAFETY-24: an energy floor under the peak guard's forced discharge

SAFETY-07 can command a discharge to hold a billed quarter down, and
nothing below it consulted the state of charge. On the 2026-08-20 replay
it asks for 878 Wh in a day. Relying on the BMS is not absurd - it is a
real floor and it works - but it is the pack's protection rather than the
operator's, and a month of aggressive quarters leaves the battery
repeatedly at that cut-out with no EMS-side record of why. The first
symptom is a pack never available when wanted, which is indistinguishable
from the SoC drift MAINT-01 exists to correct.

decide() now takes soc and soc_floor, both required and neither
defaulted, and discharge_permitted() is the one place the question is
answered. Above the floor nothing changes. At or below it the guard files
a 0 W floor instead of a sized one - one-directional, so charging stays
blocked and no discharge is capped - and reports floor_limited with the
reason it bound. It is not a trip: every stop in 11.2's table still
outranks the claim, and the floor is never negative, so 9.1's asymmetry
survives as a property of the object (0 negative floors over 1296 swept
combinations, SoC included).

The SoC is graded only after `wanted > 0` is established, so it is never
evaluated where it governs nothing. An unreadable SoC is floor-limited,
not a full battery - a full battery is exactly the value that would
disarm the floor, and this project shipped that defaulting once already.

Failing to shave is not silent: one notification per episode
(goodwe_peak_soc_floor), distinct from the saturation alarm because the
two ask for opposite operator actions, plus its own status row and an
action-log line.

Verified by replay. The 2026-08-20 capture is driven against a modelled
pack sized from the day's own measured appetite, so it genuinely
exhausts: without the floor it reaches the BMS cut-out and holds there
for 1227 guard cycles; with it the pack stops at 20.0 % and never touches
the BMS. The energy withheld equals the energy between the two floors to
within one cycle at the rail. The honest half is reported too - the worst
quarter goes 4338 W -> 5030 W, because a floor-limited guard shaves less
on purpose.

Two new options, mirrored once in peakguard.PEAK_OPTION_DEFAULTS
(TARIFF-02's pattern), imported by validate.py and main.py rather than
typed as literals and pinned to config.yaml by a check that reads the
file - so CFG-03 still tracks three places. validate.py rule 8 refuses
peak_soc_floor <= bms_soc_floor at startup, in CFG-01/MAINT-04's manner.
maintenance_soc_floor is deliberately not reused and not renamed: it is a
drain target, not a spend limit, and the rename is recorded as a decision
to revisit if a third floor appears.

Eleven mutations of the shipped source were run against the checks; all
eleven go red and there are no survivors.

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

goodwe_controller/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 ## Unreleased
 
+**The capacity-peak guard's forced discharge now has an EMS-side energy floor
+(SAFETY-24).** SAFETY-07 can command a discharge to hold a billed quarter down,
+and nothing below it consulted the state of charge — `soc_floor` belongs to the
+maintenance cycle, and freeze.py already recorded 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**. Relying on the BMS is not absurd — it is a real
+floor and it works — but it is the pack's protection rather than the operator's,
+and a month of aggressive quarters leaves the battery repeatedly at that cut-out
+with no EMS-side record of why.
+
+`decide()` now takes `soc` and `soc_floor`, both **required** and neither
+defaulted. Above the floor nothing changes. At or below it the guard files a
+**0 W** floor instead of a sized one — one-directional, so charging stays blocked
+and no discharge is capped — and reports `floor_limited` with the reason it
+bound. It is not a trip: every stop in §11.2's table still outranks the claim,
+and the floor can never be negative, so §9.1's "discharge and export are never
+capped by the peak guard" survives as a property of the object (swept: 0 negative
+floors across 1296 combinations of load, elapsed, battery, SoC and floor).
+
+**Failing to shave is not silent.** A floor-limited cycle raises one notification
+per episode (`goodwe_peak_soc_floor`), distinct from the saturation alarm because
+the two ask the operator for opposite things, and renders its own status row.
+An **unreadable SoC is floor-limited, not a full battery** — a full battery is
+exactly the value that would disarm the floor, and this project has shipped that
+defaulting once before (`| float(100)` in the stage-5 loop).
+
+**Verified by replay, not by argument.** The 2026-08-20 capture is driven against
+a modelled pack sized from the day's own measured appetite, so it genuinely
+exhausts: without the floor it reaches the BMS cut-out and sits there for 1227
+guard cycles; with it the pack stops at 20.0 % and never touches the BMS. The
+energy withheld equals the energy between the two floors to within one cycle at
+the rail. The honest half is reported too — the worst quarter goes from 4338 W to
+5030 W, because a floor-limited guard shaves less on purpose.
+
+**Two new options, mirrored once.** `peak_soc_floor` (20) and `bms_soc_floor`
+(10), whose defaults live in `peakguard.PEAK_OPTION_DEFAULTS` — TARIFF-02's
+pattern — imported by `validate.py` and `main.py` rather than typed as literals,
+and pinned to `config.yaml` by a check that reads the file. CFG-03 still tracks
+three places. `validate.py` rule 8 refuses `peak_soc_floor <= bms_soc_floor` at
+startup, in CFG-01/MAINT-04's manner. `maintenance_soc_floor` is deliberately
+**not** reused and deliberately **not** renamed: it is a drain target, not a
+spend limit, and the rename is recorded as a decision to revisit if a third
+floor ever appears.
+
 **The grid-following loop is now capped against the month's billed capacity peak
 (SAFETY-07).** New `app/peakguard.py`. TARIFF-01 measured the quarter; this is the
 consumer it was built for. Every cycle the guard projects the open quarter,