Gate: contract-status-declared

The Output Contract statuses are the ones the handler returns — and only those.

Property	Value
Checker	contract-status-declared
Confronts	spec
Blocking by default — new project	yes
Blocking by default — existing project	no — informs

How it measures

Confronts the Output Contract table of an INTERFACE spec — a handler, a route — against the status codes the governed code actually emits: the table was written, but does the code still keep it?

Why the gate exists, measured: in an audit of 51 spec-versus-code divergences in the reference app (2026-08), this was the MOST REPEATED pattern — eight handlers declared a contract the code did not honour. And the omitted status was almost always the SECURITY one: the 403 of ownership, the 409 of conflict. Whoever writes the table thinks about the happy path and about the “business” errors, not about the refusals of access.

The two sides of the error are different, and both matter. A status EMITTED and not declared leaves the client — programmed from the table — unable to handle the refusal: the user sees a generic error where there was a specific reason. That was accept-org-invite, which declared 3 status codes and emitted 8; the two missing 403s and the 409 were the defence against invite hijacking. A status DECLARED and never emitted is worse in another way: it is dead code in the client, and it disappears with nobody noticing. reanalyse-metadata declared 402 for exceeded quota and no path of the handler emits 402 (the quota answers 429) — a client treating 402 as “needs to pay” would never fire that branch.

What separates it from its neighbours: dependency-honored confronts the symbols the spec promises to consume; this one confronts the status codes the spec promises to return. And unlike spec-complete, it never charges the EXISTENCE of the section — with no table there is nothing to confront.

Declaring it

gates:
  - name: contract-status-declared
    on: [spec]
    check: contract-status-declared

Source: checker · its spec