diff --git a/.agents/skills/agents-shipgate/SKILL.md b/.agents/skills/agents-shipgate/SKILL.md index 59090336..943eb89e 100644 --- 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 index 6f181636..081d179f 100644 --- 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 index 6f07f5f1..503da0b0 100644 --- 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 index 5806eda3..9f16f0fb 100644 --- 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 index 24371e40..ab2f9b08 100644 --- 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/) ``. 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/) ``. 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 index 142f3903..b5cbf23f 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@

- Agents Shipgate · local-first, static Tool-Use Readiness release gate for AI agent tool surfaces + Agents Shipgate · the deterministic merge gate for AI-generated agent capability changes

@@ -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.** - +**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. + + 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 index 560ea522..379e5772 100644 --- 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 index 409c9970..806a7ecd 100644 --- 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 index 94451e92..bb5e334a 100644 --- 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 index afa92503..9847a8bb 100644 --- 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 index 06096f85..67a538ee 100644 --- 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 index 59090336..943eb89e 100644 --- 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 index 1091441b..9371e597 100644 --- 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 index 6f07f5f1..503da0b0 100644 --- 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 index bbdc9b01..f1e09740 100644 --- 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 index 04d56c9b..a8aca5e2 100644 --- 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. diff --git a/docs/concepts.md b/docs/concepts.md index 522938cd..6d23a6cd 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -1,7 +1,8 @@ # Concepts -The mental model behind Agents Shipgate, a local-first, static Tool-Use -Readiness release gate for AI agent tool surfaces. +The mental model behind Agents Shipgate, the deterministic merge gate for +AI-generated agent capability changes — a local-first, static Tool-Use +Readiness review. For the product-level definition of a Tool-Use Readiness release gate, see [`category.md`](category.md). For the agent-facing diff --git a/docs/design-partners.md b/docs/design-partners.md index b372bb7b..013fbcf9 100644 --- a/docs/design-partners.md +++ b/docs/design-partners.md @@ -1,7 +1,8 @@ # Design Partners -Three Moons Lab is looking for early design partners who are shipping -tool-using AI agents and want a repeatable release-readiness review before +Three Moons Lab is looking for early design partners who ship tool-using AI +agents — often with coding agents like Claude Code, Codex, or Cursor — and want +a deterministic merge gate on every AI-generated agent-capability change before production-like permissions are granted. ## Good Fit @@ -43,6 +44,9 @@ Three Moons Lab asks for: ## Contact +The fastest way to start: bring us one AI-generated PR that changes what your +agent can do, and we'll turn it into a deterministic merge verdict together. + Email `help@threemoonslab.com` with the subject `Agents Shipgate design partner review`. diff --git a/docs/engineering/ai-coding-workflow-verifier.md b/docs/engineering/ai-coding-workflow-verifier.md index 8fe7f120..91fd54b9 100644 --- a/docs/engineering/ai-coding-workflow-verifier.md +++ b/docs/engineering/ai-coding-workflow-verifier.md @@ -8,15 +8,15 @@ Scope: product direction, architecture constraints, roadmap, and acceptance crit ## 1. North star -Agents Shipgate is already a local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. The next product step is not to become a broader scanner. The next step is to become the deterministic verifier that must pass when Claude Code, Codex, Cursor, or a human produces an agent-related diff. +Agents Shipgate is the deterministic merge gate for AI-generated agent capability changes — today delivered as a local-first, static Tool-Use Readiness review. The next product step is not to become a broader scanner. The next step is to make that merge gate the deterministic verifier that must pass when Claude Code, Codex, Cursor, or a human produces an agent-related diff. North-star sentence: > When a coding agent changes what an AI agent can do, Agents Shipgate deterministically identifies the capability delta, applies release policy, explains the decision, and tells the coding agent or human reviewer the next safe action. -Keep the canonical category sentence: +Keep the 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. Add this sentence when the verifier loop ships: diff --git a/docs/faq.md b/docs/faq.md index 692b1eb3..6660065b 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -5,9 +5,9 @@ and AI search engines (ChatGPT, Claude, Perplexity, Google AI Overviews). ## What is agents-shipgate? -agents-shipgate is a local-first, static Tool-Use Readiness release gate for -AI agent tool surfaces. It is a CLI and GitHub Action. Open source, -Apache-2.0. +agents-shipgate is the deterministic merge gate for AI-generated agent +capability changes — a local-first, static Tool-Use Readiness review. It is a +CLI and GitHub Action. Open source, Apache-2.0. ## What is agent release readiness? diff --git a/docs/glossary.md b/docs/glossary.md index 57745c4e..342191c0 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -1,9 +1,9 @@ # Glossary -Category vocabulary for agents-shipgate, a local-first, static Tool-Use -Readiness release gate for AI agent tool surfaces. Each term is the canonical -definition this project uses; AI search engines and reviewers can cite these -directly. +Category vocabulary for agents-shipgate, the deterministic merge gate for +AI-generated agent capability changes — a local-first, static Tool-Use +Readiness review. Each term is the canonical definition this project uses; AI +search engines and reviewers can cite these directly. ## Agent release readiness diff --git a/docs/overview.md b/docs/overview.md index 652c055a..9070b13b 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,8 +1,9 @@ # Agents Shipgate Overview -Agents Shipgate is a local-first, static Tool-Use Readiness release gate for -AI agent tool surfaces. It reads `shipgate.yaml` plus declared local tool -sources and writes a Tool-Use Readiness Report 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 reads +`shipgate.yaml` plus declared local tool sources and writes a Tool-Use +Readiness Report as Markdown, JSON, and SARIF. Use it when an agent can call tools that refund, email, cancel, deploy, modify records, read sensitive data, or change infrastructure. The scanner runs before diff --git a/docs/target-repo-agent-snippets.md b/docs/target-repo-agent-snippets.md index 404cf9a0..dac46844 100644 --- a/docs/target-repo-agent-snippets.md +++ b/docs/target-repo-agent-snippets.md @@ -33,8 +33,8 @@ impact unless Shipgate is already configured or the user explicitly asks. ````md ## 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, @@ -132,8 +132,8 @@ advisory GitHub Action template under `ci-recipes/`. ````md ## Agents Shipgate -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. For agent tool-surface or release-policy changes, run: @@ -172,7 +172,7 @@ waivers, removing Shipgate CI, or weakening agent instructions. Verify-mode ```md --- -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" @@ -201,8 +201,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. @@ -271,8 +271,8 @@ References: ````md ## Tool-Use Readiness Release Gate -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. - [ ] If this PR changes agent tools, MCP/OpenAPI specs, prompts, permissions, approval policy, confirmation policy, CI release gates, or diff --git a/docs/use-cases/ai-generated-agent-prs.md b/docs/use-cases/ai-generated-agent-prs.md index 266010d1..396d777b 100644 --- a/docs/use-cases/ai-generated-agent-prs.md +++ b/docs/use-cases/ai-generated-agent-prs.md @@ -1,9 +1,10 @@ # Verify an AI-Generated Agent PR -Agents Shipgate is the local-first, static Tool-Use Readiness release gate for -AI agent tool surfaces. Built for AI coding workflows: when Claude Code, Codex, -Cursor, or a human changes an agent's tool access, Agents Shipgate turns the diff -into a deterministic merge verdict. +Agents Shipgate is the deterministic merge gate for AI-generated agent +capability changes — a local-first, static Tool-Use Readiness review. Built for +AI coding workflows: when Claude Code, Codex, Cursor, or a human changes an +agent's tool access, Agents Shipgate turns the diff into a deterministic merge +verdict. This page is the end-to-end use case for that workflow. For the deeper engineering rationale and roadmap, see diff --git a/llms-full.txt b/llms-full.txt index e4177684..26e12058 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -33,7 +33,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 @@ -56,9 +56,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/) ``. 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/) ``. 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 @@ -1897,8 +1897,9 @@ credential IDs may be preserved as local release evidence. # Concepts -The mental model behind Agents Shipgate, a local-first, static Tool-Use -Readiness release gate for AI agent tool surfaces. +The mental model behind Agents Shipgate, the deterministic merge gate for +AI-generated agent capability changes — a local-first, static Tool-Use +Readiness review. For the product-level definition of a Tool-Use Readiness release gate, see [`category.md`](category.md). For the agent-facing diff --git a/llms.txt b/llms.txt index 69e0c5ae..6c659919 100644 --- a/llms.txt +++ b/llms.txt @@ -1,6 +1,6 @@ # agents-shipgate -> Local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. CLI and GitHub Action. Apache-2.0. +> The deterministic merge gate for AI-generated agent capability changes. CLI and GitHub Action. Apache-2.0. ## Identity @@ -18,7 +18,7 @@ ## What it is -- Agents Shipgate is a 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. - Agents Shipgate reads `shipgate.yaml` plus declared local tool sources. - Agents Shipgate writes deterministic findings as Markdown, JSON, and SARIF. - Agents Shipgate fits the release-gate slot for tool-using AI agents. diff --git a/marketing/seo-geo-review.md b/marketing/seo-geo-review.md index 899372b1..e564806d 100644 --- a/marketing/seo-geo-review.md +++ b/marketing/seo-geo-review.md @@ -18,10 +18,10 @@ agent-readable README. The highest-return work is not broad SEO hygiene. It is tightening the category story around **agent release readiness** while keeping the product wedge narrow: **Tool-Use Readiness** for AI agent tool surfaces. -The current product promise should remain: +The current product promise is: -> Agents Shipgate is a 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. The market-facing expansion should be: diff --git a/prompts/add-shipgate-to-repo.md b/prompts/add-shipgate-to-repo.md index afa92503..9847a8bb 100644 --- a/prompts/add-shipgate-to-repo.md +++ b/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/pyproject.toml b/pyproject.toml index 4958d966..b5742e91 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "hatchling.build" [project] name = "agents-shipgate" version = "0.10.0" -description = "Local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. Agent release readiness for tool-using AI agents. CLI + GitHub Action. Scans MCP, OpenAPI, OpenAI Agents SDK, Anthropic, Google ADK, LangChain, CrewAI, OpenAI API, Codex plugin, n8n." +description = "The deterministic merge gate for AI-generated agent capability changes. Agent release readiness for tool-using AI agents. CLI + GitHub Action. Scans MCP, OpenAPI, OpenAI Agents SDK, Anthropic, Google ADK, LangChain, CrewAI, OpenAI API, Codex plugin, n8n." readme = "README.md" requires-python = ">=3.12" license = "Apache-2.0" diff --git a/samples/simple_crewai_agent/expected/report.md b/samples/simple_crewai_agent/expected/report.md index 54067c28..c71bb0dd 100644 --- a/samples/simple_crewai_agent/expected/report.md +++ b/samples/simple_crewai_agent/expected/report.md @@ -106,4 +106,4 @@ No findings. ## Disclaimer -Agents Shipgate is an advisory, local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. It does not certify agent safety or compliance. Findings are based on static configuration, declared policies, tool schemas, and optional SDK metadata. Runtime behavior, actual tool routing, and output interpretation are not verified. +Agents Shipgate is an advisory tool: the deterministic merge gate for AI-generated agent capability changes, run as a local-first, static Tool-Use Readiness review. It does not certify agent safety or compliance. Findings are based on static configuration, declared policies, tool schemas, and optional SDK metadata. Runtime behavior, actual tool routing, and output interpretation are not verified. diff --git a/samples/simple_langchain_agent/expected/report.md b/samples/simple_langchain_agent/expected/report.md index 529e84c9..8eb477f2 100644 --- a/samples/simple_langchain_agent/expected/report.md +++ b/samples/simple_langchain_agent/expected/report.md @@ -96,4 +96,4 @@ No findings. ## Disclaimer -Agents Shipgate is an advisory, local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. It does not certify agent safety or compliance. Findings are based on static configuration, declared policies, tool schemas, and optional SDK metadata. Runtime behavior, actual tool routing, and output interpretation are not verified. +Agents Shipgate is an advisory tool: the deterministic merge gate for AI-generated agent capability changes, run as a local-first, static Tool-Use Readiness review. It does not certify agent safety or compliance. Findings are based on static configuration, declared policies, tool schemas, and optional SDK metadata. Runtime behavior, actual tool routing, and output interpretation are not verified. diff --git a/samples/simple_openai_api_agent/expected/report.md b/samples/simple_openai_api_agent/expected/report.md index cf3cc7dd..2062299f 100644 --- a/samples/simple_openai_api_agent/expected/report.md +++ b/samples/simple_openai_api_agent/expected/report.md @@ -219,4 +219,4 @@ Next validation: ## Disclaimer -Agents Shipgate is an advisory, local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. It does not certify agent safety or compliance. Findings are based on static configuration, declared policies, tool schemas, and optional SDK metadata. Runtime behavior, actual tool routing, and output interpretation are not verified. +Agents Shipgate is an advisory tool: the deterministic merge gate for AI-generated agent capability changes, run as a local-first, static Tool-Use Readiness review. It does not certify agent safety or compliance. Findings are based on static configuration, declared policies, tool schemas, and optional SDK metadata. Runtime behavior, actual tool routing, and output interpretation are not verified. diff --git a/samples/support_refund_agent/expected/packet.html b/samples/support_refund_agent/expected/packet.html index 35b2f947..098e9f04 100644 --- a/samples/support_refund_agent/expected/packet.html +++ b/samples/support_refund_agent/expected/packet.html @@ -26,4 +26,4 @@ .status-missing { color: #7f1d1d; } .status-informational { color: #555; } .meta { color: #555; font-size: 0.92rem; } -

Release Evidence Packet

Project: support-refund-agent · Agent: refund-assistant · Environment: production_like
Run id: agents_shipgate_ebb71d7248235cc3 · Generated at: 2026-01-01T00:00:00+00:00 · Packet schema: 0.6

This packet is a reviewer-shaped synthesis of a static Agents Shipgate scan. See §10 for what the packet does not prove.

§1 Release decision — BLOCKED

CI gate behavior (informational)

Blockers

Review items

§1A Evidence matrix — compact review summary

DomainEvidence presentEvidence sourceConfidenceMissing controlsBlocking findingsReview items
Inventorypartialtool_inventory; tool_surface; +2 morehighSHIP-INVENTORY-WILDCARD-TOOLS on wildcard_mcp_tools.*: Wildcard tool exposure declared—SHIP-INVENTORY-WILDCARD-TOOLS (high)
Schemapartialtool_surface_facts.tools[].hashes; findings[]mixedSHIP-SCHEMA-MISSING-BOUNDS on stripe.create_refund: stripe.create_refund.amount has no maximum bound; SHIP-SCHEMA-BROAD-FREE-TEXT on zendesk.update_ticket: zendesk.update_ticket accepts broad free-form action input; +2 more—SHIP-SCHEMA-MISSING-BOUNDS (high); SHIP-SCHEMA-BROAD-FREE-TEXT (high); +2 more
Authpartialtool_surface_facts.scopes; tool_inventory[].auth_scopes; +1 moremixedSHIP-AUTH-MANIFEST-BROAD-SCOPE: Manifest declares broad permission scopes; SHIP-AUTH-SCOPE-COVERAGE-MISSING on shopify.cancel_order: shopify.cancel_order requires scopes not declared in the manifest; +3 more—SHIP-AUTH-MANIFEST-BROAD-SCOPE (high); SHIP-AUTH-SCOPE-COVERAGE-MISSING (high); +3 more
Approvalpartialtool_surface_facts.controls[kind=approval_policy]; findings[]highSHIP-POLICY-APPROVAL-MISSING on stripe.create_refund: stripe.create_refund lacks a declared approval policySHIP-POLICY-APPROVAL-MISSING (critical)—
Confirmationpartialtool_surface_facts.controls[kind=confirmation_policy]; findings[]highSHIP-POLICY-CONFIRMATION-MISSING on stripe.create_refund: stripe.create_refund lacks a declared confirmation policy; SHIP-POLICY-CONFIRMATION-MISSING on gmail.send_customer_email: gmail.send_customer_email lacks a declared confirmation policy—SHIP-POLICY-CONFIRMATION-MISSING (high); SHIP-POLICY-CONFIRMATION-MISSING (high)
Idempotencypartialtool_surface_facts.controls[kind=idempotency_evidence]; action_surface_facts.actions[].safeguards.idempotency; +1 moremixedSHIP-SIDEFX-IDEMPOTENCY-MISSING on stripe.create_refund: stripe.create_refund lacks idempotency evidence; SHIP-SIDEFX-IDEMPOTENCY-MISSING on gmail.send_customer_email: gmail.send_customer_email lacks idempotency evidenceSHIP-SIDEFX-IDEMPOTENCY-MISSING (critical)SHIP-SIDEFX-IDEMPOTENCY-MISSING (high)
Side effectspartialtool_inventory[].risk_tags; action_surface_facts.actions[].effect; +1 moremixedSHIP-SCHEMA-BROAD-FREE-TEXT on zendesk.update_ticket: zendesk.update_ticket accepts broad free-form action input; SHIP-SCHEMA-BROAD-FREE-TEXT on gmail.send_customer_email: gmail.send_customer_email accepts broad free-form action input; +5 moreSHIP-POLICY-APPROVAL-MISSING (critical); SHIP-SIDEFX-IDEMPOTENCY-MISSING (critical)SHIP-SCHEMA-BROAD-FREE-TEXT (high); SHIP-SCHEMA-BROAD-FREE-TEXT (high); +3 more
Memory isolationnot_declared—unknown———
Human-in-the-loop evidencenot_declared—unknown———
Prompt/scope alignmentpartialdeclared_intentions; misalignments; +2 moremediumSHIP-SCOPE-PROHIBITED-TOOL-PRESENT on stripe.create_refund: stripe.create_refund appears to overlap with a prohibited action; SHIP-SCOPE-PROHIBITED-TOOL-PRESENT on gmail.send_customer_email: gmail.send_customer_email appears to overlap with a prohibited action—SHIP-SCOPE-PROHIBITED-TOOL-PRESENT (high); SHIP-SCOPE-PROHIBITED-TOOL-PRESENT (high)
Retry/timeoutnot_declared—unknown———
Baseline debtinformational—unknown———
Action-surface policycoveredaction_surface_facts.actionsmedium———

§2 Capability ↔ Intent diff — missing

Declared

Observed tools

Divergences

§3 High-risk tool surface — partial

Total tools: 8 · High-risk: 3

ToolSourceRisk tagsApprovalIdempotency
gmail.send_customer_emailmcpcustomer_communication, external_writenono
shopify.cancel_orderopenapidestructive, writeyesyes
stripe.create_refundopenapiexternal_write, financial_action, writenono

§3A Tool-surface diff — not declared

Status: disabled — No --diff-from report or v0.3 baseline snapshot was provided.
Base: none

§3B Action-surface diff — not declared

Status: disabled — No action-surface comparison source was provided.
Base: none

§4 Approval policy coverage — partial

ToolDeclaredSourceGap finding(s)
shopify.cancel_orderyespolicies—
stripe.create_refundno—fp_f092940f62fbb012

Gap findings

§5 Idempotency / retry risk — partial

Retry policy: not declared

ToolDeclaredSourceGap finding(s)
gmail.send_customer_emailno—fp_0f8aaa912d589cf0
shopify.cancel_orderyespolicies—
stripe.create_refundno—fp_dac8011e14c53777

Gap findings

§6 Scope coverage — missing

Declared scopes

ScopeDeclaredUsed by tools
gmail:sendnogmail.send_customer_email
shopify:orders:writenoshopify.cancel_order
stripe:*yes—
stripe:refunds:writeyesstripe.create_refund
support:kb:readnosupport.search_kb
zendesk:tickets:readyes—
zendesk:tickets:writeyeszendesk.update_ticket

Unused declared scopes

Used by tools but not declared

Gap findings

§7 Memory isolation — not declared

Manifest does not declare a memory isolation policy. The current manifest schema (v0.1) has no agent.memory field. See §10 for the residual review item.

§8 Human-in-the-loop evidence — covered

Approval-required tools

Confirmation-required tools

§9 Required dynamic scenarios — partial

§10 What this packet did NOT prove

Agents Shipgate is an advisory, local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. The packet below is derived from a scan; it does not, by itself, prove the following properties:

Per-run residuals

+

Release Evidence Packet

Project: support-refund-agent · Agent: refund-assistant · Environment: production_like
Run id: agents_shipgate_ebb71d7248235cc3 · Generated at: 2026-01-01T00:00:00+00:00 · Packet schema: 0.6

This packet is a reviewer-shaped synthesis of a static Agents Shipgate scan. See §10 for what the packet does not prove.

§1 Release decision — BLOCKED

CI gate behavior (informational)

Blockers

Review items

§1A Evidence matrix — compact review summary

DomainEvidence presentEvidence sourceConfidenceMissing controlsBlocking findingsReview items
Inventorypartialtool_inventory; tool_surface; +2 morehighSHIP-INVENTORY-WILDCARD-TOOLS on wildcard_mcp_tools.*: Wildcard tool exposure declared—SHIP-INVENTORY-WILDCARD-TOOLS (high)
Schemapartialtool_surface_facts.tools[].hashes; findings[]mixedSHIP-SCHEMA-MISSING-BOUNDS on stripe.create_refund: stripe.create_refund.amount has no maximum bound; SHIP-SCHEMA-BROAD-FREE-TEXT on zendesk.update_ticket: zendesk.update_ticket accepts broad free-form action input; +2 more—SHIP-SCHEMA-MISSING-BOUNDS (high); SHIP-SCHEMA-BROAD-FREE-TEXT (high); +2 more
Authpartialtool_surface_facts.scopes; tool_inventory[].auth_scopes; +1 moremixedSHIP-AUTH-MANIFEST-BROAD-SCOPE: Manifest declares broad permission scopes; SHIP-AUTH-SCOPE-COVERAGE-MISSING on shopify.cancel_order: shopify.cancel_order requires scopes not declared in the manifest; +3 more—SHIP-AUTH-MANIFEST-BROAD-SCOPE (high); SHIP-AUTH-SCOPE-COVERAGE-MISSING (high); +3 more
Approvalpartialtool_surface_facts.controls[kind=approval_policy]; findings[]highSHIP-POLICY-APPROVAL-MISSING on stripe.create_refund: stripe.create_refund lacks a declared approval policySHIP-POLICY-APPROVAL-MISSING (critical)—
Confirmationpartialtool_surface_facts.controls[kind=confirmation_policy]; findings[]highSHIP-POLICY-CONFIRMATION-MISSING on stripe.create_refund: stripe.create_refund lacks a declared confirmation policy; SHIP-POLICY-CONFIRMATION-MISSING on gmail.send_customer_email: gmail.send_customer_email lacks a declared confirmation policy—SHIP-POLICY-CONFIRMATION-MISSING (high); SHIP-POLICY-CONFIRMATION-MISSING (high)
Idempotencypartialtool_surface_facts.controls[kind=idempotency_evidence]; action_surface_facts.actions[].safeguards.idempotency; +1 moremixedSHIP-SIDEFX-IDEMPOTENCY-MISSING on stripe.create_refund: stripe.create_refund lacks idempotency evidence; SHIP-SIDEFX-IDEMPOTENCY-MISSING on gmail.send_customer_email: gmail.send_customer_email lacks idempotency evidenceSHIP-SIDEFX-IDEMPOTENCY-MISSING (critical)SHIP-SIDEFX-IDEMPOTENCY-MISSING (high)
Side effectspartialtool_inventory[].risk_tags; action_surface_facts.actions[].effect; +1 moremixedSHIP-SCHEMA-BROAD-FREE-TEXT on zendesk.update_ticket: zendesk.update_ticket accepts broad free-form action input; SHIP-SCHEMA-BROAD-FREE-TEXT on gmail.send_customer_email: gmail.send_customer_email accepts broad free-form action input; +5 moreSHIP-POLICY-APPROVAL-MISSING (critical); SHIP-SIDEFX-IDEMPOTENCY-MISSING (critical)SHIP-SCHEMA-BROAD-FREE-TEXT (high); SHIP-SCHEMA-BROAD-FREE-TEXT (high); +3 more
Memory isolationnot_declared—unknown———
Human-in-the-loop evidencenot_declared—unknown———
Prompt/scope alignmentpartialdeclared_intentions; misalignments; +2 moremediumSHIP-SCOPE-PROHIBITED-TOOL-PRESENT on stripe.create_refund: stripe.create_refund appears to overlap with a prohibited action; SHIP-SCOPE-PROHIBITED-TOOL-PRESENT on gmail.send_customer_email: gmail.send_customer_email appears to overlap with a prohibited action—SHIP-SCOPE-PROHIBITED-TOOL-PRESENT (high); SHIP-SCOPE-PROHIBITED-TOOL-PRESENT (high)
Retry/timeoutnot_declared—unknown———
Baseline debtinformational—unknown———
Action-surface policycoveredaction_surface_facts.actionsmedium———

§2 Capability ↔ Intent diff — missing

Declared

Observed tools

Divergences

§3 High-risk tool surface — partial

Total tools: 8 · High-risk: 3

ToolSourceRisk tagsApprovalIdempotency
gmail.send_customer_emailmcpcustomer_communication, external_writenono
shopify.cancel_orderopenapidestructive, writeyesyes
stripe.create_refundopenapiexternal_write, financial_action, writenono

§3A Tool-surface diff — not declared

Status: disabled — No --diff-from report or v0.3 baseline snapshot was provided.
Base: none

§3B Action-surface diff — not declared

Status: disabled — No action-surface comparison source was provided.
Base: none

§4 Approval policy coverage — partial

ToolDeclaredSourceGap finding(s)
shopify.cancel_orderyespolicies—
stripe.create_refundno—fp_f092940f62fbb012

Gap findings

§5 Idempotency / retry risk — partial

Retry policy: not declared

ToolDeclaredSourceGap finding(s)
gmail.send_customer_emailno—fp_0f8aaa912d589cf0
shopify.cancel_orderyespolicies—
stripe.create_refundno—fp_dac8011e14c53777

Gap findings

§6 Scope coverage — missing

Declared scopes

ScopeDeclaredUsed by tools
gmail:sendnogmail.send_customer_email
shopify:orders:writenoshopify.cancel_order
stripe:*yes—
stripe:refunds:writeyesstripe.create_refund
support:kb:readnosupport.search_kb
zendesk:tickets:readyes—
zendesk:tickets:writeyeszendesk.update_ticket

Unused declared scopes

Used by tools but not declared

Gap findings

§7 Memory isolation — not declared

Manifest does not declare a memory isolation policy. The current manifest schema (v0.1) has no agent.memory field. See §10 for the residual review item.

§8 Human-in-the-loop evidence — covered

Approval-required tools

Confirmation-required tools

§9 Required dynamic scenarios — partial

§10 What this packet did NOT prove

Agents Shipgate is an advisory tool: the deterministic merge gate for AI-generated agent capability changes, run as a local-first, static Tool-Use Readiness review. The packet below is derived from a scan; it does not, by itself, prove the following properties:

Per-run residuals

diff --git a/samples/support_refund_agent/expected/packet.json b/samples/support_refund_agent/expected/packet.json index 94c50adc..a9557958 100644 --- a/samples/support_refund_agent/expected/packet.json +++ b/samples/support_refund_agent/expected/packet.json @@ -1292,7 +1292,7 @@ "Memory isolation is not modeled by the v0.1 manifest schema; no static evidence is available.", "6 active finding(s) came from heuristic provenance (keyword_heuristic=6, regex_heuristic=0); review the finding evidence before acting." ], - "headline": "Agents Shipgate is an advisory, local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. The packet below is derived from a scan; it does not, by itself, prove the following properties:", + "headline": "Agents Shipgate is an advisory tool: the deterministic merge gate for AI-generated agent capability changes, run as a local-first, static Tool-Use Readiness review. The packet below is derived from a scan; it does not, by itself, prove the following properties:", "low_confidence_tools": [], "source_warnings": [ "MCP source declares wildcard tool exposure" diff --git a/samples/support_refund_agent/expected/packet.md b/samples/support_refund_agent/expected/packet.md index 46d10dc7..07665195 100644 --- a/samples/support_refund_agent/expected/packet.md +++ b/samples/support_refund_agent/expected/packet.md @@ -223,7 +223,7 @@ This packet is a reviewer-shaped synthesis of a static Agents Shipgate scan. See ## §10 What this packet did NOT prove -Agents Shipgate is an advisory, local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. The packet below is derived from a scan; it does not, by itself, prove the following properties: +Agents Shipgate is an advisory tool: the deterministic merge gate for AI-generated agent capability changes, run as a local-first, static Tool-Use Readiness review. The packet below is derived from a scan; it does not, by itself, prove the following properties: - **Prompt robustness.** Whether the agent's prompt holds up under jailbreaks, persona drift, indirect prompt injection, or adversarial inputs. - **Runtime behavior.** Whether the agent actually invokes only the declared tools, respects approval gates at runtime, or follows policy under load. Static config is not runtime evidence. diff --git a/samples/support_refund_agent/expected/report.md b/samples/support_refund_agent/expected/report.md index 7bd41f71..10415fd5 100644 --- a/samples/support_refund_agent/expected/report.md +++ b/samples/support_refund_agent/expected/report.md @@ -225,4 +225,4 @@ Next validation: ## Disclaimer -Agents Shipgate is an advisory, local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. It does not certify agent safety or compliance. Findings are based on static configuration, declared policies, tool schemas, and optional SDK metadata. Runtime behavior, actual tool routing, and output interpretation are not verified. +Agents Shipgate is an advisory tool: the deterministic merge gate for AI-generated agent capability changes, run as a local-first, static Tool-Use Readiness review. It does not certify agent safety or compliance. Findings are based on static configuration, declared policies, tool schemas, and optional SDK metadata. Runtime behavior, actual tool routing, and output interpretation are not verified. diff --git a/skills/agents-shipgate/SKILL.md b/skills/agents-shipgate/SKILL.md index 94451e92..bb5e334a 100644 --- a/skills/agents-shipgate/SKILL.md +++ b/skills/agents-shipgate/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/skills/agents-shipgate/prompts/add-shipgate-to-repo.md b/skills/agents-shipgate/prompts/add-shipgate-to-repo.md index afa92503..9847a8bb 100644 --- a/skills/agents-shipgate/prompts/add-shipgate-to-repo.md +++ b/skills/agents-shipgate/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/src/agents_shipgate/cli/_register_scan.py b/src/agents_shipgate/cli/_register_scan.py index bc6de3df..5f66aca4 100644 --- a/src/agents_shipgate/cli/_register_scan.py +++ b/src/agents_shipgate/cli/_register_scan.py @@ -181,7 +181,7 @@ def scan( ), verbose: bool = typer.Option(False, "--verbose", help="Show debug extraction details."), ) -> None: - """Run the local-first, static Tool-Use Readiness release gate for AI agent tool surfaces.""" + """Run the deterministic merge gate for AI-generated agent capability changes.""" # Parse CLI options first, in their own try block. ConfigError raised # here is about flag values, not the manifest — emitting a manifest # diagnostic ("edit shipgate.yaml") would route the agent to the diff --git a/src/agents_shipgate/cli/discovery/agent_instructions/renderers/agents_md.py b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/agents_md.py index 93fe1a51..c54ab9f8 100644 --- a/src/agents_shipgate/cli/discovery/agent_instructions/renderers/agents_md.py +++ b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/agents_md.py @@ -15,8 +15,8 @@ def render_block() -> str: """Return the inner content (between markers) for AGENTS.md.""" return f"""## 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/src/agents_shipgate/cli/discovery/agent_instructions/renderers/claude_md.py b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/claude_md.py index 47a350db..49083154 100644 --- a/src/agents_shipgate/cli/discovery/agent_instructions/renderers/claude_md.py +++ b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/claude_md.py @@ -16,8 +16,8 @@ def render_block() -> str: """Return the inner content (between markers) for CLAUDE.md.""" return f"""## Agents Shipgate -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. For agent tool-surface or release-policy changes, run: diff --git a/src/agents_shipgate/cli/discovery/agent_instructions/renderers/cursor.py b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/cursor.py index d2ce74bb..54b78220 100644 --- a/src/agents_shipgate/cli/discovery/agent_instructions/renderers/cursor.py +++ b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/cursor.py @@ -15,7 +15,7 @@ def render_file() -> str: """Return the full file body for ``.cursor/rules/agents-shipgate.mdc``.""" return """--- -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" @@ -44,8 +44,8 @@ def render_file() -> str: 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/src/agents_shipgate/cli/discovery/agent_instructions/renderers/pr_template.py b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/pr_template.py index 3e04108c..6348aa40 100644 --- a/src/agents_shipgate/cli/discovery/agent_instructions/renderers/pr_template.py +++ b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/pr_template.py @@ -12,8 +12,8 @@ def render_block() -> str: """Return the inner content (between markers) for the PR template.""" return """## Tool-Use Readiness Release Gate -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. - [ ] If this PR changes agent tools, MCP/OpenAPI specs, prompts, permissions, approval policy, confirmation policy, CI release gates, or diff --git a/src/agents_shipgate/cli/main.py b/src/agents_shipgate/cli/main.py index b118e5a4..0773b18d 100644 --- a/src/agents_shipgate/cli/main.py +++ b/src/agents_shipgate/cli/main.py @@ -29,7 +29,7 @@ app = typer.Typer( name="agents-shipgate", - help="Local-first, static Tool-Use Readiness release gate for AI agent tool surfaces.", + help="The deterministic merge gate for AI-generated agent capability changes.", no_args_is_help=True, invoke_without_command=True, ) diff --git a/src/agents_shipgate/packet/disclaimer.py b/src/agents_shipgate/packet/disclaimer.py index 9144d6ec..87113fed 100644 --- a/src/agents_shipgate/packet/disclaimer.py +++ b/src/agents_shipgate/packet/disclaimer.py @@ -14,8 +14,9 @@ HITL_RUNTIME_CONTROL_DISCLAIMER = _HITL_RUNTIME_CONTROL_DISCLAIMER PACKET_NON_PROOF_HEADLINE = ( - "Agents Shipgate is an advisory, local-first, static Tool-Use Readiness " - "release gate for AI agent tool surfaces. The packet below is derived from " + "Agents Shipgate is an advisory tool: the deterministic merge gate for " + "AI-generated agent capability changes, run as a local-first, static " + "Tool-Use Readiness review. The packet below is derived from " "a scan; it does not, by itself, prove the following properties:" ) diff --git a/src/agents_shipgate/report/markdown.py b/src/agents_shipgate/report/markdown.py index f93468ff..f40984b2 100644 --- a/src/agents_shipgate/report/markdown.py +++ b/src/agents_shipgate/report/markdown.py @@ -20,8 +20,9 @@ ) DISCLAIMER = ( - "Agents Shipgate is an advisory, local-first, static Tool-Use Readiness " - "release gate for AI agent tool surfaces. It does not certify agent safety " + "Agents Shipgate is an advisory tool: the deterministic merge gate for " + "AI-generated agent capability changes, run as a local-first, static " + "Tool-Use Readiness review. It does not certify agent safety " "or compliance. Findings are based on static configuration, declared policies, " "tool schemas, and optional SDK metadata. Runtime behavior, actual tool routing, " "and output interpretation are not verified." diff --git a/tests/test_agent_instructions_renderers.py b/tests/test_agent_instructions_renderers.py index 35a1be1e..66e617e1 100644 --- a/tests/test_agent_instructions_renderers.py +++ b/tests/test_agent_instructions_renderers.py @@ -40,10 +40,10 @@ REPO_ROOT = Path(__file__).resolve().parent.parent EXPECTED_CLAUDE_CODE_SKILL_RENDER_SHA256 = { ".claude/skills/agents-shipgate/SKILL.md": ( - "9ce82bdc41f2e1ea28c7fec3aaeec0137efeacf8986b66a9ac0e3eccc5abd834" + "e1713eecbbb1538987b7bf2cbe90bcdac9c4491f250105b6c68e788c81d49de3" ), ".claude/skills/agents-shipgate/prompts/add-shipgate-to-repo.md": ( - "1ea69b1d3d418080c76540fff3b20044f70ed6787418eb5e4d3d39e036b34014" + "c19c03db48a5be3b002b385f9df09781e5fe32197d0dd924691f041ebe54d518" ), ".claude/skills/agents-shipgate/prompts/decide-shipgate-relevance.md": ( "8fab0595326b127fb1678828fd9b15c63cbe98f0229aad5bb87d47030e4b9ca6" @@ -75,7 +75,7 @@ } EXPECTED_CODEX_SKILL_RENDER_SHA256 = { ".agents/skills/agents-shipgate/SKILL.md": ( - "367ef145ef928912cc517149e61b0efe413e740680787ef13441a6abd55b4647" + "bfd89761a2266ab89bc686a85fdd7700b0b915d5a8b133fafae16bb758d3272e" ), ".agents/skills/agents-shipgate/references/recipes.md": ( "b5d90a1b02ebcc5bbc1c25015722508bc6d1ffde4bf28a470df88bb195c56aec" diff --git a/tests/test_docs_links.py b/tests/test_docs_links.py index edfd59e8..adfa8fff 100644 --- a/tests/test_docs_links.py +++ b/tests/test_docs_links.py @@ -206,7 +206,7 @@ def test_target_repo_snippets_pin_advisory_agent_contract(): def test_readme_onboarding_copy_pins_agent_contract(): text = (REPO_ROOT / "README.md").read_text(encoding="utf-8") - assert "Local-first, static Tool-Use Readiness release gate" in text + assert "The deterministic merge gate for AI-generated agent capability changes" in text assert "5-minute" in text assert "Copy this into your coding agent" in text assert "https://github.com/marketplace/actions/agents-shipgate" in text diff --git a/tests/test_public_surface_contract.py b/tests/test_public_surface_contract.py index 4ea59fa9..1ca96fbf 100644 --- a/tests/test_public_surface_contract.py +++ b/tests/test_public_surface_contract.py @@ -128,12 +128,10 @@ re.IGNORECASE, ) POSITIONING_PHRASE = ( - "Local-first, static Tool-Use Readiness release gate for " - "AI agent tool surfaces" + "The deterministic merge gate for AI-generated agent capability changes" ) POSITIONING_SCAN_DOCSTRING = ( - "local-first, static Tool-Use Readiness release gate for " - "AI agent tool surfaces" + "the deterministic merge gate for AI-generated agent capability changes" ) POSITIONING_SURFACES = ( "README.md", @@ -1442,8 +1440,8 @@ def test_primary_surfaces_use_mvp_wedge_positioning(relpath): def test_scan_help_uses_tool_use_readiness_positioning(): text = _normalize_ws(_read("src/agents_shipgate/cli/_register_scan.py")) assert POSITIONING_SCAN_DOCSTRING.lower() in text.lower(), ( - "scan command docstring must use the local-first, static Tool-Use " - "Readiness release gate positioning." + "scan command docstring must use the canonical merge-gate " + "positioning phrase." )