Revised and simplified V4 Plan and core documents.

docs/ver4/scope_boundary_v4.md

@@ -1,130 +1,91 @@
-# V4 Scope Boundary (Version 4)
+# V4 Scope Boundary
 
-This document defines what is and is not included in Version 4 for expanding `Document`-`Person` relationships.
+This document defines the scope for the transition from the current repository state to the Version 4 project definition.
 
 ## Purpose
 
-Create a clear implementation boundary before updating full V4 architecture, requirements, schema, and plan documents.
+Define what this revision includes, what it intentionally excludes, and what migration rules govern the transition work.
 
-## Why This Is V4 (Not V3.1)
+## In Scope
 
-V4 is required because the change is semantic and cross-cutting:
+### 1. Relationship Model
 
-- Expands relationship meaning beyond fixed `author`/`recipient`.
-- Introduces a suggestion lifecycle (`suggested` vs `asserted`).
-- Introduces policy constraints (role exclusivity matrix).
-- Impacts persistence, service contracts, API behavior, UI workflows, and test strategy.
+- Extensible role taxonomy for document-person relationships.
+- Many-to-many document-person links with many people per role.
+- Deterministic exclusivity policy for configured role pairs.
+- Set-based add/remove synchronization for document-person updates.
 
-A V3.1 patch would only be appropriate for non-semantic quality-of-life fixes inside existing role semantics.
+### 2. Document Type Governance
 
-## In Scope for V4
+- Registry-driven `DocumentType` model with stable codes and controlled selection.
+- Minimal rollout for the current corpus with no alias helper table.
 
-### 1) Relationship Semantics
+### 3. UI and API Behavior
 
-- Role taxonomy becomes extensible (not hardcoded to only two role values).
-- A `Document` can link to many `Person` records per role.
-- Relationship states are explicit:
-  - `asserted`: human-confirmed canonical link.
-  - `suggested`: machine- or heuristic-proposed link pending review.
+- 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.
 
-### 2) Policy Rules
+### 4. Verification
 
-- Enforce role exclusivity for the same `(document, person)` pair where configured.
-- Initial policy decision:
-  - `author` + `recipient` are mutually exclusive.
-  - `mentioned` may coexist with other roles.
+- Tests for many-per-role behavior.
+- Tests for exclusivity enforcement.
+- Tests for set-based relationship mutation behavior.
+- Tests for document and person delete/link cleanup regressions.
 
-### 3) Persistence and Contracts
+## Out of Scope
 
-- Evolve persistence model to support:
-  - extensible roles,
-  - suggestion lifecycle metadata,
-  - deterministic conflict handling.
-- Replace single-value relationship mutation patterns with set-based sync behavior.
-
-### 4) Human-in-the-Loop Workflow
-
-- Add assisted suggestion review flow:
-  - list suggestions,
-  - accept,
-  - reject,
-  - promote accepted suggestion to asserted link.
-- No silent auto-promotion from suggestion to asserted.
-
-### 5) UI and API Behavior
-
-- Document create/edit/detail workflows support multi-person per role.
-- UI surfaces grouped role links and suggestion status.
-- API supports role-aware retrieval and suggestion lifecycle operations.
-
-### 6) Verification
-
-- Add tests for:
-  - many-per-role behavior,
-  - exclusivity enforcement,
-  - suggestion lifecycle,
-  - migration/conflict detection,
-  - regression on delete/link cleanup behavior.
-
-## Out of Scope for V4
-
-- Automatic acceptance of suggested links without human review.
-- Full entity resolution/identity merge pipeline across all `Person` records.
-- Historical provenance graph redesign beyond relationship-level evidence fields.
-- Large-scale NLP research features unrelated to document-person linking.
-- Changes to core transcription execution model (`Job`, `JobSource`) except where needed to expose suggestion evidence inputs.
+- 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
+### A. Role Extensibility Mechanism
 
-- Adopt role registry tables (data-driven roles).
-- Do not use enum-first role expansion for V4.
+- Use registry tables for relationship roles.
 
-### B) Suggestion Storage Model
+### B. Exclusivity Matrix Baseline
 
-- Adopt a separate `document_person_suggestion` table.
-- Keep `document_person` focused on canonical asserted links.
-- Revisit only if operational complexity proves materially higher than expected.
-
-### C) Exclusivity Matrix Baseline
-
-- `author` + `recipient` are mutually exclusive for the same `(document, person)` pair.
+- `author` and `recipient` are mutually exclusive for the same `(document, person)` pair.
 - `mentioned` remains non-exclusive.
-- Hard exclusivity enforcement applies to asserted links.
-- Suggestions may be stored even if they would conflict at assert time; promotion to asserted must enforce exclusivity.
 
-### D) API Compatibility Strategy
+### C. API Compatibility Strategy
 
-- Use additive API evolution in V4.
-- In development mode, the current revision is authoritative; long-lived legacy compatibility layers are not required.
-- Deprecations should be explicit and short-lived, with removals performed in subsequent revisions.
+- Use additive API evolution.
+- In development mode, the current revision is authoritative.
+- Deprecations should be explicit and short-lived.
 
-### E) Document Type Rollout Strategy
+### D. Document Type Rollout Strategy
 
-- Use a minimal registry rollout for the current corpus: no `document_type_alias` helper table.
-- Perform a one-time manual mapping of existing document types to canonical registry types.
+- Use a minimal registry rollout for the current corpus.
+- Do not introduce a `document_type_alias` helper table.
 
-### F) Suggestion Generation Strategy (Still Open)
+### E. Database Change Policy
 
-- Option A: deterministic rules/NLP over transcribed text.
-- Option B: LLM extraction with confidence/evidence spans.
+- 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
 
-- Existing V3 author links migrate to `asserted` behavior.
-- Backfill validation identifies policy conflicts before constraints are enforced.
-- Preserve existing V3 core behavior where unaffected by role/suggestion evolution.
+- 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:
 
-- Suggestion generation strategy is chosen.
-- Suggestion acceptance workflow details are approved.
+- Relationship model, exclusivity rules, and document-type governance are approved.
 - Additive API change list and deprecation schedule are approved.
+- Migration exceptions are explicitly acknowledged.
 
-## Core V4 Documents (Current Set)
+## Core V4 Documents
 
 1. `docs/ver4/index_v4.md`
 2. `docs/ver4/requirements_v4.md`