# Interface evidence policy

Use this policy before adding or changing any HTTP or command step.

## Evidence priority

Prefer the narrowest current primary source that proves the fact:

1. A precise user-provided API contract, request/response example, command contract, or runtime artifact for the requested environment and version.
2. Current versioned OpenAPI/proto files in the resolved `tidb-management-service` source. Resolve `$TIDB_MANAGEMENT_SERVICE_DIR`, then an available `../tidb-management-service` checkout, then the pinned official [`ff5c78ac9` source](https://github.com/tidbcloud/tidb-management-service/tree/ff5c78ac952849735b14a93ecabcceec4933ea33). Search by operation ID, RPC name, or path under `api/spec/tidb_cloud_open_api/`.
3. Official CLI documentation or local `--help` output for the installed command version.
4. Current runner code for scenario schema, request construction, placeholder behavior, CEL evaluation, retries, saves, and teardown.
5. Existing scenario YAML, repository history, GHA logs, or PR discussions as supporting evidence and examples.

Do not use memory, naming conventions, an adjacent API version, or a superficially similar operation as evidence. When primary sources conflict, exhaust repository history, the resolved runner, pinned official sources, primary documentation, and supplied artifacts. If they do not select one safe contract, record a blocked evidence gap; never ask, wait, or guess.

## Required ledger

Record one row per call before editing:

| Step purpose | Interface | Contract facts used | Evidence | Status |
|---|---|---|---|---|
| Create resource | `Operation_ID` / command | method/path or subcommand; auth; request fields; expected status/exit; saved response/output fields | precise file and symbol/line, official doc, artifact, or user statement | proven / missing |

Also record lifecycle evidence for polling signals and cleanup dependencies. A row is `proven` only when every fact consumed by the YAML is supported.

## What existing YAML can prove

Existing scenario files can prove repository conventions such as:

- compatible file shape and metadata style;
- placeholder naming and dependency patterns;
- workflow/provider/auth combinations already represented;
- known resource lifecycle sequencing worth investigating.

They cannot, by themselves, prove that an endpoint, field, enum, response shape, status code, or timing assumption is correct for a new request. Confirm those facts with a current contract, runtime artifact, or precise user statement.

## Blocking gaps

Do not edit the affected call when any of these remain unknown after exhausting all available evidence:

- API tier/version, provider, auth mode, host class, method, or path;
- required versus optional fields, types, enum values, or parameter location;
- asserted status code, error semantics, response field path/casing, or state value;
- a value needed for a destructive operation or resource cleanup;
- command syntax, installed-version behavior, output format, or output field path;
- whether a resource transition is synchronous, pollable, or requires an intermediate dependency;
- which of two conflicting current sources applies.

Group related gaps into one concise blocked-evidence report. Include every searched source/revision, the execution impact, and the smallest artifact that could resolve the contract. Continue any independent, fully proven work without waiting.

## Evidence-aware repair

Review findings about YAML syntax, embedded JSON, runner-supported types, placeholder wiring, order, known retry math, or exposed secrets usually have a deterministic repair.

Review findings that would select or alter an endpoint, request field/value, expected status, response path, auth policy, provider behavior, async state, timeout, or product outcome require contract evidence. If exhaustive evidence does not uniquely select a repair, record the smallest proposed repair as a blocked evidence gap and leave the call unchanged.