viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(graph): Implement Graph View with Dagre Layout and Epic Scope (bb-18e)

Browse source
This commit is contained in:
zenchantlive 2026-02-12 23:36:41 -08:00
parent 7ab23448f0
commit 8490cb1d8c
33 changed files with 4936 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

58
.beads/issues.jsonl
View file

@ -1,3 +1,20 @@
{"id":"bb-18e","title":"Graph Clarity Follow-up (Post-Kanban)","description":"Objective:\nTrack graph-focused clarity enhancements that are explicitly out of current Kanban execution scope.\n\nScope:\n- Dependency graph comprehension aids\n- anomaly communication for cycle/deadlock scenarios\n- future AI explanation hooks for dependency understanding\n\nOut of scope for immediate execution:\n- Kanban UI polish currently underway in bb-1es\n\nPlanning note:\nThis epic stays pending until current Kanban actionability epic reaches acceptance.","acceptance_criteria":"- Graph clarity backlog is explicitly captured and linked to future implementation beads.\n- No accidental scope leakage into current Kanban pass.","notes":"Backlog epic for graph-specific clarity work discussed after bb-1es.\nPost-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.\nExecution 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).","status":"open","priority":2,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T19:45:40.5451814-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T20:21:45.1768727-08:00","labels":["backlog","graph","ux"],"dependencies":[{"issue_id":"bb-18e","depends_on_id":"bb-1es","type":"blocks","created_at":"2026-02-12T19:53:11.4089925-08:00","created_by":"zenchantlive"}]}
{"id":"bb-18e.1","title":"Add cycle warning card with focus actions in graph view","description":"Goal:\nWhen dependency cycles exist, show an explicit cycle warning card so users understand why work may be deadlocked.\n\nProblem:\nCycle states are hard to infer from dense node/edge layouts, leading to confusion (“why can’t this move?”).\n\nBehavior contract:\n- Show warning card only when cycle analysis is non-empty.\n- Card includes:\n - cycle count\n - affected bead ids (compact list)\n - click-to-focus action for each cycle group\n - plain language explanation of impact (“tasks in this loop cannot fully unblock each other without breaking the cycle”).\n- Visual style: warning but not alarmist (amber/red subtle).\n\nImplementation tasks:\n1) Build compact cycle summary model from existing detection output.\n2) Add warning card component above graph viewport.\n3) Wire click handlers to focus selected cycle nodes.\n4) Add tests for no-cycle and multi-cycle rendering behavior.\n\nOut of scope:\n- Automatic cycle resolution suggestions.\n- Mutation/write automation.","acceptance_criteria":"- Cycle warning card appears only when cycles are present.\n- Card provides actionable cycle navigation.\n- Language is plain and explains user impact.\n- Tests cover empty and non-empty cycle states.\n- Typecheck and graph guards pass.","notes":"This is the #19 idea captured as an explicit implementation bead.\nDepends on existing cycle analysis primitives already implemented.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T19:46:01.2478576-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T19:46:01.2478576-08:00","labels":["anomaly","graph","ux"],"dependencies":[{"issue_id":"bb-18e.1","depends_on_id":"bb-18e","type":"parent-child","created_at":"2026-02-12T19:46:01.2494327-08:00","created_by":"zenchantlive"},{"issue_id":"bb-18e.1","depends_on_id":"bb-1es","type":"blocks","created_at":"2026-02-12T19:53:11.9910819-08:00","created_by":"zenchantlive"}]}
{"id":"bb-18e.10","title":"Add downstream-impact risk tinting","description":"Add subtle risk tinting based on downstream impact count to highlight high-blast-radius tasks.","acceptance_criteria":"- Higher downstream impact gets stronger but subtle visual signal.\n- Does not overpower status/selection color language.\n- Works with existing legend semantics.","notes":"Use restrained styling; no heavy borders.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:21:21.812041-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T20:21:21.812041-08:00","labels":["graph","signal","ux"],"dependencies":[{"issue_id":"bb-18e.10","depends_on_id":"bb-18e","type":"parent-child","created_at":"2026-02-12T20:21:21.8153577-08:00","created_by":"zenchantlive"},{"issue_id":"bb-18e.10","depends_on_id":"bb-18e.4","type":"blocks","created_at":"2026-02-12T20:21:43.4643033-08:00","created_by":"zenchantlive"}]}
{"id":"bb-18e.11","title":"AI dependency explanation scaffold (deferred)","description":"Prepare integration scaffold for later AI explanation in dependency view (why blocked / next steps), without shipping model calls yet.","acceptance_criteria":"- Data contract for AI explanation input is defined.\n- UI placeholder state exists but feature-flagged/off by default.\n- No network/model dependency in this bead.","notes":"Deferred feature: implement only scaffolding and interfaces.","status":"closed","priority":3,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:21:22.4738465-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T23:35:59.2331675-08:00","closed_at":"2026-02-12T23:35:59.2331675-08:00","labels":["ai","backlog","graph"],"dependencies":[{"issue_id":"bb-18e.11","depends_on_id":"bb-18e","type":"parent-child","created_at":"2026-02-12T20:21:22.4799753-08:00","created_by":"zenchantlive"},{"issue_id":"bb-18e.11","depends_on_id":"bb-18e.9","type":"blocks","created_at":"2026-02-12T20:21:44.0206618-08:00","created_by":"zenchantlive"},{"issue_id":"bb-18e.11","depends_on_id":"bb-18e.1","type":"blocks","created_at":"2026-02-12T20:21:44.590355-08:00","created_by":"zenchantlive"}]}
{"id":"bb-18e.2","title":"Add plain-English edge labels + contrast upgrade","description":"Improve edge readability by labeling relationships in plain language (blocks/parent/related) and increasing contrast for fast scan.\nScope: graph viewport only; no mutation behavior changes.","acceptance_criteria":"- Edge labels are visible and readable at default zoom.\n- Labels map correctly to relation type.\n- Contrast remains accessible on dark background.","notes":"Verification: typecheck + graph responsive guard + visual screenshot at 390/768/1440.","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:21:16.9461643-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T20:21:16.9461643-08:00","labels":["graph","readability","ux"],"dependencies":[{"issue_id":"bb-18e.2","depends_on_id":"bb-18e","type":"parent-child","created_at":"2026-02-12T20:21:16.9493723-08:00","created_by":"zenchantlive"}]}
{"id":"bb-18e.3","title":"Add directional context hints for dependency reading","description":"Add concise orientation hints explaining graph reading order (left prerequisites, right downstream impact).\nPlace hints near graph legend and keep copy plain.","acceptance_criteria":"- Direction hint appears in graph UI.\n- Hint remains visible and non-intrusive on mobile and desktop.","notes":"Use plain language only; no jargon-heavy copy.","status":"in_progress","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:21:17.525886-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T22:05:05.0265309-08:00","labels":["graph","orientation","ux"],"dependencies":[{"issue_id":"bb-18e.3","depends_on_id":"bb-18e","type":"parent-child","created_at":"2026-02-12T20:21:17.5284994-08:00","created_by":"zenchantlive"}]}
{"id":"bb-18e.4","title":"Add edge-type toggles to reduce graph noise","description":"Add controls to show/hide edge categories (blocks,parent,related) so users can simplify complex views.","acceptance_criteria":"- Users can toggle edge categories independently.\n- Default preserves current behavior.\n- Toggle state updates graph without runtime errors.","notes":"Include test coverage for toggle behavior.","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:21:18.1326942-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T20:21:18.1326942-08:00","labels":["controls","graph","ux"],"dependencies":[{"issue_id":"bb-18e.4","depends_on_id":"bb-18e","type":"parent-child","created_at":"2026-02-12T20:21:18.1347832-08:00","created_by":"zenchantlive"},{"issue_id":"bb-18e.4","depends_on_id":"bb-18e.2","type":"blocks","created_at":"2026-02-12T20:21:39.3944582-08:00","created_by":"zenchantlive"}]}
{"id":"bb-18e.5","title":"Add external-blockers-only filter","description":"Add a filter that shows only blockers outside selected epic/task context to focus on cross-epic constraints.","acceptance_criteria":"- Filter clearly isolates external blockers.\n- Selected/focus node remains visible.\n- UX works on mobile and desktop.","notes":"Must degrade gracefully if no external blockers exist.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:21:18.7705681-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T20:21:18.7705681-08:00","labels":["dependencies","filters","graph"],"dependencies":[{"issue_id":"bb-18e.5","depends_on_id":"bb-18e","type":"parent-child","created_at":"2026-02-12T20:21:18.7726627-08:00","created_by":"zenchantlive"},{"issue_id":"bb-18e.5","depends_on_id":"bb-18e.4","type":"blocks","created_at":"2026-02-12T20:21:41.1088626-08:00","created_by":"zenchantlive"}]}
{"id":"bb-18e.6","title":"Keep selected node centered during focus navigation","description":"Refine viewport behavior so selected node remains centered/predictable when user selects tasks or changes depth.","acceptance_criteria":"- Selection keeps focus node in stable viewport position.\n- No clipping/bleed regressions.\n- Fit behavior remains bounded.","notes":"Add tests for focus/viewport contract where feasible.","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:21:19.3791473-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T20:21:19.3791473-08:00","labels":["graph","interaction","ux"],"dependencies":[{"issue_id":"bb-18e.6","depends_on_id":"bb-18e","type":"parent-child","created_at":"2026-02-12T20:21:19.3807243-08:00","created_by":"zenchantlive"},{"issue_id":"bb-18e.6","depends_on_id":"bb-18e.2","type":"blocks","created_at":"2026-02-12T20:21:39.9439739-08:00","created_by":"zenchantlive"}]}
{"id":"bb-18e.7","title":"Progressive disclosure in graph task details panel","description":"Refactor graph details panel to show summary first and collapse secondary metadata under explicit expand control.","acceptance_criteria":"- Primary summary is immediately readable.\n- Secondary fields are accessible via expand action.\n- Mobile detail experience stays compact.","notes":"Do not remove any existing information; only restructure hierarchy.","status":"in_progress","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:21:20.0136797-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T22:02:52.9759525-08:00","labels":["details","graph","ux"],"dependencies":[{"issue_id":"bb-18e.7","depends_on_id":"bb-18e","type":"parent-child","created_at":"2026-02-12T20:21:20.0164851-08:00","created_by":"zenchantlive"},{"issue_id":"bb-18e.7","depends_on_id":"bb-18e.3","type":"blocks","created_at":"2026-02-12T20:21:40.5255149-08:00","created_by":"zenchantlive"}]}
{"id":"bb-18e.8","title":"Add graph keyboard navigation shortcuts","description":"Add keyboard navigation for graph workflow (e.g., next/prev task, open flow/overview, focus search).","acceptance_criteria":"- Shortcuts work without interfering with text inputs.\n- Shortcut list documented in UI/help hint.\n- Accessibility remains intact.","notes":"Treat as later-phase productivity enhancement after core clarity features.","status":"open","priority":3,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:21:20.617034-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T20:21:20.617034-08:00","labels":["accessibility","graph","productivity"],"dependencies":[{"issue_id":"bb-18e.8","depends_on_id":"bb-18e","type":"parent-child","created_at":"2026-02-12T20:21:20.6196393-08:00","created_by":"zenchantlive"},{"issue_id":"bb-18e.8","depends_on_id":"bb-18e.6","type":"blocks","created_at":"2026-02-12T20:21:41.7395727-08:00","created_by":"zenchantlive"},{"issue_id":"bb-18e.8","depends_on_id":"bb-18e.7","type":"blocks","created_at":"2026-02-12T20:21:42.3306409-08:00","created_by":"zenchantlive"}]}
{"id":"bb-18e.9","title":"Persist graph state in URL params","description":"Persist selected epic/task/tab/depth/filter state in URL so refresh/share restores context.","acceptance_criteria":"- Reload restores graph context from URL.\n- Shared URL opens same state deterministically.\n- Invalid params fail safely to defaults.","notes":"Add route/param parsing tests.","status":"in_progress","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:21:21.2077039-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:58:56.9471903-08:00","labels":["graph","routing","ux"],"dependencies":[{"issue_id":"bb-18e.9","depends_on_id":"bb-18e","type":"parent-child","created_at":"2026-02-12T20:21:21.2103973-08:00","created_by":"zenchantlive"},{"issue_id":"bb-18e.9","depends_on_id":"bb-18e.6","type":"blocks","created_at":"2026-02-12T20:21:42.8897325-08:00","created_by":"zenchantlive"}]}
{"id":"bb-1es","title":"Kanban Actionability \u0026 Execution Clarity","description":"Objective:\nCreate a focused Kanban polish epic that improves execution clarity and triage speed without expanding scope into graph rendering changes.\n\nScope boundaries:\n- In scope: Kanban page only (`/`), especially lane workflow, task card signal density, and detail panel actionability.\n- Out of scope: Dependency graph edge visuals/layout (tracked separately), AI-generated summaries (future bead), keyboard system-wide shortcuts (future bead).\n\nUser outcomes this epic must deliver:\n1) Users can immediately identify what to pick next.\n2) Users can quickly understand impact (what this task unblocks).\n3) Users can evaluate readiness from one details panel without context switching.\n4) Users can triage by recency and urgency with minimal cognitive load.\n\nExecution plan:\n- Phase A: Add Next Actionable workflow entrypoint.\n- Phase B: Improve card signal density (recency + unblocks count).\n- Phase C: Add execution checklist to details panel.\n- Phase D: Verify responsive behavior and no regressions on write/mutation flow.\n\nNon-negotiables:\n- Maintain strict read/write boundary (no direct JSONL writes).\n- Preserve existing mutation semantics via bd bridge.\n- Keep mobile layout readable and avoid extra vertical clutter.\n- Evidence-first completion: tests + visual proof.","acceptance_criteria":"- Kanban has a deterministic “next actionable” affordance and it selects a valid ready task.\n- Task cards expose recency and unblock-impact signals without overwhelming visual noise.\n- Details panel includes concise execution checklist with clear pass/fail indicators.\n- All additions are responsive and do not regress existing lane filtering or detail drawer behavior.\n- Typecheck and tests pass.","notes":"Planning contract:\n- This epic is implementation-focused and should be executed through child beads.\n- Child beads must include explicit UX contract, test updates, and verification commands.\n- AI summary concept is deferred to a later phase after core UX/actionability stabilizes.\nExecution sequencing updated: bb-1es.1 is foundational and now blocks bb-1es.3 + bb-1es.4. Recommended implementation order: bb-1es.1 -\u003e bb-1es.3 -\u003e bb-1es.4 -\u003e bb-1es.2.","status":"closed","priority":1,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T19:44:06.0783399-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T20:16:55.5910638-08:00","closed_at":"2026-02-12T20:16:55.5910638-08:00","close_reason":"All child beads complete and verified (typecheck + kanban tests + kanban guard contract).","labels":["kanban","ux","workflow"]}
{"id":"bb-1es.1","title":"Add Next Actionable task picker to Kanban","description":"Goal:\nAdd a high-signal “Next Actionable” control in Kanban that jumps users directly to the best next task to work on.\n\nProblem being solved:\nUsers currently scan multiple lanes/cards manually to find what is unblocked and high-priority. This is slow and inconsistent.\n\nBehavior contract:\n- Action is visible in Kanban controls area.\n- On click, algorithm selects one candidate task from Ready lane.\n- Candidate ranking:\n 1) lowest priority number first (P0 \u003e P1 \u003e ...)\n 2) tasks with higher unblock impact first (if tie)\n 3) most recently updated first (if tie)\n 4) stable deterministic fallback by bead id\n- Resulting behavior:\n - Ready lane becomes active.\n - Selected task is focused (details open if currently closed/minimized).\n - If no actionable task exists, show lightweight empty-state feedback.\n\nImplementation tasks:\n1) Add selector helper in lib layer (pure function + tests).\n2) Wire control button in Kanban controls.\n3) Connect selection plumbing in Kanban page state.\n4) Add empty-path UX when no candidate found.\n5) Ensure no side effects on mutation/write paths.\n\nOut of scope:\n- AI ranking\n- dependency graph page behavior","acceptance_criteria":"- A “Next Actionable” control exists and is keyboard accessible.\n- It always picks a deterministic candidate from Ready lane or shows no-candidate feedback.\n- It activates Ready lane + selects the target task.\n- Unit tests cover ranking and no-candidate case.\n- Guard and type checks pass.","notes":"Verification required:\n- npm run typecheck\n- node --import tsx --test tests/lib/kanban.test.ts\n- node --test tests/guards/kanban-responsive-contract.test.mjs\n- Visual spot check on desktop + mobile screenshot","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T19:44:24.021787-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T20:16:26.9615478-08:00","closed_at":"2026-02-12T20:16:26.9615478-08:00","close_reason":"Implemented deterministic Next Actionable picker + UI control wiring; verified with typecheck and kanban tests/guards.","labels":["kanban","triage","workflow"],"dependencies":[{"issue_id":"bb-1es.1","depends_on_id":"bb-1es","type":"parent-child","created_at":"2026-02-12T19:44:24.0238625-08:00","created_by":"zenchantlive"}]}
{"id":"bb-1es.2","title":"Add recency signal (last updated) to Kanban cards","description":"Goal:\nIncrease Kanban card decision signal with a subtle “updated recently” indicator that helps triage stale vs active work.\n\nProblem:\nCards currently lack strong temporal signal, making it hard to prioritize fresh blockers and newly changed work.\n\nBehavior contract:\n- Each visible card shows concise recency text (e.g., “updated 2h ago”, “updated 3d ago”).\n- Use neutral/subtle styling so it does not overpower title/status.\n- Handle missing/invalid timestamps gracefully (“updated unknown”).\n- Time formatting should be deterministic and testable.\n\nImplementation tasks:\n1) Add timestamp formatter utility (pure + tested).\n2) Add recency metadata row to card footer/header with subtle hierarchy.\n3) Ensure recency doesn’t break compact/mobile card layouts.\n4) Add tests for formatting buckets (minutes/hours/days).\n\nOut of scope:\n- Relative live ticking every second.\n- server-side locale negotiation.","acceptance_criteria":"- Cards show readable recency text derived from updated_at when available.\n- Missing timestamp case is handled without UI breakage.\n- Visual hierarchy remains subtle and non-noisy.\n- Unit tests cover formatter behavior.\n- Typecheck + guard tests pass.","notes":"Design guidance:\n- Keep recency in secondary typography tier.\n- Avoid adding hard borders/heavy pills.\n- Use existing token palette.\n\nVerification required:\n- npm run typecheck\n- node --import tsx --test tests/lib/kanban.test.ts\n- node --test tests/guards/kanban-responsive-contract.test.mjs","status":"closed","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T19:44:41.8782564-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T20:16:41.4329721-08:00","closed_at":"2026-02-12T20:16:41.4329721-08:00","close_reason":"Implemented recency signal on Kanban cards with safe fallback; verified with typecheck and kanban tests/guards.","labels":["kanban","triage","ux"],"dependencies":[{"issue_id":"bb-1es.2","depends_on_id":"bb-1es","type":"parent-child","created_at":"2026-02-12T19:44:41.8803405-08:00","created_by":"zenchantlive"},{"issue_id":"bb-1es.2","depends_on_id":"bb-1es.3","type":"blocks","created_at":"2026-02-12T20:14:31.3947619-08:00","created_by":"zenchantlive"}]}
{"id":"bb-1es.3","title":"Show downstream impact chip (Unblocks N) on Kanban cards","description":"Goal:\nAdd a compact “Unblocks N” impact chip on Kanban cards so users can quickly see downstream value of completing a task.\n\nProblem:\nUsers can’t quickly assess impact from card scan alone; downstream unblock effect is hidden.\n\nBehavior contract:\n- Cards display `Unblocks N` when N \u003e 0.\n- Value is derived from dependency graph model / adjacency semantics already in app.\n- Clicking card still selects task normally; chip itself is not a separate interaction target.\n- Styling should be subtle and consistent with existing status metadata.\n\nImplementation tasks:\n1) Define computation source for downstream count in kanban data helpers.\n2) Add chip to card metadata row with low visual weight.\n3) Validate counts on sample fixtures including zero and multi-dependency cases.\n4) Ensure no overlap/clipping in narrow mobile cards.\n\nOut of scope:\n- Deep dependency chain impact scoring.\n- graph-page edge/line enhancements.","acceptance_criteria":"- Cards show `Unblocks N` for tasks with downstream dependents.\n- Zero-impact tasks do not show noisy empty chip.\n- Counts are consistent with current dependency model.\n- Tests cover representative dependency cases.\n- Typecheck and responsive guard pass.","notes":"Verification required:\n- npm run typecheck\n- node --import tsx --test tests/lib/kanban.test.ts\n- node --import tsx --test tests/lib/graph.test.ts\n- node --test tests/guards/kanban-responsive-contract.test.mjs","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T19:44:58.9549903-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T20:16:28.8736644-08:00","closed_at":"2026-02-12T20:16:28.8736644-08:00","close_reason":"Implemented Unblocks N impact chip on cards with dependency-based counts; verified with typecheck and kanban tests/guards.","labels":["dependencies","kanban","signal"],"dependencies":[{"issue_id":"bb-1es.3","depends_on_id":"bb-1es","type":"parent-child","created_at":"2026-02-12T19:44:58.9576417-08:00","created_by":"zenchantlive"},{"issue_id":"bb-1es.3","depends_on_id":"bb-1es.1","type":"blocks","created_at":"2026-02-12T19:53:13.1942487-08:00","created_by":"zenchantlive"}]}
{"id":"bb-1es.4","title":"Add execution-readiness checklist to Kanban details","description":"Goal:\nAdd an execution checklist block in Kanban detail panel to translate issue state into actionable readiness checks.\n\nProblem:\nDetails currently show metadata, but users still need to mentally compute if task is executable now.\n\nBehavior contract:\n- Detail panel includes a compact checklist with pass/fail states.\n- Initial checklist items:\n 1) Owner assigned\n 2) Not blocked by open blockers\n 3) Has acceptance/description signal (basic quality gate)\n 4) Status compatible with execution (ready/in_progress)\n- Checklist should read as guidance, not hard enforcement.\n- Works on desktop detail and mobile drawer detail.\n\nImplementation tasks:\n1) Add pure checklist derivation helper + tests.\n2) Render checklist component in detail panel below summary metadata.\n3) Ensure blocked-tree links still work unchanged.\n4) Keep footprint compact (no excessive vertical expansion).\n\nOut of scope:\n- AI-generated checklist reasoning.\n- Workflow mutation side effects.","acceptance_criteria":"- Detail panel displays checklist with deterministic computed states.\n- Checklist visible on desktop and mobile detail experiences.\n- No regressions in blocked-by tree deep links.\n- Unit tests cover checklist derivation scenarios.\n- Typecheck + tests pass.","notes":"Future hook:\n- This bead should structure checklist data so future AI explanations can enrich each failed item.\n\nVerification required:\n- npm run typecheck\n- node --import tsx --test tests/lib/kanban.test.ts\n- node --test tests/guards/kanban-responsive-contract.test.mjs\n- Manual mobile + desktop detail check","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T19:45:15.7992627-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T20:16:27.6045434-08:00","closed_at":"2026-02-12T20:16:27.6045434-08:00","close_reason":"Implemented execution-readiness checklist in Kanban detail (desktop/mobile paths); verified with typecheck and kanban tests/guards.","labels":["details","kanban","workflow"],"dependencies":[{"issue_id":"bb-1es.4","depends_on_id":"bb-1es","type":"parent-child","created_at":"2026-02-12T19:45:15.8018512-08:00","created_by":"zenchantlive"},{"issue_id":"bb-1es.4","depends_on_id":"bb-1es.1","type":"blocks","created_at":"2026-02-12T19:53:12.6068453-08:00","created_by":"zenchantlive"}]}
{"id":"bb-29x","title":"Quality Gates, Testing, and Performance Validation","description":"Establish verification confidence through unit/integration tests, boundary tests, and performance baselines for parser and realtime workflows.","acceptance_criteria":"Feature lanes are only closed after passing tests, capturing visual evidence, and documenting smoke-check results.","notes":"Definition of done locked (2026-02-12): every completed feature lane requires automated tests + visual screenshots + runtime smoke checks before close.","status":"open","priority":1,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:15.8368971-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:54:11.1739286-08:00","labels":["perf","quality","testing"],"dependencies":[{"issue_id":"bb-29x","depends_on_id":"bb-ymg","type":"blocks","created_at":"2026-02-11T17:12:23.6722466-08:00","created_by":"zenchantlive"},{"issue_id":"bb-29x","depends_on_id":"bb-xhm","type":"blocks","created_at":"2026-02-11T17:12:24.1823625-08:00","created_by":"zenchantlive"},{"issue_id":"bb-29x","depends_on_id":"bb-bvn","type":"blocks","created_at":"2026-02-11T17:12:24.6873031-08:00","created_by":"zenchantlive"},{"issue_id":"bb-29x","depends_on_id":"bb-u6f","type":"blocks","created_at":"2026-02-11T17:12:25.193566-08:00","created_by":"zenchantlive"}]}
{"id":"bb-29x.1","title":"Implement unit tests for parser, pathing, scanner, and bd bridge","description":"Add focused fast tests for foundational modules and error handling paths.","acceptance_criteria":"Unit tests cover nominal and edge-case logic for each foundational module.","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:16.6578316-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:12:16.6578316-08:00","labels":["tests","unit"],"dependencies":[{"issue_id":"bb-29x.1","depends_on_id":"bb-29x","type":"parent-child","created_at":"2026-02-11T17:12:16.6594181-08:00","created_by":"zenchantlive"},{"issue_id":"bb-29x.1","depends_on_id":"bb-29x.5","type":"blocks","created_at":"2026-02-11T20:10:11.5066258-08:00","created_by":"zenchantlive"}]}
{"id":"bb-29x.2","title":"Implement API integration tests for read, mutate, and SSE routes","description":"Validate route contracts and interaction boundaries across read/write/realtime layers.","acceptance_criteria":"Integration suite verifies route behavior and error semantics.","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:17.4912736-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:12:17.4912736-08:00","labels":["integration","tests"],"dependencies":[{"issue_id":"bb-29x.2","depends_on_id":"bb-29x","type":"parent-child","created_at":"2026-02-11T17:12:17.4923012-08:00","created_by":"zenchantlive"},{"issue_id":"bb-29x.2","depends_on_id":"bb-29x.1","type":"blocks","created_at":"2026-02-11T17:12:38.9423299-08:00","created_by":"zenchantlive"},{"issue_id":"bb-29x.2","depends_on_id":"bb-29x.5","type":"blocks","created_at":"2026-02-11T20:10:10.6325422-08:00","created_by":"zenchantlive"}]}
@ -5,13 +22,20 @@
{"id":"bb-29x.4","title":"Document operational runbook and boundary rationale","description":"Write architecture docs covering scanner policy, bd bridge behavior, and consistency guardrails for future maintainers.","acceptance_criteria":"Runbook documents startup, troubleshooting, and boundary rules.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:19.1385778-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:12:19.1385778-08:00","labels":["docs","runbook"],"dependencies":[{"issue_id":"bb-29x.4","depends_on_id":"bb-29x","type":"parent-child","created_at":"2026-02-11T17:12:19.1402086-08:00","created_by":"zenchantlive"},{"issue_id":"bb-29x.4","depends_on_id":"bb-29x.2","type":"blocks","created_at":"2026-02-11T17:12:39.9591458-08:00","created_by":"zenchantlive"},{"issue_id":"bb-29x.4","depends_on_id":"bb-29x.5","type":"blocks","created_at":"2026-02-11T20:10:12.3474801-08:00","created_by":"zenchantlive"}]}
{"id":"bb-29x.5","title":"Epic Design Gate: scope, decisions, and acceptance contract","description":"Design/discovery gate for bb-29x before further implementation.\n\nMust capture:\n- Product intent and user outcomes for this epic\n- Explicit architecture decisions and tradeoffs\n- API/data contracts and edge cases\n- Windows-specific constraints and path/process assumptions\n- Test strategy and verification commands\n- Non-goals and out-of-scope boundaries\n\nCompletion rule:\nDo not start new implementation tasks in this epic until this gate is closed with agreed decisions.","acceptance_criteria":"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.","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T20:09:42.1507616-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:09:42.1507616-08:00","dependencies":[{"issue_id":"bb-29x.5","depends_on_id":"bb-29x","type":"parent-child","created_at":"2026-02-11T20:09:42.1525436-08:00","created_by":"zenchantlive"}]}
{"id":"bb-3pr","title":"Smoke test mutation lifecycle 2","description":"Temporary issue for API mutation smoke test","status":"closed","priority":1,"issue_type":"task","assignee":"zenchantlive","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T19:44:10.9737485-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T19:44:16.4912473-08:00","closed_at":"2026-02-11T19:44:16.4912473-08:00","close_reason":"Cleanup after API smoke test","labels":["api","smoke"],"comments":[{"id":1,"issue_id":"bb-3pr","author":"zenchantlive","text":"Smoke test comment via API route","created_at":"2026-02-12T03:44:13Z"},{"id":2,"issue_id":"bb-3pr","author":"zenchantlive","text":"Smoke test reopen","created_at":"2026-02-12T03:44:15Z"}]}
{"id":"bb-6aj","title":"Project Registry and Multi-Project Scanner","description":"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.","acceptance_criteria":"Projects can be added/removed/listed and discovered via scanner with deterministic normalization.","status":"open","priority":0,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:47.7205517-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:16:49.4354917-08:00","labels":["multi-project","scanner"],"dependencies":[{"issue_id":"bb-6aj","depends_on_id":"bb-92d","type":"blocks","created_at":"2026-02-11T17:12:19.6374139-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj","title":"Project Registry and Multi-Project Scanner","description":"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.","acceptance_criteria":"Projects can be added/removed/listed and discovered via scanner with deterministic normalization.","notes":"UI productization backlog added (2026-02-12): bb-6aj.6 design gate -\u003e bb-6aj.7 shared scope state -\u003e bb-6aj.8 project manager panel + bb-6aj.9 scanner UX + bb-6aj.10 scoped reads -\u003e bb-6aj.11 aggregate mode -\u003e bb-6aj.12 verification evidence. This sequence turns existing backend scanner/registry foundations into end-user multi-project workflows.\n2026-02-13 epic completion: UI productization chain complete (bb-6aj.6 -\u003e .7 -\u003e .8/.9/.10 -\u003e .11 -\u003e .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.","status":"closed","priority":0,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:47.7205517-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T22:35:21.1595002-08:00","closed_at":"2026-02-12T22:35:21.1595002-08:00","close_reason":"multi-project-scanner-epic-complete","labels":["multi-project","scanner"],"dependencies":[{"issue_id":"bb-6aj","depends_on_id":"bb-92d","type":"blocks","created_at":"2026-02-11T17:12:19.6374139-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj.1","title":"Persist project registry in %USERPROFILE%\\\\.beadboard\\\\projects.json","description":"Implement read/write management for registry file in user profile path, isolated from repository files and safe for local machine usage.","acceptance_criteria":"Registry file is created lazily and survives app restarts.","status":"closed","priority":0,"issue_type":"task","assignee":"agent-a","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:48.5403111-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:53:17.2085722-08:00","closed_at":"2026-02-11T17:53:17.2085722-08:00","close_reason":"Implemented %USERPROFILE%/.beadboard/projects.json registry persistence with Windows-safe normalization and dedupe.","labels":["config","registry"],"dependencies":[{"issue_id":"bb-6aj.1","depends_on_id":"bb-6aj","type":"parent-child","created_at":"2026-02-11T17:11:48.5419102-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj.10","title":"Wire project-scoped reads into Kanban and Graph","description":"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","acceptance_criteria":"Kanban and Graph render data for the selected project scope and remain stable when switching projects.","notes":"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).","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T21:41:42.9381588-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T22:33:58.8681434-08:00","closed_at":"2026-02-12T22:33:58.8681434-08:00","close_reason":"project-scoped-reads-wired","labels":["graph","kanban","multi-project"],"dependencies":[{"issue_id":"bb-6aj.10","depends_on_id":"bb-6aj","type":"parent-child","created_at":"2026-02-12T21:41:42.9408199-08:00","created_by":"zenchantlive"},{"issue_id":"bb-6aj.10","depends_on_id":"bb-6aj.7","type":"blocks","created_at":"2026-02-12T21:41:42.9477322-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj.11","title":"Aggregate mode (cross-project view) with clear project badges","description":"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","acceptance_criteria":"Users can switch between single-project and aggregate mode and always see which project each issue belongs to.","notes":"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.","status":"closed","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T21:41:55.9490928-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T22:34:25.0717745-08:00","closed_at":"2026-02-12T22:34:25.0717745-08:00","close_reason":"aggregate-mode-with-project-badges-shipped","labels":["aggregate","multi-project","ux"],"dependencies":[{"issue_id":"bb-6aj.11","depends_on_id":"bb-6aj","type":"parent-child","created_at":"2026-02-12T21:41:55.9506643-08:00","created_by":"zenchantlive"},{"issue_id":"bb-6aj.11","depends_on_id":"bb-6aj.10","type":"blocks","created_at":"2026-02-12T21:41:55.9554276-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj.12","title":"Verification pass: multi-project UX, guards, and screenshots","description":"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","acceptance_criteria":"Evidence bundle exists showing multi-project registry/scanner/project-scope behavior works across supported breakpoints without boundary regressions.","notes":"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.","status":"closed","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T21:42:09.5711968-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T22:34:52.5493875-08:00","closed_at":"2026-02-12T22:34:52.5493875-08:00","close_reason":"verification-evidence-bundle-complete","labels":["multi-project","qa","verification"],"dependencies":[{"issue_id":"bb-6aj.12","depends_on_id":"bb-6aj","type":"parent-child","created_at":"2026-02-12T21:42:09.5732507-08:00","created_by":"zenchantlive"},{"issue_id":"bb-6aj.12","depends_on_id":"bb-6aj.8","type":"blocks","created_at":"2026-02-12T21:42:09.5784936-08:00","created_by":"zenchantlive"},{"issue_id":"bb-6aj.12","depends_on_id":"bb-6aj.9","type":"blocks","created_at":"2026-02-12T21:42:09.5816386-08:00","created_by":"zenchantlive"},{"issue_id":"bb-6aj.12","depends_on_id":"bb-6aj.10","type":"blocks","created_at":"2026-02-12T21:42:09.5847707-08:00","created_by":"zenchantlive"},{"issue_id":"bb-6aj.12","depends_on_id":"bb-6aj.11","type":"blocks","created_at":"2026-02-12T21:42:09.5884105-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj.2","title":"Implement registry API for add/remove/list operations","description":"Expose robust API endpoints with path validation and normalized identity checks to prevent duplicates.","acceptance_criteria":"API supports add, remove, list and returns clear validation errors.","status":"closed","priority":0,"issue_type":"task","assignee":"agent-a","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:49.3542564-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:53:23.9298353-08:00","closed_at":"2026-02-11T17:53:23.9298353-08:00","close_reason":"Implemented /api/projects GET/POST/DELETE with validation, normalization, and registry integration.","labels":["api","registry"],"dependencies":[{"issue_id":"bb-6aj.2","depends_on_id":"bb-6aj","type":"parent-child","created_at":"2026-02-11T17:11:49.3558158-08:00","created_by":"zenchantlive"},{"issue_id":"bb-6aj.2","depends_on_id":"bb-6aj.1","type":"blocks","created_at":"2026-02-11T17:12:26.7117348-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj.3","title":"Build scanner with profile-root default and depth/ignore controls","description":"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.","acceptance_criteria":"Scanner discovers projects without traversing entire drives by default.","status":"closed","priority":0,"issue_type":"task","assignee":"zenchantlive","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:50.1925005-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:47:56.2978358-08:00","closed_at":"2026-02-11T20:47:56.2978358-08:00","close_reason":"Implemented scanner + /api/scan with safe defaults and full-drive mode.","labels":["performance","scanner"],"dependencies":[{"issue_id":"bb-6aj.3","depends_on_id":"bb-6aj","type":"parent-child","created_at":"2026-02-11T17:11:50.1940841-08:00","created_by":"zenchantlive"},{"issue_id":"bb-6aj.3","depends_on_id":"bb-6aj.1","type":"blocks","created_at":"2026-02-11T17:12:27.2225981-08:00","created_by":"zenchantlive"},{"issue_id":"bb-6aj.3","depends_on_id":"bb-6aj.5","type":"blocks","created_at":"2026-02-11T20:10:09.155154-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj.3.1","title":"Add explicit full-drive scan mode for C:/D: by user action","description":"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.","acceptance_criteria":"Full-drive scan is only activated explicitly, never by default startup logic.","status":"closed","priority":2,"issue_type":"task","assignee":"zenchantlive","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:51.0244174-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:42:04.4870337-08:00","closed_at":"2026-02-11T20:42:04.4870337-08:00","close_reason":"Added explicit full-drive scan mode gated by mode=full-drive.","labels":["optional","scanner"],"dependencies":[{"issue_id":"bb-6aj.3.1","depends_on_id":"bb-6aj.3","type":"parent-child","created_at":"2026-02-11T17:11:51.0259617-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj.4","title":"Implement aggregate project issue context model","description":"Define normalized project identity payload attached to every issue for cross-project Kanban, timeline, and session views.","acceptance_criteria":"Aggregated read output always includes stable project metadata.","status":"closed","priority":1,"issue_type":"task","assignee":"zenchantlive","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:51.8518922-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T19:45:21.5826669-08:00","closed_at":"2026-02-11T19:45:21.5826669-08:00","close_reason":"Added project context model and attached to read issues.","labels":["aggregation","data-model"],"dependencies":[{"issue_id":"bb-6aj.4","depends_on_id":"bb-6aj","type":"parent-child","created_at":"2026-02-11T17:11:51.8534893-08:00","created_by":"zenchantlive"},{"issue_id":"bb-6aj.4","depends_on_id":"bb-6aj.2","type":"blocks","created_at":"2026-02-11T17:12:27.7270195-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj.5","title":"Epic Design Gate: scope, decisions, and acceptance contract","description":"Design/discovery gate for bb-6aj before further implementation.\n\nMust capture:\n- Product intent and user outcomes for this epic\n- Explicit architecture decisions and tradeoffs\n- API/data contracts and edge cases\n- Windows-specific constraints and path/process assumptions\n- Test strategy and verification commands\n- Non-goals and out-of-scope boundaries\n\nCompletion rule:\nDo not start new implementation tasks in this epic until this gate is closed with agreed decisions.","design":"Intent: Provide Windows-native multi-project discovery using registry + scanner with safe defaults; never scan full drives unless explicitly requested.\n\nDecisions:\n- Scan roots: %USERPROFILE% + registry entries; optional full-drive mode adds C:\\ and D:\\ only when mode=full-drive.\n- Bounded recursion (default maxDepth=6) and ignore list to protect performance.\n- Normalize paths with canonicalizeWindowsPath/windowsPathKey; dedupe by key.\n- API contract: GET /api/scan?mode=default|full-drive\u0026depth=\u003cint\u003e returns { mode, roots, projects, stats }.\n\nEdge cases:\n- Missing/unreadable directories are skipped (ENOENT/ENOTDIR/EACCES/EPERM) without aborting scan.\n- Invalid mode/depth returns 400.\n\nWindows constraints:\n- Use drive-letter paths only; no Unix assumptions.\n\nTesting:\n- scanner.test.ts covers default roots, full-drive roots, ignore list, and depth limits.\n- npm test to verify.\n\nNon-goals:\n- No background watcher or SSE here.\n- No default full-drive scan.","acceptance_criteria":"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.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T20:09:37.50785-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:47:55.9830645-08:00","closed_at":"2026-02-11T20:47:55.9830645-08:00","close_reason":"Captured scanner design/contract and verification plan.","dependencies":[{"issue_id":"bb-6aj.5","depends_on_id":"bb-6aj","type":"parent-child","created_at":"2026-02-11T20:09:37.509509-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj.6","title":"UI multi-project design gate and execution contract","description":"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)","acceptance_criteria":"Written implementation-ready contract exists with explicit child task sequencing and no ambiguity on project-scoping behavior.","notes":"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.","status":"closed","priority":1,"issue_type":"task","assignee":"zenchantlive","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T21:40:46.3161508-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T22:00:06.0043328-08:00","closed_at":"2026-02-12T22:00:06.0043328-08:00","close_reason":"design-contract-complete","labels":["multi-project","planning","ui"],"dependencies":[{"issue_id":"bb-6aj.6","depends_on_id":"bb-6aj","type":"parent-child","created_at":"2026-02-12T21:40:46.3177321-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj.7","title":"Shared project scope store + URL persistence","description":"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=\u003ckey\u003e\u0026mode=single|aggregate)\\n- hydration from URL on load and safe fallback when missing/invalid\\n- no JSONL writes; read boundaries preserved","acceptance_criteria":"Project scope can be selected, persisted in URL, restored on refresh, and consumed consistently by both pages.","notes":"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\u003c-\u003eGraph links and rendered active scope badge in both headers. Remaining for full AC: explicit interactive scope selector/store and mode(single|aggregate) URL state.\n2026-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.","status":"closed","priority":1,"issue_type":"task","assignee":"zenchantlive","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T21:41:00.7974464-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T22:32:27.6431192-08:00","closed_at":"2026-02-12T22:32:27.6431192-08:00","close_reason":"scope-state-url-persistence-complete","labels":["multi-project","state","ui"],"dependencies":[{"issue_id":"bb-6aj.7","depends_on_id":"bb-6aj","type":"parent-child","created_at":"2026-02-12T21:41:00.7992088-08:00","created_by":"zenchantlive"},{"issue_id":"bb-6aj.7","depends_on_id":"bb-6aj.6","type":"blocks","created_at":"2026-02-12T21:41:00.804019-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj.8","title":"Project manager panel (list/add/remove registry roots)","description":"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","acceptance_criteria":"Users can manage registry projects entirely from UI and immediately use newly added project roots in scope selection.","notes":"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.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T21:41:13.2668167-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T22:33:03.9808623-08:00","closed_at":"2026-02-12T22:33:03.9808623-08:00","close_reason":"project-manager-panel-shipped","labels":["multi-project","registry","ui"],"dependencies":[{"issue_id":"bb-6aj.8","depends_on_id":"bb-6aj","type":"parent-child","created_at":"2026-02-12T21:41:13.2688831-08:00","created_by":"zenchantlive"},{"issue_id":"bb-6aj.8","depends_on_id":"bb-6aj.7","type":"blocks","created_at":"2026-02-12T21:41:13.2730616-08:00","created_by":"zenchantlive"}]}
{"id":"bb-6aj.9","title":"Scanner UX (discover/import projects from safe roots)","description":"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","acceptance_criteria":"Users can discover projects via scanner and import them into registry without leaving the app.","notes":"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.\n2026-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.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T21:41:29.9411271-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T23:17:32.5251756-08:00","closed_at":"2026-02-12T22:33:32.8319572-08:00","close_reason":"scanner-discover-import-ux-shipped","labels":["multi-project","scanner","ui"],"dependencies":[{"issue_id":"bb-6aj.9","depends_on_id":"bb-6aj","type":"parent-child","created_at":"2026-02-12T21:41:29.9432224-08:00","created_by":"zenchantlive"},{"issue_id":"bb-6aj.9","depends_on_id":"bb-6aj.7","type":"blocks","created_at":"2026-02-12T21:41:29.9479575-08:00","created_by":"zenchantlive"}]}
{"id":"bb-92d","title":"Foundation and Read/Write Boundary","description":"Establish the Windows-native Next.js foundation, canonical Beads schema handling, and strict data boundaries: read from JSONL, write only via bd.exe. This epic defines the non-negotiable invariants that all later work must preserve.","acceptance_criteria":"App boots on Windows, schema/parser contracts exist, and no direct issues.jsonl write path exists in code.","status":"closed","priority":0,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:41.0756295-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:28:27.8108066-08:00","closed_at":"2026-02-11T17:28:27.8108066-08:00","close_reason":"Completed foundation milestone: bootstrap, licensing/docs, schema contracts, parser, windows path normalization, and write-boundary guardrails.","labels":["beadboard","foundation","windows"]}
{"id":"bb-92d.1","title":"Bootstrap Next.js 15 + React 19 + TypeScript strict","description":"Initialize project scaffold with strict TypeScript, App Router baseline, and repeatable scripts for lint/typecheck/test in PowerShell.","acceptance_criteria":"npm install and dev startup work on Windows; strict type checking enabled.","status":"closed","priority":0,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:41.9363647-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:23:14.0089901-08:00","closed_at":"2026-02-11T17:23:14.0089901-08:00","close_reason":"Bootstrapped Next.js 15 + React 19 + strict TypeScript; install/typecheck/dev startup verified on Windows.","labels":["foundation","nextjs"],"dependencies":[{"issue_id":"bb-92d.1","depends_on_id":"bb-92d","type":"parent-child","created_at":"2026-02-11T17:11:41.9379355-08:00","created_by":"zenchantlive"}]}
{"id":"bb-92d.2","title":"Add MIT license and baseline repository docs","description":"Add LICENSE and baseline docs that state Windows-native support, read/write boundaries, and required runtime dependencies.","acceptance_criteria":"MIT license present and docs describe core architecture constraints.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:42.7699961-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:23:50.7519159-08:00","closed_at":"2026-02-11T17:23:50.7519159-08:00","close_reason":"Added MIT license and baseline repository documentation with architecture boundary rules.","labels":["docs","license"],"dependencies":[{"issue_id":"bb-92d.2","depends_on_id":"bb-92d","type":"parent-child","created_at":"2026-02-11T17:11:42.7715653-08:00","created_by":"zenchantlive"}]}
@ -29,11 +53,19 @@
{"id":"bb-bc4.4","title":"Implement mobile/tablet detail panel interaction model","description":"Adapt detail panel behavior for small screens (overlay or drawer model) with safe viewport sizing, accessible dismissal, and non-destructive navigation. Desktop retains efficient side-panel behavior.","acceptance_criteria":"Detail view is usable on mobile/tablet and does not trap or obscure board interaction irrecoverably.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T18:50:45.8342573-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T18:59:19.8911935-08:00","closed_at":"2026-02-11T18:59:19.8911935-08:00","close_reason":"Implemented mobile detail overlay flow while preserving desktop sticky side-detail behavior.","labels":["detail-panel","mobile","ux"],"dependencies":[{"issue_id":"bb-bc4.4","depends_on_id":"bb-bc4","type":"parent-child","created_at":"2026-02-11T18:50:45.8360334-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bc4.4","depends_on_id":"bb-bc4.2","type":"blocks","created_at":"2026-02-11T18:51:10.0929812-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bc4.4","depends_on_id":"bb-bc4.3","type":"blocks","created_at":"2026-02-11T18:51:10.9352149-08:00","created_by":"zenchantlive"}]}
{"id":"bb-bc4.5","title":"Playwright multi-breakpoint visual verification","description":"Capture and review before/after screenshots at 390x844, 768x1024, and 1440x900 to validate reachability, clipping, control usability, and detail-panel behavior. Store artifacts under artifacts/ with explicit naming conventions.","acceptance_criteria":"Required six screenshots exist (before/after x 3 breakpoints) and observations confirm responsive/visual acceptance criteria.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T18:50:47.0018379-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T18:59:20.7427588-08:00","closed_at":"2026-02-11T18:59:20.7427588-08:00","close_reason":"Captured required Playwright before/after screenshots at mobile/tablet/desktop and validated layout usability.","labels":["playwright","verification","visual"],"dependencies":[{"issue_id":"bb-bc4.5","depends_on_id":"bb-bc4","type":"parent-child","created_at":"2026-02-11T18:50:47.0034039-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bc4.5","depends_on_id":"bb-bc4.4","type":"blocks","created_at":"2026-02-11T18:51:11.7817934-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bc4.5","depends_on_id":"bb-bc4.3","type":"blocks","created_at":"2026-02-11T18:51:12.6236762-08:00","created_by":"zenchantlive"}]}
{"id":"bb-bq6","title":"Smoke test mutation lifecycle","description":"Temporary issue for API mutation smoke test","status":"open","priority":3,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T19:43:52.1686473-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:40:02.1018374-08:00","labels":["api","smoke"],"comments":[{"id":4,"issue_id":"bb-bq6","author":"zenchantlive","text":"UI visibility test complete: reopening","created_at":"2026-02-12T04:40:02Z"}]}
{"id":"bb-bvn","title":"Dependency Graph (React Flow)","description":"Visualize issue relationships and blocked chains through an interactive graph backed by parsed dependency edges.","acceptance_criteria":"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.","notes":"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.","status":"open","priority":2,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:09.2057278-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:54:10.3326048-08:00","labels":["graph","react-flow"],"dependencies":[{"issue_id":"bb-bvn","depends_on_id":"bb-trz","type":"blocks","created_at":"2026-02-11T17:12:22.6642419-08:00","created_by":"zenchantlive"}]}
{"id":"bb-bvn.1","title":"Parse dependency edges and build adjacency structures","description":"Build graph data preparation pipeline for dependency workspace.\n\nScope:\n- Input: parsed Bead issues from read layer only (`readIssuesFromDisk`).\n- Build normalized node map keyed by issue id.\n- Build typed edge list from `dependencies[]` supporting: blocks, parent, relates_to, duplicates, supersedes.\n- Include reverse index (incoming/outgoing) to support focus queries.\n- Preserve issue metadata needed by UI nodes: id, title, status, priority, issue_type, assignee, updated_at.\n\nRules:\n- Ignore dependency edges that point to missing issue IDs but record count for diagnostics.\n- Deduplicate duplicate edges (same source, target, type).\n- Treat path/project context as explicit API argument for future multi-project support.\n- Do not mutate source issues.\n\nOutput contracts:\n- `GraphModel = { nodes, edges, adjacency, diagnostics }`\n- `adjacency` includes incoming/outgoing arrays per node.\n- `diagnostics` includes counts for missing targets and dropped duplicates.\n\nTest plan:\n- Unit tests for edge extraction across all supported types.\n- Unit tests for dedupe and missing-target behavior.\n- Unit tests for adjacency correctness and deterministic ordering.\r\n","acceptance_criteria":"- Graph model contains all valid nodes and typed edges from issue dependencies.\n- Duplicate edges are removed deterministically.\n- Missing-target edges do not crash model generation and are surfaced in diagnostics.\n- Adjacency maps are correct for incoming/outgoing lookups.\n- Unit tests cover all supported dependency types and edge cases.\r\n","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:10.0434044-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:58:31.5313317-08:00","labels":["graph","parser"],"dependencies":[{"issue_id":"bb-bvn.1","depends_on_id":"bb-bvn","type":"parent-child","created_at":"2026-02-11T17:12:10.0449367-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bvn.1","depends_on_id":"bb-bvn.4","type":"blocks","created_at":"2026-02-11T20:10:02.7644711-08:00","created_by":"zenchantlive"}]}
{"id":"bb-bvn.2","title":"Implement React Flow graph view with pan/zoom/select interactions","description":"Implement deterministic React Flow graph UI (non-chaotic workspace mode).\n\nScope:\n- New graph page/view with React Flow canvas.\n- Deterministic auto-layout (DAG style) for stable mental model:\n - selected node centered in focus mode\n - upstream blockers left, downstream dependents right\n- Use card-like nodes (not bubbles) with minimal status accent.\n- Edge styling by dependency type:\n - blocks: solid\n - parent: thicker muted\n - relates_to: dashed\n - duplicates/supersedes: distinct but subtle styles\n\nInteraction:\n- Click node opens shared detail panel.\n- Controls: hop depth switch (1/2/full), collapse closed, fit-to-selection.\n- Disable freeform drag by default to avoid n8n-like chaos (optional manual toggle can be deferred).\n\nResponsive behavior:\n- Desktop/tablet: full canvas + detail panel split.\n- Mobile: simplified dependency focus mode (selected + immediate blockers/dependents list) instead of dense full canvas.\n\nIntegration:\n- Read-only against graph model from bb-bvn.1.\n- No writeback from graph lane.\n\nTest/verification:\n- Component tests for control toggles and selected-node behavior.\n- Guard test for responsive fallback contract.\n- Playwright screenshots: mobile/tablet/desktop graph view.\r\n","acceptance_criteria":"- Graph renders with deterministic layout and typed edges.\n- Default depth is 2 hops with controls for 1/2/full.\n- Node selection opens detail panel and fit-to-selection works.\n- Mobile shows simplified focus view (no unusable dense canvas).\n- Visual verification screenshots captured for mobile/tablet/desktop.\r\n","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:10.8683725-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:58:46.8359811-08:00","labels":["graph","ui"],"dependencies":[{"issue_id":"bb-bvn.2","depends_on_id":"bb-bvn","type":"parent-child","created_at":"2026-02-11T17:12:10.8694189-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bvn.2","depends_on_id":"bb-bvn.1","type":"blocks","created_at":"2026-02-11T17:12:36.8736785-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bvn.2","depends_on_id":"bb-bvn.4","type":"blocks","created_at":"2026-02-11T20:10:04.4783802-08:00","created_by":"zenchantlive"}]}
{"id":"bb-bvn.3","title":"Add blocked-chain highlighting and cycle anomaly signaling","description":"Add analysis overlays for blocker triage and anomaly visibility.\n\nScope:\n- Compute and highlight blocked chains from selected node.\n- Show concise blocker summary:\n - open blocker count\n - in-progress blocker count\n - first actionable blocker\n- Cycle/anomaly signaling:\n - detect cycles in dependency graph\n - mark involved nodes/edges with warning style and explanation text\n\nUI behavior:\n- \"Show blocking path only\" toggle to reduce noise.\n- Hovering a node/edge highlights direct dependency chain.\n- Keep styling subtle and readable; avoid visual overload.\n\nRules:\n- Analysis is read-only and derived from current graph model.\n- Must not fail hard on malformed dependency data; degrade with warnings.\n\nTest plan:\n- Unit tests for blocked-chain derivation and cycle detection logic.\n- UI tests for toggle behavior and warning visibility.\n- Screenshot verification for normal and anomaly cases.\r\n","acceptance_criteria":"- Selected issue can display clear blocked-chain context.\n- Cycle/anomaly conditions are detected and visibly flagged.\n- Blocking-path-only mode materially reduces graph noise.\n- Analysis features remain performant and do not break base graph rendering.\n- Tests and screenshots verify normal + anomaly paths.\r\n","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:11.687878-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:59:01.6815133-08:00","labels":["analysis","graph"],"dependencies":[{"issue_id":"bb-bvn.3","depends_on_id":"bb-bvn","type":"parent-child","created_at":"2026-02-11T17:12:11.6890831-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bvn.3","depends_on_id":"bb-bvn.2","type":"blocks","created_at":"2026-02-11T17:12:37.378326-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bvn.3","depends_on_id":"bb-bvn.4","type":"blocks","created_at":"2026-02-11T20:10:03.6326727-08:00","created_by":"zenchantlive"}]}
{"id":"bb-bvn","title":"Dependency Graph (React Flow)","description":"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.","acceptance_criteria":"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.","notes":"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.\nExecution order set 2026-02-12: bb-bvn is the active next epic and should be finished to UX acceptance before timeline/session epics.","status":"closed","priority":0,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:09.2057278-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T18:57:49.5827802-08:00","closed_at":"2026-02-12T18:57:49.5827802-08:00","close_reason":"All child tasks complete (bb-bvn.1/.2/.3/.4), dependency graph workflow implemented and verified across tests and visual artifacts.","labels":["graph","react-flow"],"dependencies":[{"issue_id":"bb-bvn","depends_on_id":"bb-trz","type":"blocks","created_at":"2026-02-11T17:12:22.6642419-08:00","created_by":"zenchantlive"}]}
{"id":"bb-bvn.1","title":"Parse dependency edges and build adjacency structures","description":"Build graph data preparation pipeline for dependency workspace.\n\nScope:\n- Input: parsed Bead issues from read layer only (`readIssuesFromDisk`).\n- Build normalized node map keyed by issue id.\n- Build typed edge list from `dependencies[]` supporting: blocks, parent, relates_to, duplicates, supersedes.\n- Include reverse index (incoming/outgoing) to support focus queries.\n- Preserve issue metadata needed by UI nodes: id, title, status, priority, issue_type, assignee, updated_at.\n\nRules:\n- Ignore dependency edges that point to missing issue IDs but record count for diagnostics.\n- Deduplicate duplicate edges (same source, target, type).\n- Treat path/project context as explicit API argument for future multi-project support.\n- Do not mutate source issues.\n\nOutput contracts:\n- `GraphModel = { nodes, edges, adjacency, diagnostics }`\n- `adjacency` includes incoming/outgoing arrays per node.\n- `diagnostics` includes counts for missing targets and dropped duplicates.\n\nTest plan:\n- Unit tests for edge extraction across all supported types.\n- Unit tests for dedupe and missing-target behavior.\n- Unit tests for adjacency correctness and deterministic ordering.\r\n","acceptance_criteria":"- Graph model contains all valid nodes and typed edges from issue dependencies.\n- Duplicate edges are removed deterministically.\n- Missing-target edges do not crash model generation and are surfaced in diagnostics.\n- Adjacency maps are correct for incoming/outgoing lookups.\n- Unit tests cover all supported dependency types and edge cases.\r\n","notes":"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.","status":"closed","priority":1,"issue_type":"task","assignee":"zenchantlive","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:10.0434044-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T09:10:52.6262123-08:00","closed_at":"2026-02-12T09:10:52.6262123-08:00","close_reason":"Completed graph model preparation pipeline with deterministic contracts and full unit coverage; ready for React Flow rendering task bb-bvn.2.","labels":["graph","parser"],"dependencies":[{"issue_id":"bb-bvn.1","depends_on_id":"bb-bvn","type":"parent-child","created_at":"2026-02-11T17:12:10.0449367-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bvn.1","depends_on_id":"bb-bvn.4","type":"blocks","created_at":"2026-02-11T20:10:02.7644711-08:00","created_by":"zenchantlive"}]}
{"id":"bb-bvn.2","title":"Implement React Flow graph view with pan/zoom/select interactions","description":"Implement deterministic React Flow graph UI (non-chaotic workspace mode).\n\nScope:\n- New graph page/view with React Flow canvas.\n- Deterministic auto-layout (DAG style) for stable mental model:\n - selected node centered in focus mode\n - upstream blockers left, downstream dependents right\n- Use card-like nodes (not bubbles) with minimal status accent.\n- Edge styling by dependency type:\n - blocks: solid\n - parent: thicker muted\n - relates_to: dashed\n - duplicates/supersedes: distinct but subtle styles\n\nInteraction:\n- Click node opens shared detail panel.\n- Controls: hop depth switch (1/2/full), collapse closed, fit-to-selection.\n- Disable freeform drag by default to avoid n8n-like chaos (optional manual toggle can be deferred).\n\nResponsive behavior:\n- Desktop/tablet: full canvas + detail panel split.\n- Mobile: simplified dependency focus mode (selected + immediate blockers/dependents list) instead of dense full canvas.\n\nIntegration:\n- Read-only against graph model from bb-bvn.1.\n- No writeback from graph lane.\n\nTest/verification:\n- Component tests for control toggles and selected-node behavior.\n- Guard test for responsive fallback contract.\n- Playwright screenshots: mobile/tablet/desktop graph view.\r\n","acceptance_criteria":"- Graph renders with deterministic layout and typed edges.\n- Default depth is 2 hops with controls for 1/2/full.\n- Node selection opens detail panel and fit-to-selection works.\n- Mobile shows simplified focus view (no unusable dense canvas).\n- Visual verification screenshots captured for mobile/tablet/desktop.\r\n","notes":"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/.","status":"closed","priority":1,"issue_type":"task","assignee":"zenchantlive","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:10.8683725-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T18:57:24.4716865-08:00","closed_at":"2026-02-12T18:57:24.4716865-08:00","close_reason":"Implemented React Flow graph workspace with deterministic layout, interaction controls, responsive fallback, and visual verification artifacts; tests/typecheck are green.","labels":["graph","ui"],"dependencies":[{"issue_id":"bb-bvn.2","depends_on_id":"bb-bvn","type":"parent-child","created_at":"2026-02-11T17:12:10.8694189-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bvn.2","depends_on_id":"bb-bvn.1","type":"blocks","created_at":"2026-02-11T17:12:36.8736785-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bvn.2","depends_on_id":"bb-bvn.4","type":"blocks","created_at":"2026-02-11T20:10:04.4783802-08:00","created_by":"zenchantlive"}]}
{"id":"bb-bvn.3","title":"Add blocked-chain highlighting and cycle anomaly signaling","description":"Add analysis overlays for blocker triage and anomaly visibility.\n\nScope:\n- Compute and highlight blocked chains from selected node.\n- Show concise blocker summary:\n - open blocker count\n - in-progress blocker count\n - first actionable blocker\n- Cycle/anomaly signaling:\n - detect cycles in dependency graph\n - mark involved nodes/edges with warning style and explanation text\n\nUI behavior:\n- \"Show blocking path only\" toggle to reduce noise.\n- Hovering a node/edge highlights direct dependency chain.\n- Keep styling subtle and readable; avoid visual overload.\n\nRules:\n- Analysis is read-only and derived from current graph model.\n- Must not fail hard on malformed dependency data; degrade with warnings.\n\nTest plan:\n- Unit tests for blocked-chain derivation and cycle detection logic.\n- UI tests for toggle behavior and warning visibility.\n- Screenshot verification for normal and anomaly cases.\r\n","acceptance_criteria":"- Selected issue can display clear blocked-chain context.\n- Cycle/anomaly conditions are detected and visibly flagged.\n- Blocking-path-only mode materially reduces graph noise.\n- Analysis features remain performant and do not break base graph rendering.\n- Tests and screenshots verify normal + anomaly paths.\r\n","notes":"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).","status":"closed","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:11.687878-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T18:57:24.8694169-08:00","closed_at":"2026-02-12T18:57:24.8694169-08:00","close_reason":"Implemented blocked-chain analysis, blocking-path emphasis, and cycle anomaly signaling with regression coverage; tests/typecheck are green.","labels":["analysis","graph"],"dependencies":[{"issue_id":"bb-bvn.3","depends_on_id":"bb-bvn","type":"parent-child","created_at":"2026-02-11T17:12:11.6890831-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bvn.3","depends_on_id":"bb-bvn.2","type":"blocks","created_at":"2026-02-11T17:12:37.378326-08:00","created_by":"zenchantlive"},{"issue_id":"bb-bvn.3","depends_on_id":"bb-bvn.4","type":"blocks","created_at":"2026-02-11T20:10:03.6326727-08:00","created_by":"zenchantlive"}]}
{"id":"bb-bvn.4","title":"Epic Design Gate: scope, decisions, and acceptance contract","description":"Design/discovery gate for bb-bvn before further implementation.\n\nMust capture:\n- Product intent and user outcomes for this epic\n- Explicit architecture decisions and tradeoffs\n- API/data contracts and edge cases\n- Windows-specific constraints and path/process assumptions\n- Test strategy and verification commands\n- Non-goals and out-of-scope boundaries\n\nCompletion rule:\nDo not start new implementation tasks in this epic until this gate is closed with agreed decisions.","acceptance_criteria":"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.","notes":"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.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T20:09:40.290642-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:59:12.4823711-08:00","closed_at":"2026-02-11T20:59:12.4823711-08:00","close_reason":"Design gate complete: bb-bvn child tasks now contain concrete scope, contracts, dependencies, and testable acceptance criteria.","dependencies":[{"issue_id":"bb-bvn.4","depends_on_id":"bb-bvn","type":"parent-child","created_at":"2026-02-11T20:09:40.2922349-08:00","created_by":"zenchantlive"}]}
{"id":"bb-dcv","title":"Agent Communication \u0026 Coordination Patterns","description":"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.\n\nGoals:\n- Define 'Protocol' for agent-to-agent comments (prefixes, structure).\n- Establish Identity standards (how agents refer to themselves).\n- Ensure CLI support for all protocol actions (commenting, signaling).\n\nDeliverables:\n- RFC-001: Agent Coordination Protocol.\n- Skill: beadboard-driver (teaching the protocol).\n\nThis epic blocks bb-u6f (Agent Sessions) because session attribution relies on the Identity standards defined here.","status":"open","priority":1,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T21:35:07.1826787-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:36:56.4424829-08:00"}
{"id":"bb-dcv.1","title":"Research \u0026 RFC: Agent Skills and Handoff Protocols","description":"Conduct research and draft a 'Request for Comments' (RFC) document that defines the standard operating procedures for agent-to-agent interaction within Beadboard.\n\nKey Questions to Answer:\n1. Identity: How do we consistently identify an agent? (e.g. assignee formats).\n2. Handoff Protocol: Structure of a handoff comment (e.g. [HANDOFF]).\n3. Blocker Signaling: How to raise a flag (e.g. [BLOCKED]).\n4. Parsing: Can/should we have bd parse-comments?\n\nDeliverables:\n- docs/RFC-001-Agent-Coordination.md: Finalized spec.\n- skills/beadboard-driver/SKILL.md (Draft): Prototype skill.\n- Gap Analysis: Missing CLI commands.\n\nAcceptance Criteria:\n- RFC document created and committed.\n- Protocol covers: Identity, Handoff, Blocker, Assignment.\n- Gap analysis lists required code changes.","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T21:37:32.9086915-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:37:32.9086915-08:00","dependencies":[{"issue_id":"bb-dcv.1","depends_on_id":"bb-dcv","type":"parent-child","created_at":"2026-02-12T21:37:32.9107758-08:00","created_by":"zenchantlive"}]}
{"id":"bb-n7p","title":"Swimlane status model: ready + dependency-derived blocked","notes":"Implemented new swimlane model: removed deferred lane from board usage; added ready lane and dependency-derived blocked lane. Lane rules: closed-\u003eDone; blocked-\u003eBlocked if explicit status blocked OR has active incoming blocker edge; in_progress/review-\u003eIn Progress; otherwise Ready. Added laneToMutationStatus to map board lane writes to bead statuses (ready-\u003eopen). Updated board labels/colors, drag-drop lane source tracking, and controls stat label Open-\u003eReady. 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).","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T17:55:04.1851993-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T18:40:08.0620089-08:00","closed_at":"2026-02-12T18:40:08.0620089-08:00","close_reason":"Implemented ready/blocked swimlane model, blocked-tree deep links to lane focus, and verification passed (kanban tests, typecheck, full test suite).","labels":["kanban","status","swimlane"]}
{"id":"bb-q1s","title":"UI Bead Editing Across Kanban + Graph","description":"Objective:\nAdd true UI editing for bead fields across both detail panels (Kanban + Graph) using one shared edit core so behavior stays consistent.\n\nWhy:\nWrite-back infrastructure exists, but users currently cannot edit bead content from UI detail panels.\n\nScope:\n- Shared edit validation + mutation adapter.\n- Reusable editor UI block for issue fields.\n- Integration into both Kanban and Graph detail panels.\n- Verification for responsive behavior and mutation safety.\n\nOut of scope:\n- Dependency relation editing.\n- AI content generation.\n- Bulk editing.","acceptance_criteria":"- Users can edit core bead fields from both Kanban and Graph detail panels.\n- Both surfaces use the same validation and update path.\n- Save/cancel/error states are consistent across both surfaces.\n- Typecheck/tests/guards pass and no direct JSONL writes are introduced.","notes":"Execution order enforced through child dependencies.\nExecution order: bb-q1s.1 shared core -\u003e bb-q1s.2 kanban + bb-q1s.3 graph (parallel) -\u003e bb-q1s.4 verification/polish.","status":"closed","priority":1,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:50:12.3431904-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:11:43.1747329-08:00","closed_at":"2026-02-12T21:11:43.1747329-08:00","close_reason":"Shared UI bead editing shipped across Kanban and Graph with verification evidence.","labels":["editing","mutation","ui"]}
{"id":"bb-q1s.1","title":"Shared edit core: schema + update adapter + state machine","description":"Build shared edit core used by both detail panels.\n\nIncludes:\n- editable field schema\n- validation rules\n- payload adapter for /api/beads/update\n- form state model: pristine/dirty/saving/error","acceptance_criteria":"- Shared edit core is framework-agnostic and reused by both UIs.\n- Validation covers title/priority/labels/assignee/owner/description.\n- Adapter emits stable update payload.","notes":"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.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:50:31.668852-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:10:59.9315015-08:00","closed_at":"2026-02-12T21:10:59.9315015-08:00","close_reason":"Shared edit core delivered and validated via unit tests + typecheck.","labels":["editing","lib","shared"],"dependencies":[{"issue_id":"bb-q1s.1","depends_on_id":"bb-q1s","type":"parent-child","created_at":"2026-02-12T20:50:31.6709483-08:00","created_by":"zenchantlive"}]}
{"id":"bb-q1s.2","title":"Kanban detail integration of shared editor","description":"Integrate shared editor into Kanban detail panel (desktop + mobile drawer).\n\nIncludes:\n- Edit button and mode switch\n- Save/Cancel\n- optimistic update + rollback via existing mutation path\n- inline error handling","acceptance_criteria":"- Kanban detail can edit and save core fields.\n- Cancel restores non-saved edits.\n- Save errors show clear inline message.","notes":"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.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:50:32.2815939-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:11:00.5718636-08:00","closed_at":"2026-02-12T21:11:00.5718636-08:00","close_reason":"Kanban detail integration complete with shared edit behavior and verification.","labels":["editing","kanban","ui"],"dependencies":[{"issue_id":"bb-q1s.2","depends_on_id":"bb-q1s","type":"parent-child","created_at":"2026-02-12T20:50:32.2836956-08:00","created_by":"zenchantlive"},{"issue_id":"bb-q1s.2","depends_on_id":"bb-q1s.1","type":"blocks","created_at":"2026-02-12T20:50:47.1937109-08:00","created_by":"zenchantlive"}]}
{"id":"bb-q1s.3","title":"Graph detail integration of shared editor","description":"Integrate same shared editor into graph detail panel container.\n\nIncludes:\n- identical field behavior/validation\n- identical save/cancel semantics\n- deep-link context preserved after save","acceptance_criteria":"- Graph detail can edit and save same fields as Kanban.\n- Behavior matches Kanban editing semantics.","notes":"Integrated same shared editor path into Graph task details drawer by reusing KanbanDetail and passing projectRoot/onIssueUpdated hooks; refresh wired via router.refresh().","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:50:32.9165031-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:11:01.2178741-08:00","closed_at":"2026-02-12T21:11:01.2178741-08:00","close_reason":"Graph detail integration complete with shared edit semantics.","labels":["editing","graph","ui"],"dependencies":[{"issue_id":"bb-q1s.3","depends_on_id":"bb-q1s","type":"parent-child","created_at":"2026-02-12T20:50:32.9234917-08:00","created_by":"zenchantlive"},{"issue_id":"bb-q1s.3","depends_on_id":"bb-q1s.1","type":"blocks","created_at":"2026-02-12T20:50:47.795674-08:00","created_by":"zenchantlive"}]}
{"id":"bb-q1s.4","title":"Cross-surface verification + UX polish for edit flows","description":"Finalize edit experience and verify both surfaces end-to-end.\n\nIncludes:\n- responsive polish\n- keyboard/focus behavior\n- guard/unit test updates\n- mutation smoke checks","acceptance_criteria":"- Typecheck and tests pass.\n- Guards confirm edit controls render on both surfaces.\n- No write boundary regressions.","notes":"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.","status":"closed","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T20:50:33.598391-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:11:29.5913307-08:00","closed_at":"2026-02-12T21:11:29.5913307-08:00","close_reason":"Cross-surface verification and polish completed with fresh evidence.","labels":["editing","ux","verification"],"dependencies":[{"issue_id":"bb-q1s.4","depends_on_id":"bb-q1s","type":"parent-child","created_at":"2026-02-12T20:50:33.601069-08:00","created_by":"zenchantlive"},{"issue_id":"bb-q1s.4","depends_on_id":"bb-q1s.2","type":"blocks","created_at":"2026-02-12T20:50:48.3822381-08:00","created_by":"zenchantlive"},{"issue_id":"bb-q1s.4","depends_on_id":"bb-q1s.3","type":"blocks","created_at":"2026-02-12T20:50:48.9933212-08:00","created_by":"zenchantlive"}]}
{"id":"bb-sse-smoke","title":"SSE smoke 1770870992420","status":"open","priority":2,"issue_type":"task","created_at":"2026-02-12T04:36:32.42Z","updated_at":"2026-02-12T04:36:32.422Z"}
{"id":"bb-tpc","title":"Live File Watching and SSE Transport","description":"Realtime transport epic to deliver deterministic file-change propagation from .beads/issues.jsonl(.new) into the Kanban UI.\n\nScope boundaries:\n- Read source remains disk JSONL via read-issues; no bd CLI reads.\n- Mutation/write path remains bd.exe only (already implemented in bb-ymg).\n- This epic adds one-way change detection + push invalidation, not business-rule mutation logic.\n\nImplementation contract:\n1) Watch manager (`src/lib/watcher.ts`)\n- Uses chokidar to monitor `\u003cprojectRoot\u003e/.beads/issues.jsonl` and `.beads/issues.jsonl.new`.\n- Normalizes project roots with existing Windows path helpers.\n- Supports start/stop per project and global cleanup for tests/dev reloads.\n- Emits typed change events with monotonic event ids and timestamps.\n\n2) Burst and lock stability (`bb-tpc.2`)\n- Debounce/coalesce rapid write bursts into one logical event per project window.\n- Treat transient lock/read contention as retryable (EBUSY/EPERM) in read path.\n\n3) SSE server (`src/app/api/events/route.ts`)\n- `text/event-stream` endpoint with heartbeat and `id:` fields.\n- Optional `projectRoot` filter for scoped subscribers.\n- Cleans up subscriptions and timers on disconnect.\n\n4) Frontend subscriber (`bb-tpc.4`)\n- EventSource client reconnect behavior handled by browser defaults.\n- On event, re-fetch affected project issues and reconcile local state.\n- No direct JSONL polling loops after SSE is active.\n\nNon-goals in this epic:\n- WebSocket transport.\n- Cross-process durable event bus.\n- React Query migration (deferred; current lane keeps existing local fetch/reconcile pattern).\r\n","acceptance_criteria":"- Editing `.beads/issues.jsonl` externally triggers UI refresh in \u003c1s without manual reload.\n- SSE stream remains connected with periodic heartbeat; reconnect path resumes safely.\n- Event stream and watcher code use Windows-safe path normalization.\n- No direct JSONL writes introduced (guard still passes).\n- `npm run typecheck`, `npm run test`, `npm run dev` pass.\r\n","notes":"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.","status":"closed","priority":0,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:52.6737283-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:37:49.787539-08:00","closed_at":"2026-02-11T20:37:49.787539-08:00","close_reason":"Completed watcher/SSE tracer end-to-end for project-scoped realtime updates with tests and smoke checks.","labels":["realtime","sse","watcher"]}
{"id":"bb-tpc.1","title":"Implement chokidar watch manager for registered projects","description":"Implement `src/lib/watcher.ts` watch manager for project-scoped issue files.\n\nScope:\n- Watch both `\u003cprojectRoot\u003e/.beads/issues.jsonl` and `\u003cprojectRoot\u003e/.beads/issues.jsonl.new`.\n- Support startWatch(projectRoot), stopWatch(projectRoot), stopAll().\n- Ensure idempotent start behavior (no duplicate watchers for same canonical root).\n- Emit typed events into in-process realtime bus with:\n - id (monotonic)\n - projectRoot (canonical path)\n - kind (changed|renamed)\n - path\n - at (ISO timestamp)\n\nImplementation notes:\n- chokidar with `ignoreInitial: true` and Windows-safe normalized paths.\n- Maintain internal map keyed by windowsPathKey(projectRoot).\n- Route event -\u003e coalescer (bb-tpc.2), not direct SSE writes.\n\nTest plan:\n- Unit tests verify idempotent lifecycle and key normalization behavior.\n- Unit tests verify events from both jsonl candidates are accepted.\r\n","acceptance_criteria":"- Starting watch for same project twice creates one active watcher.\n- Stopping watch removes watcher and prevents further events.\n- Events include canonical project root and unique monotonic event id.\n- Watch target includes both `.beads/issues.jsonl` and `.beads/issues.jsonl.new`.\r\n","notes":"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.","status":"closed","priority":0,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:53.5050717-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:36:50.2745024-08:00","closed_at":"2026-02-11T20:36:50.2745024-08:00","close_reason":"Watcher lifecycle manager implemented with canonical project scoping and tested watch behavior.","labels":["chokidar","watcher"],"dependencies":[{"issue_id":"bb-tpc.1","depends_on_id":"bb-tpc","type":"parent-child","created_at":"2026-02-11T17:11:53.5071586-08:00","created_by":"zenchantlive"},{"issue_id":"bb-tpc.1","depends_on_id":"bb-6aj.2","type":"blocks","created_at":"2026-02-11T17:12:28.2304516-08:00","created_by":"zenchantlive"},{"issue_id":"bb-tpc.1","depends_on_id":"bb-tpc.5","type":"blocks","created_at":"2026-02-11T20:10:00.4246352-08:00","created_by":"zenchantlive"}]}
@ -46,16 +78,16 @@
{"id":"bb-trz.2","title":"Build bead cards with priority/type/labels/assignee/dependency metadata","description":"Design compact cards exposing the most actionable issue metadata while preserving readability at high board density.","acceptance_criteria":"Cards show id, priority, type, labels, assignee, and dependency indicators.","status":"closed","priority":1,"issue_type":"task","assignee":"agent-b","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:58.4435327-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:56:50.8141656-08:00","closed_at":"2026-02-11T17:56:50.8141656-08:00","close_reason":"Tracer bullet 1 Kanban baseline implemented and verified","labels":["cards","kanban"],"dependencies":[{"issue_id":"bb-trz.2","depends_on_id":"bb-trz","type":"parent-child","created_at":"2026-02-11T17:11:58.4450798-08:00","created_by":"zenchantlive"},{"issue_id":"bb-trz.2","depends_on_id":"bb-trz.1","type":"blocks","created_at":"2026-02-11T17:12:30.7837277-08:00","created_by":"zenchantlive"}]}
{"id":"bb-trz.3","title":"Implement detail slide-out panel with full issue metadata","description":"Add focused issue detail panel showing description, timestamps, dependencies, and lifecycle fields used by power users.","acceptance_criteria":"Selecting a card opens detail panel with complete issue context.","status":"closed","priority":1,"issue_type":"task","assignee":"agent-b","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:11:59.2746013-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:56:50.8161639-08:00","closed_at":"2026-02-11T17:56:50.8161639-08:00","close_reason":"Tracer bullet 1 Kanban baseline implemented and verified","labels":["details","kanban"],"dependencies":[{"issue_id":"bb-trz.3","depends_on_id":"bb-trz","type":"parent-child","created_at":"2026-02-11T17:11:59.2756402-08:00","created_by":"zenchantlive"},{"issue_id":"bb-trz.3","depends_on_id":"bb-trz.2","type":"blocks","created_at":"2026-02-11T17:12:31.2944-08:00","created_by":"zenchantlive"}]}
{"id":"bb-trz.4","title":"Add search/filter/stats controls for status/type/priority/labels","description":"Provide fast filtering and at-a-glance counts, including critical issue indicators, for daily planning and triage workflows.","acceptance_criteria":"Search and filters apply consistently across board and counts.","status":"closed","priority":1,"issue_type":"task","assignee":"agent-b","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:00.0927161-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:56:50.8186688-08:00","closed_at":"2026-02-11T17:56:50.8186688-08:00","close_reason":"Tracer bullet 1 Kanban baseline implemented and verified","labels":["filters","stats"],"dependencies":[{"issue_id":"bb-trz.4","depends_on_id":"bb-trz","type":"parent-child","created_at":"2026-02-11T17:12:00.0942721-08:00","created_by":"zenchantlive"},{"issue_id":"bb-trz.4","depends_on_id":"bb-trz.2","type":"blocks","created_at":"2026-02-11T17:12:31.798413-08:00","created_by":"zenchantlive"}]}
{"id":"bb-u6f","title":"Agent Session Views and Metrics","description":"Group work by agent session and actor fields to provide auditability and practical productivity insights for asynchronous coding workflows.","acceptance_criteria":"Session-based summaries and detail views are available per project and aggregate contexts.","notes":"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.","status":"open","priority":2,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:12.5083912-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:54:10.8939662-08:00","labels":["agents","sessions"],"dependencies":[{"issue_id":"bb-u6f","depends_on_id":"bb-tpc","type":"blocks","created_at":"2026-02-11T17:12:23.1727361-08:00","created_by":"zenchantlive"}]}
{"id":"bb-u6f.1","title":"Extract and normalize session identity fields from issue data","description":"Derive session grouping from closed_by_session, assignee, and created_by with robust fallback semantics.","acceptance_criteria":"Issues are consistently assigned to session buckets when data exists.","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:13.3239834-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:12:13.3239834-08:00","labels":["agents","data"],"dependencies":[{"issue_id":"bb-u6f.1","depends_on_id":"bb-u6f","type":"parent-child","created_at":"2026-02-11T17:12:13.3255058-08:00","created_by":"zenchantlive"},{"issue_id":"bb-u6f.1","depends_on_id":"bb-u6f.4","type":"blocks","created_at":"2026-02-11T20:09:55.5193741-08:00","created_by":"zenchantlive"}]}
{"id":"bb-u6f","title":"Agent Session Views and Metrics","description":"Provide agent-session accountability views for solo supervision: session list, per-session outcomes, and practical throughput metrics. Focus on operational decisions, not vanity dashboards.","acceptance_criteria":"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.","notes":"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.\nExecution 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.","status":"open","priority":1,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:12.5083912-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T12:45:51.8058469-08:00","labels":["agents","sessions"],"dependencies":[{"issue_id":"bb-u6f","depends_on_id":"bb-tpc","type":"blocks","created_at":"2026-02-11T17:12:23.1727361-08:00","created_by":"zenchantlive"},{"issue_id":"bb-u6f","depends_on_id":"bb-xhm","type":"blocks","created_at":"2026-02-12T12:45:51.3676788-08:00","created_by":"zenchantlive"},{"issue_id":"bb-u6f","depends_on_id":"bb-dcv","type":"blocks","created_at":"2026-02-12T21:40:13.985575-08:00","created_by":"zenchantlive"}]}
{"id":"bb-u6f.1","title":"Extract and normalize session identity fields from issue data","description":"Define the AgentSession model and implement logic to aggregate individual events and closed tasks into coherent sessions.\n\nFiles:\n- [NEW] src/lib/agent-sessions.ts -- Model types + aggregation logic\n\nData Contract:\ninterface AgentSession {\n id: string; // from closed_by_session or inferred\n startedAt: string; // ISO timestamp\n endedAt: string; // ISO timestamp\n closedIssueIds: string[];\n touchedIssueIds: string[];\n status: 'active' | 'completed';\n}\n\nAggregation Logic:\n1. Group by closed_by_session (hard link). All issues with same session ID belong together.\n2. Infer from ActivityLogs: For non-closed items, checking actor/time matches.\n3. MVP: Focus primarily on closed_by_session grouping.\n\nAcceptance Criteria:\n- AgentSession interface defined and exported.\n- aggregateSessions(issues, events) returns AgentSession[].\n- Correctly groups issues by closed_by_session.\n- Correctly computes start/end from closed_at timestamps.\n- Unit tests for aggregation logic.","acceptance_criteria":"Issues are consistently assigned to session buckets when data exists.","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:13.3239834-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:37:59.3265433-08:00","labels":["agents","data"],"dependencies":[{"issue_id":"bb-u6f.1","depends_on_id":"bb-u6f","type":"parent-child","created_at":"2026-02-11T17:12:13.3255058-08:00","created_by":"zenchantlive"},{"issue_id":"bb-u6f.1","depends_on_id":"bb-u6f.4","type":"blocks","created_at":"2026-02-11T20:09:55.5193741-08:00","created_by":"zenchantlive"}]}
{"id":"bb-u6f.2","title":"Build session list and detail views for claimed/completed/open outcomes","description":"Present session-level issue outcomes and navigation for operational review and accountability.","acceptance_criteria":"Users can inspect session summaries and drill into individual session issue sets.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:14.1559358-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:12:14.1559358-08:00","labels":["agents","ui"],"dependencies":[{"issue_id":"bb-u6f.2","depends_on_id":"bb-u6f","type":"parent-child","created_at":"2026-02-11T17:12:14.157502-08:00","created_by":"zenchantlive"},{"issue_id":"bb-u6f.2","depends_on_id":"bb-u6f.1","type":"blocks","created_at":"2026-02-11T17:12:37.9045555-08:00","created_by":"zenchantlive"},{"issue_id":"bb-u6f.2","depends_on_id":"bb-u6f.4","type":"blocks","created_at":"2026-02-11T20:09:57.2147927-08:00","created_by":"zenchantlive"}]}
{"id":"bb-u6f.3","title":"Add baseline productivity metrics (completion rate, throughput, active span)","description":"Compute lightweight operational metrics from session issue events and timestamps.","acceptance_criteria":"Metrics are available with documented definitions and caveats.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:15.0144056-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:12:15.0144056-08:00","labels":["agents","metrics"],"dependencies":[{"issue_id":"bb-u6f.3","depends_on_id":"bb-u6f","type":"parent-child","created_at":"2026-02-11T17:12:15.0155323-08:00","created_by":"zenchantlive"},{"issue_id":"bb-u6f.3","depends_on_id":"bb-u6f.2","type":"blocks","created_at":"2026-02-11T17:12:38.4424336-08:00","created_by":"zenchantlive"},{"issue_id":"bb-u6f.3","depends_on_id":"bb-u6f.4","type":"blocks","created_at":"2026-02-11T20:09:56.3707709-08:00","created_by":"zenchantlive"}]}
{"id":"bb-u6f.4","title":"Epic Design Gate: scope, decisions, and acceptance contract","description":"Design/discovery gate for bb-u6f before further implementation.\n\nMust capture:\n- Product intent and user outcomes for this epic\n- Explicit architecture decisions and tradeoffs\n- API/data contracts and edge cases\n- Windows-specific constraints and path/process assumptions\n- Test strategy and verification commands\n- Non-goals and out-of-scope boundaries\n\nCompletion rule:\nDo not start new implementation tasks in this epic until this gate is closed with agreed decisions.","acceptance_criteria":"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.","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T20:09:41.2150441-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:09:41.2150441-08:00","dependencies":[{"issue_id":"bb-u6f.4","depends_on_id":"bb-u6f","type":"parent-child","created_at":"2026-02-11T20:09:41.216603-08:00","created_by":"zenchantlive"}]}
{"id":"bb-xhm","title":"Timeline and Activity Feed","description":"Provide a chronological activity view derived from issue snapshots and updates, enabling users to review agent/system activity over time.","acceptance_criteria":"Users can inspect chronological issue lifecycle events with useful filtering.","notes":"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.","status":"open","priority":2,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:05.8525088-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:54:10.6071785-08:00","labels":["activity","timeline"],"dependencies":[{"issue_id":"bb-xhm","depends_on_id":"bb-tpc","type":"blocks","created_at":"2026-02-11T17:12:22.1602338-08:00","created_by":"zenchantlive"}]}
{"id":"bb-xhm.1","title":"Define activity event model for created/updated/closed/reopened actions","description":"Create stable event schema to represent issue lifecycle transitions and their project/session attribution.","acceptance_criteria":"Event model supports all required timeline activity types.","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:06.6781387-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:12:06.6781387-08:00","labels":["model","timeline"],"dependencies":[{"issue_id":"bb-xhm.1","depends_on_id":"bb-xhm","type":"parent-child","created_at":"2026-02-11T17:12:06.6791721-08:00","created_by":"zenchantlive"},{"issue_id":"bb-xhm.1","depends_on_id":"bb-xhm.4","type":"blocks","created_at":"2026-02-11T20:10:05.9709567-08:00","created_by":"zenchantlive"}]}
{"id":"bb-xhm.2","title":"Implement snapshot diffing for derived timeline events","description":"Compare periodic snapshots and watcher updates to infer meaningful change events without requiring write interception.","acceptance_criteria":"Diff engine emits deterministic event records for relevant field changes.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:07.5007059-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:12:07.5007059-08:00","labels":["diff","timeline"],"dependencies":[{"issue_id":"bb-xhm.2","depends_on_id":"bb-xhm","type":"parent-child","created_at":"2026-02-11T17:12:07.501756-08:00","created_by":"zenchantlive"},{"issue_id":"bb-xhm.2","depends_on_id":"bb-xhm.1","type":"blocks","created_at":"2026-02-11T17:12:35.3430513-08:00","created_by":"zenchantlive"},{"issue_id":"bb-xhm.2","depends_on_id":"bb-tpc.2","type":"blocks","created_at":"2026-02-11T17:12:35.8495336-08:00","created_by":"zenchantlive"},{"issue_id":"bb-xhm.2","depends_on_id":"bb-xhm.4","type":"blocks","created_at":"2026-02-11T20:10:07.6688195-08:00","created_by":"zenchantlive"}]}
{"id":"bb-xhm.3","title":"Build timeline UI with date grouping and project/assignee/event filters","description":"Render reverse-chronological feed suitable for morning review workflows with practical filter controls.","acceptance_criteria":"Timeline view supports grouping and filter combinations with acceptable performance.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:08.3834905-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T17:12:08.3834905-08:00","labels":["timeline","ui"],"dependencies":[{"issue_id":"bb-xhm.3","depends_on_id":"bb-xhm","type":"parent-child","created_at":"2026-02-11T17:12:08.3851144-08:00","created_by":"zenchantlive"},{"issue_id":"bb-xhm.3","depends_on_id":"bb-xhm.2","type":"blocks","created_at":"2026-02-11T17:12:36.3627477-08:00","created_by":"zenchantlive"},{"issue_id":"bb-xhm.3","depends_on_id":"bb-xhm.4","type":"blocks","created_at":"2026-02-11T20:10:06.8100606-08:00","created_by":"zenchantlive"}]}
{"id":"bb-xhm.4","title":"Epic Design Gate: scope, decisions, and acceptance contract","description":"Design/discovery gate for bb-xhm before further implementation.\n\nMust capture:\n- Product intent and user outcomes for this epic\n- Explicit architecture decisions and tradeoffs\n- API/data contracts and edge cases\n- Windows-specific constraints and path/process assumptions\n- Test strategy and verification commands\n- Non-goals and out-of-scope boundaries\n\nCompletion rule:\nDo not start new implementation tasks in this epic until this gate is closed with agreed decisions.","acceptance_criteria":"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.","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T20:09:39.3625154-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:09:39.3625154-08:00","dependencies":[{"issue_id":"bb-xhm.4","depends_on_id":"bb-xhm","type":"parent-child","created_at":"2026-02-11T20:09:39.3645827-08:00","created_by":"zenchantlive"}]}
{"id":"bb-u6f.4","title":"Epic Design Gate: scope, decisions, and acceptance contract","description":"Design/discovery gate for bb-u6f before further implementation.\n\nMust capture:\n- Product intent and user outcomes for this epic\n- Explicit architecture decisions and tradeoffs\n- API/data contracts and edge cases\n- Windows-specific constraints and path/process assumptions\n- Test strategy and verification commands\n- Non-goals and out-of-scope boundaries\n\nCompletion rule:\nDo not start new implementation tasks in this epic until this gate is closed with agreed decisions.","acceptance_criteria":"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.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T20:09:41.2150441-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T23:29:55.9362248-08:00","closed_at":"2026-02-12T23:29:55.9362248-08:00","dependencies":[{"issue_id":"bb-u6f.4","depends_on_id":"bb-u6f","type":"parent-child","created_at":"2026-02-11T20:09:41.216603-08:00","created_by":"zenchantlive"}]}
{"id":"bb-xhm","title":"Timeline and Activity Feed","description":"Build a high-signal timeline view that explains what changed, by whom, and when, without noise.\n\nProduct 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.\n\nArchitecture decisions:\n1. Snapshot-based diffing (not write interception) - keeps read/write boundary clean\n2. Derived events, not stored - ActivityEvent[] computed from JSONL diffs, not persisted separately\n3. In-memory snapshot store - watcher fires on changes, we diff previous vs current in memory\n4. Solo-dev focus - no multi-user attribution beyond created_by/assignee\n\nExecution order: bb-xhm.4 (design gate, DONE) -\u003e bb-xhm.1 (event model) -\u003e bb-xhm.2 (diffing) -\u003e bb-xhm.3 (UI)\n\nDependencies:\n- Depends on bb-bvn for shared UX and component patterns (DONE)\n- Depends on bb-tpc for live file watching and SSE transport (DONE)\n\nNon-goals:\n- No direct JSONL writes; read/write boundary preserved\n- No multi-user collaboration features\n- No persisted event store or event database\n\nAcceptance criteria:\n- Event model (bb-xhm.1) defines ActivityEventKind union with 16 transition types and ActivityEvent interface\n- Snapshot diffing (bb-xhm.2) produces deterministic ActivityEvent[] from JSONL changes with all field comparison rules\n- Timeline UI (bb-xhm.3) at /timeline renders events with date grouping, kind/assignee/project filters, and one-click navigation to issue context\n- All pages share the existing visual design system (dark theme, text-text-* tokens, rounded cards)\n- Tests exist for event model, diffing engine, and UI rendering\n- Typecheck and lint pass across all new files (bun run typecheck \u0026\u0026 bun run lint)","acceptance_criteria":"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.","notes":"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.\nExecution order set 2026-02-12: start after bb-bvn visual/interaction contracts are finalized; depends on bb-bvn for shared UX and component patterns.","status":"open","priority":1,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:05.8525088-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:08:37.3922977-08:00","labels":["activity","timeline"],"dependencies":[{"issue_id":"bb-xhm","depends_on_id":"bb-tpc","type":"blocks","created_at":"2026-02-11T17:12:22.1602338-08:00","created_by":"zenchantlive"},{"issue_id":"bb-xhm","depends_on_id":"bb-bvn","type":"blocks","created_at":"2026-02-12T12:45:52.624726-08:00","created_by":"zenchantlive"}]}
{"id":"bb-xhm.1","title":"Define activity event model for created/updated/closed/reopened actions","description":"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).\n\nFiles:\n- [NEW] src/lib/activity-events.ts -- Type definitions + factory helpers\n\nData contract:\n- 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\n- ActivityEvent interface with fields: id (monotonic counter), issueId, issueTitle, kind, at (ISO timestamp), projectRoot, actor (best-effort attribution from assignee/created_by), previousValue, newValue\n- createActivityEvent() factory function enforcing required fields at construction\n\nGrounding in existing types:\n- Builds on BeadIssue from src/lib/types.ts (uses status, assignee, created_by, dependencies, labels fields)\n- ProjectRoot string for multi-project support (matches IssuesChangedEvent convention from realtime.ts)\n\nAcceptance criteria:\n- ActivityEventKind union covers all 16 transition types listed above\n- ActivityEvent interface is exported and importable by bb-xhm.2 and bb-xhm.3\n- Factory function createActivityEvent() enforces required fields at construction time\n- Unit tests cover: creating each event kind, validating required fields, round-trip JSON serialization\n- Typecheck passes (bun run typecheck)","acceptance_criteria":"Event model supports all required timeline activity types.","status":"open","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:06.6781387-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:00:55.2316751-08:00","labels":["model","timeline"],"dependencies":[{"issue_id":"bb-xhm.1","depends_on_id":"bb-xhm","type":"parent-child","created_at":"2026-02-11T17:12:06.6791721-08:00","created_by":"zenchantlive"},{"issue_id":"bb-xhm.1","depends_on_id":"bb-xhm.4","type":"blocks","created_at":"2026-02-11T20:10:05.9709567-08:00","created_by":"zenchantlive"}]}
{"id":"bb-xhm.2","title":"Implement snapshot diffing for derived timeline events","description":"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.\n\nFiles:\n- [NEW] src/lib/snapshot-differ.ts -- Core diff logic\n- [MODIFY] src/lib/watcher.ts -- Wire differ into onFlush callback\n\nDiff algorithm:\n1. Read current issues.jsonl into Map\u003cid, BeadIssue\u003e\n2. Compare against previous snapshot (also Map\u003cid, BeadIssue\u003e):\n a. For each id in current but not previous: emit 'created'\n b. For each id in previous but not current: emit 'deleted'\n c. For each id in both: compare fields and emit specific events\n3. Store current as new 'previous' snapshot\n4. Return ActivityEvent[]\n\nField comparison rules:\n- status open-\u003eclosed: emit 'closed' (previousValue=old status, newValue='closed')\n- status closed-\u003eopen: emit 'reopened' (previousValue='closed', newValue=new status)\n- status other: emit 'status_changed' (previousValue=old, newValue=new)\n- title: emit 'title_changed' (previousValue=old title, newValue=new title)\n- priority: emit 'priority_changed' (previousValue=old as string, newValue=new as string)\n- assignee null-\u003eX: emit 'assigned' (previousValue=null, newValue=X)\n- assignee X-\u003enull: emit 'unassigned' (previousValue=X, newValue=null)\n- assignee X-\u003eY: emit 'reassigned' (previousValue=X, newValue=Y)\n- labels: emit 'labels_changed' (previousValue=removed labels comma-sep, newValue=added labels comma-sep)\n- dependencies: emit 'dependency_added'/'dependency_removed' (values are dep target strings)\n\nIntegration point:\nIssuesWatchManager.onFlush currently only emits IssuesChangedEvent (file-level). After this bead:\n1. onFlush reads new issues.jsonl\n2. Runs diffSnapshots(previous, current) to get ActivityEvent[]\n3. Emits activity events through a new ActivityEventBus (separate from IssuesEventBus)\n4. Stores current as new previous snapshot\n\nDepends on bb-xhm.1 for ActivityEvent types.\nDepends on bb-tpc.2 for coalesced watcher events.\n\nAcceptance criteria:\n- diffSnapshots(prev, curr, projectRoot) returns ActivityEvent[]\n- All field comparison rules above are implemented\n- Edge cases handled: empty previous (first load = all 'created'), identical snapshots (no events), issue with only updated_at changed (no event)\n- Unit tests: created, deleted, each field change, multiple changes per diff, no-op diff\n- Performance: diff of 200 issues completes in \u003c10ms\n- Typecheck passes (bun run typecheck)","acceptance_criteria":"Diff engine emits deterministic event records for relevant field changes.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:07.5007059-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:01:45.5437274-08:00","labels":["diff","timeline"],"dependencies":[{"issue_id":"bb-xhm.2","depends_on_id":"bb-xhm","type":"parent-child","created_at":"2026-02-11T17:12:07.501756-08:00","created_by":"zenchantlive"},{"issue_id":"bb-xhm.2","depends_on_id":"bb-xhm.1","type":"blocks","created_at":"2026-02-11T17:12:35.3430513-08:00","created_by":"zenchantlive"},{"issue_id":"bb-xhm.2","depends_on_id":"bb-tpc.2","type":"blocks","created_at":"2026-02-11T17:12:35.8495336-08:00","created_by":"zenchantlive"},{"issue_id":"bb-xhm.2","depends_on_id":"bb-xhm.4","type":"blocks","created_at":"2026-02-11T20:10:07.6688195-08:00","created_by":"zenchantlive"}]}
{"id":"bb-xhm.3","title":"Build timeline UI with date grouping and project/assignee/event filters","description":"Render a reverse-chronological activity feed as a new /timeline page. Date-grouped, filterable, and navigable to issue context in one click.\n\nFiles:\n- [NEW] src/app/timeline/page.tsx -- Server component (reads issues, computes initial snapshot)\n- [NEW] src/components/timeline/timeline-page.tsx -- Client component (SSE subscription, filters, rendering)\n- [NEW] src/components/timeline/timeline-event-row.tsx -- Single event row component\n- [NEW] src/components/timeline/timeline-filters.tsx -- Filter bar component\n\nUI contract:\n1. Date grouping: Events grouped by date headers ('Today', 'Yesterday', 'Feb 10', etc.)\n2. Event row: Shows icon (per event kind), issue ID (monospace), title, actor, relative timestamp\n3. Filters: Project (when multi-project), event kind (checkboxes), assignee, date range\n4. Navigation: Click any event row to navigate to the issue in Workflow Explorer (/graph)\n5. Live updates: Subscribe to ActivityEventBus via SSE for new events, prepend to feed\n6. Design: Follow existing visual system (dark theme, text-text-* tokens, rounded cards, border accents, same header/panel patterns as graph page)\n\nRouting:\n- Add /timeline Next.js route\n- Add link in Workflow Explorer header (next to existing Kanban link)\n\nDepends on bb-xhm.1 for ActivityEvent types.\nDepends on bb-xhm.2 for ActivityEventBus providing live events via SSE.\n\nAcceptance criteria:\n- /timeline page renders with date-grouped event feed\n- Each event kind displays appropriate icon and human-readable description\n- Filter by event kind works (toggle checkboxes)\n- Click on event row navigates to issue context in Workflow Explorer\n- Live SSE updates prepend new events at the top\n- Responsive: usable on mobile (single-column stack)\n- Typecheck and lint pass (bun run typecheck \u0026\u0026 bun run lint)\n- No regressions to existing Kanban or Graph pages","acceptance_criteria":"Timeline view supports grouping and filter combinations with acceptable performance.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:08.3834905-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:08:16.5334224-08:00","labels":["timeline","ui"],"dependencies":[{"issue_id":"bb-xhm.3","depends_on_id":"bb-xhm","type":"parent-child","created_at":"2026-02-11T17:12:08.3851144-08:00","created_by":"zenchantlive"},{"issue_id":"bb-xhm.3","depends_on_id":"bb-xhm.2","type":"blocks","created_at":"2026-02-11T17:12:36.3627477-08:00","created_by":"zenchantlive"},{"issue_id":"bb-xhm.3","depends_on_id":"bb-xhm.4","type":"blocks","created_at":"2026-02-11T20:10:06.8100606-08:00","created_by":"zenchantlive"}]}
{"id":"bb-xhm.4","title":"Epic Design Gate: scope, decisions, and acceptance contract","description":"Design/discovery gate for bb-xhm before further implementation.\n\nMust capture:\n- Product intent and user outcomes for this epic\n- Explicit architecture decisions and tradeoffs\n- API/data contracts and edge cases\n- Windows-specific constraints and path/process assumptions\n- Test strategy and verification commands\n- Non-goals and out-of-scope boundaries\n\nCompletion rule:\nDo not start new implementation tasks in this epic until this gate is closed with agreed decisions.","acceptance_criteria":"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.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T20:09:39.3625154-08:00","created_by":"zenchantlive","updated_at":"2026-02-12T21:09:39.2227447-08:00","closed_at":"2026-02-12T21:09:39.2227447-08:00","close_reason":"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.","dependencies":[{"issue_id":"bb-xhm.4","depends_on_id":"bb-xhm","type":"parent-child","created_at":"2026-02-11T20:09:39.3645827-08:00","created_by":"zenchantlive"}]}
{"id":"bb-ymg","title":"CLI Write-Back via bd.exe","description":"Write-back architecture for BeadBoard.\n\nScope:\n- All issue mutations must execute through bd.exe commands.\n- No direct writes to .beads/issues.jsonl are permitted anywhere in app code.\n- Mutation flow includes create/update/close/reopen/comment.\n\nDesign decisions:\n- Process execution uses child_process.execFile with arg arrays (no shell interpolation).\n- Commands run with project-scoped cwd so each request targets the intended repo.\n- Executable resolution supports explicit configured path and PATH fallback.\n- API responses are normalized with stable ok/error shape for frontend and tests.\n- UI writeback uses optimistic updates with rollback and authoritative re-read.\n\nImplemented artifacts:\n- src/lib/bd-path.ts\n- src/lib/bridge.ts\n- src/lib/mutations.ts\n- src/app/api/beads/{create,update,close,reopen,comment}/route.ts\n- src/app/api/beads/read/route.ts\n- src/lib/writeback.ts\n- Kanban drag-and-drop transition wiring in components.","acceptance_criteria":"Acceptance contract:\n1) Source tree has no direct issues.jsonl write path (guard test passes).\n2) Bridge returns structured command result including classification for timeout/not_found/non_zero_exit/bad_args.\n3) Mutation routes validate payloads and map operations to bd commands.\n4) Reopen and comment flows are supported and verified.\n5) Optimistic status updates rollback on failure and reconcile from authoritative read endpoint.\n6) typecheck + test + dev + mutation smoke lifecycle all pass.","status":"closed","priority":1,"issue_type":"epic","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:00.9164956-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:37:50.0859031-08:00","closed_at":"2026-02-11T20:37:50.0859031-08:00","close_reason":"Write-back epic unblocked and complete: bridge, mutation API, optimistic transitions, and drag/drop flows are implemented and verified.","labels":["bd-cli","mutation"],"dependencies":[{"issue_id":"bb-ymg","depends_on_id":"bb-trz","type":"blocks","created_at":"2026-02-11T17:12:21.1512868-08:00","created_by":"zenchantlive"},{"issue_id":"bb-ymg","depends_on_id":"bb-tpc","type":"blocks","created_at":"2026-02-11T17:12:21.6536312-08:00","created_by":"zenchantlive"}]}
{"id":"bb-ymg.1","title":"Implement bd bridge using child_process.execFile with project-scoped cwd","description":"Bridge layer requirements and implementation.\n\nCommand execution contract:\n- Uses execFile(command, args, options) with windowsHide and timeout.\n- Uses projectRoot as cwd for all commands.\n- Returns structured payload: success, classification, command, args, cwd, stdout, stderr, code, durationMs, error.\n\nError model:\n- not_found: executable missing / ENOENT.\n- timeout: ETIMEDOUT, killed process, or SIGTERM timeout path.\n- bad_args: non-zero exits with invalid/unknown/usage style stderr.\n- non_zero_exit: non-zero exits not classified as bad_args.\n- unknown: fallback classification.\n\nVerification:\n- tests/lib/bridge.test.ts covers success and all key failure classes.","acceptance_criteria":"Acceptance contract:\n- Bridge command execution is shell-safe and Windows-path-safe.\n- Structured result schema is stable and consumed by mutation layer.\n- Timeout and failure classes are deterministic under test.","notes":"Implemented src/lib/bridge.ts with execFile-based bd runner, project-scoped cwd, timeout support, structured command result payload, and failure classification (not_found, timeout, bad_args, non_zero_exit, unknown). Added RED-\u003eGREEN tests in tests/lib/bridge.test.ts.","status":"closed","priority":0,"issue_type":"task","assignee":"zenchantlive","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:01.7327732-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:14:33.7176637-08:00","closed_at":"2026-02-11T19:45:16.7478549-08:00","close_reason":"Bridge implemented with structured result/error classification and project-scoped execFile command execution; tests added.","labels":["bridge","execfile"],"dependencies":[{"issue_id":"bb-ymg.1","depends_on_id":"bb-ymg","type":"parent-child","created_at":"2026-02-11T17:12:01.7343468-08:00","created_by":"zenchantlive"},{"issue_id":"bb-ymg.1","depends_on_id":"bb-6aj.2","type":"blocks","created_at":"2026-02-11T17:12:32.3039711-08:00","created_by":"zenchantlive"}]}
{"id":"bb-ymg.1.1","title":"Resolve bd.exe location from PATH and configuration fallback","description":"Executable resolution contract.\n\nResolution order:\n1) explicit configured executable path (request/config)\n2) PATH scan for bd.exe, bd.cmd, bd.bat, bd\n\nFailure behavior:\n- Throw actionable guidance when missing, including install command:\n npm install -g @beads/bd\n- Error message explicitly mentions explicit path when provided but invalid.\n\nVerification:\n- tests/lib/bd-path.test.ts validates config-first behavior, PATH lookup, and missing executable guidance.","acceptance_criteria":"Acceptance contract:\n- Resolver is deterministic for config and PATH inputs.\n- Missing executable guidance is actionable and user-readable.","notes":"Implemented src/lib/bd-path.ts executable resolution with config-first then PATH lookup (bd.exe/bd.cmd/bd.bat/bd), plus actionable setup guidance when missing. Added tests/lib/bd-path.test.ts for success/failure cases.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-11T17:12:02.5593205-08:00","created_by":"zenchantlive","updated_at":"2026-02-11T20:14:34.4905469-08:00","closed_at":"2026-02-11T19:44:57.3720854-08:00","close_reason":"Executable resolution implemented with config/PATH fallback and actionable missing-bd guidance; tests added.","labels":["bridge","setup"],"dependencies":[{"issue_id":"bb-ymg.1.1","depends_on_id":"bb-ymg.1","type":"parent-child","created_at":"2026-02-11T17:12:02.5603636-08:00","created_by":"zenchantlive"}]}

139
docs/plans/2026-02-13-multi-project-ui-contract.md Normal file
View file

@ -0,0 +1,139 @@
# Multi-Project UI Contract (bb-6aj.6)
Date: 2026-02-13
Owner: `bb-6aj.6`
Scope: Convert existing registry/scanner backend into stable, user-facing project scope workflows for Kanban and Graph.
## 1) Product Workflow Contract
Primary user flow:
1. Select project scope (`local` or one registry project).
2. View project-scoped issues in Kanban and Graph using the same selected scope.
3. Manage registry roots (add/remove) from a single shared manager panel.
4. Discover import candidates from safe scan roots and add selected projects to registry.
5. (Later phase) Optionally switch to aggregate mode for cross-project read-only views.
Rules:
- Project scope is always explicit in URL query (`?project=`).
- Scope change affects reads only; mutations continue to target current scope root.
- Project scope must persist when navigating between `/` and `/graph`.
- No direct JSONL writes at any point.
## 2) Screen Ownership
Kanban (`/`):
- Primary triage and mutation workspace.
- Owns project scope picker entry point and registry manager entry.
- Displays selected project context in header.
Graph (`/graph`):
- Readability-first dependency exploration for selected scope.
- Shares same project scope query + model as Kanban.
- Must preserve current scope when linking back to Kanban.
Shared controls:
- Project scope resolver utility (server-safe).
- URL serialization/parsing for project selection.
- Scope badge/pill visual token (consistent across pages).
Out of scope for this contract:
- Timeline/session epics behavior changes.
- Full graph redesign beyond scope persistence/read correctness.
## 3) URL and State Contract
Query key:
- `project`: scope key string.
Key encoding:
- `local`: current workspace (`process.cwd()`).
- registry project: `windowsPathKey(project.path)` derived from registry entry.
Resolution behavior:
1. Build scope options: `local` + registry projects (dedup by key).
2. If `project` query matches an option key, use that root.
3. If missing or invalid, fallback to `local`.
4. Reads use resolved root; returned issues include resolved `project` context.
Navigation behavior:
- `Kanban -> Graph` carries `?project=<key>`.
- `Graph -> Kanban` carries `?project=<key>`.
- Any scope picker action rewrites URL query without losing active route.
## 4) Aggregate Mode Contract (Deferred to bb-6aj.11)
- Aggregate mode is read-only across multiple project roots.
- Aggregate mode does not become default.
- Aggregate mode must visually mark per-project source on each card/row.
- Mutations from aggregate mode are disabled until explicit target scope is chosen.
## 5) Empty and Error States
No projects in registry:
- Show local project as selected.
- Show non-blocking empty hint in manager panel.
Invalid query key:
- Fallback to local scope.
- Keep page functional; do not hard fail.
Read failure for selected root:
- Preserve selected scope in UI.
- Show actionable error card with path and retry affordance.
Scanner failures:
- Show root-level failure summary with skipped/error counts.
- Do not alter current selection automatically.
## 6) Phased Execution Plan
Phase A (`bb-6aj.7`): Shared scope model + URL persistence
- Add server utility to resolve active scope from query + registry.
- Wire `/` and `/graph` to resolved scope.
- Ensure cross-links preserve `?project=`.
Phase B (`bb-6aj.8`): Registry manager panel
- List registry projects with add/remove actions.
- Validate Windows absolute paths with clear error text.
Phase C (`bb-6aj.9`): Scanner UX
- Scan safe roots with mode/depth controls.
- Allow selective import to registry.
Phase D (`bb-6aj.10`): Project-scoped reads in core views
- Ensure all read endpoints/components use selected scope root.
- Validate no regressions in local-only flow.
Phase E (`bb-6aj.11`): Aggregate mode
- Add cross-project read view with project badges.
- Keep mutations disabled without explicit project selection.
Phase F (`bb-6aj.12`): Verification and guardrails
- Typecheck + tests + Playwright evidence at required breakpoints.
## 7) Acceptance Criteria Matrix
Functional:
- Same `project` key yields same root and same issue set on both pages.
- Invalid `project` key falls back to local root cleanly.
- Route transitions preserve selected scope.
Boundary safety:
- No direct `.beads/issues.jsonl` writes.
- Existing mutation API boundaries unchanged.
Verification:
- Unit tests for scope resolution and URL behavior.
- Existing tests remain green.
- Playwright captures prove scope persistence on `/` and `/graph`.
## 8) Risks and Mitigations
Risk: Query value leaks absolute paths.
- Mitigation: use opaque normalized key, not raw path.
Risk: Registry drift vs URL key stale.
- Mitigation: deterministic fallback to local + visible selected-scope indicator.
Risk: UX churn from adding controls too early.
- Mitigation: enforce phase order and keep Phase A minimal.

41
scripts/capture-graph.mjs Normal file
View file

@ -0,0 +1,41 @@
import { chromium } from 'playwright';
import path from 'node:path';
import fs from 'node:fs/promises';
const url = process.argv[2];
if (!url) {
console.error('Usage: node scripts/capture-graph.mjs <url>');
process.exit(1);
}
const outputDir = path.join('artifacts');
await fs.mkdir(outputDir, { recursive: true });
const browser = await chromium.launch({ headless: true });
async function screenshot(name, viewport, prepare) {
const page = await browser.newPage({ viewport });
await page.goto(url, { waitUntil: 'networkidle' });
await page.waitForTimeout(1000);
if (prepare) {
await prepare(page);
await page.waitForTimeout(450);
}
await page.screenshot({
path: path.join(outputDir, name),
fullPage: true,
});
await page.close();
}
await screenshot('graph-next-1440.png', { width: 1440, height: 900 });
await screenshot('graph-next-768.png', { width: 768, height: 1024 });
await screenshot('graph-next-390-overview.png', { width: 390, height: 844 });
await screenshot('graph-next-390-flow.png', { width: 390, height: 844 }, async (page) => {
const flowButton = page.getByRole('button', { name: 'Switch to Graph' });
if (await flowButton.count()) {
await flowButton.first().click();
}
});
await browser.close();

38
src/app/graph/page.tsx Normal file
View file

@ -0,0 +1,38 @@
import { DependencyGraphPage } from '../../components/graph/dependency-graph-page';
export const dynamic = 'force-dynamic';
import { readIssuesForScope } from '../../lib/aggregate-read';
import { resolveProjectScope } from '../../lib/project-scope';
import { listProjects } from '../../lib/registry';
interface GraphPageProps {
searchParams?: Promise<Record<string, string | string[] | undefined>>;
}
export default async function GraphPage({ searchParams }: GraphPageProps) {
const params = (await searchParams) ?? {};
const requestedProjectKey = typeof params.project === 'string' ? params.project : null;
const requestedMode = typeof params.mode === 'string' ? params.mode : null;
const registryProjects = await listProjects();
const scope = resolveProjectScope({
currentProjectRoot: process.cwd(),
registryProjects,
requestedProjectKey,
requestedMode,
});
const issues = await readIssuesForScope({
mode: scope.mode,
selected: scope.selected,
scopeOptions: scope.options,
});
return (
<DependencyGraphPage
issues={issues}
projectRoot={scope.selected.root}
projectScopeKey={scope.selected.key}
projectScopeOptions={scope.options}
projectScopeMode={scope.mode}
/>
);
}

219
src/components/graph/dependency-flow-strip.tsx Normal file
View file

@ -0,0 +1,219 @@
'use client';
import type { GraphNode } from '../../lib/graph';
import type { PathWorkspace } from '../../lib/graph-view';
import type { BeadIssue } from '../../lib/types';
/** Props for an individual flow card in the dependency strip. */
interface FlowCardProps {
/** The graph node data for this card. */
node: GraphNode;
/** Whether this card is the currently selected/focused task. */
selected: boolean;
/** Number of issues blocking this node. */
blockedBy: number;
/** Number of issues this node blocks. */
blocks: number;
/** Callback fired when the user clicks this card. */
onSelect: (id: string) => void;
}
/** Props for the DependencyFlowStrip component. */
interface DependencyFlowStripProps {
/** The computed path workspace containing blockers, focus, and dependents. */
workspace: PathWorkspace;
/** ID of the currently selected task, or null. */
selectedId: string | null;
/** Map of issue ID to blocker/blocks counts. */
signalById: Map<string, { blockedBy: number; blocks: number }>;
/** Callback fired when the user selects a card. */
onSelect: (id: string) => void;
}
/**
* Returns the Tailwind background color class for a status dot indicator.
*/
function statusDot(status: BeadIssue['status']): string {
switch (status) {
case 'open':
return 'bg-sky-400';
case 'in_progress':
return 'bg-amber-400';
case 'blocked':
return 'bg-rose-500';
case 'deferred':
return 'bg-slate-400';
case 'closed':
return 'bg-emerald-400';
case 'pinned':
return 'bg-violet-400';
case 'hooked':
return 'bg-orange-400';
default:
return 'bg-zinc-500';
}
}
/**
* A compact card representing a single node in the dependency flow.
* Shows ID, title, status, and blocker/blocks counts.
*/
function FlowCard({ node, selected, blockedBy, blocks, onSelect }: FlowCardProps) {
return (
<button
type="button"
onClick={() => onSelect(node.id)}
className={`workflow-card w-full rounded-xl px-3 py-2.5 text-left transition duration-200 ${selected
? 'workflow-card-selected'
: 'hover:border-sky-300/40 hover:bg-[linear-gradient(165deg,rgba(76,94,134,0.2),rgba(18,20,30,0.84))]'
}`}
>
{/* Header: node ID + status dot */}
<div className="flex items-center justify-between gap-2">
<span className="font-mono text-[9px] tracking-[0.04em] text-text-muted/80">{node.id}</span>
<span className={`h-2 w-2 shrink-0 rounded-full ${statusDot(node.status)}`} />
</div>
{/* Node title - truncates at 2 lines */}
<p className="mt-1 text-[12px] font-semibold leading-tight text-text-strong line-clamp-2">{node.title}</p>
{/* Dependency signal counts */}
<p className="mt-1 text-[10px] text-text-body">
{blockedBy} blockers &bull; {blocks} dependents
</p>
</button>
);
}
/**
* Renders a section header with a count badge.
*/
function SectionHeader({ label, count, color }: { label: string; count: number; color: string }) {
return (
<div className="flex items-center gap-2 mb-2">
<span className={`text-[10px] font-bold uppercase tracking-[0.15em] ${color}`}>{label}</span>
<span className="rounded-md bg-white/5 px-1.5 py-0.5 text-[9px] font-bold text-text-muted/60">{count}</span>
</div>
);
}
/**
* Renders the dependency flow as three responsive sections stacked vertically:
* Blocked By, Selected/Focus, and Blocks (Dependents).
* Each section uses a responsive wrapping grid so cards never overflow.
* On larger screens the three sections sit side-by-side; on smaller screens they stack.
*/
import { useState } from 'react';
// ... (FlowCardProps, DependencyFlowStripProps, statusDot, FlowCard, SectionHeader definitions remain unchanged)
/**
* Renders the dependency flow as three responsive sections stacked vertically:
* Blocked By, Selected/Focus, and Blocks (Dependents).
* Each section uses a responsive wrapping grid so cards never overflow.
* On larger screens the three sections sit side-by-side; on smaller screens they stack.
*/
export function DependencyFlowStrip({ workspace, selectedId, signalById, onSelect }: DependencyFlowStripProps) {
const [minimized, setMinimized] = useState(false);
// Flatten the multi-hop blocker/dependent arrays for display
const blockerNodes = workspace.blockers.flat();
const dependentNodes = workspace.dependents.flat();
return (
<div className="rounded-2xl border border-white/5 bg-white/[0.01] px-5 py-4 ring-1 ring-white/5 transition-all duration-300">
<div className="flex items-center justify-between mb-4">
<h3 className="text-[10px] font-bold uppercase tracking-[0.2em] text-text-muted/70">
Dependency Flow
</h3>
<button
onClick={() => setMinimized(!minimized)}
className="rounded p-1 hover:bg-white/5 text-text-muted transition-colors"
title={minimized ? "Expand" : "Minimize"}
>
<svg
xmlns="http://www.w3.org/2000/svg"
width="16"
height="16"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
strokeWidth="2"
strokeLinecap="round"
strokeLinejoin="round"
className={`transition-transform duration-200 ${minimized ? 'rotate-180' : ''}`}
>
<polyline points="18 15 12 9 6 15"></polyline>
</svg>
</button>
</div>
{/* Responsive three-column layout: stacks on mobile, side-by-side on desktop */}
{!minimized && (
<div className="grid gap-4 md:grid-cols-3 animate-in fade-in slide-in-from-top-2 duration-200">
{/* Blocked By section */}
<div>
<SectionHeader label="Blocked By" count={blockerNodes.length} color="text-rose-400/70" />
{blockerNodes.length > 0 ? (
<div className="grid gap-2 grid-cols-[repeat(auto-fill,minmax(12rem,1fr))]">
{blockerNodes.map((node) => (
<FlowCard
key={node.id}
node={node}
selected={selectedId === node.id}
blockedBy={signalById.get(node.id)?.blockedBy ?? 0}
blocks={signalById.get(node.id)?.blocks ?? 0}
onSelect={onSelect}
/>
))}
</div>
) : (
<div className="rounded-xl border border-dashed border-white/5 bg-white/[0.01] px-3 py-4 text-center">
<p className="text-[10px] text-text-muted/40">No blockers</p>
</div>
)}
</div>
{/* Selected / Focused task section */}
<div>
<SectionHeader label="Selected" count={workspace.focus ? 1 : 0} color="text-sky-400/70" />
{workspace.focus ? (
<FlowCard
node={workspace.focus}
selected
blockedBy={signalById.get(workspace.focus.id)?.blockedBy ?? 0}
blocks={signalById.get(workspace.focus.id)?.blocks ?? 0}
onSelect={onSelect}
/>
) : (
<div className="rounded-xl border border-dashed border-white/5 bg-white/[0.01] px-3 py-4 text-center">
<p className="text-[10px] text-text-muted/40">Select a task</p>
</div>
)}
</div>
{/* Blocks (Dependents) section */}
<div>
<SectionHeader label="Blocks" count={dependentNodes.length} color="text-amber-400/70" />
{dependentNodes.length > 0 ? (
<div className="grid gap-2 grid-cols-[repeat(auto-fill,minmax(12rem,1fr))]">
{dependentNodes.map((node) => (
<FlowCard
key={node.id}
node={node}
selected={selectedId === node.id}
blockedBy={signalById.get(node.id)?.blockedBy ?? 0}
blocks={signalById.get(node.id)?.blocks ?? 0}
onSelect={onSelect}
/>
))}
</div>
) : (
<div className="rounded-xl border border-dashed border-white/5 bg-white/[0.01] px-3 py-4 text-center">
<p className="text-[10px] text-text-muted/40">No dependents</p>
</div>
)}
</div>
</div>
)}
</div>
);
}

921
src/components/graph/dependency-graph-page.tsx Normal file
View file

@ -0,0 +1,921 @@
'use client';
import Link from 'next/link';
import { useRouter, useSearchParams } from 'next/navigation';
import { useCallback, useEffect, useMemo, useState } from 'react';
import {
MarkerType,
Position,
ReactFlowProvider,
type Edge,
type Node,
type NodeMouseHandler,
type NodeTypes,
} from '@xyflow/react';
import '@xyflow/react/dist/style.css';
import dagre from 'dagre';
import { EpicChipStrip } from './epic-chip-strip';
import { WorkflowTabs, type WorkflowTab } from './workflow-tabs';
import { TaskCardGrid, type BlockerDetail } from './task-card-grid';
import { TaskDetailsDrawer } from './task-details-drawer';
import { DependencyFlowStrip } from './dependency-flow-strip';
import { GraphNodeCard, type GraphNodeData } from './graph-node-card';
import { GraphSection } from './graph-section';
import { ProjectScopeControls } from '../shared/project-scope-controls';
import { buildGraphModel, type GraphNode } from '../../lib/graph';
import {
buildPathWorkspace,
type GraphHopDepth,
analyzeBlockedChain,
detectDependencyCycles,
} from '../../lib/graph-view';
import { buildBlockedByTree, type BlockedTreeNode } from '../../lib/kanban';
import { type BeadIssue } from '../../lib/types';
import type { ProjectScopeOption } from '../../lib/project-scope';
/** Props for the DependencyGraphPage component. */
interface DependencyGraphPageProps {
/** All issues in the project. */
issues: BeadIssue[];
/** The project root key for graph model construction. */
projectRoot: string;
/** URL scope key (local or registry key). */
projectScopeKey: string;
/** Available scope options for context rendering. */
projectScopeOptions: ProjectScopeOption[];
/** Scope mode selection from URL (single/aggregate). */
projectScopeMode: 'single' | 'aggregate';
}
/** Available hop depth values for the depth selector. */
const DEPTH_OPTIONS: GraphHopDepth[] = [1, 2, 'full'];
/**
* Positions nodes using the Dagre graph layout engine.
* This respects dependency direction (Left-to-Right) and creates a true flowchart.
*/
function layoutDagre(nodes: Node<GraphNodeData>[], edges: Edge[]): Node<GraphNodeData>[] {
const dagreGraph = new dagre.graphlib.Graph();
dagreGraph.setDefaultEdgeLabel(() => ({}));
// Set layout direction: 'LR' = Left-to-Right (Blocker -> Blocked)
dagreGraph.setGraph({ rankdir: 'LR' });
// Node dimensions (must match Card dimensions + some padding?)
// Card is ~280x120?
// We can be precise or approximate.
const nodeWidth = 320;
const nodeHeight = 150;
for (const node of nodes) {
dagreGraph.setNode(node.id, { width: nodeWidth, height: nodeHeight });
}
for (const edge of edges) {
dagreGraph.setEdge(edge.source, edge.target);
}
dagre.layout(dagreGraph);
// Apply positions back to nodes
// Dagre gives center coordinates (x, y). ReactFlow expects top-left?
// ReactFlow handles position as top-left by default.
// Wait, Dagre node `x,y` is the CENTER of the node?
// Let's check docs or common knowledge. Yes, Dagre usually returns center.
// ReactFlow nodes position is Top-Left.
return nodes.map((node) => {
const nodeWithPosition = dagreGraph.node(node.id);
return {
...node,
position: {
x: nodeWithPosition.x - nodeWidth / 2,
y: nodeWithPosition.y - nodeHeight / 2,
},
};
});
}
/**
* Main Workflow Explorer page component.
* Provides a tabbed interface for browsing tasks and visualizing dependencies.
*
* Layout structure:
* - Header: title + navigation
* - Toolbar: hop depth, filters, epic chips, tab switcher
* - Tasks tab: responsive card grid + details drawer
* - Dependencies tab: flow strip + ReactFlow graph
*/
export function DependencyGraphPage({
issues,
projectRoot,
projectScopeKey,
projectScopeOptions,
projectScopeMode,
}: DependencyGraphPageProps) {
const router = useRouter();
const searchParams = useSearchParams();
// --- State ---
const [selectedEpicId, setSelectedEpicId] = useState<string | null>(null);
const [selectedId, setSelectedId] = useState<string | null>(null);
const [depth, setDepth] = useState<GraphHopDepth>(2);
const [hideClosed, setHideClosed] = useState(false);
const [showBlockingOnly, setShowBlockingOnly] = useState(false);
const [showFilters, setShowFilters] = useState(false);
const [activeTab, setActiveTab] = useState<WorkflowTab>('tasks');
const [drawerOpen, setDrawerOpen] = useState(false);
// Task-specific: sort ready (actionable) tasks to the top
const [sortReadyFirst, setSortReadyFirst] = useState(true);
// Mobile panel toggle (preserved for mobile responsiveness)
const [mobilePanel, setMobilePanel] = useState<'overview' | 'flow'>('overview');
const requestedEpicId = searchParams.get('epic');
const requestedTaskId = searchParams.get('task');
const requestedTab = searchParams.get('tab');
const kanbanHref = useMemo(() => {
const params = new URLSearchParams();
if (projectScopeMode !== 'single') {
params.set('mode', projectScopeMode);
}
if (projectScopeKey !== 'local') {
params.set('project', projectScopeKey);
}
const query = params.toString();
return query ? `/?${query}` : '/';
}, [projectScopeKey, projectScopeMode]);
const activeScope = useMemo(
() => projectScopeOptions.find((option) => option.key === projectScopeKey) ?? projectScopeOptions[0] ?? null,
[projectScopeKey, projectScopeOptions],
);
// --- Derived data: epics ---
const epics = useMemo(
() =>
issues
.filter((issue) => issue.issue_type === 'epic')
.sort((a, b) => {
// Push closed epics to the end
if (a.status === 'closed' && b.status !== 'closed') return 1;
if (b.status === 'closed' && a.status !== 'closed') return -1;
return a.id.localeCompare(b.id);
}),
[issues],
);
// --- Derived data: tasks grouped by parent epic ---
const tasksByEpic = useMemo(() => {
const map = new Map<string, BeadIssue[]>();
// Initialize empty arrays for each epic
for (const epic of epics) {
map.set(epic.id, []);
}
// Assign each non-epic issue to its parent epic
for (const issue of issues) {
if (issue.issue_type === 'epic') continue;
const parentDep = issue.dependencies.find((dep) => dep.type === 'parent');
const candidateEpicId = parentDep?.target ?? (issue.id.includes('.') ? issue.id.split('.')[0] : null);
if (candidateEpicId && map.has(candidateEpicId)) {
map.get(candidateEpicId)?.push(issue);
}
}
// Sort tasks within each epic: filter by closed status, then by priority
for (const [epicId, children] of map.entries()) {
map.set(
epicId,
children
.filter((x) => (!hideClosed ? true : x.status !== 'closed'))
.sort((a, b) => {
const priorityDiff = a.priority - b.priority;
if (priorityDiff !== 0) return priorityDiff;
return a.id.localeCompare(b.id);
}),
);
}
return map;
}, [epics, hideClosed, issues]);
const beadCounts = useMemo(() => {
const counts = new Map<string, number>();
for (const epic of epics) {
counts.set(epic.id, tasksByEpic.get(epic.id)?.length ?? 0);
}
return counts;
}, [epics, tasksByEpic]);
// --- Derived: Map task ID to its Epic (for easy lookup) ---
const epicByTaskId = useMemo(() => {
const map = new Map<string, BeadIssue>();
// Iterate tasksByEpic map
for (const [epicId, tasks] of tasksByEpic.entries()) {
const epic = epics.find((e) => e.id === epicId);
if (!epic) continue;
for (const t of tasks) {
map.set(t.id, epic);
}
}
return map;
}, [epics, tasksByEpic]);
// --- Auto-select first epic if none selected ---
useEffect(() => {
if (epics.length === 0) {
if (selectedEpicId !== null) {
setSelectedEpicId(null);
}
return;
}
const hasSelectedEpic = selectedEpicId ? epics.some((epic) => epic.id === selectedEpicId) : false;
if (!hasSelectedEpic) {
setSelectedEpicId(epics[0].id);
}
}, [epics, selectedEpicId]);
useEffect(() => {
if (requestedTab === 'tasks' || requestedTab === 'dependencies') {
setActiveTab(requestedTab);
}
}, [requestedTab]);
useEffect(() => {
if (!requestedEpicId) return;
if (!epics.some((epic) => epic.id === requestedEpicId)) return;
setSelectedEpicId(requestedEpicId);
}, [epics, requestedEpicId]);
useEffect(() => {
if (!requestedTaskId) {
return;
}
if (!issues.some((issue) => issue.id === requestedTaskId)) {
return;
}
setSelectedId(requestedTaskId);
}, [issues, requestedTaskId]);
// If project scope changes and the selected task no longer exists, reset selection.
useEffect(() => {
if (!selectedId) {
return;
}
if (!issues.some((issue) => issue.id === selectedId)) {
setSelectedId(null);
}
}, [issues, selectedId]);
// --- Derived: selected epic and its tasks ---
const selectedEpic = useMemo(() => epics.find((epic) => epic.id === selectedEpicId) ?? null, [epics, selectedEpicId]);
const projectLevelTasks = useMemo(
() =>
issues
.filter((issue) => issue.issue_type !== 'epic')
.filter((issue) => (!hideClosed ? true : issue.status !== 'closed'))
.sort((a, b) => {
const priorityDiff = a.priority - b.priority;
if (priorityDiff !== 0) {
return priorityDiff;
}
return a.id.localeCompare(b.id);
}),
[hideClosed, issues],
);
const selectedEpicTasks = useMemo(() => {
const epicChildren = selectedEpic ? tasksByEpic.get(selectedEpic.id) ?? [] : [];
if (epicChildren.length > 0) {
return epicChildren;
}
// Fallback: some projects have tasks but weak/missing parent links.
// Keep the page usable by showing project-level tasks instead of a blank view.
if (projectLevelTasks.length > 0) {
return projectLevelTasks;
}
// Last-resort fallback: if there are only epics, render epics as selectable items.
return epics.filter((epic) => (!hideClosed ? true : epic.status !== 'closed'));
}, [epics, hideClosed, projectLevelTasks, selectedEpic, tasksByEpic]);
const selectedEpicHasChildren = useMemo(() => {
if (selectedEpic) {
return (tasksByEpic.get(selectedEpic.id) ?? []).length > 0;
}
return false;
}, [selectedEpic, tasksByEpic]);
// --- Auto-select best task when epic changes ---
useEffect(() => {
// Keep current selection if it remains visible in the current scope.
if (selectedId && selectedEpicTasks.some((task) => task.id === selectedId)) {
return;
}
const best = selectedEpicTasks.find((task) => task.status !== 'closed') ?? selectedEpicTasks[0] ?? null;
if (best?.id !== selectedId) {
setSelectedId(best?.id ?? null);
}
}, [selectedEpic, selectedEpicTasks, selectedId]);
// --- Graph model ---
const graphModel = useMemo(() => buildGraphModel(issues, { projectKey: projectRoot }), [issues, projectRoot]);
// --- Signal map: blocker/blocks counts per issue ---
const signalById = useMemo(() => {
const map = new Map<string, { blockedBy: number; blocks: number }>();
for (const issue of issues) {
const adjacency = graphModel.adjacency[issue.id];
map.set(issue.id, {
blockedBy: adjacency?.incoming.length ?? 0,
blocks: adjacency?.outgoing.length ?? 0,
});
}
return map;
}, [graphModel.adjacency, issues]);
// --- Blocker chain analysis for selected node ---
const blockerAnalysis = useMemo(() => {
if (!selectedId) return null;
return analyzeBlockedChain(graphModel, { focusId: selectedId });
}, [graphModel, selectedId]);
// --- Cycle detection across the entire graph ---
const cycleAnalysis = useMemo(() => {
return detectDependencyCycles(graphModel);
}, [graphModel]);
const cycleNodeIdSet = useMemo(() => new Set(cycleAnalysis.cycleNodeIds), [cycleAnalysis]);
// --- Path workspace: blockers and dependents for the selected node ---
const workspace = useMemo(
() =>
buildPathWorkspace(graphModel, {
focusId: selectedId,
depth,
hideClosed,
}),
[depth, graphModel, hideClosed, selectedId],
);
// --- Currently selected issue object ---
const selectedIssue = useMemo(() => issues.find((issue) => issue.id === selectedId) ?? null, [issues, selectedId]);
// --- Compute which node IDs are in the selected dependency chain (for dimming) ---
const chainNodeIds = useMemo(() => {
if (!selectedId || !blockerAnalysis) return new Set<string>();
const ids = new Set<string>([selectedId, ...blockerAnalysis.blockerNodeIds]);
// Also include dependents
for (const node of workspace.dependents.flat()) {
ids.add(node.id);
}
return ids;
}, [selectedId, blockerAnalysis, workspace.dependents]);
// --- Compute actionable (unblocked) status for each node ---
const actionableNodeIds = useMemo(() => {
const ids = new Set<string>();
for (const issue of issues) {
if (issue.status === 'closed') continue;
const adjacency = graphModel.adjacency[issue.id];
if (!adjacency) continue;
// A node is actionable if none of its incoming "blocks" edges come from non-closed nodes
const hasOpenBlocker = adjacency.incoming.some((edge) => {
if (edge.type !== 'blocks') return false;
const sourceNode = issues.find((i) => i.id === edge.source);
return sourceNode ? sourceNode.status !== 'closed' : false;
});
if (!hasOpenBlocker) {
ids.add(issue.id);
}
}
return ids;
}, [graphModel.adjacency, issues]);
// --- Sorted epic tasks: optionally sort ready/actionable tasks first ---
const sortedEpicTasks = useMemo(() => {
if (!sortReadyFirst) return selectedEpicTasks;
// Partition: ready (actionable + open) first, then in-progress, then blocked, then closed
return [...selectedEpicTasks].sort((a, b) => {
const aReady = actionableNodeIds.has(a.id) && a.status !== 'closed';
const bReady = actionableNodeIds.has(b.id) && b.status !== 'closed';
// Ready tasks bubble to the top
if (aReady && !bReady) return -1;
if (!aReady && bReady) return 1;
// Within same readiness group, keep original priority order
return 0;
});
}, [selectedEpicTasks, actionableNodeIds, sortReadyFirst]);
// --- Build blocker tooltip data per node ---
const blockerTooltipMap = useMemo(() => {
const map = new Map<string, string[]>();
for (const issue of issues) {
const adjacency = graphModel.adjacency[issue.id];
if (!adjacency) continue;
const lines: string[] = [];
for (const edge of adjacency.incoming) {
if (edge.type !== 'blocks') continue;
const source = issues.find((i) => i.id === edge.source);
if (source && source.status !== 'closed') {
lines.push(`${source.id} (${source.status}) - "${source.title}"`);
}
}
map.set(issue.id, lines);
}
return map;
}, [graphModel.adjacency, issues]);
// --- Detailed blocker info for task cards ---
const blockerDetailsMap = useMemo(() => {
const map = new Map<string, BlockerDetail[]>();
for (const task of selectedEpicTasks) {
const adjacency = graphModel.adjacency[task.id];
if (!adjacency) continue;
const details: BlockerDetail[] = [];
for (const edge of adjacency.incoming) {
if (edge.type !== 'blocks') continue;
const source = issues.find((i) => i.id === edge.source);
if (source && source.status !== 'closed') {
const sourceEpic = epicByTaskId.get(source.id);
details.push({
id: source.id,
title: source.title,
status: source.status,
priority: source.priority,
epicTitle: sourceEpic?.title,
});
}
}
if (details.length > 0) map.set(task.id, details);
}
return map;
}, [graphModel.adjacency, issues, selectedEpicTasks, epicByTaskId]);
// --- External blocker names for each task (shown inline on nodes) ---
const externalBlockerNames = useMemo(() => {
const epicTaskIds = new Set(selectedEpicTasks.map((t) => t.id));
const map = new Map<string, string[]>();
for (const task of selectedEpicTasks) {
const adjacency = graphModel.adjacency[task.id];
if (!adjacency) continue;
const externalNames: string[] = [];
for (const edge of adjacency.incoming) {
if (edge.type !== 'blocks') continue;
// Only include blockers from OUTSIDE this epic
if (!epicTaskIds.has(edge.source) && edge.source !== selectedEpicId) {
const source = issues.find((i) => i.id === edge.source);
if (source && source.status !== 'closed') {
externalNames.push(`${source.id}: ${source.title}`);
}
}
}
if (externalNames.length > 0) map.set(task.id, externalNames);
}
return map;
}, [graphModel.adjacency, issues, selectedEpicId, selectedEpicTasks]);
// --- Detailed downstream blocking info for task cards ---
const blocksDetailsMap = useMemo(() => {
const map = new Map<string, BlockerDetail[]>();
for (const task of selectedEpicTasks) {
const adjacency = graphModel.adjacency[task.id];
if (!adjacency) continue;
const details: BlockerDetail[] = [];
for (const edge of adjacency.outgoing) {
if (edge.type !== 'blocks') continue;
const target = issues.find((i) => i.id === edge.target);
if (target && target.status !== 'closed') {
const targetEpic = epicByTaskId.get(target.id);
details.push({
id: target.id,
title: target.title,
status: target.status,
priority: target.priority,
epicTitle: targetEpic?.title,
});
}
}
if (details.length > 0) map.set(task.id, details);
}
return map;
}, [graphModel.adjacency, issues, selectedEpicTasks, epicByTaskId]);
// --- ReactFlow model: ONLY this epic's tasks in status lanes ---
const flowModel = useMemo(() => {
if (selectedEpicTasks.length === 0) {
return { nodes: [] as Node<GraphNodeData>[], edges: [] as Edge[] };
}
// SCOPED: Only the epic's own child tasks (no cross-epic workspace nodes)
const issueById = new Map(issues.map((issue) => [issue.id, issue]));
const visibleTasks = selectedEpicTasks
.filter((issue) => (!hideClosed ? true : issue.status !== 'closed'));
// Build ReactFlow nodes with our custom GraphNodeData
const baseNodes: Node<GraphNodeData>[] = visibleTasks
.map((issue) => ({
id: issue.id,
data: {
title: issue.title,
kind: 'issue' as const,
status: issue.status,
priority: issue.priority,
blockedBy: signalById.get(issue.id)?.blockedBy ?? 0,
blocks: signalById.get(issue.id)?.blocks ?? 0,
isActionable: actionableNodeIds.has(issue.id),
isCycleNode: cycleNodeIdSet.has(issue.id),
isDimmed: selectedId ? !chainNodeIds.has(issue.id) : false,
blockerTooltipLines: externalBlockerNames.get(issue.id) ?? blockerTooltipMap.get(issue.id) ?? [],
},
position: { x: 0, y: 0 },
sourcePosition: Position.Right,
targetPosition: Position.Left,
type: 'flowNode',
}));
const visibleIds = new Set(baseNodes.map((node) => node.id));
const graphEdges: Edge[] = [];
// Search ALL issues for blocking edges between visible nodes.
// Dependencies may be stored on issues outside visibleTasks but
// still connect two nodes that are both visible in the graph.
for (const issue of issues) {
for (const dep of issue.dependencies) {
// Both endpoints must be visible in the graph
if (!visibleIds.has(issue.id) && !visibleIds.has(dep.target)) continue;
if (!visibleIds.has(issue.id) || !visibleIds.has(dep.target)) continue;
// Only show blocking edges (skip parent, relates_to, etc.)
if (dep.type !== 'blocks') continue;
// Avoid self-loops
if (issue.id === dep.target) continue;
const edgeId = `${issue.id}:blocks:${dep.target}`;
const linkedToSelection = selectedId ? issue.id === selectedId || dep.target === selectedId : false;
graphEdges.push({
id: edgeId,
source: issue.id,
target: dep.target,
className: linkedToSelection ? 'workflow-edge-selected' : 'workflow-edge-muted',
animated: linkedToSelection,
style: {
stroke: linkedToSelection ? '#7dd3fc' : '#fbbf24',
strokeWidth: linkedToSelection ? 2.5 : 1.8,
opacity: linkedToSelection ? 1 : 0.55,
},
markerEnd: { type: MarkerType.ArrowClosed, color: linkedToSelection ? '#7dd3fc' : '#fbbf24', width: 14, height: 14 },
});
}
}
return {
nodes: layoutDagre(baseNodes, graphEdges),
edges: graphEdges,
};
}, [
hideClosed, issues, selectedEpicTasks, selectedId,
signalById, actionableNodeIds, cycleNodeIdSet,
chainNodeIds, blockerTooltipMap, externalBlockerNames,
]);
const nodeTypes: NodeTypes = useMemo(
() => ({
// eslint-disable-next-line @typescript-eslint/no-explicit-any
flowNode: GraphNodeCard as any,
}),
[],
);
// --- Handle node click in the graph (also opens detail drawer) ---
const handleFlowNodeClick: NodeMouseHandler = useCallback((_, node) => {
setSelectedId(node.id);
setDrawerOpen(true);
}, []);
// --- Default edge rendering options ---
const defaultEdgeOptions = useMemo(
() => ({
type: 'smoothstep' as const,
zIndex: 40,
interactionWidth: 24,
}),
[],
);
// --- Handle task selection (opens drawer on Tasks tab) ---
// If the target is in another epic or IS an epic, switch to that epic first.
const handleTaskSelect = useCallback((id: string, shouldOpenDrawer = true) => {
// 1. If task is already visible in current epic view, just select it
if (selectedEpicTasks.some((t) => t.id === id)) {
setSelectedId(id);
if (shouldOpenDrawer) setDrawerOpen(true);
return;
}
// 2. If the target IS an epic itself, switch to that epic
const targetIsEpic = epics.some((e) => e.id === id);
if (targetIsEpic) {
setSelectedEpicId(id);
// Select the epic itself so the drawer shows its details
setSelectedId(id);
if (shouldOpenDrawer) setDrawerOpen(true);
return;
}
// 3. Target is a task in another epic -- find which epic owns it
const targetIssue = issues.find((i) => i.id === id);
if (targetIssue) {
// Determine parent epic: explicit parent dependency, or convention (id prefix before first dot)
const parentDep = targetIssue.dependencies.find((dep) => dep.type === 'parent');
const epicId = parentDep?.target ?? (targetIssue.id.includes('.') ? targetIssue.id.split('.')[0] : null);
if (epicId && epicId !== selectedEpicId) {
const epicExists = epics.some((e) => e.id === epicId);
if (epicExists) {
// If the target is closed and we are hiding closed tasks, unhide so we can see it
if (targetIssue.status === 'closed' && hideClosed) {
setHideClosed(false);
}
setSelectedEpicId(epicId);
setSelectedId(id);
if (shouldOpenDrawer) setDrawerOpen(true);
return;
}
}
}
// 4. Fallback: select the id directly (might be orphan)
setSelectedId(id);
if (shouldOpenDrawer) setDrawerOpen(true);
}, [selectedEpicTasks, selectedEpicId, issues, epics, hideClosed]);
// --- Handle drawer close ---
const handleDrawerClose = useCallback(() => {
setDrawerOpen(false);
}, []);
return (
<main className="mx-auto max-w-[1880px] px-4 py-4 sm:px-6 sm:py-6 lg:px-10">
{/* Page header */}
<header className="mb-6 rounded-3xl border border-white/5 bg-[radial-gradient(circle_at_2%_2%,rgba(56,189,248,0.12),transparent_40%),linear-gradient(170deg,rgba(15,23,42,0.92),rgba(11,12,16,0.95))] px-5 py-5 sm:px-8 sm:py-8 shadow-[0_32px_64px_-16px_rgba(0,0,0,0.6)] backdrop-blur-2xl">
<p className="font-mono text-[10px] uppercase tracking-[0.2em] text-sky-400/70 font-bold">BeadBoard Workspace</p>
<div className="mt-2 flex flex-wrap items-center justify-between gap-4">
<div className="flex items-center gap-4">
<h1 className="text-2xl font-bold tracking-tight text-text-strong sm:text-4xl">Workflow Explorer</h1>
<Link href={kanbanHref} className="rounded-xl border border-white/10 bg-white/5 px-3 py-1.5 text-[10px] font-bold text-text-body transition-all hover:bg-white/10 hover:border-white/20 sm:px-4 sm:text-xs">
&larr; Kanban
</Link>
</div>
<p className="hidden max-w-md text-sm leading-relaxed text-text-muted/90 sm:block">
Epic-driven dependency visualization. Drill into task relationships, triage blockers, and understand downstream impact at a glance.
</p>
</div>
{activeScope ? (
<p className="mt-3 text-xs text-text-muted/90">
Scope:{' '}
<span className="rounded-md border border-white/10 bg-white/5 px-2 py-0.5 font-mono text-[11px] text-text-body">
{activeScope.source === 'local' ? 'local workspace' : activeScope.displayPath}
</span>
</p>
) : null}
<div className="mt-3">
<ProjectScopeControls
projectScopeKey={projectScopeKey}
projectScopeMode={projectScopeMode}
projectScopeOptions={projectScopeOptions}
/>
</div>
</header>
{/* Main content area */}
<section className="rounded-[2.5rem] border border-white/5 bg-[linear-gradient(180deg,rgba(255,255,255,0.015),rgba(255,255,255,0.005))] shadow-2xl backdrop-blur-sm overflow-hidden">
{/* Toolbar row: epic chips + tab switcher */}
<div className="flex flex-wrap items-center gap-4 border-b border-white/5 px-6 py-4 bg-white/[0.02]">
{/* Epic chip strip - shows titles, not just IDs */}
<div className="flex-1 min-w-0">
<EpicChipStrip
epics={epics}
selectedEpicId={selectedEpicId}
beadCounts={beadCounts}
onSelect={setSelectedEpicId}
/>
</div>
{/* Right side: filter toggle + stats + mobile toggle */}
<div className="flex items-center gap-3">
{/* Filters toggle - hides power-user controls behind a button */}
<button
type="button"
onClick={() => setShowFilters((current) => !current)}
className={`rounded-xl border px-3 py-1.5 text-xs font-bold transition-all ${showFilters
? 'border-sky-400/30 bg-sky-400/10 text-sky-300'
: 'border-white/10 bg-white/5 text-text-muted hover:bg-white/10'
}`}
>
Filters {showFilters ? '▴' : '▾'}
</button>
{/* Mobile panel toggle */}
<div className="md:hidden">
<button
type="button"
onClick={() => setMobilePanel((current) => (current === 'overview' ? 'flow' : 'overview'))}
className="rounded-xl border border-sky-400/30 bg-sky-400/10 px-4 py-1.5 text-xs font-bold text-sky-300 transition-all hover:bg-sky-400/20"
>
{mobilePanel === 'overview' ? 'Switch to Graph' : 'Back to Selection'}
</button>
</div>
</div>
</div>
{/* Collapsible filters row - tab-aware: different filters per tab */}
{showFilters ? (
<div className="flex flex-wrap items-center gap-4 border-b border-white/5 px-6 py-3 bg-white/[0.01]">
{/* Shared filter: Hide closed */}
<label className="inline-flex cursor-pointer items-center gap-3 rounded-xl border border-white/10 bg-black/40 px-4 py-1.5 text-xs font-medium text-text-body transition-all hover:bg-white/5">
<input type="checkbox" className="h-3.5 w-3.5 rounded border-white/20 bg-white/5 text-sky-500" checked={hideClosed} onChange={(event) => setHideClosed(event.target.checked)} />
Hide closed
</label>
{/* Tasks-specific filters */}
{activeTab === 'tasks' ? (
<label className="inline-flex cursor-pointer items-center gap-3 rounded-xl border border-white/10 bg-black/40 px-4 py-1.5 text-xs font-medium text-text-body transition-all hover:bg-white/5">
<input type="checkbox" className="h-3.5 w-3.5 rounded border-white/20 bg-white/5 text-sky-500" checked={sortReadyFirst} onChange={(event) => setSortReadyFirst(event.target.checked)} />
Ready first
</label>
) : null}
{/* Dependencies-specific filters */}
{activeTab === 'dependencies' ? (
<>
<div className="flex items-center gap-3">
<label className="text-[10px] font-bold uppercase tracking-widest text-text-muted" htmlFor="depth-select">
Hop Depth
</label>
<select
id="depth-select"
className="ui-field ui-select rounded-xl px-3 py-1.5 text-xs font-medium ring-sky-400/20 focus:ring-2 outline-none transition-all"
value={String(depth)}
onChange={(event) => {
const value = event.target.value;
setDepth(value === 'full' ? 'full' : (Number(value) as 1 | 2));
}}
>
{DEPTH_OPTIONS.map((option) => (
<option className="ui-option" key={String(option)} value={String(option)}>
{option === 'full' ? 'Infinite' : `${option} hop${option === 1 ? '' : 's'}`}
</option>
))}
</select>
</div>
<label className="inline-flex cursor-pointer items-center gap-3 rounded-xl border border-white/10 bg-black/40 px-4 py-1.5 text-xs font-medium text-text-body transition-all hover:bg-white/5">
<input type="checkbox" className="h-3.5 w-3.5 rounded border-white/20 bg-white/5 text-sky-500" checked={showBlockingOnly} onChange={(event) => setShowBlockingOnly(event.target.checked)} />
Blocking path only
</label>
</>
) : null}
</div>
) : null}
{/* Tab switcher row + selected epic context */}
<div className="hidden md:flex items-center justify-between border-b border-white/5 px-6 py-3 bg-white/[0.01]">
<WorkflowTabs activeTab={activeTab} onTabChange={setActiveTab} />
{selectedEpic ? (
<div className="flex items-center gap-3 text-xs">
<span className="font-mono text-[10px] text-text-muted/50">{selectedEpic.id}</span>
<span className="font-medium text-text-body truncate max-w-[20rem]">{selectedEpic.title}</span>
{!selectedEpicHasChildren && projectLevelTasks.length > 0 ? (
<span className="rounded-md bg-sky-400/10 px-2 py-0.5 text-[9px] font-bold uppercase tracking-wider text-sky-300/90">
project tasks fallback
</span>
) : null}
<span className="rounded-md bg-white/5 px-2 py-0.5 text-[9px] font-bold uppercase tracking-wider text-text-muted/60">
{selectedEpicTasks.length} tasks
</span>
</div>
) : null}
</div>
{/* ====== MOBILE LAYOUT ====== */}
{/* Mobile: overview panel (epic selection + task cards + dep flow) */}
<div className={`${mobilePanel === 'overview' ? 'flex' : 'hidden'} flex-col gap-6 p-6 md:hidden`}>
<section className="space-y-6 rounded-3xl bg-[rgba(14,20,33,0.88)] p-6 ring-1 ring-white/10 backdrop-blur-xl">
{/* Epic selector as horizontal scroll */}
<div>
<h2 className="text-[10px] font-bold uppercase tracking-[0.2em] text-text-muted/70">1) Select Epic</h2>
<div className="mt-4">
<EpicChipStrip
epics={epics}
selectedEpicId={selectedEpicId}
beadCounts={beadCounts}
onSelect={setSelectedEpicId}
/>
</div>
</div>
{/* Selected epic info */}
<section className="rounded-2xl bg-white/5 p-5 ring-1 ring-white/5">
<h3 className="text-base font-bold text-text-strong">{selectedEpic?.title ?? 'No epic selected'}</h3>
<p className="mt-1 text-xs font-medium text-text-muted/80">
{selectedEpicTasks.length} tasks &bull; <span className="uppercase">{selectedEpic?.status ?? 'unknown'}</span>
</p>
</section>
{/* Task cards */}
<section className="rounded-2xl bg-white/[0.02] p-5 ring-1 ring-white/5">
<h3 className="mb-4 text-[10px] font-bold uppercase tracking-[0.2em] text-text-muted/70">2) Pick Task</h3>
<div className="max-h-[30vh] overflow-y-auto overscroll-contain custom-scrollbar">
<TaskCardGrid
tasks={sortedEpicTasks}
selectedId={selectedId}
signalById={signalById}
blockerDetailsMap={blockerDetailsMap}
blocksDetailsMap={blocksDetailsMap}
actionableIds={actionableNodeIds}
onSelect={handleTaskSelect}
/>
</div>
</section>
</section>
</div>
{/* ====== DESKTOP LAYOUT ====== */}
{/* Desktop: Tasks tab content - use conditional rendering, not Tailwind dynamic classes */}
{activeTab === 'tasks' ? (
<div className="hidden md:block p-6">
<TaskCardGrid
tasks={sortedEpicTasks}
selectedId={selectedId}
signalById={signalById}
blockerDetailsMap={blockerDetailsMap}
blocksDetailsMap={blocksDetailsMap}
actionableIds={actionableNodeIds}
onSelect={handleTaskSelect}
/>
</div>
) : null}
{/* Desktop: Dependencies tab content (graph only, no flow strip) */}
{activeTab === 'dependencies' ? (
<div className="hidden md:flex min-h-0 flex-col p-6">
{/* Dependency Flow Strip - above graph */}
<div className="mb-6">
<DependencyFlowStrip
workspace={workspace}
selectedId={selectedId}
signalById={signalById}
onSelect={setSelectedId}
/>
</div>
<ReactFlowProvider>
<GraphSection
nodes={flowModel.nodes}
edges={flowModel.edges}
nodeTypes={nodeTypes}
defaultEdgeOptions={defaultEdgeOptions}
onNodeClick={handleFlowNodeClick}
blockerAnalysis={blockerAnalysis}
hideClosed={hideClosed}
/>
</ReactFlowProvider>
</div>
) : null}
{/* Mobile: graph panel */}
<section className={`${mobilePanel === 'flow' ? 'flex' : 'hidden'} min-h-0 flex-col border-t border-white/10 bg-[rgba(8,12,20,0.9)] p-6 backdrop-blur-xl md:hidden`}>
<ReactFlowProvider>
<GraphSection
nodes={flowModel.nodes}
edges={flowModel.edges}
nodeTypes={nodeTypes}
defaultEdgeOptions={defaultEdgeOptions}
onNodeClick={handleFlowNodeClick}
blockerAnalysis={blockerAnalysis}
hideClosed={hideClosed}
/>
</ReactFlowProvider>
</section>
</section>
{/* Task details drawer - slides in from right on task selection */}
<TaskDetailsDrawer
issue={selectedIssue}
open={drawerOpen}
onClose={handleDrawerClose}
projectRoot={projectRoot}
editable={projectScopeMode === 'single'}
onIssueUpdated={() => router.refresh()}
blockedTree={selectedIssue ? buildBlockedByTree(issues, selectedIssue.id) : undefined}
outgoingBlocks={selectedId ? blocksDetailsMap.get(selectedId) ?? [] : []}
onSelectBlockedIssue={handleTaskSelect}
/>
</main>
);
}

139
src/components/graph/epic-chip-strip.tsx Normal file
View file

@ -0,0 +1,139 @@
'use client';
import { useState } from 'react';
import { Chip } from '../shared/chip';
import type { BeadIssue } from '../../lib/types';
/** Props for the EpicChipStrip component. */
interface EpicChipStripProps {
/** List of all epic issues to display as selectable chips. */
epics: BeadIssue[];
/** Currently selected epic ID, or null if none selected. */
selectedEpicId: string | null;
/** Map of epic ID to total bead (task) count. */
beadCounts: Map<string, number>;
/** Callback fired when the user clicks an epic chip. */
onSelect: (epicId: string) => void;
}
/**
* Returns the label and color for an epic's status.
*/
function statusStyle(status: BeadIssue['status']): { label: string; dot: string } {
switch (status) {
case 'open':
return { label: 'Open', dot: 'bg-sky-400' };
case 'in_progress':
return { label: 'In Progress', dot: 'bg-amber-400' };
case 'blocked':
return { label: 'Blocked', dot: 'bg-rose-500' };
case 'closed':
return { label: 'Done', dot: 'bg-emerald-400' };
case 'deferred':
return { label: 'Deferred', dot: 'bg-slate-400' };
default:
return { label: status, dot: 'bg-zinc-500' };
}
}
/**
* Renders an epic selector as a dropdown button that expands an inline selection panel.
* When collapsed: shows the selected epic's title as a button.
* When expanded: shows a horizontal strip of epic cards with ID, title, and status,
* pushing page content down naturally.
*/
export function EpicChipStrip({ epics, selectedEpicId, beadCounts, onSelect }: EpicChipStripProps) {
// Track whether the epic selector panel is expanded
const [expanded, setExpanded] = useState(false);
// Find the currently selected epic for the button label
const selectedEpic = epics.find((epic) => epic.id === selectedEpicId);
return (
<div className="relative">
{/* Collapsed state: button showing selected epic */}
<button
type="button"
onClick={() => setExpanded((current) => !current)}
className="flex items-center gap-2.5 rounded-xl border border-white/10 bg-white/[0.04] px-4 py-2 text-left transition-all hover:bg-white/[0.07] hover:border-white/15 active:scale-[0.98] w-full"
>
{/* Status dot */}
{selectedEpic ? (
<span className={`h-2.5 w-2.5 shrink-0 rounded-full ${statusStyle(selectedEpic.status).dot}`} />
) : null}
{/* Selected epic label */}
<div className="min-w-0 flex-1">
<span className="block text-[10px] font-bold uppercase tracking-wider text-text-muted/50">
Epic
</span>
<span className="block truncate text-sm font-semibold text-text-strong">
{selectedEpic ? selectedEpic.title : 'Select an epic'}
</span>
</div>
{/* Expand/collapse chevron */}
<span className="text-text-muted/50 text-sm shrink-0">
{expanded ? '\u25b2' : '\u25bc'}
</span>
</button>
{/* Expanded state: horizontal card strip */}
{expanded ? (
<div className="mt-2 rounded-2xl border border-white/8 bg-[#0c0e14]/95 p-3 shadow-[0_16px_48px_rgba(0,0,0,0.5)] backdrop-blur-lg animate-fade-in">
<div className="grid gap-2 grid-cols-[repeat(auto-fill,minmax(14rem,1fr))]">
{epics.map((epic) => {
// Determine if this card is the currently selected epic
const isSelected = epic.id === selectedEpicId;
// Closed epics get a muted visual treatment
const isClosed = epic.status === 'closed';
const style = statusStyle(epic.status);
const count = beadCounts.get(epic.id) ?? 0;
return (
<button
key={epic.id}
type="button"
onClick={() => {
onSelect(epic.id);
setExpanded(false);
}}
className={`flex flex-col gap-2 rounded-xl border px-3 py-2.5 text-left transition-all duration-200 ${isSelected
? 'border-sky-400/40 bg-sky-400/10 ring-1 ring-sky-400/15'
: isClosed
? 'border-white/5 bg-white/[0.02] opacity-50 hover:opacity-80'
: 'border-white/8 bg-white/[0.03] hover:bg-white/[0.06] hover:border-white/15'
}`}
>
{/* Top row: ID + Status + Priority */}
<div className="flex items-center justify-between gap-2 w-full">
<span className="font-mono text-[9px] uppercase tracking-wider text-text-muted/60">{epic.id}</span>
<div className="flex items-center gap-1.5">
<div className="flex items-center gap-1 rounded-md bg-white/5 px-1.5 py-0.5">
<span className={`h-1.5 w-1.5 rounded-full ${style.dot}`} />
<span className="text-[9px] font-bold uppercase tracking-wider text-text-muted/70">{style.label}</span>
</div>
<span className="text-[10px] font-bold text-amber-400/80 bg-amber-400/10 px-1.5 py-0.5 rounded">P{epic.priority}</span>
</div>
</div>
{/* Epic title */}
<p className={`text-[12px] font-semibold leading-tight text-text-strong line-clamp-2 ${isClosed ? 'line-through' : ''}`}>
{epic.title}
</p>
{/* Metadata Row: Bead Count */}
<div className="flex items-center gap-2 mt-1">
<span className="text-[10px] text-text-muted bg-white/5 px-2 py-0.5 rounded-full border border-white/5">
{count} {count === 1 ? 'bead' : 'beads'}
</span>
</div>
</button>
);
})}
</div>
</div>
) : null}
</div>
);
}

199
src/components/graph/graph-node-card.tsx Normal file
View file

@ -0,0 +1,199 @@
'use client';
import { useState } from 'react';
import { Handle, Position, type NodeProps, type Node } from '@xyflow/react';
import type { BeadIssue } from '../../lib/types';
/** Data payload for each custom ReactFlow node. */
export interface GraphNodeData {
/** Index signature required by ReactFlow's Node<Record<string, unknown>> constraint. */
[key: string]: unknown;
/** Display title of the task/epic. */
title: string;
/** Whether this is an epic or a regular issue. */
kind: 'epic' | 'issue';
/** Current workflow status. */
status: BeadIssue['status'];
/** Priority level (0 = highest). */
priority: number;
/** Number of issues blocking this node. */
blockedBy: number;
/** Number of issues this node blocks. */
blocks: number;
/** Whether this node has zero open blockers and is actionable. */
isActionable: boolean;
/** Whether this node is part of a dependency cycle. */
isCycleNode: boolean;
/** Whether this node should appear dimmed (not in selected chain). */
isDimmed: boolean;
/** Tooltip lines describing blocker details for hover display. */
blockerTooltipLines: string[];
}
/**
* Returns the Tailwind background color class for a status dot indicator.
*/
function statusDot(status: BeadIssue['status']): string {
switch (status) {
case 'open':
return 'bg-sky-400';
case 'in_progress':
return 'bg-amber-400';
case 'blocked':
return 'bg-rose-500';
case 'deferred':
return 'bg-slate-400';
case 'closed':
return 'bg-emerald-400';
case 'pinned':
return 'bg-violet-400';
case 'hooked':
return 'bg-orange-400';
default:
return 'bg-zinc-500';
}
}
/**
* Returns the base card style class based on the node kind (epic vs issue).
*/
function nodeStyle(kind: GraphNodeData['kind']): string {
return kind === 'epic'
? 'bg-[linear-gradient(160deg,rgba(56,189,248,0.06),rgba(15,23,42,0.9))] border-sky-400/15'
: 'bg-[linear-gradient(160deg,rgba(255,255,255,0.03),rgba(15,23,42,0.85))] border-white/8';
}
/**
* Custom ReactFlow node component with:
* - Status-aware styling (green glow for actionable, red ring for cycles)
* - Hover tooltip showing blocker details or "Ready to work"
* - Pulse animation on selection
* - Dim effect when not in the selected dependency chain
*/
export function GraphNodeCard({ id, data, selected }: NodeProps<Node<GraphNodeData>>) {
// Track hover state for tooltip visibility
const [hovered, setHovered] = useState(false);
return (
<div
className="relative"
onMouseEnter={() => setHovered(true)}
onMouseLeave={() => setHovered(false)}
>
{/* Target handle for incoming edges (from the left) */}
<Handle type="target" position={Position.Left} className="!opacity-0" />
{/* Main card body */}
<div
className={`group w-[18.5rem] rounded-xl border px-3 py-3 text-left transition-all duration-300 ${nodeStyle(data.kind)} ${
// Status-based left border accent for visual scanning
data.status === 'in_progress' ? 'border-l-2 border-l-amber-400/60' :
data.status === 'blocked' ? 'border-l-2 border-l-rose-500/60' :
data.status === 'closed' ? 'border-l-2 border-l-emerald-400/40 opacity-60' : ''
} ${
// Cycle detection ring
data.isCycleNode ? 'ring-2 ring-rose-400/55' : ''
} ${
// Actionable / "ready to work" glow effect
data.isActionable && !selected
? 'ring-1 ring-emerald-400/30 shadow-[0_0_20px_rgba(16,185,129,0.12)]'
: ''
} ${
// Selected state with pulse animation
selected
? 'border-sky-400/50 shadow-[0_20px_48px_-8px_rgba(0,0,0,0.5)] ring-1 ring-sky-400/20 node-select-pulse'
: 'hover:border-white/20 hover:shadow-[0_8px_32px_-4px_rgba(0,0,0,0.3)]'
} ${
// Dim effect for nodes not in the selected chain
data.isDimmed ? 'opacity-30' : 'opacity-100'
}`}
>
{/* Header: ID + priority + status badges */}
<div className="flex items-center justify-between gap-2 border-b border-white/5 pb-1.5 mb-1.5">
<span className="font-mono text-[9px] uppercase tracking-[0.12em] text-text-muted/60">{id}</span>
<div className="flex items-center gap-1.5">
{/* "READY" badge for actionable nodes */}
{data.isActionable ? (
<span className="rounded-md bg-emerald-500/15 px-1.5 py-0.5 text-[7px] font-bold uppercase tracking-wider text-emerald-400 ring-1 ring-emerald-500/20">
Ready
</span>
) : null}
{/* Status badge: IN PROGRESS, BLOCKED, DONE */}
{data.status === 'in_progress' ? (
<span className="rounded-md bg-amber-400/10 px-1.5 py-0.5 text-[7px] font-bold uppercase tracking-wider text-amber-400">
In Progress
</span>
) : data.status === 'blocked' ? (
<span className="rounded-md bg-rose-400/10 px-1.5 py-0.5 text-[7px] font-bold uppercase tracking-wider text-rose-400">
Blocked
</span>
) : data.status === 'closed' ? (
<span className="rounded-md bg-emerald-400/10 px-1.5 py-0.5 text-[7px] font-bold uppercase tracking-wider text-emerald-400">
Done
</span>
) : null}
<span className="text-[9px] font-bold uppercase tracking-wider text-text-muted/40">p{data.priority}</span>
<span className={`h-2 w-2 rounded-full ring-2 ring-black/40 ${statusDot(data.status)}`} />
</div>
</div>
{/* Title - strikethrough for closed tasks */}
<p className={`text-[15px] font-bold leading-[1.2] tracking-tight text-text-strong group-hover:text-sky-100 transition-colors ${data.status === 'closed' ? 'line-through opacity-70' : ''}`}>
{data.title}
</p>
{/* Footer: show blocker names for blocked tasks, click hint for others */}
{data.blockerTooltipLines.length > 0 ? (
<div className="mt-2 border-t border-white/5 pt-1.5">
<p className="text-[8px] font-bold uppercase tracking-widest text-rose-400/70 mb-0.5">Waiting on</p>
{data.blockerTooltipLines.slice(0, 2).map((line) => (
<p key={line} className="text-[9px] text-text-muted/70 truncate leading-tight">
{line}
</p>
))}
{data.blockerTooltipLines.length > 2 ? (
<p className="text-[8px] text-text-muted/50">
+{data.blockerTooltipLines.length - 2} more
</p>
) : null}
</div>
) : null}
</div>
{/* Tooltip: shown on hover with 300ms CSS delay */}
{hovered ? (
<div className="absolute left-1/2 top-full z-50 mt-2 -translate-x-1/2 animate-fade-in">
<div className="max-w-xs rounded-lg border border-white/10 bg-[#0d0f14]/95 px-3 py-2 shadow-[0_12px_32px_rgba(0,0,0,0.6)] backdrop-blur-lg">
{data.isActionable ? (
<>
<p className="text-[10px] font-bold text-emerald-400">Ready to work</p>
<p className="mt-0.5 text-[10px] text-text-muted/80">
No open blockers. {data.blocks} task{data.blocks === 1 ? '' : 's'} depend{data.blocks === 1 ? 's' : ''} on this.
</p>
</>
) : (
<>
<p className="text-[10px] font-bold text-rose-400">
Blocked by {data.blockedBy} task{data.blockedBy === 1 ? '' : 's'}
</p>
{data.blockerTooltipLines.length > 0 ? (
<ul className="mt-1 space-y-0.5">
{data.blockerTooltipLines.map((line) => (
<li key={line} className="text-[9px] text-text-muted/80">
&bull; {line}
</li>
))}
</ul>
) : null}
</>
)}
</div>
</div>
) : null}
{/* Source handle for outgoing edges (to the right) */}
<Handle type="source" position={Position.Right} className="!opacity-0" />
</div>
);
}

111
src/components/graph/graph-section.tsx Normal file
View file

@ -0,0 +1,111 @@
'use client';
import {
Background,
ReactFlow,
type Edge,
type Node,
type NodeMouseHandler,
type NodeTypes,
} from '@xyflow/react';
import type { BlockedChainAnalysis } from '../../lib/graph-view';
import type { GraphNodeData } from './graph-node-card';
/** Props for the GraphSection component. */
interface GraphSectionProps {
/** ReactFlow nodes with layout positions applied. */
nodes: Node<GraphNodeData>[];
/** ReactFlow edges connecting the nodes. */
edges: Edge[];
/** Map of custom node type names to their React components. */
nodeTypes: NodeTypes;
/** Default edge rendering options. */
defaultEdgeOptions: {
type: 'smoothstep';
zIndex: number;
interactionWidth: number;
};
/** Callback fired when a node is clicked in the graph. */
onNodeClick: NodeMouseHandler;
/** Optional blocker summary for the currently selected task. */
blockerAnalysis?: BlockedChainAnalysis | null;
/** Whether closed items are hidden from the graph workspace. */
hideClosed?: boolean;
}
/**
* Renders the ReactFlow graph with status-lane layout.
* Shows a compact legend and full graph viewport.
* Nodes are positioned in columns by status: Done | In Progress | Ready | Blocked.
*/
export function GraphSection({
nodes,
edges,
nodeTypes,
defaultEdgeOptions,
onNodeClick,
blockerAnalysis,
hideClosed = false,
}: GraphSectionProps) {
return (
<div className="flex flex-col gap-3">
{/* Compact legend + tip */}
<div className="workflow-graph-legend flex flex-wrap items-center justify-between gap-3 rounded-xl border border-white/5 bg-white/[0.02] px-3 py-2">
<p className="text-[10px] text-text-muted/60">
<span className="font-bold uppercase tracking-[0.15em]">Legend</span>
{' '}
{!hideClosed ? (
<>
<span className="text-emerald-400">Done</span>
{' \u2192 '}
</>
) : null}
<span className="text-amber-400">In Progress</span>
{' \u2192 '}
<span className="text-cyan-400">Ready</span>
{' \u2192 '}
<span className="text-rose-400">Blocked</span>
</p>
<p className="text-[10px] text-text-muted/40">
Click a task to see details &bull;{' '}
<span className="inline-block h-1 w-4 rounded bg-amber-400 align-middle" /> = blocks
</p>
{blockerAnalysis ? (
<p className="text-[10px] text-text-muted/60">
Open blockers: {blockerAnalysis.openBlockerCount}
{' | '}
In progress blockers: {blockerAnalysis.inProgressBlockerCount}
</p>
) : null}
</div>
{/* ReactFlow graph viewport */}
<div className="relative h-[60vh] min-h-[35rem] overflow-hidden rounded-2xl border border-white/5 bg-[radial-gradient(circle_at_50%_50%,rgba(15,23,42,0.4),rgba(5,8,15,0.8))] shadow-inner">
<ReactFlow
className="workflow-graph-flow"
defaultEdgeOptions={defaultEdgeOptions}
proOptions={{ hideAttribution: true }}
fitView
fitViewOptions={{ padding: 0.3 }}
minZoom={0.3}
maxZoom={1.5}
translateExtent={[
[-500, -500],
[3000, 2500],
]}
nodes={nodes}
edges={edges}
nodeTypes={nodeTypes}
nodesDraggable={false}
nodesConnectable={false}
elementsSelectable
onlyRenderVisibleElements
onNodeClick={onNodeClick}
>
<Background gap={32} size={1} color="rgba(255,255,255,0.03)" />
</ReactFlow>
</div>
</div>
);
}

366
src/components/graph/task-card-grid.tsx Normal file
View file

@ -0,0 +1,366 @@
'use client';
import type { BeadIssue } from '../../lib/types';
/** Props for an individual task card in the grid. */
/** Details for a blocker task shown on the card. */
export interface BlockerDetail {
id: string;
title: string;
status: BeadIssue['status'];
priority: BeadIssue['priority'];
epicTitle?: string;
}
/** Props for an individual task card in the grid. */
interface TaskCardProps {
/** The issue data for this card. */
issue: BeadIssue;
/** Whether this card is the currently selected task. */
selected: boolean;
/** Number of issues blocking this task. */
blockedBy: number;
/** Number of issues this task blocks. */
blocks: number;
/** List of issues blocking this task. */
blockers: BlockerDetail[];
/** List of issues this task blocks. */
blocking: BlockerDetail[];
/** Whether this task is actionable (unblocked). */
isActionable: boolean;
/** Callback fired when the user clicks this card (or a blocker). */
onSelect: (id: string, shouldOpenDrawer?: boolean) => void;
}
/** Props for the TaskCardGrid component. */
interface TaskCardGridProps {
/** List of tasks to display in the grid. */
tasks: BeadIssue[];
/** ID of the currently selected task, or null. */
selectedId: string | null;
/** Map of issue ID to blocker/blocks counts. */
signalById: Map<string, { blockedBy: number; blocks: number }>;
/** Map of issue ID to detailed blocker info. */
blockerDetailsMap: Map<string, BlockerDetail[]>;
/** Map of issue ID to detailed downstream blocking info. */
blocksDetailsMap: Map<string, BlockerDetail[]>;
/** Set of actionable (unblocked) task IDs. */
actionableIds: Set<string>;
/** Callback fired when the user selects a task. */
onSelect: (id: string, shouldOpenDrawer?: boolean) => void;
}
/**
* Returns the Tailwind background color class for a status dot indicator.
* Mirrors the statusDot function from the original monolith.
*/
function statusDot(status: BeadIssue['status']): string {
switch (status) {
case 'open':
return 'bg-sky-400';
case 'in_progress':
return 'bg-amber-400';
case 'blocked':
return 'bg-rose-500';
case 'deferred':
return 'bg-slate-400';
case 'closed':
return 'bg-emerald-400';
case 'pinned':
return 'bg-violet-400';
case 'hooked':
return 'bg-orange-400';
default:
return 'bg-zinc-500';
}
}
/**
* Returns a human-friendly label and text color class for a status.
*/
function statusBadge(status: BeadIssue['status'], isActionable: boolean, hasBlockers: boolean): { label: string; textColor: string; bgColor: string } {
// If effectively blocked (has open blockers), show Blocked (unless closed/done)
if (hasBlockers && status !== 'closed' && status !== 'in_progress') {
return { label: 'Blocked', textColor: 'text-rose-400', bgColor: 'bg-rose-400/10' };
}
// Special case: "Blocked Now Open" -> Ready
if (status === 'blocked' && isActionable) {
return { label: 'Ready', textColor: 'text-cyan-400', bgColor: 'bg-cyan-400/10' };
}
switch (status) {
case 'in_progress':
return { label: 'In Progress', textColor: 'text-amber-400', bgColor: 'bg-amber-400/10' };
case 'blocked':
return { label: 'Blocked', textColor: 'text-rose-400', bgColor: 'bg-rose-400/10' };
case 'closed':
return { label: 'Done', textColor: 'text-emerald-400', bgColor: 'bg-emerald-400/10' };
case 'deferred':
return { label: 'Deferred', textColor: 'text-slate-400', bgColor: 'bg-slate-400/10' };
case 'open':
// Open with no blockers -> Ready
return { label: 'Ready', textColor: 'text-cyan-400', bgColor: 'bg-cyan-400/10' };
default:
return { label: status, textColor: 'text-zinc-400', bgColor: 'bg-zinc-400/10' };
}
}
/**
* Returns a card-level border class based on status for visual distinction.
*/
function statusBorder(status: BeadIssue['status'], isActionable: boolean, hasBlockers: boolean): string {
if (hasBlockers && status !== 'closed' && status !== 'in_progress') {
return 'border-l-2 border-l-rose-500/60';
}
if (status === 'blocked' && isActionable) {
return 'border-l-2 border-l-cyan-400/60';
}
if (status === 'open') {
return 'border-l-2 border-l-cyan-400/60';
}
switch (status) {
case 'in_progress':
return 'border-l-2 border-l-amber-400/60';
case 'blocked':
return 'border-l-2 border-l-rose-500/60';
case 'closed':
return 'border-l-2 border-l-emerald-400/40 opacity-60';
default:
return '';
}
}
/**
* A single task card displaying the issue ID, title, priority, type, assignee,
* and detailed blocker list (interactive).
*/
function TaskCard({ issue, selected, blockedBy, blocks, blockers, blocking, isActionable, onSelect }: TaskCardProps) {
const hasBlockers = blockers.length > 0; // Note: blockers list only contains OPEN blockers (computed in page)
const badge = statusBadge(issue.status, isActionable, hasBlockers);
const projectName = (issue as BeadIssue & { project?: { name?: string } }).project?.name ?? null;
return (
<div
role="button"
tabIndex={0}
onClick={() => onSelect(issue.id, false)}
onKeyDown={(e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
onSelect(issue.id, false);
}
}}
className={`workflow-card group relative flex w-full flex-col rounded-xl px-4 py-4 text-left transition duration-200 ${statusBorder(
issue.status,
isActionable,
hasBlockers,
)} ${selected
? 'workflow-card-selected'
: 'hover:border-sky-300/40 hover:bg-[linear-gradient(165deg,rgba(76,94,134,0.2),rgba(18,20,30,0.84))]'
}`}
>
{/* Expand / Open Drawer Button */}
<button
type="button"
className="absolute right-2 top-2 z-10 rounded p-1.5 text-text-muted/50 hover:bg-white/10 hover:text-sky-300 transition-colors hover:opacity-100"
onClick={(e) => {
e.stopPropagation();
onSelect(issue.id, true);
}}
title="Open Details"
>
<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className="opacity-70 group-hover:opacity-100"><polyline points="15 3 21 3 21 9" /><polyline points="9 21 3 21 3 15" /><line x1="21" y1="3" x2="14" y2="10" /><line x1="3" y1="21" x2="10" y2="14" /></svg>
</button>
<div className="flex w-full items-start justify-between gap-3 pr-6">
<div className="flex flex-col gap-1.5 min-w-0 flex-1">
<div className="flex items-center gap-2">
<span className={`h-2 w-2 rounded-full ${statusDot(issue.status)} ring-1 ring-white/10`} />
<span className="font-mono text-[10px] text-text-muted">{issue.id}</span>
{/* Status Badge */}
<span className={`rounded px-1.5 py-0.5 text-[9px] font-bold uppercase tracking-wider ${badge.textColor} ${badge.bgColor}`}>
{badge.label}
</span>
</div>
{projectName ? (
<div className="inline-flex w-fit rounded border border-sky-300/25 bg-sky-500/10 px-1.5 py-0.5 font-mono text-[9px] text-sky-200">
project: {projectName}
</div>
) : null}
<h3 className="line-clamp-3 text-sm font-medium leading-snug text-text-strong">
{issue.title}
</h3>
</div>
</div>
{/* Labels */}
{issue.labels?.length > 0 ? (
<div className="mt-2 flex flex-wrap gap-1">
{issue.labels.map((label) => (
<span key={label} className="rounded bg-white/5 px-1.5 py-0.5 text-[9px] font-medium text-text-muted/80 backdrop-blur-sm border border-white/5">
{label}
</span>
))}
</div>
) : null}
{/* "Waiting On" section for blockers */}
{blockers.length > 0 ? (
<div className="mt-auto pt-2 w-full">
<div className="rounded-lg bg-black/20 p-2 border border-white/5">
<p className="mb-1.5 text-[9px] font-bold uppercase tracking-widest text-rose-400/80">Waiting On</p>
<div className="flex flex-col gap-1.5">
{blockers.map((blocker) => (
<div
key={blocker.id}
role="button"
tabIndex={0}
onClick={(e) => {
e.stopPropagation();
onSelect(blocker.id, false);
}}
onKeyDown={(e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.stopPropagation();
onSelect(blocker.id, false);
}
}}
className="group relative flex flex-col gap-0.5 rounded border border-white/5 bg-white/5 px-2.5 py-2 hover:border-sky-400/30 hover:bg-white/10 transition-colors"
>
{/* Expand Button */}
<button
type="button"
className="absolute right-1 top-1 z-10 rounded p-1 text-text-muted/50 hover:bg-white/10 hover:text-sky-300 transition-colors hover:opacity-100"
onClick={(e) => {
e.stopPropagation();
onSelect(blocker.id, true);
}}
title="Open Details"
>
<svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className="opacity-70 group-hover:opacity-100"><polyline points="15 3 21 3 21 9" /><polyline points="9 21 3 21 3 15" /><line x1="21" y1="3" x2="14" y2="10" /><line x1="3" y1="21" x2="10" y2="14" /></svg>
</button>
<div className="flex items-center gap-2 pr-5">
<span className={`h-1.5 w-1.5 shrink-0 rounded-full ${statusDot(blocker.status)}`} />
<span className="font-mono text-[9px] text-text-muted">{blocker.id}</span>
<span className="line-clamp-1 text-[10px] font-medium text-text-body">{blocker.title}</span>
</div>
{blocker.epicTitle ? (
<div className="pl-3.5 text-[9px] text-text-muted/60 truncate max-w-full pr-5">
<span className="group-hover:text-sky-300/70 transition-colors">↳ {blocker.epicTitle}</span>
</div>
) : null}
</div>
))}
</div>
</div>
</div>
) : null}
{/* "Blocking" section (downstream) */}
{blocking.length > 0 ? (
<div className={`${blockers.length > 0 ? 'mt-2' : 'mt-auto'} w-full`}>
<div className="rounded-lg bg-black/20 p-2 border border-white/5">
<p className="mb-1.5 text-[9px] font-bold uppercase tracking-widest text-amber-400/80">Blocking</p>
<div className="flex flex-col gap-1.5">
{blocking.map((item) => (
<div
key={item.id}
role="button"
tabIndex={0}
onClick={(e) => {
e.stopPropagation();
onSelect(item.id, false);
}}
onKeyDown={(e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.stopPropagation();
onSelect(item.id, false);
}
}}
className="group relative flex flex-col gap-0.5 rounded border border-white/5 bg-white/5 px-2.5 py-2 hover:border-sky-400/30 hover:bg-white/10 transition-colors"
>
{/* Expand Button */}
<button
type="button"
className="absolute right-1 top-1 z-10 rounded p-1 text-text-muted/50 hover:bg-white/10 hover:text-sky-300 transition-colors hover:opacity-100"
onClick={(e) => {
e.stopPropagation();
onSelect(item.id, true);
}}
title="Open Details"
>
<svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className="opacity-70 group-hover:opacity-100"><polyline points="15 3 21 3 21 9" /><polyline points="9 21 3 21 3 15" /><line x1="21" y1="3" x2="14" y2="10" /><line x1="3" y1="21" x2="10" y2="14" /></svg>
</button>
<div className="flex items-center gap-2 pr-5">
<span className={`h-1.5 w-1.5 shrink-0 rounded-full ${statusDot(item.status)}`} />
<span className="font-mono text-[9px] text-text-muted">{item.id}</span>
<span className="line-clamp-1 text-[10px] font-medium text-text-body">{item.title}</span>
</div>
{item.epicTitle ? (
<div className="pl-3.5 text-[9px] text-text-muted/60 truncate max-w-full pr-5">
<span className="group-hover:text-sky-300/70 transition-colors">↳ {item.epicTitle}</span>
</div>
) : null}
</div>
))}
</div>
</div>
</div>
) : null}
{/* Footer Metadata: Assignee, Due Date */}
<div className={`mt-3 flex w-full items-center justify-between border-t border-white/5 pt-3 text-[10px] text-text-muted/60`}>
<div className="flex items-center gap-3">
{/* Assignee */}
<div className="flex items-center gap-1.5">
<span className="i-lucide-user h-3 w-3 opacity-70" />
<span>{issue.assignee ?? 'Unassigned'}</span>
</div>
{/* Due Date (if exists) */}
{issue.due_at ? (
<div className="flex items-center gap-1.5">
<span className="i-lucide-calendar h-3 w-3 opacity-70" />
<span>{new Date(issue.due_at as string).toLocaleDateString(undefined, { month: 'short', day: 'numeric' })}</span>
</div>
) : null}
</div>
</div>
</div>
);
}
/**
* Renders a responsive grid of task cards.
* Uses auto-fill with minmax to prevent cards from being too narrow to read.
*/
export function TaskCardGrid({ tasks, selectedId, signalById, blockerDetailsMap, blocksDetailsMap, actionableIds, onSelect }: TaskCardGridProps) {
// Show an empty state when no tasks exist in the selected epic
if (tasks.length === 0) {
return (
<div className="rounded-2xl border border-dashed border-white/10 bg-white/[0.02] px-6 py-12 text-center">
<p className="text-xs font-medium uppercase tracking-widest text-text-muted/50">No tasks in this epic</p>
</div>
);
}
return (
<div className="grid gap-3 overflow-y-auto overscroll-contain pr-1 custom-scrollbar grid-cols-[repeat(auto-fill,minmax(18rem,1fr))]">
{tasks.map((task) => (
<TaskCard
key={task.id}
issue={task}
selected={selectedId === task.id}
blockedBy={signalById.get(task.id)?.blockedBy ?? 0}
blocks={signalById.get(task.id)?.blocks ?? 0}
blockers={blockerDetailsMap?.get(task.id) ?? []}
blocking={blocksDetailsMap?.get(task.id) ?? []}
isActionable={actionableIds?.has(task.id) ?? false}
onSelect={onSelect}
/>
))}
</div>
);
}

117
src/components/graph/task-details-drawer.tsx Normal file
View file

@ -0,0 +1,117 @@
'use client';
import { useEffect, useRef } from 'react';
import type { BeadIssue } from '../../lib/types';
import type { BlockedTreeNode } from '../../lib/kanban';
import { KanbanDetail } from '../kanban/kanban-detail';
/** Props for the TaskDetailsDrawer component. */
interface TaskDetailsDrawerProps {
/** The issue to display, or null if nothing is selected. */
issue: BeadIssue | null;
/** Whether the drawer is open (visible). */
open: boolean;
/** Callback fired when the user closes the drawer. */
onClose: () => void;
/** Project root for mutation requests. */
projectRoot?: string;
/** Whether editing is enabled for the drawer. */
editable?: boolean;
/** Callback fired after successful save. */
onIssueUpdated?: (issueId: string) => Promise<void> | void;
/** Tree of blocked issues (incoming). */
blockedTree?: { total: number; nodes: BlockedTreeNode[] };
/** List of issues blocked by this one (outgoing). */
outgoingBlocks?: { id: string; title: string; status: string }[];
/** Callback when a blocked/blocking issue is clicked. */
onSelectBlockedIssue?: (issueId: string) => void;
}
/**
* A slide-in drawer panel from the right side that shows full task details.
* Opens when a task is selected, closes via the X button or clicking the backdrop.
* Uses CSS translate for the slide animation.
*/
export function TaskDetailsDrawer({
issue,
open,
onClose,
projectRoot,
editable = true,
onIssueUpdated,
blockedTree,
outgoingBlocks,
onSelectBlockedIssue
}: TaskDetailsDrawerProps) {
// Reference for the drawer panel to manage focus trapping
const drawerRef = useRef<HTMLDivElement>(null);
// Close drawer on Escape key press
useEffect(() => {
if (!open) return;
function handleKeyDown(event: KeyboardEvent) {
if (event.key === 'Escape') {
onClose();
}
}
document.addEventListener('keydown', handleKeyDown);
return () => document.removeEventListener('keydown', handleKeyDown);
}, [open, onClose]);
return (
<>
{/* Backdrop overlay - click to close */}
<div
className={`fixed inset-0 z-40 bg-black/40 backdrop-blur-sm transition-opacity duration-300 ${open ? 'opacity-100' : 'pointer-events-none opacity-0'
}`}
onClick={onClose}
aria-hidden="true"
/>
{/* Drawer panel - slides in from right */}
<div
ref={drawerRef}
className={`fixed right-0 top-0 z-50 flex h-full w-full max-w-md flex-col border-l border-white/10 bg-[#0b0c10]/95 backdrop-blur-xl shadow-[-32px_0_64px_rgba(0,0,0,0.5)] transition-transform duration-300 ease-out ${open ? 'translate-x-0' : 'translate-x-full'
}`}
>
{/* Drawer header with close button */}
<div className="flex items-center justify-between border-b border-white/5 bg-white/[0.02] px-6 py-4">
<p className="text-[10px] font-bold uppercase tracking-[0.2em] text-text-muted/70">Task Details</p>
<button
type="button"
onClick={onClose}
className="rounded-lg border border-white/10 bg-white/5 px-3 py-1 text-xs font-bold text-text-body transition-all hover:bg-white/10 active:scale-95"
>
Close
</button>
</div>
{/* Scrollable content area */}
<div className="flex-1 overflow-y-auto overscroll-contain p-6 custom-scrollbar">
{issue ? (
<KanbanDetail
issue={issue}
framed={false}
projectRoot={projectRoot}
editable={editable}
onIssueUpdated={onIssueUpdated}
blockedTree={blockedTree}
outgoingBlocks={outgoingBlocks}
onSelectBlockedIssue={onSelectBlockedIssue}
/>
) : (
<div className="flex h-full items-center justify-center">
<p className="text-xs font-medium uppercase tracking-widest text-text-muted/50">
Select a task to view details
</p>
</div>
)}
</div>
</div>
</>
);
}

47
src/components/graph/workflow-tabs.tsx Normal file
View file

@ -0,0 +1,47 @@
'use client';
/** The two available view tabs in the Workflow Explorer. */
export type WorkflowTab = 'tasks' | 'dependencies';
/** Props for the WorkflowTabs component. */
interface WorkflowTabsProps {
/** The currently active tab. */
activeTab: WorkflowTab;
/** Callback fired when the user switches tabs. */
onTabChange: (tab: WorkflowTab) => void;
}
/** Tab label and key pairs for rendering. */
const TAB_OPTIONS: { key: WorkflowTab; label: string }[] = [
{ key: 'tasks', label: 'Tasks' },
{ key: 'dependencies', label: 'Dependencies' },
];
/**
* A two-tab switcher for toggling between the Tasks view and Dependencies view.
* Uses a pill-style indicator that slides to the active tab.
*/
export function WorkflowTabs({ activeTab, onTabChange }: WorkflowTabsProps) {
return (
<div className="inline-flex items-center gap-1 rounded-xl border border-white/8 bg-white/[0.02] p-1">
{TAB_OPTIONS.map((tab) => {
// Determine if this tab is currently active
const isActive = activeTab === tab.key;
return (
<button
key={tab.key}
type="button"
onClick={() => onTabChange(tab.key)}
className={`rounded-lg px-4 py-1.5 text-xs font-bold uppercase tracking-wider transition-all duration-200 ${isActive
? 'bg-sky-400/10 text-sky-200 shadow-[0_2px_8px_rgba(56,189,248,0.1)]'
: 'text-text-muted/60 hover:text-text-body hover:bg-white/[0.04]'
}`}
>
{tab.label}
</button>
);
})}
</div>
);
}

322
src/components/shared/project-scope-controls.tsx Normal file
View file

@ -0,0 +1,322 @@
'use client';
import { useMemo, useState } from 'react';
import { usePathname, useRouter, useSearchParams } from 'next/navigation';
import type { ProjectScopeMode, ProjectScopeOption } from '../../lib/project-scope';
interface ScannerProject {
key: string;
displayPath: string;
}
interface ScannerPayload {
projects: ScannerProject[];
stats: {
scannedDirectories: number;
ignoredDirectories: number;
skippedDirectories: number;
elapsedMs: number;
};
}
interface ProjectScopeControlsProps {
projectScopeKey: string;
projectScopeMode: ProjectScopeMode;
projectScopeOptions: ProjectScopeOption[];
}
function buildHref(pathname: string, mode: ProjectScopeMode, key: string): string {
const params = new URLSearchParams();
if (mode !== 'single') {
params.set('mode', mode);
}
if (key !== 'local') {
params.set('project', key);
}
const query = params.toString();
return query ? `${pathname}?${query}` : pathname;
}
export function ProjectScopeControls({
projectScopeKey,
projectScopeMode,
projectScopeOptions,
}: ProjectScopeControlsProps) {
const pathname = usePathname();
const searchParams = useSearchParams();
const router = useRouter();
const [open, setOpen] = useState(false);
const [addPath, setAddPath] = useState('');
const [statusMessage, setStatusMessage] = useState<string | null>(null);
const [busy, setBusy] = useState(false);
const [scanResult, setScanResult] = useState<ScannerPayload | null>(null);
const [scanMode, setScanMode] = useState<'default' | 'full-drive'>('default');
const selected = useMemo(
() => projectScopeOptions.find((option) => option.key === projectScopeKey) ?? projectScopeOptions[0] ?? null,
[projectScopeKey, projectScopeOptions],
);
const discovered = useMemo(() => {
if (!scanResult) {
return [];
}
const registered = new Set(projectScopeOptions.map((option) => option.key));
return scanResult.projects.filter((project) => !registered.has(project.key));
}, [projectScopeOptions, scanResult]);
const navigate = (mode: ProjectScopeMode, key: string) => {
const href = buildHref(pathname, mode, key);
router.push(href);
router.refresh();
};
const setMode = (mode: ProjectScopeMode) => {
navigate(mode, projectScopeKey);
};
const setProjectKey = (key: string) => {
navigate(projectScopeMode, key);
};
const addProject = async () => {
if (!addPath.trim()) {
setStatusMessage('Enter an absolute Windows path (example: C:/Repos/MyProject).');
return;
}
setBusy(true);
setStatusMessage(null);
try {
const response = await fetch('/api/projects', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ path: addPath.trim() }),
});
const payload = (await response.json()) as { error?: string };
if (!response.ok) {
throw new Error(payload.error ?? 'Failed to add project.');
}
setAddPath('');
setStatusMessage('Project added.');
router.refresh();
} catch (error) {
setStatusMessage(error instanceof Error ? error.message : 'Failed to add project.');
} finally {
setBusy(false);
}
};
const removeProject = async (path: string, key: string) => {
setBusy(true);
setStatusMessage(null);
try {
const response = await fetch('/api/projects', {
method: 'DELETE',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ path }),
});
const payload = (await response.json()) as { error?: string };
if (!response.ok) {
throw new Error(payload.error ?? 'Failed to remove project.');
}
if (projectScopeKey === key) {
navigate(projectScopeMode, 'local');
} else {
router.refresh();
}
setStatusMessage('Project removed.');
} catch (error) {
setStatusMessage(error instanceof Error ? error.message : 'Failed to remove project.');
} finally {
setBusy(false);
}
};
const runScan = async () => {
setBusy(true);
setStatusMessage(null);
try {
const response = await fetch(`/api/scan?mode=${scanMode}`, { cache: 'no-store' });
const payload = (await response.json()) as ScannerPayload & { error?: string };
if (!response.ok) {
throw new Error(payload.error ?? 'Scan failed.');
}
setScanResult(payload);
setStatusMessage(`Scan complete. Found ${payload.projects.length} projects.`);
} catch (error) {
setStatusMessage(error instanceof Error ? error.message : 'Scan failed.');
} finally {
setBusy(false);
}
};
const importProject = async (project: ScannerProject) => {
setBusy(true);
setStatusMessage(null);
try {
const response = await fetch('/api/projects', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ path: project.displayPath }),
});
const payload = (await response.json()) as { error?: string };
if (!response.ok) {
throw new Error(payload.error ?? 'Import failed.');
}
setStatusMessage(`Imported ${project.displayPath}`);
router.refresh();
} catch (error) {
setStatusMessage(error instanceof Error ? error.message : 'Import failed.');
} finally {
setBusy(false);
}
};
return (
<section className="rounded-xl border border-border-soft bg-surface/65 p-3">
<div className="flex flex-wrap items-center gap-2">
<label className="text-[11px] font-semibold uppercase tracking-[0.12em] text-text-muted">Scope</label>
<select
className="ui-field ui-select rounded-lg px-2 py-1 text-xs"
value={projectScopeKey}
onChange={(event) => setProjectKey(event.target.value)}
>
{projectScopeOptions.map((option) => (
<option className="ui-option" key={option.key} value={option.key}>
{option.source === 'local' ? 'Local workspace' : option.displayPath}
</option>
))}
</select>
<label className="text-[11px] font-semibold uppercase tracking-[0.12em] text-text-muted">Mode</label>
<select
className="ui-field ui-select rounded-lg px-2 py-1 text-xs"
value={projectScopeMode}
onChange={(event) => setMode(event.target.value as ProjectScopeMode)}
>
<option className="ui-option" value="single">Single project</option>
<option className="ui-option" value="aggregate">Aggregate</option>
</select>
<button
type="button"
onClick={() => setOpen((value) => !value)}
className="rounded-lg border border-border-soft bg-surface-muted/70 px-2.5 py-1 text-xs text-text-body"
>
{open ? 'Hide manager' : 'Manage projects'}
</button>
</div>
{selected ? (
<p className="mt-2 text-xs text-text-muted">
Active: <span className="font-mono text-text-body">{selected.source === 'local' ? 'local workspace' : selected.displayPath}</span>
</p>
) : null}
{open ? (
<div className="mt-3 grid gap-3 border-t border-border-soft pt-3">
<div className="rounded-lg border border-border-soft/80 bg-surface/55 p-2.5">
<p className="text-[11px] font-semibold uppercase tracking-[0.12em] text-text-muted">Add project root</p>
<div className="mt-2 flex flex-wrap gap-2">
<input
type="text"
className="ui-field flex-1 rounded-lg px-2 py-1.5 text-xs"
placeholder="C:/Repos/MyProject"
value={addPath}
onChange={(event) => setAddPath(event.target.value)}
/>
<button
type="button"
disabled={busy}
onClick={() => void addProject()}
className="rounded-lg border border-border-soft bg-surface-muted/70 px-2.5 py-1.5 text-xs text-text-body disabled:opacity-60"
>
Add
</button>
</div>
</div>
<div className="rounded-lg border border-border-soft/80 bg-surface/55 p-2.5">
<p className="text-[11px] font-semibold uppercase tracking-[0.12em] text-text-muted">Registered projects</p>
<div className="mt-2 space-y-1.5">
{projectScopeOptions.filter((option) => option.source === 'registry').map((option) => (
<div key={option.key} className="flex items-center justify-between gap-2 rounded-md border border-border-soft/80 bg-surface-muted/40 px-2 py-1.5">
<button
type="button"
onClick={() => setProjectKey(option.key)}
className="truncate text-left font-mono text-xs text-text-body hover:text-sky-100"
title={option.displayPath}
>
{option.displayPath}
</button>
<button
type="button"
disabled={busy}
onClick={() => void removeProject(option.displayPath, option.key)}
className="rounded border border-rose-300/30 bg-rose-500/10 px-1.5 py-0.5 text-[11px] text-rose-100 disabled:opacity-60"
>
Remove
</button>
</div>
))}
{projectScopeOptions.every((option) => option.source !== 'registry') ? (
<p className="text-xs text-text-muted">No registered projects yet.</p>
) : null}
</div>
</div>
<div className="rounded-lg border border-border-soft/80 bg-surface/55 p-2.5">
<div className="flex flex-wrap items-center gap-2">
<p className="text-[11px] font-semibold uppercase tracking-[0.12em] text-text-muted">Scanner</p>
<select
className="ui-field ui-select rounded-lg px-2 py-1 text-xs"
value={scanMode}
onChange={(event) => setScanMode(event.target.value as 'default' | 'full-drive')}
>
<option className="ui-option" value="default">Safe roots</option>
<option className="ui-option" value="full-drive">Full drive</option>
</select>
<button
type="button"
disabled={busy}
onClick={() => void runScan()}
className="rounded-lg border border-border-soft bg-surface-muted/70 px-2.5 py-1 text-xs text-text-body disabled:opacity-60"
>
Run scan
</button>
</div>
{scanResult ? (
<p className="mt-2 text-[11px] text-text-muted">
scanned {scanResult.stats.scannedDirectories}, ignored {scanResult.stats.ignoredDirectories}, skipped {scanResult.stats.skippedDirectories} ({scanResult.stats.elapsedMs}ms)
</p>
) : null}
{discovered.length > 0 ? (
<div className="mt-2 max-h-40 space-y-1.5 overflow-y-auto pr-1">
{discovered.map((project) => (
<div key={project.key} className="flex items-center justify-between gap-2 rounded-md border border-border-soft/80 bg-surface-muted/40 px-2 py-1.5">
<span className="truncate font-mono text-xs text-text-body" title={project.displayPath}>
{project.displayPath}
</span>
<button
type="button"
disabled={busy}
onClick={() => void importProject(project)}
className="rounded border border-sky-300/30 bg-sky-500/10 px-1.5 py-0.5 text-[11px] text-sky-100 disabled:opacity-60"
>
Import
</button>
</div>
))}
</div>
) : scanResult ? (
<p className="mt-2 text-xs text-text-muted">No new projects to import.</p>
) : null}
</div>
{statusMessage ? <p className="text-xs text-text-muted">{statusMessage}</p> : null}
</div>
) : null}
{searchParams.get('project') && projectScopeKey === 'local' ? (
<p className="mt-2 text-[11px] text-amber-200/90">Unknown project key in URL; fell back to local workspace.</p>
) : null}
</section>
);
}

69
src/lib/aggregate-read.ts Normal file
View file

@ -0,0 +1,69 @@
import type { BeadDependency, BeadIssueWithProject } from './types';
import type { ProjectScopeOption } from './project-scope';
import { readIssuesFromDisk } from './read-issues';
function scopeIssueId(projectKey: string, issueId: string): string {
return `${projectKey}::${issueId}`;
}
function remapDependencies(
dependencies: BeadDependency[],
scopedIssueByOriginalId: Map<string, string>,
): BeadDependency[] {
return dependencies.map((dependency) => ({
...dependency,
target: scopedIssueByOriginalId.get(dependency.target) ?? dependency.target,
}));
}
function scopeIssuesForProject(
project: ProjectScopeOption,
issues: BeadIssueWithProject[],
): BeadIssueWithProject[] {
const scopedIssueByOriginalId = new Map<string, string>();
for (const issue of issues) {
scopedIssueByOriginalId.set(issue.id, scopeIssueId(project.key, issue.id));
}
return issues.map((issue) => {
const scopedId = scopedIssueByOriginalId.get(issue.id) ?? scopeIssueId(project.key, issue.id);
return {
...issue,
id: scopedId,
dependencies: remapDependencies(issue.dependencies, scopedIssueByOriginalId),
metadata: {
...issue.metadata,
original_id: issue.id,
project_key: project.key,
},
project: {
...issue.project,
key: project.key,
},
};
});
}
export async function readIssuesForScope(options: {
mode: 'single' | 'aggregate';
selected: ProjectScopeOption;
scopeOptions: ProjectScopeOption[];
}): Promise<BeadIssueWithProject[]> {
if (options.mode === 'single') {
return readIssuesFromDisk({
projectRoot: options.selected.root,
projectSource: options.selected.source,
});
}
const result = await Promise.all(
options.scopeOptions.map(async (project) => {
const issues = await readIssuesFromDisk({
projectRoot: project.root,
projectSource: project.source,
});
return scopeIssuesForProject(project, issues);
}),
);
return result.flat();
}

489
src/lib/graph-view.ts Normal file
View file

@ -0,0 +1,489 @@
import dagre from 'dagre';
import type { GraphEdge, GraphModel, GraphNode } from './graph';
export type GraphHopDepth = 1 | 2 | 'full';
export interface GraphViewOptions {
focusId: string | null;
depth: GraphHopDepth;
hideClosed: boolean;
}
export interface PositionedGraphNode extends GraphNode {
position: { x: number; y: number };
}
export interface GraphViewModel {
nodes: PositionedGraphNode[];
edges: GraphEdge[];
}
export interface PathWorkspace {
focus: GraphNode | null;
blockers: GraphNode[][];
dependents: GraphNode[][];
}
const NODE_WIDTH = 340;
const NODE_HEIGHT = 132;
function sortEdges(a: GraphEdge, b: GraphEdge): number {
if (a.source !== b.source) {
return a.source.localeCompare(b.source);
}
if (a.type !== b.type) {
return a.type.localeCompare(b.type);
}
return a.target.localeCompare(b.target);
}
function sortNodes(a: GraphNode, b: GraphNode): number {
return a.id.localeCompare(b.id);
}
function collectIdsWithDepth(model: GraphModel, focusId: string, depth: Exclude<GraphHopDepth, 'full'>): Set<string> {
const visited = new Set<string>([focusId]);
let frontier = new Set<string>([focusId]);
for (let step = 0; step < depth; step += 1) {
const next = new Set<string>();
for (const nodeId of frontier) {
const adjacency = model.adjacency[nodeId];
if (!adjacency) {
continue;
}
for (const edge of adjacency.outgoing) {
if (!visited.has(edge.target)) {
visited.add(edge.target);
next.add(edge.target);
}
}
for (const edge of adjacency.incoming) {
if (!visited.has(edge.source)) {
visited.add(edge.source);
next.add(edge.source);
}
}
}
frontier = next;
if (frontier.size === 0) {
break;
}
}
return visited;
}
function applyFocusWorkspaceLayout(nodes: GraphNode[], edges: GraphEdge[], focusId: string): PositionedGraphNode[] {
const incomingDepth = new Map<string, number>([[focusId, 0]]);
const outgoingDepth = new Map<string, number>([[focusId, 0]]);
let incomingFrontier = new Set<string>([focusId]);
let outgoingFrontier = new Set<string>([focusId]);
let incomingStep = 0;
let outgoingStep = 0;
while (incomingFrontier.size > 0) {
incomingStep += 1;
const next = new Set<string>();
for (const nodeId of incomingFrontier) {
for (const edge of edges) {
if (edge.target !== nodeId) {
continue;
}
if (!incomingDepth.has(edge.source)) {
incomingDepth.set(edge.source, incomingStep);
next.add(edge.source);
}
}
}
incomingFrontier = next;
}
while (outgoingFrontier.size > 0) {
outgoingStep += 1;
const next = new Set<string>();
for (const nodeId of outgoingFrontier) {
for (const edge of edges) {
if (edge.source !== nodeId) {
continue;
}
if (!outgoingDepth.has(edge.target)) {
outgoingDepth.set(edge.target, outgoingStep);
next.add(edge.target);
}
}
}
outgoingFrontier = next;
}
const columns = new Map<number, GraphNode[]>();
for (const node of nodes) {
let column = 0;
if (node.id !== focusId) {
const inDepth = incomingDepth.get(node.id);
const outDepth = outgoingDepth.get(node.id);
if (inDepth && outDepth) {
column = inDepth <= outDepth ? -inDepth : outDepth;
} else if (inDepth) {
column = -inDepth;
} else if (outDepth) {
column = outDepth;
}
}
const bucket = columns.get(column) ?? [];
bucket.push(node);
columns.set(column, bucket);
}
const columnKeys = [...columns.keys()].sort((a, b) => a - b);
const positioned: PositionedGraphNode[] = [];
for (const columnKey of columnKeys) {
const columnNodes = (columns.get(columnKey) ?? []).sort((a, b) => a.id.localeCompare(b.id));
columnNodes.forEach((node, rowIndex) => {
positioned.push({
...node,
position: {
x: (columnKey + 3) * (NODE_WIDTH + 60),
y: rowIndex * (NODE_HEIGHT + 26),
},
});
});
}
return positioned.sort((a, b) => {
if (a.id === focusId) {
return -1;
}
if (b.id === focusId) {
return 1;
}
return a.id.localeCompare(b.id);
});
}
function applyLayout(nodes: GraphNode[], edges: GraphEdge[], focusId: string | null): PositionedGraphNode[] {
if (focusId) {
return applyFocusWorkspaceLayout(nodes, edges, focusId);
}
if (edges.length === 0) {
const columns = Math.max(1, Math.ceil(Math.sqrt(nodes.length)));
return nodes.map((node, index) => {
const col = index % columns;
const row = Math.floor(index / columns);
return {
...node,
position: {
x: col * (NODE_WIDTH + 36),
y: row * (NODE_HEIGHT + 28),
},
};
});
}
const graph = new dagre.graphlib.Graph();
graph.setDefaultEdgeLabel(() => ({}));
graph.setGraph({
rankdir: 'LR',
ranksep: 110,
nodesep: 36,
});
for (const node of nodes) {
graph.setNode(node.id, { width: NODE_WIDTH, height: NODE_HEIGHT });
}
for (const edge of edges) {
graph.setEdge(edge.source, edge.target);
}
dagre.layout(graph);
const positioned = nodes
.map((node) => {
const point = graph.node(node.id);
return {
...node,
position: {
x: Math.round((point?.x ?? 0) - NODE_WIDTH / 2),
y: Math.round((point?.y ?? 0) - NODE_HEIGHT / 2),
},
};
})
.sort((a, b) => {
if (focusId && a.id === focusId) {
return -1;
}
if (focusId && b.id === focusId) {
return 1;
}
return a.id.localeCompare(b.id);
});
return positioned;
}
export function buildGraphViewModel(model: GraphModel, options: GraphViewOptions): GraphViewModel {
const nodeById = new Map(model.nodes.map((node) => [node.id, node]));
const baseVisibleIds = options.focusId
? options.depth === 'full'
? new Set(model.nodes.map((node) => node.id))
: collectIdsWithDepth(model, options.focusId, options.depth)
: new Set(model.nodes.map((node) => node.id));
const filteredIds = new Set(
[...baseVisibleIds].filter((id) => {
const node = nodeById.get(id);
if (!node) {
return false;
}
if (!options.hideClosed) {
return true;
}
if (id === options.focusId) {
return true;
}
return node.status !== 'closed';
}),
);
const nodes = model.nodes.filter((node) => filteredIds.has(node.id)).sort(sortNodes);
const edges = model.edges
.filter((edge) => filteredIds.has(edge.source) && filteredIds.has(edge.target))
.sort(sortEdges);
return {
nodes: applyLayout(nodes, edges, options.focusId),
edges,
};
}
function includeByClosedFilter(node: GraphNode, hideClosed: boolean, forceInclude: boolean): boolean {
if (forceInclude) {
return true;
}
if (!hideClosed) {
return true;
}
return node.status !== 'closed';
}
export function buildPathWorkspace(model: GraphModel, options: GraphViewOptions): PathWorkspace {
const nodeById = new Map(model.nodes.map((node) => [node.id, node]));
const focusId = options.focusId;
const focusNode = focusId ? nodeById.get(focusId) ?? null : null;
if (!focusNode || !focusId) {
return { focus: null, blockers: [], dependents: [] };
}
const maxDepth = options.depth === 'full' ? Number.POSITIVE_INFINITY : options.depth;
const blockers: GraphNode[][] = [];
const dependents: GraphNode[][] = [];
const blockerSeen = new Set<string>([focusId]);
const dependentSeen = new Set<string>([focusId]);
let blockerFrontier = new Set<string>([focusId]);
let dependentFrontier = new Set<string>([focusId]);
for (let depth = 1; depth <= maxDepth; depth += 1) {
const nextBlockerFrontier = new Set<string>();
const nextDependentFrontier = new Set<string>();
const blockerLevel: GraphNode[] = [];
const dependentLevel: GraphNode[] = [];
for (const nodeId of blockerFrontier) {
const adjacency = model.adjacency[nodeId];
if (!adjacency) {
continue;
}
for (const edge of adjacency.incoming) {
if (blockerSeen.has(edge.source)) {
continue;
}
blockerSeen.add(edge.source);
nextBlockerFrontier.add(edge.source);
const node = nodeById.get(edge.source);
if (node && includeByClosedFilter(node, options.hideClosed, false)) {
blockerLevel.push(node);
}
}
}
for (const nodeId of dependentFrontier) {
const adjacency = model.adjacency[nodeId];
if (!adjacency) {
continue;
}
for (const edge of adjacency.outgoing) {
if (dependentSeen.has(edge.target)) {
continue;
}
dependentSeen.add(edge.target);
nextDependentFrontier.add(edge.target);
const node = nodeById.get(edge.target);
if (node && includeByClosedFilter(node, options.hideClosed, false)) {
dependentLevel.push(node);
}
}
}
blockerLevel.sort(sortNodes);
dependentLevel.sort(sortNodes);
if (blockerLevel.length > 0) {
blockers.push(blockerLevel);
}
if (dependentLevel.length > 0) {
dependents.push(dependentLevel);
}
blockerFrontier = nextBlockerFrontier;
dependentFrontier = nextDependentFrontier;
if (blockerFrontier.size === 0 && dependentFrontier.size === 0) {
break;
}
}
return { focus: focusNode, blockers, dependents };
}
export interface BlockedChainAnalysis {
blockerNodeIds: string[];
openBlockerCount: number;
inProgressBlockerCount: number;
firstActionableBlockerId: string | null;
chainEdgeIds: string[];
}
export function analyzeBlockedChain(model: GraphModel, options: { focusId: string }): BlockedChainAnalysis {
const focusId = options.focusId;
const visited = new Set<string>([focusId]);
let queue = [focusId];
const chainEdgeIds: string[] = [];
const blockerNodeIds: string[] = [];
while (queue.length > 0) {
const nodeId = queue.shift()!;
const adjacency = model.adjacency[nodeId];
if (!adjacency) continue;
for (const edge of adjacency.incoming) {
if (edge.type !== 'blocks') continue;
chainEdgeIds.push(`${edge.source}:${edge.type}:${edge.target}`);
if (!visited.has(edge.source)) {
visited.add(edge.source);
queue.push(edge.source);
blockerNodeIds.push(edge.source);
}
}
}
const blockers = blockerNodeIds.map(id => model.nodes.find(n => n.id === id)).filter(Boolean) as GraphNode[];
const openBlockers = blockers.filter((b) => b.status !== 'closed');
const inProgress = openBlockers.filter((b) => b.status === 'in_progress');
const openCount = openBlockers.filter(b => b.status === 'open' || b.status === 'blocked').length;
const firstActionable = openBlockers.find((b) => {
const adj = model.adjacency[b.id];
if (!adj) return true;
return !adj.incoming.some(e => e.type === 'blocks' && model.nodes.find(n => n.id === e.source)?.status !== 'closed');
});
return {
blockerNodeIds: blockerNodeIds.sort(),
openBlockerCount: openCount,
inProgressBlockerCount: inProgress.length,
firstActionableBlockerId: firstActionable?.id ?? null,
chainEdgeIds: chainEdgeIds.sort(),
};
}
export interface CycleAnomaly {
cycles: string[][];
cycleNodeIds: string[];
cycleEdgeIds: string[];
}
export function detectDependencyCycles(model: GraphModel): CycleAnomaly {
const cycleNodeIdsSet = new Set<string>();
const cycleEdgeIdsSet = new Set<string>();
const cycleKeys = new Set<string>();
const cycles: string[][] = [];
const relevantEdges = model.edges.filter((e) => e.type === 'blocks');
const adj = new Map<string, string[]>();
for (const node of model.nodes) {
adj.set(node.id, []);
}
for (const edge of relevantEdges) {
const list = adj.get(edge.source) ?? [];
list.push(edge.target);
adj.set(edge.source, list);
}
for (const [nodeId, neighbors] of adj.entries()) {
adj.set(
nodeId,
[...neighbors].sort((a, b) => a.localeCompare(b)),
);
}
const visited = new Set<string>();
const recStack = new Set<string>();
const path: string[] = [];
function walk(nodeId: string): void {
visited.add(nodeId);
recStack.add(nodeId);
path.push(nodeId);
const neighbors = adj.get(nodeId) ?? [];
for (const nextId of neighbors) {
if (!visited.has(nextId)) {
walk(nextId);
} else if (recStack.has(nextId)) {
const cycleStartIndex = path.indexOf(nextId);
if (cycleStartIndex >= 0) {
const cycleNodes = path.slice(cycleStartIndex);
const canonical = [...cycleNodes].sort((a, b) => a.localeCompare(b));
const cycleKey = canonical.join('|');
if (!cycleKeys.has(cycleKey)) {
cycleKeys.add(cycleKey);
cycles.push(canonical);
}
canonical.forEach((id) => cycleNodeIdsSet.add(id));
for (let i = 0; i < cycleNodes.length; i += 1) {
const s = cycleNodes[i];
const t = cycleNodes[(i + 1) % cycleNodes.length];
cycleEdgeIdsSet.add(`${s}:blocks:${t}`);
}
}
}
}
recStack.delete(nodeId);
path.pop();
}
for (const node of model.nodes) {
if (!visited.has(node.id)) {
walk(node.id);
}
}
cycles.sort((a, b) => a.join('|').localeCompare(b.join('|')));
return {
cycles,
cycleNodeIds: [...cycleNodeIdsSet].sort(),
cycleEdgeIds: [...cycleEdgeIdsSet].sort(),
};
}

137
src/lib/graph.ts Normal file
View file

@ -0,0 +1,137 @@
import type { BeadDependencyType, BeadIssue } from './types';
type SupportedGraphEdgeType = Extract<
BeadDependencyType,
'blocks' | 'parent' | 'relates_to' | 'duplicates' | 'supersedes'
>;
const SUPPORTED_EDGE_TYPES = new Set<BeadDependencyType>([
'blocks',
'parent',
'relates_to',
'duplicates',
'supersedes',
]);
export interface GraphNode {
id: string;
title: string;
status: BeadIssue['status'];
priority: number;
issueType: string;
assignee: string | null;
updatedAt: string;
}
export interface GraphEdge {
source: string;
target: string;
type: SupportedGraphEdgeType;
}
export interface GraphAdjacencyEntry {
incoming: GraphEdge[];
outgoing: GraphEdge[];
}
export interface GraphModelDiagnostics {
missingTargets: number;
droppedDuplicates: number;
unsupportedTypes: number;
}
export interface GraphModel {
nodes: GraphNode[];
edges: GraphEdge[];
adjacency: Record<string, GraphAdjacencyEntry>;
diagnostics: GraphModelDiagnostics;
projectKey: string | null;
}
export interface BuildGraphModelOptions {
projectKey?: string;
}
function edgeSort(a: GraphEdge, b: GraphEdge): number {
if (a.source !== b.source) {
return a.source.localeCompare(b.source);
}
if (a.type !== b.type) {
return a.type.localeCompare(b.type);
}
return a.target.localeCompare(b.target);
}
function isSupportedEdgeType(type: BeadDependencyType): type is SupportedGraphEdgeType {
return SUPPORTED_EDGE_TYPES.has(type);
}
export function buildGraphModel(issues: BeadIssue[], options: BuildGraphModelOptions = {}): GraphModel {
const nodes = issues
.map((issue) => ({
id: issue.id,
title: issue.title,
status: issue.status,
priority: issue.priority,
issueType: issue.issue_type,
assignee: issue.assignee,
updatedAt: issue.updated_at,
}))
.sort((a, b) => a.id.localeCompare(b.id));
const nodeIds = new Set(nodes.map((node) => node.id));
const edgeKeys = new Set<string>();
const edges: GraphEdge[] = [];
const diagnostics: GraphModelDiagnostics = {
missingTargets: 0,
droppedDuplicates: 0,
unsupportedTypes: 0,
};
for (const issue of issues) {
for (const dependency of issue.dependencies) {
if (!isSupportedEdgeType(dependency.type)) {
diagnostics.unsupportedTypes += 1;
continue;
}
if (!nodeIds.has(dependency.target)) {
diagnostics.missingTargets += 1;
continue;
}
const edgeKey = `${issue.id}::${dependency.type}::${dependency.target}`;
if (edgeKeys.has(edgeKey)) {
diagnostics.droppedDuplicates += 1;
continue;
}
edgeKeys.add(edgeKey);
edges.push({
source: issue.id,
target: dependency.target,
type: dependency.type,
});
}
}
edges.sort(edgeSort);
const adjacency: Record<string, GraphAdjacencyEntry> = {};
for (const node of nodes) {
adjacency[node.id] = { incoming: [], outgoing: [] };
}
for (const edge of edges) {
adjacency[edge.source].outgoing.push(edge);
adjacency[edge.target].incoming.push(edge);
}
return {
nodes,
edges,
adjacency,
diagnostics,
projectKey: options.projectKey ?? null,
};
}

168
src/lib/issue-editor.ts Normal file
View file

@ -0,0 +1,168 @@
import type { MutationStatus, UpdateMutationPayload } from './mutations';
import type { BeadIssue } from './types';
export interface EditableIssueDraft {
title: string;
description: string;
status: MutationStatus;
priority: number;
issueType: string;
assignee: string;
owner: string;
labelsInput: string;
}
export type EditableIssueFieldErrors = Partial<Record<keyof EditableIssueDraft, string>>;
export type EditState = 'pristine' | 'dirty' | 'saving' | 'error';
export function parseLabelsInput(labelsInput: string): string[] {
const seen = new Set<string>();
const labels: string[] = [];
for (const rawPart of labelsInput.split(',')) {
const part = rawPart.trim();
if (!part || seen.has(part)) {
continue;
}
seen.add(part);
labels.push(part);
}
return labels;
}
export function buildEditableIssueDraft(issue: BeadIssue): EditableIssueDraft {
const editableStatus: MutationStatus =
issue.status === 'open' ||
issue.status === 'in_progress' ||
issue.status === 'blocked' ||
issue.status === 'deferred' ||
issue.status === 'closed'
? issue.status
: 'open';
return {
title: issue.title,
description: issue.description ?? '',
status: editableStatus,
priority: issue.priority,
issueType: issue.issue_type,
assignee: issue.assignee ?? '',
owner: issue.owner ?? '',
labelsInput: issue.labels.map((label) => label.trim()).filter(Boolean).join(', '),
};
}
export function validateEditableIssueDraft(draft: EditableIssueDraft): { ok: true; errors: {} } | { ok: false; errors: EditableIssueFieldErrors } {
const errors: EditableIssueFieldErrors = {};
if (!draft.title.trim()) {
errors.title = 'Title is required.';
}
if (!Number.isInteger(draft.priority) || draft.priority < 0 || draft.priority > 4) {
errors.priority = 'Priority must be between 0 and 4.';
}
if (!['open', 'in_progress', 'blocked', 'deferred', 'closed'].includes(draft.status)) {
errors.status = 'Status must be open, in progress, blocked, deferred, or closed.';
}
if (!draft.issueType.trim()) {
errors.issueType = 'Issue type is required.';
}
const parts = draft.labelsInput.split(',').map((part) => part.trim());
if (parts.some((part) => part.length === 0) && draft.labelsInput.trim().length > 0) {
errors.labelsInput = 'Labels must be comma-separated non-empty values.';
}
if (Object.keys(errors).length > 0) {
return { ok: false, errors };
}
return { ok: true, errors: {} };
}
function normalizeNullable(value: string): string | undefined {
const trimmed = value.trim();
return trimmed.length > 0 ? trimmed : undefined;
}
function labelsChanged(current: string[], next: string[]): boolean {
if (current.length !== next.length) {
return true;
}
for (let i = 0; i < current.length; i += 1) {
if (current[i] !== next[i]) {
return true;
}
}
return false;
}
export function buildIssueUpdatePayload(
issue: BeadIssue,
draft: EditableIssueDraft,
projectRoot: string,
): UpdateMutationPayload | null {
const nextTitle = draft.title.trim();
const nextDescription = draft.description.trim();
const nextAssignee = normalizeNullable(draft.assignee);
const nextIssueType = draft.issueType.trim();
const nextLabels = parseLabelsInput(draft.labelsInput);
const payload: UpdateMutationPayload = {
projectRoot,
id: issue.id,
};
if (nextTitle !== issue.title) {
payload.title = nextTitle;
}
if (nextDescription !== (issue.description ?? '')) {
payload.description = nextDescription;
}
if (draft.priority !== issue.priority) {
payload.priority = draft.priority;
}
if (draft.status !== issue.status) {
payload.status = draft.status;
}
if (nextIssueType !== issue.issue_type) {
payload.issueType = nextIssueType;
}
if (nextAssignee !== (issue.assignee ?? undefined)) {
payload.assignee = nextAssignee;
}
if (labelsChanged(issue.labels, nextLabels)) {
payload.labels = nextLabels;
}
if (
payload.title === undefined &&
payload.description === undefined &&
payload.status === undefined &&
payload.priority === undefined &&
payload.issueType === undefined &&
payload.assignee === undefined &&
payload.labels === undefined
) {
return null;
}
return payload;
}
export function classifyEditState(input: { dirty: boolean; saving: boolean; error: string | null }): EditState {
if (input.saving) {
return 'saving';
}
if (input.error) {
return 'error';
}
if (input.dirty) {
return 'dirty';
}
return 'pristine';
}

263
src/lib/kanban.ts
View file

@ -1,6 +1,6 @@
import type { BeadIssue } from './types';
export const KANBAN_STATUSES = ['open', 'in_progress', 'blocked', 'deferred', 'closed'] as const;
export const KANBAN_STATUSES = ['ready', 'in_progress', 'blocked', 'closed'] as const;
export type KanbanStatus = (typeof KANBAN_STATUSES)[number];
@ -15,15 +15,29 @@ export interface KanbanFilterOptions {
export interface KanbanStats {
total: number;
open: number;
ready: number;
active: number;
blocked: number;
done: number;
p0: number;
}
function isKanbanStatus(status: string): status is KanbanStatus {
return KANBAN_STATUSES.includes(status as KanbanStatus);
export type BoardMutationStatus = 'open' | 'in_progress' | 'blocked' | 'closed';
export interface BlockedTreeNode {
id: string;
title: string;
level: number;
}
export interface ExecutionChecklistItem {
key: 'owner_assigned' | 'no_open_blockers' | 'quality_signal' | 'execution_compatible';
label: string;
passed: boolean;
}
function isReviewStatus(status: string): boolean {
return status.toLowerCase().includes('review');
}
function issueSort(a: BeadIssue, b: BeadIssue): number {
@ -35,6 +49,65 @@ function issueSort(a: BeadIssue, b: BeadIssue): number {
return b.updated_at.localeCompare(a.updated_at);
}
function hasOpenBlockers(issues: BeadIssue[], targetId: string): boolean {
return issues.some(
(issue) =>
issue.status !== 'closed' &&
issue.dependencies.some((dep) => dep.type === 'blocks' && dep.target === targetId),
);
}
function hasQualitySignal(issue: BeadIssue): boolean {
const description = issue.description?.trim() ?? '';
if (description.length > 0) {
return true;
}
if (issue.labels.some((label) => label.toLowerCase().includes('accept'))) {
return true;
}
const acceptance = issue.metadata.acceptance;
if (typeof acceptance === 'string') {
return acceptance.trim().length > 0;
}
if (Array.isArray(acceptance)) {
return acceptance.length > 0;
}
return false;
}
function deriveBlockedIds(issues: BeadIssue[]): Set<string> {
const issueById = new Map(issues.map((issue) => [issue.id, issue]));
const blockedIds = new Set<string>();
for (const issue of issues) {
for (const dep of issue.dependencies) {
if (dep.type !== 'blocks') continue;
const blocker = issueById.get(issue.id);
if (!blocker) continue;
if (blocker.status === 'closed') continue;
blockedIds.add(dep.target);
}
}
return blockedIds;
}
function laneForIssue(issue: BeadIssue, blockedIds: Set<string>): KanbanStatus {
if (issue.status === 'closed') {
return 'closed';
}
if (issue.status === 'blocked' || blockedIds.has(issue.id)) {
return 'blocked';
}
if (issue.status === 'in_progress' || isReviewStatus(issue.status)) {
return 'in_progress';
}
return 'ready';
}
export function filterKanbanIssues(issues: BeadIssue[], filters: KanbanFilterOptions): BeadIssue[] {
const query = (filters.query ?? '').trim().toLowerCase();
const type = (filters.type ?? '').trim().toLowerCase();
@ -67,17 +140,19 @@ export function filterKanbanIssues(issues: BeadIssue[], filters: KanbanFilterOpt
export function buildKanbanColumns(issues: BeadIssue[]): KanbanColumns {
const columns = {
open: [],
ready: [],
in_progress: [],
blocked: [],
deferred: [],
closed: [],
} as KanbanColumns;
const blockedIds = deriveBlockedIds(issues);
for (const issue of issues) {
if (isKanbanStatus(issue.status)) {
columns[issue.status].push(issue);
const lane = laneForIssue(issue, blockedIds);
if (lane === 'ready' && issue.issue_type === 'epic') {
continue;
}
columns[lane].push(issue);
}
for (const status of KANBAN_STATUSES) {
@ -88,12 +163,176 @@ export function buildKanbanColumns(issues: BeadIssue[]): KanbanColumns {
}
export function buildKanbanStats(issues: BeadIssue[]): KanbanStats {
const columns = buildKanbanColumns(issues);
return {
total: issues.length,
open: issues.filter((x) => x.status === 'open').length,
active: issues.filter((x) => x.status === 'in_progress').length,
blocked: issues.filter((x) => x.status === 'blocked').length,
done: issues.filter((x) => x.status === 'closed').length,
ready: columns.ready.length,
active: columns.in_progress.length,
blocked: columns.blocked.length,
done: columns.closed.length,
p0: issues.filter((x) => x.priority === 0).length,
};
}
export function laneToMutationStatus(status: KanbanStatus): BoardMutationStatus {
switch (status) {
case 'ready':
return 'open';
case 'in_progress':
return 'in_progress';
case 'blocked':
return 'blocked';
case 'closed':
return 'closed';
default:
return 'open';
}
}
export function buildBlockedByTree(
issues: BeadIssue[],
focusId: string | null,
options: { maxNodes?: number } = {},
): { total: number; nodes: BlockedTreeNode[] } {
if (!focusId) {
return { total: 0, nodes: [] };
}
const issueById = new Map(issues.map((issue) => [issue.id, issue]));
const incomingByTarget = new Map<string, string[]>();
for (const issue of issues) {
for (const dep of issue.dependencies) {
if (dep.type !== 'blocks') continue;
const list = incomingByTarget.get(dep.target) ?? [];
list.push(issue.id);
incomingByTarget.set(dep.target, list);
}
}
for (const [targetId, blockerIds] of incomingByTarget.entries()) {
incomingByTarget.set(
targetId,
[...new Set(blockerIds)].sort((a, b) => a.localeCompare(b)),
);
}
const maxNodes = Math.max(1, options.maxNodes ?? 12);
const visited = new Set<string>([focusId]);
const queued = new Set<string>();
const queue: Array<{ id: string; level: number }> = [{ id: focusId, level: 0 }];
const nodes: BlockedTreeNode[] = [];
let total = 0;
while (queue.length > 0) {
const current = queue.shift() as { id: string; level: number };
const blockers = incomingByTarget.get(current.id) ?? [];
for (const blockerId of blockers) {
if (visited.has(blockerId) || queued.has(blockerId)) continue;
queued.add(blockerId);
total += 1;
const blocker = issueById.get(blockerId);
if (nodes.length < maxNodes) {
nodes.push({
id: blockerId,
title: blocker?.title ?? blockerId,
level: current.level + 1,
});
}
queue.push({ id: blockerId, level: current.level + 1 });
}
visited.add(current.id);
}
return { total, nodes };
}
export function findIssueLane(columns: KanbanColumns, issueId: string): KanbanStatus | null {
for (const status of KANBAN_STATUSES) {
if (columns[status].some((issue) => issue.id === issueId)) {
return status;
}
}
return null;
}
export function buildUnblocksCountByIssue(issues: BeadIssue[]): Map<string, number> {
const unblocksByIssue = new Map<string, number>();
for (const issue of issues) {
const targets = new Set(
issue.dependencies.filter((dep) => dep.type === 'blocks').map((dep) => dep.target),
);
unblocksByIssue.set(issue.id, targets.size);
}
return unblocksByIssue;
}
export function pickNextActionableIssue(columns: KanbanColumns, issues: BeadIssue[]): BeadIssue | null {
if (columns.ready.length === 0) {
return null;
}
const unblocksByIssue = buildUnblocksCountByIssue(issues);
const ranked = [...columns.ready].sort((a, b) => {
const priorityDiff = a.priority - b.priority;
if (priorityDiff !== 0) {
return priorityDiff;
}
const unblocksDiff = (unblocksByIssue.get(b.id) ?? 0) - (unblocksByIssue.get(a.id) ?? 0);
if (unblocksDiff !== 0) {
return unblocksDiff;
}
const updatedDiff = b.updated_at.localeCompare(a.updated_at);
if (updatedDiff !== 0) {
return updatedDiff;
}
return a.id.localeCompare(b.id);
});
return ranked[0] ?? null;
}
export function formatUpdatedRecency(updatedAt: string | null | undefined, nowMs = Date.now()): string {
if (!updatedAt) {
return 'updated unknown';
}
const parsed = Date.parse(updatedAt);
if (Number.isNaN(parsed)) {
return 'updated unknown';
}
const elapsedSeconds = Math.max(0, Math.floor((nowMs - parsed) / 1000));
if (elapsedSeconds < 60) {
return 'updated now';
}
if (elapsedSeconds < 3600) {
return `updated ${Math.floor(elapsedSeconds / 60)}m`;
}
if (elapsedSeconds < 86400) {
return `updated ${Math.floor(elapsedSeconds / 3600)}h`;
}
if (elapsedSeconds < 604800) {
return `updated ${Math.floor(elapsedSeconds / 86400)}d`;
}
return `updated ${Math.floor(elapsedSeconds / 604800)}w`;
}
export function buildExecutionChecklist(issue: BeadIssue, issues: BeadIssue[]): ExecutionChecklistItem[] {
const columns = buildKanbanColumns(issues);
const lane = findIssueLane(columns, issue.id);
const openBlockers = hasOpenBlockers(issues, issue.id);
return [
{ key: 'owner_assigned', label: 'Owner assigned', passed: Boolean(issue.owner?.trim()) },
{ key: 'no_open_blockers', label: 'Not blocked by open blockers', passed: !openBlockers },
{ key: 'quality_signal', label: 'Has acceptance or description signal', passed: hasQualitySignal(issue) },
{
key: 'execution_compatible',
label: 'Execution-compatible status (ready or in progress)',
passed: lane === 'ready' || lane === 'in_progress',
},
];
}

13
src/lib/mutations.ts
View file

@ -23,6 +23,7 @@ export interface UpdateMutationPayload extends MutationBasePayload {
description?: string;
status?: MutationStatus;
priority?: number;
issueType?: string;
assignee?: string;
labels?: string[];
}
@ -162,11 +163,20 @@ export function validateMutationPayload(operation: MutationOperation, payload: u
description: asOptionalString(data.description),
status: asOptionalStatus(data.status),
priority: asOptionalPriority(data.priority),
issueType: asOptionalString(data.issueType),
assignee: asOptionalString(data.assignee),
labels: asOptionalLabels(data.labels),
};
if (!mapped.title && !mapped.description && !mapped.status && mapped.priority === undefined && !mapped.assignee && !mapped.labels) {
if (
!mapped.title &&
!mapped.description &&
!mapped.status &&
mapped.priority === undefined &&
!mapped.issueType &&
!mapped.assignee &&
!mapped.labels
) {
throw new MutationValidationError('At least one update field is required.');
}
@ -232,6 +242,7 @@ export function buildBdMutationArgs(operation: MutationOperation, payload: Mutat
if (data.priority !== undefined) {
args.push('-p', String(data.priority));
}
pushOptionalArg(args, '-t', data.issueType);
pushOptionalArg(args, '-a', data.assignee);
pushOptionalLabels(args, data.labels);
args.push('--json');

15
src/lib/parser.ts
View file

@ -15,14 +15,21 @@ function normalizeDependencies(value: unknown): BeadDependency[] {
return null;
}
const dep = item as { type?: unknown; target?: unknown };
if (typeof dep.type !== 'string' || typeof dep.target !== 'string') {
const dep = item as { type?: unknown; target?: unknown; depends_on_id?: unknown };
if (typeof dep.type !== 'string') {
return null;
}
const target = typeof dep.target === 'string' ? dep.target : typeof dep.depends_on_id === 'string' ? dep.depends_on_id : null;
if (!target) {
return null;
}
const normalizedType = dep.type === 'parent-child' ? 'parent' : dep.type;
return {
type: dep.type as BeadDependency['type'],
target: dep.target,
type: normalizedType as BeadDependency['type'],
target,
};
})
.filter((dep): dep is BeadDependency => dep !== null);

104
src/lib/project-scope.ts Normal file
View file

@ -0,0 +1,104 @@
import { canonicalizeWindowsPath, toDisplayPath, windowsPathKey } from './pathing';
export interface ProjectScopeRegistryEntry {
path: string;
}
export interface ProjectScopeOption {
key: string;
root: string;
displayPath: string;
source: 'local' | 'registry';
}
export type ProjectScopeMode = 'single' | 'aggregate';
export interface ResolveProjectScopeInput {
currentProjectRoot: string;
registryProjects: ProjectScopeRegistryEntry[];
requestedProjectKey?: string | null;
requestedMode?: string | null;
}
export interface ResolvedProjectScope {
mode: ProjectScopeMode;
selected: ProjectScopeOption;
readRoots: string[];
options: ProjectScopeOption[];
}
function normalizeRequestedKey(input?: string | null): string | null {
if (typeof input !== 'string') {
return null;
}
const trimmed = input.trim();
if (!trimmed) {
return null;
}
return trimmed.toLowerCase();
}
function buildLocalOption(currentProjectRoot: string): ProjectScopeOption {
const root = canonicalizeWindowsPath(currentProjectRoot);
return {
key: 'local',
root,
displayPath: toDisplayPath(root),
source: 'local',
};
}
function buildRegistryOptions(registryProjects: ProjectScopeRegistryEntry[]): ProjectScopeOption[] {
const seen = new Set<string>();
const options: ProjectScopeOption[] = [];
for (const project of registryProjects) {
const root = canonicalizeWindowsPath(project.path);
const key = windowsPathKey(root);
if (seen.has(key)) {
continue;
}
seen.add(key);
options.push({
key,
root,
displayPath: toDisplayPath(root),
source: 'registry',
});
}
return options;
}
function normalizeMode(input?: string | null): ProjectScopeMode {
if (input === 'aggregate') {
return 'aggregate';
}
return 'single';
}
export function resolveProjectScope(input: ResolveProjectScopeInput): ResolvedProjectScope {
const local = buildLocalOption(input.currentProjectRoot);
const registry = buildRegistryOptions(input.registryProjects);
const options = [local, ...registry];
const requestedKey = normalizeRequestedKey(input.requestedProjectKey);
const mode = normalizeMode(input.requestedMode);
const readRoots =
mode === 'aggregate' ? options.map((option) => option.root) : [local.root];
if (!requestedKey || requestedKey === 'local') {
return { mode, selected: local, readRoots, options };
}
const selected = options.find((option) => option.key === requestedKey);
const resolvedSelected = selected ?? local;
const resolvedReadRoots =
mode === 'aggregate' ? readRoots : [resolvedSelected.root];
return {
mode,
selected: resolvedSelected,
readRoots: resolvedReadRoots,
options,
};
}

55
src/lib/scanner.ts
View file

@ -47,6 +47,20 @@ const DEFAULT_IGNORE_DIRECTORIES = [
'artifacts',
'logs',
'.worktrees', // TODO: confirm whether worktrees should be scan targets.
'worktrees',
'.agents',
'.kimi',
'.zenflow',
'.gemini',
'appdata',
];
const DEFAULT_IGNORE_PATH_FRAGMENTS = [
'\\go\\pkg\\mod\\',
'\\.agents\\skills\\',
'\\.kimi\\skills\\',
'\\.gemini\\skills\\',
'\\.zenflow\\worktrees\\',
];
function userProfileRoot(): string {
@ -73,6 +87,18 @@ async function ensureDirectoryExists(input: string): Promise<string | null> {
}
}
async function fileExists(input: string): Promise<boolean> {
try {
const stat = await fs.stat(input);
return stat.isFile();
} catch (error) {
if (shouldSkipFsError(error as NodeJS.ErrnoException)) {
return false;
}
throw error;
}
}
async function resolveFullDriveRoots(): Promise<string[]> {
const candidates = ['C:\\', 'D:\\'];
const roots: string[] = [];
@ -128,6 +154,20 @@ function buildIgnoreSet(additional: string[] = []): Set<string> {
);
}
function shouldIgnorePath(dir: string): boolean {
const normalized = toCanonicalRoot(dir).toLowerCase();
return DEFAULT_IGNORE_PATH_FRAGMENTS.some((fragment) => normalized.includes(fragment));
}
function shouldIgnoreDirectoryName(name: string): boolean {
const normalized = name.trim().toLowerCase();
return (
normalized.startsWith('beadboard-read-') ||
normalized.startsWith('beadboard-watch-') ||
normalized.startsWith('skills-')
);
}
function recordProject(projects: Map<string, ScannerProject>, root: string): void {
const normalized = toCanonicalRoot(root);
const key = windowsPathKey(normalized);
@ -155,6 +195,11 @@ async function scanRoot(
continue;
}
if (current.depth > 0 && shouldIgnorePath(current.dir)) {
stats.ignoredDirectories += 1;
continue;
}
stats.scannedDirectories += 1;
let entries: Dirent[];
try {
@ -179,7 +224,7 @@ async function scanRoot(
}
const entryName = entry.name.toLowerCase();
if (ignoreSet.has(entryName)) {
if (ignoreSet.has(entryName) || shouldIgnoreDirectoryName(entryName)) {
stats.ignoredDirectories += 1;
continue;
}
@ -190,7 +235,13 @@ async function scanRoot(
}
if (hasBeads) {
recordProject(projects, current.dir);
const issuesPath = path.join(current.dir, '.beads', 'issues.jsonl');
const fallbackIssuesPath = path.join(current.dir, '.beads', 'issues.jsonl.new');
const [primaryExists, fallbackExists] = await Promise.all([fileExists(issuesPath), fileExists(fallbackIssuesPath)]);
if (primaryExists || fallbackExists) {
recordProject(projects, current.dir);
}
}
}
}

72
tests/guards/graph-responsive-contract.test.mjs Normal file
View file

@ -0,0 +1,72 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs/promises';
import path from 'node:path';
const ROOT = process.cwd();
async function read(relativePath) {
return fs.readFile(path.join(ROOT, relativePath), 'utf8');
}
test('graph page defines tabbed layout, epic chips, and mobile fallback', async () => {
const graphPage = await read('src/components/graph/dependency-graph-page.tsx');
// Tabbed layout: Tasks and Dependencies tabs
assert.match(graphPage, /WorkflowTabs/, 'should use WorkflowTabs component');
assert.match(graphPage, /activeTab/, 'should track active tab state');
// Epic chip strip replaces sidebar
assert.match(graphPage, /EpicChipStrip/, 'should use EpicChipStrip component');
// Mobile panel toggle preserved
assert.match(graphPage, /Switch to Graph/);
assert.match(graphPage, /Back to Selection/);
// Task card grid extracted
assert.match(graphPage, /TaskCardGrid/, 'should use TaskCardGrid component');
// Task details drawer
assert.match(graphPage, /TaskDetailsDrawer/, 'should use TaskDetailsDrawer drawer');
assert.match(graphPage, /projectRoot=\{projectRoot\}/, 'drawer should receive project root for edits');
assert.match(graphPage, /onIssueUpdated=\{\(\) => router.refresh\(\)\}/, 'drawer should trigger refresh after edits');
// Dependency flow strip
assert.match(graphPage, /DependencyFlowStrip/, 'should use DependencyFlowStrip component');
// Graph section with ReactFlow
assert.match(graphPage, /GraphSection/, 'should use GraphSection component');
assert.match(graphPage, /ReactFlowProvider/, 'should wrap graph in ReactFlowProvider');
// Edge options and node types still configured
assert.match(graphPage, /defaultEdgeOptions/);
assert.match(graphPage, /nodeTypes/);
// Actionable node detection
assert.match(graphPage, /actionableNodeIds/, 'should compute actionable (unblocked) nodes');
assert.match(graphPage, /ui-field/, 'graph filters should use shared dark field styling');
assert.match(graphPage, /ui-select/, 'graph select should use shared dark select styling');
});
test('extracted graph section has viewport and legend', async () => {
const graphSection = await read('src/components/graph/graph-section.tsx');
assert.match(graphSection, /className=\"workflow-graph-flow\"/, 'graph should have workflow-graph-flow class');
assert.match(graphSection, /workflow-graph-legend/, 'should have legend');
assert.match(graphSection, /translateExtent=\{\[/, 'should set translate extent');
assert.match(graphSection, /defaultEdgeOptions=\{/, 'should pass edge options');
assert.match(graphSection, /blockerAnalysis/, 'should show blocker stats');
assert.match(graphSection, /hideClosed/, 'should support hideClosed state in legend');
assert.match(graphSection, /!hideClosed/, 'done legend should be hidden when closed items are hidden');
});
test('graph node card supports tooltips and actionable glow', async () => {
const nodeCard = await read('src/components/graph/graph-node-card.tsx');
assert.match(nodeCard, /isActionable/, 'should check actionable state');
assert.match(nodeCard, /ring-emerald-400/, 'actionable nodes should have green glow');
assert.match(nodeCard, /node-select-pulse/, 'selected nodes should pulse');
assert.match(nodeCard, /blockerTooltipLines/, 'should display blocker tooltip');
assert.match(nodeCard, /isDimmed/, 'should support dimming non-chain nodes');
assert.match(nodeCard, /Ready to work/, 'actionable tooltip text');
});

18
tests/guards/kanban-responsive-contract.test.mjs
View file

@ -15,6 +15,8 @@ test('kanban board uses expandable vertical swimlanes', async () => {
assert.match(board, /aria-expanded/);
assert.match(board, /onActivateStatus/);
assert.match(board, /max-h-\[50vh\]/);
assert.match(board, /showClosed/, 'board should accept showClosed control');
assert.match(board, /status !== 'closed' \|\| showClosed/, 'done lane should be hidden when showClosed is false');
});
test('kanban page defines mobile detail drawer behavior', async () => {
@ -31,4 +33,20 @@ test('kanban controls use fluid full-width sizing on small viewports', async ()
assert.match(controls, /w-full/);
assert.match(controls, /sm:w-/);
assert.match(controls, /ui-field/, 'controls should use shared dark field styling');
assert.match(controls, /ui-select/, 'selects should use shared dark select styling');
assert.match(controls, /Next Actionable/);
assert.match(controls, /nextActionableFeedback/);
});
test('kanban detail includes execution checklist rendering', async () => {
const detail = await read('src/components/kanban/kanban-detail.tsx');
assert.match(detail, /Execution checklist/i);
assert.match(detail, /Summary/i);
assert.match(detail, /Task metadata/i);
assert.match(detail, /Timeline/i);
assert.match(detail, /Edit fields/i);
assert.match(detail, /Save changes/i);
assert.match(detail, /projectRoot\?/i);
});

87
tests/lib/aggregate-read.test.ts Normal file
View file

@ -0,0 +1,87 @@
import assert from 'node:assert/strict';
import fs from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import test from 'node:test';
import { readIssuesForScope } from '../../src/lib/aggregate-read';
import type { ProjectScopeOption } from '../../src/lib/project-scope';
async function writeIssues(root: string, lines: unknown[]): Promise<void> {
const beadsDir = path.join(root, '.beads');
await fs.mkdir(beadsDir, { recursive: true });
await fs.writeFile(
path.join(beadsDir, 'issues.jsonl'),
lines.map((line) => JSON.stringify(line)).join('\n'),
'utf8',
);
}
test('readIssuesForScope reads selected project in single mode', async () => {
const localRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'beadboard-scope-single-'));
await writeIssues(localRoot, [{ id: 'bb-1', title: 'Local issue', issue_type: 'task', status: 'open', priority: 1 }]);
const local: ProjectScopeOption = {
key: 'local',
root: localRoot,
displayPath: localRoot.replaceAll('\\', '/'),
source: 'local',
};
const issues = await readIssuesForScope({
mode: 'single',
selected: local,
scopeOptions: [local],
});
assert.equal(issues.length, 1);
assert.equal(issues[0].id, 'bb-1');
});
test('readIssuesForScope scopes ids and dependencies in aggregate mode', async () => {
const localRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'beadboard-scope-agg-local-'));
const registryRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'beadboard-scope-agg-reg-'));
await writeIssues(localRoot, [
{ id: 'bb-epic', title: 'Local epic', issue_type: 'epic', status: 'open', priority: 1 },
{
id: 'bb-epic.1',
title: 'Local task',
issue_type: 'task',
status: 'open',
priority: 1,
dependencies: [{ type: 'parent-child', depends_on_id: 'bb-epic' }],
},
]);
await writeIssues(registryRoot, [
{ id: 'bb-epic', title: 'Registry epic', issue_type: 'epic', status: 'open', priority: 1 },
]);
const local: ProjectScopeOption = {
key: 'local',
root: localRoot,
displayPath: localRoot.replaceAll('\\', '/'),
source: 'local',
};
const registry: ProjectScopeOption = {
key: 'd:\\repos\\alpha',
root: registryRoot,
displayPath: registryRoot.replaceAll('\\', '/'),
source: 'registry',
};
const issues = await readIssuesForScope({
mode: 'aggregate',
selected: local,
scopeOptions: [local, registry],
});
assert.equal(issues.length, 3);
assert.equal(issues.some((issue) => issue.id === 'local::bb-epic'), true);
assert.equal(issues.some((issue) => issue.id === 'd:\\repos\\alpha::bb-epic'), true);
const localTask = issues.find((issue) => issue.id === 'local::bb-epic.1');
assert.ok(localTask);
assert.equal(localTask.dependencies.some((dependency) => dependency.target === 'local::bb-epic'), true);
assert.equal(localTask.metadata.original_id, 'bb-epic.1');
});

174
tests/lib/graph-view.test.ts Normal file
View file

@ -0,0 +1,174 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { buildGraphModel } from '../../src/lib/graph';
import { analyzeBlockedChain, buildGraphViewModel, buildPathWorkspace, detectDependencyCycles } from '../../src/lib/graph-view';
import type { BeadIssue } from '../../src/lib/types';
function issue(overrides: Partial<BeadIssue>): BeadIssue {
return {
id: overrides.id ?? 'bb-x',
title: overrides.title ?? 'Issue',
description: overrides.description ?? null,
status: overrides.status ?? 'open',
priority: overrides.priority ?? 2,
issue_type: overrides.issue_type ?? 'task',
assignee: overrides.assignee ?? null,
owner: overrides.owner ?? null,
labels: overrides.labels ?? [],
dependencies: overrides.dependencies ?? [],
created_at: overrides.created_at ?? '2026-02-12T00:00:00Z',
updated_at: overrides.updated_at ?? '2026-02-12T00:00:00Z',
closed_at: overrides.closed_at ?? null,
close_reason: overrides.close_reason ?? null,
closed_by_session: overrides.closed_by_session ?? null,
created_by: overrides.created_by ?? null,
due_at: overrides.due_at ?? null,
estimated_minutes: overrides.estimated_minutes ?? null,
external_ref: overrides.external_ref ?? null,
metadata: overrides.metadata ?? {},
};
}
test('buildGraphViewModel limits visible nodes by hop depth around focus', () => {
const model = buildGraphModel([
issue({ id: 'bb-1', dependencies: [{ type: 'blocks', target: 'bb-2' }] }),
issue({ id: 'bb-2', dependencies: [{ type: 'blocks', target: 'bb-3' }] }),
issue({ id: 'bb-3', dependencies: [{ type: 'blocks', target: 'bb-4' }] }),
issue({ id: 'bb-4' }),
]);
const depth1 = buildGraphViewModel(model, { focusId: 'bb-2', depth: 1, hideClosed: false });
const depth2 = buildGraphViewModel(model, { focusId: 'bb-2', depth: 2, hideClosed: false });
assert.deepEqual(
depth1.nodes.map((x) => x.id),
['bb-2', 'bb-1', 'bb-3'],
);
assert.deepEqual(
depth2.nodes.map((x) => x.id),
['bb-2', 'bb-1', 'bb-3', 'bb-4'],
);
});
test('buildGraphViewModel can hide closed nodes while preserving focused node', () => {
const model = buildGraphModel([
issue({ id: 'bb-1', status: 'closed', dependencies: [{ type: 'blocks', target: 'bb-2' }] }),
issue({ id: 'bb-2', status: 'open' }),
]);
const hidden = buildGraphViewModel(model, { focusId: null, depth: 'full', hideClosed: true });
const focused = buildGraphViewModel(model, { focusId: 'bb-1', depth: 'full', hideClosed: true });
assert.deepEqual(hidden.nodes.map((x) => x.id), ['bb-2']);
assert.deepEqual(focused.nodes.map((x) => x.id), ['bb-1', 'bb-2']);
});
test('buildGraphViewModel keeps deterministic edge ordering', () => {
const model = buildGraphModel([
issue({
id: 'bb-2',
dependencies: [
{ type: 'parent', target: 'bb-1' },
{ type: 'blocks', target: 'bb-3' },
],
}),
issue({ id: 'bb-1' }),
issue({ id: 'bb-3' }),
]);
const view = buildGraphViewModel(model, { focusId: null, depth: 'full', hideClosed: false });
assert.deepEqual(
view.edges.map((x) => `${x.source}|${x.type}|${x.target}`),
['bb-2|blocks|bb-3', 'bb-2|parent|bb-1'],
);
assert.equal(view.nodes.every((x) => Number.isFinite(x.position.x) && Number.isFinite(x.position.y)), true);
});
test('buildPathWorkspace returns upstream/downstream levels around focus', () => {
const model = buildGraphModel([
issue({ id: 'bb-1', dependencies: [{ type: 'blocks', target: 'bb-2' }] }),
issue({ id: 'bb-2', dependencies: [{ type: 'blocks', target: 'bb-3' }] }),
issue({ id: 'bb-3' }),
]);
const workspace = buildPathWorkspace(model, { focusId: 'bb-2', depth: 2, hideClosed: false });
assert.equal(workspace.focus?.id, 'bb-2');
assert.deepEqual(workspace.blockers.map((level) => level.map((node) => node.id)), [['bb-1']]);
assert.deepEqual(workspace.dependents.map((level) => level.map((node) => node.id)), [['bb-3']]);
});
test('buildPathWorkspace hides closed nodes when requested', () => {
const model = buildGraphModel([
issue({ id: 'bb-1', status: 'closed', dependencies: [{ type: 'blocks', target: 'bb-2' }] }),
issue({ id: 'bb-2' }),
]);
const workspace = buildPathWorkspace(model, { focusId: 'bb-2', depth: 2, hideClosed: true });
assert.equal(workspace.blockers.length, 0);
assert.equal(workspace.focus?.id, 'bb-2');
});
test('buildPathWorkspace full depth keeps deterministic blocker and dependent levels', () => {
const model = buildGraphModel([
issue({ id: 'bb-1', dependencies: [{ type: 'blocks', target: 'bb-2' }] }),
issue({ id: 'bb-2', dependencies: [{ type: 'blocks', target: 'bb-3' }] }),
issue({ id: 'bb-3', dependencies: [{ type: 'blocks', target: 'bb-4' }] }),
issue({ id: 'bb-4', dependencies: [{ type: 'blocks', target: 'bb-5' }] }),
issue({ id: 'bb-5' }),
]);
const workspace = buildPathWorkspace(model, { focusId: 'bb-3', depth: 'full', hideClosed: false });
assert.deepEqual(workspace.blockers.map((level) => level.map((node) => node.id)), [['bb-2'], ['bb-1']]);
assert.deepEqual(workspace.dependents.map((level) => level.map((node) => node.id)), [['bb-4'], ['bb-5']]);
});
test('analyzeBlockedChain returns blocker counts, first actionable blocker, and chain edges', () => {
const model = buildGraphModel([
issue({ id: 'bb-1', status: 'open', dependencies: [{ type: 'blocks', target: 'bb-2' }] }),
issue({ id: 'bb-2', status: 'in_progress', dependencies: [{ type: 'blocks', target: 'bb-3' }] }),
issue({ id: 'bb-3', status: 'blocked' }),
]);
const summary = analyzeBlockedChain(model, { focusId: 'bb-3' });
assert.equal(summary.blockerNodeIds.length, 2);
assert.equal(summary.openBlockerCount, 1);
assert.equal(summary.inProgressBlockerCount, 1);
assert.equal(summary.firstActionableBlockerId, 'bb-1');
assert.deepEqual(summary.chainEdgeIds, ['bb-1:blocks:bb-2', 'bb-2:blocks:bb-3']);
});
test('detectDependencyCycles reports cycle nodes and edges for blocks relations', () => {
const model = buildGraphModel([
issue({ id: 'bb-1', dependencies: [{ type: 'blocks', target: 'bb-2' }] }),
issue({ id: 'bb-2', dependencies: [{ type: 'blocks', target: 'bb-3' }] }),
issue({ id: 'bb-3', dependencies: [{ type: 'blocks', target: 'bb-1' }] }),
issue({ id: 'bb-4', dependencies: [{ type: 'blocks', target: 'bb-5' }] }),
issue({ id: 'bb-5' }),
]);
const anomaly = detectDependencyCycles(model);
assert.equal(anomaly.cycles.length, 1);
assert.deepEqual(anomaly.cycleNodeIds, ['bb-1', 'bb-2', 'bb-3']);
assert.deepEqual(anomaly.cycleEdgeIds, ['bb-1:blocks:bb-2', 'bb-2:blocks:bb-3', 'bb-3:blocks:bb-1']);
});
test('detectDependencyCycles does not mark non-cycle predecessor as cyclic', () => {
const model = buildGraphModel([
issue({ id: 'bb-a', dependencies: [{ type: 'blocks', target: 'bb-b' }] }),
issue({ id: 'bb-b', dependencies: [{ type: 'blocks', target: 'bb-c' }] }),
issue({ id: 'bb-c', dependencies: [{ type: 'blocks', target: 'bb-a' }] }),
issue({ id: 'bb-x', dependencies: [{ type: 'blocks', target: 'bb-a' }] }),
]);
const anomaly = detectDependencyCycles(model);
assert.deepEqual(anomaly.cycleNodeIds, ['bb-a', 'bb-b', 'bb-c']);
assert.equal(anomaly.cycleNodeIds.includes('bb-x'), false);
assert.equal(anomaly.cycleEdgeIds.includes('bb-x:blocks:bb-a'), false);
});

127
tests/lib/graph.test.ts Normal file
View file

@ -0,0 +1,127 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import type { BeadDependency, BeadIssue } from '../../src/lib/types';
import { buildGraphModel } from '../../src/lib/graph';
function issue(overrides: Partial<BeadIssue>): BeadIssue {
return {
id: overrides.id ?? 'bb-x',
title: overrides.title ?? 'Issue',
description: overrides.description ?? null,
status: overrides.status ?? 'open',
priority: overrides.priority ?? 2,
issue_type: overrides.issue_type ?? 'task',
assignee: overrides.assignee ?? null,
owner: overrides.owner ?? null,
labels: overrides.labels ?? [],
dependencies: overrides.dependencies ?? [],
created_at: overrides.created_at ?? '2026-02-12T00:00:00Z',
updated_at: overrides.updated_at ?? '2026-02-12T00:00:00Z',
closed_at: overrides.closed_at ?? null,
close_reason: overrides.close_reason ?? null,
closed_by_session: overrides.closed_by_session ?? null,
created_by: overrides.created_by ?? null,
due_at: overrides.due_at ?? null,
estimated_minutes: overrides.estimated_minutes ?? null,
external_ref: overrides.external_ref ?? null,
metadata: overrides.metadata ?? {},
};
}
function dep(type: BeadDependency['type'], target: string): BeadDependency {
return { type, target };
}
test('buildGraphModel extracts supported dependency types with deterministic ordering', () => {
const issues = [
issue({
id: 'bb-2',
dependencies: [
dep('parent', 'bb-1'),
dep('blocks', 'bb-3'),
],
}),
issue({
id: 'bb-1',
dependencies: [dep('supersedes', 'bb-3')],
}),
issue({
id: 'bb-3',
dependencies: [
dep('duplicates', 'bb-1'),
dep('relates_to', 'bb-2'),
],
}),
];
const model = buildGraphModel(issues, { projectKey: 'demo' });
assert.deepEqual(model.nodes.map((x) => x.id), ['bb-1', 'bb-2', 'bb-3']);
assert.deepEqual(
model.edges.map((x) => `${x.source}|${x.type}|${x.target}`),
[
'bb-1|supersedes|bb-3',
'bb-2|blocks|bb-3',
'bb-2|parent|bb-1',
'bb-3|duplicates|bb-1',
'bb-3|relates_to|bb-2',
],
);
assert.equal(model.projectKey, 'demo');
});
test('buildGraphModel deduplicates duplicate edges and tracks diagnostics', () => {
const issues = [
issue({
id: 'bb-1',
dependencies: [
dep('blocks', 'bb-2'),
dep('blocks', 'bb-2'),
dep('blocks', 'bb-2'),
],
}),
issue({ id: 'bb-2' }),
];
const model = buildGraphModel(issues);
assert.equal(model.edges.length, 1);
assert.equal(model.diagnostics.droppedDuplicates, 2);
assert.equal(model.diagnostics.missingTargets, 0);
});
test('buildGraphModel ignores missing-target edges and unsupported types', () => {
const issues = [
issue({
id: 'bb-1',
dependencies: [
dep('blocks', 'bb-missing'),
dep('replies_to', 'bb-2'),
],
}),
issue({ id: 'bb-2' }),
];
const model = buildGraphModel(issues);
assert.equal(model.edges.length, 0);
assert.equal(model.diagnostics.missingTargets, 1);
assert.equal(model.diagnostics.unsupportedTypes, 1);
});
test('buildGraphModel builds incoming/outgoing adjacency maps', () => {
const issues = [
issue({ id: 'bb-1', dependencies: [dep('blocks', 'bb-2')] }),
issue({ id: 'bb-2', dependencies: [dep('parent', 'bb-3')] }),
issue({ id: 'bb-3' }),
];
const model = buildGraphModel(issues);
assert.deepEqual(model.adjacency['bb-1'].outgoing.map((x) => x.target), ['bb-2']);
assert.deepEqual(model.adjacency['bb-1'].incoming.map((x) => x.source), []);
assert.deepEqual(model.adjacency['bb-2'].incoming.map((x) => x.source), ['bb-1']);
assert.deepEqual(model.adjacency['bb-2'].outgoing.map((x) => x.target), ['bb-3']);
assert.deepEqual(model.adjacency['bb-3'].incoming.map((x) => x.source), ['bb-2']);
});

142
tests/lib/issue-editor.test.ts Normal file
View file

@ -0,0 +1,142 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
buildEditableIssueDraft,
buildIssueUpdatePayload,
classifyEditState,
parseLabelsInput,
validateEditableIssueDraft,
type EditableIssueDraft,
} from '../../src/lib/issue-editor';
import type { BeadIssue } from '../../src/lib/types';
function makeIssue(overrides: Partial<BeadIssue> = {}): BeadIssue {
const has = (key: keyof BeadIssue) => Object.prototype.hasOwnProperty.call(overrides, key);
return {
id: overrides.id ?? 'bb-101',
title: overrides.title ?? 'Implement shared edit surface',
description: has('description') ? (overrides.description as string | null) : 'First line',
status: overrides.status ?? 'open',
priority: overrides.priority ?? 2,
issue_type: overrides.issue_type ?? 'task',
assignee: has('assignee') ? (overrides.assignee as string | null) : null,
owner: has('owner') ? (overrides.owner as string | null) : null,
labels: overrides.labels ?? ['ux', 'graph'],
dependencies: overrides.dependencies ?? [],
created_at: overrides.created_at ?? '2026-02-13T00:00:00.000Z',
updated_at: overrides.updated_at ?? '2026-02-13T00:00:00.000Z',
closed_at: overrides.closed_at ?? null,
close_reason: overrides.close_reason ?? null,
closed_by_session: overrides.closed_by_session ?? null,
created_by: overrides.created_by ?? 'zenchantlive',
due_at: overrides.due_at ?? null,
estimated_minutes: overrides.estimated_minutes ?? null,
external_ref: overrides.external_ref ?? null,
metadata: overrides.metadata ?? {},
};
}
test('buildEditableIssueDraft normalizes nullable issue fields', () => {
const issue = makeIssue({
description: null,
assignee: null,
owner: null,
labels: ['graph', ' ux ', ''],
});
const draft = buildEditableIssueDraft(issue);
assert.equal(draft.title, issue.title);
assert.equal(draft.description, '');
assert.equal(draft.status, issue.status);
assert.equal(draft.assignee, '');
assert.equal(draft.owner, '');
assert.equal(draft.labelsInput, 'graph, ux');
});
test('validateEditableIssueDraft returns validation errors for invalid input', () => {
const draft = {
title: ' ',
description: 'desc',
status: 'tombstone',
priority: 7,
issueType: '',
assignee: 'dev-a',
owner: '',
labelsInput: 'ok, , invalid',
} as unknown as EditableIssueDraft;
const result = validateEditableIssueDraft(draft);
assert.equal(result.ok, false);
assert.equal(result.errors.title, 'Title is required.');
assert.equal(result.errors.status, 'Status must be open, in progress, blocked, deferred, or closed.');
assert.equal(result.errors.priority, 'Priority must be between 0 and 4.');
assert.equal(result.errors.issueType, 'Issue type is required.');
assert.equal(result.errors.labelsInput, 'Labels must be comma-separated non-empty values.');
});
test('buildIssueUpdatePayload includes only changed mutable fields', () => {
const issue = makeIssue({
title: 'Old title',
description: 'Old description',
priority: 2,
issue_type: 'task',
assignee: 'old-assignee',
labels: ['legacy'],
owner: 'owner-a',
});
const draft: EditableIssueDraft = {
title: 'New title',
description: 'Old description',
status: 'in_progress',
priority: 1,
issueType: 'feature',
assignee: 'new-assignee',
owner: 'owner-b',
labelsInput: 'legacy,ui',
};
const payload = buildIssueUpdatePayload(issue, draft, 'C:/repo');
assert.deepEqual(payload, {
projectRoot: 'C:/repo',
id: issue.id,
title: 'New title',
status: 'in_progress',
priority: 1,
issueType: 'feature',
assignee: 'new-assignee',
labels: ['legacy', 'ui'],
});
});
test('buildIssueUpdatePayload returns null when no mutable fields changed', () => {
const issue = makeIssue({
title: 'Same title',
description: 'Same description',
status: 'open',
priority: 2,
issue_type: 'task',
assignee: null,
owner: 'owner-a',
labels: ['a', 'b'],
});
const draft = buildEditableIssueDraft(issue);
const payload = buildIssueUpdatePayload(issue, draft, 'C:/repo');
assert.equal(payload, null);
});
test('parseLabelsInput deduplicates, trims, and preserves order', () => {
assert.deepEqual(parseLabelsInput(' alpha, beta,alpha, gamma , ,beta'), ['alpha', 'beta', 'gamma']);
});
test('classifyEditState derives ui state from dirty/saving/error flags', () => {
assert.equal(classifyEditState({ dirty: false, saving: false, error: null }), 'pristine');
assert.equal(classifyEditState({ dirty: true, saving: false, error: null }), 'dirty');
assert.equal(classifyEditState({ dirty: true, saving: true, error: null }), 'saving');
assert.equal(classifyEditState({ dirty: true, saving: false, error: 'boom' }), 'error');
});

134
tests/lib/kanban.test.ts
View file

@ -4,9 +4,14 @@ import assert from 'node:assert/strict';
import type { BeadIssue } from '../../src/lib/types';
import {
KANBAN_STATUSES,
buildExecutionChecklist,
buildBlockedByTree,
buildKanbanColumns,
buildKanbanStats,
buildUnblocksCountByIssue,
findIssueLane,
filterKanbanIssues,
pickNextActionableIssue,
} from '../../src/lib/kanban';
function issue(overrides: Partial<BeadIssue>): BeadIssue {
@ -56,19 +61,24 @@ test('buildKanbanColumns groups by core statuses and sorts by priority ascending
const issues = [
issue({ id: 'bb-1', status: 'open', priority: 2 }),
issue({ id: 'bb-2', status: 'open', priority: 0 }),
issue({ id: 'bb-3', status: 'blocked', priority: 1 }),
issue({ id: 'bb-4', status: 'pinned', priority: 1 }),
issue({ id: 'bb-epic', status: 'open', priority: 0, issue_type: 'epic' }),
issue({ id: 'bb-3', status: 'in_progress', priority: 1 }),
issue({ id: 'bb-4', status: 'deferred', priority: 1 }),
issue({ id: 'bb-5', status: 'open', priority: 3, dependencies: [{ type: 'blocks', target: 'bb-1' }] }),
issue({ id: 'bb-6', status: 'open', priority: 4, dependencies: [{ type: 'blocks', target: 'bb-2' }] }),
];
const columns = buildKanbanColumns(issues);
assert.deepEqual(Object.keys(columns), KANBAN_STATUSES);
assert.deepEqual(columns.open.map((x) => x.id), ['bb-2', 'bb-1']);
assert.deepEqual(columns.blocked.map((x) => x.id), ['bb-3']);
assert.deepEqual(columns.ready.map((x) => x.id), ['bb-4', 'bb-5', 'bb-6']);
assert.equal(columns.ready.some((x) => x.issue_type === 'epic'), false);
assert.deepEqual(columns.in_progress.map((x) => x.id), ['bb-3']);
assert.deepEqual(columns.blocked.map((x) => x.id), ['bb-2', 'bb-1']);
assert.equal(columns.closed.length, 0);
});
test('buildKanbanStats reports total/open/active/blocked/done/p0', () => {
test('buildKanbanStats reports total/ready/active/blocked/done/p0', () => {
const issues = [
issue({ status: 'open', priority: 0 }),
issue({ status: 'open', priority: 2 }),
@ -80,9 +90,121 @@ test('buildKanbanStats reports total/open/active/blocked/done/p0', () => {
const stats = buildKanbanStats(issues);
assert.equal(stats.total, 5);
assert.equal(stats.open, 2);
assert.equal(stats.ready, 2);
assert.equal(stats.active, 1);
assert.equal(stats.blocked, 1);
assert.equal(stats.done, 1);
assert.equal(stats.p0, 1);
});
test('buildBlockedByTree returns compact blocker tree with depth and total', () => {
const issues = [
issue({ id: 'bb-1', title: 'Target issue' }),
issue({ id: 'bb-2', title: 'Direct blocker A', dependencies: [{ type: 'blocks', target: 'bb-1' }] }),
issue({ id: 'bb-3', title: 'Direct blocker B', dependencies: [{ type: 'blocks', target: 'bb-1' }] }),
issue({ id: 'bb-4', title: 'Nested blocker', dependencies: [{ type: 'blocks', target: 'bb-2' }] }),
];
const tree = buildBlockedByTree(issues, 'bb-1');
assert.equal(tree.total, 3);
assert.deepEqual(
tree.nodes.map((node) => `${node.id}:${node.level}`),
['bb-2:1', 'bb-3:1', 'bb-4:2'],
);
});
test('findIssueLane resolves ready lane for unblocked linked issues', () => {
const issues = [
issue({ id: 'bb-1', status: 'open' }),
issue({ id: 'bb-2', status: 'blocked' }),
issue({ id: 'bb-3', status: 'closed' }),
];
const columns = buildKanbanColumns(issues);
assert.equal(findIssueLane(columns, 'bb-1'), 'ready');
assert.equal(findIssueLane(columns, 'bb-2'), 'blocked');
assert.equal(findIssueLane(columns, 'bb-3'), 'closed');
assert.equal(findIssueLane(columns, 'bb-404'), null);
});
test('pickNextActionableIssue is deterministic by priority asc, unblocks desc, updated desc, id asc', () => {
const issues = [
issue({
id: 'bb-1',
status: 'open',
priority: 1,
updated_at: '2026-02-10T01:00:00Z',
dependencies: [{ type: 'blocks', target: 'bb-10' }],
}),
issue({
id: 'bb-2',
status: 'open',
priority: 1,
updated_at: '2026-02-10T02:00:00Z',
dependencies: [{ type: 'blocks', target: 'bb-11' }, { type: 'blocks', target: 'bb-12' }],
}),
issue({
id: 'bb-3',
status: 'open',
priority: 1,
updated_at: '2026-02-10T02:00:00Z',
dependencies: [{ type: 'blocks', target: 'bb-13' }, { type: 'blocks', target: 'bb-14' }],
}),
issue({ id: 'bb-10', status: 'blocked' }),
issue({ id: 'bb-11', status: 'blocked' }),
issue({ id: 'bb-12', status: 'blocked' }),
issue({ id: 'bb-13', status: 'blocked' }),
issue({ id: 'bb-14', status: 'blocked' }),
];
const columns = buildKanbanColumns(issues);
const next = pickNextActionableIssue(columns, issues);
assert.equal(next?.id, 'bb-2');
});
test('pickNextActionableIssue returns null when no ready issue exists', () => {
const issues = [issue({ id: 'bb-1', status: 'in_progress' }), issue({ id: 'bb-2', status: 'closed' })];
const columns = buildKanbanColumns(issues);
assert.equal(pickNextActionableIssue(columns, issues), null);
});
test('buildUnblocksCountByIssue counts unique blocks dependencies per issue', () => {
const issues = [
issue({
id: 'bb-1',
dependencies: [
{ type: 'blocks', target: 'bb-2' },
{ type: 'blocks', target: 'bb-2' },
{ type: 'blocks', target: 'bb-3' },
{ type: 'relates_to', target: 'bb-4' },
],
}),
];
const map = buildUnblocksCountByIssue(issues);
assert.equal(map.get('bb-1'), 2);
});
test('buildExecutionChecklist evaluates owner, blockers, quality signal, and execution-compatible lane', () => {
const issues = [
issue({
id: 'bb-1',
status: 'open',
owner: 'dev-a',
description: 'Implements acceptance criteria with rollback notes',
}),
issue({ id: 'bb-2', status: 'open', dependencies: [{ type: 'blocks', target: 'bb-1' }] }),
];
const checklist = buildExecutionChecklist(issues[0], issues);
assert.deepEqual(
checklist.map((item) => item.passed),
[true, false, true, false],
);
});

11
tests/lib/mutations.test.ts
View file

@ -29,6 +29,17 @@ test('buildBdMutationArgs maps reopen correctly', () => {
assert.deepEqual(args, ['reopen', 'bb-123', '-r', 'retry work', '--json']);
});
test('buildBdMutationArgs maps update issue type correctly', () => {
const payload = validateMutationPayload('update', {
projectRoot: root,
id: 'bb-123',
issueType: 'feature',
});
const args = buildBdMutationArgs('update', payload);
assert.deepEqual(args, ['update', 'bb-123', '-t', 'feature', '--json']);
});
test('buildBdMutationArgs maps comment correctly', () => {
const payload = validateMutationPayload('comment', {
projectRoot: root,

21
tests/lib/parser.test.ts
View file

@ -49,3 +49,24 @@ test('parseIssuesJsonl can include tombstones when requested', () => {
assert.equal(result.length, 2);
});
test('parseIssuesJsonl supports beads dependency schema with depends_on_id and parent-child', () => {
const input = JSON.stringify({
id: 'bb-6',
title: 'Dependency test',
dependencies: [
{ type: 'blocks', depends_on_id: 'bb-1' },
{ type: 'parent-child', depends_on_id: 'bb-epic' },
{ type: 'relates_to', target: 'bb-2' },
],
});
const result = parseIssuesJsonl(input);
assert.equal(result.length, 1);
assert.deepEqual(result[0].dependencies, [
{ type: 'blocks', target: 'bb-1' },
{ type: 'parent', target: 'bb-epic' },
{ type: 'relates_to', target: 'bb-2' },
]);
});

87
tests/lib/project-scope.test.ts Normal file
View file

@ -0,0 +1,87 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { resolveProjectScope, type ProjectScopeRegistryEntry } from '../../src/lib/project-scope';
const REGISTRY: ProjectScopeRegistryEntry[] = [
{ path: 'D:/Repos/Alpha' },
{ path: 'D:/Repos/Beta' },
];
test('resolveProjectScope defaults to local when query key is missing', () => {
const scope = resolveProjectScope({
currentProjectRoot: 'C:/Users/Zenchant/codex/beadboard',
registryProjects: REGISTRY,
});
assert.equal(scope.mode, 'single');
assert.equal(scope.selected.source, 'local');
assert.equal(scope.selected.root, 'C:\\Users\\Zenchant\\codex\\beadboard');
assert.equal(scope.selected.key, 'local');
assert.deepEqual(scope.readRoots, ['C:\\Users\\Zenchant\\codex\\beadboard']);
assert.equal(scope.options[0].key, 'local');
assert.equal(scope.options.length, 3);
});
test('resolveProjectScope selects registry project when key matches', () => {
const scope = resolveProjectScope({
currentProjectRoot: 'C:/Users/Zenchant/codex/beadboard',
registryProjects: REGISTRY,
requestedProjectKey: 'd:\\repos\\beta',
});
assert.equal(scope.selected.source, 'registry');
assert.equal(scope.selected.root, 'D:\\Repos\\Beta');
assert.equal(scope.selected.key, 'd:\\repos\\beta');
assert.deepEqual(scope.readRoots, ['D:\\Repos\\Beta']);
});
test('resolveProjectScope falls back to local when query key is unknown', () => {
const scope = resolveProjectScope({
currentProjectRoot: 'C:/Users/Zenchant/codex/beadboard',
registryProjects: REGISTRY,
requestedProjectKey: 'd:\\repos\\missing',
});
assert.equal(scope.selected.source, 'local');
assert.equal(scope.selected.key, 'local');
assert.deepEqual(scope.readRoots, ['C:\\Users\\Zenchant\\codex\\beadboard']);
});
test('resolveProjectScope deduplicates registry entries by normalized key', () => {
const scope = resolveProjectScope({
currentProjectRoot: 'C:/Users/Zenchant/codex/beadboard',
registryProjects: [{ path: 'D:/Repos/Alpha/' }, { path: 'd:\\repos\\alpha' }],
});
assert.equal(scope.options.length, 2);
assert.equal(scope.options.filter((option) => option.source === 'registry').length, 1);
});
test('resolveProjectScope supports aggregate mode and reads all roots', () => {
const scope = resolveProjectScope({
currentProjectRoot: 'C:/Users/Zenchant/codex/beadboard',
registryProjects: REGISTRY,
requestedProjectKey: 'd:\\repos\\alpha',
requestedMode: 'aggregate',
});
assert.equal(scope.mode, 'aggregate');
assert.equal(scope.selected.key, 'd:\\repos\\alpha');
assert.deepEqual(scope.readRoots, [
'C:\\Users\\Zenchant\\codex\\beadboard',
'D:\\Repos\\Alpha',
'D:\\Repos\\Beta',
]);
});
test('resolveProjectScope falls back to single mode for unknown mode values', () => {
const scope = resolveProjectScope({
currentProjectRoot: 'C:/Users/Zenchant/codex/beadboard',
registryProjects: REGISTRY,
requestedMode: 'invalid-mode',
});
assert.equal(scope.mode, 'single');
assert.deepEqual(scope.readRoots, ['C:\\Users\\Zenchant\\codex\\beadboard']);
});

71
tests/lib/scanner.test.ts
View file

@ -51,12 +51,27 @@ test('scanForProjects respects depth limits and ignore list', async () => {
await withTempUserProfile(async (userProfile) => {
const projectRoot = path.join(userProfile, 'ProjectA');
await fs.mkdir(path.join(projectRoot, '.beads'), { recursive: true });
await fs.writeFile(
path.join(projectRoot, '.beads', 'issues.jsonl'),
JSON.stringify({ id: 'bb-a', title: 'A', issue_type: 'task', status: 'open', priority: 1 }),
'utf8',
);
const ignoredRoot = path.join(userProfile, 'node_modules', 'Ignored');
await fs.mkdir(path.join(ignoredRoot, '.beads'), { recursive: true });
await fs.writeFile(
path.join(ignoredRoot, '.beads', 'issues.jsonl'),
JSON.stringify({ id: 'bb-ignored', title: 'Ignored', issue_type: 'task', status: 'open', priority: 1 }),
'utf8',
);
const deepRoot = path.join(userProfile, 'Deep', 'Level1', 'Level2', 'ProjectDeep');
await fs.mkdir(path.join(deepRoot, '.beads'), { recursive: true });
await fs.writeFile(
path.join(deepRoot, '.beads', 'issues.jsonl'),
JSON.stringify({ id: 'bb-deep', title: 'Deep', issue_type: 'task', status: 'open', priority: 1 }),
'utf8',
);
const result = await scanForProjects({ maxDepth: 1 });
const keys = result.projects.map((project) => project.key);
@ -66,3 +81,59 @@ test('scanForProjects respects depth limits and ignore list', async () => {
assert.equal(keys.includes(windowsPathKey(canonicalizeWindowsPath(deepRoot))), false);
});
});
test('scanForProjects ignores directories that have .beads but no issues JSONL files', async () => {
await withTempUserProfile(async (userProfile) => {
const falsePositiveRoot = path.join(userProfile, 'LooksLikeBeadsProject');
await fs.mkdir(path.join(falsePositiveRoot, '.beads'), { recursive: true });
const validRoot = path.join(userProfile, 'ValidProject');
await fs.mkdir(path.join(validRoot, '.beads'), { recursive: true });
await fs.writeFile(
path.join(validRoot, '.beads', 'issues.jsonl'),
JSON.stringify({ id: 'bb-1', title: 'valid', issue_type: 'task', status: 'open', priority: 1 }),
'utf8',
);
const result = await scanForProjects();
const keys = result.projects.map((project) => project.key);
assert.equal(keys.includes(windowsPathKey(canonicalizeWindowsPath(falsePositiveRoot))), false);
assert.equal(keys.includes(windowsPathKey(canonicalizeWindowsPath(validRoot))), true);
});
});
test('scanForProjects ignores tool/cache paths even if they contain issues JSONL', async () => {
await withTempUserProfile(async (userProfile) => {
const tempBeads = path.join(userProfile, 'AppData', 'Local', 'Temp', 'beadboard-read-X');
await fs.mkdir(path.join(tempBeads, '.beads'), { recursive: true });
await fs.writeFile(
path.join(tempBeads, '.beads', 'issues.jsonl'),
JSON.stringify({ id: 'bb-temp', title: 'temp', issue_type: 'task', status: 'open', priority: 1 }),
'utf8',
);
const skillsBeads = path.join(userProfile, '.agents', 'skills', 'create-beads-orchestration');
await fs.mkdir(path.join(skillsBeads, '.beads'), { recursive: true });
await fs.writeFile(
path.join(skillsBeads, '.beads', 'issues.jsonl'),
JSON.stringify({ id: 'bb-skill', title: 'skill', issue_type: 'task', status: 'open', priority: 1 }),
'utf8',
);
const realProject = path.join(userProfile, 'RealProject');
await fs.mkdir(path.join(realProject, '.beads'), { recursive: true });
await fs.writeFile(
path.join(realProject, '.beads', 'issues.jsonl'),
JSON.stringify({ id: 'bb-real', title: 'real', issue_type: 'task', status: 'open', priority: 1 }),
'utf8',
);
const result = await scanForProjects();
const keys = result.projects.map((project) => project.key);
assert.equal(keys.includes(windowsPathKey(canonicalizeWindowsPath(tempBeads))), false);
assert.equal(keys.includes(windowsPathKey(canonicalizeWindowsPath(skillsBeads))), false);
assert.equal(keys.includes(windowsPathKey(canonicalizeWindowsPath(realProject))), true);
});
});