bb coord: agent coordination reference doc (for v5 skill)

## TASK CONTEXT
The beadboard-driver v5 skill (beadboard-maf) needs a definitive reference document for the coordination system. The current coord-events-sessions-ack.md references deprecated bb agent commands and has no WHEN-to-use triggers. This doc becomes the source for maf.6 (comm system rewrite for v5).

## TASK CONTRACT
**Goal**: Write a complete, accurate coordination system reference at .agents/skills/beadboard-driver/references/coordination-system.md.

**Success Criteria**:
- Documents all bb agent commands with flags and examples (send, inbox, read, ack, register, list, show, activity-lease, reserve, release, status)
- Message state machine documented: unread → read → acked, with requires_ack: true for HANDOFF and BLOCKED
- WHEN-to-use trigger map covers at least 6 scenarios (task complete → HANDOFF, blocked → BLOCKED, FYI → INFO, async decision → DECISION, etc.)
- Inbox polling protocol: frequency recommendation + what to do with unacked required messages
- Reservation conflict resolution documented: active agent blocks, stale/evicted warns with --takeover-stale
- Worked example showing full HANDOFF flow from sender through recipient to ack
- bd mail delegate config documented (how to configure bb as the delegate)

**Scope**:
- New file: .agents/skills/beadboard-driver/references/coordination-system.md
- May deprecate/replace coord-events-sessions-ack.md

**Out of Scope**:
- SKILL.md update (maf.10)
- Memory, swarm, or lifecycle docs (separate maf tasks)

## IMPLEMENTATION CONSTRAINTS
- Reference actual command flags from tools/bb.ts and src/lib/agent-mail.ts — not speculative
- Test examples against real command output where possible

## VERIFICATION REQUIREMENTS
- File exists at .agents/skills/beadboard-driver/references/coordination-system.md
- All bb agent commands documented with at least one complete example
- WHEN-to-use trigger map covers at least 6 scenarios


Added canonical coordination reference at skills/beadboard-driver/references/coordination-system.md (per user path clarification: skills folder, not .agents). Document includes all bb agent commands/flags with examples; message state machine and requires_ack semantics; WHEN-to-use trigger map (8 scenarios); inbox polling protocol; reservation conflict policy; full HANDOFF walkthrough; bd mail delegate setup to bb-mail-shim and missing-bb fallback behavior. Verification evidence: file existence confirmed; command coverage and trigger counts validated with rg checks. Memory review: no new reusable memory.


Published coordination-system reference doc for v5 skill with complete command/flow/delegate guidance.


v5: agent state + liveness reference doc (new)

TASK CONTEXT
- Bead ID: beadboard-maf.1
- Parent/Epic: beadboard-maf
- Dependencies: None (parallelizable with maf.2-maf.5)

TASK CONTRACT
- Goal: Write a new agent-state-liveness.md reference covering bd agent state, bd agent heartbeat, bd slot, and the Witness death timeout — the live command surface agents use to report liveness to BeadBoard UI.
- Success Criteria:
  - All liveness states documented: idle, spawning, running, working, stuck, done, stopped, dead
  - bd agent state <id> <state> usage with examples for each state transition
  - bd agent heartbeat <id> documented with polling guidance (when to call, how often)
  - bd slot set <agent-id> hook <bead-id> documented: attach current work to agent slot
  - Witness death timeout explained: what happens when heartbeat is missed
  - bd agent state stuck documented as the signal for BLOCKED condition
  - Saved at skills/beadboard-driver/references/agent-state-liveness.md
- Scope:
  - New reference doc only
  - All bd agent subcommands relevant to agents (state, heartbeat, show)
  - bd slot set/clear/show
- Out of Scope:
  - bd agent backfill-labels (admin command)
  - BeadBoard UI internals for rendering liveness

IMPLEMENTATION CONSTRAINTS
- Written for a cold agent reading first time
- Every command shown with a real example, not just signature

VERIFICATION REQUIREMENTS
- Required commands: None (doc task)
- Required artifacts: skills/beadboard-driver/references/agent-state-liveness.md


Created new reference: skills/beadboard-driver/references/agent-state-liveness.md. Includes all liveness states (idle/spawning/running/working/stuck/done/stopped/dead), bd agent state usage with transition examples, bd agent heartbeat guidance/cadence, bd slot set/clear/show usage, witness timeout interpretation, and explicit blocked workflow using state stuck + BLOCKED mail signal. Verification artifact: skills/beadboard-driver/references/agent-state-liveness.md exists. Memory review: no new reusable memory.


Added comprehensive agent state+liveness reference for cold agents with command-backed workflows.


v5: memory system reference update

TASK CONTEXT
- Bead ID: beadboard-maf.2
- Parent/Epic: beadboard-maf
- Dependencies: None (parallelizable with maf.1, maf.3-maf.5)

TASK CONTRACT
- Goal: Update memory-system.md to add missing operational guidance: domain anchor IDs, WHEN-to-query trigger, and the full injection playbook from help/memory/query_and_injection.txt.
- Success Criteria:
  - Domain anchor IDs added: beadboard-76p (Arch), beadboard-nq9 (Workflow), beadboard-5r1 (Agent Ops), beadboard-fld (UI/UX), beadboard-8st (Reliability)
  - WHEN-to-query trigger added: at session start, before claiming work, when entering a new domain
  - Full injection playbook included (Steps 1-7 from query_and_injection.txt): domain selection, bd query, provenance check, attach via dep relate, contract bead for hard rules, record acknowledgement, preserve provenance in notes
  - 'Ratify by closing' clarified: closed decision bead = active canonical memory
  - Noise budget promotion policy added: incident repeats 2+ times = soft candidate, survives release window = hard candidate
- Scope:
  - skills/beadboard-driver/references/memory-system.md rewrite/expansion
- Out of Scope:
  - Changes to bd itself
  - New canonical memory creation

IMPLEMENTATION CONSTRAINTS
- Source of truth for injection playbook: help/memory/query_and_injection.txt in beadboard repo
- Source of truth for schema: help/memory/schema_and_noise_budget.txt

VERIFICATION REQUIREMENTS
- Required commands: None (doc task)
- Required artifacts: updated skills/beadboard-driver/references/memory-system.md


Rewrote skills/beadboard-driver/references/memory-system.md with v5 memory protocol. Added required domain anchor IDs (beadboard-76p, beadboard-nq9, beadboard-5r1, beadboard-fld, beadboard-8st), WHEN-to-query triggers (session start / pre-claim / domain shift), full 7-step injection playbook from help/memory/query_and_injection.txt, ratification clarification (closed decision bead = active canonical memory), and noise-budget promotion policy (repeat incidents -> soft candidate; release-surviving workaround -> hard/soft). Verification artifact: updated memory-system.md in skills path. Memory review: no new reusable memory.

v5: memory system reference update


Updated memory-system reference with anchor IDs, full injection playbook, and promotion/ratification rules.