baya-monorepo/docs/_plan/phase-5-roadmap.md

# 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

_(filled in by the agent that runs this phase)_