PromptOwl + ContextNest Docs
Contents

Status Lifecycle

Updated Open in ChatGPTOpen in Claude

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

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 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.

Sources

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

Related pages

  • Remote & Governed NestsA nest does not have to live on your local disk. ContextNest can register remote nests and route reads and writes to them over MCP — the same ctx commands…
  • Governance & StewardshipGovernance is how a nest keeps its AI-readable surface trustworthy. Every document moves through a review lifecycle, and only approved content is ever…
  • FrontmatterEvery Context Nest document begins with a YAML frontmatter block delimited by ---. The frontmatter contains structured metadata that the resolver…
  • Context IndexThe context.yaml file is the machine-readable manifest of a Context Nest vault. It is auto-generated by the CLI and serves as the primary entry point for…
  • Core ConceptsContext Nest is built on a small set of composable concepts. Understanding these gives you the full picture of how vaults work.

Referenced by