ai-contract-platform/project-docs/V2-phase3-review-result-write-path-policy-2026-07-01.md

V2 Phase 3 Review Result Write Path Policy

Date: 2026-07-01

Background

Phase 3 has introduced structured review result tables:

• review_risk_items
• review_citations
• review_repair_actions

Read paths are being moved to structured-first behavior while keeping the public ReviewTask.risk_items and ReviewTask.citations response fields compatible.

The current write path still dual-writes legacy JSON and structured rows:

1. review_worker.execute_review_task(...) converts AI Platform review output into JSON-compatible risk_items, citations, and primary_sources.
2. SqlAlchemyReviewOrchestration.complete_review_task(...) enriches risk_items with legal asset recommendations such as clause_recommendations.
3. ContractReviewTaskRepository.complete_review_task(...) writes review_tasks.risk_items, review_tasks.citations, primary_sources, confidence, and ai_audit_run_id.
4. sync_structured_review_results(...) rebuilds review_risk_items and review_citations from the persisted review task payload.
5. Clause repair writes structured repair state and still updates legacy risk_items when legacy JSON exists.

Decision

Do not stop writing legacy review_tasks.risk_items or review_tasks.citations yet.

For the current Phase 3 slice, these JSON columns are compatibility/display caches, not the primary source for structured queries or state decisions when structured rows exist.

Field Policy

Field	Current role	Policy
review_tasks.risk_items	Compatibility display cache. Still carries rich UI payload such as clause_recommendations, original AI fields, related_clause, and legacy repair display fields.	Continue dual-write. Do not treat as primary read source when structured rows exist.
review_tasks.citations	Compatibility display cache. Can carry metadata not yet modeled in review_citations, such as source_type, score, locator, document_id, chunk_id, and knowledge_base_id.	Continue dual-write. Structured citations remain primary for query/search; legacy-only citations stay supplemental.
review_tasks.primary_sources	AI source payload cache. Not covered by the structured risk/citation migration.	Continue write. Revisit in a later source/provenance slice.
review_tasks.risk_level	Aggregate task-level risk.	Continue write.
review_risk_items	Structured risk rows for queries, action context, repair state, and structured read APIs.	Primary source for structured behavior.
review_citations	Structured citation rows for query/search and structured read APIs.	Primary source for structured citation behavior.
review_repair_actions	Structured repair action history.	Primary source for repair audit/state.

Freeze Preconditions

Before freezing or stopping writes to review_tasks.risk_items, V2 needs one of:

• structured storage for full clause recommendation cards, or
• a serializer that can regenerate compatible clause_recommendations from published clause/rule snapshots, repair actions, and structured risk rows.

Before freezing or stopping writes to review_tasks.citations, V2 needs one of:

• structured metadata on review_citations, or
• a serializer that can regenerate compatibility fields such as source_type, score, locator, document_id, chunk_id, and knowledge_base_id.

Guardrails

• Keep API responses compatible: ReviewTask.risk_items and ReviewTask.citations remain present.
• New read/query/search behavior should use structured rows first.
• Legacy JSON may supplement structured rows where it contains compatibility-only fields.
• No column removal or stop-write migration should be done until the freeze preconditions are met and verified in smoke.

Completed Follow-Up Slice

The first structured recommendation slice is complete:

• review_risk_recommendations now stores recommendation cards structurally.
• StructuredReviewRisk.clause_recommendations is available to management/read pages.
• ReviewTask.risk_items can synthesize clause_recommendations from structured recommendations when legacy risk JSON is absent.

Legacy review_tasks.risk_items is still written as a compatibility display cache. It should not be frozen until smoke backfill verifies recommendation coverage on existing review tasks.

Status Update

As of this slice, the legacy JSON fields remain writable and are intentionally treated as compatibility display caches.

Structured rows are already the primary source for query/search/repair logic, but the JSON payload is still needed for front-end compatibility until recommendation cards and citation metadata are fully modeled structurally.