Spec: independent OKF 0.2 toolchain — validation, safe writes, MCP, CI, and graph

[chrishiguto]

Problem statement

The okf package is an independent implementation of Google OKF 0.2. The package must remain limited to that specification.

The package also needs stable automation interfaces:

• Findings need stable IDs and machine-readable reports.
• Agents need safe read and write tools.
• Bundle writes need prospective validation and atomic commit.
• Index and log maintenance must not drift.
• Graph consumers need one versioned query interface.
• Repositories need a simple CI gate.

Downstream packages can add more checks. They must compose those checks outside okf. The okf validator must not load, register, suppress, or execute downstream rules.

Architecture invariant

For a given bundle, okf must always produce the same OKF Spec report. No caller configuration can change that report.

OkfSpecReport(bundle) is independent of every downstream package.

A downstream package can inspect an OKF-valid candidate before commit. The downstream package cannot replace the OKF Spec gate.

downstream acceptance
    = OKF Spec conformance
      AND downstream checks

The conjunction belongs to the downstream package. It does not belong to okf.

Solution

1. Closed OKF Spec validation

One module owns OKF Spec validation.

• The Spec rule implementations are internal and immutable.
• The validator does not accept a rule catalog.
• The validator does not accept suppressions.
• The validator does not accept downstream parameters.
• Stable findings use okf/<code> IDs.
• The report contains errors and advisories.
• Spec conformance depends only on Spec errors.
• Advisory findings do not make a bundle non-conformant.

The package can expose read-only rule descriptors. A descriptor can contain the ID, text, severity, and Spec reference. A descriptor cannot contain a replaceable run function.

2. Stable Finding and Report contracts

One module owns the value types for findings and reports.

• A finding has an ID, severity, message, and optional location.
• A report has one text projection and one JSON projection.
• Load failures merge into the same Spec report.
• CLI, MCP, and CI consume the same Spec report.
• No adapter can change the Spec conformance result.

An adapter can apply a local exit policy to advisories. The adapter must not report that policy as OKF Spec non-conformance.

3. Prepared bundle changes

The write seam is a prepared candidate.

describe change
→ prepare candidate in memory
→ validate candidate against the OKF Spec
→ expose candidate to the caller
→ commit the prepared change atomically

prepare returns one of these results:

• A refusal with the OKF Spec report.
• A prepared change with the candidate and its OKF Spec report.

commit accepts only a prepared change that okf created. The commit operation checks that the source bundle did not change after preparation.

The prepared change is opaque. Its candidate view is immutable. It binds the exact bytes or digest that passed Spec validation. commit writes those exact bytes and rejects a forged, changed, or stale prepared value.

The prepared candidate is the composition seam. A downstream package can run extra checks before it calls commit.

4. MCP server

okf mcp exposes a fixed read and write surface over standard input and standard output.

Read tools:

• list-concepts
• lookup-concept
• query-graph
• validate

Write tools:

• create-concept
• update-concept
• link-concepts
• deprecate-concept

Each write tool translates its arguments into a change set. The tool calls prepare, returns a Spec refusal when necessary, and commits only a prepared change.

The MCP server does not accept external validators. The MCP server does not use a strict write verdict. A candidate with only advisory findings can commit.

Malformed tool input remains a tool error. A candidate with a Spec error produces a report-carrying refusal.

An unresolved link is valid input. The base write path does not require the target concept to exist.

5. Index and log ownership

One model owns the index.md and log.md entry formats.

• Rules read entries through this model.
• Writers emit entries through this model.
• A write updates only affected indexes and their ancestors.
• A write preserves unrelated authored indexes.
• An idempotent change writes no files.

The package can provide a default index planner. A downstream package can create a different OKF-valid change set. Every candidate still passes the closed Spec gate.

6. CI gate

Releases attach compiled binaries. A thin composite GitHub Action runs base OKF validation.

The action consumes the same Spec report as the CLI and MCP server. The action does not load downstream rules.

7. Graph query interface

okf graph remains the single graph producer. It supports JSON, DOT, and Mermaid output.

One versioned graph-query interface owns all filters. CLI flags and MCP query-graph are adapters over that interface.

Architecture

flowchart TB
  files["OKF bundle files"]

  subgraph okf["okf — Google OKF 0.2"]
    load["load bundle"]
    validate["closed OKF Spec validator"]
    report["OKF Spec report"]
    plan["change planners"]
    prepare["prepare candidate"]
    commit["atomic commit"]
    graph["versioned graph query"]

    load --> validate --> report
    plan --> prepare --> validate
    prepare --> commit
    load --> graph
  end

  files --> load
  commit --> files

  subgraph surfaces["okf adapters"]
    cli["CLI"]
    mcp["MCP"]
    ci["CI"]
  end

  report --> cli
  report --> mcp
  report --> ci

  downstream["downstream package\nextra checks and extra planning"]
  prepare -->|"inspect candidate"| downstream
  downstream -->|"commit prepared change"| commit

Loading

The okf package has no dependency on the downstream package. The okf package has no downstream rule-registration seam.

User stories

1. As an engineer, I want stable okf/... IDs in text and JSON reports.
2. As an engineer, I want the same Spec report on CLI, MCP, and CI surfaces.
3. As a coding agent, I want typed read tools for bundle navigation.
4. As a coding agent, I want write tools that commit only Spec-valid prepared changes.
5. As a coding agent, I want atomic concept, index, and log updates.
6. As a downstream author, I want to inspect a Spec-valid candidate before commit.
7. As a downstream author, I do not want to modify or replace OKF Spec validation.
8. As a team lead, I want a one-line CI gate for Google OKF 0.2.
9. As a graph consumer, I want one versioned query contract.
10. As an okf maintainer, I want all downstream behavior outside this package.

Implementation decisions

Validation

• The Spec validator has no injected catalog.
• The Spec validator always runs its fixed internal rules.
• Public rule information is metadata only.
• Stable finding IDs remain part of the output contract.
• Suppression is not part of the core Spec verdict.
• Strict write validation is not permitted.

Writes

• prepare owns candidate construction and Spec validation.
• commit owns transactionality and rollback.
• A prepared change acts as proof of prior Spec validation.
• The prepared candidate is immutable and bound to the exact validated bytes.
• Commit detects stale source state, candidate tampering, and forged prepared values.
• MCP verbs are adapters over change planning, preparation, and commit.
• Broken links are tolerated as required by Google OKF 0.2.
• Unrelated conformant indexes are not regenerated.

Composition

• Downstream rule registries belong to downstream packages.
• Downstream parameters belong to downstream packages.
• Downstream suppressions belong to downstream packages.
• A downstream package combines its result with the OKF Spec result.
• The core package never produces a combined downstream verdict.

CI and graph

• Release binaries provide the validation engine for CI.
• The GitHub Action remains thin.
• The graph module owns one filter interface and one versioned JSON schema.

Sub-issues

• Contract: findings, reports, prepared changes, and index/log types #3 defines Finding, Report, prepared-change, and index/log value contracts. It does not define an open executable rule catalog.
• Closed OKF Spec validator and stable okf/... finding IDs #4 adds stable okf/... IDs and moves Spec rules behind a closed validator.
• Graph: query filters and versioned JSON schema #10 defines the shared graph-query interface.
• MCP server: read surface #11 provides the MCP read surface.
• MCP server: concept writes through prepare and commit #12 provides concept writes through prepare and commit.
• MCP server: link and lifecycle writes through prepare and commit #13 provides link and lifecycle writes through prepare and commit.
• CI gate: release binaries and composite GitHub Action #14 provides the CI gate and release binaries.
• Index and log model: one owner for the entry format #15 owns index and log entry parsing and serialization.
• Prepared bundle changes: prospective Spec validation and atomic commit #16 owns candidate preparation and atomic commit.

Testing decisions

• Tests exercise public interfaces and protocol surfaces.
• A clause-by-clause conformance matrix maps the pinned OKF Spec requirements to tests.
• A conformance corpus pins the OKF Spec report and covers every hard rule and tolerant-reader case.
• No public configuration can change the Spec report for a bundle.
• A missing required field fails on every Spec validation surface.
• An advisory-only candidate can commit.
• An unresolved link can commit.
• A prepared change cannot commit after its source state changes.
• A caller cannot mutate or forge the candidate that commit writes.
• An idempotent change writes no files.
• An unrelated authored index remains byte-identical.
• CLI, MCP, and CI return the same Spec findings.

Out of scope

• Rules that are not part of Google OKF 0.2.
• External rule registration inside the Spec validator.
• External suppressions inside the Spec verdict.
• External parameters inside the Spec validator.
• A combined downstream verdict in this package.
• Downstream-specific index ordering or document conventions.
• HTML graph visualization.
• Enrichment or batch-agent systems.
• Executing Attested Computations.
• Changes to the upstream Google OKF specification.

Further notes

• The package targets OKF 0.2.
• The package pins Spec revision 3fcbb9f.
• The central invariant is simple: okf validates Google OKF 0.2 and nothing else.