Post check results back from CI

CI can post check runs and statuses to a Forge using a capability token as a bearer credential, through the GitHub-compatible REST façade at /api/v3.

Default-deny, and three conditions

A bearer is admitted to the check/status write routes only when all three hold:

1. The repository has opted the bearer mechanism into its web_auth policy. This is default-deny — the surface is off until an owner turns it on, per repository.
2. The token's human root is a member of that repository.
3. The token carries the checks:write metadata scope it was consented for.

A content-scoped token — even a read-only one — holds no metadata scope at all and is refused 403 with TVO-GHC-002. It can never post a check it never consented to. Delegated bearers are refused outright, so a metadata scope cannot be delegated. A native channel-bound principal governs by membership alone.

Checks gate landing, and the gate is default-closed

A proposal cannot land until every declared required check is passing. An absent required check counts as pending and blocks, so a lost job blocks the land rather than sliding through. A cancelled or blocked check does not satisfy the gate either.

Plugin checks are different

A plugin:<id> check must be recorded by a Forge admin or a designated attester — a regular member cannot self-post a pass. Attempting it is refused at POST /checks with TVO-FORGE-009 and 403. A required plugin check that is absent, failing, wrongly authored, or stamped with a stale revision blocks the land with TVO-PLUGIN-015 and 422.

Secrets never enter a check body

Values are masked and do not appear in check or event bodies. A clearance denial names the secret and the step index — never a value.

Honest refusals

Routes with no native TOVIO referent — issues, labels, milestones — return 501 with TVO-GHC-001 rather than faking a response. An unsupported reference or sha form is 422 (TVO-GHC-004); an OAuth scope with no enforceable native capability is refused at consent with 400 (TVO-GHC-003), never silently granted.

Know the addressing answer before you wire anything

TOVIO commits are blake3: addresses; GitHub clients expect 40-hex SHA-1. The façade fixes a sha presentation per repository at creation, and the per-repository compatibility report states which one you get. Read that report first — it also lists every incompatibility the façade cannot reproduce, as an explicit statement rather than a silent failure.