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.