# Draft V4.3 Scope Boundary

This document defines the proposed boundary for the constrained-settings revision that follows the V4.2 evidence-and-provenance work. It is intentionally a draft until the earlier revisions have been used and the remaining workflows have been validated.

## Purpose

- Provide a constrained Settings area for safe maintenance of selected application-managed configuration.
- Avoid exposing secrets, restart-sensitive settings, or unrestricted filesystem editing through the UI.

## Proposed In Scope

### 1. Settings Navigation

- Add a Settings entry to application navigation.
- Provide separate, clearly described settings areas rather than a raw configuration editor.
- Restrict V4.3 settings to application-managed values that can be validated and safely changed at runtime.

### 2. Document Type Maintenance

- List active and inactive Document Types.
- Add new types with a stable unique code and user-facing label.
- Edit mutable labels and sort order.
- Activate or deactivate types without invalidating historical Documents.
- Do not allow changing a stable code after creation.
- Do not delete types that are referenced by Documents.

### 3. Person Role Maintenance

- List active and inactive Person Roles.
- Add new roles with a stable unique code and user-facing label.
- Edit mutable labels.
- Activate or deactivate roles without invalidating historical links.
- Do not allow changing a stable code after creation.
- Do not delete roles that are referenced by document-person links.

### 4. Prompt Maintenance

- List prompt markdown files from the configured prompt directory.
- View a prompt with a concise explanation of its purpose and use.
- Edit an existing prompt as plain markdown text.
- Validate the filename boundary and reject empty prompt content.
- Save changes explicitly and report filesystem failures.
- Preserve submission-time prompt text and hash already frozen on existing Jobs.
- Define a safe-write and recovery approach before this feature is considered final scope.

## Proposed Out of Scope

- Viewing or editing raw `.env` files.
- Displaying or changing provider API keys and other secrets.
- Editing host, port, database connection, upload paths, or other restart-sensitive runtime settings.
- Arbitrary file browsing or arbitrary prompt paths.
- Runtime theme/CSS editing.
- Installing themes or plugins.
- Source page renumbering or reordering.
- Source movement between Documents.
- Automatic ordering based on filenames, OCR, or image content.
- FamilySearch API synchronization.
- A generic external-reference registry.
- Ancestry references and Google Maps links.

## Proposed Design Decisions

### A. Registry Codes Are Immutable

- Document Type and Person Role codes are stable identifiers.
- Labels and active state remain mutable.
- Historical references remain valid when a registry entry is inactive.

### B. No Raw Environment Editor

- `.env` may contain secrets and values that are not safely reloadable.
- V4.3 exposes only purpose-built forms backed by explicit validation and service methods.

### C. Prompt Editing Is Constrained

- Prompt maintenance is limited to direct children of the configured prompt directory.
- Existing Job provenance is never rewritten when a prompt file changes.
- The UI must distinguish editing the default for future submissions from inspecting historical Job prompts.

## Decisions Required Before Scope Freeze

1. Define prompt backup, atomic-write, and recovery behavior.
2. Decide whether prompt creation and deletion are needed or whether V4.3 edits existing prompts only.
3. Confirm whether registry sort-order maintenance is needed for Person Roles as well as Document Types.
4. Confirm that settings changes remain local to the current installation and do not require an API surface.

## Draft Acceptance Criteria

1. Document Type and Person Role maintenance preserves stable codes and historical references.
2. Inactive registry entries remain visible on historical records but are excluded from default create selectors.
3. Prompt edits are restricted to valid markdown files in the configured prompt directory.
4. A prompt edit affects future Jobs only and leaves stored Job provenance unchanged.
5. No Settings page exposes secrets or unrestricted filesystem access.
6. Focused service and UI tests pass without regressing V4.1 or V4.2 workflows.

## Scope Freeze Gate

V4.3 implementation should not begin until:

- V4.1 has been used sufficiently to validate priorities.
- V4.2 evidence and provenance work has been completed and validated.
- The four open decisions above are resolved.
- The prompt-write safety policy is documented.
- The implementation plan is revised from draft to committed delivery plan.

## Related Local References

- [Draft V4.3 Implementation Plan](implementation_plan_v4_3.md)
- [V4.2 Scope Boundary](../ver4.2/scope_boundary_v4_2.md)
- [V4.1 Scope Boundary](../ver4.1/scope_boundary_v4_1.md)
- [V4 Architecture](../ver4/architecture_v4.md)
- [V4 Schema](../ver4/schema_v4.md)