docs(OMN-14587): fan out canon-shape ratchet baseline to omnibase_infra

[jonahgabriel]

Evidence-Source: OCC#4143
Evidence-Ticket: OMN-14587

Summary

Generates and commits scripts/ci/canonical_handler_shape_baseline.py for
omnibase_infra by running omnibase_core's canon-shape classifier
(OMN-14355/14368) against this repo's node tree via the existing
--package/--src-root/--baseline fan-out flags — the exact command
OMN-14587 specifies:

uv run python <omnibase_core>/scripts/ci/canonical_handler_shape.py --update \
    --package omnibase_infra --src-root <omnibase_infra>/src \
    --baseline <omnibase_infra>/scripts/ci/canonical_handler_shape_baseline.py --full

Mirrors the omnimarket baseline (OMN-14368: 111 non-canonical / 350 total).
This is measurement only — no handler code changed.

Result: 115 node contract.yaml files scanned, 22 canonical, 93
non-canonical (baseline freezes the 93). Category breakdown: nonadaptable
45, op_method 25, empty 12, envelope_in_core 8, no_binding 3.

Note: 2 of the 115 scanned entries
(omnibase_infra.nodes.node_architecture_validator /
.node_architecture_validator.handlers, and the node_ledger_projection_compute
equivalent) are duplicate hits from a nested handlers/contract.yaml file
sitting alongside the node's own top-level contract.yaml — a data-quality
artifact worth a separate look, not fixed here.

Update (follow-on commit): CI-gate wiring

The original PR shipped baseline-generation only, deferring CI-gate wiring
to keep the change reviewable as pure measurement. This follow-on commit
(daeba345) closes that deferred deliverable: adds a "Canonical
handler-shape ratchet" step to the existing lint job (a required needs:
dependency of the required "CI Summary" check), mirroring the omnimarket
wiring (OMN-14372/#1751) exactly — same --full scan, same sibling-checkout
reuse pattern (.ci/omnibase_core, already cloned for Transport-mock lint /
OMN-13026), same "no pre-commit mirror yet" rationale (OMN-14563 tracks the
real fix: relocate the classifier into an installed omnibase_core module;
pre-commit try-repo empirically proved a manifest-only export doesn't
work).

Closes the "[ ] Wire it as an enforced CI gate" item in OMN-14587.

dod_evidence (CI-gate wiring, OMN-14587)

RED/GREEN proof, local, against the committed baseline
(scripts/ci/canonical_handler_shape_baseline.py):

• RED (full scan, throwaway node node_zzz_canary_throwaway with a
  raw-dict handle(self, data: dict) -> dict): hard-fails "NEW
  non-canonical node(s)" — exit 1. The 93 baselined non-canonical nodes
  stayed WARN (non-blocking), not RED, confirming the shrink-only ratchet
  discriminates baselined debt from new regressions.
• GREEN (full scan, throwaway removed): new=0 unproven_flips=0 warn=93 — exit 0.
• pre-commit run --files .github/workflows/ci.yml — all applicable hooks
  pass.

CI enforcement not yet proven live: this repo's lint job (and every
other job) is gated behind occ-preflight, which fails on this PR pending
an OCC companion (Evidence-Source missing) — the same state as before this
commit. The new step has not executed in a green CI run yet. proof_class =
code-complete + locally-RED/GREEN, NOT enforcement-proven, pending the OCC
companion below.

OCC-COMPANION-NEEDED: omnibase_infra#2300 OMN-14587 (not authored here —
per 2026-07-13 operator decision, agents do not author OCC companions;
Codex owns all OCC).

Closes OMN-14587.

Test plan

• scripts/ci/canonical_handler_shape.py --update --package omnibase_infra --src-root ... --baseline ... --full run against a fresh dev-based
  worktree; output confirmed 115 nodes / 22 canonical / 93 non-canonical.
• Pre-commit hooks passed on the new file (SPDX header, ruff format/check,
  trailing whitespace, etc.).
• CI-gate wiring: local RED/GREEN proof above; pre-commit run --files .github/workflows/ci.yml clean.
• gh pr checks 2300 green — blocked on occ-preflight (OCC companion
  owed), not on this change's own content.

Summary by CodeRabbit

• Chores
  • Added automated CI checks to detect newly introduced non-standard handler patterns.
  • Added a baseline to track existing handler-shape exceptions and prevent regression.

Evidence-Commit: 9d39582a61ee122f9afb3e627621f15a4268851e

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a frozen non-canonical handler-shape baseline and a lint CI gate that runs the canonical handler-shape classifier against omnibase_infra source and rejects new violations or baseline growth.

Changes

Handler-shape ratchet

Layer / File(s)	Summary
Frozen handler-shape baseline scripts/ci/canonical_handler_shape_baseline.py	Defines the documented ratchet rules and frozen NON_CANONICAL node-path tuple.
Lint enforcement .github/workflows/ci.yml	Runs canonical_handler_shape.py in full mode using the baseline and current src tree, failing on newly introduced non-canonical nodes or baseline growth.

Estimated code review effort: 3 (Moderate) | ~15–30 minutes

Sequence Diagram(s)

sequenceDiagram
  participant GitHubActionsLint
  participant CanonicalHandlerShape
  participant OmnibaseInfraSrc
  participant HandlerShapeBaseline
  GitHubActionsLint->>CanonicalHandlerShape: run full classification for omnibase_infra
  CanonicalHandlerShape->>OmnibaseInfraSrc: inspect handler-shape nodes
  CanonicalHandlerShape->>HandlerShapeBaseline: compare against NON_CANONICAL
  HandlerShapeBaseline-->>GitHubActionsLint: provide frozen baseline
  CanonicalHandlerShape-->>GitHubActionsLint: pass or fail on new nodes or baseline growth

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Title check	✅ Passed	The title clearly summarizes the main change: extending the canon-shape ratchet baseline to omnibase_infra.

✨ 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-14587-fan-out-canon-shape-ratchet-omn-1435514368-to-omnibase_infra

---

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

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

.github/workflows/ci.yml (1)

263-268: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Pin the classifier checkout for reproducible enforcement.

This step executes code from the .ci/omnibase_core checkout, which uses ref: dev in the surrounding workflow. A moving branch can change classifier semantics without any change to this PR. Pin the checkout to an immutable commit and regenerate the baseline against that exact revision.

🤖 Prompt for 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.

In @.github/workflows/ci.yml around lines 263 - 268, Pin the `.ci/omnibase_core`
checkout used by the “Canonical handler-shape ratchet” step to an immutable
commit instead of the moving `dev` ref, then regenerate
`canonical_handler_shape_baseline.py` using that exact checkout revision so
enforcement remains reproducible.

🤖 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/ci.yml:
- Around line 243-249: Update the CI comment describing the canonical
handler-shape baseline to report the final baseline count of 92 non-canonical
handlers instead of 93, while preserving the scanned total and keeping it
synchronized with the regenerated baseline.

In `@scripts/ci/canonical_handler_shape_baseline.py`:
- Around line 13-14: Update the generator source that produces the canonical
handler shape baseline so its docstring no longer claims pre-commit enforcement;
describe the classifier as CI-only, then regenerate
scripts/ci/canonical_handler_shape_baseline.py rather than editing the generated
file directly.

---

Nitpick comments:
In @.github/workflows/ci.yml:
- Around line 263-268: Pin the `.ci/omnibase_core` checkout used by the
“Canonical handler-shape ratchet” step to an immutable commit instead of the
moving `dev` ref, then regenerate `canonical_handler_shape_baseline.py` using
that exact checkout revision so enforcement remains reproducible.

🪄 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: 76a5d0df-9c6d-40f9-9f72-fb3f47a95b27

📥 Commits

Reviewing files that changed from the base of the PR and between 9c349c1 and d37ebb6.

📒 Files selected for processing (2)

• .github/workflows/ci.yml
• scripts/ci/canonical_handler_shape_baseline.py