Add ElkSharp compound node support

docs/implplan/SPRINT_20260328_003_ElkSharp_compound_sugiyama_support.md

@@ -0,0 +1,84 @@
+# Sprint 20260328-003 - ElkSharp Compound Sugiyama Support
+
+## Topic & Scope
+- Extend the native ElkSharp layered engine to support true compound nodes using the existing `ParentNodeId` model contract.
+- Keep the current layered pipeline shape for flat graphs while adding a hierarchy-aware path for compound graphs.
+- Working directory: `src/__Libraries/StellaOps.ElkSharp/`.
+- Expected evidence: focused ElkSharp compound-layout tests, flat-layout regression coverage, and workflow engine docs updated for compound-node support.
+
+## Dependencies & Concurrency
+- Depends on the current ElkSharp layered pipeline in `src/__Libraries/StellaOps.ElkSharp/`.
+- Safe cross-module edits for this sprint are limited to:
+  - `src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/`
+  - `docs/workflow/`
+
+## Documentation Prerequisites
+- `docs/code-of-conduct/CODE_OF_CONDUCT.md`
+- `docs/code-of-conduct/TESTING_PRACTICES.md`
+- `docs/workflow/ENGINE.md`
+- `src/__Libraries/StellaOps.ElkSharp/AGENTS.md`
+- `src/__Libraries/StellaOps.ElkSharp/ElkSharpLayeredLayoutEngine.cs`
+- `src/__Libraries/StellaOps.ElkSharp/ElkGraphValidator.cs`
+- `src/__Libraries/StellaOps.ElkSharp/ElkLayerAssignment.cs`
+- `src/__Libraries/StellaOps.ElkSharp/ElkNodeOrdering.cs`
+- `src/__Libraries/StellaOps.ElkSharp/ElkNodePlacement.cs`
+- `src/__Libraries/StellaOps.ElkSharp/ElkEdgeRouter.cs`
+
+## Delivery Tracker
+
+### TASK-001 - Add compound hierarchy validation and metadata
+Status: DONE
+Dependency: none
+Owners: Implementer
+Task description:
+- Replace the flat-only `ParentNodeId` rejection with strict compound validation for parent existence, cycle-free containment, and leaf-only real edges.
+- Add reusable internal hierarchy metadata so the layered engine can reason about top-level groups, descendants, ancestors, and lowest common ancestors without duplicating tree traversal logic.
+
+Completion criteria:
+- [x] Compound graphs with valid `ParentNodeId` trees are accepted
+- [x] Invalid parent references, containment cycles, and non-leaf edge endpoints are rejected deterministically
+- [x] Internal hierarchy helpers expose the data needed by ordering, placement, and routing
+
+### TASK-002 - Implement hierarchy-aware layered ordering and parent placement
+Status: DONE
+Dependency: TASK-001
+Owners: Implementer
+Task description:
+- Keep flat graphs on the existing path, but add a compound-aware path that layers and routes visible leaves while keeping siblings contiguous in each layer ordering.
+- Compute non-empty parent bounds bottom-up from child bounds plus header and padding, while preserving absolute child coordinates in the final result.
+
+Completion criteria:
+- [x] Flat graphs still use the existing path unchanged
+- [x] Compound children of the same parent stay adjacent in the ordered layers
+- [x] Parent bounds wrap descendants with header and padding and respect minimum declared width and height
+
+### TASK-003 - Add compound boundary crossings, tests, and docs
+Status: DONE
+Dependency: TASK-002
+Owners: Implementer
+Task description:
+- Insert explicit parent-boundary crossings for leaf-to-leaf edges that leave or enter compounds, keeping edges from silently skipping compound borders.
+- Add focused compound-layout tests and update workflow engine docs and ElkSharp guidance to describe the supported compound contract.
+
+Completion criteria:
+- [x] Routed edges that cross compound boundaries expose explicit boundary-crossing points
+- [x] Focused ElkSharp tests cover empty parents, nested parents, parent bounds, and invalid compound input
+- [x] `docs/workflow/ENGINE.md` and `src/__Libraries/StellaOps.ElkSharp/AGENTS.md` document compound-node support and v1 limits
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-28 | Sprint created and work started for native ElkSharp compound-node support using the existing `ParentNodeId` contract. | Implementer |
+| 2026-03-28 | Added compound hierarchy validation, compound-aware layered placement/routing, focused public-surface tests, and contract documentation updates. | Implementer |
+| 2026-03-28 | `ElkSharpCompoundLayoutTests` passed (6/6). Full renderer project still reproduces the pre-existing post-artifact `testhost` hang, and a separate flat-layout regression slice in `ElkSharpWorkflowRenderLayoutEngineTests` currently fails on this branch. | Implementer |
+
+## Decisions & Risks
+- The compound rollout is limited to strict containment trees and leaf-to-leaf real edges in v1. Parent endpoints remain invalid input.
+- Flat-graph behavior must remain stable when no node sets `ParentNodeId`.
+- Compound routing will start by adding explicit ancestor boundary crossings on top of the existing routed leaf paths so the engine can ship usable compound support without rewriting the entire router in one step.
+- Broader renderer verification on the current branch is not yet fully green: `ElkSharpCompoundLayoutTests` pass, the document-processing artifact is regenerated successfully, but the full renderer project still leaves a hung `testhost` after the artifact phase and `ElkSharpWorkflowRenderLayoutEngineTests` currently reports four flat-layout failures that need separate triage.
+
+## Next Checkpoints
+- After TASK-001: focused validator and hierarchy tests
+- After TASK-002: compound ordering and parent-bounds tests
+- After TASK-003: targeted ElkSharp renderer test project run and workflow docs update