Re-evaluate monorepo↔split-repo workflow overhead

[tomgrv]

Context

This repo maintains each src/<feature> in a single monorepo but also redistributes each one to its own standalone repo (e.g. devcontainer-features-act, devcontainer-features-gitutils, etc.) via .github/workflows/split-monorepo.yml, with changes synced back via merge-monorepo.yml. This is confirmed to be intentional, load-bearing infrastructure — this issue is not a proposal to remove it, but to evaluate and document it so the operational cost is visible and understood.

Problem

The split/merge mechanism adds real operational overhead:

• Cross-repo PRs opened automatically on every split target.
• GitHub App token management for cross-repo write access.
• Two-way sync (monorepo → split repos via split-monorepo.yml, split repos → monorepo via merge-monorepo.yml) that must stay conflict-free.

There's currently no documentation explaining why the split exists (e.g. consumer expectations, GHCR publishing requirements, discoverability) versus relying solely on GHCR's per-feature image tagging from the monorepo directly.

Proposal

• Add documentation (e.g. in .github/workflows/split-monorepo.yml comments or a short architecture note) explaining the concrete reason the split-repo distribution is needed, so future contributors don't mistake it for incidental complexity.
• Identify any failure modes in the current sync (e.g. what happens on merge conflicts between monorepo and split repo) and whether they're handled today.
• If, after documenting it, there's a lower-overhead alternative that preserves the same guarantees, propose it — but only as a follow-up, not as part of this issue.

Acceptance criteria

• Written rationale for the split-repo mechanism exists somewhere discoverable (workflow comments or a doc).
• Known failure modes of the sync are identified and either handled or explicitly accepted as out of scope.