Revised and simplified V4 Plan and core documents.

docs/ver4/implementation_plan_v4.md

@@ -2,106 +2,96 @@
 
 ## Goal
 
-Implement V4 document-person relationship expansion and document type governance with extensible registries, assisted suggestion lifecycle, and policy-enforced exclusivity while preserving V3 transcription behavior.
+Implement the Version 4 project definition from the current repository state while preserving existing data by default.
+
+## Migration Policy
+
+- Database changes are non-destructive by default.
+- Exception: the legacy `document_type` text field may be replaced by a `document_type_id` reference without migrating existing text values.
+- Exception: `document_person` links may be recreated manually.
 
 ## Current Project Impact
 
-- `src/transcription/db/models.py` will require relationship schema evolution for role extensibility and suggestion lifecycle support.
-- `src/transcription/db/models.py` will require document type registry entities and document type reference updates.
-- `src/transcription/services/documents.py` will require set-based relationship sync and policy checks.
-- `src/transcription/services/documents.py` will require registry-based document type lookup, validation, and normalization helpers.
-- API modules under `src/transcription/api/**` will require role/state-aware contracts and suggestion lifecycle endpoints.
-- API modules under `src/transcription/api/**` will require additive document type catalog and code-based selection contracts.
-- UI pages under `src/transcription/ui/pages/**` will require multi-role, multi-person editing, suggestion review controls, and registry-backed type selectors.
-- Existing tests under `tests/services`, `tests/api`, and `tests/ui` need expanded coverage for V4 behavior and regression safety.
+- `src/transcription/db/models.py` requires full schema alignment with the V4 core documents.
+- `src/transcription/services/documents.py` requires set-based document-person sync, exclusivity checks, and document-type resolution.
+- API modules require additive role-aware relationship behavior and document-type selection behavior.
+- UI pages require grouped role displays, multi-role editing, and registry-backed document-type selection.
+- Existing tests require updates for role enforcement, document-type selection, and regression safety.
 
 ## Implementation Phases
 
-### 1. Finalize V4 Schema Decisions
+### 1. Finalize the Transition Documents
 
-- Role extensibility mechanism: use role registry tables.
-- Document type extensibility mechanism: use `document_type` registry tables.
-- Suggestion storage model: use a separate `document_person_suggestion` table.
-- Exclusivity baseline: `author` vs `recipient` exclusive, `mentioned` non-exclusive.
-- Enforce exclusivity on asserted links; evaluate conflicts on suggestion acceptance.
+- Confirm the reset scope.
+- Confirm the database exception policy.
+- Keep core V4 documents as the only authoritative product definition.
 
-### 2. Evolve Persistence Layer
+### 2. Align the Persistence Layer
 
-- Implement selected schema model in SQLModel.
-- Add constraints and indexes for dedupe, filtering, and policy support.
-- Add migration/backfill logic for V3 links to V4 asserted semantics.
-- Add conflict scan tooling for historical records violating exclusivity rules.
-- Perform a one-time manual mapping of existing document type values to registry-backed type references (`document_type_id`) for the current small corpus.
+- Update SQLModel definitions to match the final V4 schema.
+- Add `person_role`, `role_exclusivity`, and `document_type` support.
+- Replace legacy document-type storage with `document_type_id`.
+- Apply the accepted manual exception strategy for `document_type` and `document_person` data.
+- Preserve all other data structures non-destructively.
 
-### 3. Implement Service-Layer Policy and Sync Semantics
+### 3. Update Services and Write Semantics
 
-- Add relationship delta sync operations (set-based add/remove).
-- Implement centralized policy evaluator for exclusivity checks.
-- Add suggestion lifecycle operations (propose/list/accept/reject).
-- Ensure accepted suggestions create/confirm asserted links atomically.
-- Add document type resolution operations by stable `code` and active/inactive state handling.
+- Implement set-based synchronization for document-person updates.
+- Implement deterministic exclusivity conflict checks.
+- Remove suggestion-related service behavior.
+- Add document-type resolution and validation by stable code or id.
 
-### 4. Implement API Contract Changes
+### 4. Update API Contracts
 
-- Add role-aware and state-aware query parameters/filters.
-- Add suggestion lifecycle endpoints and response models.
-- Add deterministic conflict/error payloads aligned to V4 error policy.
-- Use additive endpoint evolution for V4; during development mode, deprecate then remove without maintaining long-lived legacy runtime compatibility layers.
-- Add document type catalog endpoints with active-only filtering and code-based selection for document writes.
+- Keep API evolution additive.
+- Add role-aware relationship retrieval and write behavior.
+- Add document-type catalog retrieval and code-based selection for document writes.
+- Remove suggestion-related API surfaces from the V4 target state.
 
 ### 5. Update UI Workflows
 
-- Replace single-author controls with grouped multi-role selectors.
-- Replace unconstrained document type free-text entry with registry-backed type selection.
-- Add pending suggestion review panel and accept/reject actions.
-- Update document/person detail cards to group links by role and state.
-- Preserve edit-state ergonomics on validation/conflict failures.
+- Replace single-person link editing with grouped multi-role editing.
+- Render grouped role links on document and person detail views.
+- Replace free-text document type entry with registry-backed selection.
+- Preserve clear validation and conflict messaging.
 
 ### 6. Verification and Hardening
 
-- Add service tests for:
-  - many-per-role behavior,
-  - exclusivity enforcement,
-  - set-based sync correctness,
-  - suggestion transition validity,
-  - document type code resolution and inactive-type handling.
-- Add API tests for role/state filtering and conflict response shapes.
-- Add API tests for document type catalog retrieval and code-based write validation.
-- Add UI tests/manual walkthroughs for create/edit/review workflows.
-- Add UI tests/manual walkthroughs for registry-backed document type selection and validation messaging.
-- Add regression tests for document/person delete cleanup semantics.
+- Add or update service tests for many-per-role behavior, exclusivity enforcement, and set-based sync correctness.
+- Add API tests for relationship behavior and document-type selection.
+- Add UI tests or walkthrough coverage for grouped roles and type selection.
+- Add regression coverage for delete and cleanup semantics.
 
 ## Done When
 
-- V4 relationship schema and contracts are implemented and validated.
-- V4 document type registry schema and contracts are implemented and validated.
-- Suggestions remain non-canonical until explicit acceptance.
-- Exclusivity policy is enforced deterministically across service/API boundaries.
-- Existing V3 links are migrated to V4 asserted semantics without data loss.
-- Existing document type strings are manually normalized to registry references for the current corpus.
-- Test suite includes V4-specific coverage and passes on supported backends.
+- Core V4 documents and code paths agree on the final project definition.
+- Relationship-role writes are deterministic and non-destructive.
+- Exclusivity rules are enforced consistently.
+- Document type selection is registry-backed.
+- The accepted manual exceptions for `document_type` and `document_person` are completed.
+- The focused test coverage passes.
 
 ## Out of Scope
 
-- Automatic acceptance of suggestions.
-- Global person entity-resolution/merge engine.
-- Core transcription execution redesign unrelated to relationship expansion.
-- Automated semantic document type classification.
+- Suggested/asserted relationship state.
+- Suggestion review or extraction workflows.
+- Global person entity-resolution engine.
+- Automated semantic document-type classification.
 
 ## Delivery Order Recommendation
 
-1. Requirements freeze (`requirements_v4.md`).
-2. Schema decision freeze (`schema_v4.md`).
-3. Error policy freeze (`error_handling_v4.md`).
-4. Implementation of persistence and service layer.
-5. API and UI changes.
-6. Final integration and regression validation.
+1. Freeze scope boundary and implementation plan.
+2. Freeze core V4 documents.
+3. Align persistence models.
+4. Align services and API behavior.
+5. Align UI behavior.
+6. Run focused verification and regression checks.
 
 ## Related Local References
 
 - [V4 Scope Boundary](scope_boundary_v4.md)
-- [V4 Requirements](requirements_v4.md)
-- [V4 Schema](schema_v4.md)
-- [V4 Architecture](architecture_v4.md)
-- [V4 Error Handling](error_handling_v4.md)
-- [V3 Implementation Plan](../implementation_plan_v3.md)
+- [System Overview](index_v4.md)
+- [System Requirements](requirements_v4.md)
+- [Data Model](schema_v4.md)
+- [System Architecture](architecture_v4.md)
+- [Error Handling Policy](error_handling_v4.md)