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
177 lines
3.7 KiB
Markdown
177 lines
3.7 KiB
Markdown
# Contributing with AI (Refactor Branch — PEDW FrontEnd)
|
|
|
|
## Purpose
|
|
|
|
This guide defines how engineers and AI agents should work safely and efficiently in this refactor branch.
|
|
|
|
This branch focuses on **safe, behaviour-preserving refactor of the new appeal flow**.
|
|
|
|
---
|
|
|
|
## Start Here (Required Order)
|
|
|
|
1. Read `.clinerules/refactor-branch-rules.md`
|
|
2. Read `GUARDRAILS.md`
|
|
3. Read core context:
|
|
- `context/refactor-branch-charter.md`
|
|
- `context/newappeal-refactor-guardrails.md`
|
|
- `context/architecture.md`
|
|
- `context/domain-flows.md`
|
|
|
|
Only read additional files when directly relevant.
|
|
|
|
Do **not** load all context, templates, or memory-bank files by default.
|
|
|
|
---
|
|
|
|
## Core Principle
|
|
|
|
This is a **refactor branch**, not a feature branch.
|
|
|
|
- Preserve current live S78 behaviour
|
|
- Do not introduce business-rule changes unless explicitly requested
|
|
- Prefer small, safe, reversible changes
|
|
- Focus on structure, not behaviour
|
|
|
|
---
|
|
|
|
## Standard AI-Assisted Workflow
|
|
|
|
### 1. Scope
|
|
|
|
- Define requirement
|
|
- Confirm non-goals
|
|
- Identify impacted flow areas
|
|
- Identify risk level
|
|
|
|
### 2. Plan
|
|
|
|
- Keep plan small and incremental
|
|
- Identify safe boundaries
|
|
- Avoid mixing refactor + feature work
|
|
|
|
### 3. Implement
|
|
|
|
- Make the smallest viable change
|
|
- Prefer extraction over rewrite
|
|
- Preserve interfaces and payload shapes
|
|
|
|
### 4. Validate
|
|
|
|
Minimum required:
|
|
|
|
- `npm run lint`
|
|
- targeted manual checks
|
|
- EN/CY parity checks (if user-facing)
|
|
- negative-path checks for sensitive flows
|
|
|
|
### 5. Document (only when needed)
|
|
|
|
- update `memory-bank/change-log.md` for non-trivial work
|
|
- record decisions or pitfalls if useful
|
|
|
|
---
|
|
|
|
## Templates (Use Only When Needed)
|
|
|
|
Templates are optional tools, not default context.
|
|
|
|
Use **only one** template if needed:
|
|
|
|
- feature implementation
|
|
- bug fix
|
|
- refactor
|
|
- debugging
|
|
- code review
|
|
|
|
Do not load all templates.
|
|
Do not treat templates as baseline context.
|
|
|
|
---
|
|
|
|
## Context Loading Rule (Critical)
|
|
|
|
Always use the **minimum required context**.
|
|
|
|
### Default context for this branch:
|
|
|
|
- `context/refactor-branch-charter.md`
|
|
- `context/newappeal-refactor-guardrails.md`
|
|
- `context/architecture.md`
|
|
- `context/domain-flows.md`
|
|
|
|
### Only load additional files when:
|
|
|
|
- working with integrations → `integration-map.md`
|
|
- reviewing test gaps → `test-coverage-map.md`
|
|
- performing release work → `runbook.md`
|
|
- working on specific planned sequence → `context/plans/*`
|
|
|
|
Never load:
|
|
|
|
- all context files
|
|
- all templates
|
|
- onboarding or overview docs
|
|
|
|
---
|
|
|
|
## Branching Protocol
|
|
|
|
This repository currently uses different branch rules depending on the work type.
|
|
|
|
### For BAU / normal delivery work
|
|
|
|
- create work branches from `SIPS-Development`
|
|
|
|
### For new appeal refactor work
|
|
|
|
- use the `refactor` branch as the base branch
|
|
- do refactor implementation either:
|
|
- directly on `refactor`, if that is the agreed working model, or
|
|
- on a short-lived feature branch created from `refactor`
|
|
|
|
Do not perform refactor implementation directly on `SIPS-Development`.
|
|
|
|
If unsure which branch model applies, stop and confirm before making changes.
|
|
|
|
---
|
|
|
|
## No-Break Rules (Always Enforce)
|
|
|
|
- Do not weaken auth/session behaviour
|
|
- Do not weaken security headers/CSP
|
|
- Keep EN/CY behaviour aligned
|
|
- Do not expose secrets or personal data
|
|
- Protect save/resume/upload/submit journeys
|
|
|
|
---
|
|
|
|
## PR Minimum (AI-Assisted)
|
|
|
|
Every change must include:
|
|
|
|
- Scope summary
|
|
- Files changed
|
|
- Risk notes (auth/data/i18n/a11y)
|
|
- Validation evidence
|
|
- Rollback plan
|
|
|
|
---
|
|
|
|
## Handling Unknowns
|
|
|
|
If unsure:
|
|
|
|
1. Choose the safer option
|
|
2. Do not change behaviour
|
|
3. call out assumptions clearly
|
|
4. log open questions if needed
|
|
|
|
---
|
|
|
|
## Summary Rule
|
|
|
|
If in doubt:
|
|
|
|
> Preserve behaviour, reduce risk, keep changes small.
|