feat(OMN-11271): enforce ## Infra Health section in handoff docs

[jonahgabriel]

Evidence-Ticket: OMN-11271
Evidence-Source: 101a7bb8a36b991061893b376c9759bea7301ab1

Summary

• Adds `.pre-commit-hooks/check-handoff-infra-health.sh` — hard-fails on handoff documents (`docs/handoffs/*.md`, `docs/handoff.md`, `docs/tracking/handoff.md`) missing the mandatory `## Infra Health` section
• Adds `.github/workflows/handoff-infra-health-gate.yml` — reusable GHA workflow with required status check `gate / Handoff Infra Health` that applies the same grep logic on PR-changed files
• Wires the hook into `.pre-commit-config.yaml` at pre-commit stage
• 6 unit tests covering accept/reject/ignore paths

Both layers block unconditionally — no warn-only mode per CLAUDE.md Rule #5 (enforcement, not detection) and Rule #10 (no informational gates).

Ticket

OMN-11271 — Handoff CI enforcement: pre-commit + CI check that handoff docs include infra health section

dod_evidence

• type: pre_commit_hook_added
  artifact: .pre-commit-hooks/check-handoff-infra-health.sh
  description: Hard-fail hook wired in .pre-commit-config.yaml, 6 passing unit tests

• type: gha_workflow_added
  artifact: .github/workflows/handoff-infra-health-gate.yml
  description: Reusable workflow with required status check gate / Handoff Infra Health

Test plan

• Merge a test handoff PR without ## Infra Health — CI blocks it
• Add ## Infra Health — CI passes
• uv run pytest tests/hooks/test_check_handoff_infra_health.py -v — 6 tests pass

Summary by CodeRabbit

• Chores
  • Implemented automated validation to ensure handoff documentation includes required infrastructure health information
  • Updated pull request validation workflow triggers to specific event types

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces validation enforcement requiring handoff markdown documents to include a mandatory ## Infra Health section. A pre-commit hook script checks files locally; a reusable GitHub Actions workflow performs the same check in CI; the reviewdog-caller workflow is updated to remove merge group triggers; and comprehensive test fixtures validate the enforcement behavior across valid, invalid, and non-handoff document scenarios.

Changes

Infra Health Section Enforcement

Layer / File(s)	Summary
Pre-commit hook script and configuration \.pre-commit-hooks/check-handoff-infra-health.sh, \.pre-commit-config.yaml	The shell script reads markdown files from git staging area or filesystem, verifies each handoff document contains ^## Infra Health via regex, and exits non-zero on violations. The hook is configured in pre-commit-config.yaml to run at the pre-commit stage on all markdown files.
GitHub Actions workflow and configuration updates \.github/workflows/handoff-infra-health-gate.yml, \.github/workflows/reviewdog-caller.yml	A new reusable workflow handoff-infra-health-gate runs on workflow_call and PR events, filters to handoff markdown files under docs/, performs the infra health check via bash, and emits GitHub error annotations with ticket references when violations occur. The reviewdog-caller workflow removes the merge_group trigger, restricting it to pull request events.
Test fixtures and validation suite tests/hooks/fixtures/handoff_infra_health/*\.md, tests/hooks/test_check_handoff_infra_health.py	Three markdown fixtures cover the validation scope: a handoff document missing the section, one with it, and a non-handoff document. The pytest test suite verifies the hook rejects handoff docs lacking ## Infra Health, accepts those with it, handles docs/tracking/* variants, and ignores non-handoff markdown and non-markdown files.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• OmniNode-ai/omniclaude#1582: Removes the merge_group trigger from .github/workflows/reviewdog-caller.yml in a related configuration update affecting the same workflow file.

Poem

🐰 A hook that hops through handoff files with care,
Ensuring health is documented everywhere,
From pre-commit to CI gates so bright,
The infra checks now always get it right! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: enforcing the Infra Health section requirement in handoff documentation files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jonah/omn-11271-handoff-ci-enforcement

---

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

[github-actions]

⚠️ Hostile Reviewer — DEGRADED (informational)

Blocking findings (critical/error): 0
Total findings: 0
Models succeeded: none

Note: All reviewer models failed or were unavailable. Degraded results are informational during the pilot phase (OMN-8524) and do not block merge. Error: cli_review exited non-zero (all models failed or binary error)

---

Gate semantics (pilot phase)

Verdict	Meaning	Blocks merge?
passed	No critical/error findings	No
blocked	CRITICAL or ERROR findings found	Yes
degraded	All models unavailable (infra)	No (pilot)

Powered by omniintelligence.review_pairing.cli_review — node-based adversarial review via HandlerLlmCliSubprocess (OMN-8524)

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/handoff-infra-health-gate.yml:
- Around line 59-60: The fallback that sets CHANGED_FILES using "git diff
--name-only HEAD~1...HEAD" is insufficient; replace it with a robust strategy
that computes the PR base/head SHAs and diffs across the full PR (e.g., fetch
origin ${BASE_REF}, compute MERGE_BASE via git merge-base origin/${BASE_REF}
${GITHUB_SHA} or use provided GITHUB_BASE_SHA/GITHUB_HEAD_SHA) and then run "git
diff --name-only <merge-base>...<head>" so CHANGED_FILES always reflects all PR
changes instead of only the last commit.
- Around line 42-45: Update the "Checkout code" GitHub Actions step that
currently uses actions/checkout@v6 to pin to the full 40-character commit SHA
for the desired release (replace the tag with something like
actions/checkout@<FULL_COMMIT_SHA>) and add the setting persist-credentials:
false under the step's with: block (in addition to existing fetch-depth: 0) to
disable credential persistence and reduce supply-chain risk.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e1bd665f-6784-40a1-8bdd-0ae7b1815bfc

📥 Commits

Reviewing files that changed from the base of the PR and between 3e4ed0c and 45b931b.

📒 Files selected for processing (8)

• .github/workflows/handoff-infra-health-gate.yml
• .github/workflows/reviewdog-caller.yml
• .pre-commit-config.yaml
• .pre-commit-hooks/check-handoff-infra-health.sh
• tests/hooks/fixtures/handoff_infra_health/invalid_missing_section.md
• tests/hooks/fixtures/handoff_infra_health/non_handoff_doc.md
• tests/hooks/fixtures/handoff_infra_health/valid_with_section.md
• tests/hooks/test_check_handoff_infra_health.py

💤 Files with no reviewable changes (1)

• .github/workflows/reviewdog-caller.yml