Skip to content

Repository Topology: Hub-and-Orphan

This repository adopts the Hub-and-Orphan repository pattern as an explicit repository topology choice.

Core Topology Invariants

  1. Hub Branch as Read-Only Discovery Projection
  2. The Hub branch (default: main) is an integration and discovery projection.
  3. Direct mutations to component source files inside the Hub are strictly forbidden.

  4. Autonomous agents and human developers discover repository structure by reading contracts/repository-topology.json from the Hub branch.

  5. Orphan Branches as Independent Component Authorities

  6. Each component history lives on its own isolated Git orphan branch with no shared commit history.

  7. The orphan branch is the single source of truth and mutation authority for that component.

  8. Branch-Name Equals Mount-Path Rule

  9. For every orphan component, its Git branch name must exactly equal its mount path inside the Hub.

  10. Example: an orphan branch named docs is mounted at docs/ in the Hub.

  11. Leaf-Only Namespace Invariant

  12. Component mount paths must occupy disjoint leaf namespaces.

  13. No component mount path may be an ancestor, parent, or sub-directory of another component mount path.

  14. Self-Referencing Submodule Projection

  15. The Hub mounts orphan branches as submodules pointing back to the consumer repository itself (. or remote origin).

  16. Authority-to-Hub Synchronization Direction

  17. Mutations must be committed to the component orphan branch authority first.
  18. Once the orphan branch advances, the Hub branch updates its submodule pointer to the new commit.
  19. Synchronization is strictly unidirectional: authority -> Hub.

Machine-Readable Contract

The canonical topology declaration is defined in contracts/repository-topology.json and validated by schemas/repository-topology.schema.json.

Declaration and execution boundary

Selection declares intended consumer topology; it does not prove that Git already implements it. Composer only materializes files. It does not create or switch branches, update refs, mutate .git, run arbitrary hooks, or update remote submodules. Policy and the coding agent verify actual Git state and perform separately authorized operations. The Hub name comes from hub.branch; main is only a seed example.

Synchronization is provider-neutral. GitHub Actions may implement it, but is not part of topology identity. A projection records the immutable component commit in a submodule gitlink, then derives discovery metadata from that same gitlink. A stale projection must remain identified as stale, never become a second content authority. Rename/deletion requires an explicit authority migration and coordinated contract, gitlink, .gitmodules, and discovery updates; no automatic deletion or rename executor is provided by this component.