Module Development Lifecycle

Trigger: any new BizOS module or substantial module change. Owner: Jonny Allum. Policy anchors: POL-05, POL-06.

The canonical detail lives in BUILD_PLAN.md (house template) and CLAUDE.md; this SOP is the ordered checklist with the governance hooks.

The strict order

1. Brief — for a new module, write the research + build prompt under docs/modules/<ID>_<NAME>.md (the O11/O12/F09 pattern): the domain, the UK regulatory reality, the tables, the engine maths, the AI surface.
2. Migration — next number from BUILD_PLAN.md counter; idempotent; RLS + touch triggers on every table (SOP-04).
3. DB helpers — typed row shapes flow from packages/db/src/types.ts.
4. Pure engine — src/lib/<name>/engine.ts: no Node builtins, no clock reads; all derivations computed at read time.
5. Pluggable store — local.ts + supabase.ts behind one getXStore() contract; multi-write orchestrations live in the store so both adapters share one workflow.
6. Board — under src/modules/<name>/; empty/loading/error states are acceptance criteria.
7. Registration — @bizos/config entry (id, category, deps, vertical lock, owned tables, aiContext) + src/modules/registry.ts mapping; regenerate the registry seed (module-registry-sync).
8. AI wiring — same PR, no exceptions — signal provider in lib/ai/signals.ts reusing the engine maths (compact: counts, renewal bands, byStatus, one worst item; degrade to null); digest/import wiring; any executable actions into action-registry.ts with confirm step (SOP-13).
9. Round-trip test — tsx round-trip proving the workflow and the engine arithmetic against known-good numbers.
10. Gates — pnpm turbo run typecheck test build green + cd apps/shell && pnpm exec tsx audit.mts PASS.
11. Docs + kanban — tick BUILD_PLAN.md, keep README/docs counts in sync (audit checks them). Commit + push.

Scaffolding

tools/module-generator (bizos-new-module) scaffolds a single-table CRUD module and prints the 3 shared-file wiring edits — use it, then follow the order above for everything it can't know (engine, signals, tests).

Definition of done

A module is done when a stranger can use it with no data, on a slow connection, with an error — and when JonnyAI can answer questions about it from live signals that match the board's own numbers.