Doc Status Conventions

Status: Active Last reviewed: 2026-07-20

Defines the doc-status enum, the two supported ways to declare it, and the advisory lint check that reports on coverage. This is a metadata convention, not a mass-edit mandate — existing docs are not rewritten to comply; new/touched docs should follow it going forward.

The status enum

A doc's status must be exactly one of:

Status	Meaning
Active	Current guidance. Trust it for today's implementation.
Draft	In progress / not yet finalized. Direction only, expect changes.
Accepted	A decision has been adopted and is binding (e.g. an accepted ADR).
Reference	Evergreen convention / guide / spec — current and trustworthy, but not itself driving the active roadmap.
Superseded	Replaced by a newer doc. Kept for history; don't implement from it.
Archived	Retired. Historical record only.
Living	An ongoing tracker/log that's continuously updated rather than a point-in-time deliverable (distinct from Active in that it never "completes").

docs/adr/*.md files follow their own established status vocabulary (Proposed / Accepted / Superseded by NNNN / Deprecated — see docs/adr/README.md) rather than this enum. That's expected and not a lint defect.

How to declare a status

Pick one form — both are detected by the lint check:

1. YAML frontmatter (top of file):

---
status: Active
---

2. Top-of-file bold line (the existing convention across most current docs):

**Status:** Active

The value should be the bare enum word, with no trailing narrative — **Status:** Active, not **Status:** Active — living tracker, update in place as fixes ship. A bare value is what the lint check counts as valid; descriptive context belongs in the paragraph below the status line, not appended to it.

Lint check

yarn docs:lint-status (scripts/lint-doc-status.mjs) scans docs/**/*.md — excluding .vitepress/, public/, node_modules/, any *TEMPLATE.md, SKILL.md, and README.md — and reports:

• total files scanned
• files with a valid (in-enum) status
• files missing a status entirely
• files with a status marker whose value isn't one of the six enum words

This check is currently advisory. It always exits 0 and is not wired into yarn docs:check or any pre-push/CI gate. Many existing docs will show up as missing or out-of-enum — most current **Status:** lines carry narrative text (e.g. "Active — living tracker…") rather than a bare enum value, and plenty of docs predate any status metadata at all. That's expected; this convention does not require rewriting them. Bring a doc's status line into the enum the next time you touch that doc for substantive reasons, not as a standalone cleanup pass.