generated from john/python-template
gpt-5.3-codesx review: Phase 5 Release Readiness & Contract Enforcement
Quality Gate / gate (push) Failing after 10s
Quality Gate / gate (push) Failing after 10s
This commit is contained in:
Jim Lancaster
@@ -1,253 +0,0 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user