gpt-5.3-codex review Phase 3

2026-08-19 20:50:21 -05:00
parent de8cdb6e1a
commit 30fcef3892
10 changed files with 25 additions and 55 deletions
@@ -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.
@@ -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
@@ -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.
@@ -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
@@ -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.
+5. **Canonical V4 authority:** findings must resolve against `docs/ver4/*` first.
-6. **Media boundary conformance:** print/export media is record-validated and UI media URL generation uses controlled resolver paths.
+6. **Schema contract fidelity:** when model/persistence behavior changes, `docs/ver4/schema_v4.md` remains field-accurate with `src/transcription/db/models.py`.
-7. **Eager-loading conformance:** service/UI read paths satisfy `lazy="raise"` expectations.
+7. **Media boundary conformance:** print/export media is record-validated and UI media URL generation uses controlled resolver paths.
-8. **Cross-cutting error conformance:** service/API/UI translation and retry behavior align with `.github/instructions/error-handling.instructions.md`.
+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
@@ -26,8 +26,7 @@ When documents disagree, use this order:
 4. Durable failure behavior: [Error Handling invariant](../invariant/error_handling.md).
 5. Durable AI evidence behavior: [Digital Evidence and AI Processing Provenance](../invariant/ai_evidence_and_provenance.md).
 6. Data definitions and relationships: current models plus the [V4 schema](../ver4/schema_v4.md).
-7. Historical context only: [V4 revision history](../ver4/history.md).
+7. Implementation truth: current code and tests.
 8. Implementation truth: current code and tests.
 If code intentionally changes accepted page behavior, update the corresponding page contract in the same change. If code accidentally differs, correct the implementation rather than rewriting intent to match a defect.
@@ -6,7 +6,7 @@ V4.8 is the first release since V4.5 to add **new user-facing behavior**. V4.6 w
 ## Dependency on V4.7
-**The model-performance rollup below must not begin until V4.7 Phase 4 lands.** `duration_ms` currently measures provider call *plus* image normalization, artifact persistence, and a DB commit, while the timeout governs only the provider call. A rollup built on it would chart preprocessing time mixed with provider latency and look authoritative while quietly misleading. V4.7 Phase 1 removes normalization and artifact persistence from that window, but the commit remains inside it until Phase 4. See archived V4.7 scope boundary at `docs-v4x-archive:docs/ver4.7/scope_boundary_v4_7.md`.
+**The model-performance rollup below must not begin until V4.7 Phase 4 lands.** `duration_ms` currently measures provider call *plus* image normalization, artifact persistence, and a DB commit, while the timeout governs only the provider call. A rollup built on it would chart preprocessing time mixed with provider latency and look authoritative while quietly misleading. V4.7 Phase 1 removes normalization and artifact persistence from that window, but the commit remains inside it until Phase 4.
 ## Candidate Features
@@ -103,8 +103,6 @@ Item 6 is not recommended.
 ## Related Local References
 - Archived V4.7 scope boundary: `docs-v4x-archive:docs/ver4.7/scope_boundary_v4_7.md` (blocking dependency for item 5)
 - Archived V4.6 scope boundary: `docs-v4x-archive:docs/ver4.6/scope_boundary_v4_6.md`
 - [Architecture & Code Review Report](../architecture_code_review_2026-08-17.md)
 - `.github/instructions/ui.instructions.md`
 - `src/transcription/ui/homepage_store.py` - existing multi-image storage
@@ -156,16 +156,14 @@ Responsibilities:
 - Print/export media uses record-validated API endpoints to avoid direct filesystem path exposure.
 - General UI media URLs are generated through shared resolver helpers to keep path handling consistent and centralized.
-## Historical Context Boundary
+## Scope Boundary
-Superseded V4.x scope/plan/review documents were intentionally removed from the active tree and archived at git tag `docs-v4x-archive`.  
+Current architecture rules live only in `docs/ver4/*`.
 Current architecture rules live only in `docs/ver4/*`; historical files are reference material only.
 ## Related References
 - [System Requirements](requirements_v4.md)
 - [Data Model](schema_v4.md)
 - [Error Handling Policy](error_handling_v4.md)
 - [V4 Revision History](history.md)
 - [Error Handling invariant](../invariant/error_handling.md)
 - [AI evidence invariant](../invariant/ai_evidence_and_provenance.md)
@@ -1,33 +0,0 @@
 # V4 Revision History (Archived)
 This index tracks superseded V4.x documents as historical context.
 These revisions were intentionally removed from the active working tree to prevent accidental reuse by tools and AI agents.
 They are preserved at immutable git tag `docs-v4x-archive`.
 ## Archive Map
 | Revision | Archived Paths at `docs-v4x-archive` |
 | :--- | :--- |
 | V4.0 | `docs/ver4.0/scope_boundary_v4.md`, `docs/ver4.0/implementation_plan_v4.md` |
 | V4.1 | `docs/ver4.1/scope_boundary_v4_1.md`, `docs/ver4.1/implementation_plan_v4_1.md` |
 | V4.2 | `docs/ver4.2/scope_boundary_v4_2.md`, `docs/ver4.2/implementation_plan_v4_2.md` |
 | V4.3 | `docs/ver4.3/scope_boundary_v4_3.md`, `docs/ver4.3/implementation_plan_v4_3.md` |
 | V4.4 | `docs/ver4.4/scope_boundary_v4_4.md`, `docs/ver4.4/implementation_plan_v4_4.md` |
 | V4.5 | `docs/ver4.5/scope_boundary_v4_5.md`, `docs/ver4.5/implementation_plan_v4_5.md` |
 | V4.6 | `docs/ver4.6/scope_boundary_v4_6.md`, `docs/ver4.6/implementation_plan_v4_6.md`, `docs/ver4.6/review_log_v4_6.md` |
 | V4.7 | `docs/ver4.7/scope_boundary_v4_7.md`, `docs/ver4.7/implementation_plan_v4_7.md`, `docs/ver4.7/review_log_v4_7.md` |
 | V4.8 | `../ver4.8/feature_backlog_v4_8.md` |
 To inspect archived content locally:
 `git show docs-v4x-archive:docs/ver4.6/scope_boundary_v4_6.md`
 ## Canonical Contract Reminder
 Use `docs/ver4/` for current-state requirements, architecture, schema, and error policy:
 - `index_v4.md`
 - `architecture_v4.md`
 - `requirements_v4.md`
 - `schema_v4.md`
 - `error_handling_v4.md`
@@ -8,7 +8,6 @@ This directory is the single source of truth for current V4 behavior and archite
 2. [System Requirements](requirements_v4.md) for verifiable current-state requirements.
 3. [Data Model](schema_v4.md) for entities, constraints, and evidence persistence rules.
 4. [Error Handling Policy](error_handling_v4.md) for category, translation, and retry behavior.
 5. [V4 Revision History](history.md) for superseded scope and implementation documents.
 ## Cross-Version Invariants
@@ -21,4 +20,4 @@ This directory is the single source of truth for current V4 behavior and archite
 ## Baseline Statement
 The current V4 baseline includes behavior delivered through V4.7 architectural cleanup.
-Versioned V4.x scope and implementation documents are retained as historical records only at git tag `docs-v4x-archive` and do not define active contracts.
+Use only this `docs/ver4/*` tree for active design and implementation decisions.