0006. Engineering conventions
- Status: Accepted
- Date: 2026-11-07
Context
Section titled “Context”The project is developed largely by coding agents working in parallel, and the core logic (sending, idempotency, tenant isolation) fails in ways that are expensive to discover in production. Conventions need to keep changes small, reviewable, reversible, and verified by tests rather than by reading.
Decision
Section titled “Decision”- One logical change per pull request, squash-merged.
- Conventional Commits for commit messages and pull request titles.
- Every commit builds and passes tests.
- Trunk-based development with short-lived branches from
main. - SemVer release tags.
- gitleaks in pre-commit and CI, added when code exists.
- Each parallel task gets its own worktree, branch, and pull request.
- Test first: a behaviour change starts with a failing test. Every invariant in ADR 0007 has a test that would catch its violation.
- The first code pull requests build the first validation milestone in docs/architecture.md as a walking skeleton, before other features. Its four checks (replay does not send twice, unsubscribing during a delay prevents the send, cross-project access is denied, duplicate provider webhooks do not inflate metrics) are executable tests.
Consequences
Section titled “Consequences”- With squash merge, the pull request title becomes the commit subject on
main, so it must be a valid Conventional Commit.