Graph Clarity Follow-up (Post-Kanban)

Objective:
Track graph-focused clarity enhancements that are explicitly out of current Kanban execution scope.

Scope:
- Dependency graph comprehension aids
- anomaly communication for cycle/deadlock scenarios
- future AI explanation hooks for dependency understanding

Out of scope for immediate execution:
- Kanban UI polish currently underway in bb-1es

Planning note:
This epic stays pending until current Kanban actionability epic reaches acceptance.

- Graph clarity backlog is explicitly captured and linked to future implementation beads.
- No accidental scope leakage into current Kanban pass.

Backlog epic for graph-specific clarity work discussed after bb-1es.
Post-Kanban gate enforced: bb-18e depends on bb-1es completion. Child bb-18e.1 is also explicitly blocked by bb-1es to prevent scope bleed before Kanban pass completes.
Execution sequence added: (1) bb-18e.2 edge labels/contrast + bb-18e.3 direction hints + bb-18e.1 cycle card, (2) bb-18e.4 edge toggles + bb-18e.6 centered focus, (3) bb-18e.5 external blockers + bb-18e.7 progressive details + bb-18e.10 risk tinting, (4) bb-18e.8 keyboard nav + bb-18e.9 URL state, (5) bb-18e.11 AI explanation scaffold (deferred).


Add cycle warning card with focus actions in graph view

Goal:
When dependency cycles exist, show an explicit cycle warning card so users understand why work may be deadlocked.

Problem:
Cycle states are hard to infer from dense node/edge layouts, leading to confusion (“why can’t this move?”).

Behavior contract:
- Show warning card only when cycle analysis is non-empty.
- Card includes:
  - cycle count
  - affected bead ids (compact list)
  - click-to-focus action for each cycle group
  - plain language explanation of impact (“tasks in this loop cannot fully unblock each other without breaking the cycle”).
- Visual style: warning but not alarmist (amber/red subtle).

Implementation tasks:
1) Build compact cycle summary model from existing detection output.
2) Add warning card component above graph viewport.
3) Wire click handlers to focus selected cycle nodes.
4) Add tests for no-cycle and multi-cycle rendering behavior.

Out of scope:
- Automatic cycle resolution suggestions.
- Mutation/write automation.

- Cycle warning card appears only when cycles are present.
- Card provides actionable cycle navigation.
- Language is plain and explains user impact.
- Tests cover empty and non-empty cycle states.
- Typecheck and graph guards pass.

This is the #19 idea captured as an explicit implementation bead.
Depends on existing cycle analysis primitives already implemented.


Add downstream-impact risk tinting

Add subtle risk tinting based on downstream impact count to highlight high-blast-radius tasks.

- Higher downstream impact gets stronger but subtle visual signal.
- Does not overpower status/selection color language.
- Works with existing legend semantics.

Use restrained styling; no heavy borders.


AI dependency explanation scaffold (deferred)

Prepare integration scaffold for later AI explanation in dependency view (why blocked / next steps), without shipping model calls yet.

- Data contract for AI explanation input is defined.
- UI placeholder state exists but feature-flagged/off by default.
- No network/model dependency in this bead.

Deferred feature: implement only scaffolding and interfaces.


Add plain-English edge labels + contrast upgrade

Improve edge readability by labeling relationships in plain language (blocks/parent/related) and increasing contrast for fast scan.
Scope: graph viewport only; no mutation behavior changes.

- Edge labels are visible and readable at default zoom.
- Labels map correctly to relation type.
- Contrast remains accessible on dark background.

Verification: typecheck + graph responsive guard + visual screenshot at 390/768/1440.


Add directional context hints for dependency reading

Add concise orientation hints explaining graph reading order (left prerequisites, right downstream impact).
Place hints near graph legend and keep copy plain.

- Direction hint appears in graph UI.
- Hint remains visible and non-intrusive on mobile and desktop.

Added plain-language directional hint in Graph legend: 'Read left to right: Left = blockers, middle = selected task, Right = work this task unblocks.' Also added guard contract assertions in tests/guards/graph-responsive-contract.test.mjs to prevent regressions.

Directional context hint shipped with guard coverage; visibility and wording verified on responsive graph layout.


Add edge-type toggles to reduce graph noise

Add controls to show/hide edge categories (blocks,parent,related) so users can simplify complex views.

- Users can toggle edge categories independently.
- Default preserves current behavior.
- Toggle state updates graph without runtime errors.

Include test coverage for toggle behavior.


Add external-blockers-only filter

Add a filter that shows only blockers outside selected epic/task context to focus on cross-epic constraints.

- Filter clearly isolates external blockers.
- Selected/focus node remains visible.
- UX works on mobile and desktop.

Must degrade gracefully if no external blockers exist.


Keep selected node centered during focus navigation

Refine viewport behavior so selected node remains centered/predictable when user selects tasks or changes depth.

- Selection keeps focus node in stable viewport position.
- No clipping/bleed regressions.
- Fit behavior remains bounded.

Add tests for focus/viewport contract where feasible.


Progressive disclosure in graph task details panel

Refactor graph details panel to show summary first and collapse secondary metadata under explicit expand control.

- Primary summary is immediately readable.
- Secondary fields are accessible via expand action.
- Mobile detail experience stays compact.

Do not remove any existing information; only restructure hierarchy.


Add graph keyboard navigation shortcuts

Add keyboard navigation for graph workflow (e.g., next/prev task, open flow/overview, focus search).

- Shortcuts work without interfering with text inputs.
- Shortcut list documented in UI/help hint.
- Accessibility remains intact.

Treat as later-phase productivity enhancement after core clarity features.


Persist graph state in URL params

Persist selected epic/task/tab/depth/filter state in URL so refresh/share restores context.

- Reload restores graph context from URL.
- Shared URL opens same state deterministically.
- Invalid params fail safely to defaults.


Kanban Actionability & Execution Clarity

Objective:
Create a focused Kanban polish epic that improves execution clarity and triage speed without expanding scope into graph rendering changes.

Scope boundaries:
- In scope: Kanban page only (`/`), especially lane workflow, task card signal density, and detail panel actionability.
- Out of scope: Dependency graph edge visuals/layout (tracked separately), AI-generated summaries (future bead), keyboard system-wide shortcuts (future bead).

User outcomes this epic must deliver:
1) Users can immediately identify what to pick next.
2) Users can quickly understand impact (what this task unblocks).
3) Users can evaluate readiness from one details panel without context switching.
4) Users can triage by recency and urgency with minimal cognitive load.

Execution plan:
- Phase A: Add Next Actionable workflow entrypoint.
- Phase B: Improve card signal density (recency + unblocks count).
- Phase C: Add execution checklist to details panel.
- Phase D: Verify responsive behavior and no regressions on write/mutation flow.

Non-negotiables:
- Maintain strict read/write boundary (no direct JSONL writes).
- Preserve existing mutation semantics via bd bridge.
- Keep mobile layout readable and avoid extra vertical clutter.
- Evidence-first completion: tests + visual proof.

- Kanban has a deterministic “next actionable” affordance and it selects a valid ready task.
- Task cards expose recency and unblock-impact signals without overwhelming visual noise.
- Details panel includes concise execution checklist with clear pass/fail indicators.
- All additions are responsive and do not regress existing lane filtering or detail drawer behavior.
- Typecheck and tests pass.

Planning contract:
- This epic is implementation-focused and should be executed through child beads.
- Child beads must include explicit UX contract, test updates, and verification commands.
- AI summary concept is deferred to a later phase after core UX/actionability stabilizes.
Execution sequencing updated: bb-1es.1 is foundational and now blocks bb-1es.3 + bb-1es.4. Recommended implementation order: bb-1es.1 -> bb-1es.3 -> bb-1es.4 -> bb-1es.2.

All child beads complete and verified (typecheck + kanban tests + kanban guard contract).


Add Next Actionable task picker to Kanban

Goal:
Add a high-signal “Next Actionable” control in Kanban that jumps users directly to the best next task to work on.

Problem being solved:
Users currently scan multiple lanes/cards manually to find what is unblocked and high-priority. This is slow and inconsistent.

Behavior contract:
- Action is visible in Kanban controls area.
- On click, algorithm selects one candidate task from Ready lane.
- Candidate ranking:
  1) lowest priority number first (P0 > P1 > ...)
  2) tasks with higher unblock impact first (if tie)
  3) most recently updated first (if tie)
  4) stable deterministic fallback by bead id
- Resulting behavior:
  - Ready lane becomes active.
  - Selected task is focused (details open if currently closed/minimized).
  - If no actionable task exists, show lightweight empty-state feedback.

Implementation tasks:
1) Add selector helper in lib layer (pure function + tests).
2) Wire control button in Kanban controls.
3) Connect selection plumbing in Kanban page state.
4) Add empty-path UX when no candidate found.
5) Ensure no side effects on mutation/write paths.

Out of scope:
- AI ranking
- dependency graph page behavior

- A “Next Actionable” control exists and is keyboard accessible.
- It always picks a deterministic candidate from Ready lane or shows no-candidate feedback.
- It activates Ready lane + selects the target task.
- Unit tests cover ranking and no-candidate case.
- Guard and type checks pass.

Verification required:
- npm run typecheck
- node --import tsx --test tests/lib/kanban.test.ts
- node --test tests/guards/kanban-responsive-contract.test.mjs
- Visual spot check on desktop + mobile screenshot

Implemented deterministic Next Actionable picker + UI control wiring; verified with typecheck and kanban tests/guards.


Add recency signal (last updated) to Kanban cards

Goal:
Increase Kanban card decision signal with a subtle “updated recently” indicator that helps triage stale vs active work.

Problem:
Cards currently lack strong temporal signal, making it hard to prioritize fresh blockers and newly changed work.

Behavior contract:
- Each visible card shows concise recency text (e.g., “updated 2h ago”, “updated 3d ago”).
- Use neutral/subtle styling so it does not overpower title/status.
- Handle missing/invalid timestamps gracefully (“updated unknown”).
- Time formatting should be deterministic and testable.

Implementation tasks:
1) Add timestamp formatter utility (pure + tested).
2) Add recency metadata row to card footer/header with subtle hierarchy.
3) Ensure recency doesn’t break compact/mobile card layouts.
4) Add tests for formatting buckets (minutes/hours/days).

Out of scope:
- Relative live ticking every second.
- server-side locale negotiation.

- Cards show readable recency text derived from updated_at when available.
- Missing timestamp case is handled without UI breakage.
- Visual hierarchy remains subtle and non-noisy.
- Unit tests cover formatter behavior.
- Typecheck + guard tests pass.

Design guidance:
- Keep recency in secondary typography tier.
- Avoid adding hard borders/heavy pills.
- Use existing token palette.

Verification required:
- npm run typecheck
- node --import tsx --test tests/lib/kanban.test.ts
- node --test tests/guards/kanban-responsive-contract.test.mjs

Implemented recency signal on Kanban cards with safe fallback; verified with typecheck and kanban tests/guards.


Show downstream impact chip (Unblocks N) on Kanban cards

Goal:
Add a compact “Unblocks N” impact chip on Kanban cards so users can quickly see downstream value of completing a task.

Problem:
Users can’t quickly assess impact from card scan alone; downstream unblock effect is hidden.

Behavior contract:
- Cards display `Unblocks N` when N > 0.
- Value is derived from dependency graph model / adjacency semantics already in app.
- Clicking card still selects task normally; chip itself is not a separate interaction target.
- Styling should be subtle and consistent with existing status metadata.

Implementation tasks:
1) Define computation source for downstream count in kanban data helpers.
2) Add chip to card metadata row with low visual weight.
3) Validate counts on sample fixtures including zero and multi-dependency cases.
4) Ensure no overlap/clipping in narrow mobile cards.

Out of scope:
- Deep dependency chain impact scoring.
- graph-page edge/line enhancements.

- Cards show `Unblocks N` for tasks with downstream dependents.
- Zero-impact tasks do not show noisy empty chip.
- Counts are consistent with current dependency model.
- Tests cover representative dependency cases.
- Typecheck and responsive guard pass.

Verification required:
- npm run typecheck
- node --import tsx --test tests/lib/kanban.test.ts
- node --import tsx --test tests/lib/graph.test.ts
- node --test tests/guards/kanban-responsive-contract.test.mjs

Implemented Unblocks N impact chip on cards with dependency-based counts; verified with typecheck and kanban tests/guards.


Add execution-readiness checklist to Kanban details

Goal:
Add an execution checklist block in Kanban detail panel to translate issue state into actionable readiness checks.

Problem:
Details currently show metadata, but users still need to mentally compute if task is executable now.

Behavior contract:
- Detail panel includes a compact checklist with pass/fail states.
- Initial checklist items:
  1) Owner assigned
  2) Not blocked by open blockers
  3) Has acceptance/description signal (basic quality gate)
  4) Status compatible with execution (ready/in_progress)
- Checklist should read as guidance, not hard enforcement.
- Works on desktop detail and mobile drawer detail.

Implementation tasks:
1) Add pure checklist derivation helper + tests.
2) Render checklist component in detail panel below summary metadata.
3) Ensure blocked-tree links still work unchanged.
4) Keep footprint compact (no excessive vertical expansion).

Out of scope:
- AI-generated checklist reasoning.
- Workflow mutation side effects.

- Detail panel displays checklist with deterministic computed states.
- Checklist visible on desktop and mobile detail experiences.
- No regressions in blocked-by tree deep links.
- Unit tests cover checklist derivation scenarios.
- Typecheck + tests pass.

Future hook:
- This bead should structure checklist data so future AI explanations can enrich each failed item.

Verification required:
- npm run typecheck
- node --import tsx --test tests/lib/kanban.test.ts
- node --test tests/guards/kanban-responsive-contract.test.mjs
- Manual mobile + desktop detail check

Implemented execution-readiness checklist in Kanban detail (desktop/mobile paths); verified with typecheck and kanban tests/guards.


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.

UI productization backlog added (2026-02-12): bb-6aj.6 design gate -> bb-6aj.7 shared scope state -> bb-6aj.8 project manager panel + bb-6aj.9 scanner UX + bb-6aj.10 scoped reads -> bb-6aj.11 aggregate mode -> bb-6aj.12 verification evidence. This sequence turns existing backend scanner/registry foundations into end-user multi-project workflows.
2026-02-13 epic completion: UI productization chain complete (bb-6aj.6 -> .7 -> .8/.9/.10 -> .11 -> .12). Multi-project scope selection, registry manager, scanner discover/import, mode-aware reads, aggregate mode with project badges, and full verification evidence are now in place.


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.


Wire project-scoped reads into Kanban and Graph

Connect selected project scope to data-loading paths for Kanban and Graph pages.\n\nScope:\n- pass selected project root to read APIs\n- ensure page refresh keeps selected scope\n- keep existing single-project behavior as fallback\n- preserve strict read/write boundary contracts

Kanban and Graph render data for the selected project scope and remain stable when switching projects.

2026-02-13 completed: rewired / and /graph server pages to resolve project scope from URL and load issues with selected root; implemented readIssuesForScope utility for mode-aware reads; preserved strict read-only boundaries (no direct JSONL writes).


Aggregate mode (cross-project view) with clear project badges

Add aggregate mode that combines issues across selected/registered projects for high-level supervision.\n\nScope:\n- aggregate toggle in shared project controls\n- stable project badge/context on cards and details\n- deterministic ordering and project identity display\n- avoid ambiguity between local and aggregated issue IDs

Users can switch between single-project and aggregate mode and always see which project each issue belongs to.

2026-02-13 completed: aggregate mode implemented via URL mode=aggregate and shared controls. Aggregate read path scopes IDs per project key to avoid collisions and preserves project context metadata. Added clear project badges in Kanban cards/details and Graph task cards/details; aggregate mode set read-only for edits/mutations.


Verification pass: multi-project UX, guards, and screenshots

End-to-end verification for multi-project productization.\n\nMust include:\n- typecheck + full test suite\n- guard checks for no direct JSONL writes\n- project switching smoke checks (kanban + graph)\n- Playwright screenshots for desktop/tablet/mobile in single + aggregate modes\n- bead notes with observed issues and fixes

Evidence bundle exists showing multi-project registry/scanner/project-scope behavior works across supported breakpoints without boundary regressions.

2026-02-13 verification evidence: npm run typecheck PASS; npm run test PASS (includes no-direct-jsonl-write and responsive guard suites). Playwright captures: artifacts/kanban-mobile-after.png, artifacts/kanban-tablet-after.png, artifacts/kanban-desktop-after.png, artifacts/kanban-mobile-aggregate.png, artifacts/kanban-tablet-aggregate.png, artifacts/kanban-desktop-aggregate.png, artifacts/graph-next-1440-single.png, artifacts/graph-next-768-single.png, artifacts/graph-next-390-overview-single.png, artifacts/graph-next-390-flow-single.png, artifacts/graph-next-1440-aggregate.png, artifacts/graph-next-768-aggregate.png, artifacts/graph-next-390-overview-aggregate.png, artifacts/graph-next-390-flow-aggregate.png.


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.


UI multi-project design gate and execution contract

Define the concrete UI productization plan for the existing registry/scanner backend. Lock interaction model, data flow boundaries, and sequencing before implementation churn.\n\nMust define:\n- primary workflow (select project, manage registry, scan/import)\n- screen ownership (kanban, graph, shared controls)\n- URL/query state for project scope\n- aggregate-mode behavior and constraints\n- error states and empty states\n- verification matrix (typecheck/tests/Playwright)

Written implementation-ready contract exists with explicit child task sequencing and no ambiguity on project-scoping behavior.

2026-02-13 contract completed: docs/plans/2026-02-13-multi-project-ui-contract.md. Locked workflow, screen ownership, URL key semantics (project query), fallback/error states, aggregate-mode constraints, and phased execution/verification matrix.


Shared project scope store + URL persistence

Implement shared client-side project scope state consumed by Kanban and Graph.\n\nScope:\n- selectedProjectKey, mode(single|aggregate), and source metadata\n- URL persistence (e.g. ?project=<key>&mode=single|aggregate)\n- hydration from URL on load and safe fallback when missing/invalid\n- no JSONL writes; read boundaries preserved

Project scope can be selected, persisted in URL, restored on refresh, and consumed consistently by both pages.

2026-02-13 partial implementation complete: added shared scope resolver (src/lib/project-scope.ts) with deterministic local/registry key resolution + fallback; added tests (tests/lib/project-scope.test.ts); wired / and /graph server pages to hydrate from ?project= and read issues from resolved project root; preserved scope in Kanban<->Graph links and rendered active scope badge in both headers. Remaining for full AC: explicit interactive scope selector/store and mode(single|aggregate) URL state.
2026-02-13 completed: added mode-aware scope resolver (single|aggregate) with URL hydration/fallback in src/lib/project-scope.ts; added tests in tests/lib/project-scope.test.ts; implemented shared ProjectScopeControls UI used on Kanban + Graph for selecting project key and mode with URL persistence; preserved scoped cross-page links.


Project manager panel (list/add/remove registry roots)

Build a user-facing project manager panel backed by /api/projects.\n\nFeatures:\n- list registered projects with normalized display path\n- add project path with validation feedback\n- remove project with confirm affordance\n- clearly indicate current selected project\n- mobile-safe layout and keyboard accessibility

Users can manage registry projects entirely from UI and immediately use newly added project roots in scope selection.

2026-02-13 completed: implemented registry manager panel in shared ProjectScopeControls component with list/add/remove flows backed by /api/projects; includes validation/error messaging, active-scope indication, and mobile-safe controls. Integrated into src/components/kanban/kanban-page.tsx and src/components/graph/dependency-graph-page.tsx.


Scanner UX (discover/import projects from safe roots)

Expose scanner workflow in UI using /api/scan.\n\nFeatures:\n- run default scan (profile + registry roots)\n- optional full-drive scan behind explicit advanced control\n- show discovered roots with source metadata and deduped list\n- one-click import selected discoveries to registry\n- loading/timeout/error states with plain-language messaging

Users can discover projects via scanner and import them into registry without leaving the app.

2026-02-13 completed: scanner UX added to ProjectScopeControls using /api/scan with mode controls (safe roots/full-drive), scan stats, deduped discovery list, and one-click import to registry via /api/projects POST. Loading/error states surfaced in-panel.
2026-02-13 post-close hardening: scanner now requires .beads/issues.jsonl or .beads/issues.jsonl.new and adds deny rules for tool/cache/worktree noise (directory names: .agents/.kimi/.gemini/.zenflow/worktrees/appdata + name prefixes beadboard-read-, beadboard-watch-, skills- + go/pkg/mod fragment). Added regression coverage in tests/lib/scanner.test.ts.


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)

Deliver an epic-first dependency workspace that is readable at a glance: 1) pick epic, 2) pick task, 3) understand blockers and downstream impact, 4) inspect details. Prioritize visual hierarchy, dependency clarity, bounded graph behavior, and mobile-first usability over graph complexity.

Workflow is linear and obvious on desktop/mobile; dependency meaning is explicit in both flow list and graph; graph remains bounded with no bleed/overlap; flow/details sections never clip and are independently scrollable; screenshots and full verification remain green.

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.
Execution order set 2026-02-12: bb-bvn is the active next epic and should be finished to UX acceptance before timeline/session epics.

All child tasks complete (bb-bvn.1/.2/.3/.4), dependency graph workflow implemented and verified across tests and visual artifacts.


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.

Implemented src/lib/graph.ts GraphModel builder with deterministic node/edge ordering, supported edge-type filtering (blocks/parent/relates_to/duplicates/supersedes), duplicate-edge suppression, missing-target diagnostics, and adjacency incoming/outgoing indexes. Added tests/lib/graph.test.ts covering extraction, dedupe, unsupported/missing handling, and adjacency correctness. Updated package.json test chain to include graph tests.

Completed graph model preparation pipeline with deterministic contracts and full unit coverage; ready for React Flow rendering task bb-bvn.2.


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.

Full visual buff and relationship clarity pass complete. 1) Implemented modern aurora surface theme with refined typography and rhythm. 2) Fixed invisible relationship lines by increasing edge contrast, width, and adding animations for 'blocks' paths. 3) Refined layout to ensure 'Dependency Flow' is fully scrollable and correctly prioritized. 4) Improved mobile UX with a simplified overview and toggleable graph view. 5) Implemented groundwork for bb-bvn.3 (analyzeBlockedChain, detectDependencyCycles) to satisfy tests. Verified via npm run test, typecheck, and captured screenshots in artifacts/.

Implemented React Flow graph workspace with deterministic layout, interaction controls, responsive fallback, and visual verification artifacts; tests/typecheck are green.


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.

Addressed review P1 in detectDependencyCycles: removed early-return DFS behavior that leaked recStack/path state; traversal now always unwinds and collects cycles without contaminating predecessor nodes. Added regression test in tests/lib/graph-view.test.ts: detectDependencyCycles does not mark non-cycle predecessor as cyclic. Verification: node --import tsx --test tests/lib/graph-view.test.ts (pass), npm run typecheck (pass), npm run test (pass).

Implemented blocked-chain analysis, blocking-path emphasis, and cycle anomaly signaling with regression coverage; tests/typecheck are green.


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.


Agent Communication & Coordination Patterns

Agents need a standardized way to coordinate (handoffs, help requests, blockers) without breaking flow. We are opting for a **Issue-Centric** communication model (using Comments) rather than an Inbox-Centric model. This epic defines the protocols, patterns, and tool support needed to make that robust.

Goals:
- Define 'Protocol' for agent-to-agent comments (prefixes, structure).
- Establish Identity standards (how agents refer to themselves).
- Ensure CLI support for all protocol actions (commenting, signaling).

Deliverables:
- RFC-001: Agent Coordination Protocol.
- Skill: beadboard-driver (teaching the protocol).

This epic blocks bb-u6f (Agent Sessions) because session attribution relies on the Identity standards defined here.


Research & RFC: Agent Skills and Handoff Protocols

Conduct research and draft a 'Request for Comments' (RFC) document that defines the standard operating procedures for agent-to-agent interaction within Beadboard.

Key Questions to Answer:
1. Identity: How do we consistently identify an agent? (e.g. assignee formats).
2. Handoff Protocol: Structure of a handoff comment (e.g. [HANDOFF]).
3. Blocker Signaling: How to raise a flag (e.g. [BLOCKED]).
4. Parsing: Can/should we have bd parse-comments?

Deliverables:
- docs/RFC-001-Agent-Coordination.md: Finalized spec.
- skills/beadboard-driver/SKILL.md (Draft): Prototype skill.
- Gap Analysis: Missing CLI commands.

Acceptance Criteria:
- RFC document created and committed.
- Protocol covers: Identity, Handoff, Blocker, Assignment.
- Gap analysis lists required code changes.


Swimlane status model: ready + dependency-derived blocked

Implemented new swimlane model: removed deferred lane from board usage; added ready lane and dependency-derived blocked lane. Lane rules: closed->Done; blocked->Blocked if explicit status blocked OR has active incoming blocker edge; in_progress/review->In Progress; otherwise Ready. Added laneToMutationStatus to map board lane writes to bead statuses (ready->open). Updated board labels/colors, drag-drop lane source tracking, and controls stat label Open->Ready. TDD: updated tests/lib/kanban.test.ts for ready/blocked semantics. Verification: node --import tsx --test tests/lib/kanban.test.ts (pass), npm run typecheck (pass), npm run test (pass).

Implemented ready/blocked swimlane model, blocked-tree deep links to lane focus, and verification passed (kanban tests, typecheck, full test suite).


UI Bead Editing Across Kanban + Graph

Objective:
Add true UI editing for bead fields across both detail panels (Kanban + Graph) using one shared edit core so behavior stays consistent.

Why:
Write-back infrastructure exists, but users currently cannot edit bead content from UI detail panels.

Scope:
- Shared edit validation + mutation adapter.
- Reusable editor UI block for issue fields.
- Integration into both Kanban and Graph detail panels.
- Verification for responsive behavior and mutation safety.

Out of scope:
- Dependency relation editing.
- AI content generation.
- Bulk editing.

- Users can edit core bead fields from both Kanban and Graph detail panels.
- Both surfaces use the same validation and update path.
- Save/cancel/error states are consistent across both surfaces.
- Typecheck/tests/guards pass and no direct JSONL writes are introduced.

Execution order enforced through child dependencies.
Execution order: bb-q1s.1 shared core -> bb-q1s.2 kanban + bb-q1s.3 graph (parallel) -> bb-q1s.4 verification/polish.

Shared UI bead editing shipped across Kanban and Graph with verification evidence.


Shared edit core: schema + update adapter + state machine

Build shared edit core used by both detail panels.

Includes:
- editable field schema
- validation rules
- payload adapter for /api/beads/update
- form state model: pristine/dirty/saving/error

- Shared edit core is framework-agnostic and reused by both UIs.
- Validation covers title/priority/labels/assignee/owner/description.
- Adapter emits stable update payload.

Implemented shared edit core in src/lib/issue-editor.ts with draft schema, validation, diff-to-update adapter, label parsing, and edit-state classifier. Added tests in tests/lib/issue-editor.test.ts and expanded mutation adapter to support issueType updates.

Shared edit core delivered and validated via unit tests + typecheck.


Kanban detail integration of shared editor

Integrate shared editor into Kanban detail panel (desktop + mobile drawer).

Includes:
- Edit button and mode switch
- Save/Cancel
- optimistic update + rollback via existing mutation path
- inline error handling

- Kanban detail can edit and save core fields.
- Cancel restores non-saved edits.
- Save errors show clear inline message.

Integrated shared editor into Kanban detail panel (desktop and mobile drawer) with edit mode, save/cancel, inline validation and save errors, and post-save refresh callback.

Kanban detail integration complete with shared edit behavior and verification.


Graph detail integration of shared editor

Integrate same shared editor into graph detail panel container.

Includes:
- identical field behavior/validation
- identical save/cancel semantics
- deep-link context preserved after save

- Graph detail can edit and save same fields as Kanban.
- Behavior matches Kanban editing semantics.

Integrated same shared editor path into Graph task details drawer by reusing KanbanDetail and passing projectRoot/onIssueUpdated hooks; refresh wired via router.refresh().

Graph detail integration complete with shared edit semantics.


Cross-surface verification + UX polish for edit flows

Finalize edit experience and verify both surfaces end-to-end.

Includes:
- responsive polish
- keyboard/focus behavior
- guard/unit test updates
- mutation smoke checks

- Typecheck and tests pass.
- Guards confirm edit controls render on both surfaces.
- No write boundary regressions.

Verification complete: npm run typecheck, npm run test, guard tests, and screenshots (artifacts/kanban-mobile-after.png, artifacts/kanban-tablet-after.png, artifacts/kanban-desktop-after.png, artifacts/graph-next-1440.png, artifacts/graph-next-768.png, artifacts/graph-next-390-overview.png, artifacts/graph-next-390-flow.png). Also adjusted screenshot script to use domcontentloaded due SSE/networkidle hang.

Cross-surface verification and polish completed with fresh evidence.


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

Provide agent-session accountability views for solo supervision: session list, per-session outcomes, and practical throughput metrics. Focus on operational decisions, not vanity dashboards.

Session identity is normalized and stable; per-session open/in-progress/closed outcomes are visible; baseline metrics (throughput, completion rate, active span) are correct and explainable; UI uses the same interaction and visual hierarchy conventions established in bb-bvn.

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.
Execution order set 2026-02-12: start after bb-xhm baseline event stream patterns are stable; depends on bb-xhm for shared timeline/session event semantics.


Extract and normalize session identity fields from issue data

Define the AgentSession model and implement logic to aggregate individual events and closed tasks into coherent sessions.

Files:
- [NEW] src/lib/agent-sessions.ts -- Model types + aggregation logic

Data Contract:
interface AgentSession {
  id: string; // from closed_by_session or inferred
  startedAt: string; // ISO timestamp
  endedAt: string; // ISO timestamp
  closedIssueIds: string[];
  touchedIssueIds: string[];
  status: 'active' | 'completed';
}

Aggregation Logic:
1. Group by closed_by_session (hard link). All issues with same session ID belong together.
2. Infer from ActivityLogs: For non-closed items, checking actor/time matches.
3. MVP: Focus primarily on closed_by_session grouping.

Acceptance Criteria:
- AgentSession interface defined and exported.
- aggregateSessions(issues, events) returns AgentSession[].
- Correctly groups issues by closed_by_session.
- Correctly computes start/end from closed_at timestamps.
- Unit tests for aggregation logic.

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.


Epic Design Gate: scope, decisions, and acceptance contract

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.

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.


Timeline and Activity Feed

Build a high-signal timeline view that explains what changed, by whom, and when, without noise.

Product baseline (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.

Architecture decisions:
1. Snapshot-based diffing (not write interception) - keeps read/write boundary clean
2. Derived events, not stored - ActivityEvent[] computed from JSONL diffs, not persisted separately
3. In-memory snapshot store - watcher fires on changes, we diff previous vs current in memory
4. Solo-dev focus - no multi-user attribution beyond created_by/assignee

Execution order: bb-xhm.4 (design gate, DONE) -> bb-xhm.1 (event model) -> bb-xhm.2 (diffing) -> bb-xhm.3 (UI)

Dependencies:
- Depends on bb-bvn for shared UX and component patterns (DONE)
- Depends on bb-tpc for live file watching and SSE transport (DONE)

Non-goals:
- No direct JSONL writes; read/write boundary preserved
- No multi-user collaboration features
- No persisted event store or event database

Acceptance criteria:
- Event model (bb-xhm.1) defines ActivityEventKind union with 16 transition types and ActivityEvent interface
- Snapshot diffing (bb-xhm.2) produces deterministic ActivityEvent[] from JSONL changes with all field comparison rules
- Timeline UI (bb-xhm.3) at /timeline renders events with date grouping, kind/assignee/project filters, and one-click navigation to issue context
- All pages share the existing visual design system (dark theme, text-text-* tokens, rounded cards)
- Tests exist for event model, diffing engine, and UI rendering
- Typecheck and lint pass across all new files (bun run typecheck && bun run lint)

Timeline events are deterministic from snapshots/diffs; filters (project/actor/event/date) are fast and useful; users can move from event row to issue context in one action; UI follows the same visual system and hierarchy patterns established in bb-bvn.

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.
Execution order set 2026-02-12: start after bb-bvn visual/interaction contracts are finalized; depends on bb-bvn for shared UX and component patterns.


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

Create the ActivityEvent TypeScript interface and supporting types that represent issue lifecycle transitions. This is the core data contract consumed by both the snapshot diffing engine (bb-xhm.2) and the timeline UI (bb-xhm.3).

Files:
- [NEW] src/lib/activity-events.ts -- Type definitions + factory helpers

Data contract:
- ActivityEventKind union type covering 16 event kinds: created, closed, reopened, status_changed, title_changed, priority_changed, assigned, unassigned, reassigned, labels_changed, dependency_added, dependency_removed, deleted
- ActivityEvent interface with fields: id (monotonic counter), issueId, issueTitle, kind, at (ISO timestamp), projectRoot, actor (best-effort attribution from assignee/created_by), previousValue, newValue
- createActivityEvent() factory function enforcing required fields at construction

Grounding in existing types:
- Builds on BeadIssue from src/lib/types.ts (uses status, assignee, created_by, dependencies, labels fields)
- ProjectRoot string for multi-project support (matches IssuesChangedEvent convention from realtime.ts)

Acceptance criteria:
- ActivityEventKind union covers all 16 transition types listed above
- ActivityEvent interface is exported and importable by bb-xhm.2 and bb-xhm.3
- Factory function createActivityEvent() enforces required fields at construction time
- Unit tests cover: creating each event kind, validating required fields, round-trip JSON serialization
- Typecheck passes (bun run typecheck)

Event model supports all required timeline activity types.


Implement snapshot diffing for derived timeline events

Build a diffing engine that compares two snapshots of BeadIssue[] (previous and current state of issues.jsonl) and emits an ActivityEvent[] for all detected changes. Integrates with the existing IssuesEventBus to trigger diffs when the file watcher fires.

Files:
- [NEW] src/lib/snapshot-differ.ts -- Core diff logic
- [MODIFY] src/lib/watcher.ts -- Wire differ into onFlush callback

Diff algorithm:
1. Read current issues.jsonl into Map<id, BeadIssue>
2. Compare against previous snapshot (also Map<id, BeadIssue>):
   a. For each id in current but not previous: emit 'created'
   b. For each id in previous but not current: emit 'deleted'
   c. For each id in both: compare fields and emit specific events
3. Store current as new 'previous' snapshot
4. Return ActivityEvent[]

Field comparison rules:
- status open->closed: emit 'closed' (previousValue=old status, newValue='closed')
- status closed->open: emit 'reopened' (previousValue='closed', newValue=new status)
- status other: emit 'status_changed' (previousValue=old, newValue=new)
- title: emit 'title_changed' (previousValue=old title, newValue=new title)
- priority: emit 'priority_changed' (previousValue=old as string, newValue=new as string)
- assignee null->X: emit 'assigned' (previousValue=null, newValue=X)
- assignee X->null: emit 'unassigned' (previousValue=X, newValue=null)
- assignee X->Y: emit 'reassigned' (previousValue=X, newValue=Y)
- labels: emit 'labels_changed' (previousValue=removed labels comma-sep, newValue=added labels comma-sep)
- dependencies: emit 'dependency_added'/'dependency_removed' (values are dep target strings)

Integration point:
IssuesWatchManager.onFlush currently only emits IssuesChangedEvent (file-level). After this bead:
1. onFlush reads new issues.jsonl
2. Runs diffSnapshots(previous, current) to get ActivityEvent[]
3. Emits activity events through a new ActivityEventBus (separate from IssuesEventBus)
4. Stores current as new previous snapshot

Depends on bb-xhm.1 for ActivityEvent types.
Depends on bb-tpc.2 for coalesced watcher events.

Acceptance criteria:
- diffSnapshots(prev, curr, projectRoot) returns ActivityEvent[]
- All field comparison rules above are implemented
- Edge cases handled: empty previous (first load = all 'created'), identical snapshots (no events), issue with only updated_at changed (no event)
- Unit tests: created, deleted, each field change, multiple changes per diff, no-op diff
- Performance: diff of 200 issues completes in <10ms
- Typecheck passes (bun run typecheck)

Diff engine emits deterministic event records for relevant field changes.


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

Render a reverse-chronological activity feed as a new /timeline page. Date-grouped, filterable, and navigable to issue context in one click.

Files:
- [NEW] src/app/timeline/page.tsx -- Server component (reads issues, computes initial snapshot)
- [NEW] src/components/timeline/timeline-page.tsx -- Client component (SSE subscription, filters, rendering)
- [NEW] src/components/timeline/timeline-event-row.tsx -- Single event row component
- [NEW] src/components/timeline/timeline-filters.tsx -- Filter bar component

UI contract:
1. Date grouping: Events grouped by date headers ('Today', 'Yesterday', 'Feb 10', etc.)
2. Event row: Shows icon (per event kind), issue ID (monospace), title, actor, relative timestamp
3. Filters: Project (when multi-project), event kind (checkboxes), assignee, date range
4. Navigation: Click any event row to navigate to the issue in Workflow Explorer (/graph)
5. Live updates: Subscribe to ActivityEventBus via SSE for new events, prepend to feed
6. Design: Follow existing visual system (dark theme, text-text-* tokens, rounded cards, border accents, same header/panel patterns as graph page)

Routing:
- Add /timeline Next.js route
- Add link in Workflow Explorer header (next to existing Kanban link)

Depends on bb-xhm.1 for ActivityEvent types.
Depends on bb-xhm.2 for ActivityEventBus providing live events via SSE.

Acceptance criteria:
- /timeline page renders with date-grouped event feed
- Each event kind displays appropriate icon and human-readable description
- Filter by event kind works (toggle checkboxes)
- Click on event row navigates to issue context in Workflow Explorer
- Live SSE updates prepend new events at the top
- Responsive: usable on mobile (single-column stack)
- Typecheck and lint pass (bun run typecheck && bun run lint)
- No regressions to existing Kanban or Graph pages

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.

Design gate complete. All child beads (bb-xhm.1, bb-xhm.2, bb-xhm.3) updated with execution-grade specs: concrete implementation details, file paths, data contracts, field comparison rules, integration points, and testable acceptance criteria. Epic-level description and acceptance criteria also tightened with architecture decisions and non-goals.


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.