Quality Gates & Make Contract
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The "Quality Gates & Make Contract" defines the strict engineering standards and automated validation processes required for the flext-oracle-oic repository. It establishes a zero-tolerance policy for technical debt and mandates that all changes meet specific coverage, typing, and architectural thresholds before being considered "done." This framework ensures that the Oracle Integration Cloud (OIC) extensions maintain enterprise-grade reliability and consistency across different AI agents and human contributors.
The system relies on a "Make Contract"—a set of canonical make verbs—and a "Universal Agent Law" that governs how code is modified, validated, and landed. These gates are not merely suggestions but are enforced through automated tooling and strict coding principles like SSOT (Single Source of Truth) and SOLID.
Sources: README.md:37-43, AGENTS.md:7-14
Universal Agent Law
The Universal Agent Law is the core of engineering conduct for this project. it binds all AI agents (Claude, Codex, GitHub Copilot, etc.) and human users to a strict set of operational rules.
Core Principles
- Zero-Tolerance/Strict-Total: Root causes must be fixed generically. "Dead code" must be removed immediately. If a failure appears in a contributor's flow, they "own" the fix regardless of its origin.
- Fix-Forward-Only: Contributors must never use
git reset,git revert, orgit checkoutto discard shared work. All progress must move forward to prevent destroying in-flight work from other agents. - Root Cause Only: The use of
TODO,FIXME, stubs, fakes, or type-suppression directives (like# type: ignore) is forbidden unless accompanied by a one-line documented justification. - Evidence Before Done: A task is only complete when the entire chain is validated with objective evidence, including the command executed, the exit code, and the specific output lines.
Sources: AGENTS.md:16-43, AGENTS.md:52-59
The Make Contract
The project uses a standardized "Make Contract" to execute quality gates. These canonical verbs provide a consistent interface for validation across the FLEXT ecosystem.
| Verb | Purpose |
|---|---|
check | Runs static analysis, linting, and type checking. |
test | Executes the test suite (unit, integration, and resilience tests). |
val | Performs validation of configurations and contracts. |
docs | Generates or validates documentation and API references. |
mod | Regenerates managed sections of the pyproject.toml file. |
Sources: README.md:39-41, pyproject.toml:4-6
Automated Validation Flow
The following diagram illustrates the sequence of operations an agent or developer must follow to satisfy the Quality Gates.
The flow ensures that every change is scoped, validated, and evidenced before landing in the repository.
Sources: AGENTS.md:52-65, pyproject.toml:132-135
Technical Standards & Constraints
The project enforces strict technical boundaries through configuration and specialized utility modules.
Coverage & Typing
- Test Coverage: The project maintains a mandatory coverage threshold. Currently, the
fail_underlimit for the coverage report is set to 25% as a baseline for the development phase. - Type Checking: The project utilizes
mypyandpyrightfor strict type checking. Configurations inpyproject.tomldisableimplicit_reexportand requirestrict_equality. - Banned APIs: To ensure consistency, the project bans several common libraries in favor of internal
flext_cliutilities, includingclick,rich,tabulate, andtqdm.
Sources: pyproject.toml:135, pyproject.toml:154-177, pyproject.toml:340-410
Validation Logic
The FlextOracleOicUtilitiesOracleOic class implements the logical gates for data integrity within the OIC context.
This utility ensures that any OIC integration data adheres to the INTEGRATION_NAME_RE regex and specific version patterns like XX.XX.XXXX.
Sources: src/flext_oracle_oic/_utilities/oracle_oic.py:53-85, src/flext_oracle_oic/constants.py:228-245
Performance & Monitoring Gates
Beyond static code quality, the project implements "Monitoring Gates" to validate the health and performance of the OIC environment.
Performance Thresholds
The project defines specific thresholds for operational health. If these metrics are exceeded during runtime or validation, the system triggers alerts or failures.
| Metric | Threshold | Source of Truth |
|---|---|---|
| Response Time | 5000ms | c.OracleOicValidation.PERFORMANCE_THRESHOLDS |
| Success Rate | 95% | c.OracleOicValidation.PERFORMANCE_THRESHOLDS |
| Error Rate | 5% | c.OracleOicValidation.PERFORMANCE_THRESHOLDS |
Sources: src/flext_oracle_oic/constants.py:260-264, src/flext_oracle_oic/_utilities/monitoring.py:16-45
Health Assessment Logic
The FlextOracleOicUtilitiesMonitoring class assesses metrics and returns specific recommendations. For example, a success rate below 95% is classified as a "Critical Issue" and changes the overall health status to unhealthy.
Sources: src/flext_oracle_oic/_utilities/monitoring.py:27-35
Conclusion
The Quality Gates & Make Contract system in flext-oracle-oic creates a high-trust environment by replacing manual oversight with automated, rigorous validation. By adhering to the Universal Agent Law and the canonical Make Contract, the project ensures that every contribution—whether from a human or an AI—is technically sound, thoroughly tested, and architecturally consistent.