MSBuild: multiple projects targeting one output directory overwrite `index.md` nondeterministically

[jeffpatton1971]

Summary

When multiple projects in the same solution configure Xml2Doc_OutputDir to the same repository-level documentation directory, every project generates its own index.md. Solution builds may execute those projects concurrently, so the last Xml2Doc task to finish overwrites the indexes written by the other projects.

The resulting documentation pages may all exist, while the final index links only one project's types. Its contents can depend on project completion order.

Observed scenario

A solution contains multiple class-library projects, for example:

src/Core.Abstractions/
src/Core.Engine/
docs/

Both projects enable Xml2Doc MSBuild generation and point per-type output at the same root directory:

<Xml2Doc_OutputDir>$(SolutionDir)docs</Xml2Doc_OutputDir>

After a parallel Release build:

• Markdown pages from both projects exist under docs/.
• Each project writes docs/index.md.
• The final index.md primarily or exclusively lists the project whose task finished last.
• Rebuild order or parallel timing can change which index survives.

This was encountered in a real multi-project .NET 9 solution with a large generated API surface.

Expected behavior

Xml2Doc should either:

1. support deterministic aggregation into a shared output directory; or
2. detect that multiple project invocations target the same index and fail with a clear configuration error; or
3. provide an option to suppress per-project index generation so a repository-level aggregation step can create one index after all projects finish.

A successful build must not silently publish an incomplete, build-order-dependent index.

Actual behavior

Every project writes the same index.md independently. The last writer wins.

Suggested design

The safest initial fix may be an opt-out property such as:

<Xml2Doc_GenerateIndex>false</Xml2Doc_GenerateIndex>

A fuller solution could add a solution/repository aggregation mode that consumes multiple XML inputs, orders types canonically, and writes one index after all inputs are available.

If shared-output aggregation is not supported, detect concurrent/shared ownership rather than silently overwriting.

Acceptance criteria

• A multi-project integration test reproduces two projects targeting one output directory.
• The final index is deterministic and includes both projects, or the build fails with an actionable diagnostic.
• Parallel and serial builds produce the same result.
• Type/index ordering is stable and ordinal.
• Existing single-project behavior remains backward compatible.
• Documentation explains the supported multi-project configuration.

Related work

Issue #45 covers incremental MSBuild generation but does not address multiple projects concurrently owning the same output index.