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

elksharp: stabilize document-processing terminal routing

Browse Source
This commit is contained in:
master
2026-04-05 15:02:12 +03:00
parent 3a0cfcbc89
commit 1151c30e3a
11 changed files with 2946 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
docs/implplan/SPRINT_20260403_002_ElkSharp_document_processing_routing_fixes.md Normal file
View File

@@ -0,0 +1,90 @@
# Sprint 20260403-002 - ElkSharp Document Processing Routing Fixes
## Topic & Scope
- Fix the document-processing ELKSharp routing faults confirmed during artifact review: fork-to-repeat branch docking, crowded top-corridor ownership, and the email-dispatch terminal bundle into `End`.
- Keep the fixes generic to the routing pipeline rather than hard-coding document-processing edge IDs.
- Working directory: `src/__Libraries/StellaOps.ElkSharp/`.
- Expected evidence: targeted workflow renderer tests, regenerated document-processing PNG/JSON artifacts, and focused regression assertions.
## Dependencies & Concurrency
- Depends on the current ElkSharp hybrid/finalization pipeline and the discrete boundary-slot contract.
- Safe cross-module edits limited to:
- `src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/`
- `src/Workflow/__Libraries/StellaOps.Workflow.Renderer.Svg/`
- Avoid unrelated workflow library changes because the worktree already contains user edits there.
## 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`
## Delivery Tracker
### TASK-001 - Repair document-processing routing readability defects
Status: DONE
Dependency: none
Owners: Implementer
Task description:
- Apply three renderer fixes driven by the reviewed document-processing artifact: dock fork-to-repeat branch entries on a repeat/header target instead of the left-face midpoint, spread above-graph corridor lanes by ownership instead of color-only crowding, and give terminal `End` arrivals a coherent bundle so `Email Dispatch` does not collapse into the mixed face approach.
- Add regression assertions in the focused workflow renderer test project to lock the repaired geometry.
Completion criteria:
- [x] `edge/3` enters `Process Batch` from the header/top band rather than the left-face midpoint
- [x] the top corridor keeps distinct lanes for the repeat-return and long terminal sweeps
- [x] `edge/30`, `edge/32`, and `edge/33` no longer collapse into the same ambiguous `End` bundle
- [x] targeted renderer tests pass on the individual `.csproj`
### TASK-002 - Repair semantic route-family ownership for the remaining default lanes
Status: DONE
Dependency: TASK-001
Owners: Implementer
Task description:
- Fix the deeper pipeline faults still visible in the document-processing artifact after TASK-001: the direct `Parallel Execution -> Join` bypass still owns the visual fork mainline, the `Retry Decision` default and `Cooldown Timer` continuation still do not resolve as one readable setter family, and the long `End` arrivals still split between corridor and side-face terminal strategies.
- Treat the route-family fix as a cross-layer change. The ElkSharp batching and side-resolution rules must use the same semantic family model, and the SVG renderer must stop collapsing a short horizontal-plus-shallow-diagonal continuation into a tiny vertical stub.
- Add failing regression tests first for the fork primary axis, the retry/timer local setter band, the full `End` terminal family, and the SVG-path preservation rule.
Completion criteria:
- [x] `edge/4` no longer owns the fork primary axis over the work branch into `Process Batch`
- [x] `edge/9` and `edge/10` remain in one readable local setter family without a lower detour band
- [x] all document-processing arrivals into `End` use one coherent left-face terminal family
- [x] the SVG renderer preserves short readable continuations instead of collapsing them into degenerate stubs
- [x] targeted renderer tests pass on the individual `.csproj`
### TASK-003 - Polish render annotations and remove the remaining fork-bypass false positive
Status: DONE
Dependency: TASK-002
Owners: Implementer
Task description:
- Compact the SVG legend footprint, wrap long condition labels into readable badges, and remove the remaining clean fork-bypass gateway-source false positive from both scoring and artifact inspection.
- Re-attempt the document-processing top-corridor and `End` family cleanup only after the current ElkSharp winner-refinement terminal-closure loop can absorb those rewrites without reopening heavy boundary-slot and target-join pressure in the dirty worktree.
Completion criteria:
- [x] the SVG legend height is content-driven instead of fixed to the previous oversized frame
- [x] long condition labels render as wrapped badges instead of one thin over-wide strip
- [x] clean orthogonal fork-bypass paths like document-processing `edge/4` are not counted by targeted gateway-source scoring
- [x] the document-processing rerender converges with zero gateway-source diagnostics in the latest-artifact inspection path
- [x] top-corridor and `End`-family cleanup can be reintroduced without reopening boundary-slot / target-join / under-node pressure
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-04-03 | Sprint created for the confirmed document-processing routing defects after artifact review of the ELKSharp output. | Implementer |
| 2026-04-03 | Added semantic target-side docking for fork-to-repeat and non-corridored `End` arrivals, plus above-graph corridor ownership spreading to keep terminal sweeps visually distinct. | Implementer |
| 2026-04-03 | Verified targeted renderer evidence on the individual test project: artifact PNG test passed, and focused regression tests passed for branch header docking, top-corridor ownership, and end-bundle separation. | Implementer |
| 2026-04-03 | Follow-up review found the remaining root-cause defects: fork bypass mainline ownership, retry/timer setter-family fragmentation, split `End` terminal families, and SVG short-jog collapse for the cooldown continuation. | Implementer |
| 2026-04-04 | Completed the remaining route-family work: gateway-source scoring heuristics now suppress protected corridor and clean orthogonal branch exits, gateway vertex exits only count when the departure is actually problematic, and the document-processing artifact plus focused geometry/SVG guards all pass on the renderer test project. | Implementer |
| 2026-04-05 | Added content-driven SVG legend sizing, wrapped long edge-condition badges, and a direct `edge/4` fork-bypass gateway-source regression test. Targeted renderer and scorer tests pass on the individual renderer test project. | Implementer |
| 2026-04-05 | Attempted to activate the new top-corridor and `End` terminal-family hooks in the live hybrid refinement loop, but captured document-processing rerenders reopened heavy terminal-closure pressure (`boundary-slots`, `target-joins`, `under-node`) and did not converge cleanly. The hook entry points were returned to pass-through and the remaining cleanup moved to TASK-003. | Implementer |
| 2026-04-05 | Reintroduced the winner-refinement top-corridor ownership pass with score-gated cluster metrics, reactivated the `End` terminal-family cleanup, and verified the stable document-processing rerender plus latest-artifact inspection. Direct regressions now pass for overlapping repeat/end roof-lane ownership and top-family `End` sharing. | Implementer |
## Decisions & Risks
- Cross-module edits are limited to the document-processing renderer tests and the SVG renderer so the routing contract and the emitted artifact can be pinned together.
- The work must preserve deterministic routing and existing repeat-return clearance guarantees while improving readability.
- The remaining cooldown-continuation defect is partly in the SVG path cleanup, so the sprint now includes a tightly scoped renderer fix in addition to ElkSharp routing changes.
- Final verification for TASK-002 used the individual renderer test project: the full document-processing artifact regression, the retry/local-setter and terminal-family scenario guards, the latest-artifact inspection probe, and the SVG short-continuation unit test.
- TASK-003 initially exposed a real stability risk in the dirty worktree: turning the corridor and `End`-family helpers back on without extra score-gating could reopen terminal-closure pressure and stop the document-processing artifact from converging.
- That risk is now resolved by the score-gated top-corridor ownership pass plus the stabilized `End`-family rewrite: the stable 2026-04-05 rerender and latest-artifact inspection both complete with zero gateway-source, boundary-slot, under-node, shared-lane, target-join, and target-backtracking defects.
## Next Checkpoints
- Archive the sprint after the current ElkSharp worktree is ready for commit sequencing and no additional document-processing routing follow-ups are opened from the remaining soft readability review.