Engineering Governance and Standards

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
• src/flext_auth/history.json

Engineering Governance and Standards within the FLEXT Auth project establish the inviolable core of conduct for both human developers and AI agents. This framework ensures architectural consistency, strict type safety, and a zero-debt baseline across the enterprise authentication and authorization service. The governance model is anchored by the "Universal Agent Law," which dictates a fix-forward-only approach and mandates root-cause solutions over temporary workarounds.

The scope of these standards covers every aspect of the development lifecycle, from coding principles (SOLID, SSOT, YAGNI) to mandatory quality gates and testing requirements. By adhering to these protocols, the project maintains a "Zero-Tolerance" policy toward technical debt, superseded code, and unverified results.

Sources: AGENTS.md:6-14, README.md:9-12

Universal Agent Law and Engineering Conduct

The core of engineering governance is the Universal Agent Law, a self-contained set of rules binding any AI agent or contributor. This law prioritizes the root cause of issues and forbids the introduction of "dead code," stubs, or legacy workarounds.

Core Conduct Mandates

• Zero-Tolerance Policy: Contributors must always fix root causes generically and remove superseded code in the same cycle. Classified failures found during a task must be owned and resolved, regardless of whether they were "pre-existing."
• Fix-Forward-Only: Reverting shared work is strictly forbidden. Agents must accept the current state of the working tree and apply improvements forward to avoid destroying in-flight work from other contributors.
• Evidence-Based "Done": A task is only considered complete when validated with objective evidence, including specific commands, exit codes, and output lines. Speculative or partial results are prohibited.

Sources: AGENTS.md:18-35, AGENTS.md:46-52

Universal Engineering Principles

The project enforces four primary architectural principles across all modules:

Principle	Description
SSOT	Single Source of Truth; reference one authoritative source per fact, never duplicate.
SOLID	Strict adherence to SRP, OCP, LSP, ISP, and DIP. No "god-objects."
YAGNI	"You Ain't Gonna Need It"; no speculative parameters or dead branches.
DI / DIP	Depend on abstractions (Protocols/Interfaces) and inject collaborators.

Sources: AGENTS.md:83-93

Quality Gates and Technical Standards

Engineering standards are enforced through automated quality gates and a strict-total toolchain. These gates must turn green before any code is landed in the repository.

Mandatory Tooling and Enforcement

The project uses a managed pyproject.toml configuration to enforce standardization across environments. Key tools include:

• Type Checking: mypy and pyright with strict modes enabled. Any and unchecked casts are forbidden unless documented.
• Linting and Formatting: ruff with all rules enabled, black for formatting, and codespell for documentation accuracy.
• Security Auditing: bandit and pip-audit for dependency and code-level vulnerability scanning.

Sources: pyproject.toml:130-155, pyproject.toml:500-550, AGENTS.md:73-77

Quality Gate Flow

The following diagram illustrates the lifecycle of a change as it passes through the engineering governance gates:

This flow ensures that no bypasses (such as # type: ignore or TODO) are introduced during the development cycle.

Sources: AGENTS.md:18-24, AGENTS.md:58-63, README.md:32-35

Testing and Coverage Standards

Testing is a primary governance pillar, requiring a minimum of 95% line coverage across the codebase.

The Testing Pyramid

The project implements a testing hierarchy to balance execution speed with validation depth:

1. Unit Tests (Many): Focus on domain logic and service validation in isolation (< 100ms per test).
2. Integration Tests (Some): Validate service interactions, database integrations, and JWT flows (< 1s per test).
3. End-to-End Tests (Few): Complete user journeys and multi-service workflows (< 10s per test).

Sources: tests/README.md:27-40, tests/unit/README.md:20-28

Test Metrics and Requirements

Metric	Requirement
Line Coverage	95% Minimum
Branch Coverage	90% Minimum
Unit Test Speed	< 100ms
Flaky Tests	0% Allowance
Reliability	Deterministic results across all environments

Sources: tests/README.md:80-92, tests/unit/README.md:120-130

Implementation Standards for Domain Constants

Architecture Layer 1 (Domain Constants) utilizes advanced Python 3.13+ features to ensure type-safe governance.

Constant Patterns

• StrEnum Integration: All domain enumerations (Roles, Permissions, Token Types) use StrEnum for automatic Pydantic 2 validation and string serialization.
• PEP 695 Type Aliases: Strict Literal types are used for payload validation.
• Immutable Sets: Collections.abc sets (e.g., VALID_TOKEN_TYPES) provide O(1) validation for input types.

Sources: src/flext_auth/history.json: (constants.py content)

Example: Role and Permission Governance

This structure ensures that roles and permissions are centrally governed and cannot be extended without modifying the single source of truth (SSOT).

Sources: src/flext_auth/history.json: (constants.py content)

Conclusion

Engineering Governance in FLEXT Auth is not merely a set of suggestions but a set of inviolable laws. By combining the Universal Agent Law with strict technical gates and high coverage requirements, the project ensures a maintainable, enterprise-grade security service. Contributors must prioritize root-cause fixes and forward-moving progress to maintain the integrity of the shared codebase.

Sources: AGENTS.md:6-14, tests/README.md:184-190