transcription/docs/phase-4-implementation-task-specs.md

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.