transcription/docs/ver4.0/scope_boundary_v4.md

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