1d068e748c
Derived from GAP_ANALYSIS.md (25 gaps across 5 categories). Structured as 8 sequential phases with: - Per-task checkboxes with gap IDs for traceability - Specific file paths and code patterns for each fix - Verification commands per phase - Commit message conventions - Test target summary (30→132 tests across all surfaces) - Progress log table for tracking commits - Deferred items (B4 webhooks, B5 sharing, E2 WINDSURF_CONTEXT) Phases: 1-Bug Fixes, 2-Code Quality, 3-Backend Tests, 4-Web Features, 5-DevOps, 6-E2E+Mobile Tests, 7-AI Enrichment, 8-Docs Alignment
498 lines
18 KiB
Markdown
498 lines
18 KiB
Markdown
# NoteLett — Implementation Tracker
|
||
|
||
**Created:** March 19, 2026
|
||
**Source:** `docs/GAP_ANALYSIS.md` (25 gaps across 5 categories)
|
||
**Companion docs:** `docs/PRD.md`, `docs/ROADMAP.md`, `AGENTS.md`
|
||
|
||
---
|
||
|
||
## How to Use This Document
|
||
|
||
- Each phase has a top-level checkbox that tracks overall phase completion.
|
||
- Each task within a phase has its own checkbox.
|
||
- When a task is completed, check it off and add the commit SHA in parentheses.
|
||
- Run the verification commands listed in each phase before marking it done.
|
||
- Phases are sequenced by dependency — complete Phase 1 before Phase 2, etc.
|
||
- Phases 1–3 are the critical path. Phases 4–7 can be parallelized after Phase 3.
|
||
|
||
---
|
||
|
||
## Baseline (before this tracker)
|
||
|
||
| Surface | Typecheck | Tests | Build |
|
||
|---------|-----------|-------|-------|
|
||
| Backend | ✅ pass | 24 tests (12 files) | ✅ tsc |
|
||
| Web | ✅ pass | 6 tests (5 files) | ✅ next build |
|
||
| Mobile | ✅ pass | 0 tests | n/a |
|
||
|
||
---
|
||
|
||
## Phase 1 — Bug Fixes (Gaps A1–A6, D3–D4)
|
||
|
||
**Goal:** Eliminate all runtime bugs and latent crash risks. Clean dead code.
|
||
**Estimated effort:** 2–3 hours
|
||
**Dependencies:** None — start here.
|
||
|
||
### Tasks
|
||
|
||
- [ ] **1.1** Lazy-init `extractionApi` in `web/src/lib/extraction-client.ts` (Gap A1)
|
||
- Replace `const extractionApi = createApiClient(...)` with lazy singleton `function getExtractionApi()`
|
||
- Pattern: same as NomGap `protocol-client.ts` / `social-client.ts`
|
||
- File: `web/src/lib/extraction-client.ts`
|
||
|
||
- [ ] **1.2** Lazy-init `blobClient` in `web/src/lib/blob-client.ts` (Gap A1)
|
||
- Replace `const blobClient = createBlobClient(...)` with lazy singleton `function getBlobClient()`
|
||
- Update all call sites within the file (`blobClient.getSasUrl(...)` → `getBlobClient().getSasUrl(...)`)
|
||
- File: `web/src/lib/blob-client.ts`
|
||
|
||
- [ ] **1.3** Add `"use client"` directive to `web/src/lib/notes-client.ts` (Gap A6)
|
||
- This file imports `extraction-client.ts` (module-scope API client). Without `"use client"`, any future server-component import would crash.
|
||
- Add `"use client";` as the first line of the file.
|
||
- File: `web/src/lib/notes-client.ts`
|
||
|
||
- [ ] **1.4** Add `output: "standalone"` to `web/next.config.ts` (Gap A2)
|
||
- Required for Docker builds. `outputFileTracingRoot` is already set.
|
||
- File: `web/next.config.ts`
|
||
|
||
- [ ] **1.5** Delete dead code: `web/src/lib/mock-data.ts` (Gap D3)
|
||
- Confirmed zero imports. 228 lines of unused scaffold-era mock data.
|
||
- Delete: `web/src/lib/mock-data.ts`
|
||
|
||
- [ ] **1.6** Delete dead code: `web/src/lib/review-data.ts` (Gap D4)
|
||
- Confirmed zero imports. Superseded by `review-client.ts`.
|
||
- Delete: `web/src/lib/review-data.ts`
|
||
|
||
### Verification
|
||
|
||
```bash
|
||
cd web && npm run typecheck && npm test && npm run build
|
||
```
|
||
|
||
### Commit convention
|
||
|
||
```
|
||
fix(web): lazy-init extraction + blob clients, add use-client to notes-client
|
||
|
||
- extraction-client.ts: lazy singleton (SSR crash fix) [A1]
|
||
- blob-client.ts: lazy singleton [A1]
|
||
- notes-client.ts: add "use client" directive [A6]
|
||
- next.config.ts: add output: "standalone" [A2]
|
||
- Delete mock-data.ts and review-data.ts (dead code) [D3, D4]
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 2 — Code Quality (Gaps D1–D2, A3–A4)
|
||
|
||
**Goal:** Consolidate duplicate types, optimize N+1 queries.
|
||
**Estimated effort:** 2–3 hours
|
||
**Dependencies:** Phase 1 (lazy-init changes affect the same files).
|
||
|
||
### Tasks
|
||
|
||
- [ ] **2.1** Consolidate backend response types into `web/src/lib/types.ts` (Gap D1)
|
||
- Extract `NoteDoc`, `NoteAgentActionDoc`, `NoteTaskDoc`, `NoteArtifactDoc`, `NoteRelationshipDoc`, `WorkspaceDoc` from `notes-client.ts` and `review-client.ts` into `types.ts`
|
||
- Update imports in `notes-client.ts`, `review-client.ts`, `extraction-client.ts`
|
||
- Files: `web/src/lib/types.ts`, `web/src/lib/notes-client.ts`, `web/src/lib/review-client.ts`
|
||
|
||
- [ ] **2.2** Optimize `getNoteDetail()` to call `GET /notes/:id` directly (Gap A3)
|
||
- Current: fetches ALL notes then `.find()` by ID
|
||
- Fix: Call `GET /notes/:id?workspaceId=...` directly
|
||
- Requires: either pass `workspaceId` as parameter, or add a backend route that resolves by `noteId` alone
|
||
- Option A: Add `workspaceId` parameter to `getNoteDetail(noteId, workspaceId)`
|
||
- Option B: Add backend `GET /notes/:id` route without requiring `workspaceId` (look up by userId + noteId)
|
||
- File: `web/src/lib/notes-client.ts`, possibly `backend/src/modules/notes/routes.ts`
|
||
|
||
- [ ] **2.3** Optimize `listWorkspaceSummaries()` to avoid fetching all notes (Gap A4)
|
||
- Option A: Add `GET /workspaces/summaries` backend endpoint that includes `noteCount` per workspace
|
||
- Option B: Add `noteCount` field to workspace list response via a Cosmos cross-query
|
||
- File: `web/src/lib/notes-client.ts`, `backend/src/modules/workspaces/`
|
||
|
||
- [ ] **2.4** Add backend endpoint for cross-workspace pending agent actions (Gap D2)
|
||
- `GET /note-agent-actions/pending` — returns all pending actions for the current user across workspaces
|
||
- Eliminates the N+1 pattern in `review-client.ts` → `listApprovalQueue()`
|
||
- Files: `backend/src/modules/note-agent-actions/routes.ts`, `web/src/lib/review-client.ts`
|
||
|
||
### Verification
|
||
|
||
```bash
|
||
cd backend && npm run typecheck && npm test
|
||
cd web && npm run typecheck && npm test && npm run build
|
||
```
|
||
|
||
### Commit convention
|
||
|
||
```
|
||
refactor(web): consolidate types, optimize N+1 queries [D1, A3, A4, D2]
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 3 — Backend Test Depth (Gap A5)
|
||
|
||
**Goal:** Replace registration-only route tests with real API behavior tests.
|
||
**Estimated effort:** 3–4 hours
|
||
**Dependencies:** Phase 2 (new backend endpoints should be tested too).
|
||
|
||
### Tasks
|
||
|
||
- [ ] **3.1** Add integration tests for `notes` routes
|
||
- Test: POST create → GET list → GET by ID → PATCH update → POST archive
|
||
- Test: search query, validation errors, auth enforcement, 404 on missing
|
||
- Target: 8–12 tests
|
||
- File: `backend/src/modules/notes/routes.test.ts`
|
||
|
||
- [ ] **3.2** Add integration tests for `workspaces` routes
|
||
- Test: POST create → GET list → GET by ID → PATCH update
|
||
- Test: validation, auth, 404
|
||
- Target: 6–8 tests
|
||
- File: `backend/src/modules/workspaces/routes.test.ts`
|
||
|
||
- [ ] **3.3** Add integration tests for `note-tasks` routes
|
||
- Test: POST create → GET list (by noteId + workspaceId) → PATCH update
|
||
- Target: 4–6 tests
|
||
- File: `backend/src/modules/note-tasks/routes.test.ts`
|
||
|
||
- [ ] **3.4** Add integration tests for `note-artifacts` routes
|
||
- Test: POST create → GET list (by noteId + workspaceId)
|
||
- Target: 3–5 tests
|
||
- File: `backend/src/modules/note-artifacts/routes.test.ts`
|
||
|
||
- [ ] **3.5** Add integration tests for `note-relationships` routes
|
||
- Test: POST create → GET list → DELETE
|
||
- Target: 3–5 tests
|
||
- File: `backend/src/modules/note-relationships/routes.test.ts`
|
||
|
||
- [ ] **3.6** Add integration tests for `note-agent-actions` routes
|
||
- Test: POST create → GET list → PATCH review (approve/reject) → POST batch-review
|
||
- Test: reviewedBy/reviewedAt auto-set on approve/reject
|
||
- Target: 6–8 tests
|
||
- File: `backend/src/modules/note-agent-actions/routes.test.ts`
|
||
|
||
- [ ] **3.7** Add integration tests for `saved-views` routes
|
||
- Test: POST create → GET list → GET by ID → PATCH update → DELETE
|
||
- Target: 5–7 tests
|
||
- File: `backend/src/modules/saved-views/routes.test.ts`
|
||
|
||
### Verification
|
||
|
||
```bash
|
||
cd backend && npm run typecheck && npm test
|
||
# Target: 60+ tests (up from 24)
|
||
```
|
||
|
||
### Commit convention
|
||
|
||
```
|
||
test(backend): add integration tests for all 7 route modules [A5]
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 4 — Web Feature Gaps (Gaps B1, B2, B8)
|
||
|
||
**Goal:** Add missing web CRUD flows that the PRD requires.
|
||
**Estimated effort:** 3–4 hours
|
||
**Dependencies:** Phase 2 (type consolidation), Phase 3 (backend endpoints tested).
|
||
|
||
### Tasks
|
||
|
||
- [ ] **4.1** Add "Create Note" flow to web UI (Gap B2)
|
||
- Add `CreateNoteModal` component (title, body, workspace selector, tags)
|
||
- Wire to `POST /notes` via `notes-client.ts`
|
||
- Add "New Note" button on dashboard and workspace pages
|
||
- Files: `web/src/components/CreateNoteModal.tsx`, `web/src/lib/notes-client.ts`, dashboard + workspace pages
|
||
|
||
- [ ] **4.2** Add note restore backend endpoint (Gap B1)
|
||
- Add `POST /notes/:id/restore` route (sets `status: 'active'`)
|
||
- Mirror the existing `POST /notes/:id/archive` pattern
|
||
- File: `backend/src/modules/notes/routes.ts`
|
||
|
||
- [ ] **4.3** Add archive/restore UI on note detail page (Gap B1)
|
||
- Show "Archive" button for active/draft notes, "Restore" button for archived notes
|
||
- Wire to `POST /notes/:id/archive` and `POST /notes/:id/restore`
|
||
- File: `web/src/app/(app)/notes/[noteId]/page.tsx`
|
||
|
||
- [ ] **4.4** Add "Link Note" relationship creation UI (Gap B8)
|
||
- Add "Link Note" button on note detail page
|
||
- Show note search/picker modal to select target note
|
||
- Wire to `POST /note-relationships` via `notes-client.ts`
|
||
- Files: `web/src/components/LinkNoteModal.tsx`, note detail page
|
||
|
||
- [ ] **4.5** Add web unit tests for new components
|
||
- Test: CreateNoteModal renders, validates, calls API
|
||
- Test: LinkNoteModal renders, searches, creates relationship
|
||
- Target: 4–6 tests
|
||
- Files: `web/src/components/CreateNoteModal.test.tsx`, `web/src/components/LinkNoteModal.test.tsx`
|
||
|
||
### Verification
|
||
|
||
```bash
|
||
cd backend && npm run typecheck && npm test
|
||
cd web && npm run typecheck && npm test && npm run build
|
||
```
|
||
|
||
### Commit convention
|
||
|
||
```
|
||
feat(web): add create note, archive/restore, link note flows [B1, B2, B8]
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 5 — DevOps (Gaps C1–C5)
|
||
|
||
**Goal:** Docker builds, CI, and deployment readiness.
|
||
**Estimated effort:** 2–3 hours
|
||
**Dependencies:** Phase 1 (`output: "standalone"` must be set first).
|
||
|
||
### Tasks
|
||
|
||
- [ ] **5.1** Add `backend/Dockerfile` (Gap C1)
|
||
- Multi-stage build: install → build → runtime
|
||
- Follow the NomGap/ActionTrail pattern
|
||
- Exclude test files via tsconfig (already done in backend)
|
||
- File: `backend/Dockerfile`
|
||
|
||
- [ ] **5.2** Add `web/Dockerfile` (Gap C1)
|
||
- Multi-stage build with `output: "standalone"`
|
||
- Add dummy build-time env vars for Next.js page data collection
|
||
- Follow the NomGap/ActionTrail pattern
|
||
- File: `web/Dockerfile`
|
||
|
||
- [ ] **5.3** Add `scripts/docker-prep.sh` (Gap C5)
|
||
- Pack `@bytelyst/*` packages into tarballs
|
||
- Rewrite `package.json` file: refs to tarball paths
|
||
- Add `--restore` flag to undo
|
||
- File: `scripts/docker-prep.sh`
|
||
|
||
- [ ] **5.4** Add `docker-compose.yml` (Gap C2)
|
||
- Services: backend (port 4016), web (port 3000)
|
||
- Environment variable pass-through for Cosmos, JWT, etc.
|
||
- File: `docker-compose.yml`
|
||
|
||
- [ ] **5.5** Add GitHub Actions CI workflow (Gap C3)
|
||
- Jobs: backend (typecheck + test + build), web (typecheck + test + build), mobile (typecheck)
|
||
- Triggered on push to main and PRs
|
||
- File: `.github/workflows/ci.yml`
|
||
|
||
### Verification
|
||
|
||
```bash
|
||
# Docker build smoke test
|
||
cd scripts && ./docker-prep.sh
|
||
docker build -f backend/Dockerfile .
|
||
docker build -f web/Dockerfile .
|
||
cd scripts && ./docker-prep.sh --restore
|
||
```
|
||
|
||
### Commit convention
|
||
|
||
```
|
||
feat(devops): Dockerfiles, docker-compose, CI, docker-prep [C1–C5]
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 6 — E2E & Mobile Tests (Gaps B7, C4)
|
||
|
||
**Goal:** Playwright E2E for web, Vitest for mobile.
|
||
**Estimated effort:** 3–4 hours
|
||
**Dependencies:** Phase 4 (web features must exist to E2E test).
|
||
|
||
### Tasks
|
||
|
||
- [ ] **6.1** Add Playwright config and setup (Gap C4)
|
||
- Add `playwright.config.ts` with base URL, web server auto-start
|
||
- Add `web/e2e/` directory
|
||
- Add `@playwright/test` dev dependency
|
||
- Files: `web/playwright.config.ts`, `web/package.json`
|
||
|
||
- [ ] **6.2** Add Playwright navigation E2E tests
|
||
- Test: landing page → dashboard → workspaces → search → reviews → settings
|
||
- Test: sidebar navigation, keyboard shortcuts
|
||
- Target: 6–8 tests
|
||
- File: `web/e2e/navigation.spec.ts`
|
||
|
||
- [ ] **6.3** Add Playwright CRUD flow E2E tests
|
||
- Test: create note (requires Phase 4.1) → edit → archive → restore
|
||
- Test: search notes, link notes, create artifact, create task
|
||
- Test: approval queue review (approve/reject)
|
||
- Target: 10–15 tests
|
||
- Files: `web/e2e/notes.spec.ts`, `web/e2e/reviews.spec.ts`
|
||
|
||
- [ ] **6.4** Add mobile Zustand store tests (Gap B7)
|
||
- Test: `notes-store.ts` — CRUD state transitions
|
||
- Test: `workspace-store.ts` — workspace selection, switching
|
||
- Test: `inbox-store.ts` — approval state, approve/reject actions
|
||
- Test: `auth-store.ts` — login/logout state
|
||
- Target: 8–12 tests
|
||
- Files: `mobile/src/store/notes-store.test.ts`, `mobile/src/store/workspace-store.test.ts`, `mobile/src/store/inbox-store.test.ts`, `mobile/src/store/auth-store.test.ts`
|
||
|
||
- [ ] **6.5** Add mobile API client tests (Gap B7)
|
||
- Test: `notes.ts` — API request construction, response parsing
|
||
- Test: `workspaces.ts` — list, create
|
||
- Test: `note-agent-actions.ts` — approve, reject
|
||
- Target: 6–8 tests
|
||
- Files: `mobile/src/api/notes.test.ts`, `mobile/src/api/workspaces.test.ts`, `mobile/src/api/note-agent-actions.test.ts`
|
||
|
||
### Verification
|
||
|
||
```bash
|
||
# Web E2E (requires backend running)
|
||
cd backend && npm run dev &
|
||
cd web && npx playwright test
|
||
|
||
# Mobile unit tests
|
||
cd mobile && npm test
|
||
# Target: 15+ tests (up from 0)
|
||
```
|
||
|
||
### Commit convention
|
||
|
||
```
|
||
test(web): Playwright E2E — navigation + CRUD flows [C4]
|
||
test(mobile): add store and API client unit tests [B7]
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 7 — AI Enrichment & Advanced Features (Gaps B3, B6)
|
||
|
||
**Goal:** Add extraction-backed enrichment and import/export.
|
||
**Estimated effort:** 4–5 hours
|
||
**Dependencies:** Phase 3 (backend test patterns), Phase 4 (web CRUD flows).
|
||
|
||
### Tasks
|
||
|
||
- [ ] **7.1** Add note summarization via extraction-service (Gap B6)
|
||
- Add `POST /notes/:id/summarize` backend route
|
||
- Call extraction-service with `summarization` task type
|
||
- Store summary as a note artifact (type: `summary`)
|
||
- Add "Summarize" button on web note detail page
|
||
- Files: `backend/src/modules/notes/routes.ts`, `web/src/lib/extraction-client.ts`, note detail page
|
||
|
||
- [ ] **7.2** Add note export (JSON/Markdown) (Gap B3)
|
||
- Add `GET /notes/export` backend endpoint (query params: format, workspaceId)
|
||
- Support `format=json` and `format=markdown`
|
||
- Add "Export" button on web workspace page
|
||
- Files: `backend/src/modules/notes/routes.ts`, `web/src/app/(app)/workspaces/page.tsx`
|
||
|
||
- [ ] **7.3** Add workspace-level note count to backend (Gap A4)
|
||
- Add `noteCount` field to workspace list response
|
||
- Use Cosmos cross-query or batch aggregate
|
||
- Remove the client-side all-notes fetch from `listWorkspaceSummaries()`
|
||
- Files: `backend/src/modules/workspaces/repository.ts`, `web/src/lib/notes-client.ts`
|
||
|
||
- [ ] **7.4** Add tests for new endpoints
|
||
- Test: summarize route (mock extraction-service)
|
||
- Test: export route (JSON + Markdown formats)
|
||
- Test: workspace list with note counts
|
||
- Target: 6–10 tests
|
||
- Files: `backend/src/modules/notes/routes.test.ts`, `backend/src/modules/workspaces/routes.test.ts`
|
||
|
||
### Verification
|
||
|
||
```bash
|
||
cd backend && npm run typecheck && npm test
|
||
cd web && npm run typecheck && npm test && npm run build
|
||
```
|
||
|
||
### Commit convention
|
||
|
||
```
|
||
feat(backend): note summarization, export, workspace note counts [B3, B6, A4]
|
||
feat(web): summarize + export UI triggers [B3, B6]
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 8 — Documentation Alignment (Gaps E1–E2)
|
||
|
||
**Goal:** Update all docs to reflect the final implementation state.
|
||
**Estimated effort:** 1 hour
|
||
**Dependencies:** All previous phases.
|
||
|
||
### Tasks
|
||
|
||
- [ ] **8.1** Update `docs/ROADMAP.md` phase checklists (Gap E1)
|
||
- Check off all Phase 0–3 items that are now implemented
|
||
- Add Phase 4–5 items as needed
|
||
- Update progress notes section with new commits
|
||
|
||
- [ ] **8.2** Update `AGENTS.md` with current state
|
||
- Update test counts across all surfaces
|
||
- Add any new API endpoints added in Phases 2–7
|
||
- Update repo layout if new files/dirs were added
|
||
|
||
- [ ] **8.3** Update `docs/GAP_ANALYSIS.md` final status
|
||
- Add completion notes to each resolved gap
|
||
- Update the totals table with final numbers
|
||
|
||
### Verification
|
||
|
||
```bash
|
||
# Ensure all docs reference accurate file paths and counts
|
||
cd backend && npm run typecheck && npm test
|
||
cd web && npm run typecheck && npm test && npm run build
|
||
cd mobile && npm run typecheck && npm test
|
||
```
|
||
|
||
### Commit convention
|
||
|
||
```
|
||
docs: update ROADMAP, AGENTS, GAP_ANALYSIS to reflect completed implementation
|
||
```
|
||
|
||
---
|
||
|
||
## Deferred (V2+ / Post-Launch)
|
||
|
||
These gaps are explicitly deferred per the gap analysis:
|
||
|
||
| Gap | Description | Reason |
|
||
|-----|-------------|--------|
|
||
| **B4** | Webhook/event hooks | Low priority for V1. Implement after core flows are hardened. |
|
||
| **B5** | Note sharing within workspace | Requires workspace-level access model redesign. Phase 2+ feature. |
|
||
| **E2** | WINDSURF_CONTEXT.md | Low priority — AGENTS.md covers most of this. |
|
||
|
||
---
|
||
|
||
## Progress Log
|
||
|
||
Track completed phases and commits here as work progresses.
|
||
|
||
| Date | Phase | Commit | Summary |
|
||
|------|-------|--------|---------|
|
||
| | | | |
|
||
|
||
---
|
||
|
||
## Test Target Summary
|
||
|
||
| Surface | Before | After Phase 3 | After Phase 6 | After Phase 7 |
|
||
|---------|--------|---------------|---------------|---------------|
|
||
| Backend | 24 tests (12 files) | ~75 tests | ~75 tests | ~85 tests |
|
||
| Web unit | 6 tests (5 files) | 6 tests | ~12 tests | ~12 tests |
|
||
| Web E2E | 0 | 0 | ~20 tests | ~20 tests |
|
||
| Mobile | 0 | 0 | ~15 tests | ~15 tests |
|
||
| **Total** | **30** | **~81** | **~122** | **~132** |
|
||
|
||
---
|
||
|
||
## Full Verification Checklist (run before marking any phase complete)
|
||
|
||
```bash
|
||
# ── Backend ────────────────────────────────────────
|
||
cd backend && npm run typecheck && npm test && npm run build
|
||
|
||
# ── Web ────────────────────────────────────────────
|
||
cd web && npm run typecheck && npm test && npm run build
|
||
|
||
# ── Mobile ─────────────────────────────────────────
|
||
cd mobile && npm run typecheck && npm test
|
||
|
||
# ── E2E (after Phase 6) ───────────────────────────
|
||
cd web && npx playwright test
|
||
```
|