Documentation Standards¶

Status: Accepted Authority: This document is normative for documentation structure and metadata. All docs under docs/ MUST conform to the content type taxonomy and frontmatter schema defined here. Scope: Documentation classification, metadata, and structure. Does NOT govern content accuracy (that is the domain of individual doc owners and SSOT atoms).

1. Content Type Taxonomy¶

Every document under docs/ declares exactly one content type. The type determines who the doc serves, what language it may use, and how it is enforced.

Type	Authority	Audience	MUST/SHALL allowed?	Location constraint	Examples
`normative`	Defines rules	Agents, CI, reviewers	Yes	`docs/governance/`	`morphism-kernel.md`, this file
`operational`	Implements rules	Contributors, SREs	No (quote normative source)	Any	Runbooks, onboarding, workflow prompts
`reference`	Explains concepts	Anyone	No	Any	`MORPHISM.md`, `morphism-theory.md`
`historical`	Records decisions	Auditors	No	Any	ADRs, audit reports, migration records

Rules:

normative docs MUST reside in docs/governance/ (exception: docs/standards.md — this file).
operational and reference docs MUST NOT introduce new MUST/SHALL statements; they MAY quote normative sources using blockquotes (>).
historical docs are immutable after acceptance. Amendments require a new ADR.

2. Frontmatter Schema¶

All docs under docs/ (excluding docs/ssot/atoms/) MUST include YAML frontmatter. The following fields are defined:

Required fields¶

Field	Type	Values	Purpose
`type`	string	`normative`, `operational`, `reference`, `historical`	Content classification per Section 1
`authority`	string	`canonical`, `derived`, `non-normative`	Source authority level

Optional fields¶

Field	Type	Values	Purpose
`audience`	list	`agents`, `contributors`, `sre`, `leadership`, `public`	Intended readers
`ssot-atom`	string	Atom ID from `docs/ssot/registry.json`	Links doc to SSOT atom
`last-verified`	date	`YYYY-MM-DD`	Last accuracy review date
`scope`	string	Free text	Maps to I-4 (Scope Binding)
`status`	string	`authoritative`, `derived`, `draft`, `archive`	Active-state classification for product/platform docs under the remediation contract
`owner`	string	Free text	Maintainer or team responsible for the doc's accuracy
`code-paths`	list	Repo-root-relative file or directory paths	Implementation surfaces the doc claims to describe
`runtime-surfaces`	list	Free text	Apps, packages, services, jobs, or other runtime surfaces covered
`depends-on`	list	Free text	External or internal dependencies the doc relies on

Authority levels¶

Level	Meaning	Example
`canonical`	Single source of truth for its domain. Changes here propagate outward.	`morphism-kernel.md`, `incident-response.md`
`derived`	Synthesizes or references canonical sources. MUST NOT contradict them.	`MORPHISM.md`, `INVENTORY.md`
`non-normative`	Informational only. No enforcement weight.	`worked-example.md`, ADRs

Documentation contract fields¶

The documentation remediation work adds a stricter contract for code-coupled product and platform docs.

Docs that declare any of status, owner, code-paths, runtime-surfaces, or depends-on are treated as contract-participating docs and validated by python scripts/docs_contract.py --check.
Contract-participating docs MUST include last-verified, status, and owner.
status: authoritative docs MUST use authority: canonical and MUST declare code-paths plus runtime-surfaces.
code-paths entries MUST be repo-root-relative and MUST exist.
Diff-aware checks run when scripts/docs_contract.py receives a commit range (or staged/working-tree scope). In that mode:
changed contract docs MUST update last-verified
changes to file-level code-paths in authoritative docs MUST touch the mapped doc in the same change

3. SSOT Marker Placement¶

Docs linked to an SSOT atom SHOULD wrap their canonical content in markers:

{!-- SSOT:atom-id:begin --}
... canonical content ...
{!-- SSOT:atom-id:end --}

(In actual files, replace {!-- / --} with standard HTML comment delimiters )

Markers MUST enclose only the content that is governed by the atom — not the entire file. The ssot-atom frontmatter field MUST match the marker ID.

4. Section Ordering by Type¶

Normative docs¶

YAML frontmatter
H1 title
Status / Authority / Scope header block
SSOT-marked canonical content
Amendment process
Non-normative references (footer)

Operational docs¶

YAML frontmatter
H1 title
Purpose (1-2 sentences)
Prerequisites
Procedures / steps
References to normative sources

Reference docs¶

YAML frontmatter
H1 title
NON-NORMATIVE banner (> **NON-NORMATIVE.** ...)
Overview / abstract
Body
References

Historical docs (ADRs)¶

YAML frontmatter
H1 title (ADR number + title)
NON-NORMATIVE banner
Status, Date, Decision Makers
Context, Decision, Consequences
References

5. Templates¶

Normative doc template¶

---
type: normative
authority: canonical
audience: [agents, contributors]
scope: <domain>
---

# <Title>

<!-- KERNEL_NORMATIVE: false -->

**Status:** Accepted
**Authority:** This document is normative for <domain>.
**Scope:** <what it governs>. Does NOT govern: <exclusions>.

---

## Rules

{# SSOT:<atom-id>:begin #}
...
{# SSOT:<atom-id>:end #}

---

## Amendment Process

...

---

*References: ...*

Operational doc template¶

---
type: operational
authority: derived
audience: [contributors]
---

# <Title>

<Purpose sentence.>

## Prerequisites

...

## Procedure

...

## References

- Source doc (link to normative authority)

Reference doc template¶

---
type: reference
authority: non-normative
audience: [contributors, public]
---

# <Title>

> **NON-NORMATIVE.** This document explains concepts; it does not define rules.
> Normative rules are in [morphism-kernel.md](governance/morphism-kernel.md).

...

Historical doc template (ADR)¶

---
type: historical
authority: non-normative
---

# ADR-NNN: <Title>

> **NON-NORMATIVE.** This is a decision record, not a rule source.

**Status:** Accepted | Superseded | Deprecated
**Date:** YYYY-MM-DD

## Context

...

## Decision

...

## Consequences

...

Scope¶

This document governs: content type classification, YAML frontmatter requirements, section ordering, and doc templates for all files under docs/.

This document does NOT govern: content accuracy, SSOT atom extraction mechanics, CI pipeline configuration, or application code documentation.