Skip to content

Derive superseded ADR references from outgoing relations #67

Description

@dieterbaier

Problem

The toolkit's relation contract says that source artifacts contain authoritative
outgoing relations only and that incoming relations are derived during
generation.

For ADR replacement, the semantically active relation belongs to the newer ADR:

relations:
  - type: supersedes
    target: ADR-001-old-decision

However, metamodel/artifact.schema.yaml also declares superseded_by. If
that field is manually maintained, it duplicates the incoming side of
supersedes and can silently drift.

The architecture record should preserve old decisions so their rejected
alternatives and rationale do not disappear, but it should not require two
sources of truth.

Goal

Make the ADR superseding lifecycle explicit and derive the visible
superseded_by information from the newer ADR's outgoing supersedes
relation.

Required semantics

When ADR-B supersedes ADR-A:

  • ADR-B owns the outgoing supersedes relation to ADR-A.
  • ADR-A remains in the repository as the historical decision record.
  • ADR-A has lifecycle status superseded.
  • ADR-A's original Decision text is not rewritten.
  • Generated indexes and traceability views show ADR-A as
    superseded by ADR-B.
  • No reciprocal incoming relation is manually stored on ADR-A.

Preserving ADR-A prevents a rejected alternative from being proposed again
without its previous reasoning being visible.

Scope

  • Clarify supersedes lifecycle semantics in
    skills/references/relation-rules.md.
  • Add the workflow to skills/adr/SKILL.md or
    skills/references/adr-writing-guide.md.
  • Generate the incoming superseded_by display from the outgoing relation.
  • Decide whether the existing superseded_by schema field should be removed,
    deprecated, or declared generated-only.
  • Update the validator to reject manually maintained reciprocal
    superseded_by metadata if it is no longer valid source input.
  • Add generator and validation tests.

Acceptance criteria

  • One outgoing supersedes relation produces an incoming
    superseded by entry in generated views.
  • No manually maintained reciprocal relation is required.
  • Retargeting or removing supersedes updates the generated incoming view
    without editing the old ADR.
  • The old ADR remains readable and retains its original decision and rationale.
  • Its lifecycle status clearly indicates that it is no longer current.
  • The validator detects or rejects conflicting manual incoming metadata.
  • Examples cover accepted → superseded lifecycle transitions.

Origin

Found while validating ADR refinement and superseding behaviour in
dieterbaier/budget. The project wants
to preserve obsolete decisions, following the Nygard ADR lifecycle, while
retaining the toolkit's outgoing-only relation model.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions