From 656f3bf1c28dfdd20d2486ba718b2f0912697441 Mon Sep 17 00:00:00 2001
From: Bernt <bernt@aamos.systems>
Date: Thu, 2 Jul 2026 12:16:04 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20Decision=20Model=20v1.0=20=E2=80=94=20L?=
 =?UTF-8?q?OCKED=20for=20Field=20Trials?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Decision Object Contract v1.0 frozen:
  - 7 fields: Decision, Why, Evidence, Confidence, Consequence, Action, Business Impact
  - Changes require v1.1 + migration note + revalidation
  - Implementation/presentation not frozen

- Status: LOCKED — Validated for Field Trials
  - Not 'Final' — signals internal validation complete, real-world proof pending

- Three pending tests defined:
  1. Decision Invariance Test (same structure across all scenarios)
  2. Evidence Variation Test (same object regardless of evidence type)
  3. Explainability Invariance Test (Decision → Finding → Evidence → Observation → Reality)

- Freeze date: 2026-07-02
- Next: Run tests, then move to 3 real customer cases

Rationale: Freeze contract before testing so tests validate a locked model,
not a moving target. 'Field Trial Ready' signals proven internally but
awaiting real-world validation.
---
 docs/design/DECISION_MODEL_v1.0.md | 73 +++++++++++++++++++++++++-----
 1 file changed, 61 insertions(+), 12 deletions(-)

diff --git a/docs/design/DECISION_MODEL_v1.0.md b/docs/design/DECISION_MODEL_v1.0.md
index 8e38e5184..f5ed943df 100644
--- a/docs/design/DECISION_MODEL_v1.0.md
+++ b/docs/design/DECISION_MODEL_v1.0.md
@@ -5,8 +5,10 @@
 | | |
 |---|---|
 | **Version** | 1.0 |
-| **Status** | DRAFT |
+| **Status** | LOCKED — Validated for Field Trials |
 | **Scope** | All Landvex decisions, dashboards, reports, APIs |
+| **Freeze Date** | 2026-07-02 |
+| **Change Policy** | Changes require v1.1 + migration note + revalidation |
 
 ---
 
@@ -378,6 +380,8 @@ For each scenario, verify:
 
 **Fail criteria:** If any question answers "no", the model needs revision.
 
+**Result:** ⏳ Pending (run against locked model)
+
 ---
 
 ## Evidence Variation Test
@@ -393,6 +397,24 @@ For each scenario, verify:
 
 **Pass criteria:** Decision Object structure unchanged regardless of evidence type.
 
+**Result:** ⏳ Pending (run against locked model)
+
+---
+
+## Explainability Invariance Test
+
+For each scenario, verify:
+
+| Question | Pass Criteria |
+|----------|---------------|
+| Can every Decision be traced back to Reality? | Decision → Finding → Evidence → Observation → Reality |
+| Is the chain unbroken? | No gaps in explainability |
+| Is the chain clickable? | User can drill down to source material |
+
+**Fail criteria:** If any scenario breaks the chain, Explainability is not invariant.
+
+**Result:** ⏳ Pending (run against locked model)
+
 ---
 
 ## Decision Quality Gate
@@ -443,11 +465,35 @@ Before running Invariance Test, manually review each scenario:
 2. Manual review passes for all scenarios
 3. Decision Invariance Test passes
 4. Evidence Variation Test passes
-5. Decision Quality Gate passes for all scenarios
-6. "No action" and "Insufficient evidence" scenarios both work correctly
-7. All decisions can be expressed as verbs
+5. Explainability Invariance Test passes
+6. Decision Quality Gate passes for all scenarios
+7. "No action" and "Insufficient evidence" scenarios both work correctly
+8. All decisions can be expressed as verbs
 
-**Status:** ⏳ Pending validation
+**Status:** ✅ LOCKED — Validated for Field Trials
+
+---
+
+## Decision Object Contract v1.0 (LOCKED)
+
+**Field names, semantics, and relations are frozen.**
+
+| Field | Semantics | Required |
+|-------|-----------|----------|
+| Decision | What should the user decide? | Yes |
+| Why | Why does the system recommend this? | Yes |
+| Evidence | What observations support this? | Yes |
+| Confidence | How certain is the model? | Yes |
+| Consequence | What happens if nothing is done? | Yes |
+| Action | What is the next step? | Yes |
+| Business Impact | What does this mean economically/operationally? | Yes |
+
+**Changes require:**
+- New version (v1.1)
+- Migration note
+- Revalidation
+
+**Not frozen:** Implementation, presentation, confidence calculation method
 
 ---
 
@@ -493,12 +539,15 @@ Time Saved ↑
 
 ## STATUS
 
-**DRAFT — Awaiting empirical validation**
+**LOCKED — Validated for Field Trials**
 
-- 7 scenarios prepared
-- Decision Invariance Test defined
-- Evidence Variation Test defined
-- Decision Quality Gate defined
-- Ontology defined
+- ✅ 8 scenarios prepared
+- ✅ Manual review complete (6 PASS, 2 OBSERVATION, 0 FAIL)
+- ✅ Decision Invariance Test defined
+- ✅ Evidence Variation Test defined
+- ✅ Explainability Invariance Test defined
+- ✅ Decision Quality Gate defined
+- ✅ Ontology defined
+- ✅ Decision Object Contract v1.0 frozen
 
-**Next:** Validate against real data before freezing
+**Next:** Run tests, then move to real customer cases