# 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 task has its own checkbox. Check it off and add the commit SHA in parentheses when done.
- Run the verification commands listed in each phase before marking it done.
- **Dependency chain:** Phase 1 → Phase 2 → Phase 3 (critical path).
- **After Phase 1:** Phase 5 (DevOps) can start in parallel.
- **After Phase 3:** Phases 4, 6, 7 can be parallelized.
- **Phase 8** (docs) runs last, after all other phases.

---

## 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) [x]

**Goal:** Eliminate all runtime bugs and latent crash risks. Clean dead code.
**Estimated effort:** 2–3 hours
**Dependencies:** None — start here.

### Tasks

- [x] **1.1** Lazy-init `extractionApi` in `web/src/lib/extraction-client.ts` (Gap A1) (`dbb1a84`)
  - 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`

- [x] **1.2** Lazy-init `blobClient` in `web/src/lib/blob-client.ts` (Gap A1) (`dbb1a84`)
  - Replace `const blobClient = createBlobClient(...)` with lazy singleton `function getBlobClient()`
  - Update all 4 call sites within the file (`blobClient.getSasUrl(...)` → `getBlobClient().getSasUrl(...)`)
  - Remove dead re-export `export { blobClient }` on line 48 (zero external imports)
  - File: `web/src/lib/blob-client.ts`

- [x] **1.3** Add `"use client"` directive to `web/src/lib/notes-client.ts` (Gap A6) (`dbb1a84`)
  - 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`

- [x] **1.4** Add `output: "standalone"` to `web/next.config.ts` (Gap A2) (`dbb1a84`)
  - Required for Docker builds. `outputFileTracingRoot` is already set.
  - File: `web/next.config.ts`

- [x] **1.5** Delete dead code: `web/src/lib/mock-data.ts` (Gap D3) (`dbb1a84`)
  - Confirmed zero imports. 228 lines of unused scaffold-era mock data.
  - Delete: `web/src/lib/mock-data.ts`

- [x] **1.6** Delete dead code: `web/src/lib/review-data.ts` (Gap D4) (`dbb1a84`)
  - 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 (by workspaceId + noteId)
  - Note: no DELETE route exists — only GET and POST are implemented
  - Target: 3–4 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–75 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 only (`output: "standalone"` must be set first). Can run in parallel with Phases 2–3.

### 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:** 3–4 hours
**Dependencies:** Phase 3 (backend test patterns), Phase 4 (web CRUD flows).
**Note:** Gap A4 (workspace note count optimization) is fully addressed in Phase 2 task 2.3 — not duplicated here.

### 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 tests for new endpoints
  - Test: summarize route (mock extraction-service)
  - Test: export route (JSON + Markdown formats)
  - Target: 4–8 tests
  - Files: `backend/src/modules/notes/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 endpoints [B3, B6]
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 |
|------|-------|--------|---------|
| 2026-03-19 | Phase 1 | `dbb1a84` | Bug fixes: lazy-init SSR clients, use-client directive, standalone output, delete dead code |

---

## Test Target Summary

| Surface | Before | After Phase 3 | After Phase 6 | After Phase 7 |
|---------|--------|---------------|---------------|---------------|
| Backend | 24 tests (12 files) | ~60–75 tests | ~60–75 tests | ~70–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** | **~66–81** | **~107–122** | **~117–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
```