How to govern architectural decisions across multiple repositories

Which decisions should be shared across repositories?

Share decisions when a common constraint protects an interface, security property, regulatory boundary or platform capability across several repositories. Keep local implementation choices local unless their consequences cross a repository boundary. Every shared decision should declare its owner, version, scope, precedence and adoption path. A receiving repository should be able to pin the revision it uses and record local consequences without copying the entire source record into a second, drifting document.

This creates a useful hierarchy. Global decisions describe organisation-wide constraints, platform decisions describe reusable services and APIs, and repository decisions describe local architecture. A resolver can combine them while making conflicts visible rather than letting whichever file was indexed last win.

• Pin shared authority to an explicit revision.
• Keep local owners responsible for local consequences and exceptions.
• Define precedence before repositories begin importing records.
• Detect renamed, archived or unowned shared decisions.

How can a multi-repository decision stay current?

Monitor the relationship instead of assuming that a link is enough. A shared decision should report which repositories consume it, whether each one has a compatible version, which checks are enabled and where exceptions are active. When the source changes, affected repositories can review the new consequence rather than silently inheriting it. When a repository diverges deliberately, record the local decision and its scope so the divergence remains explainable.

This is governance without centralising every implementation choice. Shared authority remains visible and versioned; local teams retain ownership of the code they operate.

What is the adoption contract for a shared decision?

A shared decision needs an adoption contract that receiving repositories can understand. Define the source revision, the scope of the rule, the local integration point, the required check, the migration window and the owner for questions. A repository should record that it consumes the decision and which local paths are affected. If it cannot adopt the rule yet, the gap should be an explicit exception with an expiry rather than an undocumented fork.

When the shared source changes, compare consequences rather than merely bumping a version. A new API boundary may require local code changes; a clarified rationale may require no code change. The resolver and evidence record should make that distinction visible to the platform owner and the local team. This is how shared authority scales without centralising every repository’s implementation details.

• Source decision and pinned revision.
• Local scope, owner and integration point.
• Required migration or enforcement evidence.
• Explicit exception when adoption is incomplete.

How should shared decisions be migrated?

Migrate a shared decision as a versioned contract. Publish the source revision, describe the changed scope or consequence, identify affected repositories and provide a migration example or check. Receiving teams should review the upgrade in their own repository, pin the revision they adopt and record an exception if they need more time. Avoid pushing a mutable live document into every agent context; reproducible authority requires a version that can be cited later.

After rollout, monitor adoption rather than assuming that a merged import means compliance. Check whether the expected local paths exist, whether the linked enforcement rule runs and whether exceptions are active or expired. A repository that cannot adopt the new rule may need a local decision, not an unbounded override. This workflow keeps shared governance explicit while allowing each team to own its implementation and risk.

• Source revision, changed consequence and migration guidance.
• Receiving repositories pin the adopted version.
• Local exceptions explain incomplete adoption and expiry.
• Post-migration checks verify scope, rules and ownership.

Do not centralise every decision

A single catalogue improves discovery but can separate local choices from the code and teams that own them. Purely local records preserve context but make cross-cutting constraints hard to distribute. A layered model keeps authority at the narrowest sensible level.

Organisation decisions may govern security, data residency or interoperability. Domain decisions may govern shared APIs. Repository decisions should cover implementation choices whose effects stay local. Each layer needs an owner and a declared scope.

Distribute versioned authority

Repositories should consume a pinned release or commit of shared decisions rather than an unversioned live feed. This makes agent retrieval and CI reproducible and allows teams to review upgrades. A central index can improve discovery, but retrieved content should resolve to the authoritative reviewed source.

• Global: regulatory, security and company-wide platform constraints.
• Domain: contracts and boundaries shared by related services.
• Repository: implementation choices owned with the code.
• Exception: narrow, approved deviation with an expiry or review date.

Make precedence deterministic

Define what happens when records conflict. A narrower decision should not silently override a mandatory higher-level control. Require an explicit exception or supersession relationship, and return the conflict to the agent and reviewer rather than selecting whichever document ranks highest semantically.

Use stable IDs across repositories and qualify them with an authority or namespace where collisions are possible. Preserve the source revision in citations so a merged change can be reconstructed later.

Roll out by risk and reuse

Begin with a small set of cross-repository decisions that teams already need repeatedly. Measure retrieval, citation accuracy, enforcement coverage and exception volume. Add federation only when ownership, update cadence and migration behaviour are clear.

AsDecided's repository-native format and deterministic interfaces provide a local foundation. A federated catalogue, organisation resolver and central exception service are additional architectural components, not prerequisites for gaining value in one repository.