Skip to content

ADR-0010 — Repository Convergence Operational Authority

  • Status: Accepted
  • Date: 2026-07-10
  • Related: ADR-0007-operational-work-system-of-record.md, ADR-0003-portability-logical-authorities.md, Capability Registry CAP-REPOS-001

Context

Repository convergence — the process of ensuring all local engineering work is committed, pushed, and free of orphaned branches, AI runtime sprawl, and unknown state — has historically been performed by ad-hoc shell scripts and agent-initiated Git operations executed without an operator gate.

This model has three failure modes, all observed in practice:

  1. Blind commits. Scripts committing untracked files without proving why those files exist, who owns them, or whether they were intentionally untracked.
  2. Uninspected deletions. Branch deletions recorded only as a count ("74 branches deleted") without evidence that each branch was merged, into what, and by whom.
  3. Ownership assumption. Evicting files like .agents/, skills/, or AGENTS.md from repositories purely by filename, without proving whether the repository canonically owns those capabilities.

The "smallest stable owner" principle requires that mutation authority live in the most stable, testable, and auditable component — not in transient scripts.

As of 2026-07-10, blu-cli is the operational authority for workstation-level repository management. The capability is being migrated from ad-hoc scripts to a governed, five-command suite: blu repos audit | plan | converge | doctor | receipt.

Decision

Operational authority for repository convergence is assigned to blu-cli.

No agent, script, or automation may directly execute destructive Git operations (branch deletion, file removal, force push, history rewrite, archive) against a repository without:

  1. A structured proposed.yaml receipt produced by blu repos audit.
  2. A deterministic planned.yaml receipt produced by blu repos plan, recording the policy version and platform contract hash used.
  3. Operator gate approval for all destructive actions.
  4. A executed.yaml receipt produced by blu repos converge.
  5. A verified.yaml receipt produced by blu repos doctor, verifying reality against expected_state observations — not against actions taken.

Non-destructive operations (fetch, status, inventory, consumer search, remote lookup) remain automatic.

The operator gate is enforced by action type, not by repository. Any action classified as destructive requires explicit approval regardless of which repository it targets.

Rule

blu repos is the sole authority for repository convergence. No destructive Git operation may be executed by an agent, script, or automation without a complete proposed → planned → approved → executed → verified receipt chain.

The receipt chain is tamper-evident: each stage seals its YAML output and records its input by SHA-256 hash. Receipts are immutable. The Receipt Store location is read from platform-contract.yaml → receipt_store.

Observation fields record verbatim evidence. Classification fields record policy conclusions. These are never co-located in the same YAML block.

Consequences

What becomes true: - blu repos audit is the only entry point for convergence workflows. - blu repos plan must be deterministic: identical inventory + policy version + platform contract → identical planned.yaml. - blu repos doctor verifies observations ("does the branch exist?"), not actions ("did converge run?"). - blu repos receipt is the evidence browser; it does not execute mutations. - All 147 repositories inventoried on 2026-07-10 require re-processing through this pipeline before any destructive actions are considered complete.

What is now blocked: - Ad-hoc scripts making Git commits, deletions, or pushes without receipts. - Agents auto-committing untracked files as a default "clean" behavior. - Branch deletion without merge evidence recorded in the receipt. - AI runtime file eviction without ownership proof.

Migration: - Existing convergence_sprint.py is retired as an authoritative tool. Its output (the 147-repo inventory) remains valid as a draft proposed.yaml input, but all classifications and proposed actions must be re-derived through blu repos plan. - The blu-cli repos subcommand group is to be stubbed (all five commands) before any implementation begins, to lock the CLI surface for downstream automation.