title: Quality Gates, Testing, and Performance Validation

description: Establish verification confidence through unit/integration tests, boundary tests, and performance baselines for parser and realtime workflows.

acceptance_criteria: Core functionality is covered by automated checks and target baselines are recorded.

status: open

issue_type: epic

created_by: zenchantlive

labels: perf quality testing

depends_on_id: bb-ymg

type: blocks

depends_on_id: bb-xhm

depends_on_id: bb-bvn


title: Implement unit tests for parser, pathing, scanner, and bd bridge

description: Add focused fast tests for foundational modules and error handling paths.

acceptance_criteria: Unit tests cover nominal and edge-case logic for each foundational module.

issue_type: task

labels: tests unit

type: parent-child


title: Implement API integration tests for read, mutate, and SSE routes

description: Validate route contracts and interaction boundaries across read/write/realtime layers.

acceptance_criteria: Integration suite verifies route behavior and error semantics.

labels: integration tests


title: Record parser and realtime performance baseline against PRD targets

description: Measure parse latency and update propagation using realistic sample sizes and document outcomes.

acceptance_criteria: Performance report exists with methodology and observed timings.

labels: benchmark perf


title: Document operational runbook and boundary rationale

description: Write architecture docs covering scanner policy, bd bridge behavior, and consistency guardrails for future maintainers.

acceptance_criteria: Runbook documents startup, troubleshooting, and boundary rules.

labels: docs runbook


title: Smoke test mutation lifecycle 2

description: Temporary issue for API mutation smoke test

status: closed

assignee: zenchantlive

close_reason: Cleanup after API smoke test

labels: api smoke

author: zenchantlive

text: Smoke test comment via API route

text: Smoke test reopen


title: Project Registry and Multi-Project Scanner

description: Support multiple Windows project roots using profile-scoped registry storage and safe discovery scanning tuned for developer machines.

acceptance_criteria: Projects can be added/removed/listed and discovered via scanner with deterministic normalization.

labels: multi-project scanner


title: Persist project registry in %USERPROFILE%\\.beadboard\\projects.json

description: Implement read/write management for registry file in user profile path, isolated from repository files and safe for local machine usage.

acceptance_criteria: Registry file is created lazily and survives app restarts.

assignee: agent-a

close_reason: Implemented %USERPROFILE%/.beadboard/projects.json registry persistence with Windows-safe normalization and dedupe.

labels: config registry


title: Implement registry API for add/remove/list operations

description: Expose robust API endpoints with path validation and normalized identity checks to prevent duplicates.

acceptance_criteria: API supports add, remove, list and returns clear validation errors.

close_reason: Implemented /api/projects GET/POST/DELETE with validation, normalization, and registry integration.

labels: api registry


title: Build scanner with profile-root default and depth/ignore controls

description: Scan %USERPROFILE% and user-defined roots for .beads directories with bounded recursion and ignore patterns to protect performance.

acceptance_criteria: Scanner discovers projects without traversing entire drives by default.

assignee: agent-c

labels: performance scanner


title: Add explicit full-drive scan mode for C:/D: by user action

description: Provide an opt-in scan mode for full drive enumeration while retaining safe defaults and progress reporting expectations.

acceptance_criteria: Full-drive scan is only activated explicitly, never by default startup logic.

labels: optional scanner


title: Implement aggregate project issue context model

description: Define normalized project identity payload attached to every issue for cross-project Kanban, timeline, and session views.

acceptance_criteria: Aggregated read output always includes stable project metadata.

close_reason: Added project context model and attached to read issues.

labels: aggregation data-model


title: Foundation and Read/Write Boundary

description: Establish the Windows-native Next.js foundation, canonical Beads schema handling, and strict data boundaries: read from JSONL, write only via bd.exe. This epic defines the non-negotiable invariants that all later work must preserve.

acceptance_criteria: App boots on Windows, schema/parser contracts exist, and no direct issues.jsonl write path exists in code.

close_reason: Completed foundation milestone: bootstrap, licensing/docs, schema contracts, parser, windows path normalization, and write-boundary guardrails.

labels: beadboard foundation windows


title: Bootstrap Next.js 15 + React 19 + TypeScript strict

description: Initialize project scaffold with strict TypeScript, App Router baseline, and repeatable scripts for lint/typecheck/test in PowerShell.

acceptance_criteria: npm install and dev startup work on Windows; strict type checking enabled.

close_reason: Bootstrapped Next.js 15 + React 19 + strict TypeScript; install/typecheck/dev startup verified on Windows.

labels: foundation nextjs


title: Add MIT license and baseline repository docs

description: Add LICENSE and baseline docs that state Windows-native support, read/write boundaries, and required runtime dependencies.

acceptance_criteria: MIT license present and docs describe core architecture constraints.

close_reason: Added MIT license and baseline repository documentation with architecture boundary rules.

labels: docs license


title: Define canonical Beads TypeScript schema types

description: Implement comprehensive issue types covering ids, status, priority, dependencies, timestamps, metadata, and session fields used by dashboard views.

acceptance_criteria: All required PRD fields are represented and reused across parser/API/UI layers.

close_reason: Added canonical Beads TypeScript schema contracts and validated via typecheck contract test.

labels: schema types


title: Implement JSONL parser with defaults and malformed-line tolerance

description: Parse one JSON object per line, skip blank/malformed lines, apply default status/type/priority, preserve priority=0, and filter tombstones by default.

acceptance_criteria: Parser tests cover malformed lines, defaults, and tombstone behavior.

close_reason: Implemented JSONL parser with schema defaults, malformed-line tolerance, and tombstone filtering options.

labels: jsonl parser


title: Add parser tests for priority=0, tombstone filtering, and dependency parsing

description: Create focused tests that protect parser behavior for critical edge cases and dependency structures used by graph/timeline views.

acceptance_criteria: Tests fail before implementation and pass after parser is complete.

close_reason: Added parser behavior tests for defaults, malformed lines, tombstones, and priority=0.

labels: parser tests


title: Implement Windows path normalization utilities

description: Create centralized helpers for canonical path keys, display formatting, and cross-drive normalization to avoid duplicate project identities.

acceptance_criteria: Canonicalization is consistent for C:\ and D:\ style paths.

close_reason: Implemented Windows path normalization utilities with canonicalization, keying, and display transformations.

labels: paths windows


title: Add guardrail test preventing direct writes to .beads/issues.jsonl

description: Enforce read/write boundary by scanning source for forbidden direct file write patterns targeting Beads issue files.

acceptance_criteria: Guardrail test fails on boundary violations and passes when write path uses bd bridge only.

close_reason: Added guardrail scanner and automated test to block direct writes to .beads/issues.jsonl.

labels: guardrail safety


title: TEMP_DELETE_ME

close_reason: cleanup temp test issue


title: Kanban Responsive Design Hardening

description: Refine tracer-bullet Kanban into a production-grade, responsive experience across mobile/tablet/desktop using tokenized Tailwind styling and strict architecture boundaries. Scope includes layout reachability, card/column sizing integrity, improved visual language, and small-screen detail-panel behavior.

acceptance_criteria: At 390x844, 768x1024, and 1440x900 all status columns are reachable, cards are not clipped, controls remain usable, and detail interactions work without direct JSONL write-path regressions.

close_reason: Responsive design hardening scope completed with tests and Playwright evidence.

labels: design-system kanban responsive ui

depends_on_id: bb-trz


title: Rework board responsiveness and horizontal reachability

description: Implement intentional responsive board behavior: fluid column sizing, explicit horizontal board scrolling strategy, and viewport-safe wrappers so every status column is reachable without layout breakage. Use relative sizing constraints and avoid rigid fixed-width assumptions.

acceptance_criteria: Board supports reliable horizontal reachability at all target breakpoints; no hidden/unreachable status columns.

close_reason: Implemented fluid horizontal board reachability with snap and overflow containment across breakpoints.

labels: kanban layout responsive


title: Fix column/card sizing and overflow behavior

description: Correct card and column sizing to prevent clipping, overflow artifacts, and unreadable metadata blocks. Ensure card internals wrap/truncate intentionally and columns maintain consistent density and scroll behavior.

acceptance_criteria: Cards remain fully readable within columns, no clipped card content, and column internals scroll predictably.

close_reason: Fixed card/column overflow and sizing with clamp-based widths, scroll-safe columns, and improved text wrapping.

labels: cards kanban overflow


title: Redesign tokenized theme and visual hierarchy

description: Upgrade visual system quality using semantic tokens for surface/text/status/priority states, stronger typography hierarchy, and improved contrast. Move away from flat/basic palette while preserving clarity and performance.

acceptance_criteria: UI theme shows clear hierarchy and contrast, aligns with premium demo quality expectations, and remains consistent across components.

close_reason: Redesigned semantic tokens/theme contrast and hierarchy to improve production visual quality.

labels: design-system theme tokens


title: Implement mobile/tablet detail panel interaction model

description: Adapt detail panel behavior for small screens (overlay or drawer model) with safe viewport sizing, accessible dismissal, and non-destructive navigation. Desktop retains efficient side-panel behavior.

acceptance_criteria: Detail view is usable on mobile/tablet and does not trap or obscure board interaction irrecoverably.

close_reason: Implemented mobile detail overlay flow while preserving desktop sticky side-detail behavior.

labels: detail-panel mobile ux


title: Playwright multi-breakpoint visual verification

description: Capture and review before/after screenshots at 390x844, 768x1024, and 1440x900 to validate reachability, clipping, control usability, and detail-panel behavior. Store artifacts under artifacts/ with explicit naming conventions.

acceptance_criteria: Required six screenshots exist (before/after x 3 breakpoints) and observations confirm responsive/visual acceptance criteria.

close_reason: Captured required Playwright before/after screenshots at mobile/tablet/desktop and validated layout usability.

labels: playwright verification visual


title: Smoke test mutation lifecycle

description: Temporary issue for API mutation smoke test

labels: api smoke


title: Dependency Graph (React Flow)

description: Visualize issue relationships and blocked chains through an interactive graph backed by parsed dependency edges.

acceptance_criteria: Graph renders dependencies correctly and supports navigation to issue details.

labels: graph react-flow

issue_id: bb-bvn


title: Parse dependency edges and build adjacency structures

description: Extract edges for blocks, parent, relates_to, duplicates, and supersedes to support graph rendering and analysis.

acceptance_criteria: Adjacency output is complete and consistent for all supported edge types.

labels: graph parser


title: Implement React Flow graph view with pan/zoom/select interactions

description: Render nodes and edges with interactive navigation and issue selection integration.

acceptance_criteria: Users can pan, zoom, and select nodes to inspect linked issue context.

labels: graph ui


title: Add blocked-chain highlighting and cycle anomaly signaling

description: Improve graph decision support by emphasizing blocked paths and flagging unexpected cycle conditions.

acceptance_criteria: Blocked paths and cycle warnings are visible and actionable.

labels: analysis graph


title: Live File Watching and SSE Transport

description: Deliver real-time dashboard updates by watching Beads issue files and streaming one-way change notifications via SSE.

acceptance_criteria: File changes trigger UI refresh without manual reload and reconnect behavior is stable.

labels: realtime sse watcher

issue_id: bb-tpc


title: Implement chokidar watch manager for registered projects

description: Start/stop watchers per active project and ensure watcher lifecycle tracks registry changes without leaking handles.

acceptance_criteria: Watcher list updates correctly when projects are added or removed.

labels: chokidar watcher

depends_on_id: bb-tpc


title: Add debounce/coalescing and transient lock handling for file change bursts

description: Coalesce rapid updates from agent activity and handle temporary read lock contention without surfacing noisy errors.

acceptance_criteria: Burst writes produce stable event cadence and no hard failures from temporary locks.

labels: stability watcher


title: Implement SSE events API endpoint with heartbeat and event IDs

description: Create SSE route supporting keepalive heartbeats and resumable event consumption patterns for browser clients.

acceptance_criteria: SSE stream remains alive and clients can reconnect automatically.

labels: api sse


title: Build frontend SSE client with scoped React Query invalidation

description: Consume server events and invalidate only affected query keys, limiting unnecessary re-fetches in multi-project mode.

acceptance_criteria: Changed project views refresh while unrelated views remain stable.

labels: frontend react-query


title: Kanban Experience (Baseline Dashboard)

description: Ship a production-ready Kanban baseline inspired by prototype behavior but backed by real Beads project data and strict typing.

acceptance_criteria: Users can inspect and filter live Beads issues through stable Kanban workflows.

close_reason: Kanban epic complete for tracer bullet 1

labels: kanban ui

issue_id: bb-trz


title: Implement Kanban column layout for Beads statuses

description: Render columns for open, in_progress, blocked, deferred, and closed with responsive behavior and clear status counts.

acceptance_criteria: All statuses map correctly and render with stable ordering.

assignee: agent-b

close_reason: Tracer bullet 1 Kanban baseline implemented and verified

labels: columns kanban


title: Build bead cards with priority/type/labels/assignee/dependency metadata

description: Design compact cards exposing the most actionable issue metadata while preserving readability at high board density.

acceptance_criteria: Cards show id, priority, type, labels, assignee, and dependency indicators.

labels: cards kanban


title: Implement detail slide-out panel with full issue metadata

description: Add focused issue detail panel showing description, timestamps, dependencies, and lifecycle fields used by power users.

acceptance_criteria: Selecting a card opens detail panel with complete issue context.

labels: details kanban


title: Add search/filter/stats controls for status/type/priority/labels

description: Provide fast filtering and at-a-glance counts, including critical issue indicators, for daily planning and triage workflows.

acceptance_criteria: Search and filters apply consistently across board and counts.

labels: filters stats


title: Agent Session Views and Metrics

description: Group work by agent session and actor fields to provide auditability and practical productivity insights for asynchronous coding workflows.

acceptance_criteria: Session-based summaries and detail views are available per project and aggregate contexts.

labels: agents sessions


title: Extract and normalize session identity fields from issue data

description: Derive session grouping from closed_by_session, assignee, and created_by with robust fallback semantics.

acceptance_criteria: Issues are consistently assigned to session buckets when data exists.

labels: agents data


title: Build session list and detail views for claimed/completed/open outcomes

description: Present session-level issue outcomes and navigation for operational review and accountability.

acceptance_criteria: Users can inspect session summaries and drill into individual session issue sets.

labels: agents ui


title: Add baseline productivity metrics (completion rate, throughput, active span)

description: Compute lightweight operational metrics from session issue events and timestamps.

acceptance_criteria: Metrics are available with documented definitions and caveats.

labels: agents metrics


title: Timeline and Activity Feed

description: Provide a chronological activity view derived from issue snapshots and updates, enabling users to review agent/system activity over time.

acceptance_criteria: Users can inspect chronological issue lifecycle events with useful filtering.

labels: activity timeline

issue_id: bb-xhm


title: Define activity event model for created/updated/closed/reopened actions

description: Create stable event schema to represent issue lifecycle transitions and their project/session attribution.

acceptance_criteria: Event model supports all required timeline activity types.

labels: model timeline


title: Implement snapshot diffing for derived timeline events

description: Compare periodic snapshots and watcher updates to infer meaningful change events without requiring write interception.

acceptance_criteria: Diff engine emits deterministic event records for relevant field changes.

labels: diff timeline


title: Build timeline UI with date grouping and project/assignee/event filters

description: Render reverse-chronological feed suitable for morning review workflows with practical filter controls.

acceptance_criteria: Timeline view supports grouping and filter combinations with acceptable performance.

labels: timeline ui


title: CLI Write-Back via bd.exe

description: Enable safe issue mutations from UI by routing all write operations through bd.exe and reflecting results through realtime reconciliation.

acceptance_criteria: No direct JSONL writes exist; all mutations use bd commands and recover cleanly from failures.

labels: bd-cli mutation

issue_id: bb-ymg


title: Implement bd bridge using child_process.execFile with project-scoped cwd

description: Wrap bd execution with command argument safety, Windows path compatibility, stdout/stderr parsing, and project-specific current working directory.

acceptance_criteria: Bridge executes supported bd commands and returns structured result/error payloads.

notes: Implemented src/lib/bridge.ts with execFile-based bd runner, project-scoped cwd, timeout support, structured command result payload, and failure classification (not_found, timeout, bad_args, non_zero_exit, unknown). Added RED->GREEN tests in tests/lib/bridge.test.ts.

close_reason: Bridge implemented with structured result/error classification and project-scoped execFile command execution; tests added.

labels: bridge execfile


title: Resolve bd.exe location from PATH and configuration fallback

description: Add detection logic for bd executable and actionable errors when not found, including setup guidance.

acceptance_criteria: Missing bd path returns clear setup instructions and diagnostics.

notes: Implemented src/lib/bd-path.ts executable resolution with config-first then PATH lookup (bd.exe/bd.cmd/bd.bat/bd), plus actionable setup guidance when missing. Added tests/lib/bd-path.test.ts for success/failure cases.

close_reason: Executable resolution implemented with config/PATH fallback and actionable missing-bd guidance; tests added.

labels: bridge setup


title: Implement mutation API for create/update/close/reopen/comment operations

description: Expose strict server-side mutation endpoints translating UI actions to corresponding bd commands with validated arguments.

acceptance_criteria: All required mutation operations execute via bd and return normalized responses.

notes: Implemented mutation validation/mapping/execution layer in src/lib/mutations.ts and App Router endpoints: /api/beads/create|update|close|reopen|comment. Added payload validation tests, route validation tests, and smoke-tested create/update/comment/close/reopen lifecycle via API.

close_reason: Mutation API implemented for create/update/close/reopen/comment with payload validation, command mapping, normalized error shape, and verified smoke lifecycle via API.

labels: api mutation


title: Add optimistic updates with rollback and SSE reconciliation

description: Apply immediate UI updates for responsiveness, rollback on command failure, and reconcile with watcher-triggered authoritative state updates.

acceptance_criteria: Failed mutations restore previous UI state and emit meaningful error feedback.

labels: optimistic state


title: Implement drag-and-drop status transitions mapped to bd commands

description: Map card moves to valid status transitions and use close/reopen semantics where applicable instead of direct file manipulation.

acceptance_criteria: DnD transitions call proper bd commands and reject invalid transitions safely.

labels: dnd kanban