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