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