Skip to content

STD-AUTH-001: Authority Precedence Hierarchy, Light Factory Composition Architecture & Documentation Drift Rule

Status: Approved Governing Standard Owner: Bluefly Architecture & Governance Scope: All agents, human operators, Gas City Rigs, DrupalWorks, and BluCity repositories.

1. Prime Directive: Authority Precedence Hierarchy

When evaluating rules, capabilities, system behavior, or code implementation, precedence MUST strictly follow this exact 5-tier order:

┌─────────────────────────────────────────────────────────────────────────┐
│ 1. LATEST CURRENT UPSTREAM DOCS / SOURCE                                │
│    └─ Defines current platform semantics (Gas City, Drupal, Contrib, GL)│
├─────────────────────────────────────────────────────────────────────────┤
│ 2. CURRENT BLUEFLY SOURCE                                               │
│    └─ Defines what is actually implemented today.                       │
├─────────────────────────────────────────────────────────────────────────┤
│ 3. CURRENT ENGINEERING STANDARD / ADR                                   │
│    └─ Defines Bluefly policy & architectural contracts.                 │
├─────────────────────────────────────────────────────────────────────────┤
│ 4. OPERATOR / PRODUCT DIRECTION ("LIGHT FACTORY")                       │
│    └─ Defines product/factory intent and WHY we build this way.        │
├─────────────────────────────────────────────────────────────────────────┤
│ 5. OLDER ARTICLES / CACHED DOCS / HISTORICAL IMPLEMENTATIONS            │
│    └─ Historical context ONLY, unless still explicitly valid.           │
└─────────────────────────────────────────────────────────────────────────┘

Interpretation Rule

  • If an older article or past implementation conflicts with current upstream documentation or source code, current upstream wins.
  • If older product documentation conflicts with current operator direction, current operator direction wins.

2. Documentation Drift Rule

If BluCity-Docs, an AGENTS.md file, or local documentation asserts behavior that no longer matches live upstream behavior or actual running codebase implementation:

DOCUMENTATION_DRIFT=YES

Governing Action:

  1. Do NOT force the running system or upstream code back to conform with outdated documentation.
  2. Record DOCUMENTATION_DRIFT=YES in the active Bead.
  3. Update the documentation to reflect current reality and upstream truth.

3. Light Factory Composable Architecture

The composable Drupal surface maps directly to Gas City durable backend orchestration:

 DRUPAL
 └── Composable, contrib-first factory surface
     ├── Recipes (recipes/)           ──► Compositions
     ├── ECA / FlowDrop               ──► Workflows
     ├── Tool API / Tool Belt         ──► Typed Capabilities
     ├── AI Agents / AI Context       ──► Agent Actors
     ├── api_normalization            ──► External API -> Entity Bridges
     ├── ContextControl               ──► Human + Governed Context UI
     └── Gas City (/opt/bluefly/blucity)─► Durable Backend Orchestration

Layer Responsibilities:

Layer Responsibility Upstream / Canonical Owner
Compositions Packaged site features & layouts Core Recipes (recipes/)
Workflows Event automation & visual logic ECA (drupal/eca), FlowDrop (drupal/flowdrop), Modeler
Typed Capabilities Executable entity & service operations Tool API (drupal/tool), Tool Belt (drupal/tool_belt)
Agent Actors Drupal-native AI agent definitions AI Agents (drupal/ai_agents), AI Context (drupal/ai_context)
External Bridges External API → Drupal-native entities api_normalization
Context UI Human + governed context interface ContextControl (contextcontrol_ai)
Backend Engine Durable work graph & execution ledger Gas City (hq Dolt database / /opt/bluefly/blucity)

4. Upstream-First Invariant

  1. Core → Contrib → Recipes → Canvas/SDC → ECA/FlowDrop → Drupal AI → Tool API/MCP → Custom Code.
  2. Custom code is a last resort. If an upstream module, recipe, or tool plugin provides a capability, configure or contribute to upstream.

5. Universal Acceptance Gate

Every work receipt, change, plan, and commit MUST explicitly report:

IS_THE_NEXT_RUN_GETTING_CHEAPER_AND_MORE_REUSABLE=YES|NO
WHY=<explanation of how custom code decreased, reusable capability increased, or workflow steps were automated>