stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Archive 6 completed sprints, add 4 new ElkSharp + FE sprint plans

Browse Source 
Archived to docs-archived/implplan/:
- SPRINT_20260320_001 FE Releases Table & Wizard (4/4 DONE)
- SPRINT_20260324_001 Platform Scripts/Variables (7/7 DONE)
- SPRINT_20260323_002 ElkSharp Bounded Edge Refinement (11/11 DONE)
- SPRINT_20260328_003 ElkSharp Compound Sugiyama (3/3 DONE)
- SPRINT_20260329_006 FE Audit Menu Consolidation (12/12 DONE)
- SPRINT_20260329_007 FE Unified Stella Assistant (7/7 DONE)

New sprint plans for in-progress work:
- ElkSharp document rendering cleanup, source decomposition,
  hybrid iterative routing
- FE DevOps onboarding UX

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
master
2026-03-30 17:23:52 +03:00
parent e91cf98f8f
commit bc255188d2
10 changed files with 2301 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
docs/implplan/SPRINT_20260320_001_FE_releases_table_and_wizard.md
View File

@@ -1,114 +0,0 @@
# Sprint 20260320-001 — Releases Table + Create Release Wizard Enhancement
## Topic & Scope
- Migrate releases pipeline table to use `app-data-table` with column sorting + right-aligned `app-pagination`.
- Enhance the Create Release wizard with target selection, strategy detail configuration, and progressive delivery support.
- Working directory: `src/Web/StellaOps.Web/src/app/features/`
- Expected evidence: build passes, pages render correctly, wizard steps complete.
## Dependencies & Concurrency
- No upstream sprint dependencies.
- Task 1 (table) and Task 2 (wizard) are independent and can be done in parallel.
## Documentation Prerequisites
- `docs/modules/release-orchestrator/deployment/strategies.md` — strategy configs
- `docs/modules/release-orchestrator/progressive-delivery/ab-releases.md` — A/B models
- `docs/modules/release-orchestrator/progressive-delivery/canary.md` — canary controller
- `docs/modules/release-orchestrator/deployment/overview.md` — execution flow
## Delivery Tracker
### TASK-001 - Releases pipeline table: use app-data-table + sorting + right-aligned pager
Status: DONE
Dependency: none
Owners: FE
Task description:
- Replace the raw `<table class="stella-table">` in `releases-unified-page.component.ts` with `<app-data-table>`.
- Define columns with `sortable: true` for: Release, Stage, Gates, Risk, Evidence, Status.
- Add sort state signal + computed sorted+filtered+paged data.
- Move `<app-pagination>` to right-aligned position below the table.
- Remove manual `<thead>/<tbody>` markup — use data-table's column definitions and cell templates.
Completion criteria:
- [ ] Table renders using `app-data-table`
- [ ] Clicking column headers sorts ascending/descending
- [ ] Pagination below table, right-aligned
- [ ] Decision capsules still render in the last column
- [ ] Build passes
### TASK-002 - Create Release wizard: target selection step
Status: DONE
Dependency: none
Owners: FE
Task description:
- Add a new step between current Step 1 (Identity) and Step 2 (Components) for target selection.
- New step allows selecting: regions, environments, specific targets/hosts.
- Use existing `PlatformContextStore` for available regions/environments.
- Support multi-select with chips for selected items.
- Wire selected targets into the release draft payload.
Completion criteria:
- [ ] Wizard shows 5 steps (Identity → Targets → Components → Config → Review)
- [ ] Target selection step shows available regions/environments from context
- [ ] Selected targets appear as chips
- [ ] Selected targets included in review step summary
- [ ] Build passes
### TASK-003 - Create Release wizard: strategy detail configuration
Status: DONE
Dependency: none
Owners: FE
Task description:
- Enhance Step 3 (Config) to show strategy-specific configuration when a strategy is selected.
- **Rolling**: batch size (count or %), batch delay, stabilization time, max failed batches.
- **Canary**: canary stages (% + duration), health thresholds (success rate, error rate, latency), manual vs auto progression.
- **Blue-Green**: switchover mode (instant vs gradual with stages), warmup period, blue keepalive duration.
- **All-at-Once**: max concurrency, failure behavior (rollback/continue/pause).
- Use a collapsible "Advanced" section that expands when the user selects a strategy.
- Pre-fill with sensible defaults from docs.
Completion criteria:
- [ ] Selecting a strategy shows its specific config fields
- [ ] All 4 strategies have their documented fields
- [ ] Defaults match documentation
- [ ] Config values included in review step
- [ ] Build passes
### TASK-004 - Create Release wizard: A/B and progressive delivery support
Status: DONE
Dependency: TASK-003
Owners: FE
Task description:
- Add "A/B Release" as a 5th deployment strategy option.
- When selected, show sub-type selector: Target-Group A/B vs Router-Based A/B.
- **Target-Group A/B**: stage editor (canary → expand → shift → complete) with % and duration.
- **Router-Based A/B**: routing strategy (weight/header/cookie/tenant), traffic % stages, health thresholds.
- Add rollback configuration: auto-rollback thresholds, manual override option.
- Reference: `docs/modules/release-orchestrator/progressive-delivery/ab-releases.md`
Completion criteria:
- [ ] A/B option available in strategy dropdown
- [ ] Sub-type selection works
- [ ] Stage editor allows adding/removing stages
- [ ] Config included in review step
- [ ] Build passes
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-03-20 | Sprint created; tasks 1-3 starting immediately. | Planning |
| 2026-03-20 | All 4 tasks DONE. Table sorting + pager, wizard targets step, strategy config, A/B release. Deployed. | FE |
## Decisions & Risks
- TASK-004 depends on TASK-003 (strategy config infrastructure must exist first).
- Custom script hooks deferred to a follow-up sprint (requires backend ScriptRunner integration).
- A/B release UI is complex — may need iteration after initial implementation.
## Next Checkpoints
- TASK-001: table + sorting + pager — should be quick (1 agent)
- TASK-002 + TASK-003: wizard enhancements — can run in parallel
- TASK-004: A/B support — after TASK-003 completes

254
docs/implplan/SPRINT_20260323_002_ElkSharp_bounded_edge_refinement.md
View File

@@ -1,254 +0,0 @@
# Sprint 20260323-002 - ElkSharp Bounded Edge Refinement
## Topic & Scope
- Add a bounded deterministic edge-refinement stage to ElkSharp without replacing the existing channel and dummy-edge routing model.
- Preserve orthogonal output, backward corridor behavior, sink corridor behavior, and target anchor heuristics.
- Working directory: `src/__Libraries/StellaOps.ElkSharp/`
- Expected evidence: targeted renderer tests, direct geometry assertions, and workflow docs updated for the new layout option.
## Dependencies & Concurrency
- Depends on the current ElkSharp routing 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/ElkSharpLayeredLayoutEngine.cs`
- `src/__Libraries/StellaOps.ElkSharp/ElkEdgeRouter.cs`
- `src/__Libraries/StellaOps.ElkSharp/ElkEdgePostProcessor.cs`
## Delivery Tracker
### TASK-001 - Add module-local ElkSharp guidance and option scaffolding
Status: DONE
Dependency: none
Owners: Implementer
Task description:
Create a module-local `AGENTS.md` for ElkSharp and extend the layout option model with bounded refinement settings that default safely and deterministically.
Completion criteria:
- [x] `src/__Libraries/StellaOps.ElkSharp/AGENTS.md` exists with local routing rules
- [x] `ElkLayoutOptions` exposes bounded refinement options without changing workflow request contracts
### TASK-002 - Implement bounded orthogonal edge refinement
Status: DONE
Dependency: TASK-001
Owners: Implementer
Task description:
Add an internal refinement stage that scores routed output, detects crossing-prone edges, and tries a small fixed set of orthogonal reroute strategies while preserving corridor and anchor semantics.
Completion criteria:
- [x] Refinement is deterministic and bounded by explicit pass and trial limits
- [x] Refinement runs only for `LeftToRight` and preserves existing corridor and port-sensitive edges
- [x] Existing simplify and tighten passes still run after refinement
### TASK-003 - Add regression tests and docs
Status: DONE
Dependency: TASK-002
Owners: Implementer
Task description:
Add regression tests covering deterministic output and option gating, and update workflow documentation to note the bounded ElkSharp refinement behavior.
Completion criteria:
- [x] Targeted workflow renderer tests cover refinement determinism and `TopToBottom` stability
- [x] Workflow docs mention the bounded refinement behavior for ElkSharp best-effort layout
- [x] Sprint execution log records validation results
### TASK-004 - Tighten iterative routing rule enforcement
Status: DONE
Dependency: TASK-003
Owners: Implementer
Task description:
Follow up on the iterative multi-strategy router now present in the ElkSharp worktree to reduce false-positive highway/proximity scoring, preserve orthogonal target-entry geometry after highway spreading, and push shared corridors away from nearby nodes when the document-processing workflow exposes rule violations.
Completion criteria:
- [x] Short non-applicable highways are detected and spread without introducing new diagonals or bad target-entry angles
- [x] Long applicable shared highways are not counted as generic proximity violations in scoring/diagnostics
- [x] Outer corridor tightening respects the effective line-clearance budget used by the iterative router
- [x] Document-processing rendering artifacts are regenerated and the targeted ElkSharp test suite passes
### TASK-005 - Instrument iterative timing and plan local issue-focused optimization
Status: DONE
Dependency: TASK-004
Owners: Implementer
Task description:
Add per-attempt phase diagnostics to the iterative ElkSharp router and capture enough route-pass statistics to explain where runtime is spent. Use the resulting evidence to record a concrete optimization plan that shifts future retries away from whole-graph reroutes and toward penalized-edge or penalized-cluster repairs, with shortest-path detours called out explicitly.
Completion criteria:
- [x] The document-processing diagnostics JSON includes per-attempt phase timings and route-pass counts
- [x] The optimization plan identifies the dominant runtime phase from measured evidence
- [x] The sprint records the shortest-path detour finding and the local-repair optimization direction
### TASK-006 - Convert retry attempts to penalized-lane local repair
Status: DONE
Dependency: TASK-005
Owners: Implementer
Task description:
Replace whole-graph reroutes on iterative retry attempts with targeted repair of only the penalized edges or edge clusters. Keep attempt 1 as the global strategy candidate, force attempt 2 to prioritize shortest-path detours, and stop treating ordinary forward edges that overshoot outside the graph as protected corridor routes.
Completion criteria:
- [x] Attempt 1 remains the only full-strategy reroute per strategy
- [x] Attempt 2+ reroute only the penalized edge subset and expose that subset in diagnostics
- [x] The document-processing render shows the `Set emailDispatchFailed -> End` edge repaired to a direct L-shape instead of the previous deep detour
- [x] Targeted renderer tests and the full workflow renderer test project pass
### TASK-007 - Add gateway-specific polygon boundary landing
Status: DONE
Dependency: TASK-006
Owners: Implementer
Task description:
Replace the remaining rectangle-style landing assumptions for `Decision`, `Fork`, and `Join` nodes with gateway-specific polygon-boundary handling. Off-axis gateway entry and exit should land on the actual boundary with short diagonal stubs, gateway-specific backtracking/entry validation should stop misclassifying those routes, and rectangle-side highway detection should no longer treat gateway targets as ordinary target-side highway groups.
Completion criteria:
- [x] Gateway helper logic can project an off-axis lane to a diagonal boundary landing instead of falling back to rectangular snapping
- [x] Workflow renderer tests cover diagonal gateway exit and diagonal gateway entry against `Decision` nodes
- [x] Document-processing artifact render passes again with zero selected broken short highways and zero selected entry-angle violations
- [x] Workflow docs and module-local guidance mention the gateway-specific landing behavior
### TASK-008 - Refine gateway diagonals to avoid corner-vertex landings
Status: DONE
Dependency: TASK-007
Owners: Implementer
Task description:
Tighten the gateway-boundary helper so `Decision`, `Fork`, and `Join` nodes still allow short diagonal stubs on their side faces, but no longer land those diagonals directly on a gateway corner vertex. Any remaining corner-diagonal cases must surface as entry-angle defects so the local repair path and the document-processing artifact assertion can catch them.
Completion criteria:
- [x] Side-face gateway diagonals remain valid for off-axis entry and exit
- [x] Corner-vertex gateway diagonals are rejected and shifted onto the adjacent edge interior
- [x] The document-processing artifact test asserts zero selected gateway corner diagonals
- [x] Workflow docs and module-local guidance mention the corner-diagonal exclusion
### TASK-009 - Fix gateway target slots and repeat-corridor node safety
Status: DONE
Dependency: TASK-008
Owners: Implementer
Task description:
Finish the gateway join fix by making gateway target slots polygon-aware instead of rectangular, while keeping local repair scoped to penalized lanes. Also remove the repeat-collector loophole that let a preserved outer corridor skip node-crossing repair when the pre-corridor prefix still crossed a node.
Completion criteria:
- [x] Gateway target slot assignment uses polygon-face intersections so repaired gateway arrivals do not collapse back onto the same face rail
- [x] Restricted local repair computes target-slot spacing against the full peer set on the same target side
- [x] Repeat-collector pre-corridor prefixes can reroute into a preserved corridor when they cross a node
- [x] The document-processing artifact render passes with zero selected node crossings and zero selected target-approach joins
- [x] The full workflow renderer test project passes
### TASK-010 - Finish source-departure lane separation and placement-grid follow-up
Status: DONE
Dependency: TASK-009
Owners: Implementer
Task description:
Add a dedicated source-side same-lane rule so two edges leaving the same source face cannot silently share the same departure lane unless an explicit corridor/highway exception applies. Separate node placement spacing from the routing lattice by deriving a placement grid from the average non-terminal node size, then revalidate the document-processing artifact so the new source-side rule does not leave late boundary-angle or target-join regressions behind.
Completion criteria:
- [x] Source-departure same-lane conflicts surface as blocking shared-lane issues instead of being treated only as target-side joins or generic proximity
- [x] Left-to-right placement spacing derives from an average-node-size placement grid rather than the edge-routing lattice alone
- [x] The document-processing artifact render revalidates with zero selected shared-lane violations and no new boundary-angle or target-join regressions
### TASK-011 - Decompose oversized ElkSharp sources
Status: DONE
Dependency: TASK-010
Owners: Implementer
Task description:
Split the oversized active ElkSharp implementation files and the directly coupled Elk-specific renderer test files into concern-based partial classes so the routing logic stays behaviorally stable while the code tree becomes easier to navigate and extend.
Completion criteria:
- [x] `ElkEdgePostProcessor` is decomposed into concern-based partial files under `src/__Libraries/StellaOps.ElkSharp/`
- [x] `ElkEdgeRouterIterative` is decomposed into concern-based partial files under `src/__Libraries/StellaOps.ElkSharp/`
- [x] The oversized Elk-specific renderer tests are decomposed into partial classes without renaming tests
- [x] Elk-focused validation is rerun and the regenerated document-processing artifact is visually reviewed for regressions
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-03-23 | Sprint created and work started for bounded deterministic ElkSharp edge refinement. | Implementer |
| 2026-03-23 | Added module-local ElkSharp guidance, implemented bounded orthogonal refinement, updated `docs/workflow/ENGINE.md`, and passed `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --filter "FullyQualifiedName~ElkSharp" -v minimal` (15/15). | Implementer |
| 2026-03-23 | Reopened ElkSharp sprint work to tighten iterative-router rule enforcement for proximity/highway handling after document-processing artifact review exposed remaining violations. | Implementer |
| 2026-03-23 | Tightened iterative router spacing/highway handling, updated ElkSharp docs, regenerated the document-processing artifacts, and passed `dotnet build src/__Libraries/StellaOps.ElkSharp/StellaOps.ElkSharp.sln`, `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal`, and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore` (20/20). | Implementer |
| 2026-03-23 | Reopened TASK-004 after review of the latest artifact showed that broken short highways were still being detected but not rejected by the iterative strategy loop. | Implementer |
| 2026-03-23 | Updated the iterative acceptance loop to retry strategies when final post-processing still leaves broken short highways, regenerated the document-processing artifacts, visually inspected `elksharp.png`, and re-ran `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` plus `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore` (20/20). | Implementer |
| 2026-03-23 | Reopened TASK-004 again to extend the iterative retry gate beyond broken short highways and verify that proximity, entry-angle, label, and crossing rules are also iterated instead of remaining score-only. | Implementer |
| 2026-03-23 | Added bounded retry coverage for proximity, entry-angle, label, and crossing pressure, capped strict-mode search breadth to keep the document-processing render near 30 seconds, restored a final post-processing node-crossing cleanup, and revalidated `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` plus `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore` (20/20). | Implementer |
| 2026-03-23 | Tightened proximity participation in the bounded retry loop, reduced strict-mode search breadth to keep the artifact render near 30 seconds, restored zero-node-crossing output with a final post-processing cleanup, and re-ran `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` plus `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore` (20/20). | Implementer |
| 2026-03-23 | Temporarily disabled highway breaking/scoring in the iterative ElkSharp router to isolate whether the document-processing artifact was being distorted by false-positive highway handling, then re-ran `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1, 23s). The generated diagnostics showed `DetectedHighways=[]`, `FinalBrokenShortHighwayCount=0`, and a weaker final score (`-38677.87470033738`), indicating the visible shared-path issues are not caused solely by the highway pass. | Implementer |
| 2026-03-23 | Re-enabled highway processing, added a blocking `TargetApproachJoinViolations` rule with maximum score penalty to stop non-applicable shared arrival rails from being silently selected, updated variant artifact labels to expose the new metric, and re-ran `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1, 87s). The best fallback render improved the `End`-side collapse from 4 join violations in baseline to 1 remaining join violation, while keeping `FinalBrokenShortHighwayCount=0`. | Implementer |
| 2026-03-23 | Expanded the iterative-router pressure path from the accidental 2-attempt/4-strategy clamp to bounded multi-attempt retries with a wider finite strategy sweep, added stagnation cutoffs to avoid blind repetition, and wired the document-processing artifact test to emit `elksharp.progress.log` plus in-memory progress diagnostics so long-running strategy searches can be inspected while they are still running. A live run confirmed the new path executed `Strategy 1 attempt 1`, `attempt 2`, `attempt 3`, then advanced to `Strategy 2` instead of stopping after two attempts. | Implementer |
| 2026-03-24 | Added per-attempt phase timings and route-pass counters to the iterative diagnostics JSON, regenerated the document-processing artifact with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1, 50s), and confirmed the runtime hotspot is overwhelmingly `route-all-edges`: for the selected `reverse` strategy the three attempts spent about `45.3s` in `route-all-edges` versus about `15.9ms` in all post-processing/scoring phases combined. The same run still reported `ExcessiveDetourViolations=1` for `edge/33`, so the shortest-path issue remains unresolved and requires a local detour-repair path rather than more full-graph retries. | Implementer |
| 2026-03-26 | Tightened the long-diagonal rule from two average node-shape lengths to one average node-shape length, mirrored the renderer artifact helper to the same threshold, added a direct `Evaluation Condition -> Internal Discussion` scoring regression, and revalidated the focused ElkSharp renderer tests. The full document-processing artifact rerun cleared long-diagonal and target-join offenders, but the selected layout still fails on a separate shared-lane pair (`edge/9+edge/22`). | Implementer |
| 2026-03-26 | Added a final winner-refinement boundary-slot restabilization pass so late shared-lane cleanup cannot pull decision-source exits back off the discrete slot lattice, added a focused document-processing layout regression for boundary-slot pressure, and updated the ElkSharp docs to record the terminal slot re-snap requirement. | Implementer |
| 2026-03-26 | Tightened the node-side slot lattice into a strict terminal rule: singleton source/target endpoints now must center on their resolved face slot, preserved repeat/corridor exits are no longer exempt from the final slot snap, and strict slot repairs may bypass the generic shared-lane validator when the centered repair is still obstacle-safe and boundary-valid. Revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~BoundarySlotHelpers_When" -v minimal` (`5/5`). | Implementer |
| 2026-03-24 | Reworked iterative retry attempts to repair only penalized edges after the first full strategy pass, made attempt 2 prioritize shortest-path detours, narrowed the protected-corridor exemption so ordinary forward overshoots still qualify for detour repair, and revalidated with `dotnet build src/__Libraries/StellaOps.ElkSharp/StellaOps.ElkSharp.sln`, `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1, 22s), and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore` (20/20). The new artifact diagnostics show attempt 2+ `Mode=local-repair` with rerouted-edge counts below the full graph, and the `Set emailDispatchFailed -> End` path is now the direct L-shape instead of the previous deep outer detour. | Implementer |
| 2026-03-24 | Added late local geometry repair for node-side entry/exit angles, repeat-collector return-lane stacking, and target-side slot spacing; narrowed repeat-collector target-join scoring so the shared outer collector column is not miscounted as a target-side join; updated the backward-family regression expectations; and revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~ElkSharpWorkflowRenderLayoutEngineTests" -v minimal` (11/11) plus `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1, 32s). The regenerated document-processing artifact now reaches `NodeCrossings=0`, `BrokenShortHighways=0`, `RepeatCollectorCorridorViolations=0`, `EntryAngleViolations=0`, `TargetApproachJoinViolations=0`, and `ExcessiveDetourViolations=0`, with strategy `reverse` becoming a valid selected result. | Implementer |
| 2026-03-24 | Added a blocking target-approach-backtracking metric plus local shortest-path repair so `Execute Batch -> Check Result` no longer curls past the target side before returning, kept attempt 2+ focused on penalized lanes only, and updated the backward-family collector regression to allow the nearest loop to take the new shorter direct return while the remaining outer-loop family still stacks on shared top collector lanes. Revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenLaidOutWithElkSharp_ShouldNotBacktrackIntoCheckResult" -v minimal` (1/1) and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~LayoutAsync_WhenBackwardFamilySharesTarget_ShouldStackOuterCollectorLanes" -v minimal` (1/1). | Implementer |
| 2026-03-24 | Optimized the A* hot path by precomputing node-obstacle blocked step masks per route, replacing the closed-set `HashSet` with indexed state flags, and adding cheap soft-obstacle bounding-box rejection before exact intersection/proximity math. Measured document-processing render time dropped from `41s` test duration / `62.34s` wall clock to `3s` / `8.94s`, and the full renderer test project dropped from `1m35s` to `6s` test duration (`17.25s` wall clock). Revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore -v minimal` (21/21). | Implementer |
| 2026-03-24 | Added gateway-specific polygon-boundary landing for `Decision`/`Fork`/`Join`, including diagonal-stub projection helpers, gateway-aware boundary-angle/backtracking scoring, and exclusion of gateway targets from rectangle-style short-highway grouping. Added focused gateway regression tests, regenerated the document-processing artifact render, and revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~GatewayBoundaryHelpers_WhenDecisionAnchorIsOffAxis_ShouldProjectDiagonalStub|FullyQualifiedName~LayoutAsync_WhenDecisionSourceExitsTowardLowerBranch_ShouldUseDiagonalGatewayExit|FullyQualifiedName~LayoutAsync_WhenDecisionTargetIsReachedOffAxis_ShouldUseDiagonalGatewayEntry" -v minimal`, `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal`, and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore -v minimal` (24/24). | Implementer |
| 2026-03-24 | Tightened gateway polygon landing again so 45-degree stubs are kept on gateway side faces but not on gateway corner vertices, added helper and artifact regressions for corner-diagonal rejection, regenerated the document-processing render, visually checked `elksharp.png`, and revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~GatewayBoundaryHelpers|FullyQualifiedName~DecisionSourceExitsTowardLowerBranch|FullyQualifiedName~DecisionTargetIsReachedOffAxis|FullyQualifiedName~DocumentProcessingWorkflow_WhenLaidOutWithElkSharp_ShouldNotBacktrackIntoCheckResult" -v minimal`, `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal`, and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore -v minimal` (26/26). | Implementer |
| 2026-03-24 | Finished the gateway-face-slot and repeat-corridor safety follow-up: gateway target slots now come from polygon-face intersections instead of rectangular side slots, restricted local repair computes slot spacing against the full peer set, and above-corridor repeat collectors reroute only the pre-corridor prefix when that prefix crosses a node. Revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~GatewayBoundaryHelpers|FullyQualifiedName~DecisionSourceExitsTowardLowerBranch|FullyQualifiedName~DecisionTargetIsReachedOffAxis" -v minimal` (7/7), `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1), and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore -v minimal` (28/28). | Implementer |
| 2026-03-24 | Fixed the latest gateway-source and repeat-return regressions without widening retries back to whole-graph reroutes: gateway-source dominant-axis detours are now only asserted when a clean direct repair opportunity actually exists, the focused blocker regression keeps a right-facing gateway exit that climbs above the blocker before continuing, and the selected document-processing artifact again keeps repeat-return lanes outside the `Load Configuration` clearance band. Revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~GatewayBoundaryHelpers_WhenDecisionSourceHeadsMostlyRight_ShouldUseDirectFaceExit|FullyQualifiedName~GatewayBoundaryHelpers_WhenDecisionSourceHasBlockingNode_ShouldRepairOnlyTheLocalExitPrefix|FullyQualifiedName~GatewayBoundaryHelpers_WhenDecisionSourceAlreadyTurnsDownIntoBlocker_ShouldRecoverRightFacingExitFirst|FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (4/4) and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore -v minimal` (38/38). | Implementer |
| 2026-03-25 | Reopened ElkSharp follow-up work for the user-reported source-side same-lane conflict between `Internal Notification -> Has Recipients` and `Internal Notification -> Set internalNotificationFailed`. Added source-departure join spreading plus blocking `SharedLaneViolations`, derived placement spacing from an average-node-size placement grid, and verified the focused helper regression with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~SourceDepartureHelpers_WhenOutgoingEdgesShareTheSameDepartureLane_ShouldSpreadOnlyTheConflictingPeer" -v minimal` (1/1). The current document-processing artifact now reports `SharedLaneViolations=0` for the selected route, but still has unresolved late boundary-angle / target-join regressions (`EntryAngleViolations=6`, `TargetApproachJoinViolations=1`), so TASK-010 remains open. | Implementer |
| 2026-03-25 | Tightened the iterative local-repair planner so attempt 2+ now selects only currently failing edges plus exact conflict peers instead of padding the repair set with generic ranked edges, and added a lock-aware parallel local builder that computes candidates concurrently but serializes overlapping source/target neighborhoods before merging deterministically. Revalidated with `dotnet build src/__Libraries/StellaOps.ElkSharp/StellaOps.ElkSharp.sln -v minimal` and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (still failing in ~20s on `SharedLaneViolations=1`, `UnderNodeViolations=2`; selected offender cluster remains `edge/15+edge/17`, `edge/9`, `edge/15`). | Implementer |
| 2026-03-26 | Cleared the last document-processing handoff by letting gateway target peer-conflict candidates start from slotted feeder paths and reusing focused target-peer conflict polish during transactional final-detour repair. Revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~Debug_DumpDocumentProcessingFinalDetourOffenders" -v normal --logger "console;verbosity=normal"` (1/1) and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1, 2m42s). | Implementer |
| 2026-03-26 | Tightened non-gateway target backtracking so a short orthogonal hook that reaches the boundary for less than one node depth is treated as a forbidden fake side entry, then added a focused `Load Configuration -> Setting configParameters` regression. | Implementer |
| 2026-03-26 | Extended the same short-hook rule to gateway targets after `Internal Notification -> Has Recipients` still approached the decision from the left and only changed direction in the last few pixels. Gateway target repair/acceptance now rejects those fake face joins, and the focused workflow regression covers the decision-target case. | Implementer |
| 2026-03-26 | Closed the remaining `Load Configuration -> End` detour follow-up by letting local obstacle-skirt repair reuse interior axes from the current route and try a zero-clearance fallback before keeping a high preserved overshoot. Revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~ShortcutHelpers_WhenRectSourceCanPreserveRectTargetTopEntry_ShouldClearExcessiveDetour" -v minimal` (1/1) and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1, 2m24s). | Implementer |
| 2026-03-26 | Added a discrete node-side slot lattice so one input/output cannot silently stack on the same boundary point: gateway faces now resolve to `1` centered slot or `2` centered slots, rectangular `left`/`right` faces to at most `3` evenly spread slots, and rectangular `top`/`bottom` faces to at most `5` evenly spread slots. Wired the same capacity/assignment logic through scoring, highway/join detection, source-target slot repair, and mixed-face alternate-side repair, then revalidated `BoundarySlotHelpers_WhenNodeKindsResolveSideCapacities_ShouldSpreadSlotsEvenly`, `GatewayBoundaryHelpers_WhenGatewayJoinReceivesDirectAndElbowedLeftArrivals_ShouldSpreadTargetSlots`, `MixedNodeFaceHelpers_WhenMixedTopFaceEntriesAreOffLatticeWithoutLaneConflict_ShouldSnapToDiscreteSlots`, and `SourceDepartureHelpers_WhenOutgoingEdgesShareTheSameDepartureLane_ShouldSpreadOnlyTheConflictingPeer` (`4/4`). | Implementer |
| 2026-03-27 | Reconciled gateway-source scoring with the resolved discrete slot lattice so late winner restabilization no longer re-flags compliant singleton gateway exits. Revalidated `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~BoundarySlotHelpers_WhenDecisionSourceSlotsNeedLateRestabilization_ShouldRepairGatewayExitsAndDefaultDetours" -v minimal` (1/1) and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~BoundarySlotHelpers_When" -v minimal` (8/8). Fresh document-processing end-to-end reruns still stalled after entering the ElkSharp layout path and did not emit new progress-log updates or fresh artifacts, so full artifact revalidation remains pending. | Implementer |
| 2026-03-28 | Added focused regressions for the remaining `edge/15`/`edge/35` target-join collapse and `edge/3`/`edge/4` shared-lane collapse, then updated final restabilization to preserve a direct shared-lane repair when it lowers shared-lane violations without increasing node crossings. Trimmed the compact terminal-closure path and the winner fast-terminal candidate builder down to local-only passes after live `elksharp.progress.log` inspection showed those supposedly cheap branches were still doing heavyweight work. Revalidated `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~FinalRestabilization_WhenForkDeparturesIntoProcessAndJoinShareALane_ShouldKeepTheSharedLaneRepair|FullyQualifiedName~FinalRestabilization_WhenRepeatRightFaceTerminalRailCollapses_ShouldKeepTheJoinRepair|FullyQualifiedName~SharedLaneHelpers_WhenForkDeparturesIntoProcessAndJoinShareALane_ShouldSeparateThem|FullyQualifiedName~TargetApproachHelpers_WhenRepeatRightFaceReturnsShareTerminalRail_ShouldPushOneArrivalFartherOut" -v minimal` (`4/4`, about `2s`). Full `DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings` revalidation is still running; the updated logs now pass the previous pseudo-hang point and reach the final winner fast-terminal focus instead of stalling before it. | Implementer |
| 2026-03-28 | Decomposed `ElkEdgePostProcessor`, `ElkEdgeRouterIterative`, `ElkSharpEdgeRefinementTests`, and `DocumentProcessingWorkflowRenderingTests` into partial files. Rebuilt the Elk renderer test project successfully via `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj -v minimal`, regenerated the document-processing artifact set under `bin/Debug/net10.0/TestResults/workflow-renderings/20260328/DocumentProcessingWorkflow/`, and visually reviewed `elksharp.png` with no obvious regression from the file split. Follow-up focused `dotnet test` runs hit the existing long-lived `testhost` hang after artifact generation, so the validation evidence for this refactor is the clean rebuild plus the fresh artifact/log outputs rather than a new full-suite completion record. | Implementer |
## Decisions & Risks
- 2026-03-26: The remaining document-processing defect was not another retry-budget issue. Gateway target peer-conflict candidate building needed a slotted feeder so focused peer-conflict polish could separate same-face arrivals without restoring the final excessive detour.
- 2026-03-26 follow-up: the `Load Configuration -> Setting configParameters` edge exposed a different blind spot. The rectangular target-entry rule only validated the final boundary angle and true overshoot, so a `6px` vertical stub into the bottom face still passed as a valid `90`-degree entry. Non-gateway target backtracking now also rejects short orthogonal hooks whose final boundary-depth is less than one node shape depth, which lets the existing backtracking endpoint normalizer move the edge onto the honest side face instead of preserving the fake bottom join.
- 2026-03-26 gateway follow-up: `Internal Notification -> Has Recipients` exposed the same cheat on a decision target. Gateway target repair previously enforced only polygon-boundary contact and a valid final angle, so a long horizontal approach plus a tiny vertical drop into the diamond still passed. Gateway target validation now rejects short orthogonal last-moment hooks as invalid face joins as well. Updated docs: `docs/workflow/ENGINE.md`.
- 2026-03-26 detour follow-up: `Load Configuration -> End` exposed a separate shortest-path blind spot after the fake entry hooks were gone. Local obstacle-skirt repair sampled only expanded-obstacle edges, so it skipped the already-safe interior lane at `Y=216.59` and preserved a much higher overshoot instead. The repair now reuses usable interior axes from the current path and tries a zero-clearance fallback before settling on a preserved detour. Updated docs: `docs/workflow/ENGINE.md`, `src/__Libraries/StellaOps.ElkSharp/AGENTS.md`.
- 2026-03-26 slot-lattice follow-up: node-boundary spreading had remained heuristic, so repeated source/target/mixed-face repairs could leave multiple edges effectively concentrated on the same face point even after join and lane conflicts were removed. Boundary-slot assignment is now explicit and shared across scoring and repair: gateways use `1` or `2` centered face slots, rectangular `left`/`right` faces use at most `3`, rectangular `top`/`bottom` faces use at most `5`, and no repair is accepted unless each edge lands on its assigned realizable slot. Updated docs: `docs/workflow/ENGINE.md`, `src/__Libraries/StellaOps.ElkSharp/AGENTS.md`.
- 2026-03-26 winner-refinement follow-up: boundary-slot assignment was correct inside the terminal repair passes, but the extra winning-solution shared-lane polish could still move decision-source exits off their assigned face slots after a valid candidate had already been chosen. Winner refinement now ends with a slot-restabilization pass that re-snaps the final selected edges before return. Updated docs: `docs/workflow/ENGINE.md`, `src/__Libraries/StellaOps.ElkSharp/AGENTS.md`.
- 2026-03-26 strict-slot follow-up: the earlier lattice still treated singleton entries and preserved repeat/corridor exits as effectively advisory, so the scorer could report concentrated/off-center endpoints that the final slot snap would skip. Final boundary-slot repair now uses the same all-endpoint lattice as scoring, with side-specific port exemptions only, and it accepts centered slot repairs when they remain obstacle-safe and boundary-valid even if the generic shared-lane validator is too conservative. Updated docs: `docs/workflow/ENGINE.md`, `src/__Libraries/StellaOps.ElkSharp/AGENTS.md`.
- 2026-03-27 gateway-source follow-up: once singleton entries and exits were scored against the same centered lattice, gateway-source scoring still treated some final slotted singleton exits as invalid because it re-applied generic near-vertex / preferred-face heuristics after the slot resolver had already chosen the realizable boundary landing. Gateway-source scoring now defers to the resolved source-slot assignment for boundary-slot-compliant singleton gateway exits, while keeping hard backtracking defects blocking. Focused slot regressions are green again, but the document-processing end-to-end renderer still needs a clean non-stalled rerun before the artifact can be treated as fully revalidated.
- 2026-03-25 follow-up: the selected document-processing artifact now enforces zero below-graph lanes and zero overlong 45-degree segments, and gateway source exits are no longer allowed to leave from fork/join tip vertices. Gateway target join detection/spreading now groups arrivals by their landed boundary band instead of letting gateway arrivals slip through as highway-like exemptions. Targeted evidence: `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1 pass, refreshed 20260325 artifact). That checkpoint still left TASK-010 open; the 2026-03-26 peer-conflict fix closes it.
- There was no module-local `AGENTS.md` under `src/__Libraries/StellaOps.ElkSharp/`; this sprint adds one before code changes so the module is no longer undocumented.
- Cross-module edits are limited to workflow renderer tests and workflow engine docs because the implementation changes a shared library used by those surfaces.
- The iterative router must remain deterministic. Seeded-random strategy variants are allowed only when the seed is graph-stable so the same graph yields the same candidate set and final output.
- Updated docs: `docs/workflow/ENGINE.md`
- Module-local guidance added: `src/__Libraries/StellaOps.ElkSharp/AGENTS.md`
- Follow-up implementation is constrained to `src/__Libraries/StellaOps.ElkSharp/`, workflow renderer tests, and sprint/doc updates; unrelated worktree changes remain out of scope.
- Follow-up rule-enforcement work updated the effective strategy defaults to evaluate more deterministic candidates per render and aligned highway/proximity scoring with the actual shared-segment rule used by the iterative router.
- Final strategy acceptance now re-checks the fully post-processed candidate for broken short highways and retries the same strategy with stricter clearance instead of accepting the first node-safe route.
- Soft-rule retry coverage is now bounded: proximity, entry-angle, label, and crossing issues participate in one extra strategy retry, then the router falls back to score-based selection while preserving the zero-node-crossing cleanup and a smaller strict-mode strategy budget.
- Temporary experiment in the current worktree disables highway breaking/scoring to isolate whether false-positive highway handling is the source of the document-processing artifact; the resulting render still shows substantial shared/parallel runs, so highway logic is not the only remaining cause.
- Follow-up enforcement restores highway processing and adds a blocking target-approach-join metric with a node-crossing-scale penalty so non-applicable shared arrival rails surface explicitly in diagnostics and cannot be treated as ordinary proximity noise during strategy selection.
- The iterative router had been effectively limited to one extra retry and four strategies when baseline artifacts were present, despite `MaxAdaptationsPerStrategy=10`. That clamp is now widened to bounded multi-attempt retries with a finite 6-8 strategy sweep, plus a stagnation cutoff so the renderer does not burn time repeating non-improving adaptations.
- The document-processing artifact harness now writes `elksharp.progress.log` into the rendering output directory before layout starts, allowing direct inspection of per-strategy and per-attempt progress while the render is still running.
- Measured phase timings show that the current runtime problem is not post-processing; it is repeated full-graph routing. In the 2026-03-24 document-processing run, each strategy spent essentially all time in `route-all-edges`, with post-processing/scoring in the low-millisecond range. Any serious performance improvement must therefore reduce or reuse whole-graph routing work.
- The current shortest-path rule still fails on `edge/33` (`905.70px` routed versus `485.55px` direct Manhattan). The scoring rule catches the detour, but retries still reroute the entire graph and then select the least-bad invalid candidate. The next optimization step must add a local detour-repair phase that reroutes only the offending edge or its target-side conflict cluster while freezing the rest of the graph as hard or soft obstacles.
- Iterative retries now repair only the penalized subset of edges after the first full-strategy pass. Diagnostics record the route mode and repaired edge ids so the document-processing artifact can prove that attempt 2+ no longer reroute the whole graph.
- The previous shortest-path exemption for any edge with corridor-like bend points was too broad and hid ordinary forward overshoot artifacts such as `edge/33`. Only protected reverse/corridor routes now keep that exemption; forward overshoots are eligible for local detour repair.
- Small or protected graphs now short-circuit to the baseline route before the iterative sweep. That preserves existing sink-corridor, backward-edge, and port-anchor contracts while still allowing the larger document-processing workflow to use iterative local repair.
- Final local geometry repair now runs after iterative post-processing to enforce node-side entry/exit angles, repeat-return lane separation, and target-slot spacing without sending more edges back through A*. The document-processing artifact test now asserts zero selected broken highways, zero repeat-collector lane collapses, zero node-side angle violations, and zero disallowed target-side joins.
- The shortest-path fix now treats target-side backtracking as a blocking defect. Late local repair trims or reroutes only the offending lane, and attempt 2+ tries a direct orthogonal shortcut before falling back to a low-penalty diagonal A* candidate when another rule blocks the straight repair.
- The A* router now precomputes blocked node-step masks, which removed the repeated obstacle scan from neighbor expansion and cut document-processing route-all-edges time from the previous tens-of-seconds range to sub-second strategy attempts. Future A* optimization should extend the same idea to previously committed edge lanes: build lane-occupancy masks or blocked-segment maps for soft obstacles, and derive intermediate grid spacing from roughly one third of the average service-task width/height instead of the current fixed dense intermediate spacing.
- Gateway nodes (`Decision`, `Fork`, `Join`) now use polygon-boundary landing instead of rectangle-side snapping. Off-axis lanes are allowed to finish with short diagonal stubs on the real gateway boundary, gateway-target backtracking detection now checks only the final near-end gateway approach instead of applying rectangle-side overshoot heuristics, and rectangle-style short-highway grouping is skipped for gateway targets because those cases are governed by gateway-boundary spacing rather than shared rectangular arrival rails.
- Gateway diagonals are now restricted to gateway side faces. If a candidate lands on a gateway corner vertex, the helper shifts it onto the adjacent edge interior and the boundary-angle validator rejects any remaining corner diagonal so local repair and artifact assertions can catch it.
- Gateway target repairs now use polygon-face slot projection instead of rectangular side slots. When only a penalized subset of edges is being repaired, target-slot spacing still considers the unchanged peer edges on that same target side so the repaired edge cannot collapse back into the existing arrival rail.
- Repeat-collector edges with preserved outer corridors are no longer exempt from node-crossing repair. If the prefix that leads into the corridor crosses a node, that prefix is rerouted into the preserved corridor while the outer corridor segment remains intact.
- Gateway-source dominant-axis scoring is now opportunity-gated: a gateway source is only treated as leaving on the wrong axis when a clean downstream-facing repair opportunity actually exists. Obstacle-blocked local exits can still take a short dogleg while the document-processing artifact assertions keep them clear of blockers and out of unrelated node clearance bands.
- Long 45-degree segments are now capped at one average node-shape length instead of two. The scoring helper and the artifact-side offender detector use the same threshold so visually long diagonals cannot survive scoring while slipping past the renderer assertions.
- Tightening the diagonal cap changes candidate selection pressure in the full document-processing artifact. The current worktree clears the long-diagonal and gateway-target join regressions, but the selected layout still exposes a separate shared-lane conflict (`edge/9+edge/22`) that needs another local repair pass before the full artifact test is green again.
- The user-reported `Internal Notification` overlap was not a target-side highway issue. The previous rule set modeled target-side joins and repeat-corridor sharing, but not two edges leaving the same source face on the same departure lane. TASK-010 adds source-departure join spreading and blocking `SharedLaneViolations` for that case.
- Node placement spacing now uses a separate placement grid derived from the average non-terminal node width/height (`ResolvePlacementGrid`) instead of depending only on the routing lattice. The focused helper/layout checks are green, but the end-to-end document-processing artifact still needs a clean rerun after the late boundary-angle / target-join regressions are resolved.
- Iterative local repair now stays constrained to currently failing lanes and exact conflict peers. The planner no longer fills the repair budget with unrelated high-severity edges once the current failing rule set has been seeded.
- Per-iteration local repair candidate building can now run in parallel, but builds that share a source or target neighborhood acquire the same lock and wait instead of racing through the same local conflict zone. Current measured document-processing renders still finish in about 20 seconds, so the remaining work is repair quality for the `edge/9` / `edge/15` cluster rather than retry churn.
- 2026-03-28 runtime follow-up: the remaining slowdown was no longer in broad winner refinement. Live `elksharp.progress.log` traces showed the expensive branch had collapsed to the final winner fast-terminal focus `[edge/15, edge/3, edge/35, edge/4]`, where both the compact terminal-closure helper and the fast-terminal candidate builder were still doing heavyweight terminal/boundary work. Both paths are now restricted to local-only passes; focused geometry regressions are green again, but the full document-processing artifact still needs a completed rerun before the runtime drop and final artifact quality can be treated as revalidated.
- 2026-03-28 decomposition follow-up: active ElkSharp code is now split into concern-based partials, and the regenerated document-processing artifact still renders cleanly after the move. The remaining validation nuisance is harness-related rather than routing-related: the renderer test host can stay resident after the artifact is written, so fresh decomposition evidence is the successful project rebuild, a new `elksharp.progress.log` ending with `ElkSharp layout optimize returned`, and visual review of the regenerated `elksharp.png`.
- Optimization plan for the next pass:
1. Build a reusable immutable per-strategy routing context so grid lines, blocked segment masks, and target-slot metadata are computed once per strategy instead of once per edge route.
2. Replace global whole-graph retries for soft penalties with issue-focused repair passes: detour edge repair, target-side join repair, and proximity cluster repair.
3. Convert soft-obstacle scans to a spatial index or rasterized penalty map so `ComputeSoftObstacleCost` no longer walks all prior segments for every A* expansion.
4. Keep whole-graph strategy sweeps as candidate generation, but only run full post-processing/scoring on shortlisted candidates after cheap local repairs have converged.
## Next Checkpoints
- After TASK-002: targeted `dotnet test` run for ElkSharp renderer tests
- After TASK-003: update sprint statuses and execution log with concrete command results

172
docs/implplan/SPRINT_20260324_001_Platform_scripts_variables_validation_diff_compat.md
View File

@@ -1,172 +0,0 @@
# Sprint 20260324_001 — Scripts Library Enhancement: Variables, Validation, Diff, Compatibility
## Topic & Scope
- Add per-target variable/secret declarations to scripts, with editable UI and Monaco completions.
- Enhance Compile/Validate with real lint checks (safety, variable refs, structure) and Monaco diagnostic markers.
- Add version diff viewer using Monaco diff editor for side-by-side version comparison.
- Add deployment compatibility checker (language-target matrix, variable resolution, secret availability).
- Working directory: `src/Platform/StellaOps.Platform.WebService/`, `src/Web/StellaOps.Web/src/app/`.
- Expected evidence: backend build success, frontend build success, e2e tests pass (T10.1–T10.6).
## Dependencies & Concurrency
- No upstream sprint dependencies.
- All 5 phases implemented in a single batch (Phase 1 models first, Phases 2-5 in parallel).
## Documentation Prerequisites
- None — self-contained feature enhancement.
## Delivery Tracker
### TASK-001 - Phase 1: Models & Contracts
Status: DONE
Dependency: none
Owners: Developer
Task description:
- Add `ScriptVariableDeclaration`, `ScriptVersionDetailDto`, `CheckCompatibilityRequest`, `CompatibilityResultDto`, `CompatibilityIssue` records to backend contracts.
- Add `Variables` field to `ScriptDetail`, `ScriptSummary`, `CreateScriptApiRequest`, `UpdateScriptApiRequest`.
- Add `DeclaredVariables` to `ValidateScriptApiRequest`, `Category` to `ScriptDiagnosticDto`.
- Add corresponding TypeScript interfaces to frontend models.
- Extend `IScriptService` with `GetVersionContentAsync` and `CheckCompatibilityAsync`.
- Extend `ScriptsApi` interface with `getVersionContent`, `checkCompatibility`, and `declaredVariables` param.
Completion criteria:
- [x] All backend DTOs compile
- [x] All frontend interfaces defined
- [x] Service interface extended
### TASK-002 - Phase 2: Per-Target Variables & Secrets
Status: DONE
Dependency: TASK-001
Owners: Developer
Task description:
- Propagate variables through create/update in `InMemoryScriptService`.
- Add sample variables to seed scripts (SERVICE_URL, TIMEOUT, DB_CONNECTION, IMAGE_REF, etc.).
- Add variables editor UI in script-detail with add/remove/edit rows.
- Show user variables in script editor context panel with click-to-insert.
- Register user variable completions alongside system vars in Monaco.
Completion criteria:
- [x] Variables persisted through create/update cycle
- [x] Mock scripts include sample variables
- [x] Variables editor renders and modifies signal state
- [x] Context panel shows user variables
- [x] Monaco autocomplete includes user variables on `$` trigger
### TASK-003 - Phase 3: Enhanced Compile/Validate
Status: DONE
Dependency: TASK-001
Owners: Developer
Task description:
- Variable reference validation: scan for `${STELLA_*}`, `$env:STELLA_*`, `Environment.GetEnvironmentVariable("STELLA_*")`.
- Bash: warn if missing `set -euo pipefail`; error on `rm -rf /`.
- C#: warn on empty catch blocks.
- General: hardcoded IPs, TODO/FIXME, >500 lines.
- Improved brace matching with line numbers.
- Frontend: pass declared variables to validate, set Monaco diagnostic markers.
Completion criteria:
- [x] Backend validation returns categorized diagnostics
- [x] Frontend mock validates bash variable refs and safety
- [x] Monaco editor shows squiggly underlines from diagnostics
- [x] Markers cleared on content change
### TASK-004 - Phase 4: Script Version Diff Viewer
Status: DONE
Dependency: TASK-001
Owners: Developer
Task description:
- Store version content in `TenantState.VersionContents` on create/update.
- Implement `GetVersionContentAsync` and GET endpoint.
- Create `ScriptDiffComponent` with Monaco diff editor.
- Add route `:scriptId/diff` and "Compare" links in version history.
Completion criteria:
- [x] Version content stored per version number
- [x] GET endpoint returns version content
- [x] Diff component loads both versions and renders Monaco diff editor
- [x] Compare links navigate with correct query params
### TASK-005 - Phase 5: Deployment Compatibility Check
Status: DONE
Dependency: TASK-001
Owners: Developer
Task description:
- Language-target matrix (bash/ECS warn, PowerShell/Linux warn).
- Variable resolution against target metadata, secret availability check.
- Runtime notes for ECS and Nomad targets.
- POST endpoint for compatibility check.
- Compatibility panel in script-detail with target type dropdown and results.
Completion criteria:
- [x] Backend returns categorized compatibility issues
- [x] POST endpoint wired
- [x] UI panel toggles, sends request, displays results
- [x] Mock client implements same matrix logic
### TASK-006 - Version restore (edit older version)
Status: DONE
Dependency: TASK-004
Owners: Developer
Task description:
- Add "Edit" button on each non-current version in version history.
- Load older version content into Monaco editor via `getVersionContent()` API.
- Show warning banner when editing an old version.
- Show confirmation modal on save — "this will create a new latest version".
- Add `setContent()` method to ScriptEditorComponent.
Completion criteria:
- [x] Edit button loads older version content into editor
- [x] Warning banner visible with "Back to latest" dismiss
- [x] Modal blocks save until confirmed
- [x] After save, editingVersion resets and version list refreshes
### TASK-007 - Input field styling (Stella Ops design system)
Status: DONE
Dependency: none
Owners: Developer
Task description:
- Match all form inputs to global search style: warm `surface-tertiary` background, same border/text/height/transition.
- Fix `box-sizing: border-box` overlap bug (inputs on same row overlapping by ~10px).
- Increase grid gaps between side-by-side fields (0.5rem → 1rem).
- Document the input field convention in `src/Web/StellaOps.Web/AGENTS.md`.
Completion criteria:
- [x] All inputs use surface-tertiary background, border-primary, 34px height, 0.12s transitions
- [x] box-sizing: border-box on all inputs — no overlap
- [x] Grid gaps 1rem between fields
- [x] AGENTS.md updated with Input Field Convention section
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-03-24 | Sprint created. All 5 phases implemented. Backend + frontend build clean. | Developer |
| 2026-03-24 | Docker images rebuilt (platform + console). Stack restarted. | Developer |
| 2026-03-24 | E2E tests T10.1–T10.6 pass (7/7 including setup). | Developer |
| 2026-03-24 | TASK-006: Version restore with warning modal implemented. | Developer |
| 2026-03-24 | TASK-007: Input field styling fixed — warm bg, border-box, spacing. AGENTS.md updated with Input Field Convention. | Developer |
## Decisions & Risks
- All script storage is in-memory (`InMemoryScriptService`). No database migration required for this sprint.
- PowerShell not in `ScriptLanguageDto` enum — PowerShell-specific backend validation omitted but variable reference scanning includes `$env:STELLA_*` patterns.
- Version content storage is append-only within `TenantState`; no cleanup on version limit.
- Input overlap root cause: `box-sizing: content-box` (browser default) + `padding: 0 0.75rem` + `border: 1px` caused inputs to extend ~26px beyond their grid cell. Fix: `box-sizing: border-box` on all inputs.
## Next Checkpoints
- Integration with real `ScriptService` backed by PostgreSQL (future sprint).
- E2E tests for new features (variables editor, diff viewer, compatibility panel) — not yet covered by existing T10 suite.
## Files Modified
| File | Changes |
|------|---------|
| `src/Platform/.../Contracts/ScriptApiModels.cs` | +6 new DTOs/records, Variables on Detail/Summary/Requests |
| `src/Platform/.../Services/IScriptService.cs` | +2 methods |
| `src/Platform/.../Services/InMemoryScriptService.cs` | Variables storage, enhanced validation, version content, compatibility |
| `src/Platform/.../Endpoints/ScriptEndpoints.cs` | +2 endpoints (version content, compatibility) |
| `src/Web/.../core/api/scripts.models.ts` | +5 interfaces |
| `src/Web/.../core/api/scripts.client.ts` | +3 API methods, mock expansions, variables on scripts |
| `src/Web/.../features/scripts/script-detail.component.ts` | Variables editor, enhanced compile, compare links, compatibility panel |
| `src/Web/.../features/scripts/script-diff.component.ts` | **New** — Monaco diff viewer |
| `src/Web/.../features/scripts/scripts.routes.ts` | +1 route (diff) |
| `src/Web/.../shared/components/script-editor/script-editor.component.ts` | User variables input, diagnostic markers |
| `src/Web/.../shared/components/script-editor/script-context.ts` | User variables in completions |

84
docs/implplan/SPRINT_20260328_003_ElkSharp_compound_sugiyama_support.md
View File

@@ -1,84 +0,0 @@
# 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

50
docs/implplan/SPRINT_20260328_004_ElkSharp_document_rendering_cleanup.md Normal file
View File

@@ -0,0 +1,50 @@
# Sprint 20260328-004 - ElkSharp Document Rendering Cleanup
## Topic & Scope
- Tighten the ElkSharp document-processing render so the generated artifact is visually clean and satisfies the current hard and soft geometry rules.
- Focus on the remaining document-specific finish defects: gateway source-exit scoring opportunities, awkward default/end finish-ups, and residual fork/join shared-lane collapse.
- Working directory: `src/__Libraries/StellaOps.ElkSharp/`.
- Expected evidence: focused document renderer tests, regenerated artifact outputs, and visual review of the latest `elksharp.png`.
## Dependencies & Concurrency
- Depends on the current ElkSharp routing/post-processing 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/ElkEdgePostProcessor.GatewayBoundary.cs`
- `src/__Libraries/StellaOps.ElkSharp/ElkEdgeRouterIterative.WinnerRefinement.cs`
- `src/__Libraries/StellaOps.ElkSharp/ElkEdgeRoutingScoring.cs`
## Delivery Tracker
### TASK-001 - Clean the document-processing ElkSharp artifact
Status: DOING
Dependency: none
Owners: Implementer
Task description:
- Use the document-processing artifact test as the primary target surface and iterate on ElkSharp routing/post-processing until the remaining source-exit finish defects are removed.
- Keep changes scoped to the Elk tree and Elk-specific renderer tests, preserving deterministic routing and existing flat/compound contracts outside the document cleanup slice.
Completion criteria:
- [ ] The document-processing artifact passes the current hard and soft geometry assertions, including gateway-source scoring and shared-lane checks
- [ ] The regenerated `elksharp.png` is visually reviewed and no obvious new curl/finish-up regression is present
- [ ] Sprint execution log records the focused commands and outcomes
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-03-28 | Sprint created and work started for document-processing artifact cleanup in ElkSharp. | Implementer |
## Decisions & Risks
- The cleanup remains scoped to the Elk tree and Elk-specific renderer tests; unrelated Platform/Web changes in the worktree are explicitly out of scope.
- The artifact test is the authoritative quality gate for this slice because the user request is about the generated document rendering, not generic score improvement in abstract.
## Next Checkpoints
- After the first routing/post-processing patch: rerun the artifact inspection test and compare the remaining offender list
- Before closing the sprint: rerun the document artifact generation path, open the resulting PNG, and record the visual review

104
docs/implplan/SPRINT_20260328_005_ElkSharp_source_decomposition.md Normal file
View File

@@ -0,0 +1,104 @@
# Sprint 20260328-005 - ElkSharp Source Decomposition
## Topic & Scope
- Reduce the size and coupling of the largest active ElkSharp source files before any further document-render tuning.
- Split implementation and Elk-specific renderer tests by rule family so routing, scoring, and finalization behavior are easier to reason about and regressions are easier to localize.
- Working directory: `src/__Libraries/StellaOps.ElkSharp/`.
- Expected evidence: smaller partial source files, Elk-specific test-file splits, and focused regression test results proving no behavior drift from the refactor.
## Dependencies & Concurrency
- Depends on the current ElkSharp routing and post-processing implementation already present 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`
- `docs/implplan/SPRINT_20260323_002_ElkSharp_bounded_edge_refinement.md`
- `docs/implplan/SPRINT_20260328_003_ElkSharp_compound_sugiyama_support.md`
## Delivery Tracker
### TASK-001 - Split oversized Elk implementation files into partial modules
Status: DOING
Dependency: none
Owners: Implementer
Task description:
- Decompose the largest active ElkSharp implementation files into smaller partial files grouped by coherent routing/scoring concerns.
- Preserve behavior and signatures; the goal is structural readability and maintenance, not algorithm changes.
Completion criteria:
- [x] `ElkNodePlacement.cs` is reduced into `ElkNodePlacement.Refinement.cs` and `ElkNodePlacement.Grid.cs`
- [x] `ElkEdgePostProcessorSimplify.cs` is reduced into `ElkEdgePostProcessorSimplify.Shortcuts.cs` and `ElkEdgePostProcessorSimplify.OuterCorridors.cs`
- [x] `ElkEdgeRouterHighway.cs` is reduced into `ElkEdgeRouterHighway.Groups.cs` and `ElkEdgeRouterHighway.Paths.cs`
- [x] `ElkRepeatCollectorCorridors.cs` is reduced into `ElkRepeatCollectorCorridors.Candidates.cs` and `ElkRepeatCollectorCorridors.Rewrite.cs`
- [x] Compile baseline is restored after removing incomplete half-split artifacts in other Elk families
- [ ] Remaining large Elk families are decomposed in stable batches that keep the tree buildable after each batch
- [ ] No public contract or deterministic behavior changes are introduced by the split
### TASK-002 - Split oversized Elk-specific renderer test files
Status: TODO
Dependency: TASK-001
Owners: Implementer
Task description:
- Break the largest Elk-specific test files into partial classes organized by rule family and scenario family.
- Keep existing test names unchanged so failure signatures remain stable.
Completion criteria:
- [ ] `ElkSharpEdgeRefinementTests.Restabilization.cs` is reduced by moving rule families into dedicated partial files
- [ ] `DocumentProcessingWorkflowRenderingTests.Scenarios.cs` is reduced by moving scenario clusters/helpers into dedicated partial files
- [ ] Test discovery remains unchanged
### TASK-003 - Revalidate focused Elk regressions after structural split
Status: TODO
Dependency: TASK-001
Owners: Implementer
Task description:
- Run focused Elk renderer regressions that cover gateway boundary handling, target-join repair, repeat-return/shared-lane cleanup, and document scenario checks.
- Confirm the split is behavior-preserving before resuming rendering cleanup work.
Completion criteria:
- [ ] Focused Elk regression tests pass after the decomposition
- [ ] Execution log records the commands and outcomes
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-03-28 | Sprint created to separate source decomposition from paused document-render cleanup work. | Implementer |
| 2026-03-28 | Reduced `ElkNodePlacement.cs` into `ElkNodePlacement.Refinement.cs` and `ElkNodePlacement.Grid.cs`; reduced `ElkEdgePostProcessorSimplify.cs` into `ElkEdgePostProcessorSimplify.Shortcuts.cs` and `ElkEdgePostProcessorSimplify.OuterCorridors.cs`. | Implementer |
| 2026-03-28 | Audit of the broader split attempt found that most other decompositions existed only as untracked helper files while the original roots still owned the same methods. Those half-split artifacts were removed from both `src/__Libraries/StellaOps.ElkSharp/` and `src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/` to restore a truthful build baseline. | Implementer |
| 2026-03-28 | `dotnet build src/__Libraries/StellaOps.ElkSharp/StellaOps.ElkSharp.csproj -v minimal` passed after the half-split cleanup. | Implementer |
| 2026-03-28 | `dotnet build src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj -v minimal` passed after removing duplicate untracked test partials; only the pre-existing `NUnit1033` renderer-test warnings remain. | Implementer |
| 2026-03-28 | Re-ran `dotnet build src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj -v minimal` after the resumed safe splits and confirmed the renderer test project still builds cleanly on the restored baseline. | Implementer |
| 2026-03-28 | Reduced `ElkEdgeRouterHighway.cs` into `ElkEdgeRouterHighway.Groups.cs` and `ElkEdgeRouterHighway.Paths.cs`, and reduced `ElkRepeatCollectorCorridors.cs` into `ElkRepeatCollectorCorridors.Candidates.cs` and `ElkRepeatCollectorCorridors.Rewrite.cs`. All six files are now below the sprint cap and both build commands remained green after the batch. | Implementer |
| 2026-03-28 | Reduced `ElkEdgeRouterAStar8Dir.cs` into `ElkEdgeRouterAStar8Dir.Costs.cs` and `ElkEdgeRouterAStar8Dir.Grid.cs`. The root file is now 286 lines and both build commands stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer |
| 2026-03-28 | Reduced `ElkEdgeRouterIterative.cs` into `ElkEdgeRouterIterative.CollectorNormalization.cs` and `ElkEdgeRouterIterative.GeometryHelpers.cs`. The root file is now 166 lines and both build commands stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer |
| 2026-03-28 | Reduced `ElkEdgeRoutingGeometry.cs` into `ElkEdgeRoutingGeometry.Boundary.cs` and `ElkEdgeRoutingGeometry.Intersections.cs`. All three files are now below the sprint cap and both build commands stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer |
| 2026-03-29 | Reduced `ElkEdgeRouter.cs` into `ElkEdgeRouter.DummyReconstruction.cs`; reduced `ElkEdgePostProcessorCorridor.cs` into `ElkEdgePostProcessorCorridor.Safety.cs`; and reduced `ElkLayoutTypes.cs` into `ElkLayoutTypes.Retry.cs` and `ElkLayoutTypes.Strategy.cs`. All resulting files are below the sprint cap and both build commands stayed green after the batch, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer |
| 2026-03-29 | Reduced `ElkEdgeRouteRefiner.cs` into `ElkEdgeRouteRefiner.Helpers.cs`. The root file is now 254 lines and both build commands stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer |
| 2026-03-29 | Reduced `ElkCompoundLayout.cs` into `ElkCompoundLayout.Ordering.cs`, `ElkCompoundLayout.BoundaryCrossings.cs`, and `ElkCompoundLayout.Positioning.cs`. The root file is now 300 lines and both build commands stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer |
| 2026-03-29 | Reduced `ElkEdgeRouterIterative.Finalization.cs` into `ElkEdgeRouterIterative.Finalization.Detours.cs`, `ElkEdgeRouterIterative.Finalization.Chooser.cs`, `ElkEdgeRouterIterative.Finalization.TerminalCleanup.Round.cs`, and `ElkEdgeRouterIterative.Finalization.TerminalCleanup.Closure.cs`. All resulting files are now at or below the sprint cap and both build commands stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer |
| 2026-03-29 | Reduced `ElkShapeBoundaries.cs` into `ElkShapeBoundaries.Intersections.cs`, `ElkShapeBoundaries.GatewayInterior.cs`, `ElkShapeBoundaries.BoundarySlots.cs`, `ElkShapeBoundaries.Exterior.cs`, and `ElkShapeBoundaries.Exterior.Helpers.cs`. The ElkSharp build and the renderer test project build both stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer |
| 2026-03-29 | Reduced `ElkEdgeRouterIterative.LocalRepair.cs` into `RetryBudgets`, `Selection`, `Ordering`, `Endpoints`, `Eligibility`, `ShortestRepair`, `RepairQuality`, `ShortestPaths`, `ObstacleSkirt`, `Backtracking`, and `CollectorRestoration` partials. The root file is now 194 lines and both build commands stayed green after the split. | Implementer |
| 2026-03-29 | Reduced `ElkEdgeRouterIterative.WinnerRefinement.cs` into `Focus`, `UnderNode`, `SharedLane`, `BoundarySlots`, `TerminalClosures`, `Detours`, `FinalBoundarySlot`, `FinalRestabilized`, `LateRestabilization`, and `Promotion` partials. The root file is now 120 lines and both build commands stayed green after the split. | Implementer |
| 2026-03-29 | Reduced `ElkEdgeRouterIterative.StrategyRepair.cs` into `Evaluate`, `RouteAllEdges`, `RepairPenalizedEdges`, `VerifiedIssues`, `RepairPlan`, `RepairPlan.Expanders`, `ParallelBuilds`, and `Fingerprints` partials. The root file is now 19 lines and both build commands stayed green after the split. | Implementer |
## Decisions & Risks
- The document-render cleanup sprint remains paused while decomposition is underway; rendering quality work resumes only after the structural split is stable.
- Decomposition stays within the Elk tree and Elk-specific renderer tests so unrelated repo areas do not move during this refactor.
- Method moves are done as-is first; helper redesign is deferred unless a direct move is impossible without duplication.
- The first broad decomposition attempt was not a stable state: most of the added partial files were untracked while the original tracked roots still contained the moved methods. Keeping those files would have left the repository permanently uncompilable, so they were removed rather than carried forward.
- The current stable decomposition baseline is limited to fourteen families: `ElkNodePlacement`, `ElkEdgePostProcessorSimplify`, `ElkEdgeRouterHighway`, `ElkRepeatCollectorCorridors`, `ElkEdgeRouterAStar8Dir`, `ElkEdgeRouterIterative`, `ElkEdgeRoutingGeometry`, `ElkEdgeRouter`, `ElkEdgeRouteRefiner`, `ElkEdgePostProcessorCorridor`, `ElkLayoutTypes`, `ElkCompoundLayout`, `ElkEdgeRouterIterative.Finalization`, and `ElkShapeBoundaries`.
- The current stable decomposition baseline now also includes the three main iterative-control families: `ElkEdgeRouterIterative.LocalRepair`, `ElkEdgeRouterIterative.StrategyRepair`, and `ElkEdgeRouterIterative.WinnerRefinement`.
- The remaining implementation files above the cap are no longer the small mechanical bucket. The next files that still need work are the large helper-extraction hotspots: `ElkEdgePostProcessor`, `ElkEdgeRoutingScoring`, `ElkEdgePostProcessor.UnderNode`, `ElkEdgePostProcessor.BoundarySlots`, `ElkEdgePostProcessor.FaceConflictRepair`, and `ElkEdgePostProcessor.GatewayBoundary`.
- Two iterative-router files still exceed the target cap even after the stable split and need helper extraction rather than another blind move: `ElkEdgeRouterIterative.StrategyRepair.Evaluate.cs` and `ElkEdgeRouterIterative.StrategyRepair.RepairPlan.cs`.
- Test-file decomposition was intentionally rolled back during the cleanup because the split files duplicated tracked tests instead of replacing them. Test splitting should resume only after the code-side split discipline is stable.
- Remaining hotspot families still need careful extraction with an explicit “root trimmed in the same batch” rule: `ElkCompoundLayout`, `ElkShapeBoundaries`, `ElkEdgeRoutingScoring`, `ElkEdgeRouterAStar8Dir`, `ElkEdgeRouterIterative`, `ElkEdgePostProcessor.BoundarySlots`, `ElkEdgePostProcessor.GatewayBoundary`, `ElkEdgePostProcessor.SharedLane`, `ElkEdgePostProcessor.TargetPeerConflicts`, and `ElkEdgePostProcessor.UnderNode`.
- Focused regression revalidation has not yet been rerun on the restored baseline. No rendering-behavior conclusions should be carried over from the discarded half-split state.
## Next Checkpoints
- Decompose the next single Elk family only if the root file is trimmed in the same batch and both build commands stay green afterward
- After the next stable implementation batch: rerun focused Elk regressions and record the first valid post-cleanup results before resuming any artifact tuning

107
docs/implplan/SPRINT_20260329_006_ElkSharp_hybrid_iterative_routing.md Normal file
View File

@@ -0,0 +1,107 @@
# Sprint 20260329-006 - ElkSharp Hybrid Iterative Routing
## Topic & Scope
- Introduce an opt-in deterministic hybrid iterative router that preserves Sugiyama geometry and replaces whole-graph brute-force strategy fan-out with one baseline route plus bounded targeted repair waves.
- Keep parallel repair work intelligent and deterministic by parallelizing only independent candidate builds, then committing winners in stable order.
- Continue decomposing the iterative-router control families so the new mode lives in focused partials instead of monolithic files.
- Working directory: `src/__Libraries/StellaOps.ElkSharp/`.
- Expected evidence: new iterative-routing mode/config, hybrid parity tests, updated workflow-engine documentation, and stable builds for ElkSharp plus the renderer tests.
## Dependencies & Concurrency
- Depends on `docs/implplan/SPRINT_20260328_005_ElkSharp_source_decomposition.md` for the ongoing source split baseline.
- Safe cross-module edits for this sprint are limited to:
- `src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/`
- `docs/workflow/`
- `docs/implplan/`
## 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`
- `docs/implplan/SPRINT_20260328_005_ElkSharp_source_decomposition.md`
## Delivery Tracker
### TASK-001 - Add an opt-in hybrid deterministic iterative routing mode
Status: DOING
Dependency: none
Owners: Implementer
Task description:
- Extend the public iterative-routing options with an explicit mode switch and bounded hybrid repair controls.
- Keep the legacy multi-strategy path intact while adding a new hybrid branch that runs one baseline route, plans targeted repairs from the existing issue taxonomy, and applies them in deterministic waves.
Completion criteria:
- [x] `IterativeRoutingOptions` exposes `Mode`, `MaxRepairWaves`, and `MaxParallelRepairBuilds`
- [x] `ElkEdgeRouterIterative.Optimize` can execute a `HybridDeterministic` path without changing legacy behavior by default
- [x] Hybrid mode preserves fixed Sugiyama node geometry and remains opt-in
- [ ] Hybrid mode replaces the remaining coarse local-repair lock policy with conflict-zone-aware scheduling across the full repair pipeline
- [ ] Hybrid mode is documented as the recommended path for `LeftToRight` once parity is proven
### TASK-002 - Add deterministic hybrid parity coverage
Status: DOING
Dependency: TASK-001
Owners: Implementer
Task description:
- Freeze the first hybrid invariants in focused Elk renderer tests.
- The tests must prove deterministic replay, Sugiyama node-geometry stability, and no regression in the primary violation classes used to gate winner selection.
Completion criteria:
- [x] A focused hybrid test file exists under `src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/`
- [x] Hybrid deterministic replay is asserted by a repeated-run geometry comparison
- [x] Hybrid node geometry is asserted against legacy mode
- [x] Hybrid primary-violation counts are asserted to be no worse than legacy for the covered stress graph
- [ ] Focused hybrid parity coverage is expanded to gateway-boundary, boundary-slot, and document-processing scenarios
### TASK-003 - Continue decomposing iterative control files around the hybrid seam
Status: DOING
Dependency: TASK-001
Owners: Implementer
Task description:
- Split the iterative-router control families so the new mode remains localized and future helper extraction is tractable.
- Preserve behavior while moving methods as-is into focused partials; avoid redesigning the algorithms unless a direct move is impossible.
Completion criteria:
- [x] `ElkEdgeRouterIterative.LocalRepair.cs` is reduced to a small root coordinator
- [x] `ElkEdgeRouterIterative.WinnerRefinement.cs` is reduced to a small root coordinator
- [x] `ElkEdgeRouterIterative.StrategyRepair.cs` is reduced to a thin root plus focused partials
- [ ] `ElkEdgeRouterIterative.StrategyRepair.Evaluate.cs` is reduced below the sprint cap
- [ ] `ElkEdgeRouterIterative.StrategyRepair.RepairPlan.cs` is reduced below the sprint cap
### TASK-004 - Sync docs and execution evidence
Status: DOING
Dependency: TASK-001
Owners: Implementer
Task description:
- Update the workflow engine layout documentation to describe the new hybrid mode and its deterministic parallel-processing contract.
- Record build and targeted-test evidence in the sprint execution log.
Completion criteria:
- [x] `docs/workflow/ENGINE.md` documents the hybrid deterministic mode and its bounded parallel-build rules
- [x] Execution log records the ElkSharp build, renderer-test build, and focused hybrid test commands
- [ ] Follow-up docs describe when hybrid should become the default and how `TopToBottom` remains on legacy until parity
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-03-29 | Sprint created to isolate hybrid iterative-routing work from the ongoing source decomposition sprint. | Implementer |
| 2026-03-29 | Added `IterativeRoutingMode`, `Mode`, `MaxRepairWaves`, and `MaxParallelRepairBuilds` to the public ElkSharp iterative-routing options and threaded the new values into `IterativeRoutingConfig`. | Implementer |
| 2026-03-29 | Added `ElkEdgeRouterIterative.Hybrid.cs` and wired `ElkEdgeRouterIterative.Optimize` to execute the new hybrid deterministic path when requested. | Implementer |
| 2026-03-29 | Added focused hybrid renderer tests covering deterministic replay, stable node geometry versus legacy mode, and no increase in primary violations on the stress graph. | Implementer |
| 2026-03-29 | `dotnet build src/__Libraries/StellaOps.ElkSharp/StellaOps.ElkSharp.csproj -v minimal` passed after the hybrid mode implementation. | Implementer |
| 2026-03-29 | `dotnet build src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj -v minimal` passed after the hybrid mode implementation; only the existing `NUnit1033` warnings remain in the renderer test project. | Implementer |
| 2026-03-29 | `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --filter "Name~HybridDeterministicMode" -v normal` passed with 3/3 tests green. | Implementer |
| 2026-03-29 | Reduced `ElkEdgeRouterIterative.LocalRepair`, `ElkEdgeRouterIterative.StrategyRepair`, and `ElkEdgeRouterIterative.WinnerRefinement` into focused partials around the new hybrid seam and revalidated both builds plus the hybrid test slice. | Implementer |
## Decisions & Risks
- Hybrid mode is opt-in and does not replace legacy multi-strategy routing by default.
- Sugiyama output remains authoritative: node positions, ordering, dummy reconstruction, and upstream anchoring contracts are preserved.
- Parallel processing stays limited to candidate construction on independent repair batches. Candidate commits remain single-threaded and deterministic.
- `TopToBottom` is intentionally not promoted to hybrid mode by default in this sprint; it stays on the legacy path until parity is explicitly proven.
- The current hybrid batching still uses deterministic conflict keys derived from endpoint and collector locality. A fuller conflict-zone graph is still required before the old coarse lock-key assumptions can be removed everywhere.
- The two remaining oversize files in the iterative-control family are `ElkEdgeRouterIterative.StrategyRepair.Evaluate.cs` and `ElkEdgeRouterIterative.StrategyRepair.RepairPlan.cs`. They require helper extraction, not another blind line move.
## Next Checkpoints
- Reduce `ElkEdgeRouterIterative.StrategyRepair.Evaluate.cs` and `ElkEdgeRouterIterative.StrategyRepair.RepairPlan.cs` below the sprint cap without behavior changes.
- Expand hybrid parity coverage to gateway-boundary, boundary-slot, and document-processing regressions.
- Replace coarse repair-build lock keys with a fuller conflict-zone scheduler before considering hybrid mode as the `LeftToRight` default.

1276
docs/implplan/SPRINT_20260329_006_FE_devops_onboarding_ux.md Normal file
View File

File diff suppressed because it is too large Load Diff