feat(OMN-2084): Add CI handshake enforcement workflow

[jonahgabriel]

Summary

• Add check-handshake.yml CI workflow that verifies the installed architecture handshake matches the omnibase_core source
• Refresh stale handshake to match omnibase_core v0.16.0 (source SHA had drifted since 2026-02-03 install)

Details

Follows the exact pattern from omnibase_spi/.github/workflows/check-handshake.yml:

• Triggers on push/PR to main/develop when handshake or workflow file changes
• Checks out omnibase_core at a pinned SHA (4dc7a0a — current main)
• Runs check-handshake.sh which compares the installed source_sha256 metadata against the current source file hash
• Fails CI if handshake has drifted from omnibase_core source

Test plan

• Local check-handshake.sh verification passes with refreshed handshake
• YAML syntax validated
• Unit tests pass (3 pre-existing flaky benchmark failures, unrelated)
• Verify CI workflow runs on this PR (triggers on .claude/architecture-handshake.md path change)
• Verify workflow_dispatch manual trigger works

Closes OMN-2084

Summary by CodeRabbit

• Documentation

  • Published architecture decision clarifying Kafka as required infrastructure with updated resilience patterns.
  • Updated operational guidance with revised Kafka configuration and failure handling requirements.

• Chores

  • Updated platform-wide architectural guidelines and development practices.
  • Added automated validation workflow to verify architecture consistency.

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request establishes Kafka as required infrastructure across the platform by updating the architecture handshake with platform-wide rules, introducing an architecture validation workflow, documenting the decision via ADR, and adjusting error handling semantics in event bus components to treat Kafka failures as fatal rather than gracefully degradable.

Changes

Cohort / File(s)	Summary
Architecture Foundation .claude/architecture-handshake.md, .github/workflows/check-handshake.yml	Updated handshake metadata, added nine Platform-Wide Rules governing architecture practices (including Kafka as required infrastructure), removed "Never block on Kafka" rule, established automated validation workflow with cross-repository dependency checking against omnibase_core.
Decision & Operations Documentation docs/decisions/adr-kafka-required-infrastructure.md, docs/operations/EVENT_BUS_OPERATIONS_RUNBOOK.md	Introduced ADR documenting Kafka as required infrastructure with fatal startup failure semantics; updated runbook to reflect resilience against transient failures rather than graceful degradation, with enhanced guidance on production configuration.
Event Bus Implementation src/omnibase_infra/event_bus/event_bus_kafka.py, src/omnibase_infra/runtime/providers/provider_kafka_producer.py	Updated docstrings and exception documentation to reflect Kafka as required infrastructure with fatal failure semantics on connection failures; no public API signatures modified, changes confined to behavioral specification and error handling semantics.

Poem

🐰 Platform-wide rules now carved in stone,
Kafka's required, no graceful fallback shown!
From handshakes checked to startup flows so tight,
Required infrastructure shines bright!
💚 Our burrows run stronger, built right.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title focuses on adding a CI handshake enforcement workflow, which is the primary change in the changeset. However, the PR also includes substantial updates to the architecture handshake metadata, Kafka infrastructure policy changes, and related documentation—making the title partially but not fully representative of the main scope.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch jonah/omn-2084-omnibase_infra-add-ci-handshake-enforcement

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/decisions/adr-kafka-required-infrastructure.md`:
- Around line 37-38: Update the ADR to remove the conflicting guidance by
eliminating the statement that "localhost:9092 defaults in config models remain
as development conveniences" and instead state that no service defaults may be
localhost per rule `#7` (no hardcoded configuration); locate and edit the
paragraph referencing "localhost:9092" and replace it with guidance that configs
must require explicit environment-specific bootstrap servers or use a
clearly-scoped development-only profile (named e.g., "dev" and not a default),
and update any dependent docs or config model examples to either omit a default
or mark the value as required to satisfy rule `#7`.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Reconcile localhost-default guidance with rule #7.

This says localhost defaults remain for development, but the architecture-handshake rule #7 now states “No localhost defaults.” Please align the ADR (and any dependent docs) with the intended rule to avoid conflicting guidance.

🤖 Prompt for AI Agents

In `@docs/decisions/adr-kafka-required-infrastructure.md` around lines 37 - 38,
Update the ADR to remove the conflicting guidance by eliminating the statement
that "localhost:9092 defaults in config models remain as development
conveniences" and instead state that no service defaults may be localhost per
rule `#7` (no hardcoded configuration); locate and edit the paragraph referencing
"localhost:9092" and replace it with guidance that configs must require explicit
environment-specific bootstrap servers or use a clearly-scoped development-only
profile (named e.g., "dev" and not a default), and update any dependent docs or
config model examples to either omit a default or mark the value as required to
satisfy rule `#7`.