23.1. Design document lifecycle

Design documents record why a change was considered and how its design evolved. They are not the normative specification after a design has been implemented. Implemented protocol behavior belongs in the API specification; implementation, deployment, and operational behavior belongs in the corresponding reference manual.

23.1.1. Required metadata

Every numbered design document must begin with these fields:

Design status

The state of the design decision. The allowed values are Draft, Proposed, Accepted, Experimental, Superseded, Rejected, and Abandoned.

Implementation status

The state of the described implementation. The allowed values are Not started, Prototype, Partial, Implemented, Removed, Unknown, and N/A.

DD shepherd

The person currently responsible for moving the design forward and keeping its status accurate. Use TBD when no current shepherd has agreed to take responsibility; historical authorship is not an assignment of current ownership.

Historical contributors

The people who made substantive contributions to the design text. Do not include authors of repository-wide formatting-only changes.

First published

The ISO date of the first commit containing substantive content for this DD. Copied template or predecessor-file history does not count.

Last substantive change

The ISO date of the newest commit that changed the design’s meaning. Pure spelling, formatting, build, or title-normalization changes do not count.

The following fields are added when applicable:

Implementation evidence

Repositories and ISO dates that establish a prototype, landing, completion, or removal. Work that is present only on a feature branch must be identified as such and has implementation status Prototype.

Superseded by

The successor design or normative specification.

Normative references

The API specifications and reference manuals that now own the implemented behavior.

Upstream follow-up

A discrepancy whose authoritative source is generated by, or maintained in, another repository. Generated files in this repository must not be edited by hand.

23.1.2. Interpreting lifecycle states

The two status fields are deliberately independent. For example, a design can be Superseded while its historical implementation remains Implemented. A feature that has substantial implementation only on a non-main branch is a Prototype, not Partial or Implemented. Policy documents use N/A unless they define measurable software or platform deliverables.

Titles beginning with XX are a legacy visual marker for deprecated design documents. They are retained for historical continuity, but the metadata fields are authoritative.

23.1.3. Maintaining design documents

When a feature lands, update its implementation status and evidence, check only Definition-of-Done items supported by repository or API evidence, and add the normative references. Preserve useful historical discussion, but place a prominent note before stale material so readers do not mistake it for current behavior. Unresolved product, security, or legal questions must remain explicit instead of being silently resolved from implementation accidents.