# Status Lifecycle

Every document in a nest carries a **status** that governs where it is in its life and whether retrieval can see it. ContextNest uses a five-state lifecycle — `draft`, `pending_review`, `approved`, `published`, plus the terminal `rejected` — that replaces the older draft / published / superseded model. Status is what lets a governed nest hold work-in-progress and proposals without leaking them into agent context.

## The five states

```mermaid
stateDiagram-v2
    [*] --> draft
    draft --> pending_review
    pending_review --> approved
    pending_review --> rejected
    approved --> published
    rejected --> [*]
```

| Status | Meaning | Visible to retrieval? |
| --- | --- | --- |
| `draft` | Authored, not yet submitted. | Only with `--include-drafts`. |
| `pending_review` | Submitted, awaiting a steward. | No (visible to audits). |
| `approved` | Accepted, not yet live. | No (visible to audits). |
| `published` | Live and retrievable. | **Yes** (default). |
| `rejected` | Terminal — declined. | No (visible to audits). |

Status values are **case-insensitively aliased and normalized**, so equivalent spellings resolve to the same canonical state.

## Retrieval behavior

Retrieval is conservative by default: it returns only `published` documents, so agents never pull unfinished or unapproved content into their context.

- `published` — returned by default.
- `draft` — surfaced only when you pass `--include-drafts`.
- `pending_review`, `approved`, `rejected` — hidden from retrieval, but visible to audits.

This means governance states can accumulate in a nest — proposals in flight, rejected drafts — without polluting what agents see. See [Injection](https://nest.promptowl.ai/d/promptowl-documents/protocol/injection/overview) for how retrieved documents enter agent context.

## Terminal states and revival

`rejected` (and retired) documents are terminal. Attempting to publish one is a **hard error** — the engine raises `RejectedDocumentError` / `SUPERSEDED_DOCUMENT` rather than silently overwriting the decision.

Reviving such a document is deliberate: it is a **two-step transition**, not an implicit re-publish. This keeps a rejected decision from being quietly resurrected and forces an explicit act to bring it back into the lifecycle.

## Related

- [Frontmatter](https://nest.promptowl.ai/d/promptowl-documents/protocol/concepts/frontmatter) — where `status` is declared
- [Injection](https://nest.promptowl.ai/d/promptowl-documents/protocol/injection/overview) — how published documents reach agents
- [Remote & Governed Nests](https://nest.promptowl.ai/d/promptowl-documents/protocol/remote-nests/remote-governed-nests) — review-driven transitions in governed nests

## Sources

Based on the ContextNest engine PRs: #25, #27, #61.