Implementation Plan (Version 4.3)

Goal

Deliver constrained, installation-local application settings while preserving the completed V4.2 behavioral baseline and historical provenance.

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.

Area	Expected impact
Documents service	Expand controlled Document Type maintenance operations.
People service	Expand controlled Person Role maintenance operations.
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 isolated registry lifecycle, prompt safety, and UI workflow coverage.

Define Document Type maintenance commands for create, relabel, 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.

Reuse existing Document and People service ownership.
Add explicit write methods rather than passing UI-mutated ORM objects directly where practical.
Normalize Document Type labels and reject case-insensitive duplicates deterministically.
Keep Person Role stable-code validation and duplicate rejection.
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.
Order Document Types alphabetically by normalized label.
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.

Place filesystem access behind a dedicated Prompt Store/service boundary.
Resolve all filenames directly beneath the configured prompt root and reject traversal.
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, nonexistent-file creation attempts, empty content, atomic replacement failures, single-backup rotation, explicit recovery, filesystem failures, and unchanged Job provenance.

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 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.

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.

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.

All V4.3 acceptance criteria are testable and satisfied.
Settings mutations cross explicit service or adapter boundaries.
Document Types use UUID-only identity and unique labels; Person Role 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.