Authority Boundary Rules¶
Parent contract: Bluefly Engineering Execution Contract
Version: 1.6
Applies to: All roles. Enforced by Implementation role; respected by Evidence and Architecture roles.
Changelog: v1.6 — §8 Gas City-as-platform vocabulary retired. Runtime is Gas City (gc); Gas City pack roles are configuration. Canonical object model: factory-operating-contract.md + current docs.gascity.com (2026-09-09). v1.5 — §8.9.0 directory-never-grants-authority; Applications/ replaces retired PROJECTS/; directory names are implementation details not authorities (hq-nb7.22) (2026-07-10). v1.4 — §8.9 Host ≠ Authority (five authorities), Agent Execution Rules (claim + authority before edits), bead Authority block, inventory-before-delete, NAS-as-host not SoR; updated §8.2 host table and §8.8 operational fact (hq-nb7.19) (2026-07-08). v1.3 — §8.8 system vocabulary, decision tree (bd/gt/gc/ops/repo/docs), rig-registration operational fact (2026-07-08). v1.2 — Added §8 Bluefly Platform Standard v1 (logical authorities, deployment planes, mutation process) (2026-07-08). v1.1 — Added §7 Bootstrap Artifact Authority Resolution (2026-07-01).
Curation 2026-09-09. Gas City is the orchestration runtime. Six primitives: Agent, Bead, Formula, Rig, Pack, Event. Mayor, Deacon, Witness, Refinery, Polecat, Town HQ, and
gtas a peer platform are not current primitives. Oracle still running Gas City isRUNTIME_CONFORMANCE=FAIL(ADR-0027), not an approved architecture. Boundary rules below that still say "Gas City owns runtime" are historical cutover text; do not implement new work against them.
1. Two Kinds of Authority¶
| Type | Definition | Example |
|---|---|---|
| Source Authority | Who authored or maintains the artifact. Where the source of truth lives. | A formula TOML authored by Bluefly in the blucity-packs repo. |
| Operational Authority | Who runs the artifact in production. Where execution happens. | The same formula executed by the Gas City orchestrator on Oracle. |
These may differ. A pack authored by Bluefly (source authority: BLUEFLY) may run on Oracle under the Gas City orchestrator (operational authority: ORACLE). Neither authority subsumes the other.
When reporting or labeling authority, always specify which type. Never use the unqualified term "owner."
2. Known Boundaries¶
| Boundary | Side A | Side B | Crossing Requires |
|---|---|---|---|
| Host boundary | Mac workspace ($ESTATE_ROOT/) |
Oracle runtime (~/gt/) |
Separate executions with separate receipts |
| Platform boundary | Bluefly governance layer | Gas City execution layer | Extension-point integration (EP1–EP7), not modification |
| Upstream boundary | Bluefly custom artifacts | Upstream platform artifacts (Gas City, Drupal, Acquia) | Fork avoidance; upstream engagement if extension point absent |
| Environment boundary | Development/documentation | Production runtime | Deployment approval (separate from implementation approval) |
This table extends as the platform grows. New boundaries are added by the Architecture role with a dated addendum.
3. One Boundary Per Execution¶
A single implementation execution may cross at most ONE boundary. If work requires changes on both sides:
- Split into separate executions.
- Each execution produces its own receipts.
- The second execution may depend on the first but must have its own approval.
This rule exists to maintain clear accountability. A receipt that spans two boundaries cannot clearly attribute mutations to the correct authority.
4. Workspace Absence ≠ System Absence¶
When an artifact is not found in the inspected scope:
- It means the artifact was not located in the repositories and directories surveyed.
- It does NOT mean the artifact does not exist elsewhere in the system.
- Evidence reports must always qualify negative findings with the scope that was searched.
The inspected workspace (Mac $ESTATE_ROOT/) is a documentation and development projection. The Oracle runtime (~/gt/) is the sole execution authority. Artifacts may exist on Oracle that are not present in the Mac workspace, and vice versa.
See: Evidence Reporting Standard, Section 4.
5. Escalation Rules¶
When a boundary crossing is needed but not authorized:
- The executing agent stops immediately.
- The agent reports BLOCKED with:
- Which boundary was encountered.
- What action requires crossing it.
- What approval is needed to proceed.
- The Architecture role evaluates and either:
- Approves the crossing (producing an architecture receipt).
- Redesigns the approach to avoid the crossing.
- Escalates to governance if the crossing involves production, schema changes, or access controls.
No agent may self-authorize a boundary crossing. The approval must come from a different role than the one requesting it.
Anti-pattern — substitute-target drift: when the true target of a task is unreachable (missing access, missing credentials, wrong environment), do not decide unilaterally that a nearby, more-accessible system is "close enough" to stand in for it. This applies with particular force to any developer workstation (Mac or otherwise): local machine state — including a local Kubernetes cluster, a local Gas City mayor/orchestrator config, or any other locally-running service that superficially resembles platform infrastructure — is out of scope for platform-health assessment entirely, not merely a boundary requiring approval to cross. A crashlooping pod or stale config on a developer workstation is not platform signal, because the workstation is not part of the platform's durable state (see [[git-discipline.md]] §6, workstation disposability). If the real target is blocked, report BLOCKED per §5 and stop for the affected scope — do not substitute a different system, or a broader interpretation of "the platform," to manufacture the appearance of progress.
6. Governance-Level Boundaries¶
Some boundaries require governance approval beyond the Architecture role:
| Action | Requires |
|---|---|
| Schema changes (database, API, configuration schema) | Governance approval |
| Production deployment | Deployment approval (separate from implementation approval) |
| Access control or permission changes | Governance approval |
| Modification to the execution contract or standards | Governance approval |
| Status changes in the operating model | Evidence-backed governance approval |
These are not negotiable by any role.
7. Bootstrap Artifact Authority Resolution¶
When a deployment fails because a required configuration file is missing, the implementing agent must resolve authority before creating the file. The absence of a file is evidence of a missing bootstrap artifact — it is not authorization to author one from memory.
Resolution order:
-
Check upstream — Does the container image already contain a default for this path? Extract it with
docker run --rm <image> cat <path>. If yes, the image is the upstream authority. Copy from the image. -
Check source — Is the file tracked in the project repository? Search the repository for the filename. If yes, the repository is the source authority. Copy from the repository.
-
Check deployment documentation — Does deployment documentation, a README, or a compose-level comment specify how this file should be created? If yes, follow that specification exactly.
-
If all three are unknown — Authority is unresolvable. Report BLOCKED. Do not create the file from agent memory.
Stop means stop: when a tool use is denied, or an operator says stop, halt the entire line of work — including cleanup of the agent's own scaffolding. Leave artifacts exactly as they are until a new instruction arrives. A denied action is not license to route around it with an adjacent action; report the denial and wait.
Prohibited action: Authoring a bootstrap artifact from training knowledge
or memory without exhausting all three checks above is equivalent to
REPO-004: UNAUTHORIZED_MUTATION and requires owner review.
Retroactive correction: If a file was already authored from memory before authority resolution, replace it with the upstream-authoritative version and restart the affected service. Receipt both actions.
8. Bluefly Platform Standard v1¶
Canonical terminology. Logical authorities are never tied to hardware. A Repository (Bluefly project git repo) is not automatically a Rig. A Rig is a Gas City registration of an external project (gc rig add). Drupal is a Rig when agents execute against it; Drupal is not a second scheduler.
Gas City primitives are Agent, Bead, Formula, Rig, Pack, Event. Mayor, Witness, Refinery, Polecat, and Deacon are Pack-supplied Agent configurations, not layers in this table. See How Gas City Works and factory-operating-contract.md (Six primitives).
8.1 Logical authorities¶
| Layer | Canonical owner | Owns | Never owns |
|---|---|---|---|
| City | Gas City | Root Pack, city deployment, city bead namespace, one Dolt server | Project source, Drupal business data |
| Rig | Gas City | Registered project scope, rig bead namespace, rig-scoped agents | City-wide coordination; source authority |
| Repository | Bluefly project / GitLab | Source, documentation, ADRs, policies, schemas, tests | Runtime state; Beads work graph |
| Deployment | Bluefly Operations | Containers, systemd, Kubernetes, Compose, Terraform, volumes | Source code |
| Machine | Operator | Editor settings, caches, shell config | Shared platform state |
Laptop rule: The laptop is never an authority. It is a client.
8.2 Hosts are not authorities¶
Permanent invariant: Host ≠ Authority.
Mac, Oracle, and NAS are hosts. They store or run things. They do not become a second source of truth by being mounted or convenient.
| Host | What it may host | What it must never become |
|---|---|---|
| Oracle | City (/opt/bluefly/blucity target), Gas City machine state (~/.gc), Bluefly Platform Deployment (/opt/bluefly). /home/ubuntu/gt is the temporary Gas City legacy plane until cutover is proven. |
A substitute for GitLab source authority |
NAS (/Volumes/AgentPlatform / /volume1/AgentPlatform) |
BluCity-Docs (docs host), BluTown (shared operational assets), packs, persistent data, deployment assets | Another development / source / runtime authority |
| Mac | Working checkouts ($ESTATE_ROOT/Applications/, worktrees/, Scratch/; optional BluCity-Docs checkout) |
An authority of any kind |
| Oracle path | Concern | Authority |
|---|---|---|
/home/ubuntu/gt |
Gas City HQ — temporary legacy plane (CUTOVER_STATUS=INCOMPLETE) |
Not the target runtime |
/home/ubuntu/.gc |
Gas City machine state | Orchestration (Gas City) |
/opt/bluefly |
Bluefly Platform — runs software | Deployment (Bluefly Platform) |
Town (~/gt) and Platform (/opt/bluefly) stay completely separate.
| NAS path (examples) | Meaning |
|---|---|
BluCity-Docs/ |
Documentation host for BluCity-Docs (authority remains the docs/GitLab contract—not “edit because mounted”) |
BluTown/ |
Shared operational assets |
applications/ (e.g. blucity-packs) |
Shared packs / application assets — not an unmanaged Git forest |
deployment/ |
Deployment configuration assets |
data/ |
Persistent runtime data |
config/ |
Shared configuration |
Prohibited reasoning: “There is a clone on the NAS / under /opt/bluefly, so I will edit that.”
Correct reasoning: “This bead’s Authority block names Source / Runtime / Deployment / Documentation; I execute only there.”
8.3 Bluefly deployment policy (not upstream Gas City)¶
Oracle containers that still participate in the legacy Gas City plane (CUTOVER_STATUS=INCOMPLETE) SHALL share that host tree via bind-mounted storage rooted at ~/gt until independent WITNESS acceptance of Gas City cutover. That is a temporary runtime fact. It is not the target architecture. Target runtime is Gas City at the city root (/opt/bluefly/blucity plus .gc/ machine state).
8.4 Repository rules¶
Repositories own only project assets.
| Allowed in Repository | Not allowed in Repository |
|---|---|
| Source, documentation, ADRs, schemas, policies, tests | Running databases, runtime state, Docker volumes, systemd state, Town runtime, deployment logs |
Rig-local artifacts from gt rig add / gt init may exist on disk inside a rig working tree — classify State (persistent metadata vs runtime). Do not equate ".beads in a repo path" with violation; ask whether town-level runtime leaked into a repository.
8.5 BluTown products (canonical NAS paths)¶
| Asset | Purpose | Canonical location |
|---|---|---|
| BluTown | Platform implementation | /Volumes/AgentPlatform/BluTown |
| BluCity-Docs | Documentation and knowledge | /Volumes/AgentPlatform/BluCity-Docs |
| blucity-packs | Gas City application packs | /Volumes/AgentPlatform/applications/blucity-packs |
| Blu Buddy | Stateless API bridge | Runtime only — owns no persistent state |
8.6 Migration priority (hosts — not authorities)¶
- Oracle — host production Gas City (
/opt/bluefly/blucity,~/.gc) and Deployment (/opt/bluefly).~/gtremains the observed legacy plane until cutover. - NAS — host documentation, shared operational assets, packs, persistent data (not Source/Runtime SoR)
- Laptop — host working checkouts only — never an authority
8.7 Artifact classification and mutation¶
Every mutation follows:
Inventory → Classify Owner → Classify State → Evidence Check → Choose Action → Execute
| Dimension | Meaning | Changes? |
|---|---|---|
| Owner | Artifact authority (City, Rig, Repository, Deployment, Machine, Unclassified) | Rarely — only with new evidence |
| State | What the artifact represents (Source, Configuration, Persistent metadata, Runtime, Cache, Unknown) | May change over time |
| Action | Engineering decision (Keep, Review, Move, Ignore, Delete, Quarantine) | Freely |
Rules: Owner is a property of the artifact; State and Action describe the current implementation. Classification (Owner + State) is immutable until evidence changes; Actions are mutable.
Evidence Check (mandatory before Move, Delete, or Quarantine):
- Owner established
- State established
- Destination owner established (for Move)
- Runtime receipt if runtime assets are affected
8.8 System vocabulary and agent decision tree (v1.2)¶
Golden rule: Every object belongs to exactly one system. These are parallel authorities by purpose, not a strict execution stack. Do not express the relationship as Gas City → Gas City → Bluefly. Gas City is an optional imported Pack on Gas City, not a runtime under it.
| Layer | System | CLI | Owns |
|---|---|---|---|
| Work | Beads | bd |
Durable work graph (prefix-scoped on the city Dolt) |
| Orchestration | Gas City | gc |
Agents, Formulas, Rigs, Packs, Events, Orders, sessions, sling |
| Deployment | Bluefly Operations | agent-docker, Terraform, Compose |
/opt/bluefly and IaC (Oracle hosts deployment; NAS may host shared deployment assets — not source) |
| Products | Bluefly Projects | Git | Source, tests, schemas (repositories) |
| Knowledge | BluCity-Docs | Git | Bluefly policy. Gas City primitive definitions stay at docs.gascity.com |
Decision tree (binding):
Track work? → bd
Run/coordinate agents? → gc (not gt)
Configure orchestration? → gc
Deploy infrastructure? → Bluefly Operations (agent-docker / IaC)
Change source? → Repository (Bluefly Projects)
Explain/document? → BluCity-Docs (policy) / docs.gascity.com (Gas City semantics)
Constitutional rules: A bead is never documentation. A city is never a Git repository. Deployment is never source authority. Documentation is never runtime. The laptop is never an authority. Runtime receipts measure conformance; they do not override current docs.gascity.com. gt as a control plane is a defect (ADR-0026).
8.8.1 Remote control surfaces (Mac client → Oracle)¶
Gas City has no documented remote HQ RPC. gt/bd require the town filesystem and Dolt on the same host as GT_TOWN_ROOT. The workstation runs neither town SoR nor authoritative bd/gt mutators.
| Surface | Scope | Bluefly posture |
|---|---|---|
SSH + on-host gt/bd |
Town mutations, beads, convoys | Thin transport only (blu work, allowlisted Oracle SSH); not an upstream Gas City protocol |
gc CLI / supervisor API (127.0.0.1:8372, /v0/events) |
Gas City orders, supervisor events | Upstream remote orchestration observe/control at city scope—not a substitute for rig tmux or gt sling |
gastown-gateway HTTP (:8787) |
Read-only town projection | Bluefly deployment (agent-docker); optional; not upstream—repair or retire before relying on it |
gt wl / DoltHub federation |
Cross-town work board | Upstream; not live tmux RPC |
Production town host: [email protected], town root /home/ubuntu/gt. Do not use stale Oracle IP defaults in client config.
Operational fact (Oracle receipts, incomplete cutover): Town HQ and Beads were healthy under gt. That plane is not the target registration SoR. Target rig identity is city.toml + .gc/site.toml. portfolio.json is Bluefly descriptive metadata only. Do not hard-code rig counts in this standard.
8.9 Five authorities, Agent Execution Rules, and bead Authority blocks (LOCKED — hq-nb7.18 / hq-nb7.19 / hq-nb7.22)¶
8.9.0 Directory names are not authorities (LOCKED)¶
Permanent invariant: The existence of a directory never grants authority.
Before creating, modifying, or deleting anything, identify the owning system (Git/GitLab, Beads, Gas City, Bluefly Operations, BluCity-Docs). Gas City (~/gt) is not a sixth owner; it is the incomplete Oracle cutover plane. Directory layout is an implementation detail, not an ownership model. Renaming a host path (e.g. PROJECTS/ → Applications/) changes zero architecture.
| Mac path (host only) | Role | Authority |
|---|---|---|
Applications/ |
Canonical local Git working copies | Git + GitLab |
worktrees/ |
Canonical local engineering worktree root (CANONICAL_ENGINEERING_WORKTREE_ROOT=[WORKSPACE-ROOT]/worktrees). FORBIDDEN: BluCity/.gc/worktrees/ — temporary Git worktrees tied to a bead/MR |
Git |
Scratch/ |
Ephemeral agent artifacts | None (disposable) |
Oracle ~/gt |
Temporary Gas City legacy workspace | Incomplete cutover — not target runtime |
NAS /Volumes/AgentPlatform |
Shared storage | Storage host only |
Retired path: PROJECTS/ — do not create, clone into, or reference in new agent instructions. [OBSERVED] Mac canonical clone root is Applications/ (Jul 2026).
Prohibited sentence pattern: “Applications/ is the working authority.” Paths are locations; authorities are systems.
8.9.1 Five authorities (canonical SoR)¶
| Authority | Canonical SoR | Typical host (not the SoR) |
|---|---|---|
| Repository Assets | GitLab | Mac Applications/ checkout; CI; the rig working tree bound in .gc/site.toml |
| Work | Beads (city Dolt + prefix scopes) | Oracle city / rig .beads/ |
| Orchestration | Gas City (gc, pack.toml, city.toml, .gc/site.toml) |
Oracle (or local dev) |
| Deployment | Bluefly Platform (/opt/bluefly) |
Oracle |
| Documentation | BluCity-Docs (policy) / docs.gascity.com (Gas City semantics) | NAS (host); optional Oracle/Mac checkouts |
Oracle ~/gt is observed incomplete cutover, not a sixth authority and not the target SoR. See ADR-0027.
Model:
GitLab → Repository Asset
↓
Gas City Rig (city.toml identity + .gc/site.toml path)
↓
City (root Pack + city.toml + one Dolt server)
↑
Bluefly Platform Deployment
NAS is a shared platform host (docs, packs, operational assets, persistent data)—not another Source / Runtime / Deployment authority.
8.9.2 Agent Execution Rules (permanent)¶
Rule 1 — Claim work first. Before touching anything: bd prime when context is missing → recover identity → gc hook → bd show <bead> → bd update <bead> --claim. bd prime is context recovery, not the work picker. Do not replace gc hook with fleet-wide bd ready unless you are explicitly triaging. If the claim fails, do not work on it—another agent owns it. See beads-work-ownership-contract.md.
Rule 2 — Verify execution authority before opening a file. Resolve object type → canonical authority → host for this bead. If the bead does not identify execution authority, stop and clarify.
Rule 3 — Never create deployment drift. Do not edit production for convenience; do not fix Oracle when the repository is the authority; do not edit NAS merely because it is mounted; do not maintain unsupervised duplicate copies. Ask: “What is the Source of Truth for this object?” If unclear, do not modify.
Rule 4 — Production Oracle is not a sandbox. Experiments, throw-away scripts, undocumented clones, documentation drafts, and alternate configs on Oracle are prohibited unless the claimed bead authorizes them.
Rule 5 — Net-negative ownership. Before writing code: upstream → existing Bluefly → configuration → infrastructure → framework/core/contrib → reusable component. Only then custom code. Success = less owned custom surface after the task than before.
Rule 6 — Runtime boundaries are sacred. Gas City owns orchestration, rigs, sessions, sling, and Pack-supplied roles. Beads own the work graph. Bluefly Platform owns deployment/IaC/agent-docker. Repository Assets own source. BluCity-Docs owns documentation. Do not blur them. Gas City remaining on Oracle is incomplete cutover, not a second owner of those concerns.
Rule 7 — Every change must reduce technical debt. Before closing a bead: did you remove duplication, reduce custom code, prefer upstream, avoid a new authority, leave fewer moving parts?
8.9.3 Mandatory Authority block on every bead¶
Every bead MUST declare (or inherit from its parent) an Authority block before Implementation may mutate filesystems:
Authority:
Source: GitLab | (specific repository)
Runtime: Oracle Town HQ | READ-ONLY | N/A
Deployment: /opt/bluefly | READ-ONLY | N/A
Documentation: BluCity-Docs | N/A
Execute: <host + path this agent may modify>
Paths never infer authority.
8.9.4 Rig registration lifecycle (objective)¶
Repository Asset → Candidate → Planned → Registered Rig → Active Runtime
Registered / Active Runtime only after: successful gt rig add, successful gt doctor validation, and appearance in gt rig list. Register a rig only when the repository requires persistent runtime orchestration (Witness, Refinery, Beads, Sling, Crew, or cross-rig coordination).
8.9.5 Inventory-before-delete (clones)¶
Never delete a clone solely because “another copy exists.” Before Delete, prove the clone is not:
- a deployment working copy
- a Docker/build context
- a bind-mounted runtime asset
- a backup or recovery / intentionally pinned release checkout
- otherwise than an unused duplicate
Only category 5 after Evidence Check is an obvious deletion candidate (Zero-Assumption Convergence Audit (NOT_FOUND)).