Tested with v0.4.0 (darwin_arm64 release tarball, checksum and sigstore bundle verified).
Repro
Starting from any bundle whose index is current:
okf index . # index.md now matches the concepts
# then change any concept's `description:` in an editor, and do NOT re-run `okf index`
okf validate .
Result: valid: true, 0 errors, 0 warnings, 0 findings — while index.md still carries the old
description and the concept carries the new one.
The gap
okf index generates every index.md from concept frontmatter, so an index is a derived
artifact. Nothing re-runs it, and validate reads the result as a file to be checked for
conformance rather than against the source it was generated from. So an index goes stale the moment
a title: or description: changes, and the bundle stays valid.
That matters because the index is what a reader — or an agent doing progressive disclosure — sees
first. A stale one misdescribes concepts that are themselves correct.
What would close it
A check mode on the generator: okf index --check (or --dry-run, or --diff) that regenerates in
memory, compares, and exits non-zero on a difference without writing. That is the standard shape for
this — gofmt -l, terraform fmt -check.
I currently do it by copying the bundle to a temp directory, running okf index there, and diffing
the results back. That works, and it is an odd thing to have to do to ask a generator whether its own
output is current.
Related, and possibly a separate issue: okf index --check today reports
{"error":{"code":500,"kind":"io","reason":"ioError","message":"generate index in --check"}}with process exit 2, because the unknown flag is taken as a path. validate and lint return a 400
usage error and exit 4 for the same mistake.
Tested with v0.4.0 (
darwin_arm64release tarball, checksum and sigstore bundle verified).Repro
Starting from any bundle whose index is current:
Result:
valid: true, 0 errors, 0 warnings, 0 findings — whileindex.mdstill carries the olddescription and the concept carries the new one.
The gap
okf indexgenerates everyindex.mdfrom concept frontmatter, so an index is a derivedartifact. Nothing re-runs it, and
validatereads the result as a file to be checked forconformance rather than against the source it was generated from. So an index goes stale the moment
a
title:ordescription:changes, and the bundle stays valid.That matters because the index is what a reader — or an agent doing progressive disclosure — sees
first. A stale one misdescribes concepts that are themselves correct.
What would close it
A check mode on the generator:
okf index --check(or--dry-run, or--diff) that regenerates inmemory, compares, and exits non-zero on a difference without writing. That is the standard shape for
this —
gofmt -l,terraform fmt -check.I currently do it by copying the bundle to a temp directory, running
okf indexthere, and diffingthe results back. That works, and it is an odd thing to have to do to ask a generator whether its own
output is current.
Related, and possibly a separate issue:
okf index --checktoday reports{"error":{"code":500,"kind":"io","reason":"ioError","message":"generate index in --check"}}with process exit 2, because the unknown flag is taken as a path.
validateandlintreturn a 400usage error and exit 4 for the same mistake.