# Dolt Database Organization & PATH Troubleshooting

Organized scattered CLI `.txt` help texts into `beadboard/help/cli/` and added explicit workflow guides in `beadboard/help/workflows` for checking recently closed beads (`bd query`) and using the new `bd vc` dolt database features.

**Issues Encountered & Resolved:**
1. User accidentally ran `dolt init` in root rather than running commands in the actual DB directory (`.beads/dolt/beadboard/`). The empty root DB was pushed to DoltHub.
2. We navigated correctly to `.beads/dolt/beadboard/` and ran `dolt push -f origin main` to forcefully overwrite the empty database on DoltHub with the actual issue history.
3. The installed `bd` binary (`0.49.6`) was out of date. User ran the remote update script to `0.57.0`.
4. The updated `bd` directory (`C:\Users\Zenchant\AppData\Local\Programs\bd`) was not on the system `PATH`. We programmatically updated the `$env:Path` in the registry and the active session.
5. `bd 0.57.0` does not bundle the `dolt` binary anymore. The `bd ready` command was throwing a "Dolt server unreachable... dolt is not installed" error.
6. We resolved this by downloading the official Dolt windows release archive, extracting `dolt.exe`, and placing it alongside `bd.exe` in the `bd` data directory. The `bd ready` command now successfully auto-starts the Dolt server.

Dolt Migration and PATH Fixes


test


All Phase 1 children complete: ContextualRightPanel now branches on epicId, taskId, swarmId, with ActivityPanel fallback. URL context contract fully wired.

Make the right panel adapt to full URL context, not just epicId. Current ContextualRightPanel only branches on epicId — all other selections (task, agent, swarm) fall through to the global ActivityPanel feed.

Ref: docs/plans/2026-02-28-ux-redesign-synthesis-prd.md §8 Phase 1

URL context contract:
  No selection       → ActivityPanel (global feed) ✓ done in Phase 0
  ?epic=X            → SwarmCommandFeed for that epic ✓ already works
  ?task=X            → Task thread + agent assignment controls
  ?agent=X           → Agent liveness details + missions + current task
  ?swarm=X           → MissionInspector (swarm topology + agent roster)

Acceptance: Selecting a task shows task thread in right panel. Selecting a swarm shows swarm inspector. No selection shows global activity feed.

Phase 1: Contextual Right Panel


Added taskId and swarmId to ContextualRightPanelProps. UnifiedShell now passes both. TypeScript clean. Stubs ready for r1i.2 and r1i.3.

TASK CONTEXT
- Bead ID: beadboard-r1i.1
- Title: Extend ContextualRightPanel props and thread taskId/swarmId from UnifiedShell
- Parent/Epic: beadboard-r1i
- Dependencies: none (first in phase)

TASK CONTRACT
- Goal: Add taskId and swarmId to ContextualRightPanelProps and pass them from UnifiedShell, so child tasks can implement per-branch rendering. No visible change yet — stubs only.
- Success Criteria:
  - ContextualRightPanelProps includes taskId?: string | null and swarmId?: string | null
  - UnifiedShell passes both params to <ContextualRightPanel>
  - TypeScript compiles clean (npm run typecheck passes)
  - Existing epicId branch and ActivityPanel fallback continue working
- Scope:
  - src/components/activity/contextual-right-panel.tsx — props interface only
  - src/components/shared/unified-shell.tsx — pass taskId, swarmId to ContextualRightPanel call (~line 162)
- Out of Scope:
  - Implementing the actual task or swarm branch content (that is r1i.2, r1i.3)
  - Adding agentId (no agent detail view planned for this phase)

IMPLEMENTATION CONSTRAINTS
- Preserve existing backend/API contracts unless explicitly stated otherwise.
- Reuse shared components and logic; avoid one-off forks.
- Keep changes targeted and minimal for this bead.

VERIFICATION REQUIREMENTS
- Required commands:
  - npm run typecheck
  - npm run lint
  - npm run test
- Report any remaining risks and follow-up beads explicitly.

Extend ContextualRightPanel props and thread taskId/swarmId from shell


TaskId branch added to ContextualRightPanel: ThreadDrawer in embedded mode renders task thread and issue metadata when taskId is set. No new typecheck errors.

TASK CONTEXT
- Bead ID: beadboard-r1i.2
- Title: Implement task branch in ContextualRightPanel (?task=X)
- Parent/Epic: beadboard-r1i
- Dependencies: beadboard-r1i.1 (taskId prop must exist on ContextualRightPanel)

TASK CONTRACT
- Goal: When a task is selected (taskId is set), the right panel shows the task thread and issue metadata using ThreadDrawer in embedded mode.
- Success Criteria:
  - Selecting any task card opens right panel showing that task's thread (comments, events)
  - ThreadDrawer renders in embedded mode (no modal/overlay behaviour)
  - Issue title, status badge, and thread items are visible in the right panel
  - Deselecting the task (clearing taskId) returns right panel to ActivityPanel global feed
  - npm run typecheck passes
- Scope:
  - src/components/activity/contextual-right-panel.tsx — add taskId branch before the ActivityPanel fallback
  - ThreadDrawer already exists at src/components/shared/thread-drawer.tsx with embedded prop
  - Use ThreadDrawer with: embedded=true, isOpen=true, issue from issues array, projectRoot
- Out of Scope:
  - Agent assignment controls in the right panel (Phase 3)
  - Creating a new component — reuse ThreadDrawer embedded mode
  - Modifying ThreadDrawer itself

IMPLEMENTATION CONSTRAINTS
- Preserve existing backend/API contracts unless explicitly stated otherwise.
- Reuse shared components and logic; avoid one-off forks.
- Keep changes targeted and minimal for this bead.

VERIFICATION REQUIREMENTS
- Required commands:
  - npm run typecheck
  - npm run lint
  - npm run test
- Report any remaining risks and follow-up beads explicitly.


SwarmId branch added via SwarmIdBranch inner component (hooks-safe): MissionInspector renders with useSwarmList for title lookup. assignedAgents wired to swarm.agents (TODO: populate from agent-registry). No new typecheck errors.

TASK CONTEXT
- Bead ID: beadboard-r1i.3
- Title: Implement swarm branch in ContextualRightPanel (?swarm=X)
- Parent/Epic: beadboard-r1i
- Dependencies: beadboard-r1i.1 (swarmId prop must exist on ContextualRightPanel)

TASK CONTRACT
- Goal: When a swarm is selected (swarmId is set), the right panel shows MissionInspector with that swarm's topology, agent roster, and mission status.
- Success Criteria:
  - Navigating to ?swarm=X renders MissionInspector in the right panel
  - MissionInspector receives correct missionId, missionTitle, projectRoot, assignedAgents
  - Existing epicId and task branches are unaffected
  - npm run typecheck passes
- Scope:
  - src/components/activity/contextual-right-panel.tsx — add swarmId branch
  - MissionInspector at src/components/mission/mission-inspector.tsx (props: missionId, missionTitle, projectRoot, assignedAgents, onClose, onAssign)
  - Resolve assignedAgents: check useSwarmList hook or /api/agents — use whatever UnifiedShell already has available
  - onClose: clear swarmId from URL state; onAssign: call /api/mission/assign
- Out of Scope:
  - Building a new swarm inspector UI — MissionInspector already exists
  - Graph swarm overlay highlighting (Phase 3)

IMPLEMENTATION CONSTRAINTS
- Preserve existing backend/API contracts unless explicitly stated otherwise.
- Reuse shared components and logic; avoid one-off forks.
- Keep changes targeted and minimal for this bead.

VERIFICATION REQUIREMENTS
- Required commands:
  - npm run typecheck
  - npm run lint
  - npm run test
- Report any remaining risks and follow-up beads explicitly.


TASK CONTEXT\n- Goal: Improve non-json status UX with complete operational diagnostics.\n\nTASK CONTRACT\n- Success Criteria:\n  -  prints runtime + bd diagnostics clearly\n  - output remains stable and parse-friendly for humans\n- Scope:\n  - launcher text rendering for status\n- Out of Scope:\n  - redesigning JSON schema\n\nVERIFICATION REQUIREMENTS\n- npm run typecheck\n- npm run lint\n- npm run test

[EPIC] Status UX Diagnostics (Text Mode)


Added full non-json status diagnostics output with tests and full verification evidence.

TASK CONTEXT\n- Parent/Epic: beadboard-rc8\n\nTASK CONTRACT\n- Goal: Make status output (without --json) print complete runtime and bd diagnostics.\n- Success Criteria:\n  - text output includes running/url/port/runtime/installMode/shimTarget/bd/project checks\n  - focused tests cover text mode\n- Scope:\n  - install/beadboard.mjs text output path\n  - new/updated launcher status tests\n- Out of Scope:\n  - adding new commands\n\nVERIFICATION REQUIREMENTS\n- node --import tsx --test tests/scripts/beadboard-launcher-status-text.test.ts\n- npm run typecheck\n- npm run lint\n- npm run test

Add comprehensive non-json status diagnostics


Recreating as proper children of Phase 0 epic with correct naming

The views array in LeftPanel and the tabs array in MobileNav both only have Social and Graph. Activity is a valid view but unreachable from navigation.

File 1: src/components/shared/left-panel.tsx
Location: views array (~line 188)
Change:
  const views: Array<{ id: ViewType; label: string }> = [
    { id: 'social', label: 'Social' },
    { id: 'graph', label: 'Graph' },
    { id: 'activity', label: 'Activity' },  // add this
  ];

File 2: src/components/shared/mobile-nav.tsx
Location: tabs array (~line 6)
Change: Add Activity tab and replace Unicode glyphs with Lucide icons:
  import { LayoutList, Share2, Activity } from 'lucide-react';
  const tabs = [
    { id: 'social', label: 'Social', icon: <LayoutList className='h-5 w-5' /> },
    { id: 'graph', label: 'Graph', icon: <Share2 className='h-5 w-5' /> },
    { id: 'activity', label: 'Activity', icon: <Activity className='h-5 w-5' /> },
  ];
Also add aria-label={tab.label} to each tab button, and update render to use {tab.icon} JSX (not string).

Check mobile-nav.tsx current icon rendering before changing - confirm the tab type and render pattern.

Acceptance: Left panel and mobile nav both show three tabs (Social, Graph, Activity). Mobile nav icons are Lucide SVGs with aria-labels.

P0.3: Add Activity tab to LeftPanel and MobileNav


Fixed: filtered memory-anchor and brainstorm epics, added hideClosed check for epic status

## Context
Epics with zero child tasks are hidden in the left panel when hideClosed=true (the default).

## Root Cause
Line 327 in left-panel.tsx:

This hides ANY epic with matchedChildren=0 when filters are active. Since hideClosed defaults to true, this hides ALL epics that have no children (which is ALL epics currently since none have parent-child deps).

## Fix
Change condition to only hide if the epic HAS children but they're all filtered out:

Fixed two issues in left-panel.tsx:
1. Line 73: Filter out memory-anchor and brainstorm epics from epic list
2. Line 327: Added check to hide closed/tombstone epics when hideClosed=true

Before: ALL epics were hidden because:
- hideClosed defaults to true
- No code checked epic status, only matchedChildren
- All 0-child epics were hidden

After:
- Memory anchors (memory-anchor label) filtered out
- Brainstorm epics (brainstorm label) filtered out
- Closed/tombstone epics hidden when hideClosed=true
- Epics with children only hidden when all children filtered

Verification: npm run typecheck PASS, npm run lint PASS (warnings only), npm run test PASS (2 pre-existing failures)

[BUG] Epics with no children hidden by hideClosed filter


Scope: Improve the Dependency Graph and Workflow Graph views to clearly indicate critical paths, differentiate between direct and indirect (transitive) blocks, and use status colors effectively. Out of scope: Other graph layouts. Success Criteria: Edges correctly reflect their dependency types visually.

Epic: Enhanced Graph Edge Visualization


Core calculation algorithm implemented successfully.

Scope: Write a robust algorithm that processes DAG nodes to identify transitive (redundant) edges across paths.\nOut of scope: UI rendering.\nSuccess Criteria: Takes nodes and edges, returns map of edges indicating if they are transitive or direct.

Transitive Reduction implemented via BFS path search. Test coverage added in graph-view.test.ts. bun run lint/typecheck/test passed cleanly.

Implement graph transitive reduction algorithm


Scope: Update ReactFlow Edge generation in workflow-graph.tsx, dependency-graph-page.tsx, and specialized-agent-dag.tsx.\nOut of scope: Algorithm calculation.\nSuccess Criteria: Critical/in-progress edges glow bright amber. Standard direct edges are blue/slate. Transitive edges are dimmed/dashed dark gray.

npm run test passed. Transitive edge styling verified.

Apply Status Colors and Transitive Context to Graph Edges


Critical chain focus highlighting successfully implemented.

Scope: When a node is clicked, highlight inbound/outbound blockers clearly, fading out the rest of the graph.\nSuccess Criteria: The critical chain of a selected task is visually obvious.

Completed critical chain highlighting using BFS on the graph edges, and tests pass cross-platform.

Implement Graph Focus (Selection) Interactivity


TASK CONTEXT\n- Parent: beadboard-c70 / beadboard-05a\n\nTASK CONTRACT\n- Goal: Add installer and launcher smoke tests for Windows/Linux/mac and wire CI matrix.\n- Success Criteria:\n  - install smoke tests per OS\n  - reinstall/idempotency + failure-mode checks\n  - CI matrix jobs for installer smoke\n- Scope: tests and workflow config\n- Out of Scope: enterprise installer signing pipeline\n\nVERIFICATION REQUIREMENTS\n- npm run typecheck\n- npm run lint\n- npm run test

Superseded by hierarchical execution tree under beadboard-05a.x

Installer test matrix + CI smoke coverage


## Goal
Merge the duplicate graph implementations (?view=graph, ?view=swarm, and /graph page) into one enhanced graph view with two modes:
- Analysis mode (default): Full dependency DAG with progressive disclosure
- Assign mode (toggled): DAG highlights ready nodes, right panel shows assignment controls

## Problem
BeadBoard has two views (`?view=graph` and `?view=swarm`) that both render the same `WorkflowGraph` DAG component, creating duplication. The standalone `/graph` page (`DependencyGraphPage`) has rich dependency analysis features (hop depth, focus workspace, cycle detection, flow strip) that are stranded -- the shell's `?view=graph` is a bare 49-line wrapper (`SmartDag`) with none of them.

## Success Criteria
- ?view=graph shows enhanced DAG with all dependency analysis features
- 'Assign' toggle enables task assignment workflow
- ?view=swarm deprecated (falls back to default view)
- Archetypes/Templates accessible from assign mode right panel
- All implementation steps completed
- npm run typecheck, lint, test all pass

## Scope
- SmartDag rewrite with progressive disclosure + tabs + assign mode
- AssignmentPanel component for assign mode
- useGraphAnalysis hook extraction
- Swarm view removal from navigation
- Delete deprecated swarm files

## Out of Scope
- Backend API changes (use existing /api/swarm/prep)
- New archetypes/templates features
- Mobile-specific layouts

## Reference
PRD: docs/prd/unified-graph-view.md

Unify Graph + Swarm into Single Enhanced Graph View


SSE Test Bead


Completed global install runtime-manager rollout plan phases 0-8 with TDD evidence, runtime metadata/shim migration, launcher runtime status, CLI doctor/update/uninstall, driver remediation alignment, and CI/docs updates.

Scope: Implement npm-global-first runtime manager with migration from repo-path shims. Out of Scope: unrelated UI/test stabilization. Success Criteria: Tasks 0-8 from docs/plans/2026-03-03-global-install-runtime-manager.md implemented with verification evidence.

Global installer runtime manager implementation


Scope:
- beadboard launcher startup UX and docs for Dolt readiness
Out of Scope:
- changing bd storage backend internals
Success Criteria:
- beadboard start prints clear guidance about bd dolt start and project folder
- beadboard start --dolt starts Dolt (if available) then starts BeadBoard dev server
- README launcher command docs include both flows

[EPIC] Start Command Dolt Bootstrapping


Added start guidance and --dolt combined startup flow with tests/docs

Scope:
- install/beadboard.mjs start command behavior and messaging
- launcher tests for start guidance and --dolt behavior
- README launcher docs
Out of Scope:
- modifying bd tool behavior
Success Criteria:
- beadboard start prints guidance to run bd dolt start in project folder and points to beadboard start --dolt
- beadboard start --dolt attempts bd dolt start in CWD before app start
- tests cover both behaviors
- README includes this guidance

Implemented startup UX + Dolt bootstrap integration:
- Added launcher flag parsing for --dolt
- beadboard start now prints explicit guidance: run `bd dolt start` in project folder, or use `beadboard start --dolt`
- Implemented `start --dolt` to invoke `bd dolt start` in current working directory before BeadBoard startup
- Added BB_START_NOOP path for deterministic launcher tests
- Updated CLI help text to show `start [--dolt]`
- Updated README launcher docs with startup note and one-command flow

TDD evidence:
- RED: node --import tsx --test tests/scripts/beadboard-launcher.test.ts (hung/cancelled before implementation due real start path)
- GREEN: node --import tsx --test tests/scripts/beadboard-launcher.test.ts (pass)
- GREEN: node --import tsx --test tests/cli/beadboard-help-output.test.ts (pass)

Verification evidence (2026-03-03):
- npm run typecheck (pass)
- npm run lint (pass, 0 errors / 21 warnings in unrelated files)
- npm run test (pass)

Memory review: no new reusable memory.

Add start guidance + --dolt path


Fixed Hide Closed regression across left panel and graph epic chip surfaces; added selected-state invalidation and regression tests.

## Context
Epics with zero child tasks are hidden in the left panel when hideClosed=true (the default).

## Root Cause
Line 327 in left-panel.tsx filters out epics with no matched children, but since all epics have 0 children currently, they get hidden.

## Notes
NEEDS DISCUSSION: Before implementing, discuss with user - the fix affects epic visibility logic.

Root cause and fixes for Hide Closed epic leakage:\n\nRoot causes:\n1) Left panel logic exempted selected epics from hide checks, so a selected closed epic (bb-u6f.7) remained visible.\n2) Dependency graph epic chip strip was fed unfiltered epics in one path, so Hide Closed did not consistently apply in that surface.\n3) Runtime data freshness was vulnerable to stale session state when SSE degraded; initial refresh hardening was added.\n\nFixes shipped:\n- left-panel.tsx: Hide Closed now hides closed/tombstone epics even when selected.\n- unified-shell.tsx: when hideClosed=true, selected closed epic is auto-cleared.\n- dependency-graph-page.tsx: EpicChipStrip and selection logic now use hide-closed filtered selectableEpics.\n- page.tsx + use-beads-subscription.ts: force-dynamic + initial silent refresh to reduce stale SSR/session reads.\n\nVerification evidence:\n- node --import tsx --test tests/components/shared/left-panel-filtering.test.ts => PASS\n- node --import tsx --test tests/components/shared/unified-shell-hide-closed-contract.test.ts => PASS\n- node --import tsx --test tests/components/graph/dependency-graph-hide-closed-contract.test.ts => PASS\n- npm run typecheck => PASS\n- npm run lint => PASS (warnings only)\n- npm run test => FAIL (pre-existing unrelated graphTab expectation in tests/hooks/url-state-integration.test.ts)\n\nMemory review trigger: create canonical memories for cross-surface filter invariants and selected-state invalidation under filters.


Phase 4 Agent Presence complete. livenessMap lifted to UnifiedShell; agent avatars on SocialCard + graph nodes with liveness animation; LeftPanel footer shows live workspace stats. Typecheck clean, lint clean, 29/31 tests pass (2 pre-existing url-state failures).

TASK CONTEXT
- Bead ID: (auto)
- Title: Phase 4: Agent Presence
- Parent/Epic: none (phase epic)
- Dependencies (must be done first): beadboard-0fi (Phase 2 — actor identity in shell)

TASK CONTRACT
- Goal: Move livenessMap from the deprecated SessionsHeader up to UnifiedShell and surface live agent state on both Social cards and Graph nodes, so an operator can see which agents are active and what they are working on within 5 seconds of opening the app.
- Success Criteria:
  - useSessionFeed called in UnifiedShell, livenessMap available at shell level
  - SocialCard shows agent avatar and liveness dot for the assigned agent
  - Graph nodes show agent avatar with pulse animation for stuck agents
  - LeftPanel footer replaced with live workspace stats (N agents active, M tasks in motion)
  - npm run typecheck && npm run lint && npm run test all pass
- Scope:
  - UnifiedShell livenessMap lift (src/hooks/use-session-feed.ts already exists)
  - SocialCard agent presence UI
  - SmartDag/graph node agent presence UI
  - LeftPanel footer stats
- Out of Scope:
  - Creating new API endpoints (liveness data already flows via SSE)
  - Agent detail right panel (covered in Phase 1)

IMPLEMENTATION CONSTRAINTS
- Preserve existing backend/API contracts unless explicitly stated otherwise.
- Reuse shared components and logic; avoid one-off forks.
- Keep changes targeted and minimal for this bead.

VERIFICATION REQUIREMENTS
- Required commands:
  - npm run typecheck
  - npm run lint
  - npm run test
- Report any remaining risks and follow-up beads explicitly.

Orchestrator agent beadboard-rnk claimed this epic. x3l.1 closed, x3l.2/3/4 dispatched as parallel sub-agents.

Phase 4: Agent Presence


useSessionFeed lifted to UnifiedShell; livenessMap+agentStats wired to SmartDag, SocialPage, LeftPanel props. Typecheck clean, tests 131/133 (2 pre-existing).

TASK CONTEXT
- Bead ID: beadboard-x3l.1
- Title: Move useSessionFeed/livenessMap up to UnifiedShell
- Parent/Epic: beadboard-x3l
- Dependencies (must be done first): none (first in phase)

TASK CONTRACT
- Goal: useSessionFeed is currently only called in sessions-page.tsx (deprecated route). Call it in UnifiedShell and make livenessMap available as a prop to SocialCard and SmartDag.
- Success Criteria:
  - useSessionFeed(projectRoot) called in UnifiedShell
  - livenessMap: Record<string, string> available in UnifiedShell scope
  - livenessMap passed down to SocialPage and SmartDag as a prop (even if they don't use it yet — that is beadboard-x3l.2 and beadboard-x3l.3)
  - No duplicate SSE connections opened (verify useSessionFeed does not re-subscribe on re-render)
  - npm run typecheck passes
- Scope:
  - src/components/shared/unified-shell.tsx — add useSessionFeed call
  - src/hooks/use-session-feed.ts — read to understand return shape before using
  - src/components/social/social-page.tsx — add livenessMap prop (pass through to cards later)
  - src/components/graph/smart-dag.tsx — add livenessMap prop (use in x3l.3)
- Out of Scope:
  - Rendering agent avatars yet (beadboard-x3l.2, x3l.3)
  - Removing useSessionFeed from sessions-page.tsx (leave it, legacy route)

IMPLEMENTATION CONSTRAINTS
- Preserve existing backend/API contracts unless explicitly stated otherwise.
- Reuse shared components and logic; avoid one-off forks.
- Keep changes targeted and minimal for this bead.

VERIFICATION REQUIREMENTS
- Required commands:
  - npm run typecheck
  - npm run lint
  - npm run test
- Report any remaining risks and follow-up beads explicitly.

DONE: Added useSessionFeed to UnifiedShell, livenessMap wired to SmartDag/SocialPage/LeftPanel. Typecheck clean. 131/133 tests pass (2 pre-existing failures in url-state-integration unrelated to this change).


AgentAvatar rendered in SocialCard header when assignee in livenessMap. mapLiveness helper exported. SocialPage passes livenessMap to cards. 9 new tests in social-card-liveness.test.ts. Typecheck clean, no regressions.

TASK CONTEXT
- Bead ID: beadboard-x3l.2
- Title: Render agent avatar and liveness dot on SocialCard
- Parent/Epic: beadboard-x3l
- Dependencies (must be done first): beadboard-x3l.1

TASK CONTRACT
- Goal: Each SocialCard for an assigned task should show the assigned agent's avatar and a liveness dot (active/stale/stuck) using livenessMap from the shell.
- Success Criteria:
  - SocialCard receives livenessMap: Record<string, string> prop
  - If issue.assignee exists and is in livenessMap, renders AgentAvatar component with liveness indicator
  - Liveness states: 'active' (green dot), 'stale' (amber dot), 'stuck' (red pulse)
  - Cards without an assignee show no avatar — no empty avatar placeholder
  - npm run typecheck passes
- Scope:
  - src/components/social/social-card.tsx — add livenessMap prop and avatar render
  - src/components/social/social-page.tsx — thread livenessMap through to each SocialCard
  - Check if AgentAvatar component exists (grep src/ for AgentAvatar) and use it; if not, render a simple initials circle
- Out of Scope:
  - Graph node agent presence (beadboard-x3l.3)
  - Inline assign affordance (Phase 3, beadboard-8ij.2)

IMPLEMENTATION CONSTRAINTS
- Preserve existing backend/API contracts unless explicitly stated otherwise.
- Reuse shared components and logic; avoid one-off forks.
- Keep changes targeted and minimal for this bead.

VERIFICATION REQUIREMENTS
- Required commands:
  - npm run typecheck
  - npm run lint
  - npm run test
- Report any remaining risks and follow-up beads explicitly.


AgentAvatar overlay added to GraphNodeCard (bottom-right, sm size) with liveness→status mapping. WorkflowGraph and SmartDag wired. 10 new tests in graph-node-liveness.test.ts. Typecheck clean, no regressions.

TASK CONTEXT
- Bead ID: beadboard-x3l.3
- Title: Render agent avatar on graph nodes with stuck-agent pulse
- Parent/Epic: beadboard-x3l
- Dependencies (must be done first): beadboard-x3l.1

TASK CONTRACT
- Goal: Active graph nodes should show the assigned agent's avatar. Nodes whose agent is in a 'stuck' liveness state should display a pulsing warning treatment so the operator can spot problems at a glance in the DAG view.
- Success Criteria:
  - Graph node card renders a small agent avatar when issue.assignee is present in livenessMap
  - Stuck agents (livenessMap value === 'stuck') show a CSS pulse/ring animation on the node border
  - Non-assigned nodes are visually unchanged
  - npm run typecheck passes
- Scope:
  - src/components/graph/smart-dag.tsx or the node card component it renders — add livenessMap prop and avatar/pulse render
  - Read SmartDag to find where individual node UI is rendered before editing
- Out of Scope:
  - SocialCard presence (beadboard-x3l.2)
  - Graph layout or DAG structure changes

IMPLEMENTATION CONSTRAINTS
- Preserve existing backend/API contracts unless explicitly stated otherwise.
- Reuse shared components and logic; avoid one-off forks.
- Keep changes targeted and minimal for this bead.

VERIFICATION REQUIREMENTS
- Required commands:
  - npm run typecheck
  - npm run lint
  - npm run test
- Report any remaining risks and follow-up beads explicitly.


LeftPanel footer replaced with WorkspaceStatsFooter showing live agent count + in-motion tasks from livenessMap/agentStats. Hardcoded Alex Chen removed. Typecheck clean, 10/10 left-panel tests pass.

TASK CONTEXT
- Bead ID: beadboard-x3l.4
- Title: Replace LeftPanel footer with live workspace stats
- Parent/Epic: beadboard-x3l
- Dependencies (must be done first): beadboard-x3l.1

TASK CONTRACT
- Goal: The LeftPanel footer currently shows a hardcoded identity string. Replace it with live stats: number of active agents and number of tasks currently in motion, derived from livenessMap and the live issues array.
- Success Criteria:
  - Footer shows 'N agents active, M tasks in motion' with real counts
  - Counts update reactively when SSE pushes changes
  - No hardcoded identity text remains in LeftPanel footer
  - npm run typecheck passes
- Scope:
  - src/components/shared/left-panel.tsx — update footer section
  - LeftPanel already receives issues prop — use it for task count
  - livenessMap passed from UnifiedShell (add to LeftPanelProps if not present)
- Out of Scope:
  - TopBar identity input (beadboard-0fi.1)
  - Changing LeftPanel navigation or epic tree

IMPLEMENTATION CONSTRAINTS
- Preserve existing backend/API contracts unless explicitly stated otherwise.
- Reuse shared components and logic; avoid one-off forks.
- Keep changes targeted and minimal for this bead.

VERIFICATION REQUIREMENTS
- Required commands:
  - npm run typecheck
  - npm run lint
  - npm run test
- Report any remaining risks and follow-up beads explicitly.


Ratified canonical workflow memory requiring explicit in-UI user confirmation for persistent regressions.

Scope: Bugs reported by user as still reproducing after an attempted fix.\nOut of Scope: Backend-only changes with no user-visible behavior.\nRule: Add an explicit confirmation checkpoint against the user-observed surface before closing or announcing completion.\nRationale: Green tests do not guarantee resolution in the user’s actual runtime context.\nFailure Mode: Assistant repeatedly claims fixes while user still sees the bug.

Canonicalized from user-correction loop: do not mark user-visible bug resolved without explicit in-UI confirmation checkpoint. Provenance: beadboard-x1y, beadboard-4k8. Linked to workflow anchor beadboard-nq9.

[MEMORY][WORKFLOW][SOFT] Persisting user-reported regressions require explicit in-UI confirmation checkpoint


Progress: Added child task for Fit to Screen control implementation in graph canvas.

DAG Views UX Overhaul (Macro/Micro Contexts)


Graph view shows a Fit to screen control; clicking it re-fits the DAG within viewport; typecheck and lint pass.

Added visible Fit to screen control in DAG graph and wired it to ReactFlow fitView for user-triggered viewport re-fit.

Scope: Add a visible Fit to Screen button in the DAG graph view that re-runs ReactFlow fitView after users pan/zoom. Out of scope: layout density controls or node size sliders.

Implemented in src/components/shared/workflow-graph.tsx: added Fit to screen button in top-right control area; wired to handleFitToScreen() using reactflow fitView().
Verification: npm run typecheck => PASS. npm run lint => PASS (19 existing warnings, 0 errors). Additional regression check: node --import tsx --test tests/api/bead-comments-item-route.test.ts => PASS (9 tests). Memory review: no new reusable memory.

Add Fit to Screen control to DAG graph canvas


Implemented recursive epic descendant inclusion and optional hierarchy (parent/subtask) edges in DAG with tests and verification evidence recorded.

Scope: Update graph issue selection for epic context to include all descendants, not only direct children; add hierarchy edge toggle for parent/subtask links in DAG.\nOut of Scope: social view behavior changes and non-DAG cards.\nSuccess Criteria: Nested subtasks appear in DAG; parent/subtask links are optional via toggle; tests cover new behavior.

Implemented DAG subtask visibility and hierarchy links.\n\nChanges:\n- Added src/lib/epic-graph.ts with collectEpicDescendantIds() and buildWorkflowEdges().\n- Updated src/components/graph/smart-dag.tsx to include recursive epic descendants (not just direct children).\n- Updated src/components/shared/workflow-graph.tsx to support hierarchy edge toggle (default on) and render SUBTASK edges alongside BLOCKS edges.\n- Added tests/lib/epic-graph.test.ts and registered it in package.json test script.\n\nTDD evidence:\n1) node --import tsx --test tests/lib/epic-graph.test.ts\n   - initial run failed (MODULE_NOT_FOUND: ../../src/lib/epic-graph)\n2) node --import tsx --test tests/lib/epic-graph.test.ts\n   - pass: 2 tests, 0 failed\n\nVerification gates:\n- npm run typecheck: PASS\n- npm run lint: PASS (warnings only, 0 errors)\n- npm run test: FAIL (pre-existing/unrelated failures in tests/hooks/url-state-integration.test.ts)\n  - /?view=graph - graph view default expected flow got overview\n  - /?view=graph&graphTab=invalid expected flow got overview\n\nMemory review: no new reusable memory.

Implement epic descendant inclusion + hierarchy edge toggle in DAG


Completed: Fixed cross-view nav with atomic buildUrlParams URL updates. Commit c246cea.

Fixed cross-view navigation between Social and Graph views. GitBranch button on social cards navigates to graph with graphTab=flow (Dependencies/DAG tab). Columns2 button on DAG nodes navigates to Social view. Fixed stale closure bug by using single buildUrlParams() -> router.push() for atomic multi-param URL updates instead of sequential setState calls. Scope: social-card.tsx, smart-dag.tsx, graph-node-card.tsx, use-url-state.ts. Success Criteria: Cross-view buttons navigate correctly without race conditions.

Fix cross-view navigation: Social <-> Graph with atomic URL params


When working on an epic, skill reads the template:XXX label, looks up the template definition, and uses team composition to spawn appropriate agents

Already captured in bb-buff.4 as template label integration concept

When the skill spawns work on an epic, it should:\n1. Check for labels starting with 'template:'\n2. Look up the template from /api/swarm/templates\n3. Use the team composition (archetype counts) to determine how many agents to spawn\n4. Follow the protoFormula workflow\n\nThis allows the user to assign templates to epics in the UI, and the skill will automatically understand what team is needed when asked to work on that epic.

Skill should read template labels from epics


Implement Frontend UI


TASK CONTEXT\n- Parent: beadboard-c70 / beadboard-05a\n\nTASK CONTRACT\n- Goal: Define canonical installer manifest schema and shared install semantics used by all OS wrappers.\n- Success Criteria:\n  - install/manifest.json schema defined\n  - shared installer contract documented and testable\n- Scope: version/channel resolution, artifact/checksum map, command mapping\n- Out of Scope: platform wrapper implementation\n\nVERIFICATION REQUIREMENTS\n- npm run typecheck\n- npm run lint

Installer Contract: canonical manifest + shared semantics


Make Archetypes and Templates Editable in Swarm View


Recreating as proper children of Phase 0 epic with correct naming

view=activity is a valid ViewType (in VALID_VIEWS in use-url-state.ts) but renderMiddleContent() in UnifiedShell returns null for it. SocialCard 'Jump to Activity' navigates users here, so they land on a blank page.

File: src/components/shared/unified-shell.tsx
Location: renderMiddleContent() function (around lines 103-140)

Change: Add before the final 'return null':
  if (view === 'activity') {
    return (
      <ActivityPanel
        issues={filteredIssues}
        projectRoot={projectRoot}
      />
    );
  }

Import: ActivityPanel is already used in contextual-right-panel.tsx:
  import { ActivityPanel } from '../activity/activity-panel';
Check ActivityPanel's props signature before adding - confirm it accepts issues and projectRoot.

Acceptance: Navigating to /?view=activity renders the activity feed. SocialCard 'Jump to Activity' link lands on content, not a blank page.

P0.2: Add activity render case to renderMiddleContent()


GraphNodeData interface includes labels field. WorkflowGraph passes issue.labels to node data. Tests verify labels are present in node data.

Completed. Added labels field to GraphNodeData interface and passed issue.labels through WorkflowGraph and dependency-graph-page. All 4 TDD tests pass. All verification gates pass.

## Completed Implementation

### Files Changed
- **src/components/graph/graph-node-card.tsx**: Added `labels: string[]` field to GraphNodeData interface
- **src/components/shared/workflow-graph.tsx**: Added `labels: issue.labels` to node data
- **src/components/graph/dependency-graph-page.tsx**: Added `labels: issue.labels` to node data (deprecated page kept working)
- **tests/components/graph/graph-node-labels.test.tsx**: Created 4 TDD tests
- **package.json**: Added new test file to test script

### Tests Written (TDD)
All 4 tests pass:
1. GraphNodeData interface includes labels field
2. GraphNodeData labels is typed as string array
3. WorkflowGraph passes issue.labels to node data
4. WorkflowGraph uses labels from issue in node mapping

### Verification Gates
- npm run typecheck: ✓ PASS
- npm run lint: ✓ PASS (0 errors, 21 warnings - all pre-existing)
- npm run test: ✓ PASS (all tests)

### Evidence
```
npm run typecheck
> tsc --noEmit
(no output = success)

npm run lint
✖ 21 problems (0 errors, 21 warnings)

npm run test
# tests 13 (including new graph-node-labels suite)
# pass 13
# fail 0
```

Pass labels to graph nodes


Anchors exist, at least 5 canonical memory nodes exist and are closed, links to anchors exist, and plan docs updated.

Phase 1 memory fabric bootstrapped in bd with anchors and canonical memory nodes

Implement Phase 1 native memory system in bd: create domain anchors, seed canonical memory decisions with strict schema labels, link via relates_to, and document evidence.

Evidence: created anchors beadboard-76p/fld/nq9/5r1/8st; created+closed canonical nodes beadboard-116,dvp,60a,zas,duo,6fv,fga; verified retrieval via bd query label=memory+mem-canonical+status=closed and connectivity via bd dep list.

Bootstrap Phase 1 Memory Fabric (anchors + canonical nodes)


Completed: Created TelemetryStrip with real /api/activity + SSE data. Commit 114bb18.

Created new TelemetryStrip component - a minimized right sidebar that shows recent activity event dots from /api/activity + SSE (same data source as ActivityPanel). Uses getEventTone() color coding. Includes maximize button to restore full activity feed. Scope: telemetry-strip.tsx (NEW), unified-shell.tsx. Success Criteria: TelemetryStrip shows real activity events as colored dots, maximize restores full feed.

Create TelemetryStrip minimized sidebar component


Given a behavior change touching multiple views, when implementation lands, then shared logic path is reused and covered by tests.
Verification command(s): rg "<shared-function-or-hook>" src tests; npm run test

Scope: Repeated logic used by multiple views or pages.
Out of Scope: One-off prototypes and disposable experiments.
Rule: Reuse shared paths/components for cross-view behavior; avoid one-off logic drift.
Rationale: Prevents silent divergence between Kanban, Graph, and API views.
Failure Mode: Patching one surface only creates inconsistent user behavior.

Provenance linked: beadboard-68k.4, beadboard-68k.5, beadboard-r1i.1

[MEMORY][ARCH][HARD] Shared logic for cross-view behavior


pulse:test-coord-izs2:1772590713612


pulse:silver-scribe:1772591154975


pulse:silver-scribe:1772591174677


pulse:silver-scribe:1772591179460