ai-contract-platform/project-docs/V2-phase3-structured-review-clause-repair-read-path-2026-07-01.md

V2 Phase 3 Structured Review Clause Repair Read Path

Date: 2026-07-01

Scope

This slice moves clause repair target resolution from legacy review_tasks.risk_items toward structured review_risk_items first.

Legacy JSON is still written back for compatibility when it exists. This slice does not remove old fields or change the public review task payload.

Changes

• Added find_display_review_risk(...) to the backend structured review read model.
• SqlAlchemyClauseRepairOrchestration.apply_clause_repair(...) now resolves the requested risk through the read model:
  • structured risk rows first
  • legacy JSON fallback only when structured rows are missing
• Applying a repair with an explicit missing risk_id now raises a workflow error.
• The existing compatibility write remains:
  • legacy review_task.risk_items is marked applied when present
  • structured review_risk_items is marked applied via record_structured_repair_action(...)
• Added a regression proving clause repair still succeeds when legacy risk_items is empty but structured risk rows exist.

Validation

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_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_clause_repair_uses_structured_risk_when_legacy_json_is_empty -q
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_structured_review_results.py -q

Observed:

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

Next Step

Continue toward structured write dominance: move any remaining repair-state decisions out of legacy review_tasks.risk_items, then decide whether review_tasks.risk_items should become response-only compatibility data.