gpt-5.3-codex review phase 1 - Flatten the documentation

.github/instructions/services.instructions.md

@@ -32,7 +32,7 @@ is the only service that may **create or delete** its rows.
 | `Source`, `JobSource` | `SourceService` |
 | `Job` | `JobService` |
 | `Person`, `PersonRole`, `DocumentPerson` | `PeopleService` |
-| `ExecutionAttempt` | `EvidenceService` |
+| `ExecutionAttempt` | `SourceService` |
 
 ### Junction tables
 
@@ -56,10 +56,8 @@ Two consequences follow, and both are deliberate:
   transition is a Job lifecycle event, not a per-page outcome. They create and delete
   nothing.
 
-`EvidenceService.promote_machine_attempt` writes two fields on `Source`
-(`preferred_execution_attempt_id`, `raw_transcription`). This is allowed on the same
-principle: selecting which attempt a Source presents is an evidence decision that happens
-to land on `Source`. It is scoped to those two projection fields.
+`EvidenceService` is read-focused and projection-focused. It may coordinate selection
+flows, but append-only attempt creation remains in `SourceService` write paths.
 
 If a new operation cannot be expressed within one owner, it belongs in an orchestration
 module, not in a cross-service import.
@@ -86,7 +84,8 @@ module, not in a cross-service import.
 - Where a service exposes create/read/update/delete for its root model, define them at the
   top of the class in that order, before derived reads and workflow helpers.
 - Not every aggregate needs all four. `ExecutionAttempt` is append-only evidence written by
-  `workflows.py`, so `EvidenceService` deliberately exposes reads and no create or delete.
+  `SourceService` workflow-facing methods, so `EvidenceService` deliberately exposes reads and
+  no create or delete.
   Do not add unused CRUD methods to satisfy symmetry.
 - `RegistryService` is generic across small lookup models and uses `<operation>_entry`
   naming instead.
@@ -132,6 +131,13 @@ Separation of concerns:
 - Services should expose session-aware write helpers (flush on caller-owned session) so orchestration controls commit boundaries.
 - Backoff/sleep behavior must run outside transactional scopes.
 
+## V4 Contract Alignment
+
+- Treat `docs/ver4/` as the active architecture and requirements baseline.
+- `Job.status` success path is `TRANSCRIBED`; `COMPLETED` is legacy-compatible and must not be used for new success transitions.
+- `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.
+
 # Service Composition
 
 A service method may read across models it does not own, using eager loads from its own

.github/instructions/ui.instructions.md

@@ -37,6 +37,7 @@ Pages may depend on application services and framework-provided dependencies. Co
 - Keep app-wide navigation and layout primitives in `components/app_shell.py`.
 - Keep generic table/event adaptation in `components/table/common.py`; feature-specific columns, row read models, and formatting belong in the feature table module.
 - Keep exception normalization and user-facing error display in `components/error_presenter.py`; preserve `AppError` details and operation identifiers at page/component boundaries.
+- Use `components/media_urls.py` for media URL generation; do not hand-build upload/static paths in page code.
 
 ## CSS Assets
 
@@ -51,3 +52,9 @@ Pages may depend on application services and framework-provided dependencies. Co
 - Limit component state to ephemeral interaction state such as loading flags, form values, dialogs, and expansion state.
 - Application and worker state must be resolved at the page or application boundary and passed through narrow interfaces such as callbacks or notifier protocols.
 - Keep filesystem, network, provider, and worker orchestration behind application services or dedicated adapters. UI code may trigger those operations but must not implement them.
+
+## V4 Contract Alignment
+
+- Treat `docs/ver4/` as the active baseline and `docs/ver4/history.md` as historical reference only.
+- 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 from API modules; direct local filesystem paths are prohibited.

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

@@ -31,6 +31,16 @@ Perform thorough, evidence-based code reviews for Python projects. Every finding
 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.
 
+## Repo-Specific Deterministic Checks (Transcription)
+
+When reviewing this repository, always include explicit pass/fail checks for:
+
+1. **Service boundary rule:** no service-to-service imports (`tests/test_service_boundaries.py`).
+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/ver4.x/*` as historical context.
+
 ## Core Review Areas
 
 ### 1. Python Best Practices (3.12+)