ADR-0023: Repository Authority Model¶
Renumbered 2026-08-05 (hq-90y.2.1): originally filed as
adr-0002-repository-authority-model.md, which collided with the pre-existing, unrelatedADR-0002-runtime-capability-baseline.md(Status: Proposed). Content and decision unchanged — identity only.
| Field | Value |
|---|---|
| Status | Accepted |
| Date | 2026-07-17 |
| Author | Thomas Scola |
| Approver | Thomas Scola |
| Scope | Platform-wide — all Bluefly repositories |
Context¶
The Bluefly Agent Platform spans 26+ repositories cloned across multiple environments: a Mac development workstation, a GitLab instance (source of truth), an Oracle Cloud deployment target, and a Synology NAS for disaster recovery.
During a repository convergence audit (Workstream 0), terminology drift was discovered. Documents referred to the NAS as "canonical" interchangeably with GitLab. Branches were described as "authoritative" without specifying which authority was meant. This ambiguity led to confusion about which copy of a repository was definitive for which purpose.
The root cause: the platform lacked a formal model that distinguishes the different kinds of authority a repository copy can hold. A repository cloned on the NAS serves a fundamentally different purpose than the same repository on GitLab — but without explicit labels, operators conflated them.
This ADR establishes a permanent, platform-wide rule.
Decision¶
Every repository must explicitly define four distinct authorities. These authorities must never be conflated.
The Four Authorities¶
| Authority | Definition | Current Default |
|---|---|---|
| Development Authority | The environment where active development occurs. Code is written, tested, and iterated here. | Mac |
| Source Authority | The single source of truth for version history. All merges land here. All CI/CD pipelines read from here. | GitLab |
| Deployment Authority | The environment that runs production workloads. Artifacts are deployed here from Source Authority. | Oracle |
| Recovery Authority | The disaster recovery copy. Holds a full clone for restore purposes. Not authoritative for development, source, or deployment. | NAS |
Key Constraints¶
- Authorities are distinct. A single environment may hold only one authority for a given repository unless explicitly documented with rationale.
- Source Authority is singular. There is exactly one Source Authority per repository. If GitLab is the Source Authority, then neither the Mac clone nor the NAS clone is authoritative for version history — they are working copies and recovery copies, respectively.
- Recovery Authority is not Source Authority. The NAS holds disaster recovery clones. It is never the canonical source. Documents must not describe NAS copies as "canonical" without the qualifier "Recovery Authority."
- Development Authority does not imply Source Authority. The Mac is where code is written. That does not make it the source of truth. Unpushed commits on the Mac are development-in-progress, not authoritative history.
Consequences¶
Repository Metadata Requirements¶
Every repository in the Bluefly platform catalog must include the following metadata:
repository: <name>
authorities:
development: <environment> # Where code is actively developed
source: <environment> # Single source of truth for history
deployment: <environment> # Where production workloads run
recovery: <environment> # Disaster recovery clone
Default authority assignment (applies unless explicitly overridden):
authorities:
development: Mac
source: GitLab
deployment: Oracle
recovery: NAS
Terminology Rules¶
The following terminology is required in all Bluefly engineering documents:
| Use This | Instead Of |
|---|---|
| "Source Authority (GitLab)" | "canonical" (unqualified) |
| "Recovery Authority (NAS)" | "NAS canonical," "NAS source" |
| "Development Authority (Mac)" | "Mac canonical," "local canonical" |
| "Deployment Authority (Oracle)" | "production copy" |
| "recovery clone" | "canonical backup" |
| "working copy" | "local source" |
The word "canonical" must not appear without an explicit authority qualifier. If "canonical" is used, it must be immediately followed by the authority type — e.g., "canonical source (GitLab)" or "canonical recovery copy (NAS)."
Execution Rule¶
This execution rule governs all repository lifecycle operations:
A repository may not be archived, merged, deleted, or replaced solely because another copy exists. Instead: Authority proven → History equivalent → Remote verified → No unique worktrees → No runtime dependency → Archive → Delete. Every step must be proven.
This rule applies to all four authorities. Removing a recovery clone requires proving that recovery capability is preserved elsewhere. Removing a development clone requires proving that no active work exists in that environment. Removing a source authority requires a formal migration to a new source (which is an architectural decision, not an operational task).
Verification Data Points¶
Before any repository lifecycle operation, the following must be collected and recorded:
| # | Data Point | Purpose |
|---|---|---|
| 1 | Current branch (each authority) | Confirm branch alignment |
| 2 | HEAD commit (each authority) | Confirm history equivalence |
| 3 | Dirty state (working copies) | Prevent data loss |
| 4 | Unpushed commits (development) | Prevent losing unmerged work |
| 5 | Remote URL (each clone) | Confirm all point to the same Source Authority |
| 6 | Fetch refspec | Detect single-branch vs full clones |
| 7 | Worktrees (development copies) | Prevent destroying active parallel work |
| 8 | CI/CD dependencies | Prevent breaking pipelines |
| 9 | Runtime dependencies | Prevent breaking deployed services |
Impact on Existing Documents¶
All existing Bluefly engineering documents that reference repository authority must be updated to use the four-authority model. A terminology migration list is maintained as a companion document.
Compliance¶
All new documentation, runbooks, and automation scripts must:
- Use the four-authority terminology defined above.
- Never use "canonical" without an authority qualifier.
- Include the authority assignment in repository metadata.
- Follow the execution rule for any repository lifecycle operation.
Existing documents must be identified and migrated. See the terminology migration list (companion document).
References¶
- Workstream 0: Repository Authority Convergence (evidence collection and audit)
- ADR-0022: Bluefly Runtime Architecture — Gas City as Foundation
- Bluefly Constitution
- Bluefly Agent Platform: Repository Catalog