pedwfrontend/context/refactor-branch-charter.md

Refactor Branch Charter — New Appeal Flow

Purpose

This branch exists to safely refactor the live new appeal flow so it is easier to maintain, safer to change, and better prepared to support additional appeal types beyond the current S78 planning appeal flow.

This is a behaviour-preserving refactor branch, not a feature branch.

Primary Goal

Create a safer internal structure for the new appeal flow while preserving current live behaviour for the S78 appeal journey.

Why This Branch Exists

The current new appeal implementation has grown over time to meet business need and now contains a mix of:

• page composition
• flow orchestration
• XML-driven form rendering
• validation
• file/document handling
• progress/save logic
• submission/finalisation logic
• integration shaping for CRM, PDF generation, and notifications

This branch exists to improve those boundaries incrementally without disrupting the live service.

Scope

In scope:

• behaviour-preserving refactor of pages/newappeal/** and components/newappeal/**
• extraction of reusable workflow logic from UI-heavy components
• improved boundaries between rendering, workflow, and integration logic
• regression test coverage for critical S78 journeys
• preparing the codebase for future appeal-type extensibility

Out of scope unless explicitly requested:

• business rule changes
• visual redesign
• broad framework/library migration
• replacing working dynamic form behaviour with hardcoded appeal-specific logic
• changes to live BAU behaviour beyond strictly necessary bug fixes

Branch Relationship to BAU

• BAU continues on SIPS-Development
• this branch is the protected refactor lane
• safe, proven slices may be merged back into SIPS-Development when ready
• urgent live fixes should go to SIPS-Development first, then be synced into this branch

Non-Negotiable Principles

1. Preserve live S78 behaviour unless explicitly told otherwise.
2. Prefer extraction over rewrite.
3. Prefer small, mergeable slices over long-lived hidden change.
4. Add or update regression protection before changing critical flow logic.
5. Keep English/Welsh behaviour aligned.
6. Treat save/resume/upload/check/submit/complete as protected journey stages.

Target Direction

The long-term direction is:

• shared new appeal workflow engine
• appeal-type definitions/configuration separated from UI rendering
• smaller, clearer components
• isolated validation and payload-shaping logic
• safer addition of future appeal types through definition + bounded type-specific rules

Definition of Success

This branch is succeeding when:

• core S78 journey behaviour remains stable
• regression confidence increases
• high-risk logic moves out of large render-heavy components
• new appeal code becomes easier to understand and test
• future appeal types can be added with less change to core flow code

Working Branch Model

This refactor stream uses the refactor branch as its working base.

• BAU continues on SIPS-Development
• refactor work is performed from refactor
• safe refactor slices may later be merged into SIPS-Development

This branch should not be treated as BAU, and BAU should not be treated as the refactor workspace.