Integrating Hibi into CI, Git Hooks, and AI Agent Loops

Wire Hibi into GitHub Actions, pre-commit hooks, or an AI coding agent’s edit loop to catch documentation drift before anyone trusts a stale doc.

Hibi is the deterministic half of a loop: it flags claims whose evidence has moved, and a human or agent decides what the prose should now say. Hibi never rewrites prose; it flags, and can stamp a status banner. It wires into three places: continuous integration, a git hook, and an AI coding agent’s edit loop.

The shape is the same everywhere. You run a Hibi command, it emits a verdict, and you act on its exit code: 0 is clean, 2 gates (a confirmed problem that should block), 3 is advisory (a re-anchorable moved or a behavioral at-risk — it warns but never gates), and 1 is an operational error. Because no model runs in the check loop, the same working tree always yields the same verdicts. That is what makes “is this doc stale?” a signal you can gate a pipeline on rather than a probabilistic guess.

A flag is a request to re-verify, not a claim that the doc is wrong. Hibi reports that the evidence under a claim moved; the person or agent who reads the flag decides the fix.

The three consumer contexts

GitHub Action

A published action that runs hibi check or hibi diff on every push or pull request and fails the build when a claim drifts.

git hook

A pre-commit or pre-push hook that runs Hibi locally and blocks the commit or push before drift ever reaches the remote.

Agent hooks

A coding agent calls hibi status before it trusts a doc, and hibi diff after it edits code, so it never acts on or leaves behind a stale page.

MCP shim

A Model Context Protocol server that serves verdicts to a tool, re-computed live on every request, never from a cached index.

GitHub Action

The Hibi repository is itself a published GitHub Action. Reference it by release tag (npupko/hibi@v0.2.3 to pin a release, or @main to track the tip) and pass its behavior through with: inputs. The action installs Bun and runs the hibi binary for you, so a minimal drift gate is a few lines:

name: docs-drift
on: [push, pull_request]

jobs:
  hibi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: npupko/hibi@v0.2.3
        with:
          command: check
          fail-on: gating

Inputs

command · string · default: "check"

Which verb to run: check (verify every claim in the store) or diff (verify only the claims touched by a range of changes). Defaults to check.

fail-on · string · default: "gating"

Strictness: when a non-zero exit should fail the job. Uses Hibi’s canonical --fail-on vocabulary: gating (default), warn, tamper, or never. See the table below.

since · string

Base ref for command: diff: the point to compare against (a branch, tag, or commit). Ignored when the command is check.

write · boolean · default: "false"

When true, Hibi stamps status banners into the drifted documents. Leave it false for a read-only gate that only reports; turn it on when you want CI to also mark the artifacts.

run-verifiers · boolean · default: "false"

When true, the action passes --run-verifiers to the command, so declared verifiers execute during the run and behavioral claims can reach supported or refuted. Off by default: verifiers execute repo-committed commands — a supply-chain surface — and Hibi never runs them without this explicit opt-in.

working-directory · string · default: "."

Directory to run Hibi in: the anchor root that contains the .claims/ store. Defaults to the repository root.

Strictness levels

fail-on decides which verdicts turn into a failing build. The vocabulary is shared with the CLI’s --fail-on flag, so a local run and the action agree.

fail-on	Build fails when…
gating	a gating verdict appears on an enforced claim: changed, orphaned, or ambiguous on either side, expired, or refuted. The default.
warn	also fails on the warning verdicts moved and at-risk, not just gating ones. The strictest setting.
tamper	fails only when a status banner has been hand-edited (its checksum no longer matches).
never	reports every verdict but never fails the build. Useful while you are still building up your claim set.

Use command: check on push to your main branch and command: diff with a since on pull requests, so PR runs only re-verify the claims a change could have touched. diff scopes its work through git diff --name-only, so it stays fast on large repositories.

When a pull request flags a behavioral claim at-risk and you have checked that the behavior still holds, the sanctioned acknowledgment is hibi ignore --claim <id> --reason <text> (the reason is required). The suppression is recorded in the store; while it holds, the at-risk is non-gating, does not affect the exit code, and is surfaced as suppressed: true in the JSON. It lapses automatically the moment any acknowledged evidence file changes again or a new evidence path appears — an acknowledgment never becomes a permanent mute.

Proving behavioral claims — check --run-verifiers

A plain hibi check grades anchors deterministically but never runs a verifier. To also prove behavioral claims — turning at-risk into supported or refuted — add --run-verifiers, which executes each claim’s declared verifier command. Hibi dogfoods exactly this: its own CI runs hibi check --run-verifiers --fail-on gating, so a broken behavioral gate turns the build red without human review.

      - uses: npupko/hibi@v0.2.3
        with:
          command: check
          run-verifiers: true
          fail-on: gating

Verifiers execute repo-committed commands — a supply-chain surface — so they run only under this explicit opt-in; see running verifiers.

Gating a plan — coverage --fail-uncovered

The plan-verification loop is the mirror image of drift-checking: instead of guarding recorded claims, you assert that a plan document is fully grounded — every promise anchored to the code that implements it. hibi coverage --doc plan.md --fail-uncovered makes that CI-enforceable: it exits with the gating code 2 while any block of the plan is still uncovered, and 0 once every block is backed by a claim.

# in a CI step, once hibi is installed:
hibi coverage --doc plan.md --fail-uncovered   # exit 2 while any block is uncovered

An uncovered block is an unimplemented or unpruned plan item. Hibi never judges whether code implements a sentence — the author (or agent) makes that judgment by anchoring each promise to its implementing code, and --fail-uncovered guards that the anchoring is complete.

git hooks

A git hook moves the same gate one step earlier, onto the developer’s machine, before a commit or push reaches the remote. Hibi has no hook manager of its own; it is a command that exits non-zero on drift, so it drops into whatever you already use.

pre-push

#!/bin/sh
# Re-verify only the claims this branch touched, against the upstream base.
hibi diff --since origin/main || {
  echo "hibi: documentation drift detected — re-verify before pushing." >&2
  exit 1
}

hibi diff --since <ref> is the natural fit for a pre-push hook: it asks “what did the changes on this branch invalidate?” and only re-verifies the claims in range. hibi check verifies the entire store and suits a pre-commit hook or a belt-and-braces final gate. Either way the hook gates on Hibi’s exit code, exactly as CI does.

If you manage hooks with a tool like lefthook or husky, register the same command there instead of hand-writing a hook file. Hibi does not care which manager invokes it; it only reads files and reports an exit code.

Pass --write in a hook only if you intend each developer to also re-stamp the document banners locally. For a pure gate, leave it off so the hook reports and blocks without modifying files mid-commit.

Agent hooks

The third context is an AI coding agent in an edit loop. The risk here is sharp: a naive agent reads a doc (often an always-loaded instruction file like CLAUDE.md) and trusts it as current. If the doc has drifted, the agent acts on a stale page. Hibi closes that gap by sitting at two points in the agent’s lifecycle.

Hibi is the deterministic half of the loop: it flags. The agent or human rewrites prose, then re-runs check.

1. SessionStart: gate before trusting a doc

   At the start of a session the agent runs hibi status --doc CLAUDE.md (or whichever instruction file it is about to rely on). status is the read-time gate: it exits 2 if any claim in that doc is gating, 3 if a claim is moved or at-risk, and 0 when the doc is clean. The agent trusts the doc only on a clean result; on a stale one it sees the banner and the exit code and knows not to act on the page as written.

2. Stop: report what an edit invalidated

   After the agent edits code, a Stop hook runs hibi diff --since <base>. Hibi reports which claims that change invalidated, so the agent can draft the corresponding prose fix. The agent (or the human reviewing the change) writes the new wording; Hibi never writes prose itself.

3. Re-run check

   Once the prose is updated, re-running hibi check confirms the claims resolve again and the verdict returns to clean.

For instruction files specifically, the banner Hibi stamps collapses to a single line (STALE — N claim(s); run hibi status --doc <p>) so the always-loaded file stays lean and the full detail lives in the JSON that status returns. The mechanics of that banner are covered on the status banners page; the ready-made Agent Skill that teaches a coding agent these loops lives on the Claude Code page.

An MCP shim that exposes Hibi to a tool must serve live-recomputed verdicts: it re-runs the resolution flow on every request and never returns a cached index. A cache would re-introduce the drift Hibi exists to kill: the stored answer would itself fall out of sync with the code.

Exit codes recap

Every context above gates on the same four exit codes. They are reproduced here for convenience; the full verdict model behind them lives on the verdicts page.

Code	Meaning
0	all clean
2	gating: changed, orphaned, or ambiguous on either side, expired, or refuted, on an enforced claim
3	advisory: moved or at-risk — re-anchorable, never gates
1	operational error

Exit 3 is advisory and never gates. A moved span is re-anchorable and a behavioral at-risk claim has no failing verifier behind it — neither is strong enough to fail a build on its own. Only exit 2 marks a confirmed, enforced drift that should block. (Under the default --fail-on gating, both bands still produce a non-zero exit, so a strict CI step fails on either; --fail-on never reports without failing — read the JSON for the result.)

moved and at-risk never gate, and suggested claims never set a failing exit code, so a build only breaks on a confirmed, enforced claim whose evidence moved. That keeps the suspect set tight: a gate you can trust, not noise you learn to ignore.

For quieter CI logs, add --no-hints (or set HIBI_ADVICE=0) to drop the per-verdict remediation menu from the JSON. When a run fails and you need to see why a claim was graded the way it was, re-run with --explain to get the full evidence tail, advisories, and the proposition fingerprint.

Where to go next

CLI reference

Every command and flag behind these hooks (check, diff, status) and the --fail-on strictness levels in full.

Verdicts, states & exit codes

The two-axis verdict model and the complete gating exit-code contract.

Status banners

How Hibi stamps staleness into the artifact, and the compact pointer used for agent instruction files.

Claude Code skill

The official Agent Skill that teaches a coding agent the SessionStart and Stop loops described above.