# Version 1 Implementation Plan

This plan defines the path from current implementation to **Version 1 complete**, aligned to the updated domain model:

- `Document` groups one or more content `Source` records
- `Job` owns original immutable provider output (`text`) and processing metadata
- `Revision` stores optional user-authored edits linked to a `Source`

The objective is to complete V1 scope with production readiness while keeping non-V1 enhancements out of active delivery.

---

## V1 Completion Definition

V1 is complete when all of the following are true:

1. **Functional complete**
   - Upload, queue, processing, status display, and transcription result inspection work end-to-end.
   - Optional revision workflow is implemented (create/list/view).
2. **Data-model complete**
   - Runtime behavior, persistence, and tests all align to `Document` / `Source` / `Job` / `Revision`.
3. **Operational complete**
   - Error handling, logs, and runbooks support reliable operation.
4. **Documentation complete**
   - Architecture, requirements, schema, error handling, and index are consistent and current.

---

## Phase 1 — Data Contract Stabilization (Schema-First)

**Goal:** Lock a single canonical contract before further feature work.

### Tasks
1. Confirm and document invariants:
   - `Job.text` is original immutable transcription output.
   - `Revision` is optional and user-authored.
   - Revisions may derive from original `Job.text` or a previous revision.
2. Verify relationship cardinality assumptions:
   - `Document` -> many `Source`
   - `Document` -> many `Job`
   - `Source` -> one `Job`
   - `Source` -> many `Revision`
3. Ensure field naming consistency (`date_created`, `date_updated`, `date_uploaded`) across code and docs.
4. Freeze V1 status lifecycle to current implementation (`queued`, `processing`, `transcribed`, `failed`).

### Deliverables
- Updated `docs/schema.md` and `docs/requirements.md` traceability alignment.
- Explicit V1 data invariants section in architecture docs.

### Exit Criteria
- No conflicting definitions of ownership/cardinality/status remain in docs.

---

## Phase 2 — Service Layer Refactor To New Model

**Goal:** Remove all obsolete `Transcript` assumptions from service/workflow code.

### Tasks
1. Refactor `services/transcription.py`:
   - Replace transcript CRUD assumptions with job-output + revision operations.
2. Refactor `services/jobs.py`:
   - Replace old timestamp/relationship accessors with current model fields.
3. Refactor `services/documents.py` and `services/store.py`:
   - Ensure upload creates and links `Document`, `Source`, and `Job` correctly.
4. Refactor `services/workflows.py`:
   - Persist original provider output to `Job`.
   - Persist failure detail to `Job.error_detail`.
   - Use `Revision` only for user-authored edits.

### Deliverables
- Service layer fully aligned with new schema.

### Exit Criteria
- No service module imports or persists `Transcript` model artifacts.

---

## Phase 3 — UI Contract Alignment

**Goal:** Align pages/components to source/job/revision semantics.

### Tasks
1. Update job detail and related UI components:
   - Display original immutable transcription from `Job.text`.
   - Display optional revisions sourced from `Source.revisions`.
2. Replace legacy terminology in UI copy:
   - “transcript history” -> “revision history” where appropriate.
3. Align date fields with new schema naming.
4. Preserve clear user messaging when no revisions exist.

### Deliverables
- Updated jobs page and detail components.

### Exit Criteria
- UI behavior and labels match documentation and domain model.

---

## Phase 4 — Database Bootstrap, Migration, and Safety

**Goal:** Make schema transition safe in dev/test and repeatable for deployment.

### Tasks
1. Update bootstrap compatibility logic in `db/operations.py`:
   - Remove obsolete transcript-table assumptions.
   - Add forward-compatible patches for current tables only.
2. Define migration/backfill approach for existing local data.
3. Document rollback and recovery steps.
4. Rehearse migration path against representative data.

### Deliverables
- Migration/upgrade runbook.
- Validated bootstrap behavior for dev/test.

### Exit Criteria
- Migration path is documented and tested with no unresolved data-loss risk.

---

## Phase 5 — Test Suite Realignment

**Goal:** Restore full confidence after the schema redesign.

### Tasks
1. Rewrite model tests for:
   - `Document`, `Source`, `Job`, `Revision` relationships and invariants.
2. Rewrite service/integration tests:
   - Worker success/failure paths using `Job.text` / `Job.error_detail`.
   - Optional revision creation and lineage behavior.
3. Update UI tests for new job-detail/revision rendering behavior.
4. Re-enable strict CI quality gates (lint, type, tests).

### Deliverables
- Updated test matrix and passing CI.

### Exit Criteria
- Critical user flows and failure paths are covered and green.

---

## Phase 6 — Reliability, Operations, and Release Readiness

**Goal:** Ensure V1 is operable and launch-safe.

### Tasks
1. Verify error taxonomy behavior across UI/API/service/worker.
2. Confirm structured logging includes relevant identifiers (`job_id`, `document_id`, `source_id` when applicable).
3. Validate retry behavior and terminal failure handling.
4. Finalize release checklist, deployment steps, and rollback procedure.
5. Execute final acceptance run against requirements traceability.

### Deliverables
- V1 release checklist and acceptance evidence.

### Exit Criteria
- Stakeholder sign-off and launch readiness achieved.

---

## Requirement Traceability Focus

The plan must keep clear evidence against these requirement groups:

- **Core flow:** REQ-0 to REQ-6
- **Runtime and operations constraints:** REQ-7 to REQ-12
- **Revision workflow:** REQ-13

A lightweight traceability table should be maintained with:

- requirement ID
- implementation status (`not started` / `in progress` / `done`)
- validation evidence (test name, screenshot, or runbook step)

---

## Suggested Execution Rhythm

- **Weekly:** requirement status and risk review
- **Per PR:** contract checks (model names, field names, lifecycle values)
- **Milestone checks:** end of Phases 2, 4, and 6

---

## Scope Discipline Rule (V1 Focus)

- Only work required to satisfy V1 requirements enters this plan.
- Nice-to-have enhancements are captured in a separate backlog document.
- Schema or contract changes after Phase 1 require explicit approval and traceability impact review.