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 and 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 §6 + 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)