Universal Project Governance
Relevant source files
The following files were used as context for generating this wiki page:
Universal Project Governance within the flext-dbt-oracle-wms project establishes the inviolable laws and engineering principles that bind all contributors, whether human or AI agents. It ensures that the project maintains a high-quality, typed, and predictable environment for Oracle WMS data transformations. This governance model centers on the concept of the "Single Source of Truth" (SSOT) and strict adherence to validated workflows.
The core of this governance is defined in the AGENTS.md file, which serves as the "Universal Agent Engineering Core" and "Universal Agent Law." It dictates everything from root-cause analysis to multi-agent coordination, ensuring that no completion is declared unless the project remains "Continuous Green" across all quality gates.
Sources: AGENTS.md:1-12, README.md:32-37
Core Engineering Laws
The project operates under a set of "Universal Agent Laws" that prioritize stability, accuracy, and technical debt elimination. These rules are agent-agnostic and apply to every session.
Zero-Tolerance and Root Cause
The governance model mandates a zero-tolerance policy toward workarounds, temporary stubs, or fakes. Every defect must be fixed at its root cause using generic, clean, and reusable canonical code. Suppressions like # type: ignore or blanket # noqa are prohibited unless accompanied by a documented one-line justification.
Fix-Forward and Concurrency
Because multiple agents may share a single working tree, the "Fix-Forward" rule forbids destructive git operations such as hard resets, restores, or stashes that might destroy in-flight work. Agents must integrate concurrent changes and stabilize the shared version together.
Sources: AGENTS.md:168-196, AGENTS.md:231-237
Quality Gates and Validation
Governance is enforced through rigorous quality gates that must pass before any work is considered "Done."
The "Done" Contract
"Done" is a hard contract requiring a complete chain of validation. This includes:
- Objective evidence through exact commands, exit codes, and output.
- All lint, format, type, and coverage gates passing with zero errors.
- Committing explicit owned paths and immediate fast-forward pushing.
Tooling and Gates
The project uses a standard suite of tools for enforcement, including Ruff, Pyrefly, Pyright, Mypy, and Pytest. These gates cover src/, tests/, examples/, and scripts/ with equal rigor.
| Gate Type | Tools Used | Requirement |
|---|---|---|
| Linting | Ruff, Pylint | Zero violations |
| Typing | Pyright, Mypy, Pyrefly | Strict-total typing, no Any |
| Security | Bandit, pip-audit | Mandatory scans |
| Testing | Pytest | Executable documentation validation |
Sources: AGENTS.md:43-57, pyproject.toml:68-124, AGENTS.md:204-213
Configuration and SSOT (Single Source of Truth)
The project enforces a strict hierarchy of authority where ~/.agents and config/*.yaml are the sole universal authorities.
P0 — Test Validation by Construction
A primary rule (P0) is that tests must never hardcode or freeze configuration values. Instead, they must read expected values from the same typed SSOT used by production. A test that breaks on a legitimate configuration change is considered a test defect and must be fixed at the test level, not by freezing the configuration.
Configuration Hierarchy
- Operator Word: The newest explicit operator instruction overrides all other authority.
- SSOT Configuration:
config/*.yamlor typed settings objects. - Canonical Source: Implementation logic derived from the SSOT.
Sources: AGENTS.md:16-33, AGENTS.md:118-125
Operational Flow and Logic
The governance logic ensures that development follows a "Plan-Execute-Validate-Land" cycle.
Execution Flow
The following diagram illustrates the lifecycle of a task under Universal Project Governance:
This flow ensures that no code lands without validation and that the state of the work (managed via "Beads") is always current.
Sources: AGENTS.md:35-41, AGENTS.md:144-149, AGENTS.md:255-263
Coordination via Beads
Beads represent the execution truth, owning plans, status, and evidence. The orchestrator role coordinates these beads and approves merges, while worker roles implement individual beads in isolated branches.
Sources: AGENTS.md:65-74, AGENTS.md:154-162
Standardized DBT Architecture
In the context of Oracle WMS data transformations, governance extends to the dbt (data build tool) structure. The project follows a "5-layer architecture" centralized through flext-meltano patterns to eliminate configuration duplication.
| Layer | Materialization | Purpose |
|---|---|---|
| Staging | View | Raw WMS data transformation and cleaning |
| Marts | Table | Business-ready data models |
| Operational | Table | Real-time operational summaries |
| Analytical | Table | Long-term reporting and analysis |
| Metrics | View | Enterprise KPIs and dashboards |
Sources: dbt_project_migrated.yml:10-40, dbt_project.yml:25-55
Summary
Universal Project Governance in flext-dbt-oracle-wms is a rigid framework designed to ensure software reliability and maintainability. By treating AI agents as disciplined engineers bound by "Universal Law," the project guarantees that all changes are root-cause focused, strictly typed, and evidence-validated. This governance eliminates "legacy" excuses and maintains a continuous green state through standardized quality gates and a strict single source of truth.
Sources: AGENTS.md:168-175, README.md:32-37