docs(checklist): rule 42 — a shared refusal code makes an arm's witness ambiguous

[lilyshen0722]

What

One rule appended to docs/development/review-checklist.md (rule 42, new section Refusal codes as witnesses). Docs-only: no version bump, no source change.

A guard added above an existing one can invalidate the arms below it without changing a line of them — the arm still passes, for the new guard's reason. What makes such an arm a witness is that its FIXTURE reaches the guard the arm NAMES, and the instrument for that is a mutation of that guard, not the shape of the assertion.

Two guards sharing a refusal code make that code non-discriminating for a given input, so counting a code's emitters says only where attribution is at risk (rule 25); the per-arm question is which guards can fire on its input. Re-aiming the fixture is the fix, and it is local and cheap. Asserting the exception message is an option that additionally pins which refusal — never a requirement. (An earlier revision of this rule claimed the opposite; see Earned.)

Earned

Today, on #2007/TASK-172. My RFC 8414 §3.3 issuer check landed above an established endpoint guard in backend/services/hostedMcpIntakeService.ts. The neighbour arm — "refuses an incomplete document rather than guessing an endpoint" — was written when only the endpoint guard existed and sent a document naming no issuer, so it was answered by the newer guard, under the same issuer_metadata_incomplete. Deleting the endpoint guard changed no test in the neighbourhood: the arm named a guard that could no longer answer its input.

Found by the gate, not the author: vera measured that deleting if (!body.authorization_endpoint || !body.token_endpoint) left the neighbourhood green, and her repair was one line (give the arm an issuer).

Measured as one instrument, same suite (30 tests), both directions — the survivor is not taken from the report:

arm fixture	endpoint guard deleted	result
no issuer (pre-repair, f0354405)	yes	30/30 green — the guard is unwitnessed
issuer present (post-repair)	yes	that arm alone reds — on the code assertion: with the guard gone nothing is thrown, so thrown.code is a TypeError

That second row is also why the first revision of this rule was wrong, and the docs gate refused it at 568df1c2 with exactly this counter-example. The rule was rewritten against the measurement: a checklist line that over-prescribes the assertion shape sends every future reader to add a second assertion instead of asking which guard answers their input.

Rider in the rule

Where a route answers { error: code } with no message — vendorFailureStatus in routes/hostedMcpConnect.ts does exactly this — two defects sharing a code are indistinguishable to the operator: a 502 reading issuer_metadata_incomplete does not say whether the document named no issuer or named no endpoint. So "same code" is a client-visible contract decision, not a test detail. Splitting the vocabulary is deliberately not in #2007; it is recorded on the TASK-172 row for whoever takes it.

Guard

node scripts/verify-numbered-rules.js docs/development/review-checklist.md
✓ 42 rules, numbers 1..42 ascending with no gap, 20 citation(s) all resolve.

Gate: rhea — cleared at 3ec8034b. Numbering passes against current main; #2000 (rules 42 + 43) remains open, so whichever of the two merges second renumbers — mine, if it is mine.