Bluefly Platform Agent Execution Architecture & Identity Contract¶

STATUS=DRAFT_PROPOSED
AUTHORITY=blueflyio/blu/blucity-docs@release/v0.1.x
SECRET_SYSTEM_OF_RECORD=1Password
CONTEXT_GRAPH_AUTHORITY=GitLab Orbit (Beta / Advisory)
SEMANTIC_DOCTRINE_SEARCH=QMD (Derived from BluCity-Docs)
WORK_GRAPH_AUTHORITY=Beads
SOURCE_AUTHORITY=GitLab
PRODUCTION_EXECUTION=Oracle K3s
DEFAULT_EXECUTION_SURFACE=GITLAB_WORKSPACE
LOCAL_WORKTREE_SURFACE=EXCEPTION
LOCAL_WORKTREE_ROOT=$BLUEFLY_WORKTREE_ROOT

1. Platform Hierarchy & Execution Flow¶

                         THOMAS
                            │
                           CMUX
                   operator cockpit only
                            │
                            ▼
                           BLU
                            │
          ┌─────────────────┼──────────────────┐
          │                 │                  │
          ▼                 ▼                  ▼
       BEADS              ORBIT              GITLAB
      work graph       context graph        authority
          │                 │                  │
          └─────────────────┼──────────────────┘
                            │
                            ▼
                    BLUEFLY AGENT ROLE
                            │
                            ▼
                  GITLAB SERVICE ACCOUNT
                            │
                            ▼
                    GITLAB WORKSPACE
                       Oracle K3s
                            │
              ┌─────────────┼──────────────┐
              │             │              │
              ▼             ▼              ▼
        Orbit Remote    Orbit Local       QMD
        estate SDLC     branch AST     doctrine
              │             │              │
              └─────────────┼──────────────┘
                            │
                            ▼
                           Git
                            │
                            ▼
                   MR → CI → Release

Side Authorities¶

1Password: Secret authority and system of record. Stores and delivers secrets; targets authorize.
Tailscale: Private transport layer, cluster connectivity, and network-level node identity.
Aperture: AI routing, model multiplexing, and provider gateway.
Oracle: Durable production/runtime execution authority (Oracle K3s + container fabric).
NAS: Durability, artifact persistence, evidence logs, and backup repository.

2. Separation of Responsibilities¶

IaC
├── GitLab service-account memberships
├── GitLab custom roles
├── group/project authorization
├── Workspace cluster authorization
├── Kubernetes infrastructure
└── Tailscale / network policy

agent-docker
├── Workspace base image
├── glab & glab orbit CLI
├── qmd CLI/MCP client
├── bd (Beads CLI)
├── language toolchains (PHP, Node, Go, Rust, Python)
├── agent CLIs
├── Tailscale client / runtime integration
└── Aperture client configuration

1Password
├── service-account PATs
├── runtime credentials
└── semantic secret references consumed by IaC / runtime

Boundary Law: agent-docker builds the execution environment. IaC builds the authority around it. 1Password holds the credentials. agent-docker MUST NEVER bake credentials, service-account memberships, or credential policies into container images.

3. Secret Exposure Policy¶

SECRET_MAY_APPEAR_IN_STDOUT=NO
SECRET_MAY_APPEAR_IN_TRANSCRIPT=NO
SECRET_MAY_APPEAR_IN_COMMAND_ARGUMENT=NO

Use approved 1Password integration patterns and semantic secret references; runtime resolution belongs to the execution environment.
Never interpolate plaintext tokens into shell commands, scripts, documentation, or agent prompts.

4. Role Elevation Policy¶

Baseline Role: The default assignment for automated Bluefly service accounts is Developer unless a more restrictive role satisfies the operation.
Elevation Gate: Elevated permissions require demonstrated, empirical necessity and target-owned evidence.
Principle of Least Privilege: Verify that standard Workspace creation, code mutation, and branch pushing succeed under the baseline role before requesting or applying custom role elevations.

5. Dual-Context Intelligence: Orbit + QMD¶

ORBIT = STRUCTURAL / LIVE CONTEXT (Tells agent WHAT EXISTS)
QMD   = DOCUMENT / SEMANTIC CONTEXT (Tells agent WHAT BLUEFLY INTENDS)
BEADS = WORK GRAPH / INTENT (Tells agent WHAT IT OWNS)
GITLAB LIVE API = TRANSACTIONAL AUTHORITY (Tells agent WHAT IS TRUE RIGHT NOW)

See Context Plane Standards for full operational definitions.

The Operational Loop¶

ORBIT = DISCOVER
GITLAB = VERIFY
GITLAB = EXECUTE
ORBIT = REASSESS

Orbit is Beta & Advisory: Orbit results reflect the latest indexing cycle. Orbit is an analytical context graph, not transactional authority.
GitLab Live API is Authoritative: Terminal verification (BROKEN_MRS=0, BRANCHES<=3, LATEST_PIPELINE=PASS) must always be evaluated against fresh GitLab API state.

6. Operator Cockpit Layout (CMUX)¶

The operator interface in CMUX provides a persistent 4-pane layout:

┌──────────────────────────────┬──────────────────────────────┐
│ AGENT                        │ GITLAB                       │
│                              │                              │
│ DRUPAL / SPECIALIST          │ MR Status & Diff             │
│ Claude / Codex / Antigravity │ CI Pipeline & Job Logs       │
│ Active session stream        │ Release State                │
├──────────────────────────────┼──────────────────────────────┤
│ WORKSPACE                    │ CONTEXT / PROOF              │
│                              │                              │
│ Remote container shell       │ ORBIT (Live Graph):          │
│ git / glab / bd              │   blast radius, dependencies │
│ Oracle K3s                   │ QMD (Doctrine):              │
│                              │   standards, ADRs, runbooks  │
└──────────────────────────────┴──────────────────────────────┘

7. The Unified Agent Identity Invariant¶

An agent identity must carry consistently across context, execution, source mutation, and evidence.

Orbit query identity
        =
Workspace owner
        =
Git push identity
        =
MR author
        =
Bluefly agent role

Because Orbit queries are authorization-filtered, this single identity governs both what the agent is permitted to know (context graph visibility) and what it is permitted to change (source and infrastructure mutation).

8. Bluefly Filesystem Placement Law¶

Filesystem placement uses semantic roots resolved by the execution surface. Workstation-specific absolute paths are prohibited in governed standards.

Semantic root	Purpose	Rule
`$BLUCITY_DOCS_ROOT`	BluCity-Docs working copy	Non-authoritative checkout of canonical `blueflyio/blu/blucity-docs` documentation
`$BLUCITY_ROOT`	Gas City development working copy	Development checkout for BluCity; production runtime authority remains Oracle
`$BLUCITY_PACKS_ROOT`	Gas City packs working copy	Development checkout for Bluefly Gas City packs
`$BLUEFLY_DEMOS_ROOT`	Demos working root	Active demos being built and maintained
`$BLUEFLY_POCS_ROOT`	POC working root	Proof-of-concept implementations
`$BLUEFLY_WORKTREE_ROOT`	Engineering worktrees	Normal local exception work happens under this resolved root
`$BLUEFLY_SCRATCH_ROOT`	Temporary/scratch space	Replaces `/tmp`, random home-directory files, or tool-owned durable scratch
`$BLUTOWN_LEGACY_ROOT`	Legacy Gas Town working tree	Status: `LEGACY_UNRESOLVED`; do not use as authority

Canonical authority is determined by GitLab project/branch and runtime owner, never by a workstation filesystem path.