Typical signals

the runtime, package manager, and dependency hydration have one typed owner
service exposure and readiness are declared instead of inferred from launch logs
finite verification, long-running launch, workflow selection, and agent boundaries remain separate

Why it matters

it turns a repo pattern into something humans, CI, and agents can read the same way
it makes the next command obvious instead of implied by README drift
it keeps readiness, setup, and execution explainable in receipts and diagnostics

Example contract

This is the current full-contract baseline. Copy the shape, then remove anything your repository cannot prove rather than retaining decorative configuration.

It uses the typed surfaces Ota can validate and execute today: toolchains, prepare, command, aggregate, launch, surfaces, readiness, workflows, and agent.

ota.yamlyaml

version: 1metadata:  ota:    minimum_version: "1.6.26"project:  name: full-contract  description: Full example of the current Ota contract surfacetoolchains:  node:    version: "22"    package_managers:      pnpm: "10"    fulfillment:      source: corepack      mode: runexecution:  default_context: host  contexts:    host:      backend: nativeenv:  vars:    APP_ENV:      default: local      allowed:        - local        - ci    DATABASE_URL:      required: true  sources:    - kind: dotenv      path: .env.localsurfaces:  app:    kind: http    label: Application preview    purpose: Browser-facing local development service    visibility: internal    port: 3000    path: /health    readiness:      kind: http      path: /health      timeout: 10sreadiness:  probes:    app-ready:      kind: http      target:        kind: task        name: dev        listener: app        address_view: host      path: /health      timeout: 10000tasks:  setup:    description: Hydrate dependencies through the declared pnpm lane    prepare:      kind: dependency_hydration      medium: package_dependencies      source:        kind: node_package_manager        cwd: .        manager: pnpm        mode: install        frozen_lockfile: true    requirements:      toolchains:        - node    effects:      writes:        - node_modules      network: true      network_kind: dependency_hydration  lint:    command:      exe: pnpm      args:        - lint    depends_on:      - setup    requirements:      toolchains:        - node  test:    command:      exe: pnpm      args:        - test    depends_on:      - setup    requirements:      toolchains:        - node  verify:    description: Run the finite verification closure after a change    aggregate:      tasks:        - lint        - test  dev:    description: Start the local application service    launch:      kind: command      exe: pnpm      args:        - dev        - --host        - 127.0.0.1        - --port        - "3000"    depends_on:      - setup    requirements:      toolchains:        - node    runtime:      kind: service      surfaces:        - appworkflows:  default: verify  verify:    intent: validation    setup:      task: setup    run:      task: verify  development:    intent: local_development    setup:      task: setup    run:      task: dev    readiness:      surfaces:        - app    exposes:      - surface: appchecks:  - name: node-installed    kind: precondition    severity: error    run: node --version  - name: app-ready    kind: health    severity: warn    probe: app-readyagent:  entrypoint: setup  default_task: verify  safe_tasks:    - setup    - lint    - test    - verify  verify_after_changes:    - verify  writable_paths:    - src    - tests    - docs    - node_modules  protected_paths:    - ota.yaml    - .env.local  notes: |    Start with `ota doctor`, then use `ota up --workflow development` for the service path.    Use `ota run verify --agent` after changes; do not add service startup to the finite verification task.