Render traceability links according to the target document context

[dieterbaier]

Problem

The generated traceability matrix currently emits file-based AsciiDoc links such as xref:../path/to/artifact.adoc#anchor[ID] from source artifact paths. This is correct for a source-oriented multi-file view, but it breaks when the matrix is included in a rendered single-page architecture document.

Observed in the consuming dieterbaier/profile project at https://architecture.dieterbaier.eu/: the deployed architecture page is a single index.html, but traceability links render to paths like ../doc-01000-introduction-and-goals.html#introduction-and-goals or ../../canvas/canvas-001-business-model.html#business-model-canvas. Those target files are not part of the published architecture output.

The same generator pattern exists in the toolkit in scripts/validate-metamodel.rb, TraceabilityMatrixGenerator#artifact_link, where the target is derived from the artifact source path relative to the generated matrix file.

Expected behavior

Traceability generation should be aware of the rendering target context:

• if the target artifact is included in the final rendered document, render an anchor-only xref such as xref:adr-001-asciidoc-primary-source[ADR-001-asciidoc-primary-source];
• if the target artifact is not included in the final rendered document, do not render a broken in-document link;
• optionally render plain text plus a repository/source link for non-included artifacts, if the configured output target supports that safely;
• keep source-oriented generated views possible where file-based xrefs are actually intended.

Implementation notes

The generator probably needs a notion of an "included artifact set" for a rendered aggregate document. In profile, the aggregate architecture document includes arc42 chapters, ADRs, quality scenarios, risks, Q&A, and the traceability matrix, but currently not the canvases and some source documents. The link renderer should choose between anchor-only xrefs and non-linked/source-linked labels based on that set.

The solution approach should apply both here and in the consuming dieterbaier/profile project, and the fix should be implemented in both projects when this is addressed.

Acceptance criteria

• Generated traceability matrix output can target a single-page rendered document without creating relative .html#... links to files that are not deployed.
• Included artifacts use anchor-based xrefs in the same document.
• Non-included artifacts are rendered without broken links, or with explicit configured repository/source links.
• Tests cover included and non-included targets.
• The dogfood example and consuming profile project can use the same approach.

[dieterbaier]

Related consuming-project issue: dieterbaier/profile#20

The solution approach should apply to both repositories. When fixing this, please update the toolkit behavior and apply/adapt it in dieterbaier/profile as well.