Gate knowledge drift in CI

The contract

Every okf verb keeps the same exit-code contract, which is all CI needs: 0 success, 1 a non-conformant bundle or a crossed lint threshold, 2 usage error.

Two gates, two strictness levels:

• okf validate fails on illegal OKF (exit 1). This one belongs in every pipeline; a non-conformant bundle is broken for every consumer.
• okf lint --fail-on warn fails on curation warnings. Opt into this once the bundle is in decent shape; running it advisory first (no flag) costs nothing.

GitHub Actions

name: knowledge
on:
  pull_request:
    paths: [ "docs/**" ]

jobs:
  okf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with: { ruby-version: "3.3" }
      - run: gem install okf
      - run: okf validate docs/
      - run: okf lint docs/ --fail-on warn --stale-after 120d

The paths filter keeps the job off unrelated PRs. --stale-after 120d opts into freshness checking; without it, staleness is never reported.

Tuning the gate

• Start advisory: run okf lint docs/ without --fail-on and read the report in the job log until the findings are ones you would actually act on.
• Narrow with check names if a category is noisy while you ramp up: --except missing_timestamp,stub (names, not category labels; the curation model lists all sixteen).
• --json turns either verb into machine-readable output if you want to annotate the PR instead of just failing it.

What CI cannot check

The deterministic gates catch structure: legality and curation shape. Whether the words still match the code is a semantic question, and that belongs to the maintain verb of the agent skill, run when the code changes, with lint --json as its input. CI catches the rot you can compute; the skill catches the rot you have to read for.