[GreenGrassBlueOcean]

Follow-up to #101 addressing review feedback from @fedem95 (#101 review):

Problem

1. --check did not call verify_who_catalog_coverage():
   The WHO catalog table is constructed strictly from WHO_DEFINITIONS. If a new WHO subsystem was registered in the codebase dispatchers but omitted from WHO_DEFINITIONS, sync_documentation.py --check exited 0 without detecting the gap. Only pytest tests/test_sync_documentation.py would catch it.
2. verify_who_catalog_coverage() only inspected _COMMAND_DISPATCH:
   Subsystems that only register event decoders were completely ignored by coverage verification.
3. Event-only WHOs had no dedicated catalog rows:
   • WHO 0 (OWNScenarioEvent) had no entry of its own and was lumped under WHO 15 (explicit_classes=("OWNScenarioEvent",)).
   • WHO 9 (OWNAuxEvent) had no row in the README catalog table at all.

Solution

1. Incorporate coverage checks into sync_documentation and --check:
   • sync_documentation() now calls verify_who_catalog_coverage().
   • Any unmapped WHO subsystems are flagged as WHO catalog gap: ... in the execution messages and prevent is_in_sync from returning true.
   • --check exits 1 with actionable guidance when catalog gaps exist.
   • main() and sync_documentation() refuse in-place disk writes to README.md and coverage.svg if unmapped WHO subsystems exist, preventing partial inconsistent updates.
2. Cover both commands and events in verify_who_catalog_coverage():
   • Inspects both _COMMAND_DISPATCH and _EVENT_DISPATCH.
   • Diagnostically reports whether the unmapped WHO is registered in _COMMAND_DISPATCH, _EVENT_DISPATCH, or both.
   • WHO 25 declares dispatch_who_keys=(25,) on its definition (its underscore-prefixed parser functions are skipped during automatic resolution in favor of explicit_classes), eliminating the hardcoded exception in verify_who_catalog_coverage().
3. Dedicated definitions for WHO 0 and WHO 9:
   • Added WHO 0 (Scenarios): OWNScenarioEvent.
   • Added WHO 9 (Auxiliary): OWNAuxEvent.
   • Cleaned up WHO 15 (CEN Scenarios): removed explicit_classes=("OWNScenarioEvent",) so it cleanly maps OWNCenCommand and OWNCENEvent.
   • Synchronized README.md catalog table with the new rows.
4. Tests:
   • Extended test_build_who_catalog_table() to assert presence of WHO 0, WHO 9, and the cleaned-up WHO 15.
   • Added isolated tests in test_who_catalog_dispatch_coverage_detects_unmapped_registries() for command-only, event-only, and dual dispatch gap detection.
   • Added test_sync_documentation_fails_on_catalog_gap_and_refuses_write() verifying that unmapped subsystems cause --check and update mode to exit 1 and refuse modifying drifted files.

Verification

Command	Result
ruff check OWNd tests setup.py scripts	clean
mypy OWNd tests/typing	0 issues (26 files)
python scripts/verify_library_standards.py	pass
python scripts/sync_documentation.py --check	in sync, exit 0
pytest tests/	1,305 passed

[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!

[fedem95]

Approving, this covers both points from #101. Merged locally into current master: --check exits 0 and the suite passes (1302). With #100 merged on top as a test, --check now exits 1 with "WHO catalog gap: WHO 6 / WHO 8 registered in _COMMAND_DISPATCH and _EVENT_DISPATCH but not mapped in WHO_DEFINITIONS", and update mode exits 1 without touching README.md (compared before/after). CI green.

Small wording notes on the new rows:

• WHO 0 says "Basic scenario execution (1–32)"; OWNScenarioEvent.event's docstring says WHAT 1–31, and WHO_0.pdf gives up to 16 scenarios on the F420 and 20 on the IR 3456.
• WHO 9 says "aux 1–9"; OWNAuxEvent doesn't restrict the channel, and I couldn't find a public WHO 9 document to check it against.