otaExecution governance for humans and AI agents.
Get startedGitHub

Reference

Diff and Explain

Read-only contract comparison and remediation planning.

referenceautomation buildersintermediatestable2026-05-30

Recommended next

Remote ExecutionSemantic Snapshots and Correlation

Purpose

ota diff shows what changed between two contract states.

ota explain turns readiness findings into an ordered fix plan.

  • use ota diff when you want to understand the impact of a contract edit before writing it
  • use the Semantic Snapshots page when the real question is archived contract truth, snapshot inspection, or receipt-to-receipt drift correlation
  • use ota explain when you want the next safe fix order instead of a flat blocker list
  • both commands are read-only
  • both commands are deterministic, so the same inputs produce the same ordering

ota diff

ota diff compares two repo contracts or two workspace contracts as normalized semantic contract truth.

It also accepts archived receipt JSON or archived .ota/contracts/... snapshot JSON when you want to compare current truth against archived run truth.

It reports added, removed, and changed assumption keys in deterministic order.

  • use it before you write a change, merge a branch, or update a workspace contract
  • use it in CI when you need semantic impact instead of a raw YAML diff
  • use it when you want to know whether a change makes readiness stronger, weaker, or just different
  • use the Semantic Snapshots page when you also need archived snapshot inspection or baseline drift correlation on receipts

ota diff JSON shape

ota diff --json returns the contract comparison as a machine-readable payload.

Status

ok tells you whether ota completed the comparison successfully.

Sides

base and target keep the resolved side paths, while additive base_input and target_input publish the semantic input kind and any resolved snapshot_path when a receipt-side diff loads .ota/contracts/... behind the scenes.

Roll-up

summary carries the change counts and readiness impact.

Ordered changes

changes is the deterministic list of semantic assumption differences. Each item usually includes path, status, additive category and risk, base, target, and optional provenance.

ota explain

ota explain turns readiness findings into an ordered remediation plan.

It is the command to use when you want ota to tell you what to fix first and why.

  • the output is ordered so the first grouped action is the best next move
  • preview-first and contract-authoring actions come before later runtime follow-ups when several blockers exist together
  • grouped actions keep the plan readable while detailed steps keep the stable finding codes
  • each action and step explains why it exists
  • each action and step can include a next safe command when ota can name one
  • the output is still read-only

ota explain JSON shape

ota explain --json returns readiness findings as an ordered remediation plan with grouped actions and detailed steps.

Status

ok tells you whether ota completed the explanation successfully, and path is the resolved contract path it explained.

Roll-up

summary carries the error, warning, info, and step counts.

Ordered actions

actions is the deterministic grouped remediation plan, so the first action is the best next move for humans, CI, and agents.

Detailed steps

steps keeps the finding-level drill-in. Each step usually includes order, code, severity, summary, why, next, and optional provenance plus stable provenance_key. ota workspace explain --json adds a top-level actions lane with explicit repo ownership, then reuses the same actions and steps split under each repo item.

How to read the outputs

  • read summary first when you want the roll-up
  • read changes when you want to review contract differences before merging
  • read actions when you want the grouped next-fix order
  • read steps when you want the underlying finding-level detail
  • read provenance for the human label and provenance_key for stable machine classification when ota can trace the diagnosis source back to repo contract, org policy, or repo signals
  • use why to understand the reason, and next to decide the next command

Use cases

  • review what a proposed contract change will do before writing it
  • compare a branch against main in CI
  • summarize the impact of a workspace bootstrap change
  • check whether a contract edit is mostly operational or mostly behavioral
  • ask for the next best fix order after ota doctor finds blockers

Examples

Diff commandsbash
ota diff ./before/ota.yaml ./after/ota.yamlota diff .ota/receipts/repo-receipt-20260621-120000-000Z.json ./ota.yamlota diff --json ./before/ota.yaml ./after/ota.yamlota explain ./repoota explain --json ./repo
Diff JSONjson
{  ok: true,  base: "/workspace/before/ota.yaml",  target: "/workspace/after/ota.yaml",  base_input: {    path: "/workspace/before/ota.yaml",    kind: "contract"  },  target_input: {    path: "/workspace/after/ota.yaml",    kind: "contract"  },  summary: {    readiness_impact: "improves",    added_count: 1,    removed_count: 0,    changed_count: 2,    weakened_count: 0,    strengthened_count: 1  },  changes: [    {      path: "tasks.test.run",      status: "change",      category: "task",      risk: "medium",      base: "\"pnpm test\"",      target: "\"pnpm test -- --runInBand\""    },    {      path: "execution.preferred",      status: "add",      category: "execution",      risk: "high",      target: "\"container\""    }  ]}
Explain JSONjson
{  ok: false,  path: "/workspace/repo/ota.yaml",  summary: {    error_count: 1,    warn_count: 1,    info_count: 0,    step_count: 2  },  steps: [    {      order: 1,      code: "OTA_TASKS_MISSING",      severity: "error",      summary: "No tasks defined in contract",      why: "The repo cannot be run until at least one task exists.",      next: "Add a setup or test task to ota.yaml"    },    {      order: 2,      code: "OTA_SERVICE_NO_HEALTHCHECK",      severity: "warn",      summary: "Required service has no healthcheck",      why: "ota cannot verify readiness without a healthcheck.",      next: "Add a healthcheck command for the service"    }  ]}

Non-goals

  • auto-writing contract changes
  • fuzzy natural-language repair
  • hiding readiness blockers behind a generic suggestion engine
  • replacing doctor, validate, or detect