Merge pull request 'Add React Flow visualization contract' (#1) from feat/react-flow-visualization-contract into test

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: corp-v1-channel-scope
 description: "Use when operating or synchronizing a Corp v1 project's Scope channel. Owns Roadmap, Epics, Features, and Ideas; correlates all six same-project channels; proactively improves evidence-based product scope; and records human approval before work enters Architecture solution design."
-version: 1.0.0
+version: 1.1.0
 author: Hermes Agent
 license: MIT
 metadata:
@@ -105,6 +105,26 @@ Lifecycle states are `Proposed`, `Approved for Solution`, `Rejected`, or `Deferr
 
 Ideas are early opportunities not yet accepted as Epics or Features. Record stable local reference, title, description, evidence/source, owner when known, status, and resulting Epic/Feature links. Preserve provenance after promotion.
 
+## React Flow visualization contract
+
+When Scope documentation contains relationship-dense data, deliberately consider a read-only `@xyflow/react` view after loading `documentation-docusaurus` and its React Flow guidance. Appropriate Scope views include:
+
+- Epic-to-Feature composition;
+- Feature-to-Feature dependencies;
+- Feature-to-question readiness relationships;
+- Requirement-to-Feature and Architecture-Decision-to-Feature traceability;
+- roadmap sequencing and a deterministic Gantt-like timeline when approved dates and lanes exist.
+
+Render a visualization only when the required relationships, dates, lanes, and states exist in validated canonical YAML and the graph materially improves comprehension. A small, linear, empty, or weakly connected dataset should remain a semantic table or list. A graph must not infer unapproved dependencies, dates, hierarchy, readiness, approval, critical path, or progress.
+
+Use one typed, deterministic adapter and the same selector to produce stable nodes, edges, legends, validation warnings, and an adjacent semantic table fallback. Generated graph data, coordinates, viewport state, and client state are derived presentation data, never a second source of truth. Preserve exact relationship semantics: questions, blockers, dependencies, decisions, approval conditions, and readiness are distinct concepts and edge types.
+
+Use Dagre for ordinary directed graphs and ELK only for complex or grouped graphs. Derive Gantt-like positions deterministically from approved dates and lanes. Use Docusaurus `BrowserOnly` where client-only rendering is required, while keeping the semantic fallback server-renderable, searchable, linkable, and usable if JavaScript or hydration fails.
+
+Documentation canvases are read-only. Disable mutation affordances, including `nodesDraggable={false}`, `nodesConnectable={false}`, connection creation, deletion, and accidental persistence. Preserve keyboard navigation, meaningful accessible labels and authoritative-record links, visible focus, non-color-only meaning, reduced-motion behavior, responsive controls, and sharp styling with `border-radius: 0`.
+
+Acceptance requires canonical-YAML validation, graph/table parity from the same selector, stable deterministic output, missing-reference failure or explicit warning behavior, empty/loading/error states, keyboard and screen-reader checks, no-JavaScript fallback, production build, browser console/network health, and remote exact-head verification. React Flow supplements the Roadmap, Epic/Feature records, and semantic tables; it never replaces governed Scope records.
+
 ## Proactive Iteration Requirement
 
 Every Scope iteration must add or materially improve at least one evidence-based scope artifact when a safe path exists: a grounded Idea, Epic, or Feature; clearer value or acceptance outcomes; dependency/risk evidence; deduplication; Roadmap reconciliation; cross-links; or a concrete unanswered product question. Never create filler to satisfy cadence.
@@ -174,4 +194,5 @@ Requires human approval for:
 - [ ] No Epic or Feature entered `Approved for Solution` without explicit human evidence.
 - [ ] Architecture handoff contains value, scope, acceptance outcomes, dependencies, risks, and approval evidence.
 - [ ] Documentation build, links, and remote readback passed.
+- [ ] When React Flow is used, its graph and semantic table share one canonical-YAML selector and pass accessibility, build, browser, and remote exact-head checks.
 - [ ] Completed work includes exact message, path, commit, URL, or run evidence.