# New Appeal Refactor Guardrails

## Purpose

These guardrails apply to all AI-assisted and human-assisted work on the refactor branch for the new appeal flow.

## Critical Rule

Preserve the current live S78 behaviour unless the task explicitly requires a behaviour change.

Do not assume a cleaner implementation is allowed to alter behaviour.

## Protected Areas

Treat the following as protected flow files:

- `pages/newappeal/index.js`
- `pages/newappeal/[appealtypes].js`
- `components/newappeal/buildsection.js`
- `components/newappeal/buildchecksection.js`
- `components/newappeal/buildrow.js`
- `components/newappeal/buildfield.js`
- `components/newappeal/buildcheckrow.js`
- `components/newappeal/complete.js`
- `components/newappeal/aboutyou.js`
- `components/newappeal/createCase.js`
- any helpers or service modules used directly by save/progress/upload/submit/finalise logic

## Protected Behaviour

The following must not regress:

1. Start a new S78 appeal
2. Create case / initial journey entry
3. Section rendering from form definition
4. Section progression
5. Save and exit
6. Resume saved appeal
7. File/document upload behaviour
8. Check answers page
9. Appeal PDF generation/download path
10. Final submit/finalisation
11. Confirmation page behaviour
12. Email/notification side effects
13. English/Welsh parity for touched areas

## Required Refactor Approach

When refactoring:

1. Understand current behaviour first
2. Identify the smallest safe boundary
3. Prefer extraction of pure/helper logic
4. Keep public interfaces stable where possible
5. Avoid changing UI, business rules, and structure in one step
6. Keep each slice easy to review and revert

## Required Testing Mindset

Before changing critical flow behaviour, add or update protection such as:

- characterization tests for current behaviour
- targeted integration/service tests
- journey-level regression checks
- payload-shape assertions for save/submit/finalise paths

If automation is not practical yet, include an explicit manual verification matrix.

## Payload/Integration Safety

Do not change without explicit need:

- CRM payload field names or structure
- boolean/value normalization behaviour
- document/file metadata shape
- save/resume payload expectations
- PDF generation inputs
- notification template selection or personalisation structure

## i18n / Accessibility Safety

For touched user-facing behaviour:

- keep EN/CY behaviour aligned
- keep labels, messages, and route behaviour consistent
- preserve semantic structure, focus behaviour, and validation messaging

## Delivery Safety

Preferred pattern for each change:

1. protect current behaviour
2. extract one concern
3. run focused validation
4. keep rollback straightforward
5. merge only when safe

## What To Avoid

Do not:

- perform broad rewrites
- mix feature delivery with refactor work
- replace dynamic/config-driven logic with one-off hardcoding
- move many responsibilities at once
- introduce new dependencies unless clearly justified
- silently change business rules while “cleaning up”

## Refactor Success Criteria

A refactor slice is successful when it:

- preserves behaviour
- reduces complexity or coupling
- improves readability or testability
- keeps regression risk controlled
- remains small enough to merge safely into `SIPS-Development`