ThreeMoonsLab · pengfei-threemoonslab · Jun 1, 2026 · Jun 1, 2026
diff --git a/.well-known/agents-shipgate.json b/.well-known/agents-shipgate.json
@@ -10,11 +10,12 @@
     "url": "https://threemoonslab.com"
   },
   "category": "agent_release_readiness",
-  "primary_wedge": "tool_use_readiness",
+  "primary_wedge": "ai_generated_agent_pr_verifier",
+  "primary_use_case": "deterministic merge verdicts for AI-generated agent capability changes",
   "positioning": {
-    "short": "Agent release readiness for tool-using AI agents",
-    "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.",
+    "short": "Merge verdicts for AI-generated agent PRs",
+    "answer": "Agents Shipgate is described by the canonical tagline: The deterministic merge gate for AI-generated agent capability changes. It is an open-source, local-first CLI and GitHub Action from Three Moons Lab that verifies PRs from Codex, Claude Code, Cursor, or humans and returns a deterministic merge verdict before agent code lands.",
+    "primary_use_case": "Run on PRs from Codex, Claude Code, Cursor, or humans when agent tools, prompts, permissions, MCP/OpenAPI surfaces, policies, or release gates change.",
     "not_for": ["llm_evals", "runtime_guardrails", "runtime_observability", "general_linting"]
   },
   "primary_keywords": [
@@ -26,7 +27,9 @@
     "OpenAPI tool scanning",
     "OpenAI Agents SDK release gate",
     "GitHub Action for AI agents",
-    "tool surface scanning"
+    "AI-generated PR review",
+    "agent capability merge verdict",
+    "deterministic merge verdict"
   ],
   "recommended_github_topics": [
     "ai-agents",
@@ -43,38 +46,87 @@
   ],
   "audiences": ["agent_builders", "platform_engineers", "security_reviewers", "coding_agents"],
   "when_to_use": [
+    "AI-generated agent PRs from Codex, Claude Code, Cursor, or similar tools",
     "AI agent tool-surface changes",
     "MCP or OpenAPI surface changes",
     "SDK tool decorator changes",
     "n8n workflow JSON changes",
     "Codex plugin package or marketplace changes",
-    "permissions, scopes, approval, confirmation, prompt, or release-gate changes"
+    "permissions, scopes, approval, confirmation, prompt, or release-gate changes",
+    "Shipgate CI, AGENTS.md, Claude Code skill, Cursor rule, baseline, waiver, or suppression changes"
   ],
   "package": {
     "pypi": "agents-shipgate",
     "github_action": "ThreeMoonsLab/agents-shipgate@v0.11.0",
     "github_repo": "ThreeMoonsLab/agents-shipgate"
   },
+  "release_status": {
+    "track": "verify-capable release",
+    "latest_release": "v0.11.0"
+  },
   "install": {
     "pipx": "pipx install agents-shipgate",
     "pip": "python -m pip install agents-shipgate",
     "uv": "uv tool install agents-shipgate"
   },
   "binaries": ["agents-shipgate", "shipgate"],
-  "quickstart": "agents-shipgate init --workspace . --write && agents-shipgate scan -c shipgate.yaml",
-  "verify": "agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json",
-  "fixture_run": "agents-shipgate fixture run support_refund_agent",
+  "quickstart": "agents-shipgate verify --preview --json",
+  "commands": {
+    "preview": "agents-shipgate verify --preview --json",
+    "install_ai_coding_workflow": "agents-shipgate init --workspace . --write --ci --agent-instructions=all",
+    "verify_pr": "agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json",
+    "trigger": "agents-shipgate trigger --base origin/main --head HEAD --json",
+    "feedback_export": "agents-shipgate feedback export --from agents-shipgate-reports/verifier.json --redact --out shipgate-feedback.json"
+  },
+  "fixture_run": "agents-shipgate fixture run ai_generated_refund_pr",
+  "static_scan_fixture_run": "agents-shipgate fixture run support_refund_agent",
   "self_check": "agents-shipgate self-check --json",
   "contract": "agents-shipgate contract --json",
   "contract_version": "1",
   "inputs": ["mcp", "openapi", "openai_agents_sdk", "anthropic_api", "google_adk", "langchain", "crewai", "openai_api", "codex_plugin", "n8n"],
-  "outputs": ["markdown", "json", "sarif", "packet_md", "packet_json", "packet_html", "verifier_json", "pr_comment_md"],
+  "outputs": ["markdown", "json", "sarif", "packet_md", "packet_json", "packet_html", "verifier_json", "pr_comment_md", "feedback_json"],
+  "artifacts": {
+    "verifier": "agents-shipgate-reports/verifier.json",
+    "report": "agents-shipgate-reports/report.json",
+    "pr_comment": "agents-shipgate-reports/pr-comment.md",
+    "feedback": "shipgate-feedback.json"
+  },
   "gating_signal": "release_decision.decision",
+  "merge_verdicts": ["mergeable", "human_review_required", "insufficient_evidence", "blocked", "unknown"],
+  "release_decisions": ["passed", "review_required", "insufficient_evidence", "blocked"],
+  "merge_verdict_labels": {
+    "passed": "mergeable",
+    "review_required": "human_review_required",
+    "insufficient_evidence": "insufficient_evidence",
+    "blocked": "blocked"
+  },
+  "verifier_read_order": [
+    "merge_verdict",
+    "can_merge_without_human",
+    "first_next_action",
+    "fix_task",
+    "capability_review.top_changes",
+    "release_decision.decision"
+  ],
+  "do_not_auto_assert": [
+    "approval",
+    "confirmation",
+    "idempotency",
+    "broad-scope",
+    "prohibited-action",
+    "runtime-trace",
+    "suppression",
+    "waiver",
+    "baseline",
+    "policy-weakening"
+  ],
   "trust_model": "static_by_default",
   "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.22.json",
+    "verifier": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/verifier-schema.v0.1.json",
     "packet": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/packet-schema.v0.6.json",
+    "feedback": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/feedback-schema.v0.1.json",
     "checks_catalog": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/checks.json"
   },
   "agent_instructions": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/AGENTS.md",
@@ -91,6 +143,23 @@
     "claude_code": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/agents/use-with-claude-code.md",
     "cursor": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/agents/use-with-cursor.md"
   },
+  "coding_agent_surfaces": {
+    "codex": {
+      "agents_md": "AGENTS.md",
+      "skill_path": ".agents/skills/agents-shipgate/",
+      "install": "agents-shipgate init --workspace . --write --ci --agent-instructions=agents-md,codex-skill"
+    },
+    "claude_code": {
+      "claude_md": "CLAUDE.md",
+      "skill_path": ".claude/skills/agents-shipgate/",
+      "slash_command": ".claude/commands/shipgate.md",
+      "install": "agents-shipgate init --workspace . --write --ci --agent-instructions=claude-md,claude-code-skill"
+    },
+    "cursor": {
+      "rules_path": ".cursor/rules/agents-shipgate.mdc",
+      "install": "agents-shipgate init --workspace . --write --ci --agent-instructions=cursor"
+    }
+  },
   "exit_codes": {
     "0": "pass",
     "2": "config_error",

diff --git a/AGENTS.md b/AGENTS.md
@@ -84,8 +84,9 @@ scanned; add `--base origin/main --head HEAD` only for a committed PR/CI ref
 after making the base ref available. Read
 `agents-shipgate-reports/verifier.json` first and lead with `merge_verdict`
 (`mergeable | human_review_required | insufficient_evidence | blocked |
-unknown`), `capability_review.top_changes[]`, and `first_next_action`.
-Then read `agents-shipgate-reports/report.json.release_decision.decision`
+unknown`), `can_merge_without_human`, `first_next_action`, `fix_task`, and
+`capability_review.top_changes[]`. Then read
+`agents-shipgate-reports/report.json.release_decision.decision`
 (`blocked | review_required | insufficient_evidence | passed`), which remains
 the release gate. Do not report completion while `merge_verdict` is `blocked`,
 `insufficient_evidence`, or `human_review_required` unless the user explicitly
@@ -96,7 +97,13 @@ expanding baselines or waivers, removing Shipgate CI, or weakening agent
 instructions. Verify-mode `SHIP-VERIFY-*` checks make those trust-root edits
 release-visible and route them to human review.
 
-To verify your install on a known fixture without writing any YAML:
+To reproduce the verify-native blocked refund PR demo without writing YAML:
+
+```bash
+agents-shipgate fixture run ai_generated_refund_pr
+```
+
+To verify your install on the older static scan fixture:
 
 ```bash
 agents-shipgate fixture run support_refund_agent

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+- **Verifier adoption-loop release prep.** Public docs and discovery metadata now
+  lead with the verify-first adoption path, pinned `v0.11.0` snippets, verifier
+  artifacts, merge verdicts, `fix_task`, and explicit Action merge-policy
+  examples. Adds the verify-native `ai_generated_refund_pr` fixture for the
+  blocked refund PR demo and introduces the provisional
+  `agents-shipgate feedback export` command plus
+  `docs/feedback-schema.v0.1.json` for redacted design-partner feedback loops.
+
 ## 0.11.0 - 2026-05-31
 
 - **Verifier PR comment v2 + additive Action outputs.** The GitHub Action now

diff --git a/README.md b/README.md
@@ -81,11 +81,25 @@ The release gate is `agents-shipgate-reports/report.json` →
 `release_decision.decision` (`blocked | review_required | insufficient_evidence | passed`).
 The PR/controller surface is `agents-shipgate-reports/verifier.json` →
 `merge_verdict` (`mergeable | human_review_required | insufficient_evidence |
-blocked | unknown`), a deterministic projection of the release decision.
+blocked | unknown`), a deterministic projection of the release decision. Read
+`verifier.json` first for `merge_verdict`, `can_merge_without_human`,
+`first_next_action`, `fix_task`, and `capability_review.top_changes`.
 
-Want a 5-minute demo 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 install check with no persistent install:
+Want a 5-minute verifier demo with zero setup? Run the verify-native blocked
+refund PR fixture:
+
+```bash
+agents-shipgate fixture run ai_generated_refund_pr
+```
+
+It builds a temporary base/head git history where the head commit adds
+`stripe.create_refund`, then writes `verifier.json`, `report.json`, and
+`pr-comment.md`. The expected merge verdict is `blocked`.
+
+The older static scan fixture remains useful when you want the full Tool-Use
+Readiness Report without a PR diff. If you already have
+[`uv`](https://docs.astral.sh/uv/) installed, the fixture path is a one-command
+install check with no persistent install:
 
 ```bash
 uvx agents-shipgate fixture run support_refund_agent
@@ -185,12 +199,14 @@ agents-shipgate init --workspace . --write --ci --agent-instructions=all
 agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json
 For committed PR/CI refs, add `--base origin/main --head HEAD` after making the
 base ref available. Read `agents-shipgate-reports/verifier.json` first and lead
-with `merge_verdict`, then read `agents-shipgate-reports/report.json` for
-`release_decision.decision`. Do not claim completion when `merge_verdict` is
-`blocked`, `insufficient_evidence`, or `human_review_required` unless the user
-explicitly accepts human review. Do not auto-assert approval. Never suppress
-findings, lower severity, expand baselines or waivers, remove Shipgate CI, or
-weaken agent instructions just to make the verifier pass.
+with `merge_verdict`, `can_merge_without_human`, `first_next_action`, `fix_task`,
+and `capability_review.top_changes`, then read
+`agents-shipgate-reports/report.json` for `release_decision.decision`. Do not
+claim completion when `merge_verdict` is `blocked`, `insufficient_evidence`, or
+`human_review_required` unless the user explicitly accepts human review. Do not auto-assert approval. Do not auto-assert confirmation, idempotency,
+broad-scope safety, prohibited-action enforcement, runtime-trace proof,
+suppressions, waivers, baselines, or policy weakening. Never remove Shipgate CI
+or weaken agent instructions just to make the verifier pass.
 ```
 
 ## Add the Codex adoption kit
@@ -579,14 +595,24 @@ jobs:
           shipgate_version: '0.11.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.
+After adoption, choose an explicit merge policy. [`examples/github-actions/07-block-on-blocked-verdict.yml`](examples/github-actions/07-block-on-blocked-verdict.yml) blocks only when `merge_verdict == blocked`; [`examples/github-actions/08-require-mergeable.yml`](examples/github-actions/08-require-mergeable.yml) requires `can_merge_without_human == true`. See [`examples/github-actions/`](examples/github-actions/) for strict / baseline / SARIF / multi-config / changed-paths recipes.
 
 Inputs: `config`, `ci_mode` (`advisory` or `strict`), `fail_on`, `baseline`, `baseline_mode`, `diff_from`, `diff_base`, `base_ref`, `head_ref`, `policy_packs`, `no_plugins`, `output_dir`, `upload_artifact`, `pr_comment`, `github_token`, `shipgate_version`. Set `diff_base: target` for PR base/head diff enrichment. The action delegates to `agents-shipgate verify` and never fetches; use `fetch-depth: 0` on checkout, or fetch the base ref in an earlier step. If `head_ref` is set, verify scans an isolated archive of that ref; otherwise it scans the checked-out workspace. If an explicit base ref or PR diff cannot be inspected, verify skips a head-only scan, writes `merge_verdict: "unknown"` to `verifier.json`, and exits 2.
 
 Outputs: `decision`, `merge_verdict`, `can_merge_without_human`, `blocker_count`, `review_item_count`, `ci_would_fail`, `diff_enabled`, `status`, `critical_count`, `high_count`, `medium_count`, `baseline_new_count`, `baseline_matched_count`, `baseline_resolved_count`, `adk_agent_count`, `adk_dynamic_toolset_count`, `trust_root_touched`, `policy_weakened`, `capability_changes_added`, `capability_changes_modified`, `capability_changes_removed`, `report_json`, `report_markdown`, `report_sarif`, `verifier_json`, `pr_comment_markdown`, `exit_code`. Prefer `merge_verdict`, `decision`, and `ci_would_fail` over legacy `status` for new release gates.
 
 Set `shipgate_version` to install a pinned PyPI release instead of the action source when your workflow requires package/version parity.
 
+For a design-partner review, export the small redacted verifier feedback
+artifact instead of sending raw report evidence:
+
+```bash
+agents-shipgate feedback export \
+  --from agents-shipgate-reports/verifier.json \
+  --redact \
+  --out shipgate-feedback.json
+```
+
 ## Pricing And Open Source Stance
 
 Agents Shipgate is and will remain free OSS for individuals and teams running it on their own infrastructure. The core manifest-first scanner, built-in checks, Markdown report, and JSON report are intended to remain open source. We do not collect telemetry and do not require an account.
@@ -617,6 +643,7 @@ readers and AI search ingest.
 - [Policy packs](docs/policy-packs.md)
 - [Baseline workflow](docs/baseline.md)
 - [JSON report schema v0.22](docs/report-schema.v0.22.json)
+- [Feedback export schema v0.1](docs/feedback-schema.v0.1.json)
 - [Privacy and redaction](docs/privacy.md)
 - [Trust model](docs/trust-model.md)
 - [AI search summary](docs/ai-search-summary.md)

diff --git a/STABILITY.md b/STABILITY.md
@@ -35,6 +35,15 @@ These commands and flags are stable across all `0.x.y` releases. They will only
 | `agents-shipgate fixture verify` | `<name>` |
 | `agents-shipgate self-check` | `--json` |
 
+### Provisional CLI command surface
+
+`agents-shipgate feedback export` is introduced in v0.11 for design-partner
+feedback loops. Its current flags are `--from`, `--redact`/`--no-redact`,
+`--out`, and `--json`. Treat the command and `feedback_schema_version: "0.1"`
+payload as provisional during the v0.11 design-partner cycle; the schema file is
+published so consumers can validate it, and any incompatible change must bump
+`feedback_schema_version`.
+
 ### Exit codes
 
 | Code | Meaning |
@@ -375,6 +384,12 @@ tests on every CI run, not by convention:
     local `git rev-parse`, `git diff`, `git ls-files`, and `git archive`
     for verify base/head and working-tree orchestration. It never fetches,
     uses fixed argv, captures output, and never executes user code.
+  - **`cli/fixture.py`** — one `subprocess.run` helper invokes local
+    `git init`, `git config`, `git add`, `git commit`, and `git update-ref`
+    against a temporary bundled fixture copy so
+    `fixture run ai_generated_refund_pr` can produce verifier artifacts.
+    This allowlisted meta-CLI surface uses fixed argv, no shell, no network
+    fetch, and no user-code execution.
   - **`fixtures.py`** — one `importlib.resources.files('agents_shipgate')`
     call to resolve the bundled fixture directory.
   - **`cli/discovery/agent_instructions/adoption_kit.py`** — one
@@ -699,6 +714,37 @@ Diff remains explanatory only.
 
 Fixture names listed by `agents-shipgate fixture list` are stable. Names will not be renamed. New fixtures may be added.
 
+`ai_generated_refund_pr` is the verify-native demo fixture. It creates a
+temporary base/head git history and writes `verifier.json`, `report.json`, and
+`pr-comment.md` for a blocked refund-capability PR.
+
+### Feedback export
+
+`agents-shipgate feedback export` derives a small local artifact from
+`agents-shipgate-reports/verifier.json`. The current schema is
+[`docs/feedback-schema.v0.1.json`](docs/feedback-schema.v0.1.json). Current
+v0.1 fields:
+
+- `feedback_schema_version`
+- `source_verifier`
+- `redacted`
+- `merge_verdict`
+- `can_merge_without_human`
+- `decision`
+- `mode`
+- `trigger`
+- `first_next_action`
+- `fix_task`
+- `capability_review`
+- `finding_ids`
+- `reviewer_feedback_requested`
+- `artifacts`
+
+The export is a design-partner and false-positive triage aid. It is derived
+from verifier projections and does not include raw finding evidence. With
+`--redact` (the default), local artifact paths are reduced to filenames so the
+artifact does not leak usernames or confidential workspace directory names.
+
 ### Agent-skill paths
 
 The following paths are part of the public agent surface and will not move within `0.x`:

diff --git a/action.yml b/action.yml
@@ -1,11 +1,11 @@
 name: Agents Shipgate
 description: >-
   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. Local-first and static-by-default. Audited
-  exceptions are pinned per call site in
+  Verifies PRs that change MCP, OpenAPI, OpenAI Agents SDK, Anthropic,
+  Google ADK, LangChain, CrewAI, OpenAI API, Codex plugin, and n8n
+  artifacts. Writes verifier.json, report.json, pr-comment.md, and SARIF
+  before your agent-capability change lands. 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