learning_ai_notes/docs/IMPLEMENTATION_TRACKER.md

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

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

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

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

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

# 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

# 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

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

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

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