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.
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:
However,
metamodel/artifact.schema.yamlalso declaressuperseded_by. Ifthat field is manually maintained, it duplicates the incoming side of
supersedesand 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_byinformation from the newer ADR's outgoingsupersedesrelation.
Required semantics
When ADR-B supersedes ADR-A:
supersedesrelation to ADR-A.superseded.superseded by ADR-B.Preserving ADR-A prevents a rejected alternative from being proposed again
without its previous reasoning being visible.
Scope
supersedeslifecycle semantics inskills/references/relation-rules.md.skills/adr/SKILL.mdorskills/references/adr-writing-guide.md.superseded_bydisplay from the outgoing relation.superseded_byschema field should be removed,deprecated, or declared generated-only.
superseded_bymetadata if it is no longer valid source input.Acceptance criteria
supersedesrelation produces an incomingsuperseded byentry in generated views.supersedesupdates the generated incoming viewwithout editing the old ADR.
Origin
Found while validating ADR refinement and superseding behaviour in
dieterbaier/budget. The project wantsto preserve obsolete decisions, following the Nygard ADR lifecycle, while
retaining the toolkit's outgoing-only relation model.