Skip to main content
Hibi is not a thing you run on a schedule and forget. It’s a thing you reach for at specific moments — the instant before you trust a doc, the instant after you change code, the instant you fold a draft into a permanent page. The moments below are grouped by intent: Author grounded prose for new code, Verify / Maintain what already exists, and Prune what no longer earns its place. Each moment is a real problem, the one command that answers it, and what you do with the answer. (For the same flows as an agent-facing playbook with raw JSON, see the hibi skill cookbook.) The running example: a service with src/retry.ts (MAX_ATTEMPTS = 5) and src/auth.ts (TOKEN_TTL_MIN = 30), a README.md, and a CLAUDE.md telling an agent “Auth tokens expire after 30 minutes.”

​
Author

​
1. Write grounded docs for a fresh feature

The problem. You just built a feature and you’re writing the doc that describes it. You want every sentence that makes a promise about the code to be anchored to the code that keeps it — so the doc can never quietly drift once it ships. The commands.
The payoff. Write the doc, then let coverage list the ungrounded blocks — the deterministic worklist. Author a claim per promise and record the set transactionally (record --from-file; every spec is validated before any write, so a typo fails the batch loudly rather than half-recording it). You’re done when coverage comes back clean. Behavioral sentences (“retries use exponential backoff”) get a command: verifier at authoring time, so hibi check --run-verifiers can prove them later. A doc quote shorter than 8 characters, or a repeated sentence the surrounding context can’t disambiguate, is refused at record time — the anchor has to be able to find its span again.

​
2. Verify built code against a pre-existing plan

The problem. You have a plan (an RFC, a spec, a design doc) and code that claims to implement it. Which promises in the plan are actually built, and which are still vapor — or were quietly dropped? The command.
The payoff. --fail-uncovered exits 2 (the gating code) while any block of the plan is ungrounded, so “this plan must be fully grounded” becomes CI-enforceable — an uncovered block is an unimplemented (or unpruned) plan item. Behavioral promises get verifiers; hibi check --run-verifiers proves them.
The honesty rule (read this). hibi never judges whether code implements a sentence — the author/agent judges by anchoring each promise to its implementing code (a sentence you cannot anchor is an unimplemented plan item); hibi makes the judgment enforceable and guards it afterward.

​
Verify / Maintain

​
3. Trust-check before you follow an instruction file

The problem. Your CLAUDE.md / AGENTS.md / README tells you how the code behaves. But docs rot silently — the moment you act on a stale instruction, you ship a bug that the doc told you to ship. You can’t eyeball every claim against the code before trusting it. The command.
The payoff. Hibi re-verifies every claim in that file against the current code and gives you a one-word decision: current: false (exit 2) means an instruction drifted. The verdict shows the shape — doc: unchanged · code: changed means the sentence is intact but the code it describes moved out from under it (someone changed the token TTL to 60 minutes; the file still says 30). You now know not to blindly trust the 30-minute rule, and the verdict’s remediation menu hands you the exact command to fix it. This is the natural SessionStart moment for an agent: check the instruction file before the session trusts it.

​
4. Keep docs honest in the same PR as the code change

The problem. You changed a constant. Somewhere in the docs, a sentence just became a lie — but you don’t remember which, and “update the docs” is the step everyone skips. Drift accumulates one forgotten sentence at a time. The command.
The payoff. Hibi evaluates only the claims whose anchored file changed since the ref (the write-time loop — it lists the changedFiles), and its documents array names exactly which docs your edit broke. Each gating verdict carries a remediation menu with the fix command pre-filled. The doc fix lands in the same PR as the code change, while you still remember why. Add --explain to see what moved (changedEvidence points at the literal value), or read the concise changed field for a one-line summary. This is the natural Stop / pre-commit moment.

​
5. See the blast radius before you refactor

The problem. You’re about to refactor src/auth.ts. What promises does the rest of the repo make about this file? Which sentences will quietly become wrong if you change its behavior? Grep won’t tell you — the doc and the code live apart. The command.
The payoff. Every claim anchored to that path, on either side, with its assertion.id, the documented sentence, and which side matched. In the example, two enforced claims ride on src/auth.ts — one in README.md, one in CLAUDE.md, both asserting the 30-minute TTL. Now you refactor knowing the contracts you must not silently break, and you already hold the ids you’ll reanchor (if still true) or retire (if now wrong) afterward.

​
6. Go from zero to protected on an existing repo

The problem. A repo has docs but no claims. Hand-authoring an anchor for every sentence is tedious enough that it never happens, so nothing is protected. The commands.
The payoff. init creates the committed .claims/ store; coverage segments the doc into blocks and reports which are backed by a claim vs uncovered — the deterministic worklist for a grounding audit. Ground the uncovered executable: true blocks first (fenced sh/bash/… examples): they can carry a command: verifier and reach a behavioral verdict, so coverage flags them as the highest-value targets. Then walk the rest and decide ground-or-prune: anchor the ones a code span backs, cut the ungrounded prose. Hibi never auto-extracts claims (no model in the loop); the judgment stays with you, and check guards the result. You’ve gone from unprotected docs to a tracked, gating store with every remaining sentence confirmed in code. Where claims declare verifiers, hibi check --run-verifiers also executes them — a pass upgrades the behavioral belief to supported, a fail gates as refuted; plain check never spawns a verifier process. When you (or an agent) already know the code that backs each sentence, author the whole set in one pass instead of one record per claim — no shell-quoting of verbatim spans:
Every spec is validated before any write, so a typo fails the batch loudly rather than half-recording it. See record --from-file.

​
7. Consolidate a doc and bring its claims along

The problem. You merged a doc into another, renamed it, or folded a draft into a permanent page. Every sentence those claims tracked now lives in a different file — but the claims still point at the old one. Re-anchoring each by hand is exactly the tedious step that gets skipped. The command.
The payoff. relocate re-homes every live claim stranded on --from onto --to in one pass. A claim is moved when its documented sentence appears verbatim in the target; each move rides the same reanchor machinery, so it keeps the claim id, owner, trust, history, and code side — it moves the claims, it doesn’t retire-and-recreate them. The old file is left untouched as audit and no longer carries the claims, so you can delete it without orphaning anything. Add --dry-run to preview first. Claims whose sentence is absent from the target are never dropped silently — they come back in the misses list for you to hibi reanchor (to a different target) or hibi retire by hand. This is the batch companion to the single-claim hibi reanchor <id> --doc …; it is not supersession, which records a document-to-document edge rather than relocating claims.

​
8. Silence a known-good at-risk

The problem. A behavioral claim went at-risk because a file in its evidence set changed — say a helper that src/retry.ts imports. You re-verified by hand: the behavior still holds. But the flag keeps resurfacing on every run, and reanchor is the wrong verb — nothing about the anchor moved. The command.
The payoff. ignore acknowledges the current changed evidence: it records the acknowledged { path → hash } map and your reason (required) on the claim. While that evidence stands still, the at-risk is non-gating and surfaces as suppressed: true in the JSON. The suppression lapses on its own the moment any acknowledged path changes again or a new evidence path appears — you silenced one inspected change-set, not the claim. If you find yourself ignoring the same claim repeatedly, that’s the cue to declare a verifier and let hibi check --run-verifiers do the re-verification for you — the run-verifier remediation action even names the tests that already exercise the anchored code, so you know which one to promote into a command: verifier.

​
9. Recover an orphaned claim

The problem. A claim went orphaned — its documented span was deleted or moved somewhere reanchor can’t find on its own. A bare reanchor has no target to relocate to, and you don’t want to hand-hunt every doc for where the sentence went. The commands.
The payoff. --suggest is read-only — it never writes the store or a document, and it refuses every mutation flag. It takes the claim’s stored doc quote, localizes it against every registered document, and prints the ranked candidate targets (path, span, similarity, snippet). Inspect them, then either re-anchor to the one you chose with an explicit --doc-range (D15’s attestation rules still apply — re-anchoring without --ref downgrades verified trust) or hibi retire the claim if the sentence is gone for good.
The pure-move case. If the sentence turns up byte-identical at a new offset and the code side is still unchanged, re-anchoring it does not downgrade trust — a byte-shift is evidence-neutral, so there is nothing to re-attest (D25). Anything fuzzier (a reword, a changed code side) downgrades exactly as a no---ref reanchor always has.

​
Prune

​
10. Prune the ungrounded

The problem. A doc has grown prose that no code backs — aspirational sentences, stale promises, notes that never became claims. You want a deterministic worklist of what to cut, not a vibe. The commands.
The payoff. Two deterministic signals feed the prune decision. coverage uncovered blocks were never grounded — ground them (if a code span backs the sentence) or cut them. list --state orphaned are claims whose grounding died — the code-side span is gone, so retire the claim and cut the sentence it tracked. hibi hands you the worklist; you make the call.
Read this caveat. “uncovered” means “no claim recorded,” not “no code backs it” — hibi provides the worklist, the author makes the prune call.

​
Triage anytime

Between those moments, one command answers “what’s red right now?” without making you parse a full report:
One lean row per claim — the claimId, the doc and code paths, the status, and the recommended action — most-severe-first. Decide intent, then act on the row’s handle: hibi reanchor <id> if the claim still holds, hibi retire <id> if it’s obsolete (idempotent, keeps the audit trail). Swap the filter for the cut you need — --state orphaned for un-relocatable claims whose span was deleted (recover them with reanchor --suggest, moment 9), --state suggested for the advisory claims that never got enforced — and add --ids-only to pipe the bare id list straight into a for id in $(…) loop.

​
How to respond to a flag

Across all of these, a flag is the start of a decision, not a banner to silence. Every drift verdict carries a deterministic remediation menu: read recommended (the unambiguous next step, or null when intent matters), pick an action, and either run its pre-filled command (reanchor/retire, or the read-only reanchor --suggest on an orphan) or do the prose work it names (fix the code, rewrite the sentence). You never rewrite a doc just to make a flag go away — you re-verify, then act.