docs/pull-requests.md

Pull Request Guidelines

PR Requirements

• Ensure npm run lint passes (Biome, TypeScript, knip, jscpd, architectural linter, documentation validator)
• Keep PRs focused on a single feature or fix
• Include clear descriptions and screenshots for UI changes
• Write descriptive commit messages using conventional commits
• Run tests with npm run test and ensure coverage is maintained
• Update documentation when making API or feature changes

Review Process

• Automated checks run on all PRs (Biome formatting/linting, TypeScript type checking, knip dead code detection, jscpd copy-paste detection, dpdm circular dependency detection, architectural linter, documentation validation)
• Human review optional but encouraged for complex changes
• Agent-to-agent review is primary mechanism
• Short-lived PRs preferred
• Test flakes addressed with follow-up runs rather than blocking
• Coverage reports available for AI analysis in coverage/ directory

Quality Gates

Before any change, run this command in the development container:

docker compose exec development-server npm run lint

This comprehensive check includes:

• Biome: Code formatting and linting
• TypeScript: Type checking with strict mode
• knip: Dead code detection
• jscpd: Copy-paste detection
• dpdm: Circular dependency detection
• Custom architectural linter: Project-specific rules
• Documentation validator: Ensures docs stay current

Merge Philosophy

In high-throughput agent environments:

• Minimize blocking merge gates
• Keep PRs short-lived
• Corrections are cheap, waiting is expensive
• Address test flakes with follow-up runs rather than blocking progress indefinitely
• Automated quality gates ensure consistency without manual bottlenecks

Commit Message Format

Use conventional commits:

• feat: for new features
• fix: for bug fixes
• docs: for documentation changes
• refactor: for code refactoring
• test: for test changes
• chore: for maintenance tasks

Related Topics

• Development Commands: docs/development-commands.md - Available npm commands
• Coding Conventions: docs/coding-conventions.md - Code style guidelines
• Quick Start: docs/quick-start.md - Setting up the project