DECISION_BOUNDARY_DOCUMENTATION.md

Decision Boundary Documentation

Architecture Overview

This system implements a Single Authoritative Decision Boundary architecture as required by governed AI practices.

---

The Decision Boundary: make_decision()

Location

File: app.py
Class: GovernedDecisionSystem
Function: make_decision()

Purpose

The make_decision() function is the ONLY place where a decision can be finalized in this system.

Architecture Lock

┌───────────────────────────────────────────────────────────┐
│                                                           │
│                    make_decision()                        │
│                                                           │
│              SINGLE DECISION BOUNDARY                     │
│                                                           │
└───────────────────────────────────────────────────────────┘
                           │
                           │
           ┌───────────┼───────────┐
           │               │               │
           │               │               │
      ┌────┴────┐   ┌────┴────┐   ┌────┴────┐
      │  Input   │   │  Rules  │   │  Human  │
      │  Data    │   │ Dataset │   │ Confirm │
      └─────────┘   └─────────┘   └─────────┘

All inputs, rules, model suggestions, and human confirmation MUST pass through this boundary.

---

Decision Flow

Step-by-Step Process

1. Input Reception

   • Claim data received
   • Decision domain specified (e.g., "motor_claims")
   • Decision type specified (e.g., "claim_severity_assessment")
   • Human confirmation status

2. Capability Verification (Step 3 of Workflow)

   capability = self._verify_capability(decision_domain, decision_type)
   

   • Checks if capability exists in AI_CAPABILITY_DICTIONARY.yaml
   • Returns error if capability not found

3. Governance Enforcement (Step 3 of Workflow)

   governance_check = self._enforce_governance(capability, human_confirmed)
   

   • Verifies explainable: true
   • Verifies auditable: true
   • Verifies human_override_allowed: true
   • Blocks execution if constraints violated

4. Dataset Boundary Retrieval (Step 2 of Workflow)

   boundaries = self._get_dataset_boundaries(decision_domain, decision_type, claim_data)
   

   • Loads decision rules from BDR-AI/insurance_decision_boundaries_v1 dataset
   • NO hardcoded thresholds
   • Returns rule_signals, model_signal, uncertainty_level

5. Toy Model Recommendation (Step 4 of Workflow)

   model_recommendation = self._toy_model_recommendation(claim_data, boundaries)
   

   • Rule-based, deterministic
   • No ML training
   • Generates non-binding recommendation
   • Includes uncertainty signal
   • NEVER overrides human authority

6. Human Confirmation Check (Step 5 of Workflow)

   if not human_confirmed:
       return {"status": "PENDING_HUMAN_CONFIRMATION", ...}
   

   • Blocks finalization without human confirmation
   • Returns pending status with recommendation
   • Prevents audit record creation

7. Decision Finalization (Only if human confirmed)

   final_decision = model_recommendation['suggested_outcome']
   

   • Human has confirmed
   • Decision is finalized
   • Audit trail created

8. Audit Trail Creation (Step 6 of Workflow)

   self._write_audit_log(decision_package)
   

   • Unique decision_id
   • Input snapshot
   • Dataset boundary used
   • Capability ID
   • Model suggestion
   • Human confirmation status
   • Timestamp
   • Persisted to governed_decision_audit.jsonl

---

Enforcement Rules

❌ PROHIBITED

• Decision logic outside make_decision()
• Hardcoded thresholds in code
• Automated decision execution without human confirmation
• ML model predictions overriding human authority
• Decisions without audit trail
• Bypassing capability registry checks

✅ REQUIRED

• All decisions through make_decision()
• Dataset-driven decision boundaries
• Human confirmation for finalization
• Complete audit trail
• Capability registry verification
• Governance flag enforcement
• Explainable recommendations

---

Code Example

Correct Usage

# Initialize system
decision_system = GovernedDecisionSystem()

# Prepare claim data
claim_data = {
    "claim_amount": 12000,
    "vehicle_age": 5,
    "accident_type": "Collision",
    "police_report": "Yes",
    "repair_estimate": 11000,
    "prior_claims": 1
}

# Call make_decision() - THE ONLY DECISION BOUNDARY
result = decision_system.make_decision(
    claim_data=claim_data,
    decision_domain="motor_claims",
    decision_type="claim_severity_assessment",
    human_confirmed=True  # Human has confirmed
)

Incorrect Usage (PROHIBITED)

# ❌ WRONG - Decision logic outside make_decision()
if claim_amount > 15000:  # Hardcoded threshold
    decision = "high_severity"

# ❌ WRONG - Bypassing human confirmation
result = model.predict(features)  # Direct ML prediction

# ❌ WRONG - No audit trail
return {"decision": "approved"}  # No logging

---

Verification Checklist

• Single make_decision() function exists
• All decision logic flows through this function
• No external decision logic
• Dataset-driven boundaries (no hardcoded thresholds)
• Capability registry verification
• Governance enforcement
• Human confirmation required
• Audit trail creation
• Explainable recommendations
• Toy model (no ML training)

---

Audit Trail Format

File: governed_decision_audit.jsonl

Each decision creates a JSON line with:

{
  "decision_id": "uuid",
  "status": "FINALIZED",
  "timestamp": "ISO-8601",
  "input_snapshot": {...},
  "dataset_boundary_used": "case_id",
  "capability_id": "CAP-001",
  "model_recommendation": {...},
  "human_confirmed": true,
  "final_decision_owner": "HUMAN",
  "final_decision": "...",
  "governance": {...}
}

---

Relationship to Workflow Requirements

STEP 1: Single Decision Boundary ✅

• make_decision() is the single authoritative function
• No decision logic outside this function
• All inputs/rules/confirmations pass through it

STEP 2: Dataset Integration ✅

• _get_dataset_boundaries() loads from HuggingFace dataset
• No hardcoded thresholds
• Dataset drives decision logic

STEP 3: Capability Registry ✅

• _verify_capability() checks registry
• _enforce_governance() enforces flags
• Blocks execution if constraints violated

STEP 4: Toy Model ✅

• _toy_model_recommendation() is rule-based
• Deterministic, no training
• Non-binding recommendations only

STEP 5: Human-in-the-Loop ✅

• Explicit confirmation check
• Blocks finalization without confirmation
• Human has final authority

STEP 6: Audit Trail ✅

• _write_audit_log() persists complete record
• All required fields included
• Structured JSON format

---

Version History

Version 2.0 - Governance-First Architecture

• Implemented single decision boundary
• Removed hardcoded thresholds
• Dataset-driven rules
• Capability registry enforcement
• Human-in-the-loop required
• Complete audit trail

Version 1.0 - Legacy (app_old.py)

• ML model-based predictions
• Hardcoded thresholds (15000, 10, 2)
• No capability registry
• Weak human confirmation
• Incomplete audit trail

---

Document Version: 1.0
Last Updated: 2026-01-03
Author: BDR Agent Factory
Status: ACTIVE