docs: add detailed implementation tracker with 8 phases and 35 checkbox tasks

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
2026-03-19 07:09:47 -07:00 · 2026-03-19 07:09:47 -07:00 · 1d068e748c
commit 1d068e748c
parent ee033f4eab
1 changed files with 497 additions and 0 deletions
--- a/docs/IMPLEMENTATION_TRACKER.md
+++ b/docs/IMPLEMENTATION_TRACKER.md
@ -0,0 +1,497 @@
+# 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
+```