Skip to main content

Derived Machine Truth

In the Open Agentic Platform, human intent is captured in Markdown specifications. However, tooling, orchestration pipelines, and validation gates require structured data. OAP bridges this gap through the concept of Derived Machine Truth.

The .derived/ Directory​

All machine-consumable truth is generated by the spec-spine compiler and stored in the .derived/ directory. This includes:

  • The compiled Spec Registry (.derived/spec-registry/by-spec/)
  • The Codebase Index (.derived/codebase-index/)

These files are deterministically generated from the Markdown source. Because they are compiler-emitted, hand-editing any file under .derived/ is a strict workflow violation.

Governed Reads (Spec 103)​

To ensure that the system operates on a consistent interpretation of the derived truth, OAP enforces a policy of Governed Reads (Spec 103).

Compiled artifacts under .derived/ MUST be read through their designated consumer binaries:

  • spec-spine registry
  • spec-spine index
  • oap-registry-enrich
  • oap-code-index-enrich

Ad-hoc parsing using tools like jq, python, awk, or sed against the compiled JSON shards in any orchestrated workflow is expressly forbidden.

Why Governed Reads Matter​

If agents or scripts parse the raw JSON directly, they become coupled to the internal schema of the compiler output. If the schema evolves, those ad-hoc parsers will break.

By forcing all reads through consumer binaries, OAP provides a stable, typed API for querying the system's state. For example, to check the lifecycle status of the spec corpus, you do not write a jq script; you run:

spec-spine registry status-report --json --nonzero-only

This ensures that the platform's understanding of itself remains consistent, regardless of how the underlying data structures are optimized.