learning_ai_common_plat/dashboards/tracker-web/docs/ROADMAP.md

# Tracker Dashboard — Master Roadmap

**Version:** 3.0
**Date:** 2026-05-25
**Status:** Phase 0 shipped · Phase 1 in progress
**Parent docs:** [`docs/PRD.md`](./PRD.md) · [`docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`](./PRODUCTION_READINESS_HANDOFF_ROADMAP.md) · [`docs/IMPLEMENTATION_TRACKER.md`](./IMPLEMENTATION_TRACKER.md)
**Companion roadmaps:** [`docs/roadmaps/`](./roadmaps/)

> **Living document.** Coding agents, developers, PMs, and public contributors can submit items
> via the [public roadmap](https://tracker.bytelyst.com/roadmap) or the [Agent API](#-agent--automation-api).
> Deployed at **https://tracker.bytelyst.com**.

---

## ⚡ Where to Start (Fresh-Agent Quick Pointer)

You just opened this repo and want to make progress. Do this in order:

1. **Read** [`PRD.md`](./PRD.md) (5 min) — what tracker is and why
2. **Read** [`roadmaps/01_FOUNDATIONS_AND_DECISIONS.md`](./roadmaps/01_FOUNDATIONS_AND_DECISIONS.md) (5 min) — locked decisions you must not silently change
3. **Read** [`PRODUCTION_READINESS_HANDOFF_ROADMAP.md`](./PRODUCTION_READINESS_HANDOFF_ROADMAP.md) (10 min) — Day-by-day Phase 1 playbook
4. **Pick the first unchecked task** in [`IMPLEMENTATION_TRACKER.md`](./IMPLEMENTATION_TRACKER.md) following the dependency chain (1.A → 1.B → 1.C → 1.D → 1.E → 1.F)
5. **Do the task**, run its verification command, **commit with format** `<type>(<scope>): <subject>`, **push to origin**, then **paste the commit SHA** into the corresponding `(______)` placeholder in `IMPLEMENTATION_TRACKER.md`
6. **Repeat** — one slice, one commit, one tracker update at a time

> **Do not skip ahead** to Phase 2+ until Phase 1 exit criteria all pass (see [`PRODUCTION_READINESS_HANDOFF_ROADMAP.md` § Exit Criteria](./PRODUCTION_READINESS_HANDOFF_ROADMAP.md#exit-criteria-for-production-readiness-end-of-phase-1)).

---

## 1. Purpose

This is the **master execution tracker** for the tracker-web dashboard. Detailed implementation
plans live under [`docs/roadmaps/`](./roadmaps/). Per-slice progress with commit SHAs lives in
[`docs/IMPLEMENTATION_TRACKER.md`](./IMPLEMENTATION_TRACKER.md).

Use this document to:

- track phase status and dependencies,
- understand sequencing across the 6 phases,
- assign workstreams to coding agents,
- link out to smaller execution roadmaps with focused detail.

---

## 2. Status Legend

Granular per-feature status — adapted from NoteLett to give more nuance than a binary
"shipped vs planned" flag.

| Status             | Meaning                                                          |
| ------------------ | ---------------------------------------------------------------- |
| 🟦 **Scaffolded**  | Package / route / component exists and boots, no behaviour yet   |
| 🟨 **Mock-backed** | UI exists but runs on mock or fallback data                      |
| 🟧 **Local-only**  | Behaviour lives in client/local state without server persistence |
| 🟩 **Integrated**  | Wired to the intended backend / platform dependency              |
| ✅ **Verified**    | Exercised by build + typecheck + tests + smoke checks            |
| ⚠️ **Bug / Gap**   | Known issue tracked in [§ Known Bugs](#known-bugs--gaps-)        |
| 🔗 **Depends**     | Blocked by another phase item                                    |
| 🤖                 | Agent-targeted feature                                           |
| 🌐                 | Public-facing feature                                            |
| 🏢                 | Internal / team feature                                          |

---

## 3. Confirmed Stack

- **Web:** Next.js 16 · React 19 · TypeScript 5 · Tailwind CSS 4
- **Backend:** `tracker-service` proxied via `platform-service` (Fastify 5, port `4003`)
- **Cache / Sessions:** valkey (Redis-compatible)
- **Data store:** Azure Cosmos DB (production) · in-memory provider (dev / smoke)
- **Shared packages:** `@bytelyst/api-client` · `@bytelyst/dashboard-components` · `@bytelyst/ui` (Phase 2) · `@bytelyst/react-auth` · `@bytelyst/logger` · `@bytelyst/telemetry-client` · `@bytelyst/blob` (Phase 2 attachments)
- **Container:** Standalone Next.js build · Caddy reverse proxy at `tracker.bytelyst.com`
- **Tests:** Vitest (unit) · Playwright (E2E) · `@axe-core/playwright` (a11y) — Phase 1
- **CI:** Gitea Actions + UI drift ratchet (Phase 1)

---

## 4. Permissions Matrix

| Action               | Public (no login) | Auth User | PM / Admin | Agent (API key) |
| -------------------- | :---------------: | :-------: | :--------: | :-------------: |
| View public roadmap  |        ✅         |    ✅     |     ✅     |       ✅        |
| Submit public idea   |        ✅         |    ✅     |     ✅     |       ✅        |
| Vote on public item  |        ✅         |    ✅     |     ✅     |       ✅        |
| View internal items  |        ❌         |    ✅     |     ✅     |   ✅ (scoped)   |
| Create internal item |        ❌         |    ✅     |     ✅     | ✅ (write key)  |
| Edit any item        |        ❌         | own only  |     ✅     | ✅ (write key)  |
| Delete item          |        ❌         |    ❌     |     ✅     |       ❌        |
| Change status        |        ❌         |    ✅     |     ✅     | ✅ (write key)  |
| Claim item           |        ❌         |    ❌     |     ❌     | ✅ (write key)  |
| Link PR to item      |        ❌         |    ✅     |     ✅     | ✅ (write key)  |
| Manage API keys      |        ❌         |    ❌     |     ✅     |       ❌        |
| Configure webhooks   |        ❌         |    ❌     |     ✅     |       ❌        |
| Access analytics     |        ❌         |    ❌     |     ✅     |  🔲 (read key)  |

---

## 5. Master Phase Tracker

| Phase | Theme                                  | Status         | Target     |
| ----- | -------------------------------------- | -------------- | ---------- |
| 0     | Foundation                             | ✅ Shipped     | —          |
| 1     | Production hardening                   | 🔄 In progress | 2026-06-14 |
| 2     | Rich item details (Linear/Jira parity) | 🔲 Planned     | 2026-07-12 |
| 3     | Agent & automation API                 | 🔲 Planned     | 2026-07-26 |
| 4     | Multi-source intake                    | 🔲 Planned     | 2026-08-09 |
| 5     | Analytics & intelligence               | 🔲 Planned     | 2026-08-30 |
| 6     | Mobile, accessibility & i18n           | 🔲 Planned     | 2026-09-13 |

---

## Phase 0 — Foundation (Shipped) ✅

Everything checked here is already shipped and running at **https://tracker.bytelyst.com**.

### 0.1 Core Item Management ✅

- [x] CRUD on tracker items
- [x] Item types: `bug` · `feature` · `task`
- [x] Statuses: `open` → `in_progress` → `done` → `closed` · `wont_fix`
- [x] Priority: `critical` · `high` · `medium` · `low`
- [x] Visibility: `internal` vs `public`
- [x] Labels, assignee, reporter, target release
- [x] Source tracking: `internal` · `user_submitted` · `auto_detected`
- [x] Vote count, comment count per item

### 0.2 Views ✅

- [x] Dashboard overview with stats by type / status / priority
- [x] Items list (search, filter, paginate)
- [x] Kanban board (4-column, button-only transitions — see B-003)
- [x] Item detail with inline edits

### 0.3 Public Roadmap ✅ 🌐

- [x] `/roadmap` — no auth
- [x] Board / list view toggle
- [x] Submit form (name + email + type + description)
- [x] Email-based voting (localStorage — see B-004)
- [x] Stats bar + search + filter

### 0.4 Authentication ✅

- [x] Email + password via platform-service
- [x] MFA · Google OAuth · JWT refresh
- [x] Product switcher (multi-product via `x-product-id` header)

### 0.5 Infrastructure ✅

- [x] Standalone Next.js Docker build
- [x] Caddy reverse proxy (`tracker.bytelyst.com`)
- [x] PostHog analytics
- [x] Vitest + Playwright scaffolding
- [x] ESLint + Prettier + Husky

---

## Phase 1 — Production Hardening 🔄

> **Goal:** Make everything shipped actually reliable in production, applying the lessons from
> the NoteLett + FlowMonk production-readiness sprints of 2026-05-22/23.
> **Target:** Sprint ending 2026-06-14
> **Detailed plan:** [`docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`](./PRODUCTION_READINESS_HANDOFF_ROADMAP.md)

> **Two numbering schemes — same content.** This file groups Phase 1 by **topic** (1.1–1.8).
> The handoff playbook groups the same work by **execution day** (1.A–1.F). Mapping:

| Topic (this doc)                   | Day milestone (handoff)                         |
| ---------------------------------- | ----------------------------------------------- |
| 1.1 Infrastructure Health          | 1.A Container Health Restoration                |
| 1.2 Docker Hardening               | 1.C Docker Hardening                            |
| 1.3 UI Drift Ratchet               | 1.D UI Drift Ratchet                            |
| 1.4 Rate Limiting & Spam           | _(in 1.F security cluster — execute alongside)_ |
| 1.5 Test Coverage                  | 1.E Test Hardening                              |
| 1.6 Error Handling & Observability | 1.F Observability + Security (obs half)         |
| 1.7 Security                       | 1.F Observability + Security (sec half)         |
| 1.8 Workspace Health               | 1.B Workspace Health                            |

> **Execution order** (sequential): 1.A → 1.B → 1.C → 1.D → 1.E → 1.F. Use this doc for
> _scope and acceptance_; use the handoff playbook for _step-by-step day-by-day execution_.

### 1.1 Infrastructure Health ⚠️

- [ ] **Fix valkey (Redis) container health** — currently `unhealthy`; root cause of most downstream container failures
- [ ] **Fix platform-service health check** — reports `unhealthy` due to valkey connectivity; depends on valkey fix
- [ ] **Fix tracker-web `/health` route** — must probe DB + platform-service reachability, not just return HTTP 200
- [ ] **Add 8 GB swap on VM** — currently 0 B; build spikes OOM-kill running services
- [ ] **Limit concurrent Gitea CI runner jobs** — cap to 1–2 parallel `next build` + `tsc` jobs (4-core VM cannot survive 4+ parallel builds)
- [ ] **Ensure `restart: unless-stopped`** on all docker-compose services

### 1.2 Docker Hardening — From NoteLett+FlowMonk learnings 🆕

- [ ] **Bake `NEXT_PUBLIC_*` values at build time** — drop hardcoded `api.bytelyst.com`; thread through `docker-compose.yml` build args (NoteLett `91b8597`, FlowMonk `5ecd829`)
- [ ] **Fix Next.js standalone static-chunks 404** in Docker — copy `.next/static` to standalone output (NoteLett `131b73c`, FlowMonk `5ecd829`)
- [ ] **IPv4 healthcheck** — Docker healthcheck must use `127.0.0.1`, not `localhost` (avoids IPv6 resolution issues) (FlowMonk `5ecd829`)
- [ ] **Corp-proxy build support** — `NODE_TLS_REJECT_UNAUTHORIZED=0` + `NPM_CONFIG_STRICT_SSL=false` in build stage only (NoteLett `e5221af`)
- [ ] **Adopt tarball-based Docker builds** via `scripts/docker-prep.sh` (already used by NoteLett, FlowMonk, ChronoMind)
- [ ] **Local docker-compose.override.yml** wires backend to sibling `platform-service`, `extraction-service`, `mcp-server` with shared JWT secret

### 1.3 UI Drift Ratchet (CI Gate) — From NoteLett UI8 🆕

- [ ] **Add `scripts/ui-drift-audit.sh`** — counts: raw form controls, legacy global classes, hardcoded color literals, direct `@bytelyst/ui` imports outside adapter
- [ ] **Add `scripts/ui-drift-ratchet.sh`** — one-way CI gate: numbers can only decrease, never increase
- [ ] **Hard-zero enforcement** for: legacy global classes, hardcoded color literals, direct `@bytelyst/ui` imports outside adapter
- [ ] **Wire into Gitea Actions CI** — `audit:release-guards` job runs ratchet + secret scan + token audit (NoteLett pattern)

### 1.4 Rate Limiting & Spam Protection 🌐

- [ ] **Rate-limit `POST /public/submit`** — minimum 10 req/min per IP
- [ ] **Cloudflare Turnstile or hCaptcha** on public submission form
- [ ] **Server-side vote deduplication per email** (current dedup is localStorage-only)
- [ ] **Sanitise all public inputs server-side** — XSS / injection guard

### 1.5 Test Coverage

- [ ] **Vitest unit tests ≥ 80 % on `src/lib/`**
- [ ] **Playwright E2E happy path:** login → create item → claim → link PR → close
- [ ] **Playwright E2E public flow:** submit + vote + status check
- [ ] **Docker compose E2E test script** — `scripts/e2e-docker-test.sh` that exercises full CRUD against live containers (NoteLett `d5e857d`, FlowMonk `e48e75b`)
- [ ] **Seed scripts** — bootstrap test data into the deployed stack
- [ ] **Port-conflict-proof E2E** — Playwright picks random ports per test run (NoteLett `7103660`)
- [ ] **E2E cleanup traps** — `trap cleanup EXIT` to prevent orphan items/comments/votes accumulating between runs (FlowMonk `033c2c9`)
- [ ] **Playwright deployed-stack support** — `BASE_URL` switch between local dev and deployed container (FlowMonk `e48e75b`)
- [ ] **`@axe-core/playwright` accessibility tests** — install + wire into Playwright config; `test:e2e:ci` script (FlowMonk `77f9bd9`)
- [ ] **API contract tests** — verify proxy routes match platform-service OpenAPI schema
- [ ] **Cosmos emulator smoke job** in CI — exercise partition-key paths (NoteLett `79e936b`)
- [ ] **Live shared-service smoke** — `pnpm run smoke:local` end-to-end against live platform-service / extraction-service / mcp-server (NoteLett pattern verified `34cb219`)

### 1.6 Error Handling & Observability

- [ ] **Global React error boundary** with friendly fallback — no raw stack traces leaked
- [ ] **Structured server-side logging** via `@bytelyst/logger` on all Next.js API routes
- [ ] **Loki log aggregation** — forward Next.js logs to deployed Loki instance
- [ ] **Prometheus `/metrics` endpoint** — request count, latency p50/p95, error rate
- [ ] **Grafana alert** on health-check failure and error rate > 1 %
- [ ] **Client-side error tracking** via Sentry or `@bytelyst/diagnostics-client`

### 1.7 Security

- [ ] **Security headers audit** — CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy
- [ ] **CSRF tokens on all mutating routes**
- [ ] **API key rotation mechanism** — prerequisite for Phase 3 agent keys
- [ ] **Audit log on every item mutation** — `{ actor, action, field, before, after, timestamp }` append-only log
- [ ] **PII scrubbing in logs** — emails and names must not appear in plaintext log lines
- [ ] **MEK rotation runbook** — operator playbook for rotating the master encryption key (NoteLett `bcad7d3`)
- [ ] **Secret management runbook** — KeyVault → env → process; rotation procedures (NoteLett `bcad7d3`)

### 1.8 Workspace Health 🆕

- [ ] **Pin React + React-DOM to single version** via `pnpm.overrides` — prevents multi-instance React bugs (NoteLett `a83e60a`, FlowMonk `59bc63f`)
- [ ] **Canonicalize `../learning_ai_common_plat` path** in `pnpm-workspace.yaml` + `.pnpmfile.cjs` (NoteLett `b2d824c`)
- [ ] **Resolve React-compiler lint advisories** in tracker-web pages (NoteLett `3c4d46f`)
- [ ] **Remove dead code** surfaced by lint pass (NoteLett `f4564d7`)
- [ ] **Dedicated Playwright `tsconfig.json`** for E2E specs (NoteLett `7ea2c48`)

---

## Phase 2 — Rich Item Details (Linear / Jira parity) 🔲

> **Goal:** Items rich enough for developers, PMs, and agents to fully spec, reproduce, and track
> work without leaving the tool.
> **Target:** Sprint ending 2026-07-12
> **Detailed plan:** `docs/roadmaps/03_RICH_ITEMS_ROADMAP.md` _(to be created when Phase 2 begins)_

### 2.1 UI Primitives Migration to `@bytelyst/ui` 🆕

> Adapted from NoteLett UI5/UI6/UI7/UI8 migration (May 22–23, 2026, `9c65899` … `0c982de`)
> and FlowMonk equivalent (`7083cf0` … `e0de740`).

- [ ] **Add Primitives adapter** — `src/components/ui/Primitives.tsx` re-exports `@bytelyst/ui` components (matches NoteLett + FlowMonk + ChronoMind pattern)
- [ ] **Migrate auth pages + create-item modal** (UI5)
- [ ] **Migrate settings page + all modals** (UI5)
- [ ] **Migrate dashboard, items list, board pages** (UI6)
- [ ] **Migrate item detail, comments, public roadmap pages** (UI7)
- [ ] **Remove legacy global classes** — `.surface-card`, `.surface-muted`, `.badge`, `.input-shell` deleted from `globals.css` (UI8)
- [ ] **Replace all hardcoded color literals** with `--tk-*` CSS variables (tracker design tokens via `@bytelyst/design-tokens`)
- [ ] **Lock direct `@bytelyst/ui` imports outside adapter** in CI via ratchet (Phase 1.3)
- [ ] **Tighten audit regex** + lock CI gate to hard-zero for legacy globals (UI8)

### 2.2 Expanded Item Types & Statuses

- [ ] **New types:** `improvement` · `chore` (fixes B-017)
- [ ] **Custom status workflows** — products define extra statuses beyond the default 5 (e.g., `needs_review`, `blocked`, `in_qa`)
- [ ] **`wont_fix` reason** — mandatory free-text when closing as wont_fix
- [ ] **Reopen flow** — explicit action with required comment; audit-logged

### 2.3 Rich Text & Markdown

- [ ] **Markdown description editor** — live preview, toolbar, keyboard shortcuts
- [ ] **Acceptance criteria checklist** — `- [ ]` items inside description, individually checkable
- [ ] **Steps to reproduce / Expected vs Actual** blocks (bug type only)
- [ ] **Code blocks** — Shiki syntax highlighting in descriptions + comments
- [ ] **`@username` mentions** in comments → in-app + email notification
- [ ] **`source: auto_detected` UI badge** (fixes B-014)

### 2.4 Attachments & Media

- [ ] **File uploads via `@bytelyst/blob`** — screenshots, logs, designs up to 25 MB
- [ ] **Clipboard paste → auto-upload → inline embed**
- [ ] **Video embeds** — Loom / YouTube paste detection
- [ ] **Attachment list** on item detail with filename, size, uploader, download, delete

### 2.5 Relationships & Linking

- [ ] **Linked items:** `blocks` / `is blocked by` / `relates to` / `duplicate of` — bidirectional
- [ ] **Sub-tasks** — child items with progress chip on parent (`3/5 done`)
- [ ] **Milestones** — named groupings with target date
- [ ] **PR / commit links** — GitHub or Gitea URL with live status badge 🔗 _(prerequisite for Phase 3 webhook auto-linking)_
- [ ] **Branch name chip** — auto-suggest `feat/tracker-{id}-{slug}` with copy button
- [ ] **External links** — Notion, Figma, Confluence, CI run URLs

### 2.6 Metadata & Custom Fields

- [ ] **Effort estimate** — Fibonacci points (1 2 3 5 8 13 21) or T-shirt (XS S M L XL)
- [ ] **Time tracking** — log hours; show logged vs estimate; sprint burndown
- [ ] **Due date** — overdue items highlighted red
- [ ] **Environment** — `production` · `staging` · `dev` · `all`
- [ ] **Affected version / Fixed in version**
- [ ] **Watchers / stakeholders** — subscribe to all updates
- [ ] **Custom fields per product** — text/number/date/select; stored in `metadata` map
- [ ] **Colour-coded labels** — hex colour per label rendered as chips
- [ ] **`metadata` map for agent data** — `{ testRunId, commitSha, ciJobUrl }` without polluting core fields

### 2.7 Activity, History & Notifications

- [ ] **Full activity log** per item — every field change, status transition, comment, attachment, PR link recorded with actor + timestamp
- [ ] **Comment reactions** — 👍 ✅ 🔥 💡 ❓
- [ ] **Comment edit + delete** — authors edit within 15 min, admins delete any
- [ ] **Item history diff view** — before/after for description edits
- [ ] **Notification preferences** — per user, per item: all · mentions · status only · none
- [ ] **In-app notification centre** — bell icon, unread count, mark all read

### 2.8 Real-Time Updates

- [ ] **Server-Sent Events (SSE) on item detail** — status, comments, activity log refresh live
- [ ] **Kanban live updates** — card moves and new cards appear in real-time for all viewers
- [ ] **Optimistic UI** — instant client-side apply with toast rollback on server error

### 2.9 Views, Filters & Search

- [ ] **Kanban drag-and-drop** (fixes B-003)
- [ ] **Saved filter views** — name, save, pin to sidebar
- [ ] **Bulk actions** — multi-select → status / assign / label / milestone / delete
- [ ] **Group by** — assignee · label · milestone · priority · type
- [ ] **Timeline / Gantt view**
- [ ] **My items view** — assigned to me · reported by me · watching · mentioned
- [ ] **Global search Ctrl+K** — full-text across all items (per-product for members, all for admin)
- [ ] **Export** — CSV + JSON of any filtered view, all metadata included

---

## Phase 3 — Agent & Automation API 🤖

> **Goal:** First-class REST API for coding agents (Claude Code, Codex, Copilot Workspace) to
> consume, update, and create tracker items — closing the loop between AI-assisted development
> and project management.
> **Target:** Sprint ending 2026-07-26
> **Detailed plan:** `docs/roadmaps/04_AGENT_API_ROADMAP.md` _(to be created when Phase 3 begins)_
> **Dependency:** Phase 2 acceptance-criteria checklist + PR link fields must ship first.

### 3.1 Agent Authentication

- [ ] **API key management UI** (admin) — generate, revoke, rotate; set name + role + product scope + IP allowlist
- [ ] **Agent roles:** `agent-read` · `agent-write` · `ci` · `webhook`
- [ ] **Key usage log** — last-used, request count, error count
- [ ] **Per-key rate limits** — configurable RPM; 429 with `Retry-After`
- [ ] **Key expiry** — optional expiry date, auto-revocation
- [ ] **API versioning** — `/api/agent/v1/`; breaking changes bump version; 6-month support window with `Deprecation` + `Sunset` headers

### 3.2 Agent Item Operations

All routes: `Authorization: Bearer <agent-key>` + `X-Product-Id: {productId}`.

**Pull & Claim**

- [ ] **`GET /api/agent/v1/items`** — list with filters; cursor pagination; `since` for incremental sync
- [ ] **`PATCH /api/agent/v1/items/:id/claim`** — atomic assign + transition to `in_progress`; `409 Conflict` if already claimed

**Create & Update**

- [ ] **`POST /api/agent/v1/items`** — create item; `source` auto-set to `auto_detected`; supports `metadata` map for `{ testRun, commitSha, ciJobUrl }`
- [ ] **`PATCH /api/agent/v1/items/:id/status`** — update with mandatory `reason` and optional `evidenceUrl`
- [ ] **`PATCH /api/agent/v1/items/:id/checklist`** — check/uncheck acceptance-criteria items 🔗 _(requires Phase 2.3)_
- [ ] **`POST /api/agent/v1/items/:id/comments`** — post implementation notes, test results, error logs

**PR Integration**

- [ ] **`PATCH /api/agent/v1/items/:id/pr`** — link or update PR; callable repeatedly as `prStatus` evolves (`open` → `merged` / `closed` / `draft`) and `ciStatus` (`pending` / `success` / `failure` / `cancelled`)

**Context**

- [ ] **`GET /api/agent/v1/items/:id/context`** — full item as LLM-ready markdown; ideal for system-prompt injection

### 3.3 Backend Domain Events 🆕

> Pattern from NoteLett `task.created` + `workspace.created` event emission (`1258d49`).
> Enables outbound webhooks, replay, and event sourcing.

- [ ] **Emit domain events** from `tracker-service` on every mutation: `item.created` · `item.updated` · `item.status_changed` · `comment.added` · `pr.linked` · `pr.status_changed` · `checklist.checked` · `vote.added` · `item.closed`
- [ ] **Event log table** — append-only `events` collection in Cosmos with partition key `productId`
- [ ] **Event replay endpoint** — `POST /api/admin/events/replay?since=...` — admin can replay events to recover state or hydrate new subscribers
- [ ] **Replay preview mode** — dry-run that shows what would happen without applying changes (pattern from FlowMonk runtime `8176395`)

### 3.4 Inbound Webhooks

- [ ] **GitHub webhook receiver** — `POST /api/webhooks/github`
  - PR opened → auto-link to item if branch matches `tracker-{id}` or `feat/tracker-{id}-*`; status → `in_progress`
  - PR merged → status → `done`; post commit SHA + PR URL as comment
  - PR closed without merge → comment noting closure; status unchanged
  - CI check failed → post failure summary + job URL as comment
- [ ] **Gitea webhook receiver** — `POST /api/webhooks/gitea` (identical handling targeting `localhost:3300`)
- [ ] **HMAC-SHA256 signature verification** — reject unsigned requests
- [ ] **Webhook event log** — last 100 inbound events per product; each replayable

### 3.5 Outbound Webhooks

- [ ] **Configuration UI** — register target URLs per product; choose event types
- [ ] **Retry with exponential backoff** — up to 5 retries over 24 h
- [ ] **Delivery log UI** — timestamp, target, event, HTTP status, duration, response snippet
- [ ] **Built-in Slack integration** — formatted item cards on configurable events

### 3.6 Agent SDK & Tooling

- [ ] **`@bytelyst/tracker-client` npm package** — typed Node.js client; auto-pagination, retry, rate-limit backoff
- [ ] **Claude Code hook template** — `PostToolUse` hook that files a tracker bug on test failure
- [ ] **CI integration guide** — GitHub Actions + Gitea Actions example steps
- [ ] **OpenAPI spec** — auto-generated; browsable at `/api-docs`

### 3.7 AI-Assisted Triage

- [ ] **Auto-classify new submissions** — LLM suggests type + priority + labels (human confirms)
- [ ] **Duplicate detection** — embedding similarity against open items; surface "Possible duplicate of #N" if > 0.85
- [ ] **Auto-assign rules** — label-based routing table editable by PM
- [ ] **Sentiment analysis** on public submissions — flag urgent/angry for fast-lane triage
- [ ] **Auto-generate acceptance criteria** 🔗 _(requires Phase 2.3 checklist)_ — LLM suggests starter `- [ ]` list for `feature` + `improvement` items

---

## Phase 4 — Multi-Source Intake 🌐🏢

> **Goal:** Every stakeholder — public users, internal team, developers, agents — has a
> frictionless native path to submit and track items.
> **Target:** Sprint ending 2026-08-09
> **Detailed plan:** `docs/roadmaps/05_INTAKE_ROADMAP.md` _(to be created when Phase 4 begins)_

### 4.1 Public Submission Enhancements 🌐

- [ ] **Optional public account** — email-only signup; track your own submissions; no internal access
- [ ] **Submission status page** — `/submissions/{token}` without login; token emailed on submit
- [ ] **Email notifications** to submitters on status changes
- [ ] **Public changelog** at `/changelog` — auto-generated from `done` + `visibility: public` items grouped by milestone
- [ ] **Vote cap per email per product** — max 5; server-enforced (proper fix for B-004)

### 4.2 Internal Team Intake 🏢

- [ ] **Quick-capture widget** — floating "Report issue" button embeddable in any bytelyst dashboard via `<script>` tag
- [ ] **Browser extension** — one-click bug capture with auto-screenshot + URL
- [ ] **Email-to-tracker** — `tracker+{productId}@bytelyst.com` → creates item; reply threading = comments
- [ ] **Slack `/tracker` slash command** — submit / list from Slack
- [ ] **Microsoft Teams bot** — equivalent for Teams

### 4.3 Developer Intake 🏢

- [ ] **GitHub Issues bidirectional sync** — issues ↔ items; status ↔ labels
- [ ] **Gitea Issues bidirectional sync** — same for `localhost:3300`
- [ ] **`npx @bytelyst/tracker` CLI** — create / list / show from terminal
- [ ] **VS Code extension** — sidebar panel for assigned items, file bugs from editor
- [ ] **CI test-failure auto-item** — Vitest / Jest / Playwright reporter plugin attaches full output

### 4.4 Cross-Product Item Routing 🆕

> NoteLett, FlowMonk, ChronoMind, NomGap, JarvisJr, LysnrAI, LocalMemGPT, MindLyst, Notelett,
> InvtTrdg all use this tracker. Items from CI failures or public submissions may need to be
> routed to the right product.

- [ ] **Product auto-detection** — infer `productId` from PR branch name, CI job URL, or submitter email domain
- [ ] **Re-route action** — admin can move item between products with audit trail
- [ ] **Cross-product duplicate detection** — flag when similar items exist in other products

### 4.5 Import Wizard 🆕

- [ ] **CSV import from Jira / Linear / GitHub Issues** with field-mapping UI — avoids cold-start when migrating

### 4.6 PM / Stakeholder Features 🏢

- [ ] **Roadmap presentation mode** — full-screen, grouped by milestone, shareable read-only link
- [ ] **Sprint planning board** — drag items into sprints; velocity chart
- [ ] **Release notes generator** — from `done` + `public` items in a milestone → draft markdown
- [ ] **Weekly digest email** — per-product opened/closed/blocked + top-voted ideas; Monday delivery

---

## Phase 5 — Analytics & Intelligence 🔲

> **Target:** Sprint ending 2026-08-30

### 5.1 Item Analytics

- [ ] **Cycle time** — time in each status per item; p50/p95/p99 across all items and per-label
- [ ] **Throughput chart** — items closed per week over rolling 12 weeks
- [ ] **Bug burn-down** — open bug count over time with configurable target line
- [ ] **Feature request leaderboard** — ranked by votes; trending velocity this week vs all-time
- [ ] **Agent productivity dashboard** — claimed / closed / abandoned per agent; PR merge rate; avg cycle time vs human

### 5.2 SLA & Alerting

- [ ] **SLA rules** — configurable per priority: `critical` > 4 h, `high` > 24 h, `medium` > 7 days
- [ ] **SLA breach alert** — assignee + PM via in-app + email + webhook
- [ ] **Stale item detector** — no activity for N days → auto-ping assignee
- [ ] **Blocked escalation** — > 3 days blocked → escalate to team lead

### 5.3 Reporting

- [ ] **CSV / PDF export** of any filtered view including custom fields
- [ ] **Scheduled email reports** — daily / weekly / monthly cadence per product
- [ ] **Embeddable public status widget** — `<script>` snippet
- [ ] **Data retention / archival** — archive items > N months; searchable but excluded from live views

---

## Phase 6 — Mobile, Accessibility & i18n 🔲

> **Target:** Sprint ending 2026-09-13

### 6.1 Responsive & Mobile

- [ ] **Fully responsive layout** — all views usable on < 768 px
- [ ] **Touch-friendly Kanban** — drag-and-drop via touch events 🔗 _(requires Phase 2.9 Kanban)_
- [ ] **PWA** — installable; offline read-only access to cached items
- [ ] **Web push notifications** — opt-in browser push for item updates / mentions / SLA breaches

### 6.2 Accessibility — `@axe-core/playwright` in CI 🆕

> Pattern from FlowMonk `77f9bd9`.

- [ ] **WCAG 2.1 AA compliance audit** — full keyboard nav, ARIA roles, contrast ≥ 4.5 : 1
- [ ] **Screen reader tested** — VoiceOver (Safari/macOS) + NVDA (Chrome/Windows)
- [ ] **Focus management** — modal/sheet close returns focus to trigger
- [ ] **Reduced motion** — all animations respect `prefers-reduced-motion`
- [ ] **`@axe-core/playwright` runs in CI** on every PR — fails on any new violation

### 6.3 Theming & Dark Mode 🆕

> Adapted from FlowMonk theme/colors.ts centralization (`81d699c`).

- [ ] **Centralised palette** — single `theme/colors.ts` (or `--tk-*` token set) source of truth
- [ ] **Zero hardcoded hex** in components — enforced by UI drift ratchet (Phase 1.3)
- [ ] **Dark mode** — system-preference aware; manual toggle in user settings
- [ ] **High-contrast theme** for accessibility

### 6.4 Internationalisation

- [ ] **i18n scaffold** — `next-intl` or equivalent; English baseline
- [ ] **RTL support** — Arabic + Hebrew layout flip
- [ ] **Locale-aware date formatting** in activity log and timelines

### 6.5 Native Apps (Stretch)

- [ ] **React Native wrapper** — iOS + Android with push notifications and offline queue

---

## Known Bugs & Gaps ⚠️

Confirmed issues ordered by severity. File new bugs via the [public roadmap](https://tracker.bytelyst.com/roadmap).

| ID    | Severity    | Description                                                                                | Affects      | Phase |
| ----- | ----------- | ------------------------------------------------------------------------------------------ | ------------ | ----- |
| B-001 | 🔴 Critical | `valkey` (Redis) container `unhealthy` — root cause of most downstream failures            | All services | 1.1   |
| B-002 | 🔴 Critical | `platform-service` container `unhealthy` — caused by B-001                                 | All apps     | 1.1   |
| B-003 | 🟠 High     | Kanban has no drag-and-drop — status changes via buttons only                              | Board view   | 2.9   |
| B-004 | 🟠 High     | Vote deduplication is localStorage-only — server has no per-email enforcement              | Roadmap      | 4.1   |
| B-005 | 🟠 High     | No rate limiting on `POST /public/submit` — open to bot spam                               | Roadmap      | 1.4   |
| B-006 | 🟡 Medium   | Description is plain text — no markdown rendering in detail view                           | Item detail  | 2.3   |
| B-007 | 🟡 Medium   | Comment edit/delete not implemented — all comments are permanent                           | Comments     | 2.7   |
| B-008 | 🟡 Medium   | No `@mention` support in comments — no notifications                                       | Comments     | 2.7   |
| B-009 | 🟡 Medium   | `/health` route returns 200 without checking dependencies                                  | Infra        | 1.1   |
| B-010 | 🟡 Medium   | No audit log — no record of field changes with actor + timestamp                           | Item detail  | 1.7   |
| B-011 | 🟡 Medium   | No real-time updates — item detail requires manual refresh for new activity                | Item detail  | 2.8   |
| B-012 | 🟢 Low      | Kanban scroll position lost on page refresh                                                | Board view   | 2.9   |
| B-013 | 🟢 Low      | Product switcher selection lost on hard refresh                                            | Nav          | 2.9   |
| B-014 | 🟢 Low      | `source: auto_detected` items have no UI badge to distinguish them                         | Items list   | 2.3   |
| B-015 | 🟢 Low      | Item detail has no loading skeleton — blank flash before data loads                        | Item detail  | 2.3   |
| B-016 | 🟢 Low      | Public roadmap stats don't refresh after submitting a new idea                             | Roadmap      | 4.1   |
| B-017 | 🟢 Low      | No `improvement` or `chore` item types — everything shoehorned into bug/feature/task       | Item create  | 2.2   |
| B-018 | 🟢 Low      | No global search across items — only per-page search bar                                   | Items list   | 2.9   |
| B-019 | 🟡 Medium   | Hardcoded color literals present in components — should be `--tk-*` tokens                 | UI           | 2.1   |
| B-020 | 🟡 Medium   | Direct `@bytelyst/ui` imports outside an adapter — should route through `Primitives.tsx`   | UI           | 2.1   |
| B-021 | 🟡 Medium   | `NEXT_PUBLIC_*` env vars hardcoded to `api.bytelyst.com` at runtime — should bake at build | Docker       | 1.2   |
| B-022 | 🟡 Medium   | No mobile/responsive layout — desktop-only                                                 | Mobile       | 6.1   |
| B-023 | 🟢 Low      | No i18n — English only                                                                     | All          | 6.4   |

---

## Submission Guide — For All Audiences

### 🌐 Public Users

Visit **[https://tracker.bytelyst.com/roadmap](https://tracker.bytelyst.com/roadmap)** → click
**"Submit an idea"**. No account required. After submitting you receive a link to track your
item without logging in.

### 🏢 Company Team / PMs / Developers

Log in at **[https://tracker.bytelyst.com/login](https://tracker.bytelyst.com/login)**. Go to
**Dashboard → Items → Create**. Set `visibility: internal` to keep it off the public roadmap.

### 🤖 Coding Agents (REST API)

> Agent API keys are managed by admin at `/dashboard/settings/api-keys` _(ships Phase 3)_.

```http
### 1. Pull items labelled for agent work
GET /api/agent/v1/items?status=open&label=agent-ready&limit=10&since=2026-05-20T00:00:00Z
Authorization: Bearer <TRACKER_AGENT_KEY>
X-Product-Id: chronomind

### 2. Claim atomically
PATCH /api/agent/v1/items/{id}/claim
Authorization: Bearer <TRACKER_AGENT_KEY>

### 3. Link your PR
PATCH /api/agent/v1/items/{id}/pr
Content-Type: application/json
Authorization: Bearer <TRACKER_AGENT_KEY>

{
  "prUrl": "https://github.com/org/repo/pull/42",
  "prNumber": 42,
  "prTitle": "fix: null-check avatar in UserCard",
  "prStatus": "open",
  "branch": "fix/tracker-{id}-null-avatar",
  "commitSha": "abc123def456",
  "ciStatus": "pending"
}

### 4. Check off an acceptance criterion
PATCH /api/agent/v1/items/{id}/checklist
Content-Type: application/json
Authorization: Bearer <TRACKER_AGENT_KEY>

{ "item": "Null-check avatar before rendering", "checked": true }

### 5. Post implementation notes
POST /api/agent/v1/items/{id}/comments
Content-Type: application/json
Authorization: Bearer <TRACKER_AGENT_KEY>

{ "body": "Fixed in `UserCard.tsx:42` by adding `avatar ?? defaultAvatar`. Unit test added." }

### 6. Mark done when PR merges
PATCH /api/agent/v1/items/{id}/status
Content-Type: application/json
Authorization: Bearer <TRACKER_AGENT_KEY>

{ "status": "done", "reason": "PR #42 merged to main" }
```

Full OpenAPI spec → **[https://tracker.bytelyst.com/api-docs](https://tracker.bytelyst.com/api-docs)** _(ships Phase 3)_

---

## Cross-Repo Learnings Applied

This roadmap incorporates lessons from the production-readiness sprints in sibling repos:

| Source repo            | Commit range                      | Theme                                                              | Where applied here                             |
| ---------------------- | --------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------- |
| `learning_ai_notes`    | `c75ed3d` → `4798944` (May 22–23) | UI primitives migration, drift ratchet, Docker hardening, runbooks | Phase 1.2, 1.3, 1.7, 1.8, Phase 2.1, Phase 6.3 |
| `learning_ai_flowmonk` | `df9819f` → `81d699c` (May 23)    | Adapted NoteLett playbook, mobile palette, axe-core a11y           | Phase 1.5, Phase 6.2, Phase 6.3                |
| `learning_ai_clock`    | `4f5ee53` → `7ab3287` (May 18–23) | Maintenance mode, fontsource, kill switch                          | Phase 1.6, Phase 1.7                           |

See [`docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`](./PRODUCTION_READINESS_HANDOFF_ROADMAP.md)
for the detailed playbook adapted from NoteLett's 26-commit production-readiness work.

---

## Contributing

1. **File an item** via the [public roadmap](https://tracker.bytelyst.com/roadmap) or the dashboard
2. **Upvote** items you care about — priority is vote-weighted
3. **Comment** with context, edge cases, or design notes
4. **Open a PR** — branch as `feat/tracker-{id}-{slug}` so the inbound webhook auto-links it _(Phase 3.4)_
5. **Mark slice progress** in [`docs/IMPLEMENTATION_TRACKER.md`](./IMPLEMENTATION_TRACKER.md) with commit SHA

---

_Maintained by the ByteLyst platform team · Questions → `platform@bytelyst.com`_