87 lines
6.2 KiB
Markdown
87 lines
6.2 KiB
Markdown
---
|
|
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.
|
|
- Treat `rewrite_architect.md` as design rationale, not a parallel contract. When it conflicts with an approved specification or current architecture, follow the more specific approved source and record the conflict.
|
|
- 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.
|