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

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.
2026-02-14 00:21:25 -08:00 · 2026-02-14 00:21:25 -08:00 · c7c3a25457
commit c7c3a25457
parent bfe4f853f0
27 changed files with 2376 additions and 137 deletions
--- a/docs/plans/2026-02-13-agent-sessions-ux-v1.md
+++ b/docs/plans/2026-02-13-agent-sessions-ux-v1.md
@ -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
--- a/docs/plans/2026-02-13-bb-agent-cli-contract.md
+++ b/docs/plans/2026-02-13-bb-agent-cli-contract.md
@ -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.
+
--- a/docs/plans/2026-02-13-timeline-ui-implementation.md
+++ b/docs/plans/2026-02-13-timeline-ui-implementation.md
@ -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** |