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 ✅ Complete (May 23, 2026)

- [x] Auth forms migrated to `Input`/`Button`/`Card`/`AlertBanner` (commits `9c65899`, `30a30ce`)
- [x] Settings page (profile, appearance, password, MCP, API tokens, danger zone, offline queue, feedback) migrated (commit `30a30ce`)
- [x] CreateNoteModal, LinkNoteModal, ShareDialog, CreateWorkspaceModal, PromptTemplateEditor migrated (commits `30a30ce`, `2408f43`)
- [x] Web typecheck, 96/96 vitest, Playwright release-flows all green

---

## Sprint 4 — UI6: Search, Workspaces, Dashboard ✅ Complete (May 23, 2026)

- [x] Dashboard page migrated to `Card` + `Badge` (commit `8d484c3`)
- [x] Workspaces list page migrated (commit `8d484c3`)
- [x] Search page migrated (commit `8d484c3`)
- [x] Chat page migrated to `Select` + `Textarea` (commit `8d484c3`)
- [x] Web vitest + visual specs green

---

## Sprint 5 — UI7 + UI8: Notes, Smart Actions, Legacy Cleanup ✅ Complete (May 23, 2026)

- [x] Note detail page migrated, Smart Actions panel migrated, NoteEditor shell migrated (commits `2408f43`, `3288e28`)
- [x] Palace page + PalacePanel, MemoryTimeline, KnowledgeGraphView migrated (commit `3288e28`)
- [x] Gaps page, prompts page, landing page, public share page, BroadcastBanner migrated (commit `3288e28`)
- [x] `.surface-card`, `.surface-muted`, `.badge`, `.input-shell` removed from `web/src/app/globals.css` (commit `0c982de`)
- [x] UI drift ratchet now enforces 0 for legacy classes / hardcoded colors / direct `@bytelyst/ui` imports outside adapter in CI
- [x] Audit regex refined so Tailwind arbitrary-value references (`bg-[color:var(--nl-surface-muted)]`) are not flagged
- [x] Final cumulative impact across UI5–UI8: raw controls 38 → 14 (–24); legacy classes 92 → 0 (−100%)

---

## Sprint 6 — Production Hardening ✅ Substantially Complete (May 23, 2026 audit)

- [x] **Backend config fail-closed in production** — `backend/src/lib/config.ts` superRefine() rejects production environments that use the dev JWT secret, JWT secret shorter than 32 chars, `DB_PROVIDER=memory`, missing Cosmos credentials, disabled field encryption, or `memory` key provider for field encryption. (already shipped before this sprint)
- [x] **Backend logging clean** — audit `grep -rnE "process\.(stdout|stderr)|console\.(log|error|warn|info)" backend/src --include="*.ts"` returns zero matches outside tests. All logging via `req.log` / `app.log`. (already shipped)
- [x] **CI: mobile + web E2E + Docker build** — `.github/workflows/ci.yml` already has dedicated jobs: `mobile` (lint+typecheck+test), `web-e2e` (Playwright), `docker-build` (backend + web images), `backend-cosmos` (emulator smoke), plus `release-guards` (ratchet + secrets).
- [x] **Docker compose smoke** — `scripts/e2e-docker-test.sh` + `scripts/e2e-docker-seed.sh` exercise login / CORS / workspace+note CRUD lifecycle against the deployed compose stack. Runs locally on Docker-capable hosts via `pnpm run e2e:docker:test`.
- [x] **Shared service smoke** — deployed compose stack via `docker-compose.override.yml` now points the backend at the sibling `platform-service` (4003), `extraction-service` (4005), and `mcp-server` (4007). Verified at http://localhost:3050 (web) and http://localhost:4016 (backend) returning 200.
- [ ] **Stale doc cleanup** — reconcile AGENTS.md, README, and older gap docs against current reality (deferred; non-blocking).

---

## 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
```