Quality Gates and CI Validations

Relevant source files

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

• AGENTS.md
• README.md
• pyproject.toml
• tests/README.md
• tests/unit/README.md
• mkdocs.yml

Quality Gates and Continuous Integration (CI) validations in the flext-auth project represent a strict, automated governance framework designed to ensure code reliability, security, and maintainability. These gates enforce project-wide standards through a combination of static analysis, comprehensive testing tiers, and engineering laws that prevent the introduction of technical debt or regressions.

The system is anchored by the Universal Agent Law, which mandates zero-tolerance for workarounds and requires objective evidence of validation before any code is considered "Done." This framework integrates multiple tools—including Ruff, Mypy, Pyrefly, and Pytest—to form a multi-layered defense against software defects and architectural erosion.

Sources: AGENTS.md:10-25, README.md:42-45, tests/README.md:195-205

The Universal Agent Law

The core of the quality governance is the Universal Agent Law, which acts as the primary engineering contract for both human developers and AI agents. It establishes a "Zero-Tolerance / Strict-Total" approach where failures must be fixed at the root cause rather than bypassed with stubs or suppressions.

Key Governance Principles

• Root Cause Only: No TODOs, stubs, fakes, or escape-hatch typing (e.g., Any) are permitted unless documented with a one-line justification.
• Evidence-Based Completion: "Done" requires a complete chain of validated results, including exit codes and command outputs.
• Strict Typing: Developers must use the most restrictive types that compile; suppression of type errors is forbidden.
• SSOT (Single Source of Truth): Duplication of facts is prohibited; systems must fail loudly when the SSOT is absent.

Sources: AGENTS.md:30-50, AGENTS.md:78-95

Automated Validation Tiers

The project utilizes a structured testing pyramid to ensure functionality at different levels of abstraction. These tiers are executed via canonical make verbs: check, test, val, and docs.

Static Analysis and Linting

Static analysis is enforced through a suite of tools configured in pyproject.toml. These tools verify code style, type safety, and dependency integrity.

Tool	Purpose	Configuration Highlights
Ruff	Linting and formatting	Enforces ALL rules; excludes legacy stubs; 88-character line length.
Mypy	Static type checking	Strict mode; forbids implicit re-exports; validates Pydantic models.
Pyrefly	Advanced type analysis	Set to error for bad argument counts, type mismatches, and unreachable code.
Deptry	Dependency validation	Monitors first-party imports and dev dependency groups.
Codespell	Documentation integrity	Checks filenames and content for common misspellings.

Sources: pyproject.toml:135-140, pyproject.toml:148-175, pyproject.toml:205-275, pyproject.toml:390-410

Testing Standards and Thresholds

Quality gates define specific numerical thresholds that must be met for a validation cycle to be considered successful.

Coverage Requirements

The project mandates high coverage levels to ensure business logic is thoroughly exercised:

• Minimum Total Coverage: 95% for all source code.
• Branch Coverage: 90% for conditional logic.
• Line Coverage: 95% for executable lines.

Performance Standards

Tests must adhere to strict timing requirements to maintain a fast CI/CD pipeline:

• Unit Tests: Must execute in less than 100ms per test.
• Integration Tests: Must execute in less than 1s per test.
• Unit Test Suite: Total execution must remain under 10 seconds.
• Memory Usage: The entire unit test suite must consume less than 50MB.

Sources: tests/unit/README.md:139-152, tests/README.md:78-85

CI/CD Integration and Git Landing

Quality gates are integrated directly into the development workflow through pre-commit hooks and automated PR checks. Code cannot be merged unless all gates are "green."

Landing Protocol

According to the Universal Agent Law, work must be landed immediately after scoped green validation.

1. Validation: Run the complete chain (Static + Tests).
2. Landing: Use git add and git commit with explicit pathspecs.
3. Commit Standard: Write commits as the user with no agent/bot attribution.
4. Push: Perform a fast-forward push.

Sources: AGENTS.md:97-105, tests/README.md:209-215

Automated Documentation Validation

The mkdocs.yml configuration includes validation for links and file references. The CI pipeline ensures that:

• Absolute Links: Warnings are issued for absolute links.
• Unrecognized Links: Warnings are issued for broken or unrecognized links.
• Docstrings: mkdocstrings validates that Python signatures and annotations are present and correctly formatted.

Sources: mkdocs.yml:78-85, mkdocs.yml:50-65

Conclusion

Quality Gates and CI Validations in flext-auth act as a non-negotiable barrier against software degradation. By combining strict engineering laws (Universal Agent Law) with high coverage requirements (95%) and automated performance standards, the project ensures that every commit maintains enterprise-grade reliability. The "Fix-Forward-Only" and "Root Cause Only" mandates further strengthen this by ensuring that the codebase evolves cleanly without the accumulation of temporary hacks or technical debt.

Sources: AGENTS.md:30-45, tests/README.md:195-200, tests/unit/README.md:175-185