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

docs(beads): etch project history into memory bank and finalize skill-bb

Browse source 
We completed the 'Deep Metadata Etch' today, transforming our Beads issues from simple trackers into a permanent narrative of our collaboration.

Triumphs:
- Exhaustively updated all epic and sub-task descriptions with technical implementation reports and 'Execution Tales'.
- Finalized the 'bb' agent CLI skill (bb.ps1), providing a reliable, path-safe interface for cross-agent communication.
- Published ADR-001 and RFC-001 to document our coordination protocols.
- Fixed the 'missing closed issues' bug across all pages by enforcing --all and --limit 0 in read-issues.ts.

Raw Honest Moment:
We realized our 'Memory Bank' was initially too shallow. We went back and re-wrote descriptions for over 15 beads to ensure that future AI agents (and human maintainers) understand not just *what* we built, but *why* we chose specific architectural trade-offs. This commit represents our commitment to documentation as a first-class citizen of engineering.
This commit is contained in:
zenchantlive 2026-02-14 00:21:25 -08:00
parent bfe4f853f0
commit c7c3a25457
27 changed files with 2376 additions and 137 deletions
Download patch file Download diff file Expand all files Collapse all files

122
docs/adr/2026-02-14-beadboard-driver-skill-and-bb-resolution.md Normal file
View file

@ -0,0 +1,122 @@
# ADR: Beadboard Driver Skill and `bb` Resolution Model
- Date: 2026-02-14
- Status: Accepted
- Scope: `bb-dcv` closeout (`bb-dcv.8`, `bb-dcv.3`)
## Context
Agent coordination required a reusable skill that works across sessions and environments, with deterministic behavior and verification evidence. Existing constraints:
- `bd` is the source of truth for task lifecycle (`ready`, `update`, `close`, deps).
- `bb` is the coordination layer (identity, mail, reservations).
- No direct writes to `.beads/issues.jsonl`.
- Evidence before completion claims.
Operational issue discovered during verification:
- `bb.ps1` depended on current working directory and broke when called outside repo.
- PowerShell argument forwarding through wrapper was unreliable.
## Decision
We implemented a new skill package `skills/beadboard-driver` with a strict policy:
1. Path resolution
- `BB_REPO` is authoritative when set.
- Resolution order: `BB_REPO` -> global `bb` -> user cache -> bounded discovery.
- If `BB_REPO` is set but invalid, fail fast with remediation.
- Never mutate shell profile or environment variables automatically.
- Cache path only after successful verification.
2. Identity policy
- One unique identity per session.
- Adjective-noun naming with collision retry.
- Register identity before coordination commands.
- Keep bead claim authority in `bd`, not `bb`.
3. Verification policy
- Dual test harness:
- Repo-level tests under `tests/skills/beadboard-driver`.
- Skill-local runner under `skills/beadboard-driver/tests`.
- Skill quick validation required.
- Full repo gates required: `typecheck`, `lint`, `test`.
4. Wrapper reliability
- Fixed `bb.ps1` to use script-relative entrypoint and arg splatting so Windows invocation works from any terminal when called by path.
## Implementation
### New skill artifacts
- `skills/beadboard-driver/SKILL.md`
- `skills/beadboard-driver/agents/openai.yaml`
- `skills/beadboard-driver/scripts/lib/driver-lib.mjs`
- `skills/beadboard-driver/scripts/resolve-bb.mjs`
- `skills/beadboard-driver/scripts/session-preflight.mjs`
- `skills/beadboard-driver/scripts/generate-agent-name.mjs`
- `skills/beadboard-driver/scripts/readiness-report.mjs`
- `skills/beadboard-driver/references/command-matrix.md`
- `skills/beadboard-driver/references/failure-modes.md`
- `skills/beadboard-driver/references/session-lifecycle.md`
- `skills/beadboard-driver/tests/run-tests.mjs`
- `skills/beadboard-driver/tests/*.contract.test.mjs`
### Repo-level test enforcement
- `tests/skills/beadboard-driver/resolve-bb.test.ts`
- `tests/skills/beadboard-driver/generate-agent-name.test.ts`
- `tests/skills/beadboard-driver/session-preflight.test.ts`
- `tests/skills/beadboard-driver/readiness-report.test.ts`
- `tests/skills/beadboard-driver/skill-local-runner.test.ts`
- `package.json` `test` script updated to include all above.
### CLI wrapper fix
- `bb.ps1` updated to:
- resolve `tools/bb.ts` via `$MyInvocation` script directory
- forward args via `@args`
### Type safety remediation
- `tools/bb.ts` updated with explicit arg coercion helpers to satisfy strict typecheck.
## Verification Evidence
Skill-specific:
- `quick_validate.py skills/beadboard-driver` -> pass
- `node --import tsx --test tests/skills/beadboard-driver/*.test.ts` -> pass
- `node skills/beadboard-driver/tests/run-tests.mjs` -> pass
Full repo gates:
- `npm run typecheck` -> pass
- `npm run lint` -> pass (0 errors)
- `npm run test` -> pass (full suite including new skill tests)
Windows `bb` execution:
- `& "C:\Users\Zenchant\codex\beadboard\bb.ps1" agent list --json` -> pass
- `& "$env:BB_REPO\bb.ps1" agent list --json` (with valid `BB_REPO` in same shell) -> pass
## Consequences
Positive:
- Agents can run a deterministic coordination workflow with explicit recovery behavior.
- Skill behavior is testable and enforced by CI path.
- Windows path invocation of `bb` is reliable by absolute or `BB_REPO` path.
Tradeoffs:
- No global `bb` package installation is provided by this ADR; direct `bb` command still requires user alias/install.
- Session/timeline UI validation remains dependent on upstream epic sequencing.
## Follow-up
`bb-dcv` is closed. `bb-u6f` remains open and depends on open `bb-xhm` (timeline/event model).
Next required order for frontend visibility of agent sessions:
1. complete `bb-xhm`
2. implement `bb-u6f`

165
docs/agent-session-flow.md Normal file
View file

@ -0,0 +1,165 @@
# Agent Session Flow & Operator Guide
This document defines the canonical workflow for human operators using `bb agent` to coordinate work in the Beadboard repo.
## Core Principle: Two Sources of Truth
1. **Work Lifecycle**: `bd` (Beads) is the ONLY source of truth for what work is happening (`in_progress`, `done`, dependencies).
2. **Coordination**: `bb agent` is the source of truth for *who* is doing it and *how* they are coordinating (reservations, handoffs).
**Rule**: Never write to `.beads/issues.jsonl` directly. Always use `bd` commands.
## Session Lifecycle
### 1. Identity Check (Start of Session)
Before claiming work, ensure your agent identity is registered and active.
```bash
# Check if you are registered
bb agent show --agent agent-ui-1
# If not, register (idempotent, use --force-update to change role/display)
bb agent register --name agent-ui-1 --role ui --display "UI Agent 1"
```
### 2. Picking and Claiming Work
Use `bd` to find and claim work. This is the "clock in" event.
```bash
# 1. Find ready work (unblocked)
bd ready
# 2. Inspect the bead
bd show bb-dcv.5
# 3. CLAIM the bead (Atomic Claim)
# This sets status=in_progress AND assigns it to you in one atomic op.
bd update bb-dcv.5 --status in_progress --notes "Starting docs work" --claim
```
### 3. Coordination (During Work)
While working, use `bb agent` to coordinate with other agents or reserve contested resources.
#### Reservations (Traffic Control)
Prevent collisions on shared files or subsystems.
```bash
# Reserve a scope (default TTL 120m)
bb agent reserve --agent agent-ui-1 --bead bb-dcv.5 --scope "src/components/graph/*"
# Check status of your reservation
bb agent status --bead bb-dcv.5
```
#### Communication (Handoffs & Blockers)
Send structured signals to other agents.
```bash
# BLOCKER: Request help
bb agent send \
--from agent-ui-1 \
--to agent-backend-1 \
--bead bb-dcv.5 \
--category BLOCKED \
--subject "API 404 on /b/users" \
--body "Endpoint missing. Blocking UI integration."
# HANDOFF: Pass context
bb agent send \
--from agent-ui-1 \
--to agent-qa-1 \
--bead bb-dcv.5 \
--category HANDOFF \
--subject "Ready for verification" \
--body "UI complete. Verify at /graph and /kanban."
```
#### Checking Mail
```bash
# Check inbox
bb agent inbox --agent agent-ui-1 --state unread
# Read a message (marks as read)
bb agent read --agent agent-ui-1 --message msg_id_123
# Acknowledge a message (required for HANDOFF/BLOCKED)
bb agent ack --agent agent-ui-1 --message msg_id_123
```
### 4. Completion (End of Session)
Wrap up the session cleanly.
1. **Release Reservations**:
```bash
# Release specific scope
bb agent release --agent agent-ui-1 --scope "src/components/graph/*"
```
2. **Update Bead Status**:
```bash
# Post evidence/results
bd update bb-dcv.5 --notes "Docs created. Validation passed."
# Close the bead
bd close bb-dcv.5 --reason "Completed all acceptance criteria"
```
## UX & Output Formats
All `bb agent` commands support human-friendly output (default) and machine-readable JSON.
### Human Format (Default)
Optimized for operator readability.
```text
$ bb agent register --name agent-ui-1 --role ui
✓ Agent registered: agent-ui-1 (role: ui)
```
### JSON Format (`--json`)
Optimized for tool parsing. Always returns a standard envelope.
```bash
$ bb agent register --name agent-ui-1 --role ui --json
```
```json
{
"ok": true,
"command": "agent register",
"data": {
"agent_id": "agent-ui-1",
"role": "ui",
"status": "idle",
...
},
"error": null
}
```
### Error Handling
Errors always return `ok: false` with a stable error code.
```json
{
"ok": false,
"command": "agent send",
"data": null,
"error": {
"code": "UNKNOWN_RECIPIENT",
"message": "Agent 'ghost-1' not found"
}
}
```
## Anti-Patterns (Don't Do This)
1. **Ghosting**: Claiming a bead but not registering an agent identity.
2. **Squatting**: Holding a reservation (`--ttl 1440`) while not actively working.
3. **Bypassing**: Writing to `issues.jsonl` directly instead of using `bd`.
4. **Zombie Claims**: Forgetting to `bd close` or `bd update --status todo` when stopping work.

29
docs/features/timeline.md Normal file
View file

@ -0,0 +1,29 @@
# Timeline & Activity Feed
## Overview
The Timeline view (`/timeline`) provides a real-time, chronological feed of project activity. It consumes events streamed from the backend via Server-Sent Events (SSE).
## Features
- **Real-time Updates:** New events appear instantly without page refresh.
- **Date Grouping:** Events are grouped by day (Today, Yesterday, etc.).
- **Polymorphic Cards:** Distinct visual styles for different event types (Status, Lifecycle, Diff).
- **History Buffer:** The server maintains a memory buffer of recent events to populate the feed on load.
## Architecture
- **Backend:**
- `ActivityEventBus` (in `src/lib/realtime.ts`) buffers recent events and handles subscriptions.
- `IssuesWatchManager` (in `src/lib/watcher.ts`) runs `diffSnapshots` on `issues.jsonl` changes and emits to the bus.
- API: `GET /api/activity` (history) and `GET /api/events` (SSE stream).
- **Frontend:**
- `TimelineStore` (Zustand) manages the event list and filters.
- `EventCard` renders the UI using "Aero Chrome" styling.
## Supported Events
Currently, the timeline tracks changes to `issues.jsonl`:
- Created / Closed / Reopened
- Status changes
- Assignee changes
- Priority / Title / Description changes
- Label / Dependency changes
*Note: Comment interactions are not yet streamed to the timeline.*

278
docs/plans/2026-02-13-agent-sessions-ux-v1.md Normal file
View file

@ -0,0 +1,278 @@
# Plan: Agent Sessions UX v1 (Task-First Social Feed, Epic-Organized) + Next-Session Execution Prompt
## Summary
Implement bb-u6f as a distinct “session operations” surface with this locked UX model:
- Information architecture: Epic Buckets -> Sortable Task Feed -> Conversation Drawer
- Interaction style: social-thread feel on each task/session card (Facebook-group-like), but operationally
strict
- Communication language: plain labels (Passed to, Needs input, Seen, Accepted)
- Write scope v1: Read + light write only (bd comments + bb read/ack), not full bb send/reserve composer
- Core requirement: users can sort tasks easily, click any task, view conversation context, and add comments/ack
actions inline
This keeps one coherent page model (no lane clutter) while making communication prominent and auditable.
———
## Current State (Grounded Facts)
- Timeline foundation exists and is implemented (/timeline, activity bus, activity API).
- bb-xhm.1/.2/.3 are closed, so timeline dependency work is technically done.
- bb-u6f.1/.2/.3 remain open and are the right implementation target.
- Agent communication backend exists (agent-registry, agent-mail, agent-reservations), with tested command
handlers.
- bb CLI now supports discoverable help and stable invocation patterns.
———
## UX/Product Spec (Decision Complete)
## 1. Primary Page
- New route: /sessions
- Top area:
- Session hero title/subtitle
- Epic bucket chips (default = “All Epics”)
- Sort controls
- Live summary pills: In Progress, Needs Input, Waiting Seen/Accepted, Idle Agents
- Main area:
- Task/session feed cards (single-column mobile, two-column desktop)
- Drilldown:
- Right-side (desktop) / bottom-sheet (mobile) conversation drawer for selected task
## 2. Feed Card Structure
Each card represents one task in session context:
- Task identity: id, title, epic, priority
- Work status: open/in_progress/blocked/deferred/closed (existing truth from bd)
- Session state (derived): Active, Reviewing, Deciding, Needs Input, Completed, Stale
- Agent context:
- current owner/assignee
- last actor
- last activity timestamp
- Communication summary:
- unread count
- pending required Seen/Accepted
- latest thread snippet
- Quick actions:
- Open conversation
- Add comment (bd comment)
- Mark Seen / Accepted on selected required message
## 3. Conversation Drawer
- Header:
- task id/title + current state chips
- Body:
- chronological thread items (task-related communication + key activity entries)
- Composer area (v1):
- Add comment (writes via existing beads comment API)
- Seen / Accepted buttons for required messages (writes via agent-mail read/ack API wrappers)
- Not in v1:
- full bb send composer
- reservation create/release controls
## 4. Plain-Language Label Mapping
Use UI-only mappings while preserving underlying protocol values:
- HANDOFF -> Passed to
- BLOCKED -> Needs input
- ACK required -> Seen / Accepted
- INFO -> Update
———
## Important API / Interface Additions
## 1. New Session Aggregation Library
- File: src/lib/agent-sessions.ts
- Exports:
- AgentSessionState union: active | reviewing | deciding | needs_input | completed | stale
- SessionTaskCard interface
- buildSessionTaskFeed(issues, activityEvents, communicationSummary) -> SessionTaskCard[]
- Rules:
- Group primarily by task (bead id) under epic buckets
- derive state from status + recent activity + pending ack-required messages
## 2. New API Endpoints
- GET /api/sessions
- Returns epic-grouped, sortable task feed payload
- Query params:
- epic (optional)
- sort (recent|priority|needs_input|owner)
- projectRoot (optional)
- GET /api/sessions/:beadId/conversation
- Returns conversation timeline for one task
- Includes:
- relevant activity events
- related agent-mail messages
- POST /api/sessions/:beadId/comment
- Proxy to existing beads comment route
- POST /api/sessions/:beadId/messages/:messageId/read
- POST /api/sessions/:beadId/messages/:messageId/ack
- Wrap readAgentMessage/ackAgentMessage
## 3. Frontend Components
- src/app/sessions/page.tsx
- src/components/sessions/sessions-page.tsx
- src/components/sessions/session-feed-card.tsx
- src/components/sessions/conversation-drawer.tsx
- src/components/sessions/sessions-filters.tsx
- Reuse: workspace-hero, epic-chip-strip, shared stat/chip primitives
———
## Data Flow
1. Server loads project-scoped issues + activity history + communication summary.
2. buildSessionTaskFeed derives card model.
3. Client renders epic bucket + sorted feed.
4. Selecting a card fetches conversation endpoint.
5. Comment/read/ack actions call session endpoints; optimistic update local drawer/feed state.
6. SSE activity updates prepend to session feed and refresh affected card state.
———
## Edge Cases / Failure Modes (Must Implement)
1. Task has no communication history: show “No conversation yet” empty state.
2. Message flood: collapse older thread items with “show more.”
3. Conflicting reactions (Accepted + Needs changes semantics): show conflict chip.
4. Stale tasks: mark stale when no activity above threshold.
5. Missing owner: warning badge Unassigned.
6. Cross-epic ambiguity: fall back to “Uncategorized” bucket.
7. Broken communication read/ack call: non-destructive error toast, no status corruption.
8. SSE disconnection: fallback polling + reconnection indicator.
9. Unknown protocol category: display as generic Update.
———
## Testing & Verification Plan
## Unit Tests
- tests/lib/agent-sessions.test.ts
- state derivation rules
- bucket grouping by epic
- sort behavior
- plain-language mapping
## API Tests
- tests/api/sessions-route.test.ts
- /api/sessions filters/sorts
- conversation payload shape
- comment/read/ack endpoints success + error paths
## UI/Behavior Tests
- tests/components/sessions/*.test.tsx (or existing project pattern equivalent)
- feed render
- drawer open/close
- action button behavior
- plain labels rendered
## Gate Commands
- npm run typecheck
- npm run lint
- npm run test
———
## Bead Sequencing / Dependency Hygiene
1. Verify/repair stale blockers:
- update bb-u6f dependency on bb-xhm to reflect closed timeline tasks if needed.
2. Execute in order:
- bb-u6f.1 (data model + aggregation)
- bb-u6f.2 (session feed UI + conversation drawer)
- bb-u6f.3 (metrics overlays)
3. Close bb-u6f only after full gates pass and notes include evidence.
———
## Assumptions / Defaults
- Existing timeline/activity infrastructure remains source for historical events.
- bd remains lifecycle authority; session UI does not bypass bead mutation constraints.
- Communication prominence is achieved through conversation drawer + card summary, not a separate inbox app.
- v1 write scope is intentionally limited to comment/read/ack.
———
## Ready-to-Paste Next-Session Prompt
You are taking over bb-u6f implementation in C:\Users\Zenchant\codex\beadboard on branch feat/ui-polish-aero-
chrome.
Non-negotiables:
- No direct writes to .beads/issues.jsonl
- Use bd for lifecycle writes and existing API wrappers for comment/read/ack
- Keep UX distinct from Kanban/Graph; this is a session operations page
- Communication must be prominent and plain-language (no HANDOFF/BLOCKED/ACK jargon shown raw)
- Evidence before assertions (run gates before close claims)
Build target:
- New /sessions page with Epic Buckets -> Sortable Task Feed -> Conversation Drawer
- Feed cards are task/session objects with work status + communication summary
- Drawer shows thread + light write actions:
- add bd comment
- mark message Seen / Accepted (read/ack)
Implement files:
- src/lib/agent-sessions.ts
- src/app/api/sessions/route.ts
- src/app/api/sessions/[beadId]/conversation/route.ts
- src/app/api/sessions/[beadId]/comment/route.ts
- src/app/api/sessions/[beadId]/messages/[messageId]/read/route.ts
- src/app/api/sessions/[beadId]/messages/[messageId]/ack/route.ts
- src/app/sessions/page.tsx
- src/components/sessions/* (page, card, drawer, filters)
Label mapping (UI):
- HANDOFF => Passed to
- BLOCKED => Needs input
- required ack => Seen / Accepted
- INFO => Update
Edge handling required:
- empty conversation
- stale sessions
- unassigned task
- SSE disconnect fallback
- unknown message category safe render
Tests required:
- tests/lib/agent-sessions.test.ts
- tests/api/sessions-route.test.ts
- session component behavior tests per existing project pattern
Execution order:
1. claim bb-u6f.1 and implement aggregation + tests
2. claim bb-u6f.2 and implement page/drawer + tests
3. claim bb-u6f.3 and implement metrics + tests
4. run:
- npm run typecheck
- npm run lint
- npm run test
5. post evidence in bead notes, then close beads in dependency order
Before closing anything:
- verify bb-u6f dependency bookkeeping is accurate (timeline blocker stale check)
- include exact command outputs in notes

322
docs/plans/2026-02-13-bb-agent-cli-contract.md Normal file
View file

@ -0,0 +1,322 @@
# bb agent CLI Contract (bb-dcv.2)
Date: 2026-02-13
Owner: `bb-dcv.2`
Status: Draft implementation contract
## 1) Scope
Define exact command and data contracts for the thin coordination layer:
1. `register`, `list`, `show`
2. `send`, `inbox`, `read`, `ack`
3. `reserve`, `release`, `status`
Out of scope:
1. Beads lifecycle/dependency mutation semantics.
2. MCP transport.
3. Skill packaging (`bb-dcv.8`).
## 2) System Boundary
Source of truth split:
1. `bd` owns issue lifecycle, status, dependencies, and claim.
2. `bb agent` owns coordination metadata (identity, messages, reservations).
Hard rule:
1. No direct writes to `.beads/issues.jsonl`.
## 3) Root Paths and Storage
Root:
1. `.beadboard/agent/`
Layout:
1. `.beadboard/agent/agents/<agent_id>.json`
2. `.beadboard/agent/messages/<agent_id>.jsonl` (recipient inbox stream)
3. `.beadboard/agent/messages/index/<message_id>.json` (message metadata)
4. `.beadboard/agent/reservations/active.json`
5. `.beadboard/agent/reservations/history.jsonl`
File semantics:
1. `*.json` files are full-state snapshots.
2. `*.jsonl` files are append-only event logs.
3. Timestamps use UTC ISO-8601.
## 4) Common CLI Conventions
Output modes:
1. Human-readable default.
2. `--json` machine-readable.
Common JSON response envelope:
```json
{
"ok": true,
"command": "agent send",
"data": {},
"error": null
}
```
Error envelope:
```json
{
"ok": false,
"command": "agent send",
"data": null,
"error": {
"code": "UNKNOWN_RECIPIENT",
"message": "Recipient agent is not registered."
}
}
```
## 5) Identity Commands
### 5.1 `bb agent register`
Input:
1. `--name <agent_id>` required.
2. `--display <display_name>` optional.
3. `--role <role>` required.
4. `--force-update` optional (updates display/role only; never renames id).
Validation:
1. `agent_id` regex: `^[a-z0-9]+(?:-[a-z0-9]+)*$`.
2. `agent_id` length: 3..48.
3. `role` non-empty.
Behavior:
1. Create new agent if not present.
2. If present and no `--force-update`, fail with `DUPLICATE_AGENT_ID`.
3. Set `status=idle` on create.
Stored schema (`agents/<agent_id>.json`):
```json
{
"agent_id": "agent-ui-1",
"display_name": "UI Agent 1",
"role": "ui",
"status": "idle",
"created_at": "2026-02-13T22:00:00.000Z",
"last_seen_at": "2026-02-13T22:00:00.000Z",
"version": 1
}
```
### 5.2 `bb agent list`
Input:
1. `--role <role>` optional filter.
2. `--status <status>` optional filter.
Output:
1. Sorted by `agent_id` asc.
### 5.3 `bb agent show`
Input:
1. `--agent <agent_id>` required.
Errors:
1. `AGENT_NOT_FOUND`.
## 6) Messaging Commands
Message categories:
1. `HANDOFF`
2. `BLOCKED`
3. `DECISION`
4. `INFO`
Ack policy:
1. Required for `HANDOFF`, `BLOCKED`.
2. Optional for `DECISION`, `INFO`.
Message schema:
```json
{
"message_id": "msg_20260213_220001_7f3c",
"thread_id": "bead:bb-dcv.6",
"bead_id": "bb-dcv.6",
"from_agent": "agent-ui-1",
"to_agent": "agent-graph-1",
"category": "HANDOFF",
"subject": "Edge direction patch ready",
"body": "Graph directionality normalized. Please validate screenshots.",
"state": "unread",
"requires_ack": true,
"created_at": "2026-02-13T22:00:01.000Z",
"read_at": null,
"acked_at": null
}
```
### 6.1 `bb agent send`
Input:
1. `--from <agent_id>` required.
2. `--to <agent_id|broadcast>` required.
3. `--bead <bead_id>` required.
4. `--category <HANDOFF|BLOCKED|DECISION|INFO>` required.
5. `--subject <text>` required.
6. `--body <text>` required.
7. `--thread <thread_id>` optional (default `bead:<bead_id>`).
Validation:
1. Sender and recipient must be registered (`broadcast` exempt).
2. `bead_id` required, non-empty.
3. `subject` and `body` non-empty.
Errors:
1. `UNKNOWN_SENDER`
2. `UNKNOWN_RECIPIENT`
3. `MISSING_BEAD_ID`
4. `INVALID_CATEGORY`
### 6.2 `bb agent inbox`
Input:
1. `--agent <agent_id>` required.
2. `--state <unread|read|acked>` optional.
3. `--bead <bead_id>` optional.
4. `--limit <n>` optional, default `50`, max `500`.
Output order:
1. `created_at` desc.
### 6.3 `bb agent read`
Input:
1. `--agent <agent_id>` required.
2. `--message <message_id>` required.
Behavior:
1. Mark `state=read` if currently `unread`.
2. Keep `acked` as terminal.
### 6.4 `bb agent ack`
Input:
1. `--agent <agent_id>` required.
2. `--message <message_id>` required.
Validation:
1. Only recipient may ack.
2. `requires_ack=false` messages may still be acked.
Behavior:
1. Set `state=acked`.
2. Set `acked_at` if null.
Errors:
1. `MESSAGE_NOT_FOUND`
2. `ACK_FORBIDDEN`
## 7) Reservation Commands
Reservation schema:
```json
{
"reservation_id": "res_20260213_220900_e1a4",
"scope": "src/components/graph/*",
"agent_id": "agent-graph-1",
"bead_id": "bb-dcv.4",
"state": "active",
"created_at": "2026-02-13T22:09:00.000Z",
"expires_at": "2026-02-14T00:09:00.000Z",
"released_at": null
}
```
### 7.1 `bb agent reserve`
Input:
1. `--agent <agent_id>` required.
2. `--scope <scope>` required.
3. `--bead <bead_id>` required.
4. `--ttl <minutes>` optional, default `120`, range `5..1440`.
5. `--takeover-stale` optional.
Behavior:
1. If active reservation exists and not expired, fail with `RESERVATION_CONFLICT`.
2. If expired and `--takeover-stale` absent, return `RESERVATION_STALE_FOUND`.
3. If expired and `--takeover-stale`, mark old as expired and create new active record.
### 7.2 `bb agent release`
Input:
1. `--agent <agent_id>` required.
2. `--scope <scope>` required.
Behavior:
1. Only owner may release active reservation.
2. Mark as `released` and append history event.
Errors:
1. `RESERVATION_NOT_FOUND`
2. `RELEASE_FORBIDDEN`
### 7.3 `bb agent status`
Input:
1. `--bead <bead_id>` optional.
2. `--agent <agent_id>` optional.
Output:
1. Active reservations.
2. Unacked required-ack messages.
3. Optional summary counts by state.
## 8) Cross-Command Invariants
1. Every message and reservation must include `bead_id`.
2. Deleting coordination data is disallowed in v1.
3. `message_id` and `reservation_id` are globally unique.
4. All write operations are atomic at file level (write temp + rename).
## 9) Error Code Registry (v1)
1. `INVALID_ARGS`
2. `AGENT_NOT_FOUND`
3. `DUPLICATE_AGENT_ID`
4. `UNKNOWN_SENDER`
5. `UNKNOWN_RECIPIENT`
6. `MISSING_BEAD_ID`
7. `INVALID_CATEGORY`
8. `MESSAGE_NOT_FOUND`
9. `ACK_FORBIDDEN`
10. `RESERVATION_CONFLICT`
11. `RESERVATION_STALE_FOUND`
12. `RESERVATION_NOT_FOUND`
13. `RELEASE_FORBIDDEN`
14. `IO_WRITE_FAILED`
15. `IO_READ_FAILED`
## 10) Test Matrix for Follow-on Tasks
Identity (`bb-dcv.7`):
1. Register success.
2. Duplicate fails.
3. Force update allowed.
4. Show/list filters.
Mail (`bb-dcv.6`):
1. Send success.
2. Unknown sender/recipient failure.
3. Inbox state filtering.
4. Read transition (`unread` -> `read`).
5. Ack transition to `acked`.
Reservations (`bb-dcv.4`):
1. Reserve success.
2. Conflict on active reservation.
3. Expired stale detection.
4. Takeover stale flow.
5. Owner-only release.
Workflow (`bb-dcv.5`):
1. `bd --claim` + `bb agent` happy path.
2. Missing bead id rejection.
3. Status summary correctness with mixed states.

53
docs/plans/2026-02-13-timeline-ui-implementation.md Normal file
View file

@ -0,0 +1,53 @@
# Implementation Plan: Timeline UI (bb-xhm.3)
## Approach
We will build a dedicated `/timeline` page that consumes `ActivityEvent` streams via SSE and displays them in a grouped, filterable feed. To support data persistence across page refreshes (without DB), we will implement an in-memory ring buffer for events on the server.
## Steps
1. **Backend History Buffer** (20 min)
- Modify `src/lib/realtime.ts` to keep last 100 events in `ActivityEventBus`.
- Create `src/app/api/activity/route.ts` to serve this history.
2. **Scaffold Timeline Route & Store** (15 min)
- Create `src/app/timeline/page.tsx`.
- Create `src/components/timeline/timeline-store.ts` (Zustand).
- Create `src/components/timeline/timeline-layout.tsx`.
3. **Implement Event Card Components** (30 min)
- Create `src/components/timeline/event-card.tsx`: Polymorphic component.
- Styles: Aero Chrome "glass" panels, status glows, diff formatting.
- **Variants:**
- `StatusEvent`: Status changes with color-coded badges.
- `CommentEvent`: Text bubble style.
- `DiffEvent`: Field-level changes.
- `LifecycleEvent`: Created/Closed/Reopened.
4. **Implement Feed Container & Grouping** (20 min)
- Create `src/components/timeline/timeline-feed.tsx`.
- Logic: Group `ActivityEvent[]` by `YYYY-MM-DD`.
- Visual: Sticky date headers.
5. **Wire Real-time SSE & Filters** (20 min)
- Fetch initial history from `/api/activity`.
- Connect `useTimelineStore` to `activityEventBus` (via SSE).
- Implement `TimelineControls`.
6. **Integration & Polish** (15 min)
- Add navigation links to Kanban (`?focus=bead-id`).
- Verify responsive layout.
7. **Testing** (20 min)
- Unit tests for store/grouping.
- Component tests for cards.
- Integration test for history API.
## Timeline
| Phase | Duration |
|-------|----------|
| Backend | 20 min |
| Scaffolding | 15 min |
| UI Components | 50 min |
| Integration | 35 min |
| Testing | 20 min |
| **Total** | **2.5 hours** |