Prep for GPT-5.3-codex architecture & code review.

docs/ver4.0/implementation_plan_v4.md

@@ -0,0 +1,102 @@
+# Implementation Plan (version 4.0)
+
+## Goal
+
+Implement the version 4.0 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` requires full schema alignment with the V4 core documents.
+- `src/transcription/services/documents.py` requires set-based document-person sync 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 the Transition Documents
+
+- Confirm the reset scope.
+- Confirm the database exception policy.
+- Keep core V4 documents as the only authoritative product definition.
+
+### 2. Align the Persistence Layer
+
+- Update SQLModel definitions to match the final V4 schema.
+- Add `person_role` 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. Update Services and Write Semantics
+
+- Organize service ownership around Documents, Sources, Jobs, and People.
+- Centralize Source extension and MIME policy in the Sources service.
+- Treat upload as an interface action and remove it from domain service naming where compatibility permits.
+- Implement set-based synchronization for document-person updates.
+- Implement deterministic uniqueness and relationship-write conflict checks.
+- Remove suggestion-related service behavior.
+- Add document-type resolution and validation by UUID.
+
+### 4. Update API Contracts
+
+- Keep API evolution additive.
+- Add role-aware relationship retrieval and write behavior.
+- Add document-type catalog retrieval and UUID-based selection for document writes.
+- Remove suggestion-related API surfaces from the V4 target state.
+
+### 5. Update UI Workflows
+
+- 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 or update service tests for many-per-role behavior, uniqueness conflict handling, 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.
+- Enforce backup-first test execution for AI-run unit tests: backup `./data` before tests, then always prompt for restore after successful tests.
+- Keep restore confirmation-gated by default so code and test outcomes can be reviewed before data is reverted.
+
+## Done When
+
+- Core V4 documents and code paths agree on the final project definition.
+- Relationship-role writes are deterministic and non-destructive.
+- Relationship-write conflict 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
+
+- Suggested/asserted relationship state.
+- Suggestion review or extraction workflows.
+- Global person entity-resolution engine.
+- Automated semantic document-type classification.
+
+## Delivery Order Recommendation
+
+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)
+- [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)

docs/ver4.0/scope_boundary_v4.md

@@ -0,0 +1,89 @@
+# V4.0 Scope Boundary
+
+This document defines the scope for the transition from the current repository state to the Version 4.0 project definition.
+
+## Purpose
+
+Define what this revision includes, what it intentionally excludes, and what migration rules govern the transition work.
+
+## In Scope
+
+### 1. Relationship Model
+
+- Extensible role taxonomy for document-person relationships.
+- Many-to-many document-person links with many people per role.
+- Set-based add/remove synchronization for document-person updates.
+
+### 2. Document Type Governance
+
+- Registry-driven `DocumentType` model with UUID identity, unique labels, and controlled selection.
+- Minimal rollout for the current corpus with no alias helper table.
+
+### 3. UI and API Behavior
+
+- Grouped role links on document and person views.
+- Multi-role relationship editing on document create/edit flows.
+- Role-aware API retrieval and write behavior.
+- Additive API evolution with explicit deprecations.
+
+### 4. Verification
+
+- Tests for many-per-role behavior.
+- Tests for set-based relationship mutation behavior.
+- Tests for document and person delete/link cleanup regressions.
+
+## Out of Scope
+
+- Suggested versus asserted relationship states.
+- Suggestion storage, review, acceptance, or rejection workflows.
+- Automatic relationship extraction or recommendation features.
+- Full entity resolution or identity merge across all people.
+- Automated semantic document type classification.
+- Redesign of the core transcription execution model.
+
+## Locked Design Decisions
+
+### A. Role Extensibility Mechanism
+
+- Use registry tables for relationship roles.
+
+### B. API Compatibility Strategy
+
+- Use additive API evolution.
+- In development mode, the current revision is authoritative.
+- Deprecations should be explicit and short-lived.
+
+### C. Document Type Rollout Strategy
+
+- Use a minimal registry rollout for the current corpus.
+- Do not introduce a `document_type_alias` helper table.
+
+### D. Database Change Policy
+
+- Future schema changes are non-destructive by default.
+- Exception: `document_type` text may be replaced by `document_type_id` without migrating the legacy text values.
+- Exception: `document_person` links may be recreated manually.
+
+## Compatibility and Rollout
+
+- Preserve existing repository behavior where unaffected by the V4 scope.
+- Treat scope boundary and implementation plan as the only transition documents.
+- Treat core V4 documents as the authoritative project definition once rewritten.
+
+## Exit Criteria for Scope Freeze
+
+V4 scope is considered frozen when:
+
+- Relationship model and document-type governance are approved.
+- Relationship model and document-type governance are approved.
+- Additive API change list and deprecation schedule are approved.
+- Migration exceptions are explicitly acknowledged.
+
+## Core V4 Documents
+
+1. `docs/ver4/index_v4.md`
+2. `docs/ver4/requirements_v4.md`
+3. `docs/ver4/schema_v4.md`
+4. `docs/ver4/architecture_v4.md`
+5. `docs/ver4/error_handling_v4.md`
+6. `docs/ver4/implementation_plan_v4.md`