v0.5.0 polish + validation sprint

[yaniswav]

Closes the v0.5.0 polish-and-validation sprint — the last sprint before marketing publication. See CHANGELOG.md [Unreleased] for the full per-sub-milestone breakdown.

Summary

No new MCP tool, no schema change, no env-var rename. Three sub-milestones :

• 5.1 Real validation — CI matrix expanded to {ubuntu-latest, windows-latest} × {3.11, 3.12, 3.13} (6 cells, fail-fast: false). Python 3.13 classifier added.
• 5.2 Audit closure + AdapterError polish — 9 polished error sites with regex-token regression tests, services/inspector.py:76 TODO retired as WONT-FIX, audit-followup-triage-v0.2.0.md fully re-walked (B6 / B9 / B10 CLOSED, B1-B5 / B7 / B8 DEFER).
• 5.3 Docs + examples + repo polish — README cascade, DDS_QUICKSTART §4-§7 rewrites, TESTING tool-count refresh, new MIGRATION_v0.3_to_v0.4.md / TROUBLESHOOTING.md / examples/ (4 walkthroughs), repo polish files (CONTRIBUTING.md, SECURITY.md, ISSUE_TEMPLATEs, PR_TEMPLATE).

Test plan

• python -m pytest -q → 399 passed, 24 skipped (was 394 baseline + 5 new tests)
• python -m ruff check src tests → clean
• python -m ruff format --check src tests → clean
• CI matrix 6 cells green (validated by this PR's checks)
• Docker rig manual build — defer to maintainer post-merge (Docker Desktop not running at sprint time)

Backward-compatibility checklist

• No new MCP tool added (cap stays at 11)
• No Pydantic schema change (all 11 tools' response models byte-for-byte unchanged)
• No change to telemetry 6-field contract (pinned by tests/test_telemetry.py)
• No new environment variable name
• No removal of existing public API symbol
• DDS_ONLY_ERROR_MSG substring tokens preserved ("DDS observability only", "TOPICFORGE_DDS_BACKEND", "TOPICFORGE_MODE") — existing pytest.raises(match=...) contracts honored

Notes for the maintainer

• The CHANGELOG [Unreleased] section is fully populated. The version bump + v0.5.0 tag are deliberate manual steps after final review (same pattern as v0.4.0).
• CODE_OF_CONDUCT.md intentionally skipped this sprint — pointer-only via CONTRIBUTING.md if you want the Contributor Covenant link added later.
• The Cyclone XTypes pipeline still awaits real-bus validation ; the v0.4.0 Phase 1.5 structural plumbing is in place but a real domain test from a maintainer is the gating factor for advertising _decode_status="full" outside the README hedge wording.

[Copilot]

Pull request overview

This PR wraps up the v0.5.0 “polish + validation” sprint by strengthening CI validation, tightening end-user diagnostics (AdapterError messages), and expanding repo documentation/templates/examples ahead of marketing publication.

Changes:

• Expand CI to a 6-cell OS/Python matrix (Ubuntu/Windows × 3.11/3.12/3.13) and add Python 3.13 classifier metadata.
• Polish multiple AdapterError sites (DDS-only remediation, Cyclone/Fast DDS diagnostics, BagService error surfacing) and add regression tests that pin key substrings/tokens.
• Add/refresh “repo polish” docs (SECURITY/CONTRIBUTING/TROUBLESHOOTING/MIGRATION), plus a new examples/ walkthrough set and GitHub templates.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/test_dds_helpers.py	Adds substring/token regression tests for DDS_ONLY_ERROR_MSG.
tests/test_bag_service.py	Adds tests asserting BagService errors surface exception type + message.
src/topicforge/services/inspector.py	Replaces TODO with a permanent design note for list_topics validation asymmetry.
src/topicforge/services/bag_service.py	Improves rosbags-required guidance and includes exception type in AdapterError messages.
src/topicforge/adapters/dds_fast/adapter.py	Enhances Fast DDS participant init failure diagnostics.
src/topicforge/adapters/dds_cyclone/adapter.py	Enhances Cyclone DDS discovery/peek errors with domain/topic context and exception type.
src/topicforge/adapters/common/dds_helpers.py	Rewrites DDS_ONLY_ERROR_MSG with explicit CompositeAdapter remediation + affected tool list.
SECURITY.md	Adds a security policy and threat model documentation.
README.md	Updates badges, positioning, tool tables, and configuration docs to reflect v0.4.0 surface.
pyproject.toml	Adds Python 3.13 classifier.
examples/README.md	Introduces runnable mock-mode example index and how-to.
examples/01-discover-ros2-stack.md	Adds an end-to-end mock walkthrough for ROS2 graph discovery.
examples/02-debug-qos-mismatch.md	Adds a mock walkthrough for DDS QoS mismatch diagnosis.
examples/03-analyze-recording.md	Adds a mock walkthrough for bag analysis + bag sample peek.
examples/04-monitor-topic-frequency.md	Adds a mock walkthrough for topic metrics + participant lifecycle events.
docs/TROUBLESHOOTING.md	Adds a troubleshooting guide keyed off polished AdapterError messages.
docs/TESTING.md	Updates testing guide from 5 tools to 11 tools and adds a tool-surface callout.
docs/projet-file/audit-followup-triage-v0.2.0.md	Refreshes audit triage status through v0.5.0 decisions.
docs/MIGRATION_v0.3_to_v0.4.md	Adds migration guide documenting v0.4.0 tool/env/schema expansions.
docs/DDS_QUICKSTART.md	Updates quickstart to CompositeAdapter + _decode_status story.
CONTRIBUTING.md	Adds contribution guidelines and development/testing contract.
CHANGELOG.md	Populates [Unreleased] with the v0.5.0 sprint breakdown.
.github/workflows/ci.yml	Expands CI matrix to include Windows and Python 3.13.
.github/PULL_REQUEST_TEMPLATE.md	Adds a structured PR template with compatibility checklist.
.github/ISSUE_TEMPLATE/feature_request.yml	Adds a feature request issue form with scope/tier prompts.
.github/ISSUE_TEMPLATE/config.yml	Disables blank issues and adds support links.
.github/ISSUE_TEMPLATE/bug_report.yml	Adds a bug report issue form with structured repro fields.

Comments suppressed due to low confidence (1)

tests/test_bag_service.py:128

• Same issue as above: tmp_path is a pathlib.Path fixture, not a pytest.TempPathFactory, and the current type annotation forces an unnecessary type: ignore when using / path joining. Use Path (or switch to tmp_path_factory if needed).

def test_bag_service_peek_surfaces_exception_type_in_error(
    monkeypatch: pytest.MonkeyPatch, tmp_path: pytest.TempPathFactory
) -> None:

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.