Document Lifecycle¶

This document describes how a document moves through its status field over time. See document-metadata-standard.md for the definition of each status value, and decision-rights.md for who holds which role.

Lifecycle stages¶

draft ──▶ proposed ──▶ approved ──▶ deprecated
                             │
                             └────▶ superseded

draft¶

Any contributor (human or AI agent) may create or edit a draft document. A draft represents current thinking, not yet reviewed for completeness or accuracy. Multiple revisions within draft do not require approval.

draft → proposed¶

Moved by the document's owner (per its owner field) once the content is believed complete and correct and ready for human review. An AI agent may prepare a document up to proposed status (recommending the move) but the actual transition to proposed should reflect that the responsible owner considers it ready — see docs/ai/human-review-and-approval.md.

proposed → approved¶

Requires explicit human approval from a role with decision rights over that document type (see decision-rights.md). An AI agent must never set status: approved itself. Approval should be recorded — e.g. via PR review/merge once a remote exists, or noted explicitly in a work log under work/ in the interim — and effective_date and last_reviewed set at that time.

proposed → draft¶

A proposal can be sent back to draft if review surfaces gaps. This is a normal, expected part of the cycle, not a failure.

approved → deprecated¶

Used when a document is no longer recommended but there is not yet a specific replacement. Deprecation is itself a decision requiring the same approval authority as the original approval.

approved → superseded¶

Used when a document is explicitly replaced by a named successor. The successor document sets supersedes: <old document_id>; ideally the superseded document is also updated with a pointer forward. Superseding requires the same approval authority as approving the original document.

Who can move a document between states¶

Transition	Who
Create / edit draft	Any contributor (human or AI agent)
draft → proposed	Document owner
proposed → approved	Human with decision rights for that document type (see decision-rights.md)
proposed → draft	Document owner or reviewer
approved → deprecated / superseded	Human with decision rights for that document type

Review cycle expectations¶

review_cycle (e.g. annual, quarterly) states the maximum interval between reviews for an approved document.
last_reviewed should be updated whenever a review occurs, even if no content changes.
A document past its review_cycle interval since last_reviewed is not automatically invalid, but should be flagged as due for review — see docs/ai/validation-requirements.md for how tooling may surface this.

What triggers a review¶

The review_cycle interval elapsing.
A change to a company-level policy or standard that a lower-level document depends on (see authority-and-inheritance.md).
A contradiction being surfaced against the document (see authority-and-inheritance.md).
A material change in the underlying venture, product, or regulatory context.
Discovery of an error or an outdated claim.

See change-management.md for how the scope of a change determines what process (simple edit vs. ADR vs. human approval) is required.

Report an issue about this page