ADR-048: Gate artifacts are read for shape, not presence


Status	Accepted (2026-08-10)
Date	2026-08-10
Author	Łukasz Bodurka
Tags	methodology, adoption, verification, consent

Context

ADR-042 made Gate 0's intake a required manifest entry, on the argument that an agent which ran the question round and one which skipped it produced an indistinguishable diff. The same argument applies to Gates 2 and 5, and was never made for them.

The checkmap (docs/method/adoption.md) calls the gate order and "every gate produces its artifact" rigid, framework-enforced, and specifies two outputs precisely: Gate 2 emits a health report (maturity per pass as absent / partial / solid, top risks, findings grouped by owner role), and Gate 5 emits a counted backlog in a given shape, every item naming its owner role, with the total described as "the go/no-go signal". Nothing in the framework read either one.

A real adoption run on 2026-08-10 (a Node application, ~250 files changed) reached self-verify drift 0 having produced neither. The repository's owner got the numbers only when they asked for them, and prose in place of both artifacts. Their verdict was that the adoption had happened to them rather than guided them, and on the evidence that is the correct reading: the run measured the repo and skipped the person, and the green number then certified a process that had not happened.

Two further findings from the same run make the mechanism concrete rather than theoretical:

The count's format is documented where the adopter never looks. It lives in the checkmap, a Zone 1 method page; standard/docs/backlog.md, the template an adopted repo actually receives, carries the owner column but has never mentioned the scope block at all. An agent filling the template correctly produces a backlog with no count in it.
The consent question is asked before the evidence exists. Step 0 asks "plan-only or execute" as part of the intake round - before a single assessment pass on a brownfield repo. The answer is therefore given about a wave nobody has seen. Assessment-only is already a legal stop after Gate 2, so the machinery for a real go/no-go exists and is simply not used as one.

Options considered

A - strengthen the wording in the skill. The instruction to produce a health report was already there and already specific about its contents. Wording that is followed when convenient is what produced this run. Rejected.
B - make the artifacts required manifest entries and stop there. This is ADR-042's mechanism, and it is necessary but not sufficient here. Presence is the whole of intake's contract; it is not the whole of these two. A file can exist, be non-placeholder, satisfy fill-from-repo, and still omit the count that the gate exists to produce. Rejected alone, adopted as half of D.
C - a review-time checklist. The blast radius has landed by the time anyone reviews a 250-file alignment PR, which is the same objection ADR-042 raised against auditing at step 8. Rejected.
D - chosen. A manifest entry for the missing artifact, plus a guard that reads both artifacts' shape. Presence closes the "the file is not there" hole via the existing mechanism; the guard closes the "the file is there and says nothing" hole that presence cannot see. A guard cannot carry a manifest exception, so neither half can be waived by an adopting repo that would rather not.

Decision

Option D. Concretely:

New rule, R27 (SPEC.md): the assessment and count gates MUST leave artifacts that carry what the gate is for - all eight passes rated on the three-value scale, top risks named, findings grouped by owner role, and a scope block whose stated total is the sum of its own categories with every item naming its owner role.
New manifest entry: docs/adoption-assessment.md, adapt: fill-from-repo, required: true, profile: core, rule: R27 - shaped after the docs/adoption-intake.md entry it is the sibling of.
New template, standard/docs/adoption-assessment.md.
New guard, standard/scripts/adoption-gates.mjs, registered in the manifest's guards and run in CI with tools/adoption-gates-test.mjs. It checks shape and arithmetic, never judgment: it cannot tell a considered partial from a guessed one, and does not pretend to. It skips itself when no assessment file exists, because self-verify already reports that as drift and counting it twice would make one gap look like two.
standard/docs/backlog.md gains the alignment scope block, so the format reaches the repo that has to produce it rather than living only in the method page.
The consent question splits. Step 0 still asks "plan-only or execute" and still records the answer, but that answer is an intent. The consent that licenses a wave is re-asked after Gate 2, with the drift number and the count in front of the user. A user who said "execute" at Step 0 and stops after reading the report has not gone back on their word, and the skill says so.

Consequences

Positive: an adoption that reaches drift 0 has necessarily produced the two artifacts a human reads to decide, and produced them with a total that adds up and an owner on every item. The failure mode this ADR was written from becomes impossible to reach silently.
Positive: the arithmetic check catches a class of rot nothing else would - a hand-maintained total drifts from its parts the first time an item is added, and a total that no longer describes its own breakdown reads as authoritative while describing nothing.
Negative: one more required file on every adopted repo, including an assessment-only run - which is the run that most obviously has one, so the record is genuine rather than manufactured to satisfy the gate.
Negative: the guard enforces a shape, and a repo whose honest assessment does not fit eight passes has to say so as a deviation rather than by silently omitting rows. That is the intended trade: the alternative is a report whose missing pass is indistinguishable from a pass nobody ran.
Neutral: R27 starts with no validation case, the same way R26 did.

Confirmation

standard.manifest.json carries the docs/adoption-assessment.md entry and the adoption-gates guard; SPEC.md carries R27 and its rule count reads R1-R27; onboard.md writes the report as the assessment pass's closing action and stops for the go/no-go before the first wave; standard/docs/backlog.md carries the scope block; a repo whose scope block claims a total its categories do not sum to fails adoption-gates while self-verify still reads drift 0.

Revisit when

Agents start producing shape-correct but guessed or hollow ratings that pass the arithmetic guard - the guard explicitly checks shape and arithmetic, never judgment, and "cannot tell a considered partial from a guessed one." That would reproduce this record's own failure mode one level deeper, the same way ADR-042's gap reappeared here.

ADR-042 - the mechanism this reuses, and the ADR whose argument this one extends to the two gates it did not cover.
ADR-020 - the intake round whose plan-only-vs-execute question this ADR splits into an intent and a consent.
ADR-006 - the prior case of a gate artifact that had to be more than present to be worth having.