PLATFORM BOUNDARIES¶

For every repository: what does it Own, what does it Consume, what does it Produce? This document prevents architectural drift by making implicit ownership explicit. Last updated: 2026-07-30

The Engineering Rule¶

Before creating a new directory, repository, runtime component, configuration file, deployment mechanism, or workflow — first determine whether the capability already exists in the official Gas Town, Gas City, or OpenClaw architecture. If it exists upstream, extend or configure it. If it does not exist upstream, document why Bluefly requires a new capability and clearly define its ownership, inputs, outputs, and lifecycle here.

Platform Layers¶

Layer 1 — Upstream Platform (Do Not Fork)
  ├── Gas City       developer experience, city/pack/agent/formula model
  ├── Gas Town       execution runtime, convoy, beads, polecats, watchdogs
  └── OpenClaw       API gateway, routing, authentication

Layer 2 — Bluefly Platform (Differentiation)
  ├── Business objects, OSSA, DUADP
  ├── Governance, Cedar policies, compliance
  ├── Product catalog, orchestration policy
  └── Deployment topology

Layer 3 — Customer Applications
  ├── Drupal / GovCMS
  ├── Customer products
  └── AI solutions

Boundary Table¶

`blucity` (GitLab: `blueflyio/blu/blucity`)¶


Owns	Gas City city root — runtime declarations for Oracle
Consumes	Packs (via `gc import install`), machine-local state (`.gc/site.toml`)
Produces	Running Gas City city on Oracle — agent topology, formulas, orders
Layer	2 — Bluefly Platform
Committed artifacts	`city.toml`, `pack.toml`, `packs.lock`, `agents/`, `formulas/`, `orders/`, `commands/`, `doctor/`
NOT committed	`.gc/` (machine-local), secrets, rig path bindings
Deployed by	GitLab CI → tag-gated `stamp-release`/`deploy-oracle` components → pinned `git archive` of the release tag → Oracle (corrected 2026-08-24; rsync deployment was removed via blucity!61 after `rsync --delete` destroyed the Gas City work store on 2026-08-23 — the risk this file's own "wrong pattern" example below already warned about)

`blucity-packs` (GitLab: `blueflyio/blu/blucity-packs`)¶


Owns	Shared pack definitions — agents, formulas, orders, doctor checks, commands
Consumes	Nothing (pure producer)
Produces	Pack artifacts: imported by `blucity` and other cities via `gc import install`
Layer	2 — Bluefly Platform
Deployed as	Pack source URL in `pack.toml` `[imports.*]`, pinned in `packs.lock`
NOT on Oracle	Not a runtime checkout. Materialized via `gc import install` only.

`agent-docker` (GitLab: `blueflyio/agent-platform/infra/agent-docker`)¶


Owns	Docker Compose deployment manifest for all containerized services on Oracle
Consumes	Docker images from registry, secrets from `secrets/`, config from `runtime/compose/`
Produces	Running containers: OpenClaw, LiteLLM, Caddy, gascity-dashboard, and other services
Layer	2 — Bluefly Platform (infra)
Deployed by	GitLab CI → build images → push to registry → Oracle `docker compose pull && up -d`
On Oracle	`/opt/bluefly/deployments/agent-docker/` — one of TWO allowed permanent checkouts

`blu-cli` (GitLab: `blueflyio/blu/blu-cli`)¶


Owns	Bluefly CLI tool
Consumes	Bluefly APIs
Produces	NPM package `@bluefly/blu-cli`
Layer	2 — Bluefly Platform
Deployed as	`npm install @bluefly/blu-cli` inside Docker images — NOT a Git checkout on Oracle
NOT on Oracle	Remove `/opt/bluefly/blu-cli` source checkout

`agent-buildkit` (GitLab: `blueflyio/agent-platform/tools/agent-buildkit`)¶


Owns	Bounded, single-target CLI tools — domain-specific operations and thin adapters only (e.g. `buildkit git resolve-structural-conflicts`, `buildkit sync converge-one`). Every command operates on ONE target and exits; none loop, retry, schedule, or dispatch.
Consumes	GitLab API (via `createGitLabClient()`), local git, npm packages for any bounded concurrency/retry/rate-limit need (`p-limit`/`p-retry`/`p-throttle` — never hand-rolled)
Produces	NPM package `@bluefly/agent-buildkit`, structured JSON per invocation for a caller (operator, script, or a Gas City agent `command`) to consume
Layer	2 — Bluefly Platform (tool provider)
Does NOT own	Retry/backoff (→ `gc converge`), scheduling (→ `gc order`; not DSM cron — DSM cron only bootstraps the `gc supervisor` host service itself), multi-step execution (→ `gc formula`), dispatch/routing (→ `gc sling`), repo registration (→ `gc rig`). A generic execution Runtime (concurrency pool, retry framework, claim persistence, factory dispatch/registry) was built here 2026-07-30 and deleted the same day once it proved out against two domains — see `agent-buildkit` git log `feat(factory-runtime)` / `revert(factory-runtime)`. Per the Gas Town→Gas City command map, merge-queue-shaped behavior (`gt mq`) has no built-in `gc` equivalent — it's composed as a Gas City Pack (formulas + orders + agent commands invoking this repo's bounded tools), authored in its own repo — not here.
Deployed as	`npm install @bluefly/agent-buildkit` — NOT a Git checkout on Oracle

`bluguide` (GitLab: `blueflyio/agent-platform/models/bluguide`)¶


Owns	Unknown — SSH access denied to Oracle
Consumes	Unknown
Produces	Unknown
Layer	TBD pending audit
NOT on Oracle	Stub directory; cannot be initialized. Remove as Gas City rig.
Action required	Audit: Is this a pack? An engineering model? If a pack, declare as import. If not runtime, remove.

`blucity-docs` (GitLab: `blueflyio/blu/blucity-docs`)¶


Owns	Platform documentation
Consumes	Content from engineering team
Produces	Documentation artifacts (HTML, Markdown)
Layer	2 — Bluefly Platform (docs)
NOT on Oracle	Documentation is not a runtime concern. Remove as Gas City rig.
On NAS / dev machines	Documentation lives where writers work, not on the production runtime.

`gitlab_components` (GitLab: `blueflyio/gitlab_components`)¶


Owns	Canonical shared CI/CD component library
Consumes	Nothing
Produces	Reusable GitLab CI components imported via `include: component:` syntax
Layer	2 — Bluefly Platform (CI/CD)
Used by	Every Bluefly repository's `.gitlab-ci.yml` via `include:component:`
NOT to be forked	Custom CI jobs should not bypass this library. Extend it instead.

`openclaw` (Upstream)¶


Owns	API gateway, routing, authentication
Consumes	Upstream config, TLS certs via Caddy
Produces	Authenticated, routed API access
Layer	1 — Upstream Platform (do not fork)
On Oracle	Docker image pulled by `agent-docker` compose. Not a source checkout.
Bluefly extension point	Configuration only — routes, upstreams, auth policy in `agent-docker` compose

`gascity-dashboard` (Upstream / Bluefly)¶


Owns	Web dashboard for Gas City supervisor monitoring
Consumes	Gas City supervisor API
Produces	Web UI for agent monitoring
Layer	1 — Upstream (if using upstream image); 2 — Bluefly if custom build
On Oracle	Docker image. Not a source checkout.
Action required	Identify whether upstream image is available or if CI must build and push

Unknown / Legacy (Audit Required)¶

The following directories exist on Oracle without clear ownership:

Path	Current state	Action
`/opt/bluefly/duadp`	Unknown — no evidence of active use	Audit: service? package? → Docker image or delete
`/opt/bluefly/ledger`	Unknown — likely legacy	Audit: active service? → Docker image or delete
`/opt/bluefly/openchamber`	Unknown — likely legacy	Audit: active service? → Docker image or delete

Audit command (run on Oracle):

for d in duadp ledger openchamber; do
  echo "=== $d ==="
  ls /opt/bluefly/$d/ 2>/dev/null | head -5
  systemctl is-active "bluefly-$d" 2>/dev/null || echo "no systemd unit"
  docker ps --filter "name=$d" --format "{{.Names}}" 2>/dev/null || echo "no container"
done

What Oracle Is¶

Oracle
  ↓
Gas Town Runtime (execution engine, convoy, beads, polecats)
  ↓
Gas City Runtime (city supervisor, agents, formulas, orders)
  ↓
OpenClaw (API gateway)
  ↓
Bluefly Runtime (agent-docker compose services)
  ↓
Customer Services

Oracle is not a development workstation. Oracle does not host engineering repositories. Oracle consumes artifacts produced by CI/CD pipelines.

CI/CD Boundary Rule¶

Every Bluefly repository's .gitlab-ci.yml MUST:

Import from blueflyio/gitlab_components via include: component: syntax
NOT implement custom CI jobs that duplicate component library functionality
Deploy artifacts (images, packages) — never source code — to Oracle

# Correct pattern (updated 2026-08-24 — deploy-rsync no longer exists; the wrong-pattern
# example below is exactly the defect that destroyed the Gas City work store on 2026-08-23)
include:
  - component: $CI_SERVER_FQDN/blueflyio/gitlab_components/[email protected]
  - component: $CI_SERVER_FQDN/blueflyio/gitlab_components/[email protected]

# Wrong pattern (do not do this)
deploy:
  script:
    - rsync -avz --delete ... # bespoke deployment logic

Destructive Action Policy¶

Before deleting any repository, branch, or runtime component:

Verify with evidence — list what will be deleted, confirm it matches the target
Check for consumers — search for imports, references, or dependents
Explicit user approval — present the list, get approval before execution
Backup — archive or tag before deletion where reversibility matters

Permanent deletion (GitLab DELETE /projects/:id) is irreversible. No batch deletion script executes without an explicit, verified, user-approved list.

PLATFORM BOUNDARIES¶

The Engineering Rule¶

Platform Layers¶

Boundary Table¶

blucity (GitLab: blueflyio/blu/blucity)¶

blucity-packs (GitLab: blueflyio/blu/blucity-packs)¶

agent-docker (GitLab: blueflyio/agent-platform/infra/agent-docker)¶

blu-cli (GitLab: blueflyio/blu/blu-cli)¶

agent-buildkit (GitLab: blueflyio/agent-platform/tools/agent-buildkit)¶

bluguide (GitLab: blueflyio/agent-platform/models/bluguide)¶

blucity-docs (GitLab: blueflyio/blu/blucity-docs)¶

gitlab_components (GitLab: blueflyio/gitlab_components)¶

openclaw (Upstream)¶

gascity-dashboard (Upstream / Bluefly)¶