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

# Status Banners: Stamp Drift Warnings Into Your Docs

> hibi check --write stamps a sentinel-delimited banner into the top of each suspect document so a reader without hibi still sees the flag.

A **status banner** is a block of plain text that `hibi check --write` writes into the top of a suspect document. It exists because a reader, human or agent, reads the raw file and trusts it. A flag that lives only in CI output is invisible to that reader.

<Note>
  Stamping is opt-in: a banner is written only under `check --write`. Only an enforced claim can put a document into the suspect set. Without `--write`, `check` is read-only.
</Note>

## What a banner looks like

```markdown theme={null}
<!--
HIBI:BEGIN v1 7f3a9c2e
STALE DOCUMENT — 2 suspect claim(s) — re-verify before trusting.
[code:changed] (prop_d6185fc85e2a4e52) Failed uploads retry up to 5 times with backoff.
[doc:orphaned] (prop_f31b0a927c440e19) Results are returned sorted ascending by score.
HIBI:END v1 7f3a9c2e
-->
```

* **`HIBI:BEGIN v1 <nonce>`** and **`HIBI:END v1 <nonce>`** are the sentinels. They are line-anchored and version-tagged. `<nonce>` is generated once per repository by `hibi init` and stored in `.claims/config.json`; a document that merely quotes the banner format uses a different nonce and is never matched.
* The **headline** is `STALE DOCUMENT — N suspect claim(s) — re-verify before trusting.` where `N` counts the body lines. A document whose only notice is its lifecycle gets `DOCUMENT STATUS — N notice(s) — re-verify before trusting.`
* **Body lines** are one per suspect proposition, sorted by id, in the form `[status] (id) text`. `status` is side-tagged (`code:changed`, `doc:orphaned`, `code:moved`, `behavior:refuted`, `expired`) or a lifecycle value (`superseded`, `archived`). `text` is the live documented sentence.

There is no timestamp, no run id, and no checksum. Re-stamping a document whose status has not changed produces no diff. Each write reports one `bannerAction`: `insert`, `replace`, `remove`, or `noop`. Clearing a banner restores the exact pre-banner bytes.

A banner written by an older hibi, whose END line carried a checksum, is still recognized once so that it gets replaced.

## Placement and comment style

The banner goes at the top of the file. If the file opens with a `---` frontmatter fence, it goes immediately after the fence.

| Format                                                          | Wrapping      |
| --------------------------------------------------------------- | ------------- |
| Markdown, HTML, XML                                             | `<!-- … -->`  |
| Python, shell, YAML, TOML, Ruby                                 | `#` per line  |
| TypeScript, JavaScript, Rust, C, Go, Java, Kotlin, Swift, Scala | `//` per line |
| other                                                           | plain lines   |

## Instruction files

`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, and `.github/copilot-instructions.md` are loaded into an agent's context on every turn. For those files the body collapses to one line:

```markdown theme={null}
<!--
HIBI:BEGIN v1 7f3a9c2e
STALE — 2 claim(s); run `hibi check --doc CLAUDE.md`
HIBI:END v1 7f3a9c2e
-->
```

The set is configurable with `StoreConfig.instructionFiles` (a list of globs in `.claims/config.json`). The per-claim detail comes from `hibi check --doc <path>`.

## Pristine documents

Some documents must never be written: a vendored spec, a third-party README. List globs in `StoreConfig.pristine`; `check --write` skips any document that matches. The globs are evaluated at stamp time. Verdicts for a pristine document still appear in the JSON and the exit code.

## What the engine writes

The engine owns the region between the sentinels and nothing else. It never edits prose. Older versions also wrote a status key into Markdown frontmatter; that is no longer written, and `check --write` removes a leftover one.

## Where to go next

<CardGroup cols={2}>
  <Card title="Lifecycle" icon="arrows-spin" href="/lifecycle">
    The `superseded` and `archived` lines that can appear in a banner body.
  </Card>

  <Card title="CI and agents" icon="robot" href="/ci">
    Wiring `check --write` and `check --doc` into CI, hooks, and agent sessions.
  </Card>
</CardGroup>