Skip to content

Context Plane Authority Model & Invariants

Scoped to this context plane's own systems (Beads/GitLab/Orbit/QMD/Workspaces/CMUX/identity/secrets/Oracle). Not the same document as authority/Authority-Model.md (the platform-wide ownership-registry/convergence-engine standard covering every Bluefly repository) — distinct scope despite the similar name; this file never restates that one's registry/invariant content, and that one does not cover context-plane query paths.

Canonical Filesystem & Authority Matrix

Target / Path Role / Purpose Nature Canonical Authority Rule
GitLab: blueflyio/blu/blucity-docs Documentation Source of Record Authoritative Canonical source of record for all durable standards, architecture, runbooks, directives, and indexes.
Oracle: /opt/bluefly/blucity Production Gas City Runtime Authoritative Production Gas City supervisor, daemon runtime, and durable city controller.
[WORKSPACE-ROOT]/BluCity-Docs Local Documentation Working Copy Working Copy Local checkout for editing and validation; non-authoritative.
[WORKSPACE-ROOT]/BluCity Local BluCity Working Copy Working Copy Local development/operator working copy of base City.
[WORKSPACE-ROOT]/BluCity-Packs Local Pack Development Working Copy Working Copy Local development working tree for Gas City packs.
[WORKSPACE-ROOT]/worktrees Local Engineering Worktrees (CANONICAL_ENGINEERING_WORKTREE_ROOT) Working Copy Designated root for branch-scoped feature/fix worktrees (independent physical directory under estate root). FORBIDDEN: BluCity/.gc/worktrees (reserved strictly for Gas City internal runtime).
[WORKSPACE-ROOT]/DEMOs Live / Production Demos Product Workspace Active demonstrations built and maintained across platform services (NOT disposable scratch).
[WORKSPACE-ROOT]/POCs Live Proof of Concepts Product Workspace Active proofs-of-concept being engineered (NOT disposable scratch).
[WORKSPACE-ROOT]/Scratch Local Temporary Workspace Disposable Replaces /tmp, random home directories, or tool-specific folders for transient analysis. Non-authoritative.
[WORKSPACE-ROOT]/BluTown Legacy Gas Town Tree Legacy Status: LEGACY_UNRESOLVED. Do not delete, do not use as authority, do not add new architecture.

Core Authority Boundaries

  1. Beads / Dolt: Work graph of record (what tasks exist, ownership, priorities, closures).
  2. GitLab: Source of record, branch permissions, MR review, Merge Trains, CI/CD pipelines, Package registry.
  3. GitLab Orbit: Canonical derived engineering context graph for GitLab-hosted code & SDLC state (STATUS=Beta / Analytical & Advisory).
  4. QMD: Canonical semantic document retrieval engine over the BluCity-Docs corpus (STATUS=Derived Search Projection / Non-authoritative).
  5. GitLab Workspaces: Ephemeral, disposable remote development sandboxes on Oracle K3s.
  6. GitLab Service Accounts: Unique non-human identities (blucity_<role>) providing strict provenance.
  7. CMUX: Mac-local human operator cockpit (observation, layout, attention management).
  8. 1Password: Secret authority of record (BlueflyAgents vault). No secrets in Git, logs, or command arguments.
  9. Tailscale & Aperture: Private network identity transport & centralized LLM/MCP proxy gateway.
  10. Oracle: Durable production execution & Gas City supervisor runtime.

Declared Non-Negotiable Invariants

  • NO_DURABLE_DOCS_IN_AGENT_HOME_DIRECTORIES=YES (~/.gemini, ~/.claude, etc. contain tool config only).
  • NO_TMP_USAGE=YES ([WORKSPACE-ROOT]/Scratch is the only temporary directory).
  • SECRET_MAY_APPEAR_IN_STDOUT=NO
  • SECRET_MAY_APPEAR_IN_TRANSCRIPT=NO
  • SECRET_MAY_APPEAR_IN_COMMAND_ARGUMENT=NO
  • IDENTITY_CONVERGENCE=DECLARED_INVARIANT: Bluefly governance requires all agent actions to converge on the assigned service account principal: Orbit Query Identity == Workspace Owner == Git Push Identity == MR Author == Bluefly Agent Role.