Quality Gates, Testing, and Performance Validation

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

Feature lanes are only closed after passing tests, capturing visual evidence, and documenting smoke-check results.

Definition of done locked (2026-02-12): every completed feature lane requires automated tests + visual screenshots + runtime smoke checks before close.


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

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

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


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

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

Integration suite verifies route behavior and error semantics.


Record parser and realtime performance baseline against PRD targets

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

Performance report exists with methodology and observed timings.


Document operational runbook and boundary rationale

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

Runbook documents startup, troubleshooting, and boundary rules.


Epic Design Gate: scope, decisions, and acceptance contract

Design/discovery gate for bb-29x before further implementation.

Must capture:
- Product intent and user outcomes for this epic
- Explicit architecture decisions and tradeoffs
- API/data contracts and edge cases
- Windows-specific constraints and path/process assumptions
- Test strategy and verification commands
- Non-goals and out-of-scope boundaries

Completion rule:
Do not start new implementation tasks in this epic until this gate is closed with agreed decisions.

A written execution-grade plan exists for this epic and all child task descriptions are updated with concrete implementation details, dependencies, and testable acceptance criteria.


Smoke test mutation lifecycle 2

Temporary issue for API mutation smoke test

Smoke test comment via API route

Smoke test reopen


Project Registry and Multi-Project Scanner

Deliver a Windows-first multi-project registry and discovery pipeline: persist project roots in the user profile, expose add/remove/list APIs, and scan safe roots to find .beads directories. Normalize all paths to stable identity keys and support aggregate views without full-drive traversal by default.

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


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

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

Registry file is created lazily and survives app restarts.

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


Implement registry API for add/remove/list operations

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

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

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


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

Implement a scanner that searches for .beads directories under %USERPROFILE% and any user-added roots. Enforce bounded recursion depth, ignore patterns (e.g., node_modules, .git, .next, dist, build), and de-duplicate results by normalized path. Return discovered project roots with source metadata and summary counts while avoiding drive-wide enumeration.

Scanner discovers projects without traversing entire drives by default.

Implemented scanner + /api/scan with safe defaults and full-drive mode.


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

Add an explicit opt-in scan mode that enumerates entire drives (C:\ and D:\) only when the user requests it. Provide progress feedback and guardrails so this mode never runs on startup or default scan paths, and clearly label it as potentially slow.

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

Added explicit full-drive scan mode gated by mode=full-drive.


Implement aggregate project issue context model

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

Aggregated read output always includes stable project metadata.

Added project context model and attached to read issues.


Design/discovery gate for bb-6aj before further implementation.

Must capture:
- Product intent and user outcomes for this epic
- Explicit architecture decisions and tradeoffs
- API/data contracts and edge cases
- Windows-specific constraints and path/process assumptions
- Test strategy and verification commands
- Non-goals and out-of-scope boundaries

Completion rule:
Do not start new implementation tasks in this epic until this gate is closed with agreed decisions.

Intent: Provide Windows-native multi-project discovery using registry + scanner with safe defaults; never scan full drives unless explicitly requested.

Decisions:
- Scan roots: %USERPROFILE% + registry entries; optional full-drive mode adds C:\ and D:\ only when mode=full-drive.
- Bounded recursion (default maxDepth=6) and ignore list to protect performance.
- Normalize paths with canonicalizeWindowsPath/windowsPathKey; dedupe by key.
- API contract: GET /api/scan?mode=default|full-drive&depth=<int> returns { mode, roots, projects, stats }.

Edge cases:
- Missing/unreadable directories are skipped (ENOENT/ENOTDIR/EACCES/EPERM) without aborting scan.
- Invalid mode/depth returns 400.

Windows constraints:
- Use drive-letter paths only; no Unix assumptions.

Testing:
- scanner.test.ts covers default roots, full-drive roots, ignore list, and depth limits.
- npm test to verify.

Non-goals:
- No background watcher or SSE here.
- No default full-drive scan.

Captured scanner design/contract and verification plan.


Foundation and Read/Write Boundary

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.

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

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


Bootstrap Next.js 15 + React 19 + TypeScript strict

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

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

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


Add MIT license and baseline repository docs

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

MIT license present and docs describe core architecture constraints.

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


Define canonical Beads TypeScript schema types

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

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

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


Implement JSONL parser with defaults and malformed-line tolerance

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

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

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


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

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

Tests fail before implementation and pass after parser is complete.

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


Implement Windows path normalization utilities

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

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

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


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

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

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

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


TEMP_DELETE_ME


Writeback phase smoke

Temp for optimistic and transition smoke

transition smoke reopen


Kanban Responsive Design Hardening

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.

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.

Responsive design hardening scope completed with tests and Playwright evidence.


Rework board responsiveness and horizontal reachability

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.

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

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


Fix column/card sizing and overflow behavior

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.

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

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


Redesign tokenized theme and visual hierarchy

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.

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

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


Implement mobile/tablet detail panel interaction model

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.

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

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


Playwright multi-breakpoint visual verification

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.

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

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


Smoke test mutation lifecycle

Temporary issue for API mutation smoke test

UI visibility test complete: reopening


Dependency Graph (React Flow)

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

Graph defaults to 2-hop focused context and remains readable; deterministic layout, typed edges, and depth controls are implemented; mobile fallback is simplified and usable.

Product baseline locked (2026-02-12): Graph UX will use React Flow with deterministic DAG layout (no chaotic freeform). Default depth is 2 hops from selected issue with controls for 1 hop / 2 hops / full. Mobile uses simplified dependency focus view (selected + immediate blockers/dependents); desktop/tablet uses full graph workspace.


Parse dependency edges and build adjacency structures

Build graph data preparation pipeline for dependency workspace.

Scope:
- Input: parsed Bead issues from read layer only (`readIssuesFromDisk`).
- Build normalized node map keyed by issue id.
- Build typed edge list from `dependencies[]` supporting: blocks, parent, relates_to, duplicates, supersedes.
- Include reverse index (incoming/outgoing) to support focus queries.
- Preserve issue metadata needed by UI nodes: id, title, status, priority, issue_type, assignee, updated_at.

Rules:
- Ignore dependency edges that point to missing issue IDs but record count for diagnostics.
- Deduplicate duplicate edges (same source, target, type).
- Treat path/project context as explicit API argument for future multi-project support.
- Do not mutate source issues.

Output contracts:
- `GraphModel = { nodes, edges, adjacency, diagnostics }`
- `adjacency` includes incoming/outgoing arrays per node.
- `diagnostics` includes counts for missing targets and dropped duplicates.

Test plan:
- Unit tests for edge extraction across all supported types.
- Unit tests for dedupe and missing-target behavior.
- Unit tests for adjacency correctness and deterministic ordering.

- Graph model contains all valid nodes and typed edges from issue dependencies.
- Duplicate edges are removed deterministically.
- Missing-target edges do not crash model generation and are surfaced in diagnostics.
- Adjacency maps are correct for incoming/outgoing lookups.
- Unit tests cover all supported dependency types and edge cases.


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

Implement deterministic React Flow graph UI (non-chaotic workspace mode).

Scope:
- New graph page/view with React Flow canvas.
- Deterministic auto-layout (DAG style) for stable mental model:
  - selected node centered in focus mode
  - upstream blockers left, downstream dependents right
- Use card-like nodes (not bubbles) with minimal status accent.
- Edge styling by dependency type:
  - blocks: solid
  - parent: thicker muted
  - relates_to: dashed
  - duplicates/supersedes: distinct but subtle styles

Interaction:
- Click node opens shared detail panel.
- Controls: hop depth switch (1/2/full), collapse closed, fit-to-selection.
- Disable freeform drag by default to avoid n8n-like chaos (optional manual toggle can be deferred).

Responsive behavior:
- Desktop/tablet: full canvas + detail panel split.
- Mobile: simplified dependency focus mode (selected + immediate blockers/dependents list) instead of dense full canvas.

Integration:
- Read-only against graph model from bb-bvn.1.
- No writeback from graph lane.

Test/verification:
- Component tests for control toggles and selected-node behavior.
- Guard test for responsive fallback contract.
- Playwright screenshots: mobile/tablet/desktop graph view.

- Graph renders with deterministic layout and typed edges.
- Default depth is 2 hops with controls for 1/2/full.
- Node selection opens detail panel and fit-to-selection works.
- Mobile shows simplified focus view (no unusable dense canvas).
- Visual verification screenshots captured for mobile/tablet/desktop.


Add blocked-chain highlighting and cycle anomaly signaling

Add analysis overlays for blocker triage and anomaly visibility.

Scope:
- Compute and highlight blocked chains from selected node.
- Show concise blocker summary:
  - open blocker count
  - in-progress blocker count
  - first actionable blocker
- Cycle/anomaly signaling:
  - detect cycles in dependency graph
  - mark involved nodes/edges with warning style and explanation text

UI behavior:
- "Show blocking path only" toggle to reduce noise.
- Hovering a node/edge highlights direct dependency chain.
- Keep styling subtle and readable; avoid visual overload.

Rules:
- Analysis is read-only and derived from current graph model.
- Must not fail hard on malformed dependency data; degrade with warnings.

Test plan:
- Unit tests for blocked-chain derivation and cycle detection logic.
- UI tests for toggle behavior and warning visibility.
- Screenshot verification for normal and anomaly cases.

- Selected issue can display clear blocked-chain context.
- Cycle/anomaly conditions are detected and visibly flagged.
- Blocking-path-only mode materially reduces graph noise.
- Analysis features remain performant and do not break base graph rendering.
- Tests and screenshots verify normal + anomaly paths.


Epic Design Gate: scope, decisions, and acceptance contract

Design/discovery gate for bb-bvn before further implementation.

Must capture:
- Product intent and user outcomes for this epic
- Explicit architecture decisions and tradeoffs
- API/data contracts and edge cases
- Windows-specific constraints and path/process assumptions
- Test strategy and verification commands
- Non-goals and out-of-scope boundaries

Completion rule:
Do not start new implementation tasks in this epic until this gate is closed with agreed decisions.

A written execution-grade plan exists for this epic and all child task descriptions are updated with concrete implementation details, dependencies, and testable acceptance criteria.

Graph design gate completed: agreed React Flow deterministic UX, default 2-hop depth controls, mobile simplified fallback, typed edge semantics, and verification contract (tests + screenshots + smoke). Child tasks bb-bvn.1/.2/.3 updated with execution-grade details.

Design gate complete: bb-bvn child tasks now contain concrete scope, contracts, dependencies, and testable acceptance criteria.


SSE smoke 1770870992420


Live File Watching and SSE Transport

Realtime transport epic to deliver deterministic file-change propagation from .beads/issues.jsonl(.new) into the Kanban UI.

Scope boundaries:
- Read source remains disk JSONL via read-issues; no bd CLI reads.
- Mutation/write path remains bd.exe only (already implemented in bb-ymg).
- This epic adds one-way change detection + push invalidation, not business-rule mutation logic.

Implementation contract:
1) Watch manager (`src/lib/watcher.ts`)
- Uses chokidar to monitor `<projectRoot>/.beads/issues.jsonl` and `.beads/issues.jsonl.new`.
- Normalizes project roots with existing Windows path helpers.
- Supports start/stop per project and global cleanup for tests/dev reloads.
- Emits typed change events with monotonic event ids and timestamps.

2) Burst and lock stability (`bb-tpc.2`)
- Debounce/coalesce rapid write bursts into one logical event per project window.
- Treat transient lock/read contention as retryable (EBUSY/EPERM) in read path.

3) SSE server (`src/app/api/events/route.ts`)
- `text/event-stream` endpoint with heartbeat and `id:` fields.
- Optional `projectRoot` filter for scoped subscribers.
- Cleans up subscriptions and timers on disconnect.

4) Frontend subscriber (`bb-tpc.4`)
- EventSource client reconnect behavior handled by browser defaults.
- On event, re-fetch affected project issues and reconcile local state.
- No direct JSONL polling loops after SSE is active.

Non-goals in this epic:
- WebSocket transport.
- Cross-process durable event bus.
- React Query migration (deferred; current lane keeps existing local fetch/reconcile pattern).

- Editing `.beads/issues.jsonl` externally triggers UI refresh in <1s without manual reload.
- SSE stream remains connected with periodic heartbeat; reconnect path resumes safely.
- Event stream and watcher code use Windows-safe path normalization.
- No direct JSONL writes introduced (guard still passes).
- `npm run typecheck`, `npm run test`, `npm run dev` pass.

Decoupled bb-tpc baseline from scanner epic: current implementation is project-scoped via query projectRoot and does not require registry integration. Multi-project watcher orchestration remains under scanner follow-up tasks.

Completed watcher/SSE tracer end-to-end for project-scoped realtime updates with tests and smoke checks.


Implement chokidar watch manager for registered projects

Implement `src/lib/watcher.ts` watch manager for project-scoped issue files.

Scope:
- Watch both `<projectRoot>/.beads/issues.jsonl` and `<projectRoot>/.beads/issues.jsonl.new`.
- Support startWatch(projectRoot), stopWatch(projectRoot), stopAll().
- Ensure idempotent start behavior (no duplicate watchers for same canonical root).
- Emit typed events into in-process realtime bus with:
  - id (monotonic)
  - projectRoot (canonical path)
  - kind (changed|renamed)
  - path
  - at (ISO timestamp)

Implementation notes:
- chokidar with `ignoreInitial: true` and Windows-safe normalized paths.
- Maintain internal map keyed by windowsPathKey(projectRoot).
- Route event -> coalescer (bb-tpc.2), not direct SSE writes.

Test plan:
- Unit tests verify idempotent lifecycle and key normalization behavior.
- Unit tests verify events from both jsonl candidates are accepted.

- Starting watch for same project twice creates one active watcher.
- Stopping watch removes watcher and prevents further events.
- Events include canonical project root and unique monotonic event id.
- Watch target includes both `.beads/issues.jsonl` and `.beads/issues.jsonl.new`.

Implemented src/lib/watcher.ts with chokidar manager, idempotent start/stop lifecycle, windowsPathKey normalization, and dual-file watch targets (.jsonl + .jsonl.new). Added tests/lib/watcher.test.ts.

Watcher lifecycle manager implemented with canonical project scoping and tested watch behavior.


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

Implement debounce/coalescing + transient lock resilience for realtime updates.

Scope:
- Coalesce rapid filesystem bursts into a single logical change event per project in a short window (e.g. 100-250ms).
- Suppress duplicate events for same project/path within the same window.
- Handle transient file lock contention in read layer with bounded retry for EBUSY/EPERM before surfacing failure.

Integration points:
- Coalescer sits between watcher and SSE broadcaster.
- Read retry applied in `readIssuesFromDisk` path used by UI reconciliation.

Test plan:
- Unit tests for coalescer burst behavior (N events => 1 broadcast).
- Unit tests for lock retry logic and eventual success/failure behavior.

- Burst writes within debounce window produce one emitted project event.
- Distinct project events are not incorrectly merged.
- Transient EBUSY/EPERM reads are retried with bounded backoff.
- Permanent read errors still surface as explicit failures.

Implemented src/lib/coalescer.ts for burst event coalescing and integrated in watcher manager. Added src/lib/read-text-retry.ts and wired readIssuesFromDisk to retry transient lock errors (EBUSY/EPERM). Added tests/lib/coalescer.test.ts and tests/lib/read-text-retry.test.ts.

Burst coalescing and transient lock retry behavior implemented and covered by tests.


Implement SSE events API endpoint with heartbeat and event IDs

Implement SSE endpoint at `src/app/api/events/route.ts` backed by in-process event bus.

Scope:
- Response headers: `Content-Type: text/event-stream`, `Cache-Control: no-cache, no-transform`, `Connection: keep-alive`.
- Emit named events (`event: issues`) with `id:` and JSON payload.
- Heartbeat comments at fixed cadence to keep intermediaries alive.
- Support optional `projectRoot` query filter so client receives only scoped updates.
- Cleanup subscriber + heartbeat resources on request abort.

Event payload contract:
{
  id: number,
  projectRoot: string,
  changedPath?: string,
  at: string
}

Test plan:
- Unit tests for SSE formatting helper and filter matching.
- Route-level test ensures proper content-type and streaming status.

- SSE endpoint responds with valid event-stream headers.
- Each issue update includes event id + timestamp payload.
- Subscriber cleanup occurs on disconnect without leaks.
- Project filter limits event delivery to matching subscribers.

Implemented SSE route at src/app/api/events/route.ts with event-stream headers, connected frame, heartbeats, issue event frames, projectRoot filtering via bus subscription, and cleanup on abort/cancel. Added tests/api/events-route.test.ts + tests/lib/realtime.test.ts.

SSE transport endpoint implemented with heartbeat/id frames and lifecycle cleanup.


Build frontend SSE client with scoped React Query invalidation

Implement frontend realtime subscriber in Kanban page.

Scope:
- Create EventSource subscription to `/api/events?projectRoot=...`.
- Listen for `issues` events and trigger authoritative refresh (`/api/beads/read`).
- Guard against duplicate subscriptions and ensure cleanup on unmount/project change.
- Preserve current optimistic mutation flow and reconcile after both mutation success and realtime events.

Failure handling:
- Do not hard-fail UI on temporary SSE disconnect.
- Keep page usable while EventSource auto-reconnects.

Test plan:
- Unit test(s) for event payload parsing and refresh trigger behavior.
- Guard checks confirm no direct JSONL writes and existing UI contracts remain intact.

- Kanban refreshes automatically after external issue file changes.
- EventSource subscription lifecycle is clean across mount/unmount.
- Mutation UX remains functional with realtime enabled.
- No regression to existing guard/test suite.

Integrated EventSource subscription in src/components/kanban/kanban-page.tsx. On issues events, Kanban performs authoritative refresh from /api/beads/read while preserving optimistic mutation flow.

Frontend SSE subscriber implemented with auto-refresh reconciliation and clean subscription lifecycle.


Design/discovery gate for bb-tpc before further implementation.

Must capture:
- Product intent and user outcomes for this epic
- Explicit architecture decisions and tradeoffs
- API/data contracts and edge cases
- Windows-specific constraints and path/process assumptions
- Test strategy and verification commands
- Non-goals and out-of-scope boundaries

Completion rule:
Do not start new implementation tasks in this epic until this gate is closed with agreed decisions.

Readiness pass complete: child tasks now include scope boundaries, contracts, failure handling, and test plans. Execution order: .1 watcher lifecycle -> .2 coalescing/retry -> .3 SSE endpoint -> .4 frontend subscriber.

Design gate satisfied with execution-grade contracts and explicit verification strategy for watcher/SSE lane.


Kanban Experience (Baseline Dashboard)

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

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

Product baseline locked (2026-02-12): Default landing view is Kanban for fast triage. Primary user is solo dev supervising multi-agent work. Project scope defaults to one project with explicit aggregate toggle.

Kanban epic complete for tracer bullet 1


Implement Kanban column layout for Beads statuses

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

All statuses map correctly and render with stable ordering.

Tracer bullet 1 Kanban baseline implemented and verified


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

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

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


Implement detail slide-out panel with full issue metadata

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

Selecting a card opens detail panel with complete issue context.


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

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

Search and filters apply consistently across board and counts.


Agent Session Views and Metrics

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

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

Product baseline locked (2026-02-12): Agent-session features should optimize for solo supervisor workflows (who changed what, when, and why) with clear per-agent accountability and low-noise summaries.


Extract and normalize session identity fields from issue data

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

Issues are consistently assigned to session buckets when data exists.


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

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

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


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

Compute lightweight operational metrics from session issue events and timestamps.

Metrics are available with documented definitions and caveats.


Design/discovery gate for bb-u6f before further implementation.

Must capture:
- Product intent and user outcomes for this epic
- Explicit architecture decisions and tradeoffs
- API/data contracts and edge cases
- Windows-specific constraints and path/process assumptions
- Test strategy and verification commands
- Non-goals and out-of-scope boundaries

Completion rule:
Do not start new implementation tasks in this epic until this gate is closed with agreed decisions.


Timeline and Activity Feed

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

Users can inspect chronological issue lifecycle events with useful filtering.

Product baseline locked (2026-02-12): Timeline is secondary to Kanban (not default landing). It should support solo-dev live supervision and focus on actionable event stream clarity rather than exhaustive noise.


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

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

Event model supports all required timeline activity types.


Implement snapshot diffing for derived timeline events

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

Diff engine emits deterministic event records for relevant field changes.


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

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

Timeline view supports grouping and filter combinations with acceptable performance.


Design/discovery gate for bb-xhm before further implementation.

Must capture:
- Product intent and user outcomes for this epic
- Explicit architecture decisions and tradeoffs
- API/data contracts and edge cases
- Windows-specific constraints and path/process assumptions
- Test strategy and verification commands
- Non-goals and out-of-scope boundaries

Completion rule:
Do not start new implementation tasks in this epic until this gate is closed with agreed decisions.

A written execution-grade plan exists for this epic and all child task descriptions are updated with concrete implementation details, dependencies, and testable acceptance criteria.


CLI Write-Back via bd.exe

Write-back architecture for BeadBoard.

Scope:
- All issue mutations must execute through bd.exe commands.
- No direct writes to .beads/issues.jsonl are permitted anywhere in app code.
- Mutation flow includes create/update/close/reopen/comment.

Design decisions:
- Process execution uses child_process.execFile with arg arrays (no shell interpolation).
- Commands run with project-scoped cwd so each request targets the intended repo.
- Executable resolution supports explicit configured path and PATH fallback.
- API responses are normalized with stable ok/error shape for frontend and tests.
- UI writeback uses optimistic updates with rollback and authoritative re-read.

Implemented artifacts:
- src/lib/bd-path.ts
- src/lib/bridge.ts
- src/lib/mutations.ts
- src/app/api/beads/{create,update,close,reopen,comment}/route.ts
- src/app/api/beads/read/route.ts
- src/lib/writeback.ts
- Kanban drag-and-drop transition wiring in components.

Acceptance contract:
1) Source tree has no direct issues.jsonl write path (guard test passes).
2) Bridge returns structured command result including classification for timeout/not_found/non_zero_exit/bad_args.
3) Mutation routes validate payloads and map operations to bd commands.
4) Reopen and comment flows are supported and verified.
5) Optimistic status updates rollback on failure and reconcile from authoritative read endpoint.
6) typecheck + test + dev + mutation smoke lifecycle all pass.

Write-back epic unblocked and complete: bridge, mutation API, optimistic transitions, and drag/drop flows are implemented and verified.


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

Bridge layer requirements and implementation.

Command execution contract:
- Uses execFile(command, args, options) with windowsHide and timeout.
- Uses projectRoot as cwd for all commands.
- Returns structured payload: success, classification, command, args, cwd, stdout, stderr, code, durationMs, error.

Error model:
- not_found: executable missing / ENOENT.
- timeout: ETIMEDOUT, killed process, or SIGTERM timeout path.
- bad_args: non-zero exits with invalid/unknown/usage style stderr.
- non_zero_exit: non-zero exits not classified as bad_args.
- unknown: fallback classification.

Verification:
- tests/lib/bridge.test.ts covers success and all key failure classes.

Acceptance contract:
- Bridge command execution is shell-safe and Windows-path-safe.
- Structured result schema is stable and consumed by mutation layer.
- Timeout and failure classes are deterministic under test.

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.

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


Resolve bd.exe location from PATH and configuration fallback

Executable resolution contract.

Resolution order:
1) explicit configured executable path (request/config)
2) PATH scan for bd.exe, bd.cmd, bd.bat, bd

Failure behavior:
- Throw actionable guidance when missing, including install command:
  npm install -g @beads/bd
- Error message explicitly mentions explicit path when provided but invalid.

Verification:
- tests/lib/bd-path.test.ts validates config-first behavior, PATH lookup, and missing executable guidance.

Acceptance contract:
- Resolver is deterministic for config and PATH inputs.
- Missing executable guidance is actionable and user-readable.

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.

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


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

Mutation API contract and mapping.

Supported operations:
- create, update, close, reopen, comment

Validation:
- Payload shape validation enforces required fields and basic constraints.
- update requires at least one mutable field.
- status values are constrained to board-supported statuses.

Command mapping:
- create -> bd create <title> [flags] --json
- update -> bd update <id> [flags] --json
- close  -> bd close <id> [-r reason] --json
- reopen -> bd reopen <id> [-r reason] --json
- comment -> bd comments add <id> <text> --json

Response shape:
- { ok, operation, command, error? }
- command field always includes normalized bridge result.

Verification:
- tests/lib/mutations.test.ts and tests/api/mutations-routes.test.ts
- Runtime smoke lifecycle executed across create/update/close/reopen/comment.

Acceptance contract:
- Every mutation route maps to bd.exe only.
- Invalid payloads return explicit bad_args responses.
- Reopen and comment operations are first-class and tested.

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.

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


Add optimistic updates with rollback and SSE reconciliation

Optimistic writeback behavior.

Frontend mutation strategy:
- Apply optimistic status update to local issue state.
- Mark issue as pending during command execution.
- On failure: rollback to previous issue snapshot and surface mutation error.
- On success: fetch authoritative issue list from /api/beads/read and replace local state.

Rationale:
- Preserves responsive UX without violating source-of-truth boundary.
- Reconciliation avoids stale local drift when external agents mutate files.

Verification:
- tests/lib/writeback.test.ts for transition planning and optimistic updater helpers.
- Runtime mutation smoke tests confirm end-to-end lifecycle.

Acceptance contract:
- Failed mutation restores prior local state.
- Successful mutation reconciles to authoritative read response.
- Pending state prevents repeated conflicting transitions.

Implemented optimistic status updates with rollback in Kanban page, per-issue pending state, and authoritative reconciliation via new GET /api/beads/read endpoint after successful mutations.

Optimistic board updates with rollback and authoritative post-mutation reconciliation via read route implemented and validated.


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

Kanban drag-and-drop transition semantics.

Transition planner rules:
- Any -> closed: use close command.
- closed -> open: use reopen command.
- closed -> in_progress|blocked|deferred: reopen then update target status.
- open|in_progress|blocked|deferred between non-closed states: update status.

UI behavior:
- Drag start attaches issue id/status metadata.
- Drop lane executes planned mutation steps in order.
- Lane card pending state is shown while mutation is in flight.

Verification:
- tests/lib/writeback.test.ts transition planning cases.
- Runtime smoke checks for close/reopen/update transition chain.

Acceptance contract:
- DnD invokes valid bd command sequence for each source->target status.
- Invalid/no-op transitions do not emit unnecessary commands.
- Pending safeguards prevent duplicate conflicting moves.

Implemented lane drag-and-drop interactions in Kanban board, status transition planning (including closed -> reopen+update), and mapped transitions to bd mutation API routes with pending-state safeguards.

Kanban lane drag-and-drop transitions now map to bd-backed close/reopen/update mutations with transition planner tests and runtime smoke validation.