otaExecution governance for humans and AI agents.
Get startedGitHub

Contract Authoring · Lesson 04 of 04

Detection candidates and reviewable application

Publish source-bound detection evidence for review, then apply only a current, complete candidate through an explicit mutation carrier.

LearnContract AuthoringFoundation7 min read1.6.27+2026-08-24

Learning objectives

  • Run ota detect --dry-run and read its output
  • Identify which inferences are high-confidence vs speculative
  • Describe the reviewable application workflow

Prerequisites

Detection is evidence-assisted authoring, not automatic truth. ota detect inspects supported repository-owned signals, attributes findings, and can publish a review artifact without changing ota.yaml.

Review before mutation

A candidate binds its source inventory, evidence manifest, proposed operations, and resulting semantic contract identity. Unknown, unsupported, or conflicting findings stay visible. Applying a candidate re-derives current repository truth and refuses stale or contradictory state.

Detection candidates can classify reviewable execution closure, but they do not infer agent-safe authority. Declare safe_for_agent only after maintainer review; command shape or a verifier-like name is not effect-safety proof.

Reviewable candidate workflow
ota detect --candidate-out .ota/candidates/detect.json .ota contract apply-candidate .ota/candidates/detect.json --json .# First contract only, after review:ota contract apply-candidate .ota/candidates/detect.json --write .

Existing contracts use explicit Git authority

Create-new publication never replaces an existing ota.yaml. A reviewed update to an existing tracked contract requires --carrier git, a clean tracked contract at HEAD, source re-derivation, and branch compare-and-swap. Ota does not push, rebase, or stage unrelated paths.

Reviewed existing-contract update
ota contract apply-candidate .ota/candidates/detect.json --write --carrier git .

Canonical terminology

detectinferenceconfidencereviewable

Commands and expected output

Publish a review artifact
ota detect --candidate-out .ota/candidates/detect.json --json .
Re-derive without writing
ota contract apply-candidate .ota/candidates/detect.json --json .

Evidence boundary for this lesson

Establishes

  • The worked examples establish the lesson's canonical Ota distinctions for its stated scope.

Does not establish

  • Reading the lesson does not validate a repository, execute its tasks, or establish organizational acceptance.

Knowledge check

Why must apply-candidate re-derive repository evidence?

A reviewed candidate is bound to a source snapshot. Re-derivation prevents stale evidence or changed repository truth from being written as though it were still reviewed. It still does not make inferred tasks agent-safe; that remains maintainer-authored contract truth.

Relevant specifications