transcription/docs/ver4.3/implementation_plan_v4_3.md

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

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.

Expected Project Impact

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, and safe writing of 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.

Proposed Implementation Phases

1. Resolve Scope-Freeze Decisions

• 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.
• Map validation, conflict, not-found, dependency, and filesystem failures to existing AppError categories.

3. 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.
• Preserve inactive entries for historical reads.
• Add service tests for create, relabel, activation, deactivation, duplicates, immutable codes, and referenced records.

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

5. 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.
• Do not render raw environment values or secrets.

6. Verification and Rollout

• Run focused service tests before UI integration tests.
• Verify inactive registry behavior in both historical display and create/edit selectors.
• Verify prompt changes are picked up by newly created Jobs while historical Jobs retain frozen content/hash.
• Run the relevant regression suite.

Migration and Compatibility Notes

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

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

Draft 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.
• Prompt writes cannot escape the configured directory or rewrite historical provenance.
• No secret or raw environment editor exists.
• V4.1 and V4.2 workflows remain intact.

Related Local References

• Draft V4.3 Scope Boundary
• V4.2 Implementation Plan
• V4.1 Implementation Plan
• V4 Implementation Plan
• V4 Error Handling Policy