Documentation Naming and Versioning

Status: Canonical Last Updated: 2026-02-06 Owner: Engineering

Purpose

This document defines the mandatory naming, versioning, and lifecycle rules for all documentation within the /docs directory.

It ensures that documentation is:

• Discoverable
• Unambiguous
• Stable over time
• Safe for both human readers and AI execution agents

This document is authoritative and overrides all non-governance documents.

Scope

These rules apply to:

• All documentation under /docs
• All contributors (human and AI)
• All branches and environments

No exception exists unless explicitly documented here.

File Naming Standards

General Rules

• File names MUST be lowercase
• Words MUST be separated by hyphens
• File names MUST be descriptive and explicit
• Abbreviations SHOULD be avoided unless industry-standard

Examples:

• authz-and-roles.md
• data-retention.md
• rate-limits-and-abuse.md

Document Type Suffixes

The following suffixes are mandatory:

No other suffixes are permitted.

Directory-Based Semantics

Document meaning is determined by directory placement.

Misplaced documents MUST be relocated.

Versioning Model

Default Rule

Documentation is versioned implicitly via Git history.

• No version numbers in filenames
• No semantic versioning in headers
• Git is the source of truth

Explicit Versioning (Exceptions)

Explicit version numbers MAY be used ONLY when:

• Required for regulatory or audit reasons
• Documenting external contracts or APIs
• Capturing immutable third-party terms

If used:

• Version MUST appear in the document header
• Version MUST NOT appear in the filename
• Version changes MUST be documented

Draft Lifecycle (.new.md)

Files suffixed with .new.md indicate:

• Draft or placeholder status
• Not yet authoritative
• Subject to change without migration guarantees

Rules:

• .new.md files MUST NOT be referenced as authoritative
• .new.md files MUST be reviewed before promotion
• Promotion occurs by removing .new from filename

Promotion to Canonical

A document is considered canonical when:

• The .new suffix is removed (if present)
• Status is marked as Canonical
• Content complies with governance and contracts

Canonical documents MUST NOT be renamed casually.

Renaming and Deprecation

Renaming Rules

• Renaming a canonical document requires justification
• References MUST be updated atomically
• Renames SHOULD preserve Git history

Deprecation Rules

When a document is deprecated:

• It MUST remain in the repo
• It MUST be clearly marked as Deprecated
• A replacement MUST be referenced if applicable

Documents MUST NOT be silently removed.

Cross-Document References

• References MUST use relative paths
• References MUST point to canonical documents
• Broken references are considered defects

Example reference format:

• docs/contracts/authz-and-roles.md

AI Execution Requirements

When used by Codex or other AI agents:

• File paths and names MUST be trusted
• Directory semantics MUST be respected
• AI agents MUST NOT invent filenames or locations
• Ambiguous references MUST halt execution

Non-Negotiable Rules

• Naming conveys meaning.
• Directory placement conveys authority.
• .new.md is non-authoritative by definition.
• Git history is the version history.
• Governance documents override all others.

References

• docs/governance/doc-authority.new.md

End of Document