transcription/docs/ver4.2/scope_boundary_v4_2.md

# Draft V4.2 Scope Boundary

This document defines the proposed boundary for the second incremental revision to Version 4. It is intentionally a draft until V4.1 has been used and the remaining workflows have been validated.

## Purpose

- Allow correction of Source page order after import.
- 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. Source Page Reordering

- Allow Sources within one Document to be reordered after import.
- Present the current order using page number and a recognizable source label or preview.
- Persist the complete intended order atomically.
- Renumber the affected Document's Sources to a contiguous sequence beginning at 1.
- Keep all Sources attached to their existing Document.
- Ensure transcription rendering and previous/next navigation use the updated order.
- Detect stale or invalid reorder submissions and fail without partial mutation.

### 2. Settings Navigation

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

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

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

### 5. 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 movement between Documents as part of reordering.
- 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. Reordering Is Set-Based

- The client submits the full ordered list of Source IDs for one Document.
- The service validates membership, completeness, duplicates, and authorization/context before writing.
- All page-number updates occur in one transaction.

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

### C. No Raw Environment Editor

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

### D. 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. Choose the reorder interaction: move-up/down controls, drag-and-drop, or both.
2. Decide whether reordering is allowed while the Document has a queued or processing Job.
3. Define prompt backup, atomic-write, and recovery behavior.
4. Decide whether prompt creation and deletion are needed or whether V4.2 edits existing prompts only.
5. Confirm whether registry sort-order maintenance is needed for Person Roles as well as Document Types.
6. Confirm that settings changes remain local to the current installation and do not require an API surface.

## Draft Acceptance Criteria

1. Reordering a Document's Sources produces contiguous page numbers and updates every ordered view consistently.
2. Invalid, incomplete, duplicate, cross-Document, or stale reorder requests make no changes.
3. Document Type and Person Role maintenance preserves stable codes and historical references.
4. Inactive registry entries remain visible on historical records but are excluded from default create selectors.
5. Prompt edits are restricted to valid markdown files in the configured prompt directory.
6. A prompt edit affects future Jobs only and leaves stored Job provenance unchanged.
7. No Settings page exposes secrets or unrestricted filesystem access.
8. Focused service and UI tests pass without regressing V4.1 workflows.

## Scope Freeze Gate

V4.2 implementation should not begin until:

- V4.1 has been used sufficiently to validate priorities.
- The six 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.2 Implementation Plan](implementation_plan_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)