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

release control ui simplificatiosn

Browse Source
This commit is contained in:
master
2026-03-24 01:20:40 +02:00
parent dd29786e38
commit d788ee757e
20 changed files with 3296 additions and 855 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
docs/implplan/SPRINT_20260323_002_ElkSharp_bounded_edge_refinement.md
View File

@@ -57,18 +57,86 @@ Completion criteria:
- [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
## 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-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 |
## Decisions & Risks
- 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 refinement stage must remain deterministic and must not introduce random strategy generation or diagonal output.
- 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.
- 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