agents-shipgate 0.14.0: codex-boundary-json replaces agent-json

agents-shipgate 0.14.0 is on PyPI and tagged on GitHub (release notes). It’s the agent-native contract cleanup: one release that consolidates the overlapping agent-facing surfaces that had accumulated through the 0.x line into a single, explicit read order. That consolidation includes deliberate breaking changes — permitted under 0.x semantics, documented in the migration note — so if your agent harness just failed on a --format flag, this post is the short version of why and what to do.

The breaking change: --format agent-json is removed

Through 0.13.x, the one-command boundary call for a coding agent was shipgate check ... --format agent-json, and the JSON it printed carried schema_version: "agent_result_v1". Both are gone in 0.14.0. The replacement:

# before (0.13.x) — removed in 0.14.0
shipgate check --agent codex --workspace . --format agent-json
# emitted schema_version: "agent_result_v1"

# after (0.14.0)
shipgate check --agent codex --workspace . --format codex-boundary-json
# emits schema_version: "shipgate.codex_boundary_result/v1"

--agent still takes codex, claude-code, or cursor. The command still emits exactly one stdout JSON object, and a coding agent still switches on the same seven control fields:

Field	What it answers
decision	The boundary verdict for this diff
completion_allowed	May the agent claim the work is done?
must_stop	Must the agent stop and hand off to a human?
first_next_action	The single next recommended action (actor, kind, command, why)
human_review	What a human reviewer must look at
repair	The mechanical fix path, when one exists
policy	Policy provenance, including policy_snapshot_sha256

The field set carried over; what changed is the name of the contract around it. The rename exists so consumers stop confusing the local boundary result with the verify controller artifact — they are different surfaces with different jobs. The full schema is in the glossary under Codex boundary result.

If you switch on schema_version in your harness, expect shipgate.codex_boundary_result/v1; the string agent_result_v1 is no longer emitted by shipgate check.

The read order, clarified

The same cleanup pinned down what a coding agent reads after agents-shipgate verify, in order:

1. agents-shipgate-reports/agent-handoff.json — the compact agent handoff projection (shipgate.agent_handoff/v1). Lead with gate.merge_verdict, then read the controller block for imperative controls.
2. verifier.json — the authoritative controller substrate: merge_verdict, applicability, agent_controller.
3. verify-run.json — the reproducibility record.
4. report.json → release_decision.decision — the release gate. This is the only gating signal; CI gates on it directly.

The handoff never computes a second verdict — gate.merge_verdict is a deterministic projection of release_decision.decision, so the two can never disagree. The machine-readable version of this order ships in the CLI’s .well-known/agents-shipgate.json discovery payload as agent_read_order.

The rest of the breaking list, briefly:

• verify no longer writes agent-result.json; read the artifacts above instead.
• verify --format agent was removed; --format json prints the full verifier artifact.
• Non-preview verify with a missing --config now fails closed: exit 2, merge_verdict: "unknown", no report.json — instead of the old lenient exit 0. (verify --preview is unchanged.)
• The GitHub Action input fail_on_decisions was renamed to fail_on_merge_verdicts, and Action outputs derived from agent-result.json were removed.

What did not change

The decision engine. There is still exactly one: every surface above is a projection of the same release_decision.decision, not a second opinion. Verification is still static by default — no LLM calls, no runtime instrumentation — and the GitHub Action still defaults to advisory mode, so adopting 0.14.0 does not change what blocks your merges until you opt into strict behavior.

The honest status also hasn’t changed: agents-shipgate is pre-1.0 beta. An earlier draft of this cycle briefly carried a 1.0.0-alpha label, and it was withdrawn — the report.json schema (report_schema_version: "0.28") is still additive-versioned rather than frozen, and no real-world detection-accuracy baseline has been published yet. A 1.0 line starts when the report schema reaches 1.0 and holds, not before.

How to upgrade

pipx upgrade agents-shipgate
# or
uv tool install --upgrade agents-shipgate

Then confirm the installed CLI speaks the new contract:

agents-shipgate contract --json

Require contract_version >= 9. Contract 9 is the 0.14.0 payload; it also adds primary_commands{}, so agents can discover the three prominent flows (shipgate check, agents-shipgate verify, shipgate audit --host) without treating supporting commands as first-look guidance.

If you pin the GitHub Action, bump the tag to ThreeMoonsLab/agents-shipgate@v0.14.0 and rename fail_on_decisions to fail_on_merge_verdicts if you set it.

For a clean end-to-end walkthrough on the new surface — install, verify a PR, wire your coding agent — start at the quickstart.