--- type: Concept title: OKF Namespace Structure & Governance Model description: How PMOS organizes its Open Knowledge Format bundle and the governance rules that keep it spec-conformant. tags: [okf, governance, knowledge-management, namespace, reference-layer] timestamp: 2026-06-29 --- # OKF Namespace Structure & Governance Model **Situating context:** This is the first OKF concept authored in PMOS. It exists because every other concept, template, and playbook in the bundle needs a shared, unambiguous answer to two questions: *what is OKF here* and *how do we keep the bundle from drifting into a bespoke schema*. It informs every authoring decision for files under `/okf/`. ## What OKF is OKF stands for **Open Knowledge Format** — the Google Cloud open spec (v0.1 draft) at . It is **not** "Organizational Knowledge Fabric" or any other expansion. Do not invent one. OKF is a deliberately minimal format: **a directory of Markdown files with YAML frontmatter.** There is no schema registry, no central authority, and no required tooling. PMOS conforms strictly to this spec rather than layering a custom schema on top of it. ## What lives in OKF (and what does not) OKF holds **timeless, curated knowledge** — the things that stay true across sessions and remain useful as reference: - Concepts (mental models, definitions, principles) - ADRs (architecture decision records) - Templates (PRD template, eval-rubric template) - Playbooks (repeatable procedures) OKF does **not** hold operational records. PRDs instances, eval-rubric instances, OKR instances, and agent run traces are operational state — they live in Supabase (P1+) and under `/planning/` (P0), **not** in the OKF bundle. The test: if it is a dated instance of work, it is operational; if it is reusable knowledge, it belongs in OKF. ### Two layers: concepts and references The bundle holds two kinds of curated knowledge that age differently: - **Concept layer** (`core/`) — timeless mental models, definitions, principles, templates, playbooks. Changes by insight, rarely. - **Reference layer** (`products//`) — a **catalog of the system's concrete assets**: one small, individually-retrievable doc per Supabase table (its schema + RLS shape), per derived view/metric, per MCP tool (the ACI), and per locked decision (an `ADR` view of `DECISIONS.md`). This is exactly how upstream OKF bundles work — they catalog every table, metric, and join — and it is the layer that **must track the backbone**: it changes whenever the system changes. Both layers are still *knowledge about the system*, not operational rows. A `data-model` doc describes a table's **shape and rules**; it never contains the table's data. An `ADR` doc is a curated **view** of a decision; `DECISIONS.md` stays the single source of truth. The reference layer is kept in sync by the [okf-sync playbook](/okf/core/playbooks/okf-sync.md) — the standing cadence that stops the bundle freezing while the product evolves. ## The bundle A **Knowledge Bundle** is a self-contained hierarchical collection of OKF concept documents — the unit of distribution. PMOS's `/okf/` tree is one bundle: ``` okf/ ← the bundle root ├── index.md ← reserved: directory listing (progressive disclosure) ├── log.md ← reserved: chronological update history, newest first ├── core/ ← canonical, cross-cutting knowledge │ ├── concepts/ ← mental models and definitions (this file lives here) │ ├── templates/ ← reusable document templates │ └── playbooks/ ← repeatable procedures ├── products/ │ └── pmos/ ← product-scoped knowledge namespace ├── shared/ ← concepts promoted for cross-PM reuse └── sources/ ← raw ingested artifacts (immutable) ``` **Concept ID = the file path within the bundle, minus the `.md` suffix.** For example, this document's concept ID is `core/concepts/okf-governance`. ### Namespace intent - `core/` — knowledge that is canonical to PMOS and cuts across products. - `products//` — knowledge scoped to one product (e.g. `products/pmos/`). - `shared/` — concepts promoted out of a product or PM namespace because they generalize across PMs. Promotion is deliberate, not automatic. - `sources/` — raw ingested artifacts kept **immutable** as provenance. Concepts are extracted *from* sources into `core/`/`products/`; sources themselves are never edited in place. ## Frontmatter rules (spec-conformant) The **only required** frontmatter field is **`type`** — a short, self-explanatory string. Examples: `Concept`, `Playbook`, `ADR`, `Reference`, `Template`. **Recommended** fields, in priority order: 1. `title` — human-readable name. 2. `description` — one-line summary; used for relevance decisions during retrieval. 3. `resource` — canonical URI for the concept. **Omit** for abstract concepts that have no canonical external URI. 4. `tags` — list of short topic labels. 5. `timestamp` — ISO 8601 last-modified date. ### Fields we explicitly dropped Earlier PMOS design drafts referenced custom required fields: `status`, `confidence`, `last_validated`, `namespace`, `owner`, `knowledge_type`, `enrichment_cadence`. **These are not required and default to absent.** Conforming to the open spec means not reinventing its schema. - Map `knowledge_type` → spec `type`. - Map `last_validated` → spec `timestamp`. - If any other field is genuinely needed, it may appear **only** as an optional, producer-defined extension key — but the default is to **not** add it. ## Reserved filenames Two filenames are reserved and **must not** be used as concept documents: - **`index.md`** — a directory listing that supports progressive disclosure (an agent reads the index to decide what else to load). It has **no frontmatter**. - **`log.md`** — a chronological update history, **newest first**, using ISO dates. ## Cross-linking Link concepts with standard Markdown links. **Absolute bundle-relative links** (beginning with `/`) are preferred, e.g. `[OKR tree](/okf/core/concepts/okr-tree.md)`. Broken links are **tolerated** — they may point at knowledge that has not been written yet, which is a feature, not an error. ## Governance: permissive conformance PMOS governance is intentionally permissive. Tooling and reviewers **must tolerate**: - Unknown `type` values. - Missing optional (recommended) fields. - Unknown extra producer-defined keys. - Broken cross-links. - Missing `index.md` files. CI frontmatter linting **may enforce** the presence of the `type` field, but **must not** reject a document for missing optional fields or for carrying extra keys. The bias is toward accepting knowledge and improving it in place, not gatekeeping it out. ## Lifecycle 1. **Ingest** — raw artifacts land immutably in `/okf/sources/`. 2. **Extract** — concepts are distilled from sources into `core/concepts/` or `products//`, each with situating context (where it came from, why, what decision it informs). 3. **Sync** — when the live backbone changes (a new table, view, MCP tool, or decision), the matching **reference doc** is authored or refreshed in the same change, per the [okf-sync playbook](/okf/core/playbooks/okf-sync.md). This is what keeps the reference layer from freezing behind the product. 4. **Promote** — concepts that generalize across PMs move to `/okf/shared/`. 5. **Record** — every meaningful change is appended to `/okf/log.md` (newest first), and to the namespace `log.md` for product-scoped changes. This lifecycle keeps provenance immutable, knowledge curated, the reference layer current, and the bundle spec-conformant.