generated from coulomb/repo-seed
250 lines
8.4 KiB
Markdown
250 lines
8.4 KiB
Markdown
---
|
|
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.
|