Governance & Engineering Rules
Relevant source files
The following files were used as context for generating this wiki page:
The flext-dbt-oracle project operates under a strict set of engineering laws and governance protocols designed to ensure architectural integrity, continuous stability, and automated verification. These rules define the relationship between human operators and AI agents, the lifecycle of code changes, and the technical constraints of the dbt Oracle adapter.
Sources: AGENTS.md:1-10, README.md:38-42
Universal Engineering Core
The project adheres to the "Universal Agent Engineering Core," where all development is governed by a Single Source of Truth (SSOT). Configuration and settings are never hardcoded in tests or implementation; instead, they are derived from canonical sources such as rules.json or defined FlextSettings.
P0 — Construction-Based Validation
A primary rule is that tests must validate configurations and settings by construction. Tests are prohibited from hardcoding values; they must read expected values from the same typed SSOT used by production code. Any test that breaks due to a legitimate configuration change is considered a defect in the test itself.
Sources: AGENTS.md:15-30
Governance Hierarchy
The project establishes a clear hierarchy of authority:
- Operator Instructions: The newest explicit operator instruction overrides all other rules.
- Project Law: Specific project rules (e.g.,
rules.json). - Universal Core: The
~/.agentsuniversal authority.
Sources: AGENTS.md:10-14, AGENTS.md:144-152
Engineering Protocols
The project enforces strict protocols for implementation, research, and validation to maintain a "Continuous Green" state.
Code Quality and Gates
All code, including tests, examples, and scripts, must pass a standardized suite of quality gates. The project prohibits the use of per-file-ignores or exclusion patterns to hide violations.
| Gate Type | Tools Used | Scope |
|---|---|---|
| Linting | Ruff, Pylint | All .py files |
| Typing | Mypy, Pyright, Pyrefly | All .py files |
| Testing | Pytest | Unit, Integration, E2E |
| Security | Bandit, pip-audit | Source and Deps |
Sources: AGENTS.md:58-71, pyproject.toml:68-125
The Fix-Forward Rule
In a multi-agent environment, reverting changes is strictly forbidden as it may destroy concurrent work. Agents must accept the current state and "fix forward" to resolve issues.
This diagram shows the mandatory "Fix Forward" logic used to handle errors in shared working trees.
Sources: AGENTS.md:54-56, AGENTS.md:204-211
Module Governance & Architecture
The project implements specific structural rules to maintain a clean Python package hierarchy and prevent side effects.
Top-Level Constraints
As enforced by test_module_governance.py, package modules are subject to the following restrictions:
- No Module-Level Loggers: Defining
loggeror_loggerat the module level is forbidden. - No Top-Level Functions: Modules should not define functions at the top level; functionality should be encapsulated within classes or specific constructs.
Sources: tests/unit/test_module_governance.py:59-93
Dependency Management
The project strictly forbids certain dependencies to ensure it remains a pure Oracle adapter without legacy PostgreSQL baggage.
This diagram illustrates the allowed vs. forbidden dependencies as defined in the project rules.
Sources: rules.json:104-118
Adapter-Specific Rules
Technical constraints for the dbt-Oracle adapter are codified in rules.json. These rules dictate the SQL dialect behavior and materialization strategies.
SQL Dialect and Type Mapping
The adapter is configured for a modern Oracle environment, supporting long identifiers and specific type mappings.
| Feature | Constraint/Value |
|---|---|
| SQL Dialect | Oracle |
| Case Sensitivity | Uppercase Default |
| Identifier Max Length | 128 characters |
| Modern dbt Only | True (>= 1.8.0) |
| Supported Materializations | table, view, incremental, snapshot |
Sources: rules.json:44-64
Data Type Enforcements
The project enforces strict mapping from dbt abstract types to Oracle-specific types to ensure consistency across models.
- String:
VARCHAR2(4000) - Boolean:
NUMBER(1,0) - Timestamp:
TIMESTAMP - Large Text:
CLOB
Sources: rules.json:65-85
Summary of Conduct
Engineering conduct is summarized by the "Zero-Tolerance" policy. Developers and agents must always fix the root cause rather than applying workarounds, remove superseded code immediately, and "fail loud" if a source of truth is missing. Every change must be land-ready, meaning it is independently validated, committed with explicit pathspecs, and pushed immediately to maintain the integration branch's health.
Sources: AGENTS.md:191-203, AGENTS.md:267-273