|
| 1 | +# ADR-0036 — The gate can see single-sourcing, and says so without blocking |
| 2 | + |
| 3 | +- **Date:** 2026-09-21 |
| 4 | +- **Status:** accepted |
| 5 | +- **Area:** contract checks, evidence policy |
| 6 | +- **Depends on:** ADR-0004 (the checks are an ordered registry), ADR-0013 (a check that judged reasoning would be wrong) |
| 7 | + |
| 8 | +## Context |
| 9 | + |
| 10 | +Twelve checks asked whether a claim was **backed**: is there a row, is there a capture, |
| 11 | +does the chain verify, is the capture whole, is it fresh, is it primary, has it been |
| 12 | +superseded. Not one asked whether it was backed **more than once**. |
| 13 | + |
| 14 | +So a corpus in which every unknown rested on a single page passed `preflight` and |
| 15 | +`--strict` with nothing to say about it. That is not hypothetical — it is this |
| 16 | +repository's own delivery-architecture corpus, on the day it was used to justify ADR-0031 |
| 17 | +and ADR-0032. Nine rows, all primary, all `full`, all fresh, and eight unknowns each |
| 18 | +resting on exactly one of them. Three of those eight carried architecture decisions. |
| 19 | + |
| 20 | +**From inside such a corpus, a single correct source and a single lucky one are |
| 21 | +indistinguishable.** Every other check would report green either way. |
| 22 | + |
| 23 | +## Decision |
| 24 | + |
| 25 | +A thirteenth check, `corroboration`, reporting the **shape** of an unknown's support: |
| 26 | + |
| 27 | +| rule | when | severity | |
| 28 | +|---|---|---| |
| 29 | +| `single-source` | one row | `warn` | |
| 30 | +| `one-voice` | several rows, one host | `warn` | |
| 31 | +| `independent` | several rows, several hosts | `pass` | |
| 32 | + |
| 33 | +### It never fails a corpus on its own |
| 34 | + |
| 35 | +Single-sourcing is frequently the right answer. A vendor's own API reference *is* the |
| 36 | +authority on that API, and demanding a second opinion about it is ceremony. This check |
| 37 | +declines to make that judgement — it describes the support and leaves the call to a |
| 38 | +reviewer, which is the same line ADR-0013 drew when it refused to let a check grade |
| 39 | +reasoning. |
| 40 | + |
| 41 | +`corroboration` joins `transport-provenance` and `capture-completeness` in `POLICY_CHECKS`, |
| 42 | +so `evidencePolicy=strict` is where an operator says they want the harder rule. All three |
| 43 | +are questions an *evidence policy* should answer rather than the kit: how it was fetched, |
| 44 | +how much arrived, how many times it was read. |
| 45 | + |
| 46 | +Every existing corpus stays green. Verified on all three in this repository — the |
| 47 | +repository's own, and both nested decision projects — each still `PASS` under the default |
| 48 | +policy, now with warnings that say something true. |
| 49 | + |
| 50 | +### The host distinction is the point, not a refinement |
| 51 | + |
| 52 | +Counting rows would have been easier and would have missed the case that matters. Two |
| 53 | +pages from one vendor are **one witness read twice**: that catches a misreading, and |
| 54 | +cannot catch a vendor being wrong about itself. The remedies differ — one wants another |
| 55 | +page, the other wants another party — so the finding names which it found. |
| 56 | + |
| 57 | +## What it immediately said about work finished an hour earlier |
| 58 | + |
| 59 | +The corroboration pass that preceded this ADR added a second source to the three |
| 60 | +delivery-architecture unknowns that carry decisions, and the commit called them |
| 61 | +*"independent"*. The check disagrees: all three second sources are `docs.github.com`, so |
| 62 | +all three report `one-voice` rather than `independent`. |
| 63 | + |
| 64 | +**The check is right and the commit message was loose.** They are independent *pages* — |
| 65 | +different URLs, written by different teams, and they did catch facts the originals omitted, |
| 66 | +including that an unpinned API client silently moves to a different version on a date. They |
| 67 | +are not independent *sources*. The corpus's own contract already said this in prose — |
| 68 | +"a second reading of the same vendor" — and the commit summarising it reached for the |
| 69 | +stronger word anyway. |
| 70 | + |
| 71 | +That is the argument for the check in miniature: the distinction is easy to state, easy to |
| 72 | +believe you have honoured, and invisible unless something counts hosts. |
| 73 | + |
| 74 | +## Alternatives considered |
| 75 | + |
| 76 | +**Fail on single-sourcing.** Would have broken every corpus in this repository and most |
| 77 | +that anyone writes, to enforce a rule that is wrong about half the time. |
| 78 | + |
| 79 | +**Count rows and ignore hosts.** Simpler, and it would have graded the delivery corpus as |
| 80 | +corroborated when it is not. |
| 81 | + |
| 82 | +**Require a second source only for unknowns marked load-bearing.** No such marking exists, |
| 83 | +and inventing one moves the judgement into the contract without making it checkable. |
| 84 | + |
| 85 | +**Leave it to review.** That is what was happening. Review missed it for as long as the |
| 86 | +corpus existed, and the corpus was used to make two architecture decisions in the meantime. |
| 87 | + |
| 88 | +## Consequences |
| 89 | + |
| 90 | +- The registry is thirteen checks; the pinned-order test and the inventory move with it. |
| 91 | +- One preflight test asserted "every check reports a **pass**" on the fixture project. That |
| 92 | + fixture is single-sourced, so it now carries one warning. The assertion was changed to |
| 93 | + "every check **reports**", with the expected warning named — rather than padding the |
| 94 | + fixture with a second source to preserve the old wording, which would have been tuning |
| 95 | + the world to fit the assertion. |
| 96 | +- The policy-membership test stopped inferring "hygiene is not hardened" from a whole |
| 97 | + verdict passing, and now isolates the claim. That proxy only ever worked while nothing |
| 98 | + else in the policy set fired. |
| 99 | + |
| 100 | +## What this ADR does not claim |
| 101 | + |
| 102 | +That two hosts make a claim true. Two vendors can repeat one another, and a specification |
| 103 | +and its own tutorial are not independent whatever their hostnames say. `independent` means |
| 104 | +*this check found no reason to flag the support*, which is weaker than correct and is the |
| 105 | +strongest thing a mechanical check can honestly report. |
0 commit comments