From 6be7ee470fe6e62b30c317fbfc40a551b3788014 Mon Sep 17 00:00:00 2001
From: Saravana Achu Mac <saravanakumardb1@gmail.com>
Date: Sun, 29 Mar 2026 19:21:29 -0700
Subject: [PATCH] docs: add agent task roadmap for delegated execution

Systematic review identified 28 tasks across 6 phases covering
auth UI, backend hardening, web UX polish, MCP wiring, and DevOps.

Made-with: Cursor
---
 docs/AGENT_TASK_ROADMAP.md | 239 +++++++++++++++++++++++++++++++++++++
 1 file changed, 239 insertions(+)
 create mode 100644 docs/AGENT_TASK_ROADMAP.md

diff --git a/docs/AGENT_TASK_ROADMAP.md b/docs/AGENT_TASK_ROADMAP.md
new file mode 100644
index 0000000..e1003fc
--- /dev/null
+++ b/docs/AGENT_TASK_ROADMAP.md
@@ -0,0 +1,239 @@
+# NoteLett — Agent Task Roadmap
+
+**Date:** March 29, 2026
+**Product:** NoteLett (`notelett`) — Structured notes for humans + AI agents
+**Repo:** `learning_ai_notes`
+**Stack:** Fastify 5 backend (port 4016) · Next.js 16 web (port 3000) · Expo mobile
+**Platform deps:** 23 `@bytelyst/*` packages (all resolve against `learning_ai_common_plat`)
+
+---
+
+## Current State
+
+| Surface | Routes / Modules | Tests | Build | Platform Pkgs |
+|---------|-----------------|-------|-------|---------------|
+| **Backend** | 7 modules, ~32 endpoints, 8 MCP tools | 20 files (unit + integration) | ✅ tsc | 13 (all used) |
+| **Web** | 6 pages, 13 components, 15 lib files | 7 unit + 7 E2E | ✅ next build | 10 (all used) |
+| **Mobile** | 4 tabs, note detail, auth, 5 stores | 23 tests (4 files) | ✅ typecheck | — |
+
+All `@bytelyst/*` dependencies exist in `learning_ai_common_plat` and resolve correctly.
+
+---
+
+## Phase 1 — Critical Web Gaps
+
+These block the web app from being usable by real users.
+
+- [ ] **1.1** Add auth pages — login, register, forgot-password
+  - Create `web/src/app/(auth)/login/page.tsx`, `register/page.tsx`, `forgot-password/page.tsx`
+  - Wire to existing `@bytelyst/react-auth` config in `web/src/lib/auth.ts`
+  - Include form validation, error states, loading states
+  - Files: new pages under `web/src/app/(auth)/`
+
+- [ ] **1.2** Add `middleware.ts` for route protection
+  - Redirect unauthenticated users from `(app)/*` routes to `/login`
+  - Redirect authenticated users from `/login` to `/dashboard`
+  - Check kill-switch status (call `checkKillSwitch()` from `web/src/lib/kill-switch.ts`)
+  - File: `web/src/middleware.ts`
+
+- [ ] **1.3** Replace plain textarea with a rich note editor
+  - Current `NoteEditor.tsx` is a bare `<textarea>` — inadequate for a notes product
+  - Add markdown support (headings, bold, italic, lists, code blocks) at minimum
+  - Consider Tiptap, Lexical, or MDXEditor
+  - File: `web/src/components/NoteEditor.tsx`
+
+- [ ] **1.4** Add workspace CRUD from web
+  - Backend already has `POST /workspaces` and `PATCH /workspaces/:id`
+  - Add create-workspace modal/form on the workspaces page
+  - Add edit/delete actions on workspace cards
+  - Files: `web/src/app/(app)/workspaces/page.tsx`, new modal component
+
+- [ ] **1.5** Wire toast notifications
+  - `ToastProvider` from `@bytelyst/ui` is mounted but zero toasts are triggered
+  - Replace `window.confirm()` calls with a confirmation dialog component
+  - Add success/error toasts after note create, update, archive, link, task create, artifact create
+  - Files: all page files + components that do mutations
+
+**Verification:**
+```
+cd web && pnpm run typecheck && pnpm test && pnpm run build
+```
+
+---
+
+## Phase 2 — Backend Hardening
+
+- [ ] **2.1** Add integration tests for all route modules using `buildTestApp()` + Fastify `.inject()`
+  - Current route tests only check handler registration counts
+  - Need real request/response tests: happy path, validation errors, auth enforcement, 404s
+  - Modules needing inject tests: notes, workspaces, note-relationships, note-tasks, note-artifacts, note-agent-actions, saved-views
+  - Files: `backend/src/modules/*/routes.integration.test.ts` (7 new files)
+
+- [ ] **2.2** Add DELETE endpoints for notes, workspaces, tasks, artifacts, relationships
+  - Currently only saved-views has DELETE
+  - Notes support archive but not hard delete — add soft-delete with a `deletedAt` timestamp
+  - Files: `backend/src/modules/*/routes.ts` + `repository.ts`
+
+- [ ] **2.3** Enforce role-based access on REST routes
+  - `requireRole` is exported and tested but not used on any REST route
+  - At minimum: write routes (POST/PATCH/DELETE) should require `editor` or `admin` role
+  - File: every `routes.ts` file
+
+- [ ] **2.4** Enforce workspace member authorization
+  - `workspace.members` array is stored but never checked
+  - Note CRUD should verify the requesting user is a member of the target workspace
+  - Files: `backend/src/modules/notes/routes.ts`, `backend/src/modules/workspaces/repository.ts`
+
+- [ ] **2.5** Activate telemetry — call `trackEvent()` on key business actions
+  - Buffer and flush infrastructure exist but no route handler actually calls `trackEvent()`
+  - Track: note.created, note.updated, note.archived, note.searched, workspace.created, agentAction.approved, agentAction.rejected
+  - Files: all `routes.ts` files + `backend/src/lib/telemetry.ts`
+
+- [ ] **2.6** Activate feature flags in route logic
+  - 6 flags registered with defaults but no route checks `isFeatureEnabled()`
+  - At minimum: gate MCP write tools behind `mcp.enabled`, gate export behind a flag
+  - Files: `backend/src/lib/feature-flags.ts`, relevant route files
+
+**Verification:**
+```
+cd backend && pnpm run typecheck && pnpm test
+```
+
+---
+
+## Phase 3 — Web UX Polish
+
+- [ ] **3.1** Add pagination to all list views
+  - Backend already returns `total`, `limit`, `offset` — web ignores them and fetches everything
+  - Add pagination controls to: notes list, workspaces list, search results, review queue, saved views
+  - Files: all page files under `web/src/app/(app)/`
+
+- [ ] **3.2** Fix `getNoteDetail` — use `GET /notes/:id` instead of fetching all notes
+  - File: `web/src/lib/notes-client.ts` line ~291
+
+- [ ] **3.3** Fix `listApprovalQueue` N+1 — add backend cross-workspace pending-actions endpoint
+  - Currently fetches all workspaces, then all actions per workspace
+  - Add `GET /note-agent-actions/pending` (already exists) usage in web client
+  - Files: `web/src/lib/review-client.ts`
+
+- [ ] **3.4** Add skeleton loading states per section (not just global spinner)
+  - File: new `Skeleton.tsx` component + integration in each page
+
+- [ ] **3.5** Add file upload UI for artifacts
+  - `blob-client.ts` supports `uploadArtifact()` but no component triggers it
+  - Add file picker + upload progress to ArtifactPanel
+  - File: `web/src/components/ArtifactPanel.tsx`
+
+- [ ] **3.6** Remove dead code
+  - Delete `web/src/lib/mock-data.ts` (228 lines, zero imports)
+  - Delete `web/src/lib/review-data.ts` (46 lines, zero imports)
+  - Remove `zustand` and `zod` from web `package.json` (declared, never imported)
+
+- [ ] **3.7** Fix SSR crash risk — lazy-init module-scope API clients
+  - `extraction-client.ts` and `blob-client.ts` instantiate clients at module scope
+  - Apply lazy singleton pattern (init on first call, not on import)
+  - Add `"use client"` to `notes-client.ts` or refactor extraction-client
+  - Files: `web/src/lib/extraction-client.ts`, `web/src/lib/blob-client.ts`, `web/src/lib/notes-client.ts`
+
+- [ ] **3.8** Consolidate duplicate type definitions
+  - `NoteAgentActionDoc`, `NoteDoc`, etc. duplicated across `notes-client.ts`, `review-client.ts`, `extraction-client.ts`
+  - Move to `web/src/lib/types.ts` and import from there
+  - Files: `web/src/lib/types.ts` + all client files
+
+**Verification:**
+```
+cd web && pnpm run typecheck && pnpm test && pnpm run build
+```
+
+---
+
+## Phase 4 — MCP & AI Enrichment
+
+- [ ] **4.1** Wire MCP tool registration to shared `mcp-server`
+  - `MCP_SERVER_URL=http://localhost:4007` is configured but no outbound call exists
+  - Backend exposes tools via `register-note-tools.ts` — need HTTP client to register them with the shared MCP server at startup
+  - File: `backend/src/server.ts` or new `backend/src/lib/mcp-registration.ts`
+
+- [ ] **4.2** Add note summarization to web UI
+  - Backend `POST /notes/:id/summarize` already works via extraction-service
+  - Add "Summarize" button to note detail page that calls the endpoint and shows the result
+  - Files: `web/src/app/(app)/notes/[noteId]/page.tsx`, `web/src/lib/notes-client.ts`
+
+- [ ] **4.3** Add note export UI
+  - Backend `GET /notes/export` already supports JSON and Markdown formats
+  - Add "Export" button to dashboard or workspace pages
+  - Files: `web/src/app/(app)/dashboard/page.tsx` or workspaces page
+
+**Verification:**
+```
+cd backend && pnpm run typecheck && pnpm test
+cd web && pnpm run typecheck && pnpm test && pnpm run build
+```
+
+---
+
+## Phase 5 — DevOps & CI
+
+- [ ] **5.1** Enable CI workflow
+  - `.github/workflows/ci.yml.disabled` exists and is fully written
+  - Review, update if needed, rename to `ci.yml`
+  - File: `.github/workflows/ci.yml`
+
+- [ ] **5.2** Fix Docker Compose platform-service reference
+  - `docker-compose.yml` references `localhost:4003` and `localhost:4005` but doesn't define those services
+  - Either add `platform-service` and `extraction-service` as services, or document that they must be run separately
+  - File: `docker-compose.yml`
+
+- [ ] **5.3** Add `.env.example` missing variables
+  - `NEXT_PUBLIC_EXTRACTION_SERVICE_URL` and `NEXT_PUBLIC_PLATFORM_SERVICE_ORIGIN` are used in code but missing from `.env.example`
+  - File: `web/.env.example`
+
+**Verification:**
+```
+docker compose build
+docker compose up -d && curl http://localhost:4016/api/bootstrap
+```
+
+---
+
+## Phase 6 — Docs Alignment
+
+- [ ] **6.1** Update `docs/ROADMAP.md` phase checklists
+  - Many Phase 0–3 items remain unchecked despite being implemented (per progress notes in §8)
+  - File: `docs/ROADMAP.md`
+
+- [ ] **6.2** Update `AGENTS.md` with current test counts and any new endpoints added in this roadmap
+
+- [ ] **6.3** Update `README.md` with current quick-start that reflects real auth and data flow
+
+---
+
+## Task Summary
+
+| Phase | Tasks | Priority | Est. Effort |
+|-------|-------|----------|-------------|
+| 1 — Critical Web Gaps | 5 | HIGH | 6–8 hours |
+| 2 — Backend Hardening | 6 | HIGH | 5–7 hours |
+| 3 — Web UX Polish | 8 | MEDIUM | 4–6 hours |
+| 4 — MCP & AI | 3 | MEDIUM | 2–3 hours |
+| 5 — DevOps & CI | 3 | MEDIUM | 1–2 hours |
+| 6 — Docs | 3 | LOW | 1 hour |
+| **Total** | **28** | | **19–27 hours** |
+
+---
+
+## Verification Commands (run after each phase)
+
+```bash
+# Backend
+cd backend && pnpm run typecheck && pnpm test && pnpm run build
+
+# Web
+cd web && pnpm run typecheck && pnpm test && pnpm run build
+
+# Mobile
+cd mobile && pnpm run typecheck && pnpm test
+
+# E2E
+cd web && pnpm exec playwright test
+```