> ## Documentation Index
> Fetch the complete documentation index at: https://hibi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`

```sh theme={null}
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`

```sh theme={null}
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`

```sh theme={null}
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

<CardGroup cols={2}>
  <Card title="Banners" icon="stamp" href="/banners">
    How lifecycle and drift appear in the file itself.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/cli-reference">
    `retire`, `supersede`, `archive`, and the rest of the verbs.
  </Card>
</CardGroup>