MAINT-20 part 2 of 3: comments and docstrings in app/main.py cut to what the code does, the why where it is not obvious, and a DECISIONS pointer. No code change, no behaviour change, no CHANGELOG entry, no version change.
Proof:python3 goodwe_controller/tools/maint20_same_code.py d4c01da (from the repository root): ast.dump() without docstrings and the python -OO code objects are identical to base. main.py ratio 1.19 -> 0.49 (code 3 661, comment+doc 4 345 -> 1 792). No docstring is removed entirely or added.
The first commit fixes the script (review finding 8): added/removed app/*.py is a code difference, no divide-by-zero, -OO comparison, allow-list of touched paths, list of docstrings removed or added.
DECISIONS: new MAIN-orchestration.md (curated reasoning by section) and MAIN-orchestration-archive.md (the shortened comments word for word, keyed by their line at d4c01da).
Reviewer: please check the archive-pointer comments in main.py; many blocks were cut mechanically to their first sentences plus one warning, with the full text in the archive.
MAINT-20 part 2 of 3: comments and docstrings in `app/main.py` cut to what the code does, the why where it is not obvious, and a DECISIONS pointer. No code change, no behaviour change, no CHANGELOG entry, no version change.
**Proof:** `python3 goodwe_controller/tools/maint20_same_code.py d4c01da` (from the repository root): `ast.dump()` without docstrings and the `python -OO` code objects are identical to base. main.py ratio 1.19 -> 0.49 (code 3 661, comment+doc 4 345 -> 1 792). No docstring is removed entirely or added.
The first commit fixes the script (review finding 8): added/removed `app/*.py` is a code difference, no divide-by-zero, `-OO` comparison, allow-list of touched paths, list of docstrings removed or added.
DECISIONS: new `MAIN-orchestration.md` (curated reasoning by section) and `MAIN-orchestration-archive.md` (the shortened comments word for word, keyed by their line at `d4c01da`).
Reviewer: please check the archive-pointer comments in main.py; many blocks were cut mechanically to their first sentences plus one warning, with the full text in the archive.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01Bdqr7PiaHcBnzPituu2yTC
Nine conflicts in app/main.py, all in comments around new code: every code
line is release/1.0's, every comment follows the part 2 rule.
Co-Authored-By: Claude <noreply@anthropic.com>
- check_peak_floor_limited: restore the SAFETY-25 line (the reserve sentence is
in messages.peak_reserve() on every branch, unreadable SoC included).
- Three status-page comments that no longer said anything (SAFETY-20 row,
AC 5 delivery row, banner-vs-text) now say their rule in one line.
- tariff_refresh_wanted docstring: no orphan "TARIFF-24)" line.
- MAIN-orchestration.md: blank line before the first heading.
- MAIN-orchestration-archive.md: refilled intro; says how to find a section
from a main.py pointer.
No code change: maint20_same_code.py 16029d7 -> SAME CODE, -OO same.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MAINT-20 part 2 review (head reviewed f8df7cd, review fixes in bbbc89b)
Checks
No code change: tools/maint20_same_code.py 16029d7 prints SAME CODE ... -OO same, OK: no code change on f8df7cd and on bbbc89b. The diff touches only app/main.py, DECISIONS/MAIN-orchestration*.md and the script. The script change is correct (added/removed file, no divide by zero, -OO code-object compare, allow-list, docstrings removed/added).
Nothing safety-relevant lost: I read 120+ of the 203 archive sections against main.py. I covered every section in the alarm methods, handle_action/shutdown, status rows, amain/CFG-01, TEL-07/TEL-11 publishing, SMA-2/SMA-10/SAFETY-128/SAFETY-137 and the cycle's safety stops. Every warning, unit, sign convention, invariant and hardware fact survives as a line + pointer, with one exception (finding 1).
Pointers: every DECISIONS/<note>.md named in main.py exists, and so does TEL-14 §3. Archive pointers name the file only (finding 4).
Tests that pin comment text (test_price_history FCST-04 phrases, test_watchdog / SAFETY-32 "the moment a poll was missed", test_peakguard "rule ordering", test_pv "missing per-unit reading", shadow.py "main.py's own header"): all still find their text.
Readable: no ragged lines in comment blocks, and no pointer split across lines. Lines over 79 columns went from 571 to 118. The fragments are fixed (finding 2).
Ratio 0.54: see the report. In short, the extra lines are mostly warnings, not history.
CI: run 1579 checks / unit success on f8df7cd. On bbbc89b: run 1581 checks / unit (pull_request) success, and run 1582 infra-pin / fresh success. Local full suite on f8df7cd (goodwe-addon-checks:1, --network none, hwsim at infra pin 3b4ff84, GOODWE_REQUIRE_HWSIM=1): 101 files, 0 failed, 1842 s; test_freeze part 3 ran on the real hwsim. On bbbc89b I ran the source-reading tests locally (named_absence, docs, bytecode, watchdog, price_history, peakguard, messages): all pass.
Findings
#
Sev
Where
What
Action
1
Low
app/main.py:4668 (check_peak_floor_limited)
The SAFETY-25 warning was dropped: the reserve sentence must render on every branch, unreadable SoC included.
Several cut comments carry no pointer: FALLBACK_BUDGET_S, _await_inflight, _release_last, the retry wait, release_zero_sent, released = False, _w, stop_event, the SMA-2 read. Full text is in the archive and the SMA-10/SAFETY-137 notes.
Small non-safety losses: "label unchanged at N=1", "both terms are required", "flag set before the await; control not touched", "part 6 grades widening the window". All are in the archive.
None
7
Info
tools/maint20_same_code.py
git diff --name-only BASE sees tracked files only, so an untracked new app/*.py is not checked (run it on a clean checkout). qualnames() keys by name, so same-named defs share one entry; the -OO compare still catches a removed docstring.
None
8
Info
DECISIONS/SAFETY-32 line 712
Cites main.py:932-936 by line number; it was already stale before this PR.
Part 3
Verdict: MERGE-READY at bbbc89b235b634826725f02d029dd76c29349711 (the owner still has to accept a ratio of 0.54). Not merged; waiting for the manager's go.
## MAINT-20 part 2 review (head reviewed `f8df7cd`, review fixes in `bbbc89b`)
**Checks**
1. No code change: `tools/maint20_same_code.py 16029d7` prints `SAME CODE ... -OO same`, `OK: no code change` on `f8df7cd` and on `bbbc89b`. The diff touches only `app/main.py`, `DECISIONS/MAIN-orchestration*.md` and the script. The script change is correct (added/removed file, no divide by zero, `-OO` code-object compare, allow-list, docstrings removed/added).
2. Nothing safety-relevant lost: I read 120+ of the 203 archive sections against main.py. I covered every section in the alarm methods, `handle_action`/`shutdown`, status rows, `amain`/CFG-01, TEL-07/TEL-11 publishing, SMA-2/SMA-10/SAFETY-128/SAFETY-137 and the cycle's safety stops. Every warning, unit, sign convention, invariant and hardware fact survives as a line + pointer, with one exception (finding 1).
3. Pointers: every `DECISIONS/<note>.md` named in main.py exists, and so does TEL-14 §3. Archive pointers name the file only (finding 4).
4. Tests that pin comment text (test_price_history FCST-04 phrases, test_watchdog / SAFETY-32 "the moment a poll was missed", test_peakguard "rule ordering", test_pv "missing per-unit reading", shadow.py "main.py's own header"): all still find their text.
5. Readable: no ragged lines in comment blocks, and no pointer split across lines. Lines over 79 columns went from 571 to 118. The fragments are fixed (finding 2).
6. Ratio 0.54: see the report. In short, the extra lines are mostly warnings, not history.
7. CI: run 1579 `checks / unit` success on `f8df7cd`. On `bbbc89b`: run 1581 `checks / unit (pull_request)` success, and run 1582 `infra-pin / fresh` success. Local full suite on `f8df7cd` (`goodwe-addon-checks:1`, `--network none`, hwsim at infra pin `3b4ff84`, `GOODWE_REQUIRE_HWSIM=1`): 101 files, 0 failed, 1842 s; test_freeze part 3 ran on the real hwsim. On `bbbc89b` I ran the source-reading tests locally (named_absence, docs, bytecode, watchdog, price_history, peakguard, messages): all pass.
**Findings**
| # | Sev | Where | What | Action |
|---|---|---|---|---|
| 1 | Low | `app/main.py:4668` (check_peak_floor_limited) | The SAFETY-25 warning was dropped: the reserve sentence must render on every branch, unreadable SoC included. | Restored as one line (bbbc89b) |
| 2 | Low | `app/main.py:5186`, `:5479`, `:5601` | Three status comments had become fragments that said no rule (SAFETY-20 "second reason", AC 5 "same honesty", banner-vs-text). | Each now says its rule in one line (bbbc89b) |
| 3 | Nit | `app/main.py:164` | The `tariff_refresh_wanted` docstring had an orphan "TARIFF-24)" line. | Refilled (bbbc89b) |
| 4 | Low | 166 `(DECISIONS/MAIN-orchestration-archive.md)` pointers | They name the file, not a section. 142 of them are found by the comment's first words; the other 24 only by a phrase. | Archive intro now says how to find a section (bbbc89b). Adding section keys to 166 sites is left for MAINT-21, which moves them anyway |
| 5 | Low | `app/main.py:125-140`, `:3078-3243`, `:4922` (SMA-10/SAFETY-137 cuts) | Several cut comments carry no pointer: FALLBACK_BUDGET_S, `_await_inflight`, `_release_last`, the retry wait, `release_zero_sent`, `released = False`, `_w`, `stop_event`, the SMA-2 read. Full text is in the archive and the SMA-10/SAFETY-137 notes. | Not changed (part 3 / MAINT-21) |
| 6 | Info | main.py `:5301`, `fresh_tariff_plan`, `check_price_gap`, `:3511` | Small non-safety losses: "label unchanged at N=1", "both terms are required", "flag set before the await; control not touched", "part 6 grades widening the window". All are in the archive. | None |
| 7 | Info | `tools/maint20_same_code.py` | `git diff --name-only BASE` sees tracked files only, so an untracked new `app/*.py` is not checked (run it on a clean checkout). `qualnames()` keys by name, so same-named defs share one entry; the `-OO` compare still catches a removed docstring. | None |
| 8 | Info | `DECISIONS/SAFETY-32` line 712 | Cites `main.py:932-936` by line number; it was already stale before this PR. | Part 3 |
**Verdict: MERGE-READY at `bbbc89b235b634826725f02d029dd76c29349711`** (the owner still has to accept a ratio of 0.54). Not merged; waiting for the manager's go.
admin
merged commit 56fc41fffa into release/1.02026-11-08 22:16:28 +01:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
MAINT-20 part 2 of 3: comments and docstrings in
app/main.pycut to what the code does, the why where it is not obvious, and a DECISIONS pointer. No code change, no behaviour change, no CHANGELOG entry, no version change.Proof:
python3 goodwe_controller/tools/maint20_same_code.py d4c01da(from the repository root):ast.dump()without docstrings and thepython -OOcode objects are identical to base. main.py ratio 1.19 -> 0.49 (code 3 661, comment+doc 4 345 -> 1 792). No docstring is removed entirely or added.The first commit fixes the script (review finding 8): added/removed
app/*.pyis a code difference, no divide-by-zero,-OOcomparison, allow-list of touched paths, list of docstrings removed or added.DECISIONS: new
MAIN-orchestration.md(curated reasoning by section) andMAIN-orchestration-archive.md(the shortened comments word for word, keyed by their line atd4c01da).Reviewer: please check the archive-pointer comments in main.py; many blocks were cut mechanically to their first sentences plus one warning, with the full text in the archive.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Bdqr7PiaHcBnzPituu2yTC
16029d7) into MAINT-20-2 c2b4302dcfMAINT-20 part 2 review (head reviewed
f8df7cd, review fixes inbbbc89b)Checks
tools/maint20_same_code.py 16029d7printsSAME CODE ... -OO same,OK: no code changeonf8df7cdand onbbbc89b. The diff touches onlyapp/main.py,DECISIONS/MAIN-orchestration*.mdand the script. The script change is correct (added/removed file, no divide by zero,-OOcode-object compare, allow-list, docstrings removed/added).handle_action/shutdown, status rows,amain/CFG-01, TEL-07/TEL-11 publishing, SMA-2/SMA-10/SAFETY-128/SAFETY-137 and the cycle's safety stops. Every warning, unit, sign convention, invariant and hardware fact survives as a line + pointer, with one exception (finding 1).DECISIONS/<note>.mdnamed in main.py exists, and so does TEL-14 §3. Archive pointers name the file only (finding 4).checks / unitsuccess onf8df7cd. Onbbbc89b: run 1581checks / unit (pull_request)success, and run 1582infra-pin / freshsuccess. Local full suite onf8df7cd(goodwe-addon-checks:1,--network none, hwsim at infra pin3b4ff84,GOODWE_REQUIRE_HWSIM=1): 101 files, 0 failed, 1842 s; test_freeze part 3 ran on the real hwsim. Onbbbc89bI ran the source-reading tests locally (named_absence, docs, bytecode, watchdog, price_history, peakguard, messages): all pass.Findings
app/main.py:4668(check_peak_floor_limited)bbbc89b)app/main.py:5186,:5479,:5601bbbc89b)app/main.py:164tariff_refresh_wanteddocstring had an orphan "TARIFF-24)" line.bbbc89b)(DECISIONS/MAIN-orchestration-archive.md)pointersbbbc89b). Adding section keys to 166 sites is left for MAINT-21, which moves them anywayapp/main.py:125-140,:3078-3243,:4922(SMA-10/SAFETY-137 cuts)_await_inflight,_release_last, the retry wait,release_zero_sent,released = False,_w,stop_event, the SMA-2 read. Full text is in the archive and the SMA-10/SAFETY-137 notes.:5301,fresh_tariff_plan,check_price_gap,:3511tools/maint20_same_code.pygit diff --name-only BASEsees tracked files only, so an untracked newapp/*.pyis not checked (run it on a clean checkout).qualnames()keys by name, so same-named defs share one entry; the-OOcompare still catches a removed docstring.DECISIONS/SAFETY-32line 712main.py:932-936by line number; it was already stale before this PR.Verdict: MERGE-READY at
bbbc89b235b634826725f02d029dd76c29349711(the owner still has to accept a ratio of 0.54). Not merged; waiting for the manager's go.