Ota v1.6.23 Now Available: Machine-Readable Execution Governance

Idea

v1.6.23 is a machine-readable governance release.

The pressure behind this version is straightforward: if Ota asks humans, CI, and AI agents to share one execution contract, then governance cannot stay partly implicit.

It has to be emitted as structured truth.

This release pushes exactly that boundary. Ota now publishes clearer governance posture before execution, clearer evidence after execution, and clearer drift ownership when contracts diverge from external repo sources.

At the same time, v1.6.23 widens first-class contract ownership for setup, orchestrator mediation, and deterministic Git materialization so more repos can stay out of shell glue.

Feature

v1.6.23 is broad, but the release is coherent. It strengthens six connected execution-governance surfaces.

1. Governance output is now significantly more machine-readable

This release adds and widens core machine output that CI systems and agent harnesses can consume directly:

• additive governance summaries on ota run --dry-run --json and ota up --json
• additive governance.merge_gate and governance.required_verification_lanes on ota doctor --json
• additive metadata.governance.merge_check_id for stable merge-lane identity
• additive capability_profile on ota tasks --json and ota workflows --json
• additive artifact_routing[] across dry-run, receipt, proof, repo up, and workspace lanes
• additive stage_family and phase signals across receipts, proof JSON, and workspace progress streams

The practical effect is important: external consumers can now read governance posture, execution lane identity, and follow-up artifact routing without scraping terminal prose or reverse-engineering semantics from mixed fields.

2. Agent safety moved from guidance toward enforced runtime behavior

v1.6.23 hardens agent-mode governance in two ways.

First, ota run --agent and ota up --agent now enforce execution-boundary safety at preflight time, with explicit refusal behavior and structured blocked receipts/results.

Second, governance evidence now carries clearer phase semantics (not_run_reason, crossing_record_state) so non-executed lanes are no longer ambiguous in machine output.

This is the right direction for serious agent operations: safety has to be enforceable and inspectable, not only documented.

3. Crossing and merge governance became explicit

This release introduces the first audited crossing-evidence slice for heavier lanes:

• additive --reason <text> support on ota run and ota up
• optional receipt.crossing on repo-target execution receipts
• mirrored governance.crossing on ota up --json where applicable

In parallel, merge-oriented governance output gets stronger with projected-vs-drift-aware merge gates and required verification lane projection.

Together, these changes make Ota much better at answering two high-value questions in machine-readable form:

• should this lane run under this governance posture?
• what exact verification identity should merge consumers trust?

4. Source-governance and detect pressure widened substantially

v1.6.23 also expands V11.2 detector-source governance and drift review pressure across real repo-owned sources:

• mise.toml, .devcontainer/devcontainer.json (including JSONC), devbox.json, and devenv.nix
• structured external AGENTS.md / CLAUDE.md boundaries and bounded command-table lanes
• Taskfile/justfile and GitHub Actions verification-lane recovery and drift warnings

The key product move is not “detect more things.”

It is that Ota now treats source provenance and source-class confidence as first-class governance signals, and warns when manual contract truth drifts from stronger external evidence.

That helps keep contracts honest as repos evolve.

5. First-class setup and action ownership widened again

This release also removes more setup-shell pressure by widening structural ownership:

• prepare.kind: tool_bootstrap now includes prepare.tool: cypress_browsers
• prepare.kind: dependency_hydration now supports source.kind: composer
• action.kind: ensure_git_template added for template materialization with fresh init
• action.kind: ensure_git_checkouts added for multi-checkout bootstrap
• ensure_git_checkout/ensure_git_checkouts widened with remote wiring and workspace-relative targets
• first-class effects.workspace_writes for explicit sibling/workspace mutation ownership
• compose.build: true and compose.service_ports: true on compose.kind: run

This continues Ota's core posture: if the behavior is real and repeatable, it should be modeled structurally in contract truth.

6. Orchestrator ownership became broader and more usable

v1.6.23 widens orchestrator mediation beyond earlier slices:

• first-class devbox and devenv orchestrator kinds
• mediated command previews across task, exec, and subcommand
• orchestrator-mediated prepare execution for command-backed hydration/bootstrap via execution.orchestrator.mode: exec
• native activation ordering fix for command-acquired tools used by orchestrated lanes
• ota doctor --fix widening to deterministic command-acquired tool activation

This closes a common real-world gap: repos can now keep orchestrator truth in contract-owned execution lanes without pretending host PATH ownership or dropping back to wrapper scripts.

Docs

If you want to adopt these capabilities directly, use the live docs:

• Get Started: Install Ota and begin with ota doctor
• Governance model: Governance for merge posture, safety posture, and machine-readable governance truth
• Architecture loop: Execution Governance Loop for how contract, execution, proof, and governance fit together
• Contract reference: Contract for tasks, workflows, setup, actions, and governance fields
• Command reference: Commands for ota doctor, ota tasks, ota workflows, ota run, and ota up
• JSON output: JSON output reference for governance, receipt, proof, and artifact-routing output
• Workflow modeling: Workflows for verification lanes, workflow intent, and execution boundaries

Release

v1.6.23 is live here: https://ota.run/releases/v1.6.23

If you already use Ota, upgrade and verify:

ota upgrade
ota --version
ota validate
ota doctor --json
ota tasks --safe --use
ota run <task> --dry-run --json

v1.6.23 keeps Ota on its core path: one declared contract, one governed execution model, and machine-readable evidence that lets humans and agents trust the same operational truth.

---

Original post here: https://ota.run/blog/ota-v1-6-23-release-essay

Comments

[Vinicius Pereira]

governance has to be emitted as structured truth is the right target, but the hard half isn't emitting it, it's keeping the emitted thing honest after it ships. a JSON receipt that says approved: reason X can lie exactly as confidently as a human comment, and it's worse because it looks like data so nobody re-reads it. the failure i keep hitting: someone edits the enforcement branch, nobody touches the code that writes the governance field, and now the structured truth is structured and wrong. what i'd want next to these fields is a reconciliation guarantee, the receipt built on the same line where the decision is made rather than assembled afterward from a second read of state, plus a preflight check that what the receipt claims fired actually fired. move the reason into the branch that grants it and there's no second place to forget it.

the --reason flag on crossing/merge is the same theme one level down. a free-text reason a human types is self-attested, so the receipt captures what the operator claimed, not what got verified. still a real gain because the claim is now attributable, but it'd be worth making the schema say which fields are captured (the human asserted this) vs derived (the system checked this), since an agent consuming them downstream will otherwise treat both as equally true. good direction, evidence as a first-class output is what agent contracts have been missing.

[Bobai Kato Ota]

Strong point. Emitting governance as JSON is only half the job; the harder part is keeping it reconciled with the exact branch that made the decision.

The direction for Ota is the same one you’re describing: the authoritative record should be emitted at the decision site, not reconstructed afterward from a second read of state, and the schema should distinguish caller-asserted fields from runner-derived or boundary-attested ones.

That’s the next governance trust refinement I’m adding to Ota.

Where have you seen this drift most in practice: the runner decision itself, CI/merge wiring, or the emitted receipt/evidence layer?

[Vinicius Pereira]

the receipt/evidence layer, and it's not close, but the reason is the useful part: drift tracks distance from the decision. the runner decision itself basically can't drift, it does whatever the branch says by definition, it IS the source of truth. CI/merge wiring drifts in one narrow way, a threshold duplicated between the gate and the runtime so the gate blesses something the runner would have scored differently, but you catch that the first time the two disagree loudly. the receipt is where it hurts because it's maximum distance: written later, usually in a different module, from a second read of state, and it's the exact layer everyone downstream trusts as THE record. so the drift is easiest precisely where the blast radius is biggest.

the concrete shape i hit most: a field recomputed at serialize-time. a row gets scored while spend reads 6000, then a later normalization stage rewrites spend into a bucket, and when the receipt re-reads spend to explain the score it cites the bucket, not the 6000 the decision actually used. nothing errored, the score is unchanged, the story next to it just quietly stopped matching the inputs it was built from. that's the whole reason i test that the points named in the reason sum to the score, it's the cheapest tripwire for exactly this.

on your taxonomy, caller-asserted / runner-derived / boundary-attested is the right cut and boundary-attested is the sneaky bucket. it FEELS derived because the system observed it, but it's captured from outside your trust boundary, so its ceiling is only as good as whatever attested it. if you don't tag it explicitly it silently collapses into runner-derived and gets trusted a notch above what it earned, which is the same class of bug as a narrated reason, just about provenance instead of logic.

[Bobai Kato Ota]

Very apt!

I agree on boundary-attested being the sneaky bucket. It arrives structured so people instinctively over-trust it, but provenance-wise it is still only as strong as the boundary that attested it.

This is directly shaping Ota for me too: authoritative governance needs to be recorded at the decision site, not recomputed later, and provenance class needs to stay explicit instead of collapsing into one generic “machine-generated” bucket.

When this goes wrong in practice, what usually ends up being the most useful tripwire first: field-level reconciliation like your points-to-score check, hook/branch identity checks, or provenance-class mismatches?

[Vinicius Pereira]

field-level reconciliation, and it's not close either, for a reason that generalizes: it watches the outcome, not the mechanism. a reconciliation check fails only when the record is already lying, which means zero false alarms from benign refactors, and it catches the end symptom regardless of which upstream cause produced it, renarrated field, stale threshold, serialize-time recompute, all of them eventually break the arithmetic. one tripwire, many failure classes, and it costs an afternoon: parse your own output, assert the parts sum to the whole. it's also the only one of the three that's self-explanatory when it goes red, whoever sees the failure understands the crime without knowing your taxonomy.

provenance-class mismatch is the second layer, and the reason it can't be first is also the reason it's indispensable: it catches the lie reconciliation can't see. a receipt can reconcile perfectly while citing boundary-attested data as if it were derived, the arithmetic is clean and the trust label is wrong. the practical version isn't really a tripwire though, it's a schema decision: make the class a REQUIRED field on every value, and the silent collapse into "machine-generated" becomes a validation error instead of a judgment call. you get the check almost for free by refusing to let the field be optional.

hook/branch identity checks i'd build last or not at all. they watch the mechanism, and mechanisms churn legitimately, every refactor makes them cry wolf, and a check that cries wolf gets disabled, which is worse than not having it. the one place they earn their keep is when the decision output has no arithmetic to reconcile, pure allow/deny with no parts, then identity is the only handle left. so the ordering principle i'd hand ota: first the check that fails only when the harm is real, then the one that catches lies arithmetic can't see, and only then the ones that watch how instead of what.