# Module maturity model

## Purpose

Provide a **shared vocabulary** for how complete a domain is—from idea to scalable production—so roadmaps, pilots, and sales claims stay aligned. **Higher maturity is not “more features”**; it is **stronger integrity, observability, and operational fit** at scale.

---

## Maturity levels

### 1. Conceptual

- **Definition:** Problem space and boundaries agreed; no durable spec or code contract.
- **Signals:** whiteboard, backlog epics only.
- **Risk:** marketing or scoping drift; **do not** bind SLAs.

### 2. Documented

- **Definition:** Written principles, state machines, data ownership, and failure modes (`docs/`).
- **Signals:** integrity docs, API sketches, UX guidelines.
- **Risk:** doc–code skew; requires explicit **verification** step before pilot claims.

### 3. Operational

- **Definition:** Code exists in module structure; **happy path** usable by internal operators with known limitations.
- **Signals:** services/repositories, routes, basic UI; logs for main commands.
- **Risk:** edge cases, weak observability, manual workarounds.

### 4. Pilot-ready

- **Definition:** **Constrained** production-like use allowed: seeded flows, checklists, rollback posture, support playbook references.
- **Signals:** `docs/pilot/`, `docs/demo/` alignment; operator validation artifacts; failure messages with stable codes where critical.
- **Risk:** scale and multi-tenant corner cases; document **non-goals** for pilot.

### 5. Production-ready

- **Definition:** Integrity guarantees enforced in code for scoped workflows; **security** (policies, validation); **auditability**; **idempotency** on money/stock paths; monitoring hooks.
- **Signals:** reconciliation story; upgrade/migration notes; on-call runbooks for domain.
- **Risk:** regression debt; requires **continuous** test and doc maintenance.

### 6. Scalable

- **Definition:** Production-ready **plus** proven behavior under **tenant count, data volume, and concurrency** targets; cost-aware queries; async boundaries where appropriate; clear SLOs.
- **Signals:** load test results, query budgets, queue/backpressure design, sharding or read-replica story if applicable.
- **Risk:** premature optimization—only assert **scalable** with evidence.

---

## Mapping maturity to capability tags

| This model | Typical matrix tags |
|------------|---------------------|
| Conceptual | — |
| Documented | **D** |
| Operational | **I** (partial) |
| Pilot-ready | **I + P** |
| Production-ready | **I** (full scope claim) + tests + runbooks |
| Scalable | **I** + performance evidence |

---

## Domain-specific nuance

- **Inventory / sales fulfillment** — maturity is driven by **movement + reservation invariants**, not screen count.
- **Accounting** — **production-ready** requires posting idempotency, period controls, and reconciliation alignment (`docs/accounting/`).
- **Manufacturing** — **documented** foundation today; **operational** begins when WO/issue/receipt movements ship with costing hooks.

---

## Related documentation

- `docs/platform/erp-capability-matrix.md`
- `docs/pilot/go-no-go-checklist.md`

---

## Self-check (Part 2)

- Six maturity levels from conceptual through scalable are defined.
- Signals and risks per level are defined.
- Mapping to capability matrix and key domains is stated.