---
schema_version: 1
id: RAC-KV2HSK685D79
type: roadmap
---
# RAC v0.13.5 — Self-Type Relationships

## Status

Planned

## Context

Authoring the Welcome series surfaced a traceability gap, recorded in
`rac-traceability-self-relationships`: RAC's relationship vocabulary could
not express **roadmap → roadmap** or **decision → decision** links. The
roadmap schema had no `related roadmaps` section and the decision schema no
`related decisions` section, so a release series could not chain its own
milestones and an ADR could not link the ADRs it builds on (beyond the
narrow `supersedes` case). Worse, the failure was silent: authors wrote
`## Related Roadmaps` and `## Related Decisions` on those types, the
sections passed validation as prose, and they produced zero edges with no
warning — 11 roadmap and 8 decision instances already in the corpus.

This milestone closes the gap. It adds the two missing relationship
sections to the roadmap and decision schemas, additively (ADR-007) and at
the end of each `optional` tuple (append-only section order). With
extraction enabled, the previously-inert sections become first-class edges,
resolved and validated like any other relationship (ADR-016). It satisfies
`rac-traceability-self-relationships` REQ-001, REQ-002, and REQ-003.

## Outcomes

- A roadmap can reference other roadmaps and a decision can reference other
  decisions; both become graph edges that resolve and validate.
- The relationship references already declared across the corpus stop being
  silently dropped: the Welcome and Watchkeeper series chain their
  milestones, and ADRs link the ADRs they build on.
- `supersedes` keeps its current decision-only replacement semantics and
  JSON shape, untouched; the new `related decisions` section is the general
  association, distinct from replacement.
- Classification is unaffected — relationship sections are optional and
  never scored — so no document changes type.

## Initiatives

### Initiative 1 — Schema Vocabulary Extension

Add `related roadmaps` to the roadmap spec's `optional` sections and
`related decisions` to the decision spec's, each appended last to preserve
section order (ADR-007), with matching relationship descriptions. Extraction
and validation pick them up automatically through the existing spec-driven
mechanism — no new analysis code.

### Initiative 2 — Corpus Reference Hygiene

Turning on validation for the newly-consumed sections checks references that
were never validated before. Repair the malformed instances it surfaces
(decision references that carried descriptive text after the id, and a stray
code fence) so `rac relationships rac/ --validate` stays clean.

### Initiative 3 — Coverage and Gap Closure

Add extraction and resolution tests for both new relationship types, and
update `rac-traceability-self-relationships` to reflect delivery.

## Constraints

- Additive only (ADR-007): no section is removed or repurposed, and the new
  sections append to each `optional` tuple rather than reordering it.
- `supersedes` is untouched — it remains decision-only and a top-level
  scalar in inspect output.
- Relationships stay structural Markdown references (ADR-016); the whole
  line is the reference, matched case-insensitively to artifact identity.

## Non-Goals

- Directional or dependency semantics for the new links — like the existing
  `related_*` sections they are undirected associations, not ordering.
- A graph-cycle check; related links may form cycles, as they already can
  across types.
- Templates gaining these sections — relationship sections are never
  templated, only recognized when present.

## Implementation Contract

The following decisions are pinned for v0.13.5.

### Schema

- Roadmap `optional` gains `related roadmaps` (appended last).
- Decision `optional` gains `related decisions` (appended last), alongside
  the existing `supersedes`.
- Both gain matching entries in the relationship-description map.

### Behaviour

- `rac inspect` exposes `related_roadmaps` for roadmaps and
  `related_decisions` for decisions in its `relationships` map.
- `rac relationships --validate` resolves and validates both, reporting
  broken/ambiguous/self references like any other relationship.
- Exit codes, JSON contracts, and `supersedes` semantics are unchanged.

## Success Measures

- `rac relationships rac/ --validate` exits 0 with the self-type edges
  included (the previously-dropped instances now resolve).
- `rac inspect` on a roadmap with `## Related Roadmaps` and a decision with
  `## Related Decisions` lists those relationships.
- A broken self-type reference is reported as a validation issue rather than
  silently ignored.

## Risks

- Enabling validation surfaces references that were never checked, which can
  newly fail the gate. Mitigated: Initiative 2 repairs them in the same
  change, and the audit record enumerated the instances in advance.
- Allowing self-type links invites cycles. Accepted: treated as undirected
  associations, consistent with existing relationship semantics.

## Assumptions

- The relationship model stays "structural references in Markdown sections"
  (ADR-016); this milestone extends the vocabulary, not the mechanism.
- Commit-time and classification behaviour are unaffected because
  relationship sections are optional and never scored.

## Related Decisions

- adr-007
- adr-016

## Related Requirements

- rac-traceability-self-relationships

## Related Roadmaps

- v0.13.0-guided-first-run
