# Phase 4: Implementation Task Specifications ## Objective Convert the canonical V4 baseline into executable, worker-ready implementation tasks that close remaining drift risk and harden enforcement. Canonical authority for all tasks: - `docs/ver4/*` - `.github/instructions/services.instructions.md` - `.github/instructions/ui.instructions.md` - `.github/instructions/error-handling.instructions.md` - `.github/skills/python-code-reviewer/skill.md` - `.github/skills/evidence-provenance-auditor/skill.md` --- ## Dependency-Ordered Task Graph | Task ID | Title | Depends On | Priority | | :--- | :--- | :--- | :--- | | P4-01 | Meta-contract regression guards | - | P0 | | P4-02 | Error taxonomy and translation conformance | P4-01 | P0 | | P4-03 | Evidence append-only write-path hardening | P4-01 | P0 | | P4-04 | Job/Page lifecycle consistency hardening | P4-02, P4-03 | P0 | | P4-05 | Eager-loading and `lazy="raise"` conformance sweep | P4-01 | P1 | | P4-06 | Media route/path safety enforcement sweep | P4-01 | P1 | | P4-07 | Duration semantics split for telemetry correctness | P4-04 | P1 | | P4-08 | Reviewer/instruction enforcement tests in CI path | P4-01..P4-07 | P1 | --- ## Task Specifications ## P4-01 — Meta-contract regression guards **Goal:** Add deterministic tests preventing drift from canonical docs/instructions/skills contracts. **Scope:** - `tests/` (new focused tests) - optionally small helper in `tests/conftest.py` if needed **Required changes:** 1. Add a test that fails if active docs/instructions/skills reference removed V4 revision paths. 2. Add a test that asserts canonical authority references exist where required (services/ui/error-handling instructions and reviewer skills). 3. Keep checks text-based and stable; avoid brittle full-document snapshots. **Acceptance criteria:** - Test suite fails on any reintroduction of legacy-path authority references. - Test suite passes with current baseline. **Validation command:** `uv run pytest tests -k "contract or instruction or skill"` --- ## P4-02 — Error taxonomy and translation conformance **Goal:** Ensure service/API/UI error translation matches canonical categories and boundaries. **Scope:** - `src/transcription/services/**/*.py` - `src/transcription/api/**/*.py` - `src/transcription/ui/**/*.py` - related tests under `tests/services`, `tests/api`, `tests/ui` **Required changes:** 1. Normalize service-edge exceptions to canonical categories: - `validation`, `not_found`, `conflict`, `external`, `timeout`, `internal`. 2. Ensure causal chain preservation (`raise ... from ...`) on translation. 3. Ensure UI/API emits user-safe envelopes/messages without stack/path/secret leakage. 4. Add/adjust tests for category mapping and envelope shape. **Acceptance criteria:** - No ad hoc category values in user/API-facing error envelopes. - Translation boundaries are deterministic and test-covered. **Validation command:** `uv run pytest tests/services tests/api tests/ui -k "error or envelope or category"` --- ## P4-03 — Evidence append-only write-path hardening **Goal:** Guarantee each provider call appends new `ExecutionAttempt` evidence and never rewrites attempt history. **Scope:** - `src/transcription/services/sources.py` - `src/transcription/services/workflows.py` - `src/transcription/services/evidence.py` - `src/transcription/db/models.py` (only if required for bug fix) - tests under `tests/services` **Required changes:** 1. Audit all attempt-write paths for accidental update/overwrite behavior. 2. Enforce append-only semantics for retries and reprocessing. 3. Keep `Source.raw_transcription` and preferred pointers as projection-only mutation surfaces. 4. Add/strengthen tests proving historical attempts are unchanged across retries/promotions. **Acceptance criteria:** - Reprocessing/retry produces new attempts, never history rewrite. - Projection changes do not mutate prior attempt evidence. **Validation command:** `uv run pytest tests/services -k "attempt or evidence or retry or promotion"` --- ## P4-04 — Job/Page lifecycle consistency hardening **Goal:** Enforce coherent status transitions and cancellation semantics across `Job` and `JobSource`. **Scope:** - `src/transcription/services/jobs.py` - `src/transcription/services/workflows.py` - related tests under `tests/services` **Required changes:** 1. Verify terminal `Job.status` resolution from page outcomes only: - `transcribed`, `partial_success`, `failed`. 2. Ensure cancellation transitions remaining `pending` pages to `cancelled`. 3. Ensure lifecycle language and emitted behavior never reintroduce legacy `completed` semantics. 4. Add/adjust reliability tests for mixed outcomes and cancel/retry edges. **Acceptance criteria:** - Job and page-level transitions remain consistent under success/failure/partial/cancel paths. - No legacy terminal vocabulary in behavior contracts or emitted statuses. **Validation command:** `uv run pytest tests/services/test_workflows_reliability.py tests/services -k "job or cancel or partial_success"` --- ## P4-05 — Eager-loading and `lazy="raise"` conformance sweep **Goal:** Eliminate hidden lazy-load access in service/UI read paths. **Scope:** - `src/transcription/services/**/*.py` - `src/transcription/ui/pages/**/*.py` - `src/transcription/ui/components/**/*.py` **Required changes:** 1. Audit relationship access sites and ensure explicit eager-loads where needed. 2. Fix any read-path assumptions that rely on implicit lazy loading. 3. Add targeted tests for high-risk rendering/read paths. **Acceptance criteria:** - Read paths that touch relationships function with `lazy="raise"` constraints intact. **Validation command:** `uv run pytest tests/services tests/ui -k "boundary or lazy or load"` --- ## P4-06 — Media route/path safety enforcement sweep **Goal:** Ensure all UI/print media flows use approved record-validated or controlled resolver patterns. **Scope:** - `src/transcription/api/v4_print.py` - `src/transcription/ui/components/media_urls.py` - `src/transcription/ui/pages/**/*.py` - `src/transcription/ui/components/**/*.py` - tests in `tests/ui` and `tests/api` where applicable **Required changes:** 1. Remove any direct filesystem path exposure to clients. 2. Ensure print/export media access is record-validated. 3. Ensure UI media URL construction uses resolver helper only. 4. Add tests that fail on unsafe URL/path construction patterns. **Acceptance criteria:** - No `file://` usage or raw absolute-path emission in UI/API responses. - Media links resolve through approved paths only. **Validation command:** `uv run pytest tests/ui tests/api -k "media or print or path"` --- ## P4-07 — Duration semantics split for telemetry correctness **Goal:** Separate provider-call latency from end-to-end processing duration so model rollups are not misleading. **Scope:** - `src/transcription/services/workflows.py` - `src/transcription/db/models.py` and migration surface if schema needs extension - `docs/ver4/schema_v4.md` (same change if model fields evolve) - tests in `tests/services` **Required changes:** 1. Introduce explicit timing fields or calculation paths that distinguish: - provider call duration - full processing duration 2. Keep existing invariants and backward compatibility behavior explicit. 3. Add tests covering success, timeout, and failure timing writes. 4. Update schema docs if persistence contract changes. **Acceptance criteria:** - Telemetry consumers can compute provider performance without preprocessing/commit skew. - Timing semantics are test-backed and documented. **Validation command:** `uv run pytest tests/services -k "duration or timeout or workflow"` --- ## P4-08 — Enforcement coverage in CI path **Goal:** Ensure critical invariant checks run in the normal validation path. **Scope:** - existing test organization and runner configs only **Required changes:** 1. Ensure boundary/provenance/contract tests are discoverable by default `pytest` runs. 2. Add grouping markers only if already consistent with project test conventions. 3. Avoid introducing new tooling; reuse existing test stack. **Acceptance criteria:** - A standard repo test run exercises meta-contract, boundary, and provenance guards. **Validation command:** `uv run pytest` --- ## Worker Handoff Contract (apply to every task) Each worker delivery must include: 1. Files changed. 2. Behavior change summary. 3. Why the change satisfies the invariant/contract. 4. Targeted test command(s) and result summary. 5. Explicit note if `docs/ver4/schema_v4.md` was updated due to model/persistence changes.