Capability Convergence Framework¶

Capabilities naturally fall toward their smallest stable owner.

Every maintained artifact—whether it is code, infrastructure, CI pipelines, configuration, documentation, operational procedures, data models, AI agents, or policies—is assumed to be a temporary capability custodian until a responsibility resolution is performed. Local implementations are temporary capability custodians. Their default trajectory is toward upstream ownership.

The engineering job is to remove artificial resistance to capability gravity. For example: - Docker should own containers. - Git should own history. - PostgreSQL should own persistence. - Prometheus should own metrics. - Terraform should own infrastructure. - Kubernetes should own orchestration. - The operating system should own scheduling.

[!IMPORTANT] The Central Invariant Responsibility should always converge toward the smallest stable owner capable of providing the required capability without degrading governance, security, observability, or operational behavior.

[!IMPORTANT] The Continuous Invariant Capability Convergence is continuous, not event-driven. Every significant change to a maintained artifact should trigger re-evaluation of its ownership.

The Ownership Hierarchy¶

This framework defines a strict architectural hierarchy to differentiate what a capability is, from who is responsible for it, who enforces it, and where it lives:

Capability: What is being provided.
Owner: Who is responsible.
Authority: What enforces it.
Custodian: Where it temporarily resides.

Hierarchy Examples¶

Capability	Owner	Authority	Custodian
Repository history	Version Control	Git	Local repository
Container lifecycle	Container Runtime	Docker	Docker Engine
Infrastructure state	Infrastructure	Terraform	Terraform state backend
Secret management policy	Bluefly Security	Bluefly Standards	Governance engine
Secret storage	Secrets Platform	1Password	Runtime injection

Ownership Decomposes by Dimension¶

"X owns it" is never precise enough. For any artifact under evaluation, resolve the owner per dimension — they are rarely the same party:

Dimension	Question
Capability	Who provides the underlying capability?
Implementation	Whose code realizes it?
Documentation	Where is the behavioral authority written?
Integration	Who wires it into our platform?
Runtime	Where does it execute?
Lifecycle	Who is allowed to change its state, and with what commands?

Worked example — the beads issue prefix: capability → Beads (upstream); implementation → bd database config, seeded by gt provisioning; documentation → upstream beads/Gas City docs; integration → Bluefly (dolt-runtime-data-plane-policy (NOT_FOUND — policy never committed)); runtime → Oracle rig databases; lifecycle → bd lifecycle commands only. Collapsing those six answers into "Bluefly owns it" is what produces duplicate authorities and unrepairable drift.

The curator's measure of success is the number of things Bluefly no longer has to own — while the things we intentionally own become higher quality and fully traceable.

The Core Governing Question¶

Every maintained artifact must be continuously evaluated against a single governing question:

"Who should be responsible for this capability?"

Authority becomes evidence used to answer that question. Everything else follows from that answer.

When evaluating current custody, use these guiding questions to challenge ownership: 0. What capability are we actually evaluating? (Evaluate the capability, not the artifact) 1. Can the nearest owner own this? 2. Can the upstream project own this? 3. Can another established authority own this? 4. Can composition replace implementation? 5. What governance capability requires retaining ownership? 6. What future capability removes this ownership?

Definition: Smallest Stable Owner¶

Smallest Stable Owner: The lowest layer in the architecture that can provide a capability with equivalent or superior functional behavior, governance, security, observability, and operational characteristics while minimizing long-term ownership and maintenance.

Architectural State vs. Execution State¶

This framework explicitly separates Architectural State (what is logically true about the artifact) from Execution State (what operations intends to do with it). - Architectural decisions (like "Retire" or "Transfer") are derived purely from capability convergence. - Execution decisions (like "Quarantine" or "Delete") are operational processes executed after the architectural state changes.

Capability Ownership Resolution Order¶

Every capability must resolve responsibility using the following hierarchy:

Nearest Existing Owner
Upstream Project
Established External Authority
Composition of Existing Authorities
Governance Layer
Local Custom Implementation (Custodian)

[!IMPORTANT] Immutable Accountability Rule Authority may move; accountability may not. Transferring a capability transfers implementation responsibility, but the audit itself remains accountable for demonstrating that the transfer was valid. A capability may only move downward through the ownership hierarchy when every higher authority has been shown unable to own it.

Upstream Platform Integration Gate¶

Binding process law: Upstream Capability Discovery (UCD) — alias Smallest Stable Owner. Run a Capability Audit with evidence before any Bluefly code.

When integrating Open Source Software or upstream platforms, engineers shall first determine whether the requested capability already exists as native functionality, configuration, plugin, provider, middleware, extension point, or officially supported integration. Bluefly code may only implement domain-specific behavior after all upstream ownership has been exhausted and documented with evidence.

This gate is a specific application of the Resolution Order above: levels 1–5 must be proven insufficient before level 6 (Local Custom Implementation) is reached.

Discovery order (investigate in sequence, stop at the first level that satisfies the requirement):

Level	Question	If YES
1. Native	Does upstream already own this (CLI, config, built-in)?	Use it. No Bluefly code.
2. Config	Can desired state be expressed in upstream config?	Commit desired state only.
3. Extension	Does upstream expose a plugin, provider, or hook?	Implement only the extension.
4. SDK / API	Official SDK, OpenAPI, MCP, or documented integration?	Wrap / compose — do not replace.
5. Ecosystem	Does upstream intentionally delegate (OAuth, OTEL, S3)?	Use the delegated project.
6. Custom	Only after 1–5 exhausted with documented evidence	Adapter / domain logic only.

Evidence requirement: Before any Level 6 code is proposed, a Capability Audit row must document why levels 1–5 were insufficient, with linked evidence (docs URLs, CLI output, source references). Absence of memory is not absence of capability — searches must be recorded.

The Convergence Algorithm¶

Capability convergence is a fixed-point recursive algorithm. Evaluate ownership iteratively:

repeat
    identify capability
    identify current custodian
    identify candidate owner
    validate equivalent capability
    if validated
        transfer responsibility
until no smaller stable owner exists

Retention Categories¶

If a capability must remain in the custody of a local implementation, it must be justified by exactly one of the following retention categories:

Reason for Retention	Meaning
Capability Gap	No existing authority can currently provide the capability.
Governance	The capability enforces organization-specific policy or decision-making.
Integration	The capability composes multiple authoritative systems without becoming a replacement authority.
Transitional	Temporary bridge during a planned migration with a documented exit condition.

[!CAUTION] Composition vs. Duplication Do not assume that because an upstream authority has a feature (e.g., GitLab has SAST), the local implementation must be deleted. Always ask: Can composition replace implementation?

Sometimes the answer is no. For example, GitLab owns Secret Detection and Dependency Scanning. Bluefly may legitimately own a governance component that composes those capabilities into an organization-specific policy. That isn't duplicate scanning; that's organizational governance. Those are different capabilities.

Principle: Governance composes existing authorities; it should not reimplement them.

Compositional Confidence Scoring¶

Architectural judgments must be strictly separated from observations, and confidence must be compositional.

Observation → Evidence → Verification → Confidence → Architectural Conclusion

The conclusion inherits its confidence from the verification of evidence.

Evidence Matrix Format¶

Audits must record findings in the following format:

Observation	Evidence	Conclusion
Workspace search returned zero references	Task-1426	No runtime consumers identified
CodeGraph provides relationship indexing	`.codegraph/`	Relationship capability can be delegated

Confidence Scoring Example¶

Major claims must be scored independently. The final architectural decision is derived from these verified claims.

Claim	Confidence
Zero dependencies	`VERIFIED`
Replacement validation	`VERIFIED`
Authority resolution	`VERIFIED`
RETIRE	`DERIVED`

Capability Convergence Framework¶

When evaluating an artifact, follow this standard governance process:

Discover capabilities.
Resolve responsibility via the recursive algorithm.
Verify the replacement (using Evidence Matrices and Confidence Scoring).
Measure remaining responsibilities via Retention Categories.
Continue resolving until no smaller stable owner exists.
Only then decide whether the artifact's Architectural State should change to RETIRE.
Let operational processes determine the Execution State (Archived, Quarantined, merged, handed off, or Deleted).

The Lifecycle States¶

The complete path from discovery to deletion incorporates validation and quarantine windows:

DISCOVER → CLASSIFY → RESOLVE → VERIFY → MONITOR → RETIRE (Architectural State) → QUARANTINE (Execution State) → DELETE CANDIDATE → DELETE → ARCHIVE EVIDENCE

Time-Bounded Quarantine¶

Quarantine is not a permanent holding area. Every quarantined artifact MUST include: * Entry Date * Review Cadence * Exit Condition * Maximum Lifetime * Owner

The Regeneration Test (required gate before RETIRE)¶

A delete-first philosophy is only safe if a removed capability can come back. No artifact may move to RETIRE — and no execution process may DELETE it — until an executable regeneration path has been proven to work, not merely assumed to exist. This closes the largest hole in convergence: deleting a capability that has no way to be reconstituted.

Every convergence decision resolves through this six-step lifecycle. Each step has a required, recorded evidence artifact; a missing artifact halts the process at that step.

Step	Question	Required Evidence
1	What capability is this?	Capability identified (not the artifact — the capability)
2	Who is the canonical owner?	Upstream documentation or organizational standard
3	Is there an upstream implementation?	Verified implementation exists
4	Is there an executable regeneration path?	Generator / installer / pipeline proven to run
5	Is the artifact disposable?	Delete + regenerate demonstrably preserves the capability
6	Verdict	`DELETE` / `CONVERGE` / `KEEP` / `QUESTION`

[!IMPORTANT] Production Removal Rule Nothing is removed from a production system until you can answer: "If this capability disappears today, what upstream system is already enforcing it?" A production deletion is never "remove file." It is "remove local ownership because the canonical upstream owner already regenerates or enforces the capability." Every change must be reversible and evidence-based.

Verdict Taxonomy¶

The convergence verdict is one of four values. DELETE and CONVERGE are fundamentally different engineering operations and must not be conflated.

Verdict	Meaning	Precondition
DELETE	The capability disappears because it should not exist.	No requirement remains; nothing upstream to converge to.
CONVERGE	Local ownership disappears while the capability remains, because an upstream authority owns it.	Upstream owner verified (Steps 3–5); the capability is preserved.
KEEP	Local code is orchestration of the upstream owner (installs/configures/invokes it, adds organizational defaults) and does not reimplement the capability.	Retention category Integration or Governance applies.
QUESTION	The verdict cannot be issued yet.	See sub-states below.

QUESTION sub-states: - BLOCKED_EXTERNAL — the verdict depends on an external authority whose intent is not yet verified (e.g. is the GitLab push rule intended as the sole branch-naming authority?). Do not converge until confirmed. - GOVERNANCE — the capability exists and has no upstream owner that subsumes it; where it runs (push gate / CI gate / scheduled report / off) is a policy choice, not a convergence. - OPERATOR — no upstream owner exists; keep-or-drop is an operator maintenance-burden decision, and dropping means explicitly accepting the loss of the check.

You are not deleting capabilities. You are deleting local ownership. CONVERGE is the default outcome for a required capability with a verified upstream owner; DELETE is reserved for capabilities that should not exist at all.

Orphaned Capabilities Are Ownership-Discovery Candidates¶

A capability with no regeneration path and no upstream owner is not a deletion candidate. It is an ownership-discovery candidate. Its lack of a regeneration path tells you it is one of two things, and the Regeneration Test deliberately refuses to decide which until the question is answered:

a legitimate Bluefly organizational capability that deserves a canonical generator, or
accumulated technical debt with no justified owner.

The correct action for an orphan is to open an ownership question (assign a candidate owner and decide 1 vs 2), never a silent deletion.

Migrate Once, at the Generator¶

When a capability is converged onto a generator (installer, template, pipeline), all downstream drift is fixed once, in the generator — never in each generated artifact and never in hand-maintained copies.

Worked example (verified 2026-07-12): the host runs Gitleaks 8.30.1, whose primary documented interface is git / dir / stdin, with detect / protect retained only as compatibility aliases; GitLab's Secret Detection analyzer already tracks the newer command forms. That command-surface migration therefore belongs once in the generator (blu secure install-hooks), not in every generated pre-commit hook and not in dozens of hand-maintained copies. A hand-written secret_regex fallback inside a generated hook is a second detection engine: if Gitleaks is the canonical owner, the generator should bootstrap Gitleaks, require it, or fail with a clear diagnostic — it should not maintain an alternate detector. Isolating the decision to one generator is itself the convergence win.

Success Metric¶

Measure engineering success by ownership eliminated while preserving capability through verified regeneration.

This unifies the three invariants of this framework: ownership convergence (toward the smallest stable owner), preservation of capability (nothing required is lost), and executable regeneration (a proven path back, not hopeful reconstruction).