Skip to content

ADR-0007: Unified Front Matter and Progressive Documentation Topology

Status

Proposed

Context

The blueprint documentation has expanded beyond a comfortable flat structure. Several sections now contain enough material that readers must hop between sibling pages without a clear progressive path.

At the same time, earlier front matter systems introduced overlapping and now-retired concepts such as qid, qi_decimal, graph-poetry attributes, and realm-driven structural meaning. The current blueprint doctrine already establishes that front matter is supportive metadata only, not the system of record, and that canonical truth comes from governed system layers rather than file headers. :contentReference[oaicite:1]{index=1} :contentReference[oaicite:2]{index=2}

A unified, lean, enforceable front matter profile is required, along with a documentation topology that preserves reading order and reduces cognitive load.

Decision

QiOS adopts the following documentation and metadata rules:

  1. Universal Front Matter Vocabulary
  2. All markdown documentation within the blueprint uses one shared front matter vocabulary.
  3. The layout field determines document intent and conditional requirements.

  4. Required fields may vary by layout, but the field vocabulary remains singular.

  5. Front Matter Is Supportive Metadata Only

  6. Front matter does not issue canonical identity.
  7. Front matter does not define schema placement, routing truth, or graph truth.

  8. Legacy fields tied to retired identity/ontology models are removed from active doctrine.

  9. Canonical Field Order

  10. Front matter fields must appear in a governed order.
  11. Fields are grouped into human-readable sections.

  12. A formatter/linter will normalize order and validate layout-specific requirements.

  13. Progressive Documentation Topology

  14. Each major blueprint section may contain ordered subfolders.
  15. Subfolders must support a progressive reading path from overview to model to rules to reference.

  16. Documentation should read linearly within a section rather than as a flat bucket of peer pages.

  17. Canonical Source Separation

  18. docs/ remains the rendered doctrine layer.
  19. standards/, registry/, adr/, and schemas/ remain canonical source layers outside docs/.
  20. The documentation site may render or summarize those sources through pages in docs/, but they do not move into docs/ merely for visibility.

Consequences

Positive

  • Reduces front matter drift and overlapping taxonomies.
  • Makes documentation easier to read in sequence.
  • Preserves separation between rendered doctrine and machine-readable source-of-truth files.
  • Creates a stable template and validation model for future growth.

Negative

  • Existing docs will need normalization and partial folder moves.
  • MkDocs navigation must be updated to reflect second-layer section structure.
  • Some legacy front matter fields and earlier taxonomy experiments will be formally retired.

Affected Documents

  • standards/content_metadata_profile.yaml
  • standards/metadata_rules.yaml
  • templates/page_template.md
  • templates/adr_template.md
  • templates/artifact_template.md
  • scripts/normalize_front_matter.py
  • mkdocs.yml
  • docs/01_governance/*
  • docs/02_architecture/*
  • docs/03_structure/*
  • docs/04_data/*
  • docs/05_compute/*
  • docs/06_applications/*
  • docs/07_operations/*