docs: add verification rules to claude.md from this week's failures

Twelve rules, each written from a bug that shipped rather than from
principle. The ones that cost the most:

- Check the protocol docs before inferring. Register meanings were argued
  across issue threads for a week, twice wrongly, while the answers sat
  in Protocols/ and docs/developer/protocol-v139.md. SOH is 1096, not
  31218; 1021 is grid import and 1037 is house load.
- Input and holding registers overlap at the same addresses. Three
  separate errors, including reading input 43 and concluding a device
  reports no DTC when the DTC lives in holding 43 -- made while warning
  another person about the same trap.
- Read OK does not mean works. A register answering 0 reports as Read OK,
  which kept two dead write registers alive through three contradicting
  field reports.
- Verify the whole chain. Three releases needed follow-ups this week and
  all three had the same shape: the half being thought about was correct
  and the other half was not.
- hasattr() gates are no-ops against dataclass fields. 31 of them exist.
- Never write file content through PowerShell.

Also adds release cadence and the pull procedure (a draft is orphaned if
you delete its tag and must be removed through the API), and PowerShell
notes for the bash idioms that fail here.

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

Author: 0xAHA

claude.md

@@ -4,6 +4,134 @@ This document provides comprehensive guidelines for AI assistants (and developer
 
 ---
 
+## 🛑 RULES THAT PREVENT REAL BUGS
+
+Every rule below exists because it was broken and something shipped wrong. The examples are
+real, not hypothetical. Read this before the sensor checklist.
+
+### 1. Check the protocol documents before inferring anything
+
+We have ~2.5 MB of Growatt protocol documentation in `Protocols/` and a 105 KB extracted
+reference in `docs/developer/protocol-v139.md`. **Search it first.** Grep the register
+number. It takes seconds.
+
+Register meanings were argued across GitHub threads for a week, twice wrongly, while the
+answers were already checked in:
+
+- Battery SOH was reported to a user as register 31218 (VPP range) and possibly
+  unobtainable. It is **1096**, documented as `BMS_SOH` under "BMS information 1082-1124".
+- Registers 1021/1037 were disputed for days. The doc states plainly: `1021 PactouserTotal`
+  (grid import), `1037 PLocalLoad total` (house load).
+
+A profile's `desc` string, a code comment, and a model's marketing name are **not
+evidence**. The protocol document and a field scan are.
+
+### 2. Input and holding registers overlap — always state the function code
+
+The same address means different things in each space. This has caused three separate
+errors:
+
+| Address | Holding (FC03) | Input (FC04) |
+|---|---|---|
+| 43 | DTC / device type code | `Iac2` phase 2 current |
+| 1083-1088 | Grid First time periods | BMS status / SOC / voltage / current / temp |
+| 1100-1108 | Battery First time slots | BMS gauge and version data |
+
+Reading input 43 and concluding a device reports no DTC — when the DTC lives in holding 43
+— is a mistake that has been made *while warning someone else about the same trap*. When
+you cite a register, say which space it is in.
+
+### 3. "Read OK" and "responds" do not mean "works"
+
+A register answering with `0` reports as **Read OK**. That is evidence the address
+responds, never that the value is meaningful or that writes take effect.
+
+Registers 1071/1091 survived three contradicting field reports because an old scan showed
+"all Read OK". They accept writes and silently ignore them.
+
+### 4. Absence of evidence needs the evidence to have been possible
+
+Before concluding a register is empty or absent, confirm the scan actually covered it.
+A v0.7.7 scan was used to prove a device reports no DTC — that scanner version never read
+the legacy holding range at all. A missing range in a scan is not a missing value.
+
+### 5. Verify the whole chain, not the half you are thinking about
+
+Three releases needed follow-ups this week, all the same shape:
+
+- v1.2.0: the read path consumed the block-size option correctly, and the form could never
+  save it. Verified the consumer, not the producer.
+- v1.3.5: fixed the option format, updated one of two fetch paths. The other raised
+  `ValueError` on every poll.
+- v1.4.0: removed a register so its sensor would disappear. The sensor platform recreated
+  it from the profile's sensor set and it reported `0.0`.
+
+**When you change a stored format, grep every consumer. When you remove data, check what
+recreates it.**
+
+### 6. `hasattr()` gates only work on dynamic attributes
+
+`condition: lambda data: hasattr(data, 'x')` reads as "only if the profile provides x". It
+is a no-op when `x` is a `GrowattData` dataclass field, because the field always exists
+with a default — the sensor is created regardless and publishes the default, typically a
+plausible-looking `0`.
+
+It works only for attributes assigned dynamically via `setattr()` (the BMS block, for
+example). 31 conditions in `sensor.py` are decorative; `tests/test_sensor_conditions.py`
+enumerates them and fails if a new one appears. To exclude a sensor for real, remove it
+from the profile's **sensor set** — that is the only hard filter.
+
+### 7. Never write file content through PowerShell
+
+Use the **Edit** and **Write** tools. `Set-Content -Encoding utf8` writes a BOM in PS 5.1,
+which broke `manifest.json` and would have stopped the integration loading. Em-dashes have
+been mangled into `â€"` in three separate files this way.
+
+Prefer plain ASCII in commit messages and shell-adjacent content — hyphens rather than
+em-dashes, straight quotes rather than curly. Non-ASCII in source files is fine *via the
+editing tools*, never via a shell redirect.
+
+Also: `Get-Content -Raw` misreads UTF-8 and will show you mojibake that is not in the file.
+Verify encoding claims with `Grep` or Python, not PowerShell.
+
+### 8. Duplicate dict keys are invisible after import
+
+Python silently keeps the last one. `tl_xh.py` defined register `3136` twice; the
+temperature mapping never existed at runtime — no sensor, no error, nothing to notice.
+Loaded `REGISTER_MAPS` cannot show this. `tests/test_profile_integrity.py` parses the
+profile sources with `ast` to catch it.
+
+### 9. Prove a new test fails without the fix
+
+Disable the fix, run the test, confirm it goes red, restore. Assertions written alongside a
+fix inherit its blind spots — a block-size test asserted `resolve_block_size(stored) == 25`,
+which called the helper on its own output and passed throughout the regression it was
+meant to catch.
+
+### 10. Read every comment on an issue before assessing it
+
+Fetching the last 3 of 16 comments has twice produced an "assessment" that missed the
+decisive measurement. The comment count is in the same API response — check it. A
+maintainer asking "are there new comments?" should never be how a five-comment exchange
+gets discovered.
+
+### 11. Two readings agreeing proves nothing; diverging proves independence
+
+Two registers matching at one moment can be coincidence. Two registers diverging at any
+moment is proof they are separate sources. Only the second direction is conclusive.
+
+Register 3176 was reported as a duplicate of register 93 after both read `545` in one scan.
+A paired reading at a different operating point refuted it. **Always ask for a second
+sample at a different operating point before remapping a register.**
+
+### 12. Mark a mapping CONFIRMED only with a citable device report
+
+`DTC_REGISTRY` in `auto_detection.py` records `CONFIRMED` or `ASSUMED` plus evidence.
+CONFIRMED means a real device on that DTC was seen running that profile, traceable to an
+issue number or scan. Anything else is ASSUMED and says so in the log and the scanner.
+
+---
+
 ## 🚨 START HERE - Adding/Updating Sensors 🚨
 
 **BEFORE making ANY changes to sensors or registers:**
@@ -18,6 +146,13 @@ This document provides comprehensive guidelines for AI assistants (and developer
 □ Step 6: Run validation script: python3 validate_sensors.py --sensor <name>
 ```
 
+**Removing a sensor is not the reverse of this list.** Deleting the register is not enough:
+the sensor platform creates whatever the profile's **sensor set** lists, and a
+`hasattr()` condition cannot stop it if the attribute is a dataclass field (rule 6). Remove
+it from the sensor set, and clear any already-registered entity in `__init__.py` — that
+cleanup must not be gated on the inverter being connected, because `coordinator.data` is an
+empty placeholder during setup (rule 5).
+
 ### 2. **Validation Tools**
 ```bash
 # Validate a specific sensor
@@ -695,6 +830,63 @@ When preparing a release:
    - Check all changed sensors work
    - Test with at least one real device if possible
 
+### Release cadence
+
+**Pre-release by default.** `gh release create vX.Y.Z --prerelease` keeps the previous
+stable marked Latest, so HACS does not offer it unless the user opted into betas. Promote
+to stable once a reporter confirms, or batch weekly.
+
+**One exception — ship stable immediately when we broke it.** A regression that takes
+entities offline, corrupts data, or publishes a wrong-but-plausible value cannot wait for
+a weekly batch, and a pre-release does not reach the people already affected. v1.3.6 and
+v1.4.1 both qualified.
+
+Pre-release convention: bump `manifest.json`, but leave the README badge at the last
+**stable** version.
+
+### Pulling a release
+
+If a release must be withdrawn:
+
+```bash
+gh release edit vX.Y.Z --draft      # off the public list and out of HACS
+```
+
+The previous stable becomes Latest again and the git tag survives. **If you then delete
+the tag, the draft is orphaned and does not disappear on its own** — find and delete it
+explicitly:
+
+```bash
+gh api repos/OWNER/REPO/releases            # find the draft's id
+gh api -X DELETE repos/OWNER/REPO/releases/ID
+```
+
+Re-cut with `gh release create vX.Y.Z --target <sha>` so the tag matches the notes it
+describes. Never leave a published tag pointing at a commit whose notes have since changed.
+
+### Verify after releasing
+
+```bash
+git fetch origin --tags
+gh api repos/OWNER/REPO/git/ref/tags/vX.Y.Z   # must equal main HEAD
+```
+
+`git merge-base` and `rev-parse` give false negatives until you `git fetch --tags` — a tag
+created by `gh release create` exists only server-side until then.
+
+---
+
+## PowerShell Notes (Windows dev environment)
+
+The shell is PowerShell 5.1. Bash idioms fail in ways that waste turns:
+
+- **No heredocs.** `<<'EOF'` is a parser error. For multi-line commit messages write the
+  message to a file and use `git commit -F <file>`.
+- **No `&&` or `||`.** Use `;` or `if ($?) { ... }`.
+- **Never write file content** — see rule 7 above. Edit/Write tools only.
+- `Get-Content -Raw` misreads UTF-8. Use `Grep` or Python to check for encoding damage.
+- `gh api` takes one positional arg; `--jq` with extra args fails confusingly.
+
 ---
 
 ## Quick Reference: File Responsibilities
@@ -730,5 +922,5 @@ When preparing a release:
 
 ---
 
-*Last updated: 2026-01-29*
-*Integration version: 0.2.7*
+*Last updated: 2026-08-09*
+*Integration version: 1.4.1*