From f308a362fd1fdf69d019245c2cfb1696067d3016 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Sun, 29 Mar 2026 19:25:38 -0700 Subject: [PATCH] fix(docs): correct agent task roadmap after codebase verification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Phase 0: 5 backend @bytelyst/* packages missing from common_plat (backend-config, backend-flags, backend-telemetry, fastify-auth, field-encrypt) — shared blocker with NomGap - Remove dead-code deletion task: mock-data.ts and review-data.ts already do not exist - Flag stale .env.example product identity (agentic-notes → notelett) - Note that Gitea CI is already active alongside disabled GitHub CI - Update task counts (28 → 32) and effort estimates Made-with: Cursor --- docs/AGENT_TASK_ROADMAP.md | 64 +++++++++++++++++++++++++++++--------- 1 file changed, 50 insertions(+), 14 deletions(-) diff --git a/docs/AGENT_TASK_ROADMAP.md b/docs/AGENT_TASK_ROADMAP.md index e1003fc..89847f8 100644 --- a/docs/AGENT_TASK_ROADMAP.md +++ b/docs/AGENT_TASK_ROADMAP.md @@ -12,11 +12,45 @@ | Surface | Routes / Modules | Tests | Build | Platform Pkgs | |---------|-----------------|-------|-------|---------------| -| **Backend** | 7 modules, ~32 endpoints, 8 MCP tools | 20 files (unit + integration) | ✅ tsc | 13 (all used) | +| **Backend** | 7 modules, ~32 endpoints, 8 MCP tools | 20 files (unit + integration) | ✅ tsc | 13 (5 missing source in common_plat) | | **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. +**Package resolution note:** 5 backend `@bytelyst/*` packages (`backend-config`, `backend-flags`, `backend-telemetry`, `fastify-auth`, `field-encrypt`) do not have source directories in `learning_ai_common_plat/packages/`. They resolve via `^0.1.0` from the private Gitea npm registry but their source must be created in common_plat. This is a shared blocker with NomGap — see Phase 0 below. + +--- + +## Phase 0 — Missing Platform Package Source (SHARED BLOCKER) + +These 5 backend packages are depended on by both NoteLett and NomGap but have no source directory in `learning_ai_common_plat/packages/`. They must be created there before either product's backend can be built from a clean checkout of common_plat. + +- [ ] **0.1** Create `@bytelyst/backend-config` in `learning_ai_common_plat/packages/backend-config/` + - Base Zod config schema extended by all product backends + - Imported by: `backend/src/lib/config.ts` + +- [ ] **0.2** Create `@bytelyst/backend-flags` in `learning_ai_common_plat/packages/backend-flags/` + - Feature flag registry for backend services + - Imported by: `backend/src/lib/feature-flags.ts` + +- [ ] **0.3** Create `@bytelyst/backend-telemetry` in `learning_ai_common_plat/packages/backend-telemetry/` + - Buffered telemetry event tracking for backends + - Imported by: `backend/src/lib/telemetry.ts` + +- [ ] **0.4** Create `@bytelyst/fastify-auth` in `learning_ai_common_plat/packages/fastify-auth/` + - JWT auth middleware (RS256 JWKS + HS256 fallback), `extractAuth`, `requireRole`, `createRequestContext` + - Imported by: `backend/src/lib/auth.ts`, `backend/src/lib/request-context.ts`, all route modules + +- [ ] **0.5** Create `@bytelyst/field-encrypt` in `learning_ai_common_plat/packages/field-encrypt/` + - Field-level encryption/decryption with AKV/env/memory key providers + - Imported by: `backend/src/lib/field-encrypt.ts`, `backend/src/modules/notes/repository.ts` + +**Note:** These tasks require changes in `learning_ai_common_plat`, not in this repo. Coordinate with the common platform agent. NomGap also depends on all 5 of these. + +**Verification:** +```bash +cd ../learning_ai_common_plat && pnpm run build +cd ../learning_ai_notes/backend && pnpm install && pnpm run typecheck +``` --- @@ -124,10 +158,8 @@ cd backend && pnpm run typecheck && pnpm test - 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.6** Remove unused dependencies + - Remove `zustand` and `zod` from web `package.json` (declared, never imported anywhere in `web/src/`) - [ ] **3.7** Fix SSR crash risk — lazy-init module-scope API clients - `extraction-client.ts` and `blob-client.ts` instantiate clients at module scope @@ -174,18 +206,19 @@ 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.1** Review and enable CI workflows + - Gitea CI (`.gitea/workflows/ci.yml`) is already active + - GitHub Actions (`.github/workflows/ci.yml.disabled`) exists but is disabled — review, update, rename to `ci.yml` if GitHub is the target + - Files: `.github/workflows/ci.yml`, `.gitea/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` +- [ ] **5.3** Fix `web/.env.example` + - **Bug:** Product identity is stale — shows `NEXT_PUBLIC_PRODUCT_NAME=ByteLyst Agentic Notes` and `NEXT_PUBLIC_PRODUCT_ID=agentic-notes` instead of `NoteLett` / `notelett` + - **Missing vars:** `NEXT_PUBLIC_EXTRACTION_SERVICE_URL` and `NEXT_PUBLIC_PLATFORM_SERVICE_ORIGIN` are used in code but not listed - File: `web/.env.example` **Verification:** @@ -212,13 +245,16 @@ docker compose up -d && curl http://localhost:4016/api/bootstrap | Phase | Tasks | Priority | Est. Effort | |-------|-------|----------|-------------| +| 0 — Missing Platform Packages | 5 | **CRITICAL** | 4–6 hours (in common_plat) | | 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 | +| 3 — Web UX Polish | 7 | MEDIUM | 4–5 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** | +| **Total** | **32** | | **23–32 hours** | + +**Phase 0 must be done first** — it requires changes in `learning_ai_common_plat` and unblocks both NoteLett and NomGap backends. ---