Remove references to "v4" throughout the code and documentation
Quality Gate / gate (push) Failing after 11s

This commit is contained in:
Jim Lancaster
2026-08-20 16:35:20 -05:00
parent eaeb0bc806
commit bf2f3ac09c
34 changed files with 140 additions and 550 deletions
@@ -7,13 +7,13 @@ applyTo: 'src/transcription/**/*.py'
Primary references:
- `docs/ver4/error_handling_v4.md`
- `docs/error_handling.md`
- `docs/invariant/error_handling.md`
- `docs/ver4/requirements_v4.md`
- `docs/requirements.md`
## Taxonomy and Categories
Use category-driven semantics aligned to canonical V4 policy:
Use category-driven semantics aligned to canonical policy:
- `validation`
- `not_found`
@@ -91,7 +91,7 @@ Required internal -> canonical mapping:
If taxonomy, retries, or envelope semantics change:
1. Update canonical docs (`docs/ver4/error_handling_v4.md`, and invariant docs if needed).
1. Update canonical docs (`docs/error_handling.md`, and invariant docs if needed).
2. Update tests in the same change.
3. Update related instruction/skill references.
4. If change affects persisted status/category fields, update `docs/ver4/schema_v4.md` when applicable.
4. If change affects persisted status/category fields, update `docs/schema.md` when applicable.
@@ -120,18 +120,18 @@ Atomicity rules:
- Terminal state (`TRANSCRIBED` or `FAILED`) and transcript row changes must succeed or roll back together.
- Retry persistence (`QUEUED` + retry increment + error detail) must succeed or roll back together.
## V4 Contract Alignment
## Contract Alignment
- Treat `docs/ver4/` as the active architecture and requirements baseline.
- Legacy V4 revision trees are out of scope for active implementation decisions and must not be referenced as authoritative service guidance.
- Treat `src/transcription/db/models.py` as runtime schema ground truth and `docs/ver4/schema_v4.md` as the field-accurate contract mirror.
- Treat `docs/` as the active architecture and requirements baseline.
- Legacy revision trees are out of scope for active implementation decisions and must not be referenced as authoritative service guidance.
- Treat `src/transcription/db/models.py` as runtime schema ground truth and `docs/schema.md` as the field-accurate contract mirror.
- `Job.status` success path is `TRANSCRIBED`.
- `JobSource.status` is queue/projection state only (`PENDING`, `TRANSCRIBED`, `FAILED`, `CANCELLED`).
- Source ingest may normalize media before persistence; persisted bytes/hash are canonical for processing and provenance.
- `ExecutionAttempt` is append-only evidence history; do not mutate historical attempt rows in runtime code.
- `Source.raw_transcription` is a projection, not authoritative history.
- Service/UI read paths that touch relationships must be eager-loaded for `lazy="raise"` compatibility.
- If model fields, enums, constraints, indexes, or relationship-loading semantics change, update `docs/ver4/schema_v4.md` in the same change.
- If model fields, enums, constraints, indexes, or relationship-loading semantics change, update `docs/schema.md` in the same change.
- If `Settings` fields or defaults change in `src/transcription/config.py`, update `.env.example` in the same change so keys/defaults remain synchronized and no stale settings remain documented.
# Service Composition
+3 -3
View File
@@ -69,10 +69,10 @@ Prohibited patterns:
- Manual URL construction from raw `Path` values in pages/components.
- User-facing payloads containing local absolute paths.
## V4 Contract Alignment
## Contract Alignment
- Treat `docs/ver4/` as the active baseline.
- Resolve lifecycle and status semantics against `src/transcription/db/models.py` and `docs/ver4/schema_v4.md`; do not introduce alternate status labels or implied legacy states in UI behavior.
- Treat `docs/` as the active baseline.
- Resolve lifecycle and status semantics against `src/transcription/db/models.py` and `docs/schema.md`; do not introduce alternate status labels or implied legacy states in UI behavior.
- Use status vocabulary exactly as modeled (`queued`, `processing`, `transcribed`, `partial_success`, `failed`; and `pending`, `transcribed`, `failed`, `cancelled`).
- Print/export media flows must use record-validated routes; direct local filesystem paths are prohibited.
- If lifecycle wording/behavior changes, update corresponding `docs/ui/pages/*.md` contracts in the same change.
@@ -21,9 +21,9 @@ Perform focused, deterministic audits of evidence integrity and provenance behav
## Normative References (must be used)
1. `docs/invariant/ai_evidence_and_provenance.md`
2. `docs/ver4/schema_v4.md`
3. `docs/ver4/requirements_v4.md`
4. `docs/ver4/error_handling_v4.md`
2. `docs/schema.md`
3. `docs/requirements.md`
4. `docs/error_handling.md`
## Deterministic Pass/Fail Checks
@@ -60,7 +60,7 @@ Perform focused, deterministic audits of evidence integrity and provenance behav
- Evidence model changes require same-change doc updates.
### H. Canonical authority boundaries
- Active guidance resolves against `docs/ver4/*` and current instruction files.
- Active guidance resolves against `docs/*` and current instruction files.
## Review Workflow
+3 -3
View File
@@ -26,7 +26,7 @@ Perform thorough, evidence-based code reviews for Python projects. Every finding
## Review Workflow
1. **Map the Repository First:** Inspect entry points, package layout, configurations, dependency manifests, and any project-specific rule files (`AGENTS.md`, `CLAUDE.md`, `.github/instructions/`). Project-specific conventions override generic advice.
2. **Establish Canonical Authority First:** Read architecture/contracts (`docs/ver4/*`, `docs/invariant/*`, UI docs) and active instructions/skills before evaluating source behavior.
2. **Establish Canonical Authority First:** Read architecture/contracts (`docs/*`, `docs/invariant/*`, UI docs) and active instructions/skills before evaluating source behavior.
3. **Read Representative Modules:** Sample across all layers (routes/pages, UI components, services, workers, persistence, provider adapters, settings, tests) before drawing conclusions.
4. **Run Drift Analysis:** Compare documented intended behavior versus repository ground truth; identify both implementation drift and undocumented-but-repeatable conventions that should be formalized.
5. **Run Dead-Code/Orphan Sweep:** Identify candidate orphan modules/functions/classes with zero inbound references, then verify expected exceptions (entrypoints, framework/plugin registration, dynamic imports/reflection, CLI hooks, test-only utilities) before marking as orphaned.
@@ -45,8 +45,8 @@ When reviewing this repository, always include explicit pass/fail checks for:
2. **UI boundary rule:** pages/components do not perform persistence access (`tests/test_ui_boundaries.py`).
3. **Status vocabulary conformance:** `JobStatus`/`JobSourceStatus` usage matches current enums in `src/transcription/db/models.py`.
4. **Evidence ownership conformance:** append-only attempt history is preserved and projection writes are not mistaken for history mutation (`src/transcription/services/sources.py`, `src/transcription/services/evidence.py`).
5. **Canonical V4 authority:** findings must resolve against `docs/ver4/*` first.
6. **Schema contract fidelity:** when model/persistence behavior changes, `docs/ver4/schema_v4.md` remains field-accurate with `src/transcription/db/models.py`.
5. **Canonical authority:** findings must resolve against `docs/*` first.
6. **Schema contract fidelity:** when model/persistence behavior changes, `docs/schema.md` remains field-accurate with `src/transcription/db/models.py`.
7. **Media boundary conformance:** print/export media is record-validated and UI media URL generation uses controlled resolver paths.
8. **Eager-loading conformance:** service/UI read paths satisfy `lazy="raise"` expectations.
9. **Cross-cutting error conformance:** service/API/UI translation and retry behavior align with `.github/instructions/error-handling.instructions.md`.
@@ -22,7 +22,7 @@ Run a deterministic audit of test usefulness. Focus on whether tests catch real
## Normative References (Transcription Repo)
1. `docs/ver4/*`
1. `docs/*`
2. `docs/invariant/*`
3. `.github/instructions/*.instructions.md`
4. `tests/test_meta_contract_guards.py`