Gas City Doctrine Enforcement (v2.0) - Sessions perform work. (Sessions are disposable). - Beads remember work. (Durable universal substrate). - Convoys group work. - Mail coordinates work. - Formulas remember how. (Reusable methods). - Agents execute. - Packs configure. - Rigs scope. - Orders trigger. - Events prove what happened. - Work is not complete until verified and promoted (Capability, Skill, Formula, Pack, Order, Policy). (No parallel "learning lifecycles" or "agent memory" outside this machinery).

Convergence Doctrine¶

Parent contract: Bluefly Engineering Execution Contract Version: 1.0 Applies to: All agents operating in the Architecture role. Informs Evidence and Implementation roles.

1. The Axiom: Net-Negative Coding¶

Bluefly builds net-negative code. Agents are rewarded for deleting custom code in favor of proven upstream and contrib platforms.

This is not a preference. It is a hard architectural constraint: - Value is measured in lines deleted and dependencies retired, never in new custom lines authored. - The best agent contribution is a net-negative pull request: replacing hundreds of lines of custom, bespoke control planes, microservices, and scripts with native upstream configuration, standard contrib modules, and upstream extension points. - A custom implementation that duplicates upstream or community contrib capability is technical debt and a defect, not an accomplishment.

This is not a preference. It is a constraint. Every architecture decision must satisfy this axiom or document why it cannot.

2. Upstream Before Custom¶

When a capability is needed, evaluate in this order:

Does an upstream platform already provide it? Use it.
Does an upstream extension point allow it? Extend through the documented extension point.
Can composition of existing platforms achieve it? Compose them.
None of the above? Document the gap, the upstream options evaluated, and the rationale for custom work. Custom work requires explicit governance approval.

A custom implementation that duplicates upstream capability is a defect, not a feature.

3. Extension-Point-First¶

When integrating with an upstream platform (Gas City, Drupal, Acquia, GitLab, etc.):

Use the platform's documented extension points before modifying platform internals.
If no extension point exists, document the gap and engage upstream — do not fork.
Extension points are integration surfaces, not authorization to reimplement the platform.

For Gas City, use only extension points documented in the official Gas City documentation or reported by the official gc CLI. Engineering-Standard must not maintain a local list of Gas City extension points.

4. Orthogonality Thesis¶

Gas City models execution mechanics. Bluefly models governance. These concerns are orthogonal.

Layer governance on top of execution. Do not merge them.
Gas City primitives and runtime behavior are defined upstream.
Bluefly governance (ContractPlane, Cedar, OSSA, receipts) handles authorization, compliance, audit, and trust.
The integration surface between them must be cited to upstream documentation or official CLI output.

5. Convergence Decisions¶

Architecture decisions follow this structure:

State the capability needed. What outcome is required?
Inventory upstream options. What already exists? (Evidence role provides this.)
Evaluate fit. Does upstream satisfy the requirement? Partially? Not at all?
Choose the integration path. Use, extend, compose, or (last resort) build custom.
Document the decision. Including: what was evaluated, what was chosen, why, and what was explicitly rejected.
Define the implementation scope. Boundaries, receipts location, terminal criteria.

Convergence decisions are append-only. A later decision may supersede an earlier one but must not delete or rewrite it.

6. What Architecture Never Does¶

Never rewrites evidence. If the evidence is wrong, request a new evidence gathering. Do not modify the evidence report.
Never fabricates findings. Architecture decisions are based on what was found, not what was hoped for.
Never implements. Architecture approves direction and scope. Implementation agents execute.
Never assumes runtime from configuration. A config file is not proof of execution. See Evidence Reporting Standard, Section 2.

7. Repository Convergence Lifecycle¶

When an entire repository is converged onto its smallest stable owners (reference implementation: ADR-0015, the skills repository), the decision structure in §5 expands into a gated lifecycle. Operational authority for repository convergence: ADR-0010.

Inventory → Capability Audit → Ownership Analysis → Replacement Validation
  → Migration Prototype → Operational Acceptance → Unused Proof
  → Archive Approval → Deletion

Ownership Analysis — Smallest Stable Owner. For every capability choose the smallest stable owner, in order: 1. Upstream platform → 2. Product → 3. Shared Bluefly capability (pack) → 4. Organization → 5. Portfolio. If Bluefly is not the smallest stable owner, Bluefly does not own it.
Replacement Validation requires an upstream equivalence matrix — per retired subsystem: the upstream feature, evidence at an explicit capability-claim level (Evidence Reporting Standard §2.1), and any remaining gap resolved as exactly one of upstream contribution, temporary compatibility layer, or retained Bluefly capability — plus a consumer ledger. Nothing retires until every listed consumer is proven migrated.
Operational Acceptance is distinct from a working prototype: demonstrate that CI, deployment, rollback, monitoring, ownership, documentation, and support all function before the replacement is adopted and before the replaced capability may retire.
Deletion is terminal and last — only after migration, archive approval, and consumer proof. Deletions ride the repository's own governance gates (hooks, review paths); a guard forcing human review of destructive change is working as designed, not an obstacle.
Artifacts. The migration ledger is a temporary artifact scoped to one repository's migration; permanent doctrine lives in Engineering Standards. Authority flows strictly downward: Engineering Standard → ADR → Migration Ledger → Receipts. An ADR records the application of a standard; it never introduces doctrine.

7.1 Pack Promotion Criteria¶

Converged reusable behavior lands in packs. Default organizational home: the canonical catalog (blucity-packs); pack identity is independent of pack location. A pack may leave the catalog only when all of the following are proven: a stable long-term owner exists for the target repository; the target repository has demonstrated long-term ownership; a runtime consumer is proven (evidence level ≥ Verified); the build pipeline is proven; documentation is transferred; governance approved the promotion. Otherwise the pack remains in the catalog.

8. Universal Ownership Order¶

§2 establishes that upstream precedes custom; this is the precedence list that decides which upstream. Evaluate platforms in this exact sequence and stop at the first one that can completely own the capability:

Operating System (POSIX/CLI primitives)
GitLab Ultimate
Docker
Kubernetes
Terraform
DDEV
PostgreSQL
Dolt / Beads
Cedar
ContractPlane
OSSA
DUADP
Gas Town
Gas City Packs
Bluefly custom code — absolute last resort

The burden of proof lies with custom code: it must justify why no platform above it can own the capability. This order refines the smallest-stable-owner rule in §7 — that rule chooses the owning tier, this list chooses the owning platform within it.

9. Capability Convergence Lifecycle¶

§7 governs converging an entire repository. A single capability progresses through these stages sequentially, and is not converged until Remaining Consumers = 0 and its status is DECOMMISSIONED:

DISCOVERED → OWNER IDENTIFIED → SUPPORTED → CONFIGURED → VERIFIED
           → EXERCISED → NO REMAINING CONSUMERS → DECOMMISSIONED

DISCOVERED — the capability exists in custom code or a template.
OWNER IDENTIFIED — the owning platform is selected via §8.
SUPPORTED — that platform provides the capability natively.
CONFIGURED — the upstream feature is configured, via API or configuration file.
VERIFIED — the configuration is confirmed by live API or runtime evidence.
EXERCISED — the capability runs for real: a merge request, push, or pipeline.
NO REMAINING CONSUMERS — every platform reference points at the new owner.
DECOMMISSIONED — the custom code is deleted and its maintenance burden is gone.

Evidence levels for stages 5–6 follow the Evidence Reporting Standard §2.1. A configuration file proves stage 4, never stage 5.

9.1 Authority Receipt¶

No custom code may be deleted before its Authority Receipt exists:

Capability: <name>
Canonical Owner: <platform from the Universal Ownership Order>
Previous Owner: <custom repository or component>
Reason for Transfer: <rationale>
Configuration Evidence: <API output, config path, or policy ID>
Verification Evidence: <runtime output, API verify response, or UI proof>
Execution Evidence: <pipeline job ID, MR link, or run log>
Remaining Consumers: <count>
Remaining Dependencies: <list>
Lines Deleted: <count>
Components Deleted: <count>
Dependencies Removed: <count>
Net Maintenance Burden: SMALLER | SAME | LARGER
Status: <lifecycle stage>

Net Maintenance Burden: LARGER is a failed convergence, not a completed one.

9.2 Success Metric¶

Convergence is measured by maintenance eliminated, never by new custom templates authored:

Templates Removed:          <count>
Runtime Services Removed:   <count>
Repositories Eliminated:    <count>
Dependencies Removed:       <count>
Configuration Added:        <count>
Capabilities Transferred:   <count>
Net Lines Deleted:          <count>
Future Upgrade Burden:      LOWER | SAME | HIGHER

9.3 Worked Example — repository-governor¶

Applying §8 and §9 to repository-governor: it is decomposed capability by capability rather than rewritten, because no single platform owns the whole of it.

Capability	Canonical owner
Filesystem traversal	Operating System (`find` / `fd`)
Repository inventory	GitLab API (`GET /groups/:id/projects`)
Project classification	DDEV + GitLab CI (`rules:exists`)
Registry state	Beads / Dolt tables
Policy evaluation	Cedar + Compliance Engine
Contract validation	OSSA
Discovery	DUADP
Orchestration	Gas City Packs — curated orchestration only, no custom business logic

10. Source/Runtime Convergence Formula¶

FORMULA=source-runtime-convergence names the recurring operational loop for closing drift between what a repository declares and what a live host is actually running — the pattern behind rig bindings, NAS mount options, a proxy's DATABASE_URL, and a secrets-connect endpoint all drifting from their own committed source independently. It is a named repeatable procedure, not a one-off incident writeup.

1. Inspect desired source        (Repository tier — §Authority Model)
2. Inspect actual runtime        (Runtime tier — §Authority Model)
3. Classify the difference       (OBSERVED / INFERRED / VERIFIED — see
                                   Runtime Dependency Investigation Standard)
4. Identify the owner            (Universal Ownership Order, §8)
5. Implement the source fix      (in the owning repository)
6. Test                          (repository-local validation)
7. Independent verify            (a second observation, not the implementer's own)
8. Merge
9. Trigger deployment
10. Runtime-owner verifies on the live host (e.g. MAYOR-ORACLE on Oracle)
11. Close only on equality       (source == runtime, independently confirmed)

Steps 3 and 7 reuse the OBSERVED/INFERRED/VERIFIED evidence ladder from Runtime Dependency Investigation by reference — this Formula does not redefine evidence classification, it sequences it into a closing loop.

Closing contract¶

MR_MERGED    != DONE
PIPELINE_GREEN != DONE

DONE  ⟺  SOURCE_CORRECT=YES  AND  DEPLOYED=YES  AND  RUNTIME_VERIFIED=YES

A merged MR proves step 8. A green pipeline proves step 6 (and, if the pipeline itself deploys, step 9). Neither proves step 10. Do not report a source/runtime convergence complete on merge or pipeline status alone — report it open until the runtime owner has independently confirmed equality on the live host, and cite that confirmation (command, output, timestamp) in the closing receipt.

This doctrine governs architecture decisions. It does not govern evidence gathering or implementation execution.