dotb_ai-platform/docs/project_quality.md

title, description

title	description
Project quality gate	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:

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

Web:

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

Contracts and migrations:

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.