Sync agent-facing contract to v0.9 and refresh adoption surfaces

[pengfei-threemoonslab]

Summary

• Contract sync. Multiple agent-facing files (llms.txt, .well-known/agents-shipgate.json, skills/agents-shipgate/SKILL.md, .claude/commands/shipgate.md, docs/faq.md, prompts/add-shipgate-to-repo.md, examples/github-actions/README.md) referenced report schema v0.7/v0.8 as current and instructed agents to gate on summary.status. Current schema is v0.9 and the gating signal has been release_decision.decision since v0.8 — coding agents reading these files would build baseline-blind release gates. Updated each file to point at v0.9 and lead with release_decision.decision. Added docs/agent-contract-current.md as the single source of truth that other surfaces link to instead of restating the contract. Added tests/test_public_surface_contract.py (33 parametrized assertions) so PRs that drift from the contract on any public surface fail CI.

• README adoption funnel. The Release Evidence Packet (first-class output per STABILITY.md) and the three Golden PRs (examples/golden-prs/) were entirely absent from the README. Promoted both: packet now has its own bullet under "What it produces" plus an expected-output block in the 60-second demo; new "See it block a PR" section links the Golden PRs. Dropped the duplicated Quickstart section (its alt-install methods are folded into "Scan your repo"). Replaced the partial CI snippet with the full advisory workflow (permissions, pr_comment, timeout, version pin).

• Action PR comment idempotent. action.yml previously called github.rest.issues.createComment() on every run, appending a fresh comment each time and spamming PRs. Now uses a <!-- agents-shipgate-pr-comment --> sticky marker plus listComments + updateComment upsert. Template also gains a CI-mode line ("this PR would fail CI" / "this PR is not blocked by Shipgate") and explicit packet-artifact pointers. examples/github-actions/README.md outputs section reordered: v0.8+ outputs (decision, blocker_count, review_item_count, ci_would_fail) lead; legacy outputs are explicitly labeled.

Type

• Check or risk-model change
• Input adapter change
• CLI or GitHub Action behavior
• Report, schema, or SARIF output
• Documentation only

The Action change (PR-comment upsert) is the only behavior change; everything else is documentation-shaped.

Verification

CI is authoritative for python -m ruff check ., python -m compileall -q src tests, and python -m pytest.

Additional local checks run:

• python -m pytest — 459 passed (including the 33 new contract-drift assertions and 4 new action-metadata assertions).
• python -m ruff check . — clean.
• node --check on the inline JS in action.yml's github-script step — parses without error.
• Manual grep for report-schema.v0.[78] across *.md/*.txt/*.json/*.yml — only matches are in CHANGELOG (historical), docs/INDEX.md (frozen-reference labels), and docs/agent-contract-current.md (frozen-reference list). No agent-facing surface advertises a stale schema as current.
• Manual grep for summary.status — every mention sits next to a 'legacy / baseline-blind / v0.7 compat' marker per the new drift test.

Release-readiness notes

• No user-code import added to default scan paths
• No network access added to default scan paths
• New or changed check IDs are documented in docs/checks.md (no check changes in this PR)
• Report/schema changes are additive or documented in STABILITY.md (no schema changes in this PR; this PR makes existing surfaces match what STABILITY.md already specifies)

Reviewer notes

• No schema bump. This is a documentation/Action-template PR. Schemas are unchanged; this PR brings agent-facing prose into line with what STABILITY.md and AGENTS.md already declare as the v0.9 contract.
• No new feature flags or CLI surface. PR-comment upsert is on by default — that's the right default and matches what most CI tools do today (super-linter, dependabot). A pr_comment_mode: create|upsert|off knob can layer on later without breaking this default.
• Bundled prompt mirrored. skills/agents-shipgate/prompts/add-shipgate-to-repo.md is byte-identical to the canonical prompts/add-shipgate-to-repo.md per the existing test_prompt_byte_identical_across_locations parity test.
• Out of scope (deferred): agents-shipgate demo alias, examples/before-after/ example, dedicated Codex/Cursor docs, scan-side next_actions[], agents-shipgate diff. None contract-affecting; spin up separate PRs when needed.

🤖 Generated with Claude Code