ThreeMoonsLab · pengfei-threemoonslab · Jul 7, 2026 · Jul 6, 2026 · Jul 7, 2026
diff --git a/.agents/skills/agents-shipgate/references/recipes.md b/.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,7 +16,7 @@
 agents-shipgate contract --json
 ```
 
-Require `agents-shipgate contract --json` to report `contract_version: "9"` or
+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:
 
 ```bash

diff --git a/.cursor/rules/agents-shipgate.mdc b/.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:
@@ -42,7 +42,7 @@
 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`, and `policy`. Do not infer a decision from prose.
+`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

diff --git a/.well-known/agents-shipgate.json b/.well-known/agents-shipgate.json
@@ -16,7 +16,12 @@
     "short": "Merge verdicts for AI-generated agent PRs",
     "answer": "Agents Shipgate is described by the canonical tagline: The deterministic merge gate for AI-generated agent capability changes. It is an open-source, local-first CLI and GitHub Action from Three Moons Lab that verifies PRs from Codex, Claude Code, Cursor, or humans and returns a deterministic merge verdict before agent code lands.",
     "primary_use_case": "Run on PRs from Codex, Claude Code, Cursor, or humans when agent tools, prompts, permissions, MCP/OpenAPI surfaces, policies, or release gates change.",
-    "not_for": ["llm_evals", "runtime_guardrails", "runtime_observability", "general_linting"]
+    "not_for": [
+      "llm_evals",
+      "runtime_guardrails",
+      "runtime_observability",
+      "general_linting"
+    ]
   },
   "primary_keywords": [
     "agent release readiness",
@@ -44,7 +49,12 @@
     "sarif",
     "agent-governance"
   ],
-  "audiences": ["agent_builders", "platform_engineers", "security_reviewers", "coding_agents"],
+  "audiences": [
+    "agent_builders",
+    "platform_engineers",
+    "security_reviewers",
+    "coding_agents"
+  ],
   "when_to_use": [
     "AI-generated agent PRs from Codex, Claude Code, Cursor, or similar tools",
     "AI agent tool-surface changes",
@@ -70,7 +80,10 @@
     "pip": "python -m pip install agents-shipgate",
     "uv": "uv tool install agents-shipgate"
   },
-  "binaries": ["agents-shipgate", "shipgate"],
+  "binaries": [
+    "agents-shipgate",
+    "shipgate"
+  ],
   "quickstart": "shipgate check --agent codex --workspace . --format codex-boundary-json",
   "primary_commands": {
     "check_codex": "shipgate check --agent codex --workspace . --format codex-boundary-json",
@@ -106,29 +119,88 @@
   "fixture_run": "agents-shipgate fixture run ai_generated_refund_pr",
   "static_scan_fixture_run": "agents-shipgate fixture run support_refund_agent",
   "feedback_loop": {
-    "when": ["false_positive", "missed_capability", "unsafe_pass", "unclear_next_action", "adapter_gap"],
+    "when": [
+      "false_positive",
+      "missed_capability",
+      "unsafe_pass",
+      "unclear_next_action",
+      "adapter_gap"
+    ],
     "export_command": "agents-shipgate feedback export --from agents-shipgate-reports/verifier.json --redact --out shipgate-feedback.json",
     "capture_command": "agents-shipgate feedback capture --before verifier-before.json --after verifier-after.json --redact --out scenario.json",
     "issue_template": "https://github.com/ThreeMoonsLab/agents-shipgate/issues/new?template=agent_feedback.yml",
-    "attach": ["shipgate-feedback.json", "minimal safe manifest/tool-source snippet"],
-    "do_not_attach": ["unredacted reports", "raw tool outputs", "secrets", "customer data", "chain-of-thought"]
+    "attach": [
+      "shipgate-feedback.json",
+      "minimal safe manifest/tool-source snippet"
+    ],
+    "do_not_attach": [
+      "unredacted reports",
+      "raw tool outputs",
+      "secrets",
+      "customer data",
+      "chain-of-thought"
+    ]
   },
   "self_check": "agents-shipgate self-check --json",
   "contract": "agents-shipgate contract --json",
   "agent_protocol": "docs/agents/protocol.md",
   "agent_result_schema_version": "agent_result_v1",
   "agent_result_schema_path": "docs/agent-result-schema.v1.json",
-  "agent_result_control_fields": ["decision", "completion_allowed", "must_stop", "first_next_action", "human_review", "repair", "policy"],
+  "agent_result_control_fields": [
+    "decision",
+    "completion_allowed",
+    "must_stop",
+    "first_next_action",
+    "human_review",
+    "repair",
+    "policy",
+    "verify_required"
+  ],
   "codex_boundary_result_schema_version": "shipgate.codex_boundary_result/v1",
   "codex_boundary_result_schema_path": "docs/codex-boundary-result-schema.v1.json",
   "verifier_schema_version": "0.1",
   "verify_run_schema_version": "shipgate.verify_run/v1",
   "agent_handoff_schema_version": "shipgate.agent_handoff/v1",
   "agent_handoff_schema_path": "docs/agent-handoff-schema.v1.json",
   "agent_handoff_artifact": "agents-shipgate-reports/agent-handoff.json",
-  "contract_version": "9",
-  "inputs": ["mcp", "openapi", "openai_agents_sdk", "anthropic_api", "google_adk", "langchain", "crewai", "openai_api", "codex_config", "codex_plugin", "n8n"],
-  "outputs": ["markdown", "json", "sarif", "packet_md", "packet_json", "packet_html", "verifier_json", "verify_run_json", "agent_handoff_json", "pr_comment_md", "check_annotations_json", "capability_lock_json", "base_capability_lock_json", "capability_lock_diff_json", "capability_lock_diff_md", "feedback_json", "attestation_json", "org_evidence_bundle_json", "host_grants_json", "org_status_json", "scenario_json", "governance_benchmark_result_json"],
+  "contract_version": "10",
+  "inputs": [
+    "mcp",
+    "openapi",
+    "openai_agents_sdk",
+    "anthropic_api",
+    "google_adk",
+    "langchain",
+    "crewai",
+    "openai_api",
+    "codex_config",
+    "codex_plugin",
+    "n8n"
+  ],
+  "outputs": [
+    "markdown",
+    "json",
+    "sarif",
+    "packet_md",
+    "packet_json",
+    "packet_html",
+    "verifier_json",
+    "verify_run_json",
+    "agent_handoff_json",
+    "pr_comment_md",
+    "check_annotations_json",
+    "capability_lock_json",
+    "base_capability_lock_json",
+    "capability_lock_diff_json",
+    "capability_lock_diff_md",
+    "feedback_json",
+    "attestation_json",
+    "org_evidence_bundle_json",
+    "host_grants_json",
+    "org_status_json",
+    "scenario_json",
+    "governance_benchmark_result_json"
+  ],
   "artifacts": {
     "verifier": "agents-shipgate-reports/verifier.json",
     "verify_run": "agents-shipgate-reports/verify-run.json",
@@ -161,9 +233,36 @@
   "capability_standard_version": "0.1",
   "governance_benchmark_catalog_schema_version": "0.2",
   "governance_benchmark_result_schema_version": "0.2",
-  "supporting_provisional_surfaces": ["agent_result", "agent_decision", "release_evidence_packet", "reviewer_summary", "verifier_summary", "capability_review", "runtime_trace_evidence", "capability_diff_projections", "skill_review"],
-  "external_integration_surfaces": ["agent_handoff", "preflight", "capability_lock", "capability_lock_diff", "capability_standard", "attestation", "registry", "org_governance", "org_evidence_bundle", "host_grants_inventory", "governance_benchmark_catalog", "governance_benchmark_result"],
-  "agent_interface_operations": ["verify_pr", "verify_local", "verify_preview"],
+  "supporting_provisional_surfaces": [
+    "agent_result",
+    "agent_decision",
+    "release_evidence_packet",
+    "reviewer_summary",
+    "verifier_summary",
+    "capability_review",
+    "runtime_trace_evidence",
+    "capability_diff_projections",
+    "skill_review"
+  ],
+  "external_integration_surfaces": [
+    "agent_handoff",
+    "preflight",
+    "capability_lock",
+    "capability_lock_diff",
+    "capability_standard",
+    "attestation",
+    "registry",
+    "org_governance",
+    "org_evidence_bundle",
+    "host_grants_inventory",
+    "governance_benchmark_catalog",
+    "governance_benchmark_result"
+  ],
+  "agent_interface_operations": [
+    "verify_pr",
+    "verify_local",
+    "verify_preview"
+  ],
   "exit_code_policy": {
     "0": "command completed; inspect JSON verdict fields for release state",
     "2": "configuration or CLI flag error",
@@ -172,11 +271,31 @@
     "6": "baseline integrity failure",
     "20": "strict-mode gate failure or opt-in governance failure"
   },
-  "mcp_tools": ["shipgate.check", "shipgate.preflight", "shipgate.explain", "shipgate.capabilities", "shipgate.handoff"],
+  "mcp_tools": [
+    "shipgate.check",
+    "shipgate.preflight",
+    "shipgate.explain",
+    "shipgate.capabilities",
+    "shipgate.handoff"
+  ],
   "gating_signal": "release_decision.decision",
-  "agent_controller_signals": ["merge_verdict", "applicability", "agent_controller"],
-  "merge_verdicts": ["mergeable", "human_review_required", "insufficient_evidence", "blocked", "unknown"],
-  "check_run_policies": ["advisory", "blocked-fails", "require-mergeable"],
+  "agent_controller_signals": [
+    "merge_verdict",
+    "applicability",
+    "agent_controller"
+  ],
+  "merge_verdicts": [
+    "mergeable",
+    "human_review_required",
+    "insufficient_evidence",
+    "blocked",
+    "unknown"
+  ],
+  "check_run_policies": [
+    "advisory",
+    "blocked-fails",
+    "require-mergeable"
+  ],
   "github_action_pr_workflow": {
     "recommended_inputs": {
       "ci_mode": "advisory",
@@ -187,8 +306,17 @@
     },
     "branch_protection_check_run_policy": "require-mergeable"
   },
-  "applicability_values": ["verified", "not_applicable", "unknown"],
-  "release_decisions": ["passed", "review_required", "insufficient_evidence", "blocked"],
+  "applicability_values": [
+    "verified",
+    "not_applicable",
+    "unknown"
+  ],
+  "release_decisions": [
+    "passed",
+    "review_required",
+    "insufficient_evidence",
+    "blocked"
+  ],
   "merge_verdict_labels": {
     "passed": "mergeable",
     "review_required": "human_review_required",

diff --git a/AGENTS.md b/AGENTS.md
@@ -1,3 +1,3 @@
 # Agents Shipgate · Agent Instructions

 Authoritative instructions for AI coding agents (Claude Code, Codex, Cursor, Aider, Cline, Windsurf, Devin, or any other harness — see [`docs/agents/any-coding-agent.md`](docs/agents/any-coding-agent.md)) working **with** this repository or a project that uses Agents Shipgate.
@@ -84,7 +84,7 @@
 
 Read the single stdout object as `shipgate.codex_boundary_result/v1`. Switch on
 `decision`, `completion_allowed`, `must_stop`, `first_next_action`,
-`human_review`, `repair`, and `policy`; never infer a local-control decision
+`human_review`, `repair`, `policy`, and `verify_required`; never infer a local-control decision
 from Markdown, PR comments, or prose. If `decision=allow` or `warn`, continue
 and summarize the result. If `first_next_action.kind=repair` and
 `repair.safe_to_attempt` is `true`, apply only that repair and rerun the

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+- **Contract v10 (additive): machine-readable `verify_required` on the Codex
+  boundary result.** `shipgate check` already escalated to `warn` and routed
+  to `verify` when a diff touched a tool surface it cannot gate; that deferral
+  now also sets a top-level boolean `verify_required` on
+  `shipgate.codex_boundary_result/v1`, and `verify_required` joins
+  `agent_result_control_fields` in the runtime contract. Agents switch on the
+  field instead of parsing warning prose; the observable pair is
+  `decision="warn"` with `verify_required=true` — "no boundary rule fired,
+  but capability is not yet gated: run verify before completion" (the
+  escalation means a plain `allow` always has `verify_required=false`). The
+  field lives on the shared `AgentResultV1` base, so the legacy
+  `agent-result-schema.v1.json` carries it too and
+  `agent_result_control_fields` validates against both schemas. Additive
+  over v9: consumers pinned to `contract_version >= 9` keep working.
+
 ## 0.14.0 - 2026-06-30
 
 - **Versioning: the `1.0.0-alpha` line is withdrawn; this work ships as

diff --git a/README.md b/README.md
@@ -141,7 +141,7 @@ shipgate check --agent cursor --workspace . --format codex-boundary-json
 ```
 
 Switch on `decision`, `completion_allowed`, `must_stop`,
-`first_next_action`, `human_review`, `repair`, and `policy`; never infer a
+`first_next_action`, `human_review`, `repair`, `policy`, and `verify_required`; never infer a
 decision from prose. `shipgate check` is necessary but not sufficient for
 capability-expanding diffs: if a change adds dynamic, undeclared, or otherwise
 ambiguous tool capability, do not treat `decision="allow"` as merge readiness;
@@ -276,7 +276,7 @@ shipgate audit --host --json --out agents-shipgate-reports/host-grants.json
 For local control, parse the `shipgate check` stdout JSON
 (`shipgate.codex_boundary_result/v1`): switch on `decision`,
 `completion_allowed`, `must_stop`, `first_next_action`, `human_review`,
-`repair`, and `policy`. For local uncommitted verify work,
+`repair`, `policy`, and `verify_required`. For local uncommitted verify work,
 omit `--base`/`--head`. For committed PR/CI refs,
 make the base ref available first because `verify` never fetches. Read
 `agents-shipgate-reports/agent-handoff.json` first and lead with

diff --git a/adoption-kits/codex-skill/.agents-shipgate-kit-metadata.json b/adoption-kits/codex-skill/.agents-shipgate-kit-metadata.json
@@ -26,7 +26,8 @@
       "6bf8b3a409df3cd6f94e070555d62eedf8ba3690b4cfdceae2d7a7482b90e91b",
       "8576dc41812871e97a5d5c213a2c9c44f9766f746d99e9bc9909ee69a4002575",
       "d7779f4f2365c84727d02da770696a40490428a396e10d7a031b316f15ef849d",
-      "64cfd980d399f24995008eeca4d196a6efd224edd01e108543ec11aeb291d085"
+      "64cfd980d399f24995008eeca4d196a6efd224edd01e108543ec11aeb291d085",
+      "d8b393e61aef853105a47630b9cbfd404378b6c9e1bbed6028b357b4e38fc72c"
     ],
     "references/report-reading.md": [
       "75a655059f3d45db365c744b0ff82d1c9d69c3638acacf640fd667ae87260d05",

diff --git a/adoption-kits/codex-skill/references/recipes.md b/adoption-kits/codex-skill/references/recipes.md
@@ -16,7 +16,7 @@ agents-shipgate --version
 agents-shipgate contract --json
 ```
 
-Require `agents-shipgate contract --json` to report `contract_version: "9"` or
+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:
 
 ```bash

diff --git a/docs/agent-contract-current.md b/docs/agent-contract-current.md
@@ -10,7 +10,9 @@ Verify the installed CLI contract locally before relying on hard-coded docs:
 agents-shipgate contract --json
 ```
 
-Runtime contract v9 also exposes the local agent command spec:
+Runtime contract v10 (v10 adds `verify_required` to
+`agent_result_control_fields` and to the boundary result; additive over v9)
+also exposes the local agent command spec:
 `primary_commands{}`, `commands{}`, `default_paths{}`, `artifacts{}`,
 `agent_read_order[]`, `verifier_read_order[]`, `merge_verdicts[]`,
 `release_decisions[]`, `do_not_auto_assert[]`, `verifier_schema_version`,
@@ -31,7 +33,7 @@ Downstream repos generated with
 `.shipgate/agent-contract.json`.
 
 - Latest release: `v0.14.0` (see [pyproject.toml](../pyproject.toml) for the in-tree version)
-- Runtime contract: `9`
+- Runtime contract: `10`
 - Current report schema: `0.28` — [`docs/report-schema.v0.28.json`](report-schema.v0.28.json)
 - Current packet schema: `0.7` — [`docs/packet-schema.v0.7.json`](packet-schema.v0.7.json)
 - Current verifier schema: `0.1` — [`docs/verifier-schema.v0.1.json`](verifier-schema.v0.1.json)
@@ -365,8 +367,21 @@ The removed `--format agent-json` alias and `agent_result_v1` schema string are
 breaking 0.14.0 changes; see [STABILITY.md](../STABILITY.md#migration-note-0-14-0).
 
 Coding agents should switch on `decision`, `completion_allowed`, `must_stop`,
-`first_next_action`, `human_review`, `repair`, and `policy`. Do not derive an agent
-decision from Markdown, PR comments, or natural language. Do not confuse this
+`first_next_action`, `human_review`, `repair`, `policy`, and `verify_required`. Do not derive an agent
+decision from Markdown, PR comments, or natural language.
+
+`verify_required` (contract v10, additive) is the machine-readable
+check→verify deferral: `true` whenever the diff touches a tool surface —
+declared or undeclared — that the boundary check does not gate. The evaluator
+simultaneously escalates what would otherwise be a clean `allow` to
+`decision="warn"`, so the observable pair is `decision="warn"` with
+`verify_required=true`: "no boundary rule fired, but capability is not yet
+gated" — run `agents-shipgate verify` and read `release_decision.decision`
+before reporting completion. A plain `decision="allow"` always has
+`verify_required=false`. It is a deterministic
+projection of the same deferral that emits the
+`capability_change_requires_verify` / `undeclared_capability_surface`
+diagnostics — not a second verdict. Do not confuse this
 local boundary result with `agents-shipgate verify`: verify writes
 `agent-handoff.json`, `verifier.json`, and `verify-run.json`, and
 `report.json` remains the full CI/reviewer substrate.

diff --git a/docs/agent-result-schema.v1.json b/docs/agent-result-schema.v1.json
@@ -666,6 +666,11 @@
       "default": null,
       "title": "Trigger"
     },
+    "verify_required": {
+      "default": false,
+      "title": "Verify Required",
+      "type": "boolean"
+    },
     "violated_rules": {
       "items": {
         "$ref": "#/$defs/AgentResultViolatedRule"

diff --git a/docs/agents/README.md b/docs/agents/README.md
@@ -28,7 +28,7 @@ shipgate check --agent codex --workspace . --format codex-boundary-json
 Use `--agent claude-code` for Claude Code and `--agent cursor` for Cursor.
 Parse stdout as `shipgate.codex_boundary_result/v1`; switch on `decision`,
 `completion_allowed`, `must_stop`, `first_next_action`, `human_review`,
-`repair`, and `policy`. Do not infer a control decision from prose.
+`repair`, `policy`, and `verify_required`. Do not infer a control decision from prose.
 
 For committed PR verification, run `agents-shipgate verify`, then read
 `agents-shipgate-reports/agent-handoff.json` first and

diff --git a/docs/agents/claude-code.md b/docs/agents/claude-code.md
@@ -8,7 +8,7 @@ shipgate check --agent claude-code --workspace . --format codex-boundary-json
 
 Parse stdout as `shipgate.codex_boundary_result/v1`. Switch only on `decision`,
 `completion_allowed`, `must_stop`, `first_next_action`, `human_review`,
-`repair`, and `policy`.
+`repair`, `policy`, and `verify_required`.
 
 If the binary is missing, surface the schema-valid install fixture with
 `first_next_action.kind="install"` and command `pipx install agents-shipgate`.