Deploy Medical Intent Escalation API

.gitattributes

@@ -33,6 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
-*.pdf filter=lfs diff=lfs merge=lfs -text
+*.onnx.data filter=lfs diff=lfs merge=lfs -text
 *.docx filter=lfs diff=lfs merge=lfs -text
 *.xlsx filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.py[cod]
+*.pyc

Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# System dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install only serving dependencies (no torch needed — ONNX Runtime only)
+COPY requirements-serve.txt .
+RUN pip install --no-cache-dir -r requirements-serve.txt
+
+# Copy application code
+COPY service/ service/
+COPY decision/ decision/
+COPY streaming_intent/ streaming_intent/
+COPY config/ config/
+COPY list/ list/
+COPY artifacts/onnx_int8/ artifacts/onnx_int8/
+COPY artifacts/config/ artifacts/config/
+
+# HF Spaces expects port 7860
+ENV PORT=7860
+ENV PYTHONUNBUFFERED=1
+ENV REQUIRE_AUTH=false
+ENV DISABLE_DOCS=false
+
+EXPOSE 7860
+
+CMD ["uvicorn", "service.app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,11 +1,32 @@
 ---
-title: DCE
-emoji: 🏆
-colorFrom: indigo
+title: Medical Intent Escalation
+emoji: 🏥
+colorFrom: blue
 colorTo: red
 sdk: docker
 pinned: false
-short_description: Medical Intent Escalation
+license: mit
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Medical Intent Escalation
+
+Real-time clinical intent classification and safety escalation API powered by DriveHealthBERT.
+
+## Endpoints
+
+- **POST /predict** — Classify medical intent from text
+- **POST /predict/clinical** — Full clinical risk assessment (R0–R3)
+- **POST /conversation/start** — Start a clinical conversation session
+- **POST /conversation/turn** — Process a patient turn
+- **POST /stream/chunk** — Process streaming STT chunks with SPRT decisions
+- **GET /health** — Health check
+- **GET /docs** — Interactive Swagger UI
+
+## Quick Test
+
+```bash
+curl -X POST "https://YOUR-SPACE.hf.space/predict" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "I have been having chest pain"}'
+```

artifacts/config/decision_policy.json

@@ -0,0 +1,71 @@
+{
+  "version": "2.0.0",
+  "created_at": "2026-03-06T04:20:52.670734+00:00",
+  "escalation_policy": {
+    "escalation_label": "ESCALATION",
+    "escalation_threshold": 0.95,
+    "description": "If P(ESCALATION) >= 0.950, escalate regardless of argmax. This prioritizes recall for safety-critical escalation detection."
+  },
+  "confidence_policy": {
+    "min_confidence": 0.3,
+    "fallback_label": "OTHER",
+    "description": "If max probability < 0.3, route to OTHER for review."
+  },
+  "calibration_metrics": {
+    "threshold": 0.95,
+    "recall": 0.9696969696969697,
+    "precision": 0.898876404494382,
+    "fpr": 0.016498625114573784,
+    "tp": 160,
+    "fp": 18,
+    "tn": 1073,
+    "fn": 5,
+    "recall_ci": {
+      "point_estimate": 0.9702812759764813,
+      "ci_lower": 0.9433872701218056,
+      "ci_upper": 0.9938281072483526,
+      "confidence_level": 0.95
+    },
+    "precision_ci": {
+      "point_estimate": 0.9000275789258342,
+      "ci_lower": 0.8563822440343247,
+      "ci_upper": 0.9408681214421253,
+      "confidence_level": 0.95
+    },
+    "fpr_ci": {
+      "point_estimate": 0.016454061300607874,
+      "ci_lower": 0.009250480061420503,
+      "ci_upper": 0.02428254680618841,
+      "confidence_level": 0.95
+    }
+  },
+  "decision_logic": [
+    "1. If P(ESCALATION) >= 0.950 \u2192 ESCALATE",
+    "2. Else if max(P) < 0.3 \u2192 route to OTHER",
+    "3. Else \u2192 return argmax label"
+  ],
+  "drift_monitoring": {
+    "enabled": true,
+    "baseline_metrics": {
+      "recall": 0.9696969696969697,
+      "fpr": 0.016498625114573784,
+      "calibration_date": "2026-03-06T04:20:52.670756+00:00"
+    },
+    "alert_thresholds": {
+      "min_recall": 0.9,
+      "max_fpr": 0.3,
+      "recall_drop_from_baseline": 0.05,
+      "fpr_increase_from_baseline": 0.1
+    },
+    "revalidation_policy": {
+      "sample_size": 100,
+      "revalidation_interval_days": 30,
+      "auto_recalibrate": false
+    },
+    "safety_guardrails": {
+      "never_lower_recall_below": 0.85,
+      "never_raise_threshold_above": 0.7,
+      "require_human_approval": true
+    }
+  }
+}

artifacts/onnx_int8/config.json

@@ -0,0 +1,44 @@
+{
+  "add_cross_attention": false,
+  "architectures": [
+    "BertForSequenceClassification"
+  ],
+  "attention_probs_dropout_prob": 0.1,
+  "bos_token_id": null,
+  "classifier_dropout": null,
+  "dtype": "float32",
+  "eos_token_id": null,
+  "hidden_act": "gelu",
+  "hidden_dropout_prob": 0.1,
+  "hidden_size": 768,
+  "id2label": {
+    "0": "ESCALATION",
+    "1": "APPOINTMENT",
+    "2": "MEDICATION",
+    "3": "SYMPTOM_CHECK",
+    "4": "GENERAL_INQUIRY",
+    "5": "BILLING"
+  },
+  "initializer_range": 0.02,
+  "intermediate_size": 3072,
+  "is_decoder": false,
+  "label2id": {
+    "APPOINTMENT": 1,
+    "BILLING": 5,
+    "ESCALATION": 0,
+    "GENERAL_INQUIRY": 4,
+    "MEDICATION": 2,
+    "SYMPTOM_CHECK": 3
+  },
+  "layer_norm_eps": 1e-12,
+  "max_position_embeddings": 512,
+  "model_type": "bert",
+  "num_attention_heads": 12,
+  "num_hidden_layers": 12,
+  "pad_token_id": 0,
+  "tie_word_embeddings": true,
+  "transformers_version": "5.0.0",
+  "type_vocab_size": 2,
+  "use_cache": false,
+  "vocab_size": 28996
+}

artifacts/onnx_int8/decision_policy.json

@@ -0,0 +1,71 @@
+{
+  "version": "2.0.0",
+  "created_at": "2026-02-19T06:04:01.530506+00:00",
+  "escalation_policy": {
+    "escalation_label": "ESCALATION",
+    "escalation_threshold": 0.8069999999999998,
+    "description": "If P(ESCALATION) >= 0.807, escalate regardless of argmax. This prioritizes recall for safety-critical escalation detection."
+  },
+  "confidence_policy": {
+    "min_confidence": 0.3,
+    "fallback_label": "OTHER",
+    "description": "If max probability < 0.3, route to OTHER for review."
+  },
+  "calibration_metrics": {
+    "threshold": 0.8069999999999998,
+    "recall": 0.9515151515151515,
+    "precision": 0.9401197604790419,
+    "fpr": 0.00916590284142988,
+    "tp": 157,
+    "fp": 10,
+    "tn": 1081,
+    "fn": 8,
+    "recall_ci": {
+      "point_estimate": 0.9522554476419556,
+      "ci_lower": 0.9182282243473766,
+      "ci_upper": 0.9817073170731707,
+      "confidence_level": 0.95
+    },
+    "precision_ci": {
+      "point_estimate": 0.9408976664848623,
+      "ci_lower": 0.9015464082389816,
+      "ci_upper": 0.9719292994412722,
+      "confidence_level": 0.95
+    },
+    "fpr_ci": {
+      "point_estimate": 0.009122676909917872,
+      "ci_lower": 0.0045207956600361665,
+      "ci_upper": 0.015582034830430797,
+      "confidence_level": 0.95
+    }
+  },
+  "decision_logic": [
+    "1. If P(ESCALATION) >= 0.807 \u2192 ESCALATE",
+    "2. Else if max(P) < 0.3 \u2192 route to OTHER",
+    "3. Else \u2192 return argmax label"
+  ],
+  "drift_monitoring": {
+    "enabled": true,
+    "baseline_metrics": {
+      "recall": 0.9515151515151515,
+      "fpr": 0.00916590284142988,
+      "calibration_date": "2026-02-19T06:04:01.530524+00:00"
+    },
+    "alert_thresholds": {
+      "min_recall": 0.9,
+      "max_fpr": 0.3,
+      "recall_drop_from_baseline": 0.05,
+      "fpr_increase_from_baseline": 0.1
+    },
+    "revalidation_policy": {
+      "sample_size": 100,
+      "revalidation_interval_days": 30,
+      "auto_recalibrate": false
+    },
+    "safety_guardrails": {
+      "never_lower_recall_below": 0.85,
+      "never_raise_threshold_above": 0.7,
+      "require_human_approval": true
+    }
+  }
+}

artifacts/onnx_int8/export_metadata.json

@@ -0,0 +1,9 @@
+{
+  "source_model": "artifacts\\pytorch\\latest",
+  "export_timestamp": "2026-02-09T05:34:58.146488+00:00",
+  "opset_version": 14,
+  "max_length": 64,
+  "format": "ONNX",
+  "quantization": null,
+  "provider": "CPUExecutionProvider"
+}

artifacts/onnx_int8/label_mappings.json

@@ -0,0 +1,18 @@
+{
+  "label2id": {
+    "ESCALATION": 0,
+    "APPOINTMENT": 1,
+    "MEDICATION": 2,
+    "SYMPTOM_CHECK": 3,
+    "GENERAL_INQUIRY": 4,
+    "BILLING": 5
+  },
+  "id2label": {
+    "0": "ESCALATION",
+    "1": "APPOINTMENT",
+    "2": "MEDICATION",
+    "3": "SYMPTOM_CHECK",
+    "4": "GENERAL_INQUIRY",
+    "5": "BILLING"
+  }
+}

artifacts/onnx_int8/model.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:839432f5a2f74ab12c1832182e6473386467ab1d44f812789854129080f54200
+size 433351691

artifacts/onnx_int8/model.onnx.data

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2eca618854e0f1521bd8b19ed895062e990e19f5878c103e78a5504c76aa8de9
+size 433270784

artifacts/onnx_int8/model_preprocessed.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2a8c406501f56f3345e2d0a59e37ffa30a428b134625bfa9805d961bfcbc414c
+size 57448739

artifacts/onnx_int8/quantization_metadata.json

@@ -0,0 +1,12 @@
+{
+  "source_model": "artifacts\\onnx",
+  "quantization_timestamp": "2026-02-19T06:03:17.727140+00:00",
+  "quantization_type": "dynamic",
+  "weight_type": "INT8",
+  "is_quantized": true,
+  "original_size_mb": 414.67,
+  "quantized_size_mb": 413.28,
+  "compression_ratio": 1.0,
+  "provider": "CPUExecutionProvider",
+  "warning": null
+}

artifacts/onnx_int8/special_tokens_map.json

@@ -0,0 +1,37 @@
+{
+  "cls_token": {
+    "content": "[CLS]",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  },
+  "mask_token": {
+    "content": "[MASK]",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  },
+  "pad_token": {
+    "content": "[PAD]",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  },
+  "sep_token": {
+    "content": "[SEP]",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  },
+  "unk_token": {
+    "content": "[UNK]",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  }
+}

artifacts/onnx_int8/tokenizer_config.json

@@ -0,0 +1,14 @@
+{
+  "backend": "tokenizers",
+  "cls_token": "[CLS]",
+  "do_lower_case": false,
+  "is_local": true,
+  "mask_token": "[MASK]",
+  "model_max_length": 1000000000000000019884624838656,
+  "pad_token": "[PAD]",
+  "sep_token": "[SEP]",
+  "strip_accents": null,
+  "tokenize_chinese_chars": true,
+  "tokenizer_class": "BertTokenizer",
+  "unk_token": "[UNK]"
+}

artifacts/onnx_int8/training_metadata.json

@@ -0,0 +1,21 @@
+{
+  "base_model": "emilyalsentzer/Bio_ClinicalBERT",
+  "max_length": 64,
+  "num_labels": 6,
+  "labels": [
+    "ESCALATION",
+    "APPOINTMENT",
+    "MEDICATION",
+    "SYMPTOM_CHECK",
+    "GENERAL_INQUIRY",
+    "BILLING"
+  ],
+  "training_config": {
+    "epochs": 8,
+    "batch_size": 16,
+    "learning_rate": 2e-05,
+    "max_length": 64
+  },
+  "timestamp": "2026-02-19T05:59:29.871942+00:00",
+  "seed": 42
+}

config/streaming_intent.yaml

@@ -0,0 +1,117 @@
+# Streaming Intent Router Configuration
+# HMM-style belief updating for STT chunk processing
+
+intents:
+  - ESCALATION
+  - APPOINTMENT
+  - MEDICATION
+  - SYMPTOM_CHECK
+  - BILLING
+  - GENERAL_INQUIRY
+  - OTHER
+
+# Prior distribution (initial belief state)
+prior:
+  ESCALATION: 0.05
+  APPOINTMENT: 0.15
+  MEDICATION: 0.15
+  SYMPTOM_CHECK: 0.15
+  BILLING: 0.10
+  GENERAL_INQUIRY: 0.15
+  OTHER: 0.25
+
+# Transition matrix T[i,j] = P(intent_t=j | intent_{t-1}=i)
+# Rows must sum to 1.0
+# High diagonal = "stickiness" (intent tends to persist)
+transition_matrix:
+  ESCALATION:
+    ESCALATION: 0.90
+    APPOINTMENT: 0.01
+    MEDICATION: 0.02
+    SYMPTOM_CHECK: 0.02
+    BILLING: 0.01
+    GENERAL_INQUIRY: 0.02
+    OTHER: 0.02
+  APPOINTMENT:
+    ESCALATION: 0.02
+    APPOINTMENT: 0.80
+    MEDICATION: 0.03
+    SYMPTOM_CHECK: 0.03
+    BILLING: 0.07
+    GENERAL_INQUIRY: 0.03
+    OTHER: 0.02
+  MEDICATION:
+    ESCALATION: 0.04
+    APPOINTMENT: 0.03
+    MEDICATION: 0.82
+    SYMPTOM_CHECK: 0.04
+    BILLING: 0.02
+    GENERAL_INQUIRY: 0.03
+    OTHER: 0.02
+  SYMPTOM_CHECK:
+    ESCALATION: 0.08
+    APPOINTMENT: 0.04
+    MEDICATION: 0.05
+    SYMPTOM_CHECK: 0.75
+    BILLING: 0.02
+    GENERAL_INQUIRY: 0.03
+    OTHER: 0.03
+  BILLING:
+    ESCALATION: 0.01
+    APPOINTMENT: 0.05
+    MEDICATION: 0.02
+    SYMPTOM_CHECK: 0.02
+    BILLING: 0.85
+    GENERAL_INQUIRY: 0.03
+    OTHER: 0.02
+  GENERAL_INQUIRY:
+    ESCALATION: 0.03
+    APPOINTMENT: 0.05
+    MEDICATION: 0.05
+    SYMPTOM_CHECK: 0.05
+    BILLING: 0.04
+    GENERAL_INQUIRY: 0.75
+    OTHER: 0.03
+  OTHER:
+    ESCALATION: 0.02
+    APPOINTMENT: 0.08
+    MEDICATION: 0.08
+    SYMPTOM_CHECK: 0.08
+    BILLING: 0.06
+    GENERAL_INQUIRY: 0.08
+    OTHER: 0.60
+
+# Emission model parameters
+emission:
+  alpha: 1.5          # Sharpening exponent for DriveHealthBERT probabilities
+  epsilon: 1.0e-8     # Smoothing to avoid zero probabilities
+
+# Decision thresholds
+thresholds:
+  theta_hi: 0.85      # Immediate escalation threshold
+  theta_med: 0.60     # Consecutive-steps escalation threshold
+  theta_lock: 0.70    # Commit threshold for non-escalation intents
+  K: 3                # Required consecutive steps for stability
+
+# Rolling window parameters
+window:
+  max_tokens: 64      # Default max tokens in rolling window
+  max_tokens_limit: 128  # Hard limit for max_tokens
+
+# Debounce parameters
+debounce:
+  debounce_ms: 150    # Minimum ms between updates (unless is_final)
+  min_change_chars: 3 # Minimum character change to trigger update
+
+# Model parameters
+model:
+  max_length: 48      # Max sequence length for BioClinicalBERT inference (reduced for latency)
+
+# SPRT (Sequential Probability Ratio Test) parameters
+# Used for statistically-principled escalation decisions
+sprt:
+  alpha: 0.05         # Type I error target (false escalation rate)
+  beta: 0.10          # Type II error target (missed escalation rate)
+  p0: 0.20            # H0: baseline escalation probability (non-escalation)
+  p1: 0.60            # H1: expected escalation probability (true escalation)
+  # Note: Run scripts/evaluate_sprt_streaming.py --estimate_p0_p1 to tune these

config/train_config.yaml

@@ -0,0 +1,87 @@
+# DCE Intent BioClinicalBERT Training Configuration
+# ============================================
+# Version: 2.0.0
+# Last Updated: 2026-02-08
+
+# Model Configuration
+# Using BioClinicalBERT for medical domain accuracy
+# Reduced max_length to 48 to maintain low latency
+model:
+  base_model: "emilyalsentzer/Bio_ClinicalBERT"
+  max_length: 48  # Reduced from 64 to compensate for larger model
+  num_labels: null  # Auto-detected from dataset
+
+# Training Hyperparameters
+training:
+  learning_rate: 3.0e-5
+  epochs: 15
+  batch_size: 16
+  eval_batch_size: 32
+  warmup_ratio: 0.1
+  weight_decay: 0.01
+  gradient_accumulation_steps: 1
+  max_grad_norm: 1.0
+  
+# Optimizer
+optimizer:
+  type: "adamw"
+  betas: [0.9, 0.999]
+  eps: 1.0e-8
+
+# Scheduler
+scheduler:
+  type: "linear"  # linear warmup then linear decay
+
+# Data Paths
+data:
+  train_path: "data/examples/train.jsonl"
+  val_path: "data/examples/val.jsonl"
+  test_path: "data/examples/test.jsonl"
+  text_column: "text"
+  label_column: "label"
+
+# Output Configuration
+output:
+  base_dir: "artifacts"
+  pytorch_dir: "artifacts/pytorch"
+  save_steps: 30
+  eval_steps: 15
+  logging_steps: 15
+  save_total_limit: 2
+
+# Reproducibility
+seed: 42
+deterministic: true
+
+# Logging
+logging:
+  level: "INFO"
+  log_to_file: true
+  log_file: "artifacts/logs/training.log"
+
+# Intent Schema (Tier 1 - Required)
+intent_schema:
+  tier1:
+    - "ESCALATION"          # Urgent medical escalation
+    - "APPOINTMENT"         # Schedule/reschedule appointments
+    - "MEDICATION"          # Medication-related queries
+    - "SYMPTOM_CHECK"       # Symptom assessment
+    - "GENERAL_INQUIRY"     # General health questions
+    - "BILLING"             # Billing/insurance questions
+    - "OTHER"               # Fallback category
+  tier2:  # Optional sub-categories
+    ESCALATION:
+      - "CHEST_PAIN"
+      - "BREATHING_DIFFICULTY"
+      - "SEVERE_BLEEDING"
+      - "LOSS_OF_CONSCIOUSNESS"
+      - "OTHER_EMERGENCY"
+
+# Evaluation Metrics
+metrics:
+  primary: "macro_f1"
+  track:
+    - "accuracy"
+    - "macro_f1"
+    - "per_class_recall"
+  escalation_label: "ESCALATION"  # Label to track recall for

config/train_config_augmented.yaml

@@ -0,0 +1,80 @@
+# DCE Intent BioClinicalBERT Training Configuration - Augmented Dataset
+# ======================================================================
+# Version: 2.1.0
+# Last Updated: 2026-02-13
+# Description: Training config using merged dataset with disease symptom data
+
+# Model Configuration
+model:
+  base_model: "emilyalsentzer/Bio_ClinicalBERT"
+  max_length: 48
+  num_labels: null  # Auto-detected from dataset
+
+# Training Hyperparameters
+# Slightly adjusted for larger dataset
+training:
+  learning_rate: 2.5e-5  # Slightly lower LR for larger dataset
+  epochs: 12  # Slightly fewer epochs since more data
+  batch_size: 16
+  eval_batch_size: 32
+  warmup_ratio: 0.1
+  weight_decay: 0.01
+  gradient_accumulation_steps: 1
+  max_grad_norm: 1.0
+  
+# Optimizer
+optimizer:
+  type: "adamw"
+  betas: [0.9, 0.999]
+  eps: 1.0e-8
+
+# Scheduler
+scheduler:
+  type: "linear"
+
+# Data Paths - Using merged augmented dataset
+data:
+  train_path: "data/merged/train.jsonl"
+  val_path: "data/merged/val.jsonl"
+  test_path: "data/merged/test.jsonl"
+  text_column: "text"
+  label_column: "label"
+
+# Output Configuration
+output:
+  base_dir: "artifacts"
+  pytorch_dir: "artifacts/pytorch"
+  save_steps: 50
+  eval_steps: 25
+  logging_steps: 25
+  save_total_limit: 2
+
+# Reproducibility
+seed: 42
+deterministic: true
+
+# Logging
+logging:
+  level: "INFO"
+  log_to_file: true
+  log_file: "artifacts/logs/training_augmented.log"
+
+# Intent Schema
+intent_schema:
+  tier1:
+    - "ESCALATION"
+    - "APPOINTMENT"
+    - "MEDICATION"
+    - "SYMPTOM_CHECK"
+    - "GENERAL_INQUIRY"
+    - "BILLING"
+    - "OTHER"
+
+# Evaluation Metrics
+metrics:
+  primary: "macro_f1"
+  track:
+    - "accuracy"
+    - "macro_f1"
+    - "per_class_recall"
+  escalation_label: "ESCALATION"

config/train_config_v2.yaml

@@ -0,0 +1,69 @@
+# DCE Intent BioClinicalBERT Training Configuration - v2 with Hard Negatives
+# ===========================================================================
+# Version: 2.2.0
+# Description: Training with hard negative examples to reduce false positives
+
+model:
+  base_model: "emilyalsentzer/Bio_ClinicalBERT"
+  max_length: 48
+  num_labels: null
+
+training:
+  learning_rate: 2.0e-5  # Slightly lower for fine-tuning
+  epochs: 10
+  batch_size: 16
+  eval_batch_size: 32
+  warmup_ratio: 0.1
+  weight_decay: 0.01
+  gradient_accumulation_steps: 1
+  max_grad_norm: 1.0
+
+optimizer:
+  type: "adamw"
+  betas: [0.9, 0.999]
+  eps: 1.0e-8
+
+scheduler:
+  type: "linear"
+
+# Using merged_v2 with hard negatives
+data:
+  train_path: "data/merged_v2/train.jsonl"
+  val_path: "data/merged_v2/val.jsonl"
+  test_path: "data/merged_v2/test.jsonl"
+  text_column: "text"
+  label_column: "label"
+
+output:
+  base_dir: "artifacts"
+  pytorch_dir: "artifacts/pytorch"
+  save_steps: 50
+  eval_steps: 25
+  logging_steps: 25
+  save_total_limit: 2
+
+seed: 42
+deterministic: true
+
+logging:
+  level: "INFO"
+  log_to_file: true
+  log_file: "artifacts/logs/training_v2.log"
+
+intent_schema:
+  tier1:
+    - "ESCALATION"
+    - "APPOINTMENT"
+    - "MEDICATION"
+    - "SYMPTOM_CHECK"
+    - "GENERAL_INQUIRY"
+    - "BILLING"
+    - "OTHER"
+
+metrics:
+  primary: "macro_f1"
+  track:
+    - "accuracy"
+    - "macro_f1"
+    - "per_class_recall"
+  escalation_label: "ESCALATION"

config/train_config_v3.yaml

@@ -0,0 +1,74 @@
+# DCE Intent BioClinicalBERT Training Configuration - v3 Taxonomy Augmented
+# ===========================================================================
+# Version: 3.0.0
+# Description: Retrain with taxonomy-augmented data from 66 clinical domains
+# Changes from v2:
+#   - Merged 1,720 taxonomy-generated samples (balanced, deduplicated)
+#   - Better coverage of minority classes (GENERAL_INQUIRY, APPOINTMENT, MEDICATION)
+#   - Negation examples to reduce false positive escalations
+#   - Slightly lower LR for fine-tuning on augmented mix
+
+model:
+  base_model: "emilyalsentzer/Bio_ClinicalBERT"
+  max_length: 48
+  num_labels: null
+
+training:
+  learning_rate: 2.0e-5
+  epochs: 6
+  batch_size: 16
+  eval_batch_size: 32
+  warmup_ratio: 0.1
+  weight_decay: 0.01
+  gradient_accumulation_steps: 1
+  max_grad_norm: 1.0
+
+optimizer:
+  type: "adamw"
+  betas: [0.9, 0.999]
+  eps: 1.0e-8
+
+scheduler:
+  type: "linear"
+
+# Using merged_v3 with taxonomy augmentation
+data:
+  train_path: "data/merged_v3/train.jsonl"
+  val_path: "data/merged_v3/val.jsonl"
+  test_path: "data/merged_v3/test.jsonl"
+  text_column: "text"
+  label_column: "label"
+
+output:
+  base_dir: "artifacts"
+  pytorch_dir: "artifacts/pytorch"
+  save_steps: 200
+  eval_steps: 100
+  logging_steps: 50
+  save_total_limit: 3
+
+seed: 42
+deterministic: true
+
+logging:
+  level: "INFO"
+  log_to_file: true
+  log_file: "artifacts/logs/training_v3.log"
+
+intent_schema:
+  tier1:
+    - "ESCALATION"
+    - "APPOINTMENT"
+    - "MEDICATION"
+    - "SYMPTOM_CHECK"
+    - "GENERAL_INQUIRY"
+    - "BILLING"
+    - "OTHER"
+
+metrics:
+  primary: "macro_f1"
+  track:
+    - "accuracy"
+    - "macro_f1"
+    - "per_class_recall"
+  escalation_label: "ESCALATION"

config/train_config_v4.yaml

@@ -0,0 +1,74 @@
+# DCE Intent BioClinicalBERT Training Configuration - v4 Severity-Relabeled
+# ===========================================================================
+# Version: 4.0.0
+# Description: Retrain with severity-based relabeling, merged OTHER, R3 augmentation
+# Changes from v3:
+#   - ESCALATION/SYMPTOM_CHECK relabeled based on R3 severity rules (1,783 fixes)
+#   - OTHER merged into GENERAL_INQUIRY
+#   - 632 new R3-specific ESCALATION samples with distinct urgent phrasing
+#   - max_length increased to 64 (was 48) for edge-case multi-symptom text
+#   - Reduced escalation_weight, using focal loss for better hard-example handling
+#   - 6 labels (no more OTHER)
+
+model:
+  base_model: "emilyalsentzer/Bio_ClinicalBERT"
+  max_length: 64
+  num_labels: null
+
+training:
+  learning_rate: 2.0e-5
+  epochs: 8
+  batch_size: 16
+  eval_batch_size: 32
+  warmup_ratio: 0.1
+  weight_decay: 0.01
+  gradient_accumulation_steps: 1
+  max_grad_norm: 1.0
+
+optimizer:
+  type: "adamw"
+  betas: [0.9, 0.999]
+  eps: 1.0e-8
+
+scheduler:
+  type: "linear"
+
+data:
+  train_path: "data/merged_v4/train.jsonl"
+  val_path: "data/merged_v4/val.jsonl"
+  test_path: "data/merged_v4/test.jsonl"
+  text_column: "text"
+  label_column: "label"
+
+output:
+  base_dir: "artifacts"
+  pytorch_dir: "artifacts/pytorch"
+  save_steps: 200
+  eval_steps: 100
+  logging_steps: 50
+  save_total_limit: 3
+
+seed: 42
+deterministic: true
+
+logging:
+  level: "INFO"
+  log_to_file: true
+  log_file: "artifacts/logs/training_v4.log"
+
+intent_schema:
+  tier1:
+    - "ESCALATION"
+    - "APPOINTMENT"
+    - "MEDICATION"
+    - "SYMPTOM_CHECK"
+    - "GENERAL_INQUIRY"
+    - "BILLING"
+
+metrics:
+  primary: "macro_f1"
+  track:
+    - "accuracy"
+    - "macro_f1"
+    - "per_class_recall"
+  escalation_label: "ESCALATION"

config/train_config_v5.yaml

@@ -0,0 +1,71 @@
+# DCE Intent BioClinicalBERT Training Configuration - v5 Temporal Context
+# ===========================================================================
+# Version: 5.0.0
+# Description: v4 base + 1,180 temporal/historical context samples
+# Changes from v4:
+#   - 820 past/resolved symptom samples (SYMPTOM_CHECK) - teaches past tense
+#   - 280 still-active-despite-past-framing samples (ESCALATION) - preserves recall
+#   - 80 third-party/informational samples (GENERAL_INQUIRY)
+#   - Total: 7,338 train + 1,256 val
+
+model:
+  base_model: "emilyalsentzer/Bio_ClinicalBERT"
+  max_length: 64
+  num_labels: null
+
+training:
+  learning_rate: 2.0e-5
+  epochs: 8
+  batch_size: 16
+  eval_batch_size: 32
+  warmup_ratio: 0.1
+  weight_decay: 0.01
+  gradient_accumulation_steps: 1
+  max_grad_norm: 1.0
+
+optimizer:
+  type: "adamw"
+  betas: [0.9, 0.999]
+  eps: 1.0e-8
+
+scheduler:
+  type: "linear"
+
+data:
+  train_path: "data/merged_v5/train.jsonl"
+  val_path: "data/merged_v5/val.jsonl"
+  text_column: "text"
+  label_column: "label"
+
+output:
+  base_dir: "artifacts"
+  pytorch_dir: "artifacts/pytorch"
+  save_steps: 200
+  eval_steps: 100
+  logging_steps: 50
+  save_total_limit: 3
+
+seed: 42
+deterministic: true
+
+logging:
+  level: "INFO"
+  log_to_file: true
+  log_file: "artifacts/logs/training_v5.log"
+
+intent_schema:
+  tier1:
+    - "ESCALATION"
+    - "APPOINTMENT"
+    - "MEDICATION"
+    - "SYMPTOM_CHECK"
+    - "GENERAL_INQUIRY"
+    - "BILLING"
+
+metrics:
+  primary: "macro_f1"
+  track:
+    - "accuracy"
+    - "macro_f1"
+    - "per_class_recall"
+  escalation_label: "ESCALATION"

config/train_config_v6.yaml

@@ -0,0 +1,75 @@
+# DCE Intent BioClinicalBERT Training Configuration - v6 Temporal Edge Cases
+# ===========================================================================
+# Version: 6.0.0
+# Description: v5 base + 840 temporal edge case samples
+# Changes from v5:
+#   - 300 BUT-clause reversal samples (ESCALATION) - "felt better but now it's back"
+#   - 300 proxy/third-party urgent reports (ESCALATION) - "my mom says chest hurts"
+#   - 90 proxy non-urgent (SYMPTOM_CHECK/GENERAL_INQUIRY) - "my friend had X last year"
+#   - 80 mixed temporal active (ESCALATION) - "had X and it hasn't gone away"
+#   - 20 intermittent dangerous (ESCALATION) - "sometimes I have trouble breathing"
+#   - 25 negated symptoms (SYMPTOM_CHECK) - "I don't have chest pain"
+#   - 25 informational (GENERAL_INQUIRY) - "what causes seizures"
+#   - Total: ~8,178 train + 1,256 val
+
+model:
+  base_model: "emilyalsentzer/Bio_ClinicalBERT"
+  max_length: 64
+  num_labels: null
+
+training:
+  learning_rate: 2.0e-5
+  epochs: 8
+  batch_size: 16
+  eval_batch_size: 32
+  warmup_ratio: 0.1
+  weight_decay: 0.01
+  gradient_accumulation_steps: 1
+  max_grad_norm: 1.0
+
+optimizer:
+  type: "adamw"
+  betas: [0.9, 0.999]
+  eps: 1.0e-8
+
+scheduler:
+  type: "linear"
+
+data:
+  train_path: "data/merged_v6/train.jsonl"
+  val_path: "data/merged_v6/val.jsonl"
+  text_column: "text"
+  label_column: "label"
+
+output:
+  base_dir: "artifacts"
+  pytorch_dir: "artifacts/pytorch"
+  save_steps: 200
+  eval_steps: 100
+  logging_steps: 50
+  save_total_limit: 3
+
+seed: 42
+deterministic: true
+
+logging:
+  level: "INFO"
+  log_to_file: true
+  log_file: "artifacts/logs/training_v6.log"
+
+intent_schema:
+  tier1:
+    - "ESCALATION"
+    - "APPOINTMENT"
+    - "MEDICATION"
+    - "SYMPTOM_CHECK"
+    - "GENERAL_INQUIRY"
+    - "BILLING"
+
+metrics:
+  primary: "macro_f1"
+  track:
+    - "accuracy"
+    - "macro_f1"
+    - "per_class_recall"
+  escalation_label: "ESCALATION"

decision/context/fhir_mappings.yaml

@@ -0,0 +1,61 @@
+# FHIR Resource Mappings for Patient Context
+#
+# Maps FHIR resources to PatientContext fields, organized by wedge.
+# Used by PatientContextBuilder to fetch only what's needed (minimum necessary).
+
+# Which FHIR resources to fetch per wedge (minimum necessary principle)
+wedge_resources:
+  post_discharge_engagement:
+    - Patient
+    - Condition
+    - MedicationRequest
+    - Observation  # labs + vitals
+    - AllergyIntolerance
+    - Encounter
+    - DocumentReference  # discharge summary
+    - Appointment
+  pre_op_optimization:
+    - Patient
+    - Condition
+    - MedicationRequest
+    - AllergyIntolerance
+    - ServiceRequest  # scheduled procedures
+    - Appointment
+  annual_wellness_visit:
+    - Patient
+    - Condition
+    - MedicationRequest
+    - Observation
+    - Immunization
+    - AllergyIntolerance
+  gap_closure:
+    - Patient
+    - Condition
+    - Immunization
+    - Observation  # screening results
+  health_risk_assessment:
+    - Patient
+    - Condition
+    - MedicationRequest
+    - Observation  # labs + screenings
+    - AllergyIntolerance
+
+# Default lookback periods per resource type
+lookback_days:
+  Observation_laboratory: 90
+  Observation_vital_signs: 30
+  MedicationRequest: 365
+  Condition: null  # all active, no date filter
+  Encounter: 365
+  Immunization: 730
+  Appointment: 90  # upcoming only
+
+# Freshness thresholds (hours) for staleness detection
+freshness_thresholds:
+  MedicationRequest: 24
+  Condition: 168  # 7 days
+  Observation_laboratory: 48
+  Observation_vital_signs: 24
+  AllergyIntolerance: 720  # 30 days
+  Immunization: 720
+  Appointment: 12

decision/engine/__init__.py

@@ -0,0 +1,55 @@
+"""
+Decision Engine for DCE Intent Classification.
+
+Phase 1: Safety Trifecta
+  - Taxonomy trigger matching (phrase, regex, partial, negation)
+  - Domain nomination (DriveHealthBERT + triggers → ranked domains)
+  - Risk classification (R0/R1/R2/R3)
+
+Phase 2: Conversation Engine
+  - Flow execution (state machine, slot tracking)
+  - Streaming flow integration
+
+Phase 3: Clinical Intelligence
+  - FHIR context-aware risk rules
+  - Multi-tenant configuration
+  - Journey orchestration
+"""
+
+from decision.engine.models import (
+    ConfidenceTier,
+    RiskClass,
+    TriggerMatch,
+    DomainNomination,
+    RiskAssessment,
+    NegationResult,
+)
+from decision.engine.trigger_engine import TaxonomyTriggerEngine
+from decision.engine.domain_nomination import DomainNominator
+from decision.engine.risk_classifier import RiskClassifier
+from decision.engine.config_loader import DecisionConfigLoader
+from decision.engine.flow_engine import FlowEngine, FlowResolver, TurnResult
+from decision.engine.fhir_context import PatientContext, PatientContextBuilder
+from decision.engine.tenant_manager import TenantManager, TenantConfig
+from decision.engine.journey_orchestrator import JourneyOrchestrator
+
+__all__ = [
+    "ConfidenceTier",
+    "RiskClass",
+    "TriggerMatch",
+    "DomainNomination",
+    "RiskAssessment",
+    "NegationResult",
+    "TaxonomyTriggerEngine",
+    "DomainNominator",
+    "RiskClassifier",
+    "DecisionConfigLoader",
+    "FlowEngine",
+    "FlowResolver",
+    "TurnResult",
+    "PatientContext",
+    "PatientContextBuilder",
+    "TenantManager",
+    "TenantConfig",
+    "JourneyOrchestrator",
+]

decision/engine/config_loader.py

@@ -0,0 +1,472 @@
+"""
+Configuration loader for the Decision Engine.
+
+Loads and validates all YAML configuration from the decision/ folder:
+  - global/global_rules.yaml
+  - taxonomy/*/triggers.yaml, rules.yaml, flows/*.yaml
+  - primitives/*.yaml
+  - orchestrator/*.yaml
+  - context/fhir_mappings.yaml
+  - tenants/*/tenant.yaml
+  - journeys/*.yaml
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+import yaml
+
+logger = logging.getLogger("decision.config_loader")
+
+
+class DecisionConfigLoader:
+    """Loads and caches all decision engine configuration from YAML files."""
+
+    def __init__(self, decision_dir: str | Path):
+        self.decision_dir = Path(decision_dir)
+        if not self.decision_dir.is_dir():
+            raise FileNotFoundError(
+                f"Decision config directory not found: {self.decision_dir}"
+            )
+
+        # Loaded config caches
+        self._global_rules: Optional[Dict[str, Any]] = None
+        self._taxonomy_triggers: Optional[Dict[str, Dict[str, Any]]] = None
+        self._taxonomy_rules: Optional[Dict[str, Dict[str, Any]]] = None
+        self._taxonomy_flows: Optional[Dict[str, Dict[str, Dict[str, Any]]]] = None
+        self._primitives: Optional[Dict[str, Dict[str, Any]]] = None
+        self._orchestrator: Optional[Dict[str, Dict[str, Any]]] = None
+        self._fhir_mappings: Optional[Dict[str, Any]] = None
+        self._tenants: Optional[Dict[str, Dict[str, Any]]] = None
+        self._journeys: Optional[Dict[str, Dict[str, Any]]] = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def load_all(self) -> None:
+        """Load all configuration files. Call once at startup."""
+        logger.info("Loading decision engine configuration from %s", self.decision_dir)
+        self._load_global_rules()
+        self._load_taxonomy()
+        self._load_primitives()
+        self._load_orchestrator()
+        self._load_fhir_mappings()
+        self._load_tenants()
+        self._load_journeys()
+        self._validate()
+        logger.info(
+            "Decision config loaded: %d domains, %d primitives, %d tenants, %d journeys",
+            len(self._taxonomy_triggers or {}),
+            len(self._primitives or {}),
+            len(self._tenants or {}),
+            len(self._journeys or {}),
+        )
+
+    @property
+    def global_rules(self) -> Dict[str, Any]:
+        if self._global_rules is None:
+            self._load_global_rules()
+        return self._global_rules
+
+    @property
+    def taxonomy_triggers(self) -> Dict[str, Dict[str, Any]]:
+        """domain_name -> triggers.yaml content"""
+        if self._taxonomy_triggers is None:
+            self._load_taxonomy()
+        return self._taxonomy_triggers
+
+    @property
+    def taxonomy_rules(self) -> Dict[str, Dict[str, Any]]:
+        """domain_name -> rules.yaml content"""
+        if self._taxonomy_rules is None:
+            self._load_taxonomy()
+        return self._taxonomy_rules
+
+    @property
+    def taxonomy_flows(self) -> Dict[str, Dict[str, Dict[str, Any]]]:
+        """domain_name -> {flow_id -> flow.yaml content}"""
+        if self._taxonomy_flows is None:
+            self._load_taxonomy()
+        return self._taxonomy_flows
+
+    @property
+    def primitives(self) -> Dict[str, Dict[str, Any]]:
+        if self._primitives is None:
+            self._load_primitives()
+        return self._primitives
+
+    @property
+    def orchestrator(self) -> Dict[str, Dict[str, Any]]:
+        if self._orchestrator is None:
+            self._load_orchestrator()
+        return self._orchestrator
+
+    @property
+    def fhir_mappings(self) -> Dict[str, Any]:
+        if self._fhir_mappings is None:
+            self._load_fhir_mappings()
+        return self._fhir_mappings
+
+    @property
+    def tenants(self) -> Dict[str, Dict[str, Any]]:
+        if self._tenants is None:
+            self._load_tenants()
+        return self._tenants
+
+    @property
+    def journeys(self) -> Dict[str, Dict[str, Any]]:
+        if self._journeys is None:
+            self._load_journeys()
+        return self._journeys
+
+    # ------------------------------------------------------------------
+    # Derived accessors
+    # ------------------------------------------------------------------
+
+    @property
+    def safety_precedence(self) -> List[str]:
+        """Ordered list of domains by clinical acuity (highest first)."""
+        return self.global_rules.get("safety_precedence", [])
+
+    @property
+    def hard_escalate_domains(self) -> Set[str]:
+        """Domains that always escalate regardless of confidence.
+
+        Includes both explicitly listed domains from global_rules AND
+        any taxonomy domain whose rules.yaml declares target_risk_class: R3.
+        """
+        explicit = set(self.global_rules.get("hard_escalate_domains", []))
+        # Auto-include every domain with target_risk_class R3
+        for domain_name, rules in (self._taxonomy_rules or {}).items():
+            if rules.get("target_risk_class") == "R3":
+                explicit.add(domain_name)
+        return explicit
+
+    @property
+    def risk_escalation_rules(self) -> List[Dict[str, Any]]:
+        """Risk escalation rule definitions from global_rules."""
+        return self.global_rules.get("risk_escalation_rules", [])
+
+    @property
+    def domain_suppression_rules(self) -> List[Dict[str, Any]]:
+        """Domain suppression rules from global_rules."""
+        return self.global_rules.get("domain_suppression", [])
+
+    @property
+    def risk_class_descriptions(self) -> Dict[str, str]:
+        """R0/R1/R2/R3 descriptions."""
+        return self.global_rules.get("risk_classes", {})
+
+    @property
+    def domain_names(self) -> List[str]:
+        """All known domain names from taxonomy."""
+        return sorted(self.taxonomy_triggers.keys())
+
+    def get_tenant(self, tenant_id: str) -> Optional[Dict[str, Any]]:
+        """Get tenant config by ID."""
+        return self.tenants.get(tenant_id)
+
+    def get_domain_priority(self, domain: str) -> int:
+        """Get priority for a domain (higher = more urgent). Default 0."""
+        triggers = self.taxonomy_triggers.get(domain, {})
+        return triggers.get("priority", 0)
+
+    def get_domain_target_risk(self, domain: str) -> Optional[str]:
+        """Get default target risk class for a domain from rules.yaml."""
+        rules = self.taxonomy_rules.get(domain, {})
+        return rules.get("target_risk_class")
+
+    def get_domain_decision_rules(self, domain: str) -> List[Dict[str, Any]]:
+        """Get decision rules for a domain."""
+        rules = self.taxonomy_rules.get(domain, {})
+        return rules.get("decision_rules", [])
+
+    # ------------------------------------------------------------------
+    # Internal loaders
+    # ------------------------------------------------------------------
+
+    def _safe_load_yaml(self, path: Path) -> Dict[str, Any]:
+        """Load a YAML file safely, returning empty dict on error."""
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                data = yaml.safe_load(f)
+                return data if isinstance(data, dict) else {}
+        except Exception as e:
+            logger.warning("Failed to load YAML %s: %s", path, e)
+            return {}
+
+    def _load_global_rules(self) -> None:
+        path = self.decision_dir / "global" / "global_rules.yaml"
+        self._global_rules = self._safe_load_yaml(path)
+        if not self._global_rules:
+            logger.error("CRITICAL: global_rules.yaml is empty or missing at %s", path)
+
+    def _load_taxonomy(self) -> None:
+        self._taxonomy_triggers = {}
+        self._taxonomy_rules = {}
+        self._taxonomy_flows = {}
+
+        taxonomy_dir = self.decision_dir / "taxonomy"
+        if not taxonomy_dir.is_dir():
+            logger.warning("Taxonomy directory not found: %s", taxonomy_dir)
+            return
+
+        for domain_dir in sorted(taxonomy_dir.iterdir()):
+            if not domain_dir.is_dir():
+                continue
+            domain_name = domain_dir.name
+
+            # Load triggers.yaml
+            triggers_path = domain_dir / "triggers.yaml"
+            if triggers_path.is_file():
+                triggers = self._safe_load_yaml(triggers_path)
+                if triggers:
+                    self._taxonomy_triggers[domain_name] = triggers
+                    # Pre-compile regex patterns for performance
+                    self._compile_trigger_regex(domain_name, triggers)
+
+            # Load rules.yaml
+            rules_path = domain_dir / "rules.yaml"
+            if rules_path.is_file():
+                rules = self._safe_load_yaml(rules_path)
+                if rules:
+                    self._taxonomy_rules[domain_name] = rules
+
+            # Load flows/*.yaml
+            flows_dir = domain_dir / "flows"
+            if flows_dir.is_dir():
+                domain_flows = {}
+                for flow_file in sorted(flows_dir.iterdir()):
+                    if flow_file.suffix in (".yaml", ".yml"):
+                        flow_data = self._safe_load_yaml(flow_file)
+                        if flow_data:
+                            flow_id = flow_data.get("flow_id", flow_file.stem)
+                            domain_flows[flow_id] = flow_data
+                if domain_flows:
+                    self._taxonomy_flows[domain_name] = domain_flows
+
+    def _compile_trigger_regex(
+        self, domain_name: str, triggers: Dict[str, Any]
+    ) -> None:
+        """Pre-compile regex patterns in trigger definitions for performance."""
+        lexical = triggers.get("lexical_signals", {})
+        for tier_name in ("high", "medium", "low"):
+            tier = lexical.get(tier_name, {})
+            raw_patterns = tier.get("regex", [])
+            compiled = []
+            for pattern in raw_patterns:
+                try:
+                    compiled.append(re.compile(pattern, re.IGNORECASE))
+                except re.error as e:
+                    logger.warning(
+                        "Invalid regex in %s/%s: %r → %s",
+                        domain_name,
+                        tier_name,
+                        pattern,
+                        e,
+                    )
+            tier["_compiled_regex"] = compiled
+
+        # Compile negation patterns
+        negation = triggers.get("negation_handling", {})
+        neg_patterns = negation.get("patterns", [])
+        negation["_compiled_patterns"] = [
+            p.lower() for p in neg_patterns
+        ]
+
+    def load_additional_taxonomy(self, taxonomy_dir: str | Path) -> int:
+        """
+        Load additional taxonomy domains from a secondary directory.
+        
+        Only loads domains that are NOT already present in the primary taxonomy.
+        Returns the number of new domains added.
+        """
+        taxonomy_dir = Path(taxonomy_dir)
+        if not taxonomy_dir.is_dir():
+            logger.warning("Additional taxonomy directory not found: %s", taxonomy_dir)
+            return 0
+
+        if self._taxonomy_triggers is None:
+            self._taxonomy_triggers = {}
+        if self._taxonomy_rules is None:
+            self._taxonomy_rules = {}
+        if self._taxonomy_flows is None:
+            self._taxonomy_flows = {}
+
+        added = 0
+        for domain_dir in sorted(taxonomy_dir.iterdir()):
+            if not domain_dir.is_dir():
+                continue
+            domain_name = domain_dir.name
+
+            # Skip domains already loaded from primary taxonomy
+            if domain_name in self._taxonomy_triggers:
+                continue
+
+            # Load triggers.yaml
+            triggers_path = domain_dir / "triggers.yaml"
+            if triggers_path.is_file():
+                triggers = self._safe_load_yaml(triggers_path)
+                if triggers:
+                    self._taxonomy_triggers[domain_name] = triggers
+                    self._compile_trigger_regex(domain_name, triggers)
+
+            # Load rules.yaml
+            rules_path = domain_dir / "rules.yaml"
+            if rules_path.is_file():
+                rules = self._safe_load_yaml(rules_path)
+                if rules:
+                    self._taxonomy_rules[domain_name] = rules
+
+            # Load flows/*.yaml
+            flows_dir = domain_dir / "flows"
+            if flows_dir.is_dir():
+                domain_flows = {}
+                for flow_file in sorted(flows_dir.iterdir()):
+                    if flow_file.suffix in (".yaml", ".yml"):
+                        flow_data = self._safe_load_yaml(flow_file)
+                        if flow_data:
+                            flow_id = flow_data.get("flow_id", flow_file.stem)
+                            domain_flows[flow_id] = flow_data
+                if domain_flows:
+                    self._taxonomy_flows[domain_name] = domain_flows
+
+            added += 1
+
+        if added:
+            logger.info(
+                "Loaded %d additional taxonomy domains from %s (total: %d)",
+                added, taxonomy_dir, len(self._taxonomy_triggers),
+            )
+        return added
+
+    def _load_primitives(self) -> None:
+        self._primitives = {}
+        prim_dir = self.decision_dir / "primitives"
+        if not prim_dir.is_dir():
+            return
+        for f in sorted(prim_dir.iterdir()):
+            if f.suffix in (".yaml", ".yml"):
+                data = self._safe_load_yaml(f)
+                if data:
+                    flow_id = data.get("flow_id", f.stem)
+                    self._primitives[flow_id] = data
+
+    def _load_orchestrator(self) -> None:
+        self._orchestrator = {}
+        orch_dir = self.decision_dir / "orchestrator"
+        if not orch_dir.is_dir():
+            return
+        for f in sorted(orch_dir.iterdir()):
+            if f.suffix in (".yaml", ".yml"):
+                data = self._safe_load_yaml(f)
+                if data:
+                    self._orchestrator[f.stem] = data
+
+    def _load_fhir_mappings(self) -> None:
+        path = self.decision_dir / "context" / "fhir_mappings.yaml"
+        self._fhir_mappings = self._safe_load_yaml(path) if path.is_file() else {}
+
+    def _load_tenants(self) -> None:
+        self._tenants = {}
+        tenants_dir = self.decision_dir / "tenants"
+        if not tenants_dir.is_dir():
+            return
+        for tenant_dir in sorted(tenants_dir.iterdir()):
+            if not tenant_dir.is_dir():
+                continue
+            tenant_path = tenant_dir / "tenant.yaml"
+            if tenant_path.is_file():
+                data = self._safe_load_yaml(tenant_path)
+                if data:
+                    tid = data.get("tenant_id", tenant_dir.name)
+                    self._tenants[tid] = data
+
+    def _load_journeys(self) -> None:
+        self._journeys = {}
+        journeys_dir = self.decision_dir / "journeys"
+        if not journeys_dir.is_dir():
+            return
+        for f in sorted(journeys_dir.iterdir()):
+            if f.suffix in (".yaml", ".yml"):
+                data = self._safe_load_yaml(f)
+                if data:
+                    wt = data.get("wedge_type", f.stem)
+                    self._journeys[wt] = data
+
+    # ------------------------------------------------------------------
+    # Validation
+    # ------------------------------------------------------------------
+
+    def _validate(self) -> None:
+        """Run basic validation checks on loaded configuration."""
+        errors = []
+
+        # Check global rules has required keys
+        required_global_keys = [
+            "safety_precedence",
+            "risk_classes",
+            "risk_escalation_rules",
+            "hard_escalate_domains",
+        ]
+        for key in required_global_keys:
+            if key not in self.global_rules:
+                errors.append(f"global_rules.yaml missing required key: {key}")
+
+        # Check every domain in safety_precedence has triggers
+        for domain in self.safety_precedence:
+            if domain not in self.taxonomy_triggers:
+                errors.append(
+                    f"safety_precedence domain '{domain}' has no triggers.yaml"
+                )
+
+        # Check hard_escalate domains exist
+        for domain in self.hard_escalate_domains:
+            if domain not in self.taxonomy_triggers:
+                errors.append(
+                    f"hard_escalate domain '{domain}' has no triggers.yaml"
+                )
+
+        # Check risk escalation rules reference valid domains
+        for rule in self.risk_escalation_rules:
+            rule_domain = rule.get("if", {}).get("domain")
+            if rule_domain and rule_domain not in self.taxonomy_triggers:
+                errors.append(
+                    f"risk rule '{rule.get('id')}' references unknown domain "
+                    f"'{rule_domain}'"
+                )
+
+        # Check tenant wedge references
+        for tid, tenant in self.tenants.items():
+            for wedge in tenant.get("enabled_wedges", []):
+                # Map short names to journey keys
+                if wedge not in self.journeys:
+                    # Try mapping common abbreviations
+                    mapping = {
+                        "pde": "pde",
+                        "pre_op": "pre_op",
+                        "awv": "awv",
+                        "gap_closure": "gap_closure",
+                        "hra": "hra",
+                    }
+                    if wedge not in mapping:
+                        logger.debug(
+                            "Tenant '%s' references wedge '%s' not in journeys",
+                            tid,
+                            wedge,
+                        )
+
+        if errors:
+            for err in errors:
+                logger.warning("Config validation: %s", err)
+            logger.warning(
+                "Decision config has %d validation warning(s)", len(errors)
+            )
+        else:
+            logger.info("Decision config validation passed")

decision/engine/domain_nomination.py

@@ -0,0 +1,326 @@
+"""
+Domain Nomination Layer.
+
+Combines DriveHealthBERT ML output with taxonomy trigger matches to produce
+a ranked list of clinical domain nominations.
+
+The nomination algorithm:
+  1. Run taxonomy triggers against the text → domain match results
+  2. Receive DriveHealthBERT label + probabilities
+  3. Fuse signals: ML confidence reinforces or weakens trigger confidence
+  4. Apply hard-escalate rules (suicidal_ideation, homicidal_ideation)
+  5. Rank by: (a) effective_confidence tier, (b) domain priority, (c) ML prob
+  6. Select recommended_flow from domain rules based on confidence tier
+  7. Return sorted list of DomainNomination objects
+
+Safety invariants:
+  - Hard-escalate domains ALWAYS nominate at HIGH confidence
+  - Negated domains are included but marked (caller decides)
+  - If ML says ESCALATION but no triggers match, still nominate with
+    a generic "unclassified_escalation" domain
+  - If triggers match a safety domain but ML says non-escalation,
+    the trigger OVERRIDES the ML (fail-open)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from decision.engine.config_loader import DecisionConfigLoader
+from decision.engine.models import (
+    ConfidenceTier,
+    DomainNomination,
+    NegationResult,
+    RiskClass,
+    TriggerMatch,
+)
+from decision.engine.trigger_engine import DomainMatchResult, TaxonomyTriggerEngine
+
+logger = logging.getLogger("decision.domain_nomination")
+
+# DriveHealthBERT label → taxonomy domain mapping hints
+# Used when ML label alone doesn't resolve to a specific domain
+_ML_LABEL_DOMAIN_HINTS: Dict[str, List[str]] = {
+    "SCHEDULING": ["scheduling", "scheduling_barrier", "missed_followup"],
+    "MEDICATION": ["medication", "medication_nonadherence"],
+    "SYMPTOM_CHECK": [],  # Too broad — rely on triggers
+    "BILLING": [],         # No taxonomy domain for billing yet
+    "GENERAL": [],
+    "ESCALATION": [],      # Rely on triggers to determine which domain
+}
+
+
+class DomainNominator:
+    """
+    Produces ranked domain nominations from ML + lexical signals.
+
+    Usage:
+        nominator = DomainNominator(config, trigger_engine)
+        nominations = nominator.nominate(
+            text="my chest is killing me",
+            ml_label="ESCALATION",
+            ml_probabilities={"ESCALATION": 0.92, ...},
+        )
+    """
+
+    def __init__(
+        self,
+        config: DecisionConfigLoader,
+        trigger_engine: TaxonomyTriggerEngine,
+    ):
+        self._config = config
+        self._trigger_engine = trigger_engine
+        self._hard_escalate: Set[str] = config.hard_escalate_domains
+        self._safety_precedence: List[str] = config.safety_precedence
+
+    def nominate(
+        self,
+        text: str,
+        ml_label: Optional[str] = None,
+        ml_probabilities: Optional[Dict[str, float]] = None,
+    ) -> List[DomainNomination]:
+        """
+        Produce ranked domain nominations for the given text.
+
+        Args:
+            text: Patient utterance (original, NOT context-prepended)
+            ml_label: DriveHealthBERT predicted label (e.g., "ESCALATION")
+            ml_probabilities: Full probability distribution from DriveHealthBERT
+
+        Returns:
+            List of DomainNomination sorted by:
+              1. Effective confidence tier (HIGH > MEDIUM > LOW)
+              2. Domain priority (higher = more urgent)
+              3. ML probability (if available)
+        """
+        ml_confidence = None
+        if ml_probabilities and ml_label:
+            ml_confidence = ml_probabilities.get(ml_label, 0.0)
+
+        # Step 1: Run taxonomy triggers
+        trigger_results = self._trigger_engine.match_all(text)
+
+        # Step 2: Build nominations from trigger results
+        nominations: List[DomainNomination] = []
+
+        for domain_name, match_result in trigger_results.items():
+            nomination = self._build_nomination(
+                domain_name=domain_name,
+                match_result=match_result,
+                ml_label=ml_label,
+                ml_confidence=ml_confidence,
+            )
+            nominations.append(nomination)
+
+        # Step 3: Handle hard-escalate domains
+        #   If any hard-escalate domain matched (even at LOW), force HIGH
+        for nom in nominations:
+            if nom.domain in self._hard_escalate and not nom.is_negated:
+                nominations = [
+                    self._force_high_confidence(n) if n.domain == nom.domain else n
+                    for n in nominations
+                ]
+
+        # Step 4: Handle ML-only signals (ML says ESCALATION but no triggers)
+        if ml_label == "ESCALATION" and ml_confidence and ml_confidence > 0.5:
+            has_safety_trigger = any(
+                not n.is_negated and n.confidence_tier >= ConfidenceTier.LOW
+                for n in nominations
+                if n.domain in set(self._safety_precedence)
+            )
+            # Check if the ML is confused by negated safety keywords:
+            # If safety domains DID match but were ALL negated, the ML is
+            # likely reacting to the keywords themselves (e.g., "I'm NOT
+            # suicidal" triggers ML ESCALATION because it sees "suicidal").
+            # In this case, trust the explicit negation over the ML signal.
+            has_negated_safety = any(
+                n.is_negated
+                for n in nominations
+                if n.domain in set(self._safety_precedence)
+            )
+            if not has_safety_trigger and not has_negated_safety:
+                # ML detected escalation but no specific domain matched
+                # (and no negated safety domains either)
+                # Create a generic nomination so it's not silently dropped
+                nominations.append(
+                    DomainNomination(
+                        domain="unclassified_escalation",
+                        display_name="Unclassified Escalation",
+                        confidence_tier=self._ml_prob_to_tier(ml_confidence),
+                        priority=50,  # Middle priority
+                        target_risk_class=RiskClass.R2,
+                        trigger_matches=(),
+                        negation_result=None,
+                        ml_label=ml_label,
+                        ml_confidence=ml_confidence,
+                        recommended_flow="handoff",
+                    )
+                )
+
+        # Step 5: Handle ML reinforcement for non-escalation labels
+        if ml_label and ml_label != "ESCALATION":
+            hint_domains = _ML_LABEL_DOMAIN_HINTS.get(ml_label, [])
+            for nom in nominations:
+                if nom.domain in hint_domains and ml_confidence:
+                    # ML confirms trigger match — boost confidence if ML is strong
+                    if ml_confidence > 0.8 and nom.confidence_tier < ConfidenceTier.HIGH:
+                        nominations = [
+                            self._boost_confidence(n) if n.domain == nom.domain else n
+                            for n in nominations
+                        ]
+
+        # Step 6: Resolve recommended_flow for each nomination
+        nominations = [self._resolve_flow(n) for n in nominations]
+
+        # Step 7: Sort
+        nominations.sort(key=self._nomination_sort_key, reverse=True)
+
+        if nominations:
+            logger.info(
+                "Domain nominations for text (len=%d): %s",
+                len(text),
+                [(n.domain, n.confidence_tier.value, n.priority) for n in nominations[:5]],
+            )
+
+        return nominations
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _build_nomination(
+        self,
+        domain_name: str,
+        match_result: DomainMatchResult,
+        ml_label: Optional[str],
+        ml_confidence: Optional[float],
+    ) -> DomainNomination:
+        """Build a DomainNomination from a DomainMatchResult."""
+        # Get target risk class from rules.yaml
+        target_risk_str = self._config.get_domain_target_risk(domain_name)
+        target_risk = None
+        if target_risk_str:
+            try:
+                target_risk = RiskClass(target_risk_str)
+            except ValueError:
+                pass
+
+        return DomainNomination(
+            domain=domain_name,
+            display_name=domain_name.replace("_", " ").title(),
+            confidence_tier=match_result.effective_confidence,
+            priority=match_result.priority,
+            target_risk_class=target_risk,
+            trigger_matches=match_result.matches,
+            negation_result=match_result.negation_result,
+            ml_label=ml_label,
+            ml_confidence=ml_confidence,
+        )
+
+    def _resolve_flow(self, nomination: DomainNomination) -> DomainNomination:
+        """Determine recommended_flow from domain decision rules."""
+        if nomination.recommended_flow:
+            return nomination
+
+        rules = self._config.get_domain_decision_rules(nomination.domain)
+        if not rules:
+            return nomination
+
+        # Find first matching rule based on confidence tier
+        for rule in rules:
+            conditions = rule.get("if", {})
+            conf_required = conditions.get("confidence")
+            if conf_required and conf_required == nomination.confidence_tier.value:
+                flow = rule.get("then", {}).get("flow")
+                if flow:
+                    return DomainNomination(
+                        domain=nomination.domain,
+                        display_name=nomination.display_name,
+                        confidence_tier=nomination.confidence_tier,
+                        priority=nomination.priority,
+                        target_risk_class=nomination.target_risk_class,
+                        trigger_matches=nomination.trigger_matches,
+                        negation_result=nomination.negation_result,
+                        ml_label=nomination.ml_label,
+                        ml_confidence=nomination.ml_confidence,
+                        recommended_flow=flow,
+                    )
+
+        return nomination
+
+    def _force_high_confidence(
+        self, nomination: DomainNomination
+    ) -> DomainNomination:
+        """Force a nomination to HIGH confidence (for hard-escalate domains)."""
+        if nomination.confidence_tier == ConfidenceTier.HIGH:
+            return nomination
+        logger.warning(
+            "HARD ESCALATE: Forcing %s to HIGH confidence (was %s)",
+            nomination.domain,
+            nomination.confidence_tier.value,
+        )
+        return DomainNomination(
+            domain=nomination.domain,
+            display_name=nomination.display_name,
+            confidence_tier=ConfidenceTier.HIGH,
+            priority=nomination.priority,
+            target_risk_class=nomination.target_risk_class,
+            trigger_matches=nomination.trigger_matches,
+            negation_result=nomination.negation_result,
+            ml_label=nomination.ml_label,
+            ml_confidence=nomination.ml_confidence,
+            recommended_flow=nomination.recommended_flow,
+        )
+
+    def _boost_confidence(
+        self, nomination: DomainNomination
+    ) -> DomainNomination:
+        """Boost confidence by one tier when ML reinforces trigger."""
+        new_tier = nomination.confidence_tier
+        if new_tier == ConfidenceTier.LOW:
+            new_tier = ConfidenceTier.MEDIUM
+        elif new_tier == ConfidenceTier.MEDIUM:
+            new_tier = ConfidenceTier.HIGH
+        if new_tier == nomination.confidence_tier:
+            return nomination
+        return DomainNomination(
+            domain=nomination.domain,
+            display_name=nomination.display_name,
+            confidence_tier=new_tier,
+            priority=nomination.priority,
+            target_risk_class=nomination.target_risk_class,
+            trigger_matches=nomination.trigger_matches,
+            negation_result=nomination.negation_result,
+            ml_label=nomination.ml_label,
+            ml_confidence=nomination.ml_confidence,
+            recommended_flow=nomination.recommended_flow,
+        )
+
+    @staticmethod
+    def _ml_prob_to_tier(prob: float) -> ConfidenceTier:
+        """Map ML probability to a confidence tier."""
+        if prob >= 0.8:
+            return ConfidenceTier.HIGH
+        elif prob >= 0.5:
+            return ConfidenceTier.MEDIUM
+        elif prob >= 0.3:
+            return ConfidenceTier.LOW
+        return ConfidenceTier.NONE
+
+    @staticmethod
+    def _nomination_sort_key(
+        nom: DomainNomination,
+    ) -> Tuple[int, int, float]:
+        """Sort key: (confidence_rank, priority, ml_confidence)."""
+        conf_rank = {
+            ConfidenceTier.HIGH: 3,
+            ConfidenceTier.MEDIUM: 2,
+            ConfidenceTier.LOW: 1,
+            ConfidenceTier.NONE: 0,
+        }
+        return (
+            conf_rank.get(nom.confidence_tier, 0),
+            nom.priority,
+            nom.ml_confidence or 0.0,
+        )

decision/engine/fhir_context.py

@@ -0,0 +1,506 @@
+"""
+FHIR Context Loader (Phase 3A).
+
+Builds a PatientContext from FHIR R4 resources for context-aware risk rules.
+
+Key features:
+  - Minimum necessary principle: only fetch resources needed for the active wedge
+  - Lookback periods: filter by date relevance
+  - Freshness detection: warn when clinical data is stale
+  - ICD-10 condition matching for risk rule evaluation
+  - Medication count for polypharmacy detection
+  - Pre-populated slot extraction for journey agendas
+
+This module provides:
+  1. PatientContext dataclass — normalized patient data for risk evaluation
+  2. PatientContextBuilder — builds context from raw FHIR bundles
+  3. FHIRClient (abstract) — interface for FHIR data fetching (Phase 3 full impl)
+
+Safety invariants:
+  - Missing context = fail closed (context-dependent rules don't fire)
+  - Stale data is flagged but still used (better than no data)
+  - PHI is never logged — only ICD codes and counts
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List, Optional, Set
+
+from decision.engine.config_loader import DecisionConfigLoader
+
+logger = logging.getLogger("decision.fhir_context")
+
+
+# ---------------------------------------------------------------------------
+# Patient Context
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PatientContext:
+    """
+    Normalized patient context for clinical decision-making.
+
+    Built from FHIR resources. Used by RiskClassifier for context-aware rules.
+    """
+    patient_id: str = ""
+
+    # Conditions (ICD-10 codes of active problems)
+    active_conditions: List[str] = field(default_factory=list)
+    # Convenience sets for common condition groups
+    has_chf: bool = False             # I50.*
+    has_copd: bool = False            # J44.*
+    has_diabetes: bool = False        # E10.*, E11.*
+    has_ckd: bool = False             # N18.*
+    has_cancer: bool = False          # C00-C97
+    has_afib: bool = False            # I48.*
+    has_depression: bool = False      # F32.*, F33.*
+    has_anxiety: bool = False         # F41.*
+
+    # Medications
+    active_medication_count: int = 0
+    active_medication_names: List[str] = field(default_factory=list)
+    is_on_anticoagulant: bool = False
+    is_on_insulin: bool = False
+    is_on_opioid: bool = False
+
+    # Demographics
+    age: Optional[int] = None
+    is_elderly: bool = False          # 65+
+    is_very_elderly: bool = False     # 75+
+
+    # Recent vitals
+    last_bp_systolic: Optional[float] = None
+    last_bp_diastolic: Optional[float] = None
+    last_heart_rate: Optional[float] = None
+    last_weight_kg: Optional[float] = None
+    last_glucose: Optional[float] = None
+    last_temperature: Optional[float] = None
+
+    # Recent encounter
+    days_since_discharge: Optional[int] = None
+    discharge_diagnosis_codes: List[str] = field(default_factory=list)
+
+    # Allergies
+    allergy_count: int = 0
+    drug_allergies: List[str] = field(default_factory=list)
+
+    # Appointments
+    has_upcoming_appointment: bool = False
+    next_appointment_days: Optional[int] = None
+
+    # Freshness / staleness warnings
+    stale_resources: List[str] = field(default_factory=list)
+    context_timestamp: Optional[datetime] = None
+
+    def to_risk_context(self) -> Dict[str, Any]:
+        """
+        Convert to the dict format expected by RiskClassifier.assess(patient_context=...).
+        """
+        return {
+            "patient_id": self.patient_id,
+            "active_conditions": self.active_conditions,
+            "active_medication_count": self.active_medication_count,
+            "has_chf": self.has_chf,
+            "has_copd": self.has_copd,
+            "has_diabetes": self.has_diabetes,
+            "has_ckd": self.has_ckd,
+            "has_cancer": self.has_cancer,
+            "has_afib": self.has_afib,
+            "has_depression": self.has_depression,
+            "has_anxiety": self.has_anxiety,
+            "is_on_anticoagulant": self.is_on_anticoagulant,
+            "is_on_insulin": self.is_on_insulin,
+            "is_on_opioid": self.is_on_opioid,
+            "age": self.age,
+            "is_elderly": self.is_elderly,
+            "is_very_elderly": self.is_very_elderly,
+            "days_since_discharge": self.days_since_discharge,
+            "stale_resources": self.stale_resources,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Patient Context Builder
+# ---------------------------------------------------------------------------
+
+# ICD-10 pattern groups for condition detection
+_CONDITION_GROUPS = {
+    "has_chf": ["I50"],
+    "has_copd": ["J44"],
+    "has_diabetes": ["E10", "E11"],
+    "has_ckd": ["N18"],
+    "has_cancer": [f"C{i:02d}" for i in range(98)],  # C00-C97
+    "has_afib": ["I48"],
+    "has_depression": ["F32", "F33"],
+    "has_anxiety": ["F41"],
+}
+
+# Medication class detection (by name substring)
+_ANTICOAGULANTS = {"warfarin", "coumadin", "heparin", "enoxaparin", "lovenox",
+                   "apixaban", "eliquis", "rivaroxaban", "xarelto", "dabigatran", "pradaxa"}
+_INSULINS = {"insulin", "humalog", "novolog", "lantus", "levemir", "tresiba",
+             "basaglar", "admelog", "fiasp", "toujeo"}
+_OPIOIDS = {"oxycodone", "hydrocodone", "morphine", "fentanyl", "codeine",
+            "tramadol", "methadone", "hydromorphone", "oxymorphone", "dilaudid",
+            "percocet", "vicodin", "norco"}
+
+
+class PatientContextBuilder:
+    """
+    Builds a PatientContext from FHIR resource bundles.
+
+    Usage:
+        builder = PatientContextBuilder(config)
+        context = builder.build_from_fhir(
+            patient_id="P-123",
+            fhir_bundle=bundle_dict,
+            wedge_type="pde",
+        )
+    """
+
+    def __init__(self, config: DecisionConfigLoader):
+        self._config = config
+        self._fhir_mappings = config.fhir_mappings
+        self._freshness_thresholds = self._fhir_mappings.get("freshness_thresholds", {})
+
+    def build_from_fhir(
+        self,
+        patient_id: str,
+        fhir_bundle: Dict[str, Any],
+        wedge_type: Optional[str] = None,
+    ) -> PatientContext:
+        """
+        Build PatientContext from a FHIR bundle response.
+
+        Args:
+            patient_id: Patient identifier
+            fhir_bundle: FHIR Bundle resource (or dict of resource lists)
+            wedge_type: Active wedge for minimum necessary filtering
+
+        Returns:
+            PatientContext ready for risk rule evaluation
+        """
+        ctx = PatientContext(
+            patient_id=patient_id,
+            context_timestamp=datetime.now(timezone.utc),
+        )
+
+        # Extract resources from bundle
+        resources = self._extract_resources(fhir_bundle)
+
+        # Build context from each resource type
+        self._process_patient(ctx, resources.get("Patient", []))
+        self._process_conditions(ctx, resources.get("Condition", []))
+        self._process_medications(ctx, resources.get("MedicationRequest", []))
+        self._process_observations(ctx, resources.get("Observation", []))
+        self._process_allergies(ctx, resources.get("AllergyIntolerance", []))
+        self._process_encounters(ctx, resources.get("Encounter", []))
+        self._process_appointments(ctx, resources.get("Appointment", []))
+
+        # Check freshness
+        self._check_freshness(ctx, resources)
+
+        logger.info(
+            "PatientContext built: patient=%s conditions=%d meds=%d age=%s chf=%s copd=%s dm=%s",
+            patient_id,
+            len(ctx.active_conditions),
+            ctx.active_medication_count,
+            ctx.age,
+            ctx.has_chf,
+            ctx.has_copd,
+            ctx.has_diabetes,
+        )
+
+        return ctx
+
+    def build_from_dict(
+        self,
+        patient_id: str,
+        data: Dict[str, Any],
+    ) -> PatientContext:
+        """
+        Build PatientContext from a pre-processed dict (e.g., from API request).
+
+        This allows callers to pass patient context directly without FHIR.
+        """
+        ctx = PatientContext(
+            patient_id=patient_id,
+            context_timestamp=datetime.now(timezone.utc),
+        )
+
+        ctx.active_conditions = data.get("active_conditions", [])
+        ctx.active_medication_count = data.get("active_medication_count", 0)
+        ctx.active_medication_names = data.get("active_medication_names", [])
+        ctx.age = data.get("age")
+        ctx.days_since_discharge = data.get("days_since_discharge")
+
+        # Derive flags from conditions
+        self._set_condition_flags(ctx)
+
+        # Derive flags from medications
+        self._set_medication_flags(ctx)
+
+        # Age flags
+        if ctx.age:
+            ctx.is_elderly = ctx.age >= 65
+            ctx.is_very_elderly = ctx.age >= 75
+
+        return ctx
+
+    # ------------------------------------------------------------------
+    # Resource processing
+    # ------------------------------------------------------------------
+
+    def _extract_resources(
+        self, bundle: Dict[str, Any]
+    ) -> Dict[str, List[Dict[str, Any]]]:
+        """Extract resources from a FHIR Bundle, grouped by resourceType."""
+        resources: Dict[str, List[Dict[str, Any]]] = {}
+
+        # Handle standard FHIR Bundle format
+        entries = bundle.get("entry", [])
+        for entry in entries:
+            resource = entry.get("resource", {})
+            rtype = resource.get("resourceType", "Unknown")
+            resources.setdefault(rtype, []).append(resource)
+
+        # Also handle flat dict format {resourceType: [resources]}
+        for key, value in bundle.items():
+            if key != "entry" and isinstance(value, list):
+                resources.setdefault(key, []).extend(value)
+
+        return resources
+
+    def _process_patient(
+        self, ctx: PatientContext, patients: List[Dict[str, Any]]
+    ) -> None:
+        if not patients:
+            return
+        patient = patients[0]
+        birth_date = patient.get("birthDate")
+        if birth_date:
+            try:
+                dob = datetime.strptime(birth_date, "%Y-%m-%d")
+                today = datetime.now()
+                ctx.age = today.year - dob.year - ((today.month, today.day) < (dob.month, dob.day))
+                ctx.is_elderly = ctx.age >= 65
+                ctx.is_very_elderly = ctx.age >= 75
+            except (ValueError, TypeError):
+                pass
+
+    def _process_conditions(
+        self, ctx: PatientContext, conditions: List[Dict[str, Any]]
+    ) -> None:
+        for condition in conditions:
+            # Only active conditions
+            clinical_status = condition.get("clinicalStatus", {})
+            if isinstance(clinical_status, dict):
+                codings = clinical_status.get("coding", [])
+                status_code = codings[0].get("code", "") if codings else ""
+            else:
+                status_code = str(clinical_status)
+
+            if status_code and status_code not in ("active", "recurrence", "relapse"):
+                continue
+
+            # Extract ICD-10 codes
+            code_concept = condition.get("code", {})
+            for coding in code_concept.get("coding", []):
+                system = coding.get("system", "")
+                code = coding.get("code", "")
+                if "icd" in system.lower() or code:
+                    ctx.active_conditions.append(code)
+
+        self._set_condition_flags(ctx)
+
+    def _set_condition_flags(self, ctx: PatientContext) -> None:
+        """Set boolean condition flags from ICD-10 codes."""
+        for flag_name, prefixes in _CONDITION_GROUPS.items():
+            has_condition = any(
+                any(code.startswith(prefix) for prefix in prefixes)
+                for code in ctx.active_conditions
+            )
+            setattr(ctx, flag_name, has_condition)
+
+    def _process_medications(
+        self, ctx: PatientContext, medications: List[Dict[str, Any]]
+    ) -> None:
+        active_meds = []
+        for med in medications:
+            status = med.get("status", "")
+            if status not in ("active", "completed"):
+                continue
+            med_name = ""
+            med_concept = med.get("medicationCodeableConcept", {})
+            if med_concept:
+                med_name = med_concept.get("text", "")
+                if not med_name:
+                    codings = med_concept.get("coding", [])
+                    if codings:
+                        med_name = codings[0].get("display", "")
+            if med_name:
+                active_meds.append(med_name)
+
+        ctx.active_medication_names = active_meds
+        ctx.active_medication_count = len(active_meds)
+        self._set_medication_flags(ctx)
+
+    def _set_medication_flags(self, ctx: PatientContext) -> None:
+        """Set medication class flags from med names."""
+        names_lower = {n.lower() for n in ctx.active_medication_names}
+        ctx.is_on_anticoagulant = bool(names_lower & _ANTICOAGULANTS)
+        ctx.is_on_insulin = bool(names_lower & _INSULINS)
+        ctx.is_on_opioid = bool(names_lower & _OPIOIDS)
+
+    def _process_observations(
+        self, ctx: PatientContext, observations: List[Dict[str, Any]]
+    ) -> None:
+        # Sort by date descending to get most recent first
+        observations.sort(
+            key=lambda o: o.get("effectiveDateTime", ""),
+            reverse=True,
+        )
+
+        for obs in observations:
+            code_concept = obs.get("code", {})
+            codings = code_concept.get("coding", [])
+            loinc_code = ""
+            for coding in codings:
+                if "loinc" in coding.get("system", "").lower():
+                    loinc_code = coding.get("code", "")
+                    break
+
+            value = obs.get("valueQuantity", {}).get("value")
+            if value is None:
+                continue
+
+            # Map LOINC codes to context fields (most recent only)
+            if loinc_code == "8480-6" and ctx.last_bp_systolic is None:  # Systolic BP
+                ctx.last_bp_systolic = float(value)
+            elif loinc_code == "8462-4" and ctx.last_bp_diastolic is None:  # Diastolic BP
+                ctx.last_bp_diastolic = float(value)
+            elif loinc_code == "8867-4" and ctx.last_heart_rate is None:  # Heart rate
+                ctx.last_heart_rate = float(value)
+            elif loinc_code == "29463-7" and ctx.last_weight_kg is None:  # Weight
+                ctx.last_weight_kg = float(value)
+            elif loinc_code in ("2339-0", "2345-7") and ctx.last_glucose is None:  # Glucose
+                ctx.last_glucose = float(value)
+            elif loinc_code == "8310-5" and ctx.last_temperature is None:  # Temperature
+                ctx.last_temperature = float(value)
+
+    def _process_allergies(
+        self, ctx: PatientContext, allergies: List[Dict[str, Any]]
+    ) -> None:
+        active_allergies = [
+            a for a in allergies
+            if a.get("clinicalStatus", {}).get("coding", [{}])[0].get("code") == "active"
+            or not a.get("clinicalStatus")
+        ]
+        ctx.allergy_count = len(active_allergies)
+
+        for allergy in active_allergies:
+            category = allergy.get("category", [])
+            if "medication" in category:
+                substance = allergy.get("code", {}).get("text", "")
+                if substance:
+                    ctx.drug_allergies.append(substance)
+
+    def _process_encounters(
+        self, ctx: PatientContext, encounters: List[Dict[str, Any]]
+    ) -> None:
+        # Find most recent discharge
+        encounters.sort(
+            key=lambda e: e.get("period", {}).get("end", ""),
+            reverse=True,
+        )
+
+        for enc in encounters:
+            period = enc.get("period", {})
+            end_date = period.get("end")
+            if not end_date:
+                continue
+            try:
+                discharge_dt = datetime.fromisoformat(end_date.replace("Z", "+00:00"))
+                now = datetime.now(timezone.utc)
+                delta = now - discharge_dt
+                ctx.days_since_discharge = delta.days
+
+                # Extract discharge diagnosis codes
+                diagnoses = enc.get("diagnosis", [])
+                for diag in diagnoses:
+                    code = diag.get("condition", {}).get("reference", "")
+                    if code:
+                        ctx.discharge_diagnosis_codes.append(code)
+                break  # Most recent only
+            except (ValueError, TypeError):
+                continue
+
+    def _process_appointments(
+        self, ctx: PatientContext, appointments: List[Dict[str, Any]]
+    ) -> None:
+        now = datetime.now(timezone.utc)
+        for appt in appointments:
+            status = appt.get("status", "")
+            if status in ("cancelled", "noshow", "entered-in-error"):
+                continue
+            start = appt.get("start")
+            if not start:
+                continue
+            try:
+                appt_dt = datetime.fromisoformat(start.replace("Z", "+00:00"))
+                if appt_dt > now:
+                    ctx.has_upcoming_appointment = True
+                    delta = appt_dt - now
+                    if ctx.next_appointment_days is None or delta.days < ctx.next_appointment_days:
+                        ctx.next_appointment_days = delta.days
+            except (ValueError, TypeError):
+                continue
+
+    def _check_freshness(
+        self, ctx: PatientContext, resources: Dict[str, List[Dict[str, Any]]]
+    ) -> None:
+        """Check resource freshness against configured thresholds."""
+        now = datetime.now(timezone.utc)
+
+        for resource_type, threshold_hours in self._freshness_thresholds.items():
+            if threshold_hours is None:
+                continue
+
+            # Map compound types (e.g., "Observation_laboratory") to base type
+            base_type = resource_type.split("_")[0]
+            entries = resources.get(base_type, [])
+            if not entries:
+                continue
+
+            # Find most recent entry date
+            latest_date = None
+            for entry in entries:
+                date_str = (
+                    entry.get("effectiveDateTime")
+                    or entry.get("authoredOn")
+                    or entry.get("recordedDate")
+                    or entry.get("meta", {}).get("lastUpdated")
+                )
+                if date_str:
+                    try:
+                        dt = datetime.fromisoformat(date_str.replace("Z", "+00:00"))
+                        if latest_date is None or dt > latest_date:
+                            latest_date = dt
+                    except (ValueError, TypeError):
+                        continue
+
+            if latest_date:
+                hours_old = (now - latest_date).total_seconds() / 3600
+                if hours_old > threshold_hours:
+                    ctx.stale_resources.append(
+                        f"{resource_type} (last updated {hours_old:.0f}h ago, threshold {threshold_hours}h)"
+                    )
+                    logger.warning(
+                        "Stale FHIR data: %s is %.0fh old (threshold: %dh)",
+                        resource_type,
+                        hours_old,
+                        threshold_hours,
+                    )

decision/engine/flow_engine.py

@@ -0,0 +1,763 @@
+"""
+Flow Execution Engine (Phase 2A).
+
+Manages multi-step clinical conversation flows with:
+  - State machine for flow step progression
+  - Slot tracking and validation
+  - Response spec enforcement (must_include, must_not, max_questions)
+  - Primitive sequence execution (greeting → identity_verify → consent)
+  - Domain-specific flow routing from risk assessment
+  - Exit condition evaluation
+
+Safety invariants:
+  - Escalation flows CANNOT be interrupted or rolled back
+  - Hard-escalate domains skip screening and go directly to escalate_r3
+  - If unclear at any step, fail open (escalate, not suppress)
+  - Response specs enforce must_not constraints — these are NEVER relaxed
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from decision.engine.config_loader import DecisionConfigLoader
+from decision.engine.models import (
+    CallPhase,
+    ConfidenceTier,
+    ConversationFlow,
+    FlowStep,
+    FlowType,
+    ResponseSpec,
+    RiskAssessment,
+    RiskClass,
+    SessionState,
+    SlotState,
+    TurnOutcome,
+)
+
+logger = logging.getLogger("decision.flow_engine")
+
+
+# ---------------------------------------------------------------------------
+# Flow Resolution
+# ---------------------------------------------------------------------------
+
+class FlowResolver:
+    """
+    Resolves which conversation flow to execute based on the current
+    session state, risk assessment, and domain rules.
+    """
+
+    def __init__(self, config: DecisionConfigLoader):
+        self._config = config
+        self._primitives = config.primitives
+        self._taxonomy_flows = config.taxonomy_flows
+        self._taxonomy_rules = config.taxonomy_rules
+        self._primitive_sequence = config.global_rules.get("primitive_sequence", [])
+        self._fallback_flow = config.global_rules.get("fallback_flow", "primitives/clarify")
+
+    def resolve_initial_flow(self, session: SessionState) -> Optional[FlowDefinition]:
+        """Resolve the first flow to execute when a call starts."""
+        if self._primitive_sequence:
+            first = self._primitive_sequence[0]
+            return self._load_primitive(first)
+        return None
+
+    def resolve_next_flow(
+        self,
+        session: SessionState,
+        assessment: Optional[RiskAssessment] = None,
+        current_exit: Optional[str] = None,
+    ) -> Optional[FlowDefinition]:
+        """
+        Resolve the next flow based on current state and exit condition.
+
+        Priority order:
+          1. Hard-escalate → escalate_r3 (immediate, cannot be overridden)
+          2. R3 assessment → domain escalate_r3 flow
+          3. R2 assessment → domain escalate_r2 flow
+          4. Explicit exit rule (on_complete, on_refused, etc.)
+          5. Primitive sequence (if still in opening)
+          6. Domain-specific recommended_flow from assessment
+          7. Fallback → clarify
+        """
+        # 1. Hard escalate overrides everything
+        if assessment and assessment.hard_escalate:
+            domain = assessment.primary_domain or "suicidal_ideation"
+            flow = self._load_domain_flow(domain, "escalate_r3")
+            if flow:
+                logger.warning("HARD ESCALATE: routing to %s/escalate_r3", domain)
+                return flow
+            # Fallback to generic handoff
+            return self._load_primitive("handoff")
+
+        # 2-3. Risk-based routing
+        if assessment and assessment.risk_class == RiskClass.R3:
+            domain = assessment.primary_domain
+            if domain:
+                flow = self._load_domain_flow(domain, "escalate_r3")
+                if flow:
+                    return flow
+            return self._load_primitive("handoff")
+
+        if assessment and assessment.risk_class == RiskClass.R2:
+            domain = assessment.primary_domain
+            if domain:
+                flow = self._load_domain_flow(domain, "escalate_r2")
+                if flow:
+                    return flow
+            return self._load_primitive("handoff")
+
+        # 4. Explicit exit rule
+        if current_exit:
+            return self._resolve_exit(current_exit, session)
+
+        # 5. Check if still in primitive sequence
+        prim_flow = self._advance_primitive_sequence(session)
+        if prim_flow:
+            return prim_flow
+
+        # 6. Domain recommended flow
+        if assessment and assessment.recommended_flow:
+            domain = assessment.primary_domain
+            if domain:
+                flow = self._load_domain_flow(domain, assessment.recommended_flow)
+                if flow:
+                    return flow
+
+        # 7. Fallback
+        return self._load_primitive("clarify")
+
+    def _resolve_exit(
+        self, exit_key: str, session: SessionState
+    ) -> Optional[FlowDefinition]:
+        """Resolve an exit rule like 'on_complete', 'on_refused', etc."""
+        # Special exit targets
+        if exit_key == "end":
+            return None  # Session over
+        if exit_key == "re_evaluate":
+            return None  # Signal to re-run assessment
+        if exit_key == "evaluate_risk":
+            return None  # Signal to run risk evaluation
+        if exit_key == "evaluate_concern":
+            return None  # Signal to evaluate a patient concern
+
+        # Try as primitive name
+        prim = self._load_primitive(exit_key)
+        if prim:
+            return prim
+
+        # Try as domain flow (format: "domain/flow_id" or just "flow_id")
+        if "/" in exit_key:
+            domain, flow_id = exit_key.split("/", 1)
+            return self._load_domain_flow(domain, flow_id)
+
+        return None
+
+    def _advance_primitive_sequence(
+        self, session: SessionState
+    ) -> Optional[FlowDefinition]:
+        """Check if the session still needs to complete primitive sequence."""
+        if session.call_phase != CallPhase.SESSION_START:
+            return None
+
+        completed = set(session.domain_history)
+        for prim_name in self._primitive_sequence:
+            if prim_name not in completed:
+                return self._load_primitive(prim_name)
+
+        # All primitives complete — advance to active call phase
+        return None
+
+    def _load_primitive(self, name: str) -> Optional[FlowDefinition]:
+        """Load a primitive flow definition by name."""
+        data = self._primitives.get(name)
+        if not data:
+            return None
+        return FlowDefinition.from_yaml(data, source=f"primitives/{name}")
+
+    def _load_domain_flow(
+        self, domain: str, flow_id: str
+    ) -> Optional[FlowDefinition]:
+        """Load a domain-specific flow definition."""
+        domain_flows = self._taxonomy_flows.get(domain, {})
+        data = domain_flows.get(flow_id)
+        if not data:
+            return None
+        return FlowDefinition.from_yaml(data, source=f"taxonomy/{domain}/{flow_id}")
+
+
+# ---------------------------------------------------------------------------
+# Flow Definition (parsed from YAML)
+# ---------------------------------------------------------------------------
+
+class FlowDefinition:
+    """A parsed conversation flow with steps and exit rules."""
+
+    def __init__(
+        self,
+        flow_id: str,
+        flow_type: str,
+        domain: Optional[str],
+        required_slots: List[str],
+        steps: List[FlowStepDef],
+        exit_rules: Dict[str, str],
+        source: str = "",
+    ):
+        self.flow_id = flow_id
+        self.flow_type = flow_type
+        self.domain = domain
+        self.required_slots = required_slots
+        self.steps = steps
+        self.exit_rules = exit_rules
+        self.source = source
+
+    @classmethod
+    def from_yaml(cls, data: Dict[str, Any], source: str = "") -> FlowDefinition:
+        """Parse a flow definition from YAML data."""
+        flow_id = data.get("flow_id", "unknown")
+        flow_type = data.get("type", "primitive")
+        domain = data.get("domain")
+        required_slots = data.get("required_slots", [])
+        exit_rules = data.get("exit", {})
+
+        steps = []
+        for action in data.get("actions", []):
+            step = FlowStepDef.from_yaml(action)
+            steps.append(step)
+
+        return cls(
+            flow_id=flow_id,
+            flow_type=flow_type,
+            domain=domain,
+            required_slots=required_slots,
+            steps=steps,
+            exit_rules=exit_rules,
+            source=source,
+        )
+
+    @property
+    def step_count(self) -> int:
+        return len(self.steps)
+
+    def get_step(self, index: int) -> Optional[FlowStepDef]:
+        if 0 <= index < len(self.steps):
+            return self.steps[index]
+        return None
+
+    def __repr__(self) -> str:
+        return f"FlowDefinition({self.flow_id}, type={self.flow_type}, steps={self.step_count})"
+
+
+class FlowStepDef:
+    """A single step in a flow, parsed from YAML."""
+
+    def __init__(
+        self,
+        step_number: int,
+        step_type: str,
+        response_spec: ResponseSpecDef,
+        collects: List[str],
+        handoff_target: Optional[str] = None,
+        handoff_urgency: Optional[str] = None,
+    ):
+        self.step_number = step_number
+        self.step_type = step_type
+        self.response_spec = response_spec
+        self.collects = collects
+        self.handoff_target = handoff_target
+        self.handoff_urgency = handoff_urgency
+
+    @classmethod
+    def from_yaml(cls, data: Dict[str, Any]) -> FlowStepDef:
+        step_number = data.get("step", 0)
+        step_type = data.get("type", "respond")
+        spec_data = data.get("response_spec", {})
+        response_spec = ResponseSpecDef.from_yaml(spec_data)
+        collects = data.get("collects", [])
+        handoff_target = data.get("target")
+        handoff_urgency = data.get("urgency")
+
+        return cls(
+            step_number=step_number,
+            step_type=step_type,
+            response_spec=response_spec,
+            collects=collects,
+            handoff_target=handoff_target,
+            handoff_urgency=handoff_urgency,
+        )
+
+
+class ResponseSpecDef:
+    """LLM response constraints parsed from YAML."""
+
+    def __init__(
+        self,
+        spec_id: str,
+        goal: str,
+        tone: str,
+        must_include: List[str],
+        must_ask: List[str],
+        must_not: List[str],
+        max_questions: int,
+    ):
+        self.spec_id = spec_id
+        self.goal = goal
+        self.tone = tone
+        self.must_include = must_include
+        self.must_ask = must_ask
+        self.must_not = must_not
+        self.max_questions = max_questions
+
+    @classmethod
+    def from_yaml(cls, data: Dict[str, Any]) -> ResponseSpecDef:
+        return cls(
+            spec_id=data.get("id", ""),
+            goal=data.get("goal", ""),
+            tone=data.get("tone", "professional"),
+            must_include=data.get("must_include", []),
+            must_ask=data.get("must_ask", []),
+            must_not=data.get("must_not", []),
+            max_questions=data.get("max_questions", 0),
+        )
+
+    def validate_response(self, response_text: str) -> List[str]:
+        """
+        Validate an LLM-generated response against this spec.
+        Returns list of violations (empty = valid).
+        """
+        violations = []
+        response_lower = response_text.lower()
+
+        # Check must_include
+        for phrase in self.must_include:
+            if phrase.lower() not in response_lower:
+                violations.append(f"MISSING required phrase: '{phrase}'")
+
+        # Check must_not — SAFETY CRITICAL, never relaxed
+        for phrase in self.must_not:
+            if phrase.lower() in response_lower:
+                violations.append(f"FORBIDDEN phrase found: '{phrase}'")
+
+        # Check max_questions (count question marks)
+        question_count = response_text.count("?")
+        if question_count > self.max_questions and self.max_questions >= 0:
+            violations.append(
+                f"Too many questions: {question_count} > max {self.max_questions}"
+            )
+
+        return violations
+
+    def to_prompt_constraints(self) -> str:
+        """Generate constraint text for LLM prompt injection."""
+        lines = [f"Goal: {self.goal}", f"Tone: {self.tone}"]
+        if self.must_include:
+            lines.append(f"Must include: {', '.join(self.must_include)}")
+        if self.must_ask:
+            lines.append(f"Must ask about: {', '.join(self.must_ask)}")
+        if self.must_not:
+            lines.append(f"NEVER say: {', '.join(self.must_not)}")
+        if self.max_questions >= 0:
+            lines.append(f"Maximum questions: {self.max_questions}")
+        return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Flow Execution Engine
+# ---------------------------------------------------------------------------
+
+class FlowEngine:
+    """
+    Executes conversation flows and manages session state.
+
+    Usage:
+        engine = FlowEngine(config)
+        session = engine.create_session("session-123")
+        
+        # Start call
+        result = engine.start_call(session)
+        # result.response_spec has what Avery should say
+        
+        # Process patient response
+        result = engine.process_turn(session, patient_text, assessment)
+        # result tells you: next response_spec, slots collected, flow status
+    """
+
+    def __init__(self, config: DecisionConfigLoader):
+        self._config = config
+        self._resolver = FlowResolver(config)
+        self._sessions: Dict[str, SessionState] = {}
+
+    def create_session(
+        self,
+        session_id: str,
+        patient_id: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+    ) -> SessionState:
+        """Create a new call session."""
+        session = SessionState(
+            session_id=session_id,
+            patient_id=patient_id,
+            tenant_id=tenant_id,
+            call_phase=CallPhase.SESSION_START,
+        )
+        self._sessions[session_id] = session
+        logger.info("Session created: %s (patient=%s, tenant=%s)", session_id, patient_id, tenant_id)
+        return session
+
+    def get_session(self, session_id: str) -> Optional[SessionState]:
+        """Retrieve an existing session."""
+        return self._sessions.get(session_id)
+
+    def destroy_session(self, session_id: str) -> None:
+        """Destroy a session."""
+        self._sessions.pop(session_id, None)
+
+    def start_call(self, session: SessionState) -> TurnResult:
+        """
+        Start a new call — returns the first flow step (greeting).
+        """
+        flow = self._resolver.resolve_initial_flow(session)
+        if not flow:
+            return TurnResult(
+                outcome=TurnOutcome.END,
+                message="No initial flow available",
+            )
+
+        session.current_flow = flow.flow_id
+        session.current_step = 0
+
+        step = flow.get_step(0)
+        if not step:
+            return TurnResult(outcome=TurnOutcome.END, message="Flow has no steps")
+
+        return TurnResult(
+            outcome=TurnOutcome.PROCEED,
+            flow_id=flow.flow_id,
+            flow_type=flow.flow_type,
+            step_number=0,
+            step_type=step.step_type,
+            response_spec=step.response_spec,
+            collects=step.collects,
+            handoff_target=step.handoff_target,
+            handoff_urgency=step.handoff_urgency,
+        )
+
+    def process_turn(
+        self,
+        session: SessionState,
+        patient_text: str,
+        assessment: Optional[RiskAssessment] = None,
+        extracted_slots: Optional[Dict[str, Any]] = None,
+    ) -> TurnResult:
+        """
+        Process a patient turn and determine the next action.
+
+        Args:
+            session: Current session state
+            patient_text: What the patient said
+            assessment: Risk assessment from Phase 1 engine
+            extracted_slots: Slots extracted from patient text (by NLU)
+
+        Returns:
+            TurnResult with next response_spec or escalation action
+        """
+        session.turn_count += 1
+
+        # Update slots from extracted values
+        if extracted_slots:
+            for k, v in extracted_slots.items():
+                session.slots.set_slot(k, v)
+
+        # SAFETY CHECK: If assessment triggers R3/hard_escalate, interrupt immediately
+        if assessment and (assessment.hard_escalate or assessment.risk_class == RiskClass.R3):
+            return self._handle_emergency_escalation(session, assessment)
+
+        if assessment and assessment.risk_class == RiskClass.R2:
+            return self._handle_nurse_transfer(session, assessment)
+
+        # Get current flow
+        current_flow = self._get_current_flow(session)
+        if not current_flow:
+            # No active flow — resolve from assessment
+            flow = self._resolver.resolve_next_flow(session, assessment)
+            if not flow:
+                return TurnResult(outcome=TurnOutcome.END, message="No applicable flow")
+            return self._enter_flow(session, flow)
+
+        # Advance to next step in current flow
+        return self._advance_flow(session, current_flow, assessment)
+
+    def _handle_emergency_escalation(
+        self, session: SessionState, assessment: RiskAssessment
+    ) -> TurnResult:
+        """Handle R3 / hard-escalate — interrupt everything, route to escalation."""
+        domain = assessment.primary_domain or "unknown"
+        session.call_phase = CallPhase.ENDED
+
+        # Try to load domain-specific escalation flow
+        flow = self._resolver.resolve_next_flow(session, assessment)
+        if flow and flow.steps:
+            step = flow.get_step(0)
+            logger.warning(
+                "EMERGENCY ESCALATION: session=%s domain=%s risk=%s",
+                session.session_id, domain, assessment.risk_class.value,
+            )
+            return TurnResult(
+                outcome=TurnOutcome.ESCALATE,
+                flow_id=flow.flow_id,
+                flow_type=flow.flow_type,
+                step_number=0,
+                step_type=step.step_type if step else "respond",
+                response_spec=step.response_spec if step else None,
+                handoff_target=step.handoff_target if step else "clinical_nurse",
+                handoff_urgency="immediate",
+                risk_class=assessment.risk_class,
+                domain=domain,
+                message=f"R3 EMERGENCY: {domain}",
+            )
+
+        # Fallback: generic escalation
+        return TurnResult(
+            outcome=TurnOutcome.ESCALATE,
+            handoff_target="clinical_nurse",
+            handoff_urgency="immediate",
+            risk_class=assessment.risk_class,
+            domain=domain,
+            message=f"R3 EMERGENCY: {domain} — transfer to nurse immediately",
+        )
+
+    def _handle_nurse_transfer(
+        self, session: SessionState, assessment: RiskAssessment
+    ) -> TurnResult:
+        """Handle R2 — warm transfer to nurse."""
+        domain = assessment.primary_domain or "unknown"
+
+        flow = self._resolver.resolve_next_flow(session, assessment)
+        if flow and flow.steps:
+            step = flow.get_step(0)
+            return TurnResult(
+                outcome=TurnOutcome.HANDOFF,
+                flow_id=flow.flow_id,
+                flow_type=flow.flow_type,
+                step_number=0,
+                step_type=step.step_type if step else "respond",
+                response_spec=step.response_spec if step else None,
+                handoff_target=step.handoff_target if step else "clinical_nurse",
+                handoff_urgency="soon",
+                risk_class=assessment.risk_class,
+                domain=domain,
+                message=f"R2: {domain} — schedule nurse callback",
+            )
+
+        return TurnResult(
+            outcome=TurnOutcome.HANDOFF,
+            handoff_target="clinical_nurse",
+            handoff_urgency="soon",
+            risk_class=assessment.risk_class,
+            domain=domain,
+            message=f"R2: {domain} — schedule nurse callback",
+        )
+
+    def _enter_flow(self, session: SessionState, flow: FlowDefinition) -> TurnResult:
+        """Enter a new flow and return the first step."""
+        session.current_flow = flow.flow_id
+        session.current_step = 0
+        session.domain_history.append(flow.flow_id)
+
+        step = flow.get_step(0)
+        if not step:
+            return TurnResult(outcome=TurnOutcome.PROCEED, message="Flow has no steps")
+
+        return TurnResult(
+            outcome=TurnOutcome.PROCEED,
+            flow_id=flow.flow_id,
+            flow_type=flow.flow_type,
+            step_number=0,
+            step_type=step.step_type,
+            response_spec=step.response_spec,
+            collects=step.collects,
+            handoff_target=step.handoff_target,
+            handoff_urgency=step.handoff_urgency,
+        )
+
+    def _advance_flow(
+        self,
+        session: SessionState,
+        flow: FlowDefinition,
+        assessment: Optional[RiskAssessment],
+    ) -> TurnResult:
+        """Advance to the next step in the current flow."""
+        next_step_idx = session.current_step + 1
+
+        if next_step_idx < flow.step_count:
+            # Move to next step
+            session.current_step = next_step_idx
+            step = flow.get_step(next_step_idx)
+
+            return TurnResult(
+                outcome=TurnOutcome.PROCEED,
+                flow_id=flow.flow_id,
+                flow_type=flow.flow_type,
+                step_number=next_step_idx,
+                step_type=step.step_type,
+                response_spec=step.response_spec,
+                collects=step.collects,
+                handoff_target=step.handoff_target,
+                handoff_urgency=step.handoff_urgency,
+            )
+
+        # Flow complete — evaluate exit rules
+        exit_rules = flow.exit_rules
+        exit_target = exit_rules.get("on_complete", "end")
+
+        # Check for special exits based on slot values
+        if "on_refused" in exit_rules and session.slots.get_slot("consent_given") == "no":
+            exit_target = exit_rules["on_refused"]
+        if "on_unclear" in exit_rules and session.slots.get_slot("clarification_text") is None:
+            exit_target = exit_rules.get("on_unclear", exit_target)
+        if "on_concern" in exit_rules:
+            # Check if any concern was raised during the flow
+            concern_slots = ["pain_level", "medication_adherence"]
+            for slot in concern_slots:
+                val = session.slots.get_slot(slot)
+                if val and isinstance(val, str) and any(w in val.lower() for w in ["severe", "bad", "not taking", "stopped"]):
+                    exit_target = exit_rules["on_concern"]
+                    break
+
+        # Reset current flow
+        session.current_flow = None
+        session.current_step = 0
+
+        if exit_target == "end":
+            session.call_phase = CallPhase.ENDED
+            return TurnResult(outcome=TurnOutcome.END, message="Flow complete")
+
+        if exit_target == "re_evaluate" or exit_target == "evaluate_risk":
+            # Signal to re-run the risk assessment and determine next flow
+            return TurnResult(
+                outcome=TurnOutcome.PROCEED,
+                message=f"Flow complete — re-evaluate ({exit_target})",
+                requires_reassessment=True,
+            )
+
+        # Resolve exit target as next flow
+        next_flow = self._resolver.resolve_next_flow(session, assessment, current_exit=exit_target)
+        if next_flow:
+            return self._enter_flow(session, next_flow)
+
+        return TurnResult(outcome=TurnOutcome.END, message="No next flow resolved")
+
+    def _get_current_flow(self, session: SessionState) -> Optional[FlowDefinition]:
+        """Get the current flow definition from session state."""
+        if not session.current_flow:
+            return None
+
+        # Check primitives first
+        prim = self._config.primitives.get(session.current_flow)
+        if prim:
+            return FlowDefinition.from_yaml(prim, source=f"primitives/{session.current_flow}")
+
+        # Check taxonomy flows
+        for domain, flows in self._config.taxonomy_flows.items():
+            if session.current_flow in flows:
+                return FlowDefinition.from_yaml(
+                    flows[session.current_flow],
+                    source=f"taxonomy/{domain}/{session.current_flow}",
+                )
+
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Turn Result
+# ---------------------------------------------------------------------------
+
+class TurnResult:
+    """Result of processing a conversational turn."""
+
+    def __init__(
+        self,
+        outcome: TurnOutcome,
+        flow_id: Optional[str] = None,
+        flow_type: Optional[str] = None,
+        step_number: int = 0,
+        step_type: Optional[str] = None,
+        response_spec: Optional[ResponseSpecDef] = None,
+        collects: Optional[List[str]] = None,
+        handoff_target: Optional[str] = None,
+        handoff_urgency: Optional[str] = None,
+        risk_class: Optional[RiskClass] = None,
+        domain: Optional[str] = None,
+        message: str = "",
+        requires_reassessment: bool = False,
+    ):
+        self.outcome = outcome
+        self.flow_id = flow_id
+        self.flow_type = flow_type
+        self.step_number = step_number
+        self.step_type = step_type
+        self.response_spec = response_spec
+        self.collects = collects or []
+        self.handoff_target = handoff_target
+        self.handoff_urgency = handoff_urgency
+        self.risk_class = risk_class
+        self.domain = domain
+        self.message = message
+        self.requires_reassessment = requires_reassessment
+
+    @property
+    def is_escalation(self) -> bool:
+        return self.outcome == TurnOutcome.ESCALATE
+
+    @property
+    def is_handoff(self) -> bool:
+        return self.outcome in (TurnOutcome.ESCALATE, TurnOutcome.HANDOFF)
+
+    @property
+    def is_end(self) -> bool:
+        return self.outcome == TurnOutcome.END
+
+    @property
+    def prompt_constraints(self) -> Optional[str]:
+        """Get LLM prompt constraints from response spec."""
+        if self.response_spec:
+            return self.response_spec.to_prompt_constraints()
+        return None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize for API response."""
+        result = {
+            "outcome": self.outcome.value,
+            "flow_id": self.flow_id,
+            "flow_type": self.flow_type,
+            "step_number": self.step_number,
+            "step_type": self.step_type,
+            "collects": self.collects,
+            "handoff_target": self.handoff_target,
+            "handoff_urgency": self.handoff_urgency,
+            "message": self.message,
+            "requires_reassessment": self.requires_reassessment,
+        }
+        if self.response_spec:
+            result["response_spec"] = {
+                "id": self.response_spec.spec_id,
+                "goal": self.response_spec.goal,
+                "tone": self.response_spec.tone,
+                "must_include": self.response_spec.must_include,
+                "must_ask": self.response_spec.must_ask,
+                "must_not": self.response_spec.must_not,
+                "max_questions": self.response_spec.max_questions,
+            }
+        if self.risk_class:
+            result["risk_class"] = self.risk_class.value
+        if self.domain:
+            result["domain"] = self.domain
+        return result
+
+    def __repr__(self) -> str:
+        return (
+            f"TurnResult(outcome={self.outcome.value}, flow={self.flow_id}, "
+            f"step={self.step_number}, type={self.step_type})"
+        )

decision/engine/journey_orchestrator.py

@@ -0,0 +1,478 @@
+"""
+Journey Orchestrator (Phase 3B).
+
+Manages multi-day patient engagement journeys with:
+  - Enrollment eligibility and deduplication
+  - Contact scheduling (offset days, time windows, channel selection)
+  - Contact caps (max per day/week, quiet hours)
+  - Wedge priority and conflict resolution
+  - Post-escalation suppression
+  - Journey step tracking and agenda management
+
+Usage:
+    orchestrator = JourneyOrchestrator(config, tenant_manager)
+    
+    # Enroll a patient
+    enrollment = orchestrator.enroll(patient_id, wedge_type, tenant_id, trigger_event_id)
+    
+    # Check if a contact is allowed right now
+    allowed, reason = orchestrator.can_contact(patient_id, channel="voice")
+    
+    # Get the next scheduled step
+    step = orchestrator.get_next_step(enrollment_id)
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from decision.engine.config_loader import DecisionConfigLoader
+from decision.engine.tenant_manager import TenantManager
+
+logger = logging.getLogger("decision.journey_orchestrator")
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Enrollment:
+    """A patient enrolled in a journey."""
+    enrollment_id: str
+    patient_id: str
+    wedge_type: str
+    tenant_id: str
+    trigger_event_id: str
+    status: str = "active"  # active, completed, withdrawn, paused
+    enrolled_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    current_step: int = 0
+    completed_steps: List[int] = field(default_factory=list)
+    last_contact_at: Optional[datetime] = None
+    last_contact_channel: Optional[str] = None
+    next_scheduled_at: Optional[datetime] = None
+
+
+@dataclass
+class ContactRecord:
+    """Record of a patient contact for rate limiting."""
+    patient_id: str
+    channel: str  # voice, sms
+    timestamp: datetime
+    wedge_type: str
+    risk_class: Optional[str] = None
+
+
+@dataclass
+class JourneyStep:
+    """A step in a journey to be executed."""
+    step_index: int
+    step_name: str
+    channel: str
+    offset_days: int
+    window_start_hour: int
+    window_end_hour: int
+    agenda_sequence: List[str]
+    conditional_probes: List[Dict[str, Any]]
+    pre_populated_slots: List[str]
+
+
+@dataclass
+class ContactDecision:
+    """Result of a contact eligibility check."""
+    allowed: bool
+    reason: str
+    retry_after: Optional[datetime] = None
+
+
+# ---------------------------------------------------------------------------
+# Journey Orchestrator
+# ---------------------------------------------------------------------------
+
+class JourneyOrchestrator:
+    """
+    Orchestrates multi-day patient engagement journeys.
+    """
+
+    def __init__(
+        self,
+        config: DecisionConfigLoader,
+        tenant_manager: Optional[TenantManager] = None,
+    ):
+        self._config = config
+        self._tenant_manager = tenant_manager
+        self._journeys = config.journeys
+        self._orchestrator = config.orchestrator
+
+        # In-memory stores (production: replace with persistent storage)
+        self._enrollments: Dict[str, Enrollment] = {}  # enrollment_id -> Enrollment
+        self._patient_enrollments: Dict[str, List[str]] = {}  # patient_id -> [enrollment_ids]
+        self._contact_history: Dict[str, List[ContactRecord]] = {}  # patient_id -> [ContactRecord]
+
+        # Load orchestrator rules
+        self._contact_caps = self._orchestrator.get("contact_caps", {})
+        self._wedge_priority = self._orchestrator.get("wedge_priority", {})
+        self._conflict_rules = self._orchestrator.get("conflict_resolution", {})
+        self._enrollment_rules = self._orchestrator.get("enrollment_rules", {})
+        self._suppression_rules = self._orchestrator.get("wedge_suppression", {})
+
+        logger.info(
+            "JourneyOrchestrator initialized: %d journeys, %d wedge priorities",
+            len(self._journeys),
+            len(self._wedge_priority.get("priorities", [])),
+        )
+
+    # ------------------------------------------------------------------
+    # Enrollment
+    # ------------------------------------------------------------------
+
+    def enroll(
+        self,
+        patient_id: str,
+        wedge_type: str,
+        tenant_id: str,
+        trigger_event_id: str,
+    ) -> Tuple[Optional[Enrollment], str]:
+        """
+        Enroll a patient in a journey.
+
+        Returns:
+            (Enrollment, reason) — Enrollment object if successful, None if rejected.
+        """
+        # Check journey exists
+        if wedge_type not in self._journeys:
+            return None, f"Unknown wedge type: {wedge_type}"
+
+        # Check tenant enables this wedge
+        if self._tenant_manager:
+            if not self._tenant_manager.is_wedge_enabled(tenant_id, wedge_type):
+                return None, f"Wedge '{wedge_type}' not enabled for tenant '{tenant_id}'"
+
+        # Check deduplication
+        existing = self._patient_enrollments.get(patient_id, [])
+        for eid in existing:
+            enrollment = self._enrollments.get(eid)
+            if enrollment and enrollment.status == "active":
+                if enrollment.wedge_type == wedge_type and enrollment.trigger_event_id == trigger_event_id:
+                    return None, f"Duplicate enrollment: patient already in {wedge_type} for event {trigger_event_id}"
+
+        # Check max active enrollments
+        max_active = self._enrollment_rules.get("max_active_per_patient", 3)
+        active_count = sum(
+            1 for eid in existing
+            if self._enrollments.get(eid, Enrollment("", "", "", "", "")).status == "active"
+        )
+        if active_count >= max_active:
+            return None, f"Max active enrollments ({max_active}) reached for patient {patient_id}"
+
+        # Check cooldown
+        cooldown_days = self._get_cooldown(wedge_type)
+        if cooldown_days:
+            for eid in existing:
+                prev = self._enrollments.get(eid)
+                if prev and prev.wedge_type == wedge_type and prev.status == "completed":
+                    elapsed = (datetime.now(timezone.utc) - prev.enrolled_at).days
+                    if elapsed < cooldown_days:
+                        return None, f"Cooldown active: {cooldown_days - elapsed} days remaining for {wedge_type}"
+
+        # Create enrollment
+        import uuid
+        enrollment_id = f"enr-{uuid.uuid4().hex[:12]}"
+        enrollment = Enrollment(
+            enrollment_id=enrollment_id,
+            patient_id=patient_id,
+            wedge_type=wedge_type,
+            tenant_id=tenant_id,
+            trigger_event_id=trigger_event_id,
+        )
+
+        # Calculate first contact schedule
+        journey = self._journeys[wedge_type]
+        steps = journey.get("steps", [])
+        if steps:
+            first_step = steps[0]
+            offset = first_step.get("offset_days", 1)
+            enrollment.next_scheduled_at = datetime.now(timezone.utc) + timedelta(days=offset)
+
+        self._enrollments[enrollment_id] = enrollment
+        self._patient_enrollments.setdefault(patient_id, []).append(enrollment_id)
+
+        logger.info(
+            "Enrolled patient %s in %s (enrollment=%s, tenant=%s)",
+            patient_id, wedge_type, enrollment_id, tenant_id,
+        )
+        return enrollment, "enrolled"
+
+    # ------------------------------------------------------------------
+    # Contact eligibility
+    # ------------------------------------------------------------------
+
+    def can_contact(
+        self,
+        patient_id: str,
+        channel: str = "voice",
+        now: Optional[datetime] = None,
+    ) -> ContactDecision:
+        """
+        Check if a patient can be contacted right now.
+
+        Evaluates:
+          1. Quiet hours (default 9PM-9AM)
+          2. Channel-specific daily/weekly caps
+          3. Post-escalation suppression
+          4. Voice cooldown (4h between voice calls)
+        """
+        now = now or datetime.now(timezone.utc)
+
+        # 1. Quiet hours (YAML may store as "21:00" or 21)
+        raw_start = self._contact_caps.get("quiet_hours", {}).get("start", 21)
+        raw_end = self._contact_caps.get("quiet_hours", {}).get("end", 9)
+        quiet_start = int(str(raw_start).split(":")[0])
+        quiet_end = int(str(raw_end).split(":")[0])
+        current_hour = now.hour
+        if quiet_start <= current_hour or current_hour < quiet_end:
+            resume_at = now.replace(hour=quiet_end, minute=0, second=0, microsecond=0)
+            if current_hour >= quiet_start:
+                resume_at += timedelta(days=1)
+            return ContactDecision(
+                allowed=False,
+                reason=f"Quiet hours ({quiet_start}:00-{quiet_end}:00)",
+                retry_after=resume_at,
+            )
+
+        # 2. Daily/weekly caps
+        history = self._contact_history.get(patient_id, [])
+        today = now.date()
+        week_ago = now - timedelta(days=7)
+
+        daily_total = sum(1 for r in history if r.timestamp.date() == today)
+        weekly_total = sum(1 for r in history if r.timestamp >= week_ago)
+
+        max_daily = self._contact_caps.get("max_contacts_per_day", 2)
+        max_weekly = self._contact_caps.get("max_contacts_per_week", 7)
+
+        if daily_total >= max_daily:
+            tomorrow = now.replace(hour=quiet_end, minute=0) + timedelta(days=1)
+            return ContactDecision(
+                allowed=False,
+                reason=f"Daily contact cap reached ({daily_total}/{max_daily})",
+                retry_after=tomorrow,
+            )
+
+        if weekly_total >= max_weekly:
+            return ContactDecision(
+                allowed=False,
+                reason=f"Weekly contact cap reached ({weekly_total}/{max_weekly})",
+            )
+
+        # Channel-specific caps (stored as list of {channel, max_per_day, ...})
+        raw_channel_caps = self._contact_caps.get("channel_caps", [])
+        channel_caps = {}
+        if isinstance(raw_channel_caps, list):
+            for entry in raw_channel_caps:
+                if isinstance(entry, dict) and entry.get("channel") == channel:
+                    channel_caps = entry
+                    break
+        elif isinstance(raw_channel_caps, dict):
+            channel_caps = raw_channel_caps.get(channel, {})
+        ch_max_daily = channel_caps.get("max_per_day", max_daily)
+        ch_daily = sum(1 for r in history if r.timestamp.date() == today and r.channel == channel)
+        if ch_daily >= ch_max_daily:
+            return ContactDecision(
+                allowed=False,
+                reason=f"{channel} daily cap reached ({ch_daily}/{ch_max_daily})",
+            )
+
+        # 3. Post-escalation suppression
+        suppression_rules = self._suppression_rules.get("post_escalation", [])
+        for rule in suppression_rules:
+            risk_trigger = rule.get("after_risk_class")
+            suppress_hours = rule.get("suppress_all_hours", 0)
+            if risk_trigger and suppress_hours:
+                for record in reversed(history):
+                    if record.risk_class == risk_trigger:
+                        suppress_until = record.timestamp + timedelta(hours=suppress_hours)
+                        if now < suppress_until:
+                            return ContactDecision(
+                                allowed=False,
+                                reason=f"Post-{risk_trigger} suppression ({suppress_hours}h)",
+                                retry_after=suppress_until,
+                            )
+
+        # 4. Voice cooldown
+        if channel == "voice":
+            cooldown_hours = self._contact_caps.get("voice_cooldown_hours", 4)
+            voice_records = [r for r in history if r.channel == "voice"]
+            if voice_records:
+                last_voice = max(voice_records, key=lambda r: r.timestamp)
+                cooldown_until = last_voice.timestamp + timedelta(hours=cooldown_hours)
+                if now < cooldown_until:
+                    return ContactDecision(
+                        allowed=False,
+                        reason=f"Voice cooldown ({cooldown_hours}h since last voice contact)",
+                        retry_after=cooldown_until,
+                    )
+
+        return ContactDecision(allowed=True, reason="Contact allowed")
+
+    def record_contact(
+        self,
+        patient_id: str,
+        channel: str,
+        wedge_type: str,
+        risk_class: Optional[str] = None,
+    ) -> None:
+        """Record a contact for rate limiting."""
+        record = ContactRecord(
+            patient_id=patient_id,
+            channel=channel,
+            timestamp=datetime.now(timezone.utc),
+            wedge_type=wedge_type,
+            risk_class=risk_class,
+        )
+        self._contact_history.setdefault(patient_id, []).append(record)
+
+    # ------------------------------------------------------------------
+    # Journey step management
+    # ------------------------------------------------------------------
+
+    def get_next_step(self, enrollment_id: str) -> Optional[JourneyStep]:
+        """Get the next scheduled step for an enrollment."""
+        enrollment = self._enrollments.get(enrollment_id)
+        if not enrollment or enrollment.status != "active":
+            return None
+
+        journey = self._journeys.get(enrollment.wedge_type, {})
+        steps = journey.get("steps", [])
+
+        if enrollment.current_step >= len(steps):
+            return None
+
+        step_data = steps[enrollment.current_step]
+        return JourneyStep(
+            step_index=enrollment.current_step,
+            step_name=step_data.get("name", f"step_{enrollment.current_step}"),
+            channel=step_data.get("channel", "voice"),
+            offset_days=step_data.get("offset_days", 0),
+            window_start_hour=step_data.get("window_start_hour", 9),
+            window_end_hour=step_data.get("window_end_hour", 20),
+            agenda_sequence=step_data.get("agenda_sequence", []),
+            conditional_probes=step_data.get("conditional_probes", []),
+            pre_populated_slots=step_data.get("pre_populated_slots", []),
+        )
+
+    def advance_step(self, enrollment_id: str) -> bool:
+        """Mark the current step as completed and advance to next."""
+        enrollment = self._enrollments.get(enrollment_id)
+        if not enrollment or enrollment.status != "active":
+            return False
+
+        enrollment.completed_steps.append(enrollment.current_step)
+        enrollment.current_step += 1
+        enrollment.last_contact_at = datetime.now(timezone.utc)
+
+        journey = self._journeys.get(enrollment.wedge_type, {})
+        steps = journey.get("steps", [])
+
+        if enrollment.current_step >= len(steps):
+            enrollment.status = "completed"
+            logger.info("Enrollment %s completed all steps", enrollment_id)
+            return True
+
+        # Schedule next step
+        next_step = steps[enrollment.current_step]
+        offset = next_step.get("offset_days", 0)
+        enrollment.next_scheduled_at = datetime.now(timezone.utc) + timedelta(days=offset)
+
+        logger.info(
+            "Enrollment %s advanced to step %d (scheduled in %d days)",
+            enrollment_id, enrollment.current_step, offset,
+        )
+        return True
+
+    # ------------------------------------------------------------------
+    # Conflict resolution
+    # ------------------------------------------------------------------
+
+    def resolve_conflict(
+        self, patient_id: str
+    ) -> Optional[str]:
+        """
+        When multiple enrollments are due on the same day,
+        return the enrollment_id that should proceed (highest priority wins).
+        """
+        enrollment_ids = self._patient_enrollments.get(patient_id, [])
+        active = [
+            self._enrollments[eid]
+            for eid in enrollment_ids
+            if self._enrollments.get(eid, Enrollment("", "", "", "", "")).status == "active"
+        ]
+
+        if len(active) <= 1:
+            return active[0].enrollment_id if active else None
+
+        # Get priorities
+        priorities = {
+            p.get("wedge_type"): p.get("priority", 0)
+            for p in self._wedge_priority.get("priorities", [])
+        }
+
+        # Sort by priority descending
+        active.sort(key=lambda e: priorities.get(e.wedge_type, 0), reverse=True)
+
+        winner = active[0]
+        for loser in active[1:]:
+            if loser.next_scheduled_at and winner.next_scheduled_at:
+                if loser.next_scheduled_at.date() == winner.next_scheduled_at.date():
+                    # Defer loser by 24h
+                    loser.next_scheduled_at += timedelta(hours=24)
+                    logger.info(
+                        "Conflict resolution: %s (%s) wins over %s (%s), deferring 24h",
+                        winner.wedge_type, winner.enrollment_id,
+                        loser.wedge_type, loser.enrollment_id,
+                    )
+
+        return winner.enrollment_id
+
+    # ------------------------------------------------------------------
+    # Status and listing
+    # ------------------------------------------------------------------
+
+    def get_patient_enrollments(self, patient_id: str) -> List[Enrollment]:
+        """Get all enrollments for a patient."""
+        enrollment_ids = self._patient_enrollments.get(patient_id, [])
+        return [
+            self._enrollments[eid]
+            for eid in enrollment_ids
+            if eid in self._enrollments
+        ]
+
+    def get_enrollment(self, enrollment_id: str) -> Optional[Enrollment]:
+        return self._enrollments.get(enrollment_id)
+
+    def withdraw(self, enrollment_id: str, reason: str = "") -> bool:
+        enrollment = self._enrollments.get(enrollment_id)
+        if not enrollment:
+            return False
+        enrollment.status = "withdrawn"
+        logger.info("Enrollment %s withdrawn: %s", enrollment_id, reason)
+        return True
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _get_cooldown(self, wedge_type: str) -> Optional[int]:
+        """Get cooldown days for a wedge type."""
+        cooldowns = self._enrollment_rules.get("cooldown_days", {})
+        return cooldowns.get(wedge_type)
+
+    def _get_wedge_priority(self, wedge_type: str) -> int:
+        priorities = {
+            p.get("wedge_type"): p.get("priority", 0)
+            for p in self._wedge_priority.get("priorities", [])
+        }
+        return priorities.get(wedge_type, 0)

decision/engine/models.py

@@ -0,0 +1,322 @@
+"""
+Core data models for the Decision Engine.
+
+All models are immutable dataclasses to prevent accidental mutation
+during safety-critical evaluation pipelines.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+class ConfidenceTier(enum.Enum):
+    """Confidence tier for taxonomy trigger matches."""
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    NONE = "none"
+
+    def __ge__(self, other: ConfidenceTier) -> bool:
+        order = {self.HIGH: 3, self.MEDIUM: 2, self.LOW: 1, self.NONE: 0}
+        return order[self] >= order[other]
+
+    def __gt__(self, other: ConfidenceTier) -> bool:
+        order = {self.HIGH: 3, self.MEDIUM: 2, self.LOW: 1, self.NONE: 0}
+        return order[self] > order[other]
+
+    def __le__(self, other: ConfidenceTier) -> bool:
+        order = {self.HIGH: 3, self.MEDIUM: 2, self.LOW: 1, self.NONE: 0}
+        return order[self] <= order[other]
+
+    def __lt__(self, other: ConfidenceTier) -> bool:
+        order = {self.HIGH: 3, self.MEDIUM: 2, self.LOW: 1, self.NONE: 0}
+        return order[self] < order[other]
+
+
+class RiskClass(enum.Enum):
+    """Clinical risk classification tier."""
+    R0 = "R0"  # No clinical concern
+    R1 = "R1"  # Low-level concern, routine follow-up
+    R2 = "R2"  # Moderate concern, warm transfer to nurse
+    R3 = "R3"  # Emergent, instruct to call 911 + transfer
+
+    @property
+    def is_emergent(self) -> bool:
+        return self == RiskClass.R3
+
+    @property
+    def requires_nurse(self) -> bool:
+        return self in (RiskClass.R2, RiskClass.R3)
+
+    @property
+    def severity_rank(self) -> int:
+        return {self.R0: 0, self.R1: 1, self.R2: 2, self.R3: 3}[self]
+
+    def __ge__(self, other: RiskClass) -> bool:
+        return self.severity_rank >= other.severity_rank
+
+    def __gt__(self, other: RiskClass) -> bool:
+        return self.severity_rank > other.severity_rank
+
+    def __le__(self, other: RiskClass) -> bool:
+        return self.severity_rank <= other.severity_rank
+
+    def __lt__(self, other: RiskClass) -> bool:
+        return self.severity_rank < other.severity_rank
+
+
+class MatchType(enum.Enum):
+    """Type of lexical match that fired."""
+    PHRASE = "phrase"
+    REGEX = "regex"
+    PARTIAL = "partial"
+
+
+class NegationAction(enum.Enum):
+    """What to do when negation is detected."""
+    SUPPRESS = "suppress"              # Remove domain nomination entirely
+    DOWNGRADE_CONFIDENCE = "downgrade_confidence"  # Drop confidence one tier
+
+
+class TurnOutcome(enum.Enum):
+    """Possible outcomes after a conversational turn."""
+    PROCEED = "proceed"
+    CLARIFY = "clarify"
+    ESCALATE = "escalate"
+    HANDOFF = "handoff"
+    END = "end"
+
+
+class FlowType(enum.Enum):
+    """Type of conversation flow."""
+    SCREENING = "screening"
+    ESCALATION = "escalation"
+    CLARIFICATION = "clarification"
+    RESOLUTION = "resolution"
+    HANDOFF = "handoff"
+    PRIMITIVE = "primitive"
+
+
+class CallPhase(enum.Enum):
+    """Phase of the current call."""
+    SESSION_START = "session_start"
+    ACTIVE_CALL = "active_call"
+    ENDED = "ended"
+
+
+# ---------------------------------------------------------------------------
+# Trigger & Match Models
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class TriggerMatch:
+    """A single lexical match from a taxonomy trigger."""
+    domain: str
+    confidence_tier: ConfidenceTier
+    match_type: MatchType
+    matched_text: str          # The phrase/pattern that matched
+    matched_span: str          # The actual text span from patient input
+    priority: int              # Domain priority from triggers.yaml
+
+
+@dataclass(frozen=True)
+class NegationResult:
+    """Result of negation analysis on a domain match."""
+    is_negated: bool
+    action: NegationAction
+    matched_pattern: str = ""  # Which negation pattern matched
+    original_confidence: ConfidenceTier = ConfidenceTier.NONE
+    adjusted_confidence: ConfidenceTier = ConfidenceTier.NONE
+
+
+@dataclass(frozen=True)
+class DomainNomination:
+    """A nominated clinical domain with combined confidence from ML + lexical signals."""
+    domain: str
+    display_name: str
+    confidence_tier: ConfidenceTier
+    priority: int                          # From triggers.yaml priority field
+    target_risk_class: Optional[RiskClass] # Default risk from rules.yaml
+    trigger_matches: tuple                 # Tuple of TriggerMatch (frozen)
+    negation_result: Optional[NegationResult] = None
+    ml_label: Optional[str] = None         # DriveHealthBERT predicted label
+    ml_confidence: Optional[float] = None  # DriveHealthBERT probability
+    recommended_flow: Optional[str] = None # From rules.yaml decision_rules
+
+    @property
+    def is_negated(self) -> bool:
+        return self.negation_result is not None and self.negation_result.is_negated
+
+    @property
+    def is_safety_critical(self) -> bool:
+        """R3 domains or hard-escalate domains."""
+        return self.target_risk_class == RiskClass.R3
+
+
+# ---------------------------------------------------------------------------
+# Risk Assessment Models
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class RiskRuleMatch:
+    """A risk escalation rule that fired."""
+    rule_id: str
+    domain: str
+    risk_class: RiskClass
+    conditions_met: Dict[str, Any] = field(default_factory=dict)
+    context_conditions: Optional[Dict[str, Any]] = None
+
+
+@dataclass(frozen=True)
+class SuppressionResult:
+    """Result of domain suppression evaluation."""
+    suppressed: bool
+    suppressor_domain: Optional[str] = None
+    rule_reason: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class RiskAssessment:
+    """Complete risk assessment for a patient utterance."""
+    # Primary result
+    risk_class: RiskClass
+    primary_domain: Optional[str]
+    # All nominated domains (ranked by priority)
+    domain_nominations: tuple           # Tuple of DomainNomination
+    # Which rules fired
+    matched_rules: tuple                # Tuple of RiskRuleMatch
+    # Suppression results
+    suppressions: tuple = ()            # Tuple of SuppressionResult
+    # Metadata
+    hard_escalate: bool = False         # suicidal_ideation / homicidal_ideation
+    safety_override: bool = False       # Lexical safety signal regardless of ML
+    ml_label: Optional[str] = None
+    ml_confidence: Optional[float] = None
+    recommended_flow: Optional[str] = None
+    recommended_action: Optional[TurnOutcome] = None
+
+    @property
+    def requires_911(self) -> bool:
+        return self.risk_class == RiskClass.R3
+
+    @property
+    def requires_nurse_transfer(self) -> bool:
+        return self.risk_class >= RiskClass.R2
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize for API response."""
+        return {
+            "risk_class": self.risk_class.value,
+            "primary_domain": self.primary_domain,
+            "requires_911": self.requires_911,
+            "requires_nurse_transfer": self.requires_nurse_transfer,
+            "hard_escalate": self.hard_escalate,
+            "safety_override": self.safety_override,
+            "ml_label": self.ml_label,
+            "ml_confidence": self.ml_confidence,
+            "recommended_flow": self.recommended_flow,
+            "recommended_action": self.recommended_action.value if self.recommended_action else None,
+            "domain_nominations": [
+                {
+                    "domain": n.domain,
+                    "confidence_tier": n.confidence_tier.value,
+                    "priority": n.priority,
+                    "target_risk_class": n.target_risk_class.value if n.target_risk_class else None,
+                    "is_negated": n.is_negated,
+                    "recommended_flow": n.recommended_flow,
+                    "trigger_match_count": len(n.trigger_matches),
+                }
+                for n in self.domain_nominations
+            ],
+            "matched_rules": [
+                {
+                    "rule_id": r.rule_id,
+                    "domain": r.domain,
+                    "risk_class": r.risk_class.value,
+                }
+                for r in self.matched_rules
+            ],
+        }
+
+
+# ---------------------------------------------------------------------------
+# Flow Execution Models (Phase 2 — stubs for forward compatibility)
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class ResponseSpec:
+    """LLM response constraints for a flow step."""
+    spec_id: str
+    goal: str
+    tone: str
+    must_include: tuple = ()
+    must_ask: tuple = ()
+    must_not: tuple = ()
+    max_questions: int = 0
+
+
+@dataclass(frozen=True)
+class FlowStep:
+    """A single step in a conversation flow."""
+    step_number: int
+    step_type: str              # "ask", "respond", "handoff"
+    response_spec: ResponseSpec
+    collects: tuple = ()        # Slot names to extract
+    handoff_target: Optional[str] = None
+    handoff_urgency: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ConversationFlow:
+    """A complete conversation flow definition."""
+    flow_id: str
+    flow_type: FlowType
+    domain: Optional[str]
+    required_slots: tuple = ()
+    steps: tuple = ()           # Tuple of FlowStep
+    exit_rules: Dict[str, str] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Session State Models (Phase 2 — stubs for forward compatibility)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SlotState:
+    """Mutable slot tracker for an active conversation."""
+    slots: Dict[str, Any] = field(default_factory=dict)
+
+    def set_slot(self, name: str, value: Any) -> None:
+        self.slots[name] = value
+
+    def get_slot(self, name: str) -> Optional[Any]:
+        return self.slots.get(name)
+
+    def has_slot(self, name: str) -> bool:
+        return name in self.slots
+
+    def has_all(self, slot_names: List[str]) -> bool:
+        return all(name in self.slots for name in slot_names)
+
+
+@dataclass
+class SessionState:
+    """Mutable state for an active call session."""
+    session_id: str
+    patient_id: Optional[str] = None
+    tenant_id: Optional[str] = None
+    call_phase: CallPhase = CallPhase.SESSION_START
+    current_flow: Optional[str] = None
+    current_step: int = 0
+    agenda_position: int = 0
+    slots: SlotState = field(default_factory=SlotState)
+    domain_history: List[str] = field(default_factory=list)
+    risk_history: List[RiskAssessment] = field(default_factory=list)
+    turn_count: int = 0

decision/engine/risk_classifier.py

@@ -0,0 +1,456 @@
+"""
+Risk Classifier.
+
+Evaluates domain nominations against global risk escalation rules to
+produce a final RiskAssessment with R0/R1/R2/R3 classification.
+
+Evaluation pipeline:
+  1. Check hard-escalate domains (suicidal_ideation → always R3)
+  2. For each nominated domain, evaluate risk_escalation_rules
+  3. Apply domain suppression rules (R1 wound_concern suppresses R2 wound_infection)
+  4. Select highest risk class across all active nominations
+  5. Determine recommended action (proceed / clarify / escalate / handoff)
+
+Safety invariants:
+  - Hard-escalate domains CANNOT be suppressed
+  - R3 can never be downgraded by suppression
+  - When no rules match, default to the domain's target_risk_class
+  - When no target_risk_class exists, default to R1 (fail-open)
+  - Context-aware rules require explicit context; they fail closed (don't fire)
+    when context is unavailable
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from decision.engine.config_loader import DecisionConfigLoader
+from decision.engine.models import (
+    ConfidenceTier,
+    DomainNomination,
+    RiskAssessment,
+    RiskClass,
+    RiskRuleMatch,
+    SuppressionResult,
+    TurnOutcome,
+)
+
+logger = logging.getLogger("decision.risk_classifier")
+
+
+class RiskClassifier:
+    """
+    Classifies risk from domain nominations using global rules.
+
+    Usage:
+        classifier = RiskClassifier(config)
+        assessment = classifier.assess(
+            nominations=nominations,
+            slot_values={"shortness_of_breath": "yes"},
+            patient_context=None,  # Phase 3: FHIR data
+        )
+    """
+
+    def __init__(self, config: DecisionConfigLoader):
+        self._config = config
+        self._hard_escalate: Set[str] = config.hard_escalate_domains
+        self._safety_precedence: List[str] = config.safety_precedence
+        self._risk_rules: List[Dict[str, Any]] = config.risk_escalation_rules
+        self._suppression_rules: List[Dict[str, Any]] = config.domain_suppression_rules
+
+    def assess(
+        self,
+        nominations: List[DomainNomination],
+        slot_values: Optional[Dict[str, str]] = None,
+        patient_context: Optional[Dict[str, Any]] = None,
+        ml_label: Optional[str] = None,
+        ml_confidence: Optional[float] = None,
+    ) -> RiskAssessment:
+        """
+        Produce a complete risk assessment from domain nominations.
+
+        Args:
+            nominations: Ranked domain nominations from DomainNominator
+            slot_values: Currently filled slots (from flow execution)
+            patient_context: FHIR-derived patient context (Phase 3)
+            ml_label: Original DriveHealthBERT label
+            ml_confidence: Original DriveHealthBERT confidence
+
+        Returns:
+            RiskAssessment with final risk class, matched rules, etc.
+        """
+        if not nominations:
+            return self._empty_assessment(ml_label, ml_confidence)
+
+        slot_values = slot_values or {}
+        active_nominations = [n for n in nominations if not n.is_negated]
+
+        # Step 1: Check hard-escalate domains
+        hard_escalate = False
+        hard_domain = None
+        for nom in active_nominations:
+            if nom.domain in self._hard_escalate:
+                hard_escalate = True
+                hard_domain = nom.domain
+                logger.warning(
+                    "HARD ESCALATE triggered: domain=%s", nom.domain
+                )
+                break
+
+        # Step 2: Evaluate risk rules for each nomination
+        all_rule_matches: List[RiskRuleMatch] = []
+        for nom in active_nominations:
+            matches = self._evaluate_rules_for_domain(
+                nom.domain, slot_values, patient_context
+            )
+            all_rule_matches.extend(matches)
+
+        # Step 3: Apply domain suppression
+        suppressions: List[SuppressionResult] = []
+        suppressed_domains: Set[str] = set()
+        if not hard_escalate:
+            suppressions, suppressed_domains = self._evaluate_suppressions(
+                active_nominations
+            )
+
+        # Step 4: Determine highest risk class
+        risk_class = self._determine_risk_class(
+            nominations=active_nominations,
+            rule_matches=all_rule_matches,
+            suppressed_domains=suppressed_domains,
+            hard_escalate=hard_escalate,
+            hard_domain=hard_domain,
+        )
+
+        # Step 5: Determine primary domain
+        primary_domain = self._select_primary_domain(
+            active_nominations, suppressed_domains, hard_domain
+        )
+
+        # Step 6: Determine recommended action
+        recommended_action = self._determine_action(risk_class)
+
+        # Step 7: Determine recommended flow from primary domain
+        recommended_flow = None
+        for nom in active_nominations:
+            if nom.domain == primary_domain and nom.recommended_flow:
+                recommended_flow = nom.recommended_flow
+                break
+
+        # Safety override flag
+        safety_override = any(
+            nom.confidence_tier >= ConfidenceTier.HIGH
+            and nom.domain in set(self._safety_precedence)
+            and nom.domain not in suppressed_domains
+            for nom in active_nominations
+        )
+
+        return RiskAssessment(
+            risk_class=risk_class,
+            primary_domain=primary_domain,
+            domain_nominations=tuple(nominations),
+            matched_rules=tuple(all_rule_matches),
+            suppressions=tuple(suppressions),
+            hard_escalate=hard_escalate,
+            safety_override=safety_override,
+            ml_label=ml_label,
+            ml_confidence=ml_confidence,
+            recommended_flow=recommended_flow,
+            recommended_action=recommended_action,
+        )
+
+    # ------------------------------------------------------------------
+    # Internal evaluation
+    # ------------------------------------------------------------------
+
+    def _evaluate_rules_for_domain(
+        self,
+        domain: str,
+        slot_values: Dict[str, str],
+        patient_context: Optional[Dict[str, Any]],
+    ) -> List[RiskRuleMatch]:
+        """Evaluate all global risk rules for a specific domain."""
+        matches = []
+
+        for rule in self._risk_rules:
+            rule_id = rule.get("id", "unknown")
+            conditions = rule.get("if", {})
+            result = rule.get("then", {})
+
+            # Check domain match
+            rule_domain = conditions.get("domain")
+            if rule_domain != domain:
+                continue
+
+            # Check slot conditions
+            slots_present = conditions.get("slots_present", [])
+            slot_value_conditions = conditions.get("slot_values", {})
+            context_conditions = conditions.get("context")
+
+            # All required slots must be present
+            slots_ok = all(
+                slot_name in slot_values for slot_name in slots_present
+            )
+
+            # All slot value conditions must match
+            values_ok = all(
+                slot_values.get(k) == v
+                for k, v in slot_value_conditions.items()
+            )
+
+            # Context conditions (Phase 3)
+            context_ok = True
+            if context_conditions:
+                if patient_context is None:
+                    # Fail closed: context required but not available
+                    context_ok = False
+                else:
+                    context_ok = self._evaluate_context_conditions(
+                        context_conditions, patient_context
+                    )
+
+            if slots_ok and values_ok and context_ok:
+                risk_str = result.get("risk_class", "R1")
+                try:
+                    risk = RiskClass(risk_str)
+                except ValueError:
+                    risk = RiskClass.R1
+
+                matches.append(
+                    RiskRuleMatch(
+                        rule_id=rule_id,
+                        domain=domain,
+                        risk_class=risk,
+                        conditions_met=slot_value_conditions,
+                        context_conditions=context_conditions,
+                    )
+                )
+
+        return matches
+
+    def _evaluate_context_conditions(
+        self,
+        conditions: Dict[str, Any],
+        patient_context: Dict[str, Any],
+    ) -> bool:
+        """
+        Evaluate FHIR context conditions against patient context.
+
+        Phase 3: Full implementation. Currently supports:
+          - patient_has_condition: list of ICD-10 patterns
+          - medication_count_above: int threshold
+        """
+        # patient_has_condition: check ICD-10 codes
+        required_conditions = conditions.get("patient_has_condition", [])
+        if required_conditions:
+            patient_icd_codes = patient_context.get("active_conditions", [])
+            if not self._match_icd_patterns(required_conditions, patient_icd_codes):
+                return False
+
+        # medication_count_above: check polypharmacy
+        med_threshold = conditions.get("medication_count_above")
+        if med_threshold is not None:
+            med_count = patient_context.get("active_medication_count", 0)
+            if med_count <= med_threshold:
+                return False
+
+        return True
+
+    @staticmethod
+    def _match_icd_patterns(
+        patterns: List[str], patient_codes: List[str]
+    ) -> bool:
+        """Check if any patient ICD-10 code matches any required pattern."""
+        import re
+
+        for pattern in patterns:
+            # Convert ICD-10 wildcard to regex (e.g., "I50.*" → "I50\..*")
+            regex = pattern.replace(".", r"\.").replace("*", ".*")
+            for code in patient_codes:
+                if re.match(regex, code, re.IGNORECASE):
+                    return True
+        return False
+
+    def _evaluate_suppressions(
+        self, nominations: List[DomainNomination]
+    ) -> Tuple[List[SuppressionResult], Set[str]]:
+        """
+        Evaluate domain suppression rules.
+
+        A lower-acuity domain firing at high confidence can suppress
+        a higher-acuity domain at low/medium confidence to reduce
+        false escalations.
+        """
+        suppressions: List[SuppressionResult] = []
+        suppressed: Set[str] = set()
+
+        active_domains = {n.domain: n for n in nominations}
+
+        for rule in self._suppression_rules:
+            suppressor_name = rule.get("suppressor")
+            suppressed_list = rule.get("suppressed_domains", [])
+            condition = rule.get("condition", {})
+            reason = rule.get("reason", "")
+
+            suppressor = active_domains.get(suppressor_name)
+            if not suppressor:
+                continue
+
+            # Check suppressor minimum confidence
+            min_conf_str = condition.get("suppressor_min_confidence", "medium")
+            min_conf = self._str_to_confidence(min_conf_str)
+            if suppressor.confidence_tier < min_conf:
+                continue
+
+            # Check suppressed domains
+            max_conf_str = condition.get("suppressed_max_confidence", "medium")
+            max_conf = self._str_to_confidence(max_conf_str)
+
+            for target_name in suppressed_list:
+                target = active_domains.get(target_name)
+                if not target:
+                    continue
+
+                # SAFETY: Never suppress hard-escalate domains
+                if target_name in self._hard_escalate:
+                    continue
+
+                # Only suppress if target is at or below max confidence
+                if target.confidence_tier <= max_conf:
+                    suppressed.add(target_name)
+                    suppressions.append(
+                        SuppressionResult(
+                            suppressed=True,
+                            suppressor_domain=suppressor_name,
+                            rule_reason=reason,
+                        )
+                    )
+                    logger.info(
+                        "Domain suppression: %s suppresses %s (reason: %s)",
+                        suppressor_name,
+                        target_name,
+                        reason,
+                    )
+
+        return suppressions, suppressed
+
+    def _determine_risk_class(
+        self,
+        nominations: List[DomainNomination],
+        rule_matches: List[RiskRuleMatch],
+        suppressed_domains: Set[str],
+        hard_escalate: bool,
+        hard_domain: Optional[str],
+    ) -> RiskClass:
+        """Determine the highest applicable risk class."""
+
+        # Hard escalate always wins
+        if hard_escalate:
+            return RiskClass.R3
+
+        # Collect all risk classes from rule matches (excluding suppressed)
+        risk_candidates: List[RiskClass] = []
+        for rm in rule_matches:
+            if rm.domain not in suppressed_domains:
+                risk_candidates.append(rm.risk_class)
+
+        # ALSO consider target_risk_class from nominations (even when rules
+        # matched for other domains).  Previously this was a fallback that
+        # only ran when zero rules matched, which let a benign R1 rule on
+        # domain A mask a critical R3 target on domain B.
+        for nom in nominations:
+            if nom.domain in suppressed_domains:
+                continue
+            if nom.is_negated:
+                continue
+            if nom.target_risk_class:
+                # For high-confidence matches on safety domains, use target risk
+                if nom.confidence_tier >= ConfidenceTier.HIGH:
+                    risk_candidates.append(nom.target_risk_class)
+                elif nom.confidence_tier >= ConfidenceTier.MEDIUM:
+                    # Medium confidence: one tier below target, minimum R1
+                    downgraded = self._downgrade_risk(nom.target_risk_class)
+                    risk_candidates.append(downgraded)
+                else:
+                    # Low confidence: two tiers below or R1
+                    risk_candidates.append(RiskClass.R1)
+
+        if risk_candidates:
+            return max(risk_candidates)
+
+        # Absolute fallback: if we have any non-negated nomination, R1
+        if any(not n.is_negated for n in nominations):
+            return RiskClass.R1
+
+        return RiskClass.R0
+
+    def _select_primary_domain(
+        self,
+        nominations: List[DomainNomination],
+        suppressed_domains: Set[str],
+        hard_domain: Optional[str],
+    ) -> Optional[str]:
+        """Select the primary domain from active nominations."""
+        if hard_domain:
+            return hard_domain
+
+        # Use safety precedence order for tie-breaking
+        precedence_set = set(self._safety_precedence)
+
+        for nom in nominations:
+            if nom.domain in suppressed_domains:
+                continue
+            if nom.is_negated:
+                continue
+            return nom.domain  # Already sorted by confidence + priority
+
+        # All negated or suppressed
+        return nominations[0].domain if nominations else None
+
+    @staticmethod
+    def _determine_action(risk_class: RiskClass) -> TurnOutcome:
+        """Map risk class to recommended turn outcome."""
+        if risk_class == RiskClass.R3:
+            return TurnOutcome.ESCALATE
+        elif risk_class == RiskClass.R2:
+            return TurnOutcome.HANDOFF
+        elif risk_class == RiskClass.R1:
+            return TurnOutcome.PROCEED
+        return TurnOutcome.PROCEED
+
+    @staticmethod
+    def _downgrade_risk(risk: RiskClass) -> RiskClass:
+        """Downgrade risk by one tier, minimum R1."""
+        if risk == RiskClass.R3:
+            return RiskClass.R2
+        elif risk == RiskClass.R2:
+            return RiskClass.R1
+        return RiskClass.R1
+
+    @staticmethod
+    def _str_to_confidence(s: str) -> ConfidenceTier:
+        try:
+            return ConfidenceTier(s)
+        except ValueError:
+            return ConfidenceTier.MEDIUM
+
+    def _empty_assessment(
+        self,
+        ml_label: Optional[str] = None,
+        ml_confidence: Optional[float] = None,
+    ) -> RiskAssessment:
+        """Return a default R0 assessment when no nominations exist."""
+        return RiskAssessment(
+            risk_class=RiskClass.R0,
+            primary_domain=None,
+            domain_nominations=(),
+            matched_rules=(),
+            suppressions=(),
+            hard_escalate=False,
+            safety_override=False,
+            ml_label=ml_label,
+            ml_confidence=ml_confidence,
+            recommended_flow=None,
+            recommended_action=TurnOutcome.PROCEED,
+        )

decision/engine/tenant_manager.py

@@ -0,0 +1,237 @@
+"""
+Multi-Tenant Configuration Manager (Phase 3B).
+
+Manages tenant-specific configuration overrides including:
+  - Enabled wedges and journeys per tenant
+  - Custom escalation rules (institution-specific clinical protocols)
+  - Domain overrides (enable/disable specific domains)
+  - Institution context (nurse line, ED name, timezone, branding)
+  - FHIR data source configuration
+  - Compliance settings (audit retention, PHI logging)
+
+Usage:
+    manager = TenantManager(config)
+    tenant = manager.get_tenant("example_health_system")
+    merged_rules = manager.get_merged_escalation_rules("example_health_system")
+    enabled_domains = manager.get_enabled_domains("example_health_system")
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Set
+
+from decision.engine.config_loader import DecisionConfigLoader
+
+logger = logging.getLogger("decision.tenant_manager")
+
+
+class TenantConfig:
+    """Parsed tenant configuration with convenience accessors."""
+
+    def __init__(self, tenant_id: str, raw: Dict[str, Any]):
+        self.tenant_id = tenant_id
+        self._raw = raw
+
+    @property
+    def name(self) -> str:
+        return self._raw.get("institution_name", self.tenant_id)
+
+    @property
+    def type(self) -> str:
+        return self._raw.get("institution_type", "unknown")
+
+    @property
+    def enabled_wedges(self) -> List[str]:
+        return self._raw.get("enabled_wedges", [])
+
+    @property
+    def enabled_journeys(self) -> List[str]:
+        return self._raw.get("enabled_journeys", self.enabled_wedges)
+
+    @property
+    def custom_escalation_rules(self) -> List[Dict[str, Any]]:
+        return self._raw.get("custom_escalation_rules", [])
+
+    @property
+    def domain_overrides(self) -> Dict[str, Any]:
+        return self._raw.get("domain_overrides", {})
+
+    @property
+    def disabled_domains(self) -> Set[str]:
+        overrides = self.domain_overrides
+        return {
+            domain
+            for domain, cfg in overrides.items()
+            if isinstance(cfg, dict) and not cfg.get("enabled", True)
+        }
+
+    @property
+    def institution_context(self) -> Dict[str, Any]:
+        return self._raw.get("institution_context", {})
+
+    @property
+    def nurse_line_number(self) -> str:
+        return self.institution_context.get("nurse_line_number", "")
+
+    @property
+    def ed_name(self) -> str:
+        return self.institution_context.get("ed_name", "the emergency department")
+
+    @property
+    def timezone(self) -> str:
+        return self.institution_context.get("timezone", "America/New_York")
+
+    @property
+    def operating_hours(self) -> Dict[str, str]:
+        return self.institution_context.get("operating_hours", {})
+
+    @property
+    def fhir_config(self) -> Dict[str, Any]:
+        return self._raw.get("data_source", {}).get("fhir", {})
+
+    @property
+    def branding(self) -> Dict[str, str]:
+        return self._raw.get("branding", {})
+
+    @property
+    def greeting_name(self) -> str:
+        return self.branding.get("agent_introduction", "Avery, a care assistant")
+
+    @property
+    def compliance(self) -> Dict[str, Any]:
+        return self._raw.get("compliance", {})
+
+    @property
+    def audit_retention_years(self) -> int:
+        return self.compliance.get("audit_retention_years", 7)
+
+    def __repr__(self) -> str:
+        return f"TenantConfig({self.tenant_id}, name={self.name}, wedges={self.enabled_wedges})"
+
+
+class TenantManager:
+    """
+    Manages multi-tenant configurations and rule merging.
+
+    Provides:
+    - Tenant lookup and validation
+    - Merged escalation rules (global + tenant custom)
+    - Domain filtering (respect tenant disabled_domains)
+    - Institution context for response generation
+    """
+
+    def __init__(self, config: DecisionConfigLoader):
+        self._config = config
+        self._tenants: Dict[str, TenantConfig] = {}
+
+        for tid, raw in config.tenants.items():
+            self._tenants[tid] = TenantConfig(tid, raw)
+
+        logger.info("TenantManager initialized with %d tenants", len(self._tenants))
+
+    @property
+    def tenant_ids(self) -> List[str]:
+        return sorted(self._tenants.keys())
+
+    def get_tenant(self, tenant_id: str) -> Optional[TenantConfig]:
+        return self._tenants.get(tenant_id)
+
+    def get_merged_escalation_rules(
+        self, tenant_id: str
+    ) -> List[Dict[str, Any]]:
+        """
+        Merge global escalation rules with tenant-specific custom rules.
+
+        Tenant rules are appended AFTER global rules, so they take effect
+        as additional checks. Tenant rules with the same ID as global rules
+        override the global version.
+        """
+        global_rules = list(self._config.risk_escalation_rules)
+        tenant = self._tenants.get(tenant_id)
+        if not tenant:
+            return global_rules
+
+        custom = tenant.custom_escalation_rules
+        if not custom:
+            return global_rules
+
+        # Build a map of global rules by ID
+        global_ids = {r.get("id"): i for i, r in enumerate(global_rules)}
+
+        merged = list(global_rules)
+        for rule in custom:
+            rule_id = rule.get("id")
+            if rule_id and rule_id in global_ids:
+                # Override existing rule
+                merged[global_ids[rule_id]] = rule
+                logger.info(
+                    "Tenant %s overrides global rule: %s", tenant_id, rule_id
+                )
+            else:
+                # Append new rule
+                merged.append(rule)
+                logger.info(
+                    "Tenant %s adds custom rule: %s", tenant_id, rule_id
+                )
+
+        return merged
+
+    def get_enabled_domains(
+        self, tenant_id: str, all_domains: Optional[List[str]] = None
+    ) -> List[str]:
+        """
+        Get domains enabled for a tenant (all domains minus disabled ones).
+        """
+        if all_domains is None:
+            all_domains = self._config.domain_names
+
+        tenant = self._tenants.get(tenant_id)
+        if not tenant:
+            return all_domains
+
+        disabled = tenant.disabled_domains
+        if not disabled:
+            return all_domains
+
+        enabled = [d for d in all_domains if d not in disabled]
+        logger.info(
+            "Tenant %s: %d domains enabled (%d disabled: %s)",
+            tenant_id,
+            len(enabled),
+            len(disabled),
+            disabled,
+        )
+        return enabled
+
+    def is_wedge_enabled(self, tenant_id: str, wedge_type: str) -> bool:
+        """Check if a wedge/journey is enabled for a tenant."""
+        tenant = self._tenants.get(tenant_id)
+        if not tenant:
+            return True  # No tenant config = all enabled
+        return wedge_type in tenant.enabled_wedges
+
+    def get_institution_context_for_prompts(
+        self, tenant_id: str
+    ) -> Dict[str, str]:
+        """
+        Get institution-specific context for LLM prompt injection.
+
+        Returns strings that can be inserted into response specs.
+        """
+        tenant = self._tenants.get(tenant_id)
+        if not tenant:
+            return {
+                "agent_name": "Avery",
+                "institution_name": "your healthcare provider",
+                "nurse_line": "the nurse line",
+                "ed_name": "the emergency department",
+            }
+
+        return {
+            "agent_name": "Avery",
+            "institution_name": tenant.name,
+            "nurse_line": tenant.nurse_line_number or "the nurse line",
+            "ed_name": tenant.ed_name,
+            "greeting": tenant.greeting_name,
+        }

decision/engine/training_data_generator.py

@@ -0,0 +1,373 @@
+"""
+Training Data Generator (Phase 3C).
+
+Generates synthetic training samples from taxonomy trigger definitions
+for model retraining and augmentation.
+
+Each domain's triggers.yaml contains carefully curated phrases at
+multiple confidence tiers. These can be converted into labeled training
+examples to improve DriveHealthBERT's domain coverage.
+
+Capabilities:
+  - Generate ESCALATION samples from R2/R3 domain triggers
+  - Generate domain-specific samples with label mapping
+  - Generate negation examples (negative samples for safety)
+  - Template-based augmentation with variations
+  - JSONL output compatible with train.py
+
+Usage:
+    generator = TrainingDataGenerator(config)
+    samples = generator.generate_all()
+    generator.write_jsonl(samples, "data/taxonomy_augmented.jsonl")
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import random
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from decision.engine.config_loader import DecisionConfigLoader
+
+logger = logging.getLogger("decision.training_data_generator")
+
+# Map domains to DriveHealthBERT labels
+_DOMAIN_TO_LABEL = {
+    # R3 domains → ESCALATION
+    "chest_pain": "ESCALATION",
+    "suicidal_ideation": "ESCALATION",
+    "homicidal_ideation": "ESCALATION",
+    "stroke_symptoms": "ESCALATION",
+    "seizure": "ESCALATION",
+    "severe_bleeding": "ESCALATION",
+    "anaphylaxis": "ESCALATION",
+    "airway_compromise": "ESCALATION",
+    "overdose": "ESCALATION",
+    "pregnancy_emergency": "ESCALATION",
+    "ectopic_signal": "ESCALATION",
+    "febrile_neutropenia": "ESCALATION",
+    "meningitis_signal": "ESCALATION",
+    "dka_hhs": "ESCALATION",
+    "severe_hypoglycemia": "ESCALATION",
+    "syncope": "ESCALATION",
+    "thunderclap_headache": "ESCALATION",
+    "sudden_vision_loss": "ESCALATION",
+    "acute_limb_deficit": "ESCALATION",
+
+    # R2 domains → ESCALATION (moderate, but still escalation)
+    "shortness_of_breath_rest": "ESCALATION",
+    "palpitations_dizziness": "ESCALATION",
+    "heart_failure_worsening": "ESCALATION",
+    "gi_bleed": "ESCALATION",
+    "severe_abdominal_pain": "ESCALATION",
+    "wound_infection": "ESCALATION",
+    "fall_high_risk": "ESCALATION",
+    "behavioral_crisis": "ESCALATION",
+    "acute_confusion": "ESCALATION",
+    "persistent_vomiting": "ESCALATION",
+    "post_discharge_fever": "ESCALATION",
+    "dvt_signal": "ESCALATION",
+    "npo_violation": "ESCALATION",
+    "anticoagulant_hold_failure": "ESCALATION",
+    "acute_illness_preop": "ESCALATION",
+    "worsening_depression_si": "ESCALATION",
+    "procedure_anxiety_severe": "ESCALATION",
+    "domestic_safety_concern": "ESCALATION",
+
+    # R1/R0 symptom domains → SYMPTOM_CHECK
+    "exertional_dyspnea": "SYMPTOM_CHECK",
+    "persistent_dizziness": "SYMPTOM_CHECK",
+    "abnormal_bp": "SYMPTOM_CHECK",
+    "reproducible_chest_discomfort": "SYMPTOM_CHECK",
+    "wound_concern": "SYMPTOM_CHECK",
+    "uncontrolled_pain": "SYMPTOM_CHECK",
+    "worsening_chronic_pain": "SYMPTOM_CHECK",
+    "progressive_weakness": "SYMPTOM_CHECK",
+    "urinary_retention": "SYMPTOM_CHECK",
+    "severe_diarrhea": "SYMPTOM_CHECK",
+    "poor_oral_intake": "SYMPTOM_CHECK",
+    "new_jaundice": "SYMPTOM_CHECK",
+    "glucose_out_of_range": "SYMPTOM_CHECK",
+    "recurrent_falls": "SYMPTOM_CHECK",
+    "post_procedure_incontinence": "SYMPTOM_CHECK",
+
+    # Medication domains → MEDICATION
+    "medication": "MEDICATION",
+    "medication_nonadherence": "MEDICATION",
+
+    # Scheduling domains → APPOINTMENT
+    "scheduling": "APPOINTMENT",
+    "scheduling_barrier": "APPOINTMENT",
+    "missed_followup": "APPOINTMENT",
+    "post_discharge_engagement": "APPOINTMENT",
+
+    # Screening domains → SYMPTOM_CHECK
+    "phq2_positive": "SYMPTOM_CHECK",
+    "audit_c_positive": "SYMPTOM_CHECK",
+    "screening_gap_identified": "SYMPTOM_CHECK",
+    "screening_refusal": "GENERAL_INQUIRY",
+    "cognitive_concern": "SYMPTOM_CHECK",
+
+    # Social/safety domains
+    "caregiver_safety_concern": "ESCALATION",
+    "food_insecurity": "GENERAL_INQUIRY",
+    "social_isolation": "GENERAL_INQUIRY",
+    "tobacco_use_active": "GENERAL_INQUIRY",
+}
+
+# Templates for wrapping trigger phrases into natural sentences
+_PATIENT_TEMPLATES = [
+    "{phrase}",
+    "I have {phrase}",
+    "I'm experiencing {phrase}",
+    "I've been having {phrase}",
+    "I think I have {phrase}",
+    "My {phrase} is getting worse",
+    "I need help with {phrase}",
+    "I'm worried about {phrase}",
+    "I want to talk about {phrase}",
+    "Can you help me with {phrase}",
+]
+
+_NEGATION_TEMPLATES = [
+    "I don't have {phrase}",
+    "No {phrase}",
+    "I'm not experiencing {phrase}",
+    "{phrase} has gone away",
+    "I used to have {phrase} but not anymore",
+    "My mother had {phrase} not me",
+]
+
+
+class TrainingDataGenerator:
+    """Generates training data from taxonomy triggers."""
+
+    def __init__(self, config: DecisionConfigLoader):
+        self._config = config
+        self._triggers = config.taxonomy_triggers
+        self._rules = config.taxonomy_rules
+
+    def generate_all(
+        self,
+        include_negations: bool = True,
+        max_per_domain: int = 50,
+        augment_templates: bool = True,
+        seed: int = 42,
+    ) -> List[Dict[str, str]]:
+        """
+        Generate training samples from all taxonomy domains.
+
+        Args:
+            include_negations: Also generate negative samples from negation patterns
+            max_per_domain: Maximum samples per domain
+            augment_templates: Apply template-based augmentation
+            seed: Random seed for reproducibility
+
+        Returns:
+            List of {"text": ..., "label": ..., "source": ...} dicts
+        """
+        random.seed(seed)
+        all_samples: List[Dict[str, str]] = []
+
+        for domain_name, triggers in self._triggers.items():
+            label = _DOMAIN_TO_LABEL.get(domain_name)
+            if not label:
+                logger.debug("Skipping domain %s (no label mapping)", domain_name)
+                continue
+
+            domain_samples = self._generate_for_domain(
+                domain_name, triggers, label, augment_templates, max_per_domain
+            )
+            all_samples.extend(domain_samples)
+
+            # Generate negation samples
+            if include_negations and label == "ESCALATION":
+                neg_samples = self._generate_negations(
+                    domain_name, triggers, max_per_domain // 3
+                )
+                all_samples.extend(neg_samples)
+
+        random.shuffle(all_samples)
+
+        # Summary
+        label_counts = {}
+        for s in all_samples:
+            label_counts[s["label"]] = label_counts.get(s["label"], 0) + 1
+
+        logger.info(
+            "Generated %d training samples from %d domains: %s",
+            len(all_samples),
+            len(self._triggers),
+            label_counts,
+        )
+
+        return all_samples
+
+    def _generate_for_domain(
+        self,
+        domain_name: str,
+        triggers: Dict[str, Any],
+        label: str,
+        augment: bool,
+        max_samples: int,
+    ) -> List[Dict[str, str]]:
+        """Generate training samples for a single domain."""
+        samples = []
+        lexical = triggers.get("lexical_signals", {})
+
+        for tier_name in ("high", "medium", "low"):
+            tier = lexical.get(tier_name, {})
+
+            # Direct phrase samples
+            for phrase in tier.get("phrases", []):
+                samples.append({
+                    "text": phrase,
+                    "label": label,
+                    "source": f"taxonomy/{domain_name}/{tier_name}/phrase",
+                })
+
+                # Template augmentation
+                if augment:
+                    templates = random.sample(
+                        _PATIENT_TEMPLATES, min(3, len(_PATIENT_TEMPLATES))
+                    )
+                    for template in templates:
+                        try:
+                            augmented = template.format(phrase=phrase.lower())
+                            if augmented != phrase:
+                                samples.append({
+                                    "text": augmented,
+                                    "label": label,
+                                    "source": f"taxonomy/{domain_name}/{tier_name}/augmented",
+                                })
+                        except (KeyError, IndexError):
+                            pass
+
+            # Partial samples (lower confidence)
+            for partial in tier.get("partials", []):
+                samples.append({
+                    "text": partial,
+                    "label": label,
+                    "source": f"taxonomy/{domain_name}/{tier_name}/partial",
+                })
+
+        # Deduplicate by text
+        seen = set()
+        unique = []
+        for s in samples:
+            text_lower = s["text"].lower().strip()
+            if text_lower not in seen:
+                seen.add(text_lower)
+                unique.append(s)
+
+        # Cap per domain
+        if len(unique) > max_samples:
+            unique = random.sample(unique, max_samples)
+
+        return unique
+
+    def _generate_negations(
+        self,
+        domain_name: str,
+        triggers: Dict[str, Any],
+        max_samples: int,
+    ) -> List[Dict[str, str]]:
+        """
+        Generate negative samples from negation patterns.
+
+        These become NON-ESCALATION training examples to reduce false positives.
+        """
+        samples = []
+        negation = triggers.get("negation_handling", {})
+        patterns = negation.get("patterns", [])
+
+        # Use negation patterns directly as negative examples
+        for pattern in patterns:
+            samples.append({
+                "text": pattern,
+                "label": "GENERAL_INQUIRY",  # Negated safety = not escalation
+                "source": f"taxonomy/{domain_name}/negation",
+            })
+
+        # Apply negation templates to domain phrases
+        lexical = triggers.get("lexical_signals", {})
+        high_phrases = lexical.get("high", {}).get("phrases", [])
+
+        for phrase in high_phrases[:5]:  # Top 5 high-confidence phrases
+            templates = random.sample(
+                _NEGATION_TEMPLATES, min(2, len(_NEGATION_TEMPLATES))
+            )
+            for template in templates:
+                try:
+                    negated = template.format(phrase=phrase.lower())
+                    samples.append({
+                        "text": negated,
+                        "label": "GENERAL_INQUIRY",
+                        "source": f"taxonomy/{domain_name}/negation_augmented",
+                    })
+                except (KeyError, IndexError):
+                    pass
+
+        if len(samples) > max_samples:
+            samples = random.sample(samples, max_samples)
+
+        return samples
+
+    def write_jsonl(
+        self, samples: List[Dict[str, str]], output_path: str
+    ) -> int:
+        """Write samples to JSONL file compatible with train.py."""
+        path = Path(output_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        count = 0
+        with open(path, "w", encoding="utf-8") as f:
+            for sample in samples:
+                record = {
+                    "text": sample["text"],
+                    "label": sample["label"],
+                }
+                f.write(json.dumps(record, ensure_ascii=False) + "\n")
+                count += 1
+
+        logger.info("Wrote %d samples to %s", count, path)
+        return count
+
+    def get_label_distribution(
+        self, samples: List[Dict[str, str]]
+    ) -> Dict[str, int]:
+        """Get label distribution of generated samples."""
+        dist: Dict[str, int] = {}
+        for s in samples:
+            dist[s["label"]] = dist.get(s["label"], 0) + 1
+        return dict(sorted(dist.items(), key=lambda x: x[1], reverse=True))
+
+    def get_domain_coverage_report(
+        self, samples: List[Dict[str, str]]
+    ) -> str:
+        """Generate a coverage report."""
+        domain_count: Dict[str, int] = {}
+        for s in samples:
+            source = s.get("source", "")
+            domain = source.split("/")[1] if "/" in source else "unknown"
+            domain_count[domain] = domain_count.get(domain, 0) + 1
+
+        lines = ["=== Training Data Coverage Report ===", ""]
+        lines.append(f"Total samples: {len(samples)}")
+        lines.append(f"Domains covered: {len(domain_count)}")
+        lines.append("")
+
+        dist = self.get_label_distribution(samples)
+        lines.append("Label distribution:")
+        for label, count in dist.items():
+            pct = count / len(samples) * 100
+            lines.append(f"  {label:20s}: {count:5d} ({pct:.1f}%)")
+
+        lines.append("")
+        lines.append("Top domains by sample count:")
+        for domain, count in sorted(domain_count.items(), key=lambda x: x[1], reverse=True)[:15]:
+            lines.append(f"  {domain:35s}: {count:4d}")
+
+        return "\n".join(lines)

decision/engine/trigger_engine.py

@@ -0,0 +1,323 @@
+"""
+Taxonomy Trigger Engine.
+
+Matches patient utterances against all 65 clinical domain trigger definitions
+using phrase matching, regex patterns, partial substring matching, and
+negation handling.
+
+Safety-critical: This is the last line of defense for catching clinical
+emergencies that the ML model may miss. False negatives here can be
+life-threatening.
+
+Design principles:
+  - Fail open: If in doubt, nominate the domain (better to over-escalate)
+  - Exhaustive matching: Check ALL domains, not just the first match
+  - Negation requires explicit evidence: Only suppress if negation pattern
+    clearly matches
+  - Pre-compiled regex: All patterns compiled at config load time
+  - Case-insensitive matching throughout
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from decision.engine.config_loader import DecisionConfigLoader
+from decision.engine.models import (
+    ConfidenceTier,
+    MatchType,
+    NegationAction,
+    NegationResult,
+    TriggerMatch,
+)
+
+logger = logging.getLogger("decision.trigger_engine")
+
+
+class TaxonomyTriggerEngine:
+    """
+    Matches text against taxonomy trigger definitions.
+
+    Usage:
+        engine = TaxonomyTriggerEngine(config)
+        matches = engine.match_all(text)
+        # Returns: Dict[str, DomainMatchResult] keyed by domain name
+    """
+
+    def __init__(self, config: DecisionConfigLoader):
+        self._config = config
+        self._domains: Dict[str, Dict[str, Any]] = config.taxonomy_triggers
+        logger.info(
+            "TaxonomyTriggerEngine initialized with %d domains", len(self._domains)
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def match_all(self, text: str) -> Dict[str, DomainMatchResult]:
+        """
+        Match text against ALL taxonomy domains.
+
+        Returns a dict of domain_name -> DomainMatchResult for every domain
+        that has at least one trigger match (before negation).
+
+        Negation is evaluated but does NOT remove the domain from results.
+        The caller decides what to do based on negation_result.
+        """
+        text_lower = text.lower().strip()
+        if not text_lower:
+            return {}
+
+        results: Dict[str, DomainMatchResult] = {}
+
+        for domain_name, triggers in self._domains.items():
+            result = self._match_domain(domain_name, triggers, text, text_lower)
+            if result and result.highest_confidence != ConfidenceTier.NONE:
+                results[domain_name] = result
+
+        return results
+
+    def match_domain(self, domain_name: str, text: str) -> Optional[DomainMatchResult]:
+        """Match text against a single domain's triggers."""
+        triggers = self._domains.get(domain_name)
+        if not triggers:
+            return None
+        text_lower = text.lower().strip()
+        return self._match_domain(domain_name, triggers, text, text_lower)
+
+    def check_negation(
+        self, domain_name: str, text: str
+    ) -> NegationResult:
+        """Check if text matches negation patterns for a domain."""
+        triggers = self._domains.get(domain_name, {})
+        text_lower = text.lower().strip()
+        return self._evaluate_negation(domain_name, triggers, text_lower)
+
+    # ------------------------------------------------------------------
+    # Internal matching
+    # ------------------------------------------------------------------
+
+    def _match_domain(
+        self,
+        domain_name: str,
+        triggers: Dict[str, Any],
+        text: str,
+        text_lower: str,
+    ) -> Optional[DomainMatchResult]:
+        """Match text against a single domain's trigger definition."""
+        lexical = triggers.get("lexical_signals", {})
+        priority = triggers.get("priority", 0)
+
+        all_matches: List[TriggerMatch] = []
+
+        # Check each confidence tier (high → medium → low)
+        for tier_name, tier_enum in [
+            ("high", ConfidenceTier.HIGH),
+            ("medium", ConfidenceTier.MEDIUM),
+            ("low", ConfidenceTier.LOW),
+        ]:
+            tier = lexical.get(tier_name, {})
+            tier_matches = self._match_tier(
+                domain_name, tier, tier_enum, text, text_lower, priority
+            )
+            all_matches.extend(tier_matches)
+
+        if not all_matches:
+            return None
+
+        # Determine highest confidence from matches
+        highest = ConfidenceTier.NONE
+        for m in all_matches:
+            if m.confidence_tier > highest:
+                highest = m.confidence_tier
+
+        # Evaluate negation
+        negation = self._evaluate_negation(domain_name, triggers, text_lower)
+
+        # Apply negation to adjust confidence
+        effective_confidence = highest
+        if negation.is_negated:
+            if negation.action == NegationAction.SUPPRESS:
+                effective_confidence = ConfidenceTier.NONE
+            elif negation.action == NegationAction.DOWNGRADE_CONFIDENCE:
+                effective_confidence = self._downgrade_tier(highest)
+
+        return DomainMatchResult(
+            domain=domain_name,
+            priority=priority,
+            matches=tuple(all_matches),
+            highest_confidence=highest,
+            effective_confidence=effective_confidence,
+            negation_result=negation,
+        )
+
+    def _match_tier(
+        self,
+        domain_name: str,
+        tier: Dict[str, Any],
+        tier_enum: ConfidenceTier,
+        text: str,
+        text_lower: str,
+        priority: int,
+    ) -> List[TriggerMatch]:
+        """Match text against a single confidence tier."""
+        matches: List[TriggerMatch] = []
+
+        # 1. Phrase matching (exact substring, case-insensitive)
+        for phrase in tier.get("phrases", []):
+            phrase_lower = phrase.lower()
+            idx = text_lower.find(phrase_lower)
+            if idx >= 0:
+                matched_span = text[idx : idx + len(phrase)]
+                matches.append(
+                    TriggerMatch(
+                        domain=domain_name,
+                        confidence_tier=tier_enum,
+                        match_type=MatchType.PHRASE,
+                        matched_text=phrase,
+                        matched_span=matched_span,
+                        priority=priority,
+                    )
+                )
+
+        # 2. Regex matching (pre-compiled)
+        for compiled_re in tier.get("_compiled_regex", []):
+            m = compiled_re.search(text)
+            if m:
+                matches.append(
+                    TriggerMatch(
+                        domain=domain_name,
+                        confidence_tier=tier_enum,
+                        match_type=MatchType.REGEX,
+                        matched_text=compiled_re.pattern,
+                        matched_span=m.group(0),
+                        priority=priority,
+                    )
+                )
+
+        # 3. Partial matching (substring, case-insensitive)
+        for partial in tier.get("partials", []):
+            partial_lower = partial.lower()
+            idx = text_lower.find(partial_lower)
+            if idx >= 0:
+                matched_span = text[idx : idx + len(partial)]
+                matches.append(
+                    TriggerMatch(
+                        domain=domain_name,
+                        confidence_tier=tier_enum,
+                        match_type=MatchType.PARTIAL,
+                        matched_text=partial,
+                        matched_span=matched_span,
+                        priority=priority,
+                    )
+                )
+
+        return matches
+
+    def _evaluate_negation(
+        self,
+        domain_name: str,
+        triggers: Dict[str, Any],
+        text_lower: str,
+    ) -> NegationResult:
+        """
+        Evaluate negation patterns for a domain.
+
+        SAFETY DESIGN: Negation requires an EXPLICIT match against a known
+        negation pattern. We do NOT use generic "no/not" detection because
+        that risks suppressing true emergencies.
+        """
+        negation_config = triggers.get("negation_handling", {})
+        compiled_patterns: List[str] = negation_config.get("_compiled_patterns", [])
+        action_str = negation_config.get("action", "downgrade_confidence")
+
+        try:
+            action = NegationAction(action_str)
+        except ValueError:
+            action = NegationAction.DOWNGRADE_CONFIDENCE
+
+        for pattern in compiled_patterns:
+            if pattern in text_lower:
+                return NegationResult(
+                    is_negated=True,
+                    action=action,
+                    matched_pattern=pattern,
+                )
+
+        return NegationResult(
+            is_negated=False,
+            action=action,
+        )
+
+    @staticmethod
+    def _downgrade_tier(tier: ConfidenceTier) -> ConfidenceTier:
+        """Downgrade confidence by one level."""
+        if tier == ConfidenceTier.HIGH:
+            return ConfidenceTier.MEDIUM
+        elif tier == ConfidenceTier.MEDIUM:
+            return ConfidenceTier.LOW
+        elif tier == ConfidenceTier.LOW:
+            return ConfidenceTier.NONE
+        return ConfidenceTier.NONE
+
+
+# ---------------------------------------------------------------------------
+# Domain Match Result
+# ---------------------------------------------------------------------------
+
+class DomainMatchResult:
+    """
+    Result of matching a single domain against patient text.
+
+    Contains all trigger matches, the highest raw confidence,
+    effective confidence (after negation), and negation details.
+    """
+
+    __slots__ = (
+        "domain",
+        "priority",
+        "matches",
+        "highest_confidence",
+        "effective_confidence",
+        "negation_result",
+    )
+
+    def __init__(
+        self,
+        domain: str,
+        priority: int,
+        matches: Tuple[TriggerMatch, ...],
+        highest_confidence: ConfidenceTier,
+        effective_confidence: ConfidenceTier,
+        negation_result: NegationResult,
+    ):
+        self.domain = domain
+        self.priority = priority
+        self.matches = matches
+        self.highest_confidence = highest_confidence
+        self.effective_confidence = effective_confidence
+        self.negation_result = negation_result
+
+    @property
+    def is_negated(self) -> bool:
+        return self.negation_result.is_negated
+
+    @property
+    def is_suppressed(self) -> bool:
+        return self.effective_confidence == ConfidenceTier.NONE
+
+    @property
+    def match_count(self) -> int:
+        return len(self.matches)
+
+    def __repr__(self) -> str:
+        neg = " [NEGATED]" if self.is_negated else ""
+        return (
+            f"DomainMatchResult({self.domain}, "
+            f"confidence={self.effective_confidence.value}, "
+            f"priority={self.priority}, "
+            f"matches={self.match_count}{neg})"
+        )

decision/global/global_rules.yaml

@@ -0,0 +1,666 @@
+safety_precedence:
+  # R3 domains ordered by clinical acuity
+  - chest_pain
+  - airway_compromise
+  - shortness_of_breath_rest
+  - exertional_dyspnea
+  - severe_bleeding
+  - gi_bleed
+  - stroke_symptoms
+  - acute_limb_deficit
+  - syncope
+  - anaphylaxis
+  - seizure
+  - suicidal_ideation
+  - homicidal_ideation
+  - overdose
+  - thunderclap_headache
+  - pregnancy_emergency
+  - severe_hypoglycemia
+  - dka_hhs
+  - febrile_neutropenia
+  - sudden_vision_loss
+  # R2 safety domain — domestic violence / elder abuse
+  - domestic_safety_concern
+
+call_phases:
+  - session_start
+  - active_call
+  - ended
+
+primitive_sequence:
+  - greeting
+  - identity_verify
+  - consent
+
+fallback_flow: primitives/clarify
+
+risk_classes:
+  R0: "No clinical concern identified"
+  R1: "Low-level concern, routine follow-up"
+  R2: "Moderate concern, warm transfer to nurse"
+  R3: "Emergent, instruct patient to call 911 and transfer to nurse"
+
+risk_escalation_rules:
+  - id: chest_pain_with_sob
+    if:
+      domain: chest_pain
+      slots_present:
+        - shortness_of_breath
+      slot_values:
+        shortness_of_breath: "yes"
+    then:
+      risk_class: R3
+
+  - id: chest_pain_with_syncope
+    if:
+      domain: chest_pain
+      slots_present:
+        - syncope_or_dizziness
+      slot_values:
+        syncope_or_dizziness: "yes"
+    then:
+      risk_class: R3
+
+  - id: chest_pain_isolated
+    if:
+      domain: chest_pain
+      slots_present:
+        - chest_pain_severity
+    then:
+      risk_class: R3
+
+  - id: chest_pain_screening_clear
+    if:
+      domain: chest_pain
+      slot_values:
+        shortness_of_breath: "no"
+        syncope_or_dizziness: "no"
+    then:
+      risk_class: R3
+
+  # ── DKA/HHS ──────────────────────────────────────────────────
+  - id: dka_hhs_confirmed_nausea
+    if:
+      domain: dka_hhs
+      slots_present:
+        - nausea_vomiting
+      slot_values:
+        nausea_vomiting: "yes"
+    then:
+      risk_class: R3
+
+  - id: dka_hhs_confirmed_confusion
+    if:
+      domain: dka_hhs
+      slots_present:
+        - confusion_status
+      slot_values:
+        confusion_status: "yes"
+    then:
+      risk_class: R3
+
+  - id: dka_hhs_glucose_critical
+    if:
+      domain: dka_hhs
+      slots_present:
+        - glucose_level_bucket
+      slot_values:
+        glucose_level_bucket: "severe"
+    then:
+      risk_class: R3
+
+  - id: dka_hhs_glucose_high
+    if:
+      domain: dka_hhs
+      slots_present:
+        - glucose_level_bucket
+      slot_values:
+        glucose_level_bucket: "moderate"
+    then:
+      risk_class: R2
+
+  - id: dka_hhs_screening_clear
+    if:
+      domain: dka_hhs
+      slot_values:
+        nausea_vomiting: "no"
+        confusion_status: "no"
+    then:
+      risk_class: R2
+
+  # ── Shortness of Breath at Rest ──────────────────────────────
+  - id: sob_rest_confirmed
+    if:
+      domain: shortness_of_breath_rest
+      slots_present:
+        - sob_at_rest
+      slot_values:
+        sob_at_rest: "yes"
+    then:
+      risk_class: R3
+
+  - id: sob_rest_exertion_only
+    if:
+      domain: shortness_of_breath_rest
+      slot_values:
+        sob_at_rest: "no"
+    then:
+      risk_class: R0
+
+  # ── Wound Infection ──────────────────────────────────────────
+  - id: wound_infection_confirmed_fever
+    if:
+      domain: wound_infection
+      slots_present:
+        - fever_present
+      slot_values:
+        fever_present: "yes"
+    then:
+      risk_class: R3
+
+  - id: wound_infection_confirmed_systemic
+    if:
+      domain: wound_infection
+      slots_present:
+        - wound_systemic_signs
+      slot_values:
+        wound_systemic_signs: "yes"
+    then:
+      risk_class: R3
+
+  - id: wound_infection_screening_clear
+    if:
+      domain: wound_infection
+      slot_values:
+        fever_present: "no"
+        wound_systemic_signs: "no"
+    then:
+      risk_class: R2
+
+  # ── DVT Signal ───────────────────────────────────────────────
+  - id: dvt_signal_confirmed_swelling
+    if:
+      domain: dvt_signal
+      slots_present:
+        - leg_swelling_acute
+      slot_values:
+        leg_swelling_acute: "yes"
+    then:
+      risk_class: R2
+
+  - id: dvt_signal_confirmed_tenderness
+    if:
+      domain: dvt_signal
+      slots_present:
+        - calf_tenderness
+      slot_values:
+        calf_tenderness: "yes"
+    then:
+      risk_class: R2
+
+  - id: dvt_signal_screening_clear
+    if:
+      domain: dvt_signal
+      slot_values:
+        leg_swelling_acute: "no"
+        calf_tenderness: "no"
+    then:
+      risk_class: R0
+
+  # ── Fall High Risk ───────────────���──────────────────────────
+  - id: fall_confirmed_loc
+    if:
+      domain: fall_high_risk
+      slot_values:
+        loss_of_consciousness: "yes"
+    then:
+      risk_class: R3
+
+  - id: fall_confirmed_head_strike_anticoag
+    if:
+      domain: fall_high_risk
+      slot_values:
+        head_strike: "yes"
+        on_anticoagulant: "yes"
+    then:
+      risk_class: R3
+
+  - id: fall_confirmed_head_strike
+    if:
+      domain: fall_high_risk
+      slots_present:
+        - head_strike
+      slot_values:
+        head_strike: "yes"
+    then:
+      risk_class: R2
+
+  - id: fall_confirmed_anticoagulant
+    if:
+      domain: fall_high_risk
+      slots_present:
+        - on_anticoagulant
+      slot_values:
+        on_anticoagulant: "yes"
+    then:
+      risk_class: R2
+
+  - id: fall_screening_clear
+    if:
+      domain: fall_high_risk
+      slot_values:
+        head_strike: "no"
+        injury_present: "no"
+    then:
+      risk_class: R0
+
+  # ── Anaphylaxis ─────────────────────────────────────────────
+  - id: anaphylaxis_confirmed_swelling
+    if:
+      domain: anaphylaxis
+      slots_present:
+        - tongue_lip_swelling
+      slot_values:
+        tongue_lip_swelling: "yes"
+    then:
+      risk_class: R3
+
+  - id: anaphylaxis_confirmed_breathing
+    if:
+      domain: anaphylaxis
+      slots_present:
+        - breathing_difficulty_acute
+      slot_values:
+        breathing_difficulty_acute: "yes"
+    then:
+      risk_class: R3
+
+  - id: anaphylaxis_screening_clear
+    if:
+      domain: anaphylaxis
+      slot_values:
+        rash_hives: "no"
+        tongue_lip_swelling: "no"
+        breathing_difficulty_acute: "no"
+    then:
+      risk_class: R0
+
+  # ── Overdose ────────────────────────────────────────────────
+  - id: overdose_confirmed_intentional
+    if:
+      domain: overdose
+      slots_present:
+        - intent
+      slot_values:
+        intent: "intentional"
+    then:
+      risk_class: R3
+
+  - id: overdose_confirmed_altered
+    if:
+      domain: overdose
+      slots_present:
+        - consciousness_level
+      slot_values:
+        consciousness_level: "altered"
+    then:
+      risk_class: R3
+
+  - id: overdose_screening_clear
+    if:
+      domain: overdose
+      slot_values:
+        intent: "accidental"
+        consciousness_level: "alert"
+    then:
+      risk_class: R2
+
+  # ── Stroke Symptoms (BE-FAST) ────────────────────────────────
+  - id: stroke_confirmed_balance
+    if:
+      domain: stroke_symptoms
+      slot_values:
+        balance_deficit: "yes"
+    then:
+      risk_class: R3
+
+  - id: stroke_confirmed_vision
+    if:
+      domain: stroke_symptoms
+      slot_values:
+        vision_change: "yes"
+    then:
+      risk_class: R3
+
+  - id: stroke_confirmed_facial_droop
+    if:
+      domain: stroke_symptoms
+      slots_present:
+        - facial_droop
+      slot_values:
+        facial_droop: "yes"
+    then:
+      risk_class: R3
+
+  - id: stroke_confirmed_arm_weakness
+    if:
+      domain: stroke_symptoms
+      slots_present:
+        - arm_weakness
+      slot_values:
+        arm_weakness: "yes"
+    then:
+      risk_class: R3
+
+  - id: stroke_confirmed_speech
+    if:
+      domain: stroke_symptoms
+      slots_present:
+        - speech_slurring
+      slot_values:
+        speech_slurring: "yes"
+    then:
+      risk_class: R3
+
+  - id: stroke_screening_clear
+    if:
+      domain: stroke_symptoms
+      slot_values:
+        balance_deficit: "no"
+        vision_change: "no"
+        facial_droop: "no"
+        arm_weakness: "no"
+        speech_slurring: "no"
+    then:
+      risk_class: R0
+
+  # ── Exertional Dyspnea ──────────────────────────────────────
+  - id: exertional_dyspnea_new_onset
+    if:
+      domain: exertional_dyspnea
+      slot_values:
+        dyspnea_onset: "new"
+    then:
+      risk_class: R3
+
+  - id: exertional_dyspnea_chronic
+    if:
+      domain: exertional_dyspnea
+      slot_values:
+        dyspnea_onset: "chronic"
+    then:
+      risk_class: R1
+
+  - id: exertional_dyspnea_screening_clear
+    if:
+      domain: exertional_dyspnea
+      slot_values:
+        dyspnea_onset: "chronic"
+    then:
+      risk_class: R0
+
+  # ── Abnormal BP ────────────────────────────────────────────
+  - id: abnormal_bp_critical_threshold
+    if:
+      domain: abnormal_bp
+      slots_present:
+        - bp_critical
+      slot_values:
+        bp_critical: "yes"
+    then:
+      risk_class: R3
+
+  - id: abnormal_bp_any_report
+    if:
+      domain: abnormal_bp
+      slots_present:
+        - bp_report_confirmed
+      slot_values:
+        bp_report_confirmed: "yes"
+    then:
+      risk_class: R2
+
+  # ── Anticoagulant Hold Failure ─────────────────────────────
+  - id: anticoag_still_taking
+    if:
+      domain: anticoagulant_hold_failure
+      slots_present:
+        - anticoag_still_taking
+      slot_values:
+        anticoag_still_taking: "yes"
+    then:
+      risk_class: R2
+
+  - id: anticoag_hold_compliant
+    if:
+      domain: anticoagulant_hold_failure
+      slot_values:
+        anticoag_still_taking: "no"
+    then:
+      risk_class: R0
+
+  # ── NPO Violation ─────────────────────────────────────────
+  - id: npo_recent_intake
+    if:
+      domain: npo_violation
+      slots_present:
+        - npo_last_intake_time
+      slot_values:
+        npo_intake_recent: "yes"
+    then:
+      risk_class: R2
+
+  - id: npo_compliant
+    if:
+      domain: npo_violation
+      slot_values:
+        npo_intake_recent: "no"
+    then:
+      risk_class: R0
+
+  # ── Acute Illness Pre-Op ──────────────────────────────────
+  - id: preop_illness_fever
+    if:
+      domain: acute_illness_preop
+      slots_present:
+        - illness_fever_present
+      slot_values:
+        illness_fever_present: "yes"
+    then:
+      risk_class: R2
+
+  - id: preop_illness_respiratory
+    if:
+      domain: acute_illness_preop
+      slots_present:
+        - illness_respiratory_symptoms
+      slot_values:
+        illness_respiratory_symptoms: "yes"
+    then:
+      risk_class: R2
+
+  - id: preop_illness_gi
+    if:
+      domain: acute_illness_preop
+      slots_present:
+        - illness_gi_symptoms
+      slot_values:
+        illness_gi_symptoms: "yes"
+    then:
+      risk_class: R2
+
+  - id: preop_illness_clear
+    if:
+      domain: acute_illness_preop
+      slot_values:
+        illness_fever_present: "no"
+        illness_respiratory_symptoms: "no"
+        illness_gi_symptoms: "no"
+    then:
+      risk_class: R0
+
+  # ── Domestic Safety Concern ──────────────────────────────────
+  - id: domestic_safety_immediate_danger
+    if:
+      domain: domestic_safety_concern
+      slots_present:
+        - immediate_danger
+      slot_values:
+        immediate_danger: "yes"
+    then:
+      risk_class: R2
+
+  - id: domestic_safety_not_safe_to_talk
+    if:
+      domain: domestic_safety_concern
+      slots_present:
+        - safe_to_talk
+      slot_values:
+        safe_to_talk: "no"
+    then:
+      risk_class: R2
+
+  - id: domestic_safety_screening_clear
+    if:
+      domain: domestic_safety_concern
+      slot_values:
+        safe_to_talk: "yes"
+        immediate_danger: "no"
+    then:
+      risk_class: R0
+
+  # ── Context-aware risk rules ─────────────────────────────────────────
+  # These rules require BOTH slot conditions AND patient context conditions
+  # to fire. When patient_context is None, context conditions are treated
+  # as non-matching (fail closed).
+
+  - id: sob_chf_decompensation
+    if:
+      domain: shortness_of_breath_rest
+      slots_present:
+        - sob_severity
+      slot_values:
+        sob_severity: "moderate"
+      context:
+        patient_has_condition: ["I50.*"]
+    then:
+      risk_class: R2
+
+  - id: sob_severe_chf_decompensation
+    if:
+      domain: shortness_of_breath_rest
+      slots_present:
+        - sob_severity
+      slot_values:
+        sob_severity: "severe"
+      context:
+        patient_has_condition: ["I50.*"]
+    then:
+      risk_class: R2
+
+  - id: confusion_polypharmacy
+    if:
+      domain: altered_mental_status
+      slots_present:
+        - confusion_reported
+      slot_values:
+        confusion_reported: "yes"
+      context:
+        medication_count_above: 10
+    then:
+      risk_class: R2
+
+  - id: weight_gain_chf_fluid_overload
+    if:
+      domain: weight_gain_sudden
+      slots_present:
+        - weight_change_lbs
+        - weight_gain_significant
+      slot_values:
+        weight_gain_significant: "yes"
+      context:
+        patient_has_condition: ["I50.*"]
+    then:
+      risk_class: R2
+
+hard_escalate_domains:
+  - suicidal_ideation
+  - homicidal_ideation
+
+turn_outcomes:
+  - proceed
+  - clarify
+  - escalate
+  - handoff
+  - end
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Domain Suppression Rules
+# ═══════════════════════════════════════════════════════════════��══════════════
+# These rules allow an R1 domain firing at high confidence to suppress
+# an R2/R3 domain, reducing false escalations.
+# The flow engine must be updated separately to consume these rules.
+
+domain_suppression:
+  # ── Wound domains ─────────────────────────────────────────────────────
+  # When R1 wound_concern fires at medium/high confidence, suppress R2 wound_infection
+  # at low/medium confidence (not high - genuine infection signals should still escalate)
+  - suppressor: wound_concern
+    suppressed_domains:
+      - wound_infection
+    condition:
+      suppressor_min_confidence: medium  # medium or high
+      suppressed_max_confidence: medium  # low or medium (not high)
+    reason: "Routine wound concern (R1) contradicts infection (R2) at lower confidence"
+
+  # ── Chest pain domains ────────────────────────────────────────────────
+  # When R1 reproducible_chest_discomfort fires, suppress R3 chest_pain at low/medium
+  - suppressor: reproducible_chest_discomfort
+    suppressed_domains:
+      - chest_pain
+    condition:
+      suppressor_min_confidence: medium
+      suppressed_max_confidence: medium
+    reason: "Reproducible pattern suggests non-ACS chest pain"
+
+  # ── Glucose domains ───────────────────────────────────────────────────
+  # When R1 glucose_out_of_range fires, suppress R3 dka_hhs at low/medium
+  - suppressor: glucose_out_of_range
+    suppressed_domains:
+      - dka_hhs
+      - severe_hypoglycemia
+    condition:
+      suppressor_min_confidence: medium
+      suppressed_max_confidence: medium
+    reason: "Routine glucose management (R1) vs emergency (R3)"
+
+  # ── Medication domains ────────────────────────────────────────────────
+  # When R1 medication fires, suppress R3 overdose at low/medium
+  - suppressor: medication
+    suppressed_domains:
+      - overdose
+    condition:
+      suppressor_min_confidence: medium
+      suppressed_max_confidence: medium
+    reason: "Medication inquiry (R1) vs overdose (R3)"
+
+  # ── Oral intake domains ───────────────────────────────────────────────
+  # When R1 poor_oral_intake fires, suppress R2 persistent_vomiting at low/medium
+  - suppressor: poor_oral_intake
+    suppressed_domains:
+      - persistent_vomiting
+    condition:
+      suppressor_min_confidence: medium
+      suppressed_max_confidence: medium
+    reason: "Appetite concern (R1) vs persistent vomiting (R2)"
+
+  # ── Pain domains ──────────────────────────────────────────────────────
+  # When R1 worsening_chronic_pain fires, suppress R2 uncontrolled_pain at low/medium
+  - suppressor: worsening_chronic_pain
+    suppressed_domains:
+      - uncontrolled_pain
+    condition:
+      suppressor_min_confidence: medium
+      suppressed_max_confidence: medium
+    reason: "Chronic pain management (R1) vs acute uncontrolled pain (R2)"

decision/journeys/annual_wellness_visit.yaml

@@ -0,0 +1,58 @@
+wedge_type: awv
+display_name: Annual Wellness Visit
+description: >-
+  30-day annual wellness visit preparation journey. Voice calls with SMS
+  reminders. Initial outreach uses the full 12-step agenda. Subsequent calls
+  use abbreviated agendas focused on screening reminders and visit preparation.
+default_duration_days: 30
+steps:
+  - step_id: initial_outreach
+    channel: voice
+    schedule:
+      offset_days: 30
+      window_hours: [9, 17]
+    agenda_sequence:
+      - awv_intro
+      - health_history_update
+      - medication_list_review
+      - family_history_update
+      - functional_status
+      - fall_risk_screening
+      - screening_reminders
+      - immunization_reminders
+      - advance_directives
+      - depression_screening
+      - social_determinants
+      - closing
+    teachback_steps: []
+    max_retries: 3
+    retry_delay_hours: 2
+
+  - step_id: reminder_call
+    channel: voice
+    schedule:
+      offset_days: 7
+      window_hours: [9, 17]
+    agenda_sequence:
+      - awv_intro
+      - screening_reminders
+      - immunization_reminders
+      - social_determinants
+      - closing
+    teachback_steps: []
+    max_retries: 2
+    retry_delay_hours: 4
+
+  - step_id: visit_prep_call
+    channel: voice
+    schedule:
+      offset_days: 2
+      window_hours: [9, 17]
+    agenda_sequence:
+      - awv_intro
+      - medication_list_review
+      - screening_reminders
+      - closing
+    teachback_steps: []
+    max_retries: 2
+    retry_delay_hours: 2

decision/journeys/gap_closure.yaml

@@ -0,0 +1,91 @@
+wedge_type: gap_closure
+display_name: Gap Closure
+description: >-
+  30-90 day care gap closure journey. SMS-first channel strategy with voice
+  call escalation for patients who do not respond to SMS reminders. SMS
+  messages are template-driven and do NOT pass through the DCE pipeline.
+  Only voice calls invoke the engine. Voice calls use a 7-step agenda
+  focused on gap identification, barrier assessment, and scheduling assistance.
+default_duration_days: 90
+steps:
+  # Step 1: SMS reminder (template-driven, does not invoke DCE)
+  - step_id: sms_reminder_1
+    channel: sms
+    schedule:
+      offset_days: 1
+      window_hours: [9, 20]
+    agenda_sequence: []
+    teachback_steps: []
+    max_retries: 0
+    retry_delay_hours: 0
+
+  # Step 2: SMS reminder (template-driven, does not invoke DCE)
+  - step_id: sms_reminder_2
+    channel: sms
+    schedule:
+      offset_days: 7
+      window_hours: [9, 20]
+    agenda_sequence: []
+    teachback_steps: []
+    max_retries: 0
+    retry_delay_hours: 0
+
+  # Step 3: SMS reminder (template-driven, does not invoke DCE)
+  - step_id: sms_reminder_3
+    channel: sms
+    schedule:
+      offset_days: 14
+      window_hours: [9, 20]
+    agenda_sequence: []
+    teachback_steps: []
+    max_retries: 0
+    retry_delay_hours: 0
+
+  # Step 4: First voice call — full 7-step gap closure agenda
+  - step_id: initial_outreach_call
+    channel: voice
+    schedule:
+      offset_days: 21
+      window_hours: [9, 17]
+    agenda_sequence:
+      - gap_intro
+      - gap_identification
+      - barrier_assessment
+      - motivational_support
+      - scheduling_assistance
+      - questions
+      - closing
+    teachback_steps: []
+    max_retries: 3
+    retry_delay_hours: 2
+
+  # Step 5: Follow-up voice call — abbreviated agenda
+  - step_id: follow_up_call
+    channel: voice
+    schedule:
+      offset_days: 45
+      window_hours: [9, 17]
+    agenda_sequence:
+      - gap_intro
+      - gap_identification
+      - scheduling_assistance
+      - closing
+    teachback_steps: []
+    max_retries: 2
+    retry_delay_hours: 4
+
+  # Step 6: Final voice call — last attempt
+  - step_id: final_outreach_call
+    channel: voice
+    schedule:
+      offset_days: 75
+      window_hours: [9, 17]
+    agenda_sequence:
+      - gap_intro
+      - gap_identification
+      - barrier_assessment
+      - scheduling_assistance
+      - closing
+    teachback_steps: []
+    max_retries: 2
+    retry_delay_hours: 4

decision/journeys/health_risk_assessment.yaml

@@ -0,0 +1,45 @@
+wedge_type: hra
+display_name: Health Risk Assessment
+description: >-
+  14-day health risk assessment journey. Voice calls with SMS reminders.
+  Initial call uses the full 10-step agenda covering chronic conditions,
+  functional status, mental health screening, social determinants, and
+  preventive care review. Follow-up call uses abbreviated agenda for
+  incomplete sections.
+default_duration_days: 14
+steps:
+  - step_id: initial_hra_call
+    channel: voice
+    schedule:
+      offset_days: 1
+      window_hours: [9, 17]
+    agenda_sequence:
+      - hra_intro
+      - chronic_condition_inventory
+      - functional_status_assessment
+      - mental_health_screen
+      - social_determinants_screen
+      - medication_burden_review
+      - preventive_care_review
+      - care_plan_summary
+      - closing
+      - wrap_up
+    teachback_steps: []
+    max_retries: 3
+    retry_delay_hours: 2
+
+  - step_id: followup_hra_call
+    channel: voice
+    schedule:
+      offset_days: 7
+      window_hours: [9, 17]
+    agenda_sequence:
+      - hra_intro
+      - mental_health_screen
+      - social_determinants_screen
+      - preventive_care_review
+      - care_plan_summary
+      - closing
+    teachback_steps: []
+    max_retries: 2
+    retry_delay_hours: 4

decision/journeys/post_discharge_engagement.yaml

@@ -0,0 +1,120 @@
+wedge_type: pde
+display_name: Post-Discharge Engagement
+description: >-
+  3-30 day post-discharge follow-up journey. Voice calls with SMS reminders.
+  Day 1 uses the full 14-step agenda. Subsequent calls use abbreviated agendas
+  focused on evolving patient needs.
+default_duration_days: 30
+steps:
+  - step_id: day1_call
+    channel: voice
+    schedule:
+      offset_days: 1
+      window_hours: [9, 17]
+    agenda_sequence:
+      - intro_permission
+      - discharge_context
+      - teachback_diagnosis
+      - teachback_warning_signs
+      - general_status
+      - symptom_review
+      - meds_reconciliation
+      - appointments_check
+      - pending_tests
+      - home_services
+      - problem_solving
+      - emergency_plan
+      - closing
+      - wrap_up
+    teachback_steps:
+      - teachback_diagnosis
+      - teachback_warning_signs
+    max_retries: 3
+    retry_delay_hours: 2
+    conditional_probes:
+      - probe_id: chf_symptom_review
+        when:
+          patient_has_condition: ["I50.*"]
+        must_ask:
+          - "Have you been weighing yourself daily as instructed?"
+          - "Have you noticed any new or worsening swelling in your legs or ankles?"
+          - "Have you had any trouble breathing when lying flat?"
+        slots_to_extract: ["daily_weight_check", "edema_worsening", "orthopnea"]
+        reason: "CHF-specific symptom monitoring per AHA guidelines"
+      - probe_id: copd_symptom_review
+        when:
+          patient_has_condition: ["J44.*", "J43.*"]
+        must_ask:
+          - "Have you noticed any change in your sputum color or amount?"
+          - "Are you using your rescue inhaler more than usual?"
+        slots_to_extract: ["sputum_change", "rescue_inhaler_frequency"]
+        reason: "COPD exacerbation early detection"
+      - probe_id: diabetes_symptom_review
+        when:
+          patient_has_condition: ["E11.*", "E10.*"]
+        must_ask:
+          - "Have you been checking your blood sugar regularly?"
+          - "Have you had any episodes of very high or very low blood sugar?"
+        slots_to_extract: ["glucose_monitoring", "glucose_extremes"]
+        reason: "Post-discharge glucose management"
+    pre_populated_slots:
+      - slot: discharge_med_count
+        source_field: discharge_info.discharge_medications
+        reason: "Pre-populate from discharge medication list"
+
+  - step_id: day3_call
+    channel: voice
+    schedule:
+      offset_days: 3
+      window_hours: [9, 17]
+    agenda_sequence:
+      - intro_permission
+      - general_status
+      - symptom_review
+      - meds_reconciliation
+      - closing
+    teachback_steps: []
+    max_retries: 2
+    retry_delay_hours: 4
+
+  - step_id: day7_call
+    channel: voice
+    schedule:
+      offset_days: 7
+      window_hours: [9, 17]
+    agenda_sequence:
+      - intro_permission
+      - appointments_check
+      - problem_solving
+      - closing
+    teachback_steps: []
+    max_retries: 2
+    retry_delay_hours: 4
+
+  - step_id: day14_call
+    channel: voice
+    schedule:
+      offset_days: 14
+      window_hours: [9, 17]
+    agenda_sequence:
+      - intro_permission
+      - general_status
+      - symptom_review
+      - closing
+    teachback_steps: []
+    max_retries: 2
+    retry_delay_hours: 4
+
+  - step_id: day30_call
+    channel: voice
+    schedule:
+      offset_days: 30
+      window_hours: [9, 17]
+    agenda_sequence:
+      - intro_permission
+      - general_status
+      - emergency_plan
+      - closing
+    teachback_steps: []
+    max_retries: 2
+    retry_delay_hours: 4

decision/journeys/pre_op_optimization.yaml

@@ -0,0 +1,83 @@
+wedge_type: pre_op
+display_name: Pre-Op Optimization
+description: >-
+  7-90 day pre-surgery optimization journey. Voice calls with SMS reminders.
+  Initial call uses the full 10-step agenda. Subsequent calls use abbreviated
+  agendas focused on compliance verification and anxiety management.
+default_duration_days: 90
+steps:
+  - step_id: initial_assessment
+    channel: voice
+    schedule:
+      offset_days: 7
+      window_hours: [9, 17]
+    agenda_sequence:
+      - preop_intro
+      - health_history_update
+      - medication_review
+      - allergy_verification
+      - npo_status
+      - anxiety_screening
+      - procedure_prep
+      - logistics
+      - questions
+      - closing
+    teachback_steps:
+      - npo_status
+    max_retries: 3
+    retry_delay_hours: 2
+    conditional_probes:
+      - probe_id: anticoagulant_hold_check
+        when:
+          patient_on_medication_class: ["anticoagulant", "DOAC"]
+        must_ask:
+          - "Have you stopped taking your blood thinner as instructed?"
+          - "When did you take your last dose?"
+        slots_to_extract: ["anticoag_stopped", "last_anticoag_dose"]
+        reason: "Anticoagulant hold verification per ERAS guidelines"
+      - probe_id: glp1_hold_check
+        when:
+          patient_on_medication_class: ["GLP-1_agonist"]
+        must_ask:
+          - "Have you stopped taking your GLP-1 medication as instructed?"
+        slots_to_extract: ["glp1_stopped"]
+        reason: "GLP-1 agonist hold per updated ERAS guidelines"
+      - probe_id: insulin_management
+        when:
+          patient_on_medication_class: ["insulin"]
+        must_ask:
+          - "Have you adjusted your insulin dose as your surgeon instructed?"
+        slots_to_extract: ["insulin_adjusted"]
+        reason: "Perioperative insulin management"
+
+  - step_id: compliance_check
+    channel: voice
+    schedule:
+      offset_days: 3
+      window_hours: [9, 17]
+    agenda_sequence:
+      - preop_intro
+      - medication_review
+      - npo_status
+      - anxiety_screening
+      - closing
+    teachback_steps:
+      - npo_status
+    max_retries: 2
+    retry_delay_hours: 4
+
+  - step_id: day_before_call
+    channel: voice
+    schedule:
+      offset_days: 1
+      window_hours: [9, 17]
+    agenda_sequence:
+      - preop_intro
+      - npo_status
+      - logistics
+      - anxiety_screening
+      - closing
+    teachback_steps:
+      - npo_status
+    max_retries: 2
+    retry_delay_hours: 2

decision/orchestrator/conflict_resolution.yaml

@@ -0,0 +1,79 @@
+# Cross-wedge conflict resolution rules.
+# When two wedges compete for the same contact slot, these rules decide
+# which one proceeds and what happens to the other.
+
+conflict_rules:
+  # PDE and Pre-Op on same day: PDE wins (higher priority_rank), Pre-Op defers
+  - rule_id: pde_preop_same_day
+    wedge_a: pde
+    wedge_b: pre_op
+    condition: same_day
+    winner: higher_priority
+    loser_action: defer_24h
+
+  # Tier 1 vs Tier 2 on same day: Tier 1 always wins
+  - rule_id: tier1_beats_tier2
+    wedge_a: pde
+    wedge_b: awv
+    condition: same_day
+    winner: higher_priority
+    loser_action: defer_24h
+
+  - rule_id: tier1_beats_gap
+    wedge_a: pde
+    wedge_b: gap_closure
+    condition: same_day
+    winner: higher_priority
+    loser_action: defer_24h
+
+  - rule_id: tier1_beats_hra
+    wedge_a: pde
+    wedge_b: hra
+    condition: same_day
+    winner: higher_priority
+    loser_action: defer_24h
+
+  - rule_id: preop_beats_awv
+    wedge_a: pre_op
+    wedge_b: awv
+    condition: same_day
+    winner: higher_priority
+    loser_action: defer_24h
+
+  - rule_id: preop_beats_gap
+    wedge_a: pre_op
+    wedge_b: gap_closure
+    condition: same_day
+    winner: higher_priority
+    loser_action: defer_24h
+
+  - rule_id: preop_beats_hra
+    wedge_a: pre_op
+    wedge_b: hra
+    condition: same_day
+    winner: higher_priority
+    loser_action: defer_24h
+
+  # Within Tier 2: AWV > Gap Closure > HRA (by priority_rank)
+  - rule_id: awv_beats_gap
+    wedge_a: awv
+    wedge_b: gap_closure
+    condition: same_day
+    winner: higher_priority
+    loser_action: defer_24h
+
+  - rule_id: awv_beats_hra
+    wedge_a: awv
+    wedge_b: hra
+    condition: same_day
+    winner: higher_priority
+    loser_action: defer_24h
+
+  - rule_id: gap_beats_hra
+    wedge_a: gap_closure
+    wedge_b: hra
+    condition: same_day
+    winner: higher_priority
+    loser_action: defer_24h
+
+default_loser_action: defer_24h

decision/orchestrator/contact_caps.yaml

@@ -0,0 +1,16 @@
+global_max_per_day: 2
+global_max_per_week: 7
+channel_caps:
+  - channel: voice
+    max_per_day: 1
+    max_per_week: 5
+  - channel: sms
+    max_per_day: 2
+    max_per_week: 10
+  - channel: email
+    max_per_day: 1
+    max_per_week: 3
+quiet_hours:
+  start: "21:00"
+  end: "09:00"
+emergency_override: true

decision/orchestrator/enrollment_rules.yaml

@@ -0,0 +1,53 @@
+# Enrollment rules for journey lifecycle management.
+# Controls eligibility, deduplication, and cooldown periods.
+
+dedup_key_fields:
+  - patient_id
+  - wedge_type
+  - trigger_event_id
+
+enrollment_criteria:
+  - wedge_type: pde
+    required_events:
+      - adt_discharge
+    eligible_statuses:
+      - discharged
+    cooldown_days: 30
+    max_concurrent_journeys: 1
+
+  - wedge_type: pre_op
+    required_events:
+      - surgery_scheduled
+    eligible_statuses:
+      - scheduled
+    cooldown_days: 7
+    max_concurrent_journeys: 1
+
+  - wedge_type: awv
+    required_events:
+      - awv_eligible
+    eligible_statuses:
+      - eligible
+    cooldown_days: 365
+    max_concurrent_journeys: 1
+
+  - wedge_type: gap_closure
+    required_events:
+      - gap_identified
+    eligible_statuses:
+      - open
+    cooldown_days: 90
+    max_concurrent_journeys: 3
+
+  - wedge_type: hra
+    required_events:
+      - hra_eligible
+    eligible_statuses:
+      - eligible
+    cooldown_days: 365
+    max_concurrent_journeys: 1
+
+global_enrollment_settings:
+  max_active_journeys_per_patient: 3
+  require_consent: true
+  allow_re_enrollment: true

decision/orchestrator/wedge_priority.yaml

@@ -0,0 +1,16 @@
+priorities:
+  - wedge_type: pde
+    safety_tier: 1
+    priority_rank: 100
+  - wedge_type: pre_op
+    safety_tier: 1
+    priority_rank: 90
+  - wedge_type: awv
+    safety_tier: 2
+    priority_rank: 50
+  - wedge_type: gap_closure
+    safety_tier: 2
+    priority_rank: 40
+  - wedge_type: hra
+    safety_tier: 2
+    priority_rank: 30

decision/orchestrator/wedge_suppression.yaml

@@ -0,0 +1,78 @@
+# Temporal suppression rules for cross-wedge contact orchestration.
+# After certain events, suppress outbound contacts for specified wedges.
+# Escalation lock suppression blocks ALL wedges for ALL channels.
+
+suppression_rules:
+  # After any PDE voice call, suppress routine wedges for 24 hours
+  - rule_id: pde_call_suppresses_routine
+    trigger_wedge: pde
+    trigger_event: call_completed
+    suppress_wedges:
+      - awv
+      - gap_closure
+      - hra
+    suppress_channels:
+      - voice
+      - sms
+      - email
+    duration_hours: 24
+
+  # After any Pre-Op voice call, suppress routine wedges for 24 hours
+  - rule_id: preop_call_suppresses_routine
+    trigger_wedge: pre_op
+    trigger_event: call_completed
+    suppress_wedges:
+      - awv
+      - gap_closure
+      - hra
+    suppress_channels:
+      - voice
+      - sms
+      - email
+    duration_hours: 24
+
+  # After R3 escalation lock, suppress ALL wedges (all channels)
+  - rule_id: r3_lock_suppresses_all
+    trigger_wedge: any
+    trigger_event: escalation_lock_r3
+    suppress_wedges:
+      - pde
+      - pre_op
+      - awv
+      - gap_closure
+      - hra
+    suppress_channels:
+      - voice
+      - sms
+      - email
+    duration_hours: 24
+
+  # After R2 escalation lock, suppress ALL wedges (all channels)
+  - rule_id: r2_lock_suppresses_all
+    trigger_wedge: any
+    trigger_event: escalation_lock_r2
+    suppress_wedges:
+      - pde
+      - pre_op
+      - awv
+      - gap_closure
+      - hra
+    suppress_channels:
+      - voice
+      - sms
+      - email
+    duration_hours: 72
+
+  # After any voice call, suppress voice for same patient for 4 hours
+  - rule_id: voice_cooldown
+    trigger_wedge: any
+    trigger_event: call_completed
+    suppress_wedges:
+      - pde
+      - pre_op
+      - awv
+      - gap_closure
+      - hra
+    suppress_channels:
+      - voice
+    duration_hours: 4

decision/primitives/clarify.yaml

@@ -0,0 +1,23 @@
+flow_id: clarify
+type: primitive
+
+actions:
+  - step: 1
+    type: ask
+    response_spec:
+      id: global_clarify
+      goal: "Ask the patient to repeat or clarify what they said"
+      tone: gentle_professional
+      must_include:
+        - "understand"
+      must_ask:
+        - "could you say that again"
+      must_not:
+        - "diagnos"
+      max_questions: 1
+    collects:
+      - clarification_text
+
+exit:
+  on_complete: re_evaluate
+  on_unclear: handoff