---
schema_version: 1
id: RAC-KV3JZ2085R29
type: roadmap
tags: [okf, interop]
---
# RAC v0.15.0 — OKF Frontmatter Superset (tags + git-derived timestamps)

## Status

Planned

## Context

ADR-050 adopts the conflict-free subset of OKF's reserved descriptive front
matter so a RAC bundle carries more of what OKF consumers expect, without
breaking any recorded decision. This milestone delivers it, opening the v0.15.x
interop series (distinct from v0.14.x enforcement).

Two parts. First, RAC recognises an optional `tags` field in source frontmatter —
a list of labels (ADR-025 reserved it). Second, `rac export --okf` projects
`created`/`updated` into each bundle artifact, derived from git history (ADR-045),
so the bundle is timestamped while the source stays date-free. Per ADR-050, RAC
does not add `title`/`description` to frontmatter and does not make `type`
mandatory (ADR-010 keeps documents legitimate; OKF validity already comes from the
export, which excludes them).

## Outcomes

- A RAC artifact may declare `tags: [...]`; `rac validate` accepts it and rejects
  malformed values. No `schema_version` bump — additive, like `id`/`type`/
  `relationships` before it.
- `rac export --okf` carries `tags` (from source) and `created`/`updated` (from
  git) in each artifact's front matter, present-only and deterministic.
- The source corpus stays free of stored dates (ADR-045) and forced typing
  (ADR-010); existing validation and the JSON export are unchanged.

## Initiatives

### Initiative 1 — Recognise `tags` in frontmatter

Add `tags` to the supported frontmatter fields and validate it as a list of
non-empty strings (`invalid-metadata-field` otherwise). Carry it on
`ArtifactMetadata`. Timestamps are deliberately not added to the frontmatter
schema.

### Initiative 2 — Git-derived timestamps in the OKF export

Extend the git-recency service with a first-commit lookup (gated by a
`with_creation` flag so the cadence path is unaffected) and project
`created`/`updated` into each OKF artifact's front matter, alongside `tags` from
source. Present-only; absent when git cannot answer.

### Initiative 3 — Coverage and docs

Frontmatter tests (valid/invalid tags, timestamps not supported), export tests
(tags from source, created/updated from git), and `docs/okf-profile.md` updated
to document the now-supported fields and the git-derived timestamps.

## Constraints

- Additive (ADR-007): `tags` is optional; no `schema_version` bump; existing
  frontmatter fields, validation codes, and the JSON export are unchanged.
- ADR-045: timestamps are git-derived, never stored in source frontmatter.
- ADR-010: `type` stays optional; documents remain legitimate.
- ADR-025: `title`/`description` are not added (H1/body conventions stand).
- Determinism (ADR-002): the bundle stays byte-identical for a given git state.

## Non-Goals

- Frontmatter `title`/`description`, or any conflict-resolution rules for them.
- Mandatory `type` or a CI conformance gate over untyped documents.
- Storing dates in source frontmatter.
- Exposing `tags`/timestamps in the JSON export contract (a later, versioned
  decision if wanted).

## Implementation Contract

The following decisions are pinned for v0.15.0.

### Behaviour

- `tags` is an optional list of non-empty strings; malformed values raise
  `invalid-metadata-field`. It is carried on `ArtifactMetadata.tags`.
- `rac export --okf` projects, present-only, per artifact: `created` (first
  commit), `updated` (last commit), and `tags` (from source).
- `rac validate`, `rac relationships --validate`, the JSON/HTML export, and the
  cadence/recency path are unchanged in output.

### Interface

- No CLI surface change. `rac new` templates are unchanged (no `tags` by default).

## Success Measures

- A `tags`-bearing artifact validates clean and its tags appear in the OKF bundle.
- `rac export rac/ --okf` carries `created`/`updated` on every artifact in a git
  checkout, and re-export is byte-identical.
- A source `created:`/`updated:` field is rejected as an unsupported frontmatter
  field (ADR-045 upheld).

## Risks

- Two git lookups per artifact on export. Mitigated: gated behind `with_creation`,
  paid only on `rac export --okf`, never on validate/review/cadence.
- `tags` could be mistaken for a classification or relationship signal. Mitigated:
  it is descriptive only, documented as such, and not consumed by analysis.

## Assumptions

- ADR-025 remains the frontmatter contract; this extends its reserved-field set by
  one (`tags`) as it anticipated.
- The git-recency service (ADR-045) remains the single home for git timestamps.

## Related Decisions

- adr-050
- adr-025
- adr-045
- adr-048

## Related Requirements

- rac-okf-carrier-profile

## Related Roadmaps

- v0.13.6-okf-bundle-export
