Workflows: When to Run Which Hibi Command

Eight moments, each with the one command that answers it: trust-check, post-change check, blast radius, grounding audit, plan gating, triage, document consolidation, orphan recovery.

Each section is a moment, the command for it, and what to do with the result. The same flows appear as an agent playbook with raw JSON in the skill cookbook.

Running example: src/retry.ts (MAX_ATTEMPTS = 5), src/auth.ts (TOKEN_TTL_MIN = 30), a README.md, and a CLAUDE.md that says “Auth tokens expire after 30 minutes.”

1. Trust-check before following an instruction file

hibi check --doc CLAUDE.md

Exit 2 means a sentence in the file no longer matches the code. doc: unchanged, code: changed means the sentence is intact and the code moved. Do not act on that sentence as written. The verdict’s remediation.recommended is update-claim: rewrite the sentence if it is now wrong, then run hibi reanchor <id>.

2. Keep docs honest in the same PR as the code change

hibi check --since origin/main

Only claims touching a file changed since the ref are evaluated. changedFiles lists the files; documents names the docs whose sentences the edit invalidated. Fix the prose in the same PR. --explain adds evidence.changedEvidence when the one-line changed field is not enough. An unknown ref exits 1.

3. See the blast radius before you refactor

hibi list --path src/auth.ts

One row per claim anchored to that path on either side, with claimId, text, documentPath, codePath, status, severity, enforcement, recommended, and side. Keep the ids: after the edit you reanchor the claims still true and retire the ones now wrong.

4. Go from zero to protected on an existing repo

hibi init
hibi coverage --doc README.md

coverage splits the document into sentence-level regions and reports each as covered or uncovered, with a coverageRatio. Hibi does not extract claims from prose. For each uncovered region, either record a claim (a code span backs the sentence) or remove the sentence (nothing does). Record the grounded set in one batch:

echo '[{"doc":"README.md","docQuote":"Requests are retried up to 5 times before failing.",
        "codeFile":"src/retry.ts","codeQuote":"MAX_ATTEMPTS = 5","verified":true}]' \
  | hibi record --from-file -

The batch is validated before any write; a bad item fails the whole batch. New claims are enforced by default; pass "suggest": true for an advisory claim. Re-run coverage to confirm the ratio rose, then hibi check.

5. Verify built code against a plan

hibi coverage --doc plan.md --fail-uncovered

Exit 2 while any region of the plan is uncovered, 0 once every region is backed by a claim. A sentence you cannot anchor to code is an unimplemented plan item. Give behavioral promises a --verifier command:"…" and prove them with hibi check --run-verifiers.

6. Triage

hibi list --state gating

One row per gating claim, most severe first. Act on each row’s claimId: hibi reanchor <id> if the sentence still holds, hibi retire <id> if it is obsolete. Other filters: warning, clean, orphaned, suggested, stranded (live on a superseded or archived doc), duplicate (a sentence claimed more than once). --ids-only prints bare ids for a shell loop.

7. Consolidate a document and bring its claims along

hibi supersede --from docs/old.md --to docs/merged.md

Authors the supersedes edge, flips the old document to superseded, and relocates every live claim whose sentence appears verbatim in the new document. Claims whose sentence was reworded or cut come back in misses; strandedClaims lists what is still on the old document. Resolve each miss with hibi reanchor <id> --doc docs/merged.md --doc-quote "…" or hibi retire <id>. When strandedClaims is empty, delete or archive the old file. Add --dry-run to preview.

8. Recover an orphaned claim

hibi reanchor asrt_1a2b3c --suggest
hibi reanchor asrt_1a2b3c --doc docs/retry.md --doc-quote "Retries are capped at 5 attempts"

--suggest is read-only. It ranks candidate locations for the stored doc quote across every registered document and for each code quote across files in the same language; each candidate has side, file, start, end, similarity, snippet. Reanchor to the one you pick with an explicit span. reanchor refuses to proceed on a side that was not found unless you pass a new span for it. If no candidate fits, hibi retire asrt_1a2b3c.

How to respond to a flag

Every suspect verdict carries a remediation menu. Read recommended, run its command, or do the prose work its title names. Do not rewrite a sentence to make a banner go away; re-verify, then act.