Engineering Standards¶
These documents are binding. Every contributor, human or AI agent, follows them. A change that breaks a rule is not merged.
Each rule has an ID (e.g. TST-3) so reviews and commit messages can cite it. Each rule also names
what enforces it. A rule that only a human enforces is marked review and is listed in the
pull-request checklist.
| # | Document | Covers |
|---|---|---|
| 01 | Repository layout | Where things live |
| 02 | Commits, branches & versioning | Conventional Commits, SemVer, tags, releases |
| 03 | Code quality | Python conventions, typing, linting, DI |
| 04 | Architecture rules | Layers, ports & adapters, plugins, import contracts |
| 05 | Testing | Test types, 100 % coverage, mutation testing |
| 06 | Documentation | Keeping docs from going stale, docstrings, ADRs |
| 07 | Security | Threats specific to this app and their mitigations |
| 08 | Git hooks | What runs at commit, commit-msg and pre-push |
| 09 | CI/CD | Workflows, required checks, automatic releases |
| 10 | Definition of Done | The checklist every change must satisfy |
Principles¶
- Machines enforce, humans judge. Anything a tool can check is checked by a tool, locally and in CI.
- Local hooks are a convenience; CI is the authority. Hooks can be skipped with
--no-verify. CI cannot. Every hook is repeated in CI. - No silent exceptions. Exclusions (coverage, lint, typing) are declared in configuration, with a reason, where review can see them, and never inline.
- Changing a standard is a change like any other. It goes through a PR with an ADR in
planning/adr/, and the doc-impact rule (DOC-6) applies.
Status¶
Agreed on 2026-10-24. The tooling that enforces these rules is delivered in milestone M0
(planning/SPEC.md §10). Until M0 is merged, the rules apply through review.