# V2 Phase 3 Structured Review Response Overlay

Date: 2026-07-01

## Scope

This slice moves review-task response display state away from legacy `review_tasks.risk_items` as the source of truth.

The API still returns `risk_items` for compatibility, but `repair_status` and applied clause fields are now overlaid from structured `review_risk_items` / `review_repair_actions` when available.

## Changes

- `review_task_from_model(...)` now uses `display_risk_items_from_model(...)`.
- Response `risk_items` are built as:
  - structured risk rows first
  - legacy JSON fields merged in when present
  - structured `repair_status` overriding legacy status
  - latest structured repair action adding `applied_clause_id`, `applied_at`, and `applied_by`
- If legacy `review_tasks.risk_items` is empty but structured rows exist, the API still emits compatible `risk_items` from structured data.
- Existing JSON columns are not removed and remain compatibility storage.

## Validation

```powershell
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_clause_repair_uses_structured_risk_when_legacy_json_is_empty -q
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py -q -k "clause_repair"
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_structured_review_results.py -q
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_structured_review_results_drive_next_action_when_legacy_json_is_empty yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_unified_search_returns_contract_file_and_review_task yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_review_worker_calls_ai_platform_and_persists_result -q
```

Observed:

```text
.                                                                        [100%]
...                                                                      [100%]
.........                                                                [100%]
...                                                                      [100%]
```

## Next Step

Continue this structured-first response pattern for citations if needed, then audit remaining legacy `risk_items` mutation paths before deciding whether old review JSON should become response-only compatibility data.