CURRENT UPDATE — 22 October 2026
See PENSION-PROVIDER-PROCESSING.md for current payroll/provider capabilities,
verification, supported exports and remaining limitations.
The notes below describe the earlier implementation and planning history.

HISTORICAL UPDATE — scheme setup and employee assignment fixes
Add scheme now opens a provider/frequency/name dialog and persists a draft.
The empty saved-scheme selector is replaced by an explicit no-schemes message.
Save draft accepts missing provider identifiers and unconfirmed tax relief; completed
setup still validates these. The optional internal reference remains optional.
All task pages are accessible regardless of setup completeness. Processing actions
validate their own prerequisites. Assessment now includes an employee pension
register and a persisted per-employment nominated scheme. Assignments do not create
membership or switch deductions. Enrolment resolves the nominated scheme and records
its ID/version in the membership snapshot. Existing active/pending memberships cannot
be removed by editing the nominated scheme. Provider processing limits below remain.
PENSION WORKSPACE — IMPLEMENTATION AND FOLLOW-ON DESIGN
21 October 2026

IMPLEMENTED
Pensions now uses the Reports area's shared WPF controls, typography and restrained
green accents. Five task tabs replace the single scrolling form: Scheme details,
Assessment, Membership & letters, Leavers & refunds, Provider files.
Scheme setup has two columns that stack at smaller sizes. Save/Revert remain
visible below the scrolling fields. Contact and bank details are optional.

Named schemes are employer-scoped and stored in PensionSchemeSetups. Changes use
optimistic version checks and append immutable PensionSchemeSetupHistory entries.
No existing memberships or historical payroll values are migrated or rewritten.
Read-only users cannot save schemes. New schemes require explicit tax relief.

Fields: name, reference, provider, frequency, provider employer/account reference,
scheme code, payment source, default group, tax relief, earnings basis, employee
gross rate, employer rate, additional contributions, inclusion of non-members,
address, postcode, telephone, bank, sort code, account name/number, payment reference
and method. Fields irrelevant to a selected provider are hidden and cleared on save.

CURRENT PROCESSING LIMIT
The existing engine supports NEST qualifying earnings, relief at source and its
standard 5% gross employee / 3% employer workflow. The workspace enables this
workflow only for compatible saved configurations. Other providers, rates, earnings
bases, additional contributions and tax relief options can be recorded as setup
but are explicitly labelled as not connected to payroll or provider exports.
Scheme defaults do not apply new rates to existing employees. Provider fields on
employee membership records are not yet generalised beyond NEST.
This is a screen/setup implementation, not complete multi-provider processing.

REFERENCE REVIEW
Read all extracted text from the eight Moneysoft guides (76 pages combined) and
the one-page P32; rendered all pages and inspected representative setup examples.
Original files are in C:/Users/SMRCo/Downloads. Page text and renders are retained
under verification/pension-reference. The P32 is an employer payment report,
not a source for pension assessment or contribution calculations.

Provider differences from the supplied guides:
- NEST (17 pages): employer ID; exact case-sensitive payment source and group;
  separate enrolment/contribution files; enrolment type; tax-weekly/tax-monthly
  schedule mapping; earnings period alignment; optional direct web services.
- People's Pension (8): provider account number; exact worker group; employee
  assessment status and eligibility date; combined period upload including joiners.
- TPT (8): employee member number; combined period upload including joiners.
- Carey (9): separate enrolment and contribution files.
- Workers Pension Trust (8): combined period upload including joiners.
- Workplace Pension Trust (9): separate enrolment and contribution files.
- Workplace Pensions Advisory Service (8): combined upload including joiners.
- Other providers (9): optional employer/scheme codes; conditional employee group
  and assessment category; generic enrolment/contribution layouts require provider
  acceptance, not just a renamed NEST CSV.

Shared requirements: employer duties start, re-enrolment and postponement dates;
separate scheme/frequency setup; explicit tax relief and earnings basis; optional
AVCs; scheme defaults distinguished from effective-dated employee rates; percentage
or fixed amounts; exclusion evidence; joined/left/opted-in/opted-out dates; continued
assessment of entitled workers who join; re-enrolment decisions; reviewed letters
and delivery dates; title/payroll ID and provider identity validation before export.

Do not translate Moneysoft's product instructions into universal scheme rules:
their NEST AVC checkbox instruction does not prohibit additional NEST contributions.
Current NEST guidance permits additional contributions. Also its current payroll
guide treats some schedule dates as conditional identifiers. The existing SMRC
export still requires a payment due date; changing this requires serializer tests.
Verified primary references:
https://www.nestpensions.org.uk/schemeweb/memberhelpcentre/frequently-asked-questions.html
https://nestpensions.org.uk/schemeweb/dam/nestlibrary/employer-payroll-guide-PDF.pdf
https://www.thepensionsregulator.gov.uk/en/business-advisers/automatic-enrolment-guide-for-business-advisers/automatic-enrolment-earnings-threshold

ALGORITHM FOR COMPLETING MULTI-PROVIDER SUPPORT
1. Resolve employer, pay period, employment, effective scheme version and provider
   capability profile. Use versioned tax-year thresholds, not screen constants.
2. Assess age, verified State Pension date, working location and assessable earnings.
   Record category and evidence separately from membership status. Reassess relevant
   workers each period, including entitled workers who have joined.
3. Derive permitted actions from assessment, postponement and membership history:
   automatic enrolment, opt-in with request, joining, or continued assessment.
4. Store SchemeId/version and provider-specific member fields on effective-dated
   membership records. Apply employee contribution instructions from a reviewed
   effective pay date. Keep defaults separate from applied employee instructions.
5. Calculate contributions using scheme earnings definition, tax relief, effective
   employee rates/fixed amounts/extra contributions and payroll rounding rules.
   Preserve taxable/NI treatment, salary-sacrifice and family-leave exceptions.
6. Prepare letters from the event snapshot. Saving a letter and recording actual
   delivery remain separate actions. Retain the reviewed content and delivery evidence.
7. Finalise payroll and reconcile the contribution preview to immutable payroll
   snapshots. Explain missing identity, zero-pay and partial-period cases per worker.
8. Dispatch to a verified provider adapter: combined file or separate joiner and
   contribution files. Validate against the provider's current schema and examples.
   Keep the exported bytes and source versions; do not round-trip through Excel.
9. Track exported, submitted, accepted/rejected and paid independently. No export
   implies acceptance or payment. Corrections create a new auditable version.
10. Process opt-out versus cessation, reconciled refunds and re-enrolment eligibility
    with dates and evidence, preserving historical calculations.

REMAINING IMPLEMENTATION
Generalise PensionLifecycle.PayrollTreatment (currently fixes relief at source),
bind schemes and effective contribution instructions to PayrollCalculationInput,
replace hard-coded estimates/exports with provider adapters, add provider member
fields and a workforce assessment table, then implement PDF/letter previews using
the completed Reports styling. Verify each adapter against official provider specs.
Do not advertise these as implemented from the setup screen alone.

VERIFICATION
verification/PensionWorkspaceChecks: isolated SQLite fixtures, save/reload,
employer isolation, stale-write rejection, tax-relief/rate/reference validation,
eight provider setups, workflow capability gates, WPF renders at 1180 and 760px.
verification/PensionChecks: existing report integration, historical snapshots,
reconciliation rejection, pagination, totals and qualifying earnings.
Normal SMRC.Desktop build also required. Existing NU1903 warnings concern
System.Security.Cryptography.Xml 9.0.18 and are outside this UI change.

