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.

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.

What a banner looks like

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

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

Lifecycle

The superseded and archived lines that can appear in a banner body.

CI and agents

Wiring check --write and check --doc into CI, hooks, and agent sessions.