# Phase 5 — Roadmap & technical requirements **Depends on:** Phase 4 · **Size:** one session ## Goal Answer "what next?" — recording every already-decided future item **and** proposing a sequenced order, with the technical prerequisites each step needs. The ordering is a proposal you can overrule; the recording is not negotiable. --- ## Inputs - `docs/status/backlog.md` and `implemented.md` — Phase 4's output, the ground truth - `docs/flows/index.md` — what's mocked vs built - The **deferrals with pull-triggers** from the STATUS logs: Elasticsearch `INurseSearch`, real SMS/push `INotificationDispatcher`, the analytics pipeline, the holiday feed, **8 unbuilt product tables**, and the refinement-phase-9 items 9.7–9.11 - [product/notes/future-ideas.md](../../product/notes/future-ideas.md) and [open-questions.md](../../product/notes/open-questions.md) — including PWA/Workbox caching - ui-phase-13's follow-ups: **tier (c)** — guest search + public nurse profiles (REQ-066/067), blocked on a backend phase **and an explicit privacy sign-off on the nurse-profile field list**; the OG image Persian variant - Root [CLAUDE.md](../../CLAUDE.md) §6 + [DEPLOY.md](../../DEPLOY.md) "Going to Production" — the credential-rotation obligation - `product/business/*` — anything specified but never built - `product/research/*` — go-to-market, legal landscape (informs sequencing, not scope) ## Outputs ``` docs/roadmap/ index.md the proposed sequence + the reasoning, in one page next-up.md the next 3-5 units of work, each spec'd enough to start deferred.md recorded, with the trigger that pulls each one forward tech-debt.md what must be paid before scale, and what it costs to defer pre-launch.md the hard gate before real users touch this ``` --- ## Steps ### 1. `pre-launch.md` first — it's the one with a deadline Everything that must be true before a real user with real money uses the platform. Known already: - **Rotate the committed credentials** and move the secret half out of git. The repo currently contains live credentials by deliberate pre-launch decision. Note the exception: `Seams:FieldEncryption:Key` / `:HashKey` decrypt existing PII and derive the phone-lookup hash — rotating those requires a data migration, not a config edit. Spell out that migration as its own item. - **Real external rails** — which seams are still mocked in production config (payment gateway, SMS, BNPL provider, object storage). Phase 3's mock-vs-real map is the input; this is the list of seams that must flip. - **Running as Development in production** — `DEPLOY.md` documents this as a deliberate trade. State what it implies (gRPC reflection, dev endpoints such as `/dev/last_otp`, seeding behaviour, log verbosity) and what must change. - Anything Phase 4 marked `blocker`. - Legal/tax items from `product/business/13-tax-invoicing-and-legal.md` that are code-side. Each item: what, why it blocks launch, roughly what it takes. ### 2. `deferred.md` — record faithfully, don't re-decide One row per deferral: **item · why deferred · the pull-trigger (the condition that makes it necessary) · rough size · where it was decided**. The pull-triggers already exist in the STATUS logs — preserve them verbatim in substance. A deferral with a trigger is a decision; a deferral without one is just a forgotten task, so any you find without a trigger, give one. Include the 8 unbuilt product tables, named individually. ### 3. `tech-debt.md` Debt is different from backlog: it doesn't block a flow, it raises the cost of everything after it. Candidates to assess: the single-instance in-process scheduler; search without Elasticsearch; the absence of E2E tests over the money paths; the remaining raw-state forms; the Windows-generated client lockfile wrinkle in `DEPLOY.md`; test coverage asymmetry between the two projects. For each: what it costs now, what it costs at 10× usage, and the trigger to pay it. ### 4. `next-up.md` — the opinionated part Three to five units of work, each with: goal, why now, what it unblocks, technical prerequisites, affected flows, rough size, and the backlog ids it closes. Enough that a fresh agent session could start one without re-deriving the context. **Sequencing principle to apply, and state explicitly in `index.md`:** the product's own promise is trust-first and money-holding. So the order is (1) anything that makes a *money or trust* flow lie to a user, (2) anything that makes a built flow unusable, (3) anything that makes a mocked flow real, (4) new surface area. Tier (c) guest search is new surface — it ranks below making the authenticated flows honest, regardless of how visible it is. Where a proposed item conflicts with something in `product/`, say so and defer to `product/`. ### 5. `index.md` The one-page sequence: a table of the proposed order with rationale per step, plus the standing answer to "what are we not doing, and why" (a pointer to `deferred.md`). Mark clearly which parts are **recorded decisions** and which are **this document's proposal** — the reader must be able to tell your judgement from the project's. --- ## Verification - [ ] Every `deferred` item in `docs/status/backlog.md` appears in `deferred.md` with a trigger. - [ ] Every recorded deferral from the STATUS logs is present, including the 8 unbuilt tables. - [ ] `pre-launch.md` covers credential rotation, every still-mocked production seam, and the Development-in-production trade. - [ ] Every `next-up.md` item names the backlog ids it closes and the flows it affects. - [ ] Proposal is visibly distinguished from record. ## Definition of done You can pick the next piece of work in five minutes, and you can explain to someone else why it's that piece and not another. ## Handoff **Done 2026-08-02 against `cd8144e`, in one session, single agent (no subagent fan-out needed — the inputs were five already-triaged status files plus a handful of small product docs, not a fresh harvest).** ### What was produced `docs/roadmap/` — `pre-launch.md`, `deferred.md`, `tech-debt.md`, `next-up.md`, `index.md`. All five verification checklist items pass: every deferred item in `backlog.md` (51 total — the labeled 43 plus 8 more filed by severity elsewhere that also carry deferred status) appears in `deferred.md` with its trigger preserved in substance; all 8 unbuilt product tables are named individually; `pre-launch.md` covers credential rotation, all 11 still-mocked production rails, and the Development-in-production trade; every `next-up.md` unit names the backlog ids it closes and the flows it affects; proposal is labeled apart from record throughout (index.md marks each claim **recorded** or **this phase's proposal** explicitly). ### How it was verified Read `backlog.md`, `implemented.md`, `decisions.md`, and `backlog-closed.md` in full (not sampled) since `next-up.md`/`deferred.md`/`pre-launch.md` all need to cite exact `BL-###` ids. Cross-checked the phase brief's tech-debt candidates against the actual code rather than restating them: **two turned out overstated.** "Absence of E2E tests over the money paths" — false as stated; `Baya.Test.Api` and `Baya.Test.Foundation` carry ~119 test files with real WebApplicationFactory integration coverage over Payments/Bookings/BNPL/ Payouts/Refunds. The real gap, confirmed by grepping for Playwright/Cypress in `client/package.json` (none), is that nothing automated drives a real browser against a real API — a narrower, more precise claim than the brief's. "Test coverage asymmetry" — also not a raw-count gap (119 server files vs 125 client files); the actual asymmetry is that `docs/rules/server/cqrs.md` makes testing mandatory for every new feature while root `CLAUDE.md`'s client gate is reactive ("if you touched a tested component"). Both corrected in [tech-debt.md](../roadmap/tech-debt.md) rather than carried forward as-stated. One new debt item was found and added that the brief didn't name: no OpenAPI→TypeScript codegen pipeline exists (confirmed absent by grep), which is the mechanism that would have caught the client/server DTO drifts phases 2 and 3 had to discover by hand. One deferred item, [BL-245](../status/backlog.md#deferred-43), carried its own trigger — "phase 5 verification pass" — naming this phase directly. Rather than deferring it again, it was executed: grepped the server for `SuspendNurse`/`ResolveSupportAlert`/`FlagConcern`. Two of three are real and code-traced (`ResolveSupportAlert` + `AssignSupportAlert` in `SupportAlertsController.cs`; nurse suspension as `AdminSuspendVerificationCommand`); only `FlagConcern` is genuinely absent. Corrected in place in `backlog.md` and logged in `decisions.md`, both outside this phase's own output folder — a deliberate, narrow exception to "stay in your own phase's files," made because the alternative was knowingly publishing a roadmap that cites a stale row its own source phase had flagged as needing exactly this check. ### The sequencing call worth flagging Applying the brief's stated principle (money/trust lies > unusable > mocked→real > new surface) literally puts admin RBAC ([BL-001](../status/backlog.md#blockers-18)/[BL-002](../status/backlog.md#blockers-18)) third in `next-up.md`, behind two smaller truth-fixes (nurse-verification status, checkout/payment-window honesty) — even though RBAC has zero prerequisites of its own and unblocks the most downstream work of anything in the backlog (11 of 14 business areas). `next-up.md` and `index.md` both say this outright rather than quietly picking one reading: the ranking follows the letter of the stated principle, and a reader who'd rather optimize for unlock-radius should run unit 3 first. Two more mocked domains that are just as legitimate as the four chosen (patient/care-records, partner-center) didn't fit the 3-5 slot cap and are named explicitly as next-in-line rather than silently dropped. ### What was left undone, and why - **Patient/care-records and partner-center de-mocks are not among the 5 `next-up.md` units** — both are real candidates (see above), left out only by the slot cap, not by judgment that they matter less. - **No code was written or changed** — pure roadmap synthesis, as scoped. The one exception is the BL-245 correction above, which is a fact-check, not a feature. - **This phase did not re-audit `product/business/*` line by line for "specified but never built" beyond what `backlog.md`'s Deferred section already carries** — a grep for `DEFERRED` across all 14 business docs confirmed every theme they name (the 8 tables, holiday/surge pricing, GPS discovery, double-blind reviews, tiered commission, organizations, etc.) already has a `BL-###` home. Re-deriving that reconciliation from scratch would have been redoing phase 4's job, not phase 5's.