docs: initialize engineering starter kit

docs/CONVENTIONS.md

@@ -0,0 +1,210 @@
+# Conventions
+
+This document defines project engineering standards. It should remain practical,
+specific, and enforceable.
+
+For project facts, see [PROJECT.md](PROJECT.md).
+For architecture boundaries, see [ARCHITECTURE.md](ARCHITECTURE.md).
+For task quality gates, see [CHECKLISTS.md](CHECKLISTS.md).
+
+## Naming
+
+Use names that expose intent and domain meaning.
+
+- Prefer domain terms over technical shorthand.
+- Avoid abbreviations unless they are widely understood in the project.
+- Name booleans as predicates, such as `isEnabled`, `hasPermission`, or
+  `canRetry`.
+- Name commands by action and object, such as `CreateInvoice` or
+  `syncCustomer`.
+- Name events in past tense when they represent something that happened.
+
+Add language-specific naming rules here:
+
+- `{{LANGUAGE_NAMING_RULE}}`
+
+## File Organization
+
+Files should have one clear responsibility.
+
+- Keep files small enough to review comfortably.
+- Co-locate tests with the tested module when that matches the stack convention.
+- Separate generated files from hand-written source.
+- Avoid catch-all utility files that collect unrelated behavior.
+
+Project-specific rules:
+
+- `{{FILE_ORGANIZATION_RULE}}`
+
+## Folder Organization
+
+Folders should communicate ownership and architecture boundaries.
+
+- Organize by feature or module when domain ownership matters.
+- Organize by technical layer only when it improves clarity for the project.
+- Keep public interfaces easy to find.
+- Keep infrastructure details out of domain folders unless deliberately chosen.
+
+Project-specific folder map:
+
+| Folder | Rule |
+| --- | --- |
+| `{{FOLDER}}` | `{{FOLDER_RULE}}` |
+
+## Dependency Injection
+
+Use dependency injection to make boundaries explicit and tests practical.
+
+- Inject external resources, clocks, random generators, HTTP clients, file
+  systems, queues, and database access.
+- Avoid service locators unless the framework requires them.
+- Keep object lifetimes explicit.
+- Do not inject dependencies that are pure values or local implementation
+  details.
+
+Project-specific DI rules:
+
+- `{{DEPENDENCY_INJECTION_RULE}}`
+
+## Logging
+
+Logging should support operations and debugging without leaking sensitive data.
+
+- Use structured logs when the platform supports them.
+- Include correlation or request identifiers.
+- Log decisions and external failures at meaningful boundaries.
+- Do not log secrets, access tokens, passwords, private keys, or full payment
+  data.
+- Avoid noisy logs inside tight loops or high-volume paths.
+
+Project-specific logging rules:
+
+- `{{LOGGING_RULE}}`
+
+## Validation
+
+Validation should happen at the correct boundary.
+
+- Validate transport shape at the interface boundary.
+- Validate business invariants in the domain or application layer.
+- Validate persistence constraints before relying on database failures for
+  expected user errors.
+- Return actionable validation feedback where appropriate.
+
+Project-specific validation rules:
+
+- `{{VALIDATION_RULE}}`
+
+## Error Handling
+
+Errors should be explicit, observable, and safe.
+
+- Use typed or structured errors where the language supports them.
+- Do not swallow exceptions without a recovery path.
+- Map internal errors to stable user-facing or client-facing responses.
+- Preserve diagnostic context for logs.
+- Avoid exposing stack traces or implementation details to users.
+
+Project-specific error rules:
+
+- `{{ERROR_HANDLING_RULE}}`
+
+## DTO Rules
+
+DTOs represent boundary contracts.
+
+- Keep DTOs separate from domain models when they change for different reasons.
+- Do not put business rules in DTOs.
+- Version public contracts deliberately.
+- Validate DTO shape before mapping to domain commands or queries.
+- Avoid leaking persistence models through public APIs.
+
+Project-specific DTO rules:
+
+- `{{DTO_RULE}}`
+
+## Repository Rules
+
+Repositories, gateways, or data access abstractions should express persistence
+intent without hiding important consistency behavior.
+
+- Keep query methods specific enough to reveal purpose.
+- Avoid generic repositories when they obscure domain behavior.
+- Document transaction boundaries.
+- Make idempotency explicit for write operations where retries are possible.
+
+Project-specific repository rules:
+
+- `{{REPOSITORY_RULE}}`
+
+## Service Rules
+
+Services should coordinate use cases, not become unbounded containers.
+
+- Prefer cohesive application services around use cases.
+- Keep domain rules in domain objects or domain services.
+- Keep infrastructure calls behind clear interfaces.
+- Avoid services named only after technical actions such as `Manager`,
+  `Helper`, or `Processor` unless the meaning is precise in context.
+
+Project-specific service rules:
+
+- `{{SERVICE_RULE}}`
+
+## Testing
+
+Tests should match risk and behavior.
+
+- Unit test domain logic and pure transformations.
+- Integration test database, queue, file, network, and framework boundaries.
+- End-to-end test critical user journeys.
+- Regression test bugs before or with the fix.
+- Keep tests deterministic and independent where practical.
+
+Project-specific testing rules:
+
+- `{{TESTING_RULE}}`
+
+## Git Workflow
+
+Use [branching.md](branching.md) for branch strategy.
+
+Default expectations:
+
+- Keep commits focused and reviewable.
+- Write commit messages that describe the reason and outcome.
+- Rebase or merge according to the project branch policy.
+- Do not mix unrelated refactors with behavior changes.
+
+## Pull Requests
+
+Pull requests should explain what changed, why it changed, and how it was
+validated.
+
+Recommended PR sections:
+
+- Summary.
+- Scope.
+- Validation.
+- Risks.
+- Screenshots or recordings for UI changes.
+- Migration or deployment notes when relevant.
+
+Use [CHECKLISTS.md](CHECKLISTS.md) before requesting review.
+
+## Code Reviews
+
+Reviews should prioritize correctness and maintainability.
+
+Review for:
+
+- Behavior and edge cases.
+- Security and authorization.
+- Data integrity.
+- Architecture boundaries.
+- Test quality.
+- Operational impact.
+- Readability.
+
+Style comments should reference documented conventions or automated tooling
+where possible.