Refine interactive Fabric map workplan

workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md

@@ -19,51 +19,116 @@ updated: "2026-05-18"
 ## Goal
 
 Build a clever interactive auto-layouting map over the registered Fabric
-entities so humans and agents can orient inside the infrastructure graph.
+entities so humans and agents can orient inside the infrastructure graph, while
+keeping the visualization layer reusable enough to serve other graph-producing
+repos.
 
 The current repo has static graph exports through JSON and Mermaid. That is
 useful for snapshots and docs, but it does not yet provide a navigable
 orientation surface for the registered ecosystem.
 
+Repo-scoping has already implemented the first serious local graph explorer
+shape through RREG-WP-0010 and RREG-WP-0011. Fabric should reuse those lessons
+instead of building a parallel one-off map.
+
+Reference implementation inputs:
+
+- `repo-scoping/docs/adr-dependency-graph-visualization-framework.md` selects
+  Cytoscape.js for graph-native pan, zoom, selection, styling, filtering, and
+  path exploration.
+- `repo-scoping/docs/dependency-visualization-exploration.md` defines the
+  layered graph model, display states, filter rules, manual overrides, and view
+  profiles.
+- `repo-scoping/src/repo_scoping/core/service.py` exposes Cytoscape-compatible
+  graph payloads with stable keys, metadata-rich nodes and edges, deterministic
+  show/blur/hide visibility evaluation, profile application, hidden element
+  recovery data, and visual sizing hints.
+- `repo-scoping/src/repo_scoping/web_ui/views.py` provides the current
+  interactive shell: profile controls, filter controls, manual overrides,
+  focus-by-depth, hover popups, selection details, and a layered preset layout.
+- `repo-scoping/tests/test_web_api.py` verifies the graph endpoint, ad hoc
+  filters, profile CRUD and duplicate behavior, latest-profile defaulting, and
+  UI wiring.
+
 ## Design Direction
 
-The first map should be an operational tool, not a landing page. It should open
-directly into the graph and make the current infrastructure legible through
-stable grouping, filtering, and drill-down.
+The first Fabric map should be an operational tool, not a landing page. It
+should open directly into the graph and make the current infrastructure legible
+through stable grouping, filtering, drill-down, and saved perspectives.
 
 The map should support:
 
-- force or layered auto-layout with stable seeded positions
+- force, cose, concentric, or layered auto-layout with stable seeded positions
 - grouping by domain, repo, service, capability, interface, dependency, and
   unresolved status
 - search across repo slugs, graph ids, names, capabilities, interfaces, and
   library names
-- quick filters for active services, external interfaces, missing declarations,
-  unresolved dependencies, blast radius, and dependency path
+- quick filters for review state, active services, external interfaces, missing
+  declarations, unresolved dependencies, blast radius, and dependency path
+- display states of `show`, `blur`, and `hide`, with deterministic rule
+  precedence and manual overrides
 - hover and selection detail panels with links back to registry endpoints,
   State Hub repo ids, workplans, and source files where available
-- shareable map state through URL query parameters or a copied state blob
+- saved view profiles with filter rules, manual overrides, timestamps,
+  duplicate/delete behavior, latest-profile defaulting, URL `profile_id`
+  loading, and orphaned override reporting
+- shareable map state through URL query parameters, profile ids, or a copied
+  state blob
 - graceful handling of registered-only repos that do not yet have local
   `fabric/` declarations
 
+The reusable engine should be manifest-driven. Fabric and repo-scoping should be
+able to wire the same interaction shell to different graph-producing services by
+providing a manifest that describes:
+
+- graph and profile endpoint URLs
+- node and edge identity fields
+- layer ordering and grouping fields
+- visual encodings for kind, layer, review state, lifecycle, confidence,
+  strength, freshness, and unresolved status
+- filterable fields and supported rule actions
+- detail-panel fields and deep links
+- available modes such as full graph, impact, selected path, neighborhood focus,
+  and onboarding gaps
+- profile persistence capabilities for each host application
+
 ## Architecture Notes
 
 Keep the registry as the data source. The UI should consume registry exports and
 queries rather than reloading repo files directly.
 
-Likely implementation path:
+Refined implementation path:
 
-- add a map-oriented projection endpoint or CLI export that preserves existing
-  graph ids while adding visual facets
-- serve a small local web UI from the registry service or a separate lightweight
-  static bundle
-- use a proven browser graph/layout library instead of hand-rolling physics
-- keep layout state client-side first; persist only after the workflows prove
-  useful
+- define a host-neutral graph manifest and payload contract that can represent
+  both repo-scoping dependency graphs and Fabric ecosystem graphs
+- add a Fabric map projection endpoint or CLI export that preserves existing
+  graph ids while adding visual facets expected by the engine
+- prototype a small local web UI as a reusable graph explorer shell, likely with
+  Cytoscape.js unless the transfer review finds a better fit for the
+  cross-repo contract
+- wire Fabric through an adapter manifest rather than hard-coding Fabric fields
+  throughout the UI
+- verify that a repo-scoping adapter could consume the same shell with minimal
+  glue, using RREG-WP-0010 and RREG-WP-0011 behavior as the parity target
+- decide whether the graph explorer should be extracted into a separate
+  repository after the manifest contract and first two adapters stabilize
+
+Candidate extraction shape:
+
+- working name: `graph-explorer-engine`
+- reusable package: static graph explorer assets plus TypeScript or JSON schema
+  definitions for manifests, payloads, rules, profiles, and visual facets
+- host adapters: Fabric registry adapter and repo-scoping dependency graph
+  adapter
+- host responsibilities: authentication, storage, graph projection, profile
+  persistence, and deep-link targets
+- engine responsibilities: layout, filtering, display-state evaluation if not
+  provided by host, hover and selection UI, profile control surface, focus
+  modes, and shareable state
 
 ## Tasks
 
-### T01 - Map UX And Information Architecture
+### T01 - Repo-Scoping Transfer Review
 
 ```task
 id: RAIL-FAB-WP-0008-T01
@@ -72,18 +137,24 @@ priority: high
 state_hub_task_id: "9844a9a7-f285-4523-a8d6-4ca62008ce08"
 ```
 
-Define map views, entity visual grammar, navigation behaviors, and orientation
-affordances.
+Review the repo-scoping graph implementation and turn RREG-WP-0010/RREG-WP-0011
+into concrete Fabric requirements and reusable-engine requirements.
 
 Acceptance notes:
 
-- Decide initial visual grammar for repos, services, capabilities, interfaces,
-  dependencies, bindings, libraries, and registered-only repos.
-- Decide default grouping and default filters for first load.
-- Decide whether the first implementation uses a force-directed, layered, or
-  hybrid layout.
+- Identify which repo-scoping behaviors should be reused directly: Cytoscape
+  payload shape, layered layout, show/blur/hide display states, filter rules,
+  manual overrides, view profiles, hover popups, focus depth, latest profile
+  defaulting, review-state filtering, confidence sizing, and strength sizing.
+- Identify repo-scoping-specific pieces that should remain adapter logic:
+  fact/evidence/feature/capability/ability/scope layers, impact analysis, and
+  candidate-vs-accepted semantics.
+- Decide the first Fabric visual grammar for repos, services, capabilities,
+  interfaces, dependencies, bindings, libraries, State Hub links, unresolved
+  gaps, and registered-only repos.
+- Capture a short extraction recommendation before implementation starts.
 
-### T02 - Layout-Ready Graph Projection
+### T02 - Manifest And Adapter Contract
 
 ```task
 id: RAIL-FAB-WP-0008-T02
@@ -92,16 +163,24 @@ priority: high
 state_hub_task_id: "cb0cc9f1-5225-47e5-8b47-a945c92e7168"
 ```
 
-Add or shape registry exports for map-friendly nodes, edges, groups, facets, and
-stable identifiers.
+Define the reusable graph explorer manifest, payload, filtering, and profile
+contract that lets multiple repos mount the same visualization shell.
 
 Acceptance notes:
 
-- Include registered repositories even when they have no graph snapshot yet.
-- Include node type, domain, repo, lifecycle, unresolved flags, and edge type.
-- Preserve stable ids so layout state and deep links do not churn.
+- Define required and optional graph payload fields, including `id`,
+  `stableKey`, `kind`, `layer`, label, description, source references,
+  review/lifecycle state, confidence, freshness, unresolved state, ownership,
+  visual size, edge type, edge strength, same-layer hints, and deep links.
+- Define a manifest schema for endpoints, layer order, grouping fields, style
+  tokens, detail fields, search fields, filterable fields, graph modes, profile
+  capabilities, and shareable state support.
+- Decide whether display-state evaluation lives in the host service, the engine,
+  or both with a clear precedence rule.
+- Include compatibility notes for repo-scoping's existing graph API so an
+  adapter can be added without forcing a repo-scoping rewrite.
 
-### T03 - Interactive Auto-Layout Map UI
+### T03 - Fabric Map Projection
 
 ```task
 id: RAIL-FAB-WP-0008-T03
@@ -110,36 +189,42 @@ priority: high
 state_hub_task_id: "ecd967fc-05ed-4cda-bca2-cf74e26e60b3"
 ```
 
-Build a local interactive map with layout controls, filtering, search, zoom,
-pan, and detail panels.
+Add or shape Fabric registry exports for map-friendly nodes, edges, groups,
+facets, unresolved gaps, and stable identifiers.
 
 Acceptance notes:
 
-- The first screen is the actual map.
-- Users can search, select, expand/collapse groups, and inspect details without
-  leaving the page.
-- The map remains useful with the current sparse state where many repos are
-  registered-only.
+- Include registered repositories even when they have no graph snapshot yet.
+- Include node type, domain, repo, lifecycle, State Hub ids, unresolved flags,
+  declaration source links, and edge type.
+- Preserve stable ids so layout state, profiles, and deep links do not churn.
+- Export a manifest-backed graph payload that can be consumed by the reusable
+  shell without Fabric-specific UI branches.
 
-### T04 - Operational Orientation Workflows
+### T04 - Interactive Graph Explorer Shell
 
 ```task
 id: RAIL-FAB-WP-0008-T04
 status: todo
-priority: medium
+priority: high
 state_hub_task_id: "75c1f234-026c-44ed-9c88-db39653b81e0"
 ```
 
-Add workflows for blast-radius exploration, dependency paths, unresolved gaps,
-repo grouping, and current selection sharing.
+Build the manifest-driven interactive map shell with layout controls, filtering,
+search, zoom, pan, hover popups, selection details, focus modes, and profile
+controls.
 
 Acceptance notes:
 
-- Selecting an interface can show consumers and blast radius.
-- Selecting a service can show its dependency path and provider chain.
-- Registered-only repos are visible as onboarding gaps rather than noise.
+- The first screen is the actual map.
+- Users can search, select, filter, blur, hide, focus by depth, inspect details,
+  and recover hidden or over-filtered elements without leaving the page.
+- The shell supports profile create/update/duplicate/delete where the host
+  manifest declares persistence support.
+- The map remains useful with the current sparse state where many repos are
+  registered-only.
 
-### T05 - Verification And Documentation
+### T05 - Fabric Orientation Workflows
 
 ```task
 id: RAIL-FAB-WP-0008-T05
@@ -148,12 +233,37 @@ priority: medium
 state_hub_task_id: "64fe53f1-fbea-4624-8f52-1b5e2a27cf67"
 ```
 
-Verify the map against seeded registry data, document usage, and capture
-follow-on data quality gaps.
+Add Fabric-specific workflows for blast-radius exploration, dependency paths,
+unresolved gaps, repo grouping, onboarding gaps, and shareable context.
+
+Acceptance notes:
+
+- Selecting an interface can show consumers and blast radius.
+- Selecting a service can show its dependency path and provider chain.
+- Registered-only repos are visible as onboarding gaps rather than noise.
+- Saved views can separate current operational context from backlog or
+  onboarding cleanup.
+
+### T06 - Extraction Decision, Verification, And Documentation
+
+```task
+id: RAIL-FAB-WP-0008-T06
+status: todo
+priority: medium
+state_hub_task_id: "d5567337-efe7-4fe6-8379-9e5505e25f6f"
+```
+
+Decide whether to extract the graph explorer into a separate repository, verify
+the Fabric implementation against seeded registry data, and document launch,
+refresh, manifest, and adapter usage.
 
 Acceptance notes:
 
 - Verify against the local registry after `registry/local-repos.yaml` onboarding.
 - Include at least one automated projection/API test and one UI smoke test.
+- Include an adapter parity checklist for repo-scoping against
+  RREG-WP-0010/RREG-WP-0011 behavior.
+- If extraction is recommended, propose the new repo name, source boundaries,
+  package/public API, manifest schema ownership, and migration steps.
 - Document how to launch the map and how to refresh the underlying registry
   data.