Templates can be applied to epics. BeadIssue gets templateId field. Template picker applies template to selected epic. Assignment panel shows template roster when epic selected.

Implemented epic-level template assignment. BeadIssue now has templateId field. Assignment panel shows Epic Template section when epic selected, with team roster. Template picker applies template to epic. Fixed all test files with new field.

Scope: Add templateId to BeadIssue type, update template picker to apply to epics, show template info in assignment panel. Out of scope: AI auto-assignment logic, multi-agent execution.

Added templateId to BeadIssue type. Updated assignment-panel with epic template section. Template picker now applies template to selected epic. All typecheck, lint, and tests pass.

Epic-Level Template Assignment


Wrong framing corrected — skill is for external repos, BB_REPO introduced for script paths

Scope: SKILL.md frontmatter + 'What is BeadBoard' section + script path references.\nOut of Scope: reference docs.\nProblem: ilu.2 incorrectly framed the skill as operating 'within the BeadBoard repository itself' and said scripts 'assume that path is available from the working directory.' Both are wrong — agents use this skill from their own project repos, not the BeadBoard repo. BB_REPO env var points to the BB install; scripts should use absolute paths.\nChanges needed:\n- frontmatter description: revert to non-BeadBoard-repo framing (skill is for agents in external repos)\n- 'What is BeadBoard' para: remove 'operates within the BeadBoard repository itself'\n- Step 1 script paths: add note that scripts must be referenced by absolute path via BB_REPO\nSuccess Criteria: cold agent reading the skill understands they are working in their own project, not the BeadBoard repo.

Fixed 3 wrong framings introduced by ilu.2: frontmatter now says 'any project repo'; What is BeadBoard now says 'agents almost never work inside the BeadBoard repo'; Step 1 scripts now use $BB_REPO absolute path with explanation. Tests: 12/12 pass.

Fix wrong framing: skill is for external repos not BeadBoard repo


Fixes PR 14 critical bugs

Agent: bb-pr14-bugfixer


Ratified canonical memory from user correction to preserve multi-agent scope discipline.

Scope: Sessions where multiple agents are active and the user clarifies ownership boundaries.\nOut of Scope: Single-agent sessions with no explicit ownership split.\nRule: If the user states a bead is owned by another agent, immediately stop work on that bead and continue only on the user-assigned scope.\nRationale: Prevents duplicate/conflicting work and keeps coordination clean.\nFailure Mode: Parallel agents overwrite each other or create handoff confusion.

Created from live user correction on 2026-03-02: scope for this agent is beadboard-05a; beadboard-txj is assigned elsewhere. Applied immediately by redirecting NEXT_SESSION_PROMPT work back to 05a.

[MEMORY][AGENT-OPS][SOFT] Respect user-assigned scope in multi-agent sessions


TASK CONTEXT
- Bead ID: beadboard-<epic>.x.x
- Title: [EPIC] BeadBoard Driver Skill: Creating Beads Guide
- Parent/Epic: none

task contract
- Goal: Create a comprehensive guide for creating and managing beads (epics, tasks, subtasks)
- Success criteria:
  - Agents understand bead naming format (beadboard-<epic>.x.x for tasks, beadboard-<epic>.x.x.x for subtasks)
  - Agents know how to set up dependencies using --parent and bd dep
  - Agents can write proper bead descriptions following bead-prompting standard
  - Agents know how to close beads with evidence and- Scope:
  - Creating new epics
  - Creating tasks under epics
  - Creating subtasks under tasks
  - Setting up dependencies
  - Writing descriptions
  - Closing beads

out of scope:
- Changing existing beads
- Bead naming format
- Other bead operations

label: skill:beadboard-driver,area:docs

[EPic] BeadBoard Driver Skill: Creating Beads Guide


When clicking Archetypes or Templates buttons, show a popup modal with list of existing items. User can select to use/edit or create new. Modal should have same styling as inspector modals.

Implemented popup modal pickers for Archetypes and Templates. Clicking the buttons now opens a modal with list of existing items, Select/Edit/Create options.

Created ArchetypePicker and TemplatePicker modal components. Updated assignment-panel.tsx to use picker modals instead of inline lists. Typecheck and lint pass.

Archetype/Template Picker Modal


6-8 built-in templates for common scenarios, each with optimized team composition, icons, colors, descriptions explaining when to use

Created 9 intelligent preset templates for common development workflows with optimized team compositions.

Create intelligently constructed preset templates based on the 6 archetypes for common development workflows

Created 9 intelligent preset templates: Feature Development, Bug Fix Squad, Code Review, Greenfield Project, Release Team, Investigation Team, Refactoring Team, Full Development Squad, Standard Application. Each has optimized team composition, workflow formula, color, and icon.

Intelligent Preset Templates


TASK CONTEXT\n- Bead ID: <to-be-assigned>\n- Parent/Epic: none\n- Dependencies: none\n\nTASK CONTRACT\n- Goal: Improve BeadBoard command ergonomics while keeping implementation minimal, maintainable, and operator-friendly.\n- Success Criteria:\n  - status output includes actionable runtime and bd diagnostics\n  - command behavior stays backward compatible\n  - tests cover new status contract\n- Scope:\n  - launcher/cli status output contract\n  - bd presence and local project visibility checks\n- Out of Scope:\n  - full command-surface redesign\n  - heavy runtime orchestration\n\nVERIFICATION REQUIREMENTS\n- Required commands:\n  - npm run typecheck\n  - npm run lint\n  - npm run test

[EPIC] CLI Status + BD Diagnostics


Implemented stable bd diagnostics in status --json with focused and full-gate verification evidence recorded.

TASK CONTEXT\n- Parent/Epic: beadboard-ass\n- Goal: Implement and validate stable bd diagnostics in beadboard status JSON.\n\nTASK CONTRACT\n- Success Criteria:\n  - status --json exposes bd availability/path/project fields\n  - status remains side-effect free\n  - regression test coverage included in package test script\n- Scope:\n  - install/beadboard.mjs status path\n  - tests/scripts/beadboard-launcher-runtime.test.ts and related routing tests\n- Out of Scope:\n  - new command suite beyond status contract\n\nVERIFICATION REQUIREMENTS\n- node --import tsx --test tests/scripts/beadboard-launcher-runtime.test.ts\n- npm run typecheck\n- npm run lint\n- npm run test

Verification evidence: status JSON now includes bd diagnostics (available/path/project). Commands run: node --import tsx --test tests/scripts/beadboard-launcher-runtime.test.ts (PASS), node --import tsx --test tests/scripts/beadboard-launcher.test.ts (PASS), node --import tsx --test tests/cli/beadboard-bin-routing.test.ts (PASS), npm run typecheck (PASS), npm run test (PASS), npm run lint (FAIL only known pre-existing .beads/fix.js and .beads/fix2.js errors, unchanged baseline). Files changed in this bead: install/beadboard.mjs, tests/scripts/beadboard-launcher-runtime.test.ts.

Implement bd diagnostics in status payload


Ratified from user correction: project scope is user-controlled in BeadBoard UI; agents operate within assigned repo context only.

Scope: Agent execution workflows in non-BeadBoard repos where BeadBoard is used as orchestration control plane.\nOut of Scope: User-driven UI project switching behavior implementation details.\nRule: Agents must not select or mutate project scope; they operate within the current repository context they are assigned. Project scope selection is exclusively a user action in the BeadBoard UI.\nRationale: Prevents scope drift and accidental cross-project coordination errors; keeps orchestration authority with the user.\nFailure Mode: If agents attempt to change scope, updates may appear in the wrong project context, breaking visibility and trust.

[MEMORY][AGENT][HARD] Agents do not select project scope; user controls scope in BeadBoard UI


Scope: DAG view for an epic must include nested descendant tasks and optionally render hierarchy links.\nOut of Scope: non-graph surfaces and non-epic filtering logic.\nSuccess Criteria: Nested subtasks under an epic are present in DAG data; hierarchy links can be toggled on/off in UI; tests updated with evidence.

[EPIC] Show Subtasks in DAG


All fixes implemented and tested. 14/14 tests passing. Conversation panel now opens on icon click, closes on second click, prioritizes task over epic, and back button navigates correctly.

## What was done

### Problem
Clicking the MessageSquare conversation icon on DAG nodes (WorkflowGraph / Dependencies tab) was not opening the ThreadDrawer in the right panel. The icon had been added but the panel never changed content.

### Root cause analysis
1. **Priority inversion in ContextualRightPanel**: The panel checked `epicId` BEFORE `taskId`. When the user had filtered the graph by an epic (setting `epicId` in URL), clicking the conversation icon would set `taskId` but `epicId` remained set — so SwarmCommandFeed rendered instead of ThreadDrawer.
2. **epicId not cleared on epic selection**: `setEpicId` did not clear `task` from the URL, so old taskId persisted across epic selections.
3. **Stale onSelect in flowModel**: WorkflowGraph's `flowModel` useMemo did not include `onSelect` in its dependency array, risking stale conversation callbacks.

### Fixes applied

**src/components/activity/contextual-right-panel.tsx**
- Reordered branches: `if (taskId)` now comes before `if (epicId)`
- Task conversation always takes priority over epic feed when a task is explicitly selected

**src/hooks/use-url-state.ts**
- `setEpicId` now clears `task` param: `updateUrl({ epic: id, task: null })`
- Clicking an epic in the left panel resets active task conversation, so SwarmCommandFeed correctly shows

**src/components/shared/workflow-graph.tsx**
- Added `onSelect` to `flowModel` useMemo dependency array
- Prevents stale conversation callbacks from being captured in node data

**src/components/shared/unified-shell.tsx**
- `handleGraphSelect` now toggles: clicking the same node a second time calls `setTaskId(null)`, closing the right panel
- Also bumped dep array to include `taskId`

### Earlier session changes (same epic, context compacted)
- Added MessageSquare icon to GraphNodeCard with proper prop-threading (no useUrlState inside ReactFlow nodes)
- WorkflowGraph threads `onConversationOpen` and `selectedTaskId` into node data
- Fixed ContextualRightPanel `onClose` no-ops → wired to `setTaskId(null)` / `setSwarmId(null)`
- UnifiedShell right panel is always visible (removed `panel === 'open'` gate)
- SmartDag task grid changed to horizontal scroll with fixed-width cards
- hideClosed defaults to true in SmartDag
- Added Suspense boundary in page.tsx for useSearchParams
- 14 static analysis tests in tests/components/graph/graph-node-conversation.test.tsx

### Tests
- 14/14 tests passing in tests/components/graph/graph-node-conversation.test.tsx
- All tests cover: icon presence, no useUrlState in node, prop-threading, stopPropagation, selectedTaskId highlight, onConversationOpen wiring, taskId priority over epicId, back button wired, right panel always visible, Suspense boundary

Graph DAG conversation panel wiring (Phase 1 completion)


AssignmentPanel shows: Needs Agent section (ready tasks without agent: label), Pre-assigned section (tasks with agent: label), Active Workers section scoped to current epic. Can assign from sidebar.

Starting work on AssignmentPanel enhancement. Will add three sections: Needs Agent (ready tasks without agent: label), Pre-assigned (tasks with agent: label), Active Workers scoped to current epic.

Enhance AssignmentPanel with sections


Reliability analysis complete. Critical gap: beadboard-cc8 (comments not detected by SSE). Error handling inconsistent, filter invariants not enforced. Graceful degradation partial.

Analyzes system reliability, bug patterns, error handling, and technical debt. Identifies fragility points and suggests hardening improvements.

Agent: bb-reliability-engineer


Success Criteria: (1) At least 2 distinct Dolt-powered UX concepts documented; (2) Each concept maps to concrete user jobs and technical constraints; (3) One concept selected for v1 experimentation.

Scope:
- Brainstorm unique frontend experiences powered by Dolt version history (time-travel views, memory lineage replay, change narratives, forensic debugging flows).
- Define which Dolt capabilities should be surfaced directly in UI and which should remain internal tooling.
- Produce 2-3 product concepts with clear user value and implementation risk.

Out of Scope:
- Building full production features in this epic.
- Changing core bd storage backend behavior.

Prompt:
Design cool, unique, and practical ways to use Dolt history in the frontend so users can understand how issue state, memory rules, and execution decisions evolved over time.

[epic][brainstorm] Dolt Version History as Frontend Product Surface


Removes hard-coded developer paths from tracked files

Agent: bb-path-hygiene


Scope: Consolidate 4 different agent identifiers (role-name, bead title, agent-bead-id, BB_AGENT) into a simpler system\n\nOut of Scope: Changes to bd or bb command interfaces\n\nSuccess Criteria:\n- Agent only needs to track ONE identifier\n- All commands derive from that single identifier\n- Naming convention table simplified or removed\n\nFiles: skills/beadboard-driver/SKILL.md

Simplify identity system to single canonical identifier


Graph nodes show Assign button for open/blocked tasks. Dropdown shows archetypes. Selecting archetype calls /api/swarm/prep. Shows assigned archetype badge after success. Can change/remove assignment.

Completed. Added Assign button to GraphNodeCard with Radix dropdown-menu, proper dark theme CSS, agent: label prefix, and change/remove assignment support. All 6 TDD tests pass. All verification gates pass.

## Completed Implementation

### Files Changed
- **src/components/graph/graph-node-card.tsx**: Added Assign button with Radix dropdown-menu, kept original dark theme CSS
- **src/app/api/swarm/prep/route.ts**: Added DELETE handler for remove assignment

### Key Features
- Assign button shows for open/blocked/ready tasks (not closed)
- Dropdown shows all archetypes with color indicators
- Shows current assigned archetype with Change option
- Remove assignment option in dropdown
- Uses correct `agent:` label prefix
- Auto-refreshes via SSE after assignment

### Tests Written (TDD)
All 6 tests pass:
1. GraphNodeCard checks for assignable status
2. GraphNodeCard excludes closed tasks
3. GraphNodeCard parses agent: label
4. GraphNodeCard imports Radix dropdown-menu
5. GraphNodeCard receives archetypes
6. GraphNodeCard supports assignment action

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

Add Assign button/dropdown to GraphNodeCard


Rewrite beadboard-driver skill to be a complete agent SDK for interacting with beadboard from any project.\n\nGoal: Any agent with this skill + bd can immediately use:\n- Beads (create/update/close)\n- Dependencies\n- Memory system (query → attach → ratify → evolve)\n- Comments\n- Sessions + Ack\n- Archetypes + Templates\n- Swarms + Missions\n- Coord Events\n- Realtime\n- project.md (living env-specific doc)\n- Self-healing scripts\n- Tests\n\nThis replaces the deprecated Activity Lease model and old bb/agent-mail references.\n\nSTRUCTURE:\n1. Memory System Docs (4.1)\n2. Coord Events + Sessions + Ack Docs (4.2)\n3. Archetypes + Templates + Swarms Docs (4.3)\n4. Missions + Realtime Docs (4.4)\n5. project.md Template (4.5)\n6. Self-healing Scripts (4.6)\n7. Tests (4.7)\n8. Core Skill Rewrite: skill.md v4 (4.8) - LAST

[EPIC] BeadBoard Driver Skill v4 Rewrite


TASK CONTEXT
- Bead ID: beadboard-btn.1
- Parent: beadboard-btn ([EPIC] BeadBoard Driver Skill v4 Rewrite)
- Dependencies: None

TASK CONTRACT
- Goal: Document how agents use beadboard's memory system
- Success Criteria:
  - Reference docs cover full memory workflow
  - Includes query commands, provenance validation, contract creation
- Scope:
  - Memory workflow (query → attach → ratify → evolve)
  - Domain anchors
  - Canonical memory nodes
  - Memory contracts
  - Noise budget
- Out of Scope:
  - Frontend UI for memory

IMPLEMENTATION CONSTRAINTS
- Reference docs in skills/beadboard-driver/references/
- Follow memory_fabric_workflow.txt patterns

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

Memory System Docs: Query → Attach → Ratify → Evolve


Install/discovery contract and human-facing SKILL.md positioning are implemented and verified.

TASK CONTEXT\n- Bead ID: beadboard-c70.1\n- Parent: beadboard-c70\n- Dependencies: none\n\nTASK CONTRACT\n- Goal: Define and implement deterministic install/discovery checks for beadboard-driver scripts.\n- Success Criteria:\n  - session-preflight and diagnose-env return explicit BeadBoard install guidance with GitHub link\n  - Contract tests cover missing-tool remediation output\n- Scope:\n  - bd command discovery\n  - bb path resolution behavior\n  - remediation copy\n- Out of Scope:\n  - package publishing\n\nVERIFICATION REQUIREMENTS\n- Required commands: npm run typecheck, npm run lint, npm run test

Rewrote skills/beadboard-driver/SKILL.md in stronger product+manual voice (manifesto/outcomes/proof/runbook), with explicit BeadBoard identity and GitHub install path. Added install confidence section and 'use-this-when' reference mapping. Install/discovery remediation copy is present in scripts/session-preflight.mjs and scripts/diagnose-env.mjs. Verification: node skills/beadboard-driver/tests/run-tests.mjs (pass), npm run typecheck (pass), npm run lint (0 errors, 22 warnings).

Driver install check contract (bd+bb discovery + remediation UX)


Systems analysis complete. Memory: schema good but activation weak. Agent coordination: N+1 queries, subprocess bottleneck. Meta-design: protocol events should be beads, not TypeScript interfaces.

Evaluates memory system, agent coordination, and swarm patterns. Analyzes the meta-level design of how agents communicate, learn, and evolve.

Agent: bb-systems-theorist


TASK CONTEXT\n- Parent: beadboard-c70 / beadboard-05a\n\nTASK CONTRACT\n- Goal: Keep driver detection-only and emit platform-specific install remediation.\n- Success Criteria:\n  - session-preflight and diagnose-env output per-platform install hints\n  - docs clearly separate installer vs skill responsibilities\n- Scope: skills/beadboard-driver scripts + references\n- Out of Scope: installer execution from skill\n\nVERIFICATION REQUIREMENTS\n- npm run typecheck\n- npm run lint\n- npm run test

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

Driver detection alignment: install remediation by platform


Analyze Legacy System


TASK CONTEXT\n- Bead ID: auto\n- Parent: none\n- Dependencies: none\n\nTASK CONTRACT\n- Goal: Make beadboard-driver reliably detect BeadBoard installation and provide clear install/remediation UX for both agents and humans.\n- Success Criteria:\n  - Skill docs include explicit BeadBoard identity and GitHub link\n  - Driver scripts produce deterministic install guidance when BeadBoard tooling is missing\n  - Global vs repo-local usage model is documented and testable\n- Scope:\n  - Installation checks and remediation messages\n  - Global package/distribution strategy decision\n  - Optional project template contract for global skills\n- Out of Scope:\n  - Full package publish implementation unless split into child beads\n\nIMPLEMENTATION CONSTRAINTS\n- Preserve existing bd as source-of-truth workflow semantics\n- Keep user-facing copy simple and explicit\n\nVERIFICATION REQUIREMENTS\n- Required commands: npm run typecheck, npm run lint, npm run test

Completed beadboard-i0q. Remaining epic child: beadboard-05a (global package/distribution strategy decision).

[EPIC] BeadBoard Installation + Discovery Contract for Driver Skill


When a comment is added via 'bd comments add' (or the ThreadDrawer POST), the JSONL file is mutated but the Chokidar watcher does not broadcast an SSE event. Users have to manually refresh to see new comments. The watcher snapshot diff likely only diffs top-level issue fields (status, title, etc.) and does not detect the comments array changing. Fix should: (1) detect comment-count changes in the snapshot diff, (2) emit an SSE activity/change event so subscribed clients re-fetch and display the new comment without a full page refresh.

SSE watcher misses comment additions — no live refresh on bd comment add


File created: src/hooks/use-graph-analysis.ts; Hook exports GraphAnalysis interface with: graphModel, signalById, cycleNodeIdSet, actionableNodeIds, blockerTooltipMap, blockerAnalysis, chainNodeIds; Hook takes (issues, projectRoot, selectedId) parameters; npm run typecheck passes

## TASK CONTEXT
- Bead ID: beadboard-ck0
- Title: Create useGraphAnalysis hook
- Parent/Epic: beadboard-uui (Unify Graph + Swarm into Single Enhanced Graph View)
- Dependencies (must be done first): None

## GOAL
Extract duplicated graph computation logic from workflow-graph.tsx (lines 73-135) and dependency-graph-page.tsx (lines 327-433) into a reusable hook. This consolidates the graph analysis logic that is currently duplicated across two files.

## SUCCESS CRITERIA
- File created: src/hooks/use-graph-analysis.ts (~100 lines)
- Hook exports GraphAnalysis interface with: graphModel, signalById, cycleNodeIdSet, actionableNodeIds, blockerTooltipMap, blockerAnalysis, chainNodeIds
- Hook takes (issues: BeadIssue[], projectRoot: string, selectedId: string | null | undefined) parameters
- Uses existing buildGraphModel from ../../lib/graph
- Uses analyzeBlockedChain, detectDependencyCycles from ../../lib/graph-view
- npm run typecheck passes

## SCOPE
- Create new hook file at src/hooks/use-graph-analysis.ts
- Export GraphAnalysis interface
- Use useMemo for all computed values
- Document each computed field with JSDoc comments

## OUT OF SCOPE
- Modifying existing components (that happens in beadboard-5sr)
- Adding new graph analysis features
- Changes to buildGraphModel or graph-view functions

## IMPLEMENTATION NOTES
The hook should compute:
1. graphModel: Result of buildGraphModel(issues, { projectKey: projectRoot })
2. signalById: Map of issue.id -> { blockedBy: number, blocks: number }
3. cycleNodeIdSet: Set of node IDs that are part of dependency cycles
4. actionableNodeIds: Set of node IDs that have no open blockers (ready to work)
5. blockerTooltipMap: Map of issue.id -> string[] of blocker descriptions
6. blockerAnalysis: Result of analyzeBlockedChain for selectedId (null if no selection)
7. chainNodeIds: Set of selectedId + all blocker node IDs

## VERIFICATION REQUIREMENTS
- Required commands:
  - npm run typecheck
- Required artifacts:
  - Screenshot of new hook file structure

Create useGraphAnalysis hook


UnifiedShell has assignMode and selectedAssignIssue state; SmartDag receives onAssignModeChange and onSelectedIssueChange callbacks; When view===graph && assignMode, right panel renders AssignmentPanel; Otherwise right panel renders ContextualRightPanel; Remove if (view === 'swarm') block and SwarmWorkspace import; npm run typecheck, lint, test all pass

Wire assign mode into UnifiedShell


Empty labels array now treated as 'clear all labels' — validator and arg builder both fixed. Regression tests added.

handleRemoveTemplateFromEpic in assignment-panel.tsx sends labels:[] when stripping the only template: label. asOptionalLabels([]) returns undefined, which trips the update validator: 'At least one update field is required.' Fix: asOptionalLabels should return [] (not undefined) for an explicit empty array, and the validator should accept [] as a valid labels value (meaning clear all labels).

Fixed in mutations.ts: asOptionalLabels([]) now returns [] instead of undefined; validator uses === undefined instead of \!; pushOptionalLabels passes --set-labels '' to clear all labels. 2 new regression tests added. Typecheck clean, lint clean, 30/32 tests pass (2 pre-existing).

Fix: removing last template label fails with empty labels array


/graph page either redirects to /?view=graph OR renders SmartDag in standalone layout; No DependencyGraphPage duplication; npm run typecheck, lint, test all pass

Update standalone /graph page


Ratified canonical UI memory for HideClosed invariants across source lists and selected-state invalidation.

Scope: Any Hide Closed / visibility filtering behavior for epics or tasks across left panel, graph chip bars, and selected state holders.\nOut of Scope: Independent status badges that do not affect visibility.\nRule: A visibility filter is not complete unless it is applied to (1) source lists for every surface, and (2) current selection state invalidation paths.\nRationale: Partial filter application causes closed entities to persist in one panel while hidden in another.\nFailure Mode: User sees closed items despite Hide Closed enabled, losing trust in state consistency.

Canonicalized after hideClosed regression investigation. Provenance: beadboard-x1y, beadboard-4k8, beadboard-xz5. Linked to UI anchor beadboard-fld and reliability chain beadboard-om4.

[MEMORY][UI][HARD] HideClosed invariants must include selected-state and all epic surfaces


TASK CONTEXT
- Bead ID: (auto)
- Title: Phase 5: Blocked Triage Modal
- Parent/Epic: none (phase epic)
- Dependencies (must be done first): beadboard-8ij (Phase 3 — useArchetypePicker hook), beadboard-x3l (Phase 4 — livenessMap in shell)

TASK CONTRACT
- Goal: Replace the TopBar blocked-items panel toggle with a purpose-built BlockedTriageModal that shows all blocked tasks with their blocker chain context and an inline archetype picker for immediate assignment without leaving the modal.
- Success Criteria:
  - TopBar blocked button opens BlockedTriageModal (not a panel toggle)
  - Modal lists all blocked tasks with blocker chain context (buildBlockedByTree already exists)
  - Each blocked task has an inline ArchetypePicker to assign an agent immediately
  - Assigning an agent dismisses the picker for that task but keeps the modal open
  - npm run typecheck && npm run lint && npm run test all pass
- Scope:
  - New BlockedTriageModal component
  - TopBar blocked button rerouted to open modal
  - useArchetypePicker hook reused from beadboard-8ij.1
- Out of Scope:
  - Redesigning blockedOnly URL filter (already works from Phase 0)
  - Changing how blockers are computed

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.

Phase 5: Blocked Triage Modal


BlockedTriageModal created with inline archetype picker, blocker chain display, uses deriveBlockedIds for accurate blocked computation

TASK CONTEXT
- Bead ID: beadboard-d2x.1
- Title: Build BlockedTriageModal with inline ArchetypePicker
- Parent/Epic: beadboard-d2x
- Dependencies (must be done first): beadboard-8ij.1 (useArchetypePicker hook)

TASK CONTRACT
- Goal: Build a modal component that lists all blocked tasks with their full blocker chain context and allows the operator to assign an archetype agent to each blocked task inline without dismissing the modal.
- Success Criteria:
  - BlockedTriageModal renders a list of all issues where status === 'blocked'
  - Each row shows: task title, task ID, blocker chain (use buildBlockedByTree from src/lib if it exists, or derive from issue.dependencies)
  - Each row has an inline ArchetypePicker (useArchetypePicker hook from beadboard-8ij.1) that assigns and then collapses without closing the modal
  - Modal is scrollable if blocked list is long
  - Modal closes via Escape key or close button
  - npm run typecheck passes
- Scope:
  - src/components/shared/blocked-triage-modal.tsx (new file)
  - Use shadcn Dialog primitive (already in components/ui/) for the modal shell
  - Use useArchetypePicker hook for each row's assignment action
  - Search src/lib/ for buildBlockedByTree or equivalent before writing blocker-chain logic from scratch
- Out of Scope:
  - Wiring modal open/close to TopBar (beadboard-d2x.2)
  - Changing how issues are marked blocked

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.

BlockedTriageModal created at src/components/shared/blocked-triage-modal.tsx. Uses deriveBlockedIds (exported in Task 1) and buildBlockedByTree for blocker chain. Inline archetype picker per row. 12 tests pass. Typecheck passes (pre-existing error in unrelated file). Lint passes.


TopBar blocked button now opens BlockedTriageModal instead of toggling URL

TASK CONTEXT
- Bead ID: beadboard-d2x.2
- Title: Reroute TopBar blocked button to open BlockedTriageModal
- Parent/Epic: beadboard-d2x
- Dependencies (must be done first): beadboard-d2x.1

TASK CONTRACT
- Goal: The TopBar 'Blocked Items' button currently toggles a URL param (blockedOnly). Replace this with a modal open trigger that opens BlockedTriageModal, keeping the blockedOnly filter wired from Phase 0 for the social feed but making the primary triage action the modal.
- Success Criteria:
  - Clicking 'Blocked Items' in TopBar opens BlockedTriageModal
  - BlockedTriageModal receives issues and projectRoot from UnifiedShell
  - Existing blockedOnly URL toggle in TopBar is either removed or made secondary (decide when reading the component — do not break Phase 0 work)
  - npm run typecheck passes
- Scope:
  - src/components/shared/top-bar.tsx — change blocked button handler
  - src/components/shared/unified-shell.tsx — add modal open state, pass to TopBar and BlockedTriageModal
- Out of Scope:
  - Changing BlockedTriageModal internals (beadboard-d2x.1)
  - Phase 0 blockedOnly social feed filter

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.

TopBar blocked button now opens BlockedTriageModal. UnifiedShell manages modal state. Typecheck passes (pre-existing errors), lint 0 errors, tests pass (2 pre-existing failures).


File created: src/components/graph/assignment-panel.tsx; Archetypes/Templates buttons open inspector modals; Task assignment section shows selected issue details; Archetype picker dropdown populated from useArchetypes; Prep Task for Swarm button calls /api/swarm/prep; Condensed squad roster shows active agents; npm run typecheck passes

Create AssignmentPanel component


Scope: When creating or rewriting skills for beadboard\nOut of Scope: Specific implementation details\nRule: A complete skill should have:\n1. skill.md - Entry point, manual, TOC, pointers to scripts\n2. references/ - Detailed docs for each system (memory, coord, sessions, archetypes, etc)\n3. scripts/ - Self-healing tools (on-demand, referenced by skill.md)\n4. project.md - Template that agents fill with env-specific workarounds\n5. tests/ - Skill-local and repo-level tests\n\nRationale: This structure allows agents to understand the full system while keeping skill.md readable as a selling point/manual.\n\nFailure Mode: Skills that dump everything into one file become unreadable and hard to maintain.\n\nEvidence: beadboard-1bg (skill v4 rewrite)

[MEMORY][ARCH][SOFT] Skill Structure: Entry Point + References + Scripts + Tests + project.md


setup-mail-delegate.mjs created; self-resolves path, configures delegate automatically

Scope: new script + new contract test + SKILL.md Step 0C update.\nScript: skills/beadboard-driver/scripts/setup-mail-delegate.mjs\n- Uses import.meta.url to resolve its own __dirname\n- Constructs shimPath = join(__dirname, 'bb-mail-shim.mjs')\n- Runs: bd config set mail.delegate 'node <shimPath>'\n- Outputs JSON: {ok, configured, delegate} or {ok:false, error_code, reason}\nTest: setup-mail-delegate.contract.test.mjs\n- dry_run: script exits ok and outputs expected delegate path\n- bd_missing: script exits ok with BD_NOT_FOUND error_code\nSKILL.md: replace Step 0C 'resolve absolute path' block with: node {baseDir}/scripts/setup-mail-delegate.mjs\nSuccess Criteria: agent runs one command, delegate is set correctly, no path guessing required.

Created setup-mail-delegate.mjs: uses import.meta.url to self-resolve shim absolute path, runs bd config set mail.delegate, --dry-run flag for testing. Contract test: dry-run verifies absolute path resolution to bundled shim, BD_NOT_FOUND case. Test registered in run-tests.mjs. SKILL.md Step 0C now: node {baseDir}/scripts/setup-mail-delegate.mjs (one line, no path guessing). Tests: 14/14 pass.

Add setup-mail-delegate.mjs script + contract test


Testing from curl


Completed: Unified-shell wired as central panel state coordinator. Commit c246cea.

Wired unified-shell.tsx as the central coordinator for all panel state: assignMode, taskId, lastTaskId, lastAssignMode, isNonTelemetry detection. All panel-switching flows (rocket, conversation, telemetry, minimize, social-view rocket) route through unified-shell handlers. handleSocialRocket, handleMinimize, handleNodeTelemetry etc. Scope: unified-shell.tsx. Success Criteria: Single source of truth for right panel state, no state desync across views.

Wire unified-shell as central state coordinator for panel modes


Given newly introduced UI copy, when reviewed, then wording is concise and unambiguous for first-time users.
Verification command(s): npm run lint; targeted UI review in changed components

Scope: UI copy in labels, controls, and status messaging.
Out of Scope: Internal comments and engineering-only diagnostics.
Rule: Use simple user-facing language and explicit status words.
Rationale: Reduces ambiguity and onboarding friction.
Failure Mode: Dense or vague copy increases mistakes and support load.

Provenance linked: beadboard-68k.4, beadboard-68k.2, bb-u6f.3

[MEMORY][UX][SOFT] User-facing copy must stay simple and explicit


Given independent subtasks, when execution starts, then each subtask has explicit ownership and verification evidence.
Verification command(s): bd dep tree <epic-id>; bd ready; git status --short

Scope: Any task with 2+ independent units of work.
Out of Scope: Single-file trivial edits.
Rule: Parallelize independent reads/exploration and isolate ownership for independent execution threads.
Rationale: Reduces cycle time while preserving traceability.
Failure Mode: Serial execution on independent work causes avoidable delays.

Provenance linked: bb-u6f.6, bb-u6f.6.1, beadboard-r1i

[MEMORY][AGENT][SOFT] Parallelize independent work with clear ownership


Given a new panel-switching trigger from any view, when implementation is reviewed, then the trigger routes through unified-shell handler props, not local component state.

Scope: Right panel mode switching (conversation, assign, telemetry, minimize/restore). Out of Scope: Left panel and top bar state. Rule: unified-shell.tsx is the single source of truth for right panel state (assignMode, taskId, lastTaskId, lastAssignMode). All panel-switching flows from any view (DAG nodes, social cards, top bar) must route through unified-shell handlers, not manage panel state locally. Rationale: LaunchSwarmDialog failed because it was a parallel panel system. Centralizing in unified-shell prevents state desync across views. Failure Mode: Local panel state in child components causes inconsistent behavior depending on which view the user entered from.

[MEMORY][UX][SOFT] Unified-shell owns all right-panel state transitions


Design New Component


TASK CONTEXT\n- Goal: make bb/beadboard help output human-usable by default.\n\nTASK CONTRACT\n- Success Criteria:\n  - --help prints readable command guide\n  - --json retains structured output\n- Scope:\n  - cli help rendering path\n- Out of Scope:\n  - command behavior changes beyond help text\n\nVERIFICATION REQUIREMENTS\n- npm run typecheck\n- npm run lint\n- npm run test

[EPIC] CLI Help UX


Made --help human-readable by default with json opt-in preserved and tests verified.

TASK CONTEXT\n- Parent/Epic: beadboard-f31\n\nTASK CONTRACT\n- Goal: return readable help text for bb/beadboard --help unless --json requested.\n- Success Criteria:\n  - bb --help prints usage and command groups\n  - --json still returns structured payload\n  - tests cover both paths\n- Scope:\n  - src/cli/beadboard-cli.ts output path\n- Out of Scope:\n  - new command implementations\n\nVERIFICATION REQUIREMENTS\n- node --import tsx --test tests/cli/beadboard-help-output.test.ts\n- npm run typecheck\n- npm run lint\n- npm run test

Make --help human-readable by default


Given a workaround task, when created, then trigger, rollback criteria, and retirement owner are present.
Verification command(s): bd show <workaround-id>

Scope: Temporary workaround decisions under delivery pressure.
Out of Scope: Final architecture decisions already ratified.
Rule: Any workaround must include trigger conditions, rollback criteria, and owner for retirement.
Rationale: Keeps tactical decisions from becoming accidental permanent architecture.
Failure Mode: Undocumented workaround debt accumulates and obscures system intent.

Provenance linked: bb-ff6, bb-6bx, beadboard-5vs

[MEMORY][RELIABILITY][SOFT] Workarounds require trigger rollback and owner


Canonical UI/UX memories are related to this anchor via bd dep relate.

Domain anchor for UI/UX rules, accessibility constraints, and component usage patterns.

[MEMORY-ANCHOR] UI/UX


TASK CONTEXT
- Bead ID: (to be assigned)
- Title: [EPIC] BeadBoard Driver Skill: Documentation Fixes
- Parent/Epic: none

TASK CONTRACT
- Goal: Fix documentation issues identified in cold-agent usability audit (v5a.15)
- Success Criteria:
  - All subtasks completed with evidence
  - Cold agent can use skill without guessing paths
  - Skill is portable across .agents/, .codex/, .claude/ installations
- Scope:
  - SKILL.md path conventions
  - Complete Use-The-Right-Doc Map
  - Bootstrap section for cold-start agents
  - Make skill portable (works from any project cwd)
- Out of Scope:
  - Code changes to scripts
  - New features

LABELS: skill:beadboard-driver, area:docs


Conventions section added defining {baseDir} and path resolution

TASK CONTEXT
- Bead ID: beadboard-flg.1
- Title: Define {baseDir} and path conventions in SKILL.md
- Parent/Epic: beadboard-flg

TASK CONTRACT
- Goal: Add explicit path conventions so cold agents understand how to resolve script paths regardless of where the skill is installed.
- Success Criteria:
  - SKILL.md has a '## Conventions' section
  - {baseDir} is explicitly defined as the skill's own directory
  - Path resolution is clear for skills installed at .agents/, .codex/, .claude/, or project-local
- Scope:
  - Add conventions section to SKILL.md
  - Document that commands should work from any project cwd
- Out of Scope:
  - Changing command-matrix.md content
  - Other documentation fixes

VERIFICATION REQUIREMENTS
- Cold agent can understand path resolution without guessing

Added ## Conventions section to SKILL.md (lines 64-68):
- Defined {baseDir} as skills/beadboard-driver/ relative to working directory
- Documented that script paths are relative to {baseDir}
- Added portability note for .agents/, .codex/, .claude/ installations

flg.1: Define {baseDir} and path conventions in SKILL.md


Use-The-Right-Doc Map now includes all reference documents

TASK CONTEXT
- Bead ID: beadboard-flg.2
- Title: Complete Use-The-Right-Doc Map with missing references
- Parent/Epic: beadboard-flg

TASK CONTRACT
- Goal: Add missing reference documents to the 'Use-The-Right-Doc Map' section in SKILL.md.
- Success Criteria:
  - All reference docs in references/ folder are listed in the map
  - Each entry has a clear 'Use when...' description
- Scope:
  - Add references/agent-state-liveness.md entry
  - Add any other missing reference docs
  - Verify all 7+ reference docs are listed
- Out of Scope:
  - Creating new reference docs
  - Other documentation fixes

VERIFICATION REQUIREMENTS
- Cold agent can find all reference docs from the map

Added missing references to Use-The-Right-Doc Map (lines 117-122):
- references/agent-state-liveness.md - agent state transitions, heartbeats, slot operations
- references/coordination-system.md - bb agent command reference

flg.2: Complete Use-The-Right-Doc Map with missing references


Bootstrap section added for cold-start agents

TASK CONTEXT
- Bead ID: beadboard-flg.3
- Title: Add Bootstrap section for cold-start agents
- Parent/Epic: beadboard-flg

TASK CONTRACT
- Goal: Add a Bootstrap/Cold Start section to SKILL.md that guides agents with zero prior context.
- Success Criteria:
  - SKILL.md has '## Bootstrap (Cold Start)' section
  - Includes working directory guidance
  - Includes bd installation check with link to repo
  - Includes preflight verification step
  - Step-by-step and explicit
- Scope:
  - Add bootstrap section after 'Start Here'
  - No prior knowledge of BeadBoard assumed
- Out of Scope:
  - Other documentation fixes
  - Changing existing sections

VERIFICATION REQUIREMENTS
- Fresh agent can follow bootstrap section and get to working state

Added ## Bootstrap (Cold Start) section to SKILL.md (lines 47-62):
- Step 1: Verify working directory
- Step 2: Verify bd is installed with install link
- Step 3: Run preflight verification

flg.3: Add Bootstrap section for cold-start agents


Portability guidance added - skill works from any project directory

TASK CONTEXT
- Bead ID: beadboard-flg.4
- Title: Make skill portable - paths work from any project
- Parent/Epic: beadboard-flg

TASK CONTRACT
- Goal: Ensure all command examples in SKILL.md work when the skill is installed in an agent config folder and the agent is working in ANY project directory.
- Success Criteria:
  - Agent in /any/random/project can run the skill's commands
  - No hardcoded assumptions about working directory
  - Clear instructions for path resolution
- Scope:
  - Audit all path references in SKILL.md
  - Update examples to use skill-relative paths or explain resolution
  - Test that commands work from different directory than skill location
- Out of Scope:
  - Changing actual script behavior
  - Other documentation fixes

VERIFICATION REQUIREMENTS
- Commands work from arbitrary project directories

Added portability guidance in ## Conventions section (line 68):
- Skill is portable across .agents/, .codex/, .claude/, or project-local skills/ folders
- Commands work from any project directory once skill is installed

flg.4: Make skill portable - paths work from any project


6 archetypes with comprehensive system prompts (200-400 lines each), handoff protocols defined, all prompts follow structured format (phases, output format, examples), archetypes load correctly in UI, test-agent.json deleted

Completed 6 comprehensive agent archetypes with detailed system prompts (200-400 lines each), handoff protocols, workflow phases, and examples. All verification gates pass.

Created 6 comprehensive archetypes: architect, engineer, reviewer, tester, investigator, shipper. Each has 200+ line system prompts with workflow phases, handoff protocols, and examples. Deleted test-agent.json placeholder. All verification gates pass (typecheck, lint warnings only, tests pass).

Comprehensive Agent Archetype System v2


## TASK CONTEXT
- Bead ID: beadboard-gb0
- Title: Unify Graph + Swarm into Single Enhanced Graph View
- Parent/Epic: None (this is the epic)
- Dependencies: None

## 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 (filters toolbar, tabs)
- **Assign mode** (toggled): DAG highlights ready nodes, right panel transforms into assignment controls

## PROBLEM STATEMENT
BeadBoard has two views that both render the same `WorkflowGraph` DAG component, creating duplication:
- `?view=graph` is a bare 49-line wrapper (`SmartDag`) with no rich features
- `?view=swarm` duplicates the DAG with swarm-specific UI
- Standalone `/graph` page (`DependencyGraphPage`) has rich features stranded from the shell view

## 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 child tasks completed and verified
- `npm run typecheck && npm run lint && npm run 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 (swarm-workspace.tsx, telemetry-grid.tsx, specialized-agent-dag.tsx)

## OUT OF SCOPE
- Backend API changes (use existing `/api/swarm/prep`)
- New archetypes/templates features
- Mobile-specific layouts
- Changes to archetype-inspector.tsx, template-inspector.tsx (kept for AssignmentPanel)

## REFERENCE
- PRD: `docs/prd/unified-graph-view.md`
- Step 1 (agent animations): Already COMPLETED

## CHILD TASKS
1. `beadboard-gb0.4`: Create useGraphAnalysis hook (INDEPENDENT)
2. `beadboard-gb0.2`: Add assign mode to WorkflowGraph + GraphNodeCard (INDEPENDENT)
3. `beadboard-gb0.3`: Create AssignmentPanel component (INDEPENDENT)
4. `beadboard-gb0.8`: Remove swarm view from navigation (INDEPENDENT)
5. `beadboard-gb0.1`: Rewrite SmartDag with progressive disclosure (BLOCKED BY: gb0.4)
6. `beadboard-gb0.5`: Wire assign mode into UnifiedShell (BLOCKED BY: gb0.3, gb0.1)
7. `beadboard-gb0.7`: Delete deprecated swarm files (BLOCKED BY: gb0.5, gb0.8)
8. `beadboard-gb0.6`: Update standalone /graph page (BLOCKED BY: gb0.7)

## PARALLELIZATION
Phase 1 (parallel): gb0.4, gb0.2, gb0.3, gb0.8
Phase 2 (sequential): gb0.1 (after gb0.4)
Phase 3 (sequential): gb0.5 (after gb0.3, gb0.1)
Phase 4 (sequential): gb0.7 (after gb0.5, gb0.8)
Phase 5 (sequential): gb0.6 (after gb0.7)


Toolbar with Filters and Assign toggles; Filters row with hop depth, hide closed, blocking-only, sort ready first; Tab switcher: Tasks/Dependencies; Tasks tab with TaskCardGrid; Dependencies tab with DependencyFlowStrip + GraphSection; onAssignModeChange and onSelectedIssueChange callbacks; npm run typecheck, lint, test pass

## Completed Implementation

### Files Changed
- **src/components/graph/smart-dag.tsx**: Rewrote from 49-line wrapper to 272-line enhanced DAG with:
  - Toolbar with Filters toggle + Assign toggle
  - WorkflowTabs for Tasks/Dependencies switching
  - Collapsible filter row (hide closed, ready first, depth, blocking only)
  - Tasks tab with TaskCardGrid
  - Dependencies tab with WorkflowGraph (passing assignMode)

- **tests/components/graph/smart-dag.test.tsx**: Created 12 TDD tests (all passing)
- **package.json**: Added smart-dag.test.tsx to test script

### Tests Written (TDD)
All 12 tests pass:
1. SmartDag - file exists and exports
2. SmartDag - contains Filters toggle button
3. SmartDag - contains Assign toggle button
4. SmartDag - contains WorkflowTabs
5. SmartDag - supports onAssignModeChange callback
6. SmartDag - supports onSelectedIssueChange callback
7. SmartDag - imports TaskCardGrid
8. SmartDag - imports WorkflowGraph
9. SmartDag - passes assignMode to WorkflowGraph
10. SmartDag - manages hideClosed filter
11. SmartDag - manages sortReadyFirst filter
12. SmartDag - uses useGraphAnalysis hook

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

### Deferred
- DependencyFlowStrip: Created TODO bead `beadboard-58u` for future enhancement

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

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

npm run test
# tests 12 (smart-dag suite)
# pass 12
# fail 0
```

Rewrite SmartDag with progressive disclosure


WorkflowGraphProps includes assignMode?: boolean; GraphNodeData includes isAssignMode?: boolean; Non-actionable nodes dimmed with opacity-20 in assign mode; Actionable nodes highlighted with emerald ring; npm run typecheck passes

Added assign mode data flow to WorkflowGraph and GraphNodeCard with proper visual differentiation. All gates pass.

## Evidence
- workflow-graph.tsx: Added assignMode?: boolean to WorkflowGraphProps (line 31)
- workflow-graph.tsx: Added isAssignMode: assignMode to node data (line 116)
- graph-node-card.tsx: Added isAssignMode?: boolean to GraphNodeData (line 38)
- graph-node-card.tsx: Conditional styling for assign mode (lines 117-120)
  - isAssignMode && !isActionable: opacity-20 (dims non-ready nodes)
  - isAssignMode && isActionable: ring-2 ring-emerald-400/50 (highlights ready nodes)
- npm run typecheck: PASS
- npm run lint: PASS (0 errors)
- npm run test: PASS (31/31)

## Files Changed
- MODIFIED: src/components/shared/workflow-graph.tsx
- MODIFIED: src/components/graph/graph-node-card.tsx

Add assign mode to WorkflowGraph + GraphNodeCard


File created: src/components/graph/assignment-panel.tsx; Archetypes/Templates buttons open inspector modals; Task assignment UI with archetype picker; Prep Task for Swarm button calls API; Squad roster shows active agents; npm run typecheck passes

Created AssignmentPanel component with archetype/template buttons, task assignment UI, and squad roster. All gates pass.

## Evidence
- Created: src/components/graph/assignment-panel.tsx (189 lines)
- AssignmentPanelProps: selectedIssue, projectRoot, issues, epicId?
- Archetypes/Templates buttons open inspector modals
- Task assignment section shows ID, title, status
- Archetype picker dropdown from useArchetypes
- Prep Task for Swarm button calls POST /api/swarm/prep
- Squad roster filters in_progress + assignee
- npm run typecheck: PASS
- npm run lint: PASS (0 errors - warnings for unused epicId/loading are acceptable)
- npm run test: PASS (31/31)

## Files Changed
- NEW: src/components/graph/assignment-panel.tsx

Create AssignmentPanel component


File created: src/hooks/use-graph-analysis.ts; Hook exports GraphAnalysis interface; Hook takes (issues, projectRoot, selectedId) parameters; npm run typecheck passes

Created useGraphAnalysis hook and wired it into workflow-graph.tsx, eliminating duplicated graph computation logic. All gates pass.

## Evidence
- Created: src/hooks/use-graph-analysis.ts (107 lines)
- UPDATED: src/components/shared/workflow-graph.tsx to use the hook
- Removed duplicated useMemo computations (lines 75-137) replaced with single hook call
- Hook exports: graphModel, signalById, cycleAnalysis, cycleNodeIdSet, actionableNodeIds, blockerTooltipMap, blockerAnalysis, chainNodeIds
- npm run typecheck: PASS
- npm run lint: PASS (0 errors)
- npm run test: PASS (31/31)

## Files Changed
- NEW: src/hooks/use-graph-analysis.ts
- MODIFIED: src/components/shared/workflow-graph.tsx (now uses hook)

Create useGraphAnalysis hook


assignMode and selectedAssignIssue state in UnifiedShell; SmartDag receives callbacks; Right panel renders AssignmentPanel when view===graph && assignMode; SwarmWorkspace import removed; npm run typecheck, lint, test pass

## Completed Implementation

### Files Changed
- **src/components/shared/unified-shell.tsx**: Added assign mode integration:
  - Added `assignMode` state (boolean)
  - Added `selectedAssignIssue` state (BeadIssue | null)
  - Added `handleAssignModeChange` callback
  - Added `handleSelectedIssueChange` callback
  - Passes callbacks to SmartDag
  - Conditionally renders AssignmentPanel in right panel when view==='graph' && assignMode
  - Removed deprecated SwarmWorkspace and SwarmMissionPicker (never imported)

- **tests/components/unified-shell.test.tsx**: Rewrote with node:test, 9 TDD tests (all passing)
- **package.json**: Added unified-shell.test.tsx to test script

### Tests Written (TDD)
All 9 tests pass:
1. UnifiedShell - file exists and exports
2. UnifiedShell - has assignMode state
3. UnifiedShell - has selectedAssignIssue state
4. UnifiedShell - passes onAssignModeChange to SmartDag
5. UnifiedShell - passes onSelectedIssueChange to SmartDag
6. UnifiedShell - imports AssignmentPanel
7. UnifiedShell - renders AssignmentPanel conditionally
8. UnifiedShell - does not import SwarmWorkspace
9. UnifiedShell - does not import SwarmMissionPicker

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

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

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

npm run test
# tests 9 (unified-shell suite)
# pass 9
# fail 0
```

Wire assign mode into UnifiedShell


/graph page redirects to /?view=graph or renders SmartDag; No DependencyGraphPage duplication; npm run typecheck, lint, test pass

## SKILLS REQUIRED
- **test-driven-development**: Write tests BEFORE implementation
- **linus-beads-discipline**: Track progress, close with evidence
- **verification-before-completion**: Run all gates before closing

## TEST REQUIREMENTS
Before implementing, write tests for:
1. /graph page redirects to /?view=graph OR renders SmartDag

## TASK CONTEXT
- Bead ID: beadboard-gb0.6
- Title: Update standalone /graph page
- Parent/Epic: beadboard-gb0
- Dependencies: beadboard-gb0.7 (Delete deprecated files - DEFERRED)

## GOAL
Update the standalone /graph page to provide a consistent experience with the shell's ?view=graph.

## SUCCESS CRITERIA
- /graph page either redirects to /?view=graph OR renders SmartDag in standalone layout
- No DependencyGraphPage duplication
- npm run typecheck && npm run lint && npm run test all pass

## VERIFICATION REQUIREMENTS
- Required commands:
  - npm run typecheck
  - npm run lint
  - npm run test
- Tests MUST be written first (TDD)

Update standalone /graph page


Deleted: swarm-workspace.tsx, telemetry-grid.tsx, specialized-agent-dag.tsx; No orphaned imports; npm run typecheck, lint, test pass

## SKILLS REQUIRED
- **test-driven-development**: Write tests BEFORE implementation
- **linus-beads-discipline**: Track progress, close with evidence
- **verification-before-completion**: Run all gates before closing

## TEST REQUIREMENTS
Before deleting, verify with tests:
1. No imports of swarm-workspace.tsx exist
2. No imports of telemetry-grid.tsx exist
3. No imports of specialized-agent-dag.tsx exist

## TASK CONTEXT
- Bead ID: beadboard-gb0.7
- Title: Delete deprecated swarm files
- Parent/Epic: beadboard-gb0
- Dependencies: beadboard-gb0.5 (UnifiedShell wired), beadboard-gb0.8 (Navigation cleaned - CLOSED)
- Status: DEFERRED (keeping files for reference)

## GOAL
Remove the deprecated swarm components that are replaced by the unified graph view with assign mode.

## SUCCESS CRITERIA
- Deleted: src/components/swarm/swarm-workspace.tsx
- Deleted: src/components/swarm/telemetry-grid.tsx
- Deleted: src/components/swarm/specialized-agent-dag.tsx
- No remaining imports of deleted files anywhere in codebase
- npm run typecheck && npm run lint && npm run test all pass

## VERIFICATION REQUIREMENTS
- Required commands:
  - npm run typecheck
  - npm run lint
  - npm run test
- Tests MUST be written first (TDD)

Delete deprecated swarm files


ViewType removes swarm; VALID_VIEWS removes swarm; Left panel removes swarm entry; Mobile nav removes swarm tab; npm run typecheck, lint, test pass

Removed swarm view from navigation across all components and updated tests. All gates pass.

## Evidence
- use-url-state.ts: ViewType removes 'swarm' (line 6)
- use-url-state.ts: VALID_VIEWS removes 'swarm' (line 46)
- left-panel.tsx: views array removes swarm entry (lines 187-190)
- mobile-nav.tsx: tabs array removes swarm tab (lines 6-9)
- unified-shell.tsx: Removed dead view === 'swarm' branches
- swarm-mission-picker.tsx: Changed setView('swarm') to setView('graph')
- Updated tests for swarm fallback behavior
- npm run typecheck: PASS
- npm run lint: PASS (0 errors)
- npm run test: PASS (31/31)

## Files Changed
- MODIFIED: src/hooks/use-url-state.ts
- MODIFIED: src/components/shared/left-panel.tsx
- MODIFIED: src/components/shared/mobile-nav.tsx
- MODIFIED: src/components/shared/unified-shell.tsx
- MODIFIED: src/components/swarm/swarm-mission-picker.tsx
- MODIFIED: tests/hooks/url-state-integration.test.ts
- MODIFIED: tests/components/shared/top-bar.test.tsx
- MODIFIED: tests/components/shared/mobile-nav.test.tsx

Remove swarm view from navigation


All hard-coded developer paths removed or replaced with portable alternatives. 12 documentation/config files and 5 test files updated. Verification shows 0 matches for developer-specific paths.

TASK CONTEXT
- Bead ID: beadboard-pai7.2
- Title: Remove hard-coded developer paths
- Parent/Epic: beadboard-pai7
- Dependencies: none

TASK CONTRACT
- Goal: Search and remove all hard-coded absolute developer paths from tracked files
- Success Criteria:
  - No /mnt/c/Users/* paths in any tracked files
  - No /Users/* or C:\Users\* paths in tracked files
  - All paths replaced with portable alternatives or removed
  - Verification: grep finds zero matches
- Scope:
  - All tracked files in repository
  - Absolute filesystem paths
- Out of Scope:
  - .gitignore changes (task 1)
  - Runtime artifact cleanup (task 3)
  - Test fixture paths (if clearly marked as fixtures)

IMPLEMENTATION CONSTRAINTS
- Replace with relative paths or config-based alternatives where possible
- Document any functional changes in code comments
- Ensure no functional regressions

VERIFICATION REQUIREMENTS
- Required commands:
  - grep -r "/mnt/c/Users" . --exclude-dir=.git
  - grep -r "/Users/Zenchant" . --exclude-dir=.git
  - grep -r "C:\Users\\" . --exclude-dir=.git

Commands run:
- grep -r "/mnt/c/Users" . --exclude-dir=.git --exclude-dir=.beads --exclude-dir=node_modules --exclude-dir=.next
- grep -r "/Users/Zenchant" . --exclude-dir=.git --exclude-dir=.beads --exclude-dir=node_modules --exclude-dir=.next
- grep -r "C:\\\Users\\\\\" . --exclude-dir=.git --exclude-dir=.beads --exclude-dir=node_modules --exclude-dir=.next

Files changed (12):
1. docs/plans/2026-03-03-global-install-runtime-manager.md - Replaced absolute WSL paths with relative 'beadboard'
2. docs/prompts/2026-02-28-next-session-dolt-repair.md - Replaced absolute path with relative 'beadboard'
3. docs/prompts/2026-02-28-next-session-holistic-ux-critique.md - Replaced absolute path with relative 'beadboard'
4. NEXT_SESSION_PROMPT.md - Replaced absolute path with relative 'beadboard'
5. docs/protocols/operative-protocol-v1.md - Replaced developer path example with generic '/path/to/project'
6. skills/beadboard-driver/SKILL.md - Changed WSL example path from /mnt/c/Users to /home/<you> for portability
7. .agent/skills/shadcn-ui - Changed from absolute path to relative: ../../.agents/skills/shadcn-ui/
8. .augment/skills/shadcn-ui - Changed from absolute path to relative: ../../.agents/skills/shadcn-ui/
9. .claude/skills/shadcn-ui - Changed from absolute path to relative: ../../.agents/skills/shadcn-ui/
10. .cline/skills/shadcn-ui - Changed from absolute path to relative: ../../.agents/skills/shadcn-ui/
11. .openhands/skills/shadcn-ui - Changed from absolute path to relative: ../../.agents/skills/shadcn-ui/
12. skills/shadcn-ui - Changed from absolute path to relative: ../.agents/skills/shadcn-ui/

Test files updated with portable paths:
- tests/api/projects-route.test.ts - Changed from 'c:/Users/Zenchant/codex/beadboard/' to 'c:/Users/test/project/beadboard/'
- tests/lib/mutations.test.ts - Changed from 'C:/Users/Zenchant/codex/beadboard' to 'C:/Users/test/project/beadboard'
- tests/lib/pathing.test.ts - Changed all occurrences to 'C:/Users/test/project/beadboard'
- tests/lib/project-scope.test.ts - Changed all occurrences to 'C:/Users/test/project/beadboard'
- tests/lib/read-interactions.test.ts - Changed from 'C:/Users/Zenchant/codex/beadboard' to 'C:/Users/test/project/beadboard'

Verification output:
- grep for '/mnt/c/Users': No matches found
- grep for '/Users/Zenchant': No matches found
- grep for 'C:\Users\': No matches found
- npm run typecheck: PASS
- npm run lint: PASS (28 pre-existing warnings, 0 errors)
- npm run test: PASS (all tests passing)

Remove hard-coded developer paths


Investigates UI performance issues - specifically tracking down why mail/reservations API calls are made for all agents causing 404 spam

Agent: bb-investigator


Color palette with presets + custom picker, icon/emoji selector, live preview in inspector, suggested capabilities, duplicate/clone feature, archetype cards show icon/emoji

Completed full archetype customization: color palette (30 presets), icon/emoji selector (40 emojis), capability autocomplete (30 suggestions), live preview, clone functionality, icon field support in all display components. All verification gates pass.

Enable users to fully customize their archetypes with color presets, icons/emojis, and better UX

Completed: color palette with 30 presets, icon/emoji selector with 40 emojis, suggested capabilities with autocomplete, live preview, clone functionality, updated all display components to use icon field. All verification gates pass.

Enhanced Archetype Customization


Testing another flow


BB_REPO removed, {baseDir} used correctly throughout

Scope: SKILL.md all script path references.\nProblem: I incorrectly introduced $BB_REPO to reference scripts. Scripts are bundled WITH the skill, not in a separate BeadBoard install. {baseDir} = the directory containing SKILL.md. Agent runtime knows this path and substitutes it.\nChanges:\n- Replace all $BB_REPO/skills/beadboard-driver/scripts/... with {baseDir}/scripts/...\n- Add one-line note in Step 1 explaining {baseDir} = 'the folder containing this SKILL.md'\n- Step 0 mail delegate setup: use {baseDir}/scripts/bb-mail-shim.mjs (agent must resolve to absolute path for bd config set)\n- Remove all BB_REPO export/explanation text\nSuccess Criteria: Cold agent reading skill knows exactly how to reference scripts without any external env var.

Replaced all $BB_REPO with {baseDir} throughout SKILL.md. Added explanation: {baseDir} = directory containing this SKILL.md, provided by agent runtime. Scripts are bundled with skill. Mail delegate needs absolute path resolved from {baseDir}. Removed BB_REPO export lines from bb install flow — only the global 'bb' binary is needed, no env var. Tests: 12/12 pass.

Fix script paths: use {baseDir} (skill dir) not BB_REPO


Scope: Relocate Iron Law from line 22-27 to immediately after description\n\nOut of Scope: Changes to Iron Law content\n\nSuccess Criteria:\n- Iron Law is first thing agent sees after skill description\n- Current location replaced with brief reference\n\nFiles: skills/beadboard-driver/SKILL.md

Move Iron Law to top of document


Global-vs-local project context behavior clarified and implemented via template+ensure workflow.

TASK CONTEXT\n- Bead ID: beadboard-c70.2\n- Parent: beadboard-c70\n- Dependencies: beadboard-c70.1\n\nTASK CONTRACT\n- Goal: Make project template usage clear for global vs repo-local skill installs.\n- Success Criteria:\n  - SKILL.md explains project template as source template and optional target-repo copy\n  - scripts optionally support external project context file path (if needed)\n- Scope:\n  - docs + contract tests\n- Out of Scope:\n  - UI integration changes\n\nVERIFICATION REQUIREMENTS\n- Required commands: npm run typecheck, npm run lint, npm run test

Implemented global-skill project context contract: removed in-skill project.md runtime file, added skills/beadboard-driver/project.template.md as template source, added scripts/ensure-project-context.mjs to create <target-repo>/project.md only when missing, and updated SKILL.md + command matrix accordingly. Added contract test skills/beadboard-driver/tests/ensure-project-context.contract.test.mjs and wired into run-tests.mjs. Verification: node skills/beadboard-driver/tests/run-tests.mjs (pass, 10 tests), npm run typecheck (pass), npm run lint (0 errors, 22 warnings).

Global skill project-context contract (project.md optional path model)


All existing canonical memory nodes have source bead relations and evidence_ids/plan_refs metadata; help docs require provenance capture.

Canonical memory provenance linked to historical beads and help/memory updated

Strengthen memory retrieval for fresh agents by relating canonical memory nodes to source closed beads/plans and adding explicit evidence metadata fields.

Completed provenance upgrade: all 7 canonical memory beads now link to source closed beads and include metadata keys evidence_ids + plan_refs. Updated help/memory docs to require provenance capture and provenance checks in task-start workflow.

Add provenance links and evidence metadata to canonical memory nodes


First-agent bootstrap flow added; cold agent can go from zero to full power user in any project

Scope: SKILL.md Step 0 (new), project.md creation flow.\nOut of Scope: actual script changes.\nContext: When an agent opens this skill in a project that has never used BeadBoard before, project.md will not exist. This is the signal that the agent is 'first agent in project.' The agent must:\n1. Check for project.md in CWD — if missing, run bootstrap\n2. Check bb on PATH (which bb / where bb)\n3. If bb missing: inform user that BeadBoard is required. Ask user if they want to install it.\n   - If yes: clone from GitHub repo, run 'npm i -g .' from cloned dir, set BB_REPO=<cloned-path>\n   - Also check bd (beads-cli) — if missing: npm install -g beads-cli\n4. Configure mail delegate: bd config set mail.delegate 'node $BB_REPO/skills/beadboard-driver/scripts/bb-mail-shim.mjs'\n5. Create project.md from template (note: bb and bd are installed, record versions)\n6. Continue to Step 1\nIf project.md already exists: read it, skip bootstrap, continue.\nSuccess Criteria: An agent with zero prior context can follow Step 0 → Step 9 in any project, first or subsequent session.

Added Step 0: First-Agent Bootstrap to SKILL.md. Flow: check project.md → if missing: check bd (install if needed), check bb (prompt user to confirm, clone zenchantlive/beadboard + npm i -g . + set BB_REPO), configure mail delegate, verify both preflight scripts pass, create project.md from template. Step 3 updated to 'Update' not 'Initialize/Update' since Step 0 creates it. Fixed Requirements to reference Step 0 for bb install. Fixed Step 3 script path to use BB_REPO. Fixed wrong framing bead 9ha is already closed. Tests: 12/12 pass.

Add first-agent bootstrap flow to SKILL.md


Runtime artifacts removed from git tracking: .agents/, .beads/, .augment/, .claude/, .cline/, .gemini/, .kilocode/, .openhands/. All directories now untracked but files remain on disk. Verification confirms no runtime files in git index.

TASK CONTEXT
- Bead ID: beadboard-pai7.3
- Title: Remove runtime artifacts from git tracking
- Parent/Epic: beadboard-pai7
- Dependencies: none

TASK CONTRACT
- Goal: Remove .agents/, .beads/, and other runtime directories from git tracking (not history)
- Success Criteria:
  - git rm --cached executed for .agents/ directory
  - git rm --cached executed for .beads/ directory
  - git rm --cached executed for other AI tool directories
  - git status shows these directories as untracked
  - Verification: git ls-files shows no matches
- Scope:
  - .agents/ directory
  - .beads/ directory
  - .augment/, .claude/, .cline/, .gemini/, .kilocode/, .openhands/, .qodo/ directories
  - agents/ directory (if present)
- Out of Scope:
  - Git history rewriting
  - Test fixtures (if clearly in test/ or fixtures/)
  - .gitignore updates (task 1)

IMPLEMENTATION CONSTRAINTS
- Use git rm --cached to remove from tracking only
- Do not delete actual files
- Preserve any files that are clearly test fixtures

VERIFICATION REQUIREMENTS
- Required commands:
  - git ls-files | grep "^.agents/"
  - git ls-files | grep "^.beads/"
  - git status --short

Commands run:
git rm --cached -r .agents/
git rm --cached -r .beads/
git rm --cached -r .augment/ .claude/ .cline/ .gemini/ .kilocode/ .openhands/

Verification:
git ls-files | grep '^.agents/' → no output
git ls-files | grep '^.beads/' → no output
git status --short → shows all files as deleted (D) - expected for untracked content

Total files untracked: .agents/ (1095 files), .beads/ (28 files), .augment/ (73 files), .claude/ (117 files), .cline/ (117 files), .gemini/ (3 files), .kilocode/ (117 files), .openhands/ (73 files)

No test fixtures were removed - all removed content was runtime artifacts (.agents/, .beads/, AI tool directories).


Both manuals include mandatory post-close memory review cadence and provenance relation commands/requirements.

AGENTS manuals now enforce regular memory additions and provenance relations

Update root and beadboard AGENTS manuals to require recurring memory additions and explicit provenance relation/metadata rules for canonical memory nodes.

Updated both AGENTS manuals: added mandatory post-close memory review cadence, provenance relation commands, required evidence_ids/plan_refs metadata, and fresh-agent provenance validation steps.

Enforce regular memory contribution + provenance relations in AGENTS manuals


TASK CONTEXT
- Bead ID: TBD
- Parent/Epic: beadboard-v5a

TASK CONTRACT
- Goal: Fix all critique findings from the cold-agent audit of skills/beadboard-driver. An agent anywhere must be able to load SKILL.md and become a power user without reading any BeadBoard source code.
- Success Criteria:
  - All 12 critique issues resolved with evidence.
  - Skill tested cold-agent style after fixes (follow runbook literally, zero prior knowledge).
  - Windows/WSL2 platform notes in place.
  - Heartbeat section accurately reflects turn-based LLM constraints.
  - No reference doc contradictions remain.
- Scope:
  - skills/beadboard-driver/SKILL.md
  - skills/beadboard-driver/references/*.md
  - No code changes to scripts or CLI unless a doc-fix requires it.
- Out of Scope:
  - Building the Witness/daemon (future epic).
  - Changing bd or bb CLI behavior.

[EPIC] BeadBoard Driver Skill: Remediation


All 4 runbook gaps fixed in SKILL.md; tests green

TASK CONTEXT
- Bead ID: beadboard-ilu.1
- Parent/Epic: beadboard-ilu
- Dependencies: none (first task, unblocks all others)

TASK CONTRACT
- Goal: Fix the five blocker-level and two high-priority mechanical gaps in SKILL.md that prevent a cold agent from completing the runbook.
- Success Criteria:
  - Install instructions for bd and bb added to Requirements (package names + exact install commands).
  - bb agent register step added immediately after bd create in Step 2, with BB_AGENT export shown.
  - Naming convention bridging bd bead ID and bb agent name stated explicitly (e.g. bead ID bb-silver-scribe, bb name silver-scribe, BB_AGENT=silver-scribe).
  - bd agent state <id> working added to Step 5 claim block — currently missing.
  - Hardcoded bead IDs beadboard-116 beadboard-60a beadboard-zas replaced with portable: bd query label=mem-canonical AND label=mem-hard AND status=closed.
- Scope: skills/beadboard-driver/SKILL.md only.
- Out of Scope: reference doc edits, conceptual framing, platform notes.

IMPLEMENTATION CONSTRAINTS
- Keep changes targeted to each gap. Do not reorganize sections.
- Preserve Iron Law, step numbering, Red Flags sections exactly.

VERIFICATION REQUIREMENTS
- Required commands:
  - node skills/beadboard-driver/tests/run-tests.mjs
- Required artifacts:
  - Cold-agent dry-run: follow revised SKILL.md literally from Requirements through Step 5 with no prior knowledge. Confirm no step fails or requires guessing.
- Report remaining risks and follow-up beads explicitly.

SKILL.md edits: 1a) added install commands to Requirements; 1b) added bb agent register block + naming convention in Step 2 (bd title uses bb-<role-name>); 1c) replaced hardcoded bead IDs with bd query canonical pattern; 1d) added bd agent state working after slot set in Step 5. Tests: 12/12 pass.

Fix SKILL.md runbook gaps (blockers + high)


All 3 conceptual framing gaps fixed in SKILL.md; tests green

TASK CONTEXT
- Bead ID: beadboard-ilu.2
- Parent/Epic: beadboard-ilu
- Dependencies: beadboard-ilu.1 (runbook must be settled before framing overlay)

TASK CONTRACT
- Goal: Add the missing conceptual context in SKILL.md so a zero-knowledge agent understands what BeadBoard is, why two CLIs exist, and what repo scope the skill applies to.
- Success Criteria:
  - What is BeadBoard paragraph (3 sentences max) added before Core Principle. Must cover: real-time dashboard for bd-backed agent work; surfaces liveness, state, swarm progress, mail; heartbeat/state/slots drive the UI display.
  - Paragraph under Step 6 explains the bd mail vs bb agent relationship: bd mail delegates to bb via the configured shim; always use bd mail; raw bb agent is the lower-level fallback when shim is not configured.
  - SKILL.md description corrected: either scope honestly to the BeadBoard repo, or document how the scripts folder is accessed from an external repo (abs path or env var strategy).
- Scope: skills/beadboard-driver/SKILL.md only.
- Out of Scope: Reference doc edits (beadboard-ilu.3). Runbook step mechanics (beadboard-ilu.1).

IMPLEMENTATION CONSTRAINTS
- One paragraph per gap — not a rewrite.
- Do not alter Iron Law, step numbering, or Red Flags sections.

VERIFICATION REQUIREMENTS
- Required commands:
  - node skills/beadboard-driver/tests/run-tests.mjs
- Required artifacts:
  - Cold-agent dry-run: read revised SKILL.md with no prior knowledge, confirm each conceptual question from the audit is answered without needing source code.
- Report remaining risks and follow-up beads explicitly.

SKILL.md edits: 2a) added 'What is BeadBoard' section before Iron Law; 2b) added bd mail vs bb agent explanation before mail commands in Step 6; 2c) fixed frontmatter description to reflect BeadBoard-internal operation. Tests: 12/12 pass.

Fix SKILL.md conceptual framing gaps


Reference doc inconsistencies fixed; bb agent send replaced with bd mail send throughout; project.md fields documented

TASK CONTEXT
- Bead ID: beadboard-ilu.3
- Parent/Epic: beadboard-ilu
- Dependencies: beadboard-ilu.2 (framing must be settled before cross-doc consistency pass)

TASK CONTRACT
- Goal: Eliminate contradictions and missing entries across all reference/*.md files so no doc sends an agent in a different direction than SKILL.md.
- Success Criteria:
  - session-lifecycle.md and agent-state-liveness.md blocked path changed from raw bb agent send to bd mail send, matching SKILL.md; or a clear annotation explains when each is appropriate.
  - Inbox polling cadence consolidated to one authoritative location in coordination-system.md; SKILL.md Step 6 and session-lifecycle.md point to it instead of restating it.
  - Use-The-Right-Doc Map in SKILL.md gains entry: references/archetypes-templates-swarms.md — Swarm and molecule concepts, worker join patterns, archetype contracts.
  - project.md step in SKILL.md Step 3 gains either minimum required fields inline or explicit link to skills/beadboard-driver/project.template.md with one-line description of each field.
- Scope:
  - skills/beadboard-driver/SKILL.md (Use-The-Right-Doc Map and Step 3 only)
  - skills/beadboard-driver/references/session-lifecycle.md
  - skills/beadboard-driver/references/agent-state-liveness.md
  - skills/beadboard-driver/references/coordination-system.md
- Out of Scope: Platform notes (beadboard-ilu.4). Heartbeat model changes (beadboard-ilu.5).

IMPLEMENTATION CONSTRAINTS
- Preserve all existing command examples; only correct inconsistencies, do not add new commands.
- Do not add new features or commands not already in the skill.

VERIFICATION REQUIREMENTS
- Required commands:
  - node skills/beadboard-driver/tests/run-tests.mjs
- Required artifacts:
  - Diff showing each changed file with the specific inconsistency before and after.
  - Confirm no reference doc contradicts SKILL.md on mail command choice.
- Report remaining risks and follow-up beads explicitly.

session-lifecycle.md: replaced bb agent send with bd mail send in BLOCKED path. agent-state-liveness.md: replaced bb agent send example and BLOCKED Signal Standard bullet 2. SKILL.md Step 3: added required project.md fields with exact names from template. Step 6: added pointer to coordination-system.md Inbox Polling Protocol. Tests: 12/12 pass.

Fix reference doc inconsistencies


Platform notes appendix added; Windows/WSL2 env var syntax, path formats, and binary detection covered

TASK CONTEXT
- Bead ID: beadboard-ilu.4
- Parent/Epic: beadboard-ilu
- Dependencies: beadboard-ilu.1 (runbook must be settled before platform overlay)

TASK CONTRACT
- Goal: Make the skill usable on native Windows and WSL2 without ambiguity about shell syntax and path formats.
- Success Criteria:
  - Platform Notes section added to SKILL.md (appendix after Use-The-Right-Doc Map) covering:
    - BB_AGENT export syntax: bash export, PowerShell dollar-env colon, and cmd set shown side by side in a table.
    - Mail delegate path format: WSL2 uses /mnt/c/... , native Windows uses C:\... — both shown explicitly.
    - Note that the preflight script checks for bd and bb availability; if it uses which internally it will fail on native Windows where where is the equivalent — user should verify preflight passes on their platform.
  - Step 1 (preflight) gains a one-line pointer: See Platform Notes appendix if running on Windows native or WSL2.
- Scope: skills/beadboard-driver/SKILL.md only.
- Out of Scope: Modifying preflight script or bb-mail-shim.mjs.

IMPLEMENTATION CONSTRAINTS
- Keep section concise — a three-row table is sufficient for env var syntax.
- Do not duplicate content already in AGENTS.md.

VERIFICATION REQUIREMENTS
- Required commands:
  - node skills/beadboard-driver/tests/run-tests.mjs
- Required artifacts:
  - Confirm a Windows-native agent following only SKILL.md would not hit an undocumented failure for export syntax, path format, or which vs where.
- Report remaining risks and follow-up beads explicitly.

SKILL.md: Step 1 gets pointer to Platform Notes appendix. Added Platform Notes section after Bottom Line with env var syntax table (bash/PowerShell/cmd), mail delegate path format table (WSL2/Windows native), and binary detection note. Tests: 12/12 pass.

Add platform notes for Windows and WSL2


Heartbeat cadence clarified for LLM vs daemon agents; Witness enforcement status documented

TASK CONTEXT
- Bead ID: beadboard-ilu.5
- Parent/Epic: beadboard-ilu
- Dependencies: beadboard-ilu.1, beadboard-ilu.2

TASK CONTRACT
- Goal: Make heartbeat and liveness docs honest about what turn-based LLM agents can and cannot do, without removing the feature or overpromising a Witness that is not yet running.
- Success Criteria:
  - SKILL.md Step 6 heartbeat entry gains a note: For LLM agents (Claude Code), heartbeat at turn start and before long-running commands only. The every-5-minutes cadence applies to persistent daemon-backed agents only.
  - references/agent-state-liveness.md Heartbeats section gains the same LLM vs daemon distinction.
  - One-sentence note added in both locations: The Witness enforcement layer that marks agents dead based on missed heartbeats is not yet running. Heartbeats are recorded and visible in the dashboard but not currently enforced automatically. Daemon implementation is a future epic.
  - Cadence table (5 min normal, 2-3 min high-risk) is retained but explicitly scoped to daemon agents only — not removed.
- Scope:
  - skills/beadboard-driver/SKILL.md Step 6 heartbeat block.
  - skills/beadboard-driver/references/agent-state-liveness.md Heartbeats section.
- Out of Scope: Building Witness or daemon. Changing bd agent heartbeat behavior. Removing heartbeat from skill.

IMPLEMENTATION CONSTRAINTS
- Two sentences max per addition. Do not expand into an essay.
- Use short labels LLM agents: and Daemon agents: as prefixes for scannability.

VERIFICATION REQUIREMENTS
- Required commands:
  - node skills/beadboard-driver/tests/run-tests.mjs
- Required artifacts:
  - A Claude Code agent reading the revised heartbeat section should immediately know what to do without reading source code.
- Report remaining risks and follow-up beads explicitly.

SKILL.md Step 6: added LLM vs daemon heartbeat distinction note + Witness not-yet-running caveat after heartbeat command. agent-state-liveness.md: replaced flat 'When to heartbeat' list with structured Daemon/LLM sections; added Witness current status note after Agent-side rule. Tests: 12/12 pass.

Clarify heartbeat for turn-based LLM agents


## EPIC CONTEXT
tools/bb.ts inside BeadBoard already implements a full bb agent coordination CLI (register, list, show, activity-lease, send, inbox, read, ack, reserve, release, status) backed by src/lib/agent-mail.ts, src/lib/agent-registry.ts, and src/lib/agent-reservations.ts. External agents cannot access this — it's internal to the BeadBoard repo. The global bb npm CLI (beadboard-cli.ts) only has start/open/status/doctor/uninstall.

## EPIC GOAL
Expose the existing coordination stack to: (1) external agents via the global bb CLI, (2) the BeadBoard frontend dashboard, and (3) bd mail delegate routing.

## SCOPE
- Wire bb agent commands into beadboard-cli.ts (global npm install)
- Add /api/agents/mail and /api/agents/reservations Next.js routes
- Add agent mail UI to Social/Activity views (inbox badge, HANDOFF/BLOCKED display)
- Configure bd mail to delegate to bb
- Tests + reference doc for v5 skill

## OUT OF SCOPE
- Rebuilding the coordination libs (already done)
- SSE live updates for mail (polling sufficient for v1)
- Sending messages from the UI (read/ack only in v1)

[EPIC] bb mail: BeadBoard-native coordination messaging


Completed read-only audit of 5 coordination source files and published integration contract on beadboard-izs.

## TASK CONTEXT
tools/bb.ts + src/lib/agent-mail.ts + agent-registry.ts + agent-reservations.ts + beadboard-cli.ts are the five source files that define what exists and what needs to be wired. Before writing any code, we need a precise integration map so izs.2 (global CLI), izs.3 (API routes), and izs.5 (bd mail delegate) all build toward the same contract.

## TASK CONTRACT
**Goal**: Produce an integration map documenting the existing coordination stack and specifying what each downstream izs task must build.

**Success Criteria**:
- All 5 source files read and annotated
- Storage paths confirmed: mail JSONL at ~/.beadboard/agent/messages/, reservations at ~/.beadboard/agent/reservations/active.json
- beadboard-cli.ts CLI framework identified (commander, minimist, etc.) and entry point documented
- API route contract written for /api/agents/mail and /api/agents/reservations (endpoints, request/response shape)
- Platform issues identified (Windows USERPROFILE vs Linux HOME path handling)
- Findings posted as bd comment on beadboard-izs

**Scope**:
- Read-only investigation of 5 source files
- Write audit findings as bd comment

**Out of Scope**:
- Any code changes
- Frontend or CLI implementation

## IMPLEMENTATION CONSTRAINTS
- Source files: tools/bb.ts, src/lib/agent-mail.ts, src/lib/agent-registry.ts, src/lib/agent-reservations.ts, beadboard-cli.ts (find in project root)

## VERIFICATION REQUIREMENTS
- bd comments list beadboard-izs shows audit findings comment
- API contract covers all CRUD operations for mail and reservations

Audit completed. Evidence: read tools/bb.ts, src/lib/agent-mail.ts, src/lib/agent-registry.ts, src/lib/agent-reservations.ts, src/cli/beadboard-cli.ts; posted integration contract comment to beadboard-izs via bd comments add beadboard-izs -f /tmp/beadboard-izs1-audit.md; verified via bd comments beadboard-izs --json. Memory review: no new reusable memory.

bb coord: audit existing stack + define integration contract


Already implemented — global bb CLI at /home/zenchant/.npm-global/bin/bb already exposes full bb agent command surface (register/list/show/activity-lease/send/inbox/read/ack/reserve/release/status). Verified via bb agent --help and live end-to-end test.

## TASK CONTEXT
The global bb npm CLI (beadboard-cli.ts) only handles start/open/status/doctor/self-update/uninstall. External agents (in any repo) need bb agent send/inbox/read/ack/register/list/show/activity-lease/reserve/release/status. The full implementation is in src/lib/agent-*.ts. This task ports the agent subcommand from tools/bb.ts into beadboard-cli.ts.

## TASK CONTRACT
**Goal**: Expose the full bb agent command surface through the globally-installed bb CLI.

**Success Criteria**:
- bb agent register --name foo --role ui works from any directory
- bb agent send --from foo --to bar --bead x --category INFO --subject y --body z works
- bb agent inbox --agent foo lists messages
- bb agent read --agent foo --message m marks as read
- bb agent ack --agent foo --message m acknowledges
- bb agent reserve/release/status work
- bb agent activity-lease --agent foo works
- Human-readable output by default, JSON with --json flag
- npm run build passes

**Scope**:
- Modify beadboard-cli.ts to add bb agent subcommand
- Import src/lib/agent-mail.ts, agent-registry.ts, agent-reservations.ts
- Port command routing and printResponse formatting from tools/bb.ts

**Out of Scope**:
- Changes to the lib implementations
- Frontend routes

## IMPLEMENTATION CONSTRAINTS
- Use the audit from izs.1 to understand beadboard-cli.ts structure before modifying
- Port tools/bb.ts agent command routing exactly — do not redesign the API surface
- Must work on Windows, WSL, and Linux

## VERIFICATION REQUIREMENTS
- npm run build or equivalent passes
- bb agent list returns empty list (no crash) from a fresh test run
- bb agent register --name test-coord --role test succeeds then bb agent show --agent test-coord returns record

Implemented bb agent subcommand routing in src/cli/beadboard-cli.ts (ported tools/bb.ts command surface and response formatting). Added CLI contract test in tests/cli/beadboard-cli.test.ts. Verification evidence: node --import tsx --test tests/cli/beadboard-cli.test.ts tests/cli/beadboard-help-output.test.ts tests/cli/beadboard-bin-routing.test.ts (pass, 7/7); node bin/beadboard.js agent list --json (ok true, command=agent list); node bin/beadboard.js agent register --name test-coord-izs2 --role test --json (ok true); node bin/beadboard.js agent show --agent test-coord-izs2 --json (ok true); npm run lint (exit 0, warnings only). Memory review: no new reusable memory.

bb coord: wire bb agent commands into global bb CLI


Added /api/agents/mail and /api/agents/reservations routes with read/ack compatibility endpoints and validated response contracts.

## TASK CONTEXT
BeadBoard's dashboard needs to display agent coordination data. The libs in src/lib/agent-*.ts have all the business logic; they just need Next.js API routes to expose them to the browser. The API contract is defined in izs.1.

## TASK CONTRACT
**Goal**: Create Next.js API routes for agent mail and reservations that the frontend can call.

**Success Criteria**:
- GET /api/agents/mail?agent=<id>&state=<unread|read|acked> returns inbox messages
- POST /api/agents/mail body {from, to, bead, category, subject, body, thread?} creates message
- POST /api/agents/mail/read body {agent, message} marks as read
- POST /api/agents/mail/ack body {agent, message} acknowledges message
- GET /api/agents/reservations?agent=<id> returns active reservations + unacked_required_messages
- Error shape matches existing routes: {ok: false, error: {code, message}}
- npm run typecheck passes

**Scope**:
- New files: src/app/api/agents/mail/route.ts, src/app/api/agents/reservations/route.ts
- Import and call src/lib/agent-mail.ts and src/lib/agent-reservations.ts functions

**Out of Scope**:
- Frontend UI (izs.4)
- SSE streaming for mail
- Auth beyond existing patterns in the codebase

## IMPLEMENTATION CONSTRAINTS
- Read existing routes in src/app/api/beads/ and src/app/api/agents/ for patterns before writing
- Use NextResponse for all responses
- Check izs.1 audit for confirmed API contract before implementing

## VERIFICATION REQUIREMENTS
- npm run typecheck clean
- curl localhost:3000/api/agents/mail?agent=nonexistent returns {ok: false, error: {code: "AGENT_NOT_FOUND", ...}}
- npm run lint clean

Implemented agent coordination API routes: src/app/api/agents/mail/route.ts and src/app/api/agents/reservations/route.ts with NextResponse JSON envelopes and normalized error shape {ok:false,error:{code,message}}. Added compatibility endpoints src/app/api/agents/mail/read/route.ts and src/app/api/agents/mail/ack/route.ts. Added route contract tests in tests/api/agents-mail.test.ts (missing-agent and validation flows). Verification evidence: node --import tsx --test tests/api/agents-mail.test.ts (4/4 pass); npm run typecheck (pass); npm run lint (exit 0, warnings only). Memory review: no new reusable memory.

bb coord: frontend API routes (/api/agents/mail + /api/agents/reservations)


Added Social/Activity coordination badges, inline inbox visibility, ack actions, and reservation labels using new agent APIs.

## TASK CONTEXT
The Social lens and Activity panel in UnifiedShell need to surface agent coordination state: unread message count per agent, HANDOFF/BLOCKED urgency badges, and active reservation scope labels. This makes BeadBoard the primary coordination dashboard for multi-agent sessions.

## TASK CONTRACT
**Goal**: Add agent mail and reservation visibility to the Social and Activity views in the BeadBoard dashboard.

**Success Criteria**:
- Agent cards in Social view show unread message count badge (fetched from /api/agents/mail)
- HANDOFF/BLOCKED messages show amber/red badge (urgent); INFO/DECISION show neutral
- Clicking badge shows inline message list with subject, body, category, state, from_agent
- Ack button on HANDOFF/BLOCKED messages (calls POST /api/agents/mail/ack)
- Activity panel shows recent coordination events (sends, acks) in telemetry feed
- Agent card shows active reservation scope as label (from /api/agents/reservations)
- npm run typecheck and npm run lint pass

**Scope**:
- Update src/components/social/ (agent card or social-page.tsx)
- Update src/components/activity/activity-panel.tsx for coordination events
- Fetch from API routes created in izs.3

**Out of Scope**:
- Composing new messages from UI (read/ack only in v1)
- SSE live push for mail — polling with SWR or manual refresh is fine
- New npm dependencies

## IMPLEMENTATION CONSTRAINTS
- Use existing shadcn/ui primitives from components/ui/
- Follow Tailwind patterns from src/components/social/social-page.tsx
- AgentAvatar component at src/components/shared/agent-avatar.tsx is the anchor for badges
- Check CLAUDE.md: src/components/shared/unified-shell.tsx is the root layout — understand view structure before modifying

## VERIFICATION REQUIREMENTS
- npm run typecheck && npm run lint pass
- Dev server: agent cards show message badge when unread messages exist in ~/.beadboard/agent/messages/
- HANDOFF category badge is visually distinct from INFO

Implemented coordination UI in Social/Activity surfaces. Social: src/components/social/social-page.tsx now polls /api/agents/mail and /api/agents/reservations per visible agent, computes unread badges and reservation labels, and wires ack action via /api/agents/mail/ack. SocialCard: src/components/social/social-card.tsx now renders per-agent unread badges, reservation scope chips, inline message list (subject/body/category/state/from_agent), and Ack button for requires_ack categories. Activity: src/components/activity/activity-panel.tsx now augments telemetry with coordination events (coord_send/coord_ack derived from mail API) and displays reservation scope chips per agent card. Verification evidence: npm run typecheck (pass); npm run lint (exit 0, warnings only). Manual-browser verification not run in this session. Memory review: no new reusable memory.

bb coord: frontend UI — agent mail inbox + reservation badges


Configured bd mail delegate via session preflight and added bb mail shim with verified routing and fallback error behavior.

## TASK CONTEXT
bd mail is designed as a delegate — it shells out to a configured external provider via BEADS_MAIL_DELEGATE env var or bd config set mail.delegate. The bb CLI (now with bb agent send/inbox via izs.2) is the natural delegate for BeadBoard environments. This task wires bd mail → bb agent so agents using bd mail transparently use the BeadBoard coordination stack.

## TASK CONTRACT
**Goal**: Configure bd mail to delegate to bb agent commands so the session-preflight script automatically sets up mail routing.

**Success Criteria**:
- bd config set mail.delegate bb (or equivalent) documented and working
- .agents/skills/beadboard-driver/scripts/session-preflight.mjs runs the delegate config command on startup
- bd mail send --to foo --bead x --subject y --body z routes through bb agent send
- Fallback: if bb not installed, bd mail fails with helpful error (not silent failure)
- help/cli/bd_help.txt mail section read and delegate mechanism confirmed before implementing

**Scope**:
- Update session-preflight.mjs to configure bd mail delegate
- Read help/cli/bd_help.txt to confirm exact bd mail delegate config syntax
- Document delegate config in bd comment on izs.5

**Out of Scope**:
- Changes to bd internals
- Building an alternate mail system
- project.template.md update (tracked in maf.9)

## IMPLEMENTATION CONSTRAINTS
- Read help/cli/bd_help.txt mail section BEFORE configuring — do not assume flag names
- Check BEADS_MAIL_DELEGATE env var as alternative to bd config

## VERIFICATION REQUIREMENTS
- node scripts/session-preflight.mjs completes without error
- bd mail send routes to bb after preflight runs
- bd mail without bb installed produces useful error

Implemented delegate wiring in skills/beadboard-driver/scripts/session-preflight.mjs and added skills/beadboard-driver/scripts/bb-mail-shim.mjs translating bd mail inbox/send/read/ack into bb agent commands. Added tests: tests/skills/beadboard-driver/session-preflight.test.ts and tests/skills/beadboard-driver/bb-mail-shim.test.ts. Verification evidence: node --import tsx --test tests/skills/beadboard-driver/session-preflight.test.ts tests/skills/beadboard-driver/bb-mail-shim.test.ts (3/3 pass); node skills/beadboard-driver/scripts/session-preflight.mjs (ok true, mail.configured=true); integration check with fake bb: bd mail inbox invoked bb args 'agent inbox --agent silver-scribe'; PATH=/usr/bin:/bin BB_AGENT=silver-scribe node skills/beadboard-driver/scripts/bb-mail-shim.mjs inbox -> 'bb command not found in PATH'. Memory review: no new reusable memory.

bb coord: bd mail delegate configuration + session-preflight wiring


Added and enumerated coordination integration tests across registry, reservations, API routes, and delegate shim with full gate verification.

## TASK CONTEXT
The global CLI (izs.2), API routes (izs.3, izs.4), and bd mail delegate (izs.5) all need contract tests. Tests must follow the existing Node.js native test runner with tsx loader pattern. All test files must be explicitly added to the test script in package.json.

## TASK CONTRACT
**Goal**: Add tests covering the full coordination stack integration surfaces.

**Success Criteria**:
- tests/lib/agent-mail.test.ts covers send/inbox/read/ack flows and broadcast routing
- tests/lib/agent-registry.test.ts covers register/show/list/activity-lease
- tests/lib/agent-reservations.test.ts covers reserve/release/status, conflict detection (active blocks, stale warns)
- tests/api/agents-mail.test.ts covers API route smoke tests (valid request, missing agent error)
- All 4 test files added to test script in package.json
- npm run test exits 0

**Scope**:
- New test files in tests/lib/ and tests/api/
- package.json test script updated

**Out of Scope**:
- Frontend component tests
- E2E browser tests
- Testing bd internals

## IMPLEMENTATION CONSTRAINTS
- Tests use node:test native runner with tsx loader: node --import tsx --test <file>
- No jest or vitest — native test runner only (existing pattern in tests/)
- Mock runBdCommand in registry tests (avoid requiring live bd process)
- Check tests/ directory for existing patterns before writing

## VERIFICATION REQUIREMENTS
- npm run test exits 0
- All 4 new test files listed in package.json test script
- npm run typecheck passes on test files

Expanded coordination tests and wired explicit test enumeration. Updated tests/lib/agent-registry.test.ts to cover register/show/list/activity-lease paths with backend-resilient assertions; updated tests/lib/agent-reservations.test.ts with active-owner conflict test; updated tests/api/agents-mail.test.ts with route smoke and error-shape checks including success status path for reservations; added tests/skills/beadboard-driver/bb-mail-shim.test.ts and registered it in package.json. Updated package.json test script to include tests/lib/agent-registry.test.ts, tests/api/agents-mail.test.ts, tests/skills/beadboard-driver/bb-mail-shim.test.ts. Verification evidence: node --import tsx --test tests/lib/agent-registry.test.ts tests/lib/agent-reservations.test.ts tests/api/agents-mail.test.ts tests/skills/beadboard-driver/bb-mail-shim.test.ts (16/16 pass); npm run typecheck (pass); npm run lint (exit 0, warnings only); npm run test (full suite pass). Memory review: no new reusable memory.

bb coord: tests — global CLI, API routes, mail contract