docs

docs/architecture/shared/ENUMS.md

@@ -0,0 +1,84 @@
+# Enums (Shared Contract)
+
+This document defines how enums are modeled, placed, and used across the system.
+
+Enums are frequently a source of architectural leakage. This contract removes ambiguity.
+
+## 1) Core principle (non-negotiable)
+
+Enums represent knowledge.
+
+Knowledge must live where it is true.
+
+## 2) Enum categories (strict)
+
+There are four and only four valid enum categories:
+
+1. Domain enums
+2. Application workflow enums
+3. Transport enums (HTTP contracts)
+4. UI enums (website-only)
+
+## 3) Domain enums
+
+Definition:
+
+- business meaning
+- affects rules or invariants
+
+Placement:
+
+- `core/**`
+
+Rule:
+
+- domain enums MUST NOT cross a delivery boundary
+
+## 4) Application workflow enums
+
+Definition:
+
+- internal workflow coordination
+- not business truth
+
+Placement:
+
+- `core/**`
+
+Rule:
+
+- workflow enums MUST remain internal
+
+## 5) Transport enums
+
+Definition:
+
+- constrain HTTP contracts
+
+Placement:
+
+- `apps/api/**` and `apps/website/**` (as transport representations)
+
+Rules:
+
+- transport enums are copies, not reexports of domain enums
+- transport enums MUST NOT be used inside Core
+
+## 6) UI enums
+
+Definition:
+
+- website presentation or interaction state
+
+Placement:
+
+- `apps/website/**`
+
+Rule:
+
+- UI enums MUST NOT leak into API or Core
+
+## 7) Final rule
+
+If an enum crosses a boundary, it is in the wrong place.
+