learning_ai_notes/docs/NEXT_SPRINT_ROADMAP.md

# NoteLett — Next Sprint Roadmap

> **Date:** May 22, 2026 (refreshed)
> **Last verified commit:** Sprint A workspace-path fix (pending) — `pnpm run verify` passes end-to-end (backend 373/373, web 96/96, mobile 97/97).
> **Context:** Core product (Phases 0–4) is complete. UI/UX migration (UI0–UI4) is done. Sprint A restored the green build after the May 12 Docker/UI regression. Remaining work is UI5–UI8 migration plus production-hardening.

---

## Current State

### Product Phases

| Phase | Status | Summary |
|-------|--------|---------|
| **Phase 0** | ✅ Complete | Foundations, identity, repo structure |
| **Phase 1** | ✅ Complete | Core skeleton — web, backend, mobile auth + CRUD |
| **Phase 2** | ✅ Complete | Notes MVP — relationships, tasks, artifacts, agent actions |
| **Phase 3** | ✅ Complete | Agentic layer — 8 MCP tools, approval/audit, extraction |
| **Phase 4** | ✅ Complete | Search + knowledge — saved views, Palace, RAG scoping |
| **Phase 5** | ✅ Re-verified | Production readiness — `pnpm run verify` green after Sprint A workspace-path repair |

### UI/UX Migration

| Phase | Status | Summary |
|-------|--------|---------|
| **UI0** | ✅ Complete | Baseline audit + rules |
| **UI1** | ✅ Complete | Common-platform core UI hardened |
| **UI2** | ✅ Complete | NoteLett UI adapter expanded |
| **UI3** | ✅ Complete | Review UX migrated to platform primitives |
| **UI4** | ✅ Complete | App shell + navigation migrated |
| **UI5** | ❌ Not started | Forms, modals, settings |
| **UI6** | ❌ Not started | Search, workspaces, dashboard |
| **UI7** | ❌ Not started | Notes, Smart Actions, Palace |
| **UI8** | ❌ Not started | Remove legacy globals |

### Production Readiness (refreshed May 22, 2026 after Sprint A)

| Check | Status |
|-------|--------|
| Backend typecheck | ✅ Pass |
| Backend build | ✅ Pass |
| Backend tests | ✅ 373/373 pass (54 files) |
| Backend lint | ✅ 0 errors, 14 warnings |
| Web typecheck | ✅ Pass |
| Web build | ✅ Pass |
| Web tests | ✅ 96/96 pass (22 files) |
| Web lint | ✅ 0 errors, 23 warnings (React-compiler advisories) |
| Mobile typecheck | ✅ Pass |
| Mobile tests | ✅ 97/97 pass (25 files) |
| Mobile lint | ✅ 0 errors, 30 warnings |
| Release-guard audit | ✅ Secret scan + color/token audit pass |
| Docker compose smoke | ⏸ Deferred — no Docker runtime on this host |
| Shared-service live smoke | ⏸ Deferred — needs running platform-service/extraction-service/mcp-server + Cosmos creds |

### Sprint A (May 22, 2026) — Build Restoration

Sprint A resolved the May 12 regression. Root cause: `pnpm-workspace.yaml` referenced a sibling path (`../learning_ai/learning_ai_common_plat/...`) that did not exist on dev/CI hosts. `.pnpmfile.cjs` fell back to `../learning_ai_common_plat` for some packages but missed others, so `@bytelyst/ui` came from a stale Gitea 0.1.0 tarball with no exports (breaking web typecheck + 26 tests) and `@bytelyst/monitoring` failed to install entirely (breaking backend typecheck + 2 test suites).

Fix:
- `pnpm-workspace.yaml` now references `../learning_ai_common_plat/packages/*` directly.
- `.pnpmfile.cjs` swaps `DEFAULT_COMMON_PLAT_ROOT` and `LEGACY_COMMON_PLAT_ROOT` so the canonical path is the default and the older nested path is the fallback.
- Clean reinstall regenerated `pnpm-lock.yaml` with `@bytelyst/ui@0.1.9` and `@bytelyst/monitoring@0.1.5` linked to the local checkout.

Verification: `pnpm run verify` end-to-end, plus backend/web/mobile lint and `pnpm run audit:release-guards`.

---

## Sprint 1 — Fix Backend Build ✅ Resolved by Sprint A

Original failure was misattributed to Palace/LLM API drift. Actual cause was workspace-path drift causing `@bytelyst/monitoring` to be missing from `backend/node_modules`. Once the workspace path was corrected, backend typecheck, build, lint, and all 373 tests pass without code changes to the Palace/LLM modules.

---

## Sprint 2 — Fix Web + Mobile Lint ✅ Resolved by Sprint A

Web lint now exits 0 (23 advisory warnings retained). Mobile lint exits 0 (30 advisory warnings retained). `@bytelyst/billing-client` resolves correctly once the workspace path is canonical. Driving remaining advisory warnings to zero is tracked under Sprint 6 / Q1 tech-debt.

---

## Sprint 3 — UI5: Forms, Modals, Settings (~2 days)

> **Why next:** Highest-value remaining UI migration. Auth/settings flows are user-facing and currently use raw HTML elements.

### 3.1 — Auth Forms

- [ ] Migrate login/register/forgot-password to common `Input`, `Label`, `Button`, `Card`
- [ ] Ensure accessibility labels on all form elements

### 3.2 — Settings Forms

- [ ] Migrate settings forms to `Field`, `Input`, `Textarea`, `Select`, `Switch`, `ConfirmDialog`
- [ ] Use common-platform form primitives from `@bytelyst/ui`

### 3.3 — Create/Link/Share Modals

- [ ] Migrate `CreateNoteModal`, `LinkNoteModal`, `ShareDialog` to common `Modal` + form primitives
- [ ] Action bars and button groups via platform components

### Exit Criteria

- [ ] All auth/settings/modal screens use platform UI primitives
- [ ] No raw `<button>`, `<input>`, `<textarea>`, `<select>` in migrated screens
- [ ] Playwright release-flow specs pass
- [ ] Web typecheck + tests pass

---

## Sprint 4 — UI6: Search, Workspaces, Dashboard (~2 days)

### 4.1 — Search Page

- [ ] Replace saved-search/result cards with `Panel`, `DataList`, `Badge`, `EmptyState`
- [ ] Replace filter chips with `StatusBadge` or `FilterChip`

### 4.2 — Workspaces Page

- [ ] Workspace cards → `Panel` + `Badge` + `StatCard`
- [ ] Filter bar → common filter components

### 4.3 — Dashboard

- [ ] Metric cards → `StatCard`, recent notes → `DataList`
- [ ] Two-column layout → reusable adapter primitive

### Exit Criteria

- [ ] Dashboard, search, workspaces all use platform primitives
- [ ] Responsive visual checks pass (desktop + mobile widths)
- [ ] All tests pass

---

## Sprint 5 — UI7 + UI8: Notes, Smart Actions, Legacy Cleanup (~2.5 days)

### 5.1 — Note Detail Shell

- [ ] Keep rich editor local, replace shell/toolbar/popover with common primitives
- [ ] Migrate Smart Actions cards/buttons/result panels

### 5.2 — Palace Panels

- [ ] Migrate Palace panels to common panel/list/form primitives
- [ ] Keep domain rendering local

### 5.3 — Remove Legacy Globals (UI8)

- [ ] Remove `.surface-card`, `.surface-muted`, `.badge`, `.input-shell` globals
- [ ] Add CI guard: `pnpm run audit:ui:strict`
- [ ] Verify full E2E + visual smoke

### Exit Criteria

- [ ] `pnpm run audit:ui:strict` passes (no raw controls, no legacy globals, no hardcoded colors)
- [ ] Full web test/typecheck/lint/E2E pass

---

## Sprint 6 (Future) — Production Hardening

> **After UI migration is complete.**

- [ ] Backend config: fail-closed in production (no dev defaults)
- [ ] Backend logging: replace any remaining `process.stdout/stderr` with `app.log`
- [ ] CI: add mobile tests, web E2E, Docker build check
- [ ] Shared service smoke: platform-service, extraction-service, mcp-server
- [ ] Docker compose smoke on Docker-capable host
- [ ] Stale doc cleanup (reconcile AGENTS.md, README, older gap docs)

---

## Total Estimated Effort

| Sprint | Effort | Focus |
|--------|--------|-------|
| Sprint 1 | ~2 days | Fix backend build (Palace/LLM drift) |
| Sprint 2 | ~1 day | Fix all lint (backend/web/mobile) |
| Sprint 3 | ~2 days | UI5 — forms, modals, settings |
| Sprint 4 | ~2 days | UI6 — search, workspaces, dashboard |
| Sprint 5 | ~2.5 days | UI7 + UI8 — notes, Smart Actions, legacy cleanup |
| Sprint 6 | ~2 days | Production hardening (future) |
| **Total** | **~11.5 days** | |

---

## Verification Commands

```bash
# Full verification
pnpm run verify

# Per-workspace
pnpm --filter @notelett/backend run typecheck
pnpm --filter @notelett/backend run build
pnpm --filter @notelett/backend run test
pnpm --filter @notelett/backend run lint
pnpm --filter @notelett/web run typecheck
pnpm --filter @notelett/web run build
pnpm --filter @notelett/web run test
pnpm --filter @notelett/web run lint
pnpm --filter @notelett/mobile run typecheck
pnpm --filter @notelett/mobile run lint

# UI audit
pnpm run audit:ui
pnpm run audit:ui:strict  # after UI8

# E2E
pnpm --filter @notelett/web exec playwright test e2e/release-flows.spec.ts --reporter=list --workers=1
```