From 1880301e8b34c448acf1f79a717f5f3934e2450c Mon Sep 17 00:00:00 2001 From: ZenchantLive Date: Tue, 3 Mar 2026 19:08:58 -0800 Subject: [PATCH] docs(skill): refresh command matrix and failure modes --- .../references/command-matrix.md | 114 ++++++++++++------ .../references/failure-modes.md | 82 ++++++++----- 2 files changed, 132 insertions(+), 64 deletions(-) diff --git a/skills/beadboard-driver/references/command-matrix.md b/skills/beadboard-driver/references/command-matrix.md index 849c7fb..d9e75c0 100644 --- a/skills/beadboard-driver/references/command-matrix.md +++ b/skills/beadboard-driver/references/command-matrix.md @@ -1,41 +1,81 @@ -# Command Matrix - -## Bootstrapping and Handshake - -- `node scripts/bb-init.mjs --register --role --json` - - Output: `{ ok, agent_id, mode, lease, timestamp }` -- `node scripts/bb-init.mjs --adopt [--non-interactive] --json` - - Output: `{ ok, agent_id, mode, lease, timestamp }` or `{ ok:false, error }` - -## Coordination Commands (`bb`) - -- `bb agent register --name --role ` -- `bb agent activity-lease --agent [--json]` - - Output: `{ ok, command, data: AgentRecord }` -- `bb agent list [--role ] [--status ]` -- `bb agent show --agent ` -- `bb agent send --from --to --bead --category --subject --body ` -- `bb agent inbox --agent [--state unread|read|acked] [--bead ]` -- `bb agent read --agent --message ` -- `bb agent ack --agent --message ` -- `bb agent reserve --agent --scope --bead [--ttl ] [--takeover-stale]` -- `bb agent release --agent --scope ` -- `bb agent status [--bead ] [--agent ]` - -## Lifecycle Commands (`bd`) - -- `bd ready` -- `bd show ` -- `bd update --status in_progress --claim` -- `bd update --notes ""` -- `bd close --reason ""` - -## Legacy/Internal Scripts - -- `node skills/beadboard-driver/scripts/resolve-bb.mjs` +# Command Matrix + +This matrix lists the operational command surface for the BeadBoard driver skill. +Day-to-day runbooks use `bd mail` delegation rather than direct low-level agent CLI invocations. + +## Session and Identity + - `node skills/beadboard-driver/scripts/session-preflight.mjs` -- `node skills/beadboard-driver/scripts/generate-agent-name.mjs` +- `node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs` +- `bd create --title="Agent: " --description="" --type=task --priority=0 --label="gt:agent,role:"` +- `bd agent state spawning` +- `bd agent state running` +- `bd agent heartbeat ` +- `bd agent show ` + +## Work Claim and Lifecycle + +- `bd ready` +- `bd show ` +- `bd update --status in_progress --assignee ` +- `bd slot set hook ` +- `bd update --notes ""` +- `bd close --reason ""` +- `bd slot clear hook` + +## Mail and Coordination (`bd mail` delegated) + +- `bd mail inbox` +- `bd mail send --to --bead --category --subject "" --body "
"` +- `bd mail read ` +- `bd mail ack ` + +Delegate setup and validation: + +- `bd config set mail.delegate "node /skills/beadboard-driver/scripts/bb-mail-shim.mjs"` +- `export BB_AGENT=` +- `node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs` + +## Dependency and Graph Control + +- `bd dep --blocks ` +- `bd dep add ` +- `bd dep list ` +- `bd dep tree ` +- `bd dep cycles` +- `bd dep relate ` +- `bd dep unrelate ` + +## Swarm and Molecule Operations + +- `bd swarm validate ` +- `bd swarm create [--coordinator ] [--force]` +- `bd swarm status ` +- `bd swarm list` +- `bd mol show ` +- `bd mol pour --var key=value` +- `bd mol ready` +- `bd mol progress ` +- `bd mol stale` + +## Gates and Blocked Work + +- `bd gate list` +- `bd gate list --all` +- `bd gate check` +- `bd gate check --type=bead` +- `bd gate show ` +- `bd gate resolve ` + +## Comments and Audit Trail + +- `bd comments ` +- `bd comments add ""` +- `bd comments add -f ` + +## Environment and Repair Helpers + +- `node skills/beadboard-driver/scripts/resolve-bb.mjs` - `node skills/beadboard-driver/scripts/readiness-report.mjs --checks --artifacts ` - `node skills/beadboard-driver/scripts/diagnose-env.mjs` - `node skills/beadboard-driver/scripts/heal-common-issues.mjs [--project-root ] [--apply] [--fix-git-index-lock]` -- `node skills/beadboard-driver/scripts/ensure-project-context.mjs [--project-root ]` diff --git a/skills/beadboard-driver/references/failure-modes.md b/skills/beadboard-driver/references/failure-modes.md index b92b7f4..e0f04db 100644 --- a/skills/beadboard-driver/references/failure-modes.md +++ b/skills/beadboard-driver/references/failure-modes.md @@ -1,47 +1,75 @@ # Failure Modes +This document tracks high-impact coordination and environment failures for the BeadBoard driver skill. + ## `BD_NOT_FOUND` -- Cause: `bd` missing from PATH. -- Recovery: install beads CLI or add `bd` executable directory to PATH. +- Signal: preflight or scripts fail with `BD_NOT_FOUND`. +- Cause: `bd` is not installed or not on `PATH`. +- Recovery: + - Install beads CLI. + - Re-open shell so `PATH` updates apply. + - Re-run `node skills/beadboard-driver/scripts/session-preflight.mjs`. ## `BB_NOT_FOUND` -- Cause: `BB_REPO` invalid or no `bb` command / cache / discovery hit. +- Signal: `resolve-bb.mjs` or `bb-mail-shim.mjs` reports bb command missing. +- Cause: global BeadBoard CLI not installed, or not discoverable. - Recovery: - - Set `BB_REPO` to BeadBoard repo root. - - Verify `bb.ps1` exists under `BB_REPO`. - - Retry preflight. + - Install BeadBoard globally (`bb`/`beadboard` on `PATH`). + - Re-run `node skills/beadboard-driver/scripts/resolve-bb.mjs`. + - Re-run preflight. -## `NAME_GENERATION_EXHAUSTED` +## `MAIL_DELEGATE_MISSING` / `BD_MAIL_DELEGATE_NOT_SET` -- Cause: all generated names collided with existing registry entries. +- Signal: `bd mail ...` returns delegate-not-configured or shim not invoked. +- Cause: neither env delegate (`BEADS_MAIL_DELEGATE`/`BD_MAIL_DELEGATE`) nor `mail.delegate` config is set. - Recovery: - - increase retry count (`BB_NAME_MAX_RETRIES`), - - expand adjective/noun pools, - - retry generation. + - `bd config set mail.delegate "node /skills/beadboard-driver/scripts/bb-mail-shim.mjs"` + - `export BB_AGENT=` + - `node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs` -## Reservation Conflicts +## `BB_MAIL_NOT_CONFIGURED` -- `RESERVATION_CONFLICT`: active owner exists. -- `RESERVATION_STALE_FOUND`: stale reservation exists; use takeover only when safe. -- `RELEASE_FORBIDDEN`: non-owner attempted release. +- Signal: `ensure-bb-mail-configured.mjs` fails contract checks. +- Cause: delegate points to wrong command, missing shim path, or invalid `BB_AGENT` context. +- Recovery: + - Run session preflight to re-apply expected delegate command. + - Set `BB_AGENT` explicitly. + - Validate with `node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs`. + +## `DOLT_NOT_RUNNING` + +- Signal: `bd` reads stale/fallback data, API routes return Dolt connection failures, or status checks report backend unavailable. +- Cause: Dolt SQL server not started for this workspace. +- Recovery: + - From repo root: `bd dolt start` + - Verify backend health before proceeding (`beadboard status --json` or project-specific health checks). + +## `AGENT_HEARTBEAT_MISSED` (Witness liveness degradation) + +- Signal: agent appears stale/dead in liveness surfaces after inactivity window. +- Cause: agent is not sending `bd agent heartbeat ` during active work. +- Recovery: + - Resume periodic heartbeat (typically every 30-120 seconds while active). + - Set explicit state transitions: `running` -> `working` -> `stuck|done|stopped`. + - If work was interrupted, post a coordination note/message before resuming. ## Mail Lifecycle Errors -- `UNKNOWN_SENDER` / `UNKNOWN_RECIPIENT`: register agents before send. -- `ACK_FORBIDDEN`: only recipient may ack. -- `MESSAGE_NOT_FOUND`: stale id or wrong message reference. +- `UNKNOWN_SENDER` / `UNKNOWN_RECIPIENT`: register agent identities before sending. +- `MESSAGE_NOT_FOUND`: incorrect message id or wrong inbox context. +- `ACK_FORBIDDEN`: only the message recipient can acknowledge. + +## Local Workspace Repair Signals + +- `GIT_INDEX_LOCK_PRESENT`: stale git lock blocks writes. +- Recovery: + - Confirm no active git process is still using the repo. + - Run `node skills/beadboard-driver/scripts/heal-common-issues.mjs --project-root --apply --fix-git-index-lock`. ## Policy Guardrails - Do not write `.beads/issues.jsonl` directly. -- Do not close beads without verification evidence. -- Do not bypass `BB_REPO` when it is set but invalid; fix it explicitly. - -## Local Environment Repair Signals - -- `GIT_INDEX_LOCK_PRESENT`: stale git lock can block local operations. - - Recovery: - - confirm no active git process is using the repository, - - run `node skills/beadboard-driver/scripts/heal-common-issues.mjs --project-root --apply --fix-git-index-lock`. +- Do not close beads without fresh evidence. +- Do not bypass invalid `BB_REPO` values; fix configuration first.