docs: add planning documents for buff epic and unified UX

STORY:
Major epics require upfront planning documentation. These docs capture
the design decisions, architecture, and rollout maps for the
Agent System Overhaul (bb-buff) and Unified UX (bb-ui2) epics.

COLLABORATION:
- 2026-02-14-operative-protocol-design.md: ZFC state machine design
- 2026-02-14-super-agent-buff-roadmap.md: buff epic architecture
- 2026-02-15-unified-ux-prd.md: UI epic product requirements
- docs/protocols/: protocol specifications

These documents serve as the source of truth for implementation decisions
and help future contributors understand the design rationale.

docs/plans/2026-02-14-operative-protocol-design.md

@@ -0,0 +1,112 @@
+# Operative Protocol Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Implement a robust agent coordination protocol that leverages the "Social-Dense" Hub for supervision and enables "Optimistic Concurrency" (traceable incursions) between agents.
+
+**Architecture:** We use a "Codebase as Reality" model where physical file changes trigger contextual lookups in the Agent Inbox. A new `bb-init` tool handles session bootstrapping and identity adoption, while a heartbeat mechanism provides real-time supervisor observability.
+
+**Tech Stack:** Next.js 15, TypeScript, PowerShell (bb.ps1), Node.js (scripts), SSE (real-time).
+
+---
+
+### Task 1: Infrastructure - Agent Heartbeat & Stale Logic
+
+**Files:**
+- Modify: `src/lib/agent-registry.ts`
+- Modify: `src/lib/agent-reservations.ts`
+- Test: `tests/lib/agent-heartbeat.test.ts`
+
+**Step 1: Implement Heartbeat update logic**
+Add `heartbeatAgent(agentId: string)` to `agent-registry.ts` to update `last_seen_at`.
+
+**Step 2: Implement Stale Detection**
+In `agent-reservations.ts`, add logic to `reserveAgentScope` that allows `takeoverStale: true` if the current owner's `last_seen_at` is > 15 minutes old.
+
+**Step 3: Test Heartbeat and Takeover**
+Write a test verifying that an agent can take over a scope if the owner is stale, but is blocked if the owner is active.
+
+**Step 4: Commit**
+```bash
+git add src/lib/agent-registry.ts src/lib/agent-reservations.ts tests/lib/agent-heartbeat.test.ts
+git commit -m "feat(infra): implement agent heartbeat and stale reservation takeover"
+```
+
+---
+
+### Task 2: Bootstrapping - The `bb-init` Tool
+
+**Files:**
+- Create: `scripts/bb-init.mjs`
+- Modify: `beadboard/tools/bb.ts` (add heartbeat command)
+- Test: `tests/scripts/bb-init.test.ts`
+
+**Step 1: Create `bb-init.mjs`**
+Implement logic to:
+1. Resolve `bb.ps1` path.
+2. Check for uncommitted changes (`git status`).
+3. If changes exist, query `bb agent status --scope <changed-path>` to find previous owner.
+4. Prompt for identity adoption or new registration.
+
+**Step 2: Add `bb agent heartbeat` CLI command**
+Expose the heartbeat logic in `tools/bb.ts` so agents can call it.
+
+**Step 3: Test Bootstrap Flow**
+Verify `bb-init` correctly identifies uncommitted changes and suggests the right previous agent.
+
+**Step 4: Commit**
+```bash
+git add scripts/bb-init.mjs beadboard/tools/bb.ts
+git commit -m "feat(infra): add bb-init bootstrapping and heartbeat CLI command"
+```
+
+---
+
+### Task 3: Frontend - Incursion & Overlap Visualization
+
+**Files:**
+- Modify: `src/components/sessions/AgentScorecard.tsx`
+- Modify: `src/components/sessions/AuditFeed.tsx`
+- Modify: `src/hooks/useSSE.ts`
+
+**Step 1: Update Agent Scorecard**
+Add visual states for `INVADING` (Shared Scope) and `STALE` (Heartbeat lost).
+
+**Step 2: Implement Incursion Alert**
+In the Sessions Hub, show a connection line or alert banner when two agents have active reservations in overlapping scopes.
+
+**Step 3: Stream Protocol Messages**
+Ensure `INFO`, `HANDOFF`, and `BLOCKED` messages appear prominently in the `AuditFeed` with bead-link icons.
+
+**Step 4: Commit**
+```bash
+git add src/components/sessions/ src/hooks/useSSE.ts
+git commit -m "feat(ui): visualize agent incursions and protocol messages in Hub"
+```
+
+---
+
+### Task 4: Education - Refactor Agent Skill
+
+**Files:**
+- Modify: `beadboard/skills/beadboard-driver/SKILL.md`
+
+**Step 1: Rewrite for "Operative Protocol"**
+Replace the old workflow with the new "Good Citizen" loop:
+1. `node scripts/bb-init.mjs` (Boot/Adopt).
+2. `bb agent reserve` (Claim Territory).
+3. **Physical Change -> Contextual Lookup** (Check inbox if you see unexpected changes).
+4. `bb agent send --category INFO` (Explain incursions/milestones).
+5. `bb agent heartbeat` (Keep your light green).
+
+**Step 2: Add Rationalization Table**
+Add the "Excuse vs Reality" table to stop agents from skipping protocol.
+
+**Step 3: Add Red Flags**
+Define "Silent Incursion" and "Mocking" as red flags.
+
+**Step 4: Commit**
+```bash
+git add beadboard/skills/beadboard-driver/SKILL.md
+git commit -m "docs(skill): refactor beadboard-driver to the Operative Protocol"
+```