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.

.github/skills/evidence-provenance-auditor/skill.md

@@ -24,8 +24,6 @@ Perform focused, deterministic audits of evidence integrity and provenance behav
 2. `docs/ver4/schema_v4.md`
 3. `docs/ver4/requirements_v4.md`
 4. `docs/ver4/error_handling_v4.md`
-5. `docs/ver4/history.md` (archive boundary)
-6. `docs-v4x-archive` tag (historical context only)
 
 ## Deterministic Pass/Fail Checks
 
@@ -61,19 +59,22 @@ Perform focused, deterministic audits of evidence integrity and provenance behav
 - Evidence-related model fields and semantics align with canonical docs.
 - Evidence model changes require same-change doc updates.
 
+### H. Canonical authority boundaries
+- Active guidance resolves against `docs/ver4/*` and current instruction files.
+
 ## Review Workflow
 
 1. Read normative references first.
 2. Inspect model + service + workflow write paths.
 3. Inspect evidence read/display/export paths.
 4. Report high-confidence findings with concrete path/line evidence.
-5. Classify each finding by invariant family (A-G).
+5. Classify each finding by invariant family (A-H).
 
 ## Output Format
 
 Use this structure:
 
-- Verdict by invariant family (A-G)
+- Verdict by invariant family (A-H)
 - Findings with `Location`, `Observed Behavior`, `Risk`, `Recommended Fix`
 - Drift table (`Doc claim` vs `Code reality` vs `Action`)
 - Regression guards needed

.github/skills/python-code-reviewer/skill.md

@@ -30,6 +30,7 @@ Perform thorough, evidence-based code reviews for Python projects. Every finding
 3. **Verify Claims:** Run or reference project tooling (`ruff check`, `ty`, `pytest`) rather than guessing.
 4. **Prioritize Hot Paths:** Focus deeply on request handling, database sessions, background workers, and external API calls.
 5. **Enforce Read-Only Safety:** Do not modify code unless explicitly instructed.
+6. **Escalate Provenance Audits:** For evidence/provenance-heavy changes, apply invariant checks from `.github/skills/evidence-provenance-auditor/skill.md` and include pass/fail outcomes in the report.
 
 ## Repo-Specific Deterministic Checks (Transcription)
 
@@ -39,10 +40,11 @@ When reviewing this repository, always include explicit pass/fail checks for:
 2. **UI boundary rule:** pages/components do not perform persistence access (`tests/test_ui_boundaries.py`).
 3. **Status vocabulary conformance:** `JobStatus`/`JobSourceStatus` usage matches current enums in `src/transcription/db/models.py`.
 4. **Evidence ownership conformance:** append-only attempt history is preserved and projection writes are not mistaken for history mutation (`src/transcription/services/sources.py`, `src/transcription/services/evidence.py`).
-5. **Canonical V4 authority:** findings must resolve against `docs/ver4/*` first, and treat `docs/ver4/history.md` plus `docs-v4x-archive` as historical context.
-6. **Media boundary conformance:** print/export media is record-validated and UI media URL generation uses controlled resolver paths.
-7. **Eager-loading conformance:** service/UI read paths satisfy `lazy="raise"` expectations.
-8. **Cross-cutting error conformance:** service/API/UI translation and retry behavior align with `.github/instructions/error-handling.instructions.md`.
+5. **Canonical V4 authority:** findings must resolve against `docs/ver4/*` first.
+6. **Schema contract fidelity:** when model/persistence behavior changes, `docs/ver4/schema_v4.md` remains field-accurate with `src/transcription/db/models.py`.
+7. **Media boundary conformance:** print/export media is record-validated and UI media URL generation uses controlled resolver paths.
+8. **Eager-loading conformance:** service/UI read paths satisfy `lazy="raise"` expectations.
+9. **Cross-cutting error conformance:** service/API/UI translation and retry behavior align with `.github/instructions/error-handling.instructions.md`.
 
 ## Core Review Areas