Agent Quality Gates

Relevant source files

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

• AGENTS.md
• dev/guidelines/git-workflow.md
• dev/guidelines/testing.md
• tasks.py
• pyproject.toml
• dev/adr/0001-adopt-canonical-agentic-structure.md
• dev/guidelines/documentation.md

Agent Quality Gates are mandatory validation checks that ensure every contribution meets the project's technical standards. These gates apply to both human contributors and AI agents working on the nornir-infrahub repository. All gates must pass before code is committed locally or merged into the stable branch.

Sources: AGENTS.md:73-75, dev/guidelines/git-workflow.md:14-17

Architecture of Quality Gates

The quality gate system operates in three tiers: local formatting, local linting/testing, and Continuous Integration (CI).

Tier 1: Formatting and Local Linting

Contributors run invoke format and invoke lint to validate changes before pushing. The invoke lint task executes a suite of specialized linters covering YAML, Python, type hints, and Markdown.

This diagram shows the local validation flow required before code reaches the remote repository.
Sources: tasks.py:16-64, dev/guidelines/git-workflow.md:14-20

Tier 2: Pre-commit Hooks

A .pre-commit-config.yaml file wires fast checks like ruff, rumdl, and basic file hygiene (whitespace, EOF) into the git commit process. These act as an immediate gate during the git commit command.

Sources: dev/guidelines/git-workflow.md:22-25

Tier 3: Continuous Integration (CI)

The GitHub Actions CI workflow (.github/workflows/ci.yml) replicates the local linting and testing environment. It validates Python code across versions 3.10 through 3.14.

Sources: dev/guidelines/git-workflow.md:46-56, CHANGELOG.md:27

Linter and Validator Suite

The project uses specific tools to enforce different aspects of code quality.

Tool	Focus Area	Command
Ruff	Python style and flakes	invoke lint-ruff
Pylint	Python logic and complexity	invoke lint-pylint
Ty	Static type checking	invoke lint-ty
Yamllint	YAML syntax and style	invoke lint-yaml
Rumdl	Markdown structure	invoke lint-markdown
Vale	Documentation prose style	vale <file>

Sources: tasks.py:25-64, dev/guidelines/documentation.md:46-52, pyproject.toml:236-258

Python Quality Gates

Python code must adhere to a 120-character line length and pass ty type checking. Type annotations are required on all public function signatures. The MCCabe complexity limit is set to 15.

Sources: pyproject.toml:132, pyproject.toml:154, AGENTS.md:86

Documentation Quality Gates

Documentation changes trigger two specific gates:

1. Vale: Checks prose style against the Infrahub style rules.
2. Rumdl: Enforces Markdown formatting and structure.

Sources: dev/guidelines/documentation.md:46-58

Testing Gates

The testing suite acts as a functional quality gate. It is divided into two distinct levels based on cost and dependencies.

Unit Test Gate

Unit tests are the primary gate. They must hit no network and require no Docker. A bare pytest command runs only unit tests.

Sources: dev/guidelines/testing.md:11-14

Integration Test Gate

Integration tests require a live Infrahub stack via Docker. These are marked with @pytest.mark.integration and are excluded from the default run. They must be manually invoked with pytest -m integration.

Sources: dev/guidelines/testing.md:15-18, pyproject.toml:47

This diagram illustrates the separation between fast unit test gates and slow integration test gates.
Sources: dev/guidelines/testing.md:10-23

Agentic Structure Gates

The repository enforces a "Canonical Agentic Structure" (ADR-001). This gate ensures that AI agents use the engine-agnostic .agents/ directory as the source of truth for skills.

• Auditing Gate: The auditing-agentic-structure check must pass with 0 errors and 0 warnings.
• Symlink Integrity: Claude Code skills must be a committed symlink (.claude/skills -> ../.agents/skills) to prevent drift.

Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:18-28, dev/adr/0001-adopt-canonical-agentic-structure.md:50-51

Constitutional Boundaries

The AGENTS.md file defines immutable "Never Do" rules that serve as the final quality gate:

• No Direct Push: Do not push to the stable branch.
• No Secrets: Do not commit tokens or secrets; use PROJECT_ENV_VARIABLES["INFRAHUB_TESTING_INITIAL_ADMIN_TOKEN"] for tests.
• No Gate Weakening: Do not disable or weaken lint/type gates to pass CI. Global rule disabling in pyproject.toml requires inline justification.

Sources: AGENTS.md:95-103, dev/guidelines/git-workflow.md:32-35

Summary

Agent Quality Gates provide a robust framework for maintaining the integrity of the nornir-infrahub repository. By enforcing strict formatting, linting, typing, and testing protocols at both the local and CI levels, the project ensures that all code—whether generated by an AI agent or written by a human—aligns with the OpsMill project constitution and technical architecture.