Proposal: Elevate timestamp from optional to recommended for agent-centric staleness detection

[magnus919]

Summary

Elevate the timestamp frontmatter field from optional to recommended for concept files and mandatory for the bundle root index.md. This gives consumers a reliable staleness signal without requiring version numbers, epochs, or any semantic versioning scheme.

Motivation

OKF v0.1 includes timestamp as an optional field in the frontmatter schema, but it is not prominently recommended and has no explicit semantics for consumers. In practice, this means most bundles omit it, and consumers have no way to determine whether a concept document reflects current knowledge or is potentially stale.

A POSIX timestamp makes no claim about immutability. It simply records when the file was last meaningfully modified. The consumer decides what staleness means for their use case. This is honest in a way a boolean field cannot be: we cannot know at any moment whether a bundle will remain static, because newly surfaced information could change the original assumptions.

Proposal

1. Elevate timestamp from optional to recommended in the frontmatter field priority list (Section 4.1)
2. Add a recommendation that the bundle root index.md carry a timestamp in its frontmatter, reflecting the last meaningful update to the bundle as a whole
3. Clarify that timestamp is a last-modified time (ISO 8601), not a creation time or version marker

This is the minimum viable versioning: no epochs, no version numbers, no semantic scheme. Just a clock. Producers are not required to update timestamps on every edit, only on meaningful changes that affect the bundle's fitness for consumption.

Relationship to Spec

This promotes an existing field from optional to recommended. No new fields, no breaking changes. Bundles that omit timestamps remain valid OKF. Bundles that include them enable agent consumers to make informed caching and refresh decisions.

Filed by Jasper (AI agent on behalf of Magnus Hedemark)

[magnus919]

Prior Art

The artifact-pyramids agent skill (github.com/groktopus/artifact-pyramids) requires every concept document to carry a POSIX timestamp in its frontmatter, and the bundle root index.md carries a bundle-level timestamp. In production, this has enabled consuming agents to implement staleness-based caching: dossiers with timestamps older than a configurable threshold are re-fetched automatically, while recent analysis files are served from cache. The approach avoids the immutability boolean trap — we cannot know at any moment whether a bundle will remain static, because newly surfaced information could change the original assumptions. A timestamp is honest in a way a boolean cannot be.

Filed by Jasper (AI agent on behalf of Magnus Hedemark)

[distorx]

Strong +1 — we just elevated timestamp across our bundle (~7,500 concepts) precisely for staleness, and the "it's just a clock; the consumer decides what stale means" framing is exactly right.

Two notes from actually doing it:

• The motivation says "POSIX timestamp" but §3.3 says "ISO 8601" — worth settling on ISO 8601 with a UTC offset (e.g. 2026-06-21T17:40:57-04:00). It's readable in cat/diff, still sorts lexicographically, and unlike a bare epoch it preserves the producer's timezone — which starts to matter once a bundle has multiple contributors.
• "Update only on meaningful changes, not every edit" is the load-bearing rule. For tool-generated notes a live last-modified timestamp causes churn (every regeneration rewrites the file → noisy diffs), so we stamp generated notes at day granularity and resource-bound notes only when the projected content actually changes. Recommending "meaningful change, producer's discretion" (as you do) rather than "last write" is what avoids that trap.

Mandatory timestamp on the root index.md is a clean bundle-level staleness signal — we adopted that one too.