From a6cd7fe965867eccd62462a2746fd301c56a559b Mon Sep 17 00:00:00 2001 From: root Date: Mon, 25 May 2026 10:51:55 +0000 Subject: [PATCH] =?UTF-8?q?docs(tracker):=20improve=20roadmap=20v2=20?= =?UTF-8?q?=E2=80=94=20gaps/bugs=20addressed?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review pass additions: - Add permissions matrix (public/auth-user/PM/agent per action) - Add improvement + chore item types (B-017) - Add custom status workflows - Add real-time updates section (SSE/WebSocket) โ€” new B-011 - Add global search (Ctrl+K) โ€” new B-018 - Add notification preferences + in-app notification centre - Add optimistic UI callout - Add API versioning strategy (/v1/, Deprecation/Sunset headers) - Add cursor pagination + since-timestamp to agent GET example - Add ciStatus field to PR link payload - Add `metadata` map documented explicitly for agent KV data - Add data retention/archival to Phase 5 - Add import wizard (Jira/Linear/GitHub CSV) to Phase 4 - Add upvote cap (server-side, fixes B-004 properly) to Phase 4 - Fix all tracker URLs to https://tracker.bytelyst.com - Add phase dependency annotations (๐Ÿ”—) on features with prerequisites - Expand bug table: add B-011..B-018, add Phase column - Tighten agent API examples: show response shape, cursor, X-Product-Id header Co-Authored-By: Claude Sonnet 4.6 --- dashboards/tracker-web/ROADMAP.md | 610 +++++++++++++++++++----------- 1 file changed, 386 insertions(+), 224 deletions(-) diff --git a/dashboards/tracker-web/ROADMAP.md b/dashboards/tracker-web/ROADMAP.md index 2f8f86c2..fe012b90 100644 --- a/dashboards/tracker-web/ROADMAP.md +++ b/dashboards/tracker-web/ROADMAP.md @@ -1,28 +1,49 @@ # Tracker Dashboard โ€” Product Roadmap > **Living document.** Coding agents, developers, PMs, and public contributors can submit items -> via the [public roadmap](/roadmap) or the [Agent API](#-agent--automation-api). -> Last updated: 2026-05-25. +> via the [public roadmap](https://tracker.bytelyst.com/roadmap) or the [Agent API](#-agent--automation-api). +> Deployed at **https://tracker.bytelyst.com** ยท Last updated: 2026-05-25. --- ## Legend -| Symbol | Meaning | -| ------ | ----------------------- | -| โœ… | Shipped / complete | -| ๐Ÿ”„ | In progress | -| ๐Ÿ”ฒ | Planned โ€” not started | -| ๐Ÿค– | Agent-targeted feature | -| ๐ŸŒ | Public-facing feature | -| ๐Ÿข | Internal / team feature | -| โš ๏ธ | Known bug / gap | +| Symbol | Meaning | +| ------ | ----------------------------- | +| โœ… | Shipped / complete | +| ๐Ÿ”„ | In progress | +| ๐Ÿ”ฒ | Planned โ€” not started | +| ๐Ÿค– | Agent-targeted feature | +| ๐ŸŒ | Public-facing feature | +| ๐Ÿข | Internal / team feature | +| โš ๏ธ | Known bug / gap | +| ๐Ÿ”— | Depends on another phase item | + +--- + +## 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) | --- ## Phase 0 โ€” Foundation (Current State) โœ… -Everything checked here is already shipped and running. +Everything checked here is already shipped and running at **https://tracker.bytelyst.com**. ### Core Item Management โœ… @@ -66,7 +87,7 @@ Everything checked here is already shipped and running. ### Infrastructure โœ… - [x] Dockerised (standalone Next.js build) -- [x] Caddy reverse proxy with HTTPS +- [x] Caddy reverse proxy with HTTPS (`tracker.bytelyst.com`) - [x] PostHog analytics integration - [x] Vitest unit tests - [x] Playwright E2E scaffolding @@ -81,157 +102,219 @@ Everything checked here is already shipped and running. ### 1.1 โ€” Infrastructure Health โš ๏ธ -- [ ] **Fix platform-service health check** โ€” currently reporting `unhealthy`; diagnose valkey (Redis) โ†’ platform-service dependency chain -- [ ] **Fix valkey container health** โ€” Redis-compatible cache is unhealthy; all session/queue-dependent services degrade -- [ ] **Fix tracker-web health endpoint** โ€” `/health` should verify DB + platform-service connectivity, not just return 200 -- [ ] **Add swap space on VM** โ€” currently 0 B swap; 8 GB minimum to survive build spikes -- [ ] **Kill/limit concurrent CI builds** โ€” Gitea runners spinning up `next build` + `tsc` simultaneously saturate 4-core VM -- [ ] **Add container restart policies** โ€” ensure `restart: unless-stopped` on all services +- [ ] **Fix valkey (Redis) container health** โ€” currently `unhealthy`; root cause of most downstream container failures; all session/queue-dependent services degrade +- [ ] **Fix platform-service health check** โ€” reports `unhealthy` due to valkey connectivity; fix after valkey is stable +- [ ] **Fix tracker-web `/health` route** โ€” must actively probe DB + platform-service reachability, not just return HTTP 200 +- [ ] **Add 8 GB swap space on VM** โ€” currently 0 B swap; build spikes cause OOM-kills of running services +- [ ] **Limit concurrent Gitea CI runner jobs** โ€” cap to 1โ€“2 simultaneous `next build` + `tsc` jobs; 4-core VM cannot survive 4+ parallel builds +- [ ] **Ensure `restart: unless-stopped`** on all docker-compose services โ€” several containers don't auto-recover after VM reboot ### 1.2 โ€” Rate Limiting & Spam Protection ๐ŸŒ -- [ ] **Rate-limit public `/roadmap/submit`** โ€” no throttling today; bots can flood it -- [ ] **Add hCaptcha / Turnstile to public submission form** โ€” prevent bot submissions -- [ ] **Rate-limit public vote endpoint** โ€” deduplicate votes server-side (not just localStorage) -- [ ] **Validate and sanitize all public inputs** โ€” server-side XSS/injection guards +- [ ] **Rate-limit `POST /public/submit`** โ€” no throttling today; minimum 10 req/min per IP +- [ ] **Add Cloudflare Turnstile (or hCaptcha) to public submission form** โ€” bot-proof without user friction +- [ ] **Server-side vote deduplication per email** โ€” current dedup is localStorage-only and trivially bypassed +- [ ] **Validate and sanitise all public inputs server-side** โ€” XSS / injection guard on title, description, name, email ### 1.3 โ€” Test Coverage -- [ ] **Vitest unit tests โ‰ฅ 80% on `src/lib/`** โ€” tracker-client, auth-context, utils -- [ ] **Playwright E2E: login โ†’ create item โ†’ close item** happy path +- [ ] **Vitest unit tests โ‰ฅ 80 % on `src/lib/`** โ€” `tracker-client.ts`, `auth-context.tsx`, `utils.ts` +- [ ] **Playwright E2E: login โ†’ create item โ†’ transition to done** happy path - [ ] **Playwright E2E: public roadmap submit + vote** flow -- [ ] **Playwright E2E: Kanban status drag (when drag implemented)** -- [ ] **API contract tests** โ€” ensure proxy routes match platform-service schema +- [ ] **Playwright E2E: Kanban status transitions** (update after drag-and-drop ships in Phase 2) +- [ ] **API contract tests** โ€” verify proxy routes match platform-service OpenAPI schema ### 1.4 โ€” Error Handling & Observability -- [ ] **Global error boundary with user-friendly fallback UI** โ€” no raw stack traces to users -- [ ] **Structured server-side logging** โ€” use `@bytelyst/logger` on all API routes -- [ ] **Loki log aggregation** โ€” forward Next.js server logs to Loki (already deployed) -- [ ] **Prometheus metrics on tracker-web** โ€” request count, latency, error rate -- [ ] **Alerting** โ€” alert on health-check failures, error rate spikes (Grafana โ†’ webhook) -- [ ] **Sentry (or equivalent) for client-side errors** โ€” catch unhandled React errors +- [ ] **Global React error boundary with friendly fallback** โ€” no raw stack traces leaked to users +- [ ] **Structured server-side logging** via `@bytelyst/logger` on all Next.js API routes +- [ ] **Loki log aggregation** โ€” forward Next.js server logs into the already-deployed Loki instance +- [ ] **Prometheus metrics** โ€” expose `/metrics`; scrape request count, latency p50/p95, error rate +- [ ] **Grafana alert** on health-check failure and error rate > 1 % +- [ ] **Sentry (or `@bytelyst/diagnostics-client`)** for client-side unhandled React errors ### 1.5 โ€” Security -- [ ] **Security headers audit** โ€” CSP, HSTS, X-Frame-Options, Referrer-Policy on all routes -- [ ] **CSRF protection on all mutating API routes** -- [ ] **API key rotation mechanism** โ€” for agent API keys (see Phase 3) -- [ ] **Audit log** โ€” record who changed what on every item mutation -- [ ] **PII scrubbing in logs** โ€” emails, names must not appear in raw log lines +- [ ] **Security headers audit** โ€” CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy +- [ ] **CSRF tokens on all mutating API routes** +- [ ] **API key rotation mechanism** โ€” prerequisite for Phase 3 agent keys +- [ ] **Audit log on every item mutation** โ€” `{ actor, action, field, before, after, timestamp }` written to append-only log +- [ ] **PII scrubbing in logs** โ€” emails and names must not appear in plaintext log lines --- ## Phase 2 โ€” Rich Item Details (Linear / Jira parity) ๐Ÿ”ฒ -> **Goal:** Items rich enough for developers and PMs to fully spec work without leaving the tool. +> **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 -### 2.1 โ€” Rich Text & Markdown +### 2.1 โ€” Expanded Item Types & Statuses -- [ ] **Markdown description editor** โ€” live preview, syntax highlighting, toolbar -- [ ] **Acceptance criteria block** โ€” structured checklist inside item; each criterion is checkable +- [ ] **New item types:** `improvement` (enhances existing feature) ยท `chore` (infra / maintenance / dependency bumps) +- [ ] **Custom status workflows** โ€” products can define extra statuses beyond the default five (e.g., `needs_review`, `blocked`, `in_qa`) +- [ ] **`wont_fix` reason field** โ€” free-text explanation required when closing as `wont_fix` +- [ ] **Reopen flow** โ€” explicit "Reopen" action with mandatory comment; audit-logged + +### 2.2 โ€” Rich Text & Markdown + +- [ ] **Markdown description editor** โ€” live side-by-side preview, toolbar, keyboard shortcuts (bold, italic, code, link) +- [ ] **Acceptance criteria checklist** โ€” structured `- [ ]` items inside description; individually checkable by any team member or agent + ```markdown + ## Acceptance Criteria + + - [ ] User can submit form without login + - [ ] Email confirmation sent within 60 s + - [ ] Duplicate-email server-side check prevents double vote + - [ ] Rate limit returns 429 with `Retry-After` header ``` - Acceptance Criteria - โ˜ User can submit form without login - โ˜ Email confirmation sent within 60s - โ˜ Duplicate email check prevents double-vote - ``` -- [ ] **Steps to reproduce block** (bug type only) โ€” numbered list with copy-as-markdown button -- [ ] **Expected vs Actual behaviour fields** (bug type only) -- [ ] **Code block support in descriptions and comments** โ€” syntax-highlighted fenced blocks -- [ ] **Mention support `@username`** in comments โ†’ notify mentioned user +- [ ] **Steps to reproduce** (bug type only) โ€” numbered list; "Copy as markdown" button +- [ ] **Expected vs Actual behaviour fields** (bug type only) โ€” separate text areas shown side-by-side +- [ ] **Code blocks in descriptions and comments** โ€” syntax-highlighted fenced blocks (Shiki) +- [ ] **`@username` mention in comments** โ†’ in-app + email notification to mentioned user +- [ ] **`source: auto_detected` UI badge** โ€” distinct chip on items filed by CI/agents (fixes B-014) -### 2.2 โ€” Attachments & Media +### 2.3 โ€” Attachments & Media -- [ ] **File upload to items** โ€” screenshots, logs, designs (max 25 MB; stored in blob service) -- [ ] **Image paste from clipboard** โ€” paste screenshot directly into description editor -- [ ] **Video embed support** โ€” paste Loom / YouTube URL โ†’ embed player inline -- [ ] **Attachment list on item detail** โ€” show all files with download + delete +- [ ] **File uploads** โ€” screenshots, logs, designs up to 25 MB; stored via `@bytelyst/blob` service +- [ ] **Clipboard paste into description** โ€” paste screenshot โ†’ auto-upload โ†’ embed as `![image](url)` +- [ ] **Video embed** โ€” paste Loom / YouTube URL โ†’ inline player in description +- [ ] **Attachment list on item detail** โ€” filename, size, uploader, uploaded-at, download, delete -### 2.3 โ€” Relationships & Linking +### 2.4 โ€” Relationships & Linking -- [ ] **Linked items** โ€” `blocks` / `is blocked by` / `relates to` / `duplicate of` -- [ ] **Sub-tasks** โ€” child items under a parent; progress roll-up on parent -- [ ] **Milestones** โ€” group items under a named release milestone with a target date -- [ ] **PR / Commit links** โ€” attach GitHub/Gitea PR URL; show PR title + status badge live -- [ ] **Branch name suggestion** โ€” auto-suggest `feat/tracker-{id}-{slug}` on item detail -- [ ] **External issue links** โ€” link to GitHub issues, Jira, Linear, Notion pages +- [ ] **Linked items** โ€” `blocks` / `is blocked by` / `relates to` / `duplicate of` with bidirectional display on both items +- [ ] **Sub-tasks** โ€” child items nested under parent; parent shows `3/5 done` progress chip +- [ ] **Milestones** โ€” named groupings with a target date; items can be assigned to one milestone +- [ ] **PR / commit links** โ€” attach GitHub or Gitea PR URL; show live PR title + open/merged/closed badge _(prerequisite for Phase 3 webhook auto-linking)_ +- [ ] **Branch name chip** โ€” auto-suggest `feat/tracker-{id}-{slug}` with one-click copy +- [ ] **External links** โ€” arbitrary URL + label pairs (Notion doc, Figma frame, Confluence page, CI run) -### 2.4 โ€” Metadata & Fields +### 2.5 โ€” Metadata & Custom Fields -- [ ] **Effort estimate** โ€” story points (Fibonacci) or T-shirt sizes (XS/S/M/L/XL) -- [ ] **Time tracking** โ€” log hours against an item; total vs estimate -- [ ] **Due date / SLA** โ€” date picker; highlight overdue items in red +- [ ] **Effort estimate** โ€” Fibonacci story points (1 2 3 5 8 13 21) or T-shirt sizes (XS S M L XL); picker on item detail +- [ ] **Time tracking** โ€” log hours per session; show logged vs estimate; per-sprint burndown +- [ ] **Due date** โ€” date picker; overdue items highlighted red in list and Kanban - [ ] **Environment** โ€” `production` ยท `staging` ยท `dev` ยท `all` -- [ ] **Affected version** โ€” free-text; links to release notes -- [ ] **Fixed in version** โ€” auto-populated when item closes and a release is cut -- [ ] **Stakeholders / Watchers** โ€” subscribe to item updates without being assignee -- [ ] **Custom fields** โ€” per-product key-value pairs (product teams define their own) -- [ ] **Colour-coded labels** โ€” labels get hex colour; shown as chips +- [ ] **Affected version** โ€” free-text; displayed as chip; links to changelog +- [ ] **Fixed in version** โ€” auto-populated when item closes within a milestone +- [ ] **Watchers / stakeholders** โ€” subscribe to all item updates without being the assignee +- [ ] **Custom fields** โ€” per-product admin defines field name + type (text, number, date, single-select); stored in `metadata` map +- [ ] **Colour-coded labels** โ€” each label gets a hex colour; rendered as chips in list, Kanban card, and detail views +- [ ] **`metadata` map for agent data** โ€” agents write arbitrary KV pairs (`{ testRunId, commitSha, ciJobUrl }`) without polluting core fields -### 2.5 โ€” Activity & History +### 2.6 โ€” Activity, History & Notifications -- [ ] **Full activity log on every item** โ€” every field change recorded with actor + timestamp +- [ ] **Full activity log per item** โ€” every field change, status transition, comment, attachment, PR link recorded with actor + timestamp ``` - 09:14 saravana โ†’ changed status: open โ†’ in_progress - 09:22 codex-agent โ†’ linked PR #142 - 10:05 saravana โ†’ changed priority: medium โ†’ high + 09:14 saravana status: open โ†’ in_progress + 09:22 codex-agent linked PR #142 (open) + 09:45 codex-agent checklist: "Email confirmation sent within 60 s" โœ… + 10:05 saravana priority: medium โ†’ high + 10:31 codex-agent PR #142 status: open โ†’ merged + 10:31 codex-agent status: in_progress โ†’ done (reason: PR #142 merged) ``` -- [ ] **Comment reactions** โ€” emoji reactions on comments (๐Ÿ‘ โœ… ๐Ÿ”ฅ etc.) -- [ ] **Comment edit + delete** โ€” authors can edit/delete their own comments -- [ ] **@mention notifications** โ€” in-app + email when mentioned in comment -- [ ] **Item history diff view** โ€” show before/after for description edits +- [ ] **Comment reactions** โ€” emoji reactions (๐Ÿ‘ โœ… ๐Ÿ”ฅ ๐Ÿ’ก โ“) on any comment +- [ ] **Comment edit + delete** โ€” authors can edit within 15 min; admins can delete any comment +- [ ] **Item history diff view** โ€” expandable before/after diff for description edits +- [ ] **Notification preferences** โ€” per user, per item: all activity ยท mentions only ยท status changes ยท none +- [ ] **In-app notification centre** โ€” bell icon with unread count; mark-all-read action -### 2.6 โ€” Views & Filters +### 2.7 โ€” Real-Time Updates -- [ ] **Kanban drag-and-drop** โ€” drag cards between status columns (replace button-only transitions) -- [ ] **Saved filter views** โ€” name and save a filter set; pin to sidebar -- [ ] **Bulk actions** โ€” select multiple items โ†’ bulk status change / assign / label / delete -- [ ] **Group by** โ€” group list view by assignee, label, milestone, priority -- [ ] **Timeline / Gantt view** โ€” items with due dates shown on a calendar timeline -- [ ] **My items view** โ€” quick filter: assigned to me / reported by me / watching -- [ ] **Export** โ€” CSV and JSON export of filtered item lists +- [ ] **Server-Sent Events (SSE) on item detail** โ€” status, comments, and activity log refresh live without polling +- [ ] **Kanban board live updates** โ€” card moves and new cards appear in real-time for all active viewers +- [ ] **Optimistic UI** โ€” status/priority changes apply instantly client-side; roll back on server error with toast + +### 2.8 โ€” Views, Filters & Search + +- [ ] **Kanban drag-and-drop** โ€” drag cards between status columns; persist to server immediately (fixes B-003) +- [ ] **Saved filter views** โ€” name, save, and pin a filter combination to the sidebar +- [ ] **Bulk actions** โ€” checkbox-select multiple items โ†’ bulk status change / assign / label / milestone / delete +- [ ] **Group by** โ€” group list view by assignee ยท label ยท milestone ยท priority ยท type +- [ ] **Timeline / Gantt view** โ€” items with due dates on a horizontal calendar; milestones as vertical markers +- [ ] **My items view** โ€” quick filter tabs: assigned to me ยท reported by me ยท watching ยท mentioned in +- [ ] **Global search** โ€” Ctrl+K full-text search across title + description for all products (admin); per-product search for members +- [ ] **Export** โ€” CSV and JSON download of any filtered view; includes all metadata and custom fields --- ## Phase 3 โ€” Agent & Automation API ๐Ÿค– -> **Goal:** First-class API for coding agents (Claude Code, Codex, Copilot, custom agents) to -> consume, update, and create tracker items programmatically โ€” closing the loop between -> AI-assisted development and project management. +> **Goal:** First-class REST API for coding agents (Claude Code, Codex, Copilot Workspace, custom +> agents) to consume, update, and create tracker items โ€” closing the loop between AI-assisted +> development and project management. > **Target:** Sprint ending 2026-07-26 +> **Dependency:** Phase 2 acceptance-criteria checklist and PR link fields must ship first. ### 3.1 โ€” Agent Authentication -- [ ] **API key management UI** โ€” generate / revoke / rotate API keys per agent identity -- [ ] **Agent identity model** โ€” each key has a `name`, `role` (`agent` / `ci` / `webhook`), `productId` scope, and optional IP allowlist -- [ ] **Scoped permissions** โ€” read-only keys, write keys, admin keys -- [ ] **Key usage log** โ€” last-used timestamp, request count per key -- [ ] **Rate limiting per API key** โ€” configurable RPM per key +- [ ] **API key management UI** (admin) โ€” generate, revoke, rotate keys; set name + role + product scope + optional IP allowlist +- [ ] **Agent roles:** `agent-read` ยท `agent-write` ยท `ci` ยท `webhook` โ€” minimum necessary permissions per role (see Permissions Matrix) +- [ ] **Key usage log** โ€” last-used timestamp, request count, error count per key +- [ ] **Rate limits per key** โ€” configurable RPM; `429 Too Many Requests` with `Retry-After` header on breach +- [ ] **Key expiry** โ€” optional expiry date; keys auto-revoked on expiry +- [ ] **API versioning** โ€” all agent routes under `/api/agent/v1/`; breaking changes bump version; old versions supported 6 months with `Deprecation` + `Sunset` headers ### 3.2 โ€” Agent Item Operations -- [ ] **`GET /api/agent/items`** โ€” pull items assigned to agent, by label, by status; supports `since` timestamp for polling +All routes require `Authorization: Bearer ` and `X-Product-Id: {productId}`. + +**Pull & Claim** + +- [ ] **`GET /api/agent/v1/items`** โ€” list items with filters; cursor-based pagination; `since` for incremental sync + ```http - GET /api/agent/items?status=open&label=agent-ready&assignee=codex-agent - Authorization: Bearer - ``` -- [ ] **`POST /api/agent/items`** โ€” agents create items (bug reports from CI, auto-detected regressions) - ```json + GET /api/agent/v1/items?status=open&label=agent-ready&limit=20&cursor=&since=2026-05-20T00:00:00Z + Authorization: Bearer + X-Product-Id: chronomind + + # 200 Response { - "type": "bug", - "title": "TypeError in UserCard on null avatar", - "description": "Reproduced in e2e run #4821. Stack trace: ...", - "source": "auto_detected", - "labels": ["ci-failure", "agent-reported"], - "metadata": { "testRun": "4821", "commitSha": "abc123" } + "items": [...], + "next_cursor": "eyJpZCI6IjEyMyJ9", + "has_more": true, + "total": 47 } ``` -- [ ] **`PATCH /api/agent/items/:id/claim`** โ€” agent claims an item (sets `assignee`, status โ†’ `in_progress`, records claim timestamp); prevents two agents racing on same item -- [ ] **`PATCH /api/agent/items/:id/status`** โ€” update status with a reason and optional evidence -- [ ] **`POST /api/agent/items/:id/comments`** โ€” post implementation notes, test results, error logs -- [ ] **`PATCH /api/agent/items/:id/pr`** โ€” link a PR to an item + +- [ ] **`PATCH /api/agent/v1/items/:id/claim`** โ€” atomically assign to calling agent + transition to `in_progress`; returns `409 Conflict` if already claimed (prevents parallel agent races) + +**Create & Update** + +- [ ] **`POST /api/agent/v1/items`** โ€” create item; `source` auto-set to `auto_detected` + ````json + { + "type": "bug", + "title": "TypeError: Cannot read properties of null (reading 'avatar')", + "description": "Reproduced in E2E run #4821 on `main` at commit `abc123`.\n\n```\nTypeError at UserCard.tsx:42\n```", + "source": "auto_detected", + "priority": "high", + "labels": ["ci-failure", "agent-reported", "frontend"], + "metadata": { + "testRun": "4821", + "commitSha": "abc123def456", + "ciJobUrl": "https://gitea.bytelyst.com/org/repo/actions/runs/4821" + } + } + ```` +- [ ] **`PATCH /api/agent/v1/items/:id/status`** โ€” update status with mandatory `reason` and optional `evidenceUrl` + ```json + { + "status": "done", + "reason": "PR #142 merged", + "evidenceUrl": "https://github.com/org/repo/pull/142" + } + ``` +- [ ] **`PATCH /api/agent/v1/items/:id/checklist`** โ€” check/uncheck acceptance-criteria items by text match ๐Ÿ”— _(requires Phase 2)_ + ```json + { "item": "Email confirmation sent within 60 s", "checked": true } + ``` +- [ ] **`POST /api/agent/v1/items/:id/comments`** โ€” post implementation notes, test results, diffs, error logs + +**PR Integration** + +- [ ] **`PATCH /api/agent/v1/items/:id/pr`** โ€” link or update a PR; callable multiple times as PR status evolves ```json { "prUrl": "https://github.com/org/repo/pull/142", @@ -239,89 +322,127 @@ Everything checked here is already shipped and running. "prTitle": "fix: null-check avatar in UserCard", "prStatus": "open", "branch": "fix/tracker-789-null-avatar", - "commitSha": "abc123def456" + "commitSha": "abc123def456", + "ciStatus": "pending" } ``` -- [ ] **`POST /api/agent/items/:id/checklist`** โ€” update acceptance-criteria checklist items (check/uncheck) -- [ ] **`GET /api/agent/items/:id/context`** โ€” fetch full item context formatted for LLM prompt injection (title + description + acceptance criteria + comments + linked PRs as markdown) + `prStatus`: `open` ยท `merged` ยท `closed` ยท `draft` + `ciStatus`: `pending` ยท `success` ยท `failure` ยท `cancelled` -### 3.3 โ€” Webhook Integration (Inbound) +**Context** + +- [ ] **`GET /api/agent/v1/items/:id/context`** โ€” full item as LLM-ready markdown: title, description, acceptance criteria, comments, linked PRs, activity log; ideal for agent system-prompt injection + + ```markdown + # Tracker #789: TypeError in UserCard on null avatar + + **Status:** open **Priority:** high **Assignee:** unassigned + + ## Description + + ... + + ## Acceptance Criteria + + - [ ] Null-check avatar before rendering + - [ ] Unit test covers null case + - [ ] No snapshot regression + + ## Recent Activity + + 2026-05-25 09:14 saravana: opened + ``` + +### 3.3 โ€” Inbound Webhooks - [ ] **GitHub webhook receiver** โ€” `POST /api/webhooks/github` - - PR opened โ†’ link to item if branch matches `tracker-{id}` pattern; status โ†’ `in_progress` - - PR merged โ†’ status โ†’ `done`; post merge comment on item - - PR closed without merge โ†’ comment on item; status stays - - CI check failed โ†’ post failure summary as comment on linked item -- [ ] **Gitea webhook receiver** โ€” `POST /api/webhooks/gitea` (same events as GitHub) -- [ ] **Webhook signature verification** โ€” HMAC-SHA256 on all inbound webhooks -- [ ] **Webhook delivery log** โ€” show last 100 inbound webhook events per product; replayable + - 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 โ†’ post closure comment; status unchanged + - CI check failed โ†’ post failure summary + job URL as comment on linked item + - CI check passed โ†’ update `ciStatus` on linked PR +- [ ] **Gitea webhook receiver** โ€” `POST /api/webhooks/gitea` (identical event handling, targeting `localhost:3300`) +- [ ] **HMAC-SHA256 signature verification** โ€” reject unsigned inbound webhooks +- [ ] **Webhook event log** โ€” last 100 inbound events per product; each replayable via UI -### 3.4 โ€” Webhook Integration (Outbound) +### 3.4 โ€” Outbound Webhooks -- [ ] **Outbound webhook configuration UI** โ€” register URLs to receive tracker events -- [ ] **Events fired:** `item.created` ยท `item.updated` ยท `item.status_changed` ยท `comment.added` ยท `pr.linked` ยท `item.closed` -- [ ] **Retry with exponential backoff** โ€” retry failed deliveries up to 5ร— over 24 h -- [ ] **Delivery log** โ€” show status of every outbound delivery (200 โœ… / 5xx โŒ / timeout) -- [ ] **Slack integration** โ€” built-in Slack webhook sender; configurable per product +- [ ] **Outbound webhook configuration UI** โ€” register target URLs per product; choose subscribed event types +- [ ] **Events emitted:** `item.created` ยท `item.updated` ยท `item.status_changed` ยท `comment.added` ยท `pr.linked` ยท `pr.status_changed` ยท `checklist.checked` ยท `item.closed` +- [ ] **Retry with exponential backoff** โ€” up to 5 retries over 24 h on non-2xx; final failure fires `webhook.delivery_failed` alert +- [ ] **Delivery log UI** โ€” timestamp ยท target URL ยท event type ยท HTTP status ยท duration ยท response body snippet +- [ ] **Built-in Slack integration** โ€” send formatted item cards to a Slack channel; configurable per product + per event type -### 3.5 โ€” Agent SDK / CLI +### 3.5 โ€” Agent SDK & Tooling + +- [ ] **`@bytelyst/tracker-client` npm package** โ€” typed Node.js client; auto-handles pagination cursor, retry, rate-limit backoff -- [ ] **`@bytelyst/tracker-client` npm package** โ€” typed client for Node.js agents ```ts import { TrackerClient } from '@bytelyst/tracker-client'; - const tracker = new TrackerClient({ apiKey: process.env.TRACKER_KEY, productId: 'chronomind' }); - const items = await tracker.items.list({ status: 'open', label: 'agent-ready' }); - await tracker.items.claim(items[0].id); + + const tracker = new TrackerClient({ + apiKey: process.env.TRACKER_AGENT_KEY, + productId: 'chronomind', + }); + + for await (const item of tracker.items.stream({ status: 'open', label: 'agent-ready' })) { + await tracker.items.claim(item.id); + // ... implement fix ... + await tracker.items.linkPr(item.id, { prUrl, prNumber, prTitle, prStatus: 'open' }); + } ``` -- [ ] **Claude Code hook template** โ€” ready-made `PostToolUse` hook that files a tracker item when tests fail -- [ ] **CI integration guide** โ€” docs + example GitHub Actions step to post build failures as tracker bugs + +- [ ] **Claude Code hook template** โ€” ready-made `PostToolUse` hook that auto-files a tracker `bug` when tests fail; add to `.claude/settings.json` +- [ ] **CI integration guide** โ€” GitHub Actions + Gitea Actions example steps to file bugs and update PR status +- [ ] **OpenAPI spec** โ€” auto-generated; browsable at `/api-docs` ### 3.6 โ€” AI-Assisted Triage -- [ ] **Auto-classify incoming submissions** โ€” LLM call on new public submissions to suggest type + priority + labels -- [ ] **Duplicate detection** โ€” embedding similarity check on new items vs existing open items; surface "possible duplicate of #42" banner -- [ ] **Auto-assign** โ€” configurable rules: items with label `frontend` โ†’ assign to frontend agent; `ci-failure` โ†’ assign to CI agent -- [ ] **Sentiment analysis on public submissions** โ€” flag angry/urgent submissions for faster triage -- [ ] **Auto-generate acceptance criteria** โ€” for feature requests, LLM suggests a checklist based on description +- [ ] **Auto-classify new submissions** โ€” LLM call on every new item suggests `type`, `priority`, `labels`; shown as "AI suggestions" (human confirms or dismisses; never auto-applied) +- [ ] **Duplicate detection** โ€” embedding similarity vs open items; surface "Possible duplicate of #42" if cosine similarity > 0.85 +- [ ] **Auto-assign rules** โ€” configurable routing table: label `frontend` โ†’ `frontend-agent`; label `ci-failure` โ†’ `ci-agent`; editable by PM in settings +- [ ] **Sentiment analysis on public submissions** โ€” flag angry/urgent submissions for fast-lane triage queue +- [ ] **Auto-generate acceptance criteria** ๐Ÿ”— _(requires Phase 2 checklist)_ โ€” LLM suggests starter `- [ ]` checklist for `feature` and `improvement` items; editable before saving --- ## Phase 4 โ€” Multi-Source Intake ๐ŸŒ๐Ÿข -> **Goal:** Every stakeholder โ€” public users, company team, developers, and agents โ€” has a +> **Goal:** Every stakeholder โ€” public users, internal team, developers, and agents โ€” has a > frictionless native path to submit and track items. > **Target:** Sprint ending 2026-08-09 ### 4.1 โ€” Public Submission Enhancements ๐ŸŒ -- [ ] **Public user account (optional)** โ€” create lightweight account to track your own submissions without full platform login -- [ ] **Submission status page** โ€” public URL `/submissions/{token}` shows status of your submitted idea without login -- [ ] **Email notifications to submitters** โ€” "Your idea is now In Progress" / "shipped in v2.3" -- [ ] **Public changelog** โ€” `/changelog` page auto-generated from items closed with `public` visibility + release notes field -- [ ] **Upvote limit per email** โ€” max N votes per product per email to prevent ballot stuffing +- [ ] **Optional public account** โ€” lightweight sign-up (email only) to track your own submissions; no access to internal items +- [ ] **Submission status page** โ€” `/submissions/{token}` shows item status without login; token emailed on submit +- [ ] **Email notifications to submitters** โ€” "Your idea moved to In Progress" / "Shipped in v2.3! Thanks for the report." +- [ ] **Public changelog** โ€” `/changelog` auto-generated from `done` + `visibility: public` items grouped by milestone +- [ ] **Vote cap** โ€” max 5 votes per email per product; server-enforced (proper fix for B-004) ### 4.2 โ€” Internal Team Intake ๐Ÿข -- [ ] **Quick-capture widget** โ€” floating button on any internal bytelyst dashboard โ†’ pre-fills product + reporter; one-click submit -- [ ] **Browser extension** โ€” capture bugs from any web page with screenshot + URL auto-filled -- [ ] **Email-to-tracker** โ€” send email to `tracker+{product}@bytelyst.com` โ†’ creates item; threading = comments -- [ ] **Slack `/tracker` slash command** โ€” submit item from Slack; subscribe to updates in channel -- [ ] **Microsoft Teams bot** โ€” same as Slack integration (for teams using Teams) +- [ ] **Quick-capture widget** โ€” floating "Report issue" button embeddable in any internal dashboard via `