Tighten public contract surfaces

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -11,7 +11,7 @@ body:
     id: version
     attributes:
       label: Agents Shipgate version
-      placeholder: "v0.10.0"
+      placeholder: "v0.8.0"
     validations:
       required: true
   - type: dropdown

.well-known/agents-shipgate.json

@@ -4,14 +4,21 @@
   "display_name": "Agents Shipgate",
   "tagline": "Static release-readiness gate for AI agent tool surfaces",
   "version": "0.10.0",
+  "version_context": "current main / in-tree CLI contract; may be ahead of the published release",
+  "published_release": {
+    "version": "0.8.0",
+    "tag": "v0.8.0",
+    "github_release_url": "https://github.com/ThreeMoonsLab/agents-shipgate/releases/tag/v0.8.0",
+    "pypi_url": "https://pypi.org/project/agents-shipgate/0.8.0/"
+  },
   "license": "Apache-2.0",
   "publisher": {
     "name": "Three Moons Lab",
     "url": "https://threemoonslab.com"
   },
   "package": {
     "pypi": "agents-shipgate",
-    "github_action": "ThreeMoonsLab/agents-shipgate@v0.10.0",
+    "github_action": "ThreeMoonsLab/agents-shipgate@v0.8.0",
     "github_repo": "ThreeMoonsLab/agents-shipgate"
   },
   "install": {
@@ -25,10 +32,11 @@
   "self_check": "agents-shipgate self-check --json",
   "contract": "agents-shipgate contract --json",
   "contract_version": "1",
-  "inputs": ["mcp", "openapi", "openai_agents_sdk", "anthropic_messages_api", "google_adk", "langchain", "crewai", "openai_api", "codex_plugin"],
+  "inputs": ["mcp", "openapi", "openai_agents_sdk", "anthropic_messages_api", "google_adk", "langchain", "crewai", "n8n", "openai_api", "codex_plugin"],
   "outputs": ["markdown", "json", "sarif", "packet_md", "packet_json", "packet_html"],
   "gating_signal": "release_decision.decision",
   "trust_model": "static_by_default",
+  "schemas_context": "current main / in-tree schemas; may be ahead of the published release",
   "schemas": {
     "manifest": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/manifest-v0.1.json",
     "report": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/report-schema.v0.16.json",
@@ -37,6 +45,7 @@
   },
   "agent_instructions": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/AGENTS.md",
   "agent_contract": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/agent-contract-current.md",
+  "public_contract": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/public-contract.json",
   "stability_contract": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/STABILITY.md",
   "triggers_url": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/triggers.json",
   "errors_url": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/errors.json",

README.md

@@ -19,9 +19,9 @@
 
 Agents Shipgate is an open-source CLI and GitHub Action that scans MCP,
 OpenAPI, OpenAI Agents SDK, Anthropic Messages API, Google ADK,
-LangChain/LangGraph, CrewAI, n8n, and OpenAI API artifacts, then writes a
-deterministic **Tool-Use Readiness Report** before your agent gets
-production-like permissions.
+LangChain/LangGraph, CrewAI, n8n, OpenAI API artifacts, and Codex plugin
+metadata, then writes a deterministic **Tool-Use Readiness Report** before your
+agent gets production-like permissions.
 
 **Website:** [threemoonslab.com](https://threemoonslab.com/) —
 [quickstart](https://threemoonslab.com/quickstart/),
@@ -163,7 +163,7 @@ minimal manifests, see [`docs/minimal-real-configs.md`](docs/minimal-real-config
 ## Use in CI
 
 ```yaml
-- uses: ThreeMoonsLab/agents-shipgate@v0.10.0
+- uses: ThreeMoonsLab/agents-shipgate@v0.8.0
   with:
     config: shipgate.yaml
     ci_mode: advisory
@@ -190,7 +190,7 @@ Set `pr_comment: "true"` to post a compact PR summary:
 
 ## What it produces
 
-- **Tool-Use Readiness Report** — `agents-shipgate-reports/report.{md,json,sarif}`. Markdown for human release review, JSON for tools and coding agents (current schema [v0.16](docs/report-schema.v0.16.json); gating signal is `release_decision.decision`; v0.16 adds first-class Action Surface Diff fields on top of v0.15's per-finding `provenance_kind`), SARIF for GitHub code-scanning workflows.
+- **Tool-Use Readiness Report** — `agents-shipgate-reports/report.{md,json,sarif}`. Markdown for human release review, JSON for tools and coding agents (current main schema [v0.16](docs/report-schema.v0.16.json); gating signal is `release_decision.decision`; v0.16 adds first-class Action Surface Diff fields on top of v0.15's per-finding `provenance_kind`), SARIF for GitHub code-scanning workflows.
 - **Release Evidence Packet** — `agents-shipgate-reports/packet.{md,json,html}` (and `packet.pdf` with the `[pdf]` extras). Reviewer-shaped synthesis with fixed sections, including tool-surface and action-surface diffs when available. Governed by [packet schema v0.5](docs/packet-schema.v0.5.json) — see [STABILITY.md §Release Evidence Packet](STABILITY.md#release-evidence-packet-v05).
 
 ## Exit codes
@@ -213,6 +213,7 @@ Agents Shipgate is designed to be agent-friendly. If you're a coding agent (Clau
 - **[`llms.txt`](llms.txt)** — short index of every machine-readable surface, one fetch.
 - **[`llms-full.txt`](llms-full.txt)** — long-form concatenation of `AGENTS.md` + recipes + checks + concepts + autofix policy, in one document. Built by `scripts/build-llms-full.py`.
 - **[`.well-known/agents-shipgate.json`](.well-known/agents-shipgate.json)** — discovery metadata (tagline, install commands, schema URLs, gating signal, exit codes, trigger-catalog URL).
+- **[`docs/public-contract.json`](docs/public-contract.json)** — committed public constants: latest published release, canonical tagline, install commands, GitHub Action pin, trigger URL, and current-main schema URLs.
 - **[`docs/triggers.json`](docs/triggers.json)** — machine-readable mirror of the AGENTS.md trigger table. Apply the rules to a PR diff to decide whether to propose `agents-shipgate detect`. Schema is stable for `0.x`.
 - **[`tools/shipgate-detect.py`](tools/shipgate-detect.py)** — zero-install, stdlib-only detector. `curl … | python3 - --workspace . --json` returns the same structural verdict as `agents-shipgate detect --json`. Pinned to the canonical CLI by [`tests/test_zero_install_detector.py`](tests/test_zero_install_detector.py). See [`docs/zero-install.md`](docs/zero-install.md).
 - **`agents-shipgate contract --json`** — verify the installed CLI's local contract before relying on hard-coded schema or gating assumptions.
@@ -226,7 +227,7 @@ Agents Shipgate is designed to be agent-friendly. If you're a coding agent (Clau
 - **[`prompts/`](prompts/)** — reusable prompts for common workflows
 - **[`skills/agents-shipgate/`](skills/agents-shipgate/)** + **[`.claude/commands/shipgate.md`](.claude/commands/shipgate.md)** — self-contained Claude Code skill (bundled prompts and CI recipe) and `/shipgate` slash command. See [`docs/agents/use-with-claude-code.md`](docs/agents/use-with-claude-code.md) to install in your own project.
 - **[`docs/ai-search-summary.md`](docs/ai-search-summary.md)** — human-readable summary for AI search, answer engines, and coding agents
-- **[`docs/manifest-v0.1.json`](docs/manifest-v0.1.json)** + **[`docs/report-schema.v0.16.json`](docs/report-schema.v0.16.json)** — JSON Schemas for live editor validation (current; emitted reports carry `report_schema_version: "0.16"`). v0.16 adds `action_surface_facts` and `action_surface_diff`; v0.15 added the per-finding `provenance_kind` enum. Read `release_decision.decision` for release gating in new consumers; read `agent_summary.first_recommended_action` for a deterministic next step.
+- **[`docs/manifest-v0.1.json`](docs/manifest-v0.1.json)** + **[`docs/report-schema.v0.16.json`](docs/report-schema.v0.16.json)** — JSON Schemas for current main / in-tree live editor validation (emitted reports carry `report_schema_version: "0.16"`). v0.16 adds `action_surface_facts` and `action_surface_diff`; v0.15 added the per-finding `provenance_kind` enum. Read `release_decision.decision` for release gating in new consumers; read `agent_summary.first_recommended_action` for a deterministic next step.
 - **[`docs/checks.json`](docs/checks.json)** — machine-readable check catalog
 
 Every command has a `--json` form. Errors emit a structured `next_action` line on stderr when `AGENTS_SHIPGATE_AGENT_MODE=1`.
@@ -446,12 +447,12 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
         with:
           fetch-depth: 0
-      - uses: ThreeMoonsLab/agents-shipgate@v0.10.0
+      - uses: ThreeMoonsLab/agents-shipgate@v0.8.0
         with:
           ci_mode: advisory
           diff_base: target
           pr_comment: 'true'
-          shipgate_version: '0.10.0'
+          shipgate_version: '0.8.0'
 ```
 
 Switch to `ci_mode: strict` only after your team has reviewed the advisory output. See [`examples/github-actions/`](examples/github-actions/) for strict / baseline / SARIF / multi-config / changed-paths recipes.

docs/INDEX.md

@@ -20,6 +20,7 @@ A single entry point for human readers and AI agents walking the `docs/` tree.
 
 - [`checks.md`](checks.md) — full check catalog (human-readable)
 - [`checks.json`](checks.json) — machine-readable check catalog (regenerated each release)
+- [`public-contract.json`](public-contract.json) — committed public-surface constants for published release, tagline, install commands, trigger URL, and current-main schema URLs
 - [`manifest-v0.1.json`](manifest-v0.1.json) — JSON Schema for `shipgate.yaml`
 - [`report-schema.v0.16.json`](report-schema.v0.16.json) — JSON Schema for `report.json` (current; emitted reports carry `report_schema_version: "0.16"`, which adds first-class Action Surface Diff fields)
 - [`agent-action-guide.md`](agent-action-guide.md) — per-category recipe for what to do with a finding (canonical fix per check category, last-resort suppression rules)

docs/agent-contract-current.md

@@ -10,7 +10,8 @@ Verify the installed CLI contract locally before relying on hard-coded docs:
 agents-shipgate contract --json
 ```
 
-- Latest release: `v0.10.0` (see [pyproject.toml](../pyproject.toml) for the in-tree version)
+- Latest published release: `v0.8.0`
+- In-tree CLI version on current main: `v0.10.0` (see [pyproject.toml](../pyproject.toml))
 - Runtime contract: `1`
 - Current report schema: `0.16` — [`docs/report-schema.v0.16.json`](report-schema.v0.16.json)
 - Current packet schema: `0.5` — [`docs/packet-schema.v0.5.json`](packet-schema.v0.5.json)

docs/ai-search-summary.md

@@ -11,6 +11,10 @@ It is a static release-readiness gate for AI agent tool surfaces. It reads a
 `shipgate.yaml` manifest plus declared local tool sources, then writes
 deterministic Tool-Use Readiness Reports as Markdown, JSON, and SARIF.
 
+The latest published release is `v0.8.0`. The current main branch may document
+newer in-tree CLI and schema contracts before they are published; verify a local
+install with `agents-shipgate contract --json`.
+
 Use Agents Shipgate before an AI agent receives staging, production-like, or
 production permissions to tools that can refund, email, cancel, deploy, modify
 records, read sensitive data, or change infrastructure.
@@ -42,8 +46,10 @@ Agents Shipgate supports these static tool-source inputs:
 - Google ADK Python and YAML config.
 - LangChain and LangGraph Python entrypoints, using static AST extraction.
 - CrewAI Python entrypoints, using static AST extraction.
+- n8n workflow JSON and source-control stubs.
 - OpenAI API artifacts, including prompts, function schemas, response
   formats, tests, and traces.
+- Codex plugin package and marketplace metadata.
 
 ## What it is not
 
@@ -81,8 +87,17 @@ shipgate, and Agents-Shipgate.
 - Repository: <https://github.com/ThreeMoonsLab/agents-shipgate>
 - Package: <https://pypi.org/project/agents-shipgate/>
 - GitHub Action: <https://github.com/marketplace/actions/agents-shipgate>
+- Public contract constants: [`public-contract.json`](public-contract.json)
 - Agent instructions: [`../AGENTS.md`](../AGENTS.md)
 - Machine-readable summary: [`../llms.txt`](../llms.txt)
+- Long-form agent reference: [`../llms-full.txt`](../llms-full.txt)
 - Discovery metadata: [`../.well-known/agents-shipgate.json`](../.well-known/agents-shipgate.json)
-- Report schema (current): [`report-schema.v0.14.json`](report-schema.v0.14.json) (v0.13 frozen at [`report-schema.v0.13.json`](report-schema.v0.13.json))
+- Trigger catalog: [`triggers.json`](triggers.json)
+- Current main report schema: [`report-schema.v0.16.json`](report-schema.v0.16.json)
+- Current main packet schema: [`packet-schema.v0.5.json`](packet-schema.v0.5.json)
 - Check catalog: [`checks.json`](checks.json)
+
+For release gating, coding agents should read
+`agents-shipgate-reports/report.json` and use
+`release_decision.decision` as the gate signal. Do not scrape Markdown reports
+or gate on legacy `summary.status`.

docs/distribution.md

@@ -5,7 +5,7 @@ These items require release infrastructure, registry credentials, domains, or Gi
 ## Package Channels
 
 - `agents-shipgate` is published on PyPI.
-- Pinned GitHub Action release tags are published, including `v0.10.0`.
+- Pinned GitHub Action release tags are published, including `v0.8.0`.
 - GitHub Releases attach the wheel, sdist, SBOM, and Sigstore bundles.
 - Evaluate a container image later only if it has an exercised build-and-test path.
 - Evaluate Homebrew once CLI usage warrants it.

docs/faq.md

@@ -121,7 +121,7 @@ Skip emission with `--no-packet`; re-render later with
 
 ## Is it production-ready?
 
-v0.10.0 is the latest released version. The manifest schema is stable
+v0.8.0 is the latest released version. The manifest schema is stable
 across the 0.x series; see [`STABILITY.md`](../STABILITY.md). Used by
 early design partners. Public preview.
 

docs/integrations.md

@@ -21,7 +21,7 @@ jobs:
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
       - id: agents-shipgate
-        uses: ThreeMoonsLab/agents-shipgate@v0.10.0
+        uses: ThreeMoonsLab/agents-shipgate@v0.8.0
         with:
           config: shipgate.yaml
           ci_mode: advisory
@@ -113,7 +113,7 @@ agents-shipgate:
   stage: test
   image: python:3.12
   script:
-    - python -m pip install "agents-shipgate==0.10.0"
+    - python -m pip install "agents-shipgate==0.8.0"
     - agents-shipgate scan --config shipgate.yaml --ci-mode advisory --format markdown,json,sarif
   artifacts:
     when: always
@@ -145,7 +145,7 @@ jobs:
       - image: cimg/python:3.12
     steps:
       - checkout
-      - run: python -m pip install "agents-shipgate==0.10.0"
+      - run: python -m pip install "agents-shipgate==0.8.0"
       - run: agents-shipgate scan --config shipgate.yaml --ci-mode advisory --format markdown,json,sarif
       - store_artifacts:
           path: agents-shipgate-reports
@@ -174,7 +174,7 @@ Run Agents Shipgate locally on every commit that touches a tool-surface artifact
 # .pre-commit-config.yaml
 repos:
   - repo: https://github.com/ThreeMoonsLab/agents-shipgate
-    rev: v0.10.0
+    rev: v0.8.0
     hooks:
       - id: agents-shipgate
 ```

docs/public-contract.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_version": "0.1",
+  "name": "agents-shipgate-public-contract",
+  "description": "Committed public-surface constants used to keep agent-facing discovery metadata, docs, and examples aligned without network calls in CI.",
+  "published_release": {
+    "version": "0.8.0",
+    "tag": "v0.8.0",
+    "github_release_url": "https://github.com/ThreeMoonsLab/agents-shipgate/releases/tag/v0.8.0",
+    "pypi_url": "https://pypi.org/project/agents-shipgate/0.8.0/"
+  },
+  "canonical_tagline": "Static release-readiness gate for AI agent tool surfaces",
+  "install": {
+    "pipx": "pipx install agents-shipgate",
+    "pip": "python -m pip install agents-shipgate",
+    "uv": "uv tool install agents-shipgate",
+    "uvx_fixture": "uvx agents-shipgate fixture run support_refund_agent"
+  },
+  "github_action": "ThreeMoonsLab/agents-shipgate@v0.8.0",
+  "trigger_catalog_url": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/triggers.json",
+  "gating_signal": "release_decision.decision",
+  "main_branch_contract": {
+    "context": "current main / in-tree CLI contract; may be ahead of the published release",
+    "manifest_schema_url": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/manifest-v0.1.json",
+    "report_schema_url": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/report-schema.v0.16.json",
+    "packet_schema_url": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/packet-schema.v0.5.json",
+    "checks_catalog_url": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/checks.json"
+  }
+}

docs/quickstart.md

@@ -167,7 +167,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ThreeMoonsLab/agents-shipgate@v0.10.0
+      - uses: ThreeMoonsLab/agents-shipgate@v0.8.0
         with:
           config: shipgate.yaml
           ci_mode: advisory

docs/target-repo-agent-snippets.md

@@ -204,7 +204,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: ThreeMoonsLab/agents-shipgate@v0.10.0
+      - uses: ThreeMoonsLab/agents-shipgate@v0.8.0
         with:
           config: shipgate.yaml
           ci_mode: advisory

docs/upstream-integrations.md

@@ -311,7 +311,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: ThreeMoonsLab/agents-shipgate@v0.10.0
+      - uses: ThreeMoonsLab/agents-shipgate@v0.8.0
         with:
           ci_mode: advisory
           diff_base: target

docs/zero-install.md

@@ -76,12 +76,12 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
         with:
           fetch-depth: 0
-      - uses: ThreeMoonsLab/agents-shipgate@v0.10.0
+      - uses: ThreeMoonsLab/agents-shipgate@v0.8.0
         with:
           ci_mode: advisory
           diff_base: target
           pr_comment: 'true'
-          shipgate_version: '0.10.0'
+          shipgate_version: '0.8.0'
 ```
 
 The full template lives at [`examples/github-actions/01-advisory-pr-comment.yml`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/examples/github-actions/01-advisory-pr-comment.yml).

examples/circleci/01-advisory.yml

@@ -6,7 +6,7 @@ jobs:
       - image: cimg/python:3.12
     steps:
       - checkout
-      - run: python -m pip install "agents-shipgate==0.10.0"
+      - run: python -m pip install "agents-shipgate==0.8.0"
       - run: agents-shipgate scan --config shipgate.yaml --ci-mode advisory --format markdown,json,sarif
       - store_artifacts:
           path: agents-shipgate-reports

examples/circleci/02-strict-with-baseline.yml

@@ -6,7 +6,7 @@ jobs:
       - image: cimg/python:3.12
     steps:
       - checkout
-      - run: python -m pip install "agents-shipgate==0.10.0"
+      - run: python -m pip install "agents-shipgate==0.8.0"
       - run:
           name: Agents Shipgate strict scan
           command: >

examples/circleci/03-sarif-artifact-retention.yml

@@ -6,7 +6,7 @@ jobs:
       - image: cimg/python:3.12
     steps:
       - checkout
-      - run: python -m pip install "agents-shipgate==0.10.0"
+      - run: python -m pip install "agents-shipgate==0.8.0"
       - run: agents-shipgate scan --config shipgate.yaml --ci-mode advisory --format markdown,json,sarif
       - store_artifacts:
           path: agents-shipgate-reports/report.sarif

examples/circleci/04-multi-config-workspace.yml

@@ -6,7 +6,7 @@ jobs:
       - image: cimg/python:3.12
     steps:
       - checkout
-      - run: python -m pip install "agents-shipgate==0.10.0"
+      - run: python -m pip install "agents-shipgate==0.8.0"
       - run:
           name: Agents Shipgate workspace scan
           command: >

examples/circleci/05-on-tool-source-changes.yml

@@ -6,7 +6,7 @@ jobs:
       - image: cimg/python:3.12
     steps:
       - checkout
-      - run: python -m pip install "agents-shipgate==0.10.0"
+      - run: python -m pip install "agents-shipgate==0.8.0"
       - run:
           name: Run only when tool sources changed
           command: |

examples/github-actions/01-advisory-pr-comment.yml

@@ -18,9 +18,9 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: ThreeMoonsLab/agents-shipgate@v0.10.0
+      - uses: ThreeMoonsLab/agents-shipgate@v0.8.0
         with:
           ci_mode: advisory
           diff_base: target
           pr_comment: 'true'
-          shipgate_version: '0.10.0'
+          shipgate_version: '0.8.0'