repo-scoping/workplans/RREG-WP-0010-dependency-visualization-exploration.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
RREG-WP-0010	workplan	Dependency Visualization And Exploration	capabilities	repo-scoping	done	codex	foerster-capabilities	2026-05-03	2026-05-04	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

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

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

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

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

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

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

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

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

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

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.