Enforcement and Document Lifecycle in Hibi

Claims are enforced, suggested, or retired. Documents are active, superseded, or archived. Three verbs manage both: retire, supersede, archive.

Two separate questions: may this claim gate a build, and where is this document in its life. Hibi answers each with its own field and its own verb.

Enforcement

Enforcement lives on the claim.

Enforcement	Meaning
enforced	The default. May gate a build and may stamp a banner.
suggested	Advisory. Never gates, never warns. Recorded with record --suggest. May have a coarse (--glob) or empty code side.
retired	Withdrawn with hibi retire. Kept for history; ignored by every verdict.

--verified on record is a separate boolean: it records that the author confirmed the code backs the sentence. It does not change enforcement.

retire

hibi retire <claim-id> [--dry-run]

Flips the claim’s enforcement to retired. Idempotent: a second call reports alreadyRetired: true. A retired claim never gates, never warns, is excluded from clean, and is never stamped. Do not delete the file under .claims/ by hand; the record is the audit trail.

Document lifecycle

Lifecycle lives on the document.

Lifecycle	Meaning
active	In the read path.
superseded	Replaced in full by another document. The new document carries a supersedes edge pointing at the old one.
archived	Moved out of the read path with a tombstone at its old path.

A live claim on a superseded or archived document is stranded. hibi list --state stranded lists them. A stranded claim still resolves and can still gate; the document’s lifecycle is added to its banner status.

supersede

hibi supersede --from <old> --to <new> [--dry-run]

In one pass:

1. Registers --to if needed and authors the supersedes edge on it.
2. Flips --from to superseded.
3. Relocates every live claim on --from whose sentence appears verbatim in --to. A relocated claim keeps its id, code side, and history; only its document changes.

The result lists relocated, misses (claims whose sentence was not found verbatim, with a reason), and strandedClaims (the live claims still on the old document after the pass). For each miss, either move it by hand with hibi reanchor <id> --doc <new> --doc-quote "…" (use hibi reanchor <id> --suggest to find the sentence) or withdraw it with hibi retire <id>. When strandedClaims is empty the old file can be deleted or archived without orphaning anything.

archive

hibi archive --doc <path> [--successor <path>] [--dry-run]

Moves the file to archive/, leaves a tombstone at the old path (pointing at --successor when given), and sets the document’s lifecycle to archived. Claims are not moved; the result reports strandedClaims. To withdraw a document that has no successor, archive it without --successor.

Deleting or renaming a document

Claims are content. Move them in the same change as the prose:

1. hibi list --path <old-doc> to see the claims on it.
2. hibi supersede --from <old-doc> --to <new-doc>.
3. Resolve each entry in misses with reanchor or retire.
4. When strandedClaims is empty, delete or archive the old file.

Skipping steps 2 and 3 leaves the claims doc:orphaned after the delete. Orphaned is not retired: it is a live record pointing at a missing file.

Who does what

The engine flags, stamps, and records edges. The author or agent rewrites prose and re-runs hibi check. The engine never writes prose.

Where to go next

Banners

How lifecycle and drift appear in the file itself.

CLI reference

retire, supersede, archive, and the rest of the verbs.