Skip to content

Platform Ownership and Duty Separation

ABSOLUTE — GitLab SSH Alias (2026-04-19 INCIDENT, 5hr downtime): blueflyio remotes MUST use git@gitlab-bluefly: NEVER [email protected]:. The ~/.ssh/config Host gitlab-bluefly binds id_ed25519_bluefly with IdentitiesOnly yes; direct gitlab.com bypasses it → unauthorized key → push fails. Diagnose: git remote get-url origin. Fix: git remote set-url origin git@gitlab-bluefly:<ns>/<repo>.git. Also: gitconfig credential.https://gitlab.com.username must be bluefly.

Canonical OSSA bible (in-repo): plans/__FINAL-PLANS/02-BIBLE-OSSA-AGENT-BUILDER.md. Legacy copies under plans/CONTENT-CONSOLIDATION/ are non-authoritative mirrors if present. Principal Architect dashboard (human UI layer, not above conflict chain): plans/__FINAL-PLANS/FINAL-sprint-dashboard.html — operational cockpit; see ai.json → context_hub.sprint_dashboard_path. Bootstrap path index (DRY): ai.json → context_hub.canonical_workspace_paths. Does not override domains.yaml or FINAL prose. Last Updated: 2026-04-04 v4.7 — Conflict chain: domains.yaml > FINAL > OWNERSHIP > RUNTIME-SPINE (see plans/__FINAL-PLANS/README.md). Tunnel port tables remain in domains.yaml only. Status: Active — stewardship and SOD rules. Operating model addendum: Wiki vs repo, GitLab issues/epics/milestones, environment SoD (local / NAS / GitLab / Oracle), Cloudflare vs Tailscale vs Keycloak, memory semantics (ContextControl.ai), Submolt repos, and upstream assistant stack disambiguation. The former pointers __FINAL-PLAN-TO-UPDATE.md and RUNTIME-SPINE-LIVING-PLAN.md no longer exist in this repo; treat the root AGENTS.md and Engineering-Standard/ as the live authority instead. __BARE_REPOS is retired — authoritative Gas City rig working trees on Oracle live at /opt/bluefly/rigs/<rig>/ (city root: /opt/bluefly/blucity). See oracle-canonical-architecture.

Conflict resolution (single resolver)

On any disagreement between documents or code:

  1. .agents/context/domains.yaml — runtime truth (ports, listeners, tunnels, backends). Wins over all prose.
  2. plans/__FINAL-PLANS/__FINAL-PLAN-TO-UPDATE.md — architecture intent, blockers, execution narrative, context authority (§3d–§3e).
  3. This file (OWNERSHIP.md) — SoD mapping, principles, and duty boundaries — never overrides domains.yaml on hostnames, ports, or tunnel wiring; never overrides FINAL on platform architecture.
  4. plans/__FINAL-PLANS/RUNTIME-SPINE-LIVING-PLAN.md — tracks, todos, runbooks — subordinate to FINAL for architectural truth.
  5. blueflyio-work-items-plan.md — issue text and sequencing notes (not live topology).

Chain: domains.yaml > FINAL > OWNERSHIP > RUNTIME-SPINE > work-items snapshot.

OWNERSHIP never overrides domains.yaml. If a table in this file ever disagrees with domains.yaml, treat the table as wrong and fix or delete it.

Appendix — Authority Registry (legacy YAML, merged)

The workspace previously carried a standalone registry file (01-AUTHORITY-REGISTRY.yaml). To enforce “one authority per topic”, its content is merged here as a single append-only appendix.

# Authority Registry — Bluefly Agent Platform
# (Merged from .agents/context/01-AUTHORITY-REGISTRY.yaml)
# Version: 1.0 | Date: 2026-04-18

---

##############################################################################
# CEDAR POLICY LAYER (two distinct repos — not a naming conflict)
##############################################################################

- id: cedar-policies
  name: Cedar Policy Library
  type: policy-library
  gitlab: blueflyio/cedar-policies
  description: >
    Canonical store of all .cedar policy files. No policy bodies live outside
    this repo. Policies are referenced by pack ID; evaluation happens in the
    compliance engine.
  consumed_by:
    - cedar_policy (Drupal module loads packs at runtime)
    - compliance-engine

- id: cedar_policy
  name: Cedar Policy (Drupal module)
  type: drupal-module
  gitlab: blueflyio/agent-platform/drupal/cedar_policy
  local: PROJECTS/_DRUPAL-for-today/cedar_policy
  ddev_demo: web/modules/custom/cedar_policy
  upstream_drupal: []
  description: >
    Drupal module that integrates the Cedar policy engine into Drupal.
    Loads policy packs from cedar-policies repo at runtime.
  note: MR !43 merged. composer type=drupal-module. Confirmed on drupal.org publishing track.

##############################################################################
# CONTRACTPLANE LAYER
##############################################################################

- id: contractplane-website
  name: ContractPlane.ai Website
  type: saas-product-site
  gitlab: blueflyio/contractplane.ai/contractplane.ai-website
  description: >
    Full SaaS product site — users sign in, subscribe, pay at contractplane.ai.
    Trust posture, A2H approvals, Cedar evidence, marketing. No app.* subdomain.

- id: contractplane-sdk
  name: ContractPlane SDK
  type: sdk
  gitlab: blueflyio/contractplane.ai/contractplane-sdk
  description: >
    API/SDK for ContractPlane integration. Provides contract lifecycle management,
    policy enforcement hooks, and Cedar gate integration.
  note: Lives in contractplane.ai GitLab group, not agent-platform/drupal.

- id: contractplane_client
  name: ContractPlane Client (Drupal)
  type: drupal-module
  gitlab: blueflyio/agent-platform/drupal/contractplane_client
  local: PROJECTS/_DRUPAL-for-today/contractplane_client
  ddev_demo: web/modules/custom/contractplane_client
  upstream: contractplane-sdk

##############################################################################
# CONTEXT CONTROL LAYER
##############################################################################

- id: contextcontrol-website
  name: ContextControl.ai Website
  type: saas-product-site
  gitlab: blueflyio/contextcontrol.ai/contextcontrol_ai
  description: >
    Full SaaS memory product — users sign in, subscribe, pay at contextcontrol.ai.
    Memory mgmt, multi-tenant context, marketing. No app.* subdomain.

- id: context-cli
  name: Context CLI
  type: cli-tool
  gitlab: blueflyio/contextcontrol.ai/context-cli
  local: PROJECTS/_DRUPAL-for-today/context-cli
  description: >
    CLI tool for context/memory management. Part of the ContextControl product group.
  note: Was kb-automation-cli in the old naming. Canonical: context-cli.

##############################################################################
# MARKETPLACE LAYER (6 distinct things — all coexist)
##############################################################################

- id: ai-marketplace-node-app
  name: AI Marketplace (Node/HTML app)
  type: node-app
  gitlab: blueflyio/agent-platform/apps/ai-marketplace
  local: PROJECTS/_DRUPAL-for-today/ai-marketplace
  description: >
    Standalone HTML/Node app. NO Drupal connection. Separate concern from
    Drupal marketplace modules.

- id: node-agent-marketplace
  name: Node Agent Marketplace (frontend)
  type: node-frontend
  gitlab: blueflyio/agentmarketplace/node-agent-marketplace
  description: >
    Node.js frontend. Talks to demo_agent_marketplace Drupal backend.
    Lives in the agentmarketplace GitLab group.

- id: demo_agent_marketplace
  name: Demo Agent Marketplace (Drupal backend)
  type: drupal-site
  gitlab: blueflyio/agentmarketplace/demo_agent_marketplace
  description: >
    Drupal site that serves as the marketplace backend.
    Frontend: node-agent-marketplace.
    Lives in the agentmarketplace GitLab group (not agent-platform/drupal).
  note: Canonical — do not use blueflyio/marketplace.drupl.ai (archived).

- id: agent_marketplace
  name: Agent Marketplace (Drupal module — parent)
  type: drupal-module
  gitlab: blueflyio/agent-platform/drupal/agent_marketplace
  local: PROJECTS/_DRUPAL-for-today/ai_marketplace
  action_required: EVALUATE
  description: >
    Parent Drupal module for marketplace functionality. Candidate to absorb
    ai_agents_marketplace and ai_marketplace as submodules. Needs evaluation
    to confirm which of the three Drupal marketplace modules is the parent.

- id: ai_agents_marketplace
  name: AI Agents Marketplace (Drupal module)
  type: drupal-module
  gitlab: blueflyio/agent-platform/drupal/ai_agents_marketplace
  action_required: MERGE_INTO_SUBMODULE
  target: agent_marketplace
  description: >
    Should be merged into agent_marketplace as a Drupal submodule
    (modules/ subdirectory pattern, same as source_ai_demo in source_connector).

- id: ai_marketplace-drupal
  name: AI Marketplace (Drupal module)
  type: drupal-module
  gitlab: blueflyio/agent-platform/drupal/ai_marketplace
  local: PROJECTS/_DRUPAL-for-today/ai_marketplace
  ddev_demo: web/modules/custom/ai_marketplace
  action_required: EVALUATE
  description: >
    Another Drupal marketplace module. Needs evaluation: may be the true
    parent (with agent_marketplace and ai_agents_marketplace becoming submodules),
    or may itself be a submodule candidate. Do not merge until parent is confirmed.

- id: recipe_ai_marketplace
  name: Recipe AI Marketplace
  type: drupal-recipe
  gitlab: blueflyio/agent-platform/drupal/recipes/recipe_ai_marketplace
  description: >
    Drupal recipe for AI marketplace installation/configuration.

##############################################################################
# ACQUIA SOURCE LAYER
##############################################################################

- id: source_connector
  name: Source Connector
  type: drupal-module
  gitlab: blueflyio/agent-platform/drupal/source_connector
  local: PROJECTS/_DRUPAL-for-today/source_connector
  ddev_demo: web/modules/custom/source_connector (symlink → PROJECTS/_DRUPAL-for-today)
  current_branch: feat/eca-webhook-ingest-pipeline
  open_mr: "!8 → release/v0.1.x"
  submodules:
    - modules/source_ai_demo  # committed 2026-04-18
  description: >
    External MCP/API integration layer for Acquia Source. Communicates only
    via sanctioned surfaces: OAuth 2.0, JSON:API, webhooks, Canvas CLI.
    ECA is the sole on-platform orchestration spine. Cedar is the policy gate.

- id: source_ai_demo
  name: Source AI Demo (Drupal submodule)
  type: drupal-submodule
  parent: source_connector
  path: modules/source_ai_demo
  routes:
    page: /ai-canvas
    run: POST /ai-canvas/run
  library_key: canvas
  description: >
    AI Canvas Builder demo UI. Committed 2026-04-18. Fixes applied:
    library key (demo→canvas), logger channel, routes (/ai-demo→/ai-canvas),
    info.yml name/description/php/dep.

##############################################################################
# DRUPAL PLATFORM MODULES
##############################################################################

- id: ai_agents_ossa
  name: AI Agents OSSA
  type: drupal-module
  gitlab: blueflyio/agent-platform/drupal/ai_agents_ossa
  local: PROJECTS/_DRUPAL-for-today/ai_agents_ossa
  ddev_demo: web/modules/custom/ai_agents_ossa
  upstream_drupal:
    - ai:ai
    - ai_agents:ai_agents
  suggests:
    - http_client_manager:http_client_manager
    - eca:eca
    - tool:tool_ai_connector
  description: >
    OSSA v0.5.x bridge. Imports OSSA manifests into config entities, derives
    AiAgent plugins, maps Tool API capabilities to OSSA.

- id: kb_cache
  name: KB Cache
  type: drupal-module
  gitlab: blueflyio/agent-platform/drupal/kb_cache
  local: PROJECTS/_DRUPAL-for-today/kb_cache
  ddev_demo: web/modules/custom/kb_cache
  upstream_drupal:
    - drupal:ai_context  # hard require — confirmed in info.yml
    - drupal:ai_agents
    - drupal:ai_eca
    - drupal:eca
    - drupal:tool
    - tool:tool_ai_connector
  description: >
    Knowledge Base Cache — federated AI memory write/read surface via
    ai_context_item with GAID provenance and ECA lifecycle governance.

- id: mcp_registry
  name: MCP Registry
  type: drupal-module
  gitlab: blueflyio/agent-platform/drupal/mcp_registry
  local: PROJECTS/_DRUPAL-for-today/mcp_registry
  upstream_drupal:
    - drupal:mcp  # hard require — confirmed in composer.json
  suggests:
    - drupal:mcp_client
  description: >
    MCP registry and discovery layer built on drupal/mcp contrib.
    Enhanced by agent-protocol. Do not re-implement MCP protocol in custom modules.

- id: api_normalization
  name: API Normalization
  type: drupal-module
  gitlab: blueflyio/agent-platform/drupal/api_normalization
  local: PROJECTS/_DRUPAL-for-today/api_normalization
  ddev_demo: web/modules/custom/api_normalization

- id: agentic_canvas_blocks
  name: Agentic Canvas Blocks
  type: drupal-module
  gitlab: blueflyio/agent-platform/drupal/agentic_canvas_blocks
  local: PROJECTS/_DRUPAL-for-today/agentic_canvas_blocks
  ddev_demo: web/modules/custom/agentic_canvas_blocks

- id: dragonfly_client
  name: Dragonfly Client
  type: drupal-module
  gitlab: blueflyio/agent-platform/drupal/dragonfly_client
  local: PROJECTS/_DRUPAL-for-today/dragonfly_client
  ddev_demo: web/modules/custom/dragonfly_client

##############################################################################
# COMPLIANCE LAYER (API services)
##############################################################################

- id: compliance-engine
  name: Compliance Engine
  type: api-service
  gitlab: blueflyio/agent-platform/services/compliance-engine
  local: PROJECTS/_DRUPAL-for-today/compliance-engine
  host: compliance.blueflyagents.com
  port: 3014
  runtime: TypeScript + Node.js
  description: >
    Compliance-as-a-Service Cedar PDP. All policy enforcement via HTTP — never
    local WASM in client code.

##############################################################################
# POLICY LIBRARY (separate from Drupal module above)
##############################################################################

- id: cedar-policies-repo
  name: Cedar Policies (policy library)
  type: policy-library
  gitlab: blueflyio/cedar-policies
  local: PROJECTS/_DRUPAL-for-today/cedar-policies
  description: >
    All .cedar policy files live here. No policy bodies outside this repo.
    Referenced by pack ID. Evaluation by compliance engine.

##############################################################################
# ITEMS WITH OPEN ACTIONS
##############################################################################

open_actions:
  - id: ai_marketplace_parent_eval
    description: >
      Three Drupal marketplace modules exist: agent_marketplace, ai_agents_marketplace,
      ai_marketplace. Determine which is parent. Merge others as submodules (modules/ pattern).
    repos:
      - blueflyio/agent-platform/drupal/agent_marketplace
      - blueflyio/agent-platform/drupal/ai_agents_marketplace
      - blueflyio/agent-platform/drupal/ai_marketplace
    priority: medium
    blocker_for: marketplace consolidation

Canonical Project Layout (Required Files and Folders)

Every platform project MUST have the following structure. Exceptions: workspace root (blueflyio) may omit src/; Drupal modules/sites use src/ per Drupal convention (or no src/ at root when code lives in modules/ or web/). Validation: run all scripts in ai.json control_primitives.run_order (validate.mjs, validate-deps.mjs, validate-project-layout.mjs, validate-three-layer.mjs), or use ossa workspace validate when OSSA CLI is installed. No root-level automation scripts; platform only (BuildKit, .agents-workspace, OSSA CLI).

Required Folders

Folder Purpose Notes
.agents/ OSSA agent manifests, skills, registry Create via ossa workspace init then ossa agents init or scaffold; reference: __RESTRICTED/openstandardagents/.agents and workspace .agents-workspace/. May contain agents/, registry.yaml (or agent-registry.yml), optional registry/, policies/, orchestration/, shared-context/, logs/ when using OSSA workspace.
docs/ All project documentation Single place for markdown and build-time docs; keeps repo root clean and aligns with SOD. Put architecture, runbooks, and agent-facing notes here.
src/ Application logic (non-Drupal) Required for Node/TS/Python/Go services. Omit only for Drupal sites/modules (where code lives under src/ per module or in web/), static sites, or repo that is purely config/templates.

Required Root Files

Standard project files:

File Purpose
README.md Project overview, setup, and links (allowed in root per project policy).
LICENSE or LICENSE.txt License text (e.g. Apache-2.0, MIT).
CONTRIBUTING.md How to contribute, branch policy, MR process.
SECURITY.md or SECURITY.txt Security policy and reporting (recommended; required for public/drupal.org).
CHANGELOG.md Release history (optional but recommended; required for semantic-release).

AI / agent context files (all projects):

File Purpose
AGENTS.md Rules engine for AI assistants; single source of build rules, prohibitions, workflows.
llms.txt Concise LLM context: pointers to OWNERSHIP.md, ai.json, paths, branch policy, key services.
ai.json Machine-readable catalog: services, dependency_standards (see ai.json in workspace root), modules, protocols.
CLAUDE.md Pointer file: "Rules in AGENTS.md; bible is OWNERSHIP.md"; paths and control primitives.

Optional AI/context files (use when relevant):

File Purpose
.cursorrules or .cursor/rules/*.mdc Cursor-specific rules (project-level overrides).
ai.ajson Alternate/annotated JSON schema or config (project-specific).
.mcp.json MCP server configuration (when project runs or defines MCP).
CONTEXT.md Extra context for IDE/agents (e.g. ide-supercharger).

Reference (blueflyio meta-workspace): Governance prose stays at workspace root (AGENTS.md, CLAUDE.md, llms.txt). The platform machine bundle lives in .agents/platform-context/ (ai.json, OWNERSHIP.md, BLU-WORKSPACE.md, dragonfly.config.json, dragonfly-test-scopes.json, skills-lock.json). Root copies of those filenames are symlinks for tools that still expect root paths. .agents-workspace/ (workspace root) contains validators: validate.mjs, validate-deps.mjs, validate-project-layout.mjs, check-ownership.mjs, registry/, discovery/, workflows/ — not duplicates of platform-context; run orchestration from here, authoritative JSON/MD from platform-context. To check every worktree project for layout: node .agents-workspace/validate-project-layout.mjs (or --json). To scaffold missing .agents/ and docs/ in a project: node .agents-workspace/scaffold-project-layout.mjs worktrees/<project>/<branch>. OSSA CLI creates .agents-workspace/ (ossa workspace init) and per-project .agents/ (ossa agents init or scaffold).

Principles

  • Single writer per concern: Every product, module or protocol has one authoritative home. Consumers read from that home and never invent their own versions.
  • Consumers read, never invent: Marketplaces and dashboards consume policies, manifests and workflows published by their authoritative repositories. Governance and evidence are produced by ContractPlane.
  • Every project ships subagents: Every service, Drupal module, and SaaS product MUST use the openstandardagents CLI (ossa agents init) to create project-local subagents in its .agents/ folder. These subagents are workers that core platform-agents orchestrators can discover and delegate to. No project is exempt. The .agents/ folder is a required project directory (see Canonical Project Layout above).
  • Two-tier agent model: platform-agents owns core agents and orchestrators (the "brain"). Project .agents/ folders own domain-specific subagents (the "hands"). Core agents discover project subagents via DUADP (discover.duadp.org) and call them as workers. Subagents must be registered to the marketplace (marketplace.blueflyagents.com) via pnpm run register:all in the platform-agents worktree.
  • Sanctioned runtime mounts (compatibility only): .agents/agents, .agents/skills, and .agents/plugins at the workspace root are POSIX symlinks — runtime mounts, not canonical authoring locations. Authoring belongs in PROJECTS/agents/agents/, PROJECTS/skills/, and PROJECTS/plugins/ respectively. The agents mount targets PROJECTS/agents/agents (catalog root), not the agents repo root. Workspace rules forbid ad-hoc symlinks in worktrees; these three mounts are the only sanctioned symlink use at workspace root for agent runtime compatibility.
  • Open source first, platform-specific last: Every module, SDK, and protocol MUST be built as open source and public by default. Platform-specific customizations (Bluefly branding, credentials, private configuration) go only in env vars, deployment config, or thin wrapper layers — never in the open source codebase itself. If a capability benefits the ecosystem, it ships in the open source repo. If it's genuinely Bluefly-specific (billing, tenant ID, internal secrets), it goes in the closed layer on top. This rule applies to DUADP, OSSA, all SDKs, all reference nodes, and all protocol implementations.
  • No Cedar policy bodies outside cedar-policies: Enforce policies centrally and reference them by pack ID; evaluation happens in the compliance engine.
  • No PDP logic in orchestration: The orchestration module is a bridge — it calls out to ContractPlane for policy decisions. It never embeds a Cedar PDP, holds policy decision records, or acts as the approval authority. See § Drupal AI Runtime — 4-Plane Ownership.
  • orchestration invokes; ContractPlane approves: This rule is absolute and applies to every capability exposed through the orchestration bridge. Never swap these roles.
  • POST /execution/run (api.copaw.us) is the ONLY entry point for agent execution: No bypass paths exist. No direct LLM calls. No Drupal $agent->solve(). Every invocation must flow through the fail-closed gateway.
  • No agent execution in the bridge layer: orchestration fires triggers. It does not call $agent->solve(), inject OssaAgentExecutor, or own the execution loop.
  • No DUADP logic outside duadp: The DUADP client is a consumer and must not implement discovery logic. DUADP informs, never routes execution.
  • No UI components outside studio-ui: All front-end projects must import components from @bluefly/studio-ui.
  • No Vast.ai logic outside agent-router: Scheduling and deployment to Vast.ai lives in the router; call its API rather than re-implementing.
  • No MCP protocol implementation outside agent-protocol: Agent-mesh and agent-buildkit are consumers of the protocol.
  • Deprecated repositories are archived and must not receive new merge requests.

Domains and Products

Domain Role Purpose
copaw.us execution_domain Primary execution gateway — api.copaw.us is the canonical execution entry; all other domains call INTO it
contractplane.ai control_domain / saas_product Full governance SaaS product — users sign in, test, subscribe, pay at contractplane.ai (root). Trust posture, A2H approvals, Cedar evidence, marketing. No forced app.* subdomain.
contextcontrol.ai memory_domain / saas_product Full shared memory SaaS product — users sign in, test, subscribe, pay at contextcontrol.ai (root). Memory mgmt, multi-tenant context, marketing. No forced app.* subdomain.
drupl.ai authority_domain Drupal ecosystem product: module marketplace, demos, feature decks, marketing. app.drupl.ai = authenticated runtime ONLY.
ContextControl.ai sovereign_deployment Sovereign/on-prem ContextControl deployment + governed content write backend — routes assets to owning domains via JSON:API. NOT the universal public library.
blueflyagents.com platform_domain Internal tooling, observability, MCP, Mesh, Agent Studio, knowledge graph, dashboards
bluefly.io corporate Corporate/company site ONLY — white papers, platform overview, cross-product architecture, investor/enterprise narrative. NOT a product marketing site.
duadp.org protocol_domain (hybrid) GitLab Pages at root; Cloudflare-tunneled runtime on subdomains (discover.duadp.org, register.duadp.org)
openstandardagents.org spec_domain (hybrid) GitLab Pages at root; Cloudflare-tunneled runtime on subdomains (studio.openstandardagents.org)
agentblu.ai consumer_domain Agent Blu UI, chat, social surfaces

Authority split — do not conflate these roles (updated 2026-04-14):

  • Execution ingress: api.copaw.us/execution/run (copaw.us execution_domain)
  • Governance SaaS product: contractplane.ai — full product including login/subscribe/pay (no app.* subdomain)
  • Shared memory SaaS product: contextcontrol.ai — full product including login/subscribe/pay (no app.* subdomain)
  • Drupal ecosystem: drupl.ai — module marketplace + marketing; app.drupl.ai runtime only
  • Governed content backend: ContextControl.ai — sovereign deployment + write backend; NOT universal public library
  • Corporate: bluefly.io — corporate narrative only; NOT a product marketing surface

Content routing: domain = product/system responsibility boundary. Governed assets published on the domain matching the owning product/corporate surface. Full model: plans/__FINAL-PLANS/CONTENT-DOMAIN-ARCHITECTURE.md.

Runtime topology detail (tunnel routes, ports, backends): .agents/context/domains.yaml is canonical. Do not maintain duplicate tunnel inventories here.

Product sentence: Bluefly is the AI context infrastructure partner for government and enterprise Drupal deployments. ContractPlane.ai is the trust, evidence, policy, compatibility, registration and release authority for autonomous systems across the OSSA/DUADP substrate.

Authority Map

Concern Authoritative System Must NOT Own
Deployed agent / skill / tool discovery (ALL runtime resolution) DUADP (duadp.org / discover.duadp.org) — GET /.well-known/duadp.json, /api/v1/agents, /api/v1/skills, /api/v1/tools .agents/registry.yaml, .agents-workspace/, workspace symlinks, local filesystem registry state, PROJECT/.agents/ filesystem path refs
Agent execution (ALL invocations) Execution gateway — POST api.copaw.us/execution/run (contractplane-gateway / moltbook-community-api stack) Drupal modules, Agent Studio macOS, any service calling LLM directly
Output verification (post-execution gate) Dragonfly (dragonfly.drupl.ai) — fail-closed Be optional or skipped in production
Agent/role manifest specification OSSA (openstandardagents) Drupal modules, ContractPlane, marketplaces
Discovery & identity DUADP (duadp + discover.duadp.org) agent-mesh, marketplaces, ContractPlane
Cedar policy packs (bodies) cedar-policies Drupal modules, ContractPlane, compliance engine, runtime repos
Policy evaluation (PDP) compliance-engine (compliance.blueflyagents.com/api/v1/evaluate) cedar_policy Drupal module, ContractPlane, orchestration bridge, Drupal PolicyEngine.php
DID identity (did:web) compliance-engine DUADP, ContractPlane, agent-mesh
DUADP node discovery (compliance) compliance-engine duadp.org inspector, federation peers
Drupal AI context memory (agent_memory entity, GAID, lifecycle, Tool plugins) kb_cache cedar_policy, duadp_client, compliance-engine — kb_cache has no hard deps; ECA handles governance
Trust posture & evidence authority ContractPlane.ai (controlplane.ai) Marketplaces, Drupal modules, orchestration bridge
External automation bridge (Drupal→Activepieces/n8n) orchestration (drupal.org/project/orchestration) Runtime execution, policy decisions, evidence, state authority
Agent runtime execution (sessions, memory, verification) harness_engine + OSSA + DUADP + StateMesh Visual config, external automation bridge, governance
Drupal visual topology / operator config surfaces modeler_api + *_modeler submodules Runtime state, execution, bridge, governance
Governance substrate contractplane (Drupal module) controlplane.ai product repo
Human identity & sessions Keycloak (bluefly realm) Any application repository
Release promotion & CI evidence GitLab + BuildKit Drupal modules, marketplaces
MCP protocol agent-protocol agent-buildkit, agent-mesh
A2A delegation agent-mesh agent-buildkit, platform-agents
Discovery registry agent-mesh (POST/GET /api/v1/discovery) agent-buildkit, openstandardagents
LLM routing & Vast.ai deployment agent-router agent-buildkit, agent-docker
UI component library studio-ui Any other project
Shared OpenAPI schemas api-schema-registry Application repositories
CI/CD templates gitlab_components Product repositories
GitLab security policies security-policies Application repositories
Marketplace catalog UX ai_marketplace (Drupal module) ContractPlane, Node.js marketplace
A2A event collection & analytics a2a-collector agent-mesh, agent-tracer
A2A streaming a2a-stream agent-mesh
Dragonfly API, CLI, OpenAPI spec, Playwright testing, ephemeral Docker containers, IaC connections, agent-docker connections dragonfly (core) dragonfly-saas, dragonfly_client — agents do NOT live here; they go in platform-agents and are called into marketplace.blueflyagents.com via discover.duadp.org
Claude Code → Dragonfly hook scripts (PostToolUse, Stop, heal CLI) ~/.claude/hooks/ (operator-level, not a repo) Do NOT embed in any project repo
dragonfly-test skill definition ai-marketplace/skills/dragonfly-test/SKILL.md platform-agents, dragonfly core
Claude Code as Dragonfly client (OSSA manifest) platform-agents/.agents/agents/@ossa/claude-code-dragonfly-client/ agentblue.ai, dragonfly core
Reusable Dragonfly CI component platform-agents/.gitlab/ci/components/dragonfly/template.yml Individual project .gitlab-ci.yml (consumers only, no reimplementation)
Dragonfly SaaS UI — landing, dashboard, admin with multi-tenancy, billing, and tenant isolation (runs atop dragonfly core) dragonfly-saas dragonfly (core), dragonfly_client — does NOT duplicate core logic; adds SaaS/tenant/billing layer only
Dragonfly Drupal integration — all fields, content types, config, entity connections, and wiring to Drupal marketplace or DUADP node dragonfly_client dragonfly (core), dragonfly-saas
Apple FM / multi-provider bridging foundation-bridge agent-router, agent-buildkit
Dependency version standards ai.json → dependency_standards Individual service repos (consume, never override)
Dependency compliance enforcement .agents-workspace/validate-deps.mjs Individual service repos
Drupal recipes (AgentDash, AI Marketplace, Secure Drupal, Agent Platform) blueflyio/agent-platform/drupal/recipes (GitLab subgroup) Ad-hoc recipe copies outside that subgroup

Finding-routing taxonomy (for §0.11 LAYER field)

When a finding emerges from an audit / enforcement pass (see BLU-OPERATOR-CONTRACT.md §0.11 / §0.14), the LAYER field uses this seven-token taxonomy. Each layer routes to specific authoritative repos / modules already documented above — this table is the routing shortcut, not a second source of truth.

LAYER token What it covers Authoritative homes (cross-ref Authority Map)
standards Specs, schemas, manifests, agent / skill / tool definitions, OSSA contract, DUADP discovery contract OSSA (openstandardagents); DUADP (duadp); platform-agents source (PROJECTS/platform-agents); marketplace skills (agentic-marketplace)
governance Policy bodies, evaluation, evidence, approvals, fail-closed gates, trust posture, compliance evaluation cedar-policies (Cedar bodies); compliance-engine (PDP, DID, DUADP node discovery); ContractPlane (contractplane.ai); contractplane Drupal module (governance substrate); workspace governance (AGENTS.md + .agents/context/BLU-OPERATOR-CONTRACT.md)
runtime Agent execution, sessions, memory, verification, dispatch, mesh, routing, state Execution gateway (POST api.copaw.us/execution/run); harness_engine + OSSA + DUADP + StateMesh; agent-mesh (A2A / discovery); agent-router (LLM routing); a2a-collector / a2a-stream; Dragonfly (post-execution gate)
drupal Drupal modules, content types, fields, ECA flows, AI module integrations, marketplace catalog UX, recipes All Drupal product / module repos under blueflyio/agent-platform/drupal/*; modeler_api (visual / config plane); kb_cache (agent context memory); ai_marketplace (catalog UX); dragonfly_client (Drupal integration)
infra Topology, tunnels, Cloudflare, Traefik, Oracle compose, Tailscale, GitLab CI, runner registration, secret injection (workstation), GitLab security policies domains.yaml (topology intent); @bluefly/iac (ingress artifacts); agent-docker (Oracle runtime); GitLab + BuildKit (release / CI); gitlab_components (CI templates); security-policies; .agents/context/BLU-AUTHENTICATION.md (workstation auth)
product Product UI / content / site behavior, customer-facing surfaces, marketing, dashboards bluefly.io (corporate); blueflyagents.com (marketplace / ops); agentblu.ai (product marketing / studio); drupl.ai (community / marketing); ContextControl.ai product surface; studio-ui (component library)
docs Understanding documents (agent.MD, llms.txt, vision.MD, README.md, AGENTS.md, CLAUDE.md, ai.json); evergreen architecture in GitLab Wiki; API schemas / OpenAPI Per-repo doc files (consumer-owned); GitLab Wiki technical-docs (evergreen architecture, never plans/); api-schema-registry (shared OpenAPI); the DOC_SYNC_REQUIRED block in BLU-OPERATOR-CONTRACT.md §0.9.1 is the trigger format

A finding that touches more than one layer (e.g. a Drupal module that bypasses governance) reports the most specific layer for ownership routing and notes the secondary layer in EVIDENCE. Cross-ref the Drupal AI 4-Plane block below for drupal + runtime + governance boundary detail.

Deployed Surfaces & SOD Layers

Domain Strategy (Separation of Duties)

Layer Domain Role Target System Auth Posture
1. Brand bluefly.io Commercial / Trust / Reference CMS Drupal CMS 2.0 Public + Editor
2. Product blueflyagents.com Ecosystem / Registry / Ops Next.js Marketplace / Ops Dashboards Public + Tenant/Op
3. Solution agentblu.ai Product Marketing / Customer Studio Marketing Shell / Studio UX Public + Customer
4. Community drupl.ai Community Editorial / Demo Drupal Community site Public + Editor
5. Private bluefly.internal Execution Mesh / Swarm / Internal Mesh, Router, Brain, Workflow Tailscale Only

Mapping & Tunnels

No numeric port matrix in this file. Duplicate host:port rows caused drift against production. The only authoritative registry is .agents/context/domains.yaml (version in file header).

Infrastructure contract and separation of duties (lockdown)

Layer Owner Responsibility Must not
Topology intent .agents/context/domains.yaml Hostnames, ports, routing, product boundaries Duplicate port tables in OWNERSHIP, ad hoc wiki-only host lists
Ingress artifacts blueflyio/agent-platform/infra/iac (@bluefly/iac) config-templates/tunnels/*.yaml, generated cloudflare-tunnel-config.yml, tunnel-routes*.json, npm run validate:config, Terraform under iac/terraform/ for Cloudflare when used Oracle docker-compose labels, Traefik backend ports (consume contract; generate routes)
Oracle runtime agent-docker deployments/oracle/docker-compose.yml, deployments/oracle/domains.yaml (Traefik loadbalancer.server.port must match containers) Invent host/port off-contract; Cloudflare dashboard as source of truth
Apply / secrets GitLab CI + operators CLOUDFLARE_API_TOKEN (masked), pipeline plan/apply, tunnel sync jobs Routine edits only in dashboard without a matching Git MR
Edge layers Documented per hostname Distinguish tunnel origin (e.g. localhost:N on cloudflared host) vs Traefik/Caddy vs container port — three numbers are not interchangeable Assuming one port column applies to all layers without checking

Generators: Regenerate tunnel config from iac: npm run generate:all in @bluefly/iac (tsx src/generate-tunnel-config.ts). Pin config-templates/canonical-domains.yaml to the contract for CI validation where used.

Compliance engine: CaaS microservice — per-domain deployments may use different published ports; shared :3010 only when explicitly tagged as shared PDP in contract and generators.

  • Blueflyagents, copaw.us, contractplane, drupl.ai, NAS, DUADP, openstandardagents: every hostname, backend listener, deployment node, and access class is in domains.yaml.
  • Tailscale-only vs public: see per-service routing / notes in domains.yaml.

Compliance Model

  • Target: per-domain PDP (see domains.yaml).
  • Temporary: platform PDP (compliance.blueflyagents.com) allowed only under domains.yaml compliance.bootstrap_exception until gap_1b completes.
  • Do not introduce new cross-domain compliance dependencies in this document beyond that bounded exception.

Marketplace Architecture

Repo URL Role
node-agent_marketplace marketplace.drupl.ai Node/Vite storefront for users; calls Drupal backend via JSON:API — listeners in domains.yaml
demo_agent_marketplace marketplace-app.drupl.ai Drupal backend for catalog, governance, admin UX
ai-marketplace marketplace.blueflyagents.com Next.js plugin/tool registry, serves OSSA manifests and tools.yaml
marketplace-plugins (services/marketplace) — @bluefly/marketplace-plugins — plugin package for Claude Code/Cursor/Windsurf. Not a backend

Flow: Users → Node storefront → Drupal backend (JSON:API) → Next.js registry serves manifests → Plugin package published to registry

Current gaps: Fix mis-routed port in Cloudflare; populate ai_marketplace; build end-to-end sync demo; ensure Next.js registry is not static.

OSSA Ecosystem

Repo Owns Does NOT Own
openstandardagents OSSA spec (JSON Schema), CLI (ossa validate/generate/test), skills CLI Manifests, execution/runtime, Drupal integration, website
openstandardagents.org Website, docs, and public builder (https://openstandardagents.org/builder/); embeds synced spec copy and uses ossa-studio API + @bluefly/studio-ui Canonical spec authoring (lives in openstandardagents), execution/deployment
platform-agents Core agent manifests (.ossa.yaml) and orchestrators — the top-level "brain" of the agent graph. Owns the catalog, CI components, webhook ingress, deploy API, and DUADP registration for all agents across the platform. Project subagents (.agents/ folders) are workers registered here and called by these orchestrators. OSSA spec, execution runtime, compliance or routing
ossa-studio (ossa/lab/ossa-studio) Hosted service: builder HTTP APIs, published npm integration for branded builders, and a Next.js UI shell that uses @bluefly/studio-ui (including flows such as openstandardagents.org/builder/). Spec authoring, execution, deployment
ossa-deploy (ossa/lab/ossa-deploy) Agent lifecycle: validation delegate, pipeline scoring via OpenJudge, artifact publishing Spec authoring, creator UI, validation logic, trust decisions

Flow: CLI authors manifests → ossa-studio (API + UI) scaffolds via ossa-deploy → ossa-deploy handles lifecycle → artifacts go to platform-agents → program sites may embed the builder UI; they do not own the spec.

Agent builder flow (studio-ui, ossa-studio, ossa-deploy, DRY consumers):

  • ossa-studio: Hosted service, HTTP APIs, and npm-oriented integration that power branded agent builders; the shipped Next.js UI uses studio-ui and calls ossa-deploy to produce artifacts.
  • ossa-deploy: Runs the pipeline, builds agent files (manifests, config, artifacts), and returns built output to ossa-studio callers (API and UI).
  • Consumption: Built agents reach targets such as Drupal, first-party program properties (for example openstandardagents.org pages that embed builder flows), and native clients (for example TDDAIStudio). Do not describe ossa-studio as a website; treat it as service + API + packages with an optional hosted UI.
  • DRY: The same studio-ui components are used in ossa-studio, openstandardagents.org, Drupal (where integrated), and the OSX app. No duplicate UI libraries; one component source for all surfaces. OWNERSHIP rule: no UI components outside studio-ui.

Two-tier agent model — mandatory for ALL projects:

Tier Location Owner Role
Core / Orchestrators __RESTRICTED/platform-agents platform-agents repo Top-level agents, orchestrators, catalog. Registered to marketplace.blueflyagents.com and discover.duadp.org.
Project Subagents <project-repo>/.agents/ Each service/module repo Domain workers. Scaffolded with ossa agents init. Registered via platform-agents pnpm run register:all. Called by core orchestrators as workers.

Every service repo (TypeScript services, Drupal modules, SaaS products) MUST have a .agents/ folder with at least one subagent manifest. Run ossa agents init in the project root to scaffold. The canonical CLI package is @bluefly/openstandardagents (npm install -g @bluefly/openstandardagents). Use it for ossa validate, ossa agents init, scaffolding, and export. To register project subagents with DUADP and marketplace, commit new manifests to platform-agents and run pnpm run register:all (see docs/register-duadp-marketplace.md).

__RESTRICTED reference repos (duadp, duadp.org, openstandardagents, ossa-studio): Use these only to audit and read. To work on them, create new worktrees from the latest remote (buildkit sync worktrees or git worktree add from the bare repo). Do not edit inside __RESTRICTED. Details: plans/ossa/AUDIT-existing-implementation.md Section 7.

Global CLIs: Install and keep updated globally so the platform uses the latest: npm install -g @bluefly/agent-buildkit and npm install -g @bluefly/openstandardagents. When releasing these npm packages: merge to release branch, push, ensure GitLab creates the release, then publish to npm if needed and run npm update -g for both. See AGENTS.md and plans/ossa/AUDIT-existing-implementation.md Section 7.2.

Current status: openstandardagents.org on GitLab Pages (CNAME DNS). duadp.org on GitLab Pages (CNAME DNS). OSSA Studio, DUADP discovery, and register nodes: see domains.yaml for hostnames and tunnel routing.

DUADP SDK status (2026-04-09):

  • STABILIZED: All pipelines passing; 42 OpenAPI validation errors resolved; strict Redocly linting enforced.
  • All 3 SDKs (TypeScript @bluefly/duadp, Go duadp, Python duadp) fully built with self-registration helpers.
  • registerWithDuadp(manifest) and registerAsFederationPeer() available in all three — zero hardcoded URLs, fully env-var driven (DUADP_REGISTER_URL, DUADP_TOKEN, DUADP_NODE_ID, DUADP_NODE_NAME, DUADP_BASE_URL).
  • Federation mesh: discover ↔ register nodes seed each other at startup via DUADP_PEERS env var in k8s manifests (persistent across restarts).
  • Pending: MR !4 deploy:k8s manual job must be triggered to push correct DUADP_NODE_ID env vars to live k8s pods (currently reporting did:web:localhost).
  • Services wanting to join the mesh: set DUADP_REGISTER_URL=https://register.duadp.org and call registerWithDuadp(manifest) at startup.

Drupal AI Runtime — 4-Plane Ownership (ARCHITECTURE FREEZE 2026-03-25)

This section is LOCKED. Every agent touching any Drupal AI module MUST read this before making changes.

The Drupal agent stack is divided into exactly four planes. Each plane has one owner. Ownership does not cross planes.

Plane Owner Responsibility Must NOT Own
Visual / Config modeler_api + *_modeler submodules Author and persist Drupal-native topology, configuration, and operator UI surfaces Execution, runtime state, policy decisions
Runtime / Execution harness_engine + OSSA + DUADP + StateMesh Sessions, memory, verification, agent execution, durable state, evidence trail Visual config, external automation bridge, policy enforcement
External Automation Bridge orchestration (drupal.org/project/orchestration) Expose approved Drupal capabilities northbound/southbound to external automation (Activepieces, n8n, Zapier) Long-running runtime, agent memory/state, approval authority, evidence, visual topology
Governance Dragonfly + ContractPlane + Cedar Remediation, approvals, policy decisions, evidence records, release/policy gates Execution, visual config, bridge logic

orchestration module — what it IS and what it is NOT

orchestration (stable 1.0.0, Drupal ^11.2, under Drupal security coverage) is an integration edge, not a platform center.

Correct uses:

  • Northbound/southbound integration edge
  • Exposing Drupal events, tools, and approved workflow triggers to external automation
  • Invoking Tool API plugins, triggering ECA flows, notifying external automators of topology changes
  • Calling harness_engine's approved control API (start session, request verification run, fetch summarized run state, trigger approved remediation workflow, emit operational events)
  • Calling DUADP outward operations (sync node, publish capabilities, trigger discovery refresh)
  • Calling Cedar/ContractPlane for policy decisions (never embedding the PDP)

Prohibited uses — any agent adding these is introducing a boundary violation:

  • Embedding a Cedar policy decision engine (PDP) inside orchestration
  • Owning ossa_policy_decisions database records or any evidence table
  • Calling $agent->solve() or $agent->setTask() directly (that is harness_engine work)
  • Injecting OssaAgentExecutor from flowdrop (that is runtime work)
  • Gating on a locally-owned PolicyEngine before executing commands
  • Acting as the approval authority for any agent operation

Hard rules (non-negotiable)

  1. orchestration invokes; ContractPlane approves — never swap these roles
  2. Dragonfly stays outside Drupal runtime — inspect/scaffold/validate/evidence only, not a Drupal workflow engine
  3. Drupal = visual design + operator control + approved workflow exposure + integration edge
  4. Runtime stack = sessions, memory, verification, multi-agent execution, durable state, evidence trail
  5. Governance stack = approvals, policy, remediation, release control, evidence records
  6. No Cedar PDP logic outside compliance-engine — cedar_policy module enforces hooks; compliance-engine service evaluates; orchestration calls out and receives a decision
  7. Policy decision records belong to ContractPlane — not to orchestration, not to any bridge module
  8. Agent execution invoked through harness_engine — the bridge fires the trigger; harness owns the loop

Narrow outward API surface per domain

Domain orchestration may expose
harness_engine start session, request verification run, fetch summarized run state, trigger approved remediation workflow, emit operational events
duadp_client sync node, publish capabilities, trigger discovery refresh, notify external automators of topology changes
cedar_policy expose approved policy-related actions outward — never move decisioning into orchestration
mcp_registry / api_normalization same pattern — visual/config in Drupal, execution outside, outward bridge through orchestration

harness_engine_modeler decision rule

Create a harness_engine_modeler submodule only if operator-authored topology exists: session templates, verification gate templates, or memory policy templates that an operator configures and persists in Drupal. Do not create it for runtime-emitted state, execution logs, or internal harness records. The modeler owns the authoring UI; harness owns the state produced at runtime.

Known violations requiring remediation (found 2026-03-25 boundary audit; updated 2026-04-09)

File Violation Status
ai_agents_ossa_orchestration/Service/PolicyEngine.php Full local Cedar PDP — makes allow/deny decisions in bridge ✅ Fixed 2026-04-09 — delegating to compliance.blueflyagents.com/api/v1/evaluate
ai_agents_ossa_orchestration/Service/AuditLogger.php (ossa_policy_decisions table) Evidence delegated to ContractPlane central evidence api via HTTP Client ✅ Fixed
OssaOrchestrationServicesProvider::executeInvoke() / OssaAgentsOrchestrationProvider.php Was calling $agent->solve() / injecting OssaAgentExecutor — raw execution in bridge layer ✅ Fixed 2026-04-09 — redirected to POST api.copaw.us/execution/run; tenant derived from \Drupal::currentUser(), not hardcoded; trace_id injected; BIBLE v4 schema (prompt flat) — PROJECTS/ContextControl.ai worktree
OssaAgentExecutor::invoke() in ai_agents_ossa_flowdrop Was calling local LLM directly — bypassed governance plane entirely ✅ Fixed 2026-04-09 — same gateway redirect as orchestration provider — PROJECTS/ContextControl.ai worktree
ExecuteDrushCommand.php Gates on local PolicyEngine::authorize() ✅ Fixed 2026-04-09 — delegates via updated API proxy
RunAgentSheet.swift (Agent Studio macOS) Was calling Drupal orchestration directly — bypassed Cedar, Dragonfly, ContractPlane ✅ Fixed 2026-04-09 — feature/final-wiring

Protocol Layers

Layer Scope Owner
MCP Agent-to-tool execution agent-protocol
CoPaw social gateway JSON-RPC agent telemetry + WebSocket routing (see domains.yaml for claw.copaw.us listener) blu-copaw-stack
A2A Agent-to-agent delegation agent-mesh
DUADP Discovery, identity, addressing duadp
A2H Human approval, escalation, consent ContractPlane
ContractPlane SaaS governance wrapping all layers controlplane.ai

System Roles

System Role
ContractPlane.ai Trust, evidence, policy, compatibility and release authority
contractplane (Drupal module) Governance substrate — workflow, permissions, orchestration, event emission
Marketplaces Consumer surfaces — consume ContractPlane contracts; never invent governance
GitLab Promotion and operations backend
Keycloak Human identity and session authority
Drupal sites Execution runtimes (storefront, dashboards, AgentDash [Fleet functionality absorbed])

Control plane ≠ control panel. ContractPlane is an authority, not a dashboard.

TypeScript Services

Service Owns Must NOT Own
agent-buildkit CLI, agent execution, deployment lifecycle Flow semantics, MCP protocol, routing, Vast.ai logic, token parsing
agent-protocol MCP server, tool/resource registration, GitLab MCP integration Agent execution, routing, registry
agent-router LLM routing, Vast.ai deploy/cost/scale logic MCP protocol, agent execution, manifest authoring
agent-mesh A2A transport, discovery API, service accounts, Duo gateway Routing, execution, policy enforcement
agent-brain Knowledge graph, vector search and RAG infrastructure Execution, routing, orchestration logic
agent-tracer OpenTelemetry tracing, metrics, dashboards Business logic, routing
compliance-engine Cedar PDP, DID identity, DUADP discovery, enforcement, audit trail Policy pack bodies, manifests
workflow-engine DAG execution, state management, retries, Langflow integration Flow definitions or agent runtime
agentic-flows Flow semantics, templates, sequential thinking definitions Flow execution or agent runtime
foundation-bridge Provider integration (Apple FM and multi-provider bridging) Routing, execution, model storage
studio-ui React UI component library Business logic, API calls, state management
dragonfly AI-powered test generation & execution — API, CLI, OpenAPI spec, Playwright testing, ephemeral Docker containers, IaC connections, agent-docker connections. Has its own .agents/ project subagents (workers). NO core agents (→ platform-agents), NO SaaS UI Core agents (→ platform-agents), SaaS UI, PHPCS/PHPStan integration (those are consumers)
dragonfly-saas Next.js SaaS layer for Dragonfly — landing, dashboard, admin, multi-tenancy (tenant-prefixed data isolation), billing/subscription management. Default payment provider: Stripe (integer-cents, no floats; Shopify as alternative). Runs atop dragonfly core; adds SaaS/tenant surface only. Uses studio-ui. Has its own .agents/ subagents. Core backend logic, core agents (→ platform-agents), OpenAPI spec (all owned by dragonfly core)
dragonfly_client Drupal module — full field definitions, content types, config, entity connections, Dragonfly API wiring. Integrates with the Drupal site's own marketplace or DUADP node. Phase 1: consume discover.duadp.org for discovery. Phase 2: site can register its own node (e.g. dragonfly-discover.drupl.ai). Has its own .agents/ subagents. Backend test execution, core agent manifests (→ platform-agents), OpenAPI spec
a2a-collector A2A event store, analytics, compliance reporting, REST API A2A transport, agent execution
a2a-stream A2A SSE streaming A2A transport, event storage
moltbook-community-api (api.copaw.us) Agent Blu Headless Execution Plane. Node/Fastify SOLE execution gateway (POST /execution/run). Owns ReMe (Memory extraction via Qdrant/Tenant boundaries), OpenJudge (native governance gates), Cedar PDP checks, Dragonfly validation trigger, and SSE execution streaming to ContractPlane UI. ContractPlane UI representation, Core OSSA Manifest definitions, Global Policy DB, Bypassable code.
ContractPlane.ai (UI) Governance Dashboard. Next.js frontend (contractplane.ai). Must rigorously use @bluefly/studio-ui React primitives (matches openstandardagents.org/builder/). Core execution, Cedar PDP logic, Raw HTML generic primitive definitions

Drupal Modules

Core Modules (under blueflyio/agent-platform/drupal/)

Module Purpose drupal.org Status
ai_agents_ossa Load/validate OSSA manifests; capability registration Yes Active
ai_agents_orchestra Multi-agent orchestration, vector memory, workflows No Active
ai_agents_client AgentDash client & protocol adapters (MCP, Duo, HTTP) No Active
ai_agents_kagent K8s integration; syncs 35+ services No — needs project Active
ai_agents_communication Agent-to-agent messaging No Active
ai_agents_cursor Cursor Cloud API integration and code generation No Active
ai_provider_apple Apple Foundation Models provider No Active
ai_provider_langchain LangChain/LangGraph memory & graph builder No Active
ai_marketplace Marketplace catalog & publishing UX No Active
contractplane Governance substrate: workflow, permissions, orchestration No Active
cedar_policy Cedar policy enforcement hooks and admin UX No — needs project Needs audit (427 files, 5 submodules)
duadp_client DUADP resolve/register/sync/cache No Active
mcp_registry MCP server registry, AgentDash orchestration, health No Active
api_normalization Multi-provider API normalisation, OpenAPI 3.1 Yes Active
code_executor Secure Docker-based code execution No Active
drupal_patch_framework AI-assisted patching & PHP test runner No Active
external_migration AI-powered content/data migration No Active
layout_system_converter Layout→SDC converter No Active
recipe_onboarding Recipe discovery, validation, AI generation No Active
dita_ccms DITA XML authoring and import/export Yes Active
dragonfly_client Drupal integration — fields, content types, config, entity connections, Dragonfly API wiring, Drupal marketplace + DUADP node integration No Not initialized — needs scaffolding
kb_cache ContextualMemory AI agent memory — ai_context_item entity (agent_memory bundle), 6-state moderation workflow, GAID minting, ECA-governed ContractPlane gate, NetworkMemoryWrite/NetworkMemorySearch Tool plugins, VectorBridge Search API, MCP exposure. Zero hard deps on custom modules. Yes (public contrib) Active — release/v0.1.x
alternative_services DDEV addon management No Active
secure_drupal Security hardening recipe (35 modules, NIST 800-53) Yes Active

Experimental/Legacy (Needs Triage)

These repos exist but have unclear status. Each must be triaged: integrate, consolidate, or archive.

Repo Likely Action
agent_marketplace Consolidate into ai_marketplace
agent_registry_consumer Consolidate into duadp_client
agentic_canvas_blocks Evaluate — may be unique
ai_agents_claude Archive — superseded by ai module
ai_agents_crewai Archive — never production
ai_agents_dashboard Consolidate into ai_agents_ossa
ai_agents_huggingface Evaluate — may have value
ai_agents_marketplace (variant) Archive — duplicate of ai_marketplace
ai_agents_tunnel Consolidate into alternative_services
ai_provider_routing_eca Consolidate into agent-router
apidog_integration Archive — one-off
blockchain_manager Archive — stale concept
recipe_agent_platform Consolidate into recipe_onboarding
recipe_secure_drupal Active — part of secure_drupal
skills_browser Consolidate into ai_marketplace
source_connector Evaluate — may have unique migration value

Blu AI & CoPaw

Architecture note: copaw.us is the execution_domain — api.copaw.us/execution/run is the sole canonical execution entry. The CoPaw social product runs on this domain's infrastructure but does not define the domain's architectural role.

Blu AI Co-Founder Agent

  • Purpose: AI co-founder deployed on Oracle via upstream assistant runtime (see FINAL §21.11 for product disambiguation — not the execution gateway)
  • Status: 17 agents chatting in Moltbook. Persona + skills live. Foundation-bridge listener in domains.yaml. TDDAIStudio ready for Xcode build.
  • Repo: submolt/copaw.us (deploy configs in plans/blu-copaw/deploy/)
  • Skills: architecture, bluefly-ops, drupal-platform, gitlab-workflow, ossa-agents, social-pipeline, browserless-browse, n8n-trigger, ollama-local-llm, qdrant-memory, redis-cache, scrapling-scrape

CoPaw Pet Social Platform

  • Purpose: Pet social network with AI agent integration
  • Status: AgentSocial tunnel active, root copaw.us lacks DNS
  • Remaining: Moltbook web rebuild (blocked by disk), fm.copaw.us tunnel, iMessage integration, OIDC auth route

Upstream assistant runtime (social / Moltbook)

  • Purpose: Multi-agent workspace framework (skills, Docker deploy) — distinct from api.copaw.us execution gateway
  • Deploy: Oracle via Docker Compose under plans/blu-copaw/deploy/
  • Innovation: Skill-based multi-agent collaboration; does not define platform execution ingress

Infrastructure & Tooling

Repository Ownership
controlplane.ai Trust posture, evidence schemas, provider compatibility & release authority; SDK + OpenAPI spec
cedar-policies Canonical Cedar policy pack files & tests (57 policies — need categorization)
duadp DUADP protocol, schemas, resolver, DID implementation & federation
security-policies GitLab security policy definitions
gitlab_components Reusable CI/CD components (19 active templates)
api-schema-registry Master OpenAPI 3.1 definitions & shared JSON schemas
agent-docker Docker images, Kubernetes manifests, NAS orchestration
iac Infrastructure-as-code (Terraform/Pulumi)
agent-tailscale Tailscale mesh networking for agents

Social & Community Projects

Separate product lines sharing infrastructure:

  • Submolt (submolt/*): Web, mobile, backend and AI agents. Active as of 2026-03-14.
  • CoPaw (submolt/copaw.us): Pet social product on the execution domain. api.copaw.us is the execution gateway — not a social product endpoint. See Blu AI section above.
  • Collaborative Impact (collaborative-impact/cim): Collaborative Impact Model; stale as of 2025-03-29.
  • bluefly.io Collective (Collective/*): Legacy/shared repos predating the agent platform; mostly stale.
  • Client sites (Collective/customers/*): Customer-specific Drupal sites (e.g., indoorplantkingdom.com).

Deprecated Items & Violations

Deprecated Repositories

  • gitlab-mcp-server — superseded by agent-protocol
  • gitlab-agent-orchestrator — superseded by platform-agents
  • drupal_fleet_manager — ARCHIVED 2026-03-18: All Fleet functionality absorbed into AgentDash. AgentDash now owns all fleet-scale operations. Must not receive new MRs.
  • Any DELETE- or WIP prefixed repo — must not receive new MRs

Resolved Violations (as of 2026-04-09)

  • agent-buildkit no longer parses tokens or implements Vast.ai logic
  • Sequential thinking definitions moved to agentic-flows
  • Production webhook removed
  • agent-docker no longer handles Vast.ai logic
  • agent-router: node-fetch removed (now uses native fetch, dependency compliant)
  • agent-router: Express 5.x route patterns fixed (no more crash loop)
  • RunAgentSheet.swift (Agent Studio macOS): Drupal orchestration bypass eliminated — now routes exclusively through POST api.copaw.us/execution/run via ExecutionRunClient (fixed 2026-04-09, feature/final-wiring)

Open Violations (as of 2026-04-09)

Violation Required Fix Severity P#
compliance-engine contains Cedar policy bodies (~29 .cedar files) Move to cedar-policies repo — duadp pack DONE (2026-03-29), compliance-engine pack still open HIGH P1.2
OssaAgentExecutor::invoke() in Drupal called $agent->solve() — bypassed execution gateway ✅ Fixed 2026-04-09 — POST api.copaw.us/execution/run, session-derived tenant, BIBLE v4 schema ~~CRITICAL~~ ~~P7.1~~
OssaAgentsOrchestrationProvider::execute() routed n8n/Activepieces through Drupal with no governance ✅ Fixed 2026-04-09 — same gateway redirect; flat prompt schema ~~HIGH~~ ~~P7.1~~
Drupal PolicyEngine.php evaluates Cedar locally in bridge module Delegate to POST compliance.blueflyagents.com/api/v1/evaluate ✅ Fixed 2026-04-09 ~~P7.1~~
agent-buildkit ships MCP servers Move to agent-protocol MEDIUM —
compliance-engine implements MCP via @modelcontextprotocol/sdk Use @bluefly/agent-protocol MEDIUM —
ossa-studio re-implements studio-ui components Use @bluefly/studio-ui MEDIUM —
dragonfly implements a DUADP descriptor endpoint Move to duadp LOW —

Decision Tree

If it's... It goes in...
OSSA manifest file platform-agents
OSSA specification (schema) openstandardagents
Agent Execution (SOLE endpoint) POST /execution/run (moltbook-community-api / api.copaw.us)
Agent execution runtime core agent-buildkit
MCP protocol/tools agent-protocol
LLM routing/Vast.ai logic agent-router
A2A transport/service discovery agent-mesh
A2A event collection a2a-collector
Flow definitions/templates agentic-flows
Flow execution workflow-engine
Knowledge graph/vector storage agent-brain
Cedar policy bodies cedar-policies
Cedar Drupal enforcement cedar_policy
DUADP protocol (SDKs, reference node, spec, federation) duadp (npm / GitLab open source)
DUADP Drupal integration (fields, config, entity wiring) duadp_client (Drupal module)
Drupal AI agent memory (ContextualMemory, GAID, Search API, MCP) kb_cache (Drupal contrib)
Trust/evidence/policy authority controlplane.ai
Governance workflow (Drupal) contractplane
Marketplace catalog ai_marketplace
Shared UI components studio-ui
Shared OpenAPI schemas api-schema-registry
CI/CD templates gitlab_components
AI-powered Drupal testing dragonfly
K8s agent lifecycle kagent
Apple FM / provider bridging foundation-bridge
Blu AI / CoPaw (social stack) submolt/copaw.us

For any new work that doesn't fit above categories, consult the architecture team before creating a repository.

Summary

The platform's strength relies on clear ownership, strict separation of duties and precise deployment boundaries. Use this document, __FINAL-PLAN-TO-UPDATE.md (architecture), and domains.yaml (runtime topology) to determine where code, policies, manifests and infrastructure should live. Do not reinvent logic present in another service, do not duplicate data and do not bypass the established authority layers.

Production recovery authority

When a production incident requires live intervention, authority and sequencing are as follows:

  1. Audit and classify first. Any agent may perform read-only inspection (logs, container state, git history, config). No writes, no restarts until classification is complete and reported.
  2. Explicit approval second. The user (Thomas) must explicitly approve the recovery action before execution. Sub-agents MUST NOT execute live remediation (Docker operations, composer commands, drush en/uninstall, SSH writes) before this approval is given in the current conversation turn.
  3. One bounded change set third. Approved remediation is limited to the exact scope approved — commands, files, containers named in the approval. Scope creep mid-execution requires a new approval gate.
  4. Verify and stop fourth. Run verification steps, report outcome, stop. Do not expand into adjacent cleanup, refactoring, or deployment work without a new explicit task.

Live recovery execution MUST NOT be delegated across sub-agents unless the orchestration workflow for that recovery was itself defined and approved in advance. Improvised sub-agent execution during a live incident is a violation of this authority model.

Appendix — Blu Ownership Contraction (2026-07-13, operator-ratified direction)

Model shift: Blu is not an orchestration platform. Gas City is the runtime; Blu is the governance layer above it. Every Blu implementation starts with one question: is this already a published Gas City capability? If yes, Blu consumes it — it does not own it.

Blu owns exactly five things:

  1. Engineering Constitution — Platform Contract Model, Evidence Discipline, Execution Contract, governance, authority boundaries, capability ownership. Independent of Gas City; applies equally to Git, Drupal, Kubernetes, Claude, Cedar. (Canonical: Engineering-Standard/standards/core/authority-boundary-rules.md §0, evidence-reporting-standard.md.)
  2. Enterprise Policy — Cedar policies, government compliance (FedRAMP, 508), corporate approval workflows, security policy, naming, identity. Bluefly concerns Gas City shouldn't own.
  3. Enterprise Products — BluGuide, GovCMS, OSSA, DUADP, Drupal AI. Products running ON the platform, not orchestration systems.
  4. Integrations — Gas City, Drupal, GitLab, 1Password, Cloudflare, Keycloak, OpenTelemetry. Adapters, not reimplementations.
  5. Knowledge — Engineering Standard, Playbooks, architecture, capability maps, documentation.

Deletion Ledger (canonical). Candidate upstream owners are NOT established ownership — implementation ownership is established only after comparing published behavioral contracts AND compatibility policies (Evidence Reporting Standard §7). The State column is machine-validated against the finite state machine in Engineering-Standard/standards/architecture/capability-convergence.md (NOT_REVIEWED → UNDER_REVIEW → UPSTREAM_INSUFFICIENT | UPSTREAM_EQUIVALENT → RETAINED | REMOVED); Reason carries the human rationale — never embedded in the state. Invariant: no direct Candidate → REMOVED — every removal requires one completed contract comparison recorded here. Update rows in place; this table is the engineering asset, not the prose around it.

Capability Current Blu owner Candidate upstream contract State Reason Blu LOC removable
Work readiness/queue blu work surfaces bd ready / gc hook UNDER_REVIEW 2026-09-10: bd ready is the Beads unblocked-work primitive. Worker session start is gc hook → claim, not fleet-wide bd ready. See Engineering-Standard/operating-model/beads-work-ownership-contract.md. TBD
Runtime monitoring blu monitor gt status / gt doctor / gt feed UPSTREAM_INSUFFICIENT 2026-07-13 (bead hq-58wi): capability decomposes. (a) Machine-resource daemon (Mac disk/cache thresholds + cleanup, ~1,100 LOC src/monitor/) — gt monitors agents/town, not workstation resources; no upstream contract. (b) snapshot + gt-cost.ts already correctly CONSUME gt health/cost contracts. Gap closes when execution leaves workstations; re-review then. 0 today
Escalation of blocked work chat/ad-hoc reporting gt escalate (severity, ack, auto-re-escalate) REMOVED 2026-07-13 (bead hq-58wi): gt escalate --help verified live on Oracle — severity P0–P3, bead-tracked (gt:escalation), tiered routing. UPSTREAM_EQUIVALENT. Blu owned no code, only behavior: chat/ad-hoc blocked-reporting retired as the escalation channel wherever a town exists. 0 (process replacement)
Merge queue (any blu merge logic) Refinery + mail protocol NOT_REVIEWED — TBD
Worktree lifecycle blu worktree (blu-cli) gt worktree / polecat sandbox RETAINED Compared published contracts directly (gt worktree --help, gt polecat --help, blu-cli/src/commands/blu-worktree.ts, src/worktree/repository-resolver.ts) — not equivalent despite the shared name. gt worktree <rig> only creates a worktree inside Gas City's own ~/gt/<target-rig>/crew/<source-rig>-<name>/, scoped to registered Gas City rigs and crew identity (BD_ACTOR/GT_ROLE). Polecat sandboxes are git worktrees too, but spawned/nuked internally by Gas City's own bead-dispatch lifecycle (gt sling/gt done/Witness), not ad-hoc invocable for arbitrary repo checkout. blu-worktree resolves against AGENT_PLATFORM_HOME/NAS bare-repo storage (getBareReposPath()) for any Bluefly product repo, with no rig/crew/bead concept, plus capabilities neither upstream command has: age-based prune, NAS connectivity status diagnostics, issue-number-linked create, project/date-filtered list. Different capability domain, not a duplicate. n/a (no upstream candidate covers this domain)
Periodic automation/patrols blu slop, Node jobs Deacon plugins (plugin.md + gates) → Dogs NOT_REVIEWED — TBD
Canonical-repo protection (none — Blu implementation removed) gt tap guard (PreToolUse, exit 2) + documented external-guards extension point REMOVED 2026-07-13 (bead hq-58wi): gt tap guard --help verified live — upstream owns the guard mechanism (built-ins: pr-workflow, bd-init, mol-patrol, dangerous-command; external guards supported as standalone scripts via settings.json). No built-in canonical-checkout policy yet, but blu-cli's parallel pre-commit mechanism was a duplicate. Correction (2026-07-13, later same day, independent verification): the "diff deleted unmerged" claim above was premature — the +15-line diff (commit 27f7457, src/commands/secure.ts, adds an execution-boundary check to blu secure install-hooks's generated pre-commit template) was still live and pushed on branch chore/hq-k7eq-execution-boundary. Verified no open MR referenced it (GitLab search on both the bead ID and topical text, zero results), then deleted the branch locally and on origin. Follow-on (hq-k7eq, re-scoped): deliver the policy through gt tap's extension point or contribute the guard upstream. −15 (branch actually deleted 2026-07-13, local + origin)
Secrets orchestration blu secure / blu op / blu 1p none found in Gas City docs (2026-07-13 read) RETAINED Enterprise policy layer over 1Password/gitleaks; no upstream candidate found in inspected docs n/a
GitLab surface blu gitlab none (GitLab API is the upstream; blu is the adapter) RETAINED Integration adapter n/a
gt/bd consumption blu gascity, blu work gt CLI, Oracle bd RETAINED Thin consumers, correct shape (self-described wrappers, OBSERVED) n/a

Documentation rule (this repo): the Engineering Standard documents why Bluefly uses a capability, which published contract it depends on, what Bluefly policy layers on top, and what custom code remains and why it can't be deleted. It does not restate runtime documentation.

Standing principle (also recorded in Engineering-Standard/standards/architecture/capability-convergence.md): every Bluefly implementation MUST periodically justify its continued existence against upstream published contracts. If an upstream contract evolves to provide equivalent capability, the Bluefly implementation becomes a candidate for deletion unless it provides demonstrable additional governance, policy, or product value.