ai-contract-platform/project-docs/V2-phase3-structured-review-response-overlay-2026-07-01.md

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

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:

.                                                                        [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.