gpt-5.3-codex review Phase 3

.github/instructions/error-handling.instructions.md

@@ -23,6 +23,7 @@ Use category-driven semantics aligned to canonical V4 policy:
 - `internal`
 
 Do not invent ad hoc categories in user/API-facing envelopes unless canonical docs are updated.
+Service-layer exceptions must normalize to this category set before crossing service boundaries.
 
 ## Translation Boundaries
 
@@ -41,6 +42,7 @@ Do not invent ad hoc categories in user/API-facing envelopes unless canonical do
 - Page-level (`JobSource`): `pending`, `transcribed`, `failed`, `cancelled`.
 - Job terminals: `transcribed`, `partial_success`, `failed`.
 - Cancellation must keep job-level and page-level semantics explicit and consistent.
+- Do not emit legacy terminal state language such as `completed` in active user/API lifecycle contracts.
 
 ## User-Safe Messaging
 
@@ -67,3 +69,4 @@ If taxonomy, retries, or envelope semantics change:
 1. Update canonical docs (`docs/ver4/error_handling_v4.md`, and invariant docs if needed).
 2. Update tests in the same change.
 3. Update related instruction/skill references.
+4. If change affects persisted status/category fields, update `docs/ver4/schema_v4.md` when applicable.

.github/instructions/services.instructions.md

@@ -73,6 +73,7 @@ module, not in a cross-service import.
   [sources](../../src/transcription/services/sources.py).
 - Category mapping, retry behavior, and translation boundaries are defined in
   [error-handling instructions](./error-handling.instructions.md).
+- Service-edge exception translation must be deterministic: map to canonical categories and preserve clear provider->service->API/UI boundaries.
 
 ## Checklist
 
@@ -122,14 +123,15 @@ Atomicity rules:
 ## V4 Contract Alignment
 
 - Treat `docs/ver4/` as the active architecture and requirements baseline.
-- Treat `docs/ver4/history.md` and `docs-v4x-archive` as historical-only references.
+- Legacy V4 revision trees are out of scope for active implementation decisions and must not be referenced as authoritative service guidance.
+- Treat `src/transcription/db/models.py` as runtime schema ground truth and `docs/ver4/schema_v4.md` as the field-accurate contract mirror.
 - `Job.status` success path is `TRANSCRIBED`.
 - `JobSource.status` is queue/projection state only (`PENDING`, `TRANSCRIBED`, `FAILED`, `CANCELLED`).
 - Source ingest may normalize media before persistence; persisted bytes/hash are canonical for processing and provenance.
 - `ExecutionAttempt` is append-only evidence history; do not mutate historical attempt rows in runtime code.
 - `Source.raw_transcription` is a projection, not authoritative history.
 - Service/UI read paths that touch relationships must be eager-loaded for `lazy="raise"` compatibility.
-- If evidence-related model fields change, update `docs/ver4/schema_v4.md` in the same change.
+- If model fields, enums, constraints, indexes, or relationship-loading semantics change, update `docs/ver4/schema_v4.md` in the same change.
 
 # Service Composition
 

.github/instructions/ui.instructions.md

@@ -71,7 +71,8 @@ Prohibited patterns:
 
 ## V4 Contract Alignment
 
-- Treat `docs/ver4/` as the active baseline and `docs/ver4/history.md` as historical reference only.
+- Treat `docs/ver4/` as the active baseline.
+- Resolve lifecycle and status semantics against `src/transcription/db/models.py` and `docs/ver4/schema_v4.md`; do not introduce alternate status labels or implied legacy states in UI behavior.
 - Use status vocabulary exactly as modeled (`queued`, `processing`, `transcribed`, `partial_success`, `failed`; and `pending`, `transcribed`, `failed`, `cancelled`).
 - Print/export media flows must use record-validated routes; direct local filesystem paths are prohibited.
 - If lifecycle wording/behavior changes, update corresponding `docs/ui/pages/*.md` contracts in the same change.