Quality Gates & Make Contract

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• pyproject.toml
• tests/unit/test_module_governance.py
• src/flext_target_oracle_oic/utilities.py
• src/flext_target_oracle_oic/models.py

The "Quality Gates & Make Contract" system defines the rigorous engineering standards, automated validation checkpoints, and command-driven workflows used to maintain the integrity of the flext-target-oracle-oic repository. It serves as an inviolable framework for both human developers and AI agents to ensure that every change adheres to the project's zero-debt baseline and technical excellence requirements.

The system is anchored by the Universal Agent Law, which mandates strict engineering conduct, including zero-tolerance for workarounds, a "fix-forward-only" approach to version control, and mandatory objective evidence for task completion. These rules ensure that all contributions—regardless of their source—are consistent, high-quality, and verifiable.

Sources: AGENTS.md:7-14, README.md:36-39

Universal Engineering Conduct

All engineering activity within the repository is governed by a core set of principles designed to prevent technical debt and ensure predictable system behavior. These principles apply to every session and cannot be relaxed for convenience or speed.

Core Principles

• Zero-Tolerance / Strict-Total: Root causes must be fixed generically using canonical code. Superseded code must be removed in the same cycle it is replaced. Bypasses like TODO, FIXME, or stubs are strictly forbidden.
• Fix-Forward-Only: To prevent destroying in-flight work in a multi-agent environment, reverting shared state is prohibited without explicit user confirmation.
• SSOT (Single Source of Truth): Every fact must have one authoritative source. Guesses or local copies are not permitted when a canonical source is absent.
• Strict Typing: Use of the most restrictive types that compile. Escape hatches like Any or # type: ignore are forbidden without documented justification.

Sources: AGENTS.md:16-36, AGENTS.md:83-86, AGENTS.md:91-100

The Make Contract

The "Make Contract" establishes a standardized set of make verbs that serve as the primary interface for triggering quality gates. These commands encapsulate complex validation logic and provide a consistent entry point for both local development and CI/CD pipelines.

Verb	Purpose	Description
check	Static Analysis	Runs linters, type checkers, and formatting validators.
test	Dynamic Validation	Executes unit, integration, and end-to-end test suites.
val	Schema Validation	Validates configuration, models, and contracts against project schemas.
docs	Documentation	Generates and validates technical documentation and API references.
mod	Dependency Sync	Regenerates managed sections of pyproject.toml via flext_infra.
gen	Code Generation	Regenerates auto-generated files like lazy export maps and versions.

Sources: README.md:36-39, pyproject.toml:1-5, src/flext_target_oracle_oic/init.py:1-5

Automated Quality Gates

The project employs multiple layers of automated validation to enforce the Make Contract. These gates are configured via pyproject.toml and verified through the test suite.

Static Analysis and Linting

The project uses ruff, mypy, pyright, and pyrefly to enforce coding standards. The configuration mandates high-precision checks, including:

• Coverage Thresholds: A minimum coverage requirement (e.g., fail_under = 20) to ensure basic visibility.
• Banned APIs: Direct use of certain libraries (like rich, tqdm, or colorama) is banned in favor of flext-cli abstractions to maintain architectural consistency.
• Module Governance: Custom tests ensure modules do not define forbidden elements like module-level loggers or unapproved top-level functions.

Sources: pyproject.toml:112-115, pyproject.toml:438-510, tests/unit/test_module_governance.py:54-93

Validation Logic Flow

The following diagram illustrates how a code change must pass through the Quality Gates before being considered "Done."

This flow ensures that no code enters the main branch without objective validation.
Sources: AGENTS.md:16-21, AGENTS.md:66-70, pyproject.toml:112-115

Runtime Configuration Validation

Quality gates extend to runtime behavior through strict validation of configuration and data models. The FlextTargetOracleOicUtilities class implements these gates to ensure that the target only operates with valid parameters.

Validation Components

• Config Validation: The validate_config method checks for mandatory OIC settings like base_url and OAuth credentials.
• Model Invariants: Domain models (e.g., OICConnection) include validation logic to prevent invalid states, such as empty identifiers or names.

# src/flext_target_oracle_oic/utilities.py:31-38
@staticmethod
def validate_config(settings: t.ConfigurationMapping) -> p.Result[bool]:
    """Validate required OIC target configuration keys."""
    required = {"base_url", "oauth_client_id", "oauth_client_secret"}
    missing = sorted(key for key in required if key not in settings)
    if missing:
        return r[bool].fail(f"Missing required settings fields: {missing}")
    return r[bool].ok(value=True)

Sources: src/flext_target_oracle_oic/utilities.py:31-38, src/flext_target_oracle_oic/models.py:90-97

Governance Pointer Summary

The following table summarizes the key governance files and their roles in the Quality Gate system.

File	Role
AGENTS.md	Defines the Engineering Law and Universal Agent Law.
pyproject.toml	Configures tool-specific thresholds (mypy, ruff, coverage).
test_module_governance.py	Enforces architectural constraints on module structure.
utilities.py	Provides runtime validation for configuration and models.

Sources: README.md:41-48, tests/unit/test_module_governance.py:1-5

The "Quality Gates & Make Contract" framework ensures that the flext-target-oracle-oic project maintains high reliability and maintainability by strictly enforcing engineering standards at every stage of the development lifecycle.