Skip to content

ADR-0018: Blu as a Reasoning Engine Over External Context Providers, Not a Federator

Status: Proposed — architectural direction only, not implemented Date: 2026-07-12

Context

Blu's default instinct is to maintain its own picture of the organization (platform-contract.yaml, authority-context.json, hand-written Oracle/NAS schemas). Two upstream-owned graphs already exist or are becoming available:

  • Static capability knowledge — who owns what, what replaces a capability. Relatively stable, mostly derivable from docs/source.
  • Runtime organizational knowledge — who last touched code, which MR introduced it, what consumes it, what breaks if removed, current team ownership. GitLab Orbit's indexed SDLC graph (query_graph/get_graph_schema over projects, source, MRs, work items, pipelines, security findings, dependencies) is designed to answer exactly this.

Decision

Blu should not duplicate either graph. The two domains don't overlap, so don't force one into the other:

  • GitLab Orbit owns: source, projects, MRs, pipelines, dependencies, security findings — SDLC/code knowledge.
  • Gas Town owns: identities, convoys, molecules, beads, work routing, escalation, operational/runtime state.
  • Blu's role is not a federator — "federator" implies owning the combined graph, which it doesn't. Blu is an architectural reasoning engine that queries multiple authoritative context providers and combines their answers into a recommendation. It owns only the reasoning, not any underlying fact.

Example: a Semgrep finding on dockerode → ask Orbit "who owns this, how many repos consume it, who reviewed it, what depends on it" → ask Gas Town "which beads/convoys/agents are currently touching it" → only then reason: "Docker already owns this capability, five repos consume it, two active convoys are mid-change — remove only after migrating those consumers."

Refined to four layers, not two: Authority → Projection → Reasoning → Artifact. Example: Git (authority) → commit graph (projection) → Blu analyzes history (reasoning) → recommendation (artifact). Another: OSSA manifest (authority) → identity projection (projection) → Blu convergence reasoning (reasoning) → MR comment (artifact). Blu owns exactly one layer: Architectural Reasoning. Everything else is either upstream authority, a deterministic projection, or a disposable generated artifact.

Context Provider authority classes (stable categories; specific providers can change under them without changing the architecture): SDLC (Orbit, Git), Runtime (Gas Town), Package (Composer, npm, Go modules), Infrastructure (Terraform, Kubernetes), Organization (platform contracts, OSSA).

Rule

  1. Before creating any new canonical platform-contract-style document, ask: is this fact already available from Orbit or Gas Town? If yes, query, don't re-derive. If no, the new document becomes the legitimate canonical owner — this is the actual test for whether a new platform-contract.yaml-shaped file is justified at all.
  2. Audit ownership by capability, not by filename — absence of a specific filename (platform-contract.yaml, authority-context.json) is not evidence a capability doesn't already exist under a different name (authority receipts, Oracle execution-lock receipts, OSSA manifests, DUADP manifests). Check whether existing artifacts already satisfy what a hypothetical new contract file would provide before creating one.
  3. Classifying a piece of code as Authority vs Projection vs Reasoning vs parallel-authority-duplication requires reading the actual function bodies and their consumers — reading names/signatures alone is not sufficient.

Caveat

GitLab Orbit Remote is Beta (feature-flagged knowledge_graph, not GitLab-recommended as production-ready, only two MCP tools exist so far, schema/query DSL still evolving). Design any real implementation with a Context Provider abstraction (Orbit preferred → Git → Composer/package managers → platform contracts as fallback), not a hard dependency on Orbit's current beta API.

Consequences

Blu naturally shifts toward Orbit as it matures without being tightly coupled to it today. No code, abstraction layer, or MCP wiring exists yet for this — this ADR captures the design conversation so it isn't re-derived from scratch.