# █████

# ░░███

# ██████ ███████ ██████

# ███░░███░░░███░ ░░░░░███

# ░███ ░███ ░███ ███████

# ░███ ░███ ░███ ███ ███░░███

# ░░██████ ░░█████ ░░████████

# ░░░░░░ ░░░░░ ░░░░░░░░

#

# Copyright (C) 2026 — 2026, Ota. All Rights Reserved.

#

# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

#

# Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

# You may not use this file except in compliance with that License.

# Unless required by applicable law or agreed to in writing, software distributed under the

# License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,

# either express or implied. See the License for the specific language governing permissions

# and limitations under the License.

#

# If you need additional information or have any questions, please email: os@ota.run

version: 1

project:

name: ota

description: Ota CLI and Contract Engine

type: application

metadata:

team: Engineering

owner: ota

repo_class: open-core

execution:

preferred: container

lifecycle: persistent

supported:

- native

- container

backends:

container:

image: rust:1.95-bookworm

engines:

- docker

- podman

env:

vars:

PATH:

prepend:

- /usr/local/cargo/bin

- /usr/local/rustup/bin

tools:

toolchains:

rust:

version: "1.95.0"

components:

- rustfmt

fulfillment:

mode: run

checks:

- name: repository-readme

kind: file

severity: info

path: README.md

expect: file

tasks:

setup:

description: Prepare the Rust toolchain and fetch dependencies

notes: |

Use this as the first step in a fresh checkout or after dependency changes.

Ota fulfills the declared Rust toolchain on the selected execution path, then

prepares the workspace without compiling the crate.

category: setup

internal: true

command:

exe: cargo

args:

- fetch

requirements:

toolchains:

- rust

safe_for_agent: true

build:

description: Compile the CLI

notes: |

Use this when you want to confirm the crate still builds after code changes.

category: build

command:

exe: cargo

args:

- build

requirements:

toolchains:

- rust

depends_on:

- setup

safe_for_agent: true

fmt:

description: Check Rust formatting

notes: |

Use this before committing to catch formatting drift early.

category: test

command:

exe: cargo

args:

- fmt

- --check

requirements:

toolchains:

- rust

safe_for_agent: true

check:

description: Type-check the crate

notes: |

Use this for a fast compiler-only verification pass without running tests.

category: test

command:

exe: cargo

args:

- check

requirements:

toolchains:

- rust

depends_on:

- setup

safe_for_agent: true

test:

description: Run the Rust test suite

notes: |

Use this when you want the full unit and integration test coverage.

category: test

command:

exe: cargo

args:

- test

requirements:

toolchains:

- rust

depends_on:

- setup

safe_for_agent: true

ci:

description: Run the standard local verification suite

notes: |

Use this as the canonical local pre-commit gate.

It matches the light-weight verification path used during development.

A few process-global tests run in separate cargo invocations so container CI

preserves coverage without leaking test-local PATH or service state.

category: test

script: |

set -e

cargo fmt --check

cargo check

cargo test --lib -- --test-threads=1 \

--skip cli::tests::up_skips_policy_backed_provisioning_when_doctor_is_ready \

--skip doctor::tests::remote_doctor_mode_probes_tool_versions_through_remote_contexts \

--skip runner::tests::restart_ready_activation_restarts_reachable_backend_provider_host_producer \

--skip runner::tests::restart_ready_activation_restarts_reachable_backend_provider_topology_target \

--skip runner::tests::restart_ready_activation_restarts_reachable_native_producer

cargo test up_skips_policy_backed_provisioning_when_doctor_is_ready --lib -- --test-threads=1

cargo test remote_doctor_mode_probes_tool_versions_through_remote_contexts --lib -- --test-threads=1

cargo test restart_ready_activation_restarts_reachable --lib -- --test-threads=1

variants:

- when:

os: windows

script: |

cargo fmt --check

if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

cargo check

if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

cargo test --lib -- --test-threads=1 --skip cli::tests::up_skips_policy_backed_provisioning_when_doctor_is_ready --skip doctor::tests::remote_doctor_mode_probes_tool_versions_through_remote_contexts --skip runner::tests::restart_ready_activation_restarts_reachable_backend_provider_host_producer --skip runner::tests::restart_ready_activation_restarts_reachable_backend_provider_topology_target --skip runner::tests::restart_ready_activation_restarts_reachable_native_producer

if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

cargo test up_skips_policy_backed_provisioning_when_doctor_is_ready --lib -- --test-threads=1

if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

cargo test remote_doctor_mode_probes_tool_versions_through_remote_contexts --lib -- --test-threads=1

if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

cargo test restart_ready_activation_restarts_reachable --lib -- --test-threads=1

requirements:

toolchains:

- rust

depends_on:

- setup

- agents:sync:check

safe_for_agent: true

doctor-annotations:

description: Render ota doctor findings for CI or local review

notes: |

Use this to turn ota doctor JSON into plain CI output or GitHub annotations.

It is the repo-side adapter for hosted validation demos and PR checks.

category: dev

inputs:

render_format:

description: Output format for findings rendering

default: plain

allowed:

- plain

- github

script: |

ota doctor --json . | ota annotations --mode doctor --format "${OTA_INPUT_RENDER_FORMAT}" --input -

variants:

- when:

os: windows

script: |

ota doctor --json . | ota annotations --mode doctor --format $env:OTA_INPUT_RENDER_FORMAT --input -

depends_on:

- setup

safe_for_agent: true

contract:validate:

description: Validate the ota repo contract with the current checkout

notes: |

Use this to self-host the contract validator against `./ota.yaml`.

It exercises hook follow-ups inside the main repo without touching build artifacts or snapshots.

category: dev

command:

exe: cargo

args:

- run

- --quiet

- --bin

- ota

- --

- validate

- ./ota.yaml

- --plain

requirements:

toolchains:

- rust

after_success:

- contract:tasks

after_failure:

- contract:doctor

depends_on:

- setup

safe_for_agent: true

contract:tasks:

description: Show the next runnable task surface after contract validation succeeds

notes: |

Use this as the success follow-up for `ota run contract:validate`.

It keeps the repo contract self-hosting by pointing straight at the validated task surface.

category: dev

command:

exe: cargo

args:

- run

- --quiet

- --bin

- ota

- --

- tasks

- .

- --use

- --plain

requirements:

toolchains:

- rust

safe_for_agent: true

contract:doctor:

description: Show readiness detail after contract validation fails

notes: |

Use this as the failure follow-up for `ota run contract:validate`.

It points the operator at concrete readiness findings instead of stopping at a raw validation error.

category: dev

command:

exe: cargo

args:

- run

- --quiet

- --bin

- ota

- --

- doctor

- .

- --plain

requirements:

toolchains:

- rust

safe_for_agent: true

agents:sync:check:

description: Verify checked-in agent guidance matches the canonical contract

notes: |

Use this after changing `agent` contract fields or `AGENTS.md`.

It refuses when the managed AGENTS.md block is stale without rewriting the protected file.

category: test

script: |

set -e

review="$(cargo run --quiet --bin ota -- agents . --review --json)"

printf '%s\n' "$review" | grep -q '"sync_state": "in_sync"'

variants:

- when:

os: windows

script: |

$review = cargo run --quiet --bin ota -- agents . --review --json | ConvertFrom-Json

if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

if ($review.sync_state -ne "in_sync") {

Write-Error "AGENTS.md managed guidance is out of sync with ota.yaml"

exit 1

}

requirements:

toolchains:

- rust

depends_on:

- setup

safe_for_agent: true

compat:

description: Run the compatibility test gate

notes: |

Use this to validate generated schema/doc publication sync, schema stability, and fixture coverage before release work.

category: test

script: |

set -e

cargo run --bin sync_published_contract_schemas

cargo run --bin sync_published_doc_manifests

git diff --exit-code -- docs/spec/json-schemas/contract.json docs/spec/json-schemas/workspace-contract.json docs/spec/published-docs/canonical-docs.json

CARGO_INCREMENTAL=0 cargo test contract_is_stable

CARGO_INCREMENTAL=0 cargo test --test json_schema_contracts

CARGO_INCREMENTAL=0 cargo test --test json_output_conformance

CARGO_INCREMENTAL=0 cargo test --test examples_validate -- --test-threads=1

CARGO_INCREMENTAL=0 cargo test --test detect_fixtures

variants:

- when:

os: windows

script: |

cargo run --bin sync_published_contract_schemas

if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

cargo run --bin sync_published_doc_manifests

if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

git diff --exit-code -- docs/spec/json-schemas/contract.json docs/spec/json-schemas/workspace-contract.json docs/spec/published-docs/canonical-docs.json

if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

$env:CARGO_INCREMENTAL = "0"

cargo test contract_is_stable

if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

cargo test --test json_schema_contracts

if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

cargo test --test json_output_conformance

if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

cargo test --test examples_validate -- --test-threads=1

if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

cargo test --test detect_fixtures

requirements:

toolchains:

- rust

depends_on:

- setup

safe_for_agent: true

first-party:sync:check:

description: Enforce first-party consumer sync governance for governed surface changes

notes: |

Use this when contract-shape, governance-surface, or canonical-docs ownership files change

and you need to prove first-party consumer repos such as ota-run/skills or ota-run/ota-site

were either synced or explicitly waived.

category: test

command:

exe: ./scripts/check-first-party-sync.sh

safe_for_agent: true

pressure:evidence:site:check:

description: Verify the generated Site pressure-evidence projection against Core

notes: |

Use this from the coordinated Ota workspace after changing docs/pressure evidence.

Core owns the manifest; the Site commits only its generated discovery projection.

This refuses a stale projection rather than allowing the Site to restate pressure claims.

category: test

script: |

set -e

test -f ../ota-site/lib/sync-pressure-evidence.mjs

OTA_CORE_ROOT="$PWD" node ../ota-site/lib/sync-pressure-evidence.mjs --check

execution:

default_mode: native

safe_for_agent: true

skills:sync:check:

description: Compatibility alias for the first-party consumer sync governance check

notes: |

Prefer `first-party:sync:check`. This alias keeps older maintainer flows working while the

governance surface widens beyond ota-run/skills alone.

category: test

command:

exe: ./scripts/check-skills-sync.sh

safe_for_agent: true

schemas:sync:

description: Regenerate the published repo and workspace contract schema artifacts

notes: |

Use this after changing the Rust-owned published contract schema generator.

It rewrites `docs/spec/json-schemas/contract.json` and

`docs/spec/json-schemas/workspace-contract.json` from the canonical Rust source.

category: dev

command:

exe: cargo

args:

- run

- --bin

- sync_published_contract_schemas

requirements:

toolchains:

- rust

safe_for_agent: true

docs:manifest:sync:

description: Regenerate the published canonical docs manifest artifact

notes: |

Use this after changing the Rust-owned canonical docs publication surface.

It rewrites `docs/spec/published-docs/canonical-docs.json` from the canonical Rust source.

category: dev

command:

exe: cargo

args:

- run

- --bin

- sync_published_doc_manifests

requirements:

toolchains:

- rust

safe_for_agent: true

candidate-publication:faults:

description: Exercise contract-candidate publication fault boundaries

notes: |

Use this to verify concurrent target creation, pre-publication cleanup failure, and

post-publication durability uncertainty through the non-default test-only feature.

Production and ordinary debug binaries do not expose these fault controls.

category: test

command:

exe: cargo

args:

- test

- --features

- test-candidate-publication-faults

- --test

- json_output_conformance

- contract_candidate_write_faults_report_publication_truthfully

- --

- --exact

variants:

- when:

os: windows

command:

exe: pwsh

args:

- -NoProfile

- -Command

- Write-Output 'Skipping contract-candidate publication fault tests on Windows'

requirements:

toolchains:

- rust

safe_for_agent: true

effect-refusal-archive:faults:

description: Exercise typed-effect refusal archive post-publication durability reporting

notes: |

Use this to verify that a directory-sync failure after atomic archive publication reports

the exact published path and an explicit durability-uncertain posture. Production and

ordinary debug binaries do not expose this fault control.

category: test

command:

exe: cargo

args:

- test

- --features

- test-effect-refusal-archive-faults

- --test

- json_output_conformance

- typed_effect_policy_decision_causes_exact_pre_side_effect_refusal

- --

- --exact

variants:

- when:

os: windows

command:

exe: pwsh

args:

- -NoProfile

- -Command

- Write-Output 'Skipping typed-effect refusal archive fault tests on Windows'

requirements:

toolchains:

- rust

safe_for_agent: true

proof-assurance:faults:

description: Exercise runtime-proof attestation substitution at the live reconciliation boundary

notes: |

Use this to verify that a second valid attestation from the same proof run cannot replace

the selected negative-control digest before terminal verdict, receipt, or archive emission.

Production and ordinary debug binaries do not expose this fault control.

category: test

command:

exe: cargo

args:

- test

- --features

- test-proof-assurance-faults

- --test

- json_output_conformance

- proof_runtime_refuses_valid_sibling_attestation_substitution_before_positive_evidence

- --

- --exact

variants:

- when:

os: windows

command:

exe: pwsh

args:

- -NoProfile

- -Command

- Write-Output 'Skipping runtime-proof assurance fault tests on Windows'

requirements:

toolchains:

- rust

safe_for_agent: true

release-gate:

description: Run the GitHub Actions verification suite

notes: |

Use this to verify the repo against the release gate checks that run in GitHub Actions.

category: test

script: |

set -e

if [ "$OSTYPE" != "msys" ] && [ "$OSTYPE" != "win32" ]; then

cargo test --test real_repo_fixtures -- --test-threads=1

cargo test --test examples_validate -- --test-threads=1

else

echo "Skipping integration tests on Windows"

fi

variants:

- when:

os: windows

script: |

echo Skipping integration tests on Windows

requirements:

toolchains:

- rust

depends_on:

- ci

- candidate-publication:faults

- effect-refusal-archive:faults

- proof-assurance:faults

- compat

- first-party:sync:check

- dependency-update

safe_for_agent: true

ux-review:

description: Run the premium CLI UX review suite

notes: |

Use this after changing help text, human-readable command output, or docs that promise

specific CLI presentation. It keeps the premium snapshot-backed text surfaces honest.

category: test

command:

exe: cargo

args:

- test

- snapshot_is_stable

- --

- --test-threads=1

requirements:

toolchains:

- rust

depends_on:

- setup

safe_for_agent: true

ux:refresh:

description: Refresh premium CLI UX snapshots

notes: |

Use this when snapshot-backed output intentionally changes. It updates snapshots before

rerunning `ota run ux-review`.

category: test

inputs:

test_threads:

description: Test threads for snapshot refresh (default 1)

default: "1"

script: |

OTA_UPDATE_SNAPSHOTS=1 cargo test snapshot_is_stable -- --test-threads=${OTA_INPUT_TEST_THREADS}

requirements:

toolchains:

- rust

depends_on:

- setup

safe_for_agent: true

bump:version:

description: Bump the repo release version surfaces

notes: |

Use this through `ota run bump:version --version <patch|minor|major>` when preparing

a release and you need to update Cargo.toml, CHANGELOG.md, and the readiness workflow

pin consistently.

category: release

command:

exe: ./scripts/bump-version.sh

inputs:

version:

description: Release bump selector (`patch`, `minor`, `major`) or explicit semver version

required: true

depends_on:

- ci

dependency-update:

description: Validate dependency updates with schema/contract tests and lockfile bump tests

notes: |

Use this to validate that dependency updates are safe and deterministic.

Runs schema/contract validation and a focused test subset for lockfile bumps

to ensure CI-owned proof independent of local wrapper quirks.

category: test

script: |

set -e

# Run schema/contract validation

cargo run --quiet --bin ota -- validate ./ota.yaml --plain

# Run lockfile-specific tests

cargo test --test real_repo_fixtures -- --test-threads=1 --skip workspace_refresh_pulls_updated_git_sources_on_real_command_path

requirements:

toolchains:

- rust

depends_on:

- setup

- ci

safe_for_agent: true

install:

description: Reinstall ota from the local workspace

notes: |

Use this after local changes when you want the installed ota binary to point at this checkout.

category: dev

execution:

default_mode: native

command:

exe: ./scripts/install.sh

args:

- --from-source

variants:

- when:

os: windows

command:

exe: powershell

args:

- -ExecutionPolicy

- Bypass

- -File

- .\scripts\install.ps1

- -FromSource

agent:

entrypoint: setup

default_task: ci

safe_tasks:

- setup

- build

- fmt

- check

- test

- ci

- doctor-annotations

- contract:validate

- contract:tasks

- contract:doctor

- agents:sync:check

- compat

- first-party:sync:check

- pressure:evidence:site:check

- skills:sync:check

- schemas:sync

- docs:manifest:sync

- candidate-publication:faults

- effect-refusal-archive:faults

- proof-assurance:faults

- release-gate

- ux-review

- ux:refresh

- dependency-update

verify_after_changes:

- ci

writable_paths:

- src

- docs

- README.md

- scripts

- tests

- tasks

- CHANGELOG.md

- Cargo.toml

protected_paths:

- .github

- AGENTS.md

- Cargo.lock

- ota.yaml

- LICENSE

bootstrap:

ota:

note: Only install ota if it is missing and installation is approved.

source:

kind: git_rev

rev: 1591f574edf76f2c69c6a811dc2b07e5ed3b90d3

notes: |

Treat Ota as the default workflow, the way npm is the default in Node repos.

Use `ota validate` to verify the contract.

Use `ota doctor` to inspect readiness and agent guidance.

Use `ota tasks` to discover runnable repo actions.

When a repo already exposes a matching safe task, prefer `ota run <task>` over raw package-manager or language-tool commands.

Fall back to direct commands only when no truthful Ota task exists or when isolating an Ota defect.

Agent-safe means admitted through the declared contract, not necessarily read-only; inspect task notes, effects, and writable paths before running maintenance tasks that regenerate tracked artifacts.

Use `ota run setup` to prepare the repo.

Use `ota run contract:validate` to self-host the contract validator against this checkout.

Use `ota run ci` to run the canonical verification path.

Read `docs/ai/current-state.md` and the active plan before substantive work; they own the current implementation boundary and next proof gate.

Do not activate a later version or implementation step without an explicit reviewed and committed activation record.

Do not initiate live provider, credential, cloud, VPS, or network pressure work unless the active plan authorizes that exact boundary and the user explicitly requests it.

Treat `.github`, `AGENTS.md`, `Cargo.lock`, `ota.yaml`, and `LICENSE` as protected; change them only with explicit task-specific authorization.

After changing agent guidance, run `ota run agents:sync:check --agent`; regenerate the managed block with `ota agents . --write` only when the contract change is intentional and authorized.

Preserve unrelated worktree changes and inspect connected Core, Examples, Skills, Site, Learn, FAQ, and Glossary surfaces before declaring product work complete.

Prefer narrow changes with regression tests.

Keep public docs and contracts aligned with implementation.