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)
   ```python
   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)
   ```python
   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)
   ```python
   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)
   ```python
   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)
   ```python
   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)
   ```python
   final_decision = model_recommendation['suggested_outcome']
   ```
   - Human has confirmed
   - Decision is finalized
   - Audit trail created

8. **Audit Trail Creation** (Step 6 of Workflow)
   ```python
   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

```python
# 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)

```python
# ❌ 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

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

---

## Audit Trail Format

### File: `governed_decision_audit.jsonl`

Each decision creates a JSON line with:

```json
{
  "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