Context Preflight Contract & Enforcer¶

Mandatory preflight rule¶

Before any specialist initiates source code mutation, opens a branch, or creates a Merge Request, the agent MUST resolve the applicable fields of the context-acquisition contract below. It is context-sensitive — resolve only the fields relevant to the task, not every field for every task (see README.md §5 for examples: Drupal work → Drupal/Canvas docs; CI work → GitLab + gitlab_components; a runtime incident → Oracle/runtime evidence; documentation work → QMD + source docs).

Context-acquisition contract¶

HOST=
AUTHORITY=
TARGET=

# Work intent
BEAD-WORK_INTENT=
PROJECT-REPOSITORY=
SOURCE_OWNER=
BRANCH=
CURRENT_MR-CI_STATE=

# Doctrine & estate graph
DOCTRINE=QMD
ESTATE_DEPENDENCIES=ORBIT_REMOTE
LOCAL_CODE_DEPENDENCIES=ORBIT_LOCAL
GITLAB_TRANSACTIONAL_STATE=LIVE_GITLAB

# Product/domain (as applicable)
PRODUCT_CONTEXT=<DRUPAL|OTHER|N/A>
UPSTREAM_DOCUMENTATION=CURRENT_OFFICIAL_SOURCE

# Identity & secrets
IDENTITY=ASSIGNED_SERVICE_ACCOUNT-AGENT_ROLE
SECRETS=REFERENCE_ONLY-1PASSWORD_AUTHORITY

# Execution environment
WORKSPACE=<DDEV|GITLAB_WORKSPACE|GOVERNED_WORKTREE>

Minimal legacy form (doctrine + estate graph only — still valid for doc-only/no-code-mutation work)¶

1. QMD DOCTRINE PASS:
   - Query BluCity-Docs via `qmd query "<topic>"` to retrieve governing standards and constraints.
2. ORBIT ESTATE GRAPH PASS:
   - Query Orbit Remote via `glab orbit remote` to identify dependent callers, downstream projects, and active MR collisions.
3. ORBIT LOCAL AST PASS:
   - Run `glab orbit local index .` inside the Workspace container to index branch-specific changes.

Executable Preflight Contract Output¶

CONTEXT_PREFLIGHT_REQUIRED=YES

WORK:
  BEAD_FOUND=YES
  BEAD_OWNER=DRUPAL
  BEAD_STATE=CLAIMED

ORBIT:
  REMOTE_HEALTHY=YES
  PROJECT_INDEXED=YES
  RELATED_DEFINITIONS_CHECKED=YES
  DEPENDENCIES_CHECKED=YES
  RELATED_MRS_CHECKED=YES
  PIPELINE_CONTEXT_CHECKED=YES
  SECURITY_CONTEXT_CHECKED=YES
  CONFLICTS_FOUND=NO

QMD:
  BLUCITY_DOCS_INDEX_HEALTHY=YES
  RELEVANT_STANDARD_FOUND=YES
  ARCHITECTURE_RULES_FOUND=YES
  RELEASE_DOCTRINE_FOUND=YES
  CONFLICTING_DOCS_FOUND=NO

PRODUCT_CONTEXT:
  APPLICABLE=<YES|NO>
  DOMAIN=<DRUPAL|OTHER|N/A>
  UPSTREAM_DOCS_CHECKED=<YES|NO|N/A>

IDENTITY:
  SERVICE_ACCOUNT_CONFIRMED=YES
  SECRETS_SOURCE=1PASSWORD_REFERENCE_ONLY

RESULT:
  CONTEXT_COMPLETE=YES
  SOURCE_MUTATION_ALLOWED=YES

Treat QMD results as evidence of what the doctrine says, not proof it is current — QMD is a known stale-prone derived index, re-verify against BluCity-Docs source (or the live file via GitLab API) before relying on a search hit for a consequential decision; see the "Absence proven by a single mechanism is not absence" entry in the Failure Signature Catalog.

Relationship to other context sources¶

This contract is the gate; README.md §4 is the reference for what each source actually is and how fresh it is. Resolve fields here by consulting the matrix there, not the other way around.