> ## Documentation Index
> Fetch the complete documentation index at: https://hibi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Behavioral Claims and Verifiers in Hibi

> A claim is behavioral when it carries a verifier. Verifiers run only under check --run-verifiers and set behavior to supported or refuted.

Some sentences cannot be checked by locating text: "retries with exponential backoff", "sorts ascending". Text and AST resolution can tell you the code changed; they cannot tell you the behavior still holds. For that Hibi runs a **verifier** the author attached to the claim.

## What makes a claim behavioral

A claim is behavioral if and only if it has at least one verifier. There is no keyword heuristic and no separate flag. Attach a verifier at record time with `--verifier kind:ref` (repeatable), or with the `verifier` key in a `--from-file` spec:

```sh theme={null}
hibi record --doc README.md --doc-quote "Failed uploads retry with backoff" \
  --code-file src/upload.ts --code-quote "retryWithBackoff(" \
  --verifier command:"bun test upload"
```

`kind` is an open string used as a dispatch key. The built-in runner handles `command`: it runs `ref` as a shell command from the anchor root (the current directory, or `--cwd`), exit `0` is `supported`, non-zero is `refuted`. An external resolver can declare other kinds in its `describe` response (see [Resolvers](/resolvers)).

## Running verifiers

Verifiers execute only under:

```sh theme={null}
hibi check --run-verifiers [--verifier-timeout <seconds>]
```

The default timeout is 120 seconds per verifier. A timeout or spawn failure produces no result for that verifier.

The result lands in the verdict's `behavior` field:

| State       | Meaning                                                 |
| ----------- | ------------------------------------------------------- |
| `supported` | at least one verifier ran and every one that ran passed |
| `refuted`   | at least one verifier failed                            |

Without `--run-verifiers`, or on a claim with no verifier, `behavior` is absent. `refuted` gates on an enforced claim. `supported` is clean.

## The doc-first guard

A verifier runs only when the doc side resolved `unchanged` or `moved`. If the documented sentence is `changed`, `orphaned`, or `ambiguous`, Hibi does not run the verifier, because the sentence being verified is no longer known. The doc-side state is reported instead.

## Why verifiers are opt-in

A verifier is a command committed to the repository. Whoever can commit decides what runs on the machine of whoever checks. Hibi therefore never runs a verifier implicitly: `check` without `--run-verifiers`, `list`, and `coverage` never spawn a verifier process. External runner resolvers additionally require an entry in the default-deny manifest `.claims/resolvers.json`.

## Remediation for `refuted`

The menu for `behavior:refuted` offers `fix-code` and `fix-claim`, and never `reanchor`. Reanchoring would clear the flag without fixing the behavior.

## Where this fits

<CardGroup cols={2}>
  <Card title="Verdicts" icon="scale-balanced" href="/verdicts">
    The two axes, the gates rule, and the exit codes.
  </Card>

  <Card title="Resolvers" icon="puzzle-piece" href="/resolvers">
    The out-of-process protocol that hosts external verifier runners.
  </Card>
</CardGroup>