feat(relay): shared event-write primitive + bmad-loop relay <Event>

[pbean]

What

Factor the relay event-write logic — already duplicated between data/bmad_loop_hook.py and PR #226's hermes_hooks.relay_event (identical env-gating, casing-tolerant field extraction, atomic events/<ts>-<task>-<event>.json write) — into one core primitive that owns the event schema, and add a general bmad-loop relay <Event> command over it.

This is the general, in-tree counterpart to bmad_loop_hook.py for global/user-scoped-hook adapters — NOT Hermes-specific. An out-of-tree adapter whose CLI registers a single user-scoped hook (rather than copying the per-project script) points that hook at bmad-loop relay Stop and needs zero per-adapter relay code.

Changes

• New src/bmad_loop/events.py — write_relay_event(event_name, payload, environ) -> Path | None (+ build_event). Owns the canonical schema (ts, event, task_id, session_id, transcript_path, cwd) and the env-gated (BMAD_LOOP_RUN_DIR + BMAD_LOOP_TASK_ID), atomic write. No-ops outside an active bmad-loop session.
• bmad-loop relay <Event> in cli.py — reads the hook payload from stdin and defers to the primitive. event choices come from CANONICAL_EVENTS (never a hardcoded set).
• data/bmad_loop_hook.py — behavior unchanged. It keeps its own inlined copy on purpose: it is installed into target projects as a lone, stdlib-only file and run as a bare subprocess where the bmad_loop package need not be importable, so it cannot import the primitive. Added a docstring note documenting the deliberate duplication and the sync guard.

Tests (tests/test_relay_event.py)

• primitive: active-env write, no-env / partial-env no-op, camelCase + workspacePaths fallbacks, unusable-workspacePaths degrades to None
• CLI stdin path, no-env no-op, garbage-stdin tolerance, non-canonical event rejected (parse error), every canonical event accepted
• schema parity: the standalone script (run as a real subprocess) and the primitive emit byte-identical events across every payload dialect — pins the inlined copy to the primitive so they cannot drift
• existing tests/test_hook_script.py behavior unchanged (incl. test_installed_copy_matches_source)

Verification

• Full pytest green in both TMUX states (TMUX-unset and inside a real tmux session): 2717 passed, 7 skipped. The one failure (test_tui_app.py::test_validate_findings_multiline_message_keeps_column_alignment) is pre-existing and unrelated — an environment-sensitive TUI rendering-width test that fails identically on untouched main.
• Full trunk check — no issues.

Context

Session 2 of the PR #226 review plan (make the coding-CLI adapter axis extensible out-of-tree). Independent of the other sessions. The out-of-tree Hermes package (a later session) is where hermes_hooks.relay_event gets deleted in favor of pointing its hook at this command.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9bcb717e-c331-4513-8e94-b20c4bab156f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/generic-relay

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}