docs: PR-001 Domain Model v1.2 — Three Rules + Experience Intelligence + Capability Tags

- Added Three Rules to README: 1. Domain knows nothing about AI (no AIObservation, YOLODetection, etc.) 2. Everything is an Artifact (common contract for all produced objects) 3. All decisions are reproducible (answer: which observations, evidence, model, version, rules, reviewer, when, approved version) - Renamed Human Intelligence → Experience Intelligence - Broader scope: citizen surveys, customer satisfaction, field technician feedback, contractor experience, service desk data - More future-proof than 'Human Intelligence' - Added Capability Tags for developers: - Observation: [Detection, Vision, GPS, Image] - Decision: [Decision, Recommendation, Business] - Artifact: [Storage, Versioning, Lineage] - Makes dependencies clear as platform grows - Updated Domain Invariants: - DecisionCase: must have at least one Review before Approved - Review: must belong to exactly one Decision, must have reviewer - Added Merge Criteria: - All stakeholders (developer, AI engineer, product owner, domain expert) can read model and understand same terms - No AI objects, all Artifacts, reproducible decisions Rationale: Lock domain language before implementation. Shared vocabulary for code, docs, APIs, tests, and product discussions.
2026-07-02 14:09:45 +00:00
parent b4391f9600
commit 118180e7ff
1 changed files with 110 additions and 10 deletions
@@ -14,6 +14,68 @@

 **This package describes the LandveX domain model. It contains no dependencies to database, HTTP, cloud storage, or AI frameworks. It defines only the language, objects, and rules that the rest of the platform builds upon.**

+## Three Rules
+
+### Rule 1: Domain knows nothing about AI
+
+**No AI-specific objects in domain:**
+- ❌ `AIObservation`
+- ❌ `YOLODetection`
+- ❌ `GeminiResult`
+- ❌ `ClaudeAnalysis`
+
+**Domain only knows:**
+- ✅ `Observation`
+- ✅ `Evidence`
+- ✅ `Finding`
+- ✅ `Decision`
+- ✅ `Review`
+- ✅ `Outcome`
+
+If we switch from YOLO to a custom model in five years, the domain does not change.
+
+### Rule 2: Everything is an Artifact
+
+`Artifact` is a common contract for everything produced:
+
+```
+Artifact
+├── Image
+├── Video
+├── Dataset
+├── Annotation
+├── Model
+├── Evaluation
+├── DecisionCase
+├── Report
+└── ExperienceInsight
+```
+
+All artifacts share:
+- `id`
+- `version`
+- `hash`
+- `lineage`
+- `createdAt`
+- `createdBy`
+- `storageUri`
+
+This makes the entire platform consistent.
+
+### Rule 3: All decisions are reproducible
+
+Every Decision Case must answer:
+- Which observations were used?
+- Which evidence was used?
+- Which model?
+- Which model version?
+- Which rules?
+- Who reviewed?
+- When?
+- Which version was approved?
+
+If any question cannot be answered, the Decision Case is incomplete.
+
 ---

 ## Package Structure
@@ -286,7 +348,7 @@ interface DecisionApproved {
 - Must have at least one Observation
 - Must have at least one Evidence
 - Must have exactly one Decision
- Cannot be Approved without Review
+- Must have at least one Review before Approved
 - Immutable once created — revisions create new versions

 ### Artifact
@@ -296,8 +358,30 @@ interface DecisionApproved {
 - Version is incremented on each change
 - Parent reference creates lineage chain

+### Review
+
+- Must belong to exactly one Decision
+- Must have a reviewer
+- Must have a status (Assigned, In Review, Approved, Rejected, Needs More Evidence)
+- Approved requires at least one completed review
+
 ---

+## Capability Tags
+
+For developers — not users. Makes dependencies clear as platform grows.
+
+```
+Observation
+├── Capabilities: [Detection, Vision, GPS, Image]
+
+Decision
+├── Capabilities: [Decision, Recommendation, Business]
+
+Artifact
+├── Capabilities: [Storage, Versioning, Lineage]
+```
+
 ## TypeScript Interfaces

 ```typescript
@@ -331,7 +415,7 @@ interface DecisionCase {
  evidenceIds: string[];
  findingId: string;
  decisionId: DecisionId;
-  reviewId: string;
+  reviewIds: string[];
  status: 'pending' | 'under_review' | 'approved' | 'rejected';
  version: number;
  createdAt: Date;
@@ -525,11 +609,11 @@ The concepts `Session`, `Mission`, `Artifact`, `Observation`, `Evidence`, `Findi

 ---

-## Future Module: Human Intelligence (Not in Epic-001)
+## Future Module: Experience Intelligence (Not in Epic-001)

 **Positioning:** External Intelligence Module, not part of core domain.

-**Why separate:** Customer satisfaction data is not an observation from reality like a road crack. It is **context** that can influence priorities and decisions.
+**Why separate:** Stakeholder feedback is not an observation from reality like a road crack. It is **context** that can influence priorities and decisions.

 **Architecture:**
 ```
@@ -541,21 +625,25 @@ Reality Intelligence
 ├── Operational Intelligence     ← Future
 │   SLA, Tickets, Costs, Times
 │
-├── Human Intelligence           ← Future module
-│   Customer satisfaction
+├── Experience Intelligence      ← Future module
 │   Citizen surveys
+│   Customer satisfaction
+│   Field technician feedback
+│   Contractor experience
+│   Service desk data
 │   NPS, Complaints, Feedback
 │
 └── External Intelligence        ← Future
 │   Weather, Traffic, Demographics
 ```

-**Human Insight Artifact:**
+**Experience Insight Artifact:**
 ```
-Human Insight
+Experience Insight
 ├── Source: "Kommunenkät 2026"
 ├── Geography: [Stockholm, Nacka]
 ├── Period: "Q2 2026"
+├── Stakeholders: [Citizens, Field Technicians, Contractors]
 ├── Metrics:
 │   ├── CSAT: 4.2
 │   ├── NPS: 62
@@ -565,11 +653,11 @@ Human Insight

 **Usage:** Linked to Area or Decision Case, but never mixed with raw field observations.

-**Decision Case with Human Intelligence:**
+**Decision Case with Experience Intelligence:**
 ```
 Observation: "Crack on main street"
 Evidence: [Image, Video, History, GIS]
-Human Intelligence: "Many complaints last 30 days, low satisfaction index"
+Experience Intelligence: "Many complaints last 30 days, low satisfaction index"
 Decision: "Prioritize repair within 14 days"
 Business Impact: "Reduced risk, lower future cost, improved citizen satisfaction"
 ```
@@ -601,3 +689,15 @@ Freedom to change technology without touching core model.
 ## Status

 **READY FOR IMPLEMENTATION**
+
+**Merge Criteria:**
+- [ ] Developer can read model and understand domain language
+- [ ] AI engineer can read model and understand domain language
+- [ ] Product owner can read model and understand domain language
+- [ ] Domain expert can read model and understand domain language
+- [ ] All use same terms for `Observation`, `Evidence`, `Decision`, `Outcome`
+- [ ] No AI-specific objects in domain
+- [ ] All objects are Artifacts
+- [ ] All decisions are reproducible
+- [ ] Domain invariants documented
+- [ ] Capability tags defined