Skip to main content
Documentation drifts. Someone edits the code, the sentence that described it stays put, and the page now lies to anyone who reads it. Often that reader is an AI coding agent that loads CLAUDE.md or a README at the start of a session and acts on every line as if it were true. Hibi exists to make that drift both detectable and visible in the artifact itself, deterministically. For the mechanics first, start with How it works; to see how the reasoning becomes a verdict, read Verdicts, states & exit codes.

​
The problem & threat model

A claim is a binding between a documented sentence and the code it describes. Claims rot in three ways, and conflating them is the first mistake: The threat model is a single sentence: a naive consumer reads the raw file and trusts it. It does not consult a dashboard, a CI run, or a side channel. It reads the bytes on disk. So a staleness signal that lives only beside the file is invisible to the reader who most needs it. The status has to land in the artifact.
A flag is a request to re-verify, not a claim that the doc is wrong. The evidence under a sentence moved; a human or agent decides what the prose should now say. Hibi never rewrites prose.

​
The principles

These six commitments shape every decision in Hibi. Read them as constraints the design refuses to violate, not as features.
Hibi is deterministic: no model runs in the check loop. The same working tree always yields the same verdicts. This is not a performance choice; it is the entire value proposition. The moment “is this doc stale?” becomes probabilistic, you have traded a trustworthy, repeatable signal for a guess that varies run to run, and a guess is what a reader already had. An optional semantic resolver may advise, out-of-process, but it never decides a verdict and never gates.
Hibi reports that the evidence under a claim moved (re-verify it), never that the claim is false. Confirming falsity requires reading both sides and judging intent, which is a human or agent act, not a deterministic one. So the signal is always “suspect, not false.” This keeps Hibi honest about what it knows: the anchored code changed, therefore the belief is no longer justified, therefore someone should look again.
A tool that cries wolf gets muted, and a muted tool protects nothing. The valuable output is a tight, trustworthy suspect set, not a long list of maybes. Hibi earns that several ways: coarse file- and directory-level anchors are treated as navigation only and are never reported as stale; resolution is graded against confidence thresholds rather than a binary cutoff; several redundant signals must corroborate before a verdict is confident; and when those signals disagree, the answer is “re-verify,” not a hard “stale.”
The store holds pointers (bidirectional anchors), not a copy of the prose. A copied sentence would become a second source of truth that outlives the real doc, so the doc could drift while the copy still looked authoritative. By re-reading the live sentence at check time, Hibi closes that gap: the same mechanism that catches code drift also catches doc drift, because a sentence that was edited or deleted no longer resolves against its anchor.
The rule is “if it isn’t core, it’s a resolver or a consumer.” The core is only the data model and the verdict contract: no I/O, no CLI, no UI. Everything else (anchor grading, supersession logic, verifier execution, an optional advisor) lives behind one out-of-process protocol. A small core is auditable, and an auditable core is what makes the determinism claim believable.
Hibi treats docs as text. There is no per-format parser in the core, so Markdown, plain text, AsciiDoc, an AGENTS.md, or an editor-rules file all work the same way. Format-specific knowledge (where to place a banner, which comment syntax to use) is a thin edge concern, never a precondition for tracking a claim.

​
Why no model sits on the verdict path

One objection to a deterministic design: wouldn’t a language model understand whether the doc still matches? The published evidence says no: not reliably enough to gate on.
  • The best published doc-behavior verification tops out at an F1 of about 0.58 (precision ≈ 0.72, recall ≈ 0.48). A coin-flip-adjacent recall is not a foundation for “trust this page.”
  • LLM-as-judge consistency falls to about 0.57 under sampling, and audits have shown judges accepting up to ~63% of intentionally wrong answers. A judge that endorses two-thirds of wrong answers cannot be the thing that says a doc is fine.
  • Noisy analyzers report up to ~96% spurious warnings, and trust lost in one tier spreads to every tier; once a developer learns to ignore Hibi’s output, the accurate flags die with the false ones.
So Hibi splits the work the way the evidence demands. It routes attention deterministically (structural analysis says where something changed) and it runs executable checks the author supplied to judge behavioral truth. A model may advise (explain a change, triage a suspect set) but it may never gate and never mark a claim supported. The judgment that ships in CI is reproducible by construction.
This is also why a related signal, trace-link extraction, tops out around 77% precision at 60% recall (or 100% recall at 16% precision). The honest response to a noisy extractor is to auto-suggest, never auto-enforce: Hibi can propose candidate claims, but a human confirms one before it can gate.

​
Prior art & lineage

Hibi is an assembly of ideas that already work, plus a doc side that the closest sibling lacks. Each row is studied, not copied.
The throughline: existing tools either track code-to-code links or annotate prose, but none make a documented sentence’s relationship to code both deterministic and visible in the file. That gap is the whole reason Hibi exists.

​
Where the reasoning becomes mechanics

How it works

Claims, redundant anchors, and the doc-first flow that turns these principles into a verdict.

Verdicts, states & exit codes

The two-axis model, confidence bands, and how precision-over-recall is enforced.

Behavioral claims & verifiers

How Hibi handles claims structural checks can’t prove, without a model on the verdict path.