cleanup phases 6
This commit is contained in:
hamid
@@ -0,0 +1,182 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user