Skip to main content
A single word like “stale” hides several different questions. Did the author mean this claim to be trustworthy? Is Hibi allowed to block a merge over it? Has the code under it moved? Has a newer document replaced it? Hibi keeps those four questions in four separate status kinds and never collapses them into one flag.
The four kinds answer four different questions and live on different objects. Keeping them apart is what lets Hibi say “this doc was partly replaced and its code drifted” instead of one undifferentiated “stale.”

​
The four status kinds

The first two are authored: you decide them when you write the claim. The third is computed: Hibi recalculates it on every run and keeps it out of the store. The fourth tracks the document itself, independent of any one claim.

​
Authored trust

When you record a claim you declare how strongly you stand behind it. This is a statement about your confidence, not about the code.
verified is the only trust level that requires both an anchor and a @ref (the reference that backs the confirmation). Trust is set with --trust verified|inferred|assumed on hibi record.

​
Reanchoring is an attestation

Re-pointing a claim’s anchors is not the same as re-verifying the claim, and hibi reanchor keeps the two honest:
  • hibi reanchor <id> --ref <new-ref> asserts “I re-verified this”: selectors and evidence baselines refresh, authored trust is retained, and the new ref is recorded.
  • hibi reanchor <id> without --ref still re-anchors — the claim is findable again — but downgrades authored trust verified → inferred: nobody has re-attested that the claim is true. The downgrade is recorded on the assertion and surfaced in status and the JSON.
  • The pure-move exception. A bare hibi reanchor <id> keeps verified trust — with no downgrade recorded — in exactly one case: a pure move, where the re-resolved doc quote is byte-identical to the stored one and re-resolves uniquely at similarity 1.0, and the code side re-resolves as exactly unchanged. A byte-shift changes no evidence, so there is nothing to re-attest. Anything fuzzier downgrades as above.
This closes the gaming hole where re-linking an anchor clears CI without anyone re-checking the claim: a verified badge always means someone attested it, with a @ref, against the code it points at now.

​
Enforcement: earning the right to gate

Enforcement is the gate key. It decides whether a claim can fail your build or stamp a strong banner into a file, or whether it stays advisory.
Only an enforced claim gates or stamps a strong banner. A suggested claim is reported but never sets a failing exit code, so unconfirmed candidates can never break a build on their own.

​
How record derives enforcement

You do not pick enforced yourself; Hibi earns it for you, and refuses it if the anchor is too weak to stand behind.
1

Verified trust plus a precise anchor on both sides → enforced

If you record with verified trust and the anchor resolves precisely on the doc side and the code side, the claim is recorded as enforced.
2

Anything weaker → suggested

Without verified trust, or without a precise resolvable anchor, the claim is recorded as suggested, advisory until you confirm it.
3

An enforced record is refused unless every condition holds

record throws rather than create a weak enforced claim. To be enforced, the doc side must resolve, a @ref must be present, the code side must be precise (not a coarse or --glob target), and every code target must resolve.
Coarse and --glob targets are navigation and blast-radius only: they map which files a claim touches, but they can never back an enforced claim. (Coarse anchors are never reported as stale either; see how anchors are scored on the Anchors & selectors page.)

​
Computed states

The third kind, what the engine works out live on every check, is the two-axis verdict (doc:… / code:… resolution, plus a behavioral belief on behavioral claims) and the orthogonal expired flag. These are recomputed every run and never stored, so they are documented where they are graded rather than repeated here.

Verdicts, states & exit codes

The full two-axis model, the grading bands, and how a verdict becomes an exit code.

​
Document lifecycle

A document is more than its claims; it has a life of its own. It can be amended, replaced wholesale, withdrawn, or moved out of the read path. Caption: “Supersession is authored forward on the new document; Hibi derives the reverse edge.”

​
Supersession: replacing what a document said

When a newer document takes over from an older one, you author that relationship forward on the new document. Hibi derives the reverse edge, so the old document knows it was replaced without you editing it twice.
supersedes points at a whole Document. The old document’s lifecycle flips to superseded, and the next step is to archive it.
An old document can be amended and code-drifted at the same time: a newer doc replaced part of it, and the code under another part moved. Because the four status kinds are separate, both conditions surface together rather than masking each other.

​
Stranded claims: relocate, don’t hand-reanchor

Flipping a document’s lifecycle does not move the claims still anchored to it. So supersede, retract, and archive now report the live claims left behind in a strandedClaims: string[] field — the claims still anchored to the old, retracted, or archived document. When that list is non-empty, the operation’s next hint points at hibi relocate, the batch primitive that re-homes them in one pass:
The remedy is report-only: these operations never auto-fix. They record the edge and tell you which claims are stranded; you run relocate (or retire) yourself. relocate re-homes only the claims whose sentence appears verbatim in the target and reports the rest as misses — it never silently drops a claim.

​
Remediation: what to do when a claim needs attention

A flag is a request to re-verify, not a claim that the doc is wrong. The response is graduated by how dangerous it is to leave the document standing as-is. To withdraw a single obsolete claim, run hibi retire <claim-id> — it flips the claim’s enforcement to retired and keeps the audit trail. Never hand-edit or delete the claim’s file under .claims/. Every drift verdict carries a remediation menu that names the right verb for its state and pre-fills the command, so you rarely pick from this table by hand. The mechanics of how a banner is written, made tamper-evident, and placed at the top of a file live on the Status banners page.

​
Store health: hibi doctor

check answers “is anything drifting right now?” — it says nothing about claims that are broken in a quieter way: a side whose span was deleted, a suggested claim that never got a code anchor, a live claim stranded on a superseded document, or two propositions that share one fingerprint. hibi doctor surfaces exactly that dead state. It is purely informational and always exits 0, so it triages the store rather than gating a build, and its next hint routes you to the most pressing category (often hibi list --state orphaned). See hibi doctor for the full report.

​
Who does what

Hibi draws a hard line between the part it owns and the part it leaves to you.

The engine owns

Status, document edges, lifecycle stamping, archival, and flagging the content that needs attention. Deterministic: no model runs in the check loop.

You (or your agent) own

Rewriting the prose, then re-running hibi check. The engine never writes prose: it tells you what moved, and you decide what the doc should now say.
The engine flags and stamps; the author or agent rewrites and re-runs. That split is what keeps the signal trustworthy and the prose human.

​
Where to go next

Status banners

How a status becomes a visible, tamper-evident banner in the file itself.

CLI reference

record, supersede, retract, archive, and the rest of the verbs.