baya-monorepo/archive/clarify-chain/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

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 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, 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/BL-002) 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.