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

V2 Phase 3 Structured Review Citation Response Overlay

Date: 2026-07-01

Scope

This slice moves ReviewTask.citations response data toward structured review_citations as the primary source.

The public response still includes citations for compatibility. Legacy review_tasks.citations remains fallback and supplemental data.

Changes

• review_task_from_model(...) now uses display_citations_from_model(...).
• Response citations are built as:
  • structured citation rows first
  • legacy JSON fields merged when the same citation key exists
  • legacy-only citations appended for compatibility
• If legacy review_tasks.citations is empty but structured rows exist, the API still emits compatible citation items.
• The merge key is risk_item_id + source_id + article_id + reference, with blank/whitespace values normalized before comparison.
• Existing JSON columns are not removed.
• review_result_read_model.display_review_citations(...) now follows the same structured-first plus legacy-only supplemental strategy, so unified search and other shared read paths can still see historical compatibility-only citation text.

Validation

python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_review_task_response_citations_use_structured_overlay_with_legacy_fallback -q
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_unified_search_returns_contract_file_and_review_task -q
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_review_worker_calls_ai_platform_and_persists_result yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_unified_search_returns_contract_file_and_review_task -q
python -m py_compile yuqei-contract-platform\services\contract-api\src\yuqei_contract_api\persistence\review_tasks.py

Observed:

.                                                                        [100%]
.                                                                        [100%]
.                                                                        [100%]
...                                                                      [100%]
.........                                                                [100%]
..                                                                       [100%]

Additional regression coverage:

• Same-key structured citation overrides title/reference/quote while preserving legacy compatibility fields such as score.
• Legacy-only citation JSON remains appended after structured rows.

Next Step

Audit remaining write paths that mutate legacy review_tasks.risk_items / review_tasks.citations; after that, define whether those JSON fields become response-only compatibility payloads or are frozen for historical backcompat.