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