OKF Compliance Validator

See it in action

~/workspace/homuvault — bash

$ python3 scripts/okf-validate.py --ci OKF-CI PASS: files=156 conformant=156 errors=0 warnings=0 $ python3 scripts/okf-validate.py /tmp/new-vault/ OKF v0.1 Conformance Report Spec: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md Files scanned: 3 /tmp/new-vault/2026-07-01-Digest.md [ERROR] NO_FRONTMATTER: Missing YAML frontmatter (OKF §4.1 — required) → fix: --- type: DailyDigest title: Test Digest description: 'Some body content.' tags: [dailydigest, digest] timestamp: 2026-07-02T19:00:00Z --- /tmp/new-vault/file with spaces.md [ERROR] FILENAME_SPACES: Filename contains spaces (violates OKF §5) → fix: Rename to: file-with-spaces.md Summary: 3 errors, 0 warnings across 2 files $ python3 scripts/okf-validate.py /tmp/new-vault/ --fix [1mAuto-fix actions:[0m [INSERTED] /tmp/new-vault/2026-07-01-Digest.md — type=DailyDigest [RENAMED] /tmp/new-vault/file with spaces.md → /tmp/new-vault/file-with-spaces.md [INSERTED] /tmp/new-vault/file-with-spaces.md — type=Concept ✓ All 3 files are OKF v0.1 conformant.

Quick start

# Install the only dependency
pip install pyyaml

# Scan a vault
python3 scripts/okf-validate.py /path/to/vault

# CI mode: one-line summary, exit 1 on errors
python3 scripts/okf-validate.py --ci

# Auto-fix mechanical issues (idempotent, converges in ≤5 passes)
python3 scripts/okf-validate.py /path/to/vault --fix

# Markdown conformance report
python3 scripts/okf-validate.py /path/to/vault --report conformance.md

What it checks

Rule	Severity	Auto-fixable?
Missing YAML frontmatter	error	✅ inserts a block
Invalid YAML / non-dict frontmatter	error	❌
Missing `type:` field	error	✅ suggests a type
`type:` is not a string	error	❌
`timestamp:` not ISO 8601	warning	❌
`tags:` is not a list	warning	❌
Filename contains spaces	error	✅ renames to kebab-case
Reserved name (`index.md` / `log.md`)	skip	n/a
Missing `title:` (strict mode)	warning	❌
Missing `description:` (strict mode)	warning	❌

Features

🚀

Single file, no dependencies

Drop okf-validate.py into any project. No pip install -e . ceremony.

🔧

Real `--fix`

Converges in ≤5 passes. Renames spaces to kebab AND inserts missing frontmatter in one run.

📊

CI-friendly

--ci outputs a one-line summary and exits 1 on errors. Drop into pre-commit or cron.

📝

Markdown reports

--report FILE.md writes a polished conformance report for vault releases.

🔌

JSON output

--json for tooling integration. --strict for warning-as-error mode.

🛡️

Safe

Never overwrites existing frontmatter. Never modifies body content. Never renames index.md / log.md.

🔁

Idempotent

Running --fix twice produces the same result. Safe to re-run.

🎯

Smart inference

DailyDigest → next-day 19:00:00Z. Title from H1. Description from first paragraph.

📂

`.okfignore` support

Exclude README/CHANGELOG/LICENSE from the scan. .gitignore-style syntax.

🧪

8 smoke tests

Covering --fix convergence, --ci, --report, --json, .okfignore, and edge cases.

Integration

Pre-commit hook

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: okf-validate
      name: OKF v0.1 conformance
      entry: python3 scripts/okf-validate.py --ci
      language: system
      pass_filenames: false

GitHub Actions

name: OKF conformance
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install pyyaml
      - run: python3 scripts/okf-validate.py --ci

Cron

# /etc/cron.d/okf-daily-compliance-scan
30 6 * * * cd /path/to/vault && python3 scripts/okf-validate.py --ci --no-color