> ## 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.
# Hibi Verdicts: Claim States, Remediation, and Exit Codes
> How Hibi models a claim, grades it on anchor resolution and behavior, attaches a remediation menu, and maps the result to an exit code.
Hibi tracks **claims**: a sentence in a document, anchored to the code it describes. On every `hibi check`, each claim produces a **verdict**: a per-side anchor state, an optional behavior state, an `expired` flag, a `gates` flag, and a remediation menu. Verdicts are computed from the current files and never stored.
## The model
* A **Document** is a file with claims on it. It has a lifecycle: `active`, `superseded`, or `archived`.
* A **Proposition** is the sentence, deduplicated by content fingerprint. Two documents that state the same sentence share one proposition.
* An **Assertion** is one claim: this sentence, in this document, anchored to this code, with an owner, an enforcement level, an optional ttl, and zero or more verifiers.
* An **Anchor** has a **doc side** (one selector bundle for the sentence) and a **code side** (zero or more bundles for the code). The code side may be empty only on a `suggested` claim.
The store holds anchors, not copies of the prose. The stored quote is anchoring material; the live document span is the truth and is re-read on every run. Selector kinds and the resolution rules are on the [Anchors](/anchors) page.
A flag is a request to re-verify. Hibi reports that the text or code under a claim moved. It does not decide that the sentence is wrong, and it never edits prose.
## The flow
`hibi record` stores an anchor for the doc span and the code span(s). The anchor is the baseline, so `check` runs offline and under a shallow clone.
`check` locates the documented sentence in the current document. If the sentence is gone or changed, the verdict says so on the doc side.
Each code bundle is located in its file and graded through the cascade on the Anchors page. The worst code bundle sets the verdict's `code` state.
Under `check --run-verifiers`, a claim with verifiers runs them and gets a `behavior` state. See [Behavioral claims](/behavioral).
Hibi emits the verdict, sets the process exit code, and with `--write` stamps a banner into each suspect document.
## The two axes
### Anchor resolution
One vocabulary, applied to each side and reported as `doc:` and `code:`.
| State | Meaning |
| ----------- | ------------------------------------------------------------------ |
| `unchanged` | found, same text, same place |
| `moved` | found, same text, new place |
| `changed` | found, but the text, the AST, or a literal inside the span differs |
| `ambiguous` | matches in several places equally well |
| `orphaned` | not found |
### Behavior
Present only when a verifier ran. A claim is behavioral if and only if it carries at least one `--verifier kind:ref`.
| State | Meaning |
| ----------- | ------------------------------ |
| `supported` | every verifier that ran passed |
| `refuted` | at least one verifier failed |
Without `--run-verifiers`, or on a claim with no verifier, the `behavior` field is absent.
### The `expired` flag
A claim may carry a `ttl` (an ISO-8601 instant). Past it, the verdict has `expired: true`. It is a flag alongside the axes, not a state on them.
## The gates rule
`gates` is true if and only if the claim is `enforced` and at least one of these holds:
* `doc` or `code` is `changed`, `orphaned`, or `ambiguous`;
* `expired` is true;
* `behavior` is `refuted`.
`moved` never gates. A `moved` side on an enforced claim is a **warning**. A `suggested` claim never gates and never warns. A `retired` claim is listed but counted as neither clean, gating, nor warning.
## The verdict shape
```json theme={null}
{
"assertionId": "asrt_897e054b48d040db",
"propositionId": "prop_d6185fc85e2a4e52",
"documentId": "doc_5c9e4f99d90e2cfd",
"doc": "unchanged",
"code": "changed",
"expired": false,
"gates": true,
"changed": "src/auth.ts: value changed (was `30`)",
"remediation": { "recommended": "update-claim", "actions": [ /* … */ ] },
"notes": ["code: value changed (was `30`)"]
}
```
`behavior` appears only when a verifier ran. `changed` is a one-line summary present when a side is `changed`. `notes` carries the reason labels ("identifiers or literals renamed", "restructured", "value changed", "a number in the sentence changed", "quote not found").
Pass `--explain` to append the evidence tail: `evidence.docRegion`, `evidence.codeRegions`, `evidence.similarity` (normalized similarity of the located span to the stored quote), and `evidence.changedEvidence` (`{ path, kind: text|ast|value|verifier-source, detail }`), plus `advisories`.
The full `check` payload is `{ ok, action: "check", schemaVersion: "v3", ref, since?, changedFiles?, doc?, exitCode, summary, verdicts, documents }`. `summary` has `total`, `gating`, `warning`, `clean`, `retired`, per-state histograms `doc`, `code`, `behavior`, and `expired`. Each entry in `documents` has `id`, `path`, `lifecycle`, `suspect: [{ propositionId, status }]`, and `bannerAction` when `--write` touched the file. The `status` vocabulary is side-tagged: `code:changed`, `doc:orphaned`, `code:moved`, `behavior:refuted`, `expired`, `superseded`, `archived`.
## The remediation menu
Every suspect verdict carries a `remediation` block: `recommended` (an action id, or `null` when Hibi cannot infer intent) and an ordered `actions` list. Each action is `{ id, title, rationale, command? }`. `command` is present when Hibi can perform the step, with the claim id filled in.
| Verdict | `recommended` | Actions, in order |
| -------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `code:changed` | `update-claim` | `update-claim` ("Update the sentence, then reanchor", `hibi reanchor `), `reanchor` (as is), `retire` |
| `doc:changed` | `reverify-doc` | `reverify-doc`, `reanchor`, `retire` |
| `doc:changed` and `code:changed` | `reconcile` | `reconcile`, `reanchor`, `retire` |
| `*:orphaned` | `reanchor` | `reanchor` (`hibi reanchor --suggest`), `retire`, `supersede` |
| `*:ambiguous` | `reanchor` | `reanchor` (pass a wider span) |
| `*:moved` | `reanchor` | `reanchor` |
| `behavior:refuted` | `null` | `fix-code`, `fix-claim` |
| any of the above with `expired` | as above, or `reverify-and-rerecord` | the row's actions plus `reverify-and-rerecord` |
Notes on the table:
* The orphan menu leads with a runnable command: `hibi reanchor --suggest` lists candidate locations, after which you reanchor with an explicit span.
* `behavior:refuted` never offers `reanchor`. A failing verifier means the behavior is wrong, not that the anchor moved.
* `expired` composes. When the base menu recommends `reanchor`, or there is no base menu, the recommendation becomes `reverify-and-rerecord`.
* Orphan precedence: an orphaned side produces the orphan menu even when a verifier was refuted.
`--no-hints` (or `HIBI_ADVICE=0`) drops the `remediation` block from every verdict and `list` row.
## Exit codes
| Code | Meaning |
| ---- | ---------------------------------------------------------------------------------- |
| `0` | clean, or only warnings |
| `2` | at least one gating verdict; or a warning under `--fail-on warn` |
| `1` | operational error: no store, unknown flag, unknown `--since` ref, missing document |
`--fail-on` sets the threshold: `gating` (default), `warn` (a `moved` side also exits 2), `never` (always exit 0; read the JSON).
## Finding ungrounded sentences
Claims enter the store deliberately; Hibi does not extract them from prose. `hibi coverage --doc ` splits a document into sentence-level regions and reports which are backed by a live, code-grounded claim. The uncovered regions are the candidates for a new claim or for removal. `--fail-uncovered` exits 2 while any region is uncovered. A missing document is exit 1.
## Where to go next
The selector kinds and the resolution cascade that produces each state.
Verifiers, `--run-verifiers`, and the doc-first guard.
`retire`, `supersede`, and `archive`.
Every command and flag.