ADR-007: Empty ADR References Headers Are Dropped; Required Only When a Concern Cites a Specific ADR

Example from HELIX’s own docs. This generated page comes from docs/helix/. Use it to see the method in practice; start with the artifact-type catalog for reusable templates. Historical plans and reports may describe retired architecture.

Source identity (from 02-design/adr/ADR-007-empty-adr-references-headers-dropped.md):

ddx:
  id: ADR-007
  authoring:
    home: repo
  depends_on:
    - helix.prd

ADR-007: Empty ADR References Headers Are Dropped; Required Only When a Concern Cites a Specific ADR

Date	Status	Deciders	Related	Confidence
2026-05-30	Accepted	HELIX maintainers	concerns library, schema validator	High

Context

Aspect	Description
Problem	Many concerns ship an `ADR References` section header with no entries beneath it. The empty header creates a false promise of governing decisions that do not exist, and pads the artifact with structure that carries no information.
Current State	14 concerns currently ship an empty `ADR References` header: `a11y-wcag-aa`, `demo-asciinema`, `demo-playwright`, `design-patterns-gof`, `e2e-kind`, `e2e-playwright`, `go-std`, `hugo-hextra`, `i18n-icu`, `k8s-kind`, `o11y-otel`, `python-uv`, `rust-cargo`, `scala-sbt`. The schema validator does not require the section to be present.
Requirements	The concerns library must not advertise references that do not exist. The section should appear only when it carries real ADR citations, and should be omitted when it would otherwise be empty. The schema validator must continue to treat the section as optional.

Decision

An ADR References section header in a concern is included only when the concern actually cites one or more ADRs. Empty headers are removed by Phase 3 mechanical edits across the 14 concerns enumerated above. The schema validator does not require this section; presence is driven by content, not by template shape.

Concerns that genuinely govern decisions via ADRs keep the section and list the ADRs they cite. Concerns with no real ADR citations omit the header entirely.

Key Points: header presence follows content | empty headers removed in Phase 3 | schema validator keeps the section optional

Alternatives

Option	Pros	Cons	Evaluation
Keep empty `ADR References` headers as a template slot	Uniform structure across concerns	False promise of citations; padding without information; invites cargo-cult copy of the empty section into new concerns	Rejected: structure without content is noise
Require every concern to cite at least one ADR	Forces explicit governance	Most concerns are not governed by an ADR; would manufacture spurious references	Rejected: not all concerns need ADR backing
Drop empty headers; require the section only when ADRs are cited	Removes false promise; keeps real citations visible; matches existing validator behavior	Requires a one-time mechanical edit pass across 14 concerns	Selected: smallest change that aligns shape with content

Consequences

Type	Impact
Positive	Concerns no longer advertise references that do not exist.
Positive	Real ADR citations remain visible and unambiguous in the concerns that have them.
Positive	New concerns inherit a “populate or omit” rule that prevents the empty header from reappearing.
Negative	Phase 3 must touch 14 concern files to remove the empty headers.
Neutral	The schema validator is unchanged; the section stays optional.

Risks

Risk	Prob	Impact	Mitigation
Future concerns reintroduce the empty header by copy-paste	M	L	Phase 3 edits remove existing instances; reviewers reject empty headers on new concerns
A real ADR citation is accidentally removed alongside the empty headers	L	M	Phase 3 mechanical edits target only the enumerated 14 concerns where the section is empty

Validation

Success Metric	Review Trigger
None of the 14 enumerated concerns ships an empty `ADR References` header after Phase 3	An empty `ADR References` header appears in any concern
Concerns that cite ADRs retain the section with the citations intact	A real ADR citation is dropped by the Phase 3 edits

References

Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition: model-primary
Issuer: HELIX helix
Signing key: ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source: artifacts/adr/ADR-007-empty-adr-references-headers-dropped.md
Signed: 2026-09-23T14:11:58Z
Content digest: sha256:8c1fc4cb…f8639327

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON

{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-09-23T14:11:58Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/artifacts/adr/ADR-007-empty-adr-references-headers-dropped/",
        "digest": {
          "alg": "sha256",
          "value": "8c1fc4cb8cd86f3adb903c99685227f3d972fc04e09d8ff388854e71f8639327"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "M19z1j8-XmNqfOExHTXRZo0QHSpe8deoyntXmWa-IgoNmgS50MVZfKqbRUSq3t-OTucFxkTIvudgb-_pdJrODQ",
      "signed_at": "2026-09-23T14:11:58Z"
    }
  ]
}

attestation file · issuer keys