Labs · Lesson 01 of 05
Lab: Build a first contract
Start from a bare repo and build a complete, valid ota.yaml — step by step — using ota init, ota detect, and ota validate.
Learning objectives
- Create a valid
ota.yamlfor a Node repo - Verify it with
ota validate - Run
ota doctoron it and read the result
Prerequisites
This lab creates a first contract through the reviewable candidate path. The goal is not to maximize inferred coverage; it is to preserve evidence, review the proposed contract, and write only a conservative first contract you understand.
Lab sequence
Use a small repository with one package manifest and one verifier script. Keep the repository free of ota.yaml so create-new publication is the only mutation path.
Run this publication lab on Linux or macOS. The current durable candidate and contract writers refuse on other platforms because Ota will not weaken no-follow and create-new filesystem guarantees.
ota doctorota detect --candidate-out .ota/candidates/first.json --json .ota contract apply-candidate .ota/candidates/first.json --json .ota contract apply-candidate .ota/candidates/first.json --write .ota validateota doctorReview checklist
Inspect provenance, unknown findings, task bodies, requirements, effects, and agent-safe claims. If the candidate omits material repository behavior, add it through reviewed contract authoring rather than calling the inferred starter complete.
Canonical terminology
Evidence boundary for this lesson
Establishes
- You can produce a syntactically valid contract
ota validatepasses on the result
Does not establish
- The contract correctly models your real repo
- Tasks execute successfully
Knowledge check
What must you review before writing a detected first contract?
Review provenance, unknown and conflicting findings, task bodies, requirements, effects, agent safety, and material repository behavior the candidate did not cover.