Robert Bond
0de9268255
## Summary This PR merges the completed new-appeal refactor stream (Slices 1–8) into SIPS-Development. This refactor was executed in controlled slices with regression validation at each step. ## Scope Structural and readability improvements only: - XML/form derivation extraction - payload and file helper extraction - side-effect facade introduction - BuildSection and BuildCheckSection decomposition - BuildCheckRow formatter map refactor - nested prop boundary cleanup - start-flow cleanup (CreateCase / AboutYou) ## Behaviour No intended behavioural changes. The following were explicitly preserved: - S78 journey behaviour - payload shapes and field names/ids - HASCAS mapping logic - appellant/agent branching - validation rules and messages - redirect/query parameters (`lpa`, `apt`, `id`) - navigation and side-effect sequencing - EN/CY output parity ## Validation Full regression has been performed on: - start flow (CreateCase / AboutYou) - save and resume flows - file upload handling - check answers rendering - submit/finalisation sequence - confirmation flow - CRM insertion path - EN/CY parity Additional checks: - docsOffline branch behaviour - completion and partial-save email paths - negative-path validation scenarios - lint (warnings baseline unchanged) ## Risk Low: - changes are structural only - no business logic changes - no contract changes ## Rollback Safe rollback via reverting this merge commit. ## Notes This refactor reduces coupling and prepares the new-appeal flow for future appeal-type expansion. Related work items: #22570, #22576, #22577, #22583, #22586, #22587, #22588, #22590
229 lines
4.9 KiB
Markdown
229 lines
4.9 KiB
Markdown
# Refactor Branch Rules (Active)
|
|
|
|
## Purpose
|
|
|
|
This file defines the active working rules for this refactor branch.
|
|
|
|
This branch is focused on **safe, behaviour-preserving refactor of the new appeal flow**.
|
|
|
|
---
|
|
|
|
## Core Rule (Highest Priority)
|
|
|
|
Do not change live S78 behaviour unless explicitly instructed.
|
|
|
|
Refactor = improve structure, not behaviour.
|
|
|
|
---
|
|
|
|
## Primary Objectives
|
|
|
|
1. Make the new appeal flow easier to understand and maintain
|
|
2. Reduce risk when making future changes
|
|
3. Prepare the system for multiple appeal types
|
|
4. Improve separation of concerns (UI, workflow, data, integrations)
|
|
|
|
---
|
|
|
|
## Non-Negotiable Rules
|
|
|
|
- Preserve all current user journeys:
|
|
- start appeal
|
|
- save and exit
|
|
- resume appeal
|
|
- upload documents
|
|
- check answers
|
|
- submit appeal
|
|
- confirmation
|
|
|
|
- Do not:
|
|
- change payload structures
|
|
- change validation rules
|
|
- change business logic
|
|
- hardcode logic that is currently dynamic/config-driven
|
|
- mix refactor with feature work
|
|
|
|
---
|
|
|
|
## Refactor Approach
|
|
|
|
Always:
|
|
|
|
1. Understand current behaviour first
|
|
2. Identify smallest safe change
|
|
3. Prefer extraction over rewrite
|
|
4. Keep public interfaces stable
|
|
5. Make changes easy to review and revert
|
|
|
|
---
|
|
|
|
## Change Size Guidance
|
|
|
|
- Prefer small PRs (<400 LOC where possible)
|
|
- Avoid large multi-concern changes
|
|
- Split work into safe slices
|
|
|
|
---
|
|
|
|
## Context Usage Rules (Critical for Efficiency)
|
|
|
|
### Default context (only load these):
|
|
|
|
- `context/refactor-branch-charter.md`
|
|
- `context/newappeal-refactor-guardrails.md`
|
|
- `context/architecture.md`
|
|
- `context/domain-flows.md`
|
|
|
|
### Only load additional context when needed:
|
|
|
|
- integrations → `integration-map.md`
|
|
- testing gaps → `test-coverage-map.md`
|
|
- release concerns → `runbook.md`
|
|
- specific work plan → `context/plans/*`
|
|
|
|
### Never load by default:
|
|
|
|
- all context files
|
|
- onboarding or overview docs
|
|
- all templates
|
|
- memory-bank contents
|
|
|
|
---
|
|
|
|
## Templates Usage
|
|
|
|
Templates are optional helpers.
|
|
|
|
- Use only ONE template when needed
|
|
- Do not load all templates
|
|
- Do not treat templates as baseline context
|
|
|
|
---
|
|
|
|
## Safety Rules
|
|
|
|
- Do not weaken authentication or session logic
|
|
- Do not weaken security headers or middleware
|
|
- Do not expose secrets or personal data
|
|
- Preserve EN/CY parity
|
|
- Maintain accessibility standards
|
|
|
|
---
|
|
|
|
## Testing & Validation Expectations
|
|
|
|
Minimum:
|
|
|
|
- `npm run lint`
|
|
- targeted manual verification
|
|
- EN/CY checks (if user-facing)
|
|
- negative-path checks (for sensitive flows)
|
|
|
|
Before changing critical logic:
|
|
|
|
- add or update regression protection where possible
|
|
|
|
---
|
|
|
|
## When Unsure
|
|
|
|
If any uncertainty exists:
|
|
|
|
1. Choose the safest option
|
|
2. Do not change behaviour
|
|
3. Call out assumptions
|
|
4. Keep the change minimal
|
|
|
|
---
|
|
|
|
## Definition of Success
|
|
|
|
A successful change:
|
|
|
|
- preserves behaviour
|
|
- reduces complexity
|
|
- improves clarity or structure
|
|
- is small and safe to merge
|
|
- does not introduce regression risk
|
|
|
|
---
|
|
|
|
## One-Line Rule
|
|
|
|
If in doubt:
|
|
|
|
> Keep behaviour the same, reduce risk, and make the smallest safe change.
|
|
|
|
---
|
|
|
|
## Documentation Rule (Minimal and Targeted)
|
|
|
|
Only document information that is necessary to safely understand or change the system later.
|
|
|
|
Document:
|
|
|
|
- key decisions (why something was changed)
|
|
- non-obvious behaviour
|
|
- risks or constraints (what must not be changed)
|
|
- important assumptions
|
|
|
|
Do not document:
|
|
|
|
- obvious code behaviour
|
|
- step-by-step implementation details
|
|
- temporary or experimental work
|
|
- duplicated explanations across files
|
|
|
|
Prefer short, focused notes over long explanations.
|
|
|
|
If unsure:
|
|
|
|
> Will someone break the system in the future if this is not written down?
|
|
|
|
If yes → document it
|
|
If no → do not document it
|
|
|
|
Documentation should be minimal, high-signal, and never outweigh the value of the code itself.
|
|
|
|
## Branch Safety Rule
|
|
|
|
This refactor stream uses the `refactor` branch as its working base branch.
|
|
|
|
For refactor work:
|
|
|
|
- do all implementation from the `refactor` branch or a short-lived feature branch created from `refactor`
|
|
- do not implement refactor work directly on `SIPS-Development`
|
|
|
|
`SIPS-Development` remains the BAU integration branch.
|
|
Refactor changes may be merged into `SIPS-Development` only when proven safe.
|
|
|
|
If branch context is unclear, stop and confirm before making changes.
|
|
|
|
## Branch Model
|
|
|
|
- `SIPS-Development` = BAU branch
|
|
- `refactor` = refactor integration branch
|
|
- optional short-lived working branches for individual slices should be created from `refactor`
|
|
|
|
## Regression Safety Rule (Critical)
|
|
|
|
This is a live system. All refactor work must prove behaviour is unchanged.
|
|
|
|
Before completing any slice:
|
|
|
|
- verify core journey behaviour has not changed
|
|
- verify protected flows still work:
|
|
- save and exit
|
|
- resume appeal
|
|
- upload documents
|
|
- check answers
|
|
- submit appeal
|
|
- confirmation
|
|
|
|
- verify EN/CY parity for any affected areas
|
|
|
|
A slice is NOT complete until regression behaviour is confirmed.
|
|
|
|
If regression cannot be confidently ruled out:
|
|
→ do not proceed to next slice
|