---
title: Project quality gate
description: Checklist for reviewing completed changes against requirements, architecture, code quality, security, and verification before commit.
---

# Project quality gate

Run this review after implementation and before every commit. Review the full worktree, including untracked files, not only `git diff` output. This checklist supports the project specifications and architecture documents; it does not replace them.

## Source of truth

- Use the relevant approved specification for required behavior and acceptance criteria.
- Use `ARCHITECTURE.md` and `AGENTS.md` for module boundaries, dependency direction, and repository workflow.
- Use generated OpenAPI and shared fixtures for exact API shapes.
- Do not claim cross-service or production behavior is verified unless the agreed fixture, integration test, or operational check was run.

## Architecture and dependency review

- Trace each changed capability end to end: presentation, application, domain, infrastructure, and bootstrap where applicable.
- Keep deterministic rules and calculations pure. Keep orchestration and transaction meaning in application use cases.
- Keep SQL, network access, environment access, clocks, and secure randomness at explicit boundaries. Pass volatile values through dependencies when they affect application behavior.
- Keep concrete adapters in the bootstrap composition root. Application code depends on focused ports; presentation maps transport and calls already-wired use cases. Do not introduce a DI container or service locator without evidence.
- Keep commits and rollbacks at the application use-case boundary; persistence adapters implement storage and transaction mechanisms without deciding use-case boundaries.
- Use classes when identity, state, lifecycle, or a framework contract needs one. Use functions for stateless transformations. Do not force an OOP or functional style where it adds no value.
- Use established patterns only to solve a real boundary or lifecycle problem. Avoid generic base classes, speculative factories, duplicate repositories, wrappers, and abstractions with no meaningful substitution or behavior.
- Architecture-boundary, dependency-direction, DI/composition-root, or transaction-ownership changes are designed and implemented by the main agent. Independent agents may review or test them.

## Requirements and consistency review

- Map each changed behavior to a requirement and acceptance check. Identify missing, partial, or newly invented behavior.
- Check tenant isolation, authentication, authorization, CSRF, audit, secret handling, and failure behavior at the boundaries they apply to.
- Check API routes against Pydantic models, generated OpenAPI, and shared fixtures. Regenerate artifacts through the approved generator; do not hand-edit generated output.
- Validate canonical JSON fixtures imported by Admin Web against the backend Pydantic model, especially when TypeScript JSON imports need a type assertion.
- Check configuration names across `Settings`, example environment files, Compose, CI, and runtime entrypoints.
- Check build and test commands against the package manifests and lockfiles.
- Check Admin Web against `ARCHITECTURE.md` and the existing design system. Prefer native HTML for simple forms and tables; use project components and interaction primitives where they add needed behavior.
- Check database model changes against Alembic migrations. Startup remains read-only and must not apply migrations. Run migration verification only against an isolated test database.

## Red flags to investigate

- Hard-coded migration revisions, secrets, service URLs, environment names, or changing operational values.
- Business rules or persistence decisions in HTTP routes; adapter construction outside bootstrap; `Depends` or framework types in domain/application.
- Global mutable state, hidden I/O, implicit time/randomness, or broad exception handling that hides failure categories.
- Persistence adapters that commit outside the use-case transaction boundary.
- Raw secrets in logs, list responses, browser-visible configuration, or cacheable responses. One-time key responses use `Cache-Control: no-store`; secret storage follows the approved specification.
- Generated files edited manually, a second schema source, tests pointed at development data, or tests that assert only implementation details rather than behavior.
- Web source imports that escape `apps/web` through repository-relative paths. Keep intentional shared-contract imports limited to canonical contracts/fixtures, and verify the Docker build stage copies every imported source asset at the path the bundler resolves.
- Large or multi-purpose modules, duplicated validation/mapping, unnecessary indirection, or local optimization that conflicts with end-to-end contracts.

A red flag is a prompt to verify the relevant requirement, not an automatic ban. Keep useful complexity when a concrete invariant, security boundary, or measured need requires it.

## Verification before commit

Run the checks relevant to the changed paths and report exact pass/fail status. Do not report a command as passed if it was skipped or blocked.

Backend:

```sh
uv run ruff check src tests
uv run ruff format --check src tests
uv run pyright
uv run lint-imports
make test
```

Web:

```sh
cd apps/web
bun run format:check
bun run check
bun run test
bun run build
```

Contracts and migrations:

```sh
make contract
uv run --no-sync alembic heads
```

Use the repository's isolated test database for database tests. Do not run destructive migration commands against development or production data.

Finally inspect `git status --short`, the tracked diff, and all untracked files; run `git diff --check`. Before committing, summarize findings, checks, remaining uncertainty, and intentionally deferred work. Fix correctness, security, contract, and architecture-boundary findings introduced by the change before commit. Report pre-existing coupling or refactor candidates separately; do not expand into a broad refactor without an explicit main-agent scope decision.