You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Follow-up to #2446 / #2701, filed from the review on that PR.
The gap
ADR-0023 narrowed adr.schema.json's required sections to Context / Decision / Consequences, dropping Options Considered and Related ADRs to optional. The PR's first draft claimed those two were still asked for by "the ADR template and /blueprint:adr-validate". The review checked. Neither exists:
blueprint-adr-validate validates relationships, domain consistency, duplicate numbers, reference integrity and index drift. It has never checked sections — grep -niE "section|Options Considered|Related ADRs" blueprint-plugin/skills/blueprint-adr-validate/SKILL.md returns zero matches.
There is no five-section ADR authoring template in the repo. docs/adrs/README.md §ADR Format documents the three-section Nygard shape, and /blueprint:derive-plans points at a MADR template whose headings don't match the schema.
So ADR-0023 removed the floor's lower two rungs and no surface picked them up. The claim was withdrawn in e1d4c98 rather than papered over: the schema description, blueprint-plugin/README.md and ADR-0023 now all say the two sections are recommended-but-unenforced.
This issue is the other half — building the ceiling, if it's wanted.
Adding a gate is a different decision from narrowing one. #2446's triage decision was the narrowing; building new enforcement inside that PR would have widened it past what was decided, and the "should new ADRs be held to five sections?" question deserves its own answer rather than riding along.
Options
Add a section check to blueprint-adr-validate. It is already the skill the schema description points at as "the gate that can insist". Natural home, no new surface. Needs a decision on whether it warns or fails, and whether it applies to all ADRs or only ones above the current max number — a check that flags all 20 historical ADRs reproduces exactly the unreadable-report problem docs(blueprint): 20 of 22 ADRs lack the template sections the schema requires #2446 was filed to fix.
Ship a real five-section ADR template and point blueprint-adr-create / derive-plans at it, so new ADRs get the structure by construction rather than by audit. Weaker enforcement, but no backlog and no judgement call about grandfathering.
Neither — the convention is enough. Defensible: the corpus shows 20 of 22 ADRs were written without these sections and nobody missed them. Close this as not-planned and let the ADR-0023 wording stand as the final word.
Option 2 composes with option 1; option 3 forecloses both.
Acceptance
Whichever option lands, the prose fixed in e1d4c98 gets updated in the same commit so the repo does not go back to describing enforcement it doesn't have: adr.schema.json's sections.description and sections.title, blueprint-plugin/README.md's schema table and WARN rationale, blueprint-plugin/docs/hook-design-decisions.md's section tables, and ADR-0023's Consequences.
If option 1: a new-ADR-only or warn-only scope decided explicitly, not left to default, with the backlog count measured first (currently 20 ADRs lack both sections).
If option 3: ADR-0023 amended to say the convention is deliberate and permanent, so this doesn't get re-litigated.
Follow-up to #2446 / #2701, filed from the review on that PR.
The gap
ADR-0023 narrowed
adr.schema.json's required sections toContext/Decision/Consequences, droppingOptions ConsideredandRelated ADRsto optional. The PR's first draft claimed those two were still asked for by "the ADR template and/blueprint:adr-validate". The review checked. Neither exists:blueprint-adr-validatevalidates relationships, domain consistency, duplicate numbers, reference integrity and index drift. It has never checked sections —grep -niE "section|Options Considered|Related ADRs" blueprint-plugin/skills/blueprint-adr-validate/SKILL.mdreturns zero matches.docs/adrs/README.md§ADR Format documents the three-section Nygard shape, and/blueprint:derive-planspoints at a MADR template whose headings don't match the schema.So ADR-0023 removed the floor's lower two rungs and no surface picked them up. The claim was withdrawn in e1d4c98 rather than papered over: the schema description,
blueprint-plugin/README.mdand ADR-0023 now all say the two sections are recommended-but-unenforced.This issue is the other half — building the ceiling, if it's wanted.
Why it wasn't done in #2701
Adding a gate is a different decision from narrowing one. #2446's triage decision was the narrowing; building new enforcement inside that PR would have widened it past what was decided, and the "should new ADRs be held to five sections?" question deserves its own answer rather than riding along.
Options
blueprint-adr-validate. It is already the skill the schema description points at as "the gate that can insist". Natural home, no new surface. Needs a decision on whether it warns or fails, and whether it applies to all ADRs or only ones above the current max number — a check that flags all 20 historical ADRs reproduces exactly the unreadable-report problem docs(blueprint): 20 of 22 ADRs lack the template sections the schema requires #2446 was filed to fix.blueprint-adr-create/derive-plansat it, so new ADRs get the structure by construction rather than by audit. Weaker enforcement, but no backlog and no judgement call about grandfathering.Option 2 composes with option 1; option 3 forecloses both.
Acceptance
adr.schema.json'ssections.descriptionandsections.title,blueprint-plugin/README.md's schema table and WARN rationale,blueprint-plugin/docs/hook-design-decisions.md's section tables, and ADR-0023's Consequences.Refs #2446, #2701