Documentation Item Model

Frozen contract for all documentation governance execution. Do not modify without a new HUMAN REVIEW decision. Source of truth for: classification taxonomy, naming convention, metadata specification, enforcement model.

Classification Taxonomy

Every documentation item in this repo is classified with three fields: <docType> / <concern> / <format>.

docType

docType	What it is
`policy`	Enforced rule or contract, gate-owned
`framework`	Decision model or taxonomy, guidance-level
`catalog`	Generated inventory of a repo surface
`feature-map`	Narrative overview of a repo capability
`tooling-ref`	Reference for a tool, CLI, or workflow
`contributor-guide`	Procedural guide for human contributors
`ai-adapter`	Per-system AI instruction file
`ai-rule`	Standalone AI protocol or safety rule
`registry`	Machine-readable data file (consumed by automation)
`secrets-ref`	Environment variable and secrets documentation
`template`	Reusable authoring template
`component`	UI component, governed by component JSDoc spec (separate)
`script`	Operational script, governed by script JSDoc spec (separate)

concern

Inherits from the script taxonomy. Homogeneous across all item types.

Concern	What it covers
`content`	Docs pages, copy, authoring standards, page taxonomy, veracity
`components`	Component library, registry, naming, documentation
`governance`	Repo structure, scripts, agent docs, manifests, catalogues
`ai`	AI tooling, agent rules, adapter files, skills, discoverability

format

Format	Extension(s)	Metadata approach
`mdx`	`.mdx`	YAML frontmatter
`md`	`.md`	YAML frontmatter
`mdc`	`.mdc`	YAML frontmatter
`json`	`.json`	Registry-only (no inline metadata)
`yaml`	`.yml`, `.yaml`	Registry-only
`jsx`	`.jsx`	Component JSDoc spec (pre-existing, not overridden)
`js`	`.js`	Script JSDoc spec (pre-existing, not overridden)

Directory Convention

Locked (D1): Concern is expressed as a sub-folder within type folders, not as a file prefix. Applies to: policies/, frameworks/, features/, tooling/ Exception: Catalogue files in docs-guide/catalog/ stay flat. Concern is expressed as a filename prefix.

Metadata Specification

Required fields for MDX/MD/MDC files

consumer: [human | agent | automation]
maintenance: generated | hand-maintained | mixed
status: active | draft | deprecated

Conditional fields

generator: path/to/script.js      # required if maintenance = generated or mixed
validator: path/to/script.js      # required if maintenance = hand-maintained or mixed
lastVerified: YYYY-MM-DD          # required if maintenance = hand-maintained

JSON, YAML, ENV files

Registry-only. No inline metadata. Every file of these formats must have a corresponding entry in the governance documentation catalogue.

JSX, JS files

Pre-existing governance specs apply (component JSDoc 7-tag, script JSDoc 11-tag). This model does not override them.

Enforcement Summary

Format	Gate	Mechanism
`.mdx` in `docs-guide/`	`pr-changed` (soft gate)	Required fields check
`.md` adapter files	None currently	Manual until Phase 5 validator
`.mdc` Cursor rules	None currently	Manual until Phase 5
`.json` registry files	None currently	Catalogue entry validator (Phase 5)
`.jsx` components	`pre-commit` (existing)	Component registry validator
`.js` scripts	`pre-commit` (existing)	`script-docs.test.js`

Technical References

Compendium

Knowledge Hub

Changelogs

Documentation Guide

Documentation Item Model

Documentation Item Model

Classification Taxonomy

docType

concern

format

Directory Convention

Metadata Specification

Required fields for MDX/MD/MDC files

Conditional fields

JSON, YAML, ENV files

JSX, JS files

Enforcement Summary

​Documentation Item Model

​Classification Taxonomy

​docType

​concern

​format

​Directory Convention

​Metadata Specification

​Required fields for MDX/MD/MDC files

​Conditional fields

​JSON, YAML, ENV files

​JSX, JS files

​Enforcement Summary

Documentation Item Model

Classification Taxonomy

docType

concern

format

Directory Convention

Metadata Specification

Required fields for MDX/MD/MDC files

Conditional fields

JSON, YAML, ENV files

JSX, JS files

Enforcement Summary