Why Ota Treats Setup Failures as Contract Signals

Most setup tooling treats failure like a generic inconvenience.

Something failed. Try again. Install a thing. Maybe copy a missing file. Maybe ask the maintainer.

That is not a serious readiness model.

Ota takes a stricter position:

when ota up fails, that failure should be treated as a contract signal first, with repair guidance attached second.

That matters because ota up is not supposed to be a bag of best-effort shell helpers. It is the path that tries to realize the repo's declared setup and readiness truth.

If that path cannot make the selected workflow ready, the first meaningful fact is not “setup had an issue.”

The first meaningful fact is:

the selected contract path did not become ready from declared truth

That is a better foundation for humans, CI, and AI agents.

There is a large difference between:

• “here are some commands that often help”
• “this repo declared a real setup path, and that path did not hold”

The first is convenience automation.

The second is execution governance.

If a repo says:

• these env vars are required
• these source files may supply them
• these services must become ready
• this setup path is canonical
• this workflow should be usable after preparation

then failure is no longer vague.

It belongs to one declared path.

That is why Ota should not flatten ota up failure into soft suggestion text too early. If it does, it stops being a readiness system and turns into a polite wrapper around setup drift.

ota up is not inventing a second model beside the contract.

It is using the contract to:

• select the repo or workflow preparation path
• evaluate declared prerequisites and setup requirements
• follow the declared setup task graph
• realize declared host preparation, dependency hydration, and service startup
• stop when the selected path is blocked

That is why ota up --dry-run matters so much as a preview lane.

It lets the operator inspect the exact selected path before writes or startup happen:

ota doctorota up --dry-runota execution plan

By the time mutating ota up runs, the repo is no longer in “maybe this is the right path” territory.

It is in “this is the declared path, now prove whether it becomes ready” territory.

When ota up fails, the answer should not be reduced to one vague bucket.

In practice, setup failure usually means one of three things:

1. A declared prerequisite was not satisfied

Examples:

• a required env value never resolved
• a declared source file marked must_exist: true is missing
• a required toolchain or tool is unavailable on the selected path
• a declared managed service did not become reachable

This is the cleanest failure class.

The contract said something had to be true, and it was not.

2. The repo depends on something that was never encoded

Examples:

• setup really needs seed data, but the contract never modeled it
• a task silently assumes one extra local file or shell export
• a service path relies on one unmodeled external system

This is not a random setup glitch.

It is missing contract truth.

That distinction matters, because the right next step is not only “try a different command.” The right next step may be to widen the contract so the repo stops depending on hidden setup folklore.

3. The contract drifted from reality

Examples:

• the repo changed package-manager or setup order
• a service host, file path, or readiness expectation moved
• CI or maintainer practice evolved, but ota.yaml did not

This is where Ota should be especially honest.

The failure is not proof that Ota is wrong to be strict. It is often proof that the repo's declared truth fell behind the repo's real operating model.

None of this means ota up should fail with no help.

The point is ordering.

The first job is to classify the failure truthfully.

The second job is to point to the narrowest useful next action.

That is why the stronger follow-up lane usually looks like:

• inspect env precedence with ota env
• inspect the selected path with ota execution plan
• review readiness blockers with ota doctor
• fix the missing declared requirement or widen the contract if the dependency was never encoded

That is very different from treating the whole failure as if it were only advisory.

Repair guidance is valuable precisely because it is attached to a real failure classification.

Imagine the selected workflow declares:

• DATABASE_URL is required
• .env.local is a declared source
• Postgres must be ready
• setup hydrates dependencies before the app path starts

If ota up fails because DATABASE_URL never resolves, the correct interpretation is:

• the selected path is not ready
• the contract-owned env requirement failed
• the next step is to inspect the env precedence path, not to guess randomly

If it fails because Postgres never becomes reachable, the correct interpretation is:

• the selected path is not ready
• the service/readiness contract failed
• the next step is to inspect the declared service owner and selected workflow boundary

If it fails because the repo really also needs seed data and that truth was never modeled, the correct interpretation is:

• the selected path is not ready
• the repo still depends on hidden setup state
• the contract needs widening

That is the useful difference. The failure belongs to something concrete.

If failure classification only lives in terminal text, it is too easy for setup truth to become anecdotal again.

Receipts are the durable layer.

They let Ota carry forward:

• which contract path was selected
• what findings were present
• what the execution identity was
• which follow-up lane Ota recommended
• whether the repo was actually ready

That is why execution receipts are not just logging garnish. They are part of the trust model.

When a repo keeps failing in the same place, the useful artifact is not “someone remembers what went wrong last week.”

The useful artifact is a receipt or archived readiness result that shows the drift explicitly and can be compared again later.

For the receipt surface, see:

• Execution Receipt

AI agents are especially vulnerable to weak setup semantics.

If failure is treated as generic automation noise, an agent will often do the wrong thing next:

• patch application code for a missing service problem
• rewrite config blindly
• add shell glue instead of fixing missing contract truth
• report “setup is flaky” when the actual issue is deterministic and modelable

That is expensive.

The stronger Ota posture is:

• fail the selected path honestly
• classify the failure
• keep the next step bounded
• preserve evidence in receipts and structured output

That gives an agent a real boundary between:

• “the repo contract failed”
• “the repo still hides setup truth”
• “the next repair step is this one”

ota up should not behave like a bag of repair guesses.

It should behave like a contract-realization path with truthful failure semantics.

That means:

• setup failures are contract signals first
• next actions are attached, not substituted
• hidden dependencies should be called out as missing contract truth
• receipts should preserve what failed and why

That is the difference between setup automation that feels helpful in the moment and setup infrastructure that teams and agents can actually trust over time.

• Command Reference
• Execution Receipt
• JSON Output Reference