transcription/docs/phase5-codex-prompt.md

You are working in the transcription repository (Python 3.12+, FastAPI, NiceGUI, SQLModel/SQLAlchemy, Pydantic V2, asyncio). Follow .github/instructions/services.instructions.md, .github/instructions/ui.instructions.md, and .github/instructions/error-handling.instructions.md for any code you touch, and keep docs/ver4/* as canonical authority for intended behavior. Do not modify unrelated code.

Prerequisite: This prompt assumes Phases 1-4 (docs/phase1-codex-prompt.md through docs/phase4-codex-prompt.md) are already merged.

Goal

Implement Phase 5 (Non-blocking governance/documentation depth) from docs/architecture-code-review-2026-08-20.md, the final phase of the review's action plan:

1. [MED-01] Provenance software context depends on undeclared ambient environment state

Location: src/transcription/providers/evidence.py:144-154

Problem: build_software_context reads TRANSCRIPTION_COMMIT directly from os.environ, bypassing Settings and .env.example contract guards. Evidence exports can therefore vary by process environment in a way the repository's documented configuration surface does not declare or test.

Required fix — choose one, and justify your choice in the final report:

• Preferred: Add TRANSCRIPTION_COMMIT (or a clearly named equivalent) as a proper field on the project's Settings class (in src/transcription/config.py), document it in .env.example, and update build_software_context in src/transcription/providers/evidence.py to read it from Settings instead of os.environ directly. Add/extend tests/test_meta_contract_guards.py so this setting is covered by whatever meta-contract guard already validates Settings/.env.example alignment.
• Alternative (only if commit identity truly cannot be static config): Derive the commit identity once at application startup (e.g. from git rev-parse HEAD or a build-time artifact) and store it on app state, injecting it into build_software_context via an explicit parameter rather than ambient lookup at call time.
• In either case, remove the direct os.environ read from providers/evidence.py, and ensure provenance inputs are explicit, versioned, and testable configuration — not ambient environment leakage.
• Add a test asserting that evidence/provenance export reflects the configured commit value deterministically (not dependent on unset/inconsistent env state).

2. [LOW-01] Restore the static-analysis baseline to green and gate it in CI

Location: src/transcription/api/health.py:14-23, tests/services/test_service_base.py:31-138, src/transcription/config.py:204-208, tests/test_media_path_safety.py:3-5, tests/test_meta_contract_guards.py:3-8, tests/ui/test_media_urls.py:1-3

Problem: uv run ruff check currently reports 5 issues and uv run ty check reports 12 diagnostics on mainline, even though the pytest suite is fully green. This means static-analysis debt already exists on the trunk, undermining confidence that future structural drift will be caught early.

Required work:

• Run uv run ruff check and uv run ty check from the repo root and get the current full list of issues/diagnostics (do not assume the exact locations above are still accurate — code may have shifted since the review; re-derive the live list first).
• Fix every reported ruff check issue. Prefer the minimal correct fix over broad reformatting; do not run a repo-wide autofix/reformat that touches unrelated code.
• Fix every reported ty check diagnostic. Pay particular attention to the flagged areas: the health payload typing in api/health.py, and untyped/permissive test doubles in tests/services/test_service_base.py — these were specifically called out as notable in the review.
• Do not silence diagnostics with blanket # type: ignore/# noqa unless a fix is genuinely infeasible; if you must suppress one, add a one-line comment explaining why, scoped as narrowly as possible (single line, not file-level).
• Once both ruff check and ty check are clean, check whether this repo's CI configuration (e.g. .github/workflows/*.yml) already runs them as required gates alongside pytest. If not, add them as required steps so this baseline cannot silently regress again. Follow whatever CI tooling/style (uv, pre-commit, GitHub Actions) is already established in this repo — check .pre-commit-config.yaml and existing workflow files before adding anything new.

Validation

• Run uv run pytest and ensure the full suite passes.
• Run uv run ruff check and confirm zero issues.
• Run uv run ty check (or the project's equivalent type-check command) and confirm zero diagnostics.
• If you added/modified CI configuration, verify the workflow YAML is syntactically valid and consistent with existing job structure (do not introduce a parallel/duplicate CI pipeline).

Report back with: the Settings/provenance approach chosen for TRANSCRIPTION_COMMIT and why, the full list of ruff/ty issues fixed (before/after counts), any suppressions added and their justification, whether CI gating was added or already existed, and final pytest/ruff/ty results.