Finalized v4.3 scope

docs/ver4.3/implementation_plan_v4_3.md

@@ -1,14 +1,17 @@
-# Draft Implementation Plan (Version 4.3)
+# Implementation Plan (Version 4.3)
 
 ## Goal
 
-Prepare a safe implementation path for constrained application settings. This plan remains provisional until the V4.3 scope-freeze decisions are resolved.
+Deliver constrained, installation-local application settings while preserving the completed V4.2 behavioral baseline and historical provenance.
 
 ## Planning Constraints
 
 - V4, V4.1, and V4.2 remain the behavioral baseline.
 - Settings must use explicit domain operations rather than direct database, environment-file, or arbitrary filesystem access from UI pages.
 - Prompt changes must preserve historical Job provenance and use a defined safe-write policy.
+- Source Page Reordering is excluded.
+- Database, integration, and UI tests must use confirmed isolated test data and must never modify `data/transcription.db`.
+- Potentially destructive tests must run only through `tools/run_destructive_tests.py`.
 
 ## Expected Project Impact
 
@@ -16,59 +19,67 @@ Prepare a safe implementation path for constrained application settings. This pl
 | --- | --- |
 | Documents service | Expand controlled Document Type maintenance operations. |
 | People service | Expand controlled Person Role maintenance operations. |
-| Prompt adapter/service | Add constrained listing, reading, validation, and safe writing of prompt artifacts. |
+| Prompt adapter/service | Add constrained listing, reading, validation, atomic writing, backup, and explicit recovery of existing prompt artifacts. |
 | UI composition/navigation | Register Settings routes and navigation without moving persistence into UI code. |
-| Tests | Add registry lifecycle, prompt safety, and UI workflow coverage. |
+| Tests | Add isolated registry lifecycle, prompt safety, and UI workflow coverage. |
 
-## Proposed Implementation Phases
+## Implementation Phases
 
-### 1. Resolve Scope-Freeze Decisions
+### 1. Define Service Contracts
 
-- Define prompt atomic-write, backup, and recovery policy.
-- Decide whether prompt creation/deletion is excluded.
-- Finalize registry ordering requirements.
-- Remove the Draft designation only after these decisions are reflected in scope and acceptance criteria.
-
-### 2. Define Service Contracts
-
-- Define Document Type maintenance commands for create, relabel, sort, activate, and deactivate.
-- Define Person Role maintenance commands for create, relabel, activate, and deactivate.
-- Define a Prompt Store interface for constrained list/read/write behavior.
+- Define Document Type maintenance commands for create, relabel, sort, activate, deactivate, and delete-if-unreferenced.
+- Define Person Role maintenance commands for create, relabel, activate, deactivate, and delete-if-unreferenced.
+- Define a Prompt Store interface for constrained list, read, write, backup-status, and explicit recovery behavior.
 - Map validation, conflict, not-found, dependency, and filesystem failures to existing `AppError` categories.
 
-### 3. Expand Registry Maintenance Services
+### 2. Expand Registry Maintenance Services
 
 - Reuse existing Document and People service ownership.
 - Add explicit write methods rather than passing UI-mutated ORM objects directly where practical.
 - Normalize and validate new stable codes.
 - Reject duplicate codes deterministically.
-- Block deletion or omit deletion entirely; use activation state for lifecycle management.
+- Permit deletion only after a service-owned reference check proves the entry is unreferenced.
+- Reject deletion of referenced entries deterministically without partial mutation.
+- Permit label changes whether or not an entry is referenced.
 - Preserve inactive entries for historical reads.
-- Add service tests for create, relabel, activation, deactivation, duplicates, immutable codes, and referenced records.
+- Maintain existing Document Type sort order.
+- Order Person Roles deterministically by label and then code without adding a schema field.
+- Add service tests for create, relabel, activation, deactivation, duplicates, immutable codes, ordering, allowed deletion, and blocked referenced deletion.
 
-### 4. Add Constrained Prompt Storage
+### 3. Add Constrained Prompt Storage
 
 - Place filesystem access behind a dedicated Prompt Store/service boundary.
 - Resolve all filenames directly beneath the configured prompt root and reject traversal.
-- Permit only the agreed markdown extension and reject empty content.
-- Implement the approved safe-write strategy, including flush/replace behavior and backup/recovery if selected.
+- Permit only existing files with the agreed Markdown extension and reject empty content.
+- Exclude prompt creation and deletion.
+- Write new content to a sibling temporary file, flush and sync it, preserve the active file as the sole previous-version backup, and atomically replace the active file.
+- Expose explicit backup recovery through the same filename validation and safe-write path; never perform automatic rollback.
+- Clean up temporary files after failed writes while preserving the active prompt and any valid backup.
 - Preserve file encoding and provide explicit failures for read-only or unavailable storage.
 - Do not modify any Job row when prompt defaults change.
-- Add unit tests for valid reads/writes, traversal, invalid names, empty content, filesystem failures, and unchanged Job provenance.
+- Add unit tests for valid reads/writes, traversal, invalid names, nonexistent-file creation attempts, empty content, atomic replacement failures, single-backup rotation, explicit recovery, filesystem failures, and unchanged Job provenance.
 
-### 5. Build the Settings UI
+### 4. Build the Settings UI
 
 - Register a Settings landing page and navigation entry.
 - Add separate pages or panels for Document Types, Person Roles, and Prompts.
 - Keep pages responsible for orchestration and notifications only.
 - Use service callbacks for all mutations.
 - Explain stable codes, inactive historical entries, and future-only prompt effects in the UI.
+- Present deletion only for unreferenced registry entries and preserve clear conflict feedback if references appear before submission.
+- Present prompt backup availability and recovery as an explicit operator action.
 - Do not render raw environment values or secrets.
+- Add no settings API routes.
 
-### 6. Verification and Rollout
+### 5. Verification and Rollout
 
+- Confirm every database, integration, and UI test is configured for an isolated test database before execution.
+- Never run those tests against live data and never modify or replace `data/transcription.db`.
+- Invoke potentially destructive tests only through `tools/run_destructive_tests.py`.
 - Run focused service tests before UI integration tests.
 - Verify inactive registry behavior in both historical display and create/edit selectors.
+- Verify referenced entries can be relabeled or deactivated but not deleted.
+- Verify unreferenced entries can be deleted.
 - Verify prompt changes are picked up by newly created Jobs while historical Jobs retain frozen content/hash.
 - Run the relevant regression suite.
 
@@ -77,27 +88,33 @@ Prepare a safe implementation path for constrained application settings. This pl
 - Existing registry records remain valid.
 - Prompt editing changes mutable application files, not database provenance already captured on Jobs.
 - V4.3 must not require users to recreate existing Sources, Documents, People, roles, or types.
+- Person Role ordering requires no schema migration.
+- Registry deletion introduces no cascade behavior; references always block deletion.
 
-## Proposed Delivery Order
+## Delivery Order
 
-1. Freeze the remaining decisions.
-2. Implement registry maintenance service operations.
-3. Implement the Prompt Store and safety policy.
-4. Build Settings pages.
-5. Run integration and regression verification.
+1. Implement registry maintenance service operations.
+2. Implement the Prompt Store and safety policy.
+3. Build Settings pages.
+4. Run isolated integration and regression verification.
 
-## Draft Done Criteria
+## Done Criteria
 
 - All V4.3 acceptance criteria are testable and satisfied.
 - Settings mutations cross explicit service or adapter boundaries.
 - Registry codes cannot be accidentally changed.
+- Referenced registry entries can be relabeled or deactivated but cannot be deleted.
+- Unreferenced registry entries can be deleted without cascade behavior.
 - Prompt writes cannot escape the configured directory or rewrite historical provenance.
+- Prompt writes are atomic, retain one backup, and support explicit recovery.
 - No secret or raw environment editor exists.
+- No settings API surface exists.
 - V4.1 and V4.2 workflows remain intact.
+- Verification does not touch live data or `data/transcription.db`.
 
 ## Related Local References
 
-- [Draft V4.3 Scope Boundary](scope_boundary_v4_3.md)
+- [V4.3 Scope Boundary](scope_boundary_v4_3.md)
 - [V4.2 Implementation Plan](../ver4.2/implementation_plan_v4_2.md)
 - [V4.1 Implementation Plan](../ver4.1/implementation_plan_v4_1.md)
 - [V4 Implementation Plan](../ver4/implementation_plan_v4.md)