---
schema_version: 1
id: RAC-KV02CYZ6KGTW
type: roadmap
---
# RAC v0.8.13 — Explorer Knowledge-Graph Grammar

## Status

Planned

## Context

DESIGN-knowledge-graph specifies a terminal-readable grammar for relationship
navigation: a vertical dependency chain (`A ↓ B ↓ C`), an Impact Analysis
block that frames a change ("Changing: X / May affect: …"), and a lineage
chain for an artifact's evolution. The v0.8.5 relationship views and the
v0.8.7 Links tab present all of this information, but as flat labelled lists —
`kind → label` for outgoing edges, `← label (kind)` for impact, and one line
per supersession — rather than the design's chain-and-block grammar.

This milestone reformats the Links view to the designed grammar. It is a
presentation change only: the relationships, impact, and lineage already come
from Core through the adapter (ADR-015); `render_sections` renders them
differently. No Core, service, adapter, or state change, and no new data.

## Outcomes

- The Links view reads as the knowledge graph the design describes: a vertical
  chain from the artifact to what it depends on, so "why does this exist?" is
  answered without following links across files.
- A change is framed as impact: an "Impact Analysis" block names the artifact
  being changed and lists what may be affected, answering "what happens if
  this changes?".
- Lineage reads as evolution: supersession steps render as a vertical chain,
  answering "how did this get here?".

## Initiatives

### Initiative 1 — Dependency Chain

`render_sections` renders outgoing relationships as a vertical chain rooted at
the artifact: the artifact's id, then a `↓` connector carrying each edge's
kind, then the connected artifact — the design's `A ↓ B ↓ C` form for the
common single-edge case, fanning out vertically when an artifact declares
several edges. An artifact that declares none says so in words.

### Initiative 2 — Impact Analysis Block

Incoming references render as an "Impact Analysis" block: a "Changing:" line
naming the current artifact, then a "May affect:" list of the artifacts that
depend on it. When nothing depends on the artifact, the block says so, so the
absence of downstream impact is itself legible.

### Initiative 3 — Lineage Chain

Supersession lineage renders as a vertical chain — each recorded step joined
by a `↓` connector — rather than a flat list, so an artifact's evolution reads
top to bottom. An artifact with no recorded supersession says so.

## Implementation Contract

The following decisions are pinned for v0.8.13.

### Rendering

- The change is confined to `render_sections` in
  `rac.explorer.widgets.views`, a pure function over `RelationshipsView`. It
  emits three sections — "Relationships" (the dependency chain), "Impact
  Analysis" (Changing / May affect), and "Lineage" (the supersession chain) —
  using `↓` connectors and the design's block framing. Empty sections keep
  their existing plain-language fallbacks.
- No change to `RelationshipsView`, `RelationshipLink`, the adapter, or any
  Core or service code. The context view's own relationship lines
  (`ContextState`, the Inspection tab) are unchanged; this milestone touches
  the Links view only.

### Scope

- Presentation only: no new data, no new dependencies, no new commands, and
  no change to key semantics. Terminal readability stays the priority over
  graphical complexity (DESIGN-knowledge-graph); there is no canvas.

## Non-Goals

- An interactive canvas, a graph editor, or manual relationship editing
  (DESIGN-knowledge-graph non-goals).
- Moving any relationship intelligence into the Explorer (ADR-015).
- Changing the Inspection tab's relationship lines or the adapter's rendered
  strings.

## Success Measures

- The Links view shows a `↓`-connected chain from an artifact to its declared
  relationships, an "Impact Analysis" block with "Changing:" and "May
  affect:", and a `↓`-connected lineage chain.
- Artifacts with no relationships, no dependents, or no supersession still
  render legible plain-language sections.
- No adapter, state, or Core test changes; the relationship intelligence is
  unchanged and only its presentation differs.

## Assumptions

- The Links view remains the home for relationship navigation (v0.8.7); the
  Inspection tab keeps its own concise relationship summary.
- `RelationshipsView` already carries everything the grammar needs (outgoing,
  impact, lineage); no additional Core fields are required.

## Risks

- Fan-out readability: an artifact with many edges produces a long vertical
  list; the chain stays readable because each edge is one connector and one
  target, and terminal readability is the explicit priority.
- Chain ambiguity for multiple kinds: the `↓` connector carries the edge kind,
  so a fan-out remains unambiguous without a graphical layout.

## Related Decisions

- ADR-015

## Related Designs

- explorer-knowledge-graph

## Related Requirements

- rac-product-knowledge-navigator-explorer

## Dependencies

- v0.8.5 explorer relationship navigation
- v0.8.7 explorer visual overhaul
