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

1. Record

   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.

2. Resolve the doc side

   check locates the documented sentence in the current document. If the sentence is gone or changed, the verdict says so on the doc side.

3. Resolve the code 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.

4. Verifiers (opt-in)

   Under check --run-verifiers, a claim with verifiers runs them and gets a behavior state. See Behavioral claims.

5. Verdict, exit code, banner

   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:<state> and code:<state>.

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

{
  "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 <id>), 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 <id> --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 <id> --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 <path> 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

Anchors

The selector kinds and the resolution cascade that produces each state.

Behavioral claims

Verifiers, --run-verifiers, and the doc-first guard.

Lifecycle

retire, supersede, and archive.

CLI reference

Every command and flag.