Command

`okulo check`

Quality gate for a PR, staged changes, or the working tree — fail when hot code gets worse.

cigate

When to use it

Before merge, in CI, or as a pre-commit hook via okulo hook.

Usage

okulo check [repo] [options]

Options

Option	Default	Description
`(default mode)`	PR	Compare --head to merge-base with --base
`--staged`	off	Compare index to HEAD
`--working`	off	Compare working tree to HEAD (tracked files)
`--base`	main/master…	Base branch for PR mode
`--head`	HEAD	Side under test in PR mode
`--fail-on`	critical	`critical`, `warning`, or `none`
`-f, --format`	table	Use `markdown` for PR comments

Examples

Current branch vs main

okulo check
okulo check --base main
okulo check --base develop

PR comment artifact

okulo check --base origin/main -f markdown -o okulo-pr.md

Before you commit

okulo check --staged --fail-on warning

Gate only one area

okulo check --base main --components backend --fail-on critical

Sample output

Illustrative terminal output (column layout matches the real CLI):

Change check  feature/pay-tax vs merge-base origin/main
file                      hotspot  health before  after     Δ  cognitive
────────────────────────  ───────  ─────────────  ─────  ────  ─────────
src/billing/invoice.py          ●            3.4    2.9  -0.5  198 → 220
web/checkout/Cart.tsx           ●            4.9    5.1  +0.2  140 → 138
server/orders/api.go            -            6.4    6.4  +0.0   88 → 90

Findings
  critical  health-decline     src/billing/invoice.py  hotspot health fell 3.4 → 2.9
  warning   missing-co-change  web/checkout/Cart.tsx   usually changes with invoice.py

FAIL  1 critical · 1 warning · 0 info  (fails on: critical)

How to read it

Per-file health before → after shows whether this change healed or hurt the code you touched.
critical findings (default fail) usually mean a hotspot got worse — stop and split/refactor before merge.
missing-co-change warns you edited one side of a historically coupled pair — consider reviewing the sibling file.
Exit code 1 = gate failed (CI should block). 0 = pass.

Tips

CI checkouts need enough Git history (avoid depth 1) for meaningful results.
Empty repos (no commits yet) exit 0 with a warning — nothing to compare.

okulo check