Bluefly Context Plane Architecture

Core Doctrine: GitLab is transactional source & release truth. Beads/Gas City define work intent and execution. Orbit discovers structural & live SDLC relationships (derived, advisory). QMD discovers curated architectural doctrine and standards (derived, advisory). Context ≠ authority — a system that lets you see a fact is not necessarily the system that owns it. See §3.

1. Purpose

This directory answers, for any Bluefly agent starting work: what context exists, where it comes from, who owns it, how fresh it is, how to query it, what's authoritative vs. derived, what an agent may mutate, what must never become a second authority, and how these systems work together before/during/after execution.

This is not a product catalog. A system belongs here only if it materially participates in: authority, work context, source context, runtime context, documentation/knowledge retrieval, agent discovery, evidence/proof, identity, credentials, environment/workspace context, product/domain context, external-reference context, or event/context delivery.

2. Authority hierarchy

                         THOMAS
                            │
                          CMUX
                  (Operator Cockpit Only)
                            │
                            ▼
                           BLU
                            │
          ┌─────────────────┼──────────────────┐
          │                 │                  │
          ▼                 ▼                  ▼
        BEADS             ORBIT               QMD
     (Work Intent)     (Live Graph)        (Doctrine)
          │                 │                  │
          ▼                 ▼                  ▼
      Dolt Store     GitLab Analytics    GitLab: blucity-docs
          │                 │                  │
          └─────────────────┼──────────────────┘
                            │
                            ▼
                    BLUEFLY AGENT ROLE
                            │
                            ▼
                  GITLAB SERVICE ACCOUNT
                  (blucity_<specialist>)
                            │
                            ▼
                    GITLAB WORKSPACE
                     (Oracle K3s)
                            │
              ┌─────────────┼──────────────┐
              │             │              │
              ▼             ▼              ▼
        Orbit Remote    Orbit Local       QMD
       (Estate/SDLC)   (Branch AST)   (Standards)
              │             │              │
              └─────────────┼──────────────┘
                            │
                            ▼
                           Git
                            │
                            ▼
                   MR → CI → Release Train

3. Authoritative vs. derived — first-class rule

Readable ≠ authoritative. Every context source below is tagged by what it actually is:

• Orbit sees GitLab but is not GitLab authority.
• QMD indexes BluCity-Docs but the QMD cache is not documentation authority — BluCity-Docs source is.
• Raindrop (if ever integrated) may reference external knowledge but would never be source authority — see raindrop.md.
• Drupal runtime contains installed Composer packages, but the installed copy is not package source authority — the producer's Git repo is.
• CMUX displays agents but is not work authority.
• OpenClaw exposes a gateway but is not a second work graph.
• DDEV contains a consumer build but is not producer source authority.
• NAS contains backups/workspace data but is not source authority.

Principle: Orbit discovers, GitLab proves. QMD discovers doctrine, BluCity-Docs source proves current text. Drupal runtime proves current site state; the producer Git repo proves package source.

4. Context provider matrix

System	Role	Authority	Freshness	Agent access	Mutation rule	Detail doc
GitLab	Transactional source/release truth	AUTHORITATIVE	TRANSACTIONAL/LIVE	glab api/CLI	Governed branch→MR→CI→merge	gitlab-context.md
Beads/Dolt/Gas City	Work intent & execution	AUTHORITATIVE (work intent)	TRANSACTIONAL/LIVE	bd/gc CLI	Governed Gas City/Beads scope only	work-context.md
Orbit (Remote + Local)	Derived engineering/SDLC graph	DERIVED/ADVISORY	POINT-IN-TIME (indexing cycles)	glab orbit remote\|local	Read-only; never edit graph to "fix" GitLab truth	orbit.md
QMD	Derived doctrine/doc search	DERIVED/NON-AUTHORITATIVE	INDEXED/DERIVED, known stale-prone (see Failure Signature Catalog)	qmd search/qmd query	Never patch the cache; fix BluCity-Docs source via MR	qmd.md
CMUX	Human operator cockpit	REFERENCE (UI only)	LIVE (display)	N/A — human surface	No agent write path	cmux-integration.md
GitLab Workspaces / DDEV	Execution environment	EXECUTION	RUNTIME OBSERVATION	ddev/workspace shell	Never source authority	workspace-integration.md
Drupal (site/runtime)	Product/domain context	RUNTIME OBSERVATION (not source)	RUNTIME OBSERVATION	drush/composer show/Canvas CLI	Never edit installed copy	drupal-context.md
1Password	Secrets authority	AUTHORITATIVE (secrets only)	LIVE	op run (reference only, never echoed)	Never put secret values in any context doc	See ADR-0020, authority-model.md
GitLab service accounts	Identity	AUTHORITATIVE (identity)	LIVE	Assigned per agent role	Never impersonate another role's identity	See Identity Contract, authority-model.md
Raindrop	Unproven — no integration exists	NOT_ESTABLISHED	n/a	n/a	Do not invent a role	raindrop.md
DUADP	Agent discovery protocol — referenced in platform rules, no canonical doc found in this repo	GAP	n/a	n/a	Flagged for a future audit pass, not documented here	—

5. Required preflight sequence

Before meaningful work, resolve the applicable fields of the Context Preflight Contract — it is context-sensitive: Drupal work pulls in drupal-context.md; CI work pulls in gitlab-context.md + gitlab_components; a runtime incident pulls in Oracle/runtime evidence; documentation work pulls in QMD + source docs. Don't resolve fields irrelevant to the task at hand.

6. Context source selection model

Question	Source
What work exists?	Beads
What's the current source/MR/pipeline/release state?	GitLab live API
What depends on this?	Orbit Remote
What does this branch actually reference?	Orbit Local
What is Bluefly doctrine?	QMD → BluCity-Docs source
How does this upstream Drupal module work?	drupal.org + upstream docs/source — see drupal-context.md
What's currently enabled/configured on this Drupal site?	Drupal runtime/config + Composer state — a runtime observation, not source
What reusable execution method exists?	Gas City Formula/Skill/Pack catalogs
What credential value should I use?	Never a context doc — 1Password reference mechanism only
What external research has a human curated?	Raindrop, only if role is proven — currently not (raindrop.md)

7. Relationship to execution

Context acquisition happens before source mutation (preflight), is re-verified during execution when state may have changed (e.g., re-check GitLab MR state after a long-running task), and the resulting evidence is recorded after execution in the work item (Bead) and/or an execution receipt — see Receipts Standard. Context-plane docs never substitute for that receipt.

Documentation Modules

• Authority Model & Non-Negotiable Invariants
• GitLab: Transactional Source & Release Authority
• Work Context: Beads, Gas City, Formulas, Orders, Skills, Packs
• GitLab Orbit Specification (Remote + Local)
• QMD Semantic Document Search
• Drupal: Context Acquisition
• Context Preflight Contract & Enforcer
• CMUX Operator & Attention Plane Standard
• GitLab Workspace Context Integration
• OpenCode Execution Harness Operating Model
• Claudex Fallback Model Path & Inference Architecture
• Raindrop: Gap Record (not yet a context-plane authority)

API Schema Discovery

A third, narrower context source sits alongside Orbit and QMD for "what APIs/specs are available?" questions:

• api-schema-registry — discovery/validation/publication for Bluefly's own ~65 service contracts (aggregated corpus, service catalog, endpoints index, control-plane index; also served over HTTP by that repo's dist/serve.js).
• Engineering-Standard/reference/api-schemas/ — curated, pinned reference copies of stable external vendor schemas Bluefly consumes (GitLab REST API, Raindrop Query API), with provenance/hash metadata per schema.
• producer/upstream source — ultimate authority for any given contract; both of the above point at it rather than forking it.

Neither of these is a runtime orchestrator; see that catalog's README for the full split of concerns, including its relationship to Drupal api_normalization and Tool API/MCP.