Recommended next

When to use this page

Use this page when the question is architectural, not only command-local.

Open it when you need to explain how Ota turns declared repo truth into execution, evidence, drift analysis, and governance.

use it when someone asks whether Ota is only command execution or a broader governance loop
use it when you need one operator-facing mental model before dropping into contract, receipt, or diff detail
use it when agents, CI, or platform docs need the clean boundary between repo truth, execution truth, evidence, and policy

The five surfaces

The loop is intentionally layered.

Each surface answers a different question, and Ota stays stronger when those answers are linked instead of collapsed.

Contract truth

Use ota.yaml, ota.workspace.yaml, and ota validate when the question is what the repo or workspace declares should be true.

Execution truth

Use ota doctor, ota up, ota run, ota tasks, and ota execution plan when the question is which selected path Ota will actually prepare or execute.

Proof and receipt truth

Use ota receipt and archived proof artifacts when the question is what Ota actually ran, which env and backend won, and what readiness it proved.

Semantic diff and correlation

Use ota diff, ota receipt --snapshot, and receipt baselines when the question is what semantic contract meaning changed and whether new blockers line up with that drift.

Policy and governance truth

Use org policy packs plus ota policy and ota policy review when the question is what is approved, denied, or governance-blocked rather than merely missing.

Command mapping

contract truth: ota validate
execution truth: ota doctor, ota up, ota run, ota tasks, ota execution plan
proof and receipt truth: ota receipt
semantic diff and correlation: ota diff, ota receipt --snapshot, ota receipt --json --baseline ...
policy and governance truth: ota policy, ota policy review

Why Ota keeps these separate

the contract should declare what ought to be true without pretending it already executed
the receipt should publish what actually happened without turning into the full change ledger
semantic diff should compare normalized repo truth without being buried in runtime logs
policy should govern approval and restriction without replacing repo-level truth
operators and agents get a cleaner system when receipt, diff, and policy point to each other instead of collapsing into one artifact

Where to go next

open Contract Reference when the next question is field semantics in ota.yaml
open Command Reference when the next question is how one CLI surface behaves
open Execution Receipt when the next question is what a finished run recorded
open Semantic Snapshots and Correlation when the next question is archived contract truth or drift-aware comparison