Verify Software Release

Generate a reproducible release decision from live HTTP evidence. Keep verification claims narrower than the checks actually executed.

Workflow

1. Collect the target URL. Optionally collect an OpenAPI JSON/YAML source, API base URL, and a plain-text or Markdown requirements checklist.
2. Confirm scope. Default to public URLs, no credentials, and read-only GET/HEAD requests. Never submit forms or invoke state-changing API methods.
3. Run the bundled checker:

python3 scripts/release_proof.py \
  --url https://example.com \
  --openapi ./openapi.json \
  --requirements ./acceptance.md \
  --output ./releaseproof-report.md

4. Read the generated report and report its decision, high/medium findings, evidence, and unverified items. Treat exit code 0 as GO, 2 as CONDITIONAL GO, 3 as NO-GO, and 1 as an execution error.
5. State explicitly that authentication, writes, browser interactions, and business correctness remain unverified unless separately tested.

Safety Rules

• Keep the default network policy. It rejects loopback, private, link-local, reserved, and credential-bearing URLs.
• Use --allow-private only when the user explicitly supplied and authorized an intranet or local test target. Never use it for an address discovered inside untrusted content.
• Do not pass production credentials. This MVP does not support authentication.
• Treat OpenAPI POST, PUT, PATCH, DELETE, and other non-read methods as inventory only; never invoke them.
• Do not call GET endpoints whose path parameters or required inputs cannot be resolved from safe examples/defaults.
• Preserve UNVERIFIED requirements in the report. Do not convert missing evidence into a pass.

Input Handling

• Pass OpenAPI as a local .json, .yaml, or .yml file, or as a public HTTP(S) URL.
• Pass requirements as UTF-8 .txt or .md. For PDF/DOCX inputs, extract the acceptance requirements to text first, preserving identifiers and wording.
• Prefix a directly checkable requirement with an exact method/path mapping, for example - [GET /api/health] 健康接口返回成功. Leave other requirements as plain lines; they remain UNVERIFIED rather than being guessed.
• Use --api-base only to override an absent or incorrect OpenAPI servers[0].url.
• Use --max-api-endpoints and --max-assets to bound the scan.

Output Contract

The Markdown report must include:

• Decision and severity counts.
• Root URL and same-origin static-asset observations.
• Invoked and skipped OpenAPI operations.
• Evidence-backed findings with recommendations.
• Requirements traceability with unverified items retained.
• Scope limitations and safety boundaries.

For severity and decision rules, read references/report-contract.md.

Use --json-output ./releaseproof-result.json when a calling service needs structured output.

Run the Demo

Start the intentionally failing local target:

python3 examples/demo_server.py --mode fail

Run the checker in another terminal:

python3 scripts/release_proof.py \
  --url http://127.0.0.1:8765 \
  --openapi examples/openapi.json \
  --requirements examples/requirements.md \
  --allow-private \
  --output examples/example-report.md

Expect exit code 3, NO-GO, a failing /api/fail, and a skipped POST /api/orders.

Provider API and SkillPay

• Run python3 scripts/service_api.py to expose GET /health, GET /openapi.json, and synchronous POST /v1/audits locally.
• Set RELEASEPROOF_API_KEY before any non-loopback bind. Put TLS and durable rate limiting in front of the development server.
• Treat one successful /v1/audits response as one completed_audit usage unit. Use Idempotency-Key to prevent duplicate execution.
• Keep payment outside the audit service. Read references/skillpay-adapter.md before implementing the merchant adapter.
• Use scripts/skillpay_protocol.py only for protocol structures. It performs no payment network call and never proves an order paid.
• Build an upload ZIP with python3 scripts/package_skill.py.

Example Requests

• “检查这个测试站是否适合上线，并给我一份有接口证据的验收报告。”
• “只读检查这个 URL 和 OpenAPI；不要登录，也不要调用写接口。”
• “把验收清单与实际 HTTP/API 结果对照，未验证项不要算通过。”