> ## Documentation Index
> Fetch the complete documentation index at: https://npupko.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Trust, Enforcement, and Document Lifecycle in Hibi
> Hibi tracks four status kinds — authored trust, enforcement, computed drift, document lifecycle — so a doc can be both drifted and superseded at once.
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
| Kind | Question it answers | Who sets it | Where it lives |
| ---------------------- | --------------------------------------------------------- | ---------------------------------- | --------------------------------- |
| **Authored trust** | How much did the author vouch for this claim? | the author, at `record` time | the Proposition |
| **Enforcement** | Is Hibi allowed to gate or stamp a strong banner over it? | derived at `record`, then explicit | the Assertion |
| **Computed** | Right now, has the evidence moved? | the engine, live on every `check` | nowhere; recomputed, never stored |
| **Document lifecycle** | Where is this document in its life? | authored edges + the engine | the Document |
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.
| Trust | Meaning |
| ---------- | ---------------------------------------------------------------------------- |
| `verified` | You confirmed the claim against the code; it carries an anchor and a `@ref`. |
| `inferred` | Derived from the code but not directly confirmed. |
| `assumed` | Stated without confirmation: a working assumption. |
`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 --ref ` asserts "I re-verified this": selectors
and evidence baselines refresh, authored trust is **retained**, and the new
ref is recorded.
* `hibi reanchor ` **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 ` 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.
| Enforcement | Meaning |
| ----------- | ------------------------------------------------------------------ |
| `suggested` | A candidate claim, advisory only. Never sets a failing exit code. |
| `enforced` | A confirmed claim: may gate a build and may stamp a strong banner. |
| `retired` | Withdrawn from active enforcement, kept for history. |
**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.
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`.
Without verified trust, or without a precise resolvable anchor, the claim is
recorded as `suggested`, advisory until you confirm it.
`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](/anchors) 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.
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.
```mermaid theme={null}
stateDiagram-v2
[*] --> active
active --> amended: amends (some propositions)
active --> superseded: supersedes (whole doc)
amended --> superseded
superseded --> archived: move out of read path
active --> retracted: author withdrew
active --> archived
```
Caption: "Supersession is authored forward on the new document; Hibi derives the reverse edge."
| Lifecycle | Meaning |
| ------------ | -------------------------------------------------------------------------------------------- |
| `active` | In the read path; treated as current. |
| `amended` | Some of its propositions were replaced by a newer document; the file stays in the read path. |
| `superseded` | Replaced in full by a newer document; should be archived. |
| `archived` | Moved out of the read path, with a tombstone or redirect to its successor. |
| `retracted` | The author withdrew the claim. |
## 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.
```bash theme={null}
hibi supersede --new docs/new.md --old docs/old.md --type supersedes
```
`amends` points at one or more named **Propositions**: the specific claims
the new document changes. The old document stays in the read path; only the
named propositions flip, and its lifecycle becomes `amended`. Proposition ids
are required.
```bash theme={null}
hibi supersede --new docs/new.md --old docs/old.md --type amends --propositions prop_d6185fc85e2a4e52,prop_f31b0a927c440e19
```
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`](/cli-reference#hibi-relocate), the batch
primitive that re-homes them in one pass:
| Operation | When `strandedClaims` is non-empty, `next` is |
| ----------- | ------------------------------------------------------------------ |
| `supersede` | `hibi relocate --from --to ` |
| `archive` | `hibi relocate --from --to ` |
| `retract` | `hibi relocate --from --to # or: hibi retire ` |
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.
| Condition | Remediation |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `amended` / superseded-in-part | Stamp a banner and flip the frontmatter status; keep the file. |
| `superseded` / obsolete-in-full | Archive it: move it out of the read path with a tombstone or redirect to the successor. |
| `code:changed` / `code:orphaned` / `expired` | Stamp a banner and flag the specific claims to re-verify. |
| `doc:changed` / `doc:ambiguous` | Banner noting the prose diverged; re-confirm, or `hibi retire `. |
| `doc:orphaned` | The documented sentence was deleted: `hibi reanchor` to a new target, or `hibi retire `. |
| `refuted` | Strong banner, with a configurable gate. |
| `retracted` | Banner noting the author withdrew the claim. |
To withdraw a single obsolete claim, run **`hibi retire `** — 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`](/verdicts#the-remediation-menu) 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](/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`](/cli-reference#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.
Status, document edges, lifecycle stamping, archival, and flagging the
content that needs attention. Deterministic: no model runs in the check loop.
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
How a status becomes a visible, tamper-evident banner in the file itself.
`record`, `supersede`, `retract`, `archive`, and the rest of the verbs.