Skip to content
Back to search

agents-shipgate

Agents Shipgate — the deterministic merge gate for AI-generated agent capability changes. Review PR changes to declared coding-agent permissions, MCP bindings, hooks and workflow permissions with the agents-shipgate diff CLI command (not routed by the plugin's skill, which covers check, verify and audit --host). This static host comparison needs no manifest, policy, saved baseline or skill; it names coverage limits and implies no verdict. Optional workflow instructions use the agents-shipgate CLI installed locally.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ThreeMoonsLab/agents-shipgate with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ThreeMoonsLab/agents-shipgate'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/threemoonslab--agents-shipgate/badge.svg)](/listings/threemoonslab--agents-shipgate)

HTML

<a href="/listings/threemoonslab--agents-shipgate"><img src="/api/listings/threemoonslab--agents-shipgate/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pipx install agents-shipgate

`pipx upgrade agents-shipgate` refreshes a stale copy; a plain install is a no-op over one. Alternatives — `pip`, `uv`, and zero-install `uvx` — are in [`docs/quickstart.md`](docs/quickstart.md#install). Your agent project does **not** need Python 3.12; the CLI installs separately.

**Two lines, two promises.** The advisory line publishes rows a reviewer reads, and no authority to block anything by default; `v1.2.0` is an advisory release. The gate line publishes blocking verdicts and keeps every qualification bar. Each `v*` version is declared on exactly one line in [`.github/release-channels.json`](.github/release-channels.json). Neither line waits on the other, and [`docs/release-cadence`](docs/distribution.md#package-channels) measures both separately — one number could not have shown that the documented workflow was two months out of reach.

| Line | Carries | Install | Promises | Cadence | | --- | --- | --- | --- | --- | | **Advisory** | `diff`, `check`, `audit --host`, drift, advisory PR comments | `pipx install agents-shipgate` (`v1.2.0`), or an unqualified preview pre-release | plain-language capability rows; **no blocking authority** unless you configure a blocking policy | 14 days | | **Qualified gate** | blocking verdicts backed by qualification evidence, receipts, attestations | a `v*` release declared on the qualified line; `v1.2.0` is not one | every bar in [`release-evidence-policy-decision.md`](docs/release-evidence-policy-decision.md) | on evidence only |

**Read [which build you get](docs/quickstart.md#which-build-you-get) before you start.** The newest published release is `v1.2.0`, which implements runtime contract `41` — the agent control envelope, `current-control.json` and `--format agent-boundary-json` included — and is what `pipx install agents-shipgate` installs. It ships on the advisory channel and makes no qualification claim. The quickstart says what an older `v1.1.0`, `v1.0.0` or `v0.15.0` install lacks, and what the unqualified preview does and does not come with.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 36 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "agents-shipgate",
  3. "owner": {
  4. "name": "Three Moons Lab",
  5. "email": "help@threemoonslab.com"
  6. },
  7. "description": "Agents Shipgate — the deterministic merge gate for AI-generated agent capability changes. Review PR changes to declared coding-agent permissions, MCP bindings, hooks and workflow permissions with the agents-shipgate diff CLI command (not routed by the plugin's skill, which covers check, verify and audit --host). This static host comparison needs no manifest, policy, saved baseline or skill; it names coverage limits and implies no verdict. Optional workflow instructions use the agents-shipgate CLI installed locally.",
  8. "plugins": [
  9. {
  10. "name": "agents-shipgate",
  11. "source": "./plugins/claude-code",
  12. "description": "Review PR changes to declared coding-agent permissions, MCP bindings, hooks and workflow permissions with the agents-shipgate diff CLI command (not routed by the plugin's skill, which covers check, verify and audit --host). This static host comparison needs no manifest, policy, saved baseline or skill; it names coverage limits and implies no verdict. Tool-Use Readiness release verification is a separate workflow for repositories with a declared tool surface. Requires the agents-shipgate CLI (pipx install agents-shipgate); no hook is enabled by this metadata.",
  13. "version": "1.3.0",
  14. "author": {
  15. "name": "Three Moons Lab",
  16. "url": "https://threemoonslab.com/"
  17. },
  18. "homepage": "https://threemoonslab.com/",
  19. "repository": "https://github.com/ThreeMoonsLab/agents-shipgate",
  20. "license": "Apache-2.0",
  21. "keywords": [
  22. "agents",
  23. "claude-code",
  24. "tool-use-readiness",
  25. "release-gate",
  26. "mcp-security",
  27. "policy-as-code",
  28. "coding-agent-config",
  29. "permission-changes",
  30. "workflow-permissions"
  31. ],
  32. "category": "security",
  33. "strict": true
  34. }
  35. ]
  36. }
README.md · README · 583 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="assets/readme-header-dark.png">
  4. <img src="assets/readme-header.png" alt="Agents Shipgate · the deterministic merge gate for AI-generated agent capability changes" width="100%">
  5. </picture>
  6. </p>
  7. # Agents Shipgate
  8. [![PyPI](https://img.shields.io/pypi/v/agents-shipgate)](https://pypi.org/project/agents-shipgate/)
  9. [![Python](https://img.shields.io/pypi/pyversions/agents-shipgate)](https://pypi.org/project/agents-shipgate/)
  10. [![GitHub Action](https://img.shields.io/badge/GitHub%20Action-marketplace-blue)](https://github.com/marketplace/actions/agents-shipgate)
  11. [![License](https://img.shields.io/pypi/l/agents-shipgate)](LICENSE)
  12. [![CI](https://github.com/ThreeMoonsLab/agents-shipgate/actions/workflows/ci.yml/badge.svg)](https://github.com/ThreeMoonsLab/agents-shipgate/actions/workflows/ci.yml)
  13. **Your coding agent changed what your AI agent can do — Agents Shipgate shows you what changed before it merges.**
  14. **The deterministic merge gate for AI-generated agent capability changes.**
  15. Local-first and static by default — no agent execution, tool calls, LLM calls, or network access.
  16. <!-- Canonical tagline: The deterministic merge gate for AI-generated agent capability changes. -->
  17. Agents Shipgate is an open-source CLI and GitHub Action for local-first, static
  18. Tool-Use Readiness review. It scans MCP, OpenAPI, OpenAI Agents SDK, Anthropic
  19. Messages API, Google ADK, LangChain/LangGraph, CrewAI, OpenAI API, Codex repo
  20. config, Codex plugin, n8n, and Conductor OSS workflow artifacts, then writes a
  21. deterministic **Tool-Use Readiness Report** before your agent gets
  22. production-like permissions.
  23. ## Application agent PRs without setup
  24. The source build can compare OpenAI Agents SDK and Google ADK tool bindings
  25. without a manifest or baseline:
  26. ```bash
  27. agents-shipgate diff --application --workspace /path/to/repo --base BASE_SHA --head HEAD_SHA
  28. ```
  29. It shows source-observed changes per agent, including before/after signatures
  30. and source locations, in the package that holds the changed code's agents unless
  31. `--scope` names one. See [application comparison](docs/application-comparison.md)
  32. for scoped applications, moves, exact refs and coverage limits. Version availability
  33. is recorded in the [CHANGELOG entry](CHANGELOG.md#application-comparison-without-prior-setup):
  34. it is new in 1.2.0, and the newest published release, 1.3.0, has it, so an
  35. install older than 1.2.0 needs `pipx upgrade agents-shipgate` first.
  36. ## What did this PR change?
  37. Start with a pull request you already have that changes what a coding agent
  38. may do: `.claude/settings.json`, `.mcp.json`, Codex, Cursor or VS Code MCP
  39. configuration. No manifest, policy, saved baseline, skill or account is
  40. needed, and nothing is written to your repository. From the PR branch, with its
  41. base branch available in your clone:
  42. ```bash
  43. pipx install agents-shipgate
  44. agents-shipgate diff
  45. ```
  46. `diff` compares your working tree with its merge base on the repository's
  47. default branch (`origin/HEAD`, `origin/main` or `origin/master`) and prints one
  48. entry per changed grant or replaced rule. If the PR targets another branch, pass
  49. `--base origin/<that-branch>`; in a fork clone, fetch `upstream` and pass
  50. `--base upstream/<pr-base>`. On a PR that widens a Claude Code allow rule,
  51. drops a denial and adds an MCP server:
  52. The example below is from this source tree, run in a clone, and is
  53. **not yet released**: the published `1.3.0` prints the same comparison, but
  54. rates the removed `deny: Bash(rm -rf:*)` row `low`, the rating it gives every
  55. deny and ask grant. This tree rates a row that lifts a deny or ask rule by what
  56. the rule restricted, never below `medium` (#1036).
  57. ```text
  58. Agent capability diff origin/main (3db015cd) -> working tree
  59. ⚠ high added claude-code .mcp.json
  60. billing (command name npx; env keys BILLING_TOKEN)
  61. an MCP tool surface the agent may call has changed; package spec has no exact version; launch resolution not established: npx may resolve a local project dependency or fall back to the registry/cache
  62. ⚠ medium widened claude-code .claude/settings.json
  63. allow: Bash(npm test:*) → allow: Bash(npm *)
  64. the new rule matches everything the old rule matched; runs without a prompt
  65. ⚠ medium removed claude-code .claude/settings.json
  66. deny: Bash(rm -rf:*) → gone
  67. removes a denial the agent was subject to
  68. 3 change(s) from 4 rows, 3 widening what the agent may do (⚠).
  69. Static configuration only: this is what the files permit, not what the agent did. No verdict is implied.
  70. What this run established:
  71. only sources this entry read or tried to read are listed, so this is not the whole change: a changed file it does not read is absent
  72. .claude/settings.json (claude-code): compared; 3 rows
  73. .mcp.json (claude-code): compared; 1 row
  74. Review question: Does the team intend these 3 declared capability changes (from 4 rows)?
  75. Compared: base 3db015cd → working tree at HEAD 39a8a7b1, agents-shipgate 1.3.0.
  76. Reproduce in that working tree: agents-shipgate diff --base 3db015cd96dea7244dedd56309174e2998f5090d
  77. Permission review guidance:
  78. Conditional review choices only; current control permissions still apply. A PR note grants no authority.
  79. - Change 2: .claude/settings.json
  80. Question: Does this task need the command matches of Bash(npm *) beyond Bash(npm test:*)?
  81. Limit: These are repository declarations. Runtime access, credentials, other permission layers and task intent are not established.
  82. Choice: If intentional, record the rationale in the existing PR discussion; the declaration delta remains visible.
  83. Choice: If another scope is intended, the declaration owner chooses it at the named source. The previous value is a reference, not an automatically safe fix.
  84. Choice: If disputed, preserve the compared refs and evidence for triage; do not suppress the finding or rewrite policy to clear it.
  85. Advisory next actor: declaration owner to be assigned
  86. Verification: Compare the resulting declarations against the original base; a rerun establishes a declaration delta, not intent or runtime access.
  87. - Change 3: .claude/settings.json
  88. Question: Should this source remove the deny declaration Bash(rm -rf:*) for this task?
  89. Limit: These are repository declarations. Runtime access, credentials, other permission layers and task intent are not established.
  90. Choice: If intentional, record the rationale in the existing PR discussion; the declaration delta remains visible.
  91. Choice: If another scope is intended, the declaration owner chooses it at the named source. The previous value is a reference, not an automatically safe fix.
  92. Choice: If disputed, preserve the compared refs and evidence for triage; do not suppress the finding or rewrite policy to clear it.
  93. Advisory next actor: declaration owner to be assigned
  94. Verification: Compare the resulting declarations against the original base; a rerun establishes a declaration delta, not intent or runtime access.
  95. ```
  96. The answer is one of these, and they mean different things: named changes,
  97. like these; `No static host-grant changes detected.` when no compared grant
  98. differs and no settings file changed; `Changed, not compared: <file> (<keys>)`
  99. when a settings, MCP or hook file changed with no row, such as in a key this
  100. entry does not compare (#1027); or `Cannot compare against <base>: <reason>`
  101. when an input could not be read, which is an input limit and never a quiet
  102. pass. Any of the first three can open with `Not compared:` and a list of
  103. sources the change did not touch and `diff` could not read; nothing is claimed
  104. about those. Since `1.2.0` there is also a fifth answer, `Partial comparison
  105. against <base> …: <reason>`, where the only inputs it could not read are
  106. plugin directories whose references stop inside them: it names each one as
  107. `Not compared: <directory>`, shows the changes outside it, and says they are
  108. not the whole change. It is never a pass, and a partial answer with no entry
  109. is never a no-change answer. Every answer then
  110. says `What this run established`: which sources were compared and how many rows
  111. each gave, which changed with no compared grant changing (so a zero-row `env`
  112. or `apiKeyHelper` edit is not mistaken for no change: a file is unchanged only
  113. when its bytes are), which changed with no row attributed to them, which only
  114. one side read or published, and, when
  115. the comparison was refused, which source left an inventory incomplete. Since
  116. `1.2.0` it also names a changed input that a
  117. bounded, documented candidate list recognises but no reader of this entry
  118. reads — a plugin's `mcp.json`, a plugin manifest's `mcpServers`,
  119. `.cursor/hooks.json`, a nested `.claude/settings.json`, an external marketplace
  120. plugin source — as `added`, `removed` or `changed, not read by this entry`,
  121. with no row and no claim that a host loads it. Its
  122. first line says what it lists, so it is never the whole account of the
  123. change: any other changed file it does not read is absent. When more items are
  124. computed than it prints,
  125. it names how many it left out and that they rank below the ones it kept. The
  126. entries are for a reviewer to act on, not merge authority: each names the rule
  127. with its disposition, a replaced rule's before and after, and an MCP server's
  128. command name or redacted URL and key names, then one review question. Every
  129. answer, a zero-row one and a refusal included, names the compared commits
  130. and the command that reproduces the comparison. `--json` publishes the same entries,
  131. counters, question and command beside the rows, so a script and a reader
  132. describe one run the same way; a refused comparison is the exception, which
  133. publishes no `review` object at all, so those two lines have no JSON
  134. counterpart and a reader rebuilds the command from the `base_commit` published
  135. beside the refusal. The
  136. [quickstart](docs/quickstart.md#review-a-host-configuration-change) shows each
  137. answer, the `--base <ref>` recovery when no base can be detected, and the
  138. [surfaces `diff` does not read](docs/host-boundary-support.md#known-unread-surfaces).
  139. Supported shell changes then add conditional human choices. They establish no
  140. intent or runtime access and grant no authority. The note on the added server
  141. says its `npx` package spec has no exact version, and that the static read does
  142. not establish whether `npx` resolves a local project dependency or falls back to
  143. the registry or its cache, as [npm documents](https://docs.npmjs.com/cli/v11/commands/npm-exec#description);
  144. it changes neither the row's severity nor the widening count.
  145. When the answer is useful and you want it on every pull request, add
  146. [`examples/github-actions/14-host-only-advisory-pr.yml`](examples/github-actions/14-host-only-advisory-pr.yml):
  147. the same comparison as an advisory PR comment, with no manifest or saved
  148. baseline, and a failing job only for setup errors.
  149. ## One capability change, one verdict
  150. If your repository builds its own tool surface — MCP or OpenAPI exports,
  151. framework tool definitions — the same engine gates that too, with a manifest.
  152. A coding agent adds a refund tool to a support agent. The MCP export goes from
  153. one read-only tool to two, and the new one carries a wildcard Stripe scope:
  154. ```diff
  155. { "name": "support.search_kb",
  156. "annotations": { "readOnlyHint": true, "idempotentHint": true },
  157. "auth": { "type": "oauth2", "scopes": ["support:kb:read"] } },
  158. + { "name": "stripe.create_refund",
  159. + "annotations": { "readOnlyHint": false, "destructiveHint": true },
  160. + "auth": { "type": "oauth2", "scopes": ["stripe:*"] } }
  161. ```
  162. The diff looks fine to a human skimming it. The sample's base manifest was
  163. written ahead of it: `permissions.scopes` grants only `support:kb:read` and there
  164. is no approval policy, but `agent_bindings` already binds
  165. `stripe.create_refund` to the agent, and `action_surface` already declares it
  166. `destructive`, tagged `financial_action`, with the `stripe:*` scope — a
  167. reviewed declaration that stays dormant until the export adds the tool. That
  168. binding is what lets the gate name blockers. Without it, the same diff returns
  169. `insufficient_evidence` and asks a human to declare the tool's binding in
  170. `shipgate.yaml#agent_bindings`. Run the committed sample:
  171. ```bash
  172. uvx agents-shipgate fixture run ai_generated_refund_pr
  173. ```
  174. ```text
  175. Merge verdict: blocked
  176. Decision: blocked
  177. Can merge without human: false
  178. ```
  179. `report.md` names what changed and why it is held:
  180. ```text
  181. Decision: blocked
  182. Reason: 4 active findings block release.
  183. Blockers (4):
  184. - CRITICAL SHIP-POLICY-APPROVAL-MISSING — stripe.create_refund lacks a declared approval policy
  185. - CRITICAL SHIP-ACTION-DESTRUCTIVE-ROLLBACK-MISSING — stripe.create_refund has destructive capability without required controls
  186. - CRITICAL SHIP-ACTION-FINANCIAL-WRITE-CONTROL-MISSING — stripe.create_refund has financial write capability without required controls
  187. - CRITICAL SHIP-ACTION-WILDCARD-SCOPE — stripe.create_refund declares a broad action scope
  188. ```
  189. **The process exited zero.** In advisory mode `would_fail_ci=false`, and the
  190. change is still `blocked`. Exit status is a CI policy choice; the verdict is
  191. the answer. Teaching the two apart is the first thing
  192. [the quickstart](docs/quickstart.md) does.
  193. These excerpts are from a source checkout. For an older install, see
  194. [which build you get](docs/quickstart.md#which-build-you-get).
  195. Now the move every reviewer fears — the agent deletes the Shipgate CI gate so
  196. its own PR passes:
  197. ```bash
  198. uvx agents-shipgate fixture run agent_weakens_gate
  199. ```
  200. → `merge_verdict: blocked`, `can_merge_without_human: false`. The gate-removal
  201. checks are suppression-immune: the cheapest reward-hack is also the most
  202. visible one. More replayable incident shapes are in the
  203. [incident-shape suite](docs/incidents/README.md).
  204. One engine decides (`report.json.release_decision.decision`); everything else —
  205. `merge_verdict`, PR comments, Check Runs, Action outputs — is a deterministic
  206. projection of it. Five-minute version:
  207. [`docs/mental-model.md`](docs/mental-model.md).
  208. Host configuration alone needs none of this: [What did this PR
  209. change?](#what-did-this-pr-change) is the whole route. [Route
  210. H](docs/quickstart.md#route-h--no-manifest) adds a snapshot audit and an
  211. optional committed baseline for jobs that want them, and `v1.3.0`'s discovery
  212. routes host-only repositories there through `host_boundary_candidates`.
  213. Filename detection never establishes verified permissions.
  214. ## What your PR sees
  215. The same run writes `pr-comment.md`, the comment the GitHub Action posts.
  216. This abridged excerpt is from the published `v1.3.0` release. It reports what
  217. a change added or changed but withholds what it removed or narrowed when agent
  218. binding coverage is incomplete, and names that limit; that coverage gap does
  219. not change the four blocking findings.
  220. Abridged from the released artifact:
  221. ```text
  222. ## Agents Shipgate
  223. ### Human summary
  224. - Merge verdict: `blocked`
  225. - Can merge without human: `false`
  226. - Release gate: `blocked`
  227. - Capability delta (analysed surface): 2 subjects across 6 changes (+1 added, 2 modified, -0 removed); newly outside the analysed surface: unknown (comparison unavailable)
  228. - Top capability changes by subject:
  229. - `stripe.create_refund`: added action — blocks release; added tool — blocks
  230. release; broadened action destructive — high-risk effect destructive added;
  231. blocks release; …
  232. - Static-verdict boundary: This verdict covers deterministic static evidence
  233. only. Agents Shipgate did not execute the agent or prove runtime behavior,
  234. tool routing, credential enforcement, or safety.
  235. - Next actor: `human`
  236. ```
  237. A second fenced block carries `control` and `fix_task` for the coding agent.
  238. ## What static evidence cannot prove
  239. Both fixtures above are constructed, with a clear-cut answer, chosen to show
  240. the gate working. Real PRs are messier. When a change builds its tool surface
  241. dynamically — a toolkit factory, a config-bound allowlist, tools assembled at
  242. runtime — static extraction often cannot enumerate the result, and Shipgate
  243. returns `insufficient_evidence` and routes to a human rather than emit a
  244. confident wrong verdict. That is the intended failure mode, not a bug; reducing
  245. how often it fires on real dynamic code is active work.
  246. Every result carries its own coverage limit. Nothing here proves runtime
  247. behavior, tool routing, credential enforcement, or safety — only what the
  248. declared and statically discoverable surface says. See
  249. [Limitations](#limitations) and [ROADMAP.md](ROADMAP.md).
  250. > [!IMPORTANT]
  251. > **Status: `v1.3.0`, advisory.** The published release makes no qualification
  252. > claim. Its defaults are advisory, and blocking CI is a policy you opt into
  253. > explicitly. The decision engine is deterministic; the accuracy evidence is
  254. > small-n and incomplete, and the parts below their bars are stated here rather
  255. > than in a footnote. On the fixed host-configuration corpora measured for 1.0,
  256. > change-row precision is 70/70, widening recall 55/65, benign zero-row 5/6 and
  257. > comparable coverage 41/50 — nine of fifty comparisons answer `Cannot compare`;
  258. > recall and the benign rate remain below their original bars, recorded as such
  259. > in [ROADMAP.md](ROADMAP.md#publication-and-evidence) rather than relabeled as
  260. > passes. The real-history numbers that follow are older, measured on
  261. > 2026-07-08 on the released `v0.15.0` engine and not re-run since: on
  262. > the **19 unique labeled engine-engaged PRs** mined from **5 distinct** real
  263. > agent repos (of the 8 the mining runs covered), the gate **never
  264. > auto-passed an unsafe change** (`must_block_caught` /
  265. > `needs_human_caught` = 1.0). **But it routes to review, it does not
  266. > block:** real-history `blocked_recall` is still **0.0** — both
  267. > `must_block` PRs return `human_review_required` /
  268. > `review_required`. That release also escalated 4 of 14 safe PRs to review
  269. > (`benign_escalation_rate` 0.286, largely a cold-start whole-repo-surface
  270. > artifact on large repos). Reliable blocked-recall and zero benign escalation
  271. > are proven on the constructed-adversarial stratum, not on real history, and
  272. > the labels are AI-adjudicated (0 disagreement) pending human spot-check.
  273. > Treat it as an advisory gate while this work closes. Full numbers:
  274. > [`benchmark/miner/README.md`](benchmark/miner/README.md) and
  275. > [ROADMAP.md](ROADMAP.md).
  276. ## Install
  277. ```bash
  278. pipx install agents-shipgate
  279. ```
  280. `pipx upgrade agents-shipgate` refreshes a stale copy; a plain install is a
  281. no-op over one. Alternatives — `pip`, `uv`, and zero-install `uvx` — are in
  282. [`docs/quickstart.md`](docs/quickstart.md#install). Your agent project does
  283. **not** need Python 3.12; the CLI installs separately.
  284. **Two lines, two promises.** The advisory line publishes rows a reviewer
  285. reads, and no authority to block anything by default; `v1.3.0` is an advisory
  286. release. The gate line publishes blocking verdicts and keeps every
  287. qualification bar. Each `v*` version is declared on exactly one line in
  288. [`.github/release-channels.json`](.github/release-channels.json). Neither line
  289. waits on the other, and
  290. [`docs/release-cadence`](docs/distribution.md#package-channels) measures both
  291. separately — one number could not have shown that the documented workflow was
  292. two months out of reach.
  293. | Line | Carries | Install | Promises | Cadence |
  294. | --- | --- | --- | --- | --- |
  295. | **Advisory** | `diff`, `check`, `audit --host`, drift, advisory PR comments | `pipx install agents-shipgate` (`v1.3.0`), or an unqualified preview pre-release | plain-language capability rows; **no blocking authority** unless you configure a blocking policy | 14 days |
  296. | **Qualified gate** | blocking verdicts backed by qualification evidence, receipts, attestations | a `v*` release declared on the qualified line; `v1.3.0` is not one | every bar in [`release-evidence-policy-decision.md`](docs/release-evidence-policy-decision.md) | on evidence only |
  297. **Read [which build you get](docs/quickstart.md#which-build-you-get) before you
  298. start.** The newest published release is `v1.3.0`, which implements runtime
  299. contract `42` — the agent control envelope, `current-control.json` and
  300. `--format agent-boundary-json` included — and is what `pipx install
  301. agents-shipgate` installs. It ships on the advisory channel and makes no
  302. qualification claim. The quickstart says what an older `v1.2.0`, `v1.1.0`,
  303. `v1.0.0` or `v0.15.0` install lacks, and what the unqualified preview does and does not
  304. come with.
  305. ## Where to go next
  306. | You are | Start at | It gives you |
  307. | --- | --- | --- |
  308. | A human evaluating one PR | [`docs/quickstart.md`](docs/quickstart.md) | One review end to end: what changed, why it matters, what was not established, and the next action |
  309. | A coding agent | [`AGENTS.md`](AGENTS.md), [`llms.txt`](llms.txt), [For coding agents](#for-coding-agents) | Machine-readable contracts, the read order, and the boundary you must not cross |
  310. | Adding this to CI | [`docs/integrations.md`](docs/integrations.md), [`examples/github-actions/`](examples/github-actions/) | Advisory-first workflows, then explicit merge policies |
  311. | Adopting it in a repo | [`docs/quickstart.md`](docs/quickstart.md#run-it-on-your-own-repository) | The zero-manifest host route and the manifest route, and how to tell which one you are on |
  312. | Contributing | [`CONTRIBUTING.md`](CONTRIBUTING.md#contribution-stance-2026-10-06), [`ROADMAP.md`](ROADMAP.md) | What contributions are welcome, surface discipline, the check catalog, and what is planned |
  313. Not sure it applies at all? The stdlib-only detector answers in one fetch, with
  314. no install:
  315. ```bash
  316. curl -sSL https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/tools/shipgate-detect.py \
  317. | python3 - --workspace . --json
  318. ```
  319. See [`docs/zero-install.md`](docs/zero-install.md) for how to read its answer.
  320. ## Who this is for
  321. - **Agent builders** — review MCP, OpenAPI, and SDK tool definitions before merging changes that expand the tool surface.
  322. - **Platform teams** — add release gates for approval, scope, idempotency, and baseline drift to PR review.
  323. - **Security and GRC reviewers** — get static release evidence without running agents or importing user code.
  324. Run it when a PR adds or changes agent tool surfaces or the policy evidence
  325. around them: MCP exports and OpenAPI specs; an MCP server whose tool surface
  326. exists only as code — TypeScript, Go or Python registration sites; framework
  327. tool definitions; Codex repo config; prompts, scopes, approval and confirmation
  328. policies, prohibited actions, `shipgate.yaml`; or the CI release gate itself.
  329. ## What it scans
  330. | Input | Status |
  331. |---|---|
  332. | Model Context Protocol (MCP) exports | Supported |
  333. | OpenAPI 3.x specs | Supported |
  334. | OpenAI Agents SDK Python files/directories | Supported |
  335. | Anthropic Messages API artifacts | Supported |
  336. | Google ADK Python and YAML config | Supported |
  337. | LangChain/LangGraph static Python inputs | Supported |
  338. | CrewAI static Python inputs | Supported |
  339. | n8n workflow JSON and source-control stubs | Supported |
  340. | Conductor OSS workflow JSON | Supported |
  341. | OpenAI API artifacts | Supported |
  342. | Codex repo config | Supported |
  343. | Codex plugin packages and marketplaces | Supported |
  344. Framework adapters parse Python AST only — they never import framework packages
  345. or user modules. Dynamic or prebuilt toolsets produce warnings or
  346. `insufficient_evidence` findings unless you provide explicit MCP, OpenAPI, or
  347. local tool-inventory inputs. Framework-by-framework minimal manifests, with a
  348. runnable sample repo for each adapter, are in
  349. [`docs/minimal-real-configs.md`](docs/minimal-real-configs.md).
  350. ## Why this exists
  351. Once an AI agent can refund, email, cancel, deploy, or modify a record, every
  352. tool change becomes a release event. Code review catches code; eval suites
  353. catch behavior; observability catches runtime. None of them answer the release
  354. question: *given the tool surface declared in this PR, do we have explicit
  355. approval policies, scope coverage, idempotency evidence, and review readiness
  356. for every action?*
  357. Agents Shipgate produces a deterministic answer to that question, before
  358. promotion. The promise is deliberately narrow: a static merge gate for
  359. AI-generated agent capability changes, run at PR time. Broader lifecycle ideas
  360. are roadmap work, not claims this scanner makes today. Comparisons against
  361. tests, code review and runtime traces are in
  362. [`docs/category.md`](docs/category.md).
  363. ## For coding agents
  364. Human readers can skip this section; it exists so coding agents can find the
  365. repo's machine-readable contracts quickly.
  366. - **[`AGENTS.md`](AGENTS.md)** — canonical agent-facing instructions: install, run, common tasks, JSON-mode flags, error semantics.
  367. - **[`llms.txt`](llms.txt)** / **[`llms-full.txt`](llms-full.txt)** — short index of every machine-readable surface, and the long-form one-fetch concatenation.
  368. - **[`.well-known/agents-shipgate.json`](.well-known/agents-shipgate.json)** — discovery metadata: tagline, install commands, schema URLs, gating signal, exit codes, trigger-catalog URL.
  369. - **[`docs/triggers.json`](docs/triggers.json)** — machine-readable mirror of the AGENTS.md trigger table. Apply the rules to a PR diff to decide whether to run the verifier.
  370. - **[`tools/shipgate-detect.py`](tools/shipgate-detect.py)** — zero-install, stdlib-only detector returning the same structural verdict as `agents-shipgate detect --json`. Pinned to the CLI by [`tests/test_zero_install_detector.py`](tests/test_zero_install_detector.py).
  371. - **[`docs/agent-contract-current.md`](docs/agent-contract-current.md)** — the single source of truth for current schema versions, which JSON fields to read, the command-scoped artifact lifecycle, and the signed human-authorization protocol. Other surfaces link here instead of restating it.
  372. - **[`docs/agent-native-merge-contract.md`](docs/agent-native-merge-contract.md)** — the eight contracts (trigger, capability change, merge verdict, repair, forbidden action, human authority, trust root, attestation) each mapped to the artifact that implements it.
  373. - **[`docs/agent-autofix-boundary.md`](docs/agent-autofix-boundary.md)** — what an agent may fix mechanically, and what it must never assert. Read this before touching a declaration.
  374. - **[`docs/agents/`](docs/agents/README.md)** — per-host entry points, the local control protocol, and the feedback loop.
  375. - **[`docs/checks.json`](docs/checks.json)** + **[`docs/checks.md`](docs/checks.md)** — machine-readable and prose check catalogs.
  376. - **[`docs/report-schema.v1.0.json`](docs/report-schema.v1.0.json)** — the current report schema, `1.0`, frozen. Reports carry `report_schema_version: "1.0"`; `0.43` is the last pre-freeze version and stays published as a frozen reference at [`docs/report-schema.v0.43.json`](docs/report-schema.v0.43.json). What `1.x` may and may not change is in [`docs/report-1-0-contract.md`](docs/report-1-0-contract.md); the handoff, verifier, receipt, capability-lock and attestation schemas are listed with it in [`docs/INDEX.md`](docs/INDEX.md).
  377. - **[`STABILITY.md`](STABILITY.md)** — what will not break across `0.x` versions.
  378. Read `agents-shipgate-reports/current-control.json` first — it names which run
  379. is current, and `agents-shipgate agent control --workspace .` validates it
  380. against every artifact it binds and against the live repository, refusing the
  381. read when HEAD or the working tree has moved since the decision. The full read
  382. order, and what each artifact carries, is in
  383. [`docs/agent-contract-current.md`](docs/agent-contract-current.md).
  384. Run `agents-shipgate contract --json` before relying on hard-coded schema or
  385. gating assumptions; the permission-scoped agent-control model requires
  386. `minimum_control_contract_version: "21"`. Every command has a `--json` form.
  387. When agent mode is active, the errors a command handles itself emit a
  388. structured `next_action` line on stderr — set `AGENTS_SHIPGATE_AGENT_MODE=1`,
  389. or rely on auto-detection inside a coding agent harness (Claude Code exports
  390. `CLAUDECODE=1`, Cursor `CURSOR_TRACE_ID`). `AGENTS_SHIPGATE_AGENT_MODE=0`
  391. forces it off. Not every path emits the line yet
  392. ([#1040](https://github.com/ThreeMoonsLab/agents-shipgate/issues/1040)): usage
  393. errors and some supporting commands print prose only; see
  394. [`AGENTS.md` § Agent mode](AGENTS.md#agent-mode).
  395. ## Exit codes
  396. | Code | Meaning |
  397. |---|---|
  398. | `0` | Success; the gate did not fail (with no `fail_on` in effect, advisory mode exits `0` on every decision, `blocked` included) |
  399. | `2` | Manifest config error |
  400. | `3` | Input parse error (file missing, malformed, path traversal blocked) |
  401. | `4` | Other Agents Shipgate error |
  402. | `6` | Baseline integrity failure: `baseline verify --strict` reported `SHIP-BASELINE-INTEGRITY-MISMATCH` (the baseline is not backed by its audit log); no other command exits `6` |
  403. | `20` | Gate failure: a blocker or finding matched `fail_on` (either mode), or strict mode saw a `blocked` or `insufficient_evidence` decision, a semantic, binding or policy evidence gap, or a `blocks_release` finding; elsewhere, `skill lint`/`security`/`review` on a `fail_on` match, `fixture verify` on a changed fixture summary, `org status` on a governance violation, and an opt-in gate flag such as `audit --host --drift --fail-on-drift` that found a violation ([full rule](STABILITY.md#exit-codes)) |
  404. Exit zero is not merge permission. Read the verdict.
  405. ## Limitations
  406. Agents Shipgate is a static, manifest-first scanner. It is intentionally narrow:
  407. - It does not run agents, call tools, invoke LLMs, or verify model availability by default (static-by-default; see [Trust Model](#trust-model) and [`ALLOWED_EXCEPTIONS`](tests/test_adapter_static_only.py)).
  408. - It does not verify runtime behavior, latency, prompt quality, or routing decisions.
  409. - It does not replace dynamic security testing or human security review of the underlying systems.
  410. - It only inspects what is declared in `shipgate.yaml`, local OpenAPI specs, MCP exports, MCP server source registrations, Anthropic/OpenAI API artifacts, optional SDK AST metadata, static Google ADK/LangChain/CrewAI/n8n/Conductor OSS inputs, Codex repo config, and static Codex plugin package metadata; tools that are not declared or statically discoverable are not scanned.
  411. - The manifest remains `version: "0.1"` so existing configs keep working. Current reports carry `report_schema_version: "1.0"`; every narrowing decision is recorded in `surface_exclusions` and reachable by the release decision, while v0.43 remains frozen for archived reports.
  412. ## Trust Model
  413. **Agents Shipgate does not import user code, run agents, call tools, call LLMs, connect to MCP servers, make network calls, or collect telemetry by default.**
  414. See [Trust model](docs/trust-model.md) and [Security policy](SECURITY.md) for
  415. the default local-only guarantees and the disclosure process.
  416. For support channels, the proposed 1.x maintenance policy and the release duties
  417. still requiring owner confirmation, see [Maintenance and support](MAINTAINERS.md).
  418. ## Pricing and open-source stance
  419. Agents Shipgate is and will remain free OSS for individuals and teams running
  420. it on their own infrastructure. The core manifest-first scanner, built-in
  421. checks, and Markdown/JSON reports are intended to remain open source. We do not
  422. collect telemetry and do not require an account. If hosted dashboards, SSO,
  423. org-wide baselines, approval workflows, or trace-based evidence emerge, they
  424. should live in a separate optional product rather than moving core OSS
  425. functionality behind a paywall.
  426. Teams shipping production-like tool-using agents can apply to the
  427. [Three Moons Lab design partner program](https://threemoonslab.com/design-partners/)
  428. (mirrored at [`docs/design-partners.md`](docs/design-partners.md)). The pilot
  429. runbook is
  430. [`docs/design-partner-verifier-pilot.md`](docs/design-partner-verifier-pilot.md);
  431. what the pilot has actually observed, including the counts that are still zero,
  432. is in
  433. [`docs/design-partner-pilot-results.md`](docs/design-partner-pilot-results.md).
  434. ## Adopters
  435. Agents Shipgate is local-first and static by default, and it collects nothing:
  436. no telemetry, no analytics, no account. It therefore cannot count its own
  437. users. [`ADOPTERS.md`](ADOPTERS.md) is the opt-in public registry that stands
  438. in for that: one line per adopter, added by the adopter, naming what they gate
  439. and whether it runs locally, as advisory CI, or as blocking CI. There is **no
  440. automatic collection of any kind** behind it — every entry is user-initiated
  441. and consenting, private repositories are listed at organization granularity,
  442. and an entry is removed on request without a reason. Private design-partner observations are a separate ledger under
  443. separate consent and never become public entries on their own.
  444. Every adoption number this project publishes traces to a named entry there —
  445. no entry, no claim — and maintainer dogfooding is counted apart from external
  446. adoption. Today that is **0 external adopter entries and 1 maintainer
  447. dogfooding entry** (as of 2026-09-06). If you run it,
  448. [add yourself](ADOPTERS.md#add-yourself); there is an optional
  449. [badge](ADOPTERS.md#badge) that links back to the registry, and it implies
  450. nothing about which tier you run.
  451. ## Docs
  452. [`docs/INDEX.md`](docs/INDEX.md) is the full index. The most-used pages:
  453. - [Quickstart — one review, end to end](docs/quickstart.md)
  454. - [The 5-minute mental model](docs/mental-model.md)
  455. - [Check catalog](docs/checks.md) · [Manifest v0.1](docs/manifest-v0.1.md) · [Policy packs](docs/policy-packs.md)
  456. - [Baseline workflow](docs/baseline.md) · [Integration recipes](docs/integrations.md) · [Troubleshooting](docs/troubleshooting.md)
  457. - [Sample reports and fixtures](samples/README.md) · [Golden PRs](examples/golden-prs/README.md)
  458. - [Agent entry points](docs/agents/README.md) · [Current agent contract](docs/agent-contract-current.md)
  459. - [Trust model](docs/trust-model.md) · [Privacy and redaction](docs/privacy.md) · [Terms](docs/terms.md)
  460. - [Distribution surfaces](docs/distribution-surfaces.md) — every surface this engine is published through, and the test that proves each one
  461. The marketing site at [threemoonslab.com](https://threemoonslab.com/) carries
  462. the same concepts in search-optimised form:
  463. [quickstart](https://threemoonslab.com/quickstart/),
  464. [check catalog](https://threemoonslab.com/checks/),
  465. [glossary](https://threemoonslab.com/glossary/), and
  466. [design partners](https://threemoonslab.com/design-partners/). The in-repo docs
  467. are the canonical contract.
  468. ### Moved out of this README
  469. This file was a 900-line reference. The material is intact, in these places:
  470. | Was | Now |
  471. | --- | --- |
  472. | `#60-seconds-watch-it-block-two-prs` | [One capability change, one verdict](#one-capability-change-one-verdict) |
  473. | `#verify-first-quickstart`, `#local-boundary-check`, `#pr-and-local-verification`, `#host-grant-audit`, `#how-to-read-your-first-result` | [`docs/quickstart.md`](docs/quickstart.md) — the three prominent flows are under [Run it on your own repository](docs/quickstart.md#run-it-on-your-own-repository), the verdict tables under [Verdict reference](docs/quickstart.md#verdict-reference) |
  474. | `#verify-your-repo`, `#adopt-in-one-turn-scan-helper` | [`docs/quickstart.md`](docs/quickstart.md#run-it-on-your-own-repository) |
  475. | `#temporary-external-repository-review` | [`docs/quickstart.md`](docs/quickstart.md#temporary-external-repository-review) |
  476. | `#authorize-one-exact-coding-agent-action` | [`docs/agent-contract-current.md`](docs/agent-contract-current.md#trusted-human-authorization-for-one-exact-command) |
  477. | `#use-in-ci` | [`docs/integrations.md`](docs/integrations.md), [`examples/github-actions/`](examples/github-actions/) |
  478. | `#what-it-produces` | [`docs/agent-contract-current.md`](docs/agent-contract-current.md#read-these-first-for-release-gating) |
  479. | `#copy-this-into-your-coding-agent`, `#use-with-your-coding-agent` | [`docs/target-repo-agent-snippets.md`](docs/target-repo-agent-snippets.md), [`docs/agents/README.md`](docs/agents/README.md) |
  480. | `#sample-reports`, `#findings-gallery`, `#see-it-block-a-pr` | [`samples/README.md`](samples/README.md), [`examples/golden-prs/README.md`](examples/golden-prs/README.md) |
  481. | `#why-not-just` | [`docs/category.md`](docs/category.md) |
  482. | `#framework-notes` | The AST-only boundary is under [What it scans](#what-it-scans); the per-framework manifests are in [`docs/minimal-real-configs.md`](docs/minimal-real-configs.md) |
  483. | `#not-sure-if-shipgate-applies` | [Where to go next](#where-to-go-next), and [`docs/zero-install.md`](docs/zero-install.md) |
  484. | `#use-this-when` | Folded into [Who this is for](#who-this-is-for) |

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.