Canonicalize three-command CLI positioning

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

@@ -1,6 +1,6 @@
 ---
 name: agents-shipgate
-description: Use when the user wants to run the prominent Agents Shipgate flows — `shipgate check`, `shipgate verify`, or `shipgate audit --host` — for AI agent capability changes, PR release readiness, or coding-agent host grants.
+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.
 ---
 
 # Agents Shipgate
@@ -15,28 +15,28 @@
 
 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: "8"` 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 `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.
 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`.
-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 `shipgate verify` before completion and route trust-root review to a human when the verifier requires it.
+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.
 9. Auto-apply only high-confidence safe patches. Do not auto-assert 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: "8"` 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 `contract_version: "9"` or newer; 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 `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 `shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json`.
-- Unconfigured repo or uncertain relevance: run `shipgate verify --preview --json`.
+- 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`.
+- Unconfigured repo or uncertain relevance: run `agents-shipgate verify --preview --json`.
 - Host grants: run `shipgate audit --host --json --out agents-shipgate-reports/host-grants.json`.
 
 ## Boundaries
 
-- Do not claim a finding is fixed without re-running `shipgate verify` and reporting the new merge verdict and release decision.
-- Do not self-approve trust-root changes; when `shipgate verify` returns human review required, surface it to a human.
+- 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`.
 - 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`.

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

@@ -1,7 +1,7 @@
 # Agents Shipgate Recipes
 
 Use these recipes after the `agents-shipgate` skill triggers. The prominent
-flows are `shipgate check`, `shipgate verify`, and `shipgate audit --host`.
+flows are `shipgate check`, `agents-shipgate verify`, and `shipgate audit --host`.
 Supporting commands remain callable, but should not be the first thing an agent
 recommends.
 
@@ -16,15 +16,15 @@
 agents-shipgate contract --json
 ```
 
-Require `agents-shipgate contract --json` to report `contract_version: "8"` or
+Require `agents-shipgate contract --json` to report `contract_version: "9"` or
 newer. 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 v8 or
+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.
 
@@ -47,7 +47,7 @@
 release surfaces.
 
 ```bash
-AGENTS_SHIPGATE_AGENT_MODE=1 shipgate verify \
+AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify \
   --workspace . --config shipgate.yaml \
   --base origin/main --head HEAD --ci-mode advisory --format json
 ```
@@ -58,7 +58,7 @@
 the repo is not configured or relevance is unclear, run:
 
 ```bash
-AGENTS_SHIPGATE_AGENT_MODE=1 shipgate verify --preview --json
+AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify --preview --json
 ```
 
 Read `agents-shipgate-reports/agent-handoff.json` first. Lead with
@@ -87,7 +87,7 @@
 
 ## Supporting Setup And Repair
 
-If `shipgate verify --preview --json` says the repo needs configuration, the
+If `agents-shipgate verify --preview --json` says the repo needs configuration, the
 supporting setup commands remain available:
 
 ```bash
@@ -110,7 +110,7 @@
 4. For policy/evidence gaps, propose the exact human decision needed. Do not
    fabricate approval, confirmation, idempotency, broad-scope,
    prohibited-action, or runtime-trace evidence.
-5. Re-run `shipgate verify` and report the new merge verdict, release
+5. Re-run `agents-shipgate verify` and report the new merge verdict, release
    decision, blocker count, and review-item count.
 
 For one finding:

.claude/commands/shipgate.md

@@ -1,3 +1,3 @@
 ---
 description: Run the prominent Agents Shipgate flows: check, verify, or audit --host
 ---
@@ -10,7 +10,7 @@
 If the arguments include `audit`, run the host-grant audit flow. If they include
 `check`, run the local boundary check. Otherwise run the verifier flow. The
 supporting adoption and scan commands remain available, but this slash command
-should lead with only the prominent flows: `shipgate check`, `shipgate verify`,
+should lead with only the prominent flows: `shipgate check`, `agents-shipgate verify`,
 and `shipgate audit --host`.
 
 The canonical, self-contained verifier instructions live in the bundled prompt
@@ -26,7 +26,7 @@
 ```bash
 AGENTS_SHIPGATE_AGENT_MODE=1 shipgate check \
   --agent claude-code --workspace . --format codex-boundary-json
-AGENTS_SHIPGATE_AGENT_MODE=1 shipgate verify \
+AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify \
   --workspace . --config shipgate.yaml \
   --base origin/main --head HEAD \
   --ci-mode advisory --format json
@@ -67,7 +67,7 @@
 permissions, policies, CI gates, or `shipgate.yaml`, run the verifier:
 
 ```bash
-shipgate verify --base origin/main --head HEAD --json
+agents-shipgate verify --base origin/main --head HEAD --json
 ```
 
 Read `agents-shipgate-reports/verifier.json` first and lead with `merge_verdict`

.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:
@@ -52,9 +52,9 @@
 
 For local verification, run:
 
-  shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json
+  agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json
 
-For committed PR/CI verification, run `shipgate verify --base
+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

.well-known/agents-shipgate.json

@@ -76,8 +76,7 @@
     "check_codex": "shipgate check --agent codex --workspace . --format codex-boundary-json",
     "check_claude_code": "shipgate check --agent claude-code --workspace . --format codex-boundary-json",
     "check_cursor": "shipgate check --agent cursor --workspace . --format codex-boundary-json",
-    "verify_local": "shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --json",
-    "verify_pr": "shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --json",
+    "verify_pr": "agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --json",
     "host_audit": "shipgate audit --host --json --out agents-shipgate-reports/host-grants.json"
   },
   "commands": {
@@ -88,6 +87,7 @@
     "preflight": "agents-shipgate preflight --workspace . --config shipgate.yaml --plan - --json",
     "preview": "agents-shipgate verify --preview --json",
     "install_ai_coding_workflow": "agents-shipgate init --workspace . --write --ci --agent-instructions=default --json",
+    "verify_local": "agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --json",
     "verify_pr": "agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json",
     "agent_handoff": "agents-shipgate agent handoff --from agents-shipgate-reports/verifier.json --json",
     "trigger": "agents-shipgate trigger --base origin/main --head HEAD --json",
@@ -99,7 +99,7 @@
     "org_policy_packs": "agents-shipgate org policy-packs --config shipgate.yaml --json",
     "registry_summary": "agents-shipgate registry summary --registry .agents-shipgate/registry.jsonl --json",
     "registry_verify": "agents-shipgate registry verify --registry .agents-shipgate/registry.jsonl --json",
-    "host_audit": "agents-shipgate audit --host --json --out agents-shipgate-reports/host-grants.json",
+    "host_audit": "shipgate audit --host --json --out agents-shipgate-reports/host-grants.json",
     "capture_scenario": "agents-shipgate feedback capture --before verifier-before.json --after verifier-after.json --redact --out scenario.json",
     "governance_benchmark": "PYTHONPATH=src python scripts/run_governance_benchmark.py --catalog benchmark/agent-pr-governance/cases.yaml --json"
   },
@@ -126,7 +126,7 @@
   "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": "8",
+  "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"],
   "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.
@@ -526,7 +526,7 @@
 
 | Command | Purpose |
 |---|---|
-| `agents-shipgate audit --host` | Zero-config, read-only inventory of coding-agent host grants (MCP servers, permission rules, hooks, workflow scopes); `--json` available. Works without `shipgate.yaml`. |
+| `shipgate audit --host` | Zero-config, read-only inventory of coding-agent host grants (MCP servers, permission rules, hooks, workflow scopes); `--json` available. Works without `shipgate.yaml`. |
 | `agents-shipgate mcp-serve` | Local read-only stdio MCP server (`[mcp]` extra) exposing `shipgate.check`, `shipgate.preflight`, `shipgate.explain`, `shipgate.capabilities`, and `shipgate.handoff`. See [`docs/mcp-server.md`](docs/mcp-server.md). |
 | `agents-shipgate org status` | Local organization governance projection over exception hygiene, policy-pack pins, host-grant drift, and registry readiness; `--json` available and governance violations exit `20`. |
 | `agents-shipgate registry` | `ingest --attestation <file>` / `query` / `report --bypass` — local capability-release ledger over attestations. |