From 3370aa15e2e006009690f1fa605ec272f1abba6b Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 3 May 2026 13:28:34 +0200 Subject: [PATCH] New workplan for sophisticated visual exploration of dependencies --- ...10-dependency-visualization-exploration.md | 249 ++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 workplans/RREG-WP-0010-dependency-visualization-exploration.md diff --git a/workplans/RREG-WP-0010-dependency-visualization-exploration.md b/workplans/RREG-WP-0010-dependency-visualization-exploration.md new file mode 100644 index 0000000..f45aee9 --- /dev/null +++ b/workplans/RREG-WP-0010-dependency-visualization-exploration.md @@ -0,0 +1,249 @@ +--- +id: RREG-WP-0010 +type: workplan +title: "Dependency Visualization And Exploration" +domain: capabilities +repo: repo-scoping +status: active +owner: codex +topic_slug: foerster-capabilities +created: "2026-05-03" +updated: "2026-05-03" +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: todo +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: todo +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: todo +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: todo +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: todo +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: todo +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: todo +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: todo +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: todo +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: todo +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.