Skip to content

feat(blueprint-plugin): build the ADR section ceiling ADR-0023 deliberately left unbuilt #2702

Description

@laurigates

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.

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

  1. 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.
  2. 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.
  3. 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.

Refs #2446, #2701

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions