feat: Bus coverage + media testing

.github/workflows/build-tests.yml

@@ -0,0 +1,15 @@
+name: Build Tests
+
+on:
+  pull_request:
+    branches: [dev, master, main]
+  workflow_dispatch:
+
+jobs:
+  build:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/build-tests.yml@dev
+    secrets: inherit
+    with:
+      python_versions: '["3.10", "3.11", "3.12", "3.13", "3.14"]'
+      install_extras: 'audio,pydantic'
+      test_path: 'test/unittests/'

.github/workflows/conventional-label.yaml → .github/workflows/conventional-label.yml

@@ -7,4 +7,4 @@ jobs:
   label:
     runs-on: ubuntu-latest
     steps:
-      - uses: bcoe/conventional-release-labels@v1
+      - uses: bcoe/conventional-release-labels@v1

.github/workflows/unit_tests.yml → .github/workflows/coverage-pages.yml

@@ -1,20 +1,20 @@
-name: Run Tests
+name: Coverage Pages
 on:
-  pull_request:
+  push:
     branches:
       - dev
   workflow_dispatch:
 
 permissions:
-  pull-requests: write
-  contents: read
+  contents: write
 
 jobs:
-  unit_tests:
+  coverage_pages:
     uses: OpenVoiceOS/gh-automations/.github/workflows/coverage.yml@dev
     secrets: inherit
     with:
       python_version: "3.12"
-      install_extras: "audio"
       test_path: "test/unittests/"
       coverage_source: "ovoscope"
+      install_extras: "audio,pydantic"
+      deploy_pages: true

.github/workflows/coverage.yml

@@ -0,0 +1,16 @@
+name: Code Coverage
+
+on:
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+jobs:
+  coverage:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/coverage.yml@dev
+    secrets: inherit
+    with:
+      python_version: '3.11'
+      coverage_source: 'ovoscope'
+      test_path: 'test/unittests/'
+      min_coverage: 0

.github/workflows/lint.yml

@@ -0,0 +1,14 @@
+name: Lint
+
+on:
+  pull_request:
+    branches: [dev, master, main]
+  workflow_dispatch:
+
+jobs:
+  lint:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/lint.yml@dev
+    secrets: inherit
+    with:
+      ruff: true
+      pre_commit: false   # set true if .pre-commit-config.yaml exists

.github/workflows/release_preview.yml → .github/workflows/release-preview.yml

@@ -1,4 +1,5 @@
 name: Release Preview
+
 on:
   pull_request:
     branches: [dev]
@@ -9,5 +10,5 @@ jobs:
     uses: OpenVoiceOS/gh-automations/.github/workflows/release-preview.yml@dev
     secrets: inherit
     with:
-      package_name: "ovoscope"
-      version_file: "ovoscope/version.py"
+      package_name: 'ovoscope'
+      version_file: 'ovoscope/version.py'

.github/workflows/repo_health.yml → .github/workflows/repo-health.yml

@@ -1,10 +1,13 @@
 name: Repo Health
+
 on:
   pull_request:
-    branches: [dev]
+    branches: [dev, master, main]
   workflow_dispatch:
 
 jobs:
   repo_health:
     uses: OpenVoiceOS/gh-automations/.github/workflows/repo-health.yml@dev
     secrets: inherit
+    with:
+      version_file: 'ovoscope/version.py'

AUDIT.md

@@ -56,3 +56,129 @@ builds non-reproducible if the upstream action changes.
 ## Next Steps (Priority Order)
 1. Address CaptureSession.capture() return value — usability
 2. Pin CI action refs — reproducibility
+
+---
+
+## Audit [2026-03-12] — Correctness Bugs, Coverage Gaps, Docs
+
+### ~~[CRITICAL] `pipeline.py` race condition in `match()`~~ ✅ FIXED
+
+**Evidence**: `ovoscope/pipeline.py:159–181` — a single `threading.Event` was
+shared for both success (`intent.service.skills.activated`) and failure
+(`intent_failure`, `mycroft.skill.handler.start`) handlers.  If `intent_failure`
+fired first, `captured[0]` would be a failure message returned as success.
+Additionally, `done.wait()` return value was not checked; a timeout silently
+returned `captured[0]` (or raised `IndexError` on empty list).
+
+**Fix**: Separate `_matched` and `_failed` events; only the success handler
+populates `captured`.  Timeout and failure both return `None`.
+Source: `ovoscope/pipeline.py:149`.
+
+### ~~[MAJOR] `diff.py` — subset comparison silently ignores extra keys~~ ✅ FIXED
+
+**Evidence**: `ovoscope/diff.py:121–138` — `_dict_diff()` only iterated keys
+in `expected`, so unexpected keys in `actual` were never flagged.
+
+**Fix**: Added `strict: bool = False` parameter to `_dict_diff()` and
+`diff_fixtures()`.  When `strict=True`, extra keys in `actual` are included in
+the diff detail.  Default `False` preserves existing behaviour.
+Source: `ovoscope/diff.py:121`.
+
+### ~~[MINOR] `bus_coverage.py` — dead method `_skill_id_for_handler()`~~ ✅ FIXED
+
+**Evidence**: `ovoscope/bus_coverage.py:745–763` — `_skill_id_for_handler()`
+was never called anywhere in the codebase (verified by grep).  Its logic is
+a subset of `_skill_id_for_closure()` which is the method actually used.
+
+**Fix**: Method deleted.
+Source: formerly `ovoscope/bus_coverage.py:745`.
+
+### ~~[MAJOR] No unit tests for `media.py` (`MockOCPBackend`, `OCPCaptureSession`, `OCPPlayerHarness`)~~ ✅ FIXED
+
+**Evidence**: `ovoscope/media.py` had no corresponding test file.
+
+**Fix**: Created `test/unittests/test_media.py` — 20 tests covering
+`MockOCPBackend` state transitions, `OCPCaptureSession` message accumulation,
+and assertion helpers.
+
+### ~~[MAJOR] No unit tests for `remote_recorder.py`~~ ✅ FIXED
+
+**Evidence**: `ovoscope/remote_recorder.py` had no corresponding test file.
+
+**Fix**: Created `test/unittests/test_remote_recorder.py` — 15 tests covering
+constructor defaults, `_parse_url`, connect/disconnect lifecycle, `record()` with
+mocked bus client, timeout handling, and fixture serialization.
+
+### ~~[MINOR] Deprecated `ovos_utils.messagebus.Message` import in `test_phal.py`~~ ✅ FIXED
+
+**Evidence**: `test/unittests/test_phal.py:23` — imported `Message` from
+deprecated `ovos_utils.messagebus` instead of canonical `ovos_bus_client.message`.
+
+**Fix**: Import changed to `from ovos_bus_client.message import Message`.
+Source: `test/unittests/test_phal.py:23`.
+
+### ~~[MINOR] `SUGGESTIONS.md` missing~~ ✅ FIXED
+
+**Evidence**: `SUGGESTIONS.md` was absent despite being required by `AGENTS.md`.
+
+**Fix**: `SUGGESTIONS.md` created with 10 structured proposals.
+
+---
+## Bus Coverage Module — Full Audit [2026-03-12]
+
+### ~~[CRITICAL] async_responses excluded from emitter coverage~~ ✅ FIXED
+`execute()` now passes `messages + list(capture.async_responses)` to `record_session()`. Source: `ovoscope/__init__.py:666`.
+
+### ~~[CRITICAL] Unattributed expected_messages silently disappear~~ ✅ FIXED
+Both observed and expected messages with no `skill_id` in context now fall back to the `"__core__"` sentinel bucket. Source: `BusCoverageTracker.record_session` — `ovoscope/bus_coverage.py:510`.
+
+### [CRITICAL] Registration-time handlers always show NOT TESTED — misleading
+**Evidence**: `ovoscope/bus_coverage.py:368` / `ovoscope/__init__.py:647` — `snapshot_listeners()` is called after `MiniCroft` reaches READY. Handlers invoked *during* skill loading were called *before* the snapshot and will always show 0 invocations.
+**Impact**: Users see `register_intent: NOT TESTED` and conclude their intent registration failed.
+**Status**: Documented in `docs/bus-coverage.md` Limitations as a known structural constraint. A `LOAD_TIME` tag or pre-READY tracking remains a future enhancement.
+
+### ~~[CRITICAL] Non-skill messages silently excluded from emitter coverage~~ ✅ FIXED
+Messages with no `skill_id` in context are now attributed to the `"__core__"` bucket in `record_session()`. Source: `ovoscope/bus_coverage.py:510`.
+
+### ~~[MAJOR] Unused `skill_map` variable in `record_session()`~~ ✅ FIXED
+Dead `skill_map = self._skill_instance_map()` call removed from `record_session()`.
+
+### ~~[MAJOR] `_get_bus_events()` called three times in `snapshot_listeners()`~~ ✅ FIXED
+`bus_events = self._get_bus_events()` is now called once and reused across all three passes. Source: `ovoscope/bus_coverage.py:432`.
+
+### ~~[MAJOR] Double-stop risk in `cmd_bus_coverage()`~~ ✅ FIXED
+`test.managed = False` is now set explicitly before `test.execute()`. The `finally` block is the sole owner of `mc.stop()`. The redundant `mc.stop()` in the `except Exception` branch was also removed. Source: `ovoscope/cli.py:349`.
+
+### ~~[MAJOR] `pytest_terminal_summary` hook uses private pytest internals~~ ✅ FIXED
+`bus_coverage_session` fixture now stores merged reports on `request.config._bus_coverage_reports` in its teardown. `pytest_terminal_summary` reads that list — no private attrs. Source: `ovoscope/pytest_plugin.py:191`.
+
+### [MAJOR] `once()` handlers invisible after firing
+**Evidence**: `bus_coverage.py:368` — one-shot handlers fired during skill loading are de-registered before the snapshot.
+**Status**: Documented in `docs/bus-coverage.md` Limitations. Pre-READY tracking is a future enhancement.
+
+### [MAJOR] `ignore_messages` list silently excludes messages from emitter coverage
+**Evidence**: `ovoscope/__init__.py:504-505` — messages in `ignore_messages` never reach `responses`.
+**Status**: Documented in `docs/bus-coverage.md` Limitations. Passing ignored messages as a separate bucket is a future enhancement.
+
+### ~~[MAJOR] No JSON schema version field~~ ✅ FIXED
+`to_json()` now includes `"schema_version": "1"` as the first key. Source: `ovoscope/bus_coverage.py:297`.
+
+### ~~[MINOR] Column widths hardcoded in `print_report()`~~ ✅ FIXED
+`col_w = max(len(s.skill_id) for s in self.skills) + 2` now drives column width dynamically. Source: `ovoscope/bus_coverage.py:237`.
+
+### ~~[MINOR] Coverage summary printed before test assertions~~ ✅ FIXED
+`print_bus_coverage` block moved to after all assertions, just before `managed` teardown. Source: `ovoscope/__init__.py:795`.
+
+### ~~[MINOR] `bus_coverage_report` type hint uses `Optional[Any]`~~ ✅ FIXED
+Type hint changed to `Optional["BusCoverageReport"]`. Source: `ovoscope/__init__.py:589`.
+
+### ~~[NITPICK] `_SKIP` set has fragile `"type"` entry~~ ✅ FIXED
+Pass 2 now uses `isinstance(owner, type)` check to skip class objects, and the `"type"` string entry removed from `_SKIP`. Source: `ovoscope/bus_coverage.py:450`.
+
+### ~~Docs gaps (bus-coverage.md)~~ ✅ FIXED
+All five missing Limitations items added to `docs/bus-coverage.md`:
+- Registration-time handlers always show NOT TESTED
+- Pipeline matching is not bus-driven
+- `async_responses` now included (fix note)
+- `ignore_messages` types excluded
+- Core services use `__core__` bucket (not 0/0 — fix note)

FAQ.md

@@ -1,4 +1,46 @@
 # FAQ — `ovoscope`
+## How do I measure which bus message handlers my tests actually exercise?
+
+Use bus coverage: set `track_bus_coverage=True` on `End2EndTest`.  After
+`execute()`, `test.bus_coverage_report` contains a `BusCoverageReport` with
+per-skill listener coverage (which `bus.on()` registrations were triggered)
+and emitter coverage (which message types were observed / asserted).
+
+```python
+test = End2EndTest(
+    skill_ids=["my-skill.author"],
+    source_message=message,
+    expected_messages=[...],
+    track_bus_coverage=True,
+    print_bus_coverage=True,   # print inline summary
+)
+test.execute()
+print(test.bus_coverage_report.to_json())
+```
+
+See [docs/bus-coverage.md](docs/bus-coverage.md) for the full reference.
+`BusCoverageTracker` — `ovoscope/bus_coverage.py:242`.
+
+## How do I get an aggregate bus coverage report across an entire test suite?
+
+Use the `bus_coverage_session` pytest fixture.  Each test calls
+`bus_coverage_session.add(test.bus_coverage_report)` after `execute()`.  A
+merged table is printed automatically at session end.  See
+[docs/bus-coverage.md](docs/bus-coverage.md).
+
+## How do I run bus coverage from the command line without writing pytest tests?
+
+Use the `ovoscope bus-coverage` subcommand:
+
+```bash
+ovoscope bus-coverage path/to/fixtures/       # table report
+ovoscope bus-coverage path/to/fixtures/ --format json
+ovoscope bus-coverage path/to/fixtures/ --verbose   # per-msg detail
+```
+
+`cmd_bus_coverage` — `ovoscope/cli.py`.
+
+
 ## How do I test AudioService or PlaybackService without real audio hardware?
 Use `AudioServiceHarness` or `PlaybackServiceHarness` from `ovoscope.audio`. Both run on a
 `FakeBus` with `MockAudioBackend`/`MockTTS` respectively — no real audio device, TTS engine,
@@ -356,6 +398,15 @@ with GUICaptureSession(mc.bus) as gui:
     gui.assert_page_shown("my_skill", "main.qml")
 ```
 
+### How do I assert that a skill set a specific session data key in a namespace?
+Use `assert_namespace_has_key()`:
+```python
+with GUICaptureSession(mc.bus) as gui:
+    # ... trigger interaction ...
+    gui.assert_namespace_has_key("my_skill", "temperature")
+```
+This checks that a `mycroft.session.set` message was captured containing the given key in the specified namespace. See [docs/gui-testing.md](docs/gui-testing.md).
+
 ---
 
 ## Coverage Scanner