Skip to content

apply_okf_frontmatter.py reference

Authoritative Open Knowledge Format (OKF v0.1) compliance and enforcement engine.

Description

The apply_okf_frontmatter.py tool scans directories and ensures all .md files contain the 5 required frontmatter variables. It automatically handles line endings, quotes special values, and writes updates atomically.

Script path

tools/apply_okf_frontmatter.py

CLI signature

# Scan and standardise files in a target directory (defaults to current directory)

uv run python tools/apply_okf_frontmatter.py docs/

Mandatory fields enforced

All Markdown files are parsed to assert: - okf_version: Fixed float representation (defaults to 0.1). - type: Document category, mapped from directory paths. - title: File header string (parsed from H1 tags). - timestamp: UTC ISO 8601 creation string. - topics: Categorized string lists defining index content.

Dependencies

  • Python: 3.12+.
  • pyyaml: Robust SafeLoader parsing configuration.

Internal Python API

get_okf_type(filepath)

Derives document types dynamically from parent paths. - Types returned: governance_protocol, agent_skill, architecture_concept, automation_tool, infrastructure_playbook, documentation.

needs_double_quotes(s)

Detects if strings contain colons, parentheses, emojis, or spaces, requiring YAML escape double quotes. - Returns: Boolean.

atomic_replace_file(filepath, new_content, filename)

Atomically updates files via temporary sibling structures and os.replace(), preserving permissions. - Mechanism: Prevents data truncation in the event of hardware or system execution hangs.

Deep State of Mind (DSOM) For My AI Protocol | Harisfazillah Jamel (LinuxMalaysia) | 2026-08-14 Standard: UK English | DBP-standard Bahasa Melayu Malaysia (Piawai) | GNU General Public License v3.0