> ## Documentation Index > Fetch the complete documentation index at: https://npupko.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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 A published action that runs hibi check or hibi diff on every push or pull request and fails the build when a claim drifts. A pre-commit or pre-push hook that runs Hibi locally and blocks the commit or push before drift ever reaches the remote. 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. 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: ```yaml theme={null} 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 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`. 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. Base ref for `command: diff`: the point to compare against (a branch, tag, or commit). Ignored when the command is `check`. 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. 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. 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 --reason ` (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. ```yaml theme={null} - 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](/cli-reference#running-verifiers-check-run-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. ```sh theme={null} # 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. ```bash pre-push theme={null} #!/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 } ``` ```bash pre-commit theme={null} #!/bin/sh # Verify the whole claim set before every commit. hibi check || { echo "hibi: documentation drift detected — re-verify before committing." >&2 exit 1 } ``` `hibi diff --since ` 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](https://github.com/evilmartians/lefthook) or [husky](https://github.com/typicode/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. ```mermaid theme={null} sequenceDiagram participant A as Coding agent participant H as hibi A->>H: SessionStart: status --doc CLAUDE.md H-->>A: current? (exit 0) or STALE (banner + exit 2/3) Note over A,H: agent trusts only a current doc A->>A: edits code A->>H: Stop: diff --since H-->>A: which claims this change invalidated A->>A: drafts the prose fix; human merges ``` Hibi is the deterministic half of the loop: it flags. The agent or human rewrites prose, then re-runs `check`. 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. After the agent edits code, a Stop hook runs `hibi diff --since `. 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. 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

`) 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](/banners) page; the ready-made Agent Skill that teaches a coding agent these loops lives on the [Claude Code](/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](/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 Every command and flag behind these hooks (`check`, `diff`, `status`) and the `--fail-on` strictness levels in full. The two-axis verdict model and the complete gating exit-code contract. How Hibi stamps staleness into the artifact, and the compact pointer used for agent instruction files. The official Agent Skill that teaches a coding agent the SessionStart and Stop loops described above.