chore(refactor): commit current refactor branch updates and slice1 xml/form derivation extraction

2026-04-10 09:39:28 +01:00
parent bd3d311cfb
commit e9d4b65a3d
28 changed files with 1340 additions and 439 deletions
@@ -0,0 +1,83 @@
+# PEDW FrontEnd Guardrails
+
+## Purpose
+
+This document is a fast pre-flight checklist to reduce regressions in high-risk areas. Use it before coding, before opening a PR, and before merge.
+
+## Non-Negotiable Guardrails
+
+1. **Auth/session integrity**
+    - Do not bypass `next-auth` flow in `pages/api/auth/[...nextauth].js`.
+    - Preserve secure redirect behavior and cookie/session settings.
+2. **Security headers and CSP**
+    - Do not weaken `middleware.js` CSP/header behavior or `next.config.js` security headers without explicit rationale.
+3. **Data model safety**
+    - Treat `prisma/schema.prisma` as source-of-truth for auth/account persistence.
+4. **Bilingual parity (EN/CY)**
+    - Any user-facing route/content change must validate both locales.
+    - Keep `i18n.js`, `locales/`, and `next.config.js` rewrites aligned.
+5. **Public-service reliability**
+    - Avoid breaking core flows: search, case, account, myportal, admin.
+
+## Sensitive Flow Protection
+
+Apply extra checks for:
+
+- `pages/api/auth/**`
+- `pages/api/file/**`
+- `pages/api/email/**`
+- `pages/api/endpoint/*_api.js` handling account/user data
+
+## Relay Hash Integrity Rules (CRM-bound APIs)
+
+Apply when changing relay-bound portal endpoints and helpers (notably `pages/api/endpoint/**` and `actions/index.js`):
+
+1. Keep relay endpoint configuration sourced from `API_ROOT`.
+2. Preserve path-hash generation behavior:
+    - hash input must be request path/query (excluding domain),
+    - appended hash parameter must remain compatible with relay expectations.
+3. Do not change hash algorithm/key usage contract without coordinated relay change.
+4. Treat hash validation failures as security-relevant negative paths; verify graceful rejection handling.
+5. Never log hash key material or sensitive request payloads.
+
+Required for sensitive changes:
+
+- Negative-path validation (unauthorized, invalid input, malformed payload).
+- Safe logging (no secrets/tokens/personal data in cleartext).
+- Explicit rollback steps.
+
+## Relay Policy Change Guardrail (timeouts/retries/logging)
+
+When changing shared relay forwarding policy (for example in `pages/api/middleware/relayForwarding.js`), treat this as an operationally sensitive change even if endpoint contracts are unchanged.
+
+Minimum required before merge:
+
+1. Complete the relay governance gate in `context/runbook.md` (Relay Hardening Rollout Playbook).
+2. Attach non-prod smoke evidence for:
+    - deterministic non-retry classes (`400`, `401`, `403`, `404`)
+    - transient retry classes (`429`, `503`, timeout/network-transient)
+3. Confirm structured redacted logging and duplicate-log suppression behavior.
+4. Provide fast mitigation + rollback path (`RELAY_RETRY_MAX=0` and commit-revert path).
+
+## Pre-PR Quick Checklist
+
+- [ ] Ran `npm run lint` (or documented why unavailable)
+- [ ] Verified changed routes/APIs manually
+- [ ] Verified EN + CY behavior for impacted user-facing flow
+- [ ] Performed accessibility smoke checks (keyboard, focus, labels, headings)
+- [ ] Added risk notes (auth/data/i18n/a11y)
+- [ ] Updated `memory-bank/change-log.md` for non-trivial changes
+
+## If Assumptions Are Unclear
+
+1. Record assumptions in PR notes.
+2. Add unresolved items to `memory-bank/open-questions.md`.
+3. Choose the safer behavior and clearly mark as temporary.
+
+## Related Docs
+
+- `.clinerules`
+- `CONTRIBUTING_AI.md`
+- `context/runbook.md`
+- `context/integration-map.md`
+- `memory-bank/README.md`