Ota Assist

Ota already knows how to validate contracts, inspect declared topology, and explain readiness truth. ota assist exists so ota can turn that knowledge into one reviewed mutation at a time instead of making maintainers hand-author every YAML block.

ota assist is not chat and must not become a second source of truth. It is a deterministic contract operation surface above the same ota.yaml the rest of ota already trusts.

Preview is the default. ota assist ... only shows the proposed contract change. Nothing is written until you rerun that same command with --write.

• use preview mode first to inspect the exact proposal, then rerun with --write only when you want ota to update the contract
• assist proposes one bounded change instead of broad contract inference
• assist refuses when contract or repo truth is too weak for a safe proposal
• assist uses the same validator and doctor surfaces after apply instead of inventing a parallel authoring engine

The current shipped assist surface has seven deterministic operations: ota assist declare-readiness, ota assist declare-service, ota assist bind-task, ota assist wire-setup, ota assist declare-env, ota assist add-task, and ota assist normalize.

• ota assist declare-readiness targets a task runtime with --task <name> or a top-level managed service with --service <name>
• ota assist declare-service creates or refines one top-level managed service with --name <service> plus either explicit local manager/endpoint inputs or one canonical workspace producer binding through --producer-repo <repo> --producer <task>[:listener]
• ota assist bind-task creates or refines one tasks.<consumer>.targets.<name> edge to a producer task runtime listener
• ota assist wire-setup creates or refines tasks.setup with one explicit setup body plus an optional setup.requires_services pre-setup service phase
• ota assist declare-env creates or refines one root env requirement, one declared env source, or one explicit tasks.<name>.env.<KEY> override
• ota assist add-task creates one new tasks.<name> entry with an explicit execution body and optional fixed service listener inputs
• ota assist normalize moves one existing setup-like task into the canonical tasks.setup slot
• use --member <name> when the contract lives in a monorepo member overlay
• use --json when an editor, agent, or CI tool needs the machine proposal instead of review text
• use --style spring-http|http|tcp for task readiness shape selection, and --style compose-health for compose-managed service health state

ota assist declare-readiness --task dev

ota assist declare-service --name postgres --manager compose --port 5432 --style tcp

ota assist declare-service --name api --manager compose --compose-file docker-compose.yml --port 3000 --style http --write

ota assist declare-service --name worker --manager compose --compose-file docker-compose.yml --style compose-health

ota assist declare-service --name user-api --producer-repo api --producer dev:http --write

ota assist bind-task --task smoke --target api --to dev:http

ota assist wire-setup --run "npm install" --service postgres

ota assist declare-env --name APP_PORT --required true --default 8080

ota assist add-task --name smoke --run "cargo test"

ota assist normalize --task bootstrap --into setup

Task-targeted readiness works best when the service task and listener are already declared in the contract.

• for a Spring Boot task, ota can usually infer the http listener and propose the stronger spring-http profile
• for a single TCP listener, ota can propose TCP readiness without inventing an HTTP path
• for mixed-listener runtimes, ota now derives the style from the selected readiness listener instead of guessing from the runtime abstractly

ota assist declare-readiness --task dev --style spring-http

ota assist declare-readiness --task postgres --style tcp

Top-level managed services are stricter because a service endpoint only proves address and port projection, not protocol truth.

• if a managed service already has structured readiness, assist can refine that shape
• if the service does not already carry structured readiness, pass --style explicitly
• use --style compose-health when the service is compose-managed and container health state is the truthful readiness source
• use ota assist declare-service when the service block itself does not exist yet or still needs manager and endpoint truth
• ota assist declare-service --style compose-health is valid for compose-managed services and writes readiness.kind: compose_health without forcing a host endpoint projection
• use ota assist declare-service --producer-repo <repo> --producer <task>[:listener] when the service is canonically owned by another repo in the same workspace and local manager/readiness YAML would only duplicate that truth
• this keeps assist from quietly proposing an HTTP /health probe for a plain TCP service such as Postgres or Redis

ota assist declare-readiness --service api --style http

ota assist declare-readiness --service postgres --style tcp

ota assist declare-service --name worker --manager compose --compose-file docker-compose.yml --style compose-health

ota assist declare-service --name postgres --manager compose --compose-file docker-compose.yml --port 5432 --style tcp

ota assist declare-service --name cache --manager host --port 6379

ota assist declare-service --name user-api --producer-repo api --producer dev:http

When you pass --member, assist writes only the targeted member overlay while validating the merged member contract through the root monorepo path.

• this keeps the write narrow to the member file that actually owns the override
• validation still uses the merged contract truth, so assist does not pretend the member overlay is a standalone repo contract

ota assist declare-readiness --member api --task dev --style spring-http

ota assist bind-task --member api --task smoke --target api --to dev:http --write

ota assist bind-task is the current assist slice for wiring one consumer edge to one producer runtime listener through the contract.

• use it when the producer task runtime already exists and the remaining gap is one truthful targets.<name> binding
• use --to <task> only when the producer exposes exactly one declared listener or the existing target already pins one safe listener
• use --to <task>:<listener> when the producer has multiple listeners and you need one explicit edge
• the current shipped slice binds to producer task runtimes, not directly to top-level managed service endpoints

ota assist bind-task --task smoke --target api --to dev:http

ota assist bind-task --task smoke --target api --to dev --json

ota assist bind-task --task smoke --target api --to dev:http --address-view host --activation ensure_ready

ota assist wire-setup is the narrow assist slice for the phased ota up model.

• create tasks.setup only when you have an explicit setup body to declare
• use --service <name> to define which managed services must start before setup runs
• use --clear-services when setup should no longer have a pre-setup service phase
• assist preserves unrelated existing setup fields instead of rewriting the whole task

ota assist wire-setup --run "npm install"

ota assist wire-setup --run "npm install" --service postgres --service redis

ota assist wire-setup --member api --run "npm install" --service postgres --write

ota assist declare-env is the narrow assist slice for reviewed env requirements, declared source files, and one task-local env override at a time.

• use root env requirements when one value should stay visible, reviewable, and enforceable in the contract
• use declared env sources only when the repo intentionally depends on that file instead of ambient shell state
• use task-local env only for one explicit task override such as a fixed API base URL or CI=true
• --prepend and --append are restricted to PATH so list-style env composition stays narrow and truthful
• --member still validates the merged monorepo contract even though assist only writes the targeted member overlay

ota assist declare-env --name APP_PORT --required true --default 8080

ota assist declare-env --source-kind dotenv --source-path .env.local --must-exist true --json

ota assist declare-env --task smoke --name API_BASE --value http://127.0.0.1:3000 --write

ota assist add-task is the narrow assist slice for one new task declaration at a time.

• use it when the contract needs a new task entry and the right next move is a reviewed starter task instead of raw YAML authoring
• use --run or --script for every kind except sandbox, which can use the bounded echo sandbox starter body
• use --kind service only when you can declare one explicit listener, protocol, and port instead of asking assist to guess runtime shape
• use --member when the new task belongs in a monorepo member overlay instead of the root contract

ota assist add-task --name smoke --run "cargo test"

ota assist add-task --name dev --kind service --run "npm run dev" --listener http --protocol http --port 3000 --json

ota assist add-task --name sandbox --kind sandbox

ota assist add-task --member api --name smoke --run "npm test" --write

ota assist normalize is the narrow assist slice for moving one existing setup-like task into the canonical tasks.setup slot.

• use it when the repo already has one setup-like task under a local name such as bootstrap and the right next move is to make that truth canonical
• the current shipped scope is only --into setup
• assist deletes the original tasks.<name> entry in the same write target and writes the moved task under tasks.setup
• member-scoped normalize only works when the selected task is declared in that member overlay file, not inherited from the root contract

ota assist normalize --task bootstrap --into setup

ota assist normalize --member api --task bootstrap --into setup --write

Refusal is part of the trust model. When repo truth is too weak, ota should stop instead of guessing.

• multiple candidate listeners with no safe selection
• managed service with no protocol signal and no explicit --style
• a new managed service without an explicit manager kind
• a service with multiple endpoint projections and no explicit --endpoint when assist cannot choose safely
• a producer task binding with multiple listeners and no safe explicit or inherited listener selection
• a new setup declaration without an explicit --run or --script body
• an ota assist wire-setup service name that is not already declared under services
• an ota assist declare-env --task <name> --name <ENV> request without --value for the task-local env write
• an ota assist declare-env request that tries to use --prepend or --append on anything except PATH
• an ota assist declare-env request that combines --secret true with a new --default value
• an ota assist add-task request for a task name that already exists in the effective contract
• an ota assist add-task --kind service request without --listener, --protocol, or --port
• an ota assist add-task --kind setup request that does not target --name setup
• an ota assist normalize --task <name> --into setup request when tasks.setup already exists
• a member-scoped ota assist normalize request where the selected task is inherited from the root contract instead of declared in the member overlay
• task or service target that does not exist in the declared contract
• explicit --style http against a selected TCP listener
• replacement that would be surprising still shows the current readiness block before the proposed one in text preview

Editors, agents, and CI should consume the assist JSON contract instead of scraping review text.

• use mode, subject, inputs, assumptions, changes, validation, and next as the stable machine fields
• the live schemas for the current shipped assist surface are assist-declare-readiness.json, assist-declare-service.json, assist-bind-task.json, assist-wire-setup.json, assist-declare-env.json, assist-add-task.json, and assist-normalize.json
• use the JSON Output page when you need the public schema URL and the exact payload contract

ota assist declare-readiness --task dev --json

ota assist declare-service --name cache --manager host --port 6379 --json

ota assist bind-task --task smoke --target api --to dev --json

ota assist wire-setup --run "npm install" --service postgres --json

ota assist declare-env --source-kind dotenv --source-path .env.local --json

ota assist add-task --name dev --kind service --run "npm run dev" --listener http --protocol http --port 3000 --json

ota assist normalize --task bootstrap --into setup --json