---
schema_version: 1
id: RAC-KV3WXTPPFPR6
type: roadmap
tags: [relationships, enforcement, graph, lifecycle]
---
# RAC v0.16.0 — Relationship-Graph Integrity (Layer 3)

## Status

Planned

## Context

ADR-049 makes cross-artifact validation RAC's core, and this milestone opens the
v0.16.x graph-integrity series with the checks that validate the corpus *as a
graph* — the differentiator no single-file validator (MADR, dotprompt, OKF) has.
Referential integrity, edge-legality (domain), and decision-only
status-consistency already ship. This milestone adds the missing pieces:
a declarative relationship-type registry, **range** and **acyclicity** checks
(ADR-055), the generalized all-type status-consistency rule (implementing
ADR-051), and a validation-status roll-up on the MCP ``get_summary`` tool.

Per ADR-055 and ADR-052, the registry is code-defined and the edge vocabulary is
unchanged (``related_*`` + ``supersedes``); custom relationship types and new
directional edges are deferred.

## Outcomes

- A ``## Related <Type>`` reference that resolves to the wrong artifact type, and
  a cycle in ``supersedes``, are reported with precise, file-named diagnostics and
  fail ``rac relationships --validate``.
- A live artifact of *any* type that references a retired artifact of any type is
  flagged (ADR-051), not only decisions; the ``supersedes`` exemption is
  data-driven.
- The MCP ``get_summary`` tool reports repository validation status; the four
  read-only tools are unchanged in count.

## Initiatives

### Initiative 1 — Relationship-type registry

Add ``rac.core.relationship_types`` (``EdgeSpec`` + ``REGISTRY``) declaring per
edge kind: ``range``, ``directional``, ``acyclic``, ``symmetric``, ``inverse``,
``forbids_target_status``, ``cardinality``. Domain stays ``ArtifactSpec.optional``.

### Initiative 2 — Generalized lifecycle status (ADR-051)

Add a ``retired_status`` set and a ``status`` enum to every ``ArtifactSpec``
(decision unchanged); generalize the metadata check to all types
(``invalid-<type>-status``); replace ``_is_retired_decision`` with
``_is_retired_artifact`` reading ``spec.retired_status``. Normalize the two
free-form corpus status values; backfill stays optional. Status stays an optional,
validated ``## Status`` body section (ADR-025), never frontmatter or work state.

### Initiative 3 — Range and acyclicity checks

In ``_validate``: report ``relationship-target-type-mismatch`` for a resolved,
recognized target outside the edge's range (untyped targets exempt, ADR-010); and
``relationship-cycle`` per strongly-connected component of an acyclic edge kind.
Drive the status-consistency exemption from ``EdgeSpec.forbids_target_status``.

### Initiative 4 — Validation status in get_summary

``portfolio_from_corpus`` computes the full relationship-validation gate over the
same snapshot; ``PortfolioSummary`` gains a ``validation_status`` block
(``artifacts_ok``/``relationships_ok``/``ok``), additive, surfaced by the MCP
``get_summary`` tool and ``rac portfolio``.

### Initiative 5 — Coverage and docs

Tests for range, cycles, generalized status, per-type status validation, the
registry, and ``validation_status``; the four-tool guard stays green. Register the
new test files in the CI battery (ADR-027). Document the edge registry and graph
checks in ``docs/relationships.md``; CHANGELOG.

## Constraints

- Additive (ADR-007): existing relationship codes, the decision status code, and
  the JSON contracts are unchanged; new codes and the ``validation_status`` block
  are added.
- Determinism (ADR-002): same corpus state, identical findings and ordering
  (sorted paths; Tarjan over sorted nodes).
- ADR-052: registry is code-defined; no ``.rac/relationships.yaml``, no custom
  edge types, no schema dependency.
- ADR-010 / ADR-025 / ADR-017: status stays optional and body-resident; untyped
  documents are legitimate (exempt from range); status is knowledge lifecycle,
  never work state. The MCP surface stays at four read-only tools (ADR-030).

## Non-Goals

- Custom/repo-declared relationship types; new directional edge vocabulary.
- Enforcing cardinality or materializing inverse edges (declared only).
- A status backfill of status-less artifacts; templates seeding ``## Status``.
- Transitive closure / graph queries; a fifth MCP tool.

## Implementation Contract

Pinned for v0.16.0.

### Behaviour

- ``relationship-target-type-mismatch``: a uniquely-resolved reference whose
  recognized target type is not in the edge's range. Untyped targets are exempt.
- ``relationship-cycle``: one per SCC (>1 node) of an acyclic edge kind
  (``supersedes``), carrying the component's sorted paths.
- ``relationship-target-superseded`` generalizes to all types via
  ``spec.retired_status`` and ``EdgeSpec.forbids_target_status``; the code and
  shape are unchanged.
- ``invalid-<type>-status`` for an out-of-enum status on any type;
  ``invalid-decision-status`` is unchanged.

### Interface

- No new CLI command or flag. ``rac relationships --validate`` reports the new
  issues and exits 1 when they occur. ``get_summary`` / ``rac portfolio`` gain an
  additive ``validation_status`` block.

## Success Measures

- ``rac relationships rac/ --validate`` exits 0; a fixture with a range mismatch
  or a ``supersedes`` cycle exits 1 with a precise diagnostic.
- ``rac validate rac/`` exits 0 after the two status normalizations.
- ``get_summary`` reports ``validation_status``; the four-tool guard holds.

## Risks

- Range over-firing on legitimate references. Mitigated: untyped targets exempt,
  only recognized wrong-type targets flagged.
- A second relationship-validation pass in the portfolio summary. Mitigated: it
  reuses the corpus snapshot (no extra walk) and is paid only on summary/MCP.

## Assumptions

- ``ArtifactSpec.optional`` remains the domain source of truth (v0.14.0).
- The five artifact types and the ``related_*`` + ``supersedes`` vocabulary
  remain the relationship surface.

## Related Decisions

- adr-055
- adr-051
- adr-049
- adr-016

## Related Requirements

- rac-cross-artifact-enforcement
- rac-traceability-self-relationships

## Related Roadmaps

- v0.14.0-enforcement-foundation
- v0.14.1-status-consistency
