Quality Gates and CI

Relevant source files

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

• AGENTS.md
• pyproject.toml
• README.md
• tests/README.md
• CLAUDE.md
• tests/unit/test_architecture_boundary_contract.py
• tests/unit/athena_cli/test_packaging.py

Athena employs a rigorous suite of quality gates and continuous integration (CI) practices to maintain its architecture as a Python modular monolith. These gates ensure type safety, adherence to architectural boundaries, and code style consistency across the repository. The project enforces a strict "blank slate" design philosophy where technical debt is minimized through automated validation rather than manual oversight.

Sources: AGENTS.md:86-104, README.md:12-21

Execution Framework

The project utilizes scripts/ci.sh as the primary entry point for executing quality checks and tests locally. This ensures that the environment used by developers matches the requirements of the CI system.

Core CI Commands

Developers and agents are required to run specific commands before reporting work as complete or committing code.

Command	Description
./scripts/ci.sh quality	Runs ruff format, ruff lint, basedpyright, and import-linter.
./scripts/ci.sh test	Executes the full pytest suite.
./scripts/ci.sh all	Runs both quality checks and the test suite.
prek run --all-files	Execution of pre-commit hooks before git commit.

Sources: AGENTS.md:65-72, README.md:104-118, CLAUDE.md:18-24

CI Pipeline Flow

The following diagram illustrates the logical flow of the quality gate process executed during local development or CI.

This flow ensures that structural and stylistic issues are caught before the more time-consuming test suite is executed.
Sources: AGENTS.md:377-380, README.md:104-118

Architectural Boundary Validation

Athena uses import-linter to enforce the modular monolith's layered architecture. This prevents "big ball of mud" scenarios by strictly controlling the dependency direction between packages.

Layer Hierarchy

Dependencies are allowed to flow only from outer layers to inner layers as defined in the following hierarchy:

1. transports / jobs
2. services (Commands/Queries)
3. repositories
4. infrastructure
5. domain
6. shared

Sources: pyproject.toml:132-142, AGENTS.md:106-118

Key Forbidden Import Rules

The CI system enforces several critical boundaries to maintain hexagonal architecture:

• Services Isolation: Services must not depend on transports, concrete repository implementations (SQLAlchemy/Memory), or framework-specific libraries like starlette or fastapi.
• Domain Purity: The domain layer is prohibited from importing any I/O libraries, including pydantic, sqlalchemy, httpx, or valkey.
• Transport Independence: Different transport families (Stable, Lazer, API) must remain entirely independent of each other.

Sources: pyproject.toml:144-245, tests/unit/test_architecture_boundary_contract.py:157-195

Type Safety and Linting Standards

Athena mandates basedpyright strict mode for all production and test code. This ensures a high level of type safety across the modular boundaries.

Resolution Policy for Type Errors

The project follows a strict hierarchy for resolving type or linting errors, prohibiting broad suppressions like # type: ignore or Any.

1. Code Correction: Fixing the underlying type mismatch.
2. Typed Fakes/Stubs: Utilizing Protocol-compliant stubs or in-memory implementations instead of untyped mocks.
3. Community Stubs: Adding types-* packages.
4. Local Stubs: Generating or manually refining .pyi files in typings/.
5. Inline Suppression: Used only as a last resort with a documented reason.

Sources: AGENTS.md:417-440, tests/README.md:5-30

Linting Configuration

Ruff is used for both formatting and linting, with a target version of Python 3.13 and a line length of 99. The configuration includes a wide array of rules, including I (isort), B (bugbear), TCH (type-checking), and PL (pylint).

Sources: pyproject.toml:57-111

Automated Packaging and CLI Checks

The CI process includes unit tests that verify the integrity of the project's packaging and CLI entry points. This ensures that the athena command-line tool is correctly mapped and that all necessary packages are included in the distribution wheels.

These tests prevent regressions in the deployment artifacts and ensure that internal tools recognize osu_server and athena_cli as first-party code.
Sources: tests/unit/athena_cli/test_packaging.py:44-83

Summary

The Quality Gates and CI system in Athena represent a foundational component of its "implementation cost is zero" philosophy. By automating the enforcement of complex architectural boundaries, type safety, and coding standards, the project allows for rapid refactoring and parallel agent-driven development while maintaining the integrity of a modular monolith. Developers are required to pass all gates—from linting and strict type checking to architectural contract validation—before code is considered ready for integration.

Sources: AGENTS.md:96-104, README.md:120-123