list/search: support custom sorting for selective agent document reads

[blue-off-mind]

last_updated_at: 2026-08-13T14:31:08+08:00

Problem

okf list and okf search currently return concepts in concept-ID order. That is deterministic and useful as a default, but it gives agents only one traversal order.

For selective reading, an agent often needs to inspect a small, intentionally prioritized subset before calling okf show. Examples include:

• read the most recently changed concepts first;
• review concepts nearest to stale_after;
• find concepts least recently verified by a human;
• use a bundle-specific scalar frontmatter field such as last_updated_at, priority, or effective_at;
• combine a domain filter with a deterministic priority order.

Without CLI-level ordering, every consumer has to load the full JSON result and implement its own parsing, timestamp comparison, missing-value behavior, and tie-breaking. That duplicates logic and makes agent behavior less portable across consumers.

Proposed direction

Could list and search support query-time, multi-field sorting without changing the bundle layout or rewriting index.md?

One possible interface, for discussion:

okf list ./bundle --sort generated.at:desc
okf search ./bundle --type Policy --sort stale_after:asc --sort id:asc
okf list ./bundle --sort last_updated_at:desc --limit 20

The last example intentionally uses a producer-defined frontmatter field. OKF permits extension keys, and supporting scalar extension fields would let organizations apply their own document-governance metadata without changing OKF conformance requirements.

Desired properties

• Preserve the current concept-ID order when no sort is requested.
• Support multiple sort keys, evaluated in CLI order.
• Always produce deterministic output, with concept ID as an explicit or implicit final tie-breaker.
• Apply the same sorting semantics to list and search, ideally through a shared query layer that future consumers could reuse.
• Keep the operation read-only; sorting is a view over a bundle, not a storage mutation.
• Keep JSON output backward compatible and expose the flags through okf schema so agents can discover the capability.
• Define consistent behavior for missing, null, malformed, and mixed-type values.
• Compare standard OKF datetime fields by instant rather than raw string. This matters when timestamps use different timezone offsets.
• Consider --limit as a companion capability so a model can request only the highest-priority candidates before selectively opening documents.

Open design questions

1. Should sortable fields be a fixed set of normalized fields, arbitrary scalar frontmatter paths, or both?
2. If arbitrary fields are supported, how should callers specify comparison type (string, number, ISO 8601 datetime, boolean)?
3. Should direction be encoded in each repeatable expression (--sort field:desc) or use separate flags?
4. Should missing values default to last, or should the CLI expose an explicit null-order option?
5. For repeated fields such as verified, should the CLI expose derived keys such as verified.latest_at and verified.latest_human_at?
6. Is --limit appropriate for this issue, or should it be proposed separately after sorting semantics are agreed?

I would be interested in contributing an implementation after agreeing on the CLI and comparison semantics.