ThreeMoonsLab · pengfei-threemoonslab · May 31, 2026 · May 31, 2026 · May 31, 2026 · May 31, 2026
diff --git a/.agents/skills/agents-shipgate/SKILL.md b/.agents/skills/agents-shipgate/SKILL.md
@@ -1,11 +1,11 @@
 ---
 name: agents-shipgate
-description: Use when the user wants to add or run Agents Shipgate as a local-first, static Tool-Use Readiness release gate for an AI agent's tool surface; review or prepare a tool-using agent for release; scan MCP, OpenAPI, OpenAI Agents SDK, Anthropic, Google ADK, LangChain/LangGraph, CrewAI, OpenAI API, Codex plugin, or n8n tool artifacts; add advisory CI; or interpret, fix, triage, suppress, or explain a Shipgate finding.
+description: Use when the user wants to add or run Agents Shipgate — the deterministic merge gate for AI-generated agent capability changes — on an AI agent's tool surface; review or prepare a tool-using agent for release; scan MCP, OpenAPI, OpenAI Agents SDK, Anthropic, Google ADK, LangChain/LangGraph, CrewAI, OpenAI API, Codex plugin, or n8n tool artifacts; add advisory CI; or interpret, fix, triage, suppress, or explain a Shipgate finding.
 ---
 
 # Agents Shipgate
 
-Agents Shipgate is a local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. It reads `shipgate.yaml` plus local tool sources and writes deterministic reports as Markdown, JSON, SARIF, and Release Evidence Packets.
+Agents Shipgate is the deterministic merge gate for AI-generated agent capability changes — a local-first, static Tool-Use Readiness review. It reads `shipgate.yaml` plus local tool sources and writes deterministic reports as Markdown, JSON, SARIF, and Release Evidence Packets.
 
 Use this skill when a task touches agent tools, MCP exports, OpenAPI specs, prompts that constrain tool use, permissions/scopes, approval or confirmation policies, `shipgate.yaml`, Shipgate CI, or `agents-shipgate-reports/report.json`.
 

diff --git a/.claude/commands/shipgate.md b/.claude/commands/shipgate.md
@@ -1,14 +1,14 @@
 ---
-description: Bootstrap or verify agents-shipgate as a local-first, static Tool-Use Readiness release gate for AI agent tool surfaces
+description: Bootstrap or verify agents-shipgate as the deterministic merge gate for AI-generated agent capability changes
 ---
 
 Arguments: `$ARGUMENTS`
 
 If the arguments include `verify`, run the ongoing-PR verifier flow. Otherwise
 run the agents-shipgate bootstrap flow on the current repo: install the CLI,
-add a local-first, static Tool-Use Readiness release gate for AI agent tool
-surfaces, generate `shipgate.yaml`, fill in placeholders, run a scan, and
-surface the top findings from the JSON report.
+add the deterministic merge gate for AI-generated agent capability changes (a
+local-first, static Tool-Use Readiness review), generate `shipgate.yaml`, fill
+in placeholders, run a scan, and surface the top findings from the JSON report.
 
 The canonical, self-contained instructions live in the bundled prompt files.
 For bootstrap, read `prompts/add-shipgate-to-repo.md`. For verifier runs, read

diff --git a/.cursor/rules/agents-shipgate.mdc b/.cursor/rules/agents-shipgate.mdc
@@ -1,5 +1,5 @@
 ---
-description: Run Agents Shipgate as a local-first, static Tool-Use Readiness release gate for AI agent tool surfaces.
+description: Run Agents Shipgate as the deterministic merge gate for AI-generated agent capability changes.
 globs:
   - "shipgate.yaml"
   - "**/*openapi*.yaml"
@@ -28,8 +28,8 @@ globs:
 alwaysApply: false
 ---
 
-Agents Shipgate is the local-first, static Tool-Use Readiness release gate for
-AI agent tool surfaces.
+Agents Shipgate is the deterministic merge gate for AI-generated agent
+capability changes — a local-first, static Tool-Use Readiness review.
 
 When a change affects agent tools, MCP exports, OpenAPI specs, prompts,
 permissions, approval policies, or release gates, run Agents Shipgate.

diff --git a/.well-known/agents-shipgate.json b/.well-known/agents-shipgate.json
@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "agents-shipgate",
   "display_name": "Agents Shipgate",
-  "tagline": "Local-first, static Tool-Use Readiness release gate for AI agent tool surfaces",
+  "tagline": "The deterministic merge gate for AI-generated agent capability changes",
   "version": "0.10.0",
   "license": "Apache-2.0",
   "publisher": {
@@ -13,7 +13,7 @@
   "primary_wedge": "tool_use_readiness",
   "positioning": {
     "short": "Agent release readiness for tool-using AI agents",
-    "answer": "Agents Shipgate is described by the canonical tagline: Local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. It is an open-source CLI and GitHub Action from Three Moons Lab that produces deterministic Tool-Use Readiness Reports before production-like permissions are granted.",
+    "answer": "Agents Shipgate is described by the canonical tagline: The deterministic merge gate for AI-generated agent capability changes. It is an open-source CLI and GitHub Action from Three Moons Lab that produces deterministic Tool-Use Readiness Reports before production-like permissions are granted.",
     "primary_use_case": "Run in CI before promoting an agent whose MCP, OpenAPI, SDK, workflow, or plugin tool surface changed.",
     "not_for": ["llm_evals", "runtime_guardrails", "runtime_observability", "general_linting"]
   },

diff --git a/AGENTS.md b/AGENTS.md
@@ -8,7 +8,7 @@ Authoritative instructions for AI coding agents (Claude Code, Codex, Cursor, Aid
 
 ## What this project is
 
-Local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. Reads `shipgate.yaml` plus tool sources (MCP exports, OpenAPI specs, OpenAI Agents SDK Python files, Anthropic Messages API tool/prompt artifacts, Google ADK Python/config files, LangChain/LangGraph Python files, CrewAI Python files, OpenAI API artifacts, Codex plugin packages and marketplaces, n8n workflow JSON/stubs) and produces deterministic findings.
+The deterministic merge gate for AI-generated agent capability changes. Reads `shipgate.yaml` plus tool sources (MCP exports, OpenAPI specs, OpenAI Agents SDK Python files, Anthropic Messages API tool/prompt artifacts, Google ADK Python/config files, LangChain/LangGraph Python files, CrewAI Python files, OpenAI API artifacts, Codex plugin packages and marketplaces, n8n workflow JSON/stubs) and produces deterministic findings. Local-first and static by default — no agent execution, tool calls, LLM calls, or network access.
 
 - **Inputs:** MCP · OpenAPI · OpenAI Agents SDK · Anthropic Messages API · Google ADK · LangChain/LangGraph · CrewAI · OpenAI API · Codex plugin · n8n
 - **Outputs:** Markdown · JSON · SARIF
@@ -31,9 +31,9 @@ Do **not** use any of: `Agent Shipgate` (singular), `Agent Shipcheck`, `agents s
 
 The canonical tagline is:
 
-> Local-first, static Tool-Use Readiness release gate for AI agent tool surfaces.
+> The deterministic merge gate for AI-generated agent capability changes.
 
-This single sentence is the source of truth for the GitHub repo description, [README.md](README.md), the [wiki Home page](https://github.com/ThreeMoonsLab/agents-shipgate/wiki/Home), and the [marketing site](https://threemoonslab.com/) `<meta name="description">`. Keep them in sync.
+This single sentence is the source of truth for the GitHub repo description, [README.md](README.md), the [wiki Home page](https://github.com/ThreeMoonsLab/agents-shipgate/wiki/Home), and the [marketing site](https://threemoonslab.com/) `<meta name="description">`. Keep them in sync; the website's `.well-known` discovery file is pinned to the latest released tag and refreshes at each release.
 
 Use **Tool-Use Readiness** in Title Case when naming the product/category or
 the **Tool-Use Readiness Report** artifact. Use **tool-use readiness** in

diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="assets/readme-header-dark.png">
-    <img src="assets/readme-header.png" alt="Agents Shipgate · local-first, static Tool-Use Readiness release gate for AI agent tool surfaces" width="100%">
+    <img src="assets/readme-header.png" alt="Agents Shipgate · the deterministic merge gate for AI-generated agent capability changes" width="100%">
   </picture>
 </p>
 
@@ -13,9 +13,13 @@
 [![License](https://img.shields.io/pypi/l/agents-shipgate)](LICENSE)
 [![CI](https://github.com/ThreeMoonsLab/agents-shipgate/actions/workflows/ci.yml/badge.svg)](https://github.com/ThreeMoonsLab/agents-shipgate/actions/workflows/ci.yml)
 
-**Local-first, static Tool-Use Readiness release gate for AI agent tool surfaces.**
+**Your coding agent changed what your AI agent can do — Agents Shipgate tells you whether it can merge.**
 
-<!-- Canonical tagline: Local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. -->
+**The deterministic merge gate for AI-generated agent capability changes.**
+
+Local-first and static by default — no agent execution, tool calls, LLM calls, or network access.
+
+<!-- Canonical tagline: The deterministic merge gate for AI-generated agent capability changes. -->
 
 Agents Shipgate is an open-source CLI and GitHub Action for local-first,
 static Tool-Use Readiness review. It scans MCP, OpenAPI, OpenAI Agents SDK,
@@ -40,10 +44,32 @@ Apache-2.0.
 
 ## One-command quickstart
 
-For a 5-minute first run, use one of three paths: scan the bundled fixture,
-run the zero-install detector, or initialize Shipgate in your real repo. If you
-already have [`uv`](https://docs.astral.sh/uv/) installed, the fixture path is
-a one-command check with no persistent install:
+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.
+On a committed PR/CI ref, pass the base and head so the diff — the capability
+delta and trust-root signals — is in scope (make the base ref available first,
+e.g. `git fetch origin main`):
+
+```bash
+agents-shipgate verify --workspace . --config shipgate.yaml \
+  --ci-mode advisory --format json --base origin/main --head HEAD
+```
+
+For local, uncommitted work, omit `--base`/`--head` so your working-tree edits
+are scanned instead:
+
+```bash
+agents-shipgate verify --workspace . --config shipgate.yaml \
+  --ci-mode advisory --format json
+```
+
+The release gate is `agents-shipgate-reports/report.json` →
+`release_decision.decision` (`blocked | review_required | insufficient_evidence | passed`).
+No `shipgate.yaml` yet? Run `agents-shipgate init --workspace . --write` first.
+
+Want a 5-minute first run with zero setup? Scan the bundled fixture. If you
+already have [`uv`](https://docs.astral.sh/uv/) installed, the fixture path is a
+one-command check with no persistent install:
 
 ```bash
 uvx agents-shipgate fixture run support_refund_agent
@@ -294,8 +320,9 @@ Once an AI agent can refund, email, cancel, deploy, or modify a record, every to
 
 Agents Shipgate produces a deterministic answer to that question, before promotion.
 
-The current product promise is deliberately narrow: a local-first, static
-Tool-Use Readiness release gate. Broader lifecycle ideas are future roadmap
+The current product promise is deliberately narrow: a deterministic, local-first,
+static merge gate for AI-generated agent capability changes — the Tool-Use
+Readiness review run at PR time. Broader lifecycle ideas are future roadmap
 work, not claims this scanner makes today.
 
 ## Findings Gallery

diff --git a/action.yml b/action.yml
@@ -1,10 +1,10 @@
 name: Agents Shipgate
 description: >-
-  Local-first, static Tool-Use Readiness release gate for AI agent tool
-  surfaces. Scans MCP, OpenAPI, OpenAI Agents SDK, Anthropic, Google ADK,
+  The deterministic merge gate for AI-generated agent capability changes.
+  Scans MCP, OpenAPI, OpenAI Agents SDK, Anthropic, Google ADK,
   LangChain, CrewAI, OpenAI API, Codex plugin, and n8n artifacts.
   Writes a Tool-Use Readiness Report (Markdown / JSON / SARIF) before your
-  agent gets production-like permissions. Static-by-default. Audited
+  agent gets production-like permissions. Local-first and static-by-default. Audited
   exceptions are pinned per call site in
   tests/test_adapter_static_only.py::ALLOWED_EXCEPTIONS. Apache-2.0.
 author: ThreeMoonsLab

diff --git a/adoption-kits/claude-code-skill/.agents-shipgate-kit-metadata.json b/adoption-kits/claude-code-skill/.agents-shipgate-kit-metadata.json
@@ -4,7 +4,8 @@
   "prior_render_sha256": {
     "SKILL.md": [
       "139b5e00b916448cf2de4752221c66296a7e546865b1efdf93f98d8bb5cb3019",
-      "5ab92f77352ea31ad03c28e1d596b20ada24fa4176a5e0b0b38990e4a00fb5bb"
+      "5ab92f77352ea31ad03c28e1d596b20ada24fa4176a5e0b0b38990e4a00fb5bb",
+      "9ce82bdc41f2e1ea28c7fec3aaeec0137efeacf8986b66a9ac0e3eccc5abd834"
     ]
   },
   "bootstrap_legacy_sha256": {

diff --git a/adoption-kits/claude-code-skill/SKILL.md b/adoption-kits/claude-code-skill/SKILL.md
@@ -1,11 +1,11 @@
 ---
 name: agents-shipgate
-description: Use when the user wants to add a local-first, static Tool-Use Readiness release gate for an AI agent's tool surface, run agents-shipgate scans, fix or triage Shipgate findings, add Shipgate to CI, or interpret a shipgate report. Triggers on phrases like "add shipgate", "release readiness for my agent", "tool-use readiness", "scan my agent", "shipgate scan", "shipgate.yaml", "agents-shipgate-reports/report.json", "fix shipgate finding".
+description: Use when the user wants to add the deterministic merge gate for AI-generated agent capability changes (a local-first, static Tool-Use Readiness review) to an AI agent's tool surface, run agents-shipgate scans, fix or triage Shipgate findings, add Shipgate to CI, or interpret a shipgate report. Triggers on phrases like "add shipgate", "release readiness for my agent", "tool-use readiness", "scan my agent", "shipgate scan", "shipgate.yaml", "agents-shipgate-reports/report.json", "fix shipgate finding".
 ---
 
 # agents-shipgate skill
 
-`agents-shipgate` is a local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. It analyzes `shipgate.yaml` plus tool sources (MCP exports, OpenAPI specs, OpenAI Agents SDK Python files, Anthropic Messages API artifacts, Google ADK files, LangChain/LangGraph files, CrewAI files, OpenAI API artifacts, Codex plugin packages and marketplaces, n8n workflow JSON) and emits deterministic findings as Markdown, JSON, and SARIF.
+`agents-shipgate` is the deterministic merge gate for AI-generated agent capability changes — a local-first, static Tool-Use Readiness review. It analyzes `shipgate.yaml` plus tool sources (MCP exports, OpenAPI specs, OpenAI Agents SDK Python files, Anthropic Messages API artifacts, Google ADK files, LangChain/LangGraph files, CrewAI files, OpenAI API artifacts, Codex plugin packages and marketplaces, n8n workflow JSON) and emits deterministic findings as Markdown, JSON, and SARIF.
 
 It does **not** run agents, call tools, invoke LLMs, connect to MCP servers, or send telemetry by default. Static analysis only; audited exceptions are pinned in `tests/test_adapter_static_only.py::ALLOWED_EXCEPTIONS`.
 

diff --git a/adoption-kits/claude-code-skill/prompts/add-shipgate-to-repo.md b/adoption-kits/claude-code-skill/prompts/add-shipgate-to-repo.md
@@ -3,7 +3,8 @@
 You are working in a repo that may contain an AI agent — likely one of: an MCP server tool list (`*mcp*.json` or `.agents-shipgate/*.json`), an OpenAPI spec the agent calls, a Codex plugin package (`.codex-plugin/plugin.json`) or marketplace (`.agents/plugins/marketplace.json`), a Python file with `@function_tool` / `@tool` decorators (OpenAI Agents SDK, LangChain, CrewAI), a Google ADK agent in `agent.py`, an Anthropic Messages API artifact set under `prompts/`/`tools/anthropic-tools.json`/`policies/anthropic-policy.yaml`, or an OpenAI API artifact set under `prompts/`/`tools/openai-tools.json`/`openai-config.json`.
 
 Your job is to drive the canonical 4-call flow end-to-end in one tool-using
-turn, which adds a local-first, static Tool-Use Readiness release gate.
+turn, which adds the deterministic merge gate for AI-generated agent capability
+changes — a local-first, static Tool-Use Readiness review.
 
 ## Your task
 

diff --git a/adoption-kits/codex-skill/.agents-shipgate-kit-metadata.json b/adoption-kits/codex-skill/.agents-shipgate-kit-metadata.json
@@ -3,7 +3,8 @@
   "target": "codex-skill",
   "prior_render_sha256": {
     "SKILL.md": [
-      "920b60dcfeacb5eac55936d82f31796eb9a88bcec0e910fa56c278018c597772"
+      "920b60dcfeacb5eac55936d82f31796eb9a88bcec0e910fa56c278018c597772",
+      "367ef145ef928912cc517149e61b0efe413e740680787ef13441a6abd55b4647"
     ],
     "references/recipes.md": [
       "df5110bfa05eeabd9b918d8902b5c054fa547d1155be61ef6e7d7d63378bf210"

diff --git a/adoption-kits/codex-skill/SKILL.md b/adoption-kits/codex-skill/SKILL.md
@@ -1,11 +1,11 @@
 ---
 name: agents-shipgate
-description: Use when the user wants to add or run Agents Shipgate as a local-first, static Tool-Use Readiness release gate for an AI agent's tool surface; review or prepare a tool-using agent for release; scan MCP, OpenAPI, OpenAI Agents SDK, Anthropic, Google ADK, LangChain/LangGraph, CrewAI, OpenAI API, Codex plugin, or n8n tool artifacts; add advisory CI; or interpret, fix, triage, suppress, or explain a Shipgate finding.
+description: Use when the user wants to add or run Agents Shipgate — the deterministic merge gate for AI-generated agent capability changes — on an AI agent's tool surface; review or prepare a tool-using agent for release; scan MCP, OpenAPI, OpenAI Agents SDK, Anthropic, Google ADK, LangChain/LangGraph, CrewAI, OpenAI API, Codex plugin, or n8n tool artifacts; add advisory CI; or interpret, fix, triage, suppress, or explain a Shipgate finding.
 ---
 
 # Agents Shipgate
 
-Agents Shipgate is a local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. It reads `shipgate.yaml` plus local tool sources and writes deterministic reports as Markdown, JSON, SARIF, and Release Evidence Packets.
+Agents Shipgate is the deterministic merge gate for AI-generated agent capability changes — a local-first, static Tool-Use Readiness review. It reads `shipgate.yaml` plus local tool sources and writes deterministic reports as Markdown, JSON, SARIF, and Release Evidence Packets.
 
 Use this skill when a task touches agent tools, MCP exports, OpenAPI specs, prompts that constrain tool use, permissions/scopes, approval or confirmation policies, `shipgate.yaml`, Shipgate CI, or `agents-shipgate-reports/report.json`.
 

diff --git a/benchmark/setup-variants/10-agents-md/AGENTS.md.template b/benchmark/setup-variants/10-agents-md/AGENTS.md.template
@@ -1,7 +1,7 @@
 ## Tool-Use Readiness Release Gate
 
-This repo uses Agents Shipgate as the local-first, static Tool-Use Readiness
-release gate for AI agent tool surfaces.
+This repo uses Agents Shipgate as the deterministic merge gate for AI-generated
+agent capability changes — a local-first, static Tool-Use Readiness review.
 
 Run Shipgate when this PR changes agent tools, MCP exports, OpenAPI specs,
 prompts that constrain tool use, permissions, approval policies,

diff --git a/benchmark/setup-variants/30-cursor-rule/agents-shipgate.mdc.template b/benchmark/setup-variants/30-cursor-rule/agents-shipgate.mdc.template
@@ -1,5 +1,5 @@
 ---
-description: Run Agents Shipgate as a local-first, static Tool-Use Readiness release gate for AI agent tool surfaces.
+description: Run Agents Shipgate as the deterministic merge gate for AI-generated agent capability changes.
 globs:
   - "shipgate.yaml"
   - "**/*openapi*.yaml"
@@ -28,8 +28,8 @@ globs:
 alwaysApply: false
 ---
 
-Agents Shipgate is the local-first, static Tool-Use Readiness release gate for
-AI agent tool surfaces.
+Agents Shipgate is the deterministic merge gate for AI-generated agent
+capability changes — a local-first, static Tool-Use Readiness review.
 
 When a change affects agent tools, MCP exports, OpenAPI specs, prompts,
 permissions, approval policies, or release gates, run Agents Shipgate.

diff --git a/docs/ai-search-summary.md b/docs/ai-search-summary.md
@@ -7,8 +7,9 @@ short, citable description of Agents Shipgate.
 ## What Agents Shipgate is
 
 Agents Shipgate is an open-source CLI and GitHub Action from Three Moons Lab.
-It is a local-first, static Tool-Use Readiness release gate for AI agent tool
-surfaces. It reads a `shipgate.yaml` manifest plus declared local tool sources,
+It is the deterministic merge gate for AI-generated agent capability changes —
+a local-first, static Tool-Use Readiness review. It reads a `shipgate.yaml`
+manifest plus declared local tool sources,
 then writes deterministic Tool-Use Readiness Reports as Markdown, JSON, and
 SARIF.
 

diff --git a/docs/category.md b/docs/category.md
@@ -4,8 +4,9 @@ A **Tool-Use Readiness release gate** is a local-first, static pre-flight
 check that runs before an agent is promoted to staging, production-like, or
 production environments.
 
-Agents Shipgate is a local-first, static Tool-Use Readiness release gate for
-AI agent tool surfaces. It focuses on what tools are attached, what schemas
+Agents Shipgate is the deterministic merge gate for AI-generated agent
+capability changes: the local-first, static Tool-Use Readiness review that runs
+at PR time. It focuses on what tools are attached, what schemas
 they expose, what scopes they require, what policies the manifest declares,
 and which release risks need human review.