Update agent control docs and contract metadata

.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,9 +40,9 @@
   agents-shipgate preflight --json
   shipgate check --agent cursor --workspace . --format agent-json
 
-Read the stdout JSON only. It is `agent_result_v1`; switch on `decision`, then
-follow `first_next_action`, `repair`, and `human_review`. Do not infer a
-decision from prose.
+Read the stdout JSON only. It is `agent_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.
 
 If `decision=allow` or `warn`, continue and summarize. If
 `first_next_action.kind` is `repair` and `repair.safe_to_attempt=true`, make

.well-known/agents-shipgate.json

@@ -71,9 +71,12 @@
     "uv": "uv tool install agents-shipgate"
   },
   "binaries": ["agents-shipgate", "shipgate"],
-  "quickstart": "agents-shipgate verify --preview --json",
+  "quickstart": "shipgate check --agent codex --workspace . --format agent-json",
   "commands": {
     "agent_check": "shipgate check --agent codex --workspace . --format agent-json",
+    "agent_check_codex": "shipgate check --agent codex --workspace . --format agent-json",
+    "agent_check_claude_code": "shipgate check --agent claude-code --workspace . --format agent-json",
+    "agent_check_cursor": "shipgate check --agent cursor --workspace . --format agent-json",
     "preflight": "agents-shipgate preflight --workspace . --config shipgate.yaml --json",
     "preview": "agents-shipgate verify --preview --json",
     "install_ai_coding_workflow": "agents-shipgate init --workspace . --write --ci --agent-instructions=default --json",
@@ -92,7 +95,9 @@
   "contract": "agents-shipgate contract --json",
   "agent_protocol": "docs/agents/protocol.md",
   "agent_result_schema_version": "agent_result_v1",
-  "contract_version": "3",
+  "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"],
+  "contract_version": "4",
   "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", "agent_result_json", "verifier_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", "scenario_json", "governance_benchmark_result_json"],
   "artifacts": {

AGENTS.md

@@ -1,3 +1,3 @@
 # Agents Shipgate · Agent Instructions
 
 Authoritative instructions for AI coding agents (Claude Code, Codex, Cursor, Aider) working **with** this repository or a project that uses Agents Shipgate.
@@ -70,28 +70,53 @@
 
 Reports land at `agents-shipgate-reports/report.{md,json}`.
 
-**Before reporting an agent-capability change complete** — once `shipgate.yaml`
-exists, run the deterministic verifier on the diff:
+**Local control for coding agents** — before reporting an agent-capability
+change complete, run the local control loop and parse stdout JSON:
 
 ```bash
-agents-shipgate verify --json
+shipgate check --agent codex --workspace . --format agent-json
+shipgate check --agent claude-code --workspace . --format agent-json
+shipgate check --agent cursor --workspace . --format agent-json
 ```
 
-Inside a coding-agent harness (Claude Code exports `CLAUDECODE=1`, Cursor
-`CURSOR_TRACE_ID`) agent mode auto-enables and `--json` prints the compact
-agent result (`merge_verdict`, `can_merge_without_human`, repair
-instructions) on stdout. When `--base` is omitted, verify auto-detects the
-default branch (`origin/main` etc.) for diff context; pass `--no-base` to
-disable, or pin refs explicitly for CI:
+Read the single stdout object as `agent_result_v1`. Switch on `decision`,
+`completion_allowed`, `must_stop`, `first_next_action`, `human_review`,
+`repair`, and `policy`; 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 command. If
+`human_review.required=true` or `must_stop=true`, stop and surface the JSON
+result to a human.
+
+**Before editing a protected release surface** — ask the proactive static
+planner first:
+
+```bash
+agents-shipgate preflight --json
+agents-shipgate preflight --changed-files changed.txt --json
+agents-shipgate preflight --capability-request request.json --json
+```
+
+If `requires_human_review` is `true` or `first_next_action.actor` is `human`,
+stop and route the change to a human. Protected surfaces include
+`shipgate.yaml`, `.github/workflows/agents-shipgate.yml`,
+`AGENTS.md`/`CLAUDE.md`/Cursor rules, policy packs, baselines, waivers,
+suppressions, Codex hooks/config, Codex plugin manifests, `.mcp.json`,
+`.app.json`, and `SKILL.md`. Preflight is a routing/projection surface only;
+`release_decision.decision` remains the release gate.
+
+**PR / reviewer evidence** — for committed PR/CI refs, run the deterministic
+verifier on the diff. Make the base ref available first because `verify` never
+fetches:
 
 ```bash
 agents-shipgate verify --workspace . --config shipgate.yaml \
   --base origin/main --head HEAD --ci-mode advisory --format json
 ```
 
-For local uncommitted work the working tree is scanned. For committed PR/CI
-refs, make the base ref available first because `verify` never fetches. Read
-`agents-shipgate-reports/verifier.json` first and lead with `merge_verdict`
+For local uncommitted verifier work, omit `--base`/`--head` so the working tree
+is scanned. Read `agents-shipgate-reports/verifier.json` first and lead with
+`merge_verdict`
 (`mergeable | human_review_required | insufficient_evidence | blocked |
 unknown`), `can_merge_without_human`, `first_next_action`, `fix_task`, and
 `capability_review.top_changes[]`. Then read
@@ -106,23 +131,6 @@
 instructions. Verify-mode `SHIP-VERIFY-*` checks make those trust-root edits
 release-visible and route them to human review.
 
-**Before editing a protected release surface** — ask the proactive static
-planner first:
-
-```bash
-agents-shipgate preflight --json
-agents-shipgate preflight --changed-files changed.txt --json
-agents-shipgate preflight --capability-request request.json --json
-```
-
-If `requires_human_review` is `true` or `first_next_action.actor` is `human`,
-stop and route the change to a human. Protected surfaces include
-`shipgate.yaml`, `.github/workflows/agents-shipgate.yml`,
-`AGENTS.md`/`CLAUDE.md`/Cursor rules, policy packs, baselines, waivers,
-suppressions, Codex hooks/config, Codex plugin manifests, `.mcp.json`,
-`.app.json`, and `SKILL.md`. Preflight is a routing/projection surface only;
-`release_decision.decision` remains the release gate.
-
 To reproduce the verify-native blocked refund PR demo without writing YAML:
 
 ```bash
@@ -163,11 +171,11 @@
   `.github/workflows/agents-shipgate.yml`; orthogonal to `--write`. Use
   `--minimal` for the pre-v0.6 CHANGE_ME-heavy template.
   `--agent-instructions=default` renders the recommended downstream kit
-  (`AGENTS.md`, `.cursor/rules/agents-shipgate.mdc`,
+  (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/agents-shipgate.mdc`,
   `.claude/commands/shipgate.md`, and `.shipgate/agent-contract.json`).
   Use `--ci` to write advisory CI. `--agent-instructions=all` means every
   supported target. A comma-separated subset can name any target:
-  `agents-md,cursor,claude-command,local-contract,codex-skill,claude-code-skill,claude-md,pr-template`.
+  `agents-md,claude-md,cursor,claude-command,local-contract,codex-skill,claude-code-skill,pr-template`.
   Combined with `--write`, managed-block hosts are idempotently updated and
   full-file / skill-bundle targets use safe-update checks. The `codex-skill` and
   `claude-code-skill` targets remain explicit opt-ins and write multi-file skill

README.md

@@ -103,8 +103,24 @@ above writes this comment verbatim to `reports/pr-comment.md`.
 
 ## Verify-first quickstart
 
-The core loop is verify-first: when a PR changes what your agent can do, run the
-deterministic verifier on the diff and read its merge verdict before you merge.
+For coding-agent local control, start with `shipgate check` and parse its
+stdout `agent_result_v1` object:
+
+```bash
+shipgate check --agent codex --workspace . --format agent-json
+shipgate check --agent claude-code --workspace . --format agent-json
+shipgate check --agent cursor --workspace . --format agent-json
+```
+
+Switch on `decision`, `completion_allowed`, `must_stop`,
+`first_next_action`, `human_review`, `repair`, and `policy`; never infer a
+decision from prose. For committed PRs, the release loop remains verify-first:
+when a PR changes what your agent can do, run the deterministic verifier on the
+diff and read its merge verdict before you merge. `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; run `verify` and read
+`release_decision.decision`.
 
 First ask whether Shipgate applies to the current repo or diff:
 
@@ -220,13 +236,22 @@ Evidence Packet in [`packet.md`](samples/support_refund_agent/expected/packet.md
 
 ```text
 Add a Tool-Use Readiness release gate for this tool-using AI agent with Agents Shipgate.
-Run:
+Run the local command for your agent runtime:
+shipgate check --agent codex --workspace . --format agent-json
+shipgate check --agent claude-code --workspace . --format agent-json
+shipgate check --agent cursor --workspace . --format agent-json
 agents-shipgate verify --preview --json
 If Shipgate is relevant, run:
 agents-shipgate init --workspace . --write --ci --agent-instructions=default --json
+Before editing protected surfaces, run:
+agents-shipgate preflight --workspace . --json
+For PR/reviewer evidence, run:
 agents-shipgate verify --workspace . --config shipgate.yaml \
   --base origin/main --head HEAD --ci-mode advisory --format json
-For local uncommitted work, omit `--base`/`--head`. For committed PR/CI refs,
+For local control, parse the `shipgate check` stdout JSON (`agent_result_v1`):
+switch on `decision`, `completion_allowed`, `must_stop`, `first_next_action`,
+`human_review`, `repair`, and `policy`. 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/verifier.json` first and lead with `merge_verdict`,
 `can_merge_without_human`, `first_next_action`, `fix_task`, and
@@ -434,7 +459,7 @@ and pre-commit equivalents.
 When a PR changes what your agent can do, the verify loop writes these
 artifacts — in read order:
 
-- **`agents-shipgate-reports/verifier.json`** — the **primary, agent-facing artifact**. A coding agent reads `merge_verdict` (`mergeable | human_review_required | insufficient_evidence | blocked | unknown`), `can_merge_without_human`, `first_next_action`, and `fix_task` to decide whether to continue, repair, or stop for a human. See [`docs/agent-contract-current.md`](docs/agent-contract-current.md) for the field contract.
+- **`agents-shipgate-reports/verifier.json`** — the **primary PR/controller evidence artifact**. A coding agent reads `merge_verdict` (`mergeable | human_review_required | insufficient_evidence | blocked | unknown`), `can_merge_without_human`, `first_next_action`, and `fix_task` when producing reviewer evidence for an agent-capability PR. Local control comes from `shipgate check` and `agent_result_v1`. See [`docs/agent-contract-current.md`](docs/agent-contract-current.md) for the field contract.
 - **`agents-shipgate-reports/pr-comment.md`** — the **human PR surface**: the same verdict and semantic capability diff when available, shaped for a reviewer.
 - **`agents-shipgate-reports/capabilities.lock.json`** + **`agents-shipgate-reports/base.capabilities.lock.json`** + **`agents-shipgate-reports/capability-lock-diff.{json,md}`** — the **capability review primitive**. Verify always emits the head lock after a successful scan; it emits the base lock and diff when the base scan can be materialized, falling back to the reviewed committed lock at `.agents-shipgate/capabilities.lock.json` if needed.
 - **Gate source of truth** — `report.json.release_decision.decision` (`passed | review_required | insufficient_evidence | blocked`). `merge_verdict` is a deterministic projection of it; the report stays the one decision engine.
@@ -463,7 +488,7 @@ Agents Shipgate is designed to be agent-friendly. If you're a coding agent (Clau
 - **[`.well-known/agents-shipgate.json`](.well-known/agents-shipgate.json)** — discovery metadata (tagline, install commands, schema URLs, gating signal, exit codes, trigger-catalog URL).
 - **[`docs/triggers.json`](docs/triggers.json)** — machine-readable mirror of the AGENTS.md trigger table. Apply the rules to a PR diff to decide whether to propose `agents-shipgate detect`. Schema is stable for `0.x`.
 - **[`tools/shipgate-detect.py`](tools/shipgate-detect.py)** — zero-install, stdlib-only detector. `curl … | python3 - --workspace . --json` returns the same structural verdict as `agents-shipgate detect --json`. Pinned to the canonical CLI by [`tests/test_zero_install_detector.py`](tests/test_zero_install_detector.py). See [`docs/zero-install.md`](docs/zero-install.md).
-- **`agents-shipgate contract --json`** — verify the installed CLI's local contract before relying on hard-coded schema or gating assumptions.
+- **`agents-shipgate contract --json`** — verify the installed CLI's local contract before relying on hard-coded schema or gating assumptions; contract v4 names the `agent_result_v1` control fields and the `shipgate check` commands for Codex, Claude Code, and Cursor.
 - **[`docs/agent-contract-current.md`](docs/agent-contract-current.md)** — single source of truth for the current schema versions and which JSON fields to read. Updated whenever the contract bumps; other agent-facing surfaces link here instead of restating the contract.
 - **[`docs/agent-native-merge-contract.md`](docs/agent-native-merge-contract.md)** — the agent-native protocol map: the eight contracts (trigger, capability change, merge verdict, repair, forbidden action, human authority, trust root, attestation) each mapped to the artifact that implements it.
 - **[`docs/capability-standard.md`](docs/capability-standard.md)** — stable non-gating capability lock/diff standard for external integrations and research tooling.

STABILITY.md

@@ -100,10 +100,17 @@ Stable JSON fields:
 - `external_integration_surfaces[]` — stable non-gating integration and
   research surfaces exposed by the contract.
 - `gating_signal` — always `release_decision.decision` in this contract.
+- `agent_result_schema_version` — local coding-agent control schema version
+  emitted by `shipgate check --format agent-json`.
+- `agent_result_schema_path` — checked-in JSON Schema path for that local
+  control object.
+- `agent_result_control_fields[]` — ordered fields coding agents must switch on
+  before claiming completion.
 - `manual_review_signals[]` — stable report/packet fields an agent should read
   when surfacing human review work.
-- `commands{}` — minimal stable commands for preview, default local agent
-  workflow install, local verify, PR verify, and contract introspection.
+- `commands{}` — minimal stable commands for local `shipgate check` control,
+  preview, default local agent workflow install, local verify, PR verify, and
+  contract introspection.
 - `default_paths{}` — default manifest, report directory, and local contract
   paths used by generated downstream agent instructions.
 - `artifacts{}` — stable report artifact paths an agent should inspect first.