[GreenGrassBlueOcean]

What is the problem

In OpenWebNet-HA/OWNd#142 (fix(profiles): drop WHO 16 from the F461 and MyHomeServer1 profiles), 7 of 8 CI jobs pass and 5,072 of 5,073 tests in MyHOME conformance / MyHOME test suite pass, leaving a single failure:

• tests/test_sync_documentation.py::test_check_all_documentation_real_tree — Gateway Discovery table out of sync in docs/getting-started/hardware-compatibility.md.

OpenWebNet-HA/MyHOME#808 added pinned_whos + notes_without_who16 in scripts/update_gateway_profiles.py, tolerated = {16} in verify_profiles_against_oracle(), and rows_off_the_pin tolerance in tests/test_gateway_profiles.py::test_discovery_table_with_ownd_matches_the_committed_docs specifically to bridge the transition window between the pinned OWNd==2.0.0b11 release and OWNd#142. However, scripts/sync_documentation.py::get_gateway_discovery_block() still calls build_discovery_block() unconditionally using the installed OWNd instead of pinned_whos.

Furthermore, merging OWNd#142 to OWNd@master before OWNd 2.0.0b12 is released and pinned in manifest.json would otherwise trigger a CI catch-22 across MyHOME:

• pypi_standards.yml, test-coverage.yaml (via tests/conftest.py), and all 3 matrix legs of ha-upstream-compat.yml install OWNd@master (expecting no WHO 16 on F461 / MyHomeServer1), while
• test-coverage.yaml (sync_documentation.py --check), quality-scale.yml, and docs.yml run sync_documentation.py --check without OWNd installed (checking hardware-compatibility.md against pinned_whos, which still includes WHO 16 for OWNd==2.0.0b11).

Unblocks OpenWebNet-HA/OWNd#142 (comment 6477040171).

---

What is the solution

1. Manifest-bounded transition gate (scripts/update_gateway_profiles.py):
   • Add PRE_WHO16_OWND_PIN = "OWNd==2.0.0b11" and manifest_pins_pre_who16_ownd(manifest_path=MANIFEST_JSON) -> bool.
   • Add keyword-only *, use_pinned: bool = False to calibrate_discovery_with_ownd(), generate_gateway_discovery_table(), and build_discovery_block() so callers that validate the committed docs can pin table generation to pinned_whos while manifest.json still pins OWNd==2.0.0b11, without changing default unit-test behavior (use_pinned=False).
   • Bound tolerated = {16} in verify_profiles_against_oracle(oracle_path=ORACLE_JSON, manifest_path=MANIFEST_JSON) to manifest_pins_pre_who16_ownd(manifest_path) so that once manifest.json bumps past OWNd==2.0.0b11, stale pinned_whos / sweep_omits entries on F461 and MyHomeServer1 are immediately flagged.
2. Synchronize sync_documentation.py across with-OWNd and no-OWNd CI jobs (scripts/sync_documentation.py):
   • Pass manifest_path=CUSTOM_COMPONENTS_DIR / "manifest.json" into verify_profiles_against_oracle().
   • Have get_gateway_discovery_block() call build_discovery_block(use_pinned=manifest_pins_pre_who16_ownd(manifest_path)), keeping CI jobs with OWNd@master and CI jobs without OWNd aligned on the committed OWNd==2.0.0b11 table until the pin bump, and automatically enforcing regeneration (--update + pinned_whos / sweep_omits update) as soon as manifest.json moves to OWNd==2.0.0b12.
3. Self-expiring test assertions (tests/test_gateway_profiles.py, tests/test_sync_documentation.py):
   • Gate rows_off_the_pin in test_discovery_table_with_ownd_matches_the_committed_docs on manifest_pins_pre_who16_ownd().
   • Add explicit tests covering both halves of the lifecycle (during OWNd==2.0.0b11 and after bumping manifest.json to OWNd==2.0.0b12).

---

State Diagram

flowchart TD
    Check["sync_documentation.py --check / pytest"] --> PinGate{"manifest.json pins OWNd==2.0.0b11?"}
    PinGate -- "Yes (Transition Window)" --> UsePinned["build_discovery_block(use_pinned=True)"]
    PinGate -- "Yes (Transition Window)" --> Tolerate["verify_profiles_against_oracle: tolerate WHO 16 delta on F461 / MyHomeServer1"]
    UsePinned --> Agree["OWNd@master jobs & no-OWNd jobs agree on committed hardware-compatibility.md"]
    Tolerate --> Agree
    PinGate -- "No (Bumped >= OWNd==2.0.0b12)" --> LiveProfile["build_discovery_block(use_pinned=False)"]
    PinGate -- "No (Bumped >= OWNd==2.0.0b12)" --> StrictOracle["verify_profiles_against_oracle: zero WHO 16 tolerance"]
    LiveProfile --> Enforce["Enforces regenerating hardware-compatibility.md + updating pinned_whos & sweep_omits"]
    StrictOracle --> Enforce

Loading

---

Hardware Verification

• N/A — documentation anti-drift sentinel and cross-repo CI conformance gating only; runtime integration code under custom_components/myhome/ is untouched.

---

How is it tested

• tests/test_gateway_profiles.py::test_calibrate_discovery_use_pinned_overrides_installed_ownd:
  • Verifies build_discovery_block(use_pinned=True) matches docs/getting-started/hardware-compatibility.md byte-for-byte even when F461 and MyHomeServer1 drop WHO = 16, while build_discovery_block(use_pinned=False) reflects the updated profile rows.
• tests/test_gateway_profiles.py::test_oracle_check_enforces_who16_pin_once_manifest_bumps_past_2_0_0b11:
  • Verifies manifest_pins_pre_who16_ownd() edge cases (missing file, malformed JSON, bumped pin) and confirms verify_profiles_against_oracle() tolerates the WHO = 16 delta under OWNd==2.0.0b11, flags both F461 and MyHomeServer1 immediately upon bumping to OWNd==2.0.0b12, and clears once pinned_whos and sweep_omits are updated.
• tests/test_sync_documentation.py::test_check_all_documentation_stays_green_against_ownd_142_until_pin_bump:
  • Verifies check_all_documentation(update=False) passes on the real repository tree against OWNd#142 profiles while manifest.json pins OWNd==2.0.0b11, and that both sync_gateway_discovery(update=False) and sync_gateway_profiles(update=False) fail with actionable drift errors as soon as manifest.json bumps to OWNd==2.0.0b12.
• Full local validation run in WSL (Python 3.14.7) against both OWNd 2.0.0b11 and OpenWebNet-HA/OWNd#142 (2210296):
  • ruff check custom_components tests scripts: passed (0 violations).
  • scripts/verify_ha_standards.py: passed (all checks green).
  • scripts/sync_documentation.py --check: passed (0 drift).
  • pytest tests/test_gateway_profiles.py tests/test_sync_documentation.py tests/test_startup_requests_per_firmware.py: 129 passed.

---

Where are the traces

• N/A — no new bus captures; oracle reference data lives in tests/golden/firmware_oracle.json.

---

What does the Firmware Oracle / Encyclopedia say

1. OpenWebNet Encyclopedia (WHO = 16 vs WHO = 22):
   • WHO = 16 covers legacy 2-wire sound diffusion (F441 / F441M matrix & amplifiers, status probe *#16*0*5##), whereas F461 and MyHomeServer1 (bt_multi on emulated firmware 028206) route NuVo / WHO = 22 sound only.
2. Firmware Oracle (*#16*0*5##):
   • Refused (NACK *#*0## / SILENT bus drop): F461 (020011, SHA 1ecabc82832a) and MyHomeServer1 (028206, SHA 5d511f9f848f).
   • Accepted (ACK *#*1## / OUT 24 30 34 42 35 30 30 38 30 38 46 0d): F453 (020025), F453AV (010220), F454 (020055), H4684 (060024), MH200 (010019), and MH200N (020112).

---

Checklist

• PR Description: Follows the structured sections above (What is the problem, What is the solution, State Diagram, How is it tested, Where are the traces, What does the Firmware Oracle / Encyclopedia say).
• Trace-Backed (if protocol/device change): Behavior is verified against real OpenWebNet bus traces or gateway firmware fixtures rather than guessed.
• V2 Architecture: New or modified entities implement handle_event() and do not manually subscribe via async_dispatcher_connect.
• Tests & Linters: pytest, ruff, and scripts/verify_ha_standards.py pass.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!