ai-contract-platform/project-docs/V2-phase3-structured-review-results-implementation-2026-06-30.md

V2 Phase 3 Structured Review Results Implementation

Date: 2026-06-30

This note records Phase 3 Slice 3.5, first implementation slice.

Scope

Implemented the expand + dual-write foundation for structured contract review results.

This slice does not change API responses, frontend behavior, or existing JSON compatibility fields.

Added Schema

New Contract API Alembic revision:

• 20260630_0023_add_structured_review_results.py

New tables:

• review_risk_items
• review_citations
• review_repair_actions

The old JSON snapshot fields remain:

• review_tasks.risk_items
• review_tasks.citations
• review_tasks.primary_sources

Runtime Behavior

Review completion now dual-writes:

• existing JSON snapshots on review_tasks;
• structured review_risk_items;
• structured review_citations.

Clause repair now dual-writes:

• updated JSON review_tasks.risk_items repair status;
• structured review_repair_actions;
• structured review_risk_items.repair_status = applied.

Compatibility

Kept unchanged:

• review task list API;
• contract detail response shape;
• AI worker output mapping;
• clause repair API;
• existing JSON fallback behavior.

No cleanup migration was added. No old columns were removed.

Schema Check

Runtime schema-check now treats the new structured review result tables as Contract API core tables and governance-checked tables.

Verification

python -m compileall -q yuqei-contract-platform\services\contract-api\src\yuqei_contract_api
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_review_completion_dual_writes_structured_results yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_clause_repair_dual_writes_structured_repair_action yuqei-contract-platform\services\contract-api\tests\test_health.py::test_runtime_schema_check_warns_for_local_sqlite_auto_created_schema -q
python -m alembic -c alembic.ini heads

Result:

• Compile passed.
• Structured review result dual-write tests passed.
• Runtime schema-check local test passed.
• Alembic head is now 20260630_0023.

Next Slice

Recommended next step:

• Add an idempotent backfill command for existing review_tasks.risk_items / citations into the new structured tables.
• Then add read-side repository helpers for querying risks by contract, review task, risk level, and clause id.
• Keep API compatibility until structured read paths have passed smoke verification.