---
id: RREG-WP-0010
type: workplan
title: "Dependency Visualization And Exploration"
domain: capabilities
repo: repo-scoping
status: done
owner: codex
topic_slug: foerster-capabilities
created: "2026-05-03"
updated: "2026-05-04"
state_hub_workstream_id: "da974de8-8ef2-4df5-a357-c323f525bb2e"
---

# Dependency Visualization And Exploration

This workplan deepens the dependency graph visualization introduced in
RREG-WP-0008. The goal is to make dependency exploration useful for real
curation work: reviewers should be able to inspect graph structure, emphasize
or de-emphasize characteristic classes, hide noisy areas, preserve useful
perspectives as named view profiles, and understand facts, evidence, features,
capabilities, abilities, and scope as distinct layers.

The current Cytoscape graph is a good first slice: it exposes graph data, full
view, impact view, selected-path view, node styling, edge styling, and selection
details. The next step is to make it navigable at scale and expressive enough
for repeated curator workflows.

## Feature Model

The visualization should support three display states:

- `show`: node or edge is fully visible with normal styling and labels.
- `blur`: node or edge remains visible but appears light gray and omits
  descriptions/labels until hover or selection.
- `hide`: node or edge is removed from the active graph view.

Display states should be produced by a deterministic merge of view profile
rules, current mode, and manual overrides. Manual overrides should be reversible
and should be savable into a view profile when desired.

View profiles are named saved exploration perspectives. A profile should be able
to hold filter rules, manual node/edge overrides, mode defaults, and optional
description text. Profiles should belong to a repository first; later work can
decide whether global/shareable profiles are worth adding.

## Evidence Layer Model

```task
id: RREG-WP-0010-T01
status: done
priority: high
state_hub_task_id: "65ac4acd-e61c-4211-94b8-142fc93209bc"
```

Refine the dependency graph model so evidence is consistently represented as a
layer between facts and features where applicable, rather than appearing only as
a sibling input to capabilities.

Acceptance criteria:
- Graph serialization includes stable `layer` metadata for facts, evidence,
  features, capabilities, abilities, and scope.
- Evidence can bridge facts to features and facts to capabilities without losing
  existing approved evidence semantics.
- Existing impact propagation behavior remains compatible with the refined
  graph.
- Documentation explains when evidence points to a feature versus directly to a
  capability.

## Layered Layout And Same-Layer Edges

```task
id: RREG-WP-0010-T02
status: done
priority: high
state_hub_task_id: "e952bf83-efc3-4cb7-8abc-ac7ae00ba8e8"
```

Improve graph layout and edge rendering for layered dependency exploration.

Acceptance criteria:
- Default layout presents layers in order: facts, evidence, features,
  capabilities, abilities, scope.
- Same-layer edges use bent or curved arrows so they are visually distinct from
  upward dependency arrows.
- Same-layer edges remain flagged as normalization signals in both data and UI.
- Edge labels/tooltips expose dependency type, strength, and source.

## Graph Metadata Enrichment

```task
id: RREG-WP-0010-T03
status: done
priority: high
state_hub_task_id: "a3929bce-a2e3-4e2d-9c99-e4cc0ad2d325"
```

Enrich graph nodes and edges with the metadata needed for filtering,
inspection, and stable profile storage.

Acceptance criteria:
- Nodes expose stable keys, kind, layer, name, description, primary class,
  attributes, confidence, freshness state, ownership, and source references
  where available.
- Edges expose stable keys, dependency type, strength, source, same-layer flag,
  freshness/impact state, and source/target metadata.
- Fact nodes expose kind, path, name, value, and useful metadata-derived
  attributes.
- Payload remains Cytoscape-compatible and covered by tests.

## Filter Rule Engine

```task
id: RREG-WP-0010-T04
status: done
priority: high
state_hub_task_id: "2d51f5f5-a1e5-48ec-b297-a7376c97445c"
```

Define and implement rule-based graph filtering with `show`, `blur`, and `hide`
actions.

Acceptance criteria:
- Rules can match node/edge kind, layer, primary class, attributes, confidence,
  freshness state, ownership, dependency type, strength, same-layer flag, path,
  and text search.
- Rule precedence is deterministic and documented.
- Hide removes elements from the active view; blur keeps elements visible in
  light gray with labels/descriptions suppressed until hover or selection.
- Connected-edge behavior is explicit when a node is hidden or blurred.
- Rules can be represented as JSON for persistence and API exchange.

## Manual Visibility Overrides

```task
id: RREG-WP-0010-T05
status: done
priority: medium
state_hub_task_id: "320065c7-934d-4350-9a29-3f9cac35a6db"
```

Allow users to manually select nodes and edges and mark them as shown, hidden,
or blurred for the current exploration session.

Acceptance criteria:
- Users can apply show, blur, or hide to selected nodes and edges.
- Users can reset manual overrides without resetting filter rules.
- Manual overrides are distinguishable from rule-derived display states.
- Selected hidden items can still be recovered from a profile/editor list.

## View Profile Persistence

```task
id: RREG-WP-0010-T06
status: done
priority: high
state_hub_task_id: "95f2d2e5-b6b1-4ae3-b286-eab228372f2b"
```

Persist named dependency graph view profiles.

Acceptance criteria:
- Repository-scoped profiles can be created, listed, loaded, updated, duplicated,
  and deleted.
- Profiles store name, optional description, default graph mode, filter rules,
  manual visibility overrides, and timestamps.
- Profile storage has migrations and API coverage.
- Profiles are stable across app restarts and repository reanalysis unless
  referenced graph keys disappear, in which case orphaned overrides are surfaced.

## View Profile UI

```task
id: RREG-WP-0010-T07
status: done
priority: high
state_hub_task_id: "5f0f680f-1401-4c55-be27-cf7216efee0b"
```

Expose view profile management in the dependency graph UI.

Acceptance criteria:
- Users can select a profile, save current view as a profile, edit profile name
  and description, duplicate a profile, and delete a profile.
- Filter rules can be edited in a structured UI without requiring raw JSON for
  common cases.
- A profile summary shows active rules, manual overrides, and orphaned
  references.
- URL parameters can open a graph directly with a selected profile.

## Exploration Interaction Polish

```task
id: RREG-WP-0010-T08
status: done
priority: medium
state_hub_task_id: "9da7e01a-d192-403a-b217-4dbed6d87892"
```

Improve interactive exploration ergonomics for larger graphs.

Acceptance criteria:
- Hover temporarily reveals blurred labels and descriptions.
- Selection side panel distinguishes visible, blurred, hidden-by-rule, and
  hidden-by-manual-override states.
- Users can focus on selected node neighborhoods by depth.
- Users can clear focus without losing profile or manual override state.
- Empty and over-filtered states explain what happened and how to recover.

## API And Contract Coverage

```task
id: RREG-WP-0010-T09
status: done
priority: medium
state_hub_task_id: "4c5f69e7-878e-40a5-8997-277e232a761b"
```

Add stable API support and tests for dependency visualization and profiles.

Acceptance criteria:
- Graph endpoint supports profile selection and optional ad hoc rule payloads or
  query parameters where appropriate.
- Profile CRUD endpoints are documented in OpenAPI.
- Contract snapshot tests include profile endpoints.
- Service tests cover filter evaluation, rule precedence, and orphaned override
  behavior.
- UI tests cover profile selection, saving, manual overrides, and blur behavior
  where feasible.

## Documentation And Examples

```task
id: RREG-WP-0010-T10
status: done
priority: medium
state_hub_task_id: "6524fced-02bf-47df-a808-505fe702d7aa"
```

Document dependency visualization concepts and provide example view profiles.

Acceptance criteria:
- Documentation defines layer, display state, filter rule, manual override, and
  view profile.
- Example profiles include at least: "Scope Impact", "Hide Tooling Noise",
  "Evidence Audit", and "Same-Layer Normalization Review".
- Documentation explains cautions around hiding evidence and interpreting
  blurred context.
- The ADR for Cytoscape remains linked from visualization docs.