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:

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).

Running verifiers

Verifiers execute only under:

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

Verdicts

The two axes, the gates rule, and the exit codes.

Resolvers

The out-of-process protocol that hosts external verifier runners.