Skip to content

feat: adopt OKF v0.2 output - #581

Open
JHSeo (JHSeo-git) wants to merge 1 commit into
langchain-ai:mainfrom
JHSeo-git:feat/okf-v0.2
Open

feat: adopt OKF v0.2 output#581
JHSeo (JHSeo-git) wants to merge 1 commit into
langchain-ai:mainfrom
JHSeo-git:feat/okf-v0.2

Conversation

@JHSeo-git

@JHSeo-git JHSeo (JHSeo-git) commented Aug 4, 2026

Copy link
Copy Markdown

Closes #580

Updates OpenWiki's OKF output from v0.1 to OKF v0.2. This is the Phase 1 (core producer/validator) scope from the issue; emitting the sources provenance field from openwiki.source_paths is left as a follow-up.

Changes

Producer

  • The bundle-root index.md now declares okf_version: "0.2" (src/okf/index-sync.ts). The deterministic index sync rewrites existing root indexes on the next run, so existing wikis migrate automatically.
  • All five system-prompt OKF blocks (code chat/init/update, personal chat/init/update) now target the v0.2 schema and instruct generated: {by, at} in place of the superseded timestamp (SPEC §13.1). The producer actor is injected deterministically as openwiki/<version> via a new {OKF_PRODUCER_ACTOR} placeholder resolved in createSystemPrompt from OPENWIKI_VERSION, following the §7 actor convention.
  • Prompts tell the agent to drop a page's legacy timestamp only when it meaningfully changes that page, so untouched pages are not churned.

Validator (src/okf/frontmatter.ts)

  • New shape checks for the optional v0.2 families when present, per §5: generated (mapping with a required non-empty by), verified (a {by, at} mapping or list of them — a bare mapping is read as a one-element list per §5.2), sources (list of mappings each with a non-empty resource), status (draft | stable | deprecated), and stale_after (YYYY-MM-DD).
  • Stays permissive per §11: absent families and unknown extension keys are never flagged, and the legacy timestamp is still accepted as a non-empty string (v0.1 fallback).
  • Like the existing checks, these only feed the post-write warning that nudges the agent to fix a page; nothing is rejected or rewritten.

Docs

  • README OKF section updated to v0.2; changeset added (minor).

Notes for review

  • status is now enum-validated because v0.2 §5.4 defines a closed set. A page using status as a free-form producer extension (valid under v0.1) gets a correction warning the next time the agent writes it. If you prefer to keep status unvalidated for backward compatibility, I'm happy to relax that check.
  • The repository's own openwiki/index.md still says 0.1; it is generated, so I left it for the scheduled refresh workflow rather than hand-editing.

Testing

  • Test-first: updated/added cases in test/index-middleware.test.ts, test/prompt-okf.test.ts, and test/frontmatter-validator.test.ts (v0.2 families accepted, malformed families reported, bare verified mapping accepted, legacy timestamp still accepted), watched them fail, then implemented.
  • pnpm test (914 passed), pnpm typecheck, pnpm lint:check, and pnpm format:check are all clean.

@changeset-bot

changeset-bot Bot commented Aug 4, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 9f78f3e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
openwiki Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

The bundle-root index now declares okf_version "0.2", agent prompts
instruct the generated {by, at} trust field (actor openwiki/<version>)
in place of the superseded timestamp field, and the front-matter
validator checks the v0.2 provenance, trust, and lifecycle families
(generated, verified, sources, status, stale_after) while still
tolerating the legacy timestamp on v0.1 pages (SPEC section 13.1
fallback).

Refs langchain-ai#580
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Adopt OKF v0.2 output (generated/sources frontmatter, okf_version bump)

1 participant