S-307 (401 response) should be graded by maturity — warn for draft/alpha/rc, error for public

[hdamker]

Problem description

S-307 (owasp:api8:2023-define-error-responses-401, "Operation must document a 401 response") fires as a hard error at every API maturity. It is new in r4.x — it comes from the OWASP ruleset added only to .spectral-r4.yaml (absent in .spectral-r3.4.yaml) and is elevated from the OWASP upstream warn to error. Repositories moving to r4 while still at draft/alpha/rc therefore get a blocking error for not yet documenting a 401 response, even though the API is still being defined. Surfaced on r4.3 common-sync PRs.

Expected behavior

Grade S-307 by target_api_status: warn for draft/alpha/rc, error for public. Concretely, add a conditional_level block to the S-307 entry in validation/rules/spectral-rules.yaml:

conditional_level:
  default: error
  overrides:
    - condition:
        target_api_status: [draft, alpha, rc]
      level: warn

S-016 is the existing precedent for status-based muting, but its override currently lists [alpha, rc] and omits draft. The same change should extend S-016 to [draft, alpha, rc] so both completeness rules grade consistently across the pre-public maturity ladder.

Alternative solution

Leave S-307 as error and require all pre-public APIs to document 401 immediately. Rejected — too strict for early maturity and inconsistent with the S-016 completeness model.

Additional context

Scope is S-307 (plus the S-016 draft alignment). The security-critical OWASP errors (api2 no-credentials-in-url, api2 short-lived-access-tokens, api2 read-restricted / write-restricted, api5 admin-security-unique) should stay error even at alpha and are out of scope.