# build-plan.md

> **Live roadmap.** Source of truth for "what's next." Aligned to the
> repo's `DEVELOPMENT_PLAN.md`. Update both when scope shifts.

---

## Sequenced phases

| # | Phase | Effort | Target | Status |
|---|---|---|---|---|
| 0 | Foundation — auth, tenancy, basic CRUD, MC engine v1 | L | shipped (SA) | ✅ DONE |
| 0b | Engine audit & realism fixes (sequence-of-returns, monthly cashflow, HMRC gross-up, shortfall failure) | M | shipped 05.07.3 | ✅ DONE |
| 0c | **UK fork** — SIPP/ISA/State Pension domain, HMRC tax, Stripe, UK GDPR, SEDOL, GBP, IA sectors, FTSE/ONS market data | M | shipped 2026.05.27.1 | ✅ DONE |
| 1 | **PDF report rewrite** — chart embed, full data, client-side download | S | shipped 05.08.x | ✅ DONE |
| 2 | **Strategy comparator** — top-performer query, switch model, side-by-side | M | 2026.06.10 | ⏳ NEXT |
| 3 | **Full UK asset catalogue** — LISA, DB pension income, annuity income, offshore bond, VCT | L | 2026.06.25 | 📋 PLANNED |
| 4 | **Retirement date + accumulation phase** | L | 2026.07.10 | 📋 PLANNED |
| 5 | **SIPP/ISA tax-free limits + Lump Sum Allowance enforcement** | M | 2026.07.25 | 📋 PLANNED |
| 6 | **Realism upgrades** — TER drag, parametric returns, correlation lock | M | 2026.08.10 | 📋 PLANNED |

**Effort key:** S = 1–2 days · M = 3–7 days · L = 1.5–3 weeks.

---

## What shipped in Phase 0c (UK fork)

**Goal:** Adapt the SA retirement engine for UK advisers, UK investment wrappers, and UK regulation.

| Area | What changed |
|---|---|
| **Domain assets** | `SippAsset`, `IsaAsset`, `WorkplacePensionAsset`, `StatePensionAsset` added |
| **Tax engine** | `HmrcTaxCalculator` (replaces `SarsTaxCalculator`); 2024/25 brackets seeded |
| **State Pension** | `StatePensionAsset` — income stream model; `ni_brackets`, `state_pension_rates` tables |
| **Market data** | FTSE All-Share, UK Gilts, SONIA, ONS CPI (2000–2024) seeded |
| **Schema** | `sedol` column, `price_gbp`, `ukgdpr_consent`, `stripe_sub_id`, `ni_number_enc` |
| **Billing** | `SubscriptionService` → Stripe (`stripe_sub_id`); `BillingController` rewritten |
| **Compliance** | UK GDPR throughout (consent, audit, ConsentWithdrawn event); FCA disclaimer in PDF |
| **Currency / locale** | GBP (£) throughout; `en-GB` locale; `COALESCE(price_gbp, price_zar, 0)` compat |
| **Fund identifiers** | SEDOL replaces JSE code; `COALESCE(sedol, jse_code)` compat pattern |
| **IA sectors** | IA sector classification replaces ASISA categories |
| **Views** | All public views updated: currency, consent labels, fund identifiers, market data |

---

## What's in Phase 2 (next up)

**Goal:** Adviser sees current vs proposed fund switches and the resulting success-rate delta.

| File | Status |
|---|---|
| `app/Strategy/StrategyAdvisor.php` | NEW — picks top performers, builds revised scenario |
| `app/Strategy/RevisedScenarioBuilder.php` | NEW — clones + swaps |
| `app/Repository/FundRepository.php` | UPDATE — add `topPerformers()` query (avg return × N years, TER tiebreak) |
| `app/Http/Controllers/StrategyController.php` | NEW — orchestrates baseline + revised sims |
| `public/views/scenarios/strategy.php` | NEW — side-by-side comparison |
| `routes/web.php` | UPDATE — `/scenarios/:id/strategy` route |
| `public/views/scenarios/show.php` | UPDATE — "View revised strategy" button |

**Quota:** 1 use per strategy comparison click.

**Edge cases handled:** assets without `fund_id`, funds with <3 years performance data, no better candidate, uplift below threshold.

---

## What's in Phase 3 (after)

**Goal:** Model real UK client portfolios including full asset catalogue.

New asset types:

| Type | Pre/Post | Liquidity | Tax | Notes |
|---|---|---|---|---|
| `lisa` | Pre | Locked → 60 (or first home) | 25% govt bonus; 25% penalty if withdrawn early | Lifetime ISA |
| `db_pension_income` | Post | Fixed income | HMRC Income Tax on income | Defined Benefit pension income stream |
| `annuity_income` | Post | Fixed income | HMRC Income Tax on income | Capital surrendered at purchase |
| `offshore_bond` | Both | Accessible | Chargeable events; 5% withdrawal allowance | Segments at assignment |
| `vct` | Both | Illiquid | 30% income tax relief; tax-free dividends | Venture Capital Trust |
| `money_market` | Both | Daily | Interest taxed as income (PSA: £500–£1,000) | Cash-like |
| `fixed_deposit` | Both | Locked term | Interest taxed as income | Known rate |

Schema additions: `maturity_date`, `interest_rate`, `vesting_date`, `tax_wrapper`, `monthly_contribution`.

---

## Phase 4 — retirement date + accumulation phase

Engine adds a pre-retirement loop:
1. Monthly contributions added to each asset.
2. Returns applied as today.
3. SIPP/workplace pension annual contribution limit (£60,000 or 100% of earnings) applied.
4. At retirement date, switches to drawdown mode (today's behaviour).

Schema: `clients.retirement_date`, `scenarios.retirement_date`, `scenarios.start_phase`, `assets.monthly_contribution`.

---

## Phase 5 — SIPP/ISA limits + Lump Sum Allowance

- Lump Sum Allowance (LSA): £268,275 tax-free PCLS cap across all pensions (post April 2024).
- ISA annual allowance tracking: £20,000/yr limit.
- SIPP minimum access age: enforce 57 (from 2028) when retirement date crosses the threshold.
- HMRC bracket inflation across simulation years (Phase 5: inflate brackets by CPI annually).
- NI qualifying year deficit warning in PDF.

---

## Phases 6

See `DEVELOPMENT_PLAN.md` in the repo for full detail. Summary:
- **6:** TER drag per asset per year, optional parametric forward-looking returns, correlation lock
  when assets carry their own `fundReturns`, HMRC bracket inflation across simulation years.

---

## Workflow per phase

1. Update `DEVELOPMENT_PLAN.md` with the scope + estimate.
2. Implement in `C:\Users\User\OneDrive\Developments 2026\Claude\retireuk.costusworx.co.za`.
3. Bump version in `config/version.php` and `public/assets/js/app.js`.
4. Write/refresh `DEPLOY_NOW.md` with file list + smoke tests + rollback.
5. Mirror status updates here (this file) and in `changelog.md`.
6. Upload via cPanel File Manager (no CI yet — see `deployment.md`).