npm test passed. Ota still caught missing repo setup truth.

One of the easiest ways to over-trust a repository is to run npm test, see green output, and conclude the repo is ready.

Sometimes that is true.

Often it is not.

A repo can have a passing unit-test command while still hiding setup truth such as:

• required env values that local tests never exercise
• a database or queue dependency that the real app path needs
• a generated file or SDK that was created once on one machine and never declared
• a readiness check that only matters when the actual workflow runs

That is exactly the gap Ota is meant to catch.

This is not about replacing npm test.

It is about proving that a passing test command is weaker than a declared readiness contract.

Imagine a Node repo with:

• fast unit tests that run fully in-process
• an app server that needs DATABASE_URL
• a local Postgres dependency
• one generated client file checked into neither source control nor the contract
• a contributor habit of treating npm test as the repo’s real readiness gate

The repo still has this contributor habit:

npm test

That command passes.

But the actual repo path a developer or agent cares about is closer to:

• can the repo explain what config it needs
• can it prove the required local dependency is reachable
• can it prepare the selected path cleanly
• can the declared app workflow actually become ready

Those are different questions.

npm test can pass because it is only proving one narrow truth:

• the package graph is already hydrated enough for the current shell
• the unit-test runner starts
• the test suite itself does not depend on the missing setup fact
• the test path never crosses the real app startup boundary

That does not prove:

• that required env values are declared and resolvable
• that required services exist and are reachable
• that the canonical setup path is explicit
• that the selected app workflow becomes ready
• that a new contributor, CI runner, or coding agent can follow the same path without tribal knowledge

This is how repos become deceptively green.

The test command is not wrong.

It is just narrower than the readiness claim people attach to it.

Ota approaches the same repo as a readiness problem first.

The contract can declare the missing setup truth directly:

version: 1project:  name: demoexecution:  default_context: host  contexts:    host:      backend: native toolchains:  node:    version: ">=20.0.0" env:  vars:    DATABASE_URL:      required: true      secret: true  sources:    - kind: dotenv      path: .env.local services:  postgres:    required: true    manager:      kind: compose      name: local      file: compose.yaml      service: postgres    endpoints:      host:        address: 127.0.0.1        port: 5432    readiness:      from: host      kind: tcp tasks:  setup:    prepare:      kind: dependency_hydration      medium: package_dependencies      source:        kind: node_package_manager        cwd: .        manager: npm        mode: install    requirements:      toolchains:        - node    effects:      writes:        - node_modules      network: true      network_kind: dependency_hydration   dev:    depends_on:      - setup    requires_services:      - postgres    launch:      kind: command      exe: npm      args: [run, dev]    requirements:      toolchains:        - node    runtime:      kind: service      readiness:        kind: http        listener: web        method: GET        path: /health        success:          status: [200]        timeout: 3s      listeners:        web:          protocol: http          bind:            address: 0.0.0.0            port:              mode: fixed              value: 3000          project:            host:              address: 127.0.0.1              port:                mode: fixed                value: 3000              primary: true checks:  - name: generated-client-present    kind: file    severity: error    path: src/generated/client.ts    expect: file workflows:  default: app  app:    setup:      task: setup    run:      task: dev    services:      required:        - postgres    readiness:      checks:        - generated-client-present

Now Ota can ask a better first question than did tests pass?

It can ask:

did the declared repo path become ready from declared truth?

The useful loop becomes:

ota doctorota checkota up --dry-runota proof runtime --workflow app

If the repo also models the app workflow as a real service launch, each command answers a different question:

• ota doctor: what declared readiness truth is currently missing or drifting
• ota check: which named checks fail without starting the full runtime path
• ota up --dry-run: what setup, services, and task path ota would select before mutation
• ota proof runtime --workflow app: whether the declared app workflow actually became ready on a proof boundary

And the failure becomes more honest.

Instead of:

• npm test passed, so the repo must be fine

the operator can see something more like:

◉ ERROR  Missing environment variable: DATABASE_URL
Why:
  » workflow `app` requires declared env var `DATABASE_URL`
  » no process env value or declared env source satisfied it
Next:
  » set `DATABASE_URL`
  » or add the intended source file to `env.sources`

◉ ERROR  Missing required file: src/generated/client.ts
Why:
  » check `generated-client-present` is part of workflow `app` readiness
Next:
  » generate the client artifact
  » or declare the setup path that owns its creation

◉ ERROR  Required service not ready: postgres
Why:
  » workflow `app` requires service `postgres`
  » declared readiness probe did not succeed

That is a much stronger artifact.

It tells you:

• which workflow path was selected
• which setup assumptions were missing
• whether the missing truth belongs to env, services, or generated state
• what the next repair lane should be

The repo is no longer hiding behind one passing command.

One common reaction is to make the test command heavier:

• add integration tests
• boot more services
• bolt generation onto the test script
• let npm test quietly do setup work first

That can make the failure harder to miss, but it still leaves ownership blurry.

The operator still cannot cleanly answer:

• which part was setup
• which part was dependency readiness
• which part was verification
• whether the fix should update contract truth or only local machine state

Ota keeps those layers explicit instead of compressing them into one shell surface.

There are at least three different truths here:

1. Test truth

npm test passed.

That is useful, but narrow.

2. Readiness truth

The selected repo path still cannot become ready because config, dependency, or generated-state assumptions are missing.

That is the operational truth.

3. Governance truth

The missing assumptions now have an explicit home in the contract instead of living in maintainer memory, shell history, or “works on my machine” residue.

That is the long-term value.

This is exactly the kind of repo where a coding agent can look competent and still be wrong.

An agent can:

• run npm test
• see green
• make a patch
• hand back the change as “verified”

while missing the real repo requirement entirely.

That is not mainly a model-quality problem.

It is an execution-governance problem.

Without a contract, the agent has no authoritative answer to:

• which setup path is canonical
• which env values are real requirements
• which services matter
• which check proves readiness
• which workflow should actually count as done

Ota gives the repo a way to declare those things explicitly.

This is the core point:

npm test can prove that one test command succeeded.

Ota can prove that the repo still has undeclared or unsatisfied setup truth.

Those are not competing answers.

They are different layers of truth, and the second one is the layer most teams eventually need when:

• onboarding a new contributor
• aligning local, CI, and agent execution
• diagnosing why “it worked yesterday”
• deciding whether the fix belongs in code, setup, or the contract

If you want the underlying product surfaces behind this demo, use these together:

• Repo Readiness
• Defining Readiness
• Environment Model
• Readiness Model
• Execution Receipt Reference
• Command Reference

The right standard is not:

one command passed, therefore the repo is ready

The right standard is closer to:

the repo declared what it needs, Ota evaluated that declared path, and the selected workflow either became ready or surfaced the exact missing setup truth

That is a much better technical demo of what repo readiness means.

npm test can prove that a test command passed.

It cannot, by itself, prove that a repo is operationally ready.

Ota is useful in the gap between those two claims.

That is where missing env truth, hidden service dependencies, generated artifacts, and workflow readiness drift usually live.

And that is exactly where a serious repo contract should be stronger than a passing shell command.