Skip to content

Document Authority Metadata Standard

Parent contract: Documentation Governance Standard Version: 1.0 Applies to: All documents in the BluCity-Docs canonical hierarchy.

Purpose

Every document in the canonical hierarchy must declare its authority class in YAML front matter.

This makes the "author once, project many" principle machine-readable. It is immediately clear to both humans and AI agents whether a document is the source of truth, a derived projection, or an immutable evidence artifact — without reading the content.

Authority Classes

canonical

Authored by a human, reviewed, version-controlled. The source of truth for its domain.

---
authority: canonical
owner: Engineering-Standard            # or Products, Playbooks, etc.
source_of_truth: true
generated: false
supersedes: []                         # paths this document replaces
superseded_by: null                    # path of successor if archived
---

Rules: - Edited directly via Git workflow. - Must pass documentation review before merge. - When superseded, superseded_by must be set before the document moves to /Archives.

projection

Machine-derived from a canonical source. Never edited directly.

---
authority: projection
projection_of: Engineering-Standard/authority/portfolio-registry.yaml
generated: true
generator: portfolio-importer          # tool or pipeline that produced this
editable: false
---

Rules: - Editing a projection directly is a policy violation. The source canonical document must be updated instead. - Projections must name their projection_of source. An orphaned projection is invalid. - Regenerating a projection from its source always supersedes the prior projection.

evidence

Produced by an execution. Immutable after creation.

---
authority: evidence
produced_by: blu portfolio audit       # command or process
produced_at: 2026-07-13T21:00:00Z
editable: false
---

Rules: - Evidence documents are append-only. Never edited after creation. - Corrections are issued as new evidence documents that reference the original. - Evidence supports standards. Evidence never becomes the standard itself. - Storage: /Evidence/ hierarchy within BluCity-Docs.

Classification Rules

  1. Every document has exactly one authority value: canonical, projection, or evidence.
  2. Documents without front matter are unclassified and must not leave /Needs-Curation.
  3. A projection document must name its projection_of source.
  4. A canonical document that supersedes another must list the superseded path in supersedes.
  5. A superseded canonical document must set superseded_by before archival.
  6. editable: false is enforced by convention; CI may enforce it structurally.
  7. Every Bluefly-owned document must include bluefly_document: true, created_at, and updated_at in its front matter.

Timestamp Governance

Every Bluefly-owned Markdown document carries machine-readable timestamps in its YAML front matter.

Fields

Field Type Rule
bluefly_document boolean true marks the file as Bluefly-owned and subject to governance.
created_at ISO 8601 + tz Set once at creation. Never modified after initial creation.
updated_at ISO 8601 + tz Updated on substantive content changes only.

Timestamps use full ISO 8601 with explicit timezone offset:

2026-09-12T00:22:00-04:00

Front-matter merge rule

These fields are added to any existing front-matter block — never as a second block.

Correct (single block with all fields):

---
authority: canonical
owner: Engineering-Standard
source_of_truth: true
bluefly_document: true
created_at: 2024-11-16T13:42:21-05:00
updated_at: 2026-09-12T00:22:00-04:00
---

Incorrect (duplicate blocks — hard failure):

---
bluefly_document: true
created_at: 2026-09-12T00:22:00-04:00
updated_at: 2026-09-12T00:22:00-04:00
---

---
authority: canonical
owner: Engineering-Standard
---

Substantive change definition

A substantive change alters the meaning or content of the document. Update updated_at only for substantive changes.

Not substantive (do not update updated_at): - Formatting normalization (whitespace, line endings) - Governance block repair (adding missing fields, fixing footer) - Tool re-runs with no content diff - Timestamp-only edits (this is itself a CI failure: TIMESTAMP_CHURN)

created_at provenance (migration)

For existing files without created_at:

  1. If an existing created_at value is present → preserve it.
  2. If Git history reliably identifies the introduction commit → use git log --follow --diff-filter=A --format=%aI.
  3. Otherwise → use the migration timestamp.

Git remains the actual provenance ledger. created_at is a convenience field, not a competing authority.

Every Bluefly-owned Markdown document carries a static governance footer as an HTML comment at the end of the file.

<!-- BLUEFLY-DOC-GOVERNANCE
This is a governed Bluefly document.

Agents and humans making substantive changes MUST:
1. update `updated_at` in the YAML front matter;
2. never alter `created_at`;
3. preserve this governance block;
4. preserve authoritative content and provenance.
-->

Rules

  • The footer is an HTML comment — invisible in rendered Markdown, visible in source.
  • Machine-parseable via the <!-- BLUEFLY-DOC-GOVERNANCE sentinel.
  • No timestamp in the footer. The single timestamp authority is the front-matter updated_at.
  • The footer text is static and identical across all documents — it never varies per file.
  • Presence or absence of the sentinel is the enforcement signal for CI.

Enforcement

The check-doc-governance.mjs tool (in gitlab_components) checks and fixes governance compliance:

node check-doc-governance.mjs check [scan_root]         # read-only validation
node check-doc-governance.mjs fix [scan_root]            # idempotent application
node check-doc-governance.mjs check --diff-base <sha>    # CI/Lefthook mode

CI enforcement (via gitlab_components) checks only files changed in an MR — not the full estate.

Ownership Matrix

Authority Class Editable Lives In Example
canonical Yes (via Git) Engineering-Standard, Products, Playbooks This document
projection No Anywhere (must name source) Generated registry views
evidence No (append-only) Evidence/ Audit receipts, test results

Relationship to Other Standards