Updated memory-system reference with anchor IDs, full injection playbook, and promotion/ratification rules.

TASK CONTEXT
- Bead ID: beadboard-maf.2
- Parent/Epic: beadboard-maf
- Dependencies: None (parallelizable with maf.1, maf.3-maf.5)

TASK CONTRACT
- Goal: Update memory-system.md to add missing operational guidance: domain anchor IDs, WHEN-to-query trigger, and the full injection playbook from help/memory/query_and_injection.txt.
- Success Criteria:
  - Domain anchor IDs added: beadboard-76p (Arch), beadboard-nq9 (Workflow), beadboard-5r1 (Agent Ops), beadboard-fld (UI/UX), beadboard-8st (Reliability)
  - WHEN-to-query trigger added: at session start, before claiming work, when entering a new domain
  - Full injection playbook included (Steps 1-7 from query_and_injection.txt): domain selection, bd query, provenance check, attach via dep relate, contract bead for hard rules, record acknowledgement, preserve provenance in notes
  - 'Ratify by closing' clarified: closed decision bead = active canonical memory
  - Noise budget promotion policy added: incident repeats 2+ times = soft candidate, survives release window = hard candidate
- Scope:
  - skills/beadboard-driver/references/memory-system.md rewrite/expansion
- Out of Scope:
  - Changes to bd itself
  - New canonical memory creation

IMPLEMENTATION CONSTRAINTS
- Source of truth for injection playbook: help/memory/query_and_injection.txt in beadboard repo
- Source of truth for schema: help/memory/schema_and_noise_budget.txt

VERIFICATION REQUIREMENTS
- Required commands: None (doc task)
- Required artifacts: updated skills/beadboard-driver/references/memory-system.md

Rewrote skills/beadboard-driver/references/memory-system.md with v5 memory protocol. Added required domain anchor IDs (beadboard-76p, beadboard-nq9, beadboard-5r1, beadboard-fld, beadboard-8st), WHEN-to-query triggers (session start / pre-claim / domain shift), full 7-step injection playbook from help/memory/query_and_injection.txt, ratification clarification (closed decision bead = active canonical memory), and noise-budget promotion policy (repeat incidents -> soft candidate; release-surviving workaround -> hard/soft). Verification artifact: updated memory-system.md in skills path. Memory review: no new reusable memory.

v5: memory system reference update


Replaced placeholder swarm guidance with real bd swarm/mol command workflows and role contracts.

TASK CONTEXT
- Bead ID: beadboard-maf.3
- Parent/Epic: beadboard-maf
- Dependencies: None (parallelizable with maf.1, maf.2, maf.4, maf.5)

TASK CONTRACT
- Goal: Rewrite archetypes-templates-swarms.md replacing vague 'use your environment swarm commands' with real bd swarm and bd mol commands, and adding template discovery so agents know what swarm they're in.
- Success Criteria:
  - bd swarm create <epic-id>, bd swarm status, bd swarm list, bd swarm validate documented with examples
  - bd mol show <proto-id> documented: how agents discover the template/proto their swarm was instantiated from
  - Archetype contracts expanded: coder/reviewer/writer each get quality gates, handoff payload format, escalation triggers
  - Swarm join flow for worker agents documented (not just orchestrators)
  - Swarm closure ownership defined: who closes and when
  - Command surface section replaced with real commands (no more 'expected operations' placeholder)
- Scope:
  - skills/beadboard-driver/references/archetypes-templates-swarms.md rewrite
  - bd swarm subcommands
  - bd mol show (template discovery)
- Out of Scope:
  - bd mol pour/wisp/bond (molecule instantiation is user/orchestrator territory)
  - BeadBoard UI swarm views

IMPLEMENTATION CONSTRAINTS
- Source of truth for bd swarm: run bd swarm --help and bd swarm create --help in beadboard/
- No invented commands — only document commands verified to exist

VERIFICATION REQUIREMENTS
- Required commands: None (doc task)
- Required artifacts: updated skills/beadboard-driver/references/archetypes-templates-swarms.md

Rewrote skills/beadboard-driver/references/archetypes-templates-swarms.md with verified command surface from bd swarm and bd mol. Added concrete commands/examples for create/status/list/validate and mol show --parallel, expanded coder/reviewer/writer archetype contracts (quality gates, handoff payloads, escalation triggers), documented worker join flow, and clarified swarm closure ownership/checklist. Removed placeholder command language in favor of real commands only. Verification artifact: updated archetypes-templates-swarms.md in skills path.

v5: swarm system reference rewrite


Expanded session lifecycle into a complete command-backed runbook with correct claim/dependency/blocked flow.

TASK CONTEXT
- Bead ID: beadboard-maf.4
- Parent/Epic: beadboard-maf
- Dependencies: None (parallelizable with maf.1, maf.2, maf.3, maf.5)

TASK CONTRACT
- Goal: Expand session-lifecycle.md to cover the BLOCKED path, bd dep workflow, epic/parent bead guidance, and fix the --claim vs --assignee inconsistency.
- Success Criteria:
  - --claim replaced everywhere with --assignee <agent-bead-id> (the correct flag)
  - BLOCKED path documented: bd agent state <id> stuck + bb mail send BLOCKED + what to do while waiting
  - bd dep add and bd dep relate documented with when-to-use guidance
  - Epic/parent bead guidance: bd show <epic-id> before claiming child tasks, bd children <epic-id> to see sibling work
  - Memory review step has substance: exact decision rule for when to create vs skip canonical memory
  - Session start now includes: create agent bead, set state spawning, attach hook slot, query hard memory
- Scope:
  - skills/beadboard-driver/references/session-lifecycle.md rewrite
  - bd dep subcommands (add, relate, list, tree)
- Out of Scope:
  - Communication protocol details (covered in maf.6)

IMPLEMENTATION CONSTRAINTS
- --assignee requires an agent bead to exist first — document this ordering explicitly
- BLOCKED path must reference bd agent state stuck (not just mail events)

VERIFICATION REQUIREMENTS
- Required commands: None (doc task)
- Required artifacts: updated skills/beadboard-driver/references/session-lifecycle.md

Rewrote skills/beadboard-driver/references/session-lifecycle.md. Replaced deprecated --claim usage with correct --assignee ordering, added explicit session-start sequencing (agent bead creation, state spawning/running, hard-memory query), added epic/children read step, documented bd dep add/relate/list/tree with when-to-use guidance, expanded mandatory BLOCKED path (state stuck + BLOCKED mail + heartbeat + resume), and added concrete memory-review decision rule (create/supersede vs skip). Verification artifact: updated session-lifecycle.md in skills path.

v5: bead lifecycle + dep workflow expansion


Platform-specific bb discovery now works on Linux/WSL and Windows-compatible entrypoints remain supported.

TASK CONTEXT
- Bead ID: beadboard-maf.5
- Parent/Epic: beadboard-maf
- Dependencies: None (parallelizable with maf.1-maf.4)

TASK CONTRACT
- Goal: Fix driver-lib.mjs discoverBbPath() which only searches for bb.ps1, causing BB_NOT_FOUND on all Linux/WSL agents even when bb is in PATH.
- Success Criteria:
  - discoverBbPath() finds bb binary on Linux/WSL via PATH or known install locations
  - Windows bb.ps1 discovery still works (no regression)
  - session-preflight.contract.test.mjs passes on Linux (currently platform-assumption failure)
  - resolve-bb.contract.test.mjs passes on Linux
  - npm run typecheck, lint, test all pass
- Scope:
  - scripts/lib/driver-lib.mjs: discoverBbPath() and validateRepoPath() functions
  - Platform-branching: Windows checks bb.ps1, Linux/Mac checks bb binary in PATH and npm global
  - Contract test updates for cross-platform assumptions
- Out of Scope:
  - Windows path handling changes
  - bb mail configuration (maf.5 in izs)

IMPLEMENTATION CONSTRAINTS
- Do not break existing Windows discovery logic
- On Linux, check: PATH entries for 'bb', npm global bin, ~/.npm-global/bin/bb

VERIFICATION REQUIREMENTS
- Required commands: npm run typecheck, npm run lint, npm run test
- Required artifacts: updated driver-lib.mjs, updated contract tests

Implemented Linux/WSL discovery fix in skills/beadboard-driver/scripts/lib/driver-lib.mjs: (1) validateRepoPath now accepts bb.ps1 or bin/beadboard.js with platform-aware candidate order; (2) discoverBbPath now checks PATH via findCommandInPath('bb') before BFS; (3) BFS now searches both bb.ps1 and bin/beadboard.js cross-platform. Verification (2026-03-04): npm run typecheck -> pass; npm run lint -> pass (21 pre-existing warnings, 0 errors); npm run test -> pass.

v5: script platform fix (Linux/WSL bb discovery)


Coordination events/session/ack reference now matches live bb agent and bd mail delegate behavior, including end-to-end blocked recovery flow.

## TASK CONTEXT
- Bead ID: beadboard-maf.6
- Parent/Epic: beadboard-maf
- Dependencies: beadboard-izs (bb mail epic must be fully complete — commands finalized and reference doc written in izs.7)

coord-events-sessions-ack.md currently documents deprecated command signatures. The coordination system is fully implemented in tools/bb.ts (bb agent send/inbox/read/ack/register/reserve/release/status), backed by src/lib/agent-mail.ts, agent-registry.ts, agent-reservations.ts. izs.7 produces the canonical reference doc — this task rewrites the skill reference using it.

## TASK CONTRACT
**Goal**: Rewrite coord-events-sessions-ack.md (or replace with coordination-system.md from izs.7) with accurate bb agent command surface, WHEN-to-use triggers, and a worked BLOCKED flow example.

**Success Criteria**:
- Uses bb agent send/inbox/read/ack with correct flags (not speculative — verified against tools/bb.ts)
- WHEN-to-use trigger map: condition that triggers each category (HANDOFF, BLOCKED, DECISION, INFO)
- Inbox polling protocol: when agents check inbox (session start, before claiming task, on state=stuck)
- Full BLOCKED walkthrough: agent sends bb agent send --category BLOCKED → bd agent state stuck → user sees in BeadBoard UI → user intervenes → agent resumes
- ACK escalation path documented for requires_ack=true messages
- bd mail delegate documented as the alternative invocation path (bd mail → bb agent)
- Reservation conflict protocol: active blocks, stale warns with --takeover-stale
- Zero references to phantom or deprecated API surfaces
- Must read izs.7 coordination-system.md FIRST — do not invent command syntax

**Scope**:
- .agents/skills/beadboard-driver/references/coord-events-sessions-ack.md rewrite
- May link to or embed content from coordination-system.md (izs.7)

**Out of Scope**:
- SKILL.md update (maf.10)
- Other reference docs

## IMPLEMENTATION CONSTRAINTS
- Read izs.7 output (coordination-system.md) before writing anything
- Verify all command examples compile against actual tools/bb.ts command surface

## VERIFICATION REQUIREMENTS
- All command examples match actual bb agent flags
- WHEN-to-use map covers at least 6 trigger scenarios
- Worked BLOCKED flow is end-to-end complete

Rewrote skills/beadboard-driver/references/coord-events-sessions-ack.md against canonical izs.7 coordination-system.md and verified bb command surface in tools/bb.ts. Updated categories to HANDOFF/BLOCKED/DECISION/INFO only; added explicit ack semantics, inbox polling protocol, 7-scenario WHEN-to-use trigger map, complete BLOCKED -> bd agent state stuck -> user intervention -> ack -> running flow, bd mail delegate mapping, and reservation conflict/takeover-stale policy. Removed deprecated/phantom command and category references.

v5: comm system rewrite (coord-events-sessions-ack.md)


Command matrix and failure modes now reflect the current delegated coordination surface and verified CLI flags.

TASK CONTEXT
- Bead ID: beadboard-maf.7
- Parent/Epic: beadboard-maf
- Dependencies: beadboard-maf.6 (comm system must be rewritten so command matrix reflects real surface)

TASK CONTRACT
- Goal: Rewrite command-matrix.md and failure-modes.md to remove all dead bb agent commands and add the full live command surface.
- Success Criteria:
  - command-matrix.md: zero bb agent commands; full surface: bd agent state/heartbeat, bd swarm, bb mail, bd slot, bd gate, bd mol, bd dep, bd comments
  - failure-modes.md: reservoir/reservation errors removed; new entries: bb mail not configured (error_code + remediation), Dolt not running, bd agent heartbeat missed (Witness marks dead), bd mail delegate not set
  - All commands in matrix verified to exist (no invented flags)
- Scope:
  - skills/beadboard-driver/references/command-matrix.md full rewrite
  - skills/beadboard-driver/references/failure-modes.md update
- Out of Scope:
  - New command implementations

IMPLEMENTATION CONSTRAINTS
- Cross-reference against bd --help and bb --help output before writing
- Every command in the matrix must include the real flag names (not paraphrases)

VERIFICATION REQUIREMENTS
- Required commands: None (doc task)
- Required artifacts: updated command-matrix.md, updated failure-modes.md

Rewrote skills/beadboard-driver/references/command-matrix.md and failure-modes.md against live CLI help output (bd agent/swarm/slot/gate/mol/dep/comments/mail plus bb-backed delegate behavior). Removed old/dead direct command patterns (including --claim and direct bb agent workflow commands), corrected swarm create flags to documented --coordinator/--force surface, and added failure coverage for MAIL_DELEGATE_MISSING, BB_MAIL_NOT_CONFIGURED, DOLT_NOT_RUNNING, and AGENT_HEARTBEAT_MISSED.

v5: command matrix + failure modes rewrite


Skill/repo tests now cover cross-platform bb discovery and full bb-mail lifecycle with passing gates.

TASK CONTEXT
- Bead ID: beadboard-maf.8
- Parent/Epic: beadboard-maf
- Dependencies: beadboard-maf.5 (script fix), beadboard-maf.6 (comm system — tests must match new commands)

TASK CONTRACT
- Goal: Update skill-local and repo-level tests so they pass on Linux/WSL and cover the new bb mail integration.
- Success Criteria:
  - session-preflight.contract.test.mjs: remove Windows-only assumptions, pass on Linux
  - resolve-bb.contract.test.mjs: Linux bb binary discovery tested
  - bb-mail integration test: full send->inbox->read->ack lifecycle in isolated tmpdir
  - ensure-bb-mail-configured.mjs contract test: missing delegate detected and remediation shown
  - All tests registered in run-tests.mjs and package.json
  - npm run typecheck, lint, test all pass
- Scope:
  - skills/beadboard-driver/tests/*.contract.test.mjs updates
  - tests/skills/beadboard-driver/*.test.ts updates
  - package.json test registration
- Out of Scope:
  - Windows CI (follow-up epic)

IMPLEMENTATION CONSTRAINTS
- No mocking of bd — use real bd in tmpdir
- New test files must be added to package.json test script (explicitly enumerated)

VERIFICATION REQUIREMENTS
- Required commands: npm run typecheck, npm run lint, npm run test
- Required artifacts: all updated test files, updated package.json

Updated skill and repo tests for Linux/WSL and bb-mail lifecycle coverage. Changes: (1) Added platform-aware entrypoint fixtures to resolve-bb/session-preflight tests (bin/beadboard.js on POSIX, bb.ps1 on Windows). (2) Added ensure-bb-mail-configured script and both contract + TS tests. (3) Added bb-mail integration contract test covering send->inbox->read->ack with isolated HOME/USERPROFILE temp storage and bb PATH proxy. (4) Registered new contract tests in skills/beadboard-driver/tests/run-tests.mjs and package.json test script. (5) Fixed message-id generation in src/lib/agent-mail.ts to remove '.' and keep ids validator-safe for read/ack flow. Verification (2026-03-04): npm run typecheck -> pass; npm run lint -> pass (21 pre-existing warnings, 0 errors); npm run test -> pass (includes new contract tests).

v5: tests update


project.template.md now captures mail delegate, heartbeat, swarm defaults, and project.md environment handoff requirements.

TASK CONTEXT
- Bead ID: beadboard-maf.9
- Parent/Epic: beadboard-maf
- Dependencies: beadboard-maf.6 (bb mail commands must be finalized)

TASK CONTRACT
- Goal: Update project.template.md to include bb mail configuration, agent heartbeat policy, and swarm template field so agents filling it out get complete env-specific guidance.
- Success Criteria:
  - bb mail configuration section added: bd config set mail.delegate 'bb mail', BD_ACTOR env var
  - Agent heartbeat policy field added: how often to heartbeat in this project
  - Swarm template field added: which bd mol proto this project uses (if any)
  - Validation step noted: ensure-bb-mail-configured.mjs and session-preflight.mjs should both pass before work
  - Blank template still has useful prompts for each field (not just empty lines)
- Scope:
  - skills/beadboard-driver/project.template.md update
- Out of Scope:
  - Creating actual project.md for any specific project

IMPLEMENTATION CONSTRAINTS
- Keep the template fillable by a human or agent in one sitting
- Do not add so many fields that it becomes a burden to complete

VERIFICATION REQUIREMENTS
- Required commands: None (doc task)
- Required artifacts: updated skills/beadboard-driver/project.template.md

Updated skills/beadboard-driver/project.template.md to include v5 coordination requirements: global install checks for bd + bb/beadboard, explicit project.md lifecycle (first agent creates, later agents read/update), bb mail delegate setup command, BB_AGENT/BD_ACTOR policy, required validation scripts (session-preflight + ensure-bb-mail-configured), agent heartbeat cadence field, swarm/proto defaults, and closeout requirement to refresh project.md with new env facts.

v5: project.template.md update


Given a multi-param URL update, when the code is reviewed, then it must use a single buildUrlParams then router.push call, not sequential setX() calls.

Scope: Any code that updates multiple URL search params (view, taskId, assignMode, graphTab, etc.) in sequence. Out of Scope: Single-param updates. Rule: Never call multiple sequential setX() functions that each rebuild the URL from the same stale searchParams snapshot. Instead, use a single buildUrlParams() call to construct all params atomically, then one router.push(). Rationale: Each setX() reads the current searchParams at call time; if two run in the same tick, the second overwrites the first changes. Failure Mode: Params silently dropped, e.g. view changes but taskId reverts to previous value.

[MEMORY][ARCH][HARD] Atomic URL param updates to avoid stale closure races


TASK CONTEXT\n- Goal: make status backend diagnostics explicit and unambiguous.\n\nTASK CONTRACT\n- Success Criteria:\n  - status text distinguishes sqlite legacy/migrated and dolt backend presence\n  - status json includes structured backend diagnostics\n- Scope:\n  - install/beadboard.mjs status payload + rendering\n  - status tests updates\n- Out of Scope:\n  - backend migration logic changes\n\nVERIFICATION REQUIREMENTS\n- npm run typecheck\n- npm run lint\n- npm run test

[EPIC] Status Backend Clarity


Completed backend-aware status diagnostics and verification gates

TASK CONTEXT\n- Parent/Epic: beadboard-mmd\n\nTASK CONTRACT\n- Goal: replace ambiguous '.beads DB' status with backend-aware diagnostics.\n- Success Criteria:\n  - text status shows sqlite legacy file, sqlite migrated file, dolt repo presence\n  - json status includes backend diagnostics object\n  - tests validate new fields/labels\n- Scope:\n  - install/beadboard.mjs\n  - tests/scripts/beadboard-launcher-runtime.test.ts\n  - tests/scripts/beadboard-launcher-status-text.test.ts\n- Out of Scope:\n  - altering bd storage implementation\n\nVERIFICATION REQUIREMENTS\n- node --import tsx --test tests/scripts/beadboard-launcher-runtime.test.ts\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

Implemented backend-aware status diagnostics:
- Added bd.backend JSON object: sqliteLegacyDb/sqliteMigratedDb/doltRepo
- Replaced ambiguous text line `.beads DB` with `SQLite Legacy DB`, `SQLite Migrated DB`, and `Dolt Repo`
- Updated launcher runtime/status text tests for new fields and labels

Verification evidence (2026-03-03):
- node --import tsx --test tests/scripts/beadboard-launcher-runtime.test.ts (pass)
- node --import tsx --test tests/scripts/beadboard-launcher-status-text.test.ts (pass)
- npm run typecheck (pass)
- npm run lint (pass: 0 errors, 22 warnings)
- npm run test (pass)

Memory review: no new reusable memory.

Clarify backend diagnostics in status output


TASK CONTEXT
- Parent: None (top-level epic)
- Dependencies: None yet

TASK CONTRACT
- Goal: Establish verification confidence through tests and performance baselines
- Success Criteria:
  - Tests pass before any feature is closed
  - Performance baselines documented
- Scope:
  - Unit tests for core libs
  - API integration tests
  - Performance baselines
  - Verification gates
- Out of Scope:
  - Feature implementation

IMPLEMENTATION CONSTRAINTS
- Tests in tests/ directory
- Follow TDD workflow

VERIFICATION REQUIREMENTS
- Required commands: npm run typecheck, npm run lint, npm run test

[EPIC] Quality Gates and Testing


TASK CONTEXT
- Bead ID: beadboard-n1h.1
- Parent: beadboard-n1h
- Dependencies: None

TASK CONTRACT
- Goal: Implement unit tests for core libraries
- Success Criteria:
  - Parser tests pass
  - Pathing tests pass
  - Scanner tests pass
- Scope:
  - src/lib/parser.ts
  - src/lib/pathing.ts
  - src/lib/scanner.ts
- Out of Scope:
  - Integration tests

VERIFICATION REQUIREMENTS
- Required commands: npm run typecheck, npm run lint, npm run test

Unit Tests: Core Libraries


TASK CONTEXT
- Bead ID: beadboard-n1h.2
- Parent: beadboard-n1h
- Dependencies: None

TASK CONTRACT
- Goal: Implement API integration tests
- Success Criteria:
  - Read route tests pass
  - Mutate route tests pass
  - SSE route tests pass
- Scope:
  - /api/beads/read
  - /api/beads/create, update, close
  - /api/events (SSE)
- Out of Scope:
  - Unit tests

VERIFICATION REQUIREMENTS
- Required commands: npm run typecheck, npm run lint, npm run test

API Integration Tests


TASK CONTEXT
- Bead ID: beadboard-n1h.3
- Parent: beadboard-n1h
- Dependencies: None

TASK CONTRACT
- Goal: Record performance baselines
- Success Criteria:
  - Parser baseline captured
  - Realtime baseline captured
- Scope:
  - Parser performance
  - SSE/realtime performance
- Out of Scope:
  - Full optimization

VERIFICATION REQUIREMENTS
- Required commands: npm run typecheck, npm run lint

Performance Baselines


Canonical workflow memories are related to this anchor via bd dep relate.

Domain anchor for execution process constraints, verification gates, and delivery discipline.

[MEMORY-ANCHOR] Workflow Protocol


TASK CONTEXT\n- Parent: beadboard-c70 / beadboard-05a\n\nTASK CONTRACT\n- Goal: Implement Linux/mac installer wrapper using canonical manifest and register bb/beadboard commands.\n- Success Criteria:\n  - curl/bash compatible install.sh\n  - bb and beadboard commands available globally\n- Scope: POSIX install path + PATH guidance\n- Out of Scope: Windows-specific behavior\n\nVERIFICATION REQUIREMENTS\n- npm run typecheck\n- npm run lint\n- npm run test

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

Linux/mac wrapper: install.sh + global command shims


Test Bead 2 - SSE Check


Ratified canonical reliability memory for stale-state parity triage order.

Scope: Realtime/stale-state incidents where UI contradicts expected issue state.\nOut of Scope: Pure styling bugs with no state mismatch.\nRule: Triage must confirm parity in this order: bd record, SQL row, API payload, UI render state, then SSE health.\nRationale: Fixes made before parity checks target symptoms and miss the true mismatch layer.\nFailure Mode: Repeated 'fixed but still visible' loops with no durable resolution.

Canonicalized for stale-state triage discipline using parity sequence (bd->SQL->API->UI->SSE). Provenance: beadboard-x1y, beadboard-4k8, beadboard-cc8. Linked to reliability anchor beadboard-8st and workflow chain beadboard-x6f.

[MEMORY][RELIABILITY][HARD] For stale UI reports, verify bd->SQL->API->UI parity in order


# 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

Installer test matrix + CI smoke coverage


project.md is now session state cache; all 3 gaps fixed; returning agents skip checks entirely when all green

Scope: project.template.md revamp + SKILL.md flow changes + gap fixes 1-3.\n\nproject.md becomes the token-saving session cache. Agent reads it first. If all checks are green, skip straight to Step 2 (claim work). Only re-run a check if project.md says it failed, or agent hits an actual error.\n\nproject.template.md changes:\n- Add 'Environment Status Cache' table at top with fields: bd, bb, mail.delegate, preflight, bb_agent_policy, tests — each with status (pass/fail/unknown) + date + notes\n- Rule: if all rows = pass, agent skips Step 1 entirely\n\nSKILL.md changes:\n- Step 0 EXISTS branch: read project.md status table. If all green -> skip to Step 2. If any red/unknown -> run only that check.\n- Gap 1: add bd init check to bootstrap (check .beads exists first)\n- Gap 2: move ensure-bb-mail-configured.mjs to end of Step 2 (after export BB_AGENT), remove from Step 0D and Step 1\n- Gap 3: step-preflight is idempotent, keep as-is but Step 1 is now conditional (skip if project.md all green)\n- Step 8: add 'update project.md status cache' as mandatory close action\n\nSuccess Criteria: new agent reads project.md, sees all green, goes straight to bd ready + claiming work. No unnecessary checks.

project.template.md: full revamp with Environment Status Cache table at top (bd, bb, .beads, mail.delegate, preflight, bb_agent, tests), status values pass/fail/unknown, rule to skip Step 1 if all green, Session Log append pattern. SKILL.md: Step 0 now cache-first (EXISTS=read table, all green=skip to Step 2; MISSING=bootstrap); Bootstrap has bd init check (Gap 1 fixed); Step 1 is now conditional lookup table; Step 2 has ensure-bb-mail-configured AFTER export BB_AGENT (Gap 2 fixed); Step 3 simplified to 'only update if changed'; Step 8 adds project.md cache update. Test updated for new template header. Tests: 14/14 pass.

project.md as session state cache + gap fixes


## 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


TASK CONTEXT
- Bead ID: beadboard-v5a
- Title: [EPIC] BeadBoard Driver v5: Holistic Validation and Critique
- Parent/Epic: none
- Dependencies (must be done first): beadboard-maf

TASK CONTRACT
- Goal: Run a full validation + critique pass on the completed beadboard-driver v5 skill and produce evidence-backed remediation beads.
- Success Criteria:
  - All validation beads (v5a.1-v5a.15) completed with evidence.
  - Single consolidated audit report committed to docs/reviews.
  - Remediation bead set created with correct dependency order.
  - Go/no-go verdict and next-session handoff updated.
- Scope:
  - skills/beadboard-driver docs, scripts, tests, and related UI/coordination behavior.
  - Audit evidence generation, critique synthesis, and remediation planning.
- Out of Scope:
  - Large feature implementation unrelated to audit findings.
  - New architecture work without first recording critique findings.

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
- Required artifacts:
  - docs/reviews/YYYY-MM-DD-beadboard-driver-v5-audit.md
  - Linked follow-up beads for accepted remediation work.
- Report any remaining risks and follow-up beads explicitly.


TASK CONTEXT
- Bead ID: beadboard-v5a.1
- Title: v5 audit baseline verification run
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-maf

TASK CONTRACT
- Goal: Establish fresh baseline by running core repo gates before critique begins.
- Success Criteria:
  - typecheck/lint/test executed in current session.\n  - Exact pass/fail/warning state recorded in bead notes.\n  - Any failing gate includes immediate triage note and blocker linkage.
- Scope:
  - Run and capture npm run typecheck, npm run lint, npm run test.\n  - Record key failing files/tests if present.
- Out of Scope:
  - Fixing all discovered failures in this bead.\n  - Documentation rewrite beyond recording baseline evidence.

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.

v5 audit baseline verification run


TASK CONTEXT
- Bead ID: beadboard-v5a.10
- Title: frontend visual validation gate (manual)
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-v5a.1

TASK CONTRACT
- Goal: Run manual visual checks for frontend coordination surfaces and require explicit user confirmation evidence.
- Success Criteria:
  - Social/Activity/Graph views checked for coordination data visibility and correctness.\n  - Screenshots captured for key states (blocked, ack/read, assignee/liveness where shown).\n  - Human confirmation note recorded in bead comments/notes.
- Scope:
  - Manual UI validation flow for communication-related surfaces.\n  - Screenshot artifact capture and checklist completion.
- Out of Scope:
  - Pixel-perfect redesign work.\n  - Non-audit feature development.

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.


TASK CONTEXT
- Bead ID: beadboard-v5a.11
- Title: communication system holistic audit
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-v5a.1, beadboard-v5a.2, beadboard-v5a.10

TASK CONTRACT
- Goal: Audit communication flow end-to-end across CLI/API/UI semantics and required-ack behavior.
- Success Criteria:
  - send->inbox->read->ack lifecycle verified against docs and tests.\n  - requires_ack behavior validated for HANDOFF/BLOCKED.\n  - Delegate path (bd mail -> bb shim) parity checked against direct surface expectations.
- Scope:
  - Inspect command/API contracts and observed outputs.\n  - Verify documentation parity with actual behavior.
- Out of Scope:
  - Full backend redesign.\n  - Unrelated UI feature expansion.

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.

communication system holistic audit


TASK CONTEXT
- Bead ID: beadboard-v5a.12
- Title: memory system audit
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-v5a.1

TASK CONTRACT
- Goal: Critique memory-system guidance for anchor correctness, injection clarity, and noise-budget compliance.
- Success Criteria:
  - Domain anchor references validated against real bead IDs.\n  - Injection playbook assessed for cold-agent usability.\n  - Canonical memory creation/supersede guidance checked for correctness.
- Scope:
  - Validate references/memory-system.md against current workflow docs/help files.\n  - Identify ambiguity that can cause memory misuse/noise.
- Out of Scope:
  - Creating many new memory beads as part of audit pass.\n  - General docs cleanup outside memory domain.

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.

memory system audit


TASK CONTEXT
- Bead ID: beadboard-v5a.13
- Title: agent lifecycle and liveness audit
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-v5a.1

TASK CONTRACT
- Goal: Audit agent state/liveness docs and behavior for heartbeat, stale/dead semantics, and operational clarity.
- Success Criteria:
  - State transition guidance validated against bd agent command behavior.\n  - Heartbeat cadence recommendations checked for realism and consistency.\n  - Dead/stale handling gaps and escalation ambiguity documented.
- Scope:
  - Review agent-state-liveness.md and relevant command help/contracts.\n  - Verify state names and semantics are aligned.
- Out of Scope:
  - Reworking unrelated coordination docs.\n  - UI redesign beyond validation artifacts.

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.

agent lifecycle and liveness audit


TASK CONTEXT
- Bead ID: beadboard-v5a.14
- Title: swarm and molecule workflow audit
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-v5a.1

TASK CONTRACT
- Goal: Audit swarm/molecule guidance for execution correctness, command accuracy, and operator mental model clarity.
- Success Criteria:
  - bd swarm and bd mol command references verified against help output.\n  - Parallelization guidance checked against dependency correctness.\n  - Common failure/confusion paths documented with remediations.
- Scope:
  - Review archetypes-templates-swarms.md and command-matrix entries.\n  - Validate examples for realistic usage.
- Out of Scope:
  - Creating new swarm features.\n  - Memory/docs domains outside swarm workflow.

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.

swarm and molecule workflow audit


TASK CONTEXT
- Bead ID: beadboard-v5a.15
- Title: cold-agent usability audit
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-v5a.3, beadboard-v5a.4, beadboard-v5a.10

TASK CONTRACT
- Goal: Evaluate whether a brand-new agent can execute the skill with zero tribal knowledge.
- Success Criteria:
  - At least one cold-start simulation walkthrough completed.\n  - Ambiguity points ranked by execution risk.\n  - Recommendations prioritize reducing guesswork and cognitive load.
- Scope:
  - End-user readability and actionability critique across runbook/docs.\n  - Tie critique directly to concrete lines/sections.
- Out of Scope:
  - Deep architecture changes.\n  - Large feature implementation work.

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.

cold-agent usability audit


TASK CONTEXT
- Bead ID: beadboard-v5a.2
- Title: v5 skill-local contract suite execution
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-maf

TASK CONTRACT
- Goal: Validate skill-local contract behavior independent from the full repo test suite.
- Success Criteria:
  - node skills/beadboard-driver/tests/run-tests.mjs executed successfully.\n  - Contract-level failures (if any) categorized by domain (mail/preflight/resolve/etc).\n  - Evidence includes command output and failing test identifiers.
- Scope:
  - Execute skill-local runner and capture output.\n  - Map failures to owning script/doc contract.
- Out of Scope:
  - Broad remediation implementation.\n  - UI/manual validation work.

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.

v5 skill-local contract suite execution


TASK CONTEXT
- Bead ID: beadboard-v5a.3
- Title: SKILL.md runbook dry-run and command accuracy audit
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-v5a.1

TASK CONTRACT
- Goal: Dry-run the v5 SKILL.md exactly as written to verify command-level executability and no guessing gaps.
- Success Criteria:
  - Every runbook step classified as executable / ambiguous / incorrect.\n  - Deprecated surfaces or inaccurate flags enumerated with file references.\n  - Required install assumptions (bd + bb global) explicitly validated.
- Scope:
  - Walk SKILL.md step-by-step with real commands where safe.\n  - Capture mismatches between documented and actual behavior.
- Out of Scope:
  - Full remediation implementation.\n  - Deep cross-doc consistency analysis (handled in v5a.4).

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.


TASK CONTEXT
- Bead ID: beadboard-v5a.4
- Title: reference documentation consistency audit
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-v5a.1

TASK CONTRACT
- Goal: Audit all v5 reference docs for contradiction, drift, and missing operator-critical details.
- Success Criteria:
  - Cross-reference matrix produced for SKILL.md, references/*.md, project.template.md.\n  - Contradictions and duplicate/conflicting guidance documented.\n  - Findings include exact file paths/sections and proposed fix direction.
- Scope:
  - Analyze references under skills/beadboard-driver/references and project.template.md.\n  - Validate terminology and command-surface consistency.
- Out of Scope:
  - Running runtime failure drills.\n  - Writing final synthesis report (handled in v5a.7).

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.


TASK CONTEXT
- Bead ID: beadboard-v5a.5
- Title: test coverage gap audit for v5 skill
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-v5a.1, beadboard-v5a.2

TASK CONTRACT
- Goal: Identify meaningful untested behavior across scripts, docs contracts, and coordination flows.
- Success Criteria:
  - Coverage gap list prioritized by operational risk.\n  - Each gap mapped to candidate new/updated test file.\n  - False-positive gaps (already covered) are explicitly filtered out.
- Scope:
  - Review skills contract tests and tests/skills suite.\n  - Map required behaviors to existing test coverage.
- Out of Scope:
  - Implementing every missing test immediately.\n  - Non-skill unrelated test refactors.

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.

test coverage gap audit for v5 skill


TASK CONTEXT
- Bead ID: beadboard-v5a.6
- Title: failure-mode drill audit
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-v5a.1, beadboard-v5a.2

TASK CONTRACT
- Goal: Validate documented failure modes by running targeted drills and checking remediation quality.
- Success Criteria:
  - At least these drills assessed: delegate missing, bb missing, invalid/mismatch delegate, message id edge-case.\n  - Observed errors mapped against failure-modes.md entries.\n  - Missing/unclear remediation instructions identified.
- Scope:
  - Execute safe scripted drills and capture outputs.\n  - Compare observed behavior with docs claims.
- Out of Scope:
  - Full rewrite of failure docs beyond identified deltas.\n  - Broad feature 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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.

failure-mode drill audit


TASK CONTEXT
- Bead ID: beadboard-v5a.7
- Title: publish consolidated v5 audit report
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-v5a.3, beadboard-v5a.4, beadboard-v5a.5, beadboard-v5a.6, beadboard-v5a.10, beadboard-v5a.11, beadboard-v5a.12, beadboard-v5a.13, beadboard-v5a.14, beadboard-v5a.15

TASK CONTRACT
- Goal: Synthesize all audit findings into one evidence-backed report with severity and fix proposals.
- Success Criteria:
  - Report created at docs/reviews/YYYY-MM-DD-beadboard-driver-v5-audit.md.\n  - Findings grouped by severity with file references and command evidence.\n  - Every finding includes a concrete remediation proposal.
- Scope:
  - Write and commit consolidated audit report artifact.\n  - Ensure no major finding is omitted from source beads.
- Out of Scope:
  - Implementing all fixes in this synthesis bead.\n  - Final go/no-go decision publication (handled in v5a.9).

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.

publish consolidated v5 audit report


TASK CONTEXT
- Bead ID: beadboard-v5a.8
- Title: create remediation epic and bead graph
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-v5a.7

TASK CONTRACT
- Goal: Convert validated findings into a concrete remediation epic with correctly linked beads and execution order.
- Success Criteria:
  - New remediation epic + child beads created using bead prompting protocol.\n  - Dependencies model execution constraints (not visual order).\n  - Each remediation bead has measurable success criteria.
- Scope:
  - Bead creation, prompt-structured descriptions, dependency wiring.\n  - Prioritization by severity and blast radius.
- Out of Scope:
  - Performing all remediation implementation work.\n  - Closing audit with final go/no-go narrative (handled in v5a.9).

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.

create remediation epic and bead graph


TASK CONTEXT
- Bead ID: beadboard-v5a.9
- Title: go/no-go verdict and next-session handoff
- Parent/Epic: beadboard-v5a
- Dependencies (must be done first): beadboard-v5a.8

TASK CONTRACT
- Goal: Publish final readiness verdict and update NEXT_SESSION_PROMPT.md with exact next actions.
- Success Criteria:
  - Explicit verdict: ship-ready / conditionally-ready / not-ready with rationale.\n  - NEXT_SESSION_PROMPT.md updated to match remediation graph and priorities.\n  - Residual risks and owner expectations clearly documented.
- Scope:
  - Final decision write-up and session handoff update.\n  - Ensure handoff references audit report and remediation epic ids.
- Out of Scope:
  - Starting remediation implementation.\n  - Re-litigating already accepted findings.

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
- Required artifacts:
  - Evidence notes attached to this bead with exact commands and outputs.
  - Any requested screenshots/reports committed under docs/reviews.
- Report any remaining risks and follow-up beads explicitly.


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:maf8-recipient-1772602336486-77cc:1772602343524


pulse:maf8-recipient-1772605221538-e98f:1772605224897


pulse:maf8-recipient-1772602590511-8617:1772602599861


pulse:maf8-recipient-1772604568395-181a:1772604572634


pulse:maf8-sender-1772605221538-c382:1772605223361


pulse:maf8-recipient-1772604399694-3b18:1772604409020


pulse:maf8-recipient-1772594345463-5e30:1772594360649


pulse:maf8-recipient-1772604126900-0df6:1772604136199


pulse:maf8-sender-1772604568395-a777:1772604569982


pulse:maf8-sender-1772602408666-4c54:1772602412603


pulse:maf8-sender-1772605233998-56b0:1772605238399


pulse:maf8-recipient-1772602336486-77cc:1772602342360


pulse:maf8-recipient-1772603344712-1862:1772603348942


pulse:maf8-recipient-1772603344712-1862:1772603347709


pulse:maf8-recipient-1772602543590-2e77:1772602547725


pulse:maf8-recipient-1772595830876-a2bd:1772595843035


pulse:maf8-recipient-1772605258835-7419:1772605270341


pulse:maf8-recipient-1772594345463-5e30:1772594358748


pulse:maf8-recipient-1772604399694-3b18:1772604405332


pulse:maf8-sender-1772604535950-26bb:1772604537592


pulse:maf8-recipient-1772603406999-2bf7:1772603416157


pulse:maf8-recipient-1772602336486-77cc:1772602345847


pulse:maf8-recipient-1772604535950-4030:1772604541420


pulse:maf8-recipient-1772603406999-2bf7:1772603412462


pulse:maf8-recipient-1772604535950-4030:1772604538983


pulse:test-coord-izs2:1772590713612


pulse:maf8-recipient-1772603447464-07c5:1772603454149


pulse:maf8-sender-1772594142586-920f:1772594153763


pulse:maf8-recipient-1772602498124-349c:1772602507029


pulse:maf8-recipient-1772604414201-e81b:1772604418422


pulse:maf8-recipient-1772603406999-2bf7:1772603414974


pulse:maf8-sender-1772604399694-d676:1772604403847


pulse:maf8-sender-1772603344712-93c7:1772603346337


pulse:maf8-recipient-1772594345463-5e30:1772594356613


pulse:maf8-recipient-1772604535950-4030:1772604540190


pulse:maf8-sender-1772605258835-40c6:1772605266346


pulse:maf8-recipient-1772602590511-8617:1772602598638


pulse:maf8-sender-1772603406999-8469:1772603411091


pulse:maf8-recipient-1772594195923-64e9:1772594208703


pulse:maf8-recipient-1772604568395-181a:1772604575117


pulse:maf8-recipient-1772603406999-2bf7:1772603413681


pulse:maf8-recipient-1772594345463-5e30:1772594354573


pulse:maf8-recipient-1772604126900-0df6:1772604134923


pulse:maf8-recipient-1772604568395-181a:1772604573915


pulse:maf8-recipient-1772605258835-7419:1772605271573


pulse:maf8-recipient-1772603344712-1862:1772603351329


pulse:maf8-recipient-1772605258835-7419:1772605269064


pulse:maf8-recipient-1772595830876-a2bd:1772595840876


pulse:maf8-recipient-1772594167363-8d60:1772594178007


pulse:maf8-recipient-1772604126900-0df6:1772604133639


pulse:maf8-recipient-1772605233998-eb34:1772605241154


pulse:maf8-recipient-1772602498124-349c:1772602504668


pulse:maf8-recipient-1772594195923-64e9:1772594206787


pulse:maf8-sender-1772604414201-b833:1772604418269


pulse:maf8-sender-1772602498124-83bc:1772602502097


pulse:maf8-recipient-1772605221538-e98f:1772605228729


pulse:maf8-recipient-1772595830876-a2bd:1772595845187


pulse:maf8-recipient-1772602543590-2e77:1772602548900


pulse:maf8-recipient-1772604414201-e81b:1772604420786


pulse:maf8-recipient-1772605233998-eb34:1772605243654


pulse:maf8-sender-1772603447464-a701:1772603451537


pulse:maf8-recipient-1772603447464-07c5:1772603452929


pulse:maf8-recipient-1772602336486-77cc:1772602344707


pulse:maf8-recipient-1772605233998-eb34:1772605239885


pulse:maf8-recipient-1772594195923-64e9:1772594204897


pulse:silver-scribe:1772591154975


pulse:maf8-sender-1772594345463-989c:1772594352306


pulse:maf8-sender-1772602590511-758a:1772602594720


pulse:maf8-recipient-1772602408666-684a:1772602416347


pulse:maf8-recipient-1772602408666-684a:1772602413959


pulse:maf8-recipient-1772604535950-4030:1772604542620


pulse:maf8-recipient-1772604399694-3b18:1772604406605


pulse:silver-scribe:1772591174677


pulse:maf8-recipient-1772594167363-8d60:1772594176052


pulse:maf8-recipient-1772603447464-07c5:1772603456539


pulse:maf8-recipient-1772604126900-0df6:1772604132410


pulse:maf8-recipient-1772602408666-684a:1772602417502


pulse:maf8-sender-1772602336486-811e:1772602341005


pulse:maf8-recipient-1772603344712-1862:1772603350161


pulse:maf8-recipient-1772602498124-349c:1772602503486


pulse:maf8-recipient-1772604414201-e81b:1772604419643


pulse:maf8-recipient-1772603447464-07c5:1772603455356


pulse:maf8-recipient-1772594195923-64e9:1772594210682


pulse:maf8-recipient-1772604568395-181a:1772604571396


pulse:maf8-recipient-1772602408666-684a:1772602415146


pulse:maf8-sender-1772594195923-b170:1772594202541


pulse:maf8-recipient-1772605258835-7419:1772605267799


pulse:silver-scribe:1772591179460


pulse:maf8-recipient-1772605233998-eb34:1772605242430


pulse:maf8-sender-1772595830876-d567:1772595838320


pulse:maf8-recipient-1772604399694-3b18:1772604407826


pulse:maf8-recipient-1772605221538-e98f:1772605226223


pulse:maf8-recipient-1772602590511-8617:1772602596162


pulse:maf8-recipient-1772604414201-e81b:1772604419648


pulse:maf8-recipient-1772602543590-2e77:1772602546507


pulse:maf8-sender-1772604126900-011d:1772604131043


pulse:maf8-sender-1772602543590-06fb:1772602545115


pulse:maf8-recipient-1772602543590-2e77:1772602550063


pulse:maf8-recipient-1772602498124-349c:1772602505878


pulse:maf8-recipient-1772602590511-8617:1772602597392


pulse:maf8-sender-1772594167363-e2c2:1772594173805


pulse:maf8-recipient-1772595830876-a2bd:1772595847358


pulse:maf8-recipient-1772605221538-e98f:1772605227492