Skip to content

v0.6.0

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 04 Oct 21:12
v0.6.0
This tag was signed with the committer’s verified signature.
sknr Stephan Knauer
SSH Key Fingerprint: dG8YAu7mgXjucmJVpCx3dsUmCkCHbrHvaCQwgAkb+Ps
Verified
Learn about vigilant mode.
533b634

Release v0.6.0: Symlinked Bundle Roots, Typed List Frontmatter & Strict Filter Keys

Release v0.6.0 fixes two silent data-handling bugs, closes a symlink containment gap, hardens two provenance boundaries, and makes --filter consistent: filter keys are now exactly the frontmatter field names, and list-valued custom fields can be filtered by membership. Because it removes three undocumented --filter aliases and tightens where a bundle root may point, it is a minor release rather than a patch.

1. Breaking Changes & Migration

  • --filter keys are the frontmatter field names, with no aliases.
    • Removed the undocumented aliases tag (for tags), code_ref (for code_refs), and desc (for description).
    • A key such as tag now addresses a custom frontmatter field of that name. An old --filter "tag=security" therefore matches nothing instead of the concepts tagged security, and reports no error, because an unknown key is a valid custom field.
    • Migration: use tags=, code_refs=, and description=. The --desc flag of okf create, okf update, and okf relate is unchanged.
  • A symlinked project or vendor bundle root must stay inside the directory that contains the link.
    • knowledge -> /somewhere/else is now rejected. Before, the same link loaded as an empty bundle, and with a trailing slash (knowledge/) it loaded the outside directory unchecked.
    • User and system scope roots (~/.okf, /etc/okf, OKF_USER_DIR, OKF_SYSTEM_DIR) may be symlinks to any location, because the user configures them. Symlinks inside any bundle, and a knowledge/ subdirectory symlink, stay confined to that bundle.
  • A non-human actor can no longer add a human verification.
    • SaveConcept rejects verified entries naming a human (human, human:*, human/*, any case) when the actor is not human. Entries already recorded in the concept file may still be preserved; adding one or changing the timestamp of an existing one is rejected.
    • Affects library callers and the CLI when an agent actor writes human verifications. The CLI actor is self-declared, so --actor human/... is not blocked; the MCP server fixes its actor to agent/mcp.
  • --filter verified.by=human uses one definition of a human. Values such as humanoid-bot no longer count as human; human, human:*, and human/* do, in any case.
  • Custom list fields are typed lists in JSON output.
    • okf show --json and the MCP tools now report extra.commands as ["git commit"] and extra.repos as ["contextopia", "easygov"]. Before, block lists kept the - prefix on each item and flow lists were one string.

2. Bug Fixes

  • Symlinked bundle root loaded as an empty bundle (#45).
    • LoadBundle resolved the root but walked the unresolved path, and filepath.WalkDir does not follow a symlink at its root. The result was an empty layer and exit code 0, for example with ~/.okf as a symlink.
    • The walk now runs over the resolved root.
  • Custom list frontmatter fields were mis-parsed and stringified by okf update (#49).
    • Flow lists such as repos: [contextopia, easygov] became a single string, and okf update then wrote it back as a quoted string, permanently changing the file.
    • Flow lists (quotes and nesting included) and block lists of scalars are now parsed into typed items and stay lists across a round trip. A block list is written back as a flow list, which is valid YAML with the same meaning.
    • Block structures that are not scalar lists (lists of mappings, nested mappings, nested lists, uneven indentation) are kept verbatim.
    • Known limitation: a flow mapping inside a flow list ([{a: b}]) is still read as a string.

3. Security Hardening

  • Frontmatter smuggling in a body is detected for quoted and spaced keys.
    • A reserved key (verified, governance, generated, type, status, code_refs, stale_after) inside a nested --- block was only caught as a lowercase prefix such as verified:. Forms like "verified": {...}, 'governance' : hold, or VERIFIED : {...} slipped through.
    • One package-level regular expression now matches quotes, whitespace before the colon, and any case.
  • Human verification provenance guard (see Breaking Changes). The shared IsHumanIdentity keeps the guard and the filter consistent.

4. Features

  • --filter on list-valued custom fields (#48).

    • --filter "topics=retrieval" matches when the list contains the value (case-insensitive). topics!=retrieval matches when it does not, and topics=null matches an empty list.
    • tags and code_refs now share the same implementation.
    • To require several tags, repeat the key: --filter "tags=ci,tags=ui". Clauses are ANDed, and tags=ci,ui is rejected because ui is not a clause. There is no OR operator.

  • okf agents lint and okf validate --agents report the total file tokens next to the managed block tokens.

    • The AAG-005 budget (default 400) is measured only on the block between <!-- BEGIN OKF AGENT MEMORY --> and <!-- END OKF AGENT MEMORY -->. Content outside the block was not visible in the stats, although it is loaded on every request.
    • The output reads Token Stats: N estimated tokens in managed block (Budget: 400 tokens), M in total file. --json gains token_stats.total_tokens; existing fields are unchanged and the budget gate behaves as before.

5. Documentation & Knowledge

  • docs/guides/CLI.md documents the filter key rule, list matching, multi-tag filters, that id and path are concept properties rather than frontmatter fields, and the --actor provenance rule.
  • The AAG and DMAA RFCs, the README, and convention/dual-memory-architecture now state the enforced 400-token cap for the managed block instead of the earlier 100–200 token design target, which the linter never enforced.
  • convention/release-procedure and docs/project/playbooks/RELEASE_PLAYBOOK.md reserve signed commits, merges, tags, and pushes for the maintainer. Agents only stage changes and propose the commit message.
  • architecture/security-boundaries records the symlinked-root policy and the human verification guard, and architecture/metadata-roundtrip records the list handling.

Community & Special Thanks

  • @DevMasterDru: For the reproducible bug reports and feature requests behind this release: symlinked bundle roots loading as empty bundles (#45), custom list fields mis-parsed and stringified by okf update (#49), and --filter on list-valued frontmatter fields (#48).

Pre-Built Binaries

Pre-compiled standalone binaries for macOS, Linux, and Windows are available in the release assets on GitHub:

  • macOS (darwin/arm64, darwin/amd64)
  • Linux (linux/amd64, linux/arm64)
  • Windows (windows/amd64, windows/arm64)

Full Changelog

See commits between v0.5.0...v0.6.0 on GitHub.

Assets 12
Loading