yuqei
a3bb78e06b
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m35s
75 lines
4.6 KiB
Markdown
75 lines
4.6 KiB
Markdown
# 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.
|