---
key: docs.decision-optional-provenance
title: 2026-07-25 — OKF evaluated and rejected as a replacement; two of its optional fields adopted (#603)
status: active
since: '2026-07-25'
supersedes: none
superseded-by: none
rule: 'Decision records gain two OPTIONAL fields — `stale-after: YYYY-MM-DD` on the metadata line and a `**Sources:**` line in the metadata block; the Open Knowledge Format (OKF) itself is NOT adopted as the record format.'
signals: 'OKF, Open Knowledge Format, knowledge-catalog, okf-skills, stale-after, staleness, Sources, provenance, re-confirmation, review due · paths: scripts/decisions_lib.py scripts/decisions_validate.py scripts/build_decisions_catalog.py · issues: #603'
mechanics: docs/decisions.md → header schema; docs/decisions/README.md → Review due
sources: https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf (SPEC.md v0.2) · https://github.com/scaccogatto/okf-skills
---

**OKF is not a replacement for this system, and the reason is structural, not stylistic.** Its
conformance rules are deliberately permissive exactly where ours are deliberately strict: a consumer
MUST NOT reject a bundle for broken cross-links, unknown `type` values, or missing optional fields,
and its `status: deprecated` is a bare flag with nothing pointing at the successor. The single
catastrophic failure this corpus exists to prevent is *a superseded rule read as current*, and what
prevents it is the validator — one active record per key, reciprocal `supersedes`/`superseded-by`,
no record vanishing from the active set without an archive copy, catalog-drift detection. OKF has no
equivalent of any of those. It also has no `key`: its stable identity is the file *path*, which is
precisely what the breadcrumb rule tells agents not to trust. Adopting it would additionally mean a
second ingestion format alongside MemPalace for the same corpus.

**What it does have that we lacked is lifecycle and provenance metadata.** Records that encode
measured facts about hosts, runners or upstream behavior drift silently — nothing marked them due for
re-confirmation. `stale-after` fixes that, and `Sources:` gives the *evidence* a record rests on a
home other than buried prose. Both are additive: no format migration, and nothing changes for a
record that adopts neither. Adopt them opportunistically, on records that actually assert an external
fact — the three seeded here (`ci.runner-placement`, `ci.infra-shaped-red-under-load`,
`ci.peak-anon-measurement`) are the ones encoding measured host behavior, with dates staggered so
they don't all come due in the same week.

**The staleness check is non-blocking, and the generated catalog is clock-free — both on purpose.**
A calendar date turning an unrelated PR red, or silently drifting `docs/decisions/README.md` into a
`--check` failure with no commit touching the corpus, is a self-inflicted CI outage. So evaluating
`today >= stale-after` lives only on the validator's `::notice::` path, and the catalog's Review-due
section renders the date itself, never a stale/fresh verdict.

**OKF's `verified: {by, at}` trust tiers were considered and deferred**, not rejected. Given how
much of this corpus is agent-authored, distinguishing agent-inferred from human-confirmed-after-
measuring is real signal; it just needs its own actor convention and wasn't worth coupling to this
change.
