Skip to content

0006. Engineering conventions

  • Status: Accepted
  • Date: 2026-11-07

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.

  • 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.
  • With squash merge, the pull request title becomes the commit subject on main, so it must be a valid Conventional Commit.