Bluefly Platform Glossary¶

Overview¶

This document defines the canonical vocabulary for the Bluefly platform. It establishes standard terminology across the Governance Plane, Execution Plane, and Runtime Plane to ensure consistency in engineering communications, standards, and contracts.

Fences, Not Permission Queues (operator, 2026-08-24, binding — supersedes prior per-instance approval habits)¶

Bluefly is a Light Factory: autonomous work inside explicit, observable, auditable authority boundaries — not humans approving every move. Thomas defines the fences. Agents work freely inside them. Only crossing a fence requires Thomas.

Human approval is a fence, not a default. Required only for genuine boundary crossings: release/v0.1.x → main where explicitly reserved, destructive loss of authoritative state, changing an authority model, external/public representation as Thomas, material production action outside standing delegated authority, granting materially broader credentials, irreversible customer/business decisions, exceptions to locked product scope. Not required for: agent-to-agent communication, read-only investigation, checking another worker's status, normal feature→release delivery already authorized, CI observation, evidence gathering, rerunning a failed bounded test, routing work to the correct specialist, continuing another ready task while one waits, updating a projection from authoritative evidence, or any action already inside an agent's defined authority. A tool reporting "message requires human approval" is a BLOCKED_CAPABILITY=CROSS_SESSION_MESSAGE_TRANSPORT — a tool limit, not a governance requirement; use another path or continue other work. Do not turn Thomas into the transport layer.

No idle waiting. "Waiting on X" / "standing by" / "holding" are not valid states while ready work exists. Loop: rescan → claim ready work → route → verify → replenish → continue. If a dependency is running, check it, then work another ready node — don't sit idle watching it.

Fences by role (illustrative, not exhaustive — extend by the same pattern): Refinery may operate MR source branches, may not force-push main. Mayor may execute authorized Oracle runtime operations, may not redefine tracked source. Forge may build disposable DDEV environments, may not invent production architecture. Harbormaster may write governed backup artifacts to NAS, may not mutate Beads work state. Drupal may implement Drupal-native behavior, may not create a parallel orchestration platform.

Boards are projections, not authority. Beads/Dolt, GitLab, Gas City runtime, and deployment/runtime evidence are the authoritative inputs; a board (including the two canonical operator-designated boards) must be reproducible from them. No human or agent "owns truth" by manually maintaining a board. An unverified session claiming an identity (e.g. "Gas City Agent") does not gain write authority merely by claiming the name — require role/identity/canonical-agent-definition/authority resolved against the canonical OSSA/agent definition first; BLU + Mayor + Witness can resolve this from evidence without escalating to Thomas unless two authoritative definitions genuinely conflict.

Receipts, not narration. Minimum: OBJECTIVE= OWNER= AUTHORITY= SOURCE_SHA= ACTION= RESULT= EVIDENCE= NEXT_ACTION= HUMAN_GATE=. HUMAN_GATE is normally NONE; if not, include EXACT_DECISION= WHY_EXISTING_AUTHORITY_CANNOT_RESOLVE_IT= CONSEQUENCE_OF_YES= CONSEQUENCE_OF_NO=. Never send Thomas a choice another existing authority can decide.

Governing metric stays dollars per closed MVP blocker — not agents active, tokens spent, or messages generated. Deduplicate repeated findings; cache known capability gaps; reassign work with no new evidence within its time-box rather than let it sit.

MVP Scope Lock (operator, 2026-08-24, supersedes all other engineering priority until it closes)¶

The MVP is one narrow, sellable claim, proven end-to-end — not "the whole Bluefly platform works":

From clean source, manufacture a governed AMCS Drupal site twice, from the same canonical composition, with no hand assembly, and produce an auditable receipt.

Concretely: canonical AMCS source correct → empty DDEV Run 001 passes → destroy → empty DDEV Run 002 passes from identical source → behavior checks pass → Witness independently accepts → one customer/design-partner proof ready to show.

No fourth engineering lane until Lane 1 or Lane 2 closes. Only three lanes exist: - Lane 1 — AMCS Factory (the MVP itself): DRUPAL → FORGE → REFINERY → WITNESS - Lane 2 — P0 production safety: MAYOR / SENTINEL / HARBORMASTER - Lane 3 — Customer proof: BLU / Thomas

Anything not directly unblocking the MVP proof, production safety, or a customer conversation is deprioritized — including estate-wide MR convergence and the Cedar/compliance-engine/contractplane-sdk integration chain, unless a specific piece of either directly blocks Lane 1 or is a live P0. Broad audits, doctrine consolidation, and architecture-ambiguity closure (today's earlier work) are real and correct but not MVP-critical — they resume once Lane 1 or Lane 2 closes, not before.

Authority split for engineering spend: Dispatch = token budget/concurrency/timing supervisor (decides how many agents run, kills/reassigns low-yield loops). BLU = value authority (decides whether source work is MVP-relevant, duplicated, or stale). MAYOR = P0 runtime override only. Each specialist = local efficiency responsibility (stop when re-deriving, repeating tool calls, or blocked on a capability it doesn't own). Thomas = budget ceiling and business priority only, not token-by-token execution.

Governing metric: dollars per closed MVP blocker, not tokens per agent, not agent count. Dispatch owns that metric.

Default concurrency: 2 executors, 1 verifier, 1 supervisor, max 4 active specialists — increase only when work is truly independent and MVP-critical. Idle agents consume zero work; do not keep all specialists "alive" because they exist.

Every active agent answers: MVP_BLOCKER= EXPECTED_VALUE= NEXT_PROOF= TIME_BOX= STOP_CONDITION=. If MVP_BLOCKER=NO, suspend unless P0. Time-boxes: 15min diagnostic must show new evidence; 30min must show root cause narrowed / owner identified / fix underway / explicit blocker; 45min with no measurable progress stops and reassigns — do not reward persistence that produces no new evidence.

Report to Thomas only: MVP_PERCENT= BURNING_AGENTS= ESTIMATED_ACTIVE_LANES= CURRENT_MVP_BLOCKER= NEXT_PROOF= HUMAN_DECISION_REQUIRED= WASTE_STOPPED=. Not token-level chatter. Terminal state: MVP_MOVING — SPEND_BOUNDED.

Standing Constraint (operator, 2026-08-24, binding on all agents and all work)¶

"NO NEW PROJECTS, NO NEW MODULES, NO NEW RECIPES OR TEMPLATES. UPDATE CURATE AND OPTIMIZE WHAT WE HAVE"

Not scoped to the release path or to today — binds every agent, every task. If a task appears to require a new project, module, recipe, or template, that requirement is a signal to find the existing thing it duplicates, not a license to create one. Sits directly under the standing custom-code reduction standard: Bluefly should own less tomorrow than it owns today.

Why this is not abstract: the three architecture ambiguities closed via source audit on 2026-08-24 (contextcontrol_amcs, the AMC schema, the archived AMCS-ARCHITECTURE.md enforcement chain — see below) were all cases of a document describing an artifact that did not exist or was not what the document claimed. The estate has been accumulating described artifacts faster than real ones. This constraint is the direct corrective. It also means an archived document describing unbuilt machinery (ubuntu-1vfr) is doubly out of bounds — not current architecture, and not a specification to build to under this constraint.

Extended (operator, same day): also covers site templates — no new site templates. Diagnostic sharpened: if a task appears to require a new project/module/recipe/template/site template, treat that as a signal that ownership is wrong, or that a duplicate capability already exists — not as permission to create. Permitted actions: update, curate, optimize, consolidate, delete.

Source authority order, binding for every claim in this glossary and in any audit that feeds it: LIVE RUNTIME READBACK → CURRENT GITLAB SOURCE → OWNING IMPLEMENTATION → CI EVIDENCE → DURABLE STANDARDS → GENERATED/ARCHIVED MATERIAL → CONVERSATION

Human/team ownership fields (operator, 2026-08-24): Bluefly is a solo-developer estate — there is one human, the bluefly GitLab account. Do not return UNABLE_TO_VERIFY for a human/team owner field and do not check CODEOWNERS-style entries for confirmation; every such entry resolves to the same one person, and checking adds nothing. The only ownership question that actually matters is which existing repository or artifact is the canonical implementation of a capability — a source question, answerable from current source, distinct from "which person." Any process step phrased as needing "Maintainer sign-off" or naming a team (@blueflyio/security-team, etc.) describes an organizational structure that does not exist — a false-authority problem in the same family as a false-artifact claim, and in scope of the no-new-artifacts constraint above (false structure, not just false code). Every source claim carries PROJECT= PATH= BRANCH= SHA=. Two explicit prohibitions: do not infer behavior from a project/module/service name; do not treat _ARCHIVE content as current architecture (this is ubuntu-1vfr's finding promoted to standing doctrine, not a one-off).

Canonical Definitions¶

Planes of Operation¶

Governance Plane: The control layer (owned by Bluefly) responsible for defining policy, auditing, approvals, and enforcing Desired State. It does not execute workloads.
Execution Plane: The orchestration layer (owned by Gas City) responsible for reading the Desired State, reconciling dependencies, and driving agents to achieve the state.
Runtime Plane: The physical or virtual infrastructure where workloads and agents actually execute. It is disposable, immutable, and owns no state.
Plane (general): An architectural layer grouping one category of responsibility across a system (control, data, context). Defines a separation of concerns, not necessarily one product or service. See Context Plane.

Core Architecture Entities¶

Bluefly: The business authority and Governance Plane. It defines the object graph, policies, and Desired State, but delegates execution to Gas City.
Gas City: The orchestration platform that operates the Execution Plane. It reads Bluefly's Release Bundles and reconciles them into the Runtime Plane.
Oracle: The disposable, immutable infrastructure provider hosting the Runtime Plane. It holds no Git repositories, no manual deployment scripts, and is rebuilt entirely from IaC.

State & Deployment¶

Business Intent: The strategic goal or operational outcome required by Bluefly, declared asynchronously and abstractly, distinct from implementation details.
Desired State: The exact, versioned, declarative configuration required to fulfill Business Intent. This is compiled by Bluefly and governs what must exist.
Release Bundle: An immutable, versioned artifact containing the compiled Desired State, configurations, and pack references required for a Deployment.
Deployment: The act of transitioning a Target Environment to a specific Release Bundle via Governance Plane approval. Deployments are never manual script executions.
Environment: A bounded operational domain (e.g., Development, Staging, Production) governed by policies.
Reconciliation: The continuous, autonomous process (performed by Gas City) of comparing Runtime Plane realities against the Desired State and executing formulas to eliminate drift.

Capabilities & Contracts¶

Capability: Answers CAN — what an Actor, Agent, Tool, module, service, or system is able to do: a defined, reusable business function or technical service. Capability implies neither responsibility (Ownership) nor permission (Authority). Every Capability has exactly one authoritative implementation owner.
Pack: A portable, version-controlled unit of agent behavior, formulas, and skills used by Gas City to orchestrate work.
Contract: A declarative standard defining how agents behave, communicate, and resolve dependencies.
Authority: Answers MAY — what an Actor is permitted to decide, change, approve, or execute. Distinct from Capability (CAN) and Ownership (SHOULD): an Actor can be capable of an action and responsible for a task while lacking authority for a particular effect.
Authoritative Source: The system, record, or artifact responsible for maintaining a particular fact, rule, decision, capability, or state — the definitive source of truth for its domain (e.g. Git for source, Beads/Dolt for work, Gas City for orchestration). Generated indexes, summaries, search results, and Context Capsules may point to it but never become authoritative by repeating it. (This was the previous meaning of "Authority" in this glossary, renamed 2026-10-01.)

Standards & Product Terminology (Founder-locked, 2026-08-24)¶

OSSA: Open Standard for Software Agents. Use exactly this expansion everywhere unless the public standards site (openstandardagents.org) declares a different one, in which case that site wins.
DUADP: Decentralized Universal AI Discovery Protocol. Public protocol definition wins. "Deterministic Universal Agent Deployment Pattern" is a retired, incorrect expansion — do not use.
AMCS: Agent-Managed Content System.
AMC: Agent Marketplace Contract. CLOSED, AMC_SCHEMA=NO_CURRENT_CANONICAL_AMC_SCHEMA_FOUND (BLU fork audit, 2026-08-24, group-wide blob search for "Agent Marketplace Contract"/AMC bundle/schema artifacts, zero hits). No canonical AMC schema exists to require anything — do not describe kagent/LiteLLM/agentgateway as "AMC primitives" (required or optional) until a real schema exists; describe them by their actual current posture instead: KAGENT_OSSA_CLASSIFICATION=EXTENSION (spec/v0.5/extensions/kagent/kagent.schema.json, not in any base/required OSSA schema), KAGENT_DRUPAL_CLASSIFICATION=OPTIONAL_INTEGRATION (ai_agents_kagent depends on ai_agents_ossa, not the reverse; lifecycle: experimental; absent from recipe_blucity/recipe_amcs requirements), LITELLM_CLASSIFICATION=OPTIONAL_PROVIDER (ai_provider_litellm, standard Drupal AI provider plugin, not a dependency other modules require), AGENTGATEWAY_CLASSIFICATION=OPTIONAL_GATEWAY (MCP policy-gateway integration, its own docs describe it as a setup demo for Cedar-gated MCP federation, not a mandated dependency). Grounded in prior practice too (Foundry, 2026-08-24): ossa-deploy/OWNERSHIP.md lists these as named, separate, optional integration modules alongside many peers, none privileged as required core.
Canvas: drupal/canvas. "Experience Builder" is historic/frozen terminology and must not appear as a description of the current implementation.
Gas City: Canonical term for the orchestration platform. "Gas Town" is historical/reference-pack terminology — do not describe Gas Town as the substrate underneath Gas City.
Light / Dark Factory: A public operating metaphor only. Not a second runtime or architecture layer — do not use in architecture topology docs. "Dark Factory" describes an operating mode, not infrastructure. Origin, verified against both primary sources (BLU, 2026-08-24): Yegge coined "dark factory" as unobserved background agent work, then described Gas City itself as a "Light Factory" — a dark factory built with observability maximized ("Gas City: The Light Factory... I have begun to think of Gas City as a Light Factory... or at least, a very well-lit dark one"). Scola's article borrows that same distinction by analogy and applies it to Drupal's governance posture, not to Gas City's own architecture. Binding synthesis (Scola's proposed wording, confirmed against both sources): Gas City supplies the role-agnostic orchestration substrate; Gas Town supplies one opinionated operating pack and vocabulary; Bluefly's Light Factory is the governed operating model applied across that substrate — explicit authority, durable work, observable execution, verifiable handoffs, policy enforcement, auditable receipts; Drupal is the first durable customer product manufactured and operated through that model. Neither source frames Light Factory as a competing runtime to Gas City — a diagram may label a deployment/operating posture Light or Dark, but must never draw them as separate orchestration systems.

OSSA / DUADP / Gas City / Drupal Layering (operator doctrine, routed via Forge, 2026-08-24)¶

Layering: OSSA (portable agent/skill/tool contract) → DUADP (discovery, federation, resolution) → runtimes (Gas City execution/orchestration, Drupal business/content plane, other runtimes: Kubernetes/MCP/A2A/etc). OSSA is the sole authoritative agent-definition source — Gas City agent.toml, Drupal config entities, and DUADP registry rows are projections of it, never independent sources of truth. DUADP is the sole authoritative discovery contract (a conforming node exposes /.well-known/duadp.json plus at least one OSSA-formatted resource endpoint). Gas City is an execution projection of OSSA/DUADP into its native primitives (agents, packs, formulas, orders, sessions, beads) — do not put DUADP inside Gas City core, do not build a second registry inside Gas City, do not build a Bluefly scheduler/discovery daemon around it. Drupal is the business-facing DUADP node and OSSA bridge via ai_agents_ossa (OSSA↔Drupal AI Agent projection only, not a discovery implementation) and drupal/duadp (registry/discovery/federation only, not an agent runtime).
Discovery is not execution (governance chain, binding): DISCOVER → RESOLVE DID/GAID → VERIFY SIGNATURE + LIFECYCLE → VALIDATE OSSA → EVALUATE CEDAR/GOVERNANCE POLICY → IMPORT/PROJECT → OPERATOR OR POLICY-GATED EXECUTION → GAS CITY SESSION/FORMULA → RECEIPT. A discovered resource must never execute merely because it was discovered. Not yet true in the reference implementation (Refinery source audit, 2026-08-24, tracked as ubuntu-7lk2 P1): drupal/duadp's federation endpoints (registerPeer, receiveRevocation) have zero auth check, every DUADP route declares _access: TRUE bypassing Drupal's route-level access entirely, and a public_key is advertised in the manifest but never used — no signature verification exists anywhere in the codebase. The VERIFY SIGNATURE + LIFECYCLE step above is aspirational until this is fixed; do not treat federation trust as enforced.
Orchestration-creep boundary: DUADP discovers orchestration capabilities; it must not become an orchestrator itself. Endpoints like /api/v1/delegate and /api/v1/orchestration in the DUADP root README are flagged as non-core-extension candidates or removal candidates from the normative protocol — DUADP owning execution DAG semantics recreates the exact ownership overlap the platform is eliminating (Gas City = orchestration, DUADP = discovery, OSSA = definition, MCP/A2A = invocation, Drupal = business authority).
DUADP normative-spec contradictions (BLU direct verification against openstandardagents.org and openstandardagents.org/duadp/, 2026-08-24 — supersedes the earlier unverified list): (1) CONFIRMED — the live openstandardagents.org/duadp/ page itself already reads "Powered by the Open Standard for Software Agents (OSSA)" and titles itself "Decentralized Universal AI Discovery Protocol (DUADP)" — both expansions match founder decision exactly. If any other copy of the normative spec text differs from this, that copy is the stale one to fix, not the live public site. (2) RESOLVED (Sentinel, 2026-08-24, source-verified): the live spec's own self-claim naming ai_agents_marketplace as the DUADP reference implementation does NOT survive a source check — project 80431142's ai_agents_marketplace module contains zero DUADP code (verified group-wide within that repo). The real protocol node is duadp (project 80049553, machine name duadp not duadp_client — earlier reference to "duadp_client" was a naming error, corrected here), evidenced by duadp.services.yml's federation HTTP client, a DuadpNode config entity + AgentManager, the four protocol-verb Tool plugins (DuadpDiscover/DuadpRegister/DuadpResolve/DuadpPublish), Drush commands, and a discovery-telemetry Grafana dashboard. ai_agents_marketplace is a genuinely different capability — a Drupal-native OSSA-agent catalog built on content entities, views, facets, and analytics, with dependencies on node/taxonomy/field/views/search_api/facets/ai_agents_orchestra. These are not duplicates and coexist by design — merging them would create the duplicate the standing constraint exists to prevent, not remove one. Per the source authority order (current GitLab source outranks durable standards), the spec's self-claim is what needs correcting, not the code — same shape as ubuntu-1vfr (a document asserting an implementation into existence). NOT_ESTABLISHED, stated rather than glossed over: whether ai_agents_marketplace is supposed to speak DUADP and simply doesn't yet — source proves it doesn't today, source cannot prove intent; if that gap is real, the fix extends the existing module, never adds a third one. Refinery's federation auth-gap audit (ubuntu-7lk2) was correctly aimed at duadp, the real protocol node — not affected by this correction. (3) the payload-format MUST-vs-README contradiction is independently confirmed: the official conformance table states OSSA-formatted payloads (apiVersion: ossa/v0.4 or later) as a MUST-level requirement — if any README elsewhere says "any payload format" that contradicts the live spec, the live spec's MUST wins.
Foundation-vs-domain recipe placement: recipe_blucity (foundation) should require/configure the provider-neutral platform capability — drupal/ai, drupal/ai_agents, drupal/ai_agents_ossa, drupal/duadp, drupal/tool, drupal/key — once audited as actually absent from the canonical source (not assumed). recipe_amcs (domain) contains only AMCS-specific agent manifests, discovery policy, and product behavior. Do not manually add DUADP to amcs-demo. Not yet actioned — this is an audit-then-add sequence, not standing authorization to modify recipe_blucity today.
OSSA → Gas City projection gap: no exporter from OSSA to Gas City primitives currently exists in the public OSSA package material. If built, it belongs in the OSSA-owning repo as a thin adapter/exporter (conceptually ossa export agent.ossa.yaml --to gascity), not as Gas City source code, and DUADP resolution/sync on the Gas City side should be exec orders, not a standing agent. Not yet built — bounded platform-adapter gap, not authorization to start building it.
End-to-end proof target (not yet executed): publish an OSSA agent in Drupal → Drupal DUADP exposes it → Gas City resolves the GAID through DUADP → verifies OSSA + DID + policy → projects the agent into Gas City → executes one bead/formula → result returns to Drupal → signed/auditable receipt. This is the bounded transaction that would demonstrate "define once with OSSA, discover anywhere with DUADP, execute through Gas City, govern and productize through Drupal" — requires operator authorization before implementation, same as any other cross-repo execution work.

Commercial Model (Founder-locked, 2026-08-24)¶

Bluefly's 2026 commercial motion: sells governed modernization outcomes (customer-owned Drupal modernization delivered through the Bluefly Factory), not a marketplace/orchestration-seat product. Sequence: modernization lane → operate retainer → reusable product package → design-partner proof → repeatable platform capability. Standards/governance (OSSA, DUADP, ContextControl, ContractPlane/Cedar, evidence, certification, marketplace) are the moat and eventual scaling mechanism — they do not need to carry revenue before the company has customers.
Drupal's role: Drupal is Bluefly's first-class customer product substrate and business authority — the first reference implementation of the wider governed-organization contract. It is not the Bluefly control plane. Drupal may own business state, structured content, access, workflow, editorial experience, Canvas/SDC experience, Recipes/configuration, and customer-specific product behavior. Drupal must not become the owner of universal agent identity, cross-runtime discovery, generic policy engines, orchestration, durable platform evidence infrastructure, or runtime-independent governance contracts (the "Drupal Gravity" guardrail).
Immediate product proof: the Bluefly Drupal Launch Factory, demonstrated through AMCS. Layering: site_template_amcs (canonical reusable product) composes recipe_amcs (domain composition) which composes recipe_blucity (platform foundation). Acceptance proof is two independently created, customer-shaped governed Drupal sites built from the same canonical foundation with no hand assembly — not merely "a Recipe that works."
Canonical chain and gap classification (operator, 2026-08-24): the full chain is site_template_amcs → recipe_blucity → recipe_amcs → existing contrib modules → Canvas / SDC / theme → clean consumer. amcs-demo is explicitly disposable — never patch it manually. Any missing capability is a CANONICAL_PRODUCT_COMPOSITION_GAP, assigned to exactly one existing owner from that chain; never fixed by creating another site template, recipe, module, or project — if an existing owner can be extended, that is the required path. Consequence, binding: a finding phrased as "amcs-demo needs X" is misclassified by construction — the defect is always upstream of the demo, in whichever link of the chain owns the capability. Route findings there, not to the demo.
MASTER-PROMPT.md: does not exist. Do not reference it as authoritative and do not recreate it to satisfy old references — replace those back-references with the actual canonical doctrine/registry they meant to point to.
site_template_amcs path: blueflyio/amcs/site_template_amcs is authoritative. Correct stale references rather than maintaining aliases.
contextcontrol_amcs: CLOSED (BLU fork audit, 2026-08-24, GitLab source verified group-wide, zero exclusions). MODULE_EXISTS=NO — no contextcontrol_amcs.info.yml, no implementation, no config export reference exists anywhere in current non-archived source. BOOTSTRAP_BREAKING=NOT_ESTABLISHED, confirmed correct. Only live-source occurrence is doc text on blucity-docs main (stale, release/v0.1.x already corrected — tracked as ubuntu-o87w). ContextControl-the-product is confirmed distinct and real (blueflyio/contextcontrol.ai/contextcontrol-ai, context-cli). No adapter-naming action needed — there is no module to rename.
Six trust vocabularies (identity assurance, runtime autonomy/posture, policy sensitivity, constitutional authority, OSSA conformance, registry/supply-chain trust): do not merge into one ladder — they are different dimensions. Represent as a Trust Model Matrix with explicit crosswalks, not a seventh hierarchy.
Cedar policy helpers (local_evaluator, dev_policy_sync, gitlab_policy_sync, cedar_policy module project 76284311): CLOSED (BLU fork audit, 2026-08-24, source verified). These are real, non-stub, production-routable code — not "dev/test only" doctrine. All three: PRODUCTION_CAPABLE — NOT YET AUTHORIZED AS PRODUCTION AUTHORITY (technically callable in production today via real controllers/forms/ECA/Tool API, zero environment guard; dev_policy_sync and gitlab_policy_sync mutate real remote/local state; none of the three read any config key literally named enforcement_mode — the module defines no such key). Technical capability and governance authorization are separate axes; do not conflate "runs in dev-named code paths" with "cannot run in production" — it can. Real defect, not doctrine: zero environment guard exists (ubuntu-bnug, P1). Separately, archived AMCS-ARCHITECTURE.md describes a fail-closed enforcement_mode chain across these services that was never built (ubuntu-1vfr) — do not cite that archive as current architecture.
Composer registry endpoint (Foundry, 2026-08-24): the "group vs groups" split is folklore — GitLab's documented endpoint is singular group (.../api/v4/group/<group_id>/-/packages/composer/packages.json), confirmed against 3 real consumer composer.json files (app.drupl.ai, contractplane.ai-website, marketplace-app.drupl.ai), none of which use groups. The real inconsistency is the trailing /packages.json: present (canonical) in 2 of the 3, absent in app.drupl.ai — unverified whether GitLab still resolves without it. Auth: app.drupl.ai's CI correctly sets composer config --global gitlab-token.gitlab.com, but its composer.json also embeds a redundant Authorization: Bearer header in the repository's options.http block (env-interpolated, not a literal secret, but two auth paths layered where there should be one). Publish side (Foundry, follow-up): consistent and clean across 5 checked repos — curl -X POST "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/composer?tag=${CI_COMMIT_TAG}" -H "JOB-TOKEN: ${CI_JOB_TOKEN}" on semver tag push, CI_JOB_TOKEN only, no fix needed. Publish being per-project while consume is group-scoped is GitLab's actual Composer registry model (publish per-project, group endpoint aggregates for discovery) — not an inconsistency to "fix" into one endpoint. Third consume-side inconsistency: openclaw's example uses the numeric group ID (87749026) where 3 other consumer repos use the name (blueflyio) — standardize on the name.

Context Architecture (operator vocabulary, 2026-10-01 — defines meaning, not implementation)¶

One definition per term; reference these rather than redefining them elsewhere. Which systems hold each kind of context is mapped in Engineering-Standard/context-plane/README.md; Drupal-specific usage is in drupal-glossary.md. Governing line: context is what an Actor needs to know right now to make the next decision correctly — compiled, not dumped.

Actors, work and intent * Actor: Any identifiable participant that can take or request an action in a governed workflow — a person, AI agent, service, or other system. Broader than Agent. * Agent (Bluefly usage): A software Actor that works toward a goal with some independence from step-by-step human direction. It has Capabilities and may receive work, use Skills and Tools, consume Context, and produce actions or Evidence, always constrained by Ownership and Authority. (Upstream Gas City usage: see Agent (upstream usage) below.) * Ownership: Answers SHOULD — what an Actor is accountable for deciding, maintaining, delivering, or resolving. Situational; distinct from Capability (CAN) and Authority (MAY). * Intent: What the Actor is trying to accomplish, in its own terms ("build a form"), not the module or API that implements it. Intent informs routing and authorization; it never grants authority. * Intent Routing: Mapping an Intent to the appropriate Capability, Procedure, Tool, task briefing, or source without the Actor already knowing which component owns the problem. * Commitment: Work the organization has agreed must be accomplished — an obligation, not a statement about the world. Beads are the primary durable Commitments in the Factory. * Work Context: The context derived from the current Commitment and work graph: goal, premise, owner, status, dependencies, blockers, related work, previous attempts, decisions, and evidence. Primarily from Beads and Dolt. A Bead is work context, not general organizational knowledge. * Policy: A governed rule determining whether an action or condition is allowed, denied, required, or constrained. The human-readable rule and its enforced representation must stay traceable to each other.

Context * Context: The information an Actor needs for the current situation — applicable knowledge, current state, decisions, constraints, work, and evidence — to make the next decision or action correctly. Situational and selective; not documentation, memory, search results, or everything the organization knows. * Agent Context: The Context made available to a specific Agent for a specific situation — the relevant subset, not everything associated with the Agent. * Situational Context: Context specific to the current Actor, goal, work item, environment, time, risk, and state. Changes faster than doctrine; a primary input to a Context Capsule. * Temporal Context: Information interpreted relative to time — what is true now, what was true when a Decision was made, and what changed since an earlier execution. * Temporary Context: Context assembled for one execution and discarded or regenerated rather than maintained. A Context Capsule is Temporary Context. * Knowledge: Durable information that may help an Actor understand a domain. Broader than Context; Context is the relevant subset of knowledge, authority, state, evidence, and work. * Governed Context: Context whose source, ownership, authority, applicability, lifecycle, and review requirements are known and enforceable. * Minimum Sufficient Trusted Context: The smallest amount of current, applicable, authoritative information needed for the next decision or action. Not minimum tokens at any cost — required authority, safety, evidence, and conflicts must stay in. * Context Architecture: The practice of arranging what an organization knows so Actors receive the right information where it is needed while the organization keeps it current and governed: what belongs in durable Procedures versus changeable context, where it lives, who may change it, when it applies, and how it is retrieved. Broader than prompt engineering or token optimization. * Context Engineering: The general practice of designing and optimizing information given to AI systems. Context Architecture is the narrower organizational concern of structuring, governing, and delivering knowledge, rules, decisions, procedures, and situational information over time. * Context Plane: The architectural layer where governed, changeable organizational context is maintained and made available to workflows and Agents independently of Agent implementation, so behavior changes by changing context rather than rewriting the Agent or Procedure. A concern, not a single product. Systems map: Engineering-Standard/context-plane/README.md. * Context Control: The function of governing which context is valid, applicable, approved, visible, changeable, and available — its lifecycle, authority, review, freshness, and applicability. A function; not synonymous with the ContextControl product. * Context Control Plan: A governed definition of how context is supplied and controlled for a workflow or class of work: required context, authoritative sources, Procedures, Capability requirements, expected outputs, review or approval points, freshness rules, and execution constraints. * ContextControl (product): Bluefly's human and business control surface for governed AI operations — context curation, approvals, policy bindings, review, configuration, evidence presentation, exceptions, and operational control. It is not the Agent runtime, work database, orchestration engine, policy engine, identity provider, token issuer, or a generic RAG platform; it integrates with those authorities. * Context Compiler: The conceptual assembly layer that determines what an Actor needs to know right now. It resolves the Actor, current work, Ownership, Capability, Authority, relevant sources, freshness, conflicts, and token budget, and produces a Context Capsule. It queries the authorities that own each dimension and never becomes the authority for what it assembles. * Context Capsule: A disposable package of Minimum Sufficient Trusted Context for one Actor, goal, work item, and moment — relevant Claims, Procedures, Commitments, Observations, constraints, conflicts, and authority references. Consumed for execution; its sources remain authoritative. It references security state and never carries credentials. * Context API: The conceptual interface through which an Actor requests context for a given goal, work item, role, environment, authority, and moment, and receives a Context Capsule rather than an undifferentiated set of documents. * Context Piece: A small reusable portion of context that can be independently addressed, maintained, and assembled, so an Agent can retrieve only what it needs instead of a whole guide. * Context Card: A proposed addressable unit attaching provenance and lifecycle to a Claim, Decision, or Observation — source, owner, authority, applicability, freshness, mutability, verification, supersession, conflicts. Conceptual; not necessarily a UI card or file. * Context Specificity: How narrowly a piece of context applies (by time, location, customer, product, jurisdiction, workflow stage). More specific applicable context may refine or override a broader default. * Context Elevation: The process by which more specific applicable context overrides or refines more general context for a situation (a sale policy over a default return policy, itself constrained by local law). The most applicable valid context governs. * Context Conflict: Two relevant sources make incompatible Claims and neither can safely be ignored. Surface it with both sources and their authority; never resolve it silently by retrieval ranking or model preference. * Negative Context: What an Actor should not do, assume, reopen, or rediscover — prohibited actions, disproven assumptions, superseded approaches, known dead ends, settled decisions. Itself invalidatable by new evidence. * Do Not Rediscover: An explicit Negative Context entry naming questions or paths already sufficiently resolved, so Agents do not re-spend time and tokens on settled work unless new evidence invalidates it. * Token Budget: The model context allotted to a task or assembly. A prioritization constraint for the Context Compiler; it must never cause required authority, safety, evidence, or conflict information to be dropped. * Task Briefing: An assembly of the context needed for a specific class of work — narrower than a guide, pointing to authoritative sources for depth. * Task Atlas: An intent-oriented context surface routing an Agent from what it is trying to accomplish to the minimum relevant Claims, Procedures, Ownership, risks, and sources. A projection and router, never a second source of doctrine. First pilot: Drupal Task Atlas (bead dam-16u; see drupal-glossary.md).

Claims, evidence and decisions * Source: The identifiable origin of a Claim, Procedure, Decision, or Observation. Provenance only; does not by itself establish authority. * Claim (context assertion): A small, addressable assertion about something believed, decided, required, or observed, traceable to its Source and able to carry owner, authority, applicability, freshness, evidence, conflict, and supersession metadata. Not the Beads claim operation (taking ownership of work; see Claim under Upstream Canonical Terminology). * Proposal: A suggested Claim, Procedure, Decision, or context that has not yet received the authority to become accepted or binding. Must stay distinguishable from approved context. * Decision: An explicit choice that resolves an open question and binds until changed or superseded. Distinct from proposals, observations, and historical discussion. * Decision Record: The durable evidence of a Decision — what, why, under whose authority, when effective, and what it supersedes. * Doctrine: An accepted rule or operating principle intended to stay authoritative until deliberately changed. Long freshness horizon; still supersedable. * Observation: Time-bound evidence about the state of the world, carrying enough timing and provenance to judge whether it is still usable. * Runtime Fact: A Claim derived from direct observation of a running system. Highly authoritative for the moment measured, usually short-lived; never copied into doctrine as permanently true. * Current State: The present condition of a system, workflow, work item, or environment. Shorter useful life than doctrine; needs stronger freshness expectations. * Evidence: Information that supports or disproves a Claim, verifies an outcome, or shows an action occurred. Traceable to its source; never confused with the Claim it supports or with a Decision. Interpretation of evidence is a separate step and can be wrong while the evidence is valid. * Epistemic State: The knowledge status of a Claim — e.g. Theory, Hypothesis, Investigated, Contested, Verified, Proven, Not Established. Kept separate from whether it is approved, implemented, current, or binding. * Verified: Checked against defined evidence, stating what was tested and when. Not permanent proof where the subject can change. * Proven: Demonstrated by sufficiently strong evidence for a defined scope and environment. Not universally or permanently true.

Freshness and invalidation * Freshness: Whether information is recent enough to use safely for its purpose. Doctrine may stay fresh for years; runtime health or active ownership may go stale in minutes. * Freshness Class: A grouping of context by how quickly it becomes unreliable, setting a reusable re-verification expectation. * Reverify After: When context should be checked again if no earlier invalidating event occurs. A freshness control, not a deletion time. * Reverification: Checking that previously accepted information or evidence remains valid, triggered by time, an Event, a changed dependency, or a new version. * Stale: Possibly valid when produced, no longer fresh enough to rely on without re-verification. Stale does not mean false. * Superseded: Deliberately replaced by a newer Decision, Claim, Policy, or Procedure. Kept for history; never governs current execution. * Invalidation: Marking previously usable context as unusable, stale, or needing re-verification — caused by time, events, superseding authority, changed applicability, or contradictory evidence. * Time Invalidation: Invalidation because a defined period elapsed; suits runtime state, active ownership, and version-sensitive guidance. * Event Invalidation: Invalidation caused by a concrete event — a deployment, merged change, ownership or policy change, release, or closed work item. * Authority Invalidation: Invalidation because the Decision, Policy, or Authority behind the context was superseded, revoked, or replaced — a change in governing authority, not the passage of time. * Event: An immutable notification that something happened. Events drive refresh and invalidation; they do not replace work state, policy, or evidence.

Procedures, tools and generated surfaces * Procedure: A reusable definition of how to perform a class of work. Holds stable method; obtains changing state, ownership, policy, and evidence dynamically. * Skill: A reusable Agent Procedure for a class of work — method, decision points, required context, relevant Tools, expected evidence — that obtains versions, owners, and current facts dynamically rather than embedding them. * Skills API: The conceptual interface for discovering and consuming Skills: what a Skill does, when it applies, inputs and outputs, required Tools, context and Authority, and how completion is verified. Skills compose Tools without duplicating their schemas. * Tool: An executable capability an Agent can invoke against a system. Describes an action; does not decide when to use it or whether the Agent may. * Tool API: The typed executable-capability layer through which operations are discovered and invoked, with their contracts. Skills use Tool API capabilities; neither Skills nor Tools grant Authority. * Process Recipe: A reusable Procedure for one step of a broader process in a specific environment (Drupal, Python, Go, macOS, Linux); the process stays stable while the recipe varies. * Tooling Recipe: A reusable Procedure naming which Tools to use and how for a kind of work or environment. * Pre/Post Context Handshake: The mandatory steps around meaningful Agent work. Pre-execution resolves identity, goal, current work, Ownership, Capability, Authority, applicable context, recent changes, conflicts, and freshness to assemble the Context Capsule. Post-execution records what changed, evidence created, what was learned or disproven, work-state changes, and which context must now be invalidated, refreshed, or re-verified. Also called the pre-/post-execution hooks. * Generated Projection: Machine-produced material derived from Authoritative Sources for discovery or consumption — indexes, .agents/ artifacts, llms.txt, skills and tool catalogs, intent maps, task briefings. Disposable and regenerable; must never silently become a competing authority. * .agents/: The proposed standard project-facing interface exposing Agent-relevant context, Skills, Tool references, manifests, plans, and routing metadata. Its contents should be Generated Projections validated from authoritative sources, not independently maintained copies of rules or current state.

Upstream substrates (Bluefly role) * Dolt: The versioned data layer under durable Factory state. Its architectural role is temporal: what is true now, what was recorded earlier, when state changed, and what the work graph looked like at a point in time. * QMD: The semantic discovery and relevance layer. It answers what might be relevant — never what is true, authoritative, current, or permitted; those belong to authority, freshness, and policy mechanisms.

Technology Reduction (product vocabulary — authority: `products/Technology-Reduction/Product-Definition.md`)¶

Technology Reduction: Identifying technology an organization no longer needs to own, maintain, or customize, and safely retiring, consolidating, or replacing it with supported capabilities while preserving the business outcome.
Continuous Technology Reduction: The ongoing form of that practice — retiring or consolidating unneeded technology and preventing unnecessary custom technology from accumulating again.
Maintenance Surface: Everything an organization must actively maintain, secure, test, upgrade, or support: software, infrastructure, dependencies, credentials, integrations, configuration, and operational mechanisms.
Ownership Removed: The technology responsibility an organization no longer carries because unnecessary custom software, integrations, infrastructure, credentials, or processes were safely retired, consolidated, or moved to supported capabilities.
Reduction Report: The recurring customer-facing record of reduction outcomes: what was retired, consolidated, or retained; Maintenance Surface removed; supporting evidence; and measurable operating burden reduced.
Assessment + Remediation: A delivery model that first establishes what should change and why (evidence and priorities), then carries out the approved, bounded changes and verifies the outcome.

Upstream Canonical Terminology (Gas City / Beads glossary, RETRIEVED 2026-09-02)¶

Sourced directly from the upstream canonical glossary and product pages (gascity.com/guide/software-factory-glossary/, gascity.com/guide/gas-city-gas-town-gasworks-whos-who/, gascity.com/about/) — cite these, do not re-derive local paraphrases that drift from them.

Bead: "A durable unit of structured agent work" recording title, status, priority, assignee, notes, and relationships. RETRIEVED.
Beads (the protocol): "The open protocol for durable agent work and the open-source work-state substrate." Distinct from a single bead. RETRIEVED.
Formula: "Gas City's technical definition of a workflow: a readable TOML graph" declaring steps, dependencies, routing, and control flow; compiles into a materialized bead graph ("local run") of root + child step beads. RETRIEVED.
Order: "Gas City's technical automation definition" pairing a trigger (schedule, event, condition, or manual) with an action (a formula or a command). RETRIEVED — corrects any local phrasing that describes Orders only as "cron/event/cooldown"; cooldown is a Bluefly usage pattern of the condition/event trigger types, not a fourth upstream trigger kind.
Rig: "A project, repository, or workspace registered with Gas City" providing work and agent scope. RETRIEVED.
Pack: "A reusable bundle of factory configuration: agent templates, workflows, automations, prompts, and supporting assets." RETRIEVED.
Agent (upstream usage): "A configured coding agent" — CLI harness + provider + model + permissions + skills. RETRIEVED.
Event (upstream usage): "An immutable notification fired by Gas City activity," exposed via list/stream/cursor APIs — local observation, not a retained enterprise audit record. RETRIEVED.
Convoy: "A bead-backed grouping of related work used to track a larger delivery." Not previously catalogued here. RETRIEVED.
Claim: "An atomic assignment operation in Beads" (bd update <id> --claim) preventing duplicate work assignment. RETRIEVED.
Gate: "A condition that must be satisfied before dependent work proceeds," materializing as a blocking bead. RETRIEVED.
Ready frontier: "The work that an agent can claim now because it has no open blocker," computed via bd ready / work_query. Workers discover that frontier through gc hook, not by browsing fleet-wide bd ready. RETRIEVED; Bluefly session-start law: beads-work-ownership-contract.md.
Work graph (edge types): "Beads connected by parent-child structure, blocking dependencies, provenance, validation, and other typed relationships" — parent-child (scope/hierarchy, no sequencing implied), blocking (ordering constraints, drives bd ready), and provenance/discovered-from (records why work exists without forcing it into the original plan). RETRIEVED, gascity.com/guide/agent-work-graphs/.
Session vs. Bead: "A live coding-agent process" (Session) is temporary; a Bead is durable. Default claim lease is five minutes (heartbeat-refreshed) with a ten-minute grace period before bd reclaim returns an abandoned bead to open. RETRIEVED, gascity.com/guide/coding-agent-crash-recovery/.
Gas City vs. Gas Town vs. Gasworks (canonical relationship, RETRIEVED): Beads is the foundation (open protocol/substrate). Gas City is "the MIT-licensed open software factory platform that runs on Beads" and is the primary orchestration product. Gas Town is upstream's own predecessor project — "the predecessor software-factory project that inspired Gas City" — whose architecture Gas City "restructured... into configurable primitives"; Gas Town's operating vocabulary remains available as an importable pack for migration only, not a compatibility layer Gas City runs underneath. Gasworks is downstream — the "coming soon" multi-operator/team expansion of Gas City, bundling Beads Team Server. This refines the "Gas Town is historical/reference-pack terminology" bullet above: Gas Town is the historical predecessor, not merely a reference pack, and it inspired rather than underlies Gas City. "Gas City, Inc. is the company. Gas City without Inc. is the open-source product." Source: gascity.com/guide/gas-city-gas-town-gasworks-whos-who/, gascity.com/about/.
Beads Team Server / Gasworks (commercial products, RETRIEVED 2026-09-02, early access/waitlist as published): Beads Team Server is in early access/design-partnership preview (SaaS or self-hosted VPC), adding governed shared work, provenance, visibility, Kanban/dependency-graph/Gantt views, and Run-level tracing of agent sessions, artifacts, model/token/spend. Gasworks is "coming soon" (waitlist), bundles Beads Team Server, and is positioned "bring your own keys, zero markup" (no token tolls). Both are commercial extensions on top of the unchanged OSS Gas City/Beads component map — not required to use the OSS platform. Source: gascity.com/beads-team-server/, gascity.com/gasworks/.
Three separate "history" surfaces (do not conflate, RETRIEVED): (1) Beads work graph = durable work memory (crash recovery); (2) Gas City local dashboard/events = local execution projection, explicitly "not a retained enterprise audit record"; (3) Beads Team Server Run record = governed organizational audit/compliance record (sessions, artifacts, outcomes, spend). Source: gascity.com/guide/durable-agent-memory-audit-trail/.
Beads vs. hosted trackers, operating rule (RETRIEVED): "Use the hosted tracker for work that the organization promises, funds, reviews, or reports. Use Beads for work that agents must safely claim, block, discover, resume, and hand off." Native sync commands exist for bd jira, bd linear (bidirectional, MCP-integrated), and bd github (bidirectional/pull-only/push-only/selective) — see gc-integrations.md. Source: gascity.com/guide/beads-with-jira-linear-github-issues/.

Legacy Concepts (Archived)¶

Manual deployments, mutable production servers, and SSH-based configuration have been deprecated and replaced by Release Bundles and IaC.