transcription/docs/ver1/ver1-step3.md

Step 3 Implementation Plan: Functional Completion by Requirement Domain

Purpose

Implement Ver1 Step 3 from docs/ver1/ver1.md by completing all in-scope V1 functional requirements in a practical, user-first order while preserving:

• personal-scale operation
• single-operator workflow
• private-network deployment assumptions
• low operational overhead
• clean architecture boundaries

Primary governing docs:

• docs/ver1/ver1.md (Step 3 objective and sequencing)
• docs/architecture.md (module boundaries, workflow, simplicity guardrails)
• docs/requirements.md (REQ-0 through REQ-12 traceability)
• docs/error_handling.md (error contract across boundaries)
• docs/intent.md (verbatim transcription policy and prompt curation)
• docs/ver1/ver1-step1-2-carry-forward-checklist.md (Step 1/2 carry-forward integration)
• docs/ver1/ver1-step2-error-path-inventory.md (failure-path coverage visibility)

---

MCP Resources Reviewed and Applied

All resources on john-stream-mcp were reviewed. Step 3 applies the following guidance directly:

1. resource://skills/nicegui/document

   • modular page registration
   • one-way dependency flow (ui/api -> services -> infra)
   • async-first UI responsiveness expectations

2. resource://skills/nicegui-ui-customization/document

   • reusable UI component extraction for repeated patterns
   • in-flight guards and explicit success/failure user feedback
   • event-driven updates over ad-hoc polling

3. resource://skills/fastapi-async-sqlalchemy-modernization/document

   • explicit transaction/session boundaries
   • deterministic resource ownership and cleanup continuity from Step 1
   • incremental migration strategy with rollback-aware checkpoints

4. resource://skills/pydantic-settings/document

   • typed configuration as single source of runtime truth
   • explicit source precedence and environment-safe defaults

5. resource://skills/python-logging-dictconfig/document

   • centralized startup-only logging configuration
   • named logger discipline and boundary-level structured fields

6. resource://skills/pytesting/document

   • deterministic test structure and marker discipline
   • behavior-first tests with clear fast-path and full-suite validation

7. resource://skills/fastapi-uv-docker/document

   • health endpoint and runtime startup/shutdown hygiene
   • compose/deployment readiness constraints relevant to functional completion

8. resource://skills/python-typing/document

   • modern typing updates where touched by Step 3 work

9. resource://skills/ruff-linting-formating/document

   • maintain lint/format consistency in all modified modules

10. resource://prompts/greenfield-architecture/document

• explicit staged delivery with tradeoff-aware sequencing and test strategy

11. resource://prompts/pytest-scaffold/document
12. resource://prompts/pytest-fill-scaffold/document

• structure-first test planning, then deterministic implementation fill-in

Resources reviewed but not directly in Step 3 execution scope (no changes required now):

• copilot-customization, mcp-details, vscode-configuration, zensical-docs
• prompts: authoring, mcp-consumer-repo-shim

---

Step 3 Success Criteria

Step 3 is complete when:

1. All Step 3-targeted requirement slices are implemented and verified.
2. Functional behavior is available through UI/API where required.
3. Core data integrity and state transitions are deterministic.
4. Error behavior follows docs/error_handling.md contracts.
5. Carry-forward Step 1/2 items mapped to Step 3 are updated with evidence.

---

Requirement-Slice Execution Model (Applied to Every Slice)

For each slice, execute this sequence:

1. Confirm contract/schema and boundary ownership.
2. Implement service/domain logic.
3. Implement persistence/state transitions.
4. Integrate API and/or UI behavior.
5. Add/update unit + integration + targeted end-to-end tests.
6. Update docs and traceability artifacts.

Definition of done per slice:

• behavior is functional
• tests pass in intended marker lanes
• error pathways are classified and surfaced correctly
• requirement traceability is updated with evidence

---

Detailed Workstreams

Workstream A — Functional Baseline Audit and Slice Backlog Lock

Goals

• establish exact Step 3 functional delta from current implementation
• lock a practical slice backlog before coding

Tasks

1. Build Step 3 requirement matrix (REQ -> current status -> gap -> target slice).
2. Map each gap to one of these domains:
   • Upload and lifecycle integrity
   • Review and revision history
   • Search over accepted transcripts
   • Export workflows
   • Prompt asset management behavior
   • API/UI parity and status visibility
3. Align each slice with architecture boundary ownership and persistence strategy.
4. Link open carry-forward items from checklist:
   • CF-A1, CF-A3 (architecture continuity in Step 3)
   • CF-C1, CF-C2 (traceability/execution continuity)

Deliverables

• Step 3 requirement-slice matrix (appendix in this doc or separate artifact)
• prioritized slice backlog with owner and validation method

Exit Criteria

• every Step 3 slice maps to REQ IDs and a validation method
• no ambiguous ownership remains for in-scope slices

---

Workstream B — Core End-User Flows (Upload -> Transcribe -> Review)

Related Requirements

• REQ-0, REQ-1, REQ-2, REQ-3, REQ-4, REQ-5, REQ-6, REQ-12

Goals

• guarantee end-to-end reliability and usability of the primary user flow
• ensure review experience supports transcript acceptance and correction

Tasks

1. Validate and close any lifecycle-state gaps:
   • enforce valid transitions (queued -> processing -> transcribed/failed/completed)
   • ensure transition visibility in UI/API
2. Review experience completion:
   • transcript detail display stability
   • failure detail readability and actionability
   • acceptance/edit path for human review
3. Ensure prompt-asset integration remains file-based and auditable:
   • one prompt per Markdown file
   • prompt selection/usage traceability in job outcomes (if available in model)
4. Confirm worker/UI interactions remain responsive under long-running jobs:
   • in-flight guards
   • clear status refresh behavior

Deliverables

• complete end-user flow behavior with stable lifecycle visibility
• test coverage for happy path and failure path

Exit Criteria

• user can run upload -> process -> review reliably
• failed and successful outcomes are both actionable and traceable

---

Workstream C — Revision History and Provenance Completion

Related Requirements

• REQ-3, REQ-4, REQ-5, REQ-11

Goals

• finalize immutable transcript revision behavior and provenance consistency

Tasks

1. Define/confirm revision invariants:
   • append-only revision history
   • clear current/accepted revision indicator
2. Persist revision events consistently through service layer boundaries.
3. Ensure UI/API expose revision timeline and selected revision details.
4. Align error handling for revision conflicts and missing resources.

Deliverables

• revision-history feature completeness
• provenance and history read-path coverage

Exit Criteria

• transcript edits produce deterministic revision records
• previous revisions remain inspectable

---

Workstream D — Search Completion (Accepted Transcript Scope)

Related Requirements

• REQ-0, REQ-5, REQ-11

Goals

• provide practical search over accepted transcripts for personal corpus usage

Tasks

1. Finalize searchable scope and indexing rules (accepted/current text only).
2. Implement service-backed search query behavior.
3. Expose search in UI/API with clear result metadata (document/job/revision context).
4. Add guardrails for empty/no-result/error scenarios with actionable messaging.

Deliverables

• functional search pathway with deterministic results for accepted text

Exit Criteria

• operator can find transcripts reliably by text queries
• no-result and error states are clear and non-silent

---

Workstream E — Export Completion

Related Requirements

• REQ-0, REQ-4, REQ-5, REQ-11

Goals

• deliver practical export of transcript data for personal archive use

Tasks

1. Finalize export contract (format, included fields, scope filters).
2. Implement export service with deterministic data mapping.
3. Add UI/API trigger path and user-visible completion/failure feedback.
4. Validate export integrity against persisted source-of-record entities.

Deliverables

• end-to-end export capability with operator-visible outcomes

Exit Criteria

• export output is complete, consistent, and usable for downstream personal archive workflows

---

Workstream F — API/UI Parity and Interaction Hardening

Related Requirements

• REQ-5 plus cross-cutting REQ-2/3/4

Goals

• ensure UI and API expose coherent feature behavior and error contracts

Tasks

1. Verify API/UI parity matrix for each Step 3 slice.
2. Standardize interaction behavior:
   • loading and in-flight states
   • success/failure notifications
   • stable error_id visibility where user-facing
3. Ensure route/page modules remain composition-focused (business logic in services).

Deliverables

• API/UI parity checklist with resolved gaps

Exit Criteria

• no major flow exists in one interface with conflicting semantics in the other

---

Workstream G — Carry-Forward Integration During Step 3

Goals

• close Step 1/2 follow-ups that are Step 3-owned

Tasks

1. Update checklist item CF-A1 as Step 3 slices touch runtime resources.
2. Update checklist item CF-A3 with lightweight boundary enforcement evidence.
3. Update CF-C1/CF-C2 traceability mapping with Step 3 outcomes.

Deliverables

• updated docs/ver1/ver1-step1-2-carry-forward-checklist.md evidence entries

Exit Criteria

• Step 3-owned carry-forward items are either completed or explicitly routed with evidence

---

Test and Validation Plan

Apply pytesting guidance with deterministic, behavior-focused coverage.

Validation Lanes

1. Structure/collection:
   • uv run pytest --collect-only -q
2. Fast feedback lane:
   • uv run pytest -m unit -q
3. Main verification lane:
   • uv run pytest -m "not external" -q
4. Full suite:
   • uv run pytest -q

Required Coverage Areas

• lifecycle transition invariants
• revision history invariants
• search query behavior and result mapping
• export integrity and failure handling
• UI interaction guards and actionable failure feedback
• API envelope and status consistency for new/changed flows

Test Design Rules

• one behavior target per test
• minimize heavy mocking; prefer real-path behavior checks where practical
• keep markers explicit and strict

---

Logging, Error, and Config Guardrails for Step 3 Changes

1. Logging

   • keep centralized startup logging config (dictConfig) as canonical
   • include required error fields at boundary failures (error_id, category, operation, identifiers where available)

2. Error handling

   • preserve taxonomy stability from docs/error_handling.md
   • map any new failure pathways into existing categories
   • surface actionable suggestions in UI/API

3. Configuration

   • use typed settings and avoid ad-hoc env reads in business modules
   • keep environment behavior explicit and documented

---

Implementation Order (Detailed)

1. Workstream A: audit and backlog lock
2. Workstream B: core flow completion
3. Workstream C: revision/provenance completion
4. Workstream D: search completion
5. Workstream E: export completion
6. Workstream F: API/UI parity hardening
7. Workstream G: carry-forward integration updates
8. Full validation pass + docs/traceability updates

---

Deliverables

1. Step 3 requirement-slice matrix with REQ mapping and evidence links
2. implemented Step 3 functional slices across service/persistence/API/UI
3. updated tests and passing validation lanes
4. updated carry-forward checklist entries (CF-A1, CF-A3, CF-C1, CF-C2 as applicable)
5. Step 3 results document (docs/ver1/ver1-step3-results.md)

---

Risks and Mitigations

1. Risk: Scope creep from optional enhancements during feature completion

   • Mitigation: enforce REQ-mapped slice backlog and defer non-REQ enhancements

2. Risk: Functional parity drift between UI and API

   • Mitigation: maintain parity matrix and verify both surfaces per slice

3. Risk: Data-model changes introduce migration surprises

   • Mitigation: coordinate with Step 4 runbook expectations early and test on representative data

4. Risk: Reliability regressions while adding functionality

   • Mitigation: run full error-path regression checks and keep Step 2 contracts intact

---

Step 3 Completion Checklist

• Step 3 requirement-slice matrix completed and linked to REQ IDs.
• Core end-user flow is functionally complete and verified.
• Revision history/provenance behavior is complete and test-covered.
• Search over accepted transcripts is complete and test-covered.
• Export flow is complete and test-covered.
• API/UI parity checklist has no unresolved high-impact gaps.
• Step 3-owned carry-forward items are updated with evidence.
• Validation lanes pass (collect-only, unit, non-external, full).
• docs/ver1/ver1-step3-results.md is created with evidence and residual follow-ups.

---

Handoff to Step 4

Step 3 completion enables Step 4 (Data Model and Migration Safety) with:

• finalized functional domain behavior
• stable persistence expectations
• traceable requirement evidence
• clarified migration-impact surface