STD-001

Standards-as-Code Source Metadata

OSERA standards use human-authored Markdown with structured YAML front matter as the machine-readable source of truth.

Status: Draft
Version: 0.1.0
Pack: OSERA-SP-0.1.0 candidate
Ratified: Not ratified
Fitness: Required check
Category: Standards Governance
Applies to: OSERA maintainers, Tooling providers
Machine-readable: YAML / JSON

Structured Requirements

STD-001.REQ-001 MUST automated

Standard pages must include schema-versioned YAML front matter containing identifiers, lifecycle status, requirements, checks, evidence expectations, and pack references.

Check	Severity	Evidence
STD-001.CHECK-001 Standard front matter validates against the active OSERA schema	blocking	standard_markdown, schema-version

STD-001.REQ-002 MUST automated

The standards repository must publish normalized catalog artifacts generated from the Markdown front matter.

Check	Severity	Evidence
STD-001.CHECK-002 Generated catalog artifacts are current	blocking	docs/catalog/osera-standards.yaml, docs/catalog/osera-standards.json

Requirement

OSERA standards MUST be authored as readable Markdown pages with schema-versioned YAML front matter.

The YAML front matter is the machine-readable source for:

standard identifiers and versions;
lifecycle status;
pack membership;
requirements;
check identifiers and severity;
evidence expectations;
implementation binding names for future fitness tooling.

The standards repository MUST publish normalized catalog artifacts generated from that source metadata.

Rationale

Markdown remains the right format for reviewable standards prose. Gates and fitness functions need stronger structure than prose headings can provide.

This hybrid model keeps the current Jekyll/GitHub Pages site while making the same standards consumable by CI, acceptance gates, and downstream policy tooling.

Generated artifacts

The repository SHOULD publish generated artifacts at stable HTTP paths such as:

/catalog/osera-standards.yaml
/catalog/osera-standards.json
/catalog/packs/OSERA-SP-0.1.0.yaml
/catalog/packs/OSERA-SP-0.1.0.json

Generator posture

The generated artifacts are derived from the Markdown front matter. Contributors SHOULD update the Markdown source and rerun the generator rather than editing generated catalog files directly.

Authoring model

Standard prose pages are maintained manually in docs/_standards/*.md. The structured YAML front matter at the top of each page is the machine-readable source for standard IDs, versions, lifecycle status, pack membership, requirements, checks, evidence expectations, and future fitness-function bindings.

The documentation site renders those Markdown files through Jekyll templates. The same front matter is also used by tools/generate_catalog.rb to produce normalized YAML and JSON artifacts under docs/catalog/.

The generated YAML and JSON files SHOULD NOT be edited independently. When a standard changes, update the Markdown page and rerun the generator so the rendered documentation and machine-readable catalog remain synchronized.