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.


v5: swarm system reference rewrite

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

TASK CONTRACT
- Goal: Rewrite archetypes-templates-swarms.md replacing vague 'use your environment swarm commands' with real bd swarm and bd mol commands, and adding template discovery so agents know what swarm they're in.
- Success Criteria:
  - bd swarm create <epic-id>, bd swarm status, bd swarm list, bd swarm validate documented with examples
  - bd mol show <proto-id> documented: how agents discover the template/proto their swarm was instantiated from
  - Archetype contracts expanded: coder/reviewer/writer each get quality gates, handoff payload format, escalation triggers
  - Swarm join flow for worker agents documented (not just orchestrators)
  - Swarm closure ownership defined: who closes and when
  - Command surface section replaced with real commands (no more 'expected operations' placeholder)
- Scope:
  - skills/beadboard-driver/references/archetypes-templates-swarms.md rewrite
  - bd swarm subcommands
  - bd mol show (template discovery)
- Out of Scope:
  - bd mol pour/wisp/bond (molecule instantiation is user/orchestrator territory)
  - BeadBoard UI swarm views

IMPLEMENTATION CONSTRAINTS
- Source of truth for bd swarm: run bd swarm --help and bd swarm create --help in beadboard/
- No invented commands — only document commands verified to exist

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


Rewrote skills/beadboard-driver/references/archetypes-templates-swarms.md with verified command surface from bd swarm and bd mol. Added concrete commands/examples for create/status/list/validate and mol show --parallel, expanded coder/reviewer/writer archetype contracts (quality gates, handoff payloads, escalation triggers), documented worker join flow, and clarified swarm closure ownership/checklist. Removed placeholder command language in favor of real commands only. Verification artifact: updated archetypes-templates-swarms.md in skills path.

v5: swarm system reference rewrite


Replaced placeholder swarm guidance with real bd swarm/mol command workflows and role contracts.


v5: bead lifecycle + dep workflow expansion

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

TASK CONTRACT
- Goal: Expand session-lifecycle.md to cover the BLOCKED path, bd dep workflow, epic/parent bead guidance, and fix the --claim vs --assignee inconsistency.
- Success Criteria:
  - --claim replaced everywhere with --assignee <agent-bead-id> (the correct flag)
  - BLOCKED path documented: bd agent state <id> stuck + bb mail send BLOCKED + what to do while waiting
  - bd dep add and bd dep relate documented with when-to-use guidance
  - Epic/parent bead guidance: bd show <epic-id> before claiming child tasks, bd children <epic-id> to see sibling work
  - Memory review step has substance: exact decision rule for when to create vs skip canonical memory
  - Session start now includes: create agent bead, set state spawning, attach hook slot, query hard memory
- Scope:
  - skills/beadboard-driver/references/session-lifecycle.md rewrite
  - bd dep subcommands (add, relate, list, tree)
- Out of Scope:
  - Communication protocol details (covered in maf.6)

IMPLEMENTATION CONSTRAINTS
- --assignee requires an agent bead to exist first — document this ordering explicitly
- BLOCKED path must reference bd agent state stuck (not just mail events)

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


Rewrote skills/beadboard-driver/references/session-lifecycle.md. Replaced deprecated --claim usage with correct --assignee ordering, added explicit session-start sequencing (agent bead creation, state spawning/running, hard-memory query), added epic/children read step, documented bd dep add/relate/list/tree with when-to-use guidance, expanded mandatory BLOCKED path (state stuck + BLOCKED mail + heartbeat + resume), and added concrete memory-review decision rule (create/supersede vs skip). Verification artifact: updated session-lifecycle.md in skills path.


Expanded session lifecycle into a complete command-backed runbook with correct claim/dependency/blocked flow.


v5: script platform fix (Linux/WSL bb discovery)

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

TASK CONTRACT
- Goal: Fix driver-lib.mjs discoverBbPath() which only searches for bb.ps1, causing BB_NOT_FOUND on all Linux/WSL agents even when bb is in PATH.
- Success Criteria:
  - discoverBbPath() finds bb binary on Linux/WSL via PATH or known install locations
  - Windows bb.ps1 discovery still works (no regression)
  - session-preflight.contract.test.mjs passes on Linux (currently platform-assumption failure)
  - resolve-bb.contract.test.mjs passes on Linux
  - npm run typecheck, lint, test all pass
- Scope:
  - scripts/lib/driver-lib.mjs: discoverBbPath() and validateRepoPath() functions
  - Platform-branching: Windows checks bb.ps1, Linux/Mac checks bb binary in PATH and npm global
  - Contract test updates for cross-platform assumptions
- Out of Scope:
  - Windows path handling changes
  - bb mail configuration (maf.5 in izs)

IMPLEMENTATION CONSTRAINTS
- Do not break existing Windows discovery logic
- On Linux, check: PATH entries for 'bb', npm global bin, ~/.npm-global/bin/bb

VERIFICATION REQUIREMENTS
- Required commands: npm run typecheck, npm run lint, npm run test
- Required artifacts: updated driver-lib.mjs, updated contract tests


Implemented Linux/WSL discovery fix in skills/beadboard-driver/scripts/lib/driver-lib.mjs: (1) validateRepoPath now accepts bb.ps1 or bin/beadboard.js with platform-aware candidate order; (2) discoverBbPath now checks PATH via findCommandInPath('bb') before BFS; (3) BFS now searches both bb.ps1 and bin/beadboard.js cross-platform. Verification (2026-03-04): npm run typecheck -> pass; npm run lint -> pass (21 pre-existing warnings, 0 errors); npm run test -> pass.


Platform-specific bb discovery now works on Linux/WSL and Windows-compatible entrypoints remain supported.


v5: comm system rewrite (coord-events-sessions-ack.md)

## TASK CONTEXT
- Bead ID: beadboard-maf.6
- Parent/Epic: beadboard-maf
- Dependencies: beadboard-izs (bb mail epic must be fully complete — commands finalized and reference doc written in izs.7)

coord-events-sessions-ack.md currently documents deprecated command signatures. The coordination system is fully implemented in tools/bb.ts (bb agent send/inbox/read/ack/register/reserve/release/status), backed by src/lib/agent-mail.ts, agent-registry.ts, agent-reservations.ts. izs.7 produces the canonical reference doc — this task rewrites the skill reference using it.

## TASK CONTRACT
**Goal**: Rewrite coord-events-sessions-ack.md (or replace with coordination-system.md from izs.7) with accurate bb agent command surface, WHEN-to-use triggers, and a worked BLOCKED flow example.

**Success Criteria**:
- Uses bb agent send/inbox/read/ack with correct flags (not speculative — verified against tools/bb.ts)
- WHEN-to-use trigger map: condition that triggers each category (HANDOFF, BLOCKED, DECISION, INFO)
- Inbox polling protocol: when agents check inbox (session start, before claiming task, on state=stuck)
- Full BLOCKED walkthrough: agent sends bb agent send --category BLOCKED → bd agent state stuck → user sees in BeadBoard UI → user intervenes → agent resumes
- ACK escalation path documented for requires_ack=true messages
- bd mail delegate documented as the alternative invocation path (bd mail → bb agent)
- Reservation conflict protocol: active blocks, stale warns with --takeover-stale
- Zero references to phantom or deprecated API surfaces
- Must read izs.7 coordination-system.md FIRST — do not invent command syntax

**Scope**:
- .agents/skills/beadboard-driver/references/coord-events-sessions-ack.md rewrite
- May link to or embed content from coordination-system.md (izs.7)

**Out of Scope**:
- SKILL.md update (maf.10)
- Other reference docs

## IMPLEMENTATION CONSTRAINTS
- Read izs.7 output (coordination-system.md) before writing anything
- Verify all command examples compile against actual tools/bb.ts command surface

## VERIFICATION REQUIREMENTS
- All command examples match actual bb agent flags
- WHEN-to-use map covers at least 6 trigger scenarios
- Worked BLOCKED flow is end-to-end complete


Rewrote skills/beadboard-driver/references/coord-events-sessions-ack.md against canonical izs.7 coordination-system.md and verified bb command surface in tools/bb.ts. Updated categories to HANDOFF/BLOCKED/DECISION/INFO only; added explicit ack semantics, inbox polling protocol, 7-scenario WHEN-to-use trigger map, complete BLOCKED -> bd agent state stuck -> user intervention -> ack -> running flow, bd mail delegate mapping, and reservation conflict/takeover-stale policy. Removed deprecated/phantom command and category references.


Coordination events/session/ack reference now matches live bb agent and bd mail delegate behavior, including end-to-end blocked recovery flow.


v5: command matrix + failure modes rewrite

TASK CONTEXT
- Bead ID: beadboard-maf.7
- Parent/Epic: beadboard-maf
- Dependencies: beadboard-maf.6 (comm system must be rewritten so command matrix reflects real surface)

TASK CONTRACT
- Goal: Rewrite command-matrix.md and failure-modes.md to remove all dead bb agent commands and add the full live command surface.
- Success Criteria:
  - command-matrix.md: zero bb agent commands; full surface: bd agent state/heartbeat, bd swarm, bb mail, bd slot, bd gate, bd mol, bd dep, bd comments
  - failure-modes.md: reservoir/reservation errors removed; new entries: bb mail not configured (error_code + remediation), Dolt not running, bd agent heartbeat missed (Witness marks dead), bd mail delegate not set
  - All commands in matrix verified to exist (no invented flags)
- Scope:
  - skills/beadboard-driver/references/command-matrix.md full rewrite
  - skills/beadboard-driver/references/failure-modes.md update
- Out of Scope:
  - New command implementations

IMPLEMENTATION CONSTRAINTS
- Cross-reference against bd --help and bb --help output before writing
- Every command in the matrix must include the real flag names (not paraphrases)

VERIFICATION REQUIREMENTS
- Required commands: None (doc task)
- Required artifacts: updated command-matrix.md, updated failure-modes.md


Rewrote skills/beadboard-driver/references/command-matrix.md and failure-modes.md against live CLI help output (bd agent/swarm/slot/gate/mol/dep/comments/mail plus bb-backed delegate behavior). Removed old/dead direct command patterns (including --claim and direct bb agent workflow commands), corrected swarm create flags to documented --coordinator/--force surface, and added failure coverage for MAIL_DELEGATE_MISSING, BB_MAIL_NOT_CONFIGURED, DOLT_NOT_RUNNING, and AGENT_HEARTBEAT_MISSED.


Command matrix and failure modes now reflect the current delegated coordination surface and verified CLI flags.


v5: tests update

TASK CONTEXT
- Bead ID: beadboard-maf.8
- Parent/Epic: beadboard-maf
- Dependencies: beadboard-maf.5 (script fix), beadboard-maf.6 (comm system — tests must match new commands)

TASK CONTRACT
- Goal: Update skill-local and repo-level tests so they pass on Linux/WSL and cover the new bb mail integration.
- Success Criteria:
  - session-preflight.contract.test.mjs: remove Windows-only assumptions, pass on Linux
  - resolve-bb.contract.test.mjs: Linux bb binary discovery tested
  - bb-mail integration test: full send->inbox->read->ack lifecycle in isolated tmpdir
  - ensure-bb-mail-configured.mjs contract test: missing delegate detected and remediation shown
  - All tests registered in run-tests.mjs and package.json
  - npm run typecheck, lint, test all pass
- Scope:
  - skills/beadboard-driver/tests/*.contract.test.mjs updates
  - tests/skills/beadboard-driver/*.test.ts updates
  - package.json test registration
- Out of Scope:
  - Windows CI (follow-up epic)

IMPLEMENTATION CONSTRAINTS
- No mocking of bd — use real bd in tmpdir
- New test files must be added to package.json test script (explicitly enumerated)

VERIFICATION REQUIREMENTS
- Required commands: npm run typecheck, npm run lint, npm run test
- Required artifacts: all updated test files, updated package.json


Added label: gt:agent


Agent: bb-maf8-1772593966-a