Recently, I've spent a good amount of time with DocC and docbuild for comparison. I must say, both are quite intimidating to get 100% right for distribution, but I could reproduce the single misbehavior that's preventing me from going forward.
After hours of fiddling, I noticed that absolute links may be interpreted as relative under a specific, yet common condition, which is when the "outer" package adds a public extension of the "inner" package. By inner/outer I follow the nomenclature used here, where outer depends on inner and outer can link to inner entities.
I created a sample repo with the motivations and the steps to reproduce the issue. I can look into a fix if you have an idea what to look at, as docbuild is not really a feasible alternative for my use case.
No worries - it can be difficult to sort out! In this case, it's in the heart of DocC itself (due to it being about symbol resolution within the markdown content, rather than the orchestration of wrangling targets and extracting symbols).