| Owner | Jonny Allum (Engineering Lead) |
| Version | 1.0 · Effective 13/07/2026 · Review annually (July) |
| Applies to | All code in biz-os and related product repos |
1. The rule of gates
No change reaches production without passing all four gates: pnpm turbo run typecheck test build green across the graph, plus audit.mts PASS (repo invariants: total signal coverage, doc counts, registry consistency). For a sole operator these automated gates are the peer review — they are never skipped, weakened or worked around to ship faster.
2. Change classes
| Class | Examples | Requirements |
|---|---|---|
| Routine | Module work following the house template, copy, UI polish | Four gates; commit + push after every meaningful change |
| Schema | Any migration | SOP-04: numbered, idempotent, RLS + touch triggers, counter updated in BUILD_PLAN.md |
| Sensitive | Auth, RLS, billing, public write paths, AI action registry, cron | Four gates plus a cooling-off self-review (re-read the diff after a break) and a production smoke test after deploy (SOP-03) |
| Emergency | Hotfix during an incident | Fix forward with the smallest diff; gates still run; retrospective note in the incident record |
3. Standing engineering rules (bound here as policy)
These live in BUILD_PLAN.md/CLAUDE.md and have governance force:
- The per-module template is followed strictly: migration → db helpers → pure engine → pluggable store → board → registration → signals/digest/ import/AI wiring → round-trip test → gates. New module ⇒ its signal provider ships in the same PR (audit enforces 100% coverage).
- Pure engines have no Node builtins and no clock reads — deterministic, testable, client-safe.
- Public write paths trust nothing: server-side price resolution, caps, rate limits, possession-based tokens; GETs never mutate.
- Empty/loading/error states are acceptance criteria, not polish.
- Secrets never enter the repo; remotes stay clean (POL-01, SOP-09).
4. Dependencies and supply chain
- Dependencies are added deliberately: prefer the existing stack (Next.js, shadcn/Tailwind, Supabase, Stripe SDKs) over new packages.
- Lockfile (
pnpm-lock.yaml) is committed; unexpected lockfile churn in a diff is investigated before merge. - GitHub Dependabot/security alerts on the repo are triaged weekly: critical/high advisories on production dependencies are patched within 7 days, others batched monthly.
5. Source control
- Work lands as focused commits with descriptive messages; files staged by name.
BUILD_PLAN.md(the kanban) is updated as commits land so the plan never lies about state. - The default branch is deployable; long-lived divergence between the VM and
mainis treated as a defect (SOP-03 keeps deploys fast-forward only).