checkpoint: pre-split branch cleanup

skills/beadboard-driver/references/coord-events-sessions-ack.md

@@ -0,0 +1,121 @@
+# Coordination Events, Sessions, and Acknowledgment
+
+## Purpose
+
+Define how agents communicate status, blockers, incursions, and handoffs in a machine-readable way that BeadBoard can render and users can act on.
+
+## Operating Model
+
+- Agent works in a target repository.
+- User watches and orchestrates from BeadBoard UI.
+- Agent communication must flow through coordination events and inbox state transitions, not ad-hoc notes.
+
+## Event Categories
+
+Use explicit categories with clear intent:
+
+- `HANDOFF`: transfer ownership or next action.
+- `BLOCKED`: explicit dependency or missing input.
+- `RESUME`: adoption/resumption event.
+- `INFO`: milestone or important context.
+- `INCURSION`: overlap/collision signal for reserved scope.
+
+## Session Stream Expectations
+
+Session feeds should be audit-friendly:
+
+- Every coordination event has sender, recipient/system target, bead id, and timestamp.
+- `INCURSION` and `RESUME` are first-class timeline rows, not hidden diagnostics.
+- Events should be understandable by humans without reading implementation code.
+
+## Message Lifecycle
+
+Inbox state machine:
+
+1. `unread` when message is delivered.
+2. `read` when recipient opens/reads message.
+3. `acked` when recipient explicitly acknowledges.
+
+Required behavior:
+
+- Only recipient may ack.
+- Acks are explicit, not implied by read.
+- Blocker and handoff flows should request ack when coordination certainty is required.
+
+## Recommended Command Patterns
+
+Send structured coordination event:
+
+```bash
+bb agent send \
+  --from <agent-id> \
+  --to <peer-agent-id> \
+  --bead <bead-id> \
+  --category <HANDOFF|BLOCKED|RESUME|INFO|INCURSION> \
+  --subject "<short summary>" \
+  --body "<actionable details>"
+```
+
+Read inbox for current bead/session work:
+
+```bash
+bb agent inbox --agent <agent-id> --state unread --bead <bead-id>
+bb agent read --agent <agent-id> --message <message-id>
+bb agent ack --agent <agent-id> --message <message-id>
+```
+
+## Coordination Contracts
+
+### Handoff
+
+A `HANDOFF` should include:
+
+- what is done,
+- what remains,
+- concrete next action,
+- whether ack is required.
+
+### Blocked
+
+A `BLOCKED` should include:
+
+- blocker description,
+- requested action,
+- urgency,
+- ack requirement.
+
+### Incursion
+
+An `INCURSION` should include:
+
+- overlap kind (`exact` or `partial`),
+- owner identity,
+- incoming identity,
+- owner liveness,
+- resolution hint.
+
+### Resume
+
+A `RESUME` should include:
+
+- resume reason,
+- prior session identity,
+- adopted identity,
+- evidence summary for safe adoption.
+
+## UX Alignment
+
+Session UI should map event semantics to plain-language actions:
+
+- Handoff label: "Passed to"
+- Blocked label: "Needs input"
+- Read action: "Seen"
+- Ack action: "Accepted"
+
+## Anti-Patterns
+
+- Using comments instead of coordination events for handoffs.
+- Silent reservation collisions with no `INCURSION`/`INFO` signal.
+- Treating read as ack.
+- Sending vague events with no actionable payload.
+- Closing a blocked bead without tracking unblock communication.