P0: Make the agent control contract unambiguous

.agents/skills/agents-shipgate/SKILL.md

@@ -1,3 +1,3 @@
 ---
 name: agents-shipgate
 description: Use when the user wants to run the prominent Agents Shipgate flows — `shipgate check`, `agents-shipgate verify`, or `shipgate audit --host` — for AI agent capability changes, PR release readiness, or coding-agent host grants.
@@ -15,18 +15,18 @@
 
 1. For local checks, verifier runs, host audits, and supporting recovery commands, read `references/recipes.md`.
 2. For reading `report.json`, summarizing release decisions, or deciding what may be auto-applied, read `references/report-reading.md`.
-3. Before running Shipgate CLI commands, require a CLI whose `agents-shipgate contract --json` reports `contract_version: "9"` or newer: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. If it is missing or stale, tell the user to install or upgrade `agents-shipgate`. The Codex plugin supplies workflows, not the scanner binary.
+3. Before running Shipgate CLI commands, require a CLI whose `agents-shipgate contract --json` reports `minimum_control_contract_version: 14`: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. If it is missing or stale, tell the user to install or upgrade `agents-shipgate`. The Codex plugin supplies workflows, not the scanner binary.
 4. Set `AGENTS_SHIPGATE_AGENT_MODE=1` before running Shipgate commands so errors include structured `next_action` JSON.
 5. Default first-time CI to advisory mode. Do not enable release-blocking CI or save a baseline until a human has reviewed current findings.
-6. For local agent control, run `shipgate check --agent codex --workspace . --format codex-boundary-json` and read the stdout `shipgate.codex_boundary_result/v1` object. Switch on `decision`; follow `first_next_action`, `repair`, and `human_review`.
+6. For local agent control, run `shipgate check --agent codex --workspace . --format codex-boundary-json` and read the stdout `shipgate.codex_boundary_result/v2` object. Switch on `control.state`; follow only `control.next_action`, `control.allowed_next_commands`, and `control.human_review`. Treat `decision` as diagnostic context only.
 7. Before editing `shipgate.yaml`, Shipgate CI, AGENTS/CLAUDE/Cursor rules, policy packs, baselines, waivers, suppressions, Codex hooks/config, Codex plugin manifests, `.mcp.json`, `.app.json`, or `SKILL.md`, plan to run `agents-shipgate verify` before completion and route trust-root review to a human when the verifier requires it.
-8. For full PR verification, read `agents-shipgate-reports/agent-handoff.json` first, then `verifier.json` for detailed controller state, then `verify-run.json` for reproducibility metadata, then `report.json` for reviewer detail; `report.json.release_decision.decision` remains the release gate.
+8. For full PR verification, read `agents-shipgate-reports/agent-handoff.json` first and switch on `control.state`, then read `verifier.json` for detailed control state, `verify-run.json` for reproducibility metadata, and `report.json` for reviewer detail; `report.json.release_decision.decision` remains the release gate.
 9. Auto-apply only high-confidence safe patches. Do not auto-assert action effect, action authority, agent bindings, approval, confirmation, idempotency, broad-scope, prohibited-action, or runtime-trace evidence.
 10. Ensure `.gitignore` covers `agents-shipgate-reports/` before committing.
 
 ## Fast Paths
 
-- CLI preflight: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. Continue only when the installed CLI reports `contract_version: "9"` or newer; if it is missing or stale, ask the user to install or upgrade `agents-shipgate`.
+- CLI preflight: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. Continue only when the installed CLI reports `minimum_control_contract_version: 14`; if it is missing or stale, ask the user to install or upgrade `agents-shipgate`.
 - Agent-native check: run `shipgate check --agent codex --workspace . --format codex-boundary-json`; read only the JSON result for continue/repair/stop routing.
 - Agent-related PR/CI diff: run `agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json` after making the base ref available. For local uncommitted work, omit `--base`/`--head` so the working tree is scanned. `verify` never fetches.
 - Existing manifest / ongoing PR: run `agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json`.
@@ -37,7 +37,7 @@
 
 - Do not claim a finding is fixed without re-running `agents-shipgate verify` and reporting the new merge verdict and release decision.
 - Do not self-approve trust-root changes; when `agents-shipgate verify` returns human review required, surface it to a human.
-- Before finishing an agent-related diff, run `shipgate check --agent codex --workspace . --format codex-boundary-json` and follow `shipgate.codex_boundary_result/v1`.
+- Before finishing an agent-related diff, run `shipgate check --agent codex --workspace . --format codex-boundary-json` and follow `shipgate.codex_boundary_result/v2.control.state`. Only `complete` permits completion; a human route cannot be cleared by conversation-level acknowledgement.
 - Do not bypass the verifier by suppressing findings, lowering severity, expanding baselines or waivers, removing Shipgate CI, or weakening agent instructions; verify-mode `SHIP-VERIFY-*` checks make those trust-root edits release-visible.
 - Do not silently suppress findings. Suppressions require a non-empty `reason`.
 - Do not commit generated reports.

.agents/skills/agents-shipgate/references/recipes.md

@@ -1,3 +1,3 @@
 # Agents Shipgate Recipes
 
 Use these recipes after the `agents-shipgate` skill triggers. The prominent
@@ -16,17 +16,18 @@
 agents-shipgate contract --json
 ```
 
-Require `agents-shipgate contract --json` to report `contract_version: "10"` or
-newer. If it is missing or stale, ask the user to install or upgrade:
+Require `agents-shipgate contract --json` to report
+`minimum_control_contract_version: 14`. If it is missing or stale, ask the
+user to install or upgrade:
 
 ```bash
 pipx install agents-shipgate
 pipx upgrade agents-shipgate
 ```
 
-Do not report the task complete until the CLI exists and reports contract v9 or
-newer. Local boundary checks emit `shipgate.codex_boundary_result/v1`; legacy
-`agent_result_v1` fixtures are retained only for older protocol integrations.
+Do not report the task complete until the CLI exists and reports runtime
+contract 14. Local boundary checks emit `shipgate.codex_boundary_result/v2`;
+legacy v1 fixtures are retained only for older protocol integrations.
 
 ## Local Agent Check
 
@@ -37,8 +38,9 @@
   --agent codex --workspace . --format codex-boundary-json
 ```
 
-Read only stdout JSON. Switch on `decision`, `completion_allowed`,
-`must_stop`, `first_next_action`, `human_review`, `repair`, and `policy`.
+Read only stdout JSON. Switch on `control.state`, follow
+`control.next_action`, `control.allowed_next_commands`, and
+`control.human_review`, and treat `decision` as diagnostic context only.
 
 ## Verify A Diff
 
@@ -62,7 +64,7 @@
 ```
 
 Read `agents-shipgate-reports/agent-handoff.json` first. Lead with
-`gate.merge_verdict`, then inspect `next_action`, `controller`,
+`control.state`, then inspect `gate.merge_verdict`, `next_action`,
 `fix_task.safe_to_attempt`, and `capability_review.top_changes[]`. Then read
 `verifier.json`, `verify-run.json`, and `report.json`; the release gate remains
 `report.json.release_decision.decision`.

.agents/skills/agents-shipgate/references/report-reading.md

@@ -1,14 +1,14 @@
 # Reading Agents Shipgate Reports
 
 For verify runs, read `agents-shipgate-reports/agent-handoff.json` first. Then
-read `agents-shipgate-reports/verifier.json` for detailed controller context
+read `agents-shipgate-reports/verifier.json` for detailed control context
 and `agents-shipgate-reports/report.json` for findings. Do not scrape Markdown.
 
 ## Order
 
-1. `agent-handoff.json.gate.merge_verdict`: `mergeable`, `human_review_required`, `insufficient_evidence`, `blocked`, or `unknown`.
+1. `agent-handoff.json.control.state`: `complete`, `agent_action_required`, or `human_review_required`.
 2. `agent-handoff.json.capability_review.top_changes[]`: the highest-signal tool/action or trust-root changes.
-3. `agent-handoff.json.next_action` / `controller` / `fix_task`: who acts next and whether a coding agent may safely attempt the fix.
+3. `agent-handoff.json.next_action` / `control.next_action` / `fix_task`: who acts next and whether a coding agent may safely attempt the fix.
 4. `report.json.release_decision.decision`: `blocked`, `review_required`, `insufficient_evidence`, or `passed`; this is the release gate.
 5. `verifier.json.capability_review.top_changes[]`: supporting/provisional highest-signal tool/action or trust-root changes.
 6. `release_decision.blockers[]` and `release_decision.review_items[]`.

.claude-plugin/marketplace.json

@@ -9,8 +9,8 @@
     {
       "name": "agents-shipgate",
       "source": "./plugins/claude-code",
-      "description": "Run Agents Shipgate Tool-Use Readiness workflows from Claude Code: detect whether Shipgate applies, bootstrap the advisory gate, verify agent-capability PRs, and triage findings without fabricating human approval. Requires the agents-shipgate CLI (pipx install agents-shipgate, contract v10 or newer).",
-      "version": "0.16.0b2",
+      "description": "Run Agents Shipgate Tool-Use Readiness workflows from Claude Code: detect whether Shipgate applies, bootstrap the advisory gate, verify agent-capability PRs, and triage findings without fabricating human approval. Requires the agents-shipgate CLI (pipx install agents-shipgate, runtime contract 14).",
+      "version": "0.16.0b3",
       "author": {
         "name": "Three Moons Lab",
         "url": "https://threemoonslab.com/"

.claude/commands/shipgate.md

@@ -1,3 +1,3 @@
 ---
 description: "Run the prominent Agents Shipgate flows: check, verify, or audit --host"
 ---
@@ -51,9 +51,10 @@
 3. For verifier runs, parse `agents-shipgate-reports/agent-handoff.json` first,
    then `verifier.json`, `verify-run.json`, and
    `report.json.release_decision.decision` as the release gate.
-4. For check runs, parse stdout as `shipgate.codex_boundary_result/v1` and
-   switch on `decision`, `completion_allowed`, `must_stop`, `first_next_action`,
-   `human_review`, and `repair`.
+4. For check runs, parse stdout as `shipgate.codex_boundary_result/v2` and
+   switch on `control.state`; follow `control.next_action`,
+   `control.allowed_next_commands`, and `control.human_review`. Treat
+   `decision` as diagnostic context only.
 5. For host audits, parse `agents-shipgate-reports/host-grants.json` when
    `--out` is used, or stdout when running JSON-only.
 6. Do **not** bypass the verifier by suppressing findings, lowering severity,
@@ -80,8 +81,7 @@
 `gate.merge_verdict` (a deterministic projection of `release_decision.decision`,
 which remains the gate in `report.json`), then the authoritative substrate
 `agents-shipgate-reports/verifier.json` and supporting/provisional
-`capability_review.top_changes[]`. Do not claim completion when
-`merge_verdict` is `blocked`, `insufficient_evidence`, or
-`human_review_required` unless the user accepted the human-review requirement, and
-never weaken `shipgate.yaml`, Shipgate CI, `AGENTS.md`, policies, baselines, or
+`capability_review.top_changes[]`. Do not claim completion unless
+`control.state` is `complete`; conversation-level acknowledgement cannot clear
+a human-review route. Never weaken `shipgate.yaml`, Shipgate CI, `AGENTS.md`, policies, baselines, or
 waivers to make Shipgate pass.

.cursor/rules/agents-shipgate.mdc

@@ -1,3 +1,3 @@
 ---
 description: Run Agents Shipgate as the deterministic merge gate for AI-generated agent capability changes.
 globs:
@@ -40,15 +40,17 @@
   shipgate check --agent cursor --workspace . --format codex-boundary-json
 
 Read the check stdout JSON only. It is
-`shipgate.codex_boundary_result/v1`; switch on `decision`,
-`completion_allowed`, and `must_stop`, then follow `first_next_action`,
-`human_review`, `repair`, `policy`, and `verify_required`. Do not infer a decision from prose.
-
-If `decision=allow` or `warn`, continue and summarize. If
-`first_next_action.kind` is `repair` and `repair.safe_to_attempt=true`, make
-only the listed mechanical repair and rerun the command. If
-`human_review.required=true` or `must_stop=true`, stop and surface the JSON
-result to a human.
+`shipgate.codex_boundary_result/v2`; switch on `control.state`, then follow
+`control.next_action`, `control.allowed_next_commands`, and
+`control.human_review`. Treat `decision` as diagnostic context, not as the
+operational control signal. Do not infer control from prose.
+
+If `control.state=complete`, summarize the result and finish. If
+`control.state=agent_action_required`, perform only the exact coding-agent
+action and command authorized by `control.next_action`, then rerun the command.
+If `control.state=human_review_required`, stop and surface the JSON result to a
+human. Conversation-level acknowledgement never clears this state; only a new
+verifier artifact can do so.
 
 For local verification, run:
 
@@ -57,8 +59,8 @@
 For committed PR/CI verification, run `agents-shipgate verify --base
 origin/main --head HEAD --json` after making the base ref available; it never
 fetches. Read `agents-shipgate-reports/agent-handoff.json` first for
-`gate.merge_verdict`, `gate.can_merge_without_human`, and `controller`; then read
-`agents-shipgate-reports/verifier.json` for detailed controller context,
+`gate.merge_verdict`, `gate.can_merge_without_human`, and `control`; then read
+`agents-shipgate-reports/verifier.json` for detailed control context,
 `agents-shipgate-reports/verify-run.json` for reproducibility metadata, and
 `agents-shipgate-reports/report.json.release_decision.decision` for the
 release gate.