Implement document reconciliation v2

docs/document_reconciliation_v2.md

@@ -0,0 +1,39 @@
+# Document Reconciliation v2
+
+After a group is completely classified, `opportunity_document_links` is the
+sole authority for document selection. During rollout the canonical resolver
+uses legacy fields for a whole `(opportunity_id, document_kind)` group until
+every legacy document in that group has a current v2 link. It never mixes both
+authorities inside a group. `commercial_documents.opportunity_id`, `role`,
+`is_primary` and `is_active` are dual-write compatibility fields only.
+
+## Deployment
+
+1. Deploy this compatibility code first. It can run before migration 007.
+2. Run `python scripts/preflight_document_reconciliation_v2.py`; stop on any blocker.
+3. Run `python scripts/apply_migrations.py --dry-run` and review the pending migration.
+4. Run `python scripts/apply_migrations.py` against the intended database.
+5. Keep all consumers on this compatible release. Do not deploy v2-exclusive readers.
+6. Dry-run group batches and archive JSON/CSV: `python scripts/migrate_document_reconciliation_v2.py --dry-run --batch-size 500 --output-json /safe/path/batch.json`.
+7. Apply complete group batches. Resume with the emitted composite checkpoint,
+   `--resume-from 'OPPORTUNITY_UUID|document_kind'`. A group is checkpointed only
+   after all its documents commit.
+8. `--only-unambiguous` still writes `REVIEW_REQUIRED` links (option B), so groups
+   never become partially invisible. Resolve reviews in the admin UI.
+9. Verify no legacy-resolved groups remain, then v2-exclusive readers may be deployed.
+
+## Rollback
+
+Rollback application code first and stop every v2 consumer. Export
+`opportunity_document_link_events`; confirm all legacy compatibility fields are
+filled. In a dedicated psql session set
+`clientflow.v2_consumers_active='off'` and
+`clientflow.document_ledger_exported='on'`, then execute
+`migrations/007_document_reconciliation_v2_down.sql`. The down migration checks
+these conditions and removes dependent line columns, trigger/function, events,
+command claims and links in dependency order. The ledger is lost after export;
+manual decisions made only in v2 must be reconciled before rollback. Neither
+migration changes remote Jasmin documents.
+
+CSRF remains separate security debt; this change reuses existing admin
+authentication and does not claim to add CSRF protection.